Manual de Theos Corona

THEOS Corona ®

System Commands Reference

First Edition: September, 2002 Copyright © 1995, 1996, 1998, 2002 by THEOS Software Corporation. All rights reserved. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used only in accordance with the terms of the agreement. Information in this document is subject to change. No part of this manual may be reproduced, transmitted, transcribed or translated into any language in any form by any means without the written permission of THEOS Software Corporation. Printed in the United States of America. THEOS Software Corporation 1801 Oakland Boulevard, Suite 315 Walnut Creek, CA 94596-7000 Telephone: 925-935-1118 Fax: 925-935-1177 E-mail: [email protected] WWW: http://www.theos-software.com THEOS® and the THEOS logo are registered trademarks of THEOS Software Corporation. Microsoft®, Windows®, Windows 95® and Windows NT® are registered trademarks of Microsoft Corporation.

Table of Contents Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Documentation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Account. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Attach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Calculator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Calendar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Cat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 CDPlayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 ChDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 ClassGen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Compress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 CopyFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 CRLF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 CRT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Decrypt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Dial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 DialNet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Eject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 EmailChk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 EmailDel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 EmailGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 EmailPut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Encrypt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Erase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Expand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 3

File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FileList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FileManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FileType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Force . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTP Script File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GetFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Head. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ident . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Img. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IXDiag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Keyword. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Killfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LineEdit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LogName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Look . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lowcase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MakeBoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mixer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MkDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . More. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Msg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Net . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Net Interactive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Net ARP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Net Browse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Net Exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Net Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Net Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Net Share . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Net Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4

227 229 243 245 247 251 255 257 280 283 289 291 295 297 299 301 307 309 313 317 319 323 331 333 335 335 339 347 349 353 357 361 363 365 367 369 373 377 379 388 390 391 393 393 399 399

Net Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 Net Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 Net Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 Net IPCFG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 Net . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 Net service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 NetTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 NsLookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429 Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 Patch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 Peek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 Ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 Play. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 POP3Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 Printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459 PutFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 PWD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 Quote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 Reboot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471 Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 Reminder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 Remote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483 Rename. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 Repeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493 Restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 RMCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 RmDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507 Route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511 Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 See . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525 SendMail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 Show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549 ShutDown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561 Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565 Split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 Spooler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583

5

Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SUMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SysEd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sysgen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TArchive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TBackup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TBrowse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Telnet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TFTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . THEO+COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TheoMail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using TIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Touch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TraceRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ALIGN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BARCODES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CHANGE_AREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CHECK_PRINTER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COLOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DEFAULT_UNITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FIELD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FILE_RECORDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FONT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IMAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LIST_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NEW_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PICTURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PRINT_NEXT_PAGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PRINT_RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PRINT_TXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PRINT_WINDOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REC_PAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ROTATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SELECT_AREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SETPOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6

583 587 589 591 593 595 597 601 611 633 635 637 645 647 649 653 657 666 673 675 677 681 685 687 689 690 690 691 692 693 695 695 695 696 696 697 698 698 699 699 700 701 701 702 702 703

STYLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703 TEXT_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704 UnErase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707 UnInstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711 Unique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713 Unload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717 Unnumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719 UnZip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721 Upcase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727 Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729 VNC Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733 WhereIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739 Which . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741 Who. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743 WhoAmI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743 WhoIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745 wBypass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749 wClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749 wClip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749 wClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750 wColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750 wFinish. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750 wFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750 wInvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751 wMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751 wMove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754 wMsgBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754 wOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756 wRefresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757 wRemove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758 wRestore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758 wSave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759 wSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759 wStat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761 wSwitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765 wTitle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766 WinWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767 WordCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771 Zip. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775

Appendices A Contacting THEOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781

7

8

List of Tables 1 RAM Disk Names and Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 2 Color Codes & Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 3 Disk Density Format Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 4 Floppy Disk Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 5 FTP Command-Line Edit Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 6 LINEEDIT Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 7 LINEEDIT Backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 8 ANSI Forms Control Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 9 Regular Expression Control Character Specification . . . . . . . . . . . . . . . . . . . . . . . . . . 342 10 Regular Expression Metacharacters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 11 More Command Browse Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 12 Patch Video Mode Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 13 Patch Expression Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 14 Unit of Measurement Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687

9

10

„ Introduction This manual describes each of the commands provided with the THEOS 32 operating system. They are arranged in alphabetical order by thier command names. Commands are executed by entering a command line when the CSI prompts you. Refer to Chapter 3 “Entering Commands” of the THEOS Corona Version 5 Operating System Reference, for a description of this process and the features of the operating system available when entering commands. Commands may also be executed by using a command line in an EXEC language program. Refer to Chapter 11 “EXEC Job Control Language” of the THEOS Corona Version 5 Operating System Reference, for a description of the EXEC language and its capabilities. Refer to Documentation Conventions for information about typographic conventions used here and throughout this manual.

Introduction

11

„ Documentation Conventions Throughout this manual, syntax is used that looks like: MAILBOX user MAILBOX user text MAILBOX user file MAILBOX ( option LIST file ( FILES option…

These symbols are used to show the correct syntax for typing the command. BOLD

Words and characters shown capitalized and in boldface must be entered exactly as shown.

italics

Italicized words show parameters supplied by you.

FILELIST

Underlined portions of a word indicate the minimum spelling allowed for abbreviations of the word.

…

An ellipsis indicates that the preceding term or terms may be repeated several times.

(EnterÌ˛)

Specific keys on the keyboard are shown with a “Key Caps” font.

These standards are used in the formal definitions of the syntax of a command or feature and in the descriptive text of the feature. The descriptive text also uses the following typographic conventions to identify the various items described. File names File names that appear in text are always shown in small caps. For instance, the SYSTEM.THEOS32.DEVNAMES file. Definitions A significant word or term that is being defined in the text is

shown in boldface italics. For instance: The command name is the name of the program you want to execute. Literal text Text appearing in an example that is also referred to in the

text description of the example is shown with a different typeface. For instance: When a report is aborted, the spooler prints the message “**** A B O R T **** ” and performs a form-feed.

12 Documentation Conventions

Account Command 1

C omm a nds

The Account command maintains or displays user accounts.

ACCOUNT

drive

2

ACCOUNT

drive ( option

3

ACCOUNT

drive ( ADD name add-options

Commands

1

drive

»

optional disk drive code

name

»

account name

option

»

DELETE name IDENT IMPORT filename

PRTnn SORT TYPE

add-options

»

COPY name FULLNAME name HOME directory PASSWORD password PRIVLEV nn

PROMPT prompt-text SUBDIR directory SYNONYM name USER name

Operation

For all modes the drive parameter is optional. It tells the Account command which drive to find the /THEOS/CONFIG/ACCOUNT.BIN file. By default, Account uses the S drive. Specify another drive when you want to maintain the accounts on another disk, such as your emergency boot diskette. Mode 1—Invokes the interactive mode of the Account command. This mode is identical to the Setup Account command which is described in the THEOS Corona Version 5 Operating System Installation and Setup Guide. Mode 2—This is a command-line mode that allows you to delete an existing account definition, to list all of the existing accounts on the console or printer or to merge the account definitions from another system’s account configuration file. For a complete description of this mode, refer to “Deleting Accounts” on page 17, “Listing Accounts” on page 18 and “Importing Accounts” on page 19. Mode 3—This is a command-line mode that allows you to add a new account definition. Only the basic components of an account can be defined with this mode by using one or more of the add-options described on page 15. To specify or change all of the environment switches or environment variables, you must use the interactive mode of the command.

Commands

13

Options

DELETE account Deletes an existing account definition. Specify the account name immediately following the DELETE keyword. >account ( delete accnts

Commands

Caution: If an account owns any files do not delete it unless it has a synonym account name defined. If you delete the account you might “orphan” the files owned by that account. See “Deleting Accounts” on page 17. IDENT

Use with the PRTnn or TYPE option to request that the account listing be in account number sequence. This is the default sequence for account listings. For a description of the account listing display, refer to “Listing Accounts” on page 18. >account ( type ident

IMPORT filename Merges the account definitions in filename with the cur-

rently defined definitions on this system. Any duplicate accounts names are replaced with the account definitions in filename. Typically, filename is an account definition file from another THEOS system, possibly an older version. For pre-Corona systems, the account definition file is /SYSTEM.THEOS32.ACCOUNT:S; for Corona systems, the account definition file is in /THEOS/CONFIG/A CCOUNT.BIN:S. PRTnn

Lists all of the existing accounts on the printer. nn specifies which attached printer to use and is in the range 1–64. The options IDENT or SORT may be used in combination with this option. When neither is used, the accounts are listed in account number sequence. The alternate keywords PRINT and PRINTER may be used instead of PRT.

SORT

Used with the PRTnn or TYPE option to request that the account listing is in account name sequence. For a description of the account listing display, refer to “Listing Accounts” on page 18. >account ( printer24 sort

TYPE

14 Account

Lists all of the existing accounts on the console. The options IDENT or SORT may be used in combination with this option. When neither is used, the accounts are listed in account number sequence. Refer to “Listing Accounts” on page 18.

Add Options

COPY acct-name Specifies that the new account definition will default to

When this option is not used, the switches and environment variables defined for the SYSTEM account are used as the default values for this new account definition. FULLNAME name The name is a free format name that will be assigned to the FullName environment variable when a user logs onto this

account. HOME directory Enter the directory name that you want any user to use

as their “home” directory. This is not necessarily the starting or initial current working directory, which is set by the SUBDIR directory option. The HOME directory is the quick access directory that can be quickly set as the current working directory by merely entering the CD command. It is also set as the Home environment variable which can be used by applications for their own purposes. PASSWORD password Specifies the password for the account. The password is specified immediately following the PASSWORD key-

word. When this option is not used the new account will have no password. >acc ( add jeff password "giraffe"

For a description of the password field, its limitations and its usage, refer to “Account Name and Number” on page 97 in the THEOS Corona Version 5 Operating System Reference. PRIVLEV value Specifies the privilege level for the new account. Privilege

levels are in the range 0–9. When this option is not used a privilege level of 1 is assigned to the account. >acc ( add jeff privlev 3

For a description of the privlev field, its limitations and its usage, refer to “Privilege Level” on page 99.

Account 15

Commands

the switches and environment variables defined for the account acct-name specified. When the acct-name exists the settings for the PROMPT prompt-string, CSI case mode, SUBDIR directory, PRIVLEV value, Decimal is comma, Language, and Work drive are copied from the acct-name definition to this new account definition. Also, any user-defined variables specified in the current definition of acct-name are copied to this new account definition.

PROMPT prompt-string Specifies the CSI command prompt for the new

account. When this option is not used the currently defined prompt is used for the new account.

Commands

To specify a prompt string that contains lowercase characters or special punctuation characters, surround the prompt string with a pair of double quotation marks. To use the prompt string variables described in on page 107 of the THEOS Corona Version 5 Operating System Reference, precede each backslant character with an extra backslant character. >account ( add rachel prompt "\\a\\g"

For more information about prompt strings, refer to the prompt environment variables described on page 107 of the THEOS Corona Version 5 Operating System Reference. SUBDIR directory Specifies the starting or current working directory for

the account. When this option is not used the account uses the HOME directory as its current working directory.

The directory specified here does not have to exist at this time. However, it should exist when the account is next used by Logon. If the directory does not exist when you log onto this account the HOME directory is set to the root. >acc ( add susan password "lion" subdir /private:s SYNONYM name Specifies the synonym account name for the new

account. The synonym account name is specified immediately following the SYNONYM keyword. The synonym account must be an existing account name. The new account is assigned the same account number as the synonym account. When this option is not used the new account is assigned the next account number available. >acc ( add master synonym system privlev 5

For a description of the synonym field and its usage, refer to “Account Name and Number” on page 97. USER name This option sets the UserName environment variable to name,

which is used by some utilities and applications to find any user-specific configurations that may be defined. For a description of USER names, refer to the UserName description in the THEOS Corona Version 5 Operating System Reference.

16 Account

Notes

Refer to Appendix D: “System Files” in the THEOS Corona Version 5 Operating System Reference for a description of the file “Account.bin”. The Account command can also be invoked via the Setup command.

Adding Accounts

The interactive method allows you to define all of the attributes of the new account including password policies specific to the account, an account description field, the various system switches, search sequence, command path, default file-type, and any user-defined variables. For a description of this method refer to the Setup Account command described in the THEOS Corona Version 5 Operating System Installation and Setup Guide. Deleting Accounts

Account definitions can be deleted with the command-line option DELETE account or by using the interactive mode of the Account command and using the “Remove” button. Before deleting an account name first check to see if there are any synonym accounts defined for it (list the accounts sorted by account number). If the account does not have a synonym account name defined check to see if there are any files owned by the account. Remember to check any removable disks. DO NOT DELETE an account name that does not have any synonyms and owns files. When deleting an account name that owns files, either create a synonym account name or use the Change command to change the ownership of the files to another account that will not be deleted. Access to files owned by a deleted account can be difficult.

Account 17

Commands

You can add new accounts using either the command-line mode (Mode 3) or the interactive mode. (You can also add new accounts by importing them from another systems account file. See “Importing Accounts” on page 19.) Which method you choose depends upon your needs. The command-line method only allows you to define some of the properties of the new account. However, because they are the most important properties, it may be sufficient for most uses.

Listing Accounts

All of the accounts defined can be listed on the console or on any of the attached printers. >account (type >account (prt32 sort

Commands

By default, the account listing is sorted in account number sequence (IDENT). This groups all synonym accounts together with the primary account for the id. You can use the SORT option to sort the account listing by account name sequence. >account (type Account SYSTEM BACKUPS BASIC INCLUDES MAIL PRIVATE JOHN TEST TESTIT

User 0 0 0 0 0 1 1 2 2

Synonym SYSTEM SYSTEM SYSTEM SYSTEM PRIVATE TEST

Prv 9 5 5 5 5 5 5 2 2

Password

Yes Yes

>account (type sort Account BACKUPS BASIC INCLUDES JOHN MAIL PRIVATE SYSTEM TEST TESTIT

18 Account

User 0 0 0 1 0 1 0 2 2

Synonym

Prv

SYSTEM SYSTEM SYSTEM PRIVATE SYSTEM

5 5 5 5 5 5 9 2 2

TEST

Password

Yes Yes

Importing Accounts

The import option can be used to import the accounting structure from another THEOS system, either a Corona system or an older THEOS 32, Version 4.x system. For instance, if you have just installed a new Corona system at a site that had an existing THEOS 32 system, you can copy the accounting structure from that existing system by first copying it to a floppy: Commands

>copy system.theos32.account f

Then, put that floppy in the new system and: >account (import /system.theos32.account:f

To import the accounting structure from an existing Corona system, copy that file to a floppy: >copyfile /theos/config/account.bin /account.bin:f >account (import /account.bin:f

When importing an accounting structure, remember that the imported accounting file will be merged with the existing accounts. If there are any duplicate account names in the two files only the imported definition will exist after importing the file. Cautions

Do not delete an account name if that account has any files and the account does not have a synonym account name already defined.

Restrictions

The Account command may be used by only one user at a time. The Account command may only be executed when you are logged onto the SYSTEM account (user number 0). The Account command requires a privilege level of five. Do not edit or change the /THEOS/CONFIG/ACCOUNT.BIN file with any program other than this Account command.

See also

Logon, Password , Set, Show, Start, Sysgen

Account 19

Commands

20 Account

Attach Command This command associates logical device names such as PRINTER with physical device drivers and specifies the attachment options for a device.

ATTACH logical physical ( options

2

ATTACH logical ( options

3

ATTACH logical

4

ATTACH

Commands

1

logical

»

logical device name CON console PRTnn printer COMnn com TAPEn tape A–Z disk

physical

»

device drive name as defined in /THEOS/CONFIG/DEVNAMES.TXT:S

options

»

ALF Bnnnnnn BIDIR Cnnn COPIES=nn COPY=nn CTS

DTR En ETX FFnnn HOLD Lnnn LFnnn

NOHOLD NP Onnn Pnnn PE PN PO

PZ XPC PUBLIC QUEUE=a STPnnn Vnnn Wn XON

System commands and application programs perform input and output to devices by specifying a logical device name. A logical device name is merely a standard name that any program can use to communicate with a device such as a disk drive, tape drive, printer, console or general communications device. The operating system takes this request from the program and passes it on to the physical device driver that is currently associated with the particular logical device name. For instance, a printer might be connected to the first serial port on the computer. When a program wants to print something on that printer, it outputs data to the logical device name PRT. The operating system passes the data to the SIO1 physical device driver which, in turn, passes it on to the printer connected to the first serial port. The Attach command is the primary method of changing the association of logical device names with physical device drivers. Other methods include Start and Sysgen.

Attach

21

Operation

Mode 1—Attaches the logical device name logical to the physical device driver physical, with options. The following examples show the attachment of the second hard disk drive to logical drive letter A, the attachment of the COM1 logical device to the third serial port, with options and the attachment of logical TAPE2 to a 250MB streaming tape drive. >attach a disk2

Commands

>attach com sio3 (b19200 w8 e2 >attach tape2 tape1

Mode 2—Changes the operating parameters or options of the logical device name logical without changing its assignment to its physical device driver. The following examples show the reattachment of COM1 with a change in the specified baud rate and the reattachment of the console with a change to the line length. >attach com (b38400 >attach con (l132

Mode 3—Detaches or disassociates the logical device driver logical from its current physical device driver. The following examples show the detachment of the printer4 device and disk drive G. >attach prt4 >attach g

You cannot detach the console or disk drive S. The physical device driver is unloaded from memory if no other logical device is associated with it by this user or any other user on the system. Mode 4—Displays the currently attached devices for this user. This display is always output to the standard output device and thus can be redirected to a file or another device: >attach > attach.output:f

When the standarrd output device is a graphics console, a windowed form is used to display the attached devices. If it is a text-only console then the title is displayed in reverse video and line graphics are used to box the columns. The line graphics characters can be suppressed if the LINEGRAPH environment variable is set to N (see “Environment Variables” on page 111).

22 Attach

When the standard output device is not the console, the title, column headings and line graphics are not output.

Commands

The “Device” displayed is the first name or synonym name found in the /THEOS/CONFIG/DEVNAMES.TXT:S file that matches the “Physical” parameters. For a description of this file, refer to Appendix D: “System Files” in the THEOS Corona Version 5 Operating System Reference. Options

ALF

Applies to printer attachments only. Specifies that the printer will perform an automatic line-feed upon receipt of a carriage return character. Normally THEOS appends a line-feed to a carriage return when sent to a printer. This option tells THEOS to not append the line-feed because the printer will do that automatically.

Bnnnnnn

Specifies the baud rate (serial devices only). Valid baud rates are dependent upon the physical device driver and are limited to the following values: 110, 300, 600, 1200, 1800, 2400, 3600, 4800, 7200, 9600, 19200, 38400, 57600, 76800 and 115200.

BIDIR

Indicates that bidirectional flow control is desired. May only be used on serial devices and not all device drivers support this feature. Normally flow control refers to the transmission of characters from the computer to the peripheral device. When the BIDIR option is specified, the flow control also applies to the receipt of data from the peripheral. For instance, a BIDIR with XON handshaking means that the device driver will send an XOFF to the peripheral when it is not able to accept more characters and an XON when it is ready again. This option is used in conjunction with the CTS, DTR, ETX or XON options. Attach

23

Commands

Cnnn

Applies to console and printer attachments only. Specifies the class code for input and output translation for the console or printer. For an explanation of class codes, refer to “Console Class Codes” on page 69.

CTS

Specifies CTS hardware handshaking (serial devices only). The driver will use the DTR (Data Terminal Ready) signal to know when the peripheral device is ready to accept another character.

DTR

Specifies DTR hardware handshaking (serial devices only). It’s similar to CTS handshaking except that the driver monitors the DTR (Data Terminal Ready) signal.

En

Specifies the handshaking protocol for flow control (serial devices only). Enable

Meaning

E0

Disables flow control.

E1

Synonym to DTR option.

E2

Synonym to XON option.

E3

Synonym to ETX option.

E4

Synonym to CTS option.

E5

Synonym to XPC option. PC Term software handshaking. Similar to XON/XOFF handshaking except that scan codes 103 and 101 are used to enable/disable transmission.

ETX

Specifies ETX/ACK software handshaking (serial devices only). The device driver sends blocks of characters. After a predefined number of characters are transmitted, an ETX (End of Transmission) code is sent and the driver waits for the peripheral to respond with an ACK (Acknowledge) code.

FFnnn

Applies to console and nonslave printer attachments only. Specifies the time in milliseconds to delay transmission after a FF (form-feed), IL (insert line), DL (delete line), EOS (erase to end of screen) or EOL (erase to end of line) code is sent to the console or printer. In general, this option is used only when E0 is specified and when the device is connected via a non-intelligent serial port.

Lnnn

24 Attach

Applies to console and printer attachments only. Specifies the displayable line length for the peripheral device. The default line length value is 80.

The line-length value for printers may be any value in the range 1–254. When attaching a console the line length specified is used in conjunction with the page size to determine the character size used. See “Console Screen Sizes” on page 72 of the THEOS Corona Version 5 Operating System Reference.

LFnnn

Applies to console and nonsalve printer attachments only. Specifies the time in milliseconds to delay transmission after a LF (line-feed) is sent to the console or printer. In general, this option is used only when E0 is specified and when the device is connected via a non-intelligent serial port.

NP

Specifies that no parity generation or checking is performed on data transmitted (serial devices only). Synonymous with the PN option. This is the default parity for serial devices.

Onnn

Applies to printer attachments only. Specifies the number of “overflow lines” for the device. Overflow lines are the lines between the last printable line on a page and the first printable line on the next page. This value is used in combination with the page length specified to determine the number of lines from one page to the next. The device driver counts each line of text transmitted. When a FF code is to be sent, the device driver sends line-feed characters instead. Line-feeds are transmitted until the page length plus overflow count is reached. For instance, a printer attached with P5 O1 means that there are six lines on each “page.” This attachment would be appropriate for printing one-inch labels. If three lines are printed followed by a FF, the device driver will send three line-feed characters instead of the FF code. This option is normally only used when the peripheral device does not support form-feed controls.

Pnnn

Applies to console and printer attachments only. Specifies the displayable page length for the peripheral device. The default page length value for printers is 58; for consoles it is 24.

Attach

25

Commands

To change the line length of a session on the main console, use the Session command.

The page length value for printers may be any value in the range 1–254.

Commands

When attaching a console the page length specified is used in conjunction with the line length to determine the character size used. See “Console Screen Sizes” on page 72 of the THEOS Corona Version 5 Operating System Reference. To change the page length of a session on the main console, use the Session command. PE

Specifies that even parity is used (serial devices only).

PN

Specifies that no parity is used (serial devices only). This is the default parity for serial devices.

PO

Specifies that odd parity is used (serial devices only).

PUBLIC

Specifies that the attachment of this device is to be public and available to other users. Devices attached as PUBLIC are only available to other users when they log onto the system from the “Logon please” prompt. See “Logoff” on page 335. That is, a user that is already logged onto an account will not have access to a newly attached public device. They must logoff and logon to get access to the new device. A publicly attached device cannot be reattached. To reattach a public device you must first detach it and all other users must be logged off or stopped.

26 Attach

PZ

Specifies that zero parity is used (serial devices only).

STPnnn

Applies to floppy disk devices only. Specifies the track-to-track step delay time in milliseconds.

Vnnn

Applies to VDI devices only and specifies the VDI device driver to use. See “Attaching VDI Graphics” on page 38.

Wn

Specifies the data word length (serial devices only). Word lengths may be either W7 or W8. W7 is the default word length for serial devices.

XON

Specifies XON/XOFF software handshaking (serial devices only). The device driver monitors incoming characters from the peripheral. Receipt of an XOFF character (0x13) means that the peripheral is busy and cannot receive any characters. Receipt of an XON character (0x11) means that the peripheral is ready to receive another character.

If the device is a console with a PC Term class code specified, then an XON request is interpreted as an XPC request. XPC

The following options may be used when attaching a printer to the Spooler. These options specify how subsequent reports sent to this printer will be handled by the printer spooler. They do not affect reports already sent to the printer spooler. COPIES=nn Specifies the number of copies to print for each report. COPY=nn

Synonymous with the COPIES=nn option.

nn

Synonymous with the COPIES=nn option.

HOLD

Reports printed are held and not erased.

NOHOLD

After a report is printed it is erased.

QUEUE=a

Specifies the queue letter that is assigned to subsequent reports. The queue letter a is always interpreted as an uppercase queue identifier.

QUEUE=$a Specifies the queue letter that is assigned to subsequent

reports. The queue letter a is always interpreted as an lowercase queue identifier or as one of the 12 special character queues. a

Synonymous with the QUEUE=a option. To designate a lowercase queue letter you must enclose it in quotation marks.

There are 64 possible single-characters queues: A–Z

26 forms/queues

a–z

26 forms/queues

#$%&*+-<=>^~

12 forms/queues

Previous versions of the spooler supported only the first 26 queues. To provide compatibility with programs and procedures designed for previous versions of the operating system, queue specifications default to the uppercase queue letters.

Attach

27

Commands

Spooler Options

Identical to the XON option except that it applies to PC Term consoles. Specifying XPC when the device is not a PC Term console is automatically translated to an XON request. The XPCON character has a value of 0x65 and the XPCOFF character is 0x67.

To specify one of the lowercase queue letters you must enclose the queue within quotation marks. The 12 special character queues may be specified without quotation marks. For instance: >attach prt2 spooler (a >attach prt2 (queue=x >attach prt2 (%

; Refers to queue A ; Refers to queue X ; Refers to queue %

Commands

To specify one of the lowercase queue letters you must either enclose the letter in quotation marks or use the special syntax “QUEUE=$queue.” >attach prt2 ("a" >attach prt2 (queue=$x >attach prt2 (queue=$$

; Refers to queue a ; Refers to queue x ; Refers to queue $

When in doubt about how a queue specification will be interpreted always use quotes and then specify the desired character with the desired case. For additional information about controlling the printer spooler, refer to “Spooler” and to the section “Print Spooler” in the THEOS Corona Version 5 Operating System Reference. Attaching Consoles

Your console is initially attached via the Sysgen configuration or from a Start command issued from another console or user. You cannot detach your own console. The Attach command can be used to change the attachment of your console, either to another device or merely changing one or more of the attachment options. For instance: >attach con (c94

Be careful when changing certain console attachment parameters such as baud rate, word length and parity because you might change to a setting that does not allow you to communicate with the computer. If that happens, you will have to go to another terminal and stop and restart your user, or you may have to reboot the computer. The class code is very important when attaching a console. It controls both how information is displayed on the screen and how keyboard characters are interpreted. To change the page or line length of a session on the main console, use the Session command.

28 Attach

Attaching Printers

THEOS allows each user to have as many as 64 printers attached (PRT1 through PRT64). Printers may be attached as private devices, public devices, spooled printers and slave printers.

A printer class code can define a printer setup string. This is a sequence of characters that initializes the printer. This string is sent to the printer by Attach when it is first attached. If the printer is not ready (powered off, unplugged or off-line), Attach will display a message for approximately 10 seconds as it waits for the printer to become ready. If it is not ready at the end of this time, the setup string is not sent but the printer will be attached. Attaching Printers to the Spooler To attach a public or private printer, use commands such as: >attach prt3 hslp2 (hplaser p60 l80

or >attach prt48 hslp3 (epson public

To attach a spooled printer the printer spooler must be started (see “Sysgen” on page 591 or “Spooler” on page 571). If the spooler is started, a

printer may be attached to it by using a command like: >attach prt8 spooler

or >attach prt50 spooler (l132 hold copies=2 b

Remember, attaching a printer to the spooler associates a logical name with the printer spooler. The physical printer attachment to the spooler is controlled by which printers were publicly attached at the time that the printer spooler was started. Attaching Slave Printers A slave printer is a printer that is physically connected to your console. It is usable only as a private printer because your console is always a private device. To attach a slave printer, use a command like: >attach prt6 con (epson

Attach

29

Commands

When attaching a printer you should specify a class code. A printer class code tells THEOS how to translate the various font attribute requests such as bold and italic. It also defines the translations for graphic and international character sets.

Attaching Remote Network Printers

Commands

If your system is connected to a local area network (LAN) and one or more of the other computers on the LAN have a printer connected and attached, your system may be able to use that remote printer. What determines this usability is whether or not the other computer has its printer server started and whether or not your system has configured names for the connection to the remote printer. If the other system is a THEOS system, its printer server is PrintNet. If the other system is a Windows system, its printer server is either PrintNet or Gutenberg. On this computer you must use the Setup Net command and then configure either the PrtNet Client or the Gutenberg Client. For information about these setups, refer to THEOS Corona Version 5 Operating System Installation and Setup Guide. To make an attachment to a network printer, the physical name that you use is a name like PRTNET1, PRTNET2, etc. or GUTENB1, GUTENB2, etc. Which names you use depends upon which client was configured in the setup for this system. >attach prt40 gutenb1

When attaching a network printer, do not specify the class code. Let the definition of the physical name define the class code.

30 Attach

Attaching Disks

Physical disk drives may only be attached to logical disk drive letters A–Z. Logical drive S is always attached as the “system disk” and cannot be changed with this command. Use the System command described on page 593 to reattach the system disk. By convention, the driver letter assignments are: A and B

DosDiskC hard drive:

C, D, etc.

THEOS floppy:

F and G

Ram disk:

M

CD Rom:

R

Booted drive:

S

Other THEOS hard drives:

other letters

Commands

DosDiskA floppy:

However, you may use any drive assignments you want. Most disk drives are attached when the system is booted, depending upon the configuration defined with Setup Sysgen. Drives attached at boot time are PUBLIC drives and every user that logs on to the system will have those drives attached and available for usage. Attaching Hard Disk Drives The only option available when attaching a hard disk drive is the PUBLIC option. Hard disk drive attachments are normally performed during system bootup due to specifications in the Sysgen (see page 591). Before a hard disk can be used for the first time it must be formatted. Refer to the THEOS Corona Version 5 Operating System Installation and Setup Guide for information about disk formatting and partitioning. Attaching Floppy Disk Drives The only options available when attaching a floppy disk drive are PUBLIC and STPnnn. Floppy disk drive attachments are also normally performed during system bootup due to specifications in the Sysgen command. To prevent access attempts to a publicly attached floppy disk drive that has no disk mounted in it, be sure to omit the floppy disk drive letter from the default search sequence. See the SEARCH environment variable description in the THEOS Corona Version 5 Operating System Reference.

Attach

31

Attaching DOSDiskA Floppy Disk Drives A DOSDiskA drive is one of the Installable File Systems (IFS) available with Corona. It is a diskette drive that contains a diskette formatted with a DOS or Windows file system. A single diskette drive may be attached as both a drive containing a THEOS file system (4GB) and a DOS file system. Commands

>attach f floppy1 >attach a dosdiska

In the above example, both drive attachments refer to the same physical diskette drive. When drive code F is referenced, the diskette in the drive must have a THEOS file system. Similarly, when drive code A is referenced the diskette in the drive must have a DOS or Windows file system. Attaching DOSDiskC Disk Drives Similar to DOSDiskA drives, the DOSDiskC drive is an IFS. It is a hard drive or drive partition that was formatted with a DOS or Windows file system. On a system that can boot either THEOS or Windows, the boot drive has two disk partitions. One is formatted with a THEOS file system and the other partition is formatted with a Windows file system. The DOSDiskC physical device name refers to the boot disk’s DOS or Windows partition. In a dual-boot system, you could access the Windows’ partition by attaching the drive: >attach c dosdiskc

Once it is attached, you can access the drive in the same manner that you would access it if it contained a THEOS file system. If your system has additional drives that are formatted with DOS or Windows file system you can attach them using other DOSDiskC drive names. The /THEOS/CONFIG/DEVNAMES.TXT file defines two additional DOSDiskC drive names: DOSDISKD and DOSDISKE. After an DOSDiskC drive is attached (or DOSDiskD or DOSDiskE), it can be used like any other disk drive. With DOSDiskA or DOSDiskC attachments you can copy files from or two a DOS-formatted diskette or hard disk partition. You can perform directory listings of those drives, etc.

32 Attach

Attaching RAM Disk Drives A RAM disk is a “pseudo-disk” that is actually an area of memory that is treated as a very fast access disk drive. A RAM disk is attached and used like any other disk drive.

RAM Disk Name

Size

RAM Disk Name

Size

RAM64K

64KB

RAM8MB

8MB

RAM128K

128KB

RAM10MB

10MB

RAM192K

192KB

RAM12MB

12MB

RAM256K

256KB

RAM16MB

16MB

RAM384K

384KB

RAM32MB

32MB

RAM512K

512KB

RAM48MB

48MB

RAM640K

640KB

RAM64MB

64MB

RAM768K

768KB

RAM96MB

96MB

RAM1MB

1MB

RAM128MB

128MB

1.5MB

RAM160MB

160MB

RAM2MB RAM3MB

2MB 3MB

RAM192MB RAM224MB

192MB 224MB

RAM4MB

4MB

RAM1536K

Table 1: RAM Disk Names and Sizes

You cannot attach a RAM disk that is larger than available memory, and you should not attach a RAM disk that uses so much memory that it prevents users from executing their programs. RAM disks, when attached, are automatically “formatted” and initialized as an empty disk drive. Once attached they can be “reformatted,” labeled, cleared, or have their main directory resized with the Disk command described on page 173. Since a RAM disk is only a pseudo-disk, do not use it for long-term storage because its contents are lost whenever the system is rebooted.

Attach

33

Commands

To attach a RAM disk, use one of the physical device names in the /THEOS/CONFIG/DEVNAMES.TXT file that indicate it is a RAM disk. The specific name used determines the physical size or capacity of the RAM disk.

Attaching Image Disk Drives

Commands

An image disk, as described on page 124 of the THEOS Corona Version 5 Operating System Reference, is a pseudo-disk that is actually a file on one of the currently attached disk drives. THEOS supports as many as eight image drives (IMAGE1, IMAGE2, ..., IMAGE8). To attach an image drive, use a command like: >attach i image2

Any drive letter (other than S) can be used as the logical drive name and it may be attached with the PUBLIC option. When an image drive is attached, the Attach command first looks to see if it can find a file named DISK.IMAGEn where the IMAGEn matches the device name used. If it can find that file, it uses it as the image drive. When it does not find the file it asks you for the image file name:

File Name. You must enter a file name. This name is used to find or create a file on an existing attached drive that contains the image drive contents. Be careful to use a name that is not an existing file name unless it is the name of an existing image drive file. If you expect to be using this image drive many times use the name DISK.IMAGEn where n is the number of this image drive attachment. If the file exists, Attach uses it as the image drive and does not change its contents. If the file is not found you must specify the file size using one of the three following methods.

34 Attach

Size MB. Enter a value here to create an image drive with a capacity measured in megabytes. Size GB. Enter a value here to create an image drive with a capacity measured in gigabytes.

File System. Choose the file system for the image drive. A 4GB system must be used if the image drive will be used as a copy of a diskette. In general, except for diskette images, you should only use a 4GB file system on an image drive if the image drive file will be shared with a THEOS 32 Version 4.x system. An LFS file system provides more than just large files and drives. It also has dynamic main directory size and dynamic library sizes. You may also specify the image drive file name on the Attach command line: >attach i example.img:a

If the file does not exist, Attach responds with the same form as above but the file name is already filled in with the name that you specified on the command line. After an image drive is attached, it can be used like any other disk drive. Attaching Remote Network Drives If your system is connected to a local area network (LAN) your system may be able to use directories and files on that remote system. What determines this usability is whether or not the other computer has given permission to access its file system and defined a share name for a directory on that file system. When there is a share name to a directory on a remote file system you can attach a drive letter to it by using UNC syntax: >attach x //REMOTE-COMPUTER-NAME/SHARE-NAME

If you do not know the name of the remote computer then use the Net Browse command to find all of the computers that you can currently access on the network.

Attach

35

Commands

Size cylinders. Use these three field if you want to create an image drive that has the same capacity as some real disk drive. For instance, if the image drive will be used to hold a copy of a floppy diskette you would specify that it has 80 cylinders, 2 heads and 36 sectors. This image drive could then be used to backup from or to a real diskette.

Attaching CD-ROM Drives CD-ROM drives are accessed using the CDROM Installable File System and they are attached similar to hard disk drives.

Commands

>attach r cdrom1 (public

Attaching Tapes

THEOS allows each user to have as many as four tape drives attached at one time (TAPE1, TAPE2, TAPE3 and TAPE4). The only option available when attaching a tape drive is the PUBLIC option. For instance: >attach tape tape1 (public

Before a tape can be used for the first time it should be initialized. Refer to “Tape” on page 597 for information about tape initialization. (TArchive requires manual tape initialization; TBackup performs automatic initialization prior to creating a new backup.) Attaching COM A COM device is a general purpose, bidirectional communications port. It is normally a serial port on the computer but it may be a parallel port. Ports THEOS allows each user to have as many as 16 communications devices (COM1 through COM16). To attach a communications device use a command like: >attach com multi2 (b38400 w8 cts pe

Com and Console the Same Device In some situations it is desirable to attach a logical COM device to the same physical port used by your console. This occurs when you are using THEO+COM or ScanTerm to be a user on a remote THEOS system, and you need to transfer files between the two systems. To perform this type of attachment use the command: >attach com con

This attaches the logical device name COM1 to the same port used by your console and it does not change any of the existing settings used by the console. For instance, the baud rate, word length, parity, etc. remain unchanged. When using this type of attachment, the operation of the com port will depend upon the COM=CON Default Bypass setting in the system configuration file. Refer to the Sysgen command for a description of this setting.

36 Attach

“Self Testing” Communications

For instance, a pair of programs that are intended to communicate between two THEOS systems via a COM port can be tested on a single computer system by using two users on the system. The first user would use an attachment like: >attach com1 self1

The second user on the same system would use an attachment like: >attach com1 self2

Different logical names could be used on each attachment and different options could be specified. The important feature of these attachments is that one user is attached to SELF1 and the other is attached to SELF2. These two “physical devices” communicate with each other on the same system. The physical devices SELF3 and SELF4 form another pair of devices that communicate with each other on the system. Any data transmitted by the first user to SELF1 will be received by the other user on SELF2, and vice versa.

Attach

37

Commands

In many cases a communications device is used to communicate with another remote computer system. To facilitate testing of programs using this type of remote access, THEOS provides a special device driver for performing self-testing. That is, testing of the communications by communicating with another user on the system. This device has four names of SELF1 through SELF4 and they operate in pairs.

Attaching VDI Graphics

A VDI or Virtual Device Interface device is a peripheral capable of displaying graphics. The main console can be used as a VDI device and also some printers. Some PC Term terminals can also be used as VDI devices. Each user may have as many as four VDI devices attached at one time (VDI1, VDI2, VDI3 and VDI4).

Commands

To attach your console as a VDI device, use a command like >attach vdi con

or >attach vdi3 con (v200

To attach a printer as a VDI device, use a command like >attach vdi2 prt (v216

or >attach vdi4 sio3 (b38400 w8 cts EPSON2

Notes

Except for the console and the optional slave printer, all other private devices are detached when you log off and all publicly attached devices are reattached when you log on. See “Logoff” on page 335. The logical devices PRT1, COM1, TAPE1 and VDI1 can all be specified as PRT, COM, TAPE and VDI respectively.

Defaults

There are no built-in default options for an attachment. Any defaults used by the Attach command are defined in the DEVNAMES.TXT file for the physical device being attached. For a description of this file see Appendix D: “System Files”, “/Theos/Config Directory”, “Devnames.txt” on page 211 of the THEOS Corona Version 5 Operating System Reference.

Cautions

Be careful when reattaching the console. Because the console is the device used to display the result of the attachment and to make further changes, reattaching the console incorrectly might result in loss of control for your process.

Restrictions

The CON and S logical devices cannot be detached. (It is possible to define a “user” that has no console. See “Start” on page 583.)

See also

ClassGen, Logoff, Net, Spooler, Start, Sysgen, System

38 Attach

Backup Command The Backup command makes an exact copy of one disk onto another disk or tape, or it restores a backup copy from a tape to a disk.

BACKUP

from-drive to-drive ( options

2

BACKUP

from-drive to-tape ( options

3

BACKUP

from-tape to-drive ( options

4

BACKUP

drive ( options

Commands

1

drive

»

drive letter of source and destination disk drive

from-drive

»

drive letter of source drive to backup

to-drive

»

drive letter of destination drive to backup to

from-tape

»

logical tape name of source tape to restore backup from

to-tape

»

logical tape name of destination of backup

options

»

ASK BUFFER FROM file MULTIUSER

Operation

NOASK NOVERIFY TO file VERIFY

Mode 1—This syntax causes BACKUP to copy the entire contents of fromdrive to the to-drive. The two drives may be any combination of hard disks, floppy disks, RAM disks, image drives or network drives, but they must both be the same capacity and format. Mode 2—Creates a backup copy of the from-drive contents onto the totape. The backup copy on the tape can only be used with a Mode 3 form of the BACKUP command. Mode 3—Restores a backup copy on the from-tape onto the to-drive. The backup copy on the tape must have been created by a Mode 2 form of the BACKUP command, and it must be a backup copy of a disk volume that has the same capacity and format as the to-drive. Mode 4—Creates a backup copy of the contents of drive by using one disk drive only. drive must be a removable disk drive. The backup is done by copying as much of the source disk as possible to memory, asking you to change the diskette in drive to the destination dis-

Backup

39

kette, copying the memory image to the destination diskette, and then asking you to switch back to the source diskette. This process is repeated until the entire source diskette is copied to the destination diskette.

Commands

This mode of the Backup command is most efficient when the BUFFER, TO or FROM options are used. Options

ASK

A default option that instructs Backup to ask the operator to mount the source and destination volumes, and waits for confirmation that the proper volumes are mounted. For instance: >backup f i Source is Disk F Destination is Disk I Mount volumes now: Source is labeled "Programs". Destination is labeled "Image". OK to start backup (Y/N)

Respond with a (EnterÌ˛) only for the “Mount volumes now:” request, and a (Y) or (N) for the “OK to start backup” question. Use the NOASK option to override this default. BUFFER

Valid only with Mode 4 of the command. When used without the FROM or TO options, this option causes Backup to use a temporary file on the S drive as an image buffer of the single drive backup. In other words, the contents of the source diskette are written to a temporary file, the destination diskette is placed in the drive, and the contents of the temporary file are written to the destination diskette. The temporary file is then erased.

FROM

This option is used in combination with the BUFFER option to specify that a file created from a previous backup using the BUFFER TO option is to be used as the source for this backup. The file name is specified following this option: >backup f (buffer from distrib.master:s

The file must be a file created from a previous backup using the BUFFER TO option. The format of this backup disk (number of cylinders, heads and sectors) must be identical to the format of the original backup disk when the file was created. See TO option below.

40 Backup

MULTIUSER

Allows Backup to copy a public drive even though other users may be logged on and active. When Backup is instructed to perform a backup of a public disk, it requires single user mode. If other users are logged onto the system, it displays the message: “Must be single user or private volume.”

Use this option only if you are sure that all other users are inactive. NOASK

Disables the source and destination volume operator confirmation at the beginning of the backup and when subsequent disks or tapes are needed.

NOVERIFY Disables the verify after write operation. See VERIFY option

below. TO

This option is used in combination with the BUFFER option to specify that the destination of the backup is not another disk but a file. The file name is specified following this option: >backup f (buffer to distrib.master:s

Although the file created with this option can be copied to another drive, transmitted to another computer, etc., just like any other stream file, it is intended to be used as the source for another backup using the BUFFER FROM option or as an image drive. VERIFY

Applies only when the to-drive is a disk not a tape. This option causes Backup to read each track of data immediately after writing it to the to-drive. The information is then compared with the original information from the from-drive. Only when the data is the same does the backup continue to the next track.

Backup

41

Commands

Using this option tells Backup to not restrict the backup to single-user operation (the message is still displayed). THIS CAN BE EXTREMELY DANGEROUS! If another user changes some files while the backup is being created, the integrity of the backup is lost.

Notes

When a backup is performed, both the from-drive and the to-drive are modified to reflect that the disk was the source or destination of a backup. For instance, after a backup of the F drive:

Commands

>disk f Disk F label "Programs". Backup to disk "ProgCopy" on 10/26/01, at 13:20. File system = THEOS/4GB. Capacity = 1,474,560 (80 cylinders, 2 heads, 36 sectors). Main directory size = 4 files. Allocated bytes = 165,632. Available bytes = 1,308,928.

While the backup copy is being created the current cylinder and head number are displayed on the console. This information is provided so the operator can see how the backup is progressing. Defaults

ASK, NOVERIFY

Cautions

The MULTIUSER option tells the Backup command to not check whether or not other users are logged on or active. It does not prevent those other users from performing operations that change the database that’s being backed up. If another user does change the database during the backup operation, the integrity of the backup is compromised. Backup always destroys the prior contents of the destination drive, before any new data is written to the drive.

Restrictions

The from-drive and the to-drive must have the same format. That is, they must both have the same number of cylinders, heads and sectors. The Backup command requires a privilege level of four.

See also

42 Backup

TArchive, CopyFile, Disk, Restore, Tape, TBackup

Cache Command The Cache command enables, disables, controls or reports on the disk cache. For a general description of the THEOS disk caching capabilities, refer to “Disk Caching” on page 126.

CACHE

2

CACHE

function

function

Operation

Commands

1

»

DELAY OFF DELAY ON OFF ON

STATUS SYNC WBDIR OFF WBDIR ON

Mode 1—Invokes the interactive mode of the Cache command as described on page 44. Mode 2—Performs one of the functions described below.

Functions

DELAY OFF Disable disk write delay. Note that this also will disable direc-

tory write caching. DELAY ON Enable disk write delay. OFF

Disable disk caching. When disk caching is disabled, the memory used by the disk cache is freed.

ON

Enable disk read/write caching.

NOWBDIR

Synonymous with WBDIR OFF.

STATUS

Display disk cache statistics as described on page 44.

SYNC

Force disk synchronization with memory cache.

WBDIR OFF Disable directory write caching. WBDIR ON Enable directory write caching. The keyword “ON” may be

omitted.

Cache

43

When the STATUS command line option is used, or when Mode 1 of the Cache command is used, the following screen appears.

Commands

Cache Status and Statistics Display

This display remains on the screen and has two sections: a top section that displays the Cache Status Display and a lower section showing the Cache Statistics Display that is updated approximately once per second. This display is only available if disk caching is enabled.

44 Cache

„ Cache Status Display The top portion of the display shows the current disk cache settings. These settings are controlled by the Cache command itself or from information recorded in the Sysgen configuration. Setting

The value shown here indicates the amount of memory used by the disk cache system for caching data from physical disks. It is shown in kilobytes so the value illustrated in the previous figure reflects a six megabyte disk cache. The disk cache size is normally set in the Sysgen configuration but it may also be set by the Cache command itself if no size is specified in the configuration and the Cache command enables disk caching. A default size of 4MB or ¼ of the available memory is used in this situation.

Block size (bytes)

The block size is determined by the cache size. It indicates the smallest amount of data that is read or written to disk.

Number of blocks

This is a computed value that reflects the number of blocks of data that can be held in the disk cache memory. It is computed by dividing the cache size by the block size.

Write delay

Shows the status of the cache write delay as set by the Cache DELAY function or the Sysgen configuration.

Directory write back

Shows the status of the cache directory write back feature as set by the Cache WBDIR function or the SYSGEN configuration. Cache Status Display

Cache

45

Commands

Cache size (kilobytes)

Meaning and Source

„ Cache Statistics Display

Commands

The lower portion of the display shows the current cache statistics. This information is updated approximately once per second, thus showing the disk activity of other users and tasks. Display Item

Meaning

Instantaneous hit rate:

Shows the rate of success for the most recent disk access requests over the last three seconds, or so.

Average hit rate:

Shows the overall rate of success reflecting the percentage of the times a disk access request was satisfied since disk caching was enabled Shows the number of blocks of data currently in the disk cache that have not been written to the physical disk yet.

Number of modified blocks:

Number of probes:

Shows the total number of times that a read or write request was made.

Number of hits:

Shows the number of times that a request for information from the disk was able to be satisfied by information already in the disk cache memory.

Number of syncs:

Indicates the number of times that the disk cache system has been forced to synchronize itself with the physical disk. (See SYNC function.)

Number of reads:

Shows the number of times the disk cache system has provided information from a disk read request. This includes the times when the information is already in the disk cache memory and the times that it had to read from the physical disk.

Number of writes:

Shows the number of times the disk cache system was asked to write information to the disk. This includes the number of blocks still in the cache memory waiting to be written to the physical disk (dirty blocks).

Number of bypasses

Indicates the number of times that the disk cache system was bypassed, probably due to a request from a large read or write operation for “one time only” data. Cache Statistics Display

46 Cache

When using Mode 1 of the Cache command, when you select the “Control” button, a form is displayed allowing you to change the various disk caching parameters.

Notes

A Cache SYNC operation is performed when you reboot the system using Reboot or (Ctrl)+(Alt)+(Del).

Cautions

The performance improvements when using disk caching with write delay enabled are considerable. However, there is a slight risk to data integrity. If a power failure occurs or if the system is reset between the time that a program requests a disk write operation and when the disk caching software actually performs the write to the physical disk, the data cannot be written.

Commands

Cache Control

If this risk is unacceptable, you can still take advantage of disk caching with write delay enabled and greatly reduce this risk by utilizing an online uninterruptable power supply (UPS) for your computer system. Restrictions

The Cache command requires a privilege level of five. If disk caching is disabled, the Cache STATUS cannot be displayed.

See also

Sysgen

Cache

47

Commands

48 Cache

Calculator Command Calculator displays a calculator that can be used to perform basic arithmetic.

CALCULATOR Commands

Operation

The displayed calculator is:

Notes

With the calculator displayed you may perform the following actions: Mouse –

Keyboard

Action

(0) – (9)

Append this digit to the end of the current number.

(.)

Append a decimal point.

(+)

Add the next number entered to the total.

(-)

Subtract the next number entered from the total.

(*)

Multiple the total by the next number entered.

(/)

Divide the total by the next number entered.

(=) or (EnterÌ˛)

Perform the arithmetic and display the new total.† Calculator

49

Commands

Mouse

Keyboard

Action

(%)

Multiply the total by the current entry interpreted as a percentage.

(R)

Change the current entry to the reciprical of that value.

(G)

Change the sign of the current entry.

(@)

Change the current entry to the square root of the value.

(C)

Clear the total and the current entry.

(E)

Clear the current entry.

(Ctrl)+(L)

Clear memory.

(Ctrl)+(R)

Recall memory (change current entry to the value in memory).

(Ctrl)+(S)

Save the current entry in memory.

(Ctrl)+(P)

Add the current entry to the value in memory.

(Esc)

Exit Calculator.

†. The equal sign action causes the last operation entered to be applied to the current entry and the total, with the current entry changed to that new total. For instance, entering (C)(1)(+)(2) causes the total to be 1, the current entry to be 2 and the last operation specified to be addition. Entering (=) at this time causes the 2 to be added to the 1 making the new total and the displayed current entry to be 3. Entering (=) again causes the current entry of 3 to be added to the total of 3 making the new total and the displayed current entry to be 6. Return Code

Upon exit from Calculator, the return code is set to the integer value of the last displayed value.

Restrictions

The values that may be entered or displayed are limited to 13 digits of precision and must be in a range of ±9.999999999999×10126.

50 Calculator

Calendar Command Calendar displays a calendar for a single month or for an entire year.

CALENDAR

2

CALENDAR month

3

CALENDAR month year

4

CALENDAR year

Commands

1

month

»

calendar month number, month name or abbreviation

year

»

calendar year number, with or without century number

Operation

Mode 1—Displays the current month calendar in an interactive window that can be used to browse and display other month calendars.

Initially, the current date is highlighted with a circle around the date. You can highlight different days or change the calendar view by using the (˜), (¤), (˚), (˙), (PageUp), (PageDown), (Home) and (End) keys. You can also use the mouse to select different days, months or years. If the selected date is a recognized holiday, the holiday name is displayed at the bottom of the form. The holidays recognized by the Calendar command are defined in the CALENDAR.CFG file. For a description of this file refer to Appendix D: “System Files”, “/Theos/Config Directory”, “Calendar.cfg” on page 210 of the THEOS Corona Version 5 Operating System Reference.

Calendar

51

Mode 2—Displays the calendar for month in the current year in month display format (see “Month Display” on page 53). The month may be specified as a month number of the year (1–12), a month name (January, February, etc.) or with a month name abbreviation (Jan, Feb, Mar, etc.). For example: >calendar 3

Commands

>calendar March >calendar mar

The above three commands will display the calendar for March of the current year. Mode 3—Displays the calendar for month in year in month display format (see “Month Display” on page 53). The month may be specified as it is for Mode 2. The year may be specified as a year number in the current century (0–99) or as a complete year number (1776, 1812, 1997, 2004, etc.). See “Date Limitations” on page 52. For instance: >cal 7 1776

; Display July, 1776

>cal July 1776

; Display July, 1776

>cal Jan 3

; Display January, 2003

Mode 4—Displays the calendar for year in year display format (see “Year Display” on page 53). The year may be specified as in Mode 3, with the

exception of current century years less than 13. To avoid confusion with a Mode 2 request, years between 1–12 must be specified with their century

number (1901, 1902, etc.). For example:

Date Limitations

52 Calendar

>calendar 0

; Display 2000

>calendar 1903

; Display 1903

>calendar 3

; Display March, current year

>calendar 2010

; Display 2010

Only Gregorian calendar dates are displayed correctly by this program. Because the Gregorian calendar was inaugurated October 15, 1582, only calendars for years greater than or equal to 1583 are displayed by this command.

Month Display

When a single month is displayed by Calendar (Mode 2 and Mode 3), a simulated calendar page is drawn on the screen. For instance:

April Sun

Mon

Tue

Wed

Thu

Fri

Sat

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

Commands

Year Display

2002

When a full year is displayed by Calendar (Mode 4), two screen displays may be used if the attached screen size is insufficient to display the entire calendar. For instance, if a CALENDAR 2002 is requested with a display attached at 80 by 24:

A similar screen is displayed for the months July through December.

Calendar

53

Notes

The month names are defined in the /THEOS/OS/MESSAGE/language/MESSAGE.BIN file, numbers 260–261. For a description of this file, refer to Appendix D: “System Files,” starting on page 209.

Commands

If the calendar display is redirected to a device or file other than the console, month displays are output in a format similar to the year display, but for one month only. Restrictions

54 Calendar

See “Date Limitations” on page 52.

Cat Command Filter The Cat command is a filter that concatenates one or more files and outputs the result to the standard output device. For a description of command filters, refer to “Standard Input, Standard Output and I/O Redirection” on page 53 of the THEOS Corona Version 5 Operating System Reference.

CAT

( options

2

CAT

file… ( options

file

»

file name with optional path; may contain wild cards

options

»

NOTYPE TYPE

Operation

Commands

1

Mode 1—Copies text from the standard input device to the standard output device. Mode 2—Each file is copied to the standard output device, one after the other. >cat one.file two.file

This command copies ONE.FILE to the standard output device and then appends TWO.FILE to the end. >cat text.file1 text.file2 text.file3 > new.text

This second example uses i/o redirection to change the standard output device for this command. It is equivalent to: >copy text.file1 new.text >copy text.file2 new.text (append >copy text.file3 new.text (append

The standard input device file can be included in the list of files to be copied by using the “-” specification as a file name: >cat - one.file two.file

This command copies the contents of the standard input device file to the standard output device and then appends ONE.FILE and TWO.FILE onto the standard output device file.

Cat

55

When one or more of file contains a wild card specification, the files matching the specification are sorted in alphabetical sequence and then processed as if they were specified individually. For instance, assume that there are files named LETTER.DOCUMENT, MEMO.DOCUMENT and SPECIAL.DOCUMENT:

Commands

>cat *.document

This command is equivalent to: >cat letter.document memo.document special.document

Options

NOTYPE

Suppresses all error message display.

-s

Synonymous with the NOTYPE option described above. To use this option, do not use the left parenthesis. Instead, merely specify it somewhere in the command line. >cat -s one.file two.file >cat one.file two.file -s

TYPE

A default option that allows error messages to be displayed. The most common error message is “File not found.” which is output when one or more of the input files does not exist. Error messages are displayed on the standard error device which is normally the same as the standard output device.

Notes

A file specification can omit the file type if the environment variable FILETYPE is defined.

For more information about the FILETYPE variable, see “Environment Variables” on page 111 of the THEOS Corona Version 5 Operating System Reference. When the standard input device is the console, the end-of-file is indicated by pressing (Ctrl)+(D). When the standard output device is a disk file, it is erased prior to outputing the first file. Subsequent files are then appended to this new file. To append a file to an existing file, use the append i/o redirection symbol: >cat new.file >> old.file

As a command filter, Cat can be used in a pipe command: >filelist *.basic | cat heading.file - > result.file

56 Cat

This command line creates a directory listing and pipes this output to the Cat command, which first outputs HEADING.FILE to RESULT.FILE and then appends the directory listing which is now in the standard input device. See also

CopyFile

Commands

Cat

57

58 Cat

Commands

CDPlayer Command The CDPlayer command plays an audio CD in the CD-ROM drive.

CDPLAYER drive

2

CDPLAYER drive PLAY

3

CDPLAYER drive PAUSE

4

CDPLAYER drive RESUME

5

CDPLAYER drive STOP

6

CDPLAYER drive RANDOM

7

CDPLAYER drive LIST

8

CDPLAYER drive TRACK track

9

CDPLAYER drive LOOP

Commands

1

10 CDPLAYER drive RANDOM LOOP drive

»

drive code letter of an attached CD-ROM drive

track

»

track number of audio CD in drive

Operation

Mode 1—This is the interactive play mode of the CDPlayer command. In this mode, the audio CD is played, starting at track one. >cdplayer

If the artist, title and track titles have been entered into the CD-ROM catalog for the disc in drive, that information is displayed as each track plays

CDPlayer

59

(see “CDDB” on page 62). If the information is not available, only the time remaining and the track number are displayed. See “Graphics Display” on page 62 for additional information. On non-graphic consoles, the CDPlayer command displays the track number, time remaining in the track and the title if known. Commands

>cdplayer d 1: [01:52]

While this mode is operating, you may use the (PageDown) or (¤) key to jump to the next track, and the (PageUp) or (˜) key to jump to the previous track. The (EnterÌ˛) key replays the current track and the (Esc) key exits the program and terminates playing the album. Mode 2—Starts playing the audio CD in drive. If the artist and album title have been entered into the CD-ROM catalog for the disc in the drive, that information is displayed (see “CDDB” on page 62). The command exits but the disc continues playing until it reaches the end of the album. >cdplayer c play Don Ho: Tiny Bubbles >

While the disc plays, there are very few, if any, resources used and there is minimal impact on the operation of the system. Mode 3—Pauses but does not stop the playing of an audio disc in drive. If no disc is playing (see Mode 2), no error is detected or reported. Mode 4—Resumes playing of an audio disc in drive that was paused with a Mode 3 command. If no disc is playing (see Mode 2) or it is not paused, no error is detected or reported. Mode 5—Stops playing the audio disc in drive. If no disc is playing (see Mode 2), no error is detected or reported.

Mode 6—This is an interactive play mode of the CDPlayer command, similar to Mode 1. However, in this mode, the audio CD is played in random order. >cdplayer d random Lawrence Welk: His Greatest Hits 10: [-03:21] Beer Barrel Polka

If the artist, title and track titles have been entered into the CD-ROM catalog for the disc in drive, that information is displayed as it plays each track (see “CDDB” on page 62). If the information is not available, only the time remaining and the track number are displayed. 60 CDPlayer

While this mode is operating, you may use the (PageDown) or (¤) key to jump to the next track in the random order. The (EnterÌ˛) key replays the current track and the (Esc) key exits the program and terminates playing the album. When each track has been played once, the program exits. Commands

Mode 7—Displays the descriptive information about the CD in drive. >cdplayer d list Shania Twain / Come On Over 1: [03:54] Man! I Feel Like A Woman! 2: [03:26] I’m Holdin’ On To Love (To Save My Life) 3: [03:33] Love Gets Me Every Time 4: [03:34] Don’t Be Stupid (You Know I Love You) 5: [04:41] From This Moment On 6: [02:54] Come On Over 7: [03:39] When 8: [03:48] Whatever You Do! Don’t! 9: [04:03] If You Wanna Touch Her, Ask! 10: [03:32] You’re Still The One 11: [03:35] Honey, I’m Home 12: [03:38] That Don’t Impress Me Much 13: [03:39] Black Eyes, Blue Tears 14: [04:12] I Won’t Leave You Lonely 15: [04:22] Rock This Country! 16: [03:29] You’ve Got A WayDon McLean: Classics

The times listed for each track are the times specified in the index on the audio CD. The disc and track titles are from the CD-ROM catalog of the disc (see “CDDB” on page 62). Mode 8—Plays the single track of the audio CD in drive. If the artist and album title have been entered into the CD-ROM catalog for the disc in the drive, that information is displayed along with the track title (see “CDDB” on page 62). The command exits but the disc continues playing until it reaches the end of the requested track. Mode 9—Identical to Mode 2 except, after all of the tracks on the disc have played once, the disc is played again. This continues until CDPlayer is exited by entry of the (Esc) key. Mode 10—Identical to Mode 6 except the tracks are played randomly until CDPlayer is exited by entry of the (Esc) key. Notes

A drive mount operation is performed when CDPlayer first starts. This operation closes the drive tray if it is not already closed. You can open the drive tray with the Eject command or by using the eject button of the graphic CD Player (see “Graphics Display” on page 62).

CDPlayer

61

The drive specification may be omitted. When not specified, the first attached CD-ROM drive is used.

CDDB

When CDPlayer starts playing a disc it determines a unique code for the disc and checks to see if the system has disc and track title information saved for the disc. This information is saved in the /THEOS/CONFIG/CDDB.BIN:S file. When there is no information in this file and you have an active internet connection, the FREEDB.ORG database is queried for information about this disc. That information, if available, is saved in the CDDB.BIN file for subsequent playing of this disc.

Commands

Defaults

The FREEDB.ORG is a free, public database of CD titles and track information. The server and database is implemented with GNU software copyrighted by the Free Software Foundation. Not all discs are cataloged with FREEDB.ORG, although it is updated constantly. Some discs will display no disc or track titles. Graphics Display

When CDPlayer is invoked from a graphics console, a graphic representation of a CD player is displayed with controls. These controls may be manipulated with the mouse pointer.

Disc title Play Pause

Previous track Next track Stop

Help Mixer Intro Repeat Random Eject

Track information

Disc select

A mouse (either actual or virtual) can be used to control the actions of the CDPlayer command. When the mouse pointer hovers over one of the con-

trols its description is displayed just below the control buttons. The two list boxes near the bottom of the graphic player show the tracks on the disc and the attached disc drives that are available.

62 CDPlayer

Restrictions

The system must have at least one CDROM drive attached; there must be a supported sound card installed and configured. The CD-ROM disc in drive must be an audio CD.

See also

Attach, Eject, Mount, Play

Commands

CDPlayer

63

Commands

64 CDPlayer

Change Command The Change command changes a file’s attributes.

CHANGE

file ( options

2

CHANGE

file ( FILES options

3

CHANGE

( options

Commands

1

file

»

file name with optional path; may contain wild cards

options

»

ACCOUNT name FILES GROW n.m NOQUERY NOTYPE OWNER name PATCH nnnnnnn

Operation

PRIVATE codes PRIVLEV nn QUERY SHARED codes TOUCH TYPE

Mode 1—Changes file according to options. >change *.data (touch Ok to change "FILE1.DATA:S" (Yes,No,All) Y "FILE1.DATA:S" changed. Ok to change "FILE2.DATA:S" (Yes,No,All) N Ok to change "FILE3.DATA:S" (Yes,No,All) A "FILE3.DATA:S" changed. "FILE4.DATA:S" changed.

Mode 2—The files listed in file are changed according to options. file must be an ASCII stream file containing one file description per line. The SELECTED.FILES and SELECTED.EXEC files created by FileList and the FOUND.EXEC created by Look can be used for this specification file (see “The EXEC and FILES Options” on page 239). You may also create the file with an editor or application program. For instance, FileList is used to create a list of files to be changed: >FILELIST *.DATA:A (EXEC >FILELIST A NOT *.DATA:A (10/1/01 EXEC APPEND

A file now exists that lists all of the “data” files and all files that have been changed since 10/01/2001. The following command will change the ownership of these files to another account:

Change

65

>change selected.exec (file account develop

Mode 3—Enters the interactive mode for selecting files to be changed. >change (touch Enter file name list, terminate with empty line. ?

Commands

You may enter any file name desired, with optional path and possibly wild card specifications. For instance: >change (touch noquery Enter file name list, terminate with empty line. ?*.data "FILE1.DATA:S" changed. "FILE2.DATA:S" changed. "FILE3.DATA:S" changed. "FILE4.DATA:S" changed. ?*.text "FILE1.TEXT:S" changed. "FILE2.TEXT:S" changed. "FILE3.TEXT:S" changed. ? >

Options

ACCOUNT

Changes the account ownership of the files. The new owning account is specified immediately following this keyword: >change data.file (account develop

You must be logged onto the account that currently owns the file. This option must be used by itself. That is, you may not change the ownership of a file and its protection codes, growth factor, etc. You may only change the ownership of a file in the root directory. You may not change members of a library (however, the library itself may be changed). FILES

Indicates that Mode 2 of the Change command is to be used. The file specifies an ASCII stream file, with each record in the file specifying a single file name. The file name specifications in this file may include the path to the file. For instance, a line in the specification file might contain: custom/programs/program.source.sample:s

If this file is used in a Change command, the display will be:

66 Change

>change selected.exec (file "/CUSTOM/PROGRAMS/PROGRAM.SOURCE.SAMPLE:S" changed. GROW

Specifies the growth factor for the file. >change data.file (grow 0.5

For an explanation of file growth factors see “Growth Factor” on page 146. NOQUERY Tells Change to not ask for confirmation before applying the

requested change to a file. This is a default option for explicit file specifications. NOTYPE

Suppresses the display of the file changed messages.

OWNER

Synonymous with the ACCOUNT option.

PATCH

Changes the patch level for a program file. The new patch level is specified immediately following this keyword: >change special.command (patch 10001

Patch levels may only be added or changed in programs, device drivers or the system nucleus. PL

Synonymous with the PATCH option.

PRIVATE

Changes the owning account protection codes. The new protection codes are specified immediately following this keyword: >change my.file (private nmexwr

See “Changing Protection Codes” on page 69. PRIVLEV

Changes a command’s privilege level. The new privilege level is specified immediately following the keyword: >change my.command (privlev 3

Change

67

Commands

Growth factors are specified as either a whole number, such as 1, 2, 3, etc., or as a fraction, such as 0.1, 0.3, 0.5, etc. Do not specify a combination like 1.3. If you do, only the integer portion is used. Program and stream files do not have growth factors.

QUERY

Tells Change that you want to be “queried” or asked if each file matching the selection criteria is to be changed. This is a default option when the file specification used wild cards.

Commands

>change *.data (touch Ok to change "FILE1.DATA:S" (Yes,No,All) Y "FILE1.DATA:S" changed. Ok to change "FILE2.DATA:S" (Yes,No,All) N Ok to change "FILE3.DATA:S" (Yes,No,All) A "FILE3.DATA:S" changed. "FILE4.DATA:S" changed.

When asked, you may respond with a (Y) to change the file, an (N) to not change this file, or an (A) to change this file and all subsequent files. Pressing (Esc) exits the CHANGE command but, all changes made prior to the (Esc) entry are retained. To disable this option use the NOQUERY option. SHARED

Changes the shared access protection codes. The new protection codes are specified immediately following this keyword: >change my.file (shared wr

See “Changing Protection Codes” on page 69. TOUCH

Changes the file’s date and time to the current system date and time. This is a default option when no other options are specified.

TYPE

A default option that tells Change to display each file that is successfully changed. To disable this option use the NOTYPE option.

Notes

68 Change

Multiple options may be specified on a single command. For instance, you may request a change in a file’s growth factor, private and shared protection codes and its file date. However, you may not use the ACCOUNT or OWNER option with any other option.

Changing Protection Codes

A file has two types of protection codes associated with it: private and shared access. The private protection codes restrict what a user on the owning account may do with the file. The shared access protection codes restrict what a user on a non-owning account may do with the file. Private protection codes include: Meaning

w

Write protection. The file cannot be written to.

r

Read protection. The file cannot be read.

e

Erase protection. The file cannot be deleted.

x

Execute protection. The file cannot be executed.

Commands

Code

There are two other codes that may be specified here although they are not really protection codes: Code

Meaning

m

Set the “modified” attribute.

h

Set the “hidden” attribute.

Shared access protection codes include: Code

Meaning

w

Write protection. The file cannot be written to.

r

Read protection. The file cannot be read.

Shared access erase protection exists when a file has any of the following protection codes enabled: erase, shared read or shared write. Shared read and write protection is always enabled if the private protection is set to read or write protected. That is, setting private write protection enables shared write protection. With the exception of private read protection, each of these attributes may be turned off by preceding the protection code with the letter n. Multiple attributes may be set at one time by specifying the multiple codes one after the other without any separating spaces. The protection codes may be specified in any sequence. For example: >change my.file (private nmenw shared rw

Change

69

Commands

The above command sets the following attributes for the file: not modified, erase protected, not write protected, not read protected, shared access read and write protected. Private read protection, once set, cannot be removed. Shared read and shared write protection cannot be disabled if the file still has private read or private write protection enabled. For instance, to disable shared write protection you must also disable private write protection. Defaults

Touch is a default option when no other options are specified. QUERY is a default option for file specifications using wild cards. TYPE is a default

option. Cautions

After changing a file to hidden, it will not appear in a directory listing (see “FileList” on page 229). However, most commands, including Change, allow access to a hidden file. Private read protection cannot be reset.

Restrictions

The ACCOUNT option must be used by itself. To apply any changes to a file with this command, you must be logged onto the owning account.

See also

70 Change

Touch

ChDir Command The ChDir command changes the current working directory.

CHDIR directory

2

CHDIR

directory

»

Command synonym: Operation

Commands

1

path to new directory CD

Mode 1—Changes the current working directory to the specified directory. >chdir programs

The directory may be a simple subdirectory name as shown in the above command line, or it may be a partial or complete path specification to the desired directory. When directory does not start with the root directory specifier ( / ), it is assumed to be a subdirectory of the current working directory or a reference to a directory relative to the current working directory. For instance: >pwd /DEVELOP:S >chdir programs >pwd /DEVELOP/PROGRAMS:S >chdir ../doc/files >pwd /DEVELOP/DOC/FILES:S

The second example of the ChDir command shows a usage of the special double period directory name ( .. ) pronounced dot, dot. This syntax is a reference to the parent directory of the current working directory. In the example, the current working directory was /DEVELOP/PROGRAMS:S so the parent of this directory is /DEVELOP. Multiple dot, dot specifications can be used to indicate that the reference is to the parent of the parent of the parent, etc. For instance: ../../../../some.file

ChDir

71

If the current working directory were AAA/BBB/CCC/DDD/EEE:S, this reference is to the file /AAA/SOME.FILE:S. Alternately, you could use the dot, dot specification and add additional dots to it, one for each additional parent. The above reference could be specified with: ...../some.file

Commands

A directory name may be specified with less than the complete name. For example: >tree /develop doc files screens programs doc >cd d

The ChDir command above specified a directory name that does not exist (there is no directory named “D” under DEVELOP, the current working directory). In this situation, ChDir will try to find a directory name that starts with the specified name. In this example, it will find the subdirectory “DOC” and it will change to it. When searching for a directory name that starts with the specified name, ChDir does not search the tree alphabetically (although the Tree command

displays the subdirectories sorted alphabetically). Instead it performs a sequential search and uses the first one that it finds. If there is more than one directory name that matches, it might not use the one that you thought it would. For instance, if there are two directories named TEST1 and TEST2, changing to the T directory might change to TEST2. Mode 2—When no directory name is specified in this command, the ChDir program will check to see if the Home environment variable has a value (see “Home” on page 100 of the THEOS Corona Version 5 Operating System Reference). When Home has a value, the current working directory is set to that home directory. If Home is undefined or has no value, the current working directory is set to the root.

72 ChDir

>show home HOME=/DEVELOP:S >pwd /DEVELOP/PROGRAMS/DOC:S >cd

Notes

The command name CD is a synonym to the ChDir command. It is not a separate program but only an entry in the /THEOS/OS/MESSAGES/language/ SYNONYM.TXT file and, if standard synonyms are disabled (see “Account” on page 13 of this manual and “STDSYN” on page 110 of the THEOS Corona Version 5 Operating System Reference), this synonym name may not be allowed. When you change the current working directory using either Mode 1 or Mode 2 of this command a search is made for a file named _ChDir.msg in that new directory. If this file is found then it is displayed on the console. This file may contain the special characters and macros that may be used in logon message files. Additional information about directory names, paths and the current working directory may be found in THEOS Corona Version 5 Operating System Reference, Chapter 9 “Directories and Files,” starting on page 131 and Appendix D: “System Files,” starting on page 209.

Restrictions

The directory specified must be owned by the current account.

See also

FileManager, MkDir, PWD, RmDir, Set, Tree

ChDir

73

Commands

>pwd /DEVELOP:S

Commands

74 ChDir

ClassGen Command The ClassGen command creates or changes a console or printer class code specification file.

CLASSGEN

number ( option »

console or printer class code number (1–255)

option

»

PRTnn

Operation

Commands

number

The SYSTEM.THEOS32 library is searched for an existing class code definition file for class code number. If one is found, it is examined to determine if it is a console class code or a printer class code definition. To determine the proper number to use for a new class code, refer to Appendix D: “System Files” in the THEOS Corona Version 5 Operating System Reference. If no existing class code definition can be found for number, you are prompted with: Is this a CONSOLE class file?

Any response other than (Y) is interpreted as a “no” response and the class code definition will be for a printer. If the PRT option is specified, the class code definition is output to the printer. (A new class code number will print a report with all fields blank.) When the PRT option is not used, the appropriate set of maintenance screens are used to allow you to define or change the definitions of the class code. Options

PRTnn

Indicates that ClassGen is to print the current class code definition on the attached printer number nn. nn may be a value between 1 and 64. The option keyword PRT may be specified as PRT, PRINT or PRINTER. As a convenience, PRINTER1 may be specified as P.

ClassGen

75

Console Class Codes

ClassGen uses several screens to define a class code for consoles. These screens group the definition fields into several categories:

1. Terminal name and cursor control codes. 2. Video display attributes and cursor shape. 3. Screen editing commands. Commands

4. Keyboard input function codes. (Two screens.) 5. Line-drawing graphics. (Two screens.) 6. International symbols. (Three screens.) 7. Keyboard international symbols. (Three screens.) Refer to the “Notes” section for information about navigating between these screens, moving from field-to-field and entering special character codes. „ Console Class Code Maintenance Screens The following shows the fields in each of the maintenance screens used for console class codes. The first screen shows the fields for setup and cursor movement. THEOS® Classgen - version 5.0 CONSOLE Output attributes for class: 90 PcTerm U.S.A.

Terminal name........... 90 PcTerm U.S.A. Setup................... ESC . '1'

Direct Cursor Address... Home.................... Up...................... Down.................... Left.................... Right...................

ESC - 0x82 0x83 RS VT SYN BS FF

Figure 1: ClassGen, Consoles, Screen 1

The “Setup” field is output to the console when it is first attached.

76 ClassGen

The “Direct Cursor Address” field is coded to tell THEOS how to position the cursor on consoles using this class code. Specify the string of character that, when output to the console, positions the cursor to a specific location. Where the line or column number would be specified, use one of the following codes: Column Number

128 (0x80) Absolute

129 (0x81) Absolute

130 (0x82) Standard

131 (0x83) Standard

132 (0x84) ASCII

133 (0x85) ASCII

Commands

Row Number

The meanings of these three types of coding are: Absolute

The value substituted is the row or column number. That is, positioning to row five is accomplished by outputting a character whose value is five.

Standard

The value substituted is the row or column number plus 32. To position to row five, a character is output whose value is 37.

ASCII

The ASCII digit characters are output for the row and column. To position to row 12, the characters ‘1’ and ‘2’ are output.

Cursor addressing, as used by THEOS class codes, is always number base 0 with the origin in the upper left corner.

ClassGen

77

The second screen shows display attribute fields.

THEOS® Classgen - version 5.0 CONSOLE Output attributes for class: 90 PcTerm U.S.A.

Commands

Reverse video on........ Reverse video off....... Underline on............ Underline off........... Blink on................ Blink off............... Half intensity on....... Half intensity off...... Format mode on.......... Format mode off......... Cursor off.............. Cursor on...............

0xBD ESC G 0xBD ESC G 0xBD ESC G 0xBD ESC G 0xBD ESC G 0xBD ESC G 0xBD ESC G 0xBD ESC G ESC & ESC 0x27 ESC . '0' ESC . '1'

0x81 0x80 0x81 0x80 0x81 0x80 0x81 0x80

@ 0x84 '4' '0' 0x81 @ @ 0x84 '4' '0' 0x81 @ @ 0x84 '4' '0' 0x81 @ @ 0x84 '4' '0' 0x81 @

0x88 0x84 0x88 0x84 0x88 0x84 0x88 0x84

'2' '4' '2' '4' '2' '4' '2' '4'

0x90 0x88 0x90 0x88 0x90 0x88 0x90 0x88

'8' '2' '8' '2' '8' '2' '8' '2'

0x90 '8' 0x90 '8' 0x90 '8' 0x90 '8'

Figure 2: ClassGen, Consoles, Screen 2

Most terminals use one of two methods for enabling various video display attributes: bit-mapped and ANSI X3.64. If a particular attribute uses one of these methods, the first character of the definition for the field must be a special code that the class code can recognize as a type code. It is a single character whose value reflects the binary code resulting from the following definition: Bit

78 ClassGen

Meaning

7

Must be “on.”

6

Requires backspace for multiple attributes.

5

“On” means attributes are bit-mapped. “Off” means attributes use ANSI X3.64 coding.

4

Coding applies to UNDERLINE attribute.

3

Coding applies to BLINK attribute.

2

Coding applies to REVERSE VIDEO attribute.

1

Coding applies to FORMAT attribute.

0

Coding applies to HALF INTENSITY attribute.

For instance, a terminal using bit-maps that supports all of the attributes and doesn’t require a backspace for multiple attribute encoding would use a code of 191 (0xBF). • Bit-mapped Attribute Coding

Bit

Meaning

7

Must be “on.”

6

Not used.

5

Not used.

4

Character following applies to UNDERLINE attribute.

3

Character following applies to BLINK attribute.

2

Character following applies to REVERSE VIDEO attribute.

1 0

Character following applies to FORMAT attribute. Character following applies to HALF INTENSITY attribute.

For example, a terminal using bit-mapped coding for reverse video, blink and underline attributes might be coded as: 252 ESC G 132 '4' 136 '2' 144 '8'

where: 252

Specifies that this attribute requires special processing, uses a display position, is bit-mapped, and applies to underline, blink and reverse video.

ESC G

This is the lead-in used by the terminal for attribute coding.

132 '4'

Outputs the character “4” when reverse video is being selected.

136 '2'

Outputs the character “2” when blink is being selected.

144 '8'

Outputs the character “8” when underline is being selected.

Each attribute “on” field must be defined such that all of the attribute enable codes are specified, and that each attribute “off” field be defined such that all attributes are turned off, followed by the codes that re-enable the attributes that might be still on. The example shown in Figure 2: ClassGen

79

Commands

A terminal using bit-mapped coding should have the lead-in character described above (with bit position 5 on) followed by the character string that must be output to the terminal to enable the attribute. In this character string, where the specific attribute is specified, precede the attribute code with a special code derived from the following table:

“ClassGen, Consoles, Screen 2” on page 78 shows an example of this technique. • ANSI X3.64 Attribute Coding

Commands

A terminal using ANSI X3.64 attribute coding requires a string looking like: ESC [ '7' m

This specific string would enable the reverse video attribute. To turn off this attribute a string looking like the following is used: ESC [ '2' '7' m

Because ANSI encoding is common, THEOS class codes have built-in capability to output the proper character strings for the various video attributes supported by THEOS. A terminal using ANSI X3.64 coding has the lead-in character described above followed by a 255 (0xFF). Make sure that bit position 5 is off in the lead-in character. For instance: 0xBD 0xFF

This tells the class code that the terminal uses ANSI coding for underlining, blink, reverse video and half- intensity.

80 ClassGen

The third screen shows the fields used for screen editing commands.

THEOS® Classgen - version 5.0 CONSOLE Output attributes for class: 90 PcTerm U.S.A.

ESC ESC ESC ESC ESC ESC ESC ESC ESC ESC ESC CR ESC ESC ESC

Commands

Insert character........ Delete character........ Insert line............. Delete line............. Clear screen............ Erase unprotected....... Erase to end of line.... Erase to end of screen.. Monitor mode on......... Monitor mode off........ Send to status on....... Send to status off...... Enable Slave Printer.... Disable Slave Printer... Set alpha color.........

Q W E R * & ESC ; ESC 0x27 T Y U u g ESC f ` a ETX 0x88 0x90 0xA0 0xC0

Figure 3: ClassGen, Consoles, Screen 3

These fields are fairly obvious in their nature and the manual for your terminal should specify exactly what characters to use for each of these fields. There are three fields at the bottom of this screen that are not so obvious. The “Enable Slave Printer” and “Disable Slave Printer” fields, refer to the commands that will tell the terminal to activate its auxiliary or secondary port that should be connected to a local printer. If the terminal supports this concept, find the commands in the terminal manual that instruct the terminal to pass subsequent data to the auxiliary port and to not display them on the terminal screen. This will probably be identified as “transparent” mode. The last field, “Set alpha color,” is used on color display terminals. If the terminal does not support colors, leave this field blank. The definition in this field tells the class code how to change colors on the terminal. Specify the command string required by the terminal for changing colors. In this command string substitute the following codes in the appropriate character positions:

ClassGen

81

Commands

Code

Meaning

136 or 0x88

Foreground color

144 or 0x90

Background color

160 or 0xA0

Reverse Video foreground color

192 or 0xC0

Reverse Video background color

When a color change is requested, THEOS changes these codes to the corresponding color code. The color codes used by THEOS are: Code

Color

Code

Color

0

Black

4

Red

1

Blue

5

Magenta

2

Green

6

Yellow

3

Cyan

7

White

If your terminal does not use these same numbers or characters for its colors there is a mechanism for setting the “color palette.” If the first character of the “Set Alpha Color” field is a 255 (0xFF), then the next eight characters are interpreted as the color palette definition. This color palette must be specified in the same sequence that THEOS uses colors. For instance, if your terminal uses letters for its color codes: ‘R’ for red, ‘Y’ for yellow, ‘G’ for green, ‘W’ for white, ‘C’ for cyan, ‘B’ for blue, ‘M’ for magenta and ‘N’ for black, the color palette is defined with: 255 N B G C R M Y W

The following definition is taken from class code 180. This class code is used on color PC Terminals. It has a color palette that matches the one used by THEOS but uses ASCII digits instead of the default numeric values for the colors codes. 0xFF '0' '1' '2' '3' '4' '5' '6' '7' ESC / 0x88 0x90 0xA0 0xC0

82 ClassGen

Screens four and five show the fields defining the keyboard input key translation values.

THEOS® Classgen - version 5.0

Up...................... Down.................... Left.................... Right................... Escape.................. Top..................... Bottom.................. Delete character........ Delete left character... Page forward............ Page backward........... Word right.............. Word left............... Search forward.......... Search backward.........

0xFF 0xFF 0xFF 0xFF ESC 0xFF 0xFF 0xFF DEL 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF

Commands

CONSOLE Input function keys for class: 90 PcTerm U.S.A.

H P K M G O S Q I 0xD2 0xD3 0xC1 0xD1

Figure 4: ClassGen, Consoles, Screen 4

For each of the fields, specify the characters or codes transmitted by the terminal when the key is pressed that corresponds to the function. For instance, if the terminal manual indicates that the (Home) key sends ESC, [, H then define the “Home” field as ESC [ 'H'. If the terminal’s keyboard transmits scan codes, define the field starting with the value 255 followed by the scan code value of the key or key combination. (See above figure.)

ClassGen

83

Screens six and seven show the line graphics character definitions for the terminal.

THEOS® Classgen - version 5.0

Commands

CONSOLE Line Drawing Graphics for class: 90 PcTerm U.S.A.

Upper left corner....... Upper right corner...... Lower right corner...... Lower left corner....... Four way intersection... Left intersection....... Right intersection...... Up intersection......... Down intersection....... Horizontal.............. Vertical................ Round upper left........ Round upper right....... Round lower right....... Round lower left........

0xDA 0xBF 0xD9 0xC0 0xC5 0xC3 0xB4 0xC2 0xC1 0xC4 0xB3 0xDA 0xBF 0xD9 0xC0

Figure 5: ClassGen, Consoles, Screen 6

You should define a code for each of these fields even if the terminal does not support a specific line-drawing character or even if it doesn’t support any line-drawing characters. Many programs assume that the console can display line-drawing characters and do not make any allowances for consoles that do not. For fields not supported by the terminal, use either some other line-drawing character that appears similar to the one desired or use a regular text character. In the above example notice that the rounded corner characters (at the bottom of the display) are the same codes as the square corner characters (at the top of the display). Most terminals do not support rounded corners so the square corners should be substituted. If the terminal does not have line-drawing graphics, leave the various fields blank. THEOS will use regular text characters for any fields that are undefined. For instance, a ‘+’ character for all corners and the four-way intersection, a ‘|’ for vertical and left and right intersections, and a ‘-’ for horizontal and up and down intersections.

84 ClassGen

Screens eight, nine and ten show the fields defining the codes used to display international characters.

THEOS® Classgen - version 5.0

Uppercase Lowercase Lowercase Lowercase Lowercase Uppercase Lowercase Lowercase Lowercase Lowercase Lowercase Lowercase Lowercase Lowercase Uppercase Lowercase Lowercase Lowercase Lowercase

A a a a a E e e e e i i i i O o o o o

dieresis.... dieresis.... circumflex.. grave accent acute accent acute accent dieresis.... circumflex.. grave accent acute accent dieresis.... circumflex.. grave accent acute accent dieresis.... dieresis.... circumflex.. grave accent acute accent

Commands

CONSOLE Output International Symbols for class: 90 PcTerm U.S.A.

0x8E 0x84 0x83 0x85 0xA0 0x90 0x89 0x88 0x8A 0x82 0x8B 0x8C 0x8D 0xA1 0x99 0x94 0x93 0x95 0xA2

Figure 6: ClassGen, Consoles, Screen 8

Symbol character terminology: Dieresis

Another word for umlaut ( ¨ ) which is two dots on top of the character. Example: Ä, Ö, Ü, ä, ë, ï, ö, ü, ÿ.

Circumflex A diacritical mark that looks like an upside-down v ( ˆ ) over

the character. Example: â, ê, î, ô, û. Grave accent A diacritical mark that looks like a backward quote ( ` ) over

the character. Example: à, è, ì, ò, ù. Acute accent A diacritical mark that looks like an apostrophe ( ´ ) over the

character. Example: á, É, é, í, ó, ú. Cedilla

A diacritical mark that looks like a tail ( ¸ ) under the character. Example: ç, Ç.

Tilde

A diacritical mark that looks like a “squiggle” ( ~ ) over the character. Example: Ñ, ñ.

ClassGen

85

Commands

Diphthong

A ligature or letter combination. Example: Æ, æ.

Bolle

A diacritical mark that looks like a small circle ( ° ) over the character. Example: Å, å.

Eszet

The German “ss” letter combination. Example: ß.

The last three screens show the definitions of the codes received from the terminal when the keyboard generates the same international characters and symbols. Printer Class Codes

ClassGen also uses several screens to define class codes for printers. These screens group the definition fields into several categories:

1. Printer name, initialization and display attributes. 2. Line-drawing graphics. (Two screens) 3. International symbols. (Four screens) A printer class code uses fewer screens than a console class code mainly because there is no keyboard to define. Refer to the “Notes” section for information about navigating between these screens, moving from field-to-field and inputting special character codes.

86 ClassGen

„ Printer Class Code Maintenance Screens The following shows the fields used in each of the maintenance screens used for printer class codes.

Commands

THEOS® Classgen - version 5.0 PRINTER Attributes for class: 135 HP LaserJet II & III Printer name............ HP LaserJet II & III Setup................... ESC E ESC ( '1' '0' U

Boldface on............. Boldface off............ Underline on............ Underline off........... Italics on.............. Italics off............. Secondary color on...... Secondary color off..... Compress on............. Compress off............ Double wide on.......... Double wide off......... Double high on.......... Double high off.........

ESC ESC ESC ESC ESC ESC

( ( & & ( (

s s d d s s

'1' '0' '0' @ '1' '0'

B B D S S

ESC ( s '1' '6' . '6' '6' H ESC ( s '1' '0' H

Figure 7: ClassGen, Printers, Screen 1

Of interest in this first screen is the “Setup” field. The content of this field is sent to the printer when it is first attached. For spooled printers, this string is also sent at the beginning of each report printed by the printer spooler. The remaining fields on this screen and the other screens that follow are similar to those described in Figure 2 on page 78 and Figure 5 on page 84 . Notes

To move around a screen use the (˚) or (˙) keys, or merely enter (EnterÌ˛) to advance to the next field. The (PageDown) and (PageUp) keys move from screen to screen while the (Home) and (End) keys move to the first or last screens. To save any changes made and then exit, use the (F10) key. The (F9) or (Esc) keys exit without saving your changes.

ClassGen

87

• Entering Characters Each character in a field is separated by a space from the next character in the field.

Commands

All displayable characters except for digit characters are entered as plain text. Digit characters are enclosed in a pair of single quotation marks. • Entering Control Characters Most fields in a class code definition will require that you indicate that a control character is part of the definition. Since entry of a control character will be treated by THEOS as a command rather than data, you will have to specify the control character value in another way. Control characters are specified with either the numerical value or by their ASCII character name. The numerical value may be specified in decimal or hexadecimal. Char

88 ClassGen

ASCII

Dec

Hex

^@

NUL

0

0x0

^A

SOH

1

0x1

^B

STX

2

0x2

^C

ETX

3

^D

EOT

4

^E

ENQ

^F

ACK

^G

BEL

Char

ASCII

Dec

Hex

^P

DLE

16

0x10

^Q

DC1

17

0x11

^R

DC2

18

0x12

0x3

^S

DC3

19

0x13

0x4

^T

DC4

20

0x14

5

0x5

^U

NAK

21

0x15

6

0x6

^V

SYN

22

0x16

7

0x7

^W

ETB

23

0x17

^H

BS

8

0x8

^X

CAN

24

0x18

^I

HT

9

0x9

^Y

EM

25

0x19

^J

LF

10

0xA

^Z

SUB

26

0x1A

^K

VT

11

0xB

^[

ESC

27

0x1B

^L

FF

12

0xC

^\

FS

28

0x1C

^M

CR

13

0xD

^]

GS

29

0x1D

^N

SO

14

0xE

^^

RS

30

0x1E

^O

SI

15

0xF

^_

US

31

0x1F

DEL

127

0X7F

Control characters are always displayed with the ASCII name. Example: ESC & 27 & ESC g ESC f 0xFC ESC G 132 '4' 136 '2' 144 '8'

The ClassGen command requires a privilege level of five and may only be executed when you are logged onto the SYSTEM account (user number 0).

See also

Attach, CRT, Printer, Start, Sysgen

ClassGen

89

Commands

Restrictions

Commands

90 ClassGen

Cleanup Command The Cleanup command erases backup, work and other temporary files.

CLEANUP

2

CLEANUP ( options

options

Operation

»

ACCOUNTS ALL NOQUERY NOTYPE

Commands

1

QUERY SUBDIR TYPE

Mode 1—A menu is displayed allowing the operator to select the type of cleanup desired.

The specific options checked initially depend upon the currently saved configuration for this UserName (see “Environment Variables” on page 111). Cleanup is not started until the “Start” button is pressed.

Cleanup 91

Mode 2—Similar to Mode 1 except that the initial defaults may be set by the various options available. Cleanup is not started until the “Start” button is pressed. Options

ACCOUNTS All accounts and all directories of those accounts are cleaned

Commands

up. Requires a high privilege level and you must be logged on to the system account (account id = 0).

Defaults

92 Cleanup

ALL

Enable all cleanup masks.

NOQUERY

Do not ask for confirmation before erasing each file.

NOTYPE

Do not display the names of the files erased.

QUERY

For each file that matches the cleanup specification, ask the operator if it is okay to erase it.

SUBDIR

Files in subdirectories of the current working directory are included in the cleanup operation.

TYPE

Display the name of each file deleted.

This command uses the /THEOS/USERS directory to save and get its configuration. The default actions will depend upon the saved settings for the current user as defined in the account environment variable UserName .

Cautions

Because Cleanup erases groups of files and because it uses defaults from a possibly shared user-defined configuration, you can easily erase files that you did not intend. Always review the menu settings before starting the cleanup operation. Also, enable the logging option so that there will be a log of the files that were erased. The ACCOUNTS option requires a high privilege level and that you be logged onto the system account.

See also

FileManager

Cleanup 93

Commands

Restrictions

Commands

94 Cleanup

Clear Command The Clear command clears the console and positions the cursor to the upper left corner.

CLEAR The console screen is cleared.

Notes

The console status line is also cleared.

Commands

Operation

The console screen may also be cleared by pressing (¤) at the CSI prompt. The action of this key differs from the Clear command in two ways: The CSI prompt is displayed on line 1 and the status line is not cleared.

Clear

95

Commands

96 Clear

Clock Command The Clock command displays a clock on the screen.

CLOCK

2

CLOCK Analog

3

CLOCK Digital

Operation

Commands

1

Mode 1—Displays a clock using the last mode requested (analog or digital). Mode 2—When executed, the Clock command displays a window with an analog clock that is updated once per second.

Mode 3—Display a digital clock on the screen using the default clock font or the font defined in this user’s CLOCK.CFG file.

Notes

To terminate this clock display click on the [X] in the upper right corner of the window or press (Break),(Q). The position and size of the clock displayed can be changed by the user with the mouse. The initial position and size is determined by the last Clock 97

position and size used by this user and it is saved in the /THEOS/USERS/username/CLOCK.CFG:S file.

Commands

See also

98 Clock

Date, Show CLOCK, Show TIME

Color Command The Color command sets the default colors used on the console.

COLOR

2

COLOR fg bg rvfg rvbg

fg

»

foreground color number or name

bg

»

background color number or name

rvfg

»

reverse video foreground color number or name

rvbg

»

reverse video background color number or name

Operation

Commands

1

Mode 1—Display the current colors in effect for this console. >color Normal: WHITE on BLUE Reverse: WHITE on RED

This mode also reprograms the console to use these colors and performs an “Erase to end-of-screen” operation. This operation can be useful if the displayed colors on your console are changed without THEOS’ knowledge (for instance, by ScanTerm). Mode 2—The default colors for this console are changed. The text color is set to fg, the text background color is set to bg, reverse video text color is set to rvfg and reverse video text background color is set to rvbg. Before exiting, a “clear to end-of-screen” is performed. >color 7 3 7 1 >color Normal: WHITE on CYAN Reverse: WHITE on BLUE >color white red >color Normal: WHITE on RED Reverse: RED on WHITE

Color

99

If fewer than four colors are specified the colors are set accordingly: The reverse video background is set to BLACK.

Omit rvbg:

>color white blue cyan

Omit rvfg, rvbg: The reverse video colors are set to the reverse of the normal video colors specified. Commands

>color green black >color Normal: GREEN on BLACK Reverse: BLACK on GREEN

Omit all but fg: The background color is set to BLACK (unless fg is BLACK, in which case the background color is set to WHITE). The reverse video colors are set to the reverse of the normal video colors. >color 1 >color Normal: BLUE on BLACK Reverse: BLACK on BLUE

Colors

The colors for fg, bg, rvfg and rvbg may be specified with the color number, the color name or the single letter abbreviation of the color name. When a color name is used, it must be completely spelled out. Code 0

Name Black

Abbrev

Code

N

4

Name Red

1

Blue

B

5

Magenta

M

2

Green

G

6

Yellow

Y

3

Cyan

C

7

White

W

Abbrev

R

Table 2: Color Codes & Names

Notes

The colors changed by this command only affect the display of text output after this command. Text already on the screen is not changed. Although a program might change the color representation of the text or graphics that the program displays, the system will restore the colors to those assigned by the last usage of this command after each program exits.

Defaults

When a console is first started, the default colors used are defined by the /THEOS/CONFIG/COLOR.CFG:S file. This file is maintained by the Setup COLOR command.

Restrictions

The console must be color-capable and its class code must have a properly defined “Set alpha color” field.

See also

ClassGen, Setup Color, Sysgen

100 Color

Compare Command This command compares two files and reports any differences.

COMPARE

file1 file2 ( options

2

COMPARE

file ( FILE options

3

COMPARE

file drive ( FILE options

Commands

1

drive

»

drive code

file

»

file name with optional path

file1

»

file name with optional path; may contain wild cards

file2

»

file name with optional path; may contain wild cards

options

»

BINARY NOCASE NOSPACE

Operation

NOTYPE PRTnn TYPE

Mode 1—Compares file1 with file2 and reports on the differences between the two files. The minimum report is a message: “Files are equivalent.” or “Files are not equivalent.” Specific information about the differences is displayed if the PRTnn or TYPE option is used. Mode 2—The ASCII stream file specified by file is used as a source for a list of file name pairs to be compared. Each line in file specifies the two file names that are compared. Using this mode of the command is identical to using the Mode 1 form for each pair of files specified in file. >list compare.files program.source.program1:s programs.original.program1:s program.source.program4:s programs.original.program4:s program.source.programx:s programs.original.programx:s >compare compare.files (file PROGRAM.SOURCE.PROGRAM1:S PROGRAMS.ORIGINAL.PROGRAM1:S Files are not equivalent. PROGRAM.SOURCE.PROGRAM4:S PROGRAMS.ORIGINAL.PROGRAM4:S Files are equivalent. PROGRAM.SOURCE.PROGRAMX:S PROGRAMS.ORIGINAL.PROGRAMX:S Files are not equivalent.

Compare

101

Mode 3—Similar to Mode 2 except only the first file name in each line of file is used. The second file name is created by using the first file name and replacing the drive-code for that file with the drive specified on the command line. >filelist sample.*:s (exec

Commands

>compare selected.exec a (file File: /SAMPLE.FILE1:S, A Files are equivalent. File: /SAMPLE.FILE2:S, A Files are not equivalent. File: /SAMPLE.FILE3:S, A Files are equivalent.

Options

BINARY

Compares the two files byte-by-byte rather than line-by-line. This is a default option when either of the files is not a stream file.

NOCASE

The case mode of the characters in the two files is not significant in the comparison.

NOSPACE

Extra white space in the two files is not significant in the comparison.

NOTTYPE

A default option that suppresses the display of the differences between the two files. Only a result message is displayed: “Files are equivalent.” or “Files are not equivalent.” Use PRTnn or TYPE to override this option.

PRTnn

Displays the differences between the two files on the printer. nn specifies which attached printer to use and is in the range of 1–64. If nn is omitted, PRT1 is assumed. The format of the display depends upon the BINARY option. See “Binary File Display” on page 104 and “ASCII File Display:” on page 103. The alternate keywords PRINT and PRINTER may be used instead of PRT. As a convenience, PRINTER1 may be specified as P.

TYPE

102 Compare

Displays the differences between the two files on the standard output device (normally the console). The format of the display depends upon the BINARY option.

ASCII File Display:

When two stream files contain ASCII data and the BINARY option is not specified, the files are compared on a line-by-line basis. When option PRTnn or TYPE is used, the specific differences between the two files are shown with a plus ( + ) or minus ( - ) symbol to indicate the line that must be added or deleted from file2 to make it equivalent to file1.

>compare julian.basic julian.backup (type 1+000001 ! Program: JULIAN Compute Julian date 2+000002 3+000003 ! Programmer: John Doe 4+000004 5+000005 OPTION VERSION 1.0,"(C) 1995 by ABC Inc." 6+000006 17-000110 PRINT "Today's julian date is: "; 17+000110 PRINT "Today's Julian date is: "; Files are not equivalent.

This display indicates that the files are not the same and that the second file (JULIAN.BACKUP) must have the following changes made to it to make it the same as the first file (JULIAN.BASIC): 1. Six lines must be added at the beginning of the file. 2. The 17th line (after the six lines are added) must be deleted. 3. A new 17th line must be added. When a difference is found, the Compare command uses a buffer to scan ahead in the file to see if the difference is an addition to the file (a matching line is found later in the file1), a deletion was made (a matching line is found later in file2) or if a change was made. This buffer holds approximately 40 lines of text.

Compare

103

Commands

For instance, a MultiUser BASIC language program has been edited with new comments added at the beginning of the program (line numbers 1–6). Additionally, the capitalization of one word was changed at line 110.

Binary File Display

When two non-stream files are compared or when the BINARY option is specified, the files are compared on a byte-by-byte basis. When option PRTnn or TYPE is used, the specific differences between the two files are shown.

Commands

For instance, a program’s version number is changed, a string literal is changed and the program is recompiled. A comparison of the new program command with the prior version of the command (renamed to have a file type of OLDCMD before the recompilation) might show: >compare 00000105 00000107 00000109 00000115 00005A1D 00005A5D 00005A5E 00005A5F etc.

julian.command julian.oldcmd (type 52 53 20 21 8D 8C 31 30 4A 6A 6E 61 6E 61 6D 6E

Each line of the display shows a location in the files, the value of that location in file1, followed by the value of that location in file2. Defaults

NOTTYPE is a default option. BINARY is a default option when either of the

files is not a stream file. Return Codes

Unless an error is detected, when the two files are equivalent the return code is zero ( 0 ); otherwise the return code is one ( 1 ).

Cautions

Comparing two stream files that contain coded or binary information without using the BINARY option might produce erroneous results. When in doubt, always use the BINARY option.

104 Compare

Compress Command The Compress command compresses a file and saves the compressed form in a “compression library file.”

COMPRESS

compress-file file... ( options

2

COMPRESS

compress-file file ( FILES options

3

COMPRESS

compress-file - file

4

COMPRESS

compress-file

Commands

1

compress-file

»

file name of resulting compression file, with optional path

file

»

file name of source file, with optional path; may contain wild cards

options

»

DELETE FILES MODIFIED NOTYPE PASSWORD

Operation

PRESERVE SELFEXPAND SUBDIR TYPE

Mode 1—Each file specified on the command line is compressed and added to the compression library file compress-file. If compress-file does not exist, it is created. When compress-file exists and file already exists in that compress-file, it is removed before being added to the end of the compress-file. >compress old.programs original.source.* 47% original.source.addrsort 48% original.source.dflt 46% original.source.entity 46% original.source.eod1 38% original.source.eom1 47% original.source.eom2 47% original.source.eom3 47% original.source.eom4 40% original.source.eom5 ...

Unless the PRESERVED option is used, each file that is compressed has its modified attribute reset. (The modified attribute is set on the compress-file so it may be included on the next incremental or differential archive.)

Compress

105

Mode 2—The files listed in file are compressed and copied into compressfile. file must be an ASCII stream file containing one file description per line. The SELECTED.FILES and SELECTED.EXEC files created by FileList and the FOUND.EXEC created by Look can be used for this specification file (see “The EXEC and FILES Options” on page 239). You may also create the specification file with an editor or application program. Commands

For instance, FileList is used to create a list of files to be compressed: >filelist a not *.basic:a not *.command:a (10/1/01 exec

A file now exists that lists all of the files that have been changed since 10/01/2001. The following command will compress these files: >compress old.files selected.exec (file preserve 91% dat.acc 14% dat.def 82% dat.inccod 85% dat.ass 92% dat.def 74% frn.anldat ...

Mode 3—Similar to Mode 1 except that each file preceded by a minus sign is deleted from the compress-file instead of being added to it. >compress old.files -retail.tickets retail.tickets removed.

Mode 4—No files are compressed with this mode. Instead, the list of files already contained in compress-file are displayed on the standard output device. >compress old.files File name dat.acc dat.def dat.inccod dat.ass dat.def frn.anldat ...

Date 12May88 31Dec89 31Jul00 13Apr98 15Sep96 28Mar01

Time 11:41 16:00 19:31 19:07 18:49 08:39

Size Rate 1,024 91% 1,024 14% 1,804 82% 1,668 85% 1,024 92% 23,650 74%

The “Date,” “Time” and “Size” columns refer to the time-stamp and size of the original, uncompressed form of the file. “Rate” refers to the compression ratio of the file.

106 Compress

Options

Tells Compress to delete file after adding it to compress-file. (If file is preceded by a minus sign, as in Mode 3, it is removed from the compress-file but it is not deleted.)

FILES

Invokes Mode 2 of the Compress command.

MODIFIED

Specifies that only files that have their modified attribute set are to be compressed.

NOTYPE

Tells Compress to not display the results of each file compressed and also to suppress the progress bar. Only error messages are displayed on the stderr device. The general result message (the “nn files compressed.” message prior to exiting Compress) is also suppressed with this option. >compress old.files myprog.basic (notype >

PASSWORD

A password is specified following the PASSWORD option keyword. All of the files added to the compress-file are encoded with this password and they cannot be expanded without specifying the same password. >compress private.files *.text (notype password aardvark

PRESERVED Tells Compress to not clear the modified attribute from a file

that is compressed. Without this option, every file that is compressed has its modified attribute cleared. SELFEXPAND The resulting compress-file is a self-expanding executable

program file. The file-type of compress-file should be CMD, COMMAND or EXC. SUBDIR

Tells Compress that the full path of the file is to be used when saving the image of file. When this option is not used, only the file name is saved, not its path information. By using this option, the Expand command has sufficient information to extract and restore the file to its original location.

Compress

107

Commands

DELETE

Commands

TYPE

In combination with the NOTYPE option, this is a tri-state option that tells Compress whether to display the results of each file compression or not. When TYPE and NOTYPE are not specified, Compress displays a progress bar and any error messages but does not display the names of the files being compressed. Specifying TYPE displays the names of the files being compressed. NOTYPE displays only error messages. This display can be redirected. >compress old.files selected.exec (file 91% dat.acc 14% dat.def 82% dat.inccod ...

Notes

compress-file is referred to as a compression library file because it is a single file containing the compressed versions of one or more files. It is not a library in the normal usage of the term library. When compress-file is specified as a typeless file specification (no period and no file-type specified), the default file-type of CMP is used for the compress-file. When Mode 1 or Mode 2 is used to add files to an existing compress-file, any previous versions of the files with the same name are removed and then the current version is added to the end of the compress-file. Typically, ASCII text files are compressed to 40% to 60% of their original size; binary files (programs and formatted data files) are compressed to 50% to 70% of their original size.

Defaults

TYPE is a default option.

See also

Backup, CopyFile, Expand, FileManager, FileType, TArchive, TBackup

108 Compress

Config EXEC This command is used to save the various system configuration files in a format that is suitable for sending to THEOS customer support.

CONFIG

2

CONFIG options

options

Operation

»

Commands

1

NAME filename NOBRIEF

Mode 1—Invokes the program. Mode 2—Invokes the Config exec one or both of the options.

Options

NAME filename Defines the output name. This name is used for both the

text file that is generated and for the compressed version of the text file. The compressed version has a file-type of CMP. When this mode is not used, the text file that is created is named with the serial number of the system and a file-type of CFG. The output files are always written to the S drive. NOBRIEF

Notes

Initializes the menu so that the less-important files are included in the result.

When Config is invoked it offers the user a menu:

Select one of the menu items and press (EnterÌ˛). All System-related config. Causes the file generated to include the information from the various configuration files relating to the system. All Network-related config. Causes the file generated to include the information from the various network configuration files.

Config

109

All System and Network configs. Causes the file generated to include the information from all of the system and network related configuration files.

Commands

Customize. This displays a menu of the configuration files and allow you to specify which ones to include when generating the text file. Some of the most common items will be enabled by default.

At the end of the list of configurations available there is an additional selection that allows you to change the file name used to save the information. Defaults

The standard set of configuration information saved by this command includes: Current attachments (Attach) Current software versions (Show Version)

110 Config

System configuration file (Setup Sysgen) Show command information for various devices SIO device configuration file (Setup SIO) CRT configuration file (Setup CRT) Startup configuration file (part of Setup Sysgen) Commands

General network configuration (Setup Net Ident) THEOMail configuration file (THEOMail) FTP client configuration file (Setup Net FTP Client) FTP server configuration file (Setup Net FTP Server) HTTP server configuration file (Setup Net HTTP Server) Gutenberg client configuration file (Setup Net Gutenberg Client) Web Maintenance server configuration file (Setup Net WebMaint) Post Office server configuration file (Setup Net PostOffice) DHCP server configuration file (Setup Net DHCP) DNS server configuration file (Setup Net DNS) TNFS server and client configuration file (Setup Net TNFS) TFTP server configuration file (Setup Net TFTP) When NOB is specified, the following additional information is saved by this command: Current started users (Show User) Memory usage (Show Memory) Device names (/THEOS/CONFIG/DEVNAMES.TXT) Console session and object colors (Setup Color) DigiBoard CX configuration (Setup CX) Modem configuration (/THEOS/CONFIG/MODEM.CFG) System disk parameters (Disk S Show) Restrictions

This command may be used only while logged onto the SYSTEM account.

Config 111

Commands

112 Config

CopyFile Command The CopyFile command copies a file from one location to another.

COPYFILE

from-file to-file ( options

2

COPYFILE

from-file to-device ( options

3

COPYFILE

from-drive to-drive ( options

4

COPYFILE

file ( FILES options

5

COPYFILE

file from-drive to-device ( FILES options

6

COPYFILE

( options

Commands

1

file

»

file name of specifications file, with optional path

from-file

»

file name of source file, with optional path; may contain wild cards

to-file

»

file name of destination file, with optional path; may contain wild cards

from-drive

»

disk drive letter for source files

to-device

»

to-drive COMnn CON PRTnn TAPn

to-drive

»

disk drive letter for destination files

options

»

APPEND BYREC EOFSENT EXPORT FILES FOR nnn FRKEY kkk FRLABEL lll FROM nnn IMPORT

LOWCASE MODIFIED NEWDATE NEWFILE NOQUERY NOSORT NOTYPE NOVERIFY OLDDATE OLDER

OLDFILE PRESERVE PUBLIC QUERY REPLACE SORT SPECS SUBDIR TOKEY kkk TOLABEL lll

TRANS TRUNCATE nnn TYPE UPCASE VERIFY

date1 date2

CopyFile

113

Operation

Mode 1—Copies from-file to the to-file. >copyfile one.file another.file >copyfile *.data =.datacopy

Commands

Refer to “Restrictions” on page 129 for a description of general restrictions on file ownership, public files and copying files from or to subdirectories. The from-file and to-file may contain wild-card specifications. See “Wild Card Specifications” on page 138. Mode 2—Copies from-file to to-device. When to-device is a disk-drive label, the destination file will have the same file name as the source file. >copyfile *.data:s f >copyfile *.data:s =.=:f

The above two commands produce identical results. This mode is also used when you want to copy a file to a communications port, console, printer or to a tape volume. >copyfile master.index =.=:tape (norewind >copyfile text.file com2

Only stream files may be copied to devices other than a disk. Mode 3—This is a shorthand method for specifying that you want all files copied from one drive to another. >copyfile s f >copyfile *.*.*:s =.=.=:f

The above two commands are equivalent. Remember, unless you use the PUBLIC option, only files owned by the current account may be copied. Unless the SUBDIR option is used, only files in a single directory are copied. This mode can also be used to copy stream data from one communications port to another, or from or to a tape drive. >copyfile :com4 :com8 >copyfile :com3 sample.file:tape2

114 CopyFile

Mode 4—file is an ASCII stream file containing two file descriptions per line. The first file description in the line is treated as a from-file and the second file description is the to-file. For each line in file, a Mode 1 or Mode 2 CopyFile is performed, as appropriate.

>edit daily.files customer.master:s /backup/customer.master:s customer.history:s /backup/customer.history:s customer.invoices:s /backup/customer.invoices:s general.legder.*:s /backup/=.=.=:s check.*:s /backup/=.= /programs/program.source.*:s a >copyfile daily.files (file replace noquery notype

By using some of the file selection options in addition to this file specifications file, the copy operation can be even more powerful. For instance: >copyfile daily.files (file replace noquery notype older

Here, the OLDER option restricts the copy operation so that only files that have been changed since the last copy are copied this time. Similarly: >copyfile daily.files (file replace noquery notype modified

This command copies only those files that have their modified status set. Mode 5—Similar to Mode 4, file is an ASCII stream file but it contains one file description per line. This file description is the source file specification. If it contains a drive code, that drive code is ignored and the from-drive specified on the command line is used instead. For each line in file, a Mode 2 CopyFile is performed. For instance: >edit daily.files customer.master customer.history customer.invoices general.ledger.* check.* /programs/program.source.* >copyfile daily.files a b (file replace noquery notype noq

is equivalent to: >copyfile customer.master:a b (replace notype noq

CopyFile

115

Commands

This mode of the CopyFile command is convenient when one or more sets of files are repetitively copied. Merely edit a file containing file description pairs, such as:

>copyfile customer.history:a b (replace notype noq >copyfile customer.invoices:a b (replace notype noq >copyfile general.ledger.*:a b (replace notype noq >copyfile check.*:a b (replace notype noq

Commands

>copyfile /programs/program.source.*:a b (replace notype noq

Mode 6—This is the interactive mode of the CopyFile command. Because no files are specified on the command line, you are prompted to enter the file names to copy: >copyfile (noquery Enter file name list, terminate with empty line. ?sample.file* j "SAMPLE.FILE1:S" copied to "SAMPLE.FILE1:J". "SAMPLE.FILE2:S" copied to "SAMPLE.FILE2:J". ?sample.file* /copies/samples/=.=:j "SAMPLE.FILE1:S" copied to "/COPIES/SAMPLES/SAMPLE.FILE1:J". "SAMPLE.FILE2:S" copied to "/COPIES/SAMPLES/SAMPLE.FILE2:J". ?

Options

APPEND

Applies only to stream files. This option tells CopyFile that, if the destination file already exists and it is a stream file, the source file is appended to the end of the existing destination file.

BYREC

Applies only to indexed, keyed and direct files. Indicates that, if the destination file already exists, the records in the source file are added to the destination file. If the destination file does not exist, a new, empty file is created and the records in the source file are copied to the new destination file one record at a time. Although this copy process is slower than a file copy, the destination is a “clean” version of the source file because no deleted records are copied and the tree structure of an indexed or keyed file is built from scratch.

EOFSENT

Indicates that the default end-of-file sentinel character is not the default EOT character (^D). You will be prompted to enter the end-of-file sentinel character before copying begins. A maximum of four characters may be entered as this sentinel. Use this option only when the from-file is not a disk or tape file. That is, when the source file is coming from the console or a communications port.

116 CopyFile

EXPORT

from-file is “exported” to to-file. This option is ignored when the from-file’s organization is not direct, indexed or keyed. The purpose of the EXPORT option is to convert a file so that it can be used in an environment that does not support THEOS formatted records, or direct, indexed or keyed organization files.

For instance, from-file is an indexed file with records created by the BASIC language statement: WRITE #1,KEY$:STRING$,PHRASE$,INTEGER%,FLOAT

Each input record looks like: Key: String,"Phrase needing quotes",1,2.345

The resulting record in to-file looks like: "Key",String,"Phrase needing quotes",1,2.345

and can be read with the BASIC language statement: INPUT #1:KEY$,STRING$,PHRASE$,INTEGER%,FLOAT

Each field is comma-separated from other fields. It is enclosed in quotes if the field is a string containing embedded spaces or quotes. The EXPORT option implies the BYREC option and can be used with other record selection options such as FOR, FRKEY, FROM and TOKEY. The SPECS and TRANS options are ignored when specified with EXPORT. FILES

Indicates that Mode 4 or Mode 5 of the CopyFile command is used. The file specifies an ASCII stream file with each record in the file specifying a file to be copied. The file name specifications in this file may include the path to the file. For a Mode 4 request, the records in file specify both the source file name and the destination file name. In a Mode 5 request, the records need only specify the source file name.

FOR

Indicates that only nnn records of the source file are copied to the destination file. The FRKEY, FRLABEL or FROM option

CopyFile

117

Commands

A file is exported by copying the records in the from-file to the stream file to-file, changing the formatted fields in the record to quoted string fields. The key field of each record in from-file is output as the first field in to-file.

must be used or the FOR option will be ignored (the entire file is copied). >copyfile last.letter customer.= (from 1 for 8

Commands

This command copies the first eight lines of one file to another file. FRKEY

Used with indexed and keyed files to specify the first record to copy. kkk represents the key of the first record to copy. Only records whose keys are greater than or equal to this key are copied. Can be used with the FOR and TOKEY options to limit the number of records copied after this first record is located. >copy customer.master new.master (frkey "THEOS"

This command copies all of the records in the CUSTOMER.MASTER file whose keys start with text that is greater than or equal to “THEOS.” FRLABEL

Used with ASCII stream files to specify the first record to copy. lll represents the starting text of the first record to copy. No records are copied until a record starting with this text is found. When found, that record is copied to the destination file along with the records that follow it in the source file. Can be used with the FOR and TOLABEL options to limit the number of records copied after this first record is located. >copy memo.model new.memo (frlabel "cc:" append

This command copies the last lines of MEMO.MODEL, beginning with the line starting with “cc:”. FROM

Used with ASCII stream files to specify the first record to copy. nnn represents the record number of the first record to copy. No records are copied until the nnnth record is found. When found, that record is copied to the destination file along with the records that follow it in the source file. Can be used with the FOR and TOLABEL options to limit the number of records copied after this first record is located.

IMPORT

118 CopyFile

This is the complementary option to the EXPORT option. When used, the from-file is imported into the to-file. from-file must be a stream file containing records with comma-separated fields.

This option is ignored if to-file is not a direct, indexed or keyed file.

You can control the conversion of the fields by using the SPECS option. LOWCASE Used with ASCII stream files to translate all uppercase char-

acters to their lowercase equivalents. All non-alphabetic characters are copied without any translation. Most of the multinational characters (Ä, É, Ñ, etc.) are translated with this option. See “Lowcase” on page 347 for more information. MODIFIED

Copies the source file only if its modified attribute is set. After the file is copied, the modified attribute of the source file is reset (unless the PRESERVE option is also used). This option provides a method of creating a set of incremental copies of files. For instance, if the following command is executed everyday: >copy *.data:s f (modified

Then each day a copy is made of all files that have been updated or changed since the last time the copy was performed or the modified attributes were cleared. See “Change” on page 65 . See also “TArchive” on page 601. NEWDATE

The destination file’s directory entry is updated with the current date and time. This is a default option when any other option is used that causes the destination file to differ from the source file, such as: APPEND, BYREC, EXPORT, FOR, FRKEY, FRLABEL, FROM, LOWCASE, SPECS, TOKEY, TOLABEL, TRANS, TRUNCATE and UPCASE. To disable this option use the OLDDATE option.

NEWFILE

Indicates that CopyFile should only attempt to copy files if the destination file name does not already exist. Note that, if

CopyFile

119

Commands

The from-file is imported by copying the records in the fromfile to the to-file. Each field in the imported record is converted to a formatted field before writing it to to-file. The format of the records in the from-file is assumed to be like the format of the records that are output with the EXPORT option.

QUERY is used, you are not queried about files if the destina-

tion file name already exists. This is a default option. To disable this option use the OLDFILE or the REPLACE options.

Commands

NOQUERY

Tells CopyFile to not ask for confirmation before copying each file. This is a default option when wild cards are not used. >copyfile gl.* f (noq "GL.MASTER:S" copied to "GL.MASTER:F". "GL.JOURNAL:S" copied to "GL.JOURNAL:F". "GL.HISTORY:S" copied to "GL.HISTORY:F".

To disable this option use the QUERY option. NOSORT

A default option that tells CopyFile to copy the files matching the source file specifications in the order that the file names are found on disk. To disable this option use the SORT option.

NOTYPE

Tells CopyFile to not display the results of each file copy on the standard output device. The general result message (the “nn files copied.” message prior to exiting CopyFile) is also suppressed with this option. >copyfile gl.* f (not Ok to copy "GL.MASTER:S" (Yes,No,All) Y Ok to copy "GL.JOURNAL:S" (Yes,No,All) Y Ok to copy "GL.HISTORY:S" (Yes,No,All) Y

To disable this option use the TYPE option. NOVERIFY A default option that tells CopyFile to not verify that the copy

was done successfully. Normally, the hardware verification that is always done is more than sufficient to assure that the copy is correct. To disable this option use the VERIFY option. OLDDATE

Each destination file’s directory entry is set to the source file’s last change date. This is a default option when the destination is an exact copy of the source file. To disable this option use the NEWDATE option.

OLDER

120 CopyFile

Copies the source file to the destination file only if the destination file’s last change date is older than the source file’s or if

the destination file does not exist. The REPLACE option is implied by this option. Note that, if QUERY is used, you are not queried about files if the destination file is newer. OLDFILE

Note that only the destination file name is checked. It could be a totally different file. For instance, an existing command program could be replaced by a stream file or indexed file. To disable this option use the NEWFILE option. PRESERVE Used with the MODIFIED option to specify that source file’s

modified attribute is not to be reset. This option provides a method of creating a set of differential copies of files. For instance, if the following command is executed every day: >copy *.data:s f (modified preserve

Then each day a copy is made of all files that have been updated or changed since the last time the modified attributes were cleared. See “Change” on page 65. See also “TArchive” on page 601. PUBLIC

Allows publicly owned files to be copied. Normally, when you are logged onto a private account, only files owned by the current account are searched. With this option, files owned by the SYSTEM account may be copied as long as their shared access protections allow it. See “File Access Protection” on page 145.

QUERY

Tells CopyFile to “query” or ask if each file matching the source file specifications is to be copied. This is a default option when wild cards are used. >copy *.data i Ok to copy "CUSTOMER.DATA:S" (Yes,No,All)

When the “Ok to copy” question is asked you may respond with a (Y) for yes, (N) for no or (A) for all. Responding with (A) means yes to this file and all remaining files are included without being queried. Respond with (Esc) to cancel the copy operation. To disable this option use the NOQUERY option.

CopyFile

121

Commands

Indicates that CopyFile should attempt to copy a file only if the destination file name already exists. This option implies a REPLACE option. Note that, if QUERY is used, you are not queried about files if the destination file name does not exist.

REPLACE

Allows a file to be copied even if it already exists on the destination drive. Normally, when the destination file name already exists, CopyFile will not perform the copy. This option tells CopyFile that if it already exists it should erase the existing file and replace it with a copy of the source file.

Commands

If the destination file does not exist, this option has no effect. >copy *.data:s f (replace noquery "HISTORY.DATA:S" replaces "HISTORY.DATA:F". "CUSTOMER.DATA:S" replaces "CUSTOMER.DATA:F". "NEW.DATA:S" copied to "NEW.DATA:F". 3 files copied.

The REPLACE option is implied by both the OLDER and OLDFILE options. However, the OLDFILE option will not copy a file unless the destination file name already exists. SORT

Tells CopyFile to find all of the files that match the source file specifications and to sort the file names in ascending alphabetical order. When CopyFile has created this sorted list of possible file names to copy, it begins the normal copy operation, using the QUERY option if it is in effect. >copy *.data:s f (replace noquery sort "CUSTOMER.DATA:S" replaces "CUSTOMER.DATA:F". "HISTORY.DATA:S" replaces "HISTORY.DATA:F". "NEW.DATA:S" copied to "NEW.DATA:F". 3 files copied.

Compare this example display with the example used in the REPLACE option description. SPECS

This option allows the manipulation of each record in a stream file. With this option you can omit portions of each record, add text to each record and rearrange the contents of the records. For a description of this option’s usage, see “Copying with Field Specifications” on page 126 .

SUBDIR

Indicates that all subdirectories in the source file directory are to be copied to the destination drive. If a subdirectory does not exist on the destination drive, it is automatically created. >copy /art/*.*.*:s j (subdir noq "/ART/ARTICLE.EXE:S" copied to "ARTICLE.EXEC:J". "/ART/GENERAL/PROGRAM.NOTES.CONVERSN:S" copied to "/GENERAL/PROGRAM.NOTES.CONVERSN:J". ...

122 CopyFile

In this example all of the files in /ART directory of the S drive are copied to the J drive. When a subdirectory of /ART is encountered, it is copied along with all files in that subdirectory. If a subdirectory contains a subdirectory, its files will also be copied, and so on.

The SORT option is a default when SUBDIR is specified. TOKEY

Used with indexed and keyed files to specify the last record to copy. Can be used with the FRKEY option to limit the number of records copied before this last record is located. kkk represents the key of the last record to copy. Only records whose keys are less than or equal to this key are copied. >copy customer.master new.master (tokey "THEOS"

This command copies all of the records in the CUSTOMER.MASTER file whose keys start with text that is less than or equal to “THEOS.” TOLABEL

Used with ASCII stream files to specify the last record to copy. Can be used with the FRLABEL option to limit the number of records copied before this last record is located. lll represents the starting text of the last record to copy. Records are copied until a record starting with this text is found and, when found, that record is copied to the destination file. >copy memo.model new.memo (tolabel "Re:"

TRANS

This option allows the manipulation of each record in a stream file. With this option you can translate one or more characters in each input record to a different character in the output record. For a description of this option’s usage see “Copying with Character Translation ” on page 128.

TRUNCATE Used with stream files to truncate each record in the destina-

tion file to nnn characters.

CopyFile

123

Commands

If the source path contains subdirectories and the SUBDIR option is not used, then the subdirectories and the files in those subdirectories are not copied.

TYPE

A default option that tells CopyFile to display the results of each file copy on the standard output device. This display can be redirected.

Commands

>copyfile *.*:s j (noquery "/DEVELOPE.EXEC:S" copied to "DEVELOPE.EXEC:J". "/GRAPH.SAVE1:S" copied to "GRAPH.SAVE1:J". "/GRAPH.DATA:S" copied to "GRAPH.DATA:J". "/GRAPH.START:S" copied to "GRAPH.START:J". 4 files copied.

To disable this option use the NOTYPE option. UPCASE

Used with ASCII stream files to translate all lowercase characters to their uppercase equivalents. All non-alphabetic characters are copied without any translation. Most of the multinational characters (Ä, É, Ñ, etc.) are translated with this option. See “Upcase” on page 727 for more information.

VERIFY

Tells CopyFile to verify that the copy was made correctly by performing a read after each block of the file is written. The data read from the destination file is compared with the data that was written to the file at that location. A mismatch causes CopyFile to retry the write operation.

date1

Copies a file only if the source file’s last change date is greater than or equal to this date. That is, if the source file was changed on or after this date. This option may be used with the date2 option. >copy *.*:s f (10/15/01

The above command will copy only those files that have been created or changed since October 14, 2001. date2

Copies a file only if the source file’s last change date is less than or equal to this date. That is, if the source file was changed or or before this date. May only be specified by first specifying the date1 option. >copy *.*:s f (10/15/01 10/30/01

This command copies only those files that have been created or changed since October 14, 2001, but not any files that were created or changed after October 30, 2001.

124 CopyFile

To specify a date2 when you don’t care about date1, use a date of 1/1/86 for the date1 option. This is the earliest date maintained by the THEOS file system. >copy *.*:s f (1/1/86 11/20/01

CopyFile

125

Commands

Here, since the date1 specification is 1/1/86, only files created or changed prior to November 21, 2001, are copied.

Copying Stream Files

Many of the CopyFile options apply only to the copying of stream or sequential organization files. With stream files you can add information to the end of an existing file by using the APPEND option, change the case made of text in each record with the LOWCASE and UPCASE options, rearrange the contents in each record with the SPECS option or translate characters in each record with the TRANS option.

Commands

Stream files may also be copied to devices other than disks. For instance: >copy system.theos32.devnames prt1 >copy private.exec con

If the file is not a stream file and you attempt to copy it to a device other than a disk, the message “Invalid access method” is displayed. • Copying with Field Specifications The SPECS option provides a means of manipulating the contents of the records in a stream file. With this option you can delete portions of each record, add constant data to each record or rearrange the existing contents of each record. When the SPECS option is used, CopyFile prompts you to enter the specifications: >copyfile sample.data new.data (specs Enter specification list: ?

There are three types of specifications that you may enter: A letter, character or character code to be added to each record. Any typeable character or its numeric value in decimal or hexadecimal can be specified. Merely type the character you want added to each record. To specify the character value in hexadecimal, terminate the number with the letter h. ?A 1 ?65 1 ?41h 1

The above three specification are identical: They each specify that the letter “A” is to be placed in column one of each output record. Constant text to be added to each record. Merely type the string of characters desired surrounded by a pair of quotation marks. (Any delimiter other than a quotation mark may be used. The first character typed is always treated as the delimiter and must be matched with an identical delimiter at the end of the string of characters.)

126 CopyFile

?"New record: " 1 ?\Some text\ 20 ?+abbreviated+ 30

The position of existing text in the source record. Existing text to be copied is indicated by two decimal numbers separated by a dash:

The above specifications indicate that the characters in each source record are to be rearranged: The first ten characters are moved to columns 10 through 19; the characters in columns 11 and 12 are moved to columns 48 and 49; the character in column 13 is moved to column 47; and the remainder of the source record from columns 14 through 99 is moved to columns 50 through 135. As indicated in the example, to specify a single character of the source record, specify a column range that starts and stops on the same position (13-13). Each specification is terminated by the column number to place the letter, constant text or source text in the destination record. The specification list is a list of one or more of these specifications terminated by an empty line. Invalid specifications are ignored with no message. >copyfile sample.data new.data (specs Enter specification list: ?* 1 ?"New " 3 ?1-99 10 ?

In this example each output record will have a bullet symbol in column one, the literal text “New ” in columns three through six, and the original source record text is output starting at column 10 of each record. Columns seven through nine are output as spaces because nothing was specified for that area of the output record. Note that the records output contain only the text and data specified in the specification list. For instance, if the previous example was changed to: >copyfile sample.data new.data (specs Enter specification list: ?* 1 ?"New " 3 ?10-99 10 ?

CopyFile

127

Commands

?1-10 10 ?11-12 48 ?13-13 47 ?14-99 50

The data in the input records, columns 1 through 9, is not copied to the output record because it is not part of the specification list.

Commands

The SPECS option may be used in combination with the TRANS option. When other text modification options are specified in combination with the SPECS option (i.e., UPCASE, LOWCASE), they will manipulate the source text before the specifications are applied and therefore do not apply to the specifications text. For instance, if SPECS and UPCASE were used with the previous specifications list, the literal text “New ” would still be output in columns three through six. It would not be converted to “NEW ”. You can abandon the copy operation during entry of the specifications list by using the (Esc) or (F9) keys. • Copying with Character Translation The TRANS option allows you to translate the characters in each source record as it is copied to the destination record. When the TRANS option is used, CopyFile prompts you to enter the translations: >copyfile sample.data new.data (trans Enter translation list: ?

Translations are entered by specifying a pair of characters separated by a space. The first character is the character in the source file that is to be changed; the second character is the character that it will be changed to. The characters are specified with any typeable character or its numeric value in decimal or hexadecimal. Merely type the character you want translated, followed by a space and then the character to translate to. To specify the character value in hexadecimal, terminate the number with the letter h. >copyfile sample.data new.data (trans Enter translation list: ?ƒ A ?… E ?÷ O ?‹ U ?— N ?Ý A ?

This translation list translates all occurrences of the accented, uppercase letters to their unaccented forms. The TRANS option may be used in combination with the SPECS option. When other text modification options are specified in combination with the TRANS option (i.e., UPCASE, LOWCASE), they will manipulate the source text after the specifications are applied and therefore the “translate to” 128 CopyFile

character might be changed. For instance, if TRANS and LOWCASE were used with the previous specifications list, the accented, uppercase letters would be translated to unaccented lowercase characters. You can abandon the copy operation during entry of the translation list by using the (Esc) or (F9) keys. Of most interest when copying an indexed or keyed file is the BYREC option. This option creates an optimized copy of the source file with a completely rebuilt index to the records in the file. The BYREC option is implied by all of the options that might copy less than the entire file (FOR, FRKEY, and TOKEY). When the BYREC option is used to optimize file access, it is best to first create an empty destination file with the CREATE command described on page 131. By creating the empty file first, you can specify a contiguous file and change the key length, record length and file size. The BYREC option will use this empty file and copy the source file to it, one record at a time. The BYREC option can also be used to copy the records from one type of file organization to another. For instance, from a keyed file to an indexed file. Copying Direct Similar to indexed and keyed files, the BYREC option can reorganize a direct file. Files Notes

The FOR option requires that the FRKEY option be used. When FOR is used without the FRKEY option, the entire file will be copied. If the source and destination files are members of a library and that library does not exist on the destination drive, CopyFile asks if you want to create it: >copyfile customer.data.june j Ok to create library "/CUSTOMER.DATA:J" (Yes,No)

If you respond with (Y), the library is created on the destination drive with a size equal to the source file’s library size. Defaults

NEWDATE (when a modified copy of the source file is created), NEWFILE, NOQUERY (when wild cards are not used), NOSORT (unless the SUBDIR option is used), NOVERIFY, OLDDATE (when an exact copy of the source file is created), QUERY (when wild cards are used), SORT (when SUBDIR option is used), TYPE.

Restrictions

By default, only files owned by the current account are copied. You can copy a public file (owned by the SYSTEM account) when logged onto a private account by specifying the PUBLIC option.

CopyFile

129

Commands

Copying Indexed and Keyed Files

To copy a file owned by another account, you must specify the owning account name as part of the path and the file must provide shared read access: >copyfile private\his.file my.file

Commands

This command copies the file HIS.FILE owned by the account named PRIVATE, to your account, current working directory, file name MY.FILE. You may only copy a file to your account. By default, the destination file is in the current working directory, but you may specify a path to the directory that you want to copy it to. >copyfile my.file textfile/samples/new.file "/MY.FILE:S" copied to "/TEXTFILE/SAMPLES/NEW.FILE:S".

When the destination file specification includes a path, then that path must exist. CopyFile does not create subdirectories (except with the SUBDIR option). See also

130 CopyFile

Backup, FileManager, FileType , IXDiag, Move, Receive , Rename, Net, Restore, Send, TArchive, TBackup, THEO+COM

Create Command The Create command creates direct, indexed and keyed files, libraries of files and subdirectories.

CREATE file ( LIBRARY library-options

2

CREATE file ( SUBDIR

3

CREATE file ( DIRECT direct-options

4

CREATE file ( INDEXED indexed-options

5

CREATE file ( KEYED indexed-options

6

CREATE file ( LISAM lisam-options

7

CREATE file ( recreate-options

Commands

1

file

»

file name with optional path

library-options

»

REPLACE SIZE nnnn

NOTYPE TYPE

direct-options

»

CONTIG FILESIZE nnnnnn GROW n.m RECLEN nnnnn

NOTYPE TYPE

indexed-options

»

CONTIG FILESIZE nnnnnn GROW n.m KEYLEN nnn RECLEN nnnnn

NOTYPE TYPE

lisam-options

»

BINARY CONTIG DICTIONARY FILESIZE nnnnnn GROW n.m

KEYLEN nnn NOCASE NOTYPE RECLEN nnnnn TYPE

recreate-options

»

CLEAN CLEAR

Create

131

Operation

Mode 1—Creates a new library or resizes an existing library. file must be a file description containing both a file-name and a file-type. Libraries may not be a member of another library. >create source.programs (library size 44 >create source.programs (library size 100 replace

Commands

>create my.programs (library

Libraries, like all files on Corona, are dynamically extendable. Although you must specify the initial size of a library when creating it, the size specified is not treated as the maximum size of the library, only the initial size. When more members are added to a library that is already full of member names, the library is made larger. Mode 2—Creates a new subdirectory. file must be a file description containing a file-name. It may have a file-type but it cannot have a membername because subdirectories may not be a member of a library. >create source (subdir

Although the Create command can create subdirectories, the MkDir command is the preferred method. With MkDir you can specify the initial size of the subdirectory. Mode 3—Creates a new direct-access file. Direct files may be members of an existing library. >create accounts.payable.control (direct file 22 recl 128

When creating a direct-access file, you must specify the FILESIZE and the record length (RECLEN). Mode 4—Creates a new indexed-access file. Indexed files may be members of an existing library. >create parts.inventry.sku (indexed file 20000 recl 32 keyl 10

When creating an indexed-access file, you must specify the FILESIZE, the record length (RECLEN) and the key length (KEYLEN). Mode 5—Creates a new keyed-access file. Keyed files may be members of an existing library. >create parts.inventry.list (keyed file 60000 recl 280 key 42

When creating a keyed-access file, you must specify the FILESIZE, the record length (RECLEN) and the key length (KEYLEN).

132 Create

Mode 6—Creates a new LISAM-access file. LISAM files may be members of an existing library. >create parts.inventry.sku (lisam file 20000 recl 32 keyl 10

Mode 7—Clears the contents of an existing direct, indexed, keyed or LISAM file. The contents of all records in a direct file are initialized to zeros. Although indexed and keyed files are not zeroed with this command all of the records are removed and the space is returned to the file’s free space list. Effectively, this is the same as erasing the file and then recreating it with its current file size. However, the clearing process is faster because the disk space does not have to be reallocated. >create customer.master (clear

Library Options

REPLACE

Indicates that the existing library is to be replaced with a library of the same name but a different size. This option preserves all members of the existing library. It does this by renaming the existing library with a temporary name, creating the new, empty library with the size requested, and then renaming the members in the temporary library name to this new library. The temporary library name is then erased. If the requested size of the new library is less than the number of members already in the existing library, the size is adjusted upward so that the new library can contain all of the existing member files. See “Cautions” on page 136.

SIZE

This option is required and specifies the size of the library. This size represents the minimum size to create. Because a library uses the same search algorithm as the root directory, its size is determined by the requirements of the algorithm. For instance, requesting a size of 100 will create a library with a size of 116. Libraries on a disk using the LFS file system are dynamic in size. That is, after their initial creation their size will increase as needed when new library members are added to the libary.

Create

133

Commands

When creating an large indexed-access file, you must specify the FILESIZE, the record length (RECLEN) and the key length (KEYLEN). You may specify the sort organization for the file (BINARY, DICTIONARY or NOCASE).

Commands

Direct File Options

CONTIG

Forces the new file to use contiguous disk space. If sufficient contiguous disk space is not available, the file is not created and a “Disk full” message is reported. See “Notes” on page 135.

FILESIZE

This option is required and specifies the initial number of records that the file can contain. The physical size of the file is computed by multiplying the FILESIZE by the RECLEN. The size of a direct file is dynamic and the file may grow when required.

GROW

Specifies the growth factor for the file. Growth factors are specified as either a whole number, such as 1, 2, 3, etc., or as a fraction, such as 0.1, 0.3, 0.5, etc. Do not specify a combination like 1.3. If you do, only the integer portion is used. The default growth factor is 0.3. For an explanation of file growth factors see “Growth Factor” in the THEOS Corona Version 5 Operating System Reference..

RECLEN

This option is required and specifies the length of each record. The maximum record length is 65,535. However, if the file is to be used by a BASIC16 language program, limit the record length to 2,048.

Indexed and Keyed File Options

CONTIG

Forces the new file to use contiguous disk space. If sufficient contiguous disk space is not available the file is not created and a “Disk full” message is reported. See “Notes” on page 135.

FILESIZE

This option is required and specifies the number of records that the file can contain. The physical size of the file is computed by multiplying the FILESIZE by the sum of RECLEN plus KEYLEN plus the overhead required by the file access method (indexed or keyed). The size of an indexed or keyed file is dynamic and the file may grow when required.

GROW

Specifies the growth factor for the file. This is the same as the GROW option described above.

KEYLEN

This option is required and specifies the allocated length of the keys for each record.

RECLEN

This option is required and specifies the length of each record. This record length is separate from the KEYLEN value. The maximum record length is 65,535. However, if the file is to be used by a BASIC16 language program, limit the record length to 2,048.

134 Create

LISAM File Options

When creating LISAM files you may use the Indexed and Keyed File Options and also the following LISAM-specific options. BINARY

Specifies that the file will be maintained in standard, binary order. In this order, keys starting with “B” follow keys starting with “A,” keys starting with “a” come after uppercase keys. This is the default order for LISAM files.

sequence, although the case mode is significant, the uppercase alphabetic keys are not sorted separately from the lowercase alphabetic keys of the same letter. Specifically, the sort order for each character is: space, !, ", #, $, %, &, ', (, ), *, +, ,, -, ., /, :, ;, <, =, >, ?, @, [, \, ], ^, _, `, {, |, }, ~, ¿, ¡, ¢, £, ¥ , euro, ¼, ½, ÿ, §, °, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, a, Ä, ä, â, à, á, Å, å, Æ, æ, B, b, C, c, D, d, E, e, ë, ê, è, É, é, F, f, G, g, H, h, I, i, î, ì, í, J, j, K, k, L, l, M, m, N, n, Ñ, ñ, O, o, Ö, ö, ô, ò, ó, P, p, Q, q, R, r, S, s, ß, T, t, U, u, Ü, ü, û, ù, ú, V, v, W, w, X, x, Y, y, Z, z, other characters in binary order. NOCASE

Specifies that the case mode of the key is ignored. The file is maintained in DICTIONARY order. Duplicate keys are not allows and a key is considered a dupicate if it is identical to an existing key except for case mode. For instance, if the key “THEOS Software” existed in a file, any attempt to find it with the key “theos software,” “THEOS SOFTWARE,” etc. will find it and, an attempt to write a record with one of those keys will replace the record. Because key values are not changed on updates, the initial creation of a record determines the value of the key.

Recreate Options

Notes

CLEAN

May only be used with the CLEAR option. It causes the contents of the file to be cleared by writing binary zeros.

CLEAR

An existing direct, indexed, keyed or LISAM file is cleared. If option CLEAN is not specified at the same time, only the pointers to the existing keys are cleared, effectively erasing all of the records.

If the CONTIG option is not used for direct, indexed and keyed files, the file is created using any available disk space, contiguous or not. If there is insufficient disk space available, the requested FILESIZE of the file is reduced so that the file can fit in the largest contiguous disk space that is available. It is possible to create a library, subdirectory or data file in another account. Merely specify the complete path for the file description:

Create

135

Commands

DICTIONARY The file is maintained in dictionary order. With this

>create private\program.source (library size 44

Commands

In the above example “PRIVATE\” is the name of another account. Access to this file is restricted unless the CREATE environment variable has been defined and it includes the attributes allowing shared file access. See “CREATE” on page 102 of the THEOS Corona Version 5 Operating System Reference for a description of this environment variable. The growth factor of an existing file can be changed with the Change command described on page 65. Defaults

When the CREATE environment variable is not defined, a data file created with this command has the following attributes: modified, shared read protected, shared write protected, execute protected, not erase protected, not read protected, not write protected and not hidden. If the CREATE variable is defined, it specifies the attributes for the new file. The modified attribute and the file’s last change date is always set for newly created data files (direct, indexed, keyed and LISAM). Subdirectories and libraries created with this command have no protection codes set. The default growth factor for direct, indexed, keyed and LISAM files is 0.3 or 30%.

Cautions

136 Create

The REPLACE option should not be used if any other user might be using one of the members of the library. The REPLACE option is actually a “macro” command in that several separate operations are performed: renaming an existing library, creating a new library, and renaming existing members and erasing the old library. It is best if all users are inactive so that all of the steps can be completed without interruption.

Restrictions

Libraries and subdirectories cannot be members of libraries. Library file descriptions must contain both a file-name and a file-type. The various limitations on key length, record length and file size depends upon the type of file system in use on the resident drive:

Library size Indexed, key length

4GB

LFS

262,100

Limited by disk space only

128

128 65,535

Indexed, record length Indexed, file size

1.7GB 65,535

Direct, record length Direct, file size

1.7GB

LISAM, file size See also

4GB 256

LISAM, key length LISAM, record length

4GB

65,535, or > 16MB if using LISAM-specific i/o statements 1.7GB

Limited by disk space only

Change, MkDir

Create

137

Commands

Item

Commands

138 Create

CRLF Command The CRLF command operates on stream files and converts the end-of-record mark and national characters.

CRLF

file... ( options

2

CRLF

file... ( os options

file

»

file name with optional path, may contain wild cards

options

»

NOTYPE NOXLATE

os

»

DOS THEOS UNIX

Operation

TYPE XLATE DOS

Commands

1

XLATE OEM

CRLF only operates on stream files.

Mode 1—Performs an “auto conversion” between THEOS and DOS or UNIX or between DOS or UNIX and THEOS. The file is analyzed and, if the first record is terminated with a CR only (THEOS format), the file is converted to the DOS format using CR,LF. If the first record is terminated with an LF only (UNIX format) or a CR,LF (DOS format), the file is converted to the THEOS format using CR only. Mode 2—The record terminators in the file are converted to the terminators used by the operating system specified. The normal end-of-record termination character for the common operating systems is:

OS

Operating System

Terminator

THEOS

CR

DOS

CR,LF

UNIX

LF

DOS

Indicates that the record terminator should be changed to a CR,LF.

THEOS

Indicates that the record terminator should be changed to a CR only.

UNIX

Indicates that the record terminator should be changed to an LF only.

CRLF

139

Commands

Options

NOTYPE

Do not display the conversion messages.

NOXLATE

Do not perform any translations except for record terminators.

TYPE

A default option that displays the conversion message for each file converted. The messages are of the form “Changing CR into CRLF on file “SAMPLE.FILE:S”.”

XLATE DOS In addition to the translation of record terminators, all

embedded national characters and other characters whose value is greater than 128 are translated. This option is effective only when file uses CR or CR,LF record terminators. When effective, the eight-bit characters are translated to or from the DOS character set from or to the THEOS character set. This is a default option. XLATE OEM In addition to the translation of record terminators, all

embedded national characters and other characters whose value is greater than 128 are translated. This option is effective only when file uses CR or CR,LF record terminators. When effective, the eight-bit characters are translated to or from the Windows character set from or to the THEOS character set. Notes

The file is converted “in place.” That is, the output of this command is a file with the same name as the input. The actual process used is to output the file with a temporary file name, erase the input file, and then rename the temporary file to be the input file name.

Defaults

TYPE and XLATE DOS are default options.

Restrictions

Only ASCII stream files can be converted with this command. Other file organizations are incompatible between operating systems or do not have end-of-record marks.

See also

FileType

140 CRLF

CRT Command The CRT command demonstrates and tests the console’s display capabilities and keyboard definitions.

Operation

Commands

CRT When CRT is invoked the “CRT Test Menu” is displayed. THEOS® 32 CRT Test Video Attributes Direct Cursor Addressing Relative Cursor Addressing Scroll Up and Down Insert/Delete Line/Char Character Sets... Screen Sizes... Throughput Performance Window Manager... Mouse and ON-Key... Keyboard Exit to THEOS

Display all attribute combinations.

Use the normal menu selection keys to select the desired tests.

CRT

141

„ Video Attributes This test shows the video attributes supported by THEOS and how they are displayed on this console with the current class code.

Commands

Test Video Attributes normal

half

reverse

reverse, half

blink

blink, half

underline

underline, half

blink, underline

blink, underline, half

reverse, blink

reverse, blink, half

reverse, underline

reverse, underline, half

reverse, blink, underline

reverse, blink, underline, half

Monitor mode: v u ä ã å ç b T ` U J K M N é

P d e ‹ Q

Black Blue Green Cyan Red Magenta Normal = Black on White; Reverse = White on Black.

Yellow

S  White

Press ENTER for next screen.

The specific information shown on your screen may differ depending upon your terminal’s or monitor’s capabilities and upon the definitions in the class code (see “ClassGen” on page 75). The “Monitor mode” line shows the characters that your console will display when the monitor mode is enabled. This line is only shown if the class code defines a code for monitor mode on and off. The characters shown here are displayed when the console is a VGA monitor and class code 90 is used. The line showing the color names is displayed only if the class code has a “set alpha color” definition. When (EnterÌ˛) is pressed an “Erase unprotected” is performed. This should clear all of the attribute displays off of the screen except for those shown in half intensity on the right.

142 CRT

„ Direct Cursor Addressing The direct cursor addressing display tests the console’s and class code’s ability to accurately position the cursor. The screen should fill with asterisk ( * ) characters in a top-left to bottom-right manner. Each asterisk is displayed by positioning the cursor to the desired location, displaying the asterisk and then positioning to the next desired location.

„ Relative Cursor Addressing This screen display tests the console’s and class code’s ability to move the cursor relative to its current location (left, right, up and down). The spiraling lines shown here are drawn by moving the cursor with the left, right, up and down codes, and then outputting a single line-drawing character.

Press ENTER for next screen.

CRT

143

Commands

If the screen does not completely fill with asterisks (except for the bottom, right-hand position), there is either something wrong with the class code definition for direct cursor addressing or there is a problem with the communication’s line (baud rate, parity, etc.).

„ Scroll Up and Down

Commands

This display tests the console’s ability to scroll text up and down on the screen. First, lines of text are displayed terminated by a carriage-return, line-feed. When the bottom of the screen is reached, lines continue to display which should cause the lines above this to scroll up. !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abc !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcd "#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcde #$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdef $%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefg %&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefgh &'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghi '()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghij ()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijk )*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijkl *+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklm +,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmn ,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmno -./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnop ./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopq /0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqr 0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrs 123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrst 23456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstu 3456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuv 456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvw 56789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwx

After approximately 100 lines are displayed in this manner, the screen is cleared and new lines of text are displayed. These are displayed at the top of the screen proceeded by an “insert line” command. This causes the display to scroll down. Observe these patterns as they display. Because scrolling takes a relatively long time for a terminal to perform, if there are any handshake problems with your communication’s line, they will show up here with a pattern that does not appear uniform.

144 CRT

„ Insert/Delete Line/Char This display tests the console’s and class code’s insert and delete capabilities. First, the screen is filled with rows of numbers. Then the six insert and delete commands are performed on this displayed text:

Commands

01234567890123456789012345678901234567890123456789012345678901234 1123567890123456789012345678901234567890123456789012345678901234 21234567890123456789012345678901234567890123456789012345678901234 312345 6789012345678901234567890123456789012345678901234567890123 41234567890123456789012345678901234567890123456789012345678901234 51234567890123456789012345678901234567890123456789012345678901234 71234567890123456789012345678901234567890123456789012345678901234 81234567890123456789012345678901234567890123456789012345678901234 912345678901 01234567890123456789012345678901234567890123456789012345678901234 11234567890123 4,1 = DC 8,5 = IL 12,9 = EOL

6,3 = IC 10,7 = DL 14,11 = EOS

Press ENTER for menu.

If your console supports all of these insert and delete capabilities, the screen should look like the one displayed here (except yours should have your attached line length used). The text in the middle of the screen indicates which commands were issued and at which locations. When studying these locations, note that this program addresses the cursor with a number base of zero. Therefore, the upper left corner is location 0,0.

CRT

145

„ Character Sets There are multiple character sets supported by THEOS. When this option is selected from the main CRT menu, a Character Sets menu appears:

Commands

THEOS® 32 CRT Test Character Sets

Line Drawing Graphics National Characters THEOS Characters IBM PC Characters Exit to Main Menu

Display all line graphics characters.

Use the normal menu selection keys to select the desired tests. Note: Not all consoles support all of the character sets.

146 CRT

Line Drawing Graphics The two screens displayed by this menu item show the characters displayed when line-drawing graphics are used and a sample of the graphics display.

= URC

= LRC

= LLC

= LI

= UI

= RI

= DI

= FWI

= HORIZ

= VERT

= RULC

= RURC

= DULC

= DURC

= DLRC

= DLLC

= DLI

= DUI

= DRI

= DDI

= DFWI

= DHORIZ

= DVERT

= RLRC

Commands

= ULC

= RLLC

Press ENTER for next screen.

Press ENTER for menu.

CRT

147

National Characters The National Characters display shows all of the multinational characters supported by THEOS along with their names, such as “Lowercase e grave accent.”

Commands

A special help text file is supplied that shows how to compose these characters from the keyboard. >help compose

THEOS Characters This display shows the THEOS character set. It includes the ASCII characters, the line-drawing graphics characters and the multinational characters. THEOS Character Set

0

1 . . ! 1

2 . . " 2

3 . . # 3

4 . . $ 4

5 . . % 5

6 . . & 6

7 . . ' 7

8 . . ( 8

9 . . ) 9

A . . * :

B . . + ;

C . . , <

D . . =

E . . . >

F . . / ?

4: 5: 6: 7:

@ P ` p

A Q a q

B R b r

C S c s

D T d t

E U e u

F V f v

G W g w

H X h x

I Y i y

J Z j z

K [ k {

L \ l |

M ] m }

N ^ n ~

O _ o .

8: 9: A: B:

. .

. .

. .

. .

. .

. .

. .

. .

. .

. .

. .

. .

. .

. .

. .

. .

.

.

.

.

.

.

C: D: E: F:

Ä ô ß .

ï Ñ ÿ .

î ñ § .

ì Æ

í æ ² .

Ö Å . .

ö å . .

0: 1: 2: 3:

0 . .

ä ò ¿ .

â ó ¡ .

à Ü ¢ .

á ü £ .

É û ¥ .

ë ù l .

ê ú =C .

è Ç ¼ .

é ç ½ .

Press ENTER for menu.

148 CRT

a

.

IBM PC Characters The IBM PC character set is available on most consoles that are PC Term compatible. This character set is “Code Page 437” and is accessed by a program by enabling monitor mode.

1 v

2 u

0

! 1

4: 5: 6: 7:

@ P ` p

8: 9: A: B: C: D: E: F:

0: 1: 2: 3:

0

4 ã d $ 4

5 å e % 5

6 ç ▄ & 6

7 b Q ' 7

8 T

9 `

A U

B J

" 2

3 ä P # 3

D M  =

E N

F =C

+ ;

C K S , <

( 8

) 9

* :

. >

/ ?

A Q a q

B R b r

C S c s

D T d t

E U e u

F V f v

G W g w

H X h x

I Y i y

J Z j z

K [ k {

L \ l |

M ] m }

N ^ n ~

O _ o O

Ç É á ░

ü æ í ▒

é Æ ó ▓

â ô ú

ä ö ñ

à ò Ñ

å û ª

ç ù º

ê ÿ ¿

ë Ö ⌐

è Ü ¬

ï ¢ ½

î £ ¼

ì ¥ ¡

Ä ₧ «

Å ƒ »

α ≡

ß ±

Γ ≥

π ≤

∑ ⌠

' σ ⌡

µ ÷

τ ≈

Φ ˚

Θ •

Ω ·

█ δ √

▄ ∞ ⁿ

▌ ø ²

▐ ε ■

▀ ∩

Commands

IBM-PC Character Set

Press ENTER for menu.

This screen does not display properly if the console does not support the “Code Page 437” character set. It will not display at all if the class code number is not one of the known class codes for PC Term compatible terminals (see “CLASSnnn (Class Codes)” on page 213).

CRT

149

„ Screen Sizes

Commands

Some terminals support multiple screen sizes. For instance, most VGA display monitors support the sizes shown in the following menu. When the console supports multiple screen sizes, a menu like the following appears. This screen allows you to demonstrate the various sizes that THEOS thinks are available on your console. THEOS® 32 CRT Test Screen Size Selections - Super VGA color: Video7 40 80 80 80 80 80 80 100 132 132 132

columns columns columns columns columns columns columns columns columns columns columns

X X X X X X X X X X X

24 24 29 33 42 49 59 39 24 27 43

rows rows rows rows rows rows rows rows rows rows rows

Exit to main menu

Use SYSGEN/ATTACH to set screen sizes.

Use the normal menu selection keys to select the desired tests. This menu allows you to select various screen sizes and see how they appear on your console. The CRT command will not change the screen size of your console except during this demonstration. Once a desirable screen size is found, use the Attach or Sysgen command to set the attached screen size. Note: A VGA console can only support multiple screen sizes if the console is not using graphics. That is, SETUP VGA is configured to use “THEOS Sysgen.”

150 CRT

„ Throughput Performance This test uses two screens to test the actual throughput performance of the console as it is currently attached. First it tests the transmission rate when one full page of text is sent to the console, and then it tests the scroll rate. The accuracy of this test may be effected by buffering if the console is attached via an intelligent multiport. Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll cps (280,000) throughput bps)

Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll

Press ENTER for next screen.

Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll: 1,066

Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll msec; 54 lines/sec Press ENTER for menu.

Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll

Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll

Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll Scroll

CRT

151

Commands

Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll Full page: 81 msec; 28,000

„ Window Manager This function of the CRT command tests and demonstrates the capabilities of window management on the console.

Commands

THEOS® 32 CRT Test Window Management Function Selections

Open, Close and Reorder Windows Window Frames Window Titles Text Clipping Window Text Copy/Transfer Window Menu Functions Exit to Main Menu

Open and display some windows, reorder them, then remove and close.

Use the normal menu selection keys to select the desired demonstrations.

152 CRT

„ Mouse and ON-Key This function presents a menu that allows you to test the mouse and the “ON-KEY” capabilities of the console. THEOS® 32 CRT Test

Commands

Supported Mouse APIs

Window Manager Manager Mouse API ON-Key Events Exit to Main Menu

Mouse reports are standard mouse packets.

Use the normal menu selection keys to select the desired demonstrations.

CRT

153

Window Manager Mouse API This screen tests the Window Manager Mouse capability. Window Manager Mouse API

Commands

Window 2 Left-click Left-down Left-dclick Left-drag

E X I T

Window 1

Window 3 Row: 12 Col: 28 Button 0804

Window 4 Win: 1 Button 0804 Row: 12 Col: 28

The four windows in this display screen are used to report various information about mouse activity. Window 1: This is a large target area. Window 2: A display window that shows the last mouse event, such as: “Left-down,” “Left-click,” “Right-dclick,” etc. Window 3: A display window showing the last mouse event relative to the screen origin (upper left corner of screen). Window 4: A display window showing the last mouse event relative to the window origin. To exit from this test click on the “Exit” display button or press (Esc).

154 CRT

ON-Key Events This display allows you to test the keyboard for all keys that can be detected by the “ON-KEY” capability of THEOS’ Window Manager software. Merely press the keys you are interested in to determine if the ONKEY mechanism can detect it. If nothing displays on the screen, then ONKEY could not detect the key or key combination.

„ Keyboard This test allows you to test the console’s class code definitions for the input function keys. A simulated keyboard is displayed on the screen. As each key on the keyboard is pressed, the cursor is positioned to the key received and decoded by the class code. Notes

The operation and specific displays seen when the CRT command is used will greatly depend upon your specific console and the class code associated with that console.

See also

Attach, ClassGen, Printer, Setup, Sysgen

CRT

155

Commands

To exit from this test press (Esc) twice.

156 CRT

Commands

Date Command The Date command displays the current system date and time on the standard output device (normally the console).

DATE

2

DATE

format Operation

Commands

1

+format »

codes specifying the format of the date and time

Mode 1—Outputs the current date and time. >date Thursday,

July 4, 2002

2:49 PM PST

The year is always displayed as a four-digit number including the century, and the time is always displayed in 12-hour format using “am” and “pm” designations. The day of the week name and the month name are specific to the current language in use.. Mode 2—Outputs the current date and time formatted according to the format specifications. The format must start with a plus sign ( + ) and, if there are any lowercase characters, it must be enclosed within a pair of quotation marks. >date "+DATE: %m:%d:%y%nTIME: %H:%M:%S" DATE: 07:04:02 TIME: 10:02:15 >date "+DATE: %D%nTIME: %r" DATE: 2002.07.04 TIME: 10:02:15AM >date "+Event occurred on %B %d, %Y at %H:%M" Event occurred on July 04, 2002 at 15:42

Date

157

Commands

Format Codes

The format specification is a string of characters specifying the literal characters and symbols that are output, along with codes specifying the date or time element to output. The formatting codes use the percent character ( % ) followed by a single letter. The letter indicates the specific date or time element to use. %n

Starts a new display line.

%f

Starts a new display page (form-feed output).

%t

Tabs to the next tab stop. Tab stops are positioned every eight columns.

%%

Outputs a single percent character.

%A

Day of week name (Monday, Tuesday, etc.) Uses text in system messages #264 and 265.

%B

Month name (January, February, etc.). Uses text in system messages #261, 262 and 263.

%D

Complete date formatted using the current DATEFORM: 07/04/2002 04-07-2002 2002.07.04

DATEFORM = 1 DATEFORM = 2 DATEFORM = 3

Note that the date is always displayed with a four-digit year.

158 Date

%H

24-hour number (00–23).

%J

Day number of month, without leading zero (1–31).

%M

Minute number (00–59).

%S

Second number (00–59).

%T

Complete time in hh:mm:ss format (i.e., 15:24:32).

%Y

Year number including century (i.e., 2002).

%a

Day of the week name, abbreviated to three letters (Mon, Tue, Wed, Thu, Fri, Sat and Sun). Uses text in system message #423.

%b

Month name, abbreviated to three letters (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov and Dec). Uses text in system message #423.

Day number of month (01–31).

%h

Month name, abbreviated to three letters (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov and Dec). Uses text in system message #423. This format is identical to the %b format specification.

%j

The Julian day number (001–366).

%m

The current month number (01–12).

%r

The current time in 12-hour notation (i.e., 03:15:20PM).

%w

Weekday number with Sunday = 0.

%y

Year number in century (00–99).

Commands

Notes

%d

Remember that the format specification must start with a plus sign. If format contains any spaces or lowercase letters you must enclose it within quotation marks. This is a command that outputs to the standard output device so the output can be redirected to a disk file, printer, etc. See “Standard Input, Standard Output and I/O Redirection” on page 53 of the THEOS Corona Version 5 Operating System Reference.

See also

Set, Setup SysGen, Setup Time, Show

Date

159

Commands

160 Date

Decrypt Command The Decrypt command decrypts a sequential file using public key/private key Data Encryption Standard (DES) 56-bit or 128-bit encryption algorithms.

DECRYPT source destination ( password

2

DECRYPT source ( password > destination

3

DECRYPT ( password < source > destination

Commands

1

source

»

name of file to decrypt or encrypt

destination

»

name to use for resulting decrypted or encrypted file

password

»

private key password, case-sensitive

option

»

algorithm to use for encryption: DES DES56

DES128 TDES

Operation

Using the public key built into the Decrypt command (which is the same public key that Encrypt uses) and the private key password specified, the source file is decrypted and the result is output to the destination file.

Options

DES

Use the 56-bit DES encryption algorithm

DES56

Use the 56-bit DES encryption algorithm

DES128

Use the 128-bit DES encryption algorithm

TDES

Use the 128-bit DES encryption algorithm

Notes

Refer to the enckjsdf command for a description of the DES encryption standard. Because the password is case-sensitive and the CSI normally folds the arguments to uppercase, it is best to always enclose the password in quotation marks to ensure that it is passed to the Decrypt command properly.

Filters

The Decrypt command can operate as a filter or pipe. When not specified, the destination file for both Decrypt command is stdout. This can be redirected to a file or another program. DECRYPT

source ( password

Decrypt 161

The above command will decrypt the source file and output it to the screen. DECRYPT

source ( password |

LIST ( print

This second command will decrypt the source file and pipe the result to the LIST command which will print it to the primary printer. Commands

ENCRYPT ... DECRYPT

source (

TDES

password1 |

source ( password2 |

ENCRYPT ( TDES

DECRYPT (

password2 > dest

password1 > dest

This last command might be used to decrypt the file generated in the previous Encrypt example. Note that the sequence of the passwords is the reverse. It decrypts the source file using password2 and pipes the result to the Decrypt command to decrypt it again with password1. The result is saved in dest. Defaults

When decrypting a file, if the algorithm is not specified then DES 56-bit encryption is used.

Cautions

The private-key password is not embedded in the encrypted file. If a different key is used to decrypt the file than was used to encrypt it, the Decrypt command cannot report the error and will merely generate a destination file that is not a properly decrypted form of the original file. Remember your passwords but do not write them down for security reasons.

Restrictions

Only stream or sequential files can be encrypted.

See also

Encrypt, FileManager, WinWrite

162 Decrypt

Dial Command EXEC The Dial command is an EXEC language program that provides convenient access to the THEO+COM command’s modem and telephone number dialing capabilities.

DIAL

2

DIAL

number Operation

Commands

1

number »

telephone number to dial

Mode 1—Invokes THEO+COM in DIAL mode. The first attached communications port is used and the “Dialing Directory” is then invoked, allowing you to choose one of the entries to dial. Dialing directory maintenance is allowed along with manual dialing. Refer to the THEO+COM Installation and User’s Guide manual for a description of the dialing directory and its use. Dial automatically exits after a number is dialed or if you abort the selection of a number. Any modem or telephone connection remains connected. Mode 2—Invokes THEO+COM in DIAL mode. The first attached communications port is used and number is dialed via the device connected to that port. >dial 1 800 123-4567 Dialing 1 800 123-4567

The number may contain any of the following characters. Character

Meaning or Effect

( ) - space

Ignored: Used for readability purposes only.

digits 0–9

Generates the tones or pulses for the digit.

,

Wait for two seconds. Multiple commas may be used for additional periods of delay.

/

Wait for 125 milliseconds. (Not all modems support this code.)

W

Wait for a secondary dial tone.

@

Wait for five seconds of silence.

!

Go on-hook for ½ second and then return to off-hook. Also called flash hook.

Dial

163

Character

Meaning or Effect

letters A–Z

Generates the tones or pulses corresponding to the telephone dial letters. For instance, the number “93THEOS” would dial “9384367.” The letters A, B and C match the digit 1, the letters D, E and F match the digit 2, etc.

Commands

The letters A–D may not be specified with spaces surrounding each letter or they will be interpreted as the DTMF codes described next. *#ABCD

Generates the corresponding telephone tones if tone dialing mode is enabled. The letter codes must be specified with spaces surrounding them to avoid confusing them with the telephone dialing pad letters described above.

P

Switch to pulse dialing mode. This code must be surrounded by space characters.

T

Switch to tone dialing mode. This code must be surrounded by space characters.

R

Switch to answer mode after dialing. This code can only be used at the end of the dialing string. It is used when initiating a call to an originate-only modem. After the number is dialed, your modem switches to answer mode.

;

Returns to modem command mode after the number is dialed. This code can only be used at the end of the dialing string and it must be part of a string enclosed in quotation marks (otherwise the CSI will treat it as a comment).

Dial exits after a number is dialed. Any modem or telephone connection remains connected.

Notes

To use a communications port other than the first attached COM n device, or to use any of the THEO+COM command line options, you must use the THEO+COM command (synonym name is COM).

Defaults

Dial uses the communication protocol and configuration defined by THEO+COM’s configuration menu.

Restrictions

A modem or computer-controlled telephone dialer must be connected to the first communications port. Dial will wait forever to get a valid response from the device. You may have to abort the command ( (Break),(Q) ). The THEO+COM configuration and modem setup must be defined properly before using the Dial command.

See also

164 Dial

THEO+COM

DialNet Command The DialNet command is used to control and monitor Dial-Up Networking connections (DUN).

1

DIALNET function profile

2

DIALNET

function

»

START STOP STATUS

profile

»

name of profile defined in SETUP NET

Operation

Mode 1—This is the command-line interface to DialNet and is suitable for usage by EXECs and application programs. To use this mode when there are multiple profiles defined, you must know the name of the profile definition that you want to use. If there is only one profile defined, that profile is used automatically and you do not have to specify the profile name. DialNet can perform three functions:

To connect to a remote PPP server, use the command: >dialnet start profile-name

To display the status of a current connection to a PPP server, use the command: >dialnet status profile-name

To disconnect from a remote PPP server, use the command: >dialnet stop profile-name

Refer to the “Command-Line Interface” on page 169 for a description of the information displayed by these functions.

DialNet

165

DIALNET

The DialNet command can operate with a command-line interface or as a windowed interface. This is reflected in the two modes of operation. Both modes can perform the same operations, but the information shown and how it is displayed differs between the two.

Mode 2—This is the windowed interface to the DialNet command. When Mode 2 is used, it displays the following screen and menu:

Commands

Windowed Interface

Use the normal menu selection keys to select the desired item. The window on the right displays a brief summary about each profile that is currently connected. When Connect, Disconnect or Status is selected, and you have multiple profiles defined, you are offered a list of the profiles available for that function. Profiles are defined with the Setup Net Dial-Up Networking menu. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.) When only one profile is defined, the operation is performed automatically on that single profile. You may exit this menu be selecting the Exit item, by pressing (Esc) or by pressing (F9). Connect. Selecting this item connects to the single profile defined in your configuration or, if there are multiple profiles defined it displays a list of those profiles that are not currently connected. Select the profile that you want connected. An attempt is made to dial and connect to the PPP server specified in the profile definition. Press (Esc) if you do not want to connect to any of those profiles at this time.

166 DialNet

When successfully connected, the “Connected Profiles” window on the right is updated with the new connection summary information. Note that the “Connect Time” information display is only updated every ten seconds. For possible problems that might be encountered during the connection attempt, refer to the DialNet Start description on page 169.

DUN connections are available to all users on your system, so be sure that the connection is not being used at this time. It is possible that another session on this terminal or another user on the system is using the connection. Status. When only one profile is connected the status of that connection is displayed. When multiple profiles are connected a list of those connected profiles displays and you can select the one that you want the status displayed. Press (Esc) if you do not want to see the status of any of those profiles at this time. If there are no profiles connected, an error message displays. The status display for a connected profile appears as:

Profile: Host IP: Remote IP: Connected on: Bytes sent: Packets sent: Packets rejected: Largest packet sent: Handshake: Inactivity time-out: Modem phone speed:

Connection Status PACIFIER 206.163.58.6 204.245.231.131 03/12/2001 08:02:45 for: 00:06:12 1,591 received: 2,611 34 received: 27 2 133 received: 576 CTS/RTS Baud rate: 38,400 00:10:00 remaining: 00:07:39 28,800

Most of the meanings of the fields in this display are apparent. To clarify those that might not be apparent:

DialNet

167

Commands

Disconnect. When only one profile is connected, this function disconnects that profile. When multiple profiles are connected a list of those connected profiles is displayed and you can select the one that you want disconnected. Press (Esc) if you do not want to disconnect any of those profiles at this time. If there are no profiles connected, an error message displays.

Commands

Host IP

The IP address for your computer. This was assigned by the remote PPP server and may be different each time that you connect. (Dynamic IP address assignment.)

Remote IP

The IP address of the remote PPP server. This may be different each time that you connect if the remote site has multiple PPP servers.

Packets rejected The number of packets sent to or received from the PPP

server that were rejected for one reason or another. Each time that a packet is rejected, a log entry is added to the DUN log file defined in Setup Net Dial-Up Networking . (See THEOS Corona Version 5 Operating System Installation and Setup Guide.) Baud rate

The transmission speed between your computer and the modem. This is specified in the profile definition.

remaining

This is the amount of time remaining until the connection is automatically terminated. This time is reset to the “Inactivity Time-out” value every time that a packet is sent or received over the connection. Note: This field and the “Inactivity Time-out” field are only displayed if there is a timeout value specified for the profile.

Modem phone speed This is the transmission speed between the two

modems: your modem and the remote modem. This speed may be lower than the Baud rate speed because it is the result of negotiations between the two modems and is the best speed that they support with the current telephone connection.

168 DialNet

CommandLine Interface

The DialNet command-line interface provides all of the capabilities of the menued interface and can be used from an EXEC or application program. Unlike the menued interface, which displays a list of profile names that you can choose from, the command-line interface requires that you know the name of the profile definition that you want to use.

>dialnet start myisp > connect.message

This disk file can then be read and used by the application program. • DialNet Start The DialNet Start function connects this system to the remote PPP server defined in the profile definition. For instance: >dialnet start myisp Profile "MYISP" connected successfully, Host IP address: 206.163.58.53 Remote IP address: 204.245.231.131.

If the profile is already connected, the same messages are displayed. There are several situations that may prevent a successful connection. The PPP server is not started. (See the Setup Net Dial-Up Networking command.) The profile name specified is not defined. The profile is already in use by another user. The serial port referenced in the profile definition is in use by another task. The telephone number is invalid or cannot be reached at this time (busy or your phone line is already in use). The “Login Name” and/or “Password” specified in the profile definition is invalid. Remember that some PPP servers use case-sensitive account names and almost all use case-sensitive passwords.

DialNet

169

Commands

When DialNet is used from an application, remember that i/o redirection can be used to redirect the output of DialNet to a disk file. For instance:

• DialNet Stop The DialNet Stop function disconnects this system from a currently connected remote PPP server. For instance:

Commands

>dialnet stop myisp Profile "MYISP" is now disconnected.

There are several situations that may prevent a successful disconnection. The PPP server is not started. The profile name specified is not defined. The profile is not currently connected. • DialNet Status The DialNet Status function displays the status of a profile. >dialnet status myisp2 Dial-Up Network Profile "MYISP2" is not started. >dialnet status myisp Dial-Up Network Profile "MYISP" is connected. Connection task: 13 Host IP address: 206.163.58.17 Remote IP address: 204.245.231.131 Bytes sent: 0 Bytes received: 0 Packets sent: 0 Packets received: 0 Packets rejected: 2 Largest packet sent: 0 bytes. Largest packet received: 0 bytes. Inactivity time-out value: 600 seconds. Time remaining in inactivity timer: 67 seconds. Registered users for this profile: 1 Connect time: 00:08:53 Serial port speed: 19200 bps This connection is the default gateway.

The fields displayed in this status report have the following meanings:

170 DialNet

Connection task The user process number assigned for this connection. Host IP address The dotted IP address assigned by the remote PPP server

for your system on its network. Remote IP address The dotted IP address of the remote PPP server.

Bytes received The number of bytes received over this connection. Packets sent The number of TCP/IP packets transmitted over this connec-

tion. Packets received The number of TCP/IP packets received over this connec-

tion. Packets rejected The number of TCP/IP packets rejected. A log entry is

added to your Dial-Up Networking log file, if one was defined in the Setup Net Dial-Up Networking. Largest packet sent Size of largest packet sent to PPP server. Largest packet received Size of largest packet received from PPP server. Inactivity time-out value This value is defined in the profile definition. Time remaining in inactivity timer The amount of time remaining until an

automatic disconnect occurs. This timer is reset every time that a packet is sent or received over this connection. Registered users for this profile Indicates the number of users that are

actively using this connected profile at this time. Connect time The length of time that this profile has been connected. Serial port speed The transmission speed between your computer and the

modem. This value is specified in the profile definition. This connection is the default gateway. Indicates that, while this profile is

connected, it is the default gateway. When the profile is disconnected, the default gateway reverts to the gateway specified in the Setup Net Identification menu. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.)

DialNet

171

Commands

Bytes sent The number of bytes transmitted over this connection.

Dynamic IP Addresses

Because dial-up connections to ISPs cause your IP address to be dynamically assigned, each time that you connect you may have a different IP address assigned to your computer on their network. Besides displaying the IP address assigned to you, DialNet also writes the information to a disk file.

Commands

Each time that you successfully connect to a profile, DialNet writes the “Host IP address” to the file /THEOS/CONFIG/DUN_IP:S. When you disconnect from a profile, that file is erased, indicating that the IP address is no longer valid. This file is a stream file that can be used by application programs. If other, remote users need to access your computer via this dial-up connection, you must let them know the IP address currently assigned to your computer. Restrictions

To successfully use the DialNet command, several conditions must be met: The PPP server must be started. One or more profiles must be defined in the Setup Net Dial-up Networking menu. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.) The specific profile requested must be defined. The serial port specified in the profile definition must be attached as a public device or not attached by any user. If the serial port is a public device, it must be unused at the present time by any other process. To connect two profiles, the definitions for the profiles must use different serial ports and each must have its own telephone line.

172 DialNet

Disk Command The Disk command formats and partitions disk volumes, reports on the status of the disk and disk allocation, and performs diagnostic tests of a disk volume.

DISK

2

DISK

/:drive

3

DISK

drive ( options

4

DISK

drive ( FORMAT format-options

5

DISK

file ( options

Commands

1

drive

»

disk drive attachment letter

file

»

file name with optional path

options

»

ACCOUNT BADMAP BOOT CLEAN CLEAR

format-options

»

BOOT CYLINDERS nnnn DENSITY n HEADS nn INCREMENT nn

Operation

FAST FIX FREE FRAGMENT HEX

LABEL MAP MULTIUSER NOASK OPTIMIZE

PRTnn SEEK SIZE nn SHOW VERIFY

NOASK SECTORS nnn SIZE nn TRACKS nnnn

Mode 1—Invokes the Disk command menu described on page 184. Mode 2—Display the main, root directory size and location for drive attached as drive. >disk /:s "/:S" directory is at sector 4; offset 20 232 256 116 4,511,768

The above example shows a root directory with two extents (indicating that it has grown since it was originally allocated). It has a total size of 348 sectors.

Disk 173

Mode 3—Performs one of the status reports or diagnostic tests indicated by the specific options specified. When no option is specified the default option of FAST is performed.

Commands

>disk i Disk I label "Image". File system = THEOS. Capacity = 2,097,152 (128 cylinders, 2 heads, 32 sectors). Main directory size = 964 files. Allocated bytes = 64,512. Available bytes = 2,032,640.

When the option is FAST or SHOW the drive specification may be the wild card asterisk ( * ). This displays the disk status for each of the currently attached drives, in drive search sequence. Drives not included in the drive search sequence are omitted from this report. (The drive search sequence is described on page 110.) >set search sim >date "+Disk status as of %B %d, %Y at %H:%M" > disk.status:s >disk * >> disk.status:s

The above commands define a drive search sequence that includes the system drive and two other attached drives. Using i/o redirection, a date stamp is output to a log file and then the disk status report is appended to that log file. This log file contains: Disk status as of August 03, 2001 at 08:50 Disk S label "THEOS". Archived to disk "TUESDAY" on 3 August 2001, at 18:35. File system = THEOS/4G. Capacity = 267,386,880 (225 cylinders, 64 heads, 64 sectors). Main directory size = 1,004 files. Allocated bytes = 124,427,008. Available bytes = 142,959,872. Disk I label "Image". File system = THEOS. Capacity = 2,097,152 (128 cylinders, 2 heads, 32 sectors). Main directory size = 964 files. Allocated bytes = 64,512. Available bytes = 2,032,640. Disk M label "Ram_Disk". File system = THEOS. Capacity = 2,097,152 (256 cylinders, 1 heads, 32 sectors). Main directory size = 524 files. Allocated bytes = 53,760. Available bytes = 2,043,392.

174 Disk

Mode 4—Formats a disk volume. Formatting involves the physical formatting of every sector on the disk volume and the building of a THEOS disk volume, including the disk label information and an empty root directory. See “Formatting Disks” on page 186.

>disk master.control:s "MASTER.CONTROL:S" directory is at sector 92; offset 0 64 137 >disk julian.* "JULIAN.COMMAND:S" directory is at sector 97; offset 128 174 376,638 "JULIAN.BASIC:S" directory is at sector 164; offset 128 1 12,516 4 19,898 "JULIAN.ORIGINAL:S" directory is at sector 203; offset 0 5 9,157 "JULIAN.OLDCMD:S" directory is at sector 245; offset 128 174 376,464

The first number displayed on the second line is the count of the number of sectors used by the file starting at the sector number shown on the right. Thus, in the above example, the MASTER.CONTROL:S file has a single extent that uses 64 sectors starting at sector number 137. Options

ACCOUNT

This option has meaning only when used with the MAP option. It restricts the map display to those files owned by the current account. Compare the following example with the example shown with the MAP option. >logon acct9 >disk i (map account Sectaddr 486 490 527

Count Ext File-name 4 ACCT9\SAMPLE.DIRECT 37 ACCT9\SAMPLE.INDEXED 198 ACCT9\SAMPLE.KEYED

BADMAP

Displays a list of the unusable sectors.

BOOT

Copies the file SYSTEM.THEOS32.BOOTER1 to sectors 0–3.

CLEAN

Cleans all of the unallocated sectors on the disk by writing zeros to them. This option would be appropriate if you want to insure that all erased files are truly erased.

Disk 175

Commands

Mode 5—Displays the allocation information about file. This information includes the physical location of the directory entry for file and a list of all of the extents of file showing their locations and sizes in sectors.

Normally when a file is erased, its directory entry is marked as deleted and the disk space is returned to the free space map. The data in the file still resides on the disk and could be accessed by someone using the patch command. The data is not destroyed until the space is overwritten by another file.

Commands

This option destroys the contents of all erased files. CLEAR

Clears the disk of all files and directory entries. The root directory is rebuilt as an empty directory using its current allocated size. Use the SIZE option to clear the directory to a different size. Since this is a very destructive operation, you are asked to confirm this request before the disk is cleared. >disk f (clear Ok to erase all files on disk F (Y/N)

FAST

Displays a quick disk status. Unlike the SHOW option, files are not counted and misallocations are not checked. This is the default option when no options are indicated >disk j Disk I label "Image". File system = THEOS/IMG. Capacity = 1,048,576 (64 cylinders, 2 heads, 32 sectors). Main directory size = 964 files. Allocated bytes = 941,568. Available bytes = 107,008.

Compare this display with the display from the SHOW option. The drive may be specified with the wild card *. FIX

Attempts to correct disk misallocations.

FRAGMENT Displays a list of all of the files that are fragmented or use

more than one extent. >disk s (fragment multiuse Areas 2 3 2 ...

File name SYSTEM\ATTACH.OUTPUT SYSTEM\B20UPD.IMG SYSTEM\DIALDIR/COMPUSRV.BACKUP

Total fragmented files: 165 out of 9,939. 2 percent of files on disk are fragmented. 176 Disk

A file may be fragmented for one of three reasons: When it was originally created there was insufficient contiguous disk space for the entire file; the file grew in size and, at that time, the next free space available was not contiguous with the existing file; the file is larger than the maximum size for one extent.

FREE

Displays the list of available sectors for the disk. >disk j (free Sector 867 2,189 2,891 4,092

HEX

Count 79 308 27 4

This option can be used with the MAP and FREE options to cause the numbers to display in hexadecimal. >disk k (map hex Sectaddr 0 4 5 0x3A 0x3B

LABEL

Count Ext File-name 4 1 0x35 1 0x1FC5

** ** ** ** **

boot label main directory free space map available sectors

Changes the disk volume label. The new label can either be specified on the command line by following the LABEL keyword with an equal sign and the new label or, when this is not done, you are asked for the new label. >disk f (label Enter disk label: Sample >disk f (label=Example

Disk labels may use upper and lowercase letters, digits. the underscore, space or period characters. Labels are limited to a maximum of eight characters. After the label is changed a disk mount operation is performed. See “Mount” on page 367.

Disk 177

Commands

There is a slight performance degradation with fragmented files but it is insignificant in most situations.

MAP

Displays a usage map of all sectors on the drive volume. This map display is in disk sector number sequence. >disk i (map Sectaddr

Commands

0 4 5 246 247 251 288 486 490 527 725

Count Ext File-name 4 1 241 1 4 37 198 4 37 198 7,467

** boot ** label ** main directory ** free space map SYSTEM\TEST.DIRECT SYSTEM\TEST.INDEXED SYSTEM\TEST.KEYED ACCT9\SAMPLE.DIRECT ACCT9\SAMPLE.INDEXED ACCT9\SAMPLE.KEYED ** available sectors

The “Ext” column has numbers in it only for those files that are fragmented. See the FRAGMENT option description on page 176. There are several identifiers used in the “File-name” column to identify disk space used by non-files. These identifiers are described in the following table.

178 Disk

Message

Meaning

** boot

The first four sectors of every disk are reserved for a “bootstrap loader” program.

** label

The fifth sector of every disk contains disk label information.

** main directory

The “root” directory of the drive.

** free space map

One or more consecutive sectors identifying locations on the drive that are not in use by any file. Multiple free space map sections will be used on a drive that has had files deleted or extended, causing additional areas of the disk to become available.

** available sectors

One or more contiguous sectors that are not assigned to any file or other function.

Meaning

** missing sectors

THIS IS AN ERROR MESSAGE! It identifies an area of the disk that is not accounted for by any file or free space map.

** overlaps

THIS IS AN ERROR MESSAGE! It identifies an area of the disk that is “owned” by two or more files.

If disk errors are reported, they should be corrected as soon as possible! MULTIUSER Tells Disk not to check for multiuser operation before performing the requested function. When Disk is instructed to FORMAT or FIX a public disk, it requires single user mode. If other users

are logged onto the system, it displays the message: “Must be single user or private volume.” Using this option tells Disk to not restrict the function to single-user operation (the message is still displayed). See “Cautions” on page 187. NOASK

When used with the CLEAR option, suppresses the request “Ok to erase all files...”. Use this option only if you are certain that you have specified the proper disk.

OPTIMIZE

Cleans up and optimizes the disk’s directories and libraries by removing deleted entries (erased files), sorting subdirectories and reordering the files in subdirectories. A slight performance increase can result from this optimization.

PRTnn

Indicates that Disk is to print the information on the attached printer number nn instead of the standard output device or console. The option keyword PRT may be specified as PRT, PRINT or PRINTER. As a convenience, PRINTER1 may be specified as P.

SEEK

Tests the disk’s access and reliability by performing continuous random seeks and reading the data found there. Note that disk caching is not bypassed. For small disk volumes with disk caching enabled, this means that most if not all of the disk testing will be satisfied by the disk cache memory and is not a true test of the disk access. In this situation, disk caching should be disabled. See “Cache” on page 43. Disk 179

Commands

Message

SHOW

Analyzes the disk and displays the disk status. All files are counted and the allocations for each file are checked. Under or over-allocated amounts are reported.

Commands

>disk s (show Disk S label "THEOS5". Archived to disk "Thursday" on 8 January, 2002, at 16:25. File system = THEOS/LFS. Capacity = 13,752,668,160 (1,672 cylinders, 255 heads, 126 sec). Main directory uses 125 out of 855 files. Total files = 27,072. 510 directories. 63 libraries. 23,650 stream files. 2,730 program files. 54 indexed files. 9 keyed files 56 relative files. Allocated bytes = 1,445,377,024. Available bytes = 12,307,291,136.

Note that, if a misallocation is reported and other users are active on the system, the misallocation may be okay if it is due to another user allocating or deallocating disk space at the time this status report is generated. Check the status again after all users are logged off or at command prompts. The “File system” displays as File System

Meaning

CD-ROM

Disk is a CD-ROM disc

DOS/FAT32

Disk is a DOS or Windows disk attached as DOSDiskA or DOSDiskC

THEOS/4GB

Disk is a THEOS floppy or a THEOS hard disk formatted with the 4GB file system

THEOS/IMG

Disk is an image drive attachment

THEOS/LFS

Disk is a hard disk formatted with Corona as a Large File System

THEOS/RAMDISK

Disk is a RAMDISK attachment

TNFS

Disk is a remote network drive

The drive may be specified with the wild card *.

180 Disk

SIZE

This option can be used with the CLEAR or SHOW option. When used with the CLEAR option, you must specify the desired directory size immediately following this keyword. >disk a (clear size 200 Ok to erase all files on disk A (Y/N) Y

VERIFY

Tests a disk’s readability by reading every sector on the disk. As each sector is read, its location is displayed and a progress bar is updated to reflect the amount of the disk that has been verified so far. >disk s (verify

Disk caching is bypassed during this test. Any errors detected are displayed on both standard output and standard error devices. Note: The VERIFY option causes the Disk command to first verify that the disk contains a THEOS file system (4GB, LFS, IMG, RAMDISK). If it contains another file system (DOS, FAT32, CDROM, etc.) it reports “IFS disks cannot be opened” and exits without verifing the sectors on the disk.

Disk 181

Commands

>disk a Disk A label "Image". File system = THEOS/IMG. Capacity = 2,097,152 (128 cylinders, 2 heads, 32 sectors). Main directory size = 212 files. Allocated bytes = 15,104. Available bytes = 2,082,048.

Format Options

BOOT

Copies the file /THEOS/OS/LOADER1.SYS to sectors 0–3. Refer to in Appendix D: “System Files” in the THEOS Corona Version 5 Operating System Reference for a description.

CYLINDERS Specifies the number of cylinders or tracks per surface on the disk. The number is specified following the CYLINDERS keyword. Refer to “Formatting Disks” on page 186 for recommenda-

Commands

tions on the number cylinders. DENSITY

Specifies the density of each sector on the disk and whether or not the disk is removable or fixed. The code is specified immediately following the DENSITY keyword. Removable

Fixed

1 2

Meaning 128 bytes per sector, all surfaces.

10

256 bytes per sector, all surfaces.

3

Cylinder 0: 128 bytes per sector; remainder is 256 bytes per sector.

4

Cylinder 0, head 0: 128 bytes per sector; remainder is 256, 512 or 1024 bytes per sector.

7

13

2048 bytes per sector, all surfaces.

14

1024 bytes per sector, all surfaces.

15

512 bytes per sector, all surfaces. (IBM PC format)

Table 3: Disk Density Format Codes

Note: Only code 7 and 15 are used by standard THEOS disks. HEADS

Number of heads or recordable surfaces on the disk. Refer to “Formatting Disks” on page 186 for recommendations on the number of heads to use.

INCREMENT

Specifies the relationship between physical and logical sectors in each cylinder. An increment value of 1 indicates that sectors are accessed consecutively (1,2,3,4, etc.); a value of 2 means every other sector is read (1,3,5,7, ... 2,4,6,8, etc.); and so on. The increment value need only be specified on some older technology drives. Most newer drives use “on-board logic” that automatically sets the increment or interleave values.

182 Disk

LABEL

Specifies the disk volume label for the newly formatted or built disk. The new label can either be specified on the command line by following the LABEL keyword with an equal sign and the new label or, when this is not done, you are asked for the new label after the disk is formatted or built.

This is a default option whenever a disk is formatted or built. SECTORS

Specifies the number of sectors on each track. Refer to “Formatting Disks” on page 186 for recommendations on the number of sectors to use.

SIZE

Specifies the size of the main directory. This size cannot be changed again without reformatting, building or clearing the disk. For best performance, the size of the main directory should be at least twice as large as the expected needs of the disk. It is not necessary to specify a size when formatting a disk for usage by the TArchive or the Backup because they can recreate the directory.

TRACKS

Synonym to the CYLINDERS option.

Disk 183

Commands

Disk labels may use upper and lowercase letters, digits and the underscore character.

When no drive code or options are specified, the Disk command menu is displayed:

Commands

Disk Menu

Select Drive... Selects the drive that will be used in this next menu selection. Unless this item is used to select a different drive, the default drive of S is used. You cannot clear or format the system disk. Test Disk Misallocation. Performs a Disk (SHOW on the selected drive and then exits. Refer to the SHOW option description on page 180. Fast Show. Performs a Disk (FAST on the selected drive and then exits. Refer to the FAST option description on page 176. File Map. Performs a Disk (MAP on the selected drive. Refer to the MAP option description on page 178. Account File Map. Performs a Disk (MAP ACCOUNT on the selected drive and then exits. Refer to the ACCOUNT option description on page 175. Free Map. Performs a Disk (FREE on the selected drive and then exits. Refer to the FREE option description on page 177. Fix Misallocations. Performs a Disk (FIX on the selected drive and then exits. Refer to the FIX option description on page 176. Seek to Random Sectors. Performs a Disk (SEEK on the selected drive and then exits. Refer to the SEEK option description on page 179. Surface Analysis. Performs a Disk (VERIFY on the selected drive and then exits. Refer to the VERIFY option description on page 181. Write Boot Strap Program. Performs a Disk (BOOT on the selected drive and then exits. Refer to the BOOT option description on page 182.

184 Disk

Change Drive Label. Performs a Disk (LABEL on the selected drive and then exits. Refer to the LABEL option description on page 177. Clear Main Directory. Performs a Disk (CLEAR on the selected drive and then exits. Refer to the CLEAR option description on page 176. You cannot clear the system disk.

Display Fragmentation. Performs a Disk (FRAGMENT on the selected drive and then exits. Refer to the FRAGMENT option description on page 176. Optimize Directories. Performs a Disk (OPTIMIZE on the selected drive and then exits. Refer to the OPTIMIZE option description on page 179.

Disk 185

Commands

Clean Unused Disk Space. Performs a Disk (CLEAN on the selected drive and then exits. Refer to the CLEAN option description on page 175.

Formatting Disks

Floppy diskettes and removable hard disks can be formatted by using the Disk menu described on page 184 or Mode 4 of the Disk command. Use the Setup Disk to perform initial partitioning and setup of hard disks and Setup Floppy to format floppy diskettes or Setup Disk to format removable hard disks in bulk.

Commands

„ Floppy Disk Drives Before a floppy diskette can be used for the first time by THEOS, it must be formatted or built. A “quick format” or BUILD can be done on an unused, preformatted diskette or a previously formatted diskette. This writes the THEOS/4GB file system information on the disk with an empty directory. Floppy disk drives generally support multiple densities and capacities of diskettes. To format a floppy diskette using command-line options only, you must use the CYLINDERS, INCREMENT and SECTORS options,. Use one of the following sets of values: Cylinders

Heads

Sectors

Capacity

80 80 80 80

2 2 2 2

72 36 30 18

2.88MB 3½" 1.44MB 3½" 1.2MB 3½" 720KB 3½"

Table 4: Floppy Disk Formats

For instance: >disk f (format cylinders 80 head 2 sector 36

If all of these parameters are not specified on the command line, you are asked to select one of the known formats supported by the drive: >disk f (format Code 1 2 3

Cyls 80 80 80

Hds 2 2 2

Sects 36 30 18

Enter format code: 1

186 Disk

Capacity 1.44 MB 3¾" 1.2 MB 3¾" 720 MB 3¾"

In either situation, you are next asked to put the diskette in the drive. Pressing any key other than (Esc) starts the formatting process: Insert diskette to be formatted:(EnterÌ˛) Cylinder: 5 Head: 1 7%

Although space is reserved on the disk for a bootstrap loader (sectors 0–3), it is not written to the disk unless the BOOT option is used. After a diskette is formatted and the THEOS information is written to it, you are asked if you want to format another diskette in the same drive. You must enter a (Y) to format another disk. To terminate formatting, respond with (EnterÌ˛) or an (N). • Quick Formatting Floppy Diskettes To “quick format” a diskette or batch of diskettes, use the Setup Floppy command. A quick format does not format or verify the readability of the disk but merely writes the THEOS-specific information needed to use the disk. This information includes the THEOS disk label sector, root directory and free space map. You can quick format a diskette if it is already formatted. Defaults

The FAST option is the default option when only a drive code is specified.

Cautions

The MULTIUSER option tells the Disk command to not check whether or not other users are logged on or active. It does not prevent those other users from performing operations that change the database that this Disk command might be using. Do not use the MULTIUSER option unless you are sure that any other users logged onto the system are not going to be using the drive that you are modifying.

Disk 187

Commands

After the diskette is formatted, Disk needs a label. This label can be specified on the command line with a LABEL= option. When it is not supplied on the command line, you are asked for the label. After the label is known, the diskette is built by writing the label sector, empty directory and free space map. The size of the directory can be specified on the command line with the SIZE option or, if that is not done, a default size is used.

Restrictions

The Disk command requires a privilege level of four. To CLEAR, FIX, FORMAT or OPTIMIZE a disk, it must be either a privately attached drive or a publicly attached drive with the system in single-user mode or with the MULTIUSER option specified.

Commands

The current system disk (attached as drive S) cannot be formatted. To format that drive you will have to System over to another drive or reboot from another drive. The Disk command cannot show the status of a a file on a CD-ROM disc, nor can it be used on a DOS-formatted disk except to reformat it as a THEOS-formatted disk. See also

188 Disk

Attach, MakeBoot, Setup, System, Tape

Echo Command The Echo command defines a file or device that will be used for subsequent echoing of console displays. Alternately, it echoes the remainder of the command line to the standard output device.

ECHO file

2

ECHO device

3

ECHO

4

ECHO text

Commands

1

file

»

file name with optional path

device

»

name of attached output device such as COM1 or PRT3

text

»

any text that does not look like a file name

Operation

Mode 1—Indicates that file is to be opened to receive console display echoes. To specify a file that has no file type, be sure to use the period terminator after the file name. >echo console.output >echo example.

Console echoing is not enabled with this command. That is done by entry of (Break),(P). Mode 2—Indicates that the output device is to be opened as the file to receive console display echoes. Output devices that may be used include COM1–COM16, PRT1–PRT64 and TAPE1–TAPE4. The specified device must be currently attached. If the device is a public, non-spooled device and it is in use by another user, the Echo command will wait until it is closed by that other user before proceeding. >echo prt12

Console echoing is not enabled with this command. That is done by entry of (Break),(P). Mode 3—Closes any file or device previously specified with Mode 1 or 2 of the Echo command. Any echoing enabled with (Break),(P) is disabled.

Echo 189

Mode 4—Displays text on the console. If console echoing was enabled with Mode 1 or 2 of the Echo command and (Break),(P) has been entered, this text is also echoed to the echo file. >echo The following is for demonstration purposes only The following is for demonstration purposes only

Commands

>echo example example

Make sure that text does not look like a file or device name. Any text that contains two or more words or tokens will not be misinterpreted. If necessary, add a “dummy” token. >echo "" prt1 prt1

Notes

Except for Mode 4, the Echo command does not actually echo anything to a file. After a file or device is defined with the Echo command, you must enter a (Break),(P) to start and stop the echoing process. The Echo command is normally used with I/O redirection or in EXEC programs to add text to a log file. >echo "Begin daily archive" >> activity.log

See also

190 Echo

I/O redirection, described on page 53 in the “Fundamentals” section of the THEOS Corona Version 5 Operating System Reference.

Edit Command The Edit command is a full-screen text file editor.

EDIT

filename

2

EDIT

filename

( option

filename

»

file name with optional path

option

»

NOBACKUP

Operation

Commands

1

This command edits an existing text file or creates a new text file. >edit sample.text Top of file "/SAMPLE.TEXT:S". End of file "/SAMPLE.TEXT:S". >edit _chdir.msg Top of file "/THEOS/COMMAND/_ChDir.msg:S". Standard THEOS Command directory Contains almost all of the standard, distributed commands. Some commands are in other directories with a .LNK file pointing to it. End of file "/THEOS/COMMAND/_ChDir.msg:S".

Options

NOBACKUP

Notes

WinWrite is a more modern full-screen text file editor and should be used

Does not make a backup file when changes to this file are saved.

instead of this command. Edit Full-Screen Commands

While in full-screen mode, you can type text and use the following keys for editing the text in the file: Command (F1) (ShiftÌñ)+(F1) (F2) (ShiftÌñ)+(F2)

Meaning Search forward Search backward Move to start of next word Move to start of previous word

(F3)

Repeat last find or search

(F4)

Find line starting with specified text

Edit

191

Command (F5)

Erase from cursor to end of line

(F6)

Insert line above current line

(ShiftÌñ)+(F6) Commands

(F7) (ShiftÌñ)+(F7)

Delete current line Change case of character under cursor Transpose

(F8)

Move to start of current line

(ShiftÌñ)+(F8)

Move to end of current line

(F9)

Quit

(F10)

Save and quit

(ShiftÌñ)+(F10)

Save

(Insert)

Toggle between insert and replace character mode

(Delete)

Delete the character under the cursor

(Home)

Move to top of file (Top)

(End) (PageÌUp) (PageÌDown)

Edit Commands

Meaning

Move to end of file (Bottom) Move to and display previous page Move to and display next page

(¤)

Move cursor one character to right

(˜)

Move cursor one character to left

(˚)

Move cursor one line up

(˙)

Move cursor one line down

(Esc)

Change to Command mode

Most of the actions that you can perform in full-screen mode can also be performed in command mode. To switch between the two modes use the (Esc) key. When in command mode you can use the following commands: „ BOTTOM Position cursor after the end of the file.

BOTTOM

192 Edit

„ CHANGE Change text in the file. The syntax is:

CHANGE

2

CHANGE

/from/to

3

CHANGE

/from/to/lines

4

CHANGE

/from/to/lines occurrences

5

CHANGE

/from/to/lines occurrences start

from

»

Current text

to

»

Desired text to change to

lines

»

Number of lines to operate on

occurrences

»

Number of occurrences in each line

start

»

Number of first occurrence to change

Commands

1

Mode 1—Repeat the last CHANGE command on the text in the current line. Mode 2—Change the first occurrence of from to to in the current line. Mode 3—Change the first occurrence of from to to for each of the next lines number of lines, starting with the current line. Mode 4—Change the first occurrences number of occurrences of from to to for each of the next lines number of lines, starting with the current line. Mode 5—Change the first occurrences number of occurrences of from to to, starting with the start number of occurrence in the line, for each of the next lines number of lines starting with the current line. „ CSI Execute a system or application program and then return to editing the current file.

Edit

193

CSI

command

command

»

Command-line text to execute

Commands

„ DELETE Delete lines from the text file.

1

DELETE

2

DELETE

lines

3

DELETE

/string/

lines

»

Number of lines to delete

string

»

Text to delete down to

Mode 1—Deletes the current line. Mode 2—Delete lines number of lines starting with the current line. Mode 3—Delete each line in the file, starting with the current line, and continuing until a line containing string is found. Does not delete the line containing string. „ DUP Add duplicate lines of the current line.

1

DUP

2

DUP

lines

lines »

Number of times to duplicate current line

Mode 1—Duplicate the current line one time. Mode 2—Duplicate the current line lines number of times. „ FORMAT Reformat or justify the remainder of the current paragraph. 194 Edit

„ GET Get text from another file and add it to this file.

GET

2

GET

filename from

3

GET

filename from to

filename

»

Name of file to get text from

from

»

/string/ line

to

»

/string/ line

string

»

Text to get down to

line

»

Number of lines to get

Commands

1

Mode 1—Get and insert the text in the clipboard into this file at the current line. Text is placed in the clipboard by the PUT command and by copy and paste operations supported by other applications. Mode 2—Get lines of text from the file specified as filename. Get zero or more lines of that file until, but not including, the line specified by from. from specifies a line either by a line number or by identifying the line with a text string that occurs in the line. Mode 3—Get lines of text from the file specified as filename. Get zero or more lines of that file, starting with the line specified by from up to but not including the line specified by to.

Edit

195

„ GOTO Change the current line to a different line in the text file.

Commands

GOTO

line

line

»

Number of line to move to

The cursor and the current line is set to line number line of the text file. If that line is beyond the end of the file the current line is set to the line after the current end of the file. „ LENGTH Reports on the length of the file. For instance: Length = 75 bytes, 8117 free, 3 lines, at line 1:

„ NAME Display or change the name of the text file.

1

NAME

2

NAME

filename

filename »

Mode 1—Displays the current name of the text file. Mode 2—Changes the name of the text file to filename. „ PRINT Print the text file on attached PRINTER1 and exit. „ PRT Synonym to the PRINT command. „ PUT Copy text lines to the clipboard or to a file.

196 Edit

1

PUT

2

PUT

to

3

PUT

filename to »

Name of file to put text to

to

»

/string/ line

Commands

filename

Mode 1—Copy the current line to the clipboard. Mode 2—Copy text to the clipboard starting with the current line and continuing until, but not including, the line specified by to. This replaces any text currently in the clipboard. to specifies a line either by a line number or by identifying the line with a text string that occurs in the line. PUT 3

The above command puts three lines of text to the clipboard. PUT /the/

The above command puts zero or more lines of text to the clipboard, starting with the current line and continuing until the line containing text is found.three lines of text to the clipboard. Mode 3—Copy text to the specified filename, starting with the current line and continuing until the line specified by to is found. These lines replace any text that may be in the file currently. „ PUTD Similar to the PUT command except that the text lines are removed from this file after they are copied to the clipboard or the specified filename.

Edit

197

Commands

1

PUTD

2

PUTD to

3

PUTD filename to

filename

»

Name of file to put text to

to

»

/string/ line

„ QUIT Exit without saving any changes.

QUIT Pressing (F9) is a shortcut to this action. If there have been any changes made to the file you will be asked:

„ TOP Position cursor at the beginning of the file.

TOP „ VIEW Invokes the Script command to display the text file. Restrictions

Only ASCII, stream files can be edited with this command.

See also

LineEdit, Script, WinWrite, Viewer

198 Edit

Eject Command The Eject command ejects the media in a removable disk, disc drive or tape drive, or it ejects a page in a printer.

EJECT

device

device Operation

»

name of tape or CD-ROM device or output device such as PRT3

When device is an attached CD-ROM drive, the drive’s disc tray is opened. When device is an attached tape drive, the tape cartridge is ejected. When device is a removable disk drive, the disk is ejected. When device is an attached printer, a page eject or form-feed is output to that device. When device is not a removable drive but is instead a non-removable drive, the drive is logically unmounted. This means that the information that the operating system has saved about the drive’s format and label is cleared from memory and the current position of the read/write head is “forgotten.”

Cautions

If the device is publicly attached, you may be interfering with the operation of another user’s program.

Notes

The unmount operation that is performed on a non-removable drive can be useful because some operations performed by the system are only performed on the currently mounted drives. This feature of unmounting a drive removes a drive from this selection process.

Restrictions

The removable disk drive, tape or CD-ROM must support software-controlled ejecting.

See also

Mount

Eject 199

Commands

1

Commands

200 Eject

EmailChk Command The EmailChk command checks a folder in a mailbox for unread mail. EMAILCHK

mailbox ( PASSWORD password

2

EMAILCHK

mailbox folder ( PASSWORD password

mailbox

»

name of the mailbox to check

password

»

password for mailbox

folder

»

name of folder in mailbox to check

Operation

Commands

1

Mode 1—The default Inbox folder in mailbox is tested for unread messages. The number of unread messages found in mailbox is returned as the return code of the command. Mode 2—The specified folder in mailbox is tested for unread messages. The number of unread messages found in folder of mailbox is returned as the return code of the command.

Notes

This command does not check for mail on your POP server. The mail messages must have been previously downloaded from the server to this system with the TheoMail command.

Defaults

When a folder is not specified (Mode 1), the standard Inbox folder is used.

Return Codes

Because this command is intended to be used within an application or an EXEC, the CSI return code is the primary means of returning information. A zero or positive return code value indicates that the command was successful and the return code specifies the number of unread messages in the folder for that mailbox. A negative return code value indicates an error was encountered. RC

Restrictions

Meaning

-1

mailbox name is invalid, doesn’t exist or is corrupted.

-2

folder in mailbox does not exist.

-3

THEO+Mail is not installed correctly or not configured.

-4

mailbox name is missing.

-5

mailbox is password-protected.

As indicated by the error return codes, EmailChk can only access mailboxes that exist and are configured properly. EmailChk

201

If mailbox is password-protected, you can only access it if the PASSWORD option is specified on the command line. EmailDel, EmailGet, EmailPut, SendMail, TheoMail

Examples

The following MultiUser BASIC language program segment checks a specific folder in a mailbox for incoming, unread messages.

Commands

See also

1000 1010 1020 1030 1040 1050 1060 1070 1080 1090 1100 1110 1120 1130 1140 1150 1160 1170 1180 1190 1200 1210 1220 1230 1240 ... 1990

202 EmailChk

WHILE 1 ! Repeat forever SYSTEM "EMAILCHK SALES ORDERS" IF CSI.RETURN.CODE<0! Errors? PRINT "Error encountered when checking for mail." PRINT "Return code =";CSI.RETURN.CODE QUIT 1 IFEND IF CSI.RETURN.CODE=0! No messages? SLEEP 10*60! Wait for ten minutes CONTINUE ! Check again IFEND ! At least one message is available. Get and process. SYSTEM "EMAILGET SALES ORDERS" IF CSI.RETURN.CODE<0! Error? PRINT "Error encountered when getting mail." PRINT "Return code =";CSI.RETURN.CODE QUIT 1 IFEND ! Process message file WEND

EmailDel Command The EmailDel command deletes messages from the Inbox folder of a mailbox.

1

EMAILDEL mailbox

( options

»

name of mailbox to be checked

options

»

PASSWORD

Commands

mailbox

Operation

All of the messages marked as read in the Inbox of mailbox are removed. These messages are removed without being moved to the mailbox’s Deleted folder.

Options

The only option for this command is the PASSWORD option. It is used when the mailbox is password-protected. Specify the password after the keyword PASSWORD. >EmailDel mymail ( password "Aardwolf22"

The password should be enclosed within quotation marks to preserve the casemode specified. Restrictions

Example

mailbox must refer to an existing THEO+Mail mailbox and that mailbox must not be currently in use by TheoMail. >EmailDel Sales >EmailDel Orders (Password "PriVatE" >EmailDel General

See also

EmailChk, EmailGet, EmailPut, SendMail, TheoMail

EmailDel 203

Commands

204 EmailDel

EmailGet Command The EmailGet command gets the next unread message from a folder in a mailbox. EMAILGET

mailbox

( options

2

EMAILGET

mailbox folder ( options

mailbox

»

name of mailbox to be checked

folder

»

name of folder in mailbox to check

options

»

ALL

Operation

FN

Commands

1

PASSWORD

Mode 1—The default Inbox folder in mailbox is tested for unread messages and, if there is at least one unread message, that message is converted to a plain text file named mailbox.TEXT. If the message has attachment files associated with it, they are extracted and saved in files named mailbox.ATTACH1 through mailbox.ATTACHn. Additionally, a file is created named mailbox.ATTACH that lists the message’s headers and includes a line for each attachment extracted that shows the original file name of the attachment. The return code is set to the number of attachment files saved. Mode 2—Identical in operation to Mode 1 except that folder is checked instead of the default Inbox.

Options

ALL

Extracts and saves the message with all of the MIME headers for the message. The message saved is the same as if TheoMail was used and its File Menu, Save As “E-mail” menu item was used. When this option is not used, the message is saved with only the standard headers From, To, Cc, Date and Subject.

EmailGet 205

FN

This option specifies the saved message’s file-name. The filetype of a saved message is always TEXT. Attached files also use this file-name. >EmailGet sales (fn george

Commands

The above command saves the message as GEORGE.TEXT. Attachments are saved as GEORGE.ATTACH1, etc. When this option is not used the message is saved with a filename that is the same as the mailbox name. PASSWORD

When mailbox is password-protected, this option specifies the password needed to access the mailbox. >EmailGet private (password "Gray49aardWolf"

Because passwords are case-sensitive and may contain spaces, it is always best to enclose it within quotation marks to ensure that it is passed to the EmailGet command as specified. Notes

The message retrieved with this command is marked as read in the mailbox folder. A subsequent EmailGet on the mailbox will get the next unread message in the folder. This command does not get mail from your POP server. The mail messages must have been previously downloaded from the server to this system with the TheoMail program. You can get mail from the POP server without operator attendance by invoking the TheoMail with the command-line argument CHECK: >TheoMail (CHECK

When TheoMail is started with the CHECK option TheoMail ignores the Check for New Mail and Send on Check settings in the mailbox’s configuration and checks for incoming mail one time and then exits. Message filtering may occur on those messages according to the filter rules defined in the mailbox.

206 EmailGet

Attachments

When the unread message contains one or more attached files, those attachments are extracted from the message and saved as separate files with file-types of ATTACHnn where nn indicates the attachment number of the attachment within the message.

For instance, the original message was: From: Fred Flintstone To: Priscilla Date: Thursday, 18 March 2002, 2:08 PM Subject: Example message with attachments ---------------------------------------------------------Attached are two files for your enjoyment. Fred Flintstone <> <>

Assuming that this is the first unread in the “Friends” folder: >EmailGet private friends

gets and saves the message in four files: PRIVATE.TEXT, PRIVATE.ATTACH, PRIVATE.ATTACH1 and PRIVATE.ATTACH2. PRIVATE.TEXT This file contains the text of the message. For instance: From: Fred Flintstone To: Priscilla Date: Thursday, 18 March 2002, 2:08 PM Subject: Example message with attachments --------------------------------------------------Attached are two files for your enjoyment. Fred Flintstone PRIVATE.ATTACH This file contains the message headers and the attach-

ment summary. For instance: From: Fred Flintstone Date: Thu, 18 Mar 2002 14:08:11 -0800 Subject: Example message with attachments Attachment: "archive.test" saved as "PRIVATE.ATTACH1" Attachment: "cleanup.exe" saved as "PRIVATE.ATTACH2"

EmailGet 207

Commands

Also, when there are attachments for the message, an additional file is created named mailbox.ATTACH (or filename.ATTACH if the FN option was used. This file contains the message headers and one line for each attachment file specifying the original attached file name and the saved-as file name.

PRIVATE.ATTACH1 Contains the first attached file from the message.

Commands

PRIVATE.ATTACH2 Contains the second attached file from the message.

Defaults

In Mode 1 the default folder name that is checked for unread mail is Inbox. When the FN option is not used the file-name portion of the saved message and attachments is mailbox.

Return Codes

Because this command is intended to be used within an application or an EXEC, the CSI return code is the primary means of returning information. A zero or positive return code value indicates that the command was successful and the return code specifies the number of attachment files converted. A negative return code value indicates an error was encountered. RC

Restrictions

Meaning

-1

No unread messages in folder of mailbox.

-2

mailbox name is invalid, doesn’t exist or is corrupted.

-3

THEO+Mail is not installed correctly or not configured.

-4

mailbox name is missing.

-5

folder in mailbox does not exist.

-6

Cannot create mailbox.TEXT or one of mailbox.ATTACH1 through mailbox.ATTACHn files (mailbox may be filename if FN option is used).

-7

mailbox is password-protected.

As indicated by the error return codes, EmailGet can only get a message when there is at least one unread message in the indicated folder; can only access mailboxes that exist and are configured properly; and can only access folders in the mailbox that exist and are configured properly. If mailbox is password-protected, you can only access it if the PASSWORD option is specified on the command-line.

Cautions

The message and attachment files saved by this utility may overwrite previous message and attachment files. If the information needs to be saved for any period of time, it should be renamed to an unused file name.

See also

EmailChk, EmailDel, EmailPut, SendMail, TheoMail

208 EmailGet

Example

The following MultiUser BASIC language program segment is the continuation of the example segment used for the EmailChk on page 201. WHILE 1 ! Repeat forever SYSTEM "EMAILCHK SALES ORDERS" ! At least one message is available. Get and process. SYSTEM "EMAILGET SALES ORDERS" IF CSI.RETURN.CODE<0 ! Error? PRINT "Error encountered when getting mail." PRINT "Return code =";CSI.RETURN.CODE QUIT 1 IFEND ! Process message file ATTACH.COUNT% = CSI.RETURN.CODE! Number of attachments OPEN #16: "PRINTER" OUTPUT SEQUENTIAL OPEN #1: "SALES.TEXT" INPUT SEQUENTIAL LINPUT #1: TEXT.LINE$ WHILE NOT EOF(1) PRINT #16: TEXT.LINE$ LINPUT #1: TEXT.LINE$ WEND PRINT #16: CLOSE #1 FOR ATTACH% = 1 TO ATTACH.COUNT% PRINT #16: "Attached file: ";CRT$("EOL"); PRINT #16: "SALES.ATTACH"&STR$(ATTACH%);CRT$("EOS") NEXT CLOSE #16 WEND

EmailGet 209

Commands

1000 1010 ... 1140 1150 1160 1170 1180 1190 1200 1210 1220 1230 1240 1250 1260 1270 1280 1290 1300 1310 1320 1330 1340 1350 1360 1370 1380 1390 1400 1410 1420 1430 1440 ...

Commands

210 EmailGet

EmailPut Command

1

EMAILPUT

mailbox filename

( options

filename

»

name of file on local system

mailbox

»

name of mailbox to be checked

options

»

ATTACH BCC

CC FROM

PASSWORD REPLYTO

SUBJECT TO

Operation

filename is added to the Outbox folder in mailbox.

Options

ATTACH file Add the file as an attachment to the message. BCC addr

Add the addr as a “Blind Carbon Copy” recipient of the message.

CC addr

Add the addr as a “Carbon Copy” recipient of the message.

FROM addr Use addr as the sender address of this message. PASSWORD pw

When accessing a mailbox that is password-protected, pw is used as the password. pw should be enclosed in quotation marks to ensure that it preserves the case mode of the password.

REPLYTO addr Use addr as the “Reply To” address of this message. The default reply-to is the FROM addr. SUBJECT text TO addr

Use text as the subject line of this message.

Add the addr as the primary recipient of this message.

The command-line options for this command operate identically to the same options available with the SendMail command described on page 529.

EmailPut

211

Commands

The EmailPut command is a utility program that operates similar to the SendMail but, instead of sending the message to the SMTP server, merely places it in a mailbox’s Outbox folder. The message is ready to be sent the next time that that mailbox is used for sending messages. This program is designed with a simple, command-line interface suitable for usage as a tool in application programs. For a mail client with a more user-friendly interface, use the TheoMail command described on page 143.

Embedded Mail Headers

The filename may contain embedded mail headers. Refer to the SendMail command description of Embedded Mail Headers on page 533.

Commands

Including Text Files

The filename may also contain “boilerplate” text file inclusions. Refer to the SendMail command description of Including Text Files on page 535.

Notes

Enclose the option arguments within quotation marks. Although not required, without quotation marks the arguments will be folded to uppercase and embedded commas or spaces will terminate the argument. When there are more than 50 addresses in the To, Cc and Bcc fields (command-line options or in the embedded addressing fields), multiple copies of the message are sent, 50 addresses per message.

SendMail Command Restrictions

mailbox must refer to an existing THEO+Mail mailbox and that mailbox must not be currently in use by TheoMail. The file name specified for the message text file, and any %include files, must refer to ASCII text files. These files, and the optional attachment files, must be accessible from the current account. The file name specifications may include the path specification. Every message must have a To field and a From field specified with command-line options or embedded headers.

See also Example

EmailChk, EmailDel, EmailGet, SendMail, TheoMail >EmailPut mymail message.one >EmailPut mymail message.two ... >TheoMail mymail (send

212 EmailPut

Encrypt Command The Encrypt command encrypts a sequential file using public key/private key Data Encryption Standard (DES) 56-bit or 128-bit encryption algorithms.

ENCRYPT source destination ( option password

2

ENCRYPT source ( option password > destination

3

ENCRYPT ( option password < source > destination

Commands

1

source

»

name of file to decrypt or encrypt

destination

»

name to use for resulting decrypted or encrypted file

password

»

private key password, case-sensitive

option

»

algorithm to use for encryption: DES DES56

DES128 TDES

Operation

Using the public key built into the Encrypt command and the private key password specified, the source file is encrypted using the requested algorithm and the result is output to the destination file. The source file must be a stream or sequential organization file.

Options

DES

Use the 56-bit DES encryption algorithm

DES56

Use the 56-bit DES encryption algorithm

DES128

Use the 128-bit DES encryption algorithm

TDES

Use the 128-bit DES encryption algorithm

Notes

Data Encryption Standard (DES) originated at IBM in 1977 and was adopted by the U.S. Department of Defense. It is specified in the American National Standards Institute X3.92 and X3.106 standards and in the Federal FIPS 46 and 81 standards. DES is a widely-used method of data encryption that uses a public key and a private or secret key. With 56-bit DES encryption, there are 72×1015 (72 quadrillion) or more possible encryption keys that can be used. Like other private-key encryption methods, both the sender and the receiver must know and use the same private key. DES was once judged so difficult to break by the U.S. government that it was restricted for exportation to other countries. Most

Encrypt

213

Commands

of these restrictions have been lifted, partly because it has been proven that the encryption can be broken using “brute force” techniques. Still, the security it provides is more than sufficient for all but the most sensitive data privacy needs. 128-bit encryption provides much better security but it can also be broken given sufficient time. Because the password is case-sensitive and the CSI normally folds the arguments to uppercase, it is best to always enclose the password in quotation marks to ensure that it is passed to the Encrypt or Decrypt command properly. Filters

The Encrypt command can operate as a filters or pipes. When not specified, the destination file is stdout. This can be redirected to a file or another program. ENCRYPT

source ( password

The above command will encrypt the source file and output it to the screen. ENCRYPT

source (

TDES

password1 |

ENCRYPT ( TDES

password2 > dest

This command encrypts the source file using password1 with 128-bit encryption, pipes the result to the Encrypt command again to re-encrypt the encrypted file using password2 and 128-bit encryption. The result is saved in dest. Defaults

When encrypting a file, if the algorithm is not specified then DES 56-bit encryption is used.

Cautions

The private-key password is not embedded in the encrypted file. If a different key is used to decrypt the file the Decrypt command cannot report the error and will merely generate a destination file that is not a properly decrypted form of the original file. Remember your passwords but do not write them down for security reasons.

Restrictions

Only stream or sequential files can be encrypted.

See also

Decrypt, FileManager, WinWrite

214 Encrypt

Erase Command This command erases one or more files from disk.

ERASE

file ( options

2

ERASE

( options

3

ERASE

file ( FILES options

Commands

1

file

»

file name with optional path; may contain wild cards

options

»

CLEAN NOQUERY NOSAVE

Operation

NOTYPE QUERY TYPE

Note: This command does not normally remove files from disk. Instead, it moves the requested files to the recycle bin. You must use the NOSAVE option to remove the file from the disk with this command. Refer to Recycle Bin in the THEOS Corona Version 5 Operating System Reference manual. Mode 1—Attempts to erase file and displays the result of the attempt. >erase sample.data "SAMPLE.DATA:S" erased. One file erased, 3,840 bytes recovered.

Unless the NOTYPE option is used, a result message is displayed after all files are erased. This shows the number of files erased and the number of bytes recovered due to erasing those files. When file is a subdirectory name, the Erase command will only erase the directory if it contains no files. Use the RmDir command to erase directories that contain files or erase the files first and then erase the directory. Mode 2—Invokes the interactive mode of the Erase command. Because no files are specified on the command line, you are prompted to enter the file descriptions to erase. >erase Enter file name list, terminate with empty line. ?OUTPUT.LOG "OUTPUT.LOG:S" erased. ?SAMPLE.OUTPUT "SAMPLE.OUTPUT:S" erased. ?*.BACKUP

Erase

215

Commands

As illustrated, this interactive mode allows any file specification to be entered, including wild cards. To terminate this mode, enter a blank line. Mode 3—file is an ASCII stream file containing one file description per line. Each file description in file is erased. As each file is erased its file description is displayed (unless the NOTYPE option is specified). When the file description in file contains wild cards, you are queried for permission to erase each file that matches the specifications (unless the NOQUERY option is specified). This mode of the Erase command is convenient when one or more sets of files are repetitively being erased. Merely edit a file containing the file description, such as: >edit daily.erase work.master:s work.history:s work.invoices:s work.ledger.*:s temp*.*:s sort*.*:s /programs/program.backlib.*:s >erase daily.erase (file noquery notype

Options

CLEAN

Specifies that the contents of file are cleaned by writing zeros to every byte of the file. The file is erased after it is cleaned.

NOQUERY

Tells Erase to not ask for confirmation before erasing each file. This is a default option when wild cards are not used. >erase gl.* (noq "GL.MASTER:S" erased. "GL.JOURNAL:S" erased. "GL.HISTORY:S" erased.

To disable this option use the QUERY option.

216 Erase

Causes the files to be erase from the disk at this time. When this option is not specified and the drive is an image drive or hard disk drive, the file is moved to the recycle bin.

NOTYPE

Tells Erase to not display the results of each file erased on the standard output device. The general result message (the “nn files erased, nnn bytes recovered.” message displayed before exiting Erase) is also suppressed with this option. >erase gl.* Ok to erase Ok to erase Ok to erase

(not "GL.MASTER:S" (Yes,No,All) Y "GL.JOURNAL:S" (Yes,No,All) Y "GL.HISTORY:S" (Yes,No,All) Y

To disable this option use the TYPE option. QUERY

Tells Erase to “query” or ask if each file matching the file specifications is to be erased. This is a default option when wild cards are used. To disable this option use the NOQUERY option. >erase *.backup

When the “Ok to erase” question is asked, you may respond with a (Y) for yes, (N) for no or (A) for all. Responding with (A) means yes to this file and all remaining files are erased without being queried. Respond with (Esc)or (C) to cancel the erase operation. TYPE

A default option that tells Erase to display the results of each file erased on the standard output device. This display can be redirected. >erase *.*:s (noquery "/DEVELOPE.EXEC:S" erased. "/GRAPH.SAVE1:S" protected. "/GRAPH.DATA:S" erased. 2 files erased, 15,872 bytes recovered.

To disable this option use the NOTYPE option.

Erase

217

Commands

NOSAVE

Commands

Notes

If file is a “typeless” file description, there is no default library defined and the environment variable FILETYPE is defined, the value of FILETYPE is appended to file to form a complete file description with file-name and filetype. To erase a typeless file you should specify the file description with a period terminator. See “FILETYPE” on page 103 of the THEOS Corona Version 5 Operating System Reference for more information about this environment variable.

Recycle Bin

When the NOSAVE option is not used, all of the files erased by this command are not actually erased. Instead, the file is moved to the recycle bin which is a special, reserved directory on the SYSTEM account. Should the need arise, an erased file can be recovered from this recycle bin by using the UnErase command. However, due to space limitations, files in the recycle bin are not retained forever.

Defaults

QUERY and TYPE are default options.

Restrictions

You may erase files that are owned by the current account if the files are not erase protected. You may erase files owned by another account if they are not erase protected and they do not have shared read or shared write protection enabled. A library cannot be erased if it has any member files. The members must be erased first and then the library may be erased. A subdirectory cannot be erased if it has any member files. The members must be erased first and then the directory may be erased. A file that is currently open by another user may not be erased.

See also

218 Erase

FileManager, Rename , RmDir, UnErase

Exit Command This command exits from the Shell environment or, if you are not using Shell environment, this command logs off of the system.

Operation

The specific operation of this command depends upon your current environment: In a Shell environment: Exits the shell, returning to the prior environment. Not in Shell environment but connected via TWS, NetTerm or Telnet: Logoff the current account and disconnect. Otherwise: Logoff the current account.

Notes

The Shell environment is normally invoked from another environment such as WindoWriter, THEO+COM, etc. When Exit is used in this situation, control returns to the environment in effect before the Shell was invoked.

See also

Logoff, NetTerm, Shell, Telnet

Exit 219

Commands

EXIT

Commands

220 Exit

Expand Command The Expand command extracts and expands a file from a “compression library” created with the Compress command.

EXPAND compress-file

2

EXPAND compress-file destination ( options

3

EXPAND compress-file destination file... ( options

4

EXPAND compress-file destination file ( FILES options

Commands

1

compress-file

»

file name with optional path of the compression library file

destination

»

destination file name with optional path; may contain wild cards; may be a simple drive specification

file

»

file name of compressed file to be expanded, with optional path; may contain wild cards

options

»

NEWFILE NOQUERY NOTYPE

Operation

OLDER OLDFILE PASSWORD

QUERY REPLACE TYPE

date1 date2

Mode 1—When no destination is specified, the Expand command merely displays the contents of the compression library. Mode 2—Each of the compressed files in compress-file is extracted, expanded, and written to destination. destination may be a simple drive code specification, in which case, the files are expanded and written to that drive using their saved path information. >expand programs.cmp s /bmenu.basic:s /func_key.basic:s /menu.basic:s /model.basic:s /paint.basic:s

If the compression library uses the default file-type of .CMP you may omit specifying the file-type in the command line. For instance: >expand programs s

performs the same operation as above.

Expand

221

Mode 3—Each file specified on the command line is extracted from compress-file, expanded and stored on destination. >expand programs s menu.basic paint.basic (replace /menu.basic:s /paint.basic:s

Commands

If the files in compress-file were compressed with the SUBDIR option in effect, you must specify the original path for each file. >expand vertical.programs s /vertical/progs/menu.basic /vertical/progs/menu.basic:s

Mode 4—The files listed in file are extracted from compress-file, expanded and stored on destination. file must be an ASCII stream file containing one file description per line. The SELECTED.FILES and SELECTED.EXEC files created by FileList and the FOUND.EXEC created by Look can be used for this specification file (see “The EXEC and FILES Options” on page 239 of the THEOS Corona Version 5 Operating System Reference.) You may also create the specification file with an editor or application program. For instance, the FileList command is used to create a list of files: >filelist a (10/1/01 10/8/01 exec

A file now exists (SELECTED.FILES:S) that lists all of the files on the A disk that have been changed between 10/01/2001 and 10/08/2001. The following command will expand these files from their compressed form: >expand old.files a selected.exec (files

Options

NEWFILE

A default option that tells Expand to expand files if file does not already exist. Note: If QUERY is used, you are not queried about files if the destination file name already exists. To disable this option use the OLDFILE or the REPLACE options.

NOQUERY

Tells Expand to not ask for confirmation before expanding each file. This is a default option when Mode is used or when wild cards are not used. >expand programs s /bmenu.basic:s /func_key.basic:s /menu.basic:s /model.basic:s /paint.basic:s /phonenbr.basic:s

222 Expand

To disable this option use the QUERY option. NOTYPE

Tells Expand to not display the results of each file compressed and also to suppress the progress bar. Only error messages are displayed on the stderr device. The general result message (the “nn files expanded.” message prior to exiting Expand) is also suppressed with this option. Commands

>expand gl.compress s gl.* (not Ok to replace "/GL.MASTER:S" (Y|N|A|G)? Y Ok to replace "/GL.JOURNAL:S" (Y|N|A|G)? Y Ok to replace "/GL.HISTORY:S" (Y|N|A|G)? Y OLDER

Expands the file to the destination only if the destination file’s last change date is older than the compressed file’s or if the destination file does not exist. The REPLACE option is implied by this option. Note: If QUERY is used, you are not queried about files if the destination file is newer. This option would normally be used when a compression library is created and ported to another system. The OLDER option is used to expand only those files that need to be updated on the second system.

OLDFILE

Indicates that Expand should expand a file only if the destination file name already exists. This is the opposite of the NEWFILE option and implies a REPLACE option. Note: If QUERY is used, you are not queried about files if the destination file name does not exist. Note that only the destination file name is checked. It could be a totally different file. For instance, an existing command program could be replaced by a stream file or indexed file. To disable this option use the NEWFILE option.

PASSWORD

A password is specified following the PASSWORD option keyword. The files are expanded only if they were originally compressed with this password. If a file is compressed with a password and it doesn’t match the password specified with this Expand command or no password is specified with the Expand command, the file is not expand. >compress private.files *.text (notype password aardvark >expand private.files a (replace noq Fatal error: File: "mydata.text:a" was corrupted or incorrect password.

Expand

223

Note the message reports this as a fatal error. That is done because Expand cannot tell if the file really is corrupted or that you merely type the wrong password.

Commands

QUERY

Tells Expand to “query” or ask if each file matching the file specification is to be expanded. This is a default option when wild cards are used. >expand backups i

When the “Ok to expand” question is asked, you may respond with a (Y) for yes, (N) for no, (A) for all or (G) for go. Responding with (A) means yes to this file and all remaining files are included without being queried. Respond with (C) or (Esc) to cancel the expand operation. To disable this option use the NOQUERY option. REPLACE

Allows a file to be expanded even if it already exists on the destination drive. Normally, when the destination file name already exists, Expand will not perform the expand. This option tells Expand that it is okay if it already exists. Unless the NOQUERY option is specified, you are asked if you want to replace each file that exists on the destination. If the destination file does not exist, this option has no effect: The file is created just as if the REPLACE option was not specified. >expand data.compress f *.data (replace noquery /customer.data:f /history.data:f /accounts.data:f

The REPLACE option is implied by both the OLDER and OLDFILE options. However, the OLDFILE option will not copy a file unless the destination file name already exists.

224 Expand

TYPE

>expand programs s (noquery /program.source.bmenu:s /program.source.func_key:s /program.source.menu:s /program.source.model:s /program.source.paint:s /program.source.phonenbr:s

date1

Expands a file only if the file in compress-file has a last change date that is greater than or equal to this date. That is, if the compressed file was changed on or after this date. This option may be used with the date2 option. >compress programs Date 13Jan2002 01Oct2001 20Dec2001 11Nov2001 17Jan2001 25Jun2001

Time 11:29 19:06 14:41 11:53 12:56 14:17

; display compressed files

Size Rate File name 774 32% bmenu.basic 1,339 68% _func_key.basic 2,709 43% menu.basic 1,618 69% model.basic 356 25% paint.basic 6,726 48% phonenbr.basic

>expand programs s (1/1/02 bmenu.basic paint.basic phonenbr.basic

The above command will expand only those files that have been created or changed since January 1, 2002. date2

Expands a file only if the compressed file’s last change date is less than or equal to this date. That is, if the compressed file was changed on or before this date. May only be specified by first specifying the date1 option. >expand programs s (10/15/02 10/30/02

Expand

225

Commands

In combination with the NOTYPE option, this is a tri-state option that tells Compress whether to display the results of each file compression or not. When TYPE and NOTYPE are not specified, Compress displays a progress bar and any error messages but does not display the names of the files being compressed. Specifying TYPE displays the names of the files being compressed. NOTYPE displays only error messages. This display can be redirected.

This command expands only those files that have been created or changed since October 14, 2002, but not any files that were created or changed after October 30, 2002.

Commands

To specify a date2 when you don’t care about date1, use a date of 1/1/86 for the date1 option. This is the earliest date maintained by the THEOS file system. >expand programs s (1/1/86 12/31/00 func_key.basic menu.basic model.basic

Here, since the date1 specification is 1/1/86, all files created or changed prior to January 1, 2001, are expanded. See also

226 Expand

Compress, CopyFile, FileManager, Restore, TArchive, TBackup

File Command The File command analyzes a file and reports on its organization and general function.

FILE

file...

2

FILE

file ( FILES

file Operation

»

Commands

1

file name with optional path

Mode 1—Each file specified on the command line is examined for its organization (program command, stream, indexed, etc.) and its contents (program object, formatted records, program source, etc.). The result of this analysis is output as a message on the standard output device. >file /theos/os/*.* "/THEOS/OS/Message:S" is a subdirectory. "/THEOS/OS/TIMESYNC.SYS:S" is a 32-bit program file. "/THEOS/OS/UPGRADE1:S" is a 32-bit program file. "/THEOS/OS/TEST.O:S" is a 32-bit object file. ...

In addition to using wild card specifications, more than one file may be specified on the command line. >file *.data *.text system.*.* sample.basic "CUSTOMER.DATA:S" is an indexed file with formatted data. ...

Mode 2—The files listed in file are analyzed. file must be an ASCII stream file containing one file description per line. The SELECTED.FILES and SELECTED.EXEC files created by FileList and the FOUND.EXEC created by Look can be used for this specification file (see “The EXEC and FILES Options” on page 239). You may create the file with an editor or application program. For instance, FileList is used to create a list of files to be examined: >filelist *.data:a (exec >filelist a not *.data:a (10/1/01 exec append

A file now exists that lists all of the “data” files and all files that have been changed since 10/01/2001. The following command checks these files for organization and content: >file selected.exec (file

File

227

Notes

If file is a “typeless” file description, there is no default library defined and the environment variable FILETYPE is defined, then the value of FILETYPE is appended to file to form a complete file description with file name and file type. To report on a typeless file you should specify the file description with a period terminator. See “FileType” on page 245 . file may be a subdirectory name.

Commands

The file types recognized by the File command include: File Type

Message Displayed

Library

“filename” is a library.

Directory

“filename” is a subdirectory.

Program

“filename” is a 16-bit real mode program file. “filename” is a 16-bit program file. “filename” is a 32-bit program file.

Data

“filename” is an indexed file with formatted data. “filename” is an indexed file with text data. “filename” is a keyed file with formatted data. “filename” is a keyed file with text data. “filename” is a relative file with formatted data. “filename” is a relative file with text data.

Stream

“filename” is a stream file. “filename” is a stream file with binary data. “filename” is a stream file with textdata. “filename” is an empty file. “filename” is a Printer Class Definition file. “filename” is a Terminal Class Definition file. “filename” is a Keyboard Definition file. “filename” is a MAKE source file.

Program source

“filename” is a 16-bit BASIC source file. “filename” is a 32-bit BASIC source file. “filename” is a C source file. “filename” is an EXEC source file. “filename” is a TINSTALL source file. “filename” is a TINSTALL compiled file.

Program object

“filename” is a 16-bit object file. “filename” is a 32-bit object file.

Script

“filename” is a SCRIPT file.

Other

“filename” is a COMPRESS library file.

LISAM files are reported as indexed files. See also

228 File

FileList, FileManager

FileList Command The FileList command displays a listing of a disk’s directory.

FILELIST

( options

2

FILELIST

file... ( options

3

FILELIST

file1... NOT file2... NOT file3... ( options

4

FILELIST

drive... ( options

Commands

1

drive

»

optional disk drive attachment letter

file

»

optional file name with optional path; may contain wild cards

options

»

ACCOUNT APPEND ASCII CHECKSUM COUNT EXEC FD FILES FN FT

GROWPROTECT SORT5 HIDDENPRTnn SORT6 KEYPUBLIC SORT7 MNSERIAL SORT8 NEWESTSIZE SORT sequence NOTYPESORT1 TYPE OFFSORT2 VERSION OWNER nameSORT3 date1 PRIVLEVSORT4 date2

This command produces a directory listing of files. By default, this directory listing includes the file name description (file-name, file-type, member-name and file-drive), the last date and time that the file was changed, the file organization or type (program, indexed, library, etc.), the physical size of the file on disk and, for data files, the record and key length. By using various options, additional information about the file can be displayed including the checksum for the file, number of records in the file, growth factor, program privilege level, protection and attribute codes for the file and program version number. This directory listing is normally output to the console but it also can be displayed on one of the attached printers, redirected to a file or device or output as an EXEC language program or a data file.

FileList 229

Operation

Mode 1—Displays a directory listing of all “flat files” in the current directory of the current account. A flat file is a file that is not a member of a library.

Commands

>Filelist

If a default library is defined, then a directory listing of that library is produced. >set library system.b3220lib >filelist

230 FileList

Mode 2—Displays a directory listing of the specified file description(s). This is a very powerful mode because, by using wild cards and multiple file specifications, it allows many different operations to be performed. For instance: >filelist *.*.*:s

>filelist *.*

This displays a listing of libraries and non-library files for all drives in the default drive search sequence. No library members are included. >filelist *.*.?*:s

This displays a listing of library member files but not the library itself or any flat files. >filelist *.command *.cmd *.exec *.exc /theos/commands/*.*

The example above displays a listing of all programs, either flat files (file type is COMMAND or CMD), EXEC language flat files (file type is EXEC or EXC) and the commands, execs and link files in the /THEOS/COMMAND directory. Mode 3—This mode is similar to Mode 2 with the added ability to specify that groups of files are excluded from the listing. The directory listing produced includes files that match the file specification before the keyword NOT as long as they don’t match the file specification following the keyword NOT. For instance: >filelist *.*.*:s not system.*.*:s (public

This displays all entries for files on the S drive excluding those files with a file-name of SYSTEM. Each specification of files that are to be excluded from the listing must be preceded by the NOT keyword. >filelist *.command NOT test*.command *.exec NOT test*.exec

Include

Exclude

Include

Exclude

This displays all files with a file type of COMMAND or EXEC excluding those programs with a file name starting with TEST.

FileList 231

Commands

This displays a list of all libraries, library members and files not related to any library (flat files) that are owned by the current directory of the current account on the S drive.

The NOT file specifications exclude files that might match the specifications. For instance, >filelist test.* example.* NOT *.data

Commands

This command only excludes the “*.DATA” files from the “EXAMPLE.*” specification. All files matching “TEST.*” are still included. Also, you may not specify two or more NOT specifications in a row: There must be a normal specification preceding each NOT specification. Mode 4—This is a shorthand method of specifying that you want all files on the specified drive(s) owned by the current account and in the current working directory. The following two commands produce the same results: >filelist s >filelist *.*:s

As with Mode 2 and Mode 3, you can specify multiple drives: >filelist f g

Options

ACCOUNT

The directory listing will include files owned by all accounts if they match the file specifications and the other options. This option requires a privilege level of five. When the output is to the console or a printer, a page break occurs between each account’s files with the account name and number displayed at the top. EXEC and FILES option note: The OWNER option does cause all qualifying files from all accounts to be included. However, the owning account name or number is not output.

232 FileList

APPEND

Used with option EXEC or FILES to append an additional directory listing to the existing SELECTED.EXEC or SELECTED.FILES file. If neither EXEC nor FILES is specified, then EXEC is assumed when the APPEND option is specified.

ASCII

Causes the listing to be sorted according to the ASCII collating sequence. The normal sort order used by FileList is a special alphabetic and numeric sequence that orders file descriptions using numbers in a more natural sequence. Compare the two sort orders below. The list on the left is the normal order used by FileList; the list on the right is the order produced when the ASCII option is used.

CUSTOMER.ROUTE1 CUSTOMER.ROUTE2 CUSTOMER.ROUTE10 CUSTOMER.ROUTE20 CUSTOMER.ROUTE102

CUSTOMER.ROUTE1 CUSTOMER.ROUTE10 CUSTOMER.ROUTE102 CUSTOMER.ROUTE2 CUSTOMER.ROUTE20

CHECKSUM Compute and display the checksum for each file. A checksum

The checksum value is output in place of the “Recl” and “Keyl” columns. COUNT

Computes and displays the record count for data files (stream, indexed, keyed and relative). This record count information replaces the “Recl” and “Keyl” columns on the right side of a normal directory listing. Files other than data files are not analyzed and there is no count information displayed for them.

EXEC

Indicates that the directory listing is to be output as an EXEC language program in the file SELECTED.EXEC. See “The EXEC and FILES Options” on page 239 for a description of the SELECTED.EXEC file produced with this option and some of its uses.

FD

Used with option EXEC or FILES to indicate that the output includes only the file name, file type, member name and file drive code information for each file. Note: Member names are only included if the file specification indicates that library members are included in the directory listing.

FILES

Indicates that the directory listing is to be output to SELECTED.FILES. See “The EXEC and FILES Options” on page 239 for a description of the SELECTED.FILES file produced with this option and some of its uses.

FN

Used with option EXEC or FILES to indicate that the output includes only the file-name information for each file.

FT

Used with option EXEC or FILES to indicate that the output includes only the file-name and file-type information for each file.

GROW

Output the protection codes and growth factor for each file. The GROW and PUBLIC options produce the same results.

FileList 233

Commands

is a 16-bit value computed by adding the values of each byte in a file.

Commands

The protection codes and growth factor are output in place of the “Recl” and “Keyl” columns. HIDDEN

Include “hidden” files if they match file specification and the other options. (Files are marked as hidden with the CHANGE command described on page 65.)

KEY

Each program file matching the file specifications and any other restrictive options is analyzed for its security plug key value and its serial number. These values and the version number and version date are output, replacing the “Org,” “Size,” “Recl” and “Keyl” columns. All files other than programs will have these columns blank.

MN

Used with option EXEC or FILES to indicate that the output includes only the file-name, file-type and member-name information for each file. Note: Member-names are only included if the file specification indicates that library members are included in the directory listing.

NEWEST

Sorts the output by descending date and time and ascending file-name, file-type, member-name and file-drive. Thus, the newest files are listed first. Synonym to the SORT6 option.

NOTYPE

Do not display the directory listing, only the summary line. This option is ignored if the option EXEC or FILES is also specified.

OFF

Used with option EXEC to prepend a “&control off” command as the first line of the SELECTED.EXEC file created.

OWNER

The directory listing includes the files owned by account name. This option requires that you be logged onto the system account and that you have a privilege level of five. Normally, the directory listing is for the current account only. The PUBLIC option includes publicly owned files in addition to the files owned by the current account. The ACCOUNT and OWNER options are the only method of producing a directory listing of files owned by other private accounts.

PRIVLEV

Each program file matching the file specifications and any other restrictive options is analyzed for its privilege level requirements, its version and version date, and its patch level. These values are output, replacing the “Org,” “Size,” “Recl” and “Keyl” columns. All files other than programs will have these columns blank. The PRIVLEV and VERSION options produce the same results.

234 FileList

PROTECT

Output the protection codes and growth factor for each file. The GROW and PROTECT options produce the same results. The protection codes and growth factor are output in place of the “Recl” and “Keyl” columns.

M W R E X W R Owner read protected Owner write protected Execute protected Erase protected Shared access read protect Shared access write protect Modified Protection and attributes not enabled for a file are indicated with a period in that attribute’s position. PRTnn

Indicates that FileList is to print the directory listing on the attached printer number nn. The option keyword PRT may be specified as PRT, PRINT or PRINTER. As a convenience, PRINTER1 may be specified as P.

PUBLIC

Includes files owned by the system account, if they match the file specifications and any other restrictive options.

SERIAL

Analyzes each program file matching the file specifications and any other restrictive options. The serial number and the privilege level, version number and version date are output, replacing the “Org,” “Size,” “Recl” and “Keyl” columns. All files other than programs will have these columns blank.

SIZE

Sets the return code to the total size of the files listed, in kilobytes (K).

SORT1

Sorts the output by file-name, file-type, member-name and drive-code. This is similar to the default sequence produced by FileList. However, there is a difference between SORT1 and the default sort sequence. The default sort sequence always uses linegraphics around the list and between the columns.

FileList 235

Commands

The protection codes displayed use single, position-dependent letters:

Commands

SORT2

Sorts the output by file-drive, file-name, file-type and membername.

SORT3

Sorts the output by file-name, file-type, file-drive and membername.

SORT4

Sorts the output by file-type, file-name, member-name and file-drive.

SORT5

Sorts the output by date, time, file-name, file-type, membername and file-drive. Thus, the oldest files are listed first.

SORT6

Sorts the output by descending date and time and ascending file-name, file-type, member-name and file-drive. Thus, the newest files are listed first.

SORT7

Sorts the output by member-name, file-name, file-type and file-drive.

SORT8

Sorts the output by organization, file-name, file-type, membername and file-drive. The sequence used for sorting organization is: indexed, keyed, relative, stream, 16-bit real mode programs, 16-bit programs, 32-bit programs, subdirectories and libraries last.

SORT sequence Sorts the output by a user-specified sequence. The sequence may be any one of: FD, FN, FT, MN, DATE, SIZE and TYPE. The TYPE sequence refers to the file’s organization code

(stream, indexed, program, etc.) Multiple sort sequences are specified by using multiple SORT options. >filelist s (sort size

The above command lists the files by increasing file sizes. >filelist s (sort ft sort size

This second examples sort the listing by file type and file size.

236 FileList

TYPE

A default option that outputs the directory listing to the console.

VERSION

Each program file matching the file specifications and any other restrictive options is analyzed for its privilege level requirements, its version and version date, and its patch level. These values are output, replacing the “Org,” “Size,” “Recl” and “Keyl” columns. All files other than programs will have these columns blank.

The PRIVLEV and VERSION options produce the same results. date1

Includes a file only if the file’s last change date is greater than or equal to this date. That is, if the file was changed on or after this date. This option may be used with the date2 option.

The above command will include only those files that have been created or changed since October 14, 2001. Note: Dates are specified according to the currently set date format. Refer to “Sysgen” on page 591 and “Set” on page 541. date2

Includes a file only if the file’s last change date is less than or equal to this date. That is, if the file was changed on or before this date. May only be specified by first specifying the date1 option. >filelist *.*:s(10/15/01 10/30/01

This command includes only those files that have been created or changed since October 14, 2001, but not any files that were created or changed after October 30, 2001. To specify a date2 when you don’t care about date1, use a date of 1/1/86 for the date1 option. This is the earliest date maintained by the THEOS file system. >filelist *.*:s (1/1/86 11/20/2001

Here, since the date1 specification is 1/1/86, only files created or changed prior to November 21, 2001, are included.

FileList 237

Commands

>filelist *.*:s (10/15/01

Commands

FileList Columns

When the output of FileList is redirected to a file, the information can be extracted by a program reading the file. Use the following column numbers for each of the fields. Heading

Meaning

Col

Filename

The file-name, file-type and member-name are concatenated to form a single file name.

1-28

Date

Date file was created or last changed.

31-40

Time

Time file was created or last changed.

42-46

The following columns are not displayed when option PRIVLEV or VER-

SION is used. Org.

Type of file: program, library, etc.

48-49

Protect

Protection codes and attributes for file.

51-57

Size

Size of file in bytes. This field is right-justified with spaces on the left.

59-76

The following columns are displayed only when option VERSION or PRIVLEV is used. P

Privilege level of program.

Vers

Version number of program.

50-55

V-date

Version date of program.

57-63

48

Patch Level

The following column is displayed only when the option KEY or SERIAL is used. Serial

Program serial number.

65-69

The following column is displayed only when the option KEY is used. Key

Program security plug key.

75-81

The following column is displayed only when the option CHECKSUM is used. Checksum

File’s checksum.

The columns Keyl, Recl and Gr are not output to a redirected file.

238 FileList

71-76

The EXEC and FILES Options

When the option APPEND, EXEC or FILES is used, the directory listing is written to a disk file, either SELECTED.EXEC or SELECTED.FILES. When these files are created with the FileList command, several options may have no meaning and will be ignored while several others can be used. The options that can be used are: FD, FN, FT, MN and OFF. These options limit the amount of file description information included in the file.

Option APPEND and EXEC create a special file named SELECTED.EXEC. This file contains only the file description information with command line variables added. For instance: >filelist *.* (exec >list selected.exec &1 BACCESS.C:S &2 &3 &4 &5 &6 &7 &8 &9 &10 &1 BACCESS.O:S &2 &3 &4 &5 &6 &7 &8 &9 &10 &1 BJ.BASIC:S &2 &3 &4 &5 &6 &7 &8 &9 &10 &1 BJ.COMMAND:S &2 &3 &4 &5 &6 &7 &8 &9 &10 &1 "BJ.Data file:S" &2 &3 &4 &5 &6 &7 &8 &9 &10 &1 BJ.HELP:S &2 &3 &4 &5 &6 &7 &8 &9 &10 &1 BJ.MENU:S &2 &3 &4 &5 &6 &7 &8 &9 &10 ...

Any information that may be produced by the options CHECKSUM, COUNT, GROW, PRIVLEV, PROTECT and VERSION is suppressed. This file can be a real timesaver because the SELECTED.EXEC file can be used with many other commands that are used to modify or list your files. The FileList’s command selection capability is generally superior to most other commands. For instance, the above file could be used by executing the program: >selected.exec copyfile f >copyfile BACCESS.C:S f >copyfile BACCESS.O:S f >copyfile BJ.BASIC:S f ...

When the SELECTED.EXEC file is executed, each occurrence of the variable &1 is replaced with copyfile, each &2 is replaced with f.

FileList 239

Commands

• SELECTED.EXEC

The same program could be used in another command: >selected.exec change (ne

Commands

>change BACCESS.C:S (ne >change BACCESS.O:S (ne >change BJ.BASIC:S (ne ... >selected.exec erase >erase BACCESS.C:S >erase BACCESS.O:S >erase BJ.BASIC:S ...

Many commands have their own FILES option that allows them to use this SELECTED.EXEC or SELECTED.FILES file as a list of files. The previous usage of the SELECTED.EXEC program that changes the protection codes and then erases the files could have been done with: >change selected.exec (files ne >erase selected.exec (files

The commands that have a FILES option can use a SELECTED.EXEC file because they have programming that ignores the &1, &2, etc. variables in each line and uses only the file name information. • SELECTED.FILES The FILES option creates a special file named SELECTED.FILES that can be used as a data file for an application that needs directory-type information, or as a list of files used by other commands with their own FILES option. When the FILES option is used with no options or options that do not include FD, FN, FT or MN, the SELECTED.FILES is created containing all of the information requested in the same format as a displayed or printed listing (without line graphics): >filelist *.* (file >list selected.files Bj:S Charset.Basic:S Custmnt.O:S disk.image1:S Loan.basic:S ...

240 FileList

01/06/2002 10/24/1994 04/14/2001 01/07/2002 02/07/2001

19:23 04:53 07:57 16:25 17:16

SD S S S S

....... .W..X.. .WR.... ....... .WR....

14336 4062 157186 1048576 21194

An application can use this file by opening it and reading each record. Use the column information shown in “FileList Columns” on page 238. When any of the options FD, FN, FT or MN is used, the file name information is output as a packed file description: >filelist s (files fd

Commands

>list selected.files BACCESS.C:S BACCESS.O:S BJ.BASIC:S ...

This file can be used by other commands with their FILES option in the same way that the SELECTED.EXEC file was used in its example. For instance: >change selected.files (files ne >erase selected.files (files

Notes

Although the FileList command may be abbreviated to the single letter “f,” it must not be abbreviated to four characters because File is the full name of a different command. If file is a typeless file description and there is a default library defined, then file is assumed to be a member of the default library: file may be a subdirectory name. If the environment variable LINEGRAPH is defined and it equals N, then the directory listing is not outlined with line-graphics characters. For multiple-page displays, the standard page browsing keys are recognized. Refer to “Multiple-page Display Browsing” on page 79of the THEOS Corona Version 5 Operating System Reference. When the display is terminated early with the Quit key ( (Break),(Q) ), the summary line is displayed.

Defaults

TYPE is the only default option.

Return Codes

When option SIZE is used, the return code is set to the total size of the files listed, in number of kilobytes.

Restrictions

Options ACCOUNT and OWNER require a privilege level of five. The ACCOUNT option also requires that you be logged onto the SYSTEM account.

See also

ChDir, Disk, File, FileManager, Logon

FileList 241

Commands

242 FileList

FileManager Command The FileManager command allows you to explore and browse file directories. It also allows you to launch a file by merely selecting the file from the displayed list.

FILEMANAGER ( options

2

FILEMANAGER :drive ( options

3

FILEMANAGER directory ( options

drive

»

drive code of an attached drive

directory

»

path to desired directory

options

»

BACKUP FT HIDDEN

Command synonym: Operation

LOWCASE NOBACKUP

Commands

1

NOOBJ NOTYPE

OBJ TYPE

FM

Mode 1—Using the current working directory as a starting point, display the directory listing and begin browsing of that directory. Mode 2—Set the current working directory to the root directory of drive, display the directory listing and allow browsing of that directory. Mode 3—Sets the current working directory to directory and then opens a FileManager view of that directory. >fm /theos/command

FileManager 243

Commands

Options

BACKUP

Include backup files in directory listing.

FT

Include filetype for all files, even if file extension is “known.”

HIDDEN

Include hidden files in directory listing.

LOWCASE Fold all-uppercase file names to mixed case. NOBACKUP

Do not include backup files in directory listing.

NOOBJ

Do not include object files in directory listing.

NOTYPE

Include only filenames and filetypes in directory listing.

OBJ

Include object files in directory listing.

TYPE

Include the size, date, time and type in the directory listing.

Defaults

FileManager users the /THEOS/USERS directory to save and get its configuration. The default actions will depend upon the saved settings for the current user as defined in the account environment variable UserName .

See also

Calendar, Change, ChDir, Cleanup, Compress, Config, CopyFile, Create, CRLF, Decrypt, Disk, Encrypt, Erase, Exit, Expand, FileList, FileType, Find, FTP, Img, List, Logoff, Logon, Look, MkDir, Move, NetTerm, Play, Rename, RmDir, Setup, Shell, Show, ShutDown, TBackup, Touch, Tree, UnZip, Upcase, Viewer, WhereIs, Who, WhoAmI, WinWrite, and the THEOS Corona FileManager User’s

Guide and Reference.

244 FileManager

FileType Command The FileType command converts a THEOS file into an operating system independent form of the file, or it converts it back to a THEOS file.

FILETYPE

file... ( SAVE options

2

FILETYPE

file... ( RESTORE options

file

»

file name with optional path; may contain wild cards

options

»

NOQUERY NOTYPE

QUERY TYPE

This command converts THEOS-specific files into “THEOS File Save” format files (TFS) that are portable between operating systems. Although the contents of a TFS file may not be usable on another operating system, they can be copied and transmitted without any problems. Thus, a TFS file is useful when a THEOS file must be sent to another THEOS computer via an intermediate system such as a bulletin board system (BBS), network file server or non-THEOS FTP server. The THEOS File Save format is a file that contains the original THEOS directory entry for the file along with the binary contents of the file. This is a stream file format that is recognized and supported by all operating systems. Operation

Mode 1—Converts a THEOS file into a THEOS File Save file. The SAVE keyword does not have to be specified because it is the default. The converted file uses the same file-name as the original file and a file-type of TFS. If the original file was a member of a library, the output file-name is the original file’s member-name. >filetype sample.file "SAMPLE.FILE:S" copied to "SAMPLE.TFS:S". One file copied. >filetype data.lib.customer "DATA.LIB.CUSTOMER:S" copied to "CUSTOMER.TFS:S". One file copied.

The file-type of file may not be TFS nor may it be a simple wildcard of *. Mode 2—Converts a THEOS File Save file back to the original THEOS file.

FileType 245

Commands

1

Options

NOQUERY

Tells FileType to not ask for confirmation before converting each file. This is a default option when wild cards are not used.

Commands

>filetype *.data (noq "INDEXED.DATA:S" copied to "INDEXED.TFS:S". "DIRECT.DATA:S" copied to "DIRECT.TFS:S". "KEYED.DATA:S" copied to "KEYED.TFS:S". "DATA.DATA:S" copied to "DATA.TFS:S". 4 files copied.

To disable this option use the QUERY option. NOTYPE

Tells FileType to not display the results of each file converted on the standard output device. The general result message (the “nn files copied.” message before exiting FileType) is also suppressed with this option. >filetype *.data f (not Ok to copy "INDEXED.DATA:S" (Yes,No,All) Y Ok to copy "DIRECT.DATA:S" (Yes,No,All) Y Ok to copy "KEYED.DATA:S" (Yes,No,All) Y Ok to copy "DATA.DATA:S" (Yes,No,All) Y

To disable this option use the TYPE option. QUERY

Tells FileType to “query” or ask if each file matching the file specifications is to be converted. This is a default option when wild cards are used. >filetype *.data Ok to copy "INDEXED.DATA:S" (Yes,No,All)

When the “Ok to copy” question is asked you may respond with a (Y) for yes, (N) for no or (A) for all. Responding with (A) means yes to this file and all remaining files are then copied without being queried. Respond with (Esc) to cancel the conversion operation. This option is disabled with the NOQUERY option. TYPE

A default option that tells FileType to display the results of each file copied on the standard output device. This display can be redirected. This option is disabled with the NOTYPE option.

Defaults

Mode 1 is the default.

Restrictions

file may not specify a file-type of TFS nor may the file-type use a wildcard.

See also

Compress, CopyFile (EXPORT option), Expand, Receive , Send, THEO+COM

246 FileType

Find Command The Find command searches a directory path and locates files.

FIND file... ( options »

file name with optional path; may contain wild cards

options

»

APPEND EXEC PRTnn SORT

Operation

Commands

file

SUBDIR

date1 date2

The current working directory, or the path specified in file, and all directories subordinate to it, are searched. All files matching the file specification are output to the standard output device. >tree / data misc doc programs package doc programs vertical doc files programs programs

Any Find command executed in this example will search all of the subdirectories shown above for any and all files specified on the command line. In the following command these directories are searched for any work files: >find *.work* /vertical/checkreg.work0:s /vertical/checkreg.work1:s /data/routeb.workfile:s

Find

247

In the next command, the directories are searched for all backup files, with the list of files piped to the Erase command.

Commands

>find *.backlib*.* *.backup | erase "/VERTICAL/CUSTOMER.BACKLIB.LETR0004:S" erased. "/VERTICAL/CUSTOMER.BACKLIB.LETR0007:S" erased. "/VERTICAL/LISTS.BACKLIB.LETR0001:S" erased. "/VERTICAL/LISTS.BACKLIB.LETR0002:S" erased. "/VERTICAL/PROGRAMS/ABC.BACKLIB.MAKEFILE:S" erased. "/VERTICAL/PROGRAMS/ABC.BACKLIB.XFER:S" erased. "/VERTICAL/PROGRAMS/ABC.BACKLIB.STATUS:S" erased. "/PACKAGE/PROGRAMS/PACKAGE.BACKLIB.MENU:S" erased. "/PACKAGE/PROGRAMS/PACKAGE.BACKLIB.CHECKREG:S" erased. "/VERTICAL/LIBS.BACKUP:S" erased. "/VERTICAL/DOC/FILES/CUSTOMER.BACKUP:S" erased. 11 files erased, 53,504 bytes recovered.

Options

APPEND

Similar to the EXEC option except, if there is a SELECTED.EXEC:S prior to invoking Find, it is appended to without clearing any prior contents.

EXEC

The names of any files matching the requested specifications are output to the SELECTED.EXEC:S. This file is first erased so that, if there are no files found that match the specifications, the file does not exist. The format of each record added to this file is; &1 file-description &2 &3 &4 &5 &6 &7 &8 &9 &10

PRTnn

Indicates that Find is to print the list of files on the attached printer number nn. The option keyword PRT may be specified as PRT, PRINT or PRINTER. As a convenience, PRINTER1 may be specified as P.

SORT

Sorts the list before outputting it. This option cannot be used when the SUBDIR option is used. Compare the two lists produced with and without the SORT option. >find *.work* /vertical/checkreg.work0:s /vertical/checkreg.work1:s /data/routeb.sortfile:s >find *.work* (sort /data/routeb.sortfile:s /vertical/checkreg.work0:s /vertical/checkreg.work1:s

248 Find

When the SORT option is used the lines are sorted in alphabetical order, including any path specification. SUBDIR

>find *.*.*:s (subdir | erase (notype

For each subdirectory of the current working directory, the above command erases all of the members of all libraries in the subdirectory. Then the libraries themselves and all flat files in the subdirectory is erased. It then erases each of the subdirectories and any other flat files in the current working directory. SUBDIR cannot be used when SORT is specified.

date1

Includes a file only if the file’s last change date is greater than or equal to this date. That is, if the file was changed on or after this date. This option may be used with the date2 option. >find *.*:s (10/15/01

The above command will include only those files that have been created or changed since October 14, 2001. date2

Includes a file only if the file’s last change date is less than or equal to this date. That is, if the file was changed on or before this date. May only be specified by first specifying date1. >find *.*:s (10/15/01 10/30/01

This command includes only those files that have been created or changed since October 14, 2001, but not any files that were created or changed after October 30, 2001. To specify a date2 when you don’t care about date1, use a date of 1/1/86 for the date1 option. This is the earliest date maintained by the THEOS file system. >find *.*:s (1/1/86 11/20/01

Here, since the date1 specification is 1/1/86, only files created or changed prior to November 21, 2001, are included.

Find

249

Commands

Includes the names of all subdirectories searched. The subdirectory names are output after a subdirectory and all subordinate directories to this directory are searched. This option is particularly useful when you want to remove a branch of a directory tree:

The SUBDIR and SORT options cannot both be specified.

See also

ChDir, FileManager, FileList, Tree, WhereIs

Commands

Restrictions

250 Find

Finger Client The Finger client queries a server for the status of a specific account or for other information about accounts on a server. FINGER user-name@server

2

FINGER @server

server

»

server name or IP address

user-name

»

user account name

Commands

1

The Finger client is mainly used to determine if an account name is valid. Depending upon the Finger server at the site, it may also be used to determine if a particular account has picked up their mail recently. Operation

Mode 1—Requests information about user-name on server. The specific information returned is determined by the finger server. >finger [email protected] Querying user "acavallo" at host "pacifier.com". Login: acavallo Directory: /admin/acavallo Never logged in. No Mail. No Plan.

Name: Allen Cavallo Shell: /usr/local/bin/tcsh

Mode 2—Requests information about all users logged onto server. Many finger servers do not support this request. >finger @theos-software.com Querying user "" at host "theos-software.com". Finger online user list request denied. >finger @ccnet.com Querying user "" at host "ccnet.com". Login root texas ...

Name Operator Verio Customer Care

TTY Idle When co 10 Tue 09:54 p0 Tue 16:01

Where oz.onramp.net

Finger

251

>finger @netcom.com Querying user "" at host "netcom.com".

Commands

User Real Name abenamer Allan Benamer acapela Michael H. Collier aci ... 715 active login sessions.

Notes

Idle 1:43 0:59

TTY Host Console Location r9 netcom (unknown-8-127.ju) p6 netcom21 (uswgco2.uswest.c) pe netcom (aci.vip.best.com)

Specifying a name before the “@” of the server name specifies a particular user on the server. This name is almost always the same as the person's e-mail address. However, for the Finger client to work, the site “fingered” must be running a finger server that accepts the command and responds with the relevant information. Having an e-mail address does not guarantee that Finger will produce any results. The information displayed by this Finger Client is dependent upon, and provided by, the Finger Server specified. For instance, one Finger server might respond with a simple notification that the user has new mail. Another server might respond with lots of information, some of it might actually be useful. As an example, compare the following Finger displays: >finger [email protected] Querying user "president" at host "whitehouse.gov". Finger service for arbitrary addresses on whitehouse.gov is not supported. If you wish to send electronic mail, valid addresses are "[email protected]", and "[email protected]". >finger [email protected] Querying user "me" at host "myisp.com". Login: me Name: My Name Directory: /home/c/me Shell: /bin/tcsh Mail forwarded to: Someone Else New Mail received Wed Nov 26 10:15 2001 (PST) Unread since Wed Nov 26 10:00 2001 (PST) No Plan You have new mail. >finger [email protected] Querying user "support" at host "theos-software.com". User Id: support

Name: THEOS Support

The first response from the server at whitehouse.gov doesn’t provide any information about the specific account. Instead, it responds with a text message. The second response from myisp.com provides almost complete information while the last response from theos-software.com provides minimal information sufficient to confirm that the account name exists and includes a more descriptive name for the user at that account.

252 Finger

„ Server Specification Specification of the server for Mode 1 or Mode 2 may be accomplished by specifying: The dotted IP address for the server. >finger @207.21.75.100

>finger @my-company

Or the domain name as defined by the Domain Name Service specified in Setup Net Name Services. >finger @theos-software.com

For instance, your company might be registered with Internic (http://www.internic.net/) with a domain name of my-company.com, with an IP address of 172.20.2.1. If you have specified a host name of “HEADQUARTERS” in the host names database with that IP address, you can specify your company’s site as: 172.20.2.1 headquarters my-company.com Domain names and host names are case-insensitive.

Finger

253

Commands

The host name as defined in the file /THEOS/CONFIG/HOSTS.TXT:S. This file can be maintained by you with WinWrite or Setup Net Name Services.

Commands

254 Finger

Force Command This command attempts to force another logged-on user to cancel the command that they are executing and to optionally execute another command or EXEC program.

FORCE

username command

2

FORCE

process command

3

FORCE

user command ( NOQUERY

4

FORCE

-nq user command

command

»

an optional command line

process

»

process id number

user

»

process or username

username

»

account name that other user is logged onto

Operation

Commands

1

Mode 1—Starting with process number one, all logged-on users are examined. The first user found to be logged onto the account username is forced to perform a (Break),(Q) operation and, if that is successful and there is a command specified, that user is forced to execute command. Mode 2—If process number process is logged on it is forced to perform a (Break),(Q) operation and, if that is successful and there is a command specified, the user is forced to execute command. Mode 3—This mode is similar to Mode 1 or Mode 2 except, if the user cannot be forced on the first attempt. The NOQUERY option specifies that Force should not ask if it should try harder but exits after the first attempt. With this mode of the command, if command contains options then the NOQUERY option of the Force command must be specified with a second open parenthesis. >force 5 filelist a (print (noquery

Mode 4—Identical to Mode 3 but the no query feature is specified with the “UNIX style” option. This mode is useful when command contains its own options.

Force 255

The following two commands perform identical functions: >force 5 basic test (print (noquery >force -nq 5 basic test (print

Commands

Notes

It is possible that a user may not be forced with this command. A user’s account environment can be set to ignore (Break),(Q) requests. See “Account” on page 13. Additionally, some programs disable (Break),(Q) during some or all phases of operation (for instance, WindoWriter). If the user’s (Break),(Q) is not being honored at the time that Force attempts to make it abort its operation, Force will not know if the force was successful unless you use specify a command with the Force command. In that situation, the following message is displayed:

Respond with (Y) to have Force try harder by reenabling the other user’s (Break),(Q). If this also fails, Force exits with an error message. Cautions

It is dangerous to force another user if you do not know what that user is doing. Always use the Who or Show USERS command to find out which program the other user is executing before using the Force command. It is always best if the user is at the CSI.

Restrictions

The Force command requires a privilege level of five. You can only Force users or processs that are logged onto an account.

See also

256 Force

Show USERS, Who

FTP Client The FTP command is a File Transfer Protocol client that provides file transfer capabilities over a network between this client and any FTP server available on the network. FTP

( options

2

FTP

host

3

FTP

host user-password

4

FTP

site

5

FTP

filename

Commands

1

( options send-rec-options ( options send-rec-options

( options send-rec-options ( FILE options

filename

»

name of file on local client system containing FTP script

host

»

server server:port

localhost

»

LOCALHOST

options

»

ASCII BINARY

port

»

port number on server for FTP communication (default is 21)

send-rec-options

»

RECEIVE remote-name SEND local-name

server

»

network server name or id (may also be localhost)

site

»

site definition name from FTP configuration file

user-password

»

user name and optional password for user

Operation

NOPROXY PROXY host

VERBOSE

Mode 1—Starts the FTP client in interactive mode. In interactive mode, the FTP Commands described on page 264 are used to connect to a server, log onto an account, change directories, list directories, view, send and receive files, etc. Mode 2—Similar to Mode 1 except that a connection to host is attempted before entering interactive mode. Refer to “Server Specification” on page 260 for a description of server specifications. Because a user name is not specified, “anonymous” is used for the user name. Refer to “User Account Specification” on page 261 for a description of anonymous user accounts.

FTP

257

Mode 3—Similar to Mode 2 except that, after a connection to host is established, you are logged onto user account with password. See “User Account Specification” for information about user accounts on the FTP server.

Commands

Note: The password does not have to be specified on the command line. For security purposes, it is best to not specify it on the command line because it will appear in plain text there. Instead, omit the password. When it is not specified, FTP will prompt you to enter it “silently.” Mode 4—This mode uses a site definition to define the host and other connection parameters. Site definitions are created with the Setup Net FTP Client command. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.) All site definition names are simple names without dots or other punctuation characters. When a simple name is used, as in this mode of the command, the FTP program first checks to see if it matches one of the site definitions. If it does, it uses that site definition to make a connection to the remote server. Mode 2 of the command is assumed when it doesn’t match a site definition. Mode 5—In this mode, the contents of filename are used as a script of commands to the FTP client. This script should contain several of the FTP Commands described on page 264. See “FTP Script File” on page 280. Options

ASCII

This is a default option that specifies that files are transferred as ASCII files. Compare with the BINARY option.

BINARY

Specifies that files are transferred as binary files. In binary mode, no interpretation or conversion is performed on the contents of files transferred.

NOPROXY

If the FTP configuration file (/THEOS/CONFIG/FTP.CFG:S) specifies a default proxy server, this option ignores that specification and connects to the requested server address directly.

PROXY proxy-server Whether or not a proxy server is specified in the FTP

configuration file, proxy-server is used as the proxy server for this FTP session. A default proxy server can be specified in the FTP configuration file (/THEOS/CONFIG/FTP.CFG:S) that is maintained by the Setup Net FTP Client screen. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.) VERBOSE

258 FTP

Enables verbose mode. With verbose mode on, commands sent to and responses received from the remote FTP server are displayed. With verbose mode off, these commands are not displayed.

Send-Receive Options

These two options may only be used when the FTP server name or site name is specified on the command line (Mode 2, Mode 3 or Mode 4). The user-password may also be specified on the command line. RECEIVE remote-name Transfer the file remote-name from the FTP server to the local computer using the current transfer mode (ASCII or BINARY).

SEND local-name Transfer the file local-name from the local computer to the FTP server using the current transfer mode (ASCII or BINARY).

If local-name contains a path specification, a CD command is issued to the FTP server system to change to that directory. All files sent are located in the current working directory of the local computer. local-name may contain wild-card specifications for the file description. Note: FTP servers normally change the file date on received files to their own local date and time, or possibly to UTC time. Notes

This FTP client conforms to the standards proposed in RFC-959. That document can be found on the Internet at the following site: http://www.faqs.org/rfcs/rfc959.html This program accepts all user input from stdin and displays all output on stdout. These can be redirected to disk files or other devices, if desired. Additionally, if invoked by an EXEC program, commands may be entered with the &stack or &begstack commands. As mentioned in the section “Options” on page 258, the remote FTP server may be connected via a proxy server on another system that you can access. For general information about using proxy servers, refer to Appendix D: “Using a Proxy Server,” starting on page 203 of the THEOS Corona Version 5 Operating System Reference.

FTP

259

Commands

If remote-name contains a path specification, a CD command is issued to change to that directory. remote-name may contain wild-card specifications for the file description. All files received from the remote server are received into the current working directory of the local system.

„ Server Specification Specification of the host, for Mode 2 or Mode 3 or with the OPEN commands, may be accomplished by specifying: The dotted IP address for the server. Commands

FTP? open 207.21.75.100

The host name as defined in the file /THEOS/CONFIG/HOSTS.TXT:S. This file can be maintained by you with WinWrite. FTP? open my-company

Or the domain name as defined by the Domain Name Service specified in Setup Net Name Services. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.) FTP? open ftp.theos-software.com

For instance, your company might be registered with Internic (http://www.internic.net/index.html) with a domain name of mycompany.com, with an IP address of 172.20.2.1. If you have specified a host name of “HEADQUARTERS” in the host names database with that IP address, you can specify your company’s FTP site as 172.20.2.1 headquarters my-company.com Domain names and host names are case-insensitive. The host specification may include a port number. When not specified, the default port number of 21 is used for FTP transfers and communication. In some situations, you may need to specify a port other than 21 to access the server. For instance, a host machine may have two FTP servers. In this situation, one of the servers will use port number 21 and the other server will use a different port number. To access this other server you will have to specify the port number used by that server. A similar situation exists when a host machine that has an FTP server and a proxy server. To specify a port number other than 21, use a server name or IP address followed by a colon and the port number for that server.

260 FTP

„ FTP Server Response Messages In the examples used in this chapter, the response text shown for various commands is not necessarily what is displayed for a specific connection to a remote FTP server. The server is responsible for the specific text displayed by the FTP client. Commands

For instance, one server might display: FTP? cd temp CWD command successful FTP? remove test.file DELE command successful

While another server might display: FTP? cd temp Directory changed to "/temp" FTP? remove test.file File "test.file" has been deleted.

Additionally, the command names are shown in lowercase. Command names may be entered in uppercase, lowercase or in mixed case. „ User Account Specification Most FTP servers require that client connections are made only when a valid user account is specified and the password for that account is entered successfully. When connecting to a remote FTP server, the user account determines your home directory, which files you “own,” and what directories you can view, upload and download from. >ftp my-company.com "my-name" "my-private-password" Connecting to my-company.com (172.20.2.1) -------------------------------------------------Welcome to My Company FTP site. MY-NAME logged in. -------------------------------------------------FTP?

Note that, in the above example, the user name and password were specified with enclosing quotes. This was done because some servers use casesensitive name and password verification. Without the enclosing quotes, the Command String Interpreter (CSI) folds all tokens to uppercase before passing the argument to the program. This might cause the user name or password to be invalid.

FTP

261

Commands

>ftp FTP? open headquarters Connecting to my-company.com (172.20.2.1) -------------------------------------------------User-name: my-name Password: (enter my-private-password ) Welcome to My Company FTP site. MY-NAME user logged in. -------------------------------------------------FTP?

As indicated, when the password is requested in interactive mode, it is not displayed on your screen. Most FTP servers allow anonymous connections. An anonymous connection is made by either not specifying a user name, or by specifying the special user name of “anonymous.” When you specify a user name of “anonymous,” you will still be asked for a password. The recommended password for anonymous connections is your e-mail address. For instance, “[email protected].” In fact, some servers may require this style of password. >ftp headquarters ; connect as anonymous user Connecting to my-company.com (172.20.2.1) -------------------------------------------------Welcome to My Company FTP site. Anonymous user logged in. -------------------------------------------------FTP?

or >ftp FTP? open headquarters Connecting to my-company.com (172.20.2.1) -------------------------------------------------User-name: anonymous Password: [email protected] Welcome to My Company FTP site. Anonymous user logged in. -------------------------------------------------FTP?

When connecting as an anonymous user, the password entered is displayed as you type it. When no password is specified by you, the default anonymous password is used. This default password is defined in the FTP configuration file (/THEOS/CONFIG/FTP.CFG:S) that is maintained by the Setup Net FTP Client screen. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.) If the configuration file does not specify the password for anonymous connections, a password of “local-name@yourdomain” or, if your system is not part of a domain, then “accountname@local-name” is used for the password.

262 FTP

Note: Most FTP sites do not allow full access to anonymous users. For instance, they will frequently not allow you to upload files. They may also restrict the directories that you may view or download files from. „ Directory and File Name Specification

The file name specifications for files on the server must be specified in the syntax used by the server’s operating system. For instance, you may use the directory-name shortcuts of “./” and “../” only if the server’s operating system supports it. In most cases, this syntax will be identical to the syntax used by the THEOS operating system. „ Transfers of Non-Stream Files The FTP standard transfers stream files. However, this FTP Client can be used to send a non-stream file, such as a compiled command, indexed, keyed or relative data file, etc. It does this by repackaging the file using the FileType protocol before sending it to the remote server. When the destination is a THEOS-based FTP server, the received stream data is converted back to its original format by the THEOS FTP server. A THEOS FTP server is included in the NetServer or the WebServer Plus Paks. If the destination is not a THEOS-based FTP server, it is saved on the server as a stream file in the FileType format. This file cannot be easily used by systems other than THEOS system, but it can be stored for subsequent retrieval by a THEOS FTP client. When receiving a file from that non-THEOS FTP server, the THEOS FTP client recognizes that the file is a THEOS file in FileType format and converts the file back to its original format before saving it on the local system. Although non-stream files transferred by this client are not usable by any system other than a THEOS-based system, non-THEOS FTP sites can be used for intermediate storage. For instance, a data file could be uploaded to a generic Internet Service Provider (ISP) FTP server and then subsequently downloaded to another THEOS system. When a non-stream file is uploaded with this FTP client, subsequently downloaded by a non-THEOS FTP client and then transferred to a THEOS system (for instance, with the THEOS WorkStation Client), the resulting file will have to be converted with the FileType command before it can be used by THEOS applications.

FTP

263

Commands

Many FTP servers are implemented on systems which use case-sensitive user names, passwords, directory names and file names. Other FTP servers are implemented on systems that may or may not use case-sensitive names. It is always best to specify user names and passwords in the same case as they were given to you and to specify directory names and file names in the same case as displayed by the directory listing on the server.

FTP Commands

The following commands may be used in the interactive mode of the FTP command or they may be added to a text file and then invoked with Mode 5 of the FTP command. When the FTP command is in its interactive mode, it uses a prompt text of FTP? For instance: >ftp

Commands

FTP? verbose Verbose mode ON FTP?

A valid connection with a remote server must be made before most of the commands may be used. The only commands that do not require a connection to a remote FTP server are: BYE, CLOSE, EXIT, HELP, LCD, LMD, LPWD, MODE, OPEN, OS, QUIT, SHELL, TYPE and VERBOSE. Note: Many of the commands described here look like THEOS commands, DOS commands or UNIX commands, but they are not. These are FTP commands and only have the syntax and options as described in the following pages. „ FTP Command Line Editing You may make a mistake or want to change some parameter of the command line as you type it. It is not necessary to cancel the entire command and start over. Use the following FTP editing keys to make changes to the command before pressing (EnterÌ˛).

Edit Key

Control Key

Function

(Home)

(Ctrl)+(G)

Move to the beginning of the command line.

(End)

(Ctrl)+(E)

Move to the end of the command line. Delete the character to the left of the cursor.

(Backspace) (Del)

(Ctrl)+(Z)

Delete the character under the cursor.

(F5)

(Ctrl)+(N)

Delete all characters to end-of-line.

(˜)

(Ctrl)+(H)

Move the cursor left one character position.

(¤)

(Ctrl)+(L)

Move the cursor right one character position.

(Insert)

(Ctrl)+(R)

Toggle between character insert and replace mode. *

(Esc)

(Ctrl)+(”)

Erase the entire command line.

(EnterÌ˛)

(Ctrl)+(M)

Terminate editing and execute the command.

Table 5: FTP Command-Line Edit Keys

264 FTP

APPEND

Transfer a file from the local computer to the remote FTP server, using the current transfer mode (ASCII or BINARY). If the file already exists on the remote server, this file is appended to the end of that existing file. There are two forms of the command:

local-name may contain path specifications, which refer to the location of the file on the local client system. When remotename is not specified, the file is received onto the remote server system into the current working directory (see CHDIR command to change the current working directory on the server system) and has the same file name as local-name. When remote-name is specified, it refers to the destination location and name on the server system. remote-name may contain path specifications, but not wild cards. ASCII

Sets the current file transfer mode to ASCII. This mode should be used for text files only. Any characters that look like lineending characters might be translated into the local system’s line-ending character.

BINARY

Sets the current file transfer mode to binary. All character codes are transferred without translation or interpretation.

BYE

Terminate the current FTP session and exit the FTP client. This command is synonymous with the EXIT and QUIT commands. Use the CLOSE command if you want to terminate the session with the FTP site but remain in the FTP client program.

CD

Synonym to the CHDIR command.

CHDIR

Change the current working directory on the remote FTP server system. FTP? pwd "/" is current directory. FTP? chdir one/two Directory changed to "/one/two" FTP? cd .. Directory changed to "/one"

FTP

265

Commands

APPEND local-name APPEND local-name remote-name

CLOSE

Terminate the current FTP session without exiting from the FTP client. Some servers may display an informational message when you terminate the session. FTP? close Goodbye.

Commands

FTP? DELETE

Erases a file from the remote FTP server. The file name for the file is specified with the command: DELETE filename

filename may contain path and wild-card specifications. FTP? delete myfile.command DELE command successful. FTP? remove myfile.help DELE command successful. FTP? delete temp/myfile.txt DELE command successful. DIR

Display a directory listing for files and directories on the remote server system. The appearance of the listing depends upon the current setting of the VERBOSE mode. When VERBOSE mode is OFF, and the directory information sent by the remote FTP server is in the standard, UNIX format, the information is reformatted before displaying it. Specifically, directory names are either underlined or colored, the file name is moved to the beginning of the line, access permission codes are removed, and the date and time are changed to “dd mon year,” followed by the time in 12-hour form with an “a” or “p” indicator. With VERBOSE mode ON, the directory information is displayed exactly as received from the remote server. This command has three different forms: DIR DIR filename DIR dirname

The first form (DIR) displays the directory listing of the current working directory on the remote FTP server.

266 FTP

FTP? dir accounts files programs

16 May 2001 5:58p 11 Aug 2001 7:29p 29 Jul 2001 11:37a

FTP? v Verbose mode ON

1 owner 1 owner 1 owner

group group group

0 May 16 15:58 accounts 0 Aug 11 19:29 files 0 Jul 29 11:37 programs

The second form (DIR filename) displays the directory entry for filename on the remote FTP server. filename may contain path and wild-card specifications. Only files matching the filename specification are included. FTP? dir files/Config.cmp Config.cmp

336 26 Feb 2001 6:21p

The third form (DIR dirname) displays the directory entry of the dirname directory on the remote FTP server. dirname may contain a path specification. Only the specified dirname is displayed, not the current working directory. FTP? dir programs program1.command program2.command program3.command

89,020 12 Oct 2001 1:15p 113,920 12 Oct 2001 1:20p 77,160 2 Nov 2001 8:12a

See also: LS, SAVEDIR and SAVELS commands. EXIT

Terminate the current FTP session and exit the FTP environment. This command is synonymous with the BYE and QUIT commands.

GET

Synonym to the RECV command.

HELP

Display help information about the FTP commands available. There are two forms of this command: HELP HELP cmd-name

The first form displays all command names and abbreviations available in the FTP client environment.

FTP

267

Commands

FTP? dir d--------d--------d---------

FTP? help Following is a complete list of commands. The command name may be abbreviated. To display help for a specific command, use the syntax: HELP cmd.

Commands

APPEND ASCII ...

CLOSE DELETE

LCD LMD

MODE OPEN

RD RECV

SEND SHELL

The second form displays the specific help text for cmd-name. FTP? h lcd Syntax: LCD (change local directory) LCD

Change the current working directory on the local client system and display the new current working directory. The command name must be followed by the path to the new directory. FTP? lpwd Local directory: (null) FTP? lcd fax Local directory: /FAX:S

Note: When the FTP client exits, your current working directory is restored to the directory in use at the time that FTP was invoked. LDIR

Similar to the DIR command, this command displays a directory listing for files and directories, but on the local system. The appearance of the listing does not depend upon the setting of the VERBOSE mode. This command has two different forms: LDIR LDIR filename

The first form (DLIR) displays the directory listing of the current working directory on the local system.

268 FTP

FTP? lcd tips Local directory: /TIPS:S FTP? ldir aol.tip config.tip ftp.tip ...

1,454 2,950 557

2 Sep 2000 12:06p 12 Nov 2000 2:04p 2 Sep 2000 11:54a

FTP? ldir /data/*.* misc

15 Sep 2001

1:29p

See also: LLS command. LLS

Display the directory listing from the local system for the current working directory, a specific file or group of files. This is similar to the LDIR command but only the file names or directory names are displayed, without any detail about the files or directories. Like the LDIR command, there are two forms of this command: LLS LLS filename

The first form displays the files and directories in the current working directory of the local system. FTP? lls aol.tip config.tip ftp.tip ...

The second form (LLS filename) displays a list of files matching filename, which may contain path specifications or wild cards. See also: LDIR command.

FTP

269

Commands

The second form (LDIR filename) displays the directory entry for filename on the local system. filename may contain path and wild-card specifications. Only files matching the filename specification are included.

LMD

Creates a new directory on the local client system. The new directory name is specified with the command: LMD dirname

Commands

Unless a path is specified with dirname, the new directory is created in the current working directory of the local system (see LPWD). FTP? lmd example FTP? lcd example Local directory: /FAX/EXAMPLE:S LPWD

Display the current working directory of the local client system. FTP? lpwd Local directory: /FAX:S

LS

Display the directory listing from the remote server for the current working directory, a specific file or group of files, or directory other than the current working directory. Unlike the DIR command, the setting of the VERBOSE mode does not affect the information displayed, except for the normal inclusion of reply codes and intermediate messages. Also, only the file names or directory names are displayed, without any detail about the files or directories. Similar to the DIR command, there are three forms of this command: LS LS filename LS dirname

The first form displays the files and directories in the current working directory of the remote server. FTP? ls .login public_html .history mail .pinerc

The second form (LS filename) displays a list of files matching filename, which may contain path specifications or wild cards.

270 FTP

The third form (LS dirname) displays the files in the specified dirname. See also: DIR, SAVEDIR and SAVELS commands. Synonym to the MKDIR command.

MKDIR

Creates a new directory on the remote FTP server. The new directory name is specified with the command: MKDIR dirname

Unless a path is specified with dirname, the new directory will be created in the current working directory (see CHDIR). FTP? ls myip.htm FTP? mkdir example FTP? ls myip.htm example MODE

Display the current file transfer mode (ASCII or BINARY). This command is synonymous with the TYPE command. >ftp (binary FTP? mode Using Binary mode to transfer files.

OPEN

Establish a new FTP session. Any current FTP session is closed. There are five forms of the command: OPEN OPEN OPEN OPEN OPEN

host host user host user password site

Basically, these are all the same command. You are prompted for any information omitted from the command or the site definition. For a description of the host parameter, refer to “Server Specification ” on page 260. For a description of user and password, refer to “User Account Specification” on page 261. Sites are defined in Setup Net FTP Client. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.)

FTP

271

Commands

MD

The user and password cannot be enclosed within quotation marks. Case mode is retained as entered and quotation marks are passed to the server as part of the user name or password. With the first form of the command, you are prompted to enter the server name, user name and password. Commands

FTP? open Host-name: ftp.theos-software.com Connecting to ftp.theos-software.com (207.21.75.100) ------------------------------------------------User-name: anonymous Password: [email protected] Welcome to THEOS Software Corporation FTP site. Anonymous user logged in.

The second form connects to host and then asks you for the user name and password. The third form connects to host and logs on as user; you are prompted for the password. The fourth form supplies all of the information. Note that, with the fourth form, the password is supplied with the command and is visible. The other forms prompt you for the password, which is entered “silently.” FTP? open ftp.somesite.com Connecting to ftp.somesite.com (128.100.1.2) -------------------------------------------User-name: me Password: information messages from ftp server User me logged in.

As described in “User Account Specification”, anonymous connections are made by specifying a user name of “anonymous.” Some servers allow you to use a dash at the start of the password to suppress any information messages. This may not work for all servers. To terminate the connection, use the QUIT or CLOSE command.

272 FTP

OS

This command is synonymous with the SHELL command.

PWD

Display the current working directory of the remote FTP server. Refer to the CHDIR command for example usage.

PUT

Synonym to the SEND command.

QUIT

Terminate the current FTP session and exit the FTP environment. This command is synonymous with the BYE and EXIT commands. FTP? quit Thanks for visiting our site. You were online for 0 minutes.

The actual text displayed after the QUIT command is dependent upon the FTP server. Generally, the message is just “Goodbye.” RD

Synonym to the RMDIR command.

RECV

Transfers one or more files from the remote FTP server to the local system using the current transfer mode (ASCII or BINARY). There are two forms of the command: RECV remote-name RECV remote-name local-name

remote-name may contain a path specification or wild cards. When no path specification is included, only the current working directory on the FTP server is searched for matching files. Because most FTP servers use case-sensitive directory and file names, the remote-name should be specified with the same case mode as used on the server system. The first form of the command (RECV remote-name) saves the file on the local system in the current working directory. Any existing file on the local computer with the same name as remote-name is replaced with the received file. If the file-name or file-type of remote-name is longer than eight characters, it is truncated to the first eight characters of the name or type. FTP? recv *.htm Receiving firstfile.htm (1 of 2) 5,536 bytes received in 2.2 seconds (2.48 Kbytes/sec) Receiving secondfile.htm (2 of 2) 4,536 bytes received in 2.3 seconds (1.98 Kbytes/sec)

The above two files are received as FIRSTFIL.HTM and SECONDFI.HTM, respectively.

FTP

273

Commands

>

FTP? cd .. Directory change to "/" FTP? recv WebPages/firstfile.htm 5,536 bytes received in 2.3 seconds (2.37 Kbytes/sec)

Commands

When the second form of the command is used (RECV remotename local-name), only one file is transferred. Wild cards are not allowed in either file specification. The file is received onto the local system using the location and name specified with local-name. If local-name does not specify a path, the current working directory on the local system is used. Any existing file on the local computer with the same name as local-name is replaced with the received file. FTP? recv firstfile.htm webpage.html 5,536 bytes received in 5.0 seconds (1,117.48 bytes/sec) FTP? recv ../WebPages/firstfile.htm webpage1.html 5,536 bytes received in 2.3 seconds (2.37 Kbytes/sec)

Refer to the notes on “Transfers of Non-Stream Files” on page 263 to information about receiving compiled programs and indexed, keyed or relative data files from a THEOS FTP server. REMOTE

Executes a command on the remote FTP server. The command is specified with this REMOTE command: REMOTE command

For a list of commands available on the server, use the REMOTE HELP command. These remote commands are just

that, commands available on the remote system. They are not part of this FTP client’s command set. FTP? remote help 214-The following commands are recognized (* => umimplemented) ABOR DELE NLST QUIT RNTO ACCT* HELP NOOP REIN SITE* ALLO LIST PASS REST* SIZE APPE MDTM PASV RETR SMNT* CDUP MKD PORT RDM STAT CWD MODE PWD RNFR STOR

STOU STRU SYST TYPE USER XCUP XCWD 214 Direct comments to [email protected]. FTP? remote help stat 214 Syntax: STAT [] (status) FTP? remote stat 211-THEOS FTP Server status: Version 1.0 Connected to 209.95.32.4 Logged in as PRIVATE TYPE: ASCII, FORM: Nonprint; STRUcture: File;

274 FTP

transfer MODE: Stream No data connection 211 End of status.

Responses from the REMOTE command are always displayed with response codes included, independent of the current setting of the VERBOSE mode.

REMOVE

Synonym to the DELETE command.

RENAME

Renames a file on the remote FTP server. There are three forms of this command: RENAME RENAME old-filename RENAME old-filename new-filename

These three forms all operate the same. You are prompted for the old and new file names if they are not specified with the command. Path specifications are allowed but wild cards are not. The old-filename specification must be for a file that does exist and the new-filename specification must be for a file that does not exist. FTP? rename Old-filename: example.fil File exists, ready for destination name New-filename: example.txt File "example.fil" renamed to "example.txt". RMDIR

Removes or erases a directory on the remote FTP server. The directory name is specified with the command: RMDIR dirname

Only directories may be erased with this command. To erase a file, use the DELETE command. The dirname directory must be empty.

FTP

275

Commands

The remote SITE command may have additional, site-specific commands available.

FTP? rmdir temp temp: File exists. FTP? cd temp Directory change to "/temp" FTP? delete myfile.command DELE command successful.

Commands

FTP? cd .. Directory change to "/" FTP? rd temp Directory "temp" removed. SAVEDIR

Similar to the DIR command except that the output is saved in a file. The format of the command is: SAVEDIR filename SAVEDIR filespec filename SAVEDIR dirname filename

The filespec and dirname have the same meanings as the DIR command. They specify which files on the remote system are included in the directory listing. When filespec is omitted, all files in the current working directory are included. filename specifies the name of the file on your system that is used to save this directory listing. This command is principally used when FTP is invoked from an FTP Script File with an application program. SAVELS

Similar to the SAVEDIR command except that the directory listing format used the LS command format. The format of the command is: SAVELS filename SAVELS filespec filename SAVELS dirname filename

SEND

Transfers one or more files from the local system to the remote FTP server using the current transfer mode (ASCII or BINARY). If a file already exists on the remote server system with the same destination name, it is replaced by this transferred file. Use the APPEND command to send a file and append it to an existing file on the remote server. There are two forms of the command: SEND local-name SEND local-name remote-name

276 FTP

In the first form (SEND local-name), the local-name may contain path specifications or wild cards, but not both. When local-name does not include any path specification, the files are located on the local client system in its local current working directory (LPWD). When local-name does include a path specification, the files are located on the local client system using that path specification.

FTP? send path/file.name

is equivalent to: FTP? send path/file.name file.name

If local-name includes wild-card specifications, all files matching the specifications in the local current working directory are sent to the remote server system and saved in its current working directory. In the second form of the command (SEND local-name remotename), both names may include path specifications. However, wild cards are not allowed. The remote-name specifies the specific location and name used to save the file on the remote system. FTP? send *.htm Sending "fileone.htm" 4,536 bytes sent in 0.8 seconds (5.39 Kbytes/sec) Sending "filetwo.htm" 5,536 bytes sent in 0.8 seconds (6.71 Kbytes/sec) FTP? send private/first.file temp/file.one 139 bytes send in 0.6 seconds (227.12 Bytes/sec)

Note: FTP servers normally change the file date on received files to their own local date and time, or possibly to UTC time. Refer to the notes on “Transfers of Non-Stream Files” on page 263 for information about sending compiled programs and indexed, keyed or relative data files.

FTP

277

Commands

The file or files are sent to the remote server and saved in its current working directory (PWD).

SHELL

Use the local system’s CSI SHELL to execute commands on the local system. This command is synonymous with the OS command. There are two forms of the command:

Commands

SHELL SHELL command

In the first form, the CSI SHELL is entered. You can then enter any command, or series of commands, that you want executed on the local system. When you are finished and want to return to the FTP environment, use the special EXIT command. FTP? shell THEOS 32 Command SHELL Type "EXIT" to terminate. >logon data >exit FTP?

When the second form of the command is used, a full-screen window is opened on your display and the requested command is executed. When the command is finished, the window is closed and control returns to the FTP client. FTP? shell logon data

the data account becomes the current account FTP? TYPE

Display the current file transfer mode (ASCII or BINARY). This command is synonymous with the MODE command.

USER

Changes the user account that you are logged into on the remote server. There are three forms of the command: USER USER name USER name password

All three forms perform the same operation. With the first form of the command, you are prompted for the new user name and password. With the second form, the user name is supplied and you are prompted for the password. With the third form, you supply the user name and the password. Note that first two forms allow you to enter the password “silently.” 278 FTP

To connect as an anonymous user, specify a user name of “anonymous.” For more information about user accounts, refer to “User Account Specification” on page 261. FTP? user User-name: myname Password: User MYNAME logged in.

Toggles the verbose mode and displays the new, current mode. With VERBOSE mode OFF, response codes received from the server and intermediate messages are suppressed. With VERBOSE mode ON, these codes and intermediate messages are displayed. FTP? verbose Verbose mode ON FTP? pwd 257 "/e/download/os/" is current directory. FTP? recv ftp.cmp 200 PORT command successful. 150 Opening BINARY mode data connection forftp.cmp(63632 bytes). 226 Transfer complete. 63,632 bytes received in 0.31 seconds (207.27 Kbytes/sec) FTP? v Verbose mode OFF FTP? recv ftp.cmp 63,632 bytes received in 0.31 seconds (207.27 Kbytes/sec)

In addition, the verbose mode affects the display of the DIR command. When VERBOSE mode is OFF, and the directory information sent by the remote FTP server is in the standard, UNIX format, the information is reformatted before displaying it. Specifically, the file name is moved to the beginning of the line, access permission codes are removed, and the date and time are changed to “dd mon year,” followed by the time in 12hour form with an “a” or “p” indicator. With VERBOSE mode ON, the directory information is displayed exactly as received from the remote server. For example:

FTP

279

Commands

VERBOSE

FTP? v Verbose mode OFF FTP? dir Config.cmp FAX.C FTP.CMP

336 26 Feb 2001 6:21p 13,080 30 Jan 2001 5:05p 63,632 16 Jul 2001 12:08p

Commands

FTP? v Verbose mode ON FTP? dir 200 PORT command successful. 150 Opening ASCII mode data connection for -rwxrwxrwx 1 owner group 336 Feb 26 -rwxrwxrwx 1 owner group 13080 Jan 30 -rwxrwxrwx 1 owner group 63632 Jul 16 226 Transfer complete.

VIEW

/bin/ls. 18:21 Config.cmp 17:05 FAX.C 12:08 FTP.CMP

Transfer an ASCII text file from the FTP server computer and displays the transferred file with Viewer. The file name to transfer is specified with the command: VIEW filename Viewer is used because of its windowed display and scrolling capabilities. Also, Viewer can display HTML content.

FTP Script File Mode 5 of the FTP Client command allows you to specify an FTP script file. This script file is used to set up for an FTP session or to perform a complete, unattended file transfer. An FTP script file contains a list of FTP Commands to be executed. For instance: open ftp.theos-software.com anonymous [email protected] binary lcd /downloads cd theos/theos32 recv sp*.zip quit

The above FTP script file would connect to the THEOS Software FTP site and download the latest service pack for the operating system. It is received into the local “downloads” directory. After the file is received, the connection is terminated and the FTP Client is exited.

280 FTP

>ftp example.ftp (file open ftp.theos-software.com anonymous [email protected] Connecting to ftp.theos-software.com (207.21.75.100) -----------------------------------------------------Welcome to THEOS Software Corporation FTP site. Anonymous user logged in. -----------------------------------------------------binary Using Binary mode to transfer files.

Commands

lcd /downloads Local directory: /DOWNLOADS:S cd theos/theos32 CWD command successful. recv sp*.zip Receiving SP40210.ZIP (1 of 1) 477,742 bytes received in 161.8 seconds (2.95 Kbytes/sec) quit Goodbye

Of course, the above simple example could be handled easier with a Mode 3 command: >cd /downloads >ftp ftp.theos-software.com anonymous [email protected] (receive theos/theos32/sp*zip

However, the FTP script file capability does not have to be a single file transfer. For instance, an FTP script that connects to your company’s main office and downloads the current databases could be written as: open headquarters me my-password binary lcd /database cd /master.files/database get *.* cd /private.files/database get *.* cd / lcd / view notices.txt

This script downloads all of the files from two different directories. It resets both the local system and the remote system back to the root directory and then retrieves and displays the contents of the NOTICES.TXT file. Notice that there is no QUIT command at the end. When a script is not terminated with a QUIT or a CLOSE command (or their synonyms), the FTP Client is not exited. Instead, after the last command in the script is executed, interactive mode is entered. At this point you can perform other operations and exit when you desire.

FTP

281

282 FTP

Commands

GetFile Command This command accesses a DOS-formatted disk or partition and copies files from it.

GETFILE

drive ( DIR

2

GETFILE

DOS-file:drive file ( dos-options options

Commands

1

drive

»

THEOS drive letter of DOS disk

file

»

file name with optional path; may contain wild cards

DOS-file

»

file name with optional path; may contain wild cards

options

»

EXEC OWN=nn

dos-options

»

BINARY HIDDEN

QUERY NOQUERY

This command’s function has been replaced with the DOSDiskA and DOSDiskC attachment capability. For information about this capability refer to the “Attaching DOSDiskA Floppy Disk Drives” on page 32. Operation

Mode 1—Accesses the DOS disk in drive and displays the directory of files. >getfile f ( dir MSDOS Path: *.*:F Filename Size Date Time INSTALL.BAT 1 10/25/01 14:36 OEMSETUP.INF 1 10/25/01 14:51 README DIR 10/25/01 14:28 README.EXE 55 10/21/01 9:38

Unless a specific path is indicated, the listing is of the root directory. For instance, to list the files in the README directory you would use: >getfile readme/:f ( dir MSDOS Path: /README/*.*:F Filename Size Date Time DECNET.TXT 4 10/25/01 14:15 ...

Note that the path and file description syntax of the DOS disk may use THEOS conventions or DOS file name syntax. For instance, the following two commands perform identical requests: GetFile 283

>getfile a: (dir >getfile f (dir

Similarly, the following two commands are interpreted identically: >getfile /dos/:f (dir

Commands

>getfile a:\dos\ (dir

Mode 2—Copies one or more files from the DOS disk to the THEOS file. >getfile netware/client.dos/net.cfg:f s (binary "/NETWARE/CLIENT.DOS/NET.CFG:F" copied to "NET.CFG:S". One file copied.

As indicated in the above example, specifying a drive code only for file tells GetFile to use the DOS file name as the destination name. Because the BINARY option was not used, GetFile assumes that the DOS file is a text file and converts CR,LF pairs into CR only. Also, the file transfer is terminated when the end-of-file mark is detected. The DOS-file and drive may be specified with THEOS file name syntax or with DOS file name syntax. For instance, the following two commands copy the same file: >getfile /dos/ansi.sys:f =.=:s (bin "/DOS/ANSI.SYS:F" copied to "ANSI.SYS:S". >getfile a:\dos\ansi.sys =.=:s (bin "/DOS/ANSI.SYS:F" copied to "ANSI.SYS:S".

See notes about “Wild-Card Specifications” on page 286. Options

EXEC

This option tells GetFile to not transfer the files from the DOS disk. Instead, the list of file names found on the DOS disk are output as an EXEC language program in the file SELECTED.EXEC. This file will contain only the file description information with command line variables added. For instance: >getfile readme/*.txt:f (exec >list selected.exec &1 README/DECNET.TXT:F &2 &3 &4 &5 &6 &7 &8 &9 &10 &1 README/IBMLAN.TXT:F &2 &3 &4 &5 &6 &7 &8 &9 &10 &1 README/LANMAN.TXT:F &2 &3 &4 &5 &6 &7 &8 &9 &10 ...

This file can then be edited or used as is. For instance:

284 GetFile

>selected.exec getfile s (dos binary >getfile README/DECNET.TXT:F s (dos binary OWNER=nn Specifies the account number that currently owns the file on

the transmitting THEOS system. NOQUERY Tells GetFile to not ask for confirmation before copying each

>getfile readme/*.txt:f s (noq "/README/LANMAN.TXT:F" copied to "LANMAN.TXT:S". "/README/VINES.TXT:F" copied to "VINES.TXT:S". "/README/PCTCP.TXT:F" copied to "PCTCP.TXT:S". "/README/IBMLAN.TXT:F" copied to "IBMLAN.TXT:S". 4 files copied.

To disable this option use the QUERY option. QUERY

Tells GetFile to “query” or ask if each file matching the file specifications is to be copied. This is a default option when wild cards are used. >getfile readme/*.txt:f s Ok to copy "/README/LANMAN.TXT:F" (Yes,No,All)

When the “Ok to copy” question is asked, you may respond with a (Y) for yes, (N) for no or (A) for all. Responding with (A) means yes to this file and all remaining files are then copied without being queried. Respond with (Esc) to cancel the copy operation. To disable this option use the NOQUERY option. DOS Options

BINARY

Tells GetFile that the DOS file contains binary information and that it should transfer the entire file without any translation. When the BINARY option is not used, GetFile assumes that the DOS file is a text file and converts CR,LF pairs into CR only. Also, the file transfer is terminated when the end-of-file mark is detected. When in doubt as to the type of DOS file it is, always use the BINARY option. The CRLF command can always be used on the file after it has been transferred successfully.

HIDDEN

Includes DOS hidden files from the DOS disk.

GetFile 285

Commands

file. This is a default option when wild cards are not used.

Notes

• Wild-Card Specifications

Commands

Similar to the CopyFile command, the destination file specification may use the equal sign character ( = ) to indicate that the destination file description uses the corresponding element of the source file description. An equal sign used as the complete term of the file description (i.e., the file-name, file-type or member-name) means that the corresponding complete term from the source file description is used. For instance: >getfile *.txt:f =.text:s (noquery "FILE1.TXT:F" copied to "FILE1.TEXT:S". "FILE2.TXT:F" copied to "FILE2.TEXT:S". ...

The equal sign wild card, combined with regular characters, can have two different effects depending upon whether or not the corresponding term in the source file description used wild cards. When the source file description uses a wild card then the equal sign is replaced with the portion represented by the source file’s wild card. >getfile file*.dat:f abc=x.data:s (noquery "FILE1.DAT:S" copied to "ABC1X.DATA:S". "FILE3.DAT:S" copied to "ABC3X.DATA:S". ...

When the source file description does not use a wild card for the corresponding term, the equal sign is replaced with the complete source file term. >getfile *.dat:f =.new=:s (noquery "FILE1.DAT:S" copied to "FILE1.NEWDAT:S". "FILE3.DAT:S" copied to "FILE3.NEWDAT:S". "FILE2.DAT:S" copied to "FILE2.NEWDAT:S". ...

DOS Partitions The disk drive specified by drive may be an attached removable disk such and Disks as a floppy or removable hard disk, or it may be a partition on an attached hard disk drive. This disk or partition may be a DOS-formatted partition (16-bit FAT) or a Windows 95 disk or partition (32-bit FAT). When it is a partition of an attached THEOS drive, the DOS partition is referenced by specifying the attached THEOS drive code, for instance S or C: for drive if the DOS partition is a partition of the same physical drive that is attached as the S drive in THEOS. >getfile s (dir >getfile /windows/*.*:s >getfile /dos/ansi.sys:s =.=:s (bin "/DOS/ANSI.SYS:S" copied to "ANSI.SYS:S".

286 GetFile

Windows NT disks and partitions cannot be accessed with this command. Return Codes

When no files are transferred, the return code is set to one, indicating failure.

See also

CopyFile, CRLF, PutFile, Receive , THEO+COM

Commands GetFile 287

Commands

288 GetFile

Head Command Filter The Head command displays the beginning of a text file on the standard output device.

HEAD ( option

2

HEAD file... ( option

file

»

file name with optional path

option

»

nnn

Operation

Commands

1

Mode 1—The first 10 lines from the standard input device are output to the standard output device. This form of the Head command would normally be used in a pipe command line: >calendar 2001 January 2001 Su Mo Tu We Th 1 2 3 4 7 8 9 10 11 14 15 16 17 18 21 22 23 24 25 28 29 30 31

| head

April 2001

Fr 5 12 19 26

Sa 6 13 20 27

February 2001 Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 May 2001

March 2001 Su Mo Tu We Th 1 4 5 6 7 8 11 12 13 14 15 18 19 20 21 22 25 26 27 28 29

Fr 2 9 16 23 30

Sa 3 10 17 24 31

June 2001

>

Mode 2—The first lines of file are output to the standard output device. When more than one file is specified then the first lines of each of the files are output. >head /theos/help/english/_command.hlp (4 ACCOUNT Maintain the user account names file. ARCHIVE Back up hard disks onto floppies or tapes. ATTACH Logically connect a device for future access. BACKUP Copy full disk to disk or tape.

Options

nnn

Notes

When the standard output device is the console and multiple files are specified, the screen is cleared between each file display. When multiple files are specified, the output for each file has a heading added that identifies the file.

Specifies the number of lines of each file to output. This specification must be in the range 1–999. The default value is 10.

Head

289

The nnn option may use the DOS/UNIX style which is a leading minus sign and the option is specified before the file specifications. The following two commands produce the same results: >head /theos/help/english/_command.hlp (4 >head -4 /theos/help/english/_command.hlp

Commands

If file is a “typeless” file description, there is no default library defined and the environment variable FILETYPE is defined, the value of FILETYPE is appended to file to form a complete file description with file name and file type. To Head a typeless file you should specify the file description with a period terminator. See “FILETYPE” on page 103 of the THEOS Corona Version 5 Operating System Reference for more information. Defaults

The default number of lines displayed is 10.

See also

List, More , Tail

290 Head

Help Command The Help command displays a summary of all THEOS commands or a detailed description about a specific command.

HELP

2

(F1)

3

HELP

4

program(F1)

5

HELP

program

Commands

1

program

* »

command name or valid abbreviation

The Help command uses the files in the directory /THEOS/HELP/language:S as the source of the help text displayed. If this directory has been removed for any reason, the Help command cannot operate. Operation

Mode 1—Displays the file /THEOS/HELP/language/_COMMAND.HLP, which is a list of all commands on the operating system with a brief, one-line description.

To get more information about a particular command, select the command name with the reverse-video highlight bar and then press (EnterÌ˛). The highlight bar is moved with the (˚) and (˙) arrow keys, or by entering a letter key to jump to the next command starting with that letter. As a shortcut, the (ÌÌSpaceÌÌ) advances to the next line also. Help

291

You may also use the (Home) and (End) keys to move to the beginning or end of the list. The (PageDown) and (PageUp) keys advance to the next or previous display page. Mode 2—This is a shortcut method of invoking the Mode 1 Help display.

Commands

Mode 3—Displays detailed information about the function and operation of the command program. program may be any valid name, synonym name or abbreviation of a command. It may also be a non-command as long as there is a file for it in the /THEOS/HELP/language directory. >help message

Mode 4—This is a shortcut method of invoking the Mode 3 Help display for program. Mode 5—Displays detailed information for all commands or files listed in the /THEOS/HELP/language:S directory.

292 Help

Notes

Besides the standard command names, the Help command can display information about any subject for which there is a file in the /THEOS/HELP/ language:S directory. Provided with the operating system are files providing information about: Description

_B3221

Internal help for MultiUser BASIC language.*

_LEDIT

Internal help for LineEdit command.*

_MORE

Internal help for More command.*

_PATCH

Internal help for Patch command.*

COMPOSE

Help for composing characters on PC-Term keyboards.

CSI

Help for entering commands.

EXEC

Help for the EXEC language.

VDI

Help for using the Virtual Device Interface.

*

Commands

Subject

This information is normally displayed from within the indicated program. It can be displayed at any time with the Help command.

Help

293

Commands

294 Help

Ident Command This command displays the current account number on the standard output device.

IDENT Commands

Operation

The account number of the current account is output to the standard output device (normally the console). >ident 5

See also

Show WHO, WhoAmI

Ident

295

Commands

296 Ident

Img Command The Img command displays graphic image files on the graphics console.

IMG file ( options »

file name with optional path; may contain wild cards

options

»

CENTER CYCLE

FRAME KEEP

MAXIMIZE NOFRAME

SLIDESHOW WAIT

Operation

If file is the name of a single image file (no wild cards) then the image is displayed on the screen and Img exits leaving the image displayed. If file is omitted or is specified with wild cards, a menu of the matching files is displayed and you can select the desired file. Omitting file is the same as using a file specification of *.*.

Options

CENTER

Display the image positioned at the center of the session window. This option is only effective when a single file is specified.

CYCLE

Synonym to the SLIDESHOW option.

FRAME

Display the image with a frame around it.

KEEP

When exiting the Img command the displayed image remains on the screen. This is the default action when a single file is specified. Img 297

Commands

file

MAXIMIZE

Display the image in a window that shows the entire image, or a window as large as the current session window.

NOFRAME Display the image without a frame around it. This is a default

option.

Commands

SLIDESHOW This option is effective only when file is omitted or uses wildcards. It causes Img to not display a menu of file names but

instead to automatically display the matching image files. This option turns on the CENTER, MAXIMIZE and NOFRAME options. If the WAIT nn option is used with a non-zero nn value, the slide show is automatic with each image displayed nn seconds after the last image. You can pause and manually advance the slide show with the following keys: Key (EnterÌ˛) (PageDown)

Advance to next image.

(PageUp)

Backup to prior image.

(Home)

Display first image.

(End)

Display last image.

(Space) (Esc) WAIT nn

Action

Pause or resume slide show. Terminate slide show.

When displaying a SLIDESHOW, wait nn seconds before automatically displaying the next image. When nn is not specified (meaning that manual progression only is to be used), the last displayed image is not closed until the operator presses (Esc) or (EnterÌ˛).

Defaults

For single files, NOFRAME and KEEP are the default options. For multiple files (wild cards), there are no default options.

Restrictions

The format of the file must be BMP, GIV, PCX or JPG. The console must be graphics-capable and in graphics mode. Refer to Setup VGA for information about configuring the main console display. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.)

See also

FileManager, Viewer

298 Img

Install Command The Install command installs software from a removable disk or disc drive.

INSTALL

Operation

»

optional disk drive letter

This Install command attempts to execute the Install Exec program that it finds on either the floppy disk drive or the CD-ROM drive. The Install program that it searches for can be named INSTALL.EXC or INSTALL.EXEC. When drive is specified, only that drive is searched. When drive is not specified the Install command seaches the removable media drives in the following order: floppies in attached drive-letter sequence, image drives in attached drive-letter sequence and then all other removable media drives in attached drive-letter sequence (zip, CDROM, etc.). When an Install program is found the search is terminated and that Install program is executed.

See also

UnInstall

Install

299

Commands

drive

drive

Commands

300 Install

IXDiag Command This command checks the integrity of indexed files.

1

IXDIAG

file... ( options »

file name with optional path; may include wildcards

options

»

APPEND DATA BASIC DATA BINARY DETAILS EXCEPTIONS

Operation

EXEC FILES KEYLEN LOGFILE NOTYPE

NOWAIT RECLEN REPAIR REPLACE SAVE

SUBDIR TYPE VERIFY DATA VOLUME WAIT

The file is examined for indexed file structure integrity. Many, non-serious errors may be detected and reported along with serious, data-loss errors. The file is repaired only if specifically directed to with the REPAIR or SAVE options. Otherwise, only warning messages are displayed when errors are detected.

Options

APPEND

Used with option EXEC to indicate that problem file names are appended to the end of any existing IXERR.EXEC file. >list ixerr.exec &1 /PRIVATE/ADDR.BOOK:S &2 &3 &4 &5 &6 &7 &8 &9 &10 >ixdiag *.* (exec >list ixerr.exec &1 /PRIVATE/ADDR.BOOK:S &2 &3 &4 &5 &6 &7 &8 &9 &10 &1 /JONAS/DATA.BASE:S &2 &3 &4 &5 &6 &7 &8 &9 &10

Used with option LOGFILE to indicate that the error messages are appended to any existing logfile. DATA BASIC Records in the file are formatted BASIC language records. DATA BINARY Records in the file may be in any format and are not

checked for consistency. DETAILS

Displays information about which files are being examined and, if an error is detected, a brief description of the error. When used with the WAIT option, after an error description is displayed the program pauses and you may request more information about the error condition.

IXDiag 301

Commands

file

Compare the following three examples to see the effect of this option: >ixdiag *.* /DATA/CHECK.DETAIL:S needs minor repairs /DATA/EXPENSE.JOURNAL:S could be optimized

Commands

>ixdiag *.* (detail Examining indexed file /DATA/CHECK.DETAIL:S Bad blocks on freelist - File should be rebuilt Examining indexed file /DATA/CHECK.MASTER:S Examining indexed file /DATA/EXPENSE.JOURNAL:S Indexed file has 62.9% wasted space which could be recovered if rebuilt ... >ixdiag *.* (details wait Examining indexed file /DATA/CHECK.DETAIL:S Bad blocks on freelist - File should be rebuilt ?(F1)

Indexed file has serious problems with its freelist, which could cause problems if you tried to write new records. You may be able to read from this file but corruption is likely

Examining indexed file /DATA/CHECK.MASTER:S Examining indexed file /DATA/EXPENSE.JOURNAL:S Indexed file has 62.9% wasted space which could be recovered if rebuilt ?(F1)

THEOS may have been rebooted while this file was being updated and some space has been lost for that or similar reasons. This is basically harmless other than being a waste of disk space and this space can be recovered by recopying the file by record or by using the SAVE option. ...

Note: DETAILS, NOTYPE and TYPE are mutually exclusive options. Only the last one specified will have any effect. EXCEPTIONS An exception-file file name is specified following the option keyword. Can only be used when SAVE option is used and tells IXDiag to save any suspect and bad records to this exception-

file. EXEC

The names of all files that have problems or errors are written to the file IXERR.EXEC. If APPEND option is not specified, any existing IXERR.EXEC file is first erased. >ixdiag *.* (exec >list ixerr.exec &1 /PRIVATE/ADDR.BOOK:S &2 &3 &4 &5 &6 &7 &8 &9 &10

FILES

302 IXDiag

Indicates that file is an ASCII stream file with each record in the file specifying a single file name. The file name specifications in this file may include the path and wild cards.

The SELECTED.FILES and SELECTED.EXEC files created by FileList and the FOUND.EXEC created by Look can be used for this specification file (see “The EXEC and FILES Options” on page 239). You may also create the file with an editor or application program. For instance, FileList is used to create a list of files to be examined:

>filelist a not *.data:a (10/1/01 exec append

A SELECTED.EXEC file now exists that lists all of the “data” files and all files that have been changed since 10/01/2001. The following command checks these files: >ixdiag selected.exec (file

KEYLEN

The new key-length is specified following the option keyword. This option tells IXDiag that, when it rebuilds the file it should use the new key-length specified, not the key-length of the existing file. This option is only used when REPAIR or SAVE is used.

LOGFILE

A logfile is specified following the option keyword. Indicates that error messages are to be written to logfile. May be used with option APPEND to cause the messages to be added to any existing messages in the file.

NOTYPE

Tells IXDiag to not display messages about what files it is checking. >ixdiag *.* f (notype /DATA/CHECK.DETAIL:S needs minor repairs /DATA/EXPENSE.JOURNAL:S could be optimized /DATA/MASTER.CONTROL:S needs minor repairs /DATA/PAYABLES.MASTER:S needs minor repairs

To disable this option use the TYPE or DETAILS option. Note: DETAILS, NOTYPE and TYPE are mutually exclusive options. Only the last one specified will have any effect. NOWAIT

Used with DETAILS option to indicate that you want IXDiag to wait each time that it detects and reports an error in a file. This option has no effect when DETAILS is not specified.

RECLEN

The new record-length is specified following the option keyword. This option tells IXDiag that, when it rebuilds the file it should use the new record-length specified, not the recordlength of the existing file. IXDiag 303

Commands

>filelist *.data:a (exec

This option is only used when REPAIR or SAVE is used. REPAIR

Tells IXDiag that, if file contains errors, it should rebuild it with the corrected version.

Commands

Note: This is potentially dangerous operation. The file should be backed up first or copied to another location. >ixdiag telephon.numbers (repair details Examining indexed file /TELEPHONE.NUMBERS:S Bad blocks on freelist - File should be rebuilt Recovering /TELEPHON.NUMBERS:S on 23 Nov 2001 03:42PM : 205 records copied, 0 records skipped (205 total records).

REPLACE

Used with the SAVE and EXCEPTIONS option to tell IXDiag to replace any existing savefile or exception-file with the new data. When REPLACE is not used with SAVE and EXCEPTIONS, the records are added to any existing savefile or exception-file.

SAVE

A new savefile destination file name is specified following the option keyword. Tells IXDiag that it should rebuild the file and write the recovered records to a new file named savefile. Can be used with EXCEPTIONS to save the suspect or bad records into a new file. >ixdiag suspect.file (save suspect.new except suspect.errors Recovering SUSPECT.FILE on 23 Nov 2001 02:10PM : 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 17297 records copied, 0 records skipped (17297 total records).

SUBDIR

Tells IXDiag to check all subdirectories starting with the directory for file. >ixdiag s Examining Examining Examining Examining Indexed Examining Examining ...

TYPE

(subdir indexed indexed indexed indexed file in indexed indexed

details file /CGI/DATA/CUSTOMER.MASTER:S file /CGI/DATA/ORDERS.DETAIL:S file /CGI/DATA/ORDERS.MASTER:S file /FAX/FAX.LOG:S use -- diagnostic check skipped file /SAMPLES/SAMPLE.DATA.CUSTOMER:S file /SYSTEM.CALANDAR:S

A default option that tells IXDiag to display summary information only for files with errors. >ixdiag *.* /DATA/CHECK.DETAIL:S needs minor repairs /DATA/EXPENSE.JOURNAL:S could be optimized /DATA/MASTER.CONTROL:S needs minor repairs /DATA/PAYABLES.MASTER:S needs minor repairs

To disable this option use the NOTYPE option. Note: DETAILS, NOTYPE and TYPE are mutually exclusive options. Only the last one specified will have any effect.

304 IXDiag

VERIFY DATA Tells IXDiag to include in its tests a check to confirm that the

fields in each record of the file are BASIC formatted fields. VOLUME

Tells IXDiag to look for file in all accounts on that drive. file must be a drive specifier only:

When this option is used in combination with the SUBDIR option, all indexed files in all directories on all accounts are checked for integrity. WAIT

Defaults

Used with the DETAILS option to cause IXDiag to wait each time that it reports an error in a file. In this mode you may request additional explanation of the error message by using the (F1) key.

The following options are in effect by default: DATA BASIC, NOWAIT and TYPE.

Notes

To check all of the files on all of the accounts on all subdirectories on a disk, log onto the SYSTEM account and use the command: >ixdiag s (volume subdir

Cautions

A file should not be repaired with the REPAIR option unless it is backed up first. The data may be lost if there is any problems encountered during the repair operation.

Restrictions

Only indexed files are checked with this command. Keyed, direct and stream files are excluded. The file must not be open by any other user. The file is locked by IXDiag when it checks it.

IXDiag 305

Commands

>ixdiag s (volume PACKAGE\SYSPECT.FILE:S has serious problems SYSTEM\TELEPHON.NUMBERS needs minor repairs

Commands

306 IXDiag

Keyboard Command The Keyboard command replaces the current keyboard driver with a different or modified driver.

number name

number

»

Language code number (1–9)

name

»

Simple file name for new keyboard driver program

Commands

KEYBOARD

Operation

The keyboard driver file named /THEOS/DRIVER/name.BIN:S is assigned to PC term terminals using class code 9x, 18x, 19x and 21x where x is number.

Notes

It is not necessary to use this command unless you have made a change to one of the keyboard drivers. The language code numbers and keyboard driver names are: Code

Restrictions

Language

Name

Language

1

English (UK)

KEYBBE

Belgium

2

French

KEYBCF

Canadian French

3

German

KEYBDK

Denmark

4

Italian

KEYBFR

French

5

Spanish

KEYBGR

German

6

Swiss

KEYBIT

Italian

7

Spanish (Latin American)

KEYBLA

Spanish (Latin American)

8

French (Canadian)

KEYBSF

Swiss (French)

9

Belgium

KEYBSG

Swiss (German)

KEYBSP

Spanish

KEYBUK

English (UK)

KEYBUS

English (United States)

The keyboard driver name must be a simple name without a path, file-type or file-drive. The driver must reside in the /THEOS/DRIVER:S directory with a file-type of BIN.

Keyboard

307

Commands

308 Keyboard

Keyword Command The Keyword command displays or maintains the SYSTEM.THEOS32.KEYWORD file.

KEYWORD

nnn

2

KEYWORD

*

3

KEYWORD

option

Operation

( option Commands

1

( option

»

NOSORT PRTnn SORT TYPE

Mode 1—Display keyword nnn from the /THEOS/OS/MESSAGE/language/KEYfile.

WORD.BIN:S

Mode 2—Displays all of the keywords defined in the /THEOS/OS/MESSAGE/ language/KEYWORD.BIN:S file. When the display is to the console or printer, it is output in multiple columns. >keyword * (nosort Code 0 1 2 3 ...

Keyword Yes No Type NOTtype

Code 26 27 28 29

Keyword TRANs SPECs TRuncate NEWFile

Code 52 53 54 55

Keyword NOSORT NOMain ATTach TOUch

Code 78 79 80 81

Keyword HIStory ABbrev RDYmsg MSG

The keywords are shown in mixed case. The uppercase letters in each keyword indicate the minimum spelling or abbreviation allowed. When the output is redirected to a disk file, it is output in a single column with no headings. Mode 3—This is the keyword maintenance mode. When this mode is entered, you are prompted to enter the keyword number: >keyword Enter keyword id:

At this prompt enter either the number of the keyword you want to view or change, or press (EnterÌ˛), (Esc) or (F9) without a number to exit.

Keyword

309

When a number is entered, the current definition is displayed and you are asked for the new definition: >keyword Enter keyword id: 3

Commands

Old text: NOType New text:

To leave the keyword unchanged, press (EnterÌ˛) without any characters or spaces. To change or define a keyword enter the new text. Keywords may be a maximum of eight characters in length. You specify the minimum spelling or abbreviation for a keyword with uppercase letters. Care should be taken when specifying the minimum spelling for a keyword. Make sure that the abbreviation does not conflict with any other keyword’s abbreviation that might be used in the same context. When the new text for the keyword is entered, press (EnterÌ˛) and you are prompted for another keyword to change. Options

NOSORT

Tells Keyword to output the list of keywords in keyword number order, not in alphabetically sorted order.

PRTnn

Indicates that Keyword is to print the keywords on the attached printer number nn. The option keyword PRT may be specified as PRT, PRINT or PRINTER. As a convenience, PRINTER1 may be specified as P.

SORT

A default option that causes the keywords to be output in alphabetical order. >keyword * > sorted.keywords >list sorted.keywords 79 192 109 253 179 193

TYPE

310 Keyword

ABbrev ABORT ACCount ADD Alf ALign

A default option that causes Keyword to display the keywords on the console.

Defaults

TYPE and SORT are default options when using Mode 2 .

Cautions

This keyword file is used by all of the THEOS commands. Changing a keyword may affect many commands.

Restrictions

You must be logged onto the SYSTEM account and you must have a privilege level of five. Commands

Keywords may be a maximum of eight characters in length. See also

List, Message

Keyword

311

Commands

312 Keyword

Killfile Command This command erases one or more files from disk.

KILLFILE

file ( options

2

KILLFILE

file ( FILES options

3

KILLFILE

( options

Commands

1

file

»

file name with optional path; may contain wild cards

options

»

NOQUERY NOTYPE

QUERY TYPE

Although similar to the Erase command the Killfile command is quite different and potentially very dangerous. Killfile erases a file’s directory entry without deallocating the file’s disk space. You should only use this command in single-user mode and you should only kill a file if you know that there are problems with the files allocation. Operation

Mode 1—Attempts to erase file and displays the result of the attempt. >killfile sample.data

"SAMPLE.DATA:S" erased. One file erased, 3,840 bytes recovered.

Because Killfile operation is dangerous, the QUERY option is the default, even when the file specification is explicit. You are queried for permission to erase each file unless the NOQUERY option is specified. When file is a subdirectory name, the Killfile command will kill the directory even if it contains files. Mode 2—file is an ASCII stream file containing one file description per line. Each file description in file is killed. As each file is killed its file description is displayed (unless the NOTYPE option is specified).

Killfile

313

This mode of the Killfile command is convenient when one or more sets of files are repetitively being killed.

Commands

>edit daily.kill work.master:s work.history:s work.invoices:s work.ledger.*:s temp*.*:s sort*.*:s /programs/program.backlib.*:s >killfile daily.kill (file noquery notype

Mode 3—Invokes the interactive mode of the Killfile command. Because no files are specified on the command line, you are prompted to enter the file descriptions to erase. >killfile Enter file name list, terminate with empty line. ?/SAMPLE.DATA

"/SAMPLE.DATA:S" erased. ?*.zip

...

As illustrated, this interactive mode allows any file specification to be entered, including wild cards. To terminate this mode, enter a blank line.

314 Killfile

Options

NOQUERY Tells Killfile to not ask for confirmation before killing each file. >killfile gl.* (noquery "GL.MASTER:S" erased. "GL.JOURNAL:S" erased. "GL.HISTORY:S" erased.

Tells Killfile to not display the results of each file killed on the standard output device.

QUERY

Tells Killfile to “query” or ask if each file matching the file specifications is to be killed. This is a default option when wild cards are used. To disable this option use the NOQUERY option. >killfile *.backup

Selecting “Yes to All” means yes to this file and all remaining files are killed without being queried. Respond with (Esc)or (C) to cancel the kill operation. TYPE

A default option that tells Killfile to display the results of each file killed on the standard output device. This display can be redirected. >killfile *.*:s (noquery "/DEVELOPE.EXEC:S" erased. "/GRAPH.SAVE1:S" erased. "/GRAPH.DATA:S" erased.

Killfile

315

Commands

NOTYPE

Notes

After performing a Killfile operation you should always perform a Disk FIX operation to correct any misallocations that may be been created with the Killfile operation.

Commands

Because of its unrestricted capabilities, Killfile should only be used in single-user or maintenance mode. Defaults

QUERY and TYPE are default options.

Restrictions

Because the purpose of this command is to erase or kill a file that may have allocation problems, there are no restrictions on what files may be killed. It does not matter if the file requested is erase-protected, in use by another user, a directory or library with existing member files, owned by another account, it can be killed with this command. This command does require a privilege level of 6 to operate.

See also

316 Killfile

Erase , FileManager, Rename, RmDir

Line Command Filter This command copies one line of text from the standard input device to the standard output device.

Operation

The next line of text from the standard input device is copied to the standard output device. In the following commands a descriptive line is written to a file, followed by a FileList that appends its output to the same file. >line > filelist.output The following is a listing of all backup files. >filelist *.backlib*.* *.backup >> filelist.output

In this example the first line of the KEYWORD.HEADER is copied to a file, followed by other information appended to that file. >line < keyword.header > keywords.list >keywords * >> keywords.list

Notes

This command is normally used to write a heading or descriptive line of text to a file before writing other text to the file. A line of text is always terminated with a CR (file) or a CR,LF (console). When the standard input device is the console, the input is terminated by pressing (EnterÌ˛).

Defaults

The standard input and output devices are normally the console keyboard and display.

See also

CopyFile, Echo, Head, Tail, Tee

Line 317

Commands

LINE

Commands

318 Line

LineEdit Command The LineEdit command is a utility program that, unlike WinWrite, edits ASCII text files using line-edit mode rather than a full-screen editor.

file ( option

file

»

file name with optional path; wild cards not allowed

option

»

BACKUP NOBACKUP

Command synonym: Operation

Commands

LINEEDIT

LEDIT

This command edits an existing text file or creates a new text file. When the command is first entered, a message displays indicating whether the text file is new or an existing file: >lineedit sample.text New file "SAMPLE.TEXT". Edit: *

or >ledit system.theos32.devnames Old file: "SYSTEM.THEOS32.DEVNAMES:S". Edit: *

The edit prompt character is the asterisk ( * ) and, when displayed at the beginning of a line, it indicates that LineEdit is waiting for an editing command. There is an internal help display available in LineEdit that can be invoked by pressing (F1). This help display summarizes all of the commands available while using the LineEdit command.

LineEdit

319

Commands

Cmd

Operands

Meaning

?

Query last command

;

Comment

Again

Reexecute last "string" command

Bottom

Go to bottom of file

CAse

[U|L|M]

Set case mode Upper, Lower (inverted), Mixed

Change

[/frstr/tostr[/ [#lines [#occur [#start]]]]]

Global change

COlumn

Display column ruler

COMbine

Append next line to current line

CSI

command

Execute THEOS command, then return to LINEEDIT

DElete

[#lines|/str/]

Delete lines

Down

[#lines]

Go down

DUp

[#lines]

Duplicate current line

FILe

[filename]

Save the file, then exit

Find

[text]

Anchored locate

Get

[filename][frct|/ frstr/ [toct|tostr/]]

Merge from another file

[text]

Insert a line or Insert mode

Help Input

Ask for help

LEngth

Ask for size of file

LIst

#lines

Display lines

Locate

[/str[/]]

Locate string or Locate again

Modify

[#lines]

Modify lines

NAme

[filename]

Change file name

Next

[#lines]

Go down or locate

Page

Display full page and go down

Ut

[filename] [/tostr/|ct]

Write lines to another file

PUTD

[filename] [/tostr/|ct]

Write line and delete

Quit

[retcode|command]

Exit and execute THEOS command

Replace

[text]

Replace lines

Save

[filename]

Save file

SPlit

[?|/str/]

Split current line into two lines

TAbset

[list of col numbers]

Set tab stops

Type

[#lines]

Display lines

Up

[#lines|/str/]

Go up

VErify

[on|off]

Verify (display) status

X,Y,Z

[#lines|statement| "filename" [line#]]

Macro

TOp

Go to top of file

Table 6: LINEEDIT Command Summary

320 LineEdit

Options

BACKUP

A default option that tells LineEdit to make a backup copy of the prior version of the text file.

1. Is the existing file a member of a library and does a library exist with the same file-name but with a file-type of BACKLIB? If so, rename the file into the BACKLIB library, replacing any existing file with the same member-name in that BACKLIB library. 2. Is there a library with a file-name equal to the current account name and a file-type of BACKLIB? If so, rename the file into that library, replacing any existing file with the same member-name. 3. If there is no BACKLIB library that might apply, then rename the existing file to have a file-type of BACKUP, replacing any prior version of the backup file name. Note: Unlike WinWrite which can maintain up to nine levels of backups, only one level of backup is maintained for the file with LineEdit. File: 1st choice: 2nd choice: 3rd choice:

TEXT.FILE

LIBNAME.LIBTYPE.TEXT

account.BACKLIB.TEXT

LIBNAME.BACKLIB.TEXT

TEXT.BACKUP

account.BACKLIB.TEXT TEXT.BACKUP

Table 7: LINEEDIT Backups NOBACKUP Tells LineEdit that, when an existing file is saved to disk, the

prior version of any file with the same name is to be over-written without renaming it to be a backup of the original.

LineEdit

321

Commands

When the file is saved with either the SAVE or the FILE edit commands, LineEdit checks to see if there is a file on disk with the same name as the file it is about to write to disk. If it does exist, LineEdit renames that existing file to be a backup file. The rules used for determining the name of this backup file are:

Commands

Notes

The LineEdit command is provided as a utility that can be used by EXEC language programs and application programs that need to edit a text file without operator assistance. WindoWriter, although a far more powerful program, is a full-screen editor and, as such, requires all of its commands to be entered from the keyboard. LineEdit, being a line-oriented editor, can receive all of its commands from a text file or an EXEC program’s &stack data. >list updsyn.exec ; EXEC to update standard synonym with application name ; &begstack find DATE up 1 input CUSTOMER 2 file &end lineedit system.theos32.synonym >updsyn Old file "SYSTEM.THEOS32.SYNONYM:S". Edit: *f DATE DATE 4 *u 1 CRT 3 *i CUSTOMER 2 *file "SYSTEM.THEOS32.SYNONYM:S" filed.

Defaults

BACKUP is the default option.

Restrictions

Only stream files containing ASCII text may be edited with this command. Use Patch for making changes in other file organizations or contents.

See also

Patch, WinWrite

For a complete discussion of the operation of LineEdit and the commands available for editing text files, refer to Appendix B: “LineEdit Text File Editor,” on page 161.

322 LineEdit

List Command List displays the contents of any data or program file on the standard output device.

LIST

file... ( option

2

LIST - ( option

file

»

file name with optional path; may contain wild cards

option

»

BINARY COMnn FILES FORMAT FROM kkk

Operation

HEAD HEX INDENT nn NOHEAD NUMBERED

OLDDATE PAGE nnn PRTnn TITLE ttt TO kkk

Commands

1

TRUNC nnn

fromline toline

Mode 1—The file or files specified are displayed on the standard output device (console). Mode 2—This mode can be used when standard input has been redirected (as in a pipe) or when you want to supply the list of files from the keyboard (be sure to use option FILES). >filelist system.help32.l* system.help32.s* | list (file

When the list of files comes from the console keyboard the “-” must be specified on the command line. Terminate the list with (Ctrl)+(Q). >list - (file ?system.help32.l* ?system.help32.s* ?(Ctrl)+(D)

The above two commands display all of the help files starting with “L” or “S.”

List

323

BINARY

Displays the file in hexadecimal. See “Binary & Hex Displays” on page 329.

COMnn

The display is sent to the attached COMnn device instead of the standard output device.

FILES

Indicates that file is an ASCII stream file with each record in the file specifying a single file name. The file name specifications in this file may include the path and wild cards.

Commands

Options

The SELECTED.FILES and SELECTED.EXEC files created by FileList and the FOUND.EXEC created by Look can be used for this specification file (see “The EXEC and FILES Options” on page 239). You may also create the file with an editor or application program. For instance, FileList is used to create a list of files to be examined: >filelist *.data:a (exec >filelist a not *.data:a (10/1/00 exec append

A SELECTED.EXEC file now exists that lists all of the “data” files and all files that have been changed since 10/01/2000. The following command lists these files: >list selected.exec (file

The FileManager command can also create and add to SELECTED.EXEC, SELECTED.FILES and FOUND.EXEC files. FORMAT

The file contains first-character ANSI forms-control formatting codes. List will use these codes instead of counting lines and displaying one record per line. The ANSI forms-control standard specifies that the first character of each record is the page advancement control. This character is never printed. If these codes are not present at the beginning of each line, the first character of the line that was intended to be displayed is instead interpreted as the ANSI forms-control character and is not displayed.

324 List

These codes are: Code

Meaning Eject page.

+

Do not advance—overprint the previous line. This can only be done if the printer does not perform an automatic line advance with each carriage return. (Option ALF not specified on printer attachment.)

0

Advance two lines, skipping one blank line.

-

Advance three lines, skipping two blank lines.

other

All other characters are not printed and cause one line to advance. By convention, the space character is used for this purpose. Table 8: ANSI Forms Control Codes

FROM

This option can only be used when file is direct, indexed or keyed. For direct files, kkk is a number that specifies the first record number displayed. For indexed and keyed files, kkk is the key of the first record displayed. Only records whose keys are greater than or equal to this kkk will be included in the display. This option can be used with or without the TO option. >list keyword.bin (from 20 nohead 020: 1QUERY 021: 2NOQUERY 022: 5PRIVATE ... >list customer.master (from "Conc" trunc 47 noh Concrete Consultants, Inc.: "1300 Southwest Eve Continental Lumber Services: "101 West 43rd","P. THEOS Software Corporation: "333 Oakland Blvd, Walnut Creek Chamber of Commerce: "100 North Mai

HEADING

A default option that causes the standard page heading to display. This standard page heading includes the file name on the left size of the page and the date, time and page number on the right.

HEX

Displays the file in hexadecimal. See “Binary & Hex Displays” on page 329.

List

325

Commands

1

INDENT nn All lines output are to be indented nn columns. NOHEAD

Suppresses the standard page header.

NUMBERED Causes a sequentially assigned line number to display at the

beginning of each line. Commands

>list /theos/help/english/list.hlp (numbered nohead 1 2 3 4 5

... >list /theos/help/english/list.hlp (nohead

... OLDDATE

Causes the date and time used in the page heading to be the file’s last change date and time. When this option is not used the current system date and time displays.

PAGE

Indicates that the first page displayed is page number nnn. Note: When the output is to the console, the browse keys can still be used to display pages before page number nnn.

PRTnn

Indicates that List is to print file on the attached printer number nn. The option keyword PRT may be specified as PRT, PRINT or PRINTER.

TITLE

The word or quoted term following the keyword TITLE is used in the heading line instead of the file’s file name. >list / (title "Device Names" Device Names GUTENB1 12:136:0 GUTENB2 21:136:1 GUTENB3 22:136:2

...

326 List

23 Mar 2002 11:55am Page 1 SPO C241,W8;Jupiter.cpw.lan - HP LJ 4 Plus SPO C241,W8;Jupiter.cpw.lan - HP DeskJet 690C SPO C241,W8;Jupiter.cpw.lan - Phaser 860DP

TO

This option can only be used when file is direct, indexed or keyed. For direct files, kkk is a number that specifies the last record number displayed. For indexed and keyed files, kkk is the key of the last record displayed. Only records whose keys are less than or equal to this kkk will be included in the display.

TRUNCATE

Each line output is truncated at column nnn. If used in combination with the INDENT nn option, the truncation is performed after the indent spaces are added. When TRUNCATE is not used, lines are not truncated and those lines that are longer than the attached length of the display device (console or printer) are wrapped to the next line.

fromline

The first numeric token is assumed to be the starting line or record number. This can only be used on stream and direct files. Use the FROM option for keyed and indexed files. This option indicates that the first line or record displayed is fromline. When the output is to the console, the browse keys can still be used to display pages containing records before fromline.

toline

The second numeric token is assumed to be the ending line or record number. This can only be used if fromline is specified on a stream or direct file. Use the TO option for keyed and indexed files. This option indicates that the last line or record displayed is toline. The browse keys cannot be used to display beyond this toline record.

List

327

Commands

This option can be used with or without the FROM option.

List Displays

Most files are displayed as text. For instance: >list /theos/help/english/cat.hlp /THEOS/HELP/ENGLISH/CAT.HLP:S

23 Oct 2002 8:26am Page 1

Commands

Cat Command

 ...



This type of display is used by default for all files except programs, which use the binary display format described next. The heading line of all displays on the console or printer (not those redirected to a file) shows the file name on the left and the date, time and page number on the right. This heading line can be suppressed with the NOHEAD option, and the date can be set to the file’s last change date with the OLDDATE option. C language source programs can set the left side of this heading line with the #title directive. For multiple-page displays, the standard page browsing keys are recognized. Refer to “Multiple-page Display Browsing” on page 79 of the THEOS Corona Version 5 Operating System Reference. In addition to these standard keys, you may also use (PageUp) and (PageDown) following a number such as: (6),(PageDown). This means to advance six pages rather than the default of one page.



328 List



 Binary & Hex Displays



Program files do not contain ASCII text data and are always displayed using the BINARY display format. >list sample. command SAMPLE.COMMAND



23 Oct 2002 8:26am Page 1



Commands



000000: 8603DEC0 4E060000 6C010000 00080000 '..݃N...l.......' 000010: 940e0000 01000800 00006000 00000100 '..........`.....' 000020: 00000000 b00ac15f 35623e56 061b8161 '....».‰_5b>V...a' ...



In this display each line contains three pieces of information. On the left side is the relative location in hexadecimal. In the middle, 16 bytes of the file are shown in hexadecimal. This middle section is grouped in four, four-byte columns. On the right is the ASCII representation of those 16 bytes of the file. Any bytes that do not have a corresponding ASCII character are shown with a period. This display format can be forced for any file by using the BINARY option. Data files (direct, indexed and keyed) can use a third type of display invoked with the HEX option: >list customer.master (hex



CUSTOMER.MASTER KEY: 0000: 0010: 0020: DATA: 0000: 0010: 0020: ...



23 Oct 2001 8:26am Page 1



41414120 56656E64 696E6720 53706563 'AAA Vending Spec' 69616C69 73747300 00000000 00000000 'ialists.........' 00000000 00000000 '........' 041A3132 38323820 536F7574 68776573 '..12828 Southwes' 74205061 726B2050 6C616365 0400040D 't Park Place....' 43617374 726F2056 616C6C65 79040243 'Castro Valley..C'



or >list system.theos32.keyword (hex



SYSTEM.THEOS32.KEYWORD Direct record: 0000: 31594553 Direct record: 0000: 314E4F20 ...



1, reclen: 10 20202020 200D 2, reclen: 10 20202020 200D



23 Oct 2001 8:26am Page 1 '1YES



.'



'1NO



.'



List



329



 This HEX display is similar to the BINARY display except each record is displayed separately, with the first column showing the relative location of the data within the record. For keyed and indexed files, the key is shown separately from the record. Direct files show the record number and record length on a line directly above the record contents.



Commands



Notes



If file is a “typeless” file description, there is no default library defined and the environment variable FILETYPE is defined, the value of FILETYPE is appended to file to form a complete file description with file name and file type. To list a typeless file, you should specify the file description with a period terminator. Refer to page 103 for more information about this environment variable. MultiUser BASIC language source programs are displayed by passing the file name with the option LIST to the BASIC32 command. For instance: >list sample.basic



is identical to: >basic32 sample.basic (list



Defaults



HEADING is a default option. BINARY is a default option when programs



are listed. Restrictions



The file must have read access enabled. See “File Access Protection” on page 145.



See also



CopyFile, FileManager, More, TBrowse, Viewer, WinWrite



The BASIC language compiler has a built-in ability to list BASIC language source programs.



330 List



 Load Command The Load command loads a program or data file into memory for subsequent usage.



LOAD



program...



Operation



»



name of program or file to load into memory



The program is loaded into memory. When program is a simple name, the following locations are searched: /THEOS/COMMAND/program.CMD program.CMD



If program is already loaded into memory a second copy is not loaded. Notes



Any compiled program (organization code “P” or “Program”) may be loaded into memory. In addition, the /THEOS/CONFIG/DEVNAMES.TXT file may also be loaded. Programs are normally loaded into memory when needed and their use count is set to one. If a program is already in memory because another user or task is using it, or the program was loaded by this command or the system start-up process, that copy of the program is used and its use count is incremented. When a program is no longer needed by a user (program exit), its use count is decremented and, if zero, the program is unloaded. Programs loaded by this command or the system start-up process never have their use count decremented to zero except by Unload which is described on page 717.



Disk Caching



Loading programs and certain key data files into memory before they are needed can increase the performance of your system slightly. However, if sufficient memory is set aside for disk caching, the performance increase will be minimal, at best, and may even degrade. When disk caching is enabled, it is best to not load any programs or files with this command or Sysgen.



Load



331



Commands



program



 Commands



Caution



Do not make changes to programs or files (with LineEdit, Patch, recompilation, etc.) that have been loaded into memory. Any changes to the files affect only the disk image of the file and not the loaded version. Before making changes you should first Unload the program and file. Do not erase or change the location of a file from disk after it has been loaded. If this is done, the loaded copy of the file will not be used and cannot be unloaded except by rebooting the system.



Restrictions



The Load command requires a privilege level of five.



See also



Sysgen, Unload



332 Load



 LogName Command Displays the account name that you are logged onto.



LOGNAME The current account name is output to the standard output device. >logon develop >logname DEVELOP



See also



Ident, Show WHO, WhoAmI



LogName 333



Commands



Operation



 Commands



334 LogName



 Logoff Command Logon Command The Logoff command logs off of the current account; the Logon command logs onto a new account.



LOGOFF



2



LOGON



account ( option



account



»



account name



option



»



NOEXEC



Operation



Commands



1



NOTERM



TERM



Mode 1—You are logged off of the current account. Logging off includes: All files opened by this user are closed and all file and record locks are removed. (This is actually done by the system prior to invoking the Logoff command.) All screen windows are closed. See wFinish command described on page 750. A message displays showing the time and date of the logoff and the elapsed time that you were logged onto the system, along with the amount of CPU time used while logged onto the system. If HISTORY is ON, a record is written to the system history log file recording the fact that you have logged off of an account. See “System History File” on page 217 of the THEOS Corona Version 5 Operating System Reference. All privately attached devices (other than the console, slave printers and VDI devices) are detached. All publicly attached devices are reattached. This includes the devices attached via Sysgen and those attached by you or other users with the Attach command with option PUBLIC. The queues assigned to the public spooled printers are reassigned to their initial values. Spooled printers defined by Sysgen are assigned the queues defined in Sysgen, other printers are assigned queues in a one-to-one basis such as queue A to PRT1, queue B to PRT2, etc. All user environment variables are cleared.



Logoff



335



 >logoff Logoff at 9:12am PDT on Wednesday, October 16, 2001. Duration 1:48:36, cpu 53.780.



Commands



After Logoff completes (and the connection was not terminated because of the Exit command or the TERM option), it invokes a special mode of the Logon command that prompts you for the new account name and password.



Mode 2—The Logon command has two modes of operation: one invoked by the Logoff command and the other invoked when Logon is invoked from a command line. When Logon is invoked by Logoff, it finds and displays the contents of the file /THEOS/MENU/language/LOGON.MNU:S. It then displays the Logon form shown above. When Logon is invoked from a command line, it performs a lateral logon. The Logoff process is not invoked but the current elapsed time and CPU time are transferred to the new logon session. In this mode you must specify the account name on the command line and you cannot include the password with the account name. If the account has a password, you are prompted for it with Logon form shown above but with the “Account Name” field already filled in with the account name. A lateral logon does not clear existing user environment variables, does not detach private devices and does not reattach public devices. It resets only the account name and number and the privilege level of the account. Other system environment variables are changed only if the new account’s 336 Logon



 environment definition specifies new settings. The UserName is not changed unless there is no value for that variable currently. In both modes of Logon, when the account name and password are properly entered, the logon process is performed:



The system’s time-of-day clock is adjusted for any change in daylight savings time, if necessary. See “Daylight Savings Time and Automatic Adjustment” on page 259 of the THEOS Corona Version 5 Operating System Reference. If the TERM option is in effect, the EXEC program that invoked the Logon is terminated. When NOTERM is in effect (a default option), the EXEC program that invoked the Logon command is not terminated. If HISTORY is ON, a record is written to the system history log file recording the fact that you have logged onto an account. See “System History File” on page 217. Unsuccessful attempts to log onto an account are also recorded there. If a /SYSTEM.LOGON:S file exists it is displayed on the console. If account is not the system account or a synonym to it, the /account.LOGON file is displayed on the console. If a /SYSTEM.REMINDER file exists and there is one or more entries for today’s date, the reminder messages are displayed. If account is not the system account or a synonym to it and the account.REMINDER file exists and there is one or more entries for today’s date, the reminder messages are displayed. See “Reminder” on page 479. If the NOEXEC option is not used, a search is made for an EXEC program with a file-name or member-name of account. The normal locations for programs are searched and the environment variable PATH is used when searching for these logon files. All drives in the drive search sequence are examined. If an EXEC program is found, it is executed; otherwise processing continues at the CSI or with the next statement in the EXEC program that invoked Logon (if NOTERM is in effect).



Logon



337



Commands



The environment switches and variables are set according to the account definition. See “Account” on page 13. If the new work drive is different than the prior work drive, the work files are copied to the new work drive.



 Commands



Options



Notes



NOEXEC



Do not execute the account EXEC.



NOTERM



Do not terminate execution of the EXEC calling the Logon command. This is a default option.



TERM



Terminates execution of an EXEC program if it was executing when Logon was invoked.



When the user is connected via a network connection, use the Exit command to log off and disconnect the user. Neither the Logoff nor the Logon commands clear the console display. However, one or more of the displayed files ( /SYSTEM.LOGON:S or /account.LOGON:S ) may clear the screen by embedding a form-feed code (^L) in the text file. You may refresh the display by pressing (Enter) on a blank logon name. This is useful if you have started a user session on a terminal that was powered off. When the user turns the terminal on they can press (Enter) to see the logon prompt.



Defaults



NOTERM is a default option.



See also



Account, Exit, LogName, Show, Start, Stop, Sysgen



338 Logon



 Look Command The Look command searches files for specific text.



LOOK



file ( pattern ...



2



LOOK



file ( option pattern ...



3



LOOK



pattern



Commands



1



file



»



file name with optional path; may include wild cards



pattern



»



text string to look for; may contain “regular expressions”



option



»



APPEND EXEC FILES



Operation



Mode 1—Search file for every instance of pattern. When more than one pattern is specified, each record or line is search for each of the patterns. Mode 2—Similar to Mode 1 except that file may be a text file containing a list of files (option FILES) or the result of the search may be output to FOUND.EXEC rather than displayed on the standard output device. Mode 3—Similar to Mode 1 except that the files searched are found in the currently defined default library or, if no default library is defined, all files using the default FILETYPE. For all modes, file is examined, record by record, looking for any and all instances of pattern. An exact match must occur between pattern and the text in the file. This exact match does not include the case mode of the characters. To perform inexact match comparisons, the pattern must contain regular expressions (see “Regular Expressions” on page 341). When Look displays its results on the console, it displays every line of the file that contains pattern. The pattern in the line is highlighted in reverse video and the line is identified with its line number: >look /theos/help/english/look.hlp ("THEOS" File: /THEOS/HELP/ENGLISH/LOOK.HLP:S 3  17 Unlike other THEOS commands, the options 38 >LOOK SYSTEM. THEOS 32.DEVNAMES ("Wyse"



Look



339



 When more than one pattern is specified, it means “or.” For instance: >look some.file ("the" "and" "of"



Will look in SOME.FILE for the characters “the” or “and” or “of.”



Commands



Options



If any of the following options are used, they must be specified at the beginning of the option list before any pattern is specified. APPEND



Indicates that, if file contains pattern, the complete path and file name of file is output to FOUND.EXEC, appending a line to any existing FOUND.EXEC.



EXEC



Indicates that, if file contains pattern, the complete path and file name of file is output to FOUND.EXEC, similar to the FileList EXEC option. Any existing FOUND.EXEC file is erased first. Thus, if no file contains pattern, the FOUND.EXEC will be empty. If APPEND is used instead of, or in addition to EXEC, any existing FOUND.EXEC is not erased and any file containing pattern causes lines to be appended to the end of the existing FOUND.EXEC. >look /Theos/Help/English/*.* (exec FILES >list found.exec (nohead &1 &1 &1 &1



/THEOS/HELP/ENGLISH/B3220.HLP:S &2 &3 &4 &5 &6 &7 &8 &9 &10 /THEOS/HELP/ENGLISH/BASIC32.HLP:S &2 &3 &4 &5 &6 &7 &8 &9 &10 /THEOS/HELP/ENGLISH/CHANGE.HLP:S &2 &3 &4 &5 &6 &7 &8 &9 &10 /THEOS/HELP/ENGLISH/COPYFILE.HLP:S &2 &3 &4 &5 &6 &7 &8 &9 &10



... FILES



Indicates that file is an ASCII stream file with each record in the file specifying a single file name. The file name specifications in this file may include the path to the file and wild cards. The SELECTED.EXEC and SELECTED.FILES files created by the FileList command and the FOUND.EXEC created by previous usage of the Look command, can be used for this specification file or you may create the file with an editor or application program. For instance, the FileList is used to create a list of files to be examined: >filelist /Theos/Help/English/*.* (10/1/01 exec append



340 Look



 A SELECTED.EXEC file now exists that lists all help files that have been changed since 10/01/2001. The following commands create a list of these files that contain “PRT” and then, using that list, examines the files that contain “PRT” to find files that also contain “SORT.” Commands



>look selected.exec (files exec "PRT" >look found.exec (files "SORT" File: /THEOS/HELP/ENGLISH/ACCOUNT.HLP:S 40 SORT When used with the TYPE or PRT ...



Notes



When one or more options are used, they must be specified before any pattern. If no option is used and the pattern looks like an option, a “null” option should be used. >look some.file ("" "EXEC"



If file is a “typeless” file description, there is no default library defined and the environment variable FILETYPE is defined, the value of FILETYPE is appended to file to form a complete file description with file name and file type. To examine a typeless file, you should specify the file description with a period terminator. See “FILETYPE” on page 103 THEOS Corona Version 5 Operating System Reference for more information about this environment variable. The search pattern is case-insensitive. The Look command can examine non-text files and it can examine nonstream data files. When Look opens file it opens it as a stream of bytes and does not consider the file’s organization. For instance, when file is an indexed data file it can find character patterns in deleted records. When file is not a stream text file the location that it reports is the offset from the beginning of the file, in bytes. Return Codes



The return code is set to zero if file does not contain pattern; otherwise, the return code is set to one.



See also



Compare, FileManager, List



Regular Expressions



pattern is actually a string expression called a regular expression. A regular expression is a sequence of characters consisting of literal characters and metacharacters. Literal characters are characters that match in a one-for-one relationship with the text in the file. For instance, the search pattern “abc” is comLook



341



 posed solely of literal characters. This pattern matches only when the text file contains a sequence of three characters that exactly equals ‘a,’ ‘b,’ and ‘c.’



Commands



In addition to the normal ASCII characters, you may specify certain control characters as literal characters. These control characters must be specified with the following codes: Specification



Meaning



\a



BELL or (Ctrl)+(G) code.



\b



Backspace or (Ctrl)+(H) code.



\f



Form-feed or (Ctrl)+(L) code.



\n



New-line or (Ctrl)+(J) code.



\r



Return or (Ctrl)+(M) code.



\t



Tab or (Ctrl)+(I) code.



\v



Vertical tab or (Ctrl)+(K) code.



\0



Null or (Ctrl)+(@) code.



\'



Single-quote character



\"



Double-quote character



Table 9: Regular Expression Control Character Specification



A metacharacter is a character or group of characters that represents something other than themselves. The wild cards allowed for file specifications by most of the THEOS commands are examples of metacharacters.



342 Look



 The following table shows all of the metacharacters allowed in regular expressions. Specification



Meaning Anchor to start of line.



\$



Anchor to end of line.



\. or \?



Commands



\^



Any character matches.



\@



Any letter matches (A–Z and a–z).



\#



Any digit matches (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0).



\\



Metacharacter escape. This is how a backslant literal character is specified.



\[



Start character set.



\]



End character set.



\{



Start general repeat specification.



\}



End general repeat specification.



\*



Repeat zero or more times.



\+



Repeat one or more times. Table 10: Regular Expression Metacharacters



• Regular Expression Anchors The first two metacharacters are called anchors. These anchor other text to the beginning or end of the record searched. For instance, the pattern "\^The"



means that “The” is searched for but only when it occurs at the beginning of a record. Similarly, "the\$"



is a pattern that means search for “the” at the end of a record. Note that this last pattern will not find “the” if there is a space at the end of the line.



Look



343



 • Regular Expression Wild Cards There are three “wild card” metacharacters that allow you to search for matches on any character (\.), any letter (\@) and any digit (\#). For example, the pattern:



Commands



"THEOS\#86"



will match any sequence of characters starting with “THEOS,” followed by any single digit, followed by an “8” and a “6.” Thus, it will match “THEOS186,” “THEOS286,” “THEOS386,” “THEOS486,” etc. • Regular Expression Character Sets Searching for one character of a set of characters is done by specifying a character set. For instance, to search for a hexadecimal digit you would specify a pattern containing: "\[0123456789ABCDEFabcdef\]"



This pattern specifies a match on any character that is either a digit, an uppercase ‘A’ through ‘F’ or a lowercase ‘a’ through ‘f.’ As a convenience, when specifying character sets there are two characters that have special meaning. The hyphen or dash character ( - ), when specified between two characters, indicates a character set range. For instance, the above pattern could have been specified with: "\[0-9A-Fa-f\]"



which means the set of characters ‘0’ through ‘9,’ ‘A’ through ‘F’ and ‘a’ through ‘f.’ Ranges specified with the hyphen character refer to ranges in the ASCII collating sequence. The hyphen does not have a special meaning when it occurs at the beginning or end of a character set specification. Thus, the pattern: "\[-0-9\]"



means the set of characters dash and the digits 0 through 9. The circumflex ( ^ ) is the other character that has special meaning when used in a character set specification. When the circumflex is used at the start of the character set specification, it means that it is an exception set. That is, it is a specification of characters that do not match. For instance, the pattern: "\[^A-Z\]"



344 Look



 means a match on any character except uppercase letters. When the circumflex is used in a position other than at the start, it is merely a character included in the set. • Regular Expression Repeat Counts



" \@\{4,6\}\[ .\]"



means that you want a match on a space, followed by four to six letters, followed by a space or period. It is not necessary to specify both the minimum and maximum repeat count values. A missing minimum value uses the default value of one for the minimum; a missing maximum value uses infinity for the maximum. Thus, a pattern repeat count of “\{5\}” means five or more occurrences; a pattern of “\{,5\}” means one to five occurrences. As a convenience, there are two special metacharacters for specifying common repeat counts. The metacharacter “\*” is a shorthand specification for the repeat count “\{0\}” meaning zero or more occurrences. The metacharacter “\+” is a shorthand specification for the repeat count “\{1\}” meaning one or more occurrences.



Look



345



Commands



A search pattern may be repeated by using the repeat metacharacters “\{” and “\}” to enclose the minimum and maximum repeat counts. For instance, the pattern:



 Commands



346 Look



 Lowcase Command Filter Lowcase copies a file to the standard output device, converting all letters to lowercase.



LOWCASE



2



LOWCASE



file



file



»



Command synonym: Operation



Commands



1



file name with optional path; wild cards are not allowed LC



Mode 1—file is copied to the standard output device with all uppercase letters converted to lowercase. The original file is unchanged. >lowcase /Theos/OS/Message/English/synonym.txt account 3 archive 2 asm32 3 attach 1 ... >lowcase /Theos/OS/Message/English/synonym.txt > synonym.list



Mode 2—Copies standard input to standard output, converting all uppercase letters to lowercase. This form is normally used only in a pipe. However, if standard input is the console, records are copied until a (Ctrl)+(D) is encountered, signaling the end of the input file. >filelist *.* | lowcase > file.list



Notes



The command name LC is a synonym to the Lowcase command. It is not a separate program but only an entry in the /THEOS/OS/MESSAGES/language/ SYNONYM.TXT file and, if standard synonyms are disabled (see “Account” on page 13 of this manual and “STDSYN” on page 110 of the THEOS Corona Version 5 Operating System Reference), this synonym name may not be allowed.



Restrictions



file must be a stream file.



See also



Upcase



Lowcase



347



 Commands



348 Lowcase



 Mailbox Command The Mailbox command sends a message to another user’s mailbox or retrieves your messages.



MAILBOX



user



2



MAILBOX



user text



3



MAILBOX



user file



4



MAILBOX



( option



file



»



file name with optional path



text



»



message text to send



user



»



account name to send mail to



option



»



PURGE PURGE *



Commands



1



The first three modes of the Mailbox command send mail to other users. The fourth mode retrieves or removes your mail. Operation



Mode 1—This is the normal, multi-line mode of the Mailbox command. When the command is entered, you are prompted to enter one or more lines of text. To end the “mail,” press (EnterÌ˛) at the beginning of a line with no text or spaces in it. >mail shirley Enter message text terminated by empty line. Shirley,(EnterÌ˛)



(EnterÌ˛) The company picnic has been scheduled in August.(EnterÌ˛)



(EnterÌ˛)



Please call me by Friday so we can arrange a planning(EnterÌ˛) meeting as we have a lot to do in the next two weeks.(EnterÌ˛)



(EnterÌ˛) >



To enter a blank line without ending the message, remember to enter at least one space before pressing (EnterÌ˛). After a line is entered you cannot edit it. You can prepare a long message with an editing program and then send it with Mode 3.



Mailbox 349



 Mode 2—For short, single-line messages, this mode allows you to specify the message text on the command line. If the text contains commas, quotation marks or other punctuation characters, you should enclose the entire message in quotation marks. >mail dave Please call me when you get in. It's important.



Commands



>mail eric "Your package arrived, and it's big. Call me."



Single-word messages cannot be sent with this mode because Mailbox will assume that the single word is a file name and it will try to use Mode 3. Mode 3—Sends a previously created text file to account’s mailbox. Use this mode to send large messages to a user or to send the same message to several user accounts. Create the file with LineEdit, WindoWriter or a customized application. >mail accntg my.mail



Mode 4—This mode retrieves your mail or removes old mail from your mailbox. >logon accntg



>mailbox



As each message is displayed you are asked if you want to delete it. If you respond (Y) then the message is marked as deleted (it is not physically



350 Mailbox



 deleted until the system manager uses the PURGE option described below). Respond with (N) if you do not want it deleted at this time. Each time that Mode 4 is used without one of the PURGE options, all mail for your account is displayed whether it has been read before or not. When a message is read and marked as deleted it is not displayed again.



Notes



The two PURGE options can be used only when you are logged onto the SYSTEM account (id zero) and require a privilege level of five. PURGE



Removes all mail that has been marked as deleted.



PURGE *



Removes all mail that has been marked as deleted and all mail that has been read but not deleted.



Users are notified that there is mail waiting for them when they log onto the account (see “Logoff” on page 335). They can then use Mode 4 of the Mailbox command to read their mail. Mail for all users is saved in the file SYSTEM.MAILBOX:S. This file is created automatically the first time that Mailbox is used. Mail is only removed from this file with the PURGE option. Do not confuse this command with THEO+Mail and the mail sent and received over the Internet with that command. Mailbox operates on mail sent by the Mailbox or Msg commands only.



Restrictions



The PURGE and PURGE * options require that you be logged onto the SYSTEM account (account id=0) and that you have a privilege level of five.



See also



Logon, Msg , Reminder



Mailbox 351



Commands



Options



 Commands



352 Mailbox



 MakeBoot Command EXEC MakeBoot creates an Emergency Boot Diskette using the current operating system and



configuration.



drive Operation



drive »



Commands



MAKEBOOT



optional disk drive attachment letter



When MakeBoot is invoked it displays the following menu screen.



Use the normal menu selection keys to select the desired function. Use existing floppies. Choose this menu item if the diskettes are already formatted. MakeBoot clears the existing directory and resizes it to gain some additional space. Format floppies first. Choose this menu item if the diskettes are not formatted. MakeBoot formats the diskettes using the highest capacity available on the drive. Then it copies the necessary files. Exit. This menu item exits MakeBoot without modifying the diskette. Notes



MakeBoot requires two diskettes to hold the necessary files for booting the



computer. Be sure that you have these diskettes available before starting the process. MakeBoot will ask you to put the first diskette in the drive and then it will



format the diskette (if that option was selected), copy the necessary files to the diskette and then ask for the second diskette. It then formats that diskette (if selected) and copies the necessary files to that diskette.



A bootstrap loader is written to the first sectors of the first diskette. There will be some space available on the second diskette and you may copy additional files and programs if there is sufficient room for them.



MakeBoot 353



 MAKEBOOT Files:



The files copied to this “Emergency Boot Diskette” include:



Commands



File Operating system



/THEOS/OS/NUCLEUS.SYS



Command string interpreter



/THEOS/OS/CSI.SYS



Device drivers



/THEOS/DRIVER/CLASS901.SYS /THEOS/DRIVER/DEV1.SYS /THEOS/DRIVER/DEV2.SYS /THEOS/DRIVER/DEV3.SYS /THEOS/DRIVER/DEV64.SYS /THEOS/DRIVER/DEV101.SYS /THEOS/D RIVER/FORM2.SYS



354 MakeBoot



SYSGEN configuration



/THEOS/CONFIG/SYSGEN.CFG /THEOS/CONFIG/INSTL IST.CFG /THEOS/CONFIG/L ANGCODE.CFG



Accounting structure



/THEOS/CONFIG/ACCOUNT.BIN



System support files



/THEOS/OS/L OADER3.SYS /THEOS/OS/L OADER4.SYS /THEOS/OS/L OADER5.SYS /THEOS/OS/PCMCIA.SYS /THEOS/OS/CLOCK.SYS /THEOS/CONFIG/DEVNAMES.TXT /THEOS/OS/RESMGR.SYS /THEOS/OS/M BR.SYS /THEOS/OS/L OAD04GB.SYS /THEOS/OS/L OAD0LFS.SYS /THEOS/OS/SESSMAN.SYS /THEOS/OS/WM.SYS /THEOS/OS/M ESSAGE/ENGLISH/K EYWORD.BIN /THEOS/OS/M ESSAGE/ENGLISH/M ESSAGE.BIN /THEOS/OS/SCSI1.SYS /THEOS/OS/SCSI2.SYS /THEOS/OS/SCSI3.SYS /THEOS/OS/SCSI4.SYS /THEOS/OS/SCSI5.SYS /THEOS/OS/I2OMSG.SYS /THEOS/OS/USB.SYS /THEOS/OS/M ESSAGE/ENGLISH/SYNONYM.TXT



Commands



/THEOS/COMMAND/ATTACH.CMD /THEOS/COMMAND/COPYFILE.CMD /THEOS/COMMAND/DISK.CMD /THEOS/COMMAND/FILEL IST.CMD /THEOS/COMMAND/LOGON.CMD /THEOS/COMMAND/M OUNT.CMD /THEOS/COMMAND/SETUP.CMD /THEOS/COMMAND/SYSTEM.CMD /THEOS/COMMAND/TBACKUP.CMD



 File Command support files



1. The specific class code currently attached to the main console. When this “Emergency Boot Diskette” is booted, there are sufficient commands to format the hard disk, attach different devices, restore from tape, “system” to the hard disk, etc. It is not intended as a general boot disk. There may be sufficient space available on the disk to add more commands. If you do, remember to include any support files needed by the command (such as menus). You should not copy help files to this diskette. If any significant changes are made to the system on the hard disk, you should recreate the “Emergency Boot Diskette.” Significant changes would include an upgrade to the operating system, new or changed account environments, hard disk controller change and a change in the main console configuration or attachment. Defaults



The default drive is F, which is normally the first floppy drive.



Restrictions



MakeBoot can only be run if you are logged onto the system account.



The diskette must be 1.44MB. 1.2MB diskettes are too small to hold the necessary files. Using the Diskettes



Refer to the section “Booting with the Emergency Boot Diskettes” on page 28 THEOS Corona Version 5 Operating System Reference for a description of how these disks are used.



See also



CopyFile, Disk



MakeBoot 355



Commands



/T HEOS/MENU/ENGLISH/ATTACH.MNU /T HEOS/MENU/ENGLISH/DISK.MNU /T HEOS/MENU/ENGLISH/FILELIST.MNU /T HEOS/MENU/ENGLISH/FORM2.MNU /T HEOS/MENU/ENGLISH/RESTORE.MNU /T HEOS/MENU/ENGLISH/SETUP.MNU /T HEOS/MENU/ENGLISH/TBACKUP.MNU /T HEOS/MENU/ENGLISH/TLOGON.MNU /T HEOS/MENU/ENGLISH/LOADER5.MNU



 Commands



356 MakeBoot



 Message Command The Message command displays or maintains the /THEOS/OS/MESSAGE/language/MESSAGE.BIN file.



MESSAGE



* ( PRTnn



2



MESSAGE



3



MESSAGE nnn operand...



nnn



»



message number to display



operand



»



optional argument used by the message



Operation



Commands



1



Mode 1—Displays all of the messages defined in /THEOS/OS/MESSAGE/language/MESSAGE.BIN. >message * 0: 1: 2: 3:



Logon please: \a Password? Command not found.\n Insufficient memory.\n



...



Mode 2—This is the message maintenance mode. When this mode is entered, you are prompted to enter the message number: >message Enter message number:



At this prompt enter either the number of the message you want to view or change, or press (EnterÌ˛), (Esc) or (F9) without a number to exit. When a number is entered the current definition is displayed and you are asked for the new definition: >message Enter message number: 3 Old text: Insufficient memory.\n New text:



Message



357



 To leave the message unchanged, press (EnterÌ˛), (Esc) or (F9) without any characters or spaces. To change or define a message, enter the new text. Messages may be a maximum of 64 characters in length. For information about message content and codes used, refer to “Message File Syntax” below. Commands



When the new text for the message is entered, press (EnterÌ˛) and you are prompted for another message to change. Mode 3—Displays message number nnn on the console (not the standard output device). If the message uses variables, the operands are used for the value of these variables. Any missing operands are displayed with an ellipsis. >message 7 Invalid command syntax. >message 19 File "..." not found. >message 19 abc.def:g File "ABC.DEF:G" not found. >message 117 "Wednesday" "August" 7 2001 Date is set to Wednesday, August 7, 2001.



Options



PRTnn



Message File Syntax



Message text may contain plain text, display codes, video attributes, variable arguments and conditional expressions. Plain text includes all of the ASCII displayable characters (letters, digits, punctuation, etc.).



Indicates that Message is to print the messages on the attached printer number nn. The option keyword PRT may be specified as PRT, PRINT or PRINTER. As a convenience, PRINTER1 may be specified as P.



• Display Codes There are four display codes that can be embedded in a message: Code



358 Message



Meaning



\a



Sound the console bell.



\n



Start a new display line.



\t



Output spaces to next tab stop.



\\



Output a single backslant character.



 • Video Attributes Video attributes such as reverse video, blink, etc. are specified by using their octal values preceded by a backslant, zero. Some of the common codes include: Meaning



\016



Reverse video on.



\017



Reverse video off.



\013



Underline on.



\026



Underline off.



\035



Blink on.



\036



Blink off.



\04



Half intensity on.



\05



Half intensity off.



\0202



Status line start.



\0203



Status line end.



Commands



Code



• Variables Message text may specify that variable information will be inserted at the time the message is displayed. For instance, message 19 displays as “File "xxx" not found.” To indicate that the file name is inserted between the quotation marks, a variable number is used. In message text, variables are always indicated by using a pair of “curly brace” characters to surround a variable number. Messages containing only one variable use variable number zero. Messages with more than one variable use numbers one, two, three, etc. For instance: 19: File "{0}" not found.\n 34: Device "{1}" is already attached to process {2}.\n



• Conditional Expressions Messages can use conditional expressions to evaluate the value of a variable and display different information depending upon that value. The general syntax for a conditional expression is: {variable?value1=text1,value1=text2,...,text}



The value of variable is tested to see if it is value1, value2, etc. If it matches any of those values, then the corresponding text is output as the value of the expression. When a term does not have an equal sign it means Message



359



 that this is the “otherwise” clause and that text is output when the variable is not one of the previously listed values. An asterisk means that the original value of variable is used. For instance, message 105 is defined as: 105: {0?0=No,1=One,*} file{0?1=,s} changed.\n



Commands



This message will be displayed three different ways depending upon the value of the variable zero. >message 105 0 No files changed. >message 105 1 One file changed. >message 105 2 2 files changed.



As you can see from the second variable expression {0?1=,s}, you can specify that nothing is output when the variable is a specific value. This expression states that if variable 0 is a “1,” output nothing; otherwise output an “s.” Notes



Although the display produced by Mode 1 is similar to the display produced by the List command, there are two significant differences: 1. The message numbers displayed by the Message command are numbered from zero, corresponding to the numbers used by programs to request one of the messages. 2. Embedded control codes are displayed graphically rather than interpreted. For instance, a new-line is displayed as \n.



Cautions



The /THEOS/OS/MESSAGE/language/MESSAGE.BIN file contains all of the message text used by the operating system and its utilities. Changing an existing message can affect many programs. You should not use any of the currently unused message numbers for your own purposes. All unused numbers are reserved for operating system usage. As updates to the software require new message text, they are added to this file. Also, this file is replaced in its entirety whenever the operating system is installed or updated.



See also



360 Message



Keyword



 Mixer Command The Mixer command allows you to set the volume for various sound devices and files.



MIXER When invoked, the Mixer command displays the Mixer control screen:



Use your mouse or the (TabÌ¢) and (ñÌShift)+(TabÌ¢) keys to position to fields that you want to change and then enter the desired values. The top line of values set the left channel volume for the device and the middle line sets the right channel volume. The bottom check boxes mute or unmute the devices. The volume values are set by using the (˚) and (˙) keys or by using the mouse and clicking on the upper or lower portion of the object. Volume values range from 0 (off) to 31 (maximum). Master



Controls the volume for all devices. The actual volume for a specific device is a combination of the value for the device and the value specified here.



Wave



Controls the volume of WAV sounds (see “Play” on page 455)



Midi



Controls the volume for playing midi sounds (not supported at this time).



Mixer 361



Commands



Operation



 Commands



CD



Controls the volume of the sounds played from an audio CD (see “CDPlayer” on page 59).



Line



Controls the line-in component of the sound card.



Mic



Controls the microphone input volume of the sound card.



Notes



This command only controls the volume of sounds played from the main console. Sounds played during a TWS session are controlled by the computer and software on the client system.



Restrictions



You must have a sound card configured. Refer to the THEOS Corona Version 5 Operating System Installation and Setup Guide for a description of Setup SndCard.



See also



CDPlayer, Play



362 Mixer



 MkDir Command The MkDir command creates a new subdirectory.



MKDIR



directory



( option »



new subdirectory name; may include path



option



»



SIZE



Command synonym: Operation



Commands



directory



MD



Creates a new, empty subdirectory named directory. >tree / >mkdir subdir >tree / subdir >md subdir/sub >tree / subdir sub



You can create a directory on another account by prepending the account name to the path for directory. For example: >mkdir account\subdir



The above command creates the directory SUBDIR in the account named ACCOUNT. Options



SIZE



Specifies the initial size of the new directory. The number of initial entries is specified following the keyword SIZE. >mkdir Example (size 48



When SIZE is specified, the new directory will be created large enough to contain the requested number of directory entries if the file names for each directory entry use 8.8 names. When this option is not used, the initial size of the directory is suffiMkDir



363



 cient to hold about 130 files with 8.8 character file names. Use the SIZE option if you want to create a small directory size or one that is much larger than the default.



Commands



Notes



Directories in the Corona operating system are automatically extendable. When a directory becomes full and a request is made to add another file to it, the directory is made larger. The SIZE option should be used if you know that a directory will need to contain a certain number of files. Directory access is more efficient if it is not an extended directory but was created sufficiently large enough to start with. Directory names may be “long file names.” Unlike other commands, it is not necessary to enclose a long directory name within quotes unless you want to maintain the casemode of the characters used in the name. All tokens in the directory portion of the command line are interpreted as part of the directory name. For instance: >mkdir "THIS IS A LONG DIRECTORY NAME" >mkdir this is a long directory name



The above two commands will perform the same operation and create the same directory name. The command name MD is a synonym to the MkDir command. It is not a separate program but only an entry in the /THEOS/OS/MESSAGE/language/ SYNONYM.TXT file. If standard synonyms are disabled (see “Account” on page 13 and “STDSYN” on page 110), this synonym name may not be allowed. Defaults



If no account name is specified for directory, the new subdirectory will be owned by the current account. If no path is specified for directory, the new subdirectory is created as a subdirectory to the current working directory.



Restrictions



directory must not be the name of an existing file or subdirectory and it may not be a member of a library. directory should not be /PIPE because this is a reserved name used by the system. You may, however, create a subordinate directory named PIPE, such as: /PRIVATE/PIPE. Subdirectories may be 21 levels deep. This means that /A/B/C/D/E/F/G/H/I/J/K/ L/M/N/O/P/Q/R/S/T/U is valid, but adding another directory under U would be beyond the limit.



See also



ChDir, Create, PWD, RmDir



See “Directories and Files” on page 131 of the THEOS Corona Version 5 Operating System Reference for additional information about directories and subdirectories. 364 MkDir



 More Command Filter More copies a text file to the standard output device with page wait and browse capabilities.



MORE



file... ( nnn



2



MORE



( nnn



file



»



file name with optional path; wild cards are not allowed



nnn



»



number of lines to display per page



Operation



Commands



1



Mode 1—Copies file to the standard output device. If standard output is the console, page-waits are performed and browsing capabilities are present. >more /theos/config/devnames.txt



When the console screen is full, More displays its prompt on the last line. The MORE prompt consists of the word “More” and the amount of the file that has been displayed so far. --More--(52%)



At this time you may use any of the browse keys described on page 366. Multiple files may be specified by listing the file names on the command line, one file name after the other. When multiple files are listed this way, the (N) and (P) browse keys are enabled. >more one.file two.file three.file



Mode 2—This mode applies when More is used in a pipe. >number /theos/os/message/english/synonym.txt | more



Options



nnn



Specifies the console page depth to use. When this option is not specified, the console’s attached screen size is used. The screen size can be changed during the display with the (Z) browse key.



More



365



 Browse Keys



When the More prompt is displayed at the bottom of the screen you may use the special More browse keys.



Commands



Key



Action



(EnterÌ˛)



Display next line of file.



(ÌÌSpaceÌÌ)



Display next screenful of file.



(D) nnn(F)



Display next half-screenful of file. Skip next nnn screens.



(N)



Skip to next file.



(P)



Skip back to previous file.



(Q)



Quit.



nnn(S)



Skip nnn lines.



nnn(Z)



Set screen depth to nnn and display next screenful of file.



(/)expression



Search for text matching expression. Expression is a regular expression as described on page 341.



(!)command (?)



Execute CSI command and return. Display browse help screen. Table 11: More Command Browse Keys



Notes



When used in a pipe, More should be the last command in the pipe so that its output goes to the console and you can browse through the file using the keyboard. If file is a “typeless” file description, there is no default library defined and the environment variable FILETYPE is defined, the value of FILETYPE is appended to file to form a complete file description with file name and file type. To list a typeless file, you should specify the file description with a period terminator. See “FILETYPE” on page 103 of the THEOS Corona Version 5 Operating System Reference for more information about this environment variable.



Defaults



The default screen depth is the console’s attached page size.



Restrictions



file must be an ASCII stream file.



See also



CopyFile, List, Tee



366 More



 Mount Command Mount tells the operating system to reread the label information from a drive because the disk might have been changed.



MOUNT



drive



Operation



»



disk drive letter



This program assumes that the disk in the drive might have been changed. Any current information about drive is disregarded and the disk drive is instructed to recalibrate its heads. This is a process that moves the read/ write head to its home position. If supported by the drive mechanism and controller, the heads are moved slowly. Once the heads are in a known position, the first sectors of the disk are read and the information is saved.



Notes



If a disk is changed and the Mount command is not used, you will receive a message “Disk drive changed, need “XXXX” -” the next time that drive is accessed.



Cautions



Use the MOUNT command every time that a disk is changed, even if the new disk has the same format as the prior disk. If the new disk has the same label as the prior disk, THEOS will not know that the disk has changed and may use information saved from the prior disk to do writes!



Return Codes



This command reads the first sectors of the disk and, depending upon what it finds, sets the return code as follows: Return Code 0



Meaning/Message THEOS disk, mounted successfully



201



Disk not ready



203



Disk not initialized



204



Data transfer error



205



Sector not found



206



Track not found



207



Sector address error



563



Disk does not have a THEOS file system on it



Restrictions



You cannot Mount the S drive. Use the System command instead.



See also



Attach, Disk, Reboot, System



Mount



367



Commands



drive



 Commands



368 Mount



 Move Command Move a file or group of files from one location to another.



MOVE from-file



to-file ( options



2



MOVE from-file



to-drive ( options



3



MOVE file ( FILES options



4



MOVE ( options



Commands



1



file



»



file name of specifications file, with optional path



from-file



»



file name of source file, with optional path; may contain wild cards



to-file



»



file name of destination file, with optional path; may contain wild cards



to-drive



»



disk drive letter for destination files



options



»



KEEP NOQUERY NOTYPE QUERY



Operation



REPLACE SUBDIR TYPE



Mode 1—Each file matching from-file is copied to to-file, similar to the CopyFile command. Both the from-file and the to-file may use wild card specifications. >MOVE /programs/some.command:s /private/programs/newname.command:d



Mode 2—Each file matching from-file is copied to to-drive using the same file name as the source. A >Move some.files f (notype >move *.basic =.basiccpy:d (keep noquery



Mode 3—file must be a text file containing one or more records. Each record in this file specifies a from-file and either a to-file or a to-drive specification. For each line in file, a Move is performed. Wild cards may be used. >Move listof.files (files



Move



369



 This mode of the Move command is convenient when one or more sets of files are repetitively moved. Merely edit a file containing file description pairs, such as:



Commands



>edit daily.files customer.master:s /prior/customer.master:s customer.history:s /prior/customer.history:s general.ledger.*:s /prior/=.=.=:s check.*:s /prior/=.= >move daily.files (file noquery notype keep replace



Mode 4—This is the interactive form of the Move command where you are prompted to enter a from-file and a to-file or to-drive. This can be repeated until all of the desired files are specified and moved. The operation is terminated by entering a blank line. Options



KEEP



Tells Move to not erase the source file after it is successfully moved to the destination. With this option specified, the Move command operates similar to a CopyFile command.



NOQUERY



Tells Move to not ask for confirmation before moving each file. This is a default option when wild cards are not used. >move gl.* f (noq "GL.MASTER:S" moved to "GL.MASTER:F". "GL.JOURNAL:S" moved to "GL.JOURNAL:F". "GL.HISTORY:S" moved to "GL.HISTORY:F".



To disable this option use the QUERY option. NOTYPE



Do not display the results of each file moved on the standard output device. The general result message (the “nn files copied.” message displayed prior to exiting Move) is also suppressed with this option. >move Ok to Ok to Ok to



gl.* move move move



f (not "GL.MASTER:S" (Yes,No,All) Y "GL.JOURNAL:S" (Yes,No,All) Y "GL.HISTORY:S" (Yes,No,All) Y



To disable this option use the TYPE option.



370 Move



 QUERY



Tells Move to “query” or ask if each file matching the source file specifications is to be moved. This is a default option when wild cards are used. >move *.data i Ok to move "CUSTOMER.DATA:S" (Yes,No,All)



To disable this option use the NOQUERY option. REPLACE



Allows a file to be moved even if it already exists at the destination location. Normally, when the destination file name already exists, Move will not perform the copy. This option tells Move that if it already exists it should erase the existing file and replace it with a copy of the from-file. If the destination file does not exist, this option has no effect. >move *.data:s f (replace noquery keep "HISTORY.DATA:S" replaces "HISTORY.DATA:F". "CUSTOMER.DATA:S" replaces "CUSTOMER.DATA:F". "NEW.DATA:S" moved to "NEW.DATA:F". 3 files moved.



SUBDIR



When from-file is a subdirectory specification, this option specifies that all of the subdirectories of from-file, and the contents of those subdirectories, are moved to to-file or to-drive. If the subdirectories do not exist at the destination location they are created. >move *.* /Copy:i (subdir replace noquery keep SYSTEM\samples/tws/images/animals/bear.jpg:S moved to /COPY/tws/images/animals/bear.jpg:I SYSTEM\samples/tws/images/animals/bird.jpg:S moved to /COPY/tws/images/animals/bird.jpg:I SYSTEM\samples/tws/images/animals/buttfly.jpg:S moved to /COPY/tws/images/animals/buttfly.jpg:I SYSTEM\samples/tws/images/animals/wolf2.jpg:S moved to /COPY/tws/images/animals/wolf2.jpg:I SYSTEM\samples/tws/images/animals/cows.jpg:S moved to /COPY/tws/images/animals/cows.jpg:I



TYPE



A default option that displays the status message “... moved to ...” after each file is successfully moved. To disable this option use the NOTYPE option. Move



371



Commands



When the “Ok to move” question is asked you may respond with a (Y) for yes, (N) for no or (A) for all. Responding with (A) means yes to this file and all remaining files are moved without being queried. Respond with (Esc) to cancel the copy operation.



 The source or from-file is erased unless the KEEP option is specified.



Defaults



The QUERY option is a default if from-file contains wild cards. TYPE is a default option.



See also



CopyFile, Erase, Rename



Commands



Notes



372 Move



 Msg Command Similar to the Mailbox command, Msg sends a message to another user. However, if the user is logged on, the message is displayed on their console immediately.



MSG user ( option



2



MSG user message ( option



3



MSG * ( option



4



MSG * message ( option



user



»



account name or process number



message



»



optional message text to transmit



option



»



TITLE



Operation



Commands



1



Mode 1—This is the multi-line mode of the Msg command. When the command is invoked, you are prompted to enter one or more lines of text. To end the message press (EnterÌ˛) at the beginning of a line with no text or spaces in it. >msg Ted Enter message text terminated by empty line. Call me as soon as you get back from lunch. Something(EnterÌ˛) important has come up that changes EVERYTHING!(EnterÌ˛)



(EnterÌ˛) On Ted’s console, the message appears in a pop-up window as:



The receiving person must acknowledge the message by pressing (Esc) before it is erased. To enter a blank line without ending the message, remember to enter at least one space before pressing (EnterÌ˛).



Msg



373



 Mode 2—For short, single-line messages, this mode allows you to specify the message text on the command line. If the text contains lowercase text, commas, quotation marks or other punctuation characters that you want in the message, you should enclose the entire message in quotation marks. >mail dave Please call me when you get in. It's important.



Commands



>mail eric "Your package arrived, and it's big. Call me."



These single-line messages are displayed on the receiving user’s screen in a pop-up window just like the Mode 1 messages. Mode 3—Similar to Mode 1 except that the message is transmitted to all users logged onto the system. This mode requires a privilege level of five. The message is only sent to the active session of a console with multiple sessions defined. Mode 4—Similar to Mode 2 except that the message is transmitted to all users logged onto the system. This mode requires a privilege level of five. The message is only sent to the active session of a console with multiple sessions defined. Options



TITLE text



Notes



When user is specified with an account name, and more than one user is logged onto that account, all users logged onto that account receive the message. When there are no users logged onto the account name, you are asked if you want to put the message in the user’s mailbox. When this happens, the operation is identical to the Mailbox command.



Specifies an alternate title for the receiving user’s message window. The title is displayed in the top frame, centered. When this option is not used the default title of “ MSG From your-account (Pid=your-pid) ” is used.



>msg accounts "Where is my pay check?"



The “Receive messages” field in the account environment prevents messages from being sent directly to a user’s screen. Msg checks this switch on the user’s environment and if is is disabled, informs you and allows you to put the message in the user’s mailbox.



374 Msg



 When the message is directed to a user of a multiple-session console, the message is displayed on that session only. If the session is not active it will not appear until the user switches to the session. Messages directed to all users (* specification) are displayed only on the active session of a multiple-session console. When a message is sent to a user that already has an unacknowledged message on its screen, the new message is queued and is not displayed until the prior message is acknowledged and cleared from the display. When a message is sent to an account name and there is more than one user logged onto that account name, all of those users will receive the message. Restrictions



Mode 3 and Mode 4 require a privilege level of five.



You cannot send a message to yourself. See also



Mailbox



Msg



375



Commands



The “Receive messages” field status is ignored in Mode 3 and Mode 4: The message is sent to all users that are currently logged on.



 376 Msg



Commands



 Net Command The Net command controls Corona networking and provides a common interface for many of the functions and simple clients available Corona. NET



2



NET ARP



-a [ -N if-addr ]



3



NET ARP



-s ip-addr hw-addr [ if-addr ]



4



NET ARP



-d ip-addr [ if-addr ]



5



NET BROWSE



6



NET EXEC



7



NET RECEIVE



8



NET SEND file



9



NET SHARE



10 NET USE



Commands



1



program ( program-options exec-options file



destination-file ( send-rec-options



destination-file ( send-rec-options



share-name



unc-name



path



password



access-mode comment



password



11 NET SERVER 12 NET START 13 NET STOP



server-name server-name



14 NET IPCFG 15 NET function 16 NET service Operation



parameters host parameters



Mode 1—NET: Invoke the Net command in interactive mode. In this mode you are presented with choices allowing you to Ping, Lookup, Trace, IP Cfg, DNS, WhoIs, Finger and Scan. See “Net Interactive” on page 379. Mode 2—NET ARP: Display the Address Resolution Protocol table. See “Net ARP” on page 388.



Net



377



 Mode 3—NET ARP: Assign an IP address to a network interface card.See “Net ARP” on page 388. Mode 4—NET ARP: Delete an IP address from a network interface card.See “Net ARP” on page 388.



Commands



Mode 5—NET BROWSE: Browse the local network looking for Network File System servers. See “Net Browse” on page 390. Mode 6—NET EXEC: When executed from a client workstation connection, execute a program on the client system. See “Net Exec” on page 391. Mode 7—NET RECEIVE: When executed from a client workstation connection, receive a file from the server system. See “Net Receive” on page 393. Mode 8—NET SEND: When executed from a client workstation connection, send a file to the server system. See “Net Send” on page 393. Mode 9—NET SHARE: Display or maintain share names to other Network File System directories. See “Net Share” on page 399. Mode 10—NET USE: Display or maintain drives names for attachable shared drives. See “Net Use” on page 399. Mode 11—NET SERVER: Show the status of all of the network servers. This form also allows you to start and stop the servers. See “Net Server” on page 401. Mode 12—NET START: Start the network or a specific network server. See “Net Start” on page 402. Mode 13—NET STOP: Stop the network, a specific network server or all network servers. See “Net Stop” on page 402. Mode 14—NET IPCFG: Displays the basic configuration information for this network. See “Net IPCFG” on page 408. Mode 15—NET function: Perform one of the network functions available with Corona networking. See “Net” on page 409. Mode 16—NET service: Use one of the TCP/IP simple services. See “Net service” on page 411. Restrictions



The Net command requires at least a privilege level of one. Higher privilege levels may be required of specific functions of the command.



See also



DialNet, FTP, NetTerm, Ping, Quote, Setup, Telnet, THEOS WorkStation Client



378 Net



 Net Interactive Command The interactive form of the Net command presents the following form allowing you to use any of functions shown. These functions, for the most part, are useful in diagnosing problems that you may have with your local network or with accessing a remote server.



Host



Enter the domain name or dotted IP address of the host that you want to test.



Go



Select this button to perform the query. This button is also the default for this form. This means that if you use the (Enter) key for the Host fields, this Go button is selected automatically.



For a description of the trace display refer to the Ping command on page 453.



See also



Net Ping function, Ping command



Net Interactive



379



Commands



The Ping button provides a means of testing if a host can be accessed over the network or whether or not it is responding.



 Commands



The Lookup button is used to resolve a domain name into an IP address or to perform a reverse lookup of an IP address into a domain name.



Host



Enter the domain name or dotted IP address of the host that you are interested in.



Go



Select this button to perform the query. This button is also the default for this form. This means that if you use the (Enter) key for the Host fields, this Go button is selected automatically.



For a description of the trace display refer to the NsLookup command on page 425. See also



NsLookup



380 Net Interactive



 The Trace button traces the route that a packet takes to get from this machine to a target host.



Commands



Host



Enter the domain name that you want to inquire about. You may also enter the dotted IP address.



Go



Select this button to perform the query. This button is also the default for this form. This means that if you use the (Enter) key for the Host fields, this Go button is selected automatically.



For a description of the trace display refer to the TraceRT command on page 675. See also



TraceRT



Net Interactive



381



 Commands



The IP Cfg button displays the basic configuration information for this system.



The IPCFG display shows the information for this computer system’s network configuration. See also



Net IPCFG



382 Net Interactive



 The DNS button allows you to see what is returned by the Domain Name System when your system requests various types of records from the server.



Commands



Domain



Enter the domain name that you want to inquire about. You may also enter the dotted IP address.



Record



Select one of the offered records (Address, MX, NS, SOA). The DNS server identified in the next field (Server) will be queried for this specific record.



Server



Enter the domain name or dotted IP address of the DNS server that you want queried. It is possible that, if that server does not know the answer, it might pass the query onto another DNS server. This field is initially filled in with the DNS server address that has been configured for this systems network access.



Go



Select this button to perform the query. Note, this button is the default for this form. This means that if you use the (Enter) key for any of the other fields, this Go button is selected automatically.



Net Interactive



383



 Commands



The information displayed by this function is always in the general form: Id................ nnnn Length............ length of response Code.............. xxxxxxxxxxxxxxxxxxxxxxxx QdCount........... number-of-questions AnCount........... number-of-answer-records NsCount........... number-of-nameserver-records ArCount........... number-of-address-records Question 1: domain-name Type: n=record Class: 1=IN



Following this portion of the reply is the information specific to the query. That is, information about the domain’s address, mail exchanges, name servers or start of authority data.



384 Net Interactive



 The WhoIs button allows you to issue a request to the Internet domain database to get the registration information about a second-level domain name.



Commands



Host



Enter the second-level domain name that you want to inquire about. A second-level domain name is a name with only two parts, a .com, .us, .org, etc. (first-level) and the domain name for the desired entity such as theos, microsoft, ibm, etc. It does not have any other parts of a URL such as www, ftp, etc. Alternately, you may enter the administrative contact name or the #handle for the administrative contact of the domain in question. However, not all registrars support querying by name or handle.



Go



Select this button to perform the query. This button is also the default for this form. This means that if you use the (Enter) key for the Host fields, this Go button is selected automatically.



The format and content of the registration database may vary depending upon the administrator for the first-level domain of the requested domain. See also



WhoIs



Net Interactive



385



 Commands



The Finger button allows you to issue a finger request to a mail server.



Host



Enter one of the two forms of requesting finger information username@server This syntax requests information about a



specific user account of the mail server. @server



Go



This syntax requests information about the list of user accounts on the mail server.



Select this button to perform the query. This button is also the default for this form. This means that if you use the (Enter) key for the Host fields, this Go button is selected automatically.



Many mail servers do not support a Finger server or do not have it enabled for security reasons. Mail servers that do support it might not have enabled the capability to perform a general request with the “@server” request. See also



Finger



386 Net Interactive



 The Scan button allows you to perform a scan of a network computer looking for active servers.



Commands



Host



Enter the second-level domain name that you want to inquire about. A second-level domain name is a name with only two parts, a .com, .us, .org, etc. (first-level) and the domain name for the desired entity such as theos, microsoft, ibm, etc. It does not have any other parts of a URL such as www, ftp, etc.



Go



Select this button to perform the query. This button is also the default for this form. This means that if you use the (Enter) key for the Host fields, this Go button is selected automatically.



From



Enter the lowest port number that you want scanned.



To



Enter the highest port number that you want scanned.



Known ports only Check this field if you want to limit the scan to the com-



mon, known port numbers. These known port numbers are listed in the file /THEOS/CONFIG/SERVICES.TXT:S. When the Go button action is selected, the Host is queried for every port number between From and To or, if Known ports only is checked, the common, known port numbers between From and To. Each port that responds is reported with the server name associated with that port number. Net Interactive



387



 Net ARP Command



Commands



The Net ARP command displays the Address Resolution Protocol table and allows you to assign an IP address to a network interface card.



1



NET ARP



-a [ -N if-addr ]



2



NET ARP



-s ip-addr hw-addr [ if-addr ]



3



NET ARP



-d ip-addr [ if-addr ]



ip-addr



»



Dotted, internet address



hw-addr



»



Hardware or MAC address



if-addr



»



Interface address



Operation



Mode 1—Display the Address Resolution Protocol table. >net arp -a Interface: 192.168.100 Internet Address Physical Address 192.168.1.105 00-03-47-D5-24-E1 192.168.1.104 00-E0-7D-9D-87-BB



Except for the entries that are manually added with Mode 2, the entries in the ARP are transitory. They are added each time that a local IP is resolved into a specific network interface card’s MAC address and then removed a short time later. Mode 2—Assign an IP address to a network interface card. >net arp -s 192.168.1.157 00-e0-7d-9d-87-bb



This is the primary function of the ARP command. In some situations a particular network interface card might not be assigned an IP address through the normal means (Setup Net Interface and DHCP). With this mode of the ARP command a specific interface card is assigned the IP address that you want. In the above example, the interface card with the MAC address of 00-E0-7D-9D-87-BB is assigned the IP address of 192.168.1.157. If that



card already has an IP address assigned, then this address is added to its list of addresses.



388 Net ARP



 Unlike the automatic entries in the ARP table, these manual entries are not transitory and remain until the entry is manually deleted (Mode 3) or the system is restarted. Mode 3—Delete an IP address from a network interface card. >net arp -d 192.168.1.101



In the first example above, the ARP table is searched for any entry of the address 192.168.1.101. If an entry is found it is deleted from the table. The associated network interface card is instructed to remove that IP from its internal list of addresses that it responds to. The second example is similar to the first except that the ARP table is searched for an entry that has the IP address of 192.168.1.103 and has the specific MAC address of 00-1A-C9-9D-45-DF. If an entry is found with that combination then it is removed from the table and the interface card is reprogrammed. Options



The only option available with this command is the -N option that might be used with Mode 1. When it is used the ARP table display is limited to the entries matching the specified MAC address and interface card.



Net ARP 389



Commands



>net arp -d 192.168.1.103 00-1a-c9-9d-45-df



 Net Browse Command The Net Browse command scans the local network computers and reports on the systems currently available for network file system access.



Commands



NET BROWSE Operation



The TNFS client on this system is queried for computers on the network with network file systems available. The list of computers available is displayed.



All systems that have a network file system installed and operating are reported. There is some latency inherent in the reporting system and it is possible that a system will be listed that has been powered off for as long as 45 minutes. You may get the list of share names available on a system by positioning the highlight bar to the system’s name and pressing (Enter) or (+). If there are any shares defined on that system they will be listed. Similarly, you can remove the display of the share names for a system by pressing the (-) key when the system name is hightlighted. Restrictions



There must be a TNFS client running on this computer system.



See also



Ping, Setup TNFS



390 Net Browse



 Net Exec Command The Net Exec command is used from a client workstation connection to a THEOS host and causes the client system to execute a program. NET EXEC



program ( program-options exec-options »



program to execute on client, with parameters



exec-options



»



MAXIMIZE MINIMIZE



Operation



NORMAL NOWAIT



Commands



program



WAIT



Forces the client system to execute program. You must already be connected as a client to a THEOS server to use this mode. NetTerm, Telnet and THEOS WorkStation Client (TWS) connections can use this command. When specifying program, be sure to specify the command in the format required by the client’s operating system. For instance, assuming that the client connection is from TWS: >net exec "edit c:\autoexec.bat" >net exec "edit /autoexec.bat:c"



Only the first command is proper because that is the format used for specifying directory paths and drive codes on Windows and DOS systems. The second command will not edit the desired file. The exec-options can be specified to control the display of the command on the client system. These options are specified at the end of the command line. To avoid confusion it is best to enclose the program specification within quotation marks: >net exec "list some.file (printer" (nowait



The above command might be used with a Telnet or NetTerm connection from a THEOS system and it executes the command line list some.file (printer



on the client system as a background task. The Net command returns control to you as soon as the task is started.



Net Exec 391



 Commands



Options



The following options may be used the NET EXEC command. The Maximum, Minimum and Normal options are effective only when the client is a THEOS WorkStation Client. Maximum



Indicates that the program is executed in its maximized mode. When neither this option nor the Minimum option is used, the program is executed with its default size of window.



Minimum



Indicates that the program is executed as a minimized icon.



Normal



The program is executed in its default or normal-sized window.



NoWait



Tells the THEOS Server to not wait for completion of the program on the client system. When executed from the command line, control returns to the CSI and you may enter another THEOS command. When executed from an application program or an EXEC, control returns to the calling program. Note: When the client system is a THEOS system, the program is executed as a background task. This means that it does not have a console keyboard available to it. If the program needs a keyboard it will exit.



Wait



A default option that tells the THEOS Server to wait for completion of the program on the client system before returning control to you or the calling program.



Restrictions



When the client system is a THEOS 4.x or THEOS Corona system, do not use the Maximum, Minimum or Normal options.



See also



DialNet, FTP, NetTerm, Ping, Quote, Setup, Telnet, THEOS WorkStation Client



392 Net Exec



 Net Receive Command Net Send Command The Net Receive and Net Send commands allow you to receive and send files when a NetTerm or TWS client connection is made with a THEOS host system or directly from a system connected to a network. NET RECEIVE



file



destination-file ( send-rec-options



2



NET RECEIVE



url



( send-rec-options



3



NET SEND



file



destination-file ( send-rec-options



4



NET SEND



url



( send-rec-options



Commands



1



file



»



file name to send to or receive from THEOS server, with optional path; may contain wild cards



destination-file



»



name to assign to file on receiving system, with optional path



send-rec-options



»



ABORT FILES



url



»



Uniform Resource Locator of file to receive or send



Operation



NEWFILE NOTYPE



OLDER REPLACE



SKIP TRANSLATE



All transfers are relative to the client system issuing the request. For instance, a Net Receive means a file is received on the client system; a Net Send means a file is sent from the client system. Mode 1—Transfers file from the server to this client. You must already be connected as a client to a THEOS server and you must be logged onto an account to use this mode. Client connections are made with the NetTerm or the THEOS Workstation Client programs. (Because the Telnet protocol does not support file transfers, connections made with a Telnet client cannot use the file transfer capabilities of the Net command.) >net receive data.file /private/data.fil:a



The file and destination-file can be specified with wild cards. The syntax and operation of the wild cards is similar to the syntax and operation of wild cards used with the CopyFile command. >net receive *.data:s >net receive *.data:s =.=



Net Receive 393



 The above two command receive all files with a file-type of DATA on the S drive of the host system. The files are received with the file names unchanged into the current account, root directory. >net receive *.data:s =.newdata



Commands



In the above command, all files with a file-type of DATA on the S drive of the host system are received on the client system. They are received on the with the same file-name but the file-type changed to NEWDATA for each file. >net receive my.library.* your.library.=



In this command, each of the member files of MY.LIBRARY on the host system are received on the client system into the library YOUR.LIBRARY. The member-names are not changed. Obviously, this command could only be used when the client is NetTerm on a THEOS system as other operating systems do not have libraries. >net receive file*.data abc=x.files



The above command sends all files with a file-type of DATA and with a file-name that starts with FILE on the host system. The files are received on the client system with the file-name changed to ABC=X where the equal sign is replaced with the portion represented by the * in the source file-name. For instance, FILEONE.DATA is received as ABCONEX.DATA, FILE486.DATA is received as ABC486X.DATA, etc. >net send *.data* =.new=



The specification of file and destination-file must use the file naming conventions of its operating system. If the destination is a THEOS system then use THEOS naming conventions; if the destination is a Windows system then use Windows naming conventions. When the destination-file is specified with a drive code the file is received with a file name equal to the source file name but on the designated drive. When destination-file is omitted, the file is received with the source file name on its default drive. Mode 2—Receives a file from some system on the network that is accessible to this client. The remote system and the file to be transmitted is identified by the url. The name of the file received is taken from the file name portion of the url. The file will be received into the current account, current working directory on the system drive. >net receive ftp://fileserver/sample.txt



Note that, in the above example, the url specifies the network protocol (ftp://). This is necessary for two reasons. First, it tells the Net command 394 Net Send



 that this is a url and not a simple file name. Second, it specifies the file transfer protocol and default port to use for the file transfer.



For a complete description of the url syntax and usage, refer to Appendix D: “File References,” on page 247 in the THEOS Corona Version 5 Operating System Reference. Mode 3—Transfers file from this client to the THEOS server (RECEIVE) or transfers file from the THEOS server to this client (SEND). You must already be connected as a client to a THEOS server and you must be logged onto an account to use this mode. Client connections are made with the NetTerm or the THEOS Workstation Client programs. (Because the Telnet protocol does not support file transfers, connections made with a Telnet client cannot use the file transfer capabilities of the Net command.) >net send c:\windows\readme.txt >net receive data.file /private/data.fil:a



The send or receive direction is relative to the client system. Therefore, Net Receive receives a file from the host on the client; Net Send sends a file



from the client to the host. Both SEND and RECEIVE allow the file and destination-file to be specified with wild cards. The syntax and operation of the wild cards is similar to the syntax and operation of wild cards used with the CopyFile command. >net send *.data:s



The above command sends all files with a file-type of DATA on the S drive. The files are received with the file names unchanged. >net send *.data:s =.=



This command performs the same function as the first command: All files with a file-type of DATA on the S drive are sent and received with the same file names. >net send *.data:s =.newdata



In the above command, all files with a file-type of DATA on the S drive are sent to the host system. They are received on the host system with the same file-name but the file-type is changed to NEWDATA for each file. Net Send



395



Commands



Files may only be received from an FTP or HTTP server and the appropriate protocol must be specified in the url. The url must also specify the host and path of the file to receive. It may specify the account and account password of the owning account on the remote server. When the account is not specified the “anonymous” account is used.



 >net send my.library.* your.library.=



In this command, each of the member files of MY.LIBRARY are sent to the host system and received into the host system’s library YOUR.LIBRARY. The member-names are not changed.



Commands



>net send file*.data abc=x.files



The above command sends all files with a file-type of data and with a file-name that starts with file. The files are received on the host system with the file-name changed to ABC=X where the equal sign is replaced with the portion represented by the * in the source file name. For instance, FILEONE.DATA is received as ABCONEX.DATA, FILE486.DATA is received as ABC486X.DATA, etc. >net send *.data* =.new=



In this example, all files with a file-type of data are sent to the host system. The host system receives these files with the same file-name but the file-type is changed to NEW= where the equal sign is replaced with the source file’s file-type wild card component. For instance, FILE1.DATA111 is received as FILE1.NEW111, FILE486.DATA2002 is received as FILE486.NEW2002. The specification of file and destination-file must use the file naming conventions of its operating system. If the source is a THEOS system then use THEOS naming conventions; if the source is a Windows system then use Windows naming conventions. When the destination-file is specified with a drive code the file is received with a file name equal to the source file name but on the designated drive. When destination-file is omitted, the file is received with the source file name on its default drive. Mode 4—Sends a file from this system to a remote system on the network. The remote system is identified by the url. The name of the file sent is taken from the file name portion of the url. The file must be in the current account, current working directory on the system drive. >net send http://fileserver/myfile.txt



Files may only be sent to an FTP or HTTP server and the appropriate protocol must be specified in the url. The url must also specify the host and path of the file to send. It may specify the account and account password. When the account is not specified the “anonymous” account is used.



396 Net Send



 For a complete description of the url syntax and usage, refer to Appendix D: “File References,” on page 247 in the THEOS Corona Version 5 Operating System Reference. Options



With the exception of Files and Translate, they control the actions to be taken when the receiving system already has a file with the same file name. Specifies that, if the receiving system has an existing file with the same name as file, the transfer is to terminate without replacing this file or attempting to transfer any other files.



Files



The files listed in file are sent to or received from the server. file must be an ASCII stream file containing one or two file descriptions per line. The SELECTED.FILES and SELECTED.EXEC files created by the FILELIST command and the FOUND.EXEC created by the LOOK command can be used for this specification file. You may also create the specification file with an editor or application program. For instance, the FILELIST command is used to create a list of files to be compressed: >filelist a (10/1/01 10/8/01 exec



A file now exists that lists all of the files on the A disk that have been changed between 10/01/2001 and 10/08/2001. The following command will transfer these files from the server to the client system: >net receive selected.exec (files



When a record in file contains two file descriptions, the first file name specifies the file to transfer and the second file name specifies the name that it will be saved as on the receiving system. NewFile



Specifies that, if the receiving system has an existing file with the same name as file, you are to be asked if it should be replaced with the new file. The method of asking and the options available at that time are dependent upon the receiving system.



NoType



Suppresses the display of the transfer progress window.



Older



This option specifies that the file is only transferred if the file does not exist on the destination or if the time-stamp of the file



Net Send



397



Commands



Abort



 Commands



on the destination system is older than the time-stamp of the file on the source system. Replace



This is the default option specifying that, if the receiving system has an existing file with the same name as file, that file is replaced with the file from the sending system.



Skip



Specifies that, if the receiving system has an existing file with the same name as file, the transfer is to skip this file and continue with the next file in the list.



Translate



When the file being transferred is an ASCII stream file, the record terminators are to be translated to the receiving system’s syntax (CR for THEOS, CRLF for DOS/Windows).



Restrictions



This command may only be used when you are connected to the host computer using NetTerm, Telnet or THEOS WorkStation client software.



See also



DialNet, FTP, NetTerm, Ping, Quote, Setup, Telnet, THEOS WorkStation Client



398 Net Send



 Net Share Command Net Use Command The Net Share and Net Use commands define and maintain the names used by others to access the TNFS resources on this computer (SHARE) and for this computer to have client access to the TNFS resources on other computers (USE). NET SHARE



share-name



2



NET SHARE



share-name



3



NET SHARE



4



NET USE



unc-name



5



NET USE



unc-name password



6



NET USE



unc-name ( DELETE



7



NET USE



path



password



access-mode



comment



share-name



»



One to eight character name for directory



path



»



Path to directory on a local disk



password



»



Password required for remote access to share-name



access-mode



»



Access mode permitted: RO for read-only, RW for read & write access



comment



»



Text describing share



unc-name



»



Uniform Naming Convention name for remote share



Operation



Mode 1—Defines a share name for a directory on one of the local disks. This share name is what other computers on the network will see when they request access to this system’s files. The other systems do not refer to a disk drive but to a share name on this system. Mode 2—Removes a share name definition on this system. After removal and after restarting the TNFS server on this system, other computers on the network will no longer have access to the directory that this share name referred to. Mode 3—Displays the currently defined share names on this system.



Net Share 399



Commands



1



 Commands



Mode 4—Adds unc-name to the list of use names defined on this system. This syntax is only valid if the unc-name does not require a password to access it. When password is required, use the Mode 5 syntax. Mode 5—Similar to Mode 4 except the use name is added with a password. If the share name is defined on the server system with a password, you must specify that same password on the use name defined here. This password is supplied to the remote system when a connection is established from this client system to the file server system. The password should be enclosed within quotation marks to preserve the casemode and spacing. Mode 6—This syntax will delete the use name from the list of use names defined on this client system. Mode 7—Displays the currently defined use names to directories on other systems.



Restrictions



The Net command requires a privilege level of one.



See also



DialNet, FTP, NetTerm, Ping, Quote, Setup, Telnet, THEOS WorkStation Client



400 Net Use



 Net Server Command The Net Server command examines the servers installed on this system and reports about their status in a form that also allows you to change the status. NET SERVER The system is examined for each of the possible servers. If a server exists on the system (its primary program file is found) then the status of that server is shown. The configuration of the server is examined to determine how it is normally started and that startup mode is also shown.



Server list box Each server installed on the system is listed along with its



current status and startup mode. Use this area to select a server that you want to change. Stop/Start



Depending upon the current status of a selected server, the button here will display either “Stop” or “Start”, whatever is the opposite of the server’s current state. Press this button if you want to change the status of the selected server.



Mode



Press this button if you want to change the startup mode of the selected server. If the server is currently started manually, pressing this button will change it to start automatically the next time that the system is booted. If the server is started automatically, pressing this button will change it to only start manually.



Restrictions



This mode of the Net command requires a privilege level of 3 or better.



See also



Net Start, Net Stop



Net Server 401



Commands



Operation



 Net Start Command Net Stop Command



Commands



The Net Start and Net Stop commands start or stop network servers on this system. 1



NET START NETWORK



2



NET START server-name



3



NET START SERVERS



4



NET STOP server-name



5



NET STOP SERVERS



6



NET STOP NETWORK



server-name



Operation



»



DHCP DNS FTP HTTP LOGIN



LPD PPP NETALIVE NETEXEC NETPRT



NETTAPE TCP TDBS TELNET TFTP



THEOPOST TNFS TWINDOWS WEBMAINT



Mode 1—Starts the network or starts one of the network servers installed on this system. >net start network



The network can be automatically started at system bootup if the configuration requests it (refer to the THEOS Corona Version 5 Operating System Installation and Setup Guide). If it is not started at bootup it can be started manually with the above command. When the network is started, either automatically or manually, other network servers are also started if they have been enabled to start automatically. Mode 2—The network must be started before any of the network servers. If you attempt to start a server without first starting the network the message “Network not operational” is displayed and the return code is set to one. Once the network is started, you may start any of the other network servers installed on this system. See “Servers” on page 403 for a list and description of these servers.



402 Net Start



 Mode 3—If the network is started, this command starts all of the network servers that have been defined as automatic start but are not currently running.



Mode 5—Stops all of the servers that are currently running on this system. You can perform a Show Servers to see a list of the currently active network servers. Mode 6—Stops all networking operations on this system by stopping all of the servers and then stopping the network server itself. Servers



DHCP



The Dynamic Host Configuration Protocol server is used by other computers on the local network for network IP number assignment and other configuration information. The DHCP Server is an optional product available with the HostingServer Plus Pak or the NetServer Plus Paks.



DNS



The Domain Name System server is used by this system and other systems on the local or wide area network for domain name to IP number resolution of the various servers on this local network. Generally, there is only one DNS server enabled on a local network. The DNS Server is an optional product available with the HostingServer Plus Pak or the NetServer Plus Paks.



ExecNet



The ExecNet server allows remote clients to execute commands and programs on this system. The ExecNet Server is an optional product available with the FileServer, HostingServer, WebServer or the NetServer Plus Paks.



FTP



The File Transfer Protocol server is used by this system and other system on the local or wide area network when they want to transfer files from this computer using an FTP client program. Synonyms accepted for FTP include FTPSERVER. >net start ftp >net stop ftp



Net Stop 403



Commands



Mode 4—Stops a network server that is currently running on this system. See “Servers” on page 403 for a list of the servers that might be started. You can perform a Show Servers to see a list of the currently active network servers.



 The THEOS FTP Server is an optional product available with the WebServer Plus Pak or the NetServer Plus Paks.



Commands



HTTP



The HyperText Transfer Protocol server is used by this system and other systems on the local or wide area network when they want to use this system as a web server. Synonyms accepted for HTTP include HTTPSERVER, WEB and WEBSERVER. >net start web >net stop web



The THEOS WebServer is an optional product available with the WebServer Plus Pak or the NetServer Plus Paks. Login



The login server is used by this system and other systems on the local or wide area network when they want to connect to this system using a NetTerm client or a THEOS WorkStation client. Synonyms accepted for LOGIN include NETLOGIN. >net start login >net stop login



The Login Server may be started automatically when the network is started. Refer to the Setup Net Login Server command. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.) This server must be started on this system to allow other clients on the network to use this system as a host when connecting as a user with the THEOS WorkStation Client (Windows-based clients) or the NetTerm (THEOS-based clients). LPD



The Line Printer Daemon server is used by this system and other systems on the local or wide area network when they want to access the printers controlled by this computer. The LPD Server is an optional product available with the FileServer, HostingServer, WebServer or the NetServer Plus Paks.



Mail



The Mail server is used by this system and other systems on the local or wide area network to send or receive mail using this system as the mail server. PostOffice is a synonym name for this server. >net start mail >net stop mail



404 Net Stop



 The THEOS MailServer is an optional product available with the HostingServer or the NetServer Plus Pak. Both the MAILSERVER and MAIL names may be used to refer to the Mail Server.



NetAlive



The NetAlive server is used by this system to monitor access to local or wide area network servers and perform actions when they start or stop being available to this computer. The NetAlive Server is an optional product available with the FileServer, HostingServer, WebServer or the NetServer Plus Paks.



NetWork



The Network server refers to the TCP/IP and Ethernet server. It is the software used by all other servers for communication capabilities and it must be started before any other server.



PPP



The Point-to-Point Protocol server is used by this system to establish a connection to an Internet Service Provider (ISP) using a PPP client such as DialNet. Synonyms accepted for PPP include DIALNET, DIALUP and PPPSERVER. >net start dialup >net stop dialup



The DIALUP service is used by the PPP client DialNet and is necessary if you use a dial-up or modem to connect to another network such as the Internet. PrtNet



The PrtNet server is used by this system and other systems on the local or wide area network when they want to access the printers controlled by this computer. The PrtNet Server is an optional product available with the FileServer, HostingServer, WebServer or the NetServer Plus Paks.



TapeNet



The TapeNet server is used by this system and other systems on the local or wide area network when they want to use the tape drives controlled by this computer. The TapeNet Server is an optional product available with the FileServer, HostingServer, WebServer or the NetServer Plus Paks. Net Stop 405



Commands



The Mail Server must be started on this system to allow other clients on the network to use this system as a POP3 host for their mail clients.



 TCP



The TCP server is used by this system and other systems on the local or wide area network when they want to use the simple TCP services on this computer. See “Services” on page 412 for a list of these services. >net start tcp



Commands



>net stop tcp



The TCPSERVE, TCPSERVER and TCP names may be used to refer to the TCP Simple Services Server. A brief description of the TCP Simple Services can be found on page 411. The TCP Simple Services may be started automatically when the network is started. Refer to the Setup Net Simple TCP Services in the THEOS Corona Version 5 Operating System Installation and Setup Guide. These services must be started on this system to allow other clients on the network to use this system as the host for the TCP simple services described on page 411. TDB



The THEOS DataBase server is used by this system and other systems on the local or wide area network when they want to use the THEOS database managed by this computer.



Telnet



The Telnet server is used by this system and other systems on the local or wide area network when they want to connect to this system using a Telnet client application.



TFTP



The Trivial File Transfer Protocol server is used by this system and other systems on the local or wide area network when they want to transfer files from this computer using an TFTP client program. The TFTP Server is an optional product available with the FileServer, HostingServer, WebServer or the NetServer Plus Paks.



TNFS



The THEOS Network File System server is used by this system and other systems on the local or wide area network The TNFS Server is an optional product available with the FileServer or the NetServer Plus Paks.



TWindows



406 Net Stop



The TWindows server is used by this system and other systems on the local or wide area network when they want to connect to this system using a THEOS WorkStation client.



 WebIndex



The Web Index server is a companion server to the HTTP server. It provides word indexing and searching capabilities of the web pages stored on the HTTP server. The WebIndex Server is an optional product available with the WebServer or the NetServer Plus Paks. The Web Maintenance server is used by other systems on the local or wide area network to access this computer and perform system and network server maintenance. The WebMaint Server is an optional product available with the FileServer, HostingServer, WebServer or the NetServer Plus Paks.



Mode 7—Stops a network server. Mode 8—Stops all network servers. Restrictions



The Net command requires a privilege level of five. To use the START or STOP functions, you must be logged onto the SYSTEM account (id = zero) and have a privilege level of five.



See also



DialNet, FTP, NetTerm, Ping, Quote, Setup, Telnet, THEOS WorkStation Client



Net Stop 407



Commands



WebMaint



 Net IPCFG Command The Net IPCFG command display various configuration information about the network.



Commands



NET IPCFG Operation



Reports the current network configuration information: >net ipcfg Host Name: Saturn Domain: my.lan NIC-1: Realtek 8139 10/100 Fast Ethernet MAC = 00-00-21-C3-1E-44 IP = 192.168.1.100 / 255.255.255.0 Gateway: 192.168.1.1 DNS: 24.0.53.55 24.0.53.56



See also



408 Net IPCFG



WhoAmI



 Net function Command The Net function commands display various configuration information about the network and who is currently connected to the network. NET function »



DISCONNECT PING



Commands



function



PINGALL WHO



Operation



Invokes the requested function, displaying the results on stdout.



Functions



Disconnect This function can only be used while you are connected to the Login Server via a NetTerm or a THEOS WorkStation Client.



This function disconnects you from the host Login Server. Although this is equivalent to the Exit command, this Disconnect function cannot be used on a Telnet connect while the Exit command can be used with all connections. Ping



Broadcasts a “ping” on the network requesting that all nodes respond. The responding nodes are displayed. This display is identical to the Ping * command. >net ping Network Broadcast Ping Name Accounting Executive Administration



Address 192.168.87.12 192.168.87.15 192.168.87.63



3 Network nodes responded. PingAll



Similar to the Ping function, a “ping” is broadcast to all nodes requesting that they respond. However, it does this repeatedly every few seconds until the program is exited with (Esc) or (F9). This is identical to the Ping * * command.



Net



409



 Who



All THEOS login servers that this system can access are displayed along with the client nodes that are actively connected to those servers. >net who



Server/Client



Commands



Administration Executive Accounting Plant Development Documentation



Connect Date&Time



Pid



Account



1 Sep 2001 1 Sep 2001 1 Sep 2001



8:15am 7:48am 5:00am



6 7 8



Brad Payroll Products



1 Sep 2001



10:15am



9



Develop



Restrictions



A privilege level of five is required to use the Who function.



See also



DialNet, Exit, NetTerm, Ping, Setup, Telnet, THEOS WorkStation Client



410 Net



 Net service Command The Net service commands establish a client-server relationship between this system (client) and a TCP/IP Simple Services server. NET service host parameters



2



NET service host parameters



service



»



CHARGEN



host



»



TCP/IP address or name from the host names database. LOCALHOST may be used to access this system.



parameters



»



Optional parameters that may be used with the service



Operation



ECHO



TIME



DAYTIME



Invokes the TCP/IP Simple Services server-function. The server-functions refer to the TCP Simple Services that are available with network operations. These services are standard services available from most TCP/IP servers. TCP Simple Services are not necessarily enabled at all times. They may be enabled automatically if “Enable TCP Simple Services” is checked in the Setup Net Simple TCP Services (see THEOS Corona Version 5 Operating System Installation and Setup Guide). They may also be started manually with the Net Start TCPSERVE function described on page 402. A host name may be specified following the service name. When host is not specified the implied host is LOCALHOST, which is the default name of this computer’s network address. When a host is specified, that host is used for the TCP Simple Service instead of your system’s TCP server. This capability is particularly useful for the Time service. By specifying a host whose time is known to be accurate, you can find out and optionally set your system to the current time.



Net service 411



Commands



1



 Services



Chargen



Generates a continuous sequence of characters until terminated by entry of (Esc). Although trivial, this service is valuable when testing and debugging network applications that use data from a server.



Commands



The text string generated by the CHARGEN service is a 72-character line of ASCII characters in normal collating sequence. Each successive line increments the starting character by one. >net chargen !"#$&’()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQ... !"#$&’()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQR... >net chargen 192.168.1.102 CHARGEN connect() Connection was refused >net chargen 192.168.1.104 !"#$&’()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQ... !"#$&’()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQR...



In the second example above, a host was specified in an attempt to have that host use its CHARGEN service to generate the text strings. That host was a valid host but its TCP CHARGEN server was not started. The third example above also specified a host. In this case, that host’s CHARGEN server was available and it started generating and sending text strings to this client. DayTime



Displays the current date and time from the server. Although there is no specific standard for the format of the string returned, the THEOS DAYTIME service returns it formatted as day-name, month-name day-number, year time UTC-offset. >net daytime Tuesday, November 26, 2001 12:08:15 -0800



Note: The UTC-offset is only displayed if the system has been configured for time zones and the UTC offset has been defined. Use the SYSGEN command to set these attributes. Like the other TCP services, this service can get the information from another server by specifying a host. >net daytime time-nw.nist.gov 52219 01-11-06 17:54:13 00 0 0 224.7 UTC(NIST) *



412 Net service



 As illustrated in the above example, other system’s DAYTIME servers might not return the date and time in the same format as used by the THEOS DAYTIME server. Echo



All data sent to the server is echoed back to this client.



This service may also be requested from another host system. Time



Displays the time on a network server or gets that time and sets the time on your system. Invoking the TIME function with no host displays the current system time on your system. >net time Tue Nov 06 15:22:20 2001



When a host is specified with the TIME service, the current time from that host is retrieved and displayed. >net time time-a.timefreq.bldrdoc.gov Tue Nov 06 15:24:45 2001



Note: The above host name is for the National Institute of Standards and Technology (NIST), located in Boulder, Colorado. It reports a time that is accurate to the nearest second, depending upon the time lag of the Internet. There are other time servers maintained by NIST and they can be found by visiting the NIST web page at HTTP://WWW.BOULDER.NIST.GOV/TIMEFREQ/SERVICE/TIME-SERVERS.HTML. It does not matter where the server is physically located because the time information provided by any time server will include its UTC offset. If your system is configured properly for UTC offset the time is automatically adjusted by NET TIME. When a host is specified you may also request that this system’s date and time be set to the date and time retrieved from the remote time server. With this form, the remote server is contacted and that system’s current time is retrieved. That time is then used to set the system time of this client machine.



Net service



413



Commands



>net echo >This is a test of the TCP/IP echo command. 


 >show time 15:11:32 Monday, November 05, 2001. >net time time-nw.nist.gov (set



Commands



>show time 15:26:23 Tuesday, November 06, 2001.



See also



414 Net service



DialNet, FTP, NetTerm, Ping, Setup, Telnet, THEOS WorkStation Client



 NetTerm Client The NetTerm command establishes a client/server connection between the THEOS system that you are currently using (client) to another THEOS system that is a server on your network.



NETTERM



( options



2



NETTERM



server ( options



3



NETTERM



server account ( options



Commands



1



server



»



network server name, IP name or IP address (may also be localhost)



account



»



account name to log to after connection



localhost



»



LOCALHOST



options



»



ACCOUNT account CTL NOPRT PRTnn



Command synonym: Operation



NT



Mode 1—Invokes the NetTerm command without connecting to any server. NetTerm queries the network to find all of the THEOS servers that are connected to the network.



When no other THEOS servers are present on the network, an error message displays and the program exits. The names of the available servers are displayed in a menu.



NetTerm



415



 Commands



The list of servers is updated approximately once per second to reflect servers that are joining or leaving the network and servers whose permission list is changed. Choose one of the servers offered and a client connection is established with that server. If no default connection is defined (see “Default Connections” on page 417) and the ACCOUNT option is not used, you are started at that server’s logon prompt. Mode 2—Invokes NetTerm and connects to server. If server is not a THEOS Network Login Server, or if that THEOS server does not give you permission to connect to it, an error message displays. If no default connection is defined (see “Default Connections”) and the ACCOUNT option is not used (Mode 3), you are started at that server’s logon prompt. Mode 3—Same as Mode 2 except that you are automatically logged onto account. If that account has a password, you must enter the password when the connection is established. Options



ACCOUNT account After a connection is established, log onto account on



the server system. If account has a password, you are prompted to enter the password before you are allowed to log onto the account.



416 NetTerm



CTL



Set control mode for this console on the server. Control mode causes all control characters received to be displayed visually. For instance, receipt of a CR is displayed as ^M.



NOPRT



Do not connect any of your printers as a slave printer to the server.



 PRTnn



Default Connections



Your printer number PRTnn becomes a slave printer for your session on the remote server. When this option is not used (and the NOPRT option is not specified), your lowest numbered, attached printer becomes the slave printer.



performed on the server and you are prompted to “Logon please.” NetTerm searches your system for the NetTerm configuration file using the



following file specifications: environ/account.NTCFG environ/SYSTEM.NTCFG account.NTCFG SYSTEM.NTCFG



where environ is the current value of the environment variable NetTerm and account is the name of the account that you are using on your system when you invoked NetTerm. NetTerm Configuration File



NetTerm configuration files are ASCII text files containing the following



information: [name1 Server] Account=account [name2 Server] Account=account



etc. name1, name2 are the names of remote servers that you connect to. account is the name of the account that you want to automatically log onto when you connect with that server. For instance: [Administration Server] Account=Reports [Executive Server] Account=Remote [Production Server] Account=Guest [Development Server] Account=Programs



When this file is used to connect to the “Development” server, you are automatically logged onto the account “Programs.”



NetTerm



417



Commands



When an account name is not defined on the command line (Mode 1 or Mode 2), the account name specified in your system’s NetTerm configuration file is used. If no NetTerm configuration file is found, a normal user start is



 NetTerm Menu



Once you are connected to the server, your system is a client to the remote server. This means that any keys pressed are transmitted to the server as if you had a terminal directly connected to that system. Text received from the server is displayed on your console.



Commands



Exceptions to this transmission to the remote server are (Break) key sequences. Only (Break),(C) and (Break),(Q) are passed directly to the remote server. All other (Break) key sequences are acted upon by this NetTerm client. To transmit a (Break) key sequence other than (Break),(C) or (Break),(Q), you must press (Break),(B) followed by the key you want transmitted. For instance, to transmit a (Break),(X) to the server, you must press (Break),(B),(X). Pressing (Break),(M) displays the NetTerm menu:



Disconnect. Selecting this item performs a disconnect from this server. If you are in the middle of executing a program, a (Break),(Q) is transmitted. You are logged off the server, if necessary. When the disconnect is finished, you are presented with the menu of available servers that was described on page 415. This disconnect and reconnect can be performed directly, without using the menu, by pressing (Break),(R). Send File. Sends a file from this client to the server system. You are prompted for the file name you want transferred. You may specify any file on your system that you have access to. Specify the complete path, if necessary.



418 NetTerm



 You may also send files to the server by executing the Net Send command on the server system. This ability is particularly useful for transferring files under program control. Receive File. Similar to the “Send File” function described above except that it transfers a file from the server to this client system. You may also receive files from the server by executing the Net Receive command on the server system. Help. Displays help information about NetTerm. Note that you may press (F1) with any of the menu items selected to receive addition information about that specific menu item. About NetTerm. Displays copyright and version information about the NetTerm command and displays information about your current connection on the network: Shell to OS. Invokes the CSI shell without exiting the NetTerm command. This is the only way to maintain the connection with the server while executing another command on your system from this terminal and session. To return to the NetTerm command environment, execute the command name EXIT. Exit. Disconnects from the server and exits NetTerm. This action can also be performed without the menu by pressing (Break),(X). Notes



When connected to a remote THEOS server, you may execute any programs on that server that you have access to. While connected, the programs that you execute have the full resources of the server available to them. Additionally, they may have access to one of the printers on your client system if a printer was attached when you established the connection and you did not use the NOPRT option. NetTerm



419



Commands



Unless a different path is specified, the file is received on the server system into the current account, current working directory. An information window and status bar displays during the transfer.



 Cautions



You may execute the NetTerm command on the server. This will attempt to establish a link to another THEOS server. When this is done you will be communicating to the second server via the first server.



Commands



Although this is allowed and is useful at times, it can be quite confusing. To transmit a (Break),(C) to the second server, you must use the (Break),(B),(C) keys to tell the first server to transmit a (Break),(C) to the second system. Similarly, to terminate the connection with the second server, you must use the (Break),(B),(B),(X) keys to tell the first server to transmit a (Break),(X) to the second system. If you use the NetTerm command on the second system to connect to a third THEOS server, it is even more confusing. Restrictions



You may only connect to a THEOS server that gives your system permission to connect to it. Refer to Chapter 5 “Network Security,” starting on page 63 of the THEOS Corona Version 5 Operating System Reference for additional information about access permissions and security issues.



See also



Net, Setup, Telnet, THEOS WorkStation Client



420 NetTerm



 Notes Command The Notes command displays and maintains a user’s database of notes and messages to themselves.



NOTES



2



NOTES



folder Operation



Commands



1



folder »



Directory name for notes files



Mode 1—Using the NOTES directory for the currently set USERNAME, the notes form is displayed allowing you to view and maintain your notes:



Mode 2—Similar to Mode 1 except the directory used will be /THEOS/USERS/username/folder:S. Notes form



Notes list box The large area in the form is a list of the currently defined notes for the Category selected. You can and must select one of these notes if you want to Open, Print, Send, Remove or Change



it. Category



A drop-down list box that allows you to select a note category. The available predefined categories include: All, Business, Ideas,



Notes



421



 Miscellaneous, Personal, To Do and Unfiled . You may also define



your own categories. The category selected here determines which notes are displayed in the Notes list box. It also determines the category to be assigned to a New note that you create. Commands



New



To create a new note select the New button and the following form is displayed allowing you to enter the title and text of the note. The note is categorized with the currently selected Category unless that category is “All,” in which case the new note is saved as an “Unfiled” category. The category of a note can be changed after it is created by using the Change function.



When entering the text of the note remember that the first line of text will also be used as the title for the note and it is what appears in the Notes list box area of the main Notes form. You can advance from line-to-line by pressing the (Enter) key. To terminate entry of the new note press the (Esc) or (F10) keys.



422 Notes



Open



This button allows you to change or review an existing note.



Print



Prints the selected note on one of the attached printers.



 Send



This button displays another form allowing you to send this note as an e-mail message to someone:



Commands



You must fill in a valid From and To e-mail address. You may modify the message body by adding additional lines of text or changing the note text that is pre-loaded into the body of the message. Remove



Selecting this button deletes the note that is currently selected in the Notes list box.



Change



You can change an existing note’s category with this button. It displays the following form allowing you to select the new category for the note.



Notes



423



 You can create your own categories by using the “Edit categories” selection of the Category selection item. When this is selected you are presented with:



Commands



Creating New Categories



Just enter your new category name in the “New category” field and press the “Add” button. You can also delete any of the categories, including the preset category names. The “Reset” button allows you to restore the category list to the standard names. When this is done you are asked to confirm your choice:



When a category name is deleted, any notes that were assigned to that category are reclassified as “Unfiled.” Notes



Press the (Esc) key to exit from this command.



Defaults



Unless Mode 2 is used, the directory used to store the notes is /THEOS/USERS/username/NOTES:S.



See also



Reminder



424 Notes



 NsLookup Client The NsLookup client looks up domain names and returns their associated IP address, or looks up an IP address and returns its domain name.



NSLOOKUP



2



NSLOOKUP



domain Operation



domain



»



Commands



1



domain name or IP address or host name



Mode 1—Looks up and reports on domain. The information displayed is Server name, alias (if any), and the dotted IP addresses associated with domain. >nslookup teleport.com Server: teleport.com Address: 192.108.254.10 192.108.254.12 >nslookup www.microsoft.com Server: www.microsoft.com Address: 207.68.137.62 207.68.156.53 207.68.156.54 207.68.156.61 207.68.156.16 207.68.156.58 ...



Multiple addresses listed for a domain indicate that all of those addresses are associated with the domain. They refer to different machines at that site’s location. One may be for their FTP server, another for incoming mail, etc. Their exact function cannot be determined by this display. If the DNS server that is being used supports the feature, it is possible that NsLookup will display multiple lines identifying the Alias domain names. This is done only if there is a single IP address associated with the name requested and the DNS server supplied the alias names or the names have already been cached by the DNS resolver on this system.



NsLookup 425



 Mode 2—Enters an interactive mode where you can specify more than one domain before exiting. >nslookup



Commands



Enter name to lookup: ftp.theos-software.com Server: ftp.theos-software.com Address: 207.21.75.100 Enter name to lookup: ibm.com "ibm.com" not found. Enter name to lookup: www.ibm.com Server: www.ibm.com Address: 204.146.17.33 Enter name to lookup: laptop Server: Laptop Alias: Laptop.Documentation-system Address: 192.48.200.3 Enter name to lookup:



Pressing (EnterÌ˛) only, terminates the NsLookup command. Domain Specification



When domain is entered, the name resolver searches the following locations until a match is found or until all locations have been searched without success: 1. Cached names and IP addresses. 2. The file /THEOS/CONFIG/HOSTS.TXT:S. 3. The DNS servers. The DNS server locations are maintained by the Setup Net Name Services command. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.) domain may be specified in several ways. As a dotted IP address. When an IP address is specified, a “reverse lookup” is performed. That is, the domain name associated with the IP address is determined and displayed. >nslookup 207.21.75.100 Server: theos-software.com Address: 207.21.75.100



The host name as defined in the file /THEOS/CONFIG/HOSTS.TXT:S. This file can be maintained by you with Setup Net Name Services. >nslookup Server: Alias: Address:



426 NsLookup



my-company my-company my-company.theos-system 192.12826.30



 When domain is found in the host names database, the alias entry is displayed with the host name, dot, your-computer-name. Yourcomputer-name is defined in the Setup Net Identification . (See THEOS Corona Version 5 Operating System Installation and Setup Guide.)



>nslookup www.theos-software.com Server: www.theos-software.com Address: 207.21.75.100



NsLookup 427



Commands



Or the domain name as defined by the Domain Name Service specified in Setup Net Name Services.



 Commands



428 NsLookup



 Number Command Filter Number copies a file to the standard output device, numbering each line as it is copied.



NUMBER



2



NUMBER



file... ( options



file



»



file name with optional path



options



»



start increment



Operation



Commands



1



Mode 1—Each file is copied to the standard output device and numbered as it is copied. Specifying multiple files causes the second and remaining files to be appended to the first file copied to the standard output device and the numbering continues without being reset at the beginning of each file. >number one.file 1 Line one 2 Line two 3 Line three >number one.file one.file 1 Line one 2 Line two 3 Line three 4 Line one 5 Line two 6 Line three



This command is frequently used in a pipe: >number some.text | tee numbered.text | more



Mode 2—Copies the file from the standard input device to the standard output device, numbering each line as it is copied. When the console is the standard input device you terminate the input by entering (Ctrl),(D) on a line by itself.



Number 429



 Options



start



The starting number to use for the first file copied to standard output. The default starting number is one.



Commands



increment This option may only be used in combination with start. Specifies the increment value for each line number used. The default increment is one. >number one.file (100 100 100 Line one 200 Line two 300 Line three



Defaults



start and increment have default values of one and one.



Restrictions



file must be an ASCII stream file.



See also



Unnumber



430 Number



 Password Command The Password command allows you to change the password to your account.



PASSWORD The current account must have a password. If it does, you are prompted to enter the existing password to the account.



After entering the current password you are asked to enter the new password twice to make sure that you did not mistype it. For information about the usage and limitations of passwords, refer to “Passwords” on page 98 of the THEOS Corona Version 5 Operating System Reference. Notes



You cannot remove a password with this command. Only the Account command can remove the password for an account.



Cautions



Remember to make a note of this new password. You will not be able to log onto this account without this password and the password is not recorded anywhere in the system in plain text.



Restrictions



The account must have a password. If it doesn’t, ask the system administrator to add the password to the account with the Account command. The new password must match the current password policies. Password policies are rules governing passwords such as must contain upper and lower case characters, must not match any single word in the dictionary, etc. The policies also define the expiration time for a password. These polices are maintained by the Account command.



See also



Account, Logon



Password



431



Commands



Operation



 Commands



432 Password



 Patch Command The Patch command is a general purpose file and disk maintenance program. With it you can examine and change any file on the system or any sector of any attached disk.



PATCH



file ( options



2



PATCH



drive ( options



file



»



file name with optional path



drive



»



disk drive letter



options



»



BINARY NOVIDEO



Operation



Commands



1



Mode 1—With this mode you can view and make changes to file. The file may be any data or program disk file. file may not be a subdirectory or a library name. Refer to “Patching Files” on page 449 for a description of how Patch operates depending upon the file type (organization). Mode 2—This mode allows you to view and make changes to the data in a specific disk sector. Refer to “Patching Sectors” on page 450 for a description of this mode.



Options



BINARY



Tells Patch that file is to be treated as a stream of bytes rather than records or a program. Caution: You should only use this mode to view files. Essentially, this option tells Patch to ignore the structure of the file. If you make changes while this option is in effect, you may change a key (indexed or keyed file) to be unreachable or you may make records unreadable or programs unloadable.



NOVIDEO



Tells Patch to start in the command mode rather than the fullscreen display mode. This option is useful when Patch is being invoked from an EXEC program that has &STACK data that automatically updated a file.



Patch



433



 Video Display Mode



Patch has two basic display modes: full-screen video mode and command mode. In full-screen video mode the screen is used to display as much as one sector (256 bytes) of the disk or file at a time.



Commands



>patch /theos/config/browscap.txt



As you can see, this display is very similar to the display used by the List command when option HEX is specified. The first column shows the relative location of the data in the file. The middle portion of the screen shows the hexadecimal values for each byte of the file. And on the right is the ASCII display of those same data bytes. In full-screen video mode you can make changes to the data on the screen or move to display other sectors of the file. The keys that can be used in this mode are:



434 Patch



 Meaning



(Quit)



Exits Patch without saving changes to the file.



(File)



Saves all changes made to the file and exits Patch. Note that saving changes when the file is direct, indexed or keyed must be done for each record with the (Save) key, before selecting another record in the file.



(Save)



Saves all changes made to the record or sector without exiting Patch.



(Home)



Position to the first byte of data on this screen. If you are already positioned on the first byte, then (Home) displays the first sector of the file or record and positions to the first byte of that sector.



(End)



Position to the last byte of data on this screen. If you are already positioned on the last byte, then (End) displays the last sector of the file and positions to the last byte of that sector.



(Esc)



Exits full-screen video mode and switches to command mode. Pressing (Esc) while in command mode returns to the full-screen video mode.



(PageDown)



Displays the next sector of the file. The cursor does not move. That is, if you were positioned to the third line, second byte of the current sector, you will still be positioned to the third line, second byte of the new sector.



(PageUp)



Displays the previous sector of the file. The cursor does not move.



(Transpose) or (Ctrl)(O)



Moves the cursor from the ASCII column to the hexadecimal column, or vice versa.



(˜) (¤) (˚) (˙)



Move the cursor in the direction of the arrow. The left and right arrow keys move one byte; the up and down keys move by one line or 16 bytes. If the arrow key moves you off of this sector, the next or previous sector of the file or record is displayed. If there is no more file or record available in the direction desired, the cursor moves to the last or first byte of the file, as appropriate. Table 12: Patch Video Mode Commands



Patch



435



Commands



Key



 Key



Meaning



(Find)



Allows you to jump to a new location in the file or disk. The operation of this key depends upon the type of Patch operation being performed.



Commands



Direct, indexed and keyed files: You are asked for the record key that you want to find. Other files: You are asked for the relative location to jump to (in hexadecimal). Mode 2 of Patch: You are asked for the sector number to



patch. (SchFwd) (SchBck)



Allows you to position to the next or prior occurrence of a sequence of bytes in the file or record. The operation of these keys depends upon the location of the cursor when the key is pressed. ASCII column: Enter the ASCII text to search for. Hexadecimal columns: Enter the sequence of hexadecimal values to search for.



(Again)



Repeats the last (SchFwd) or (SchBck) performed. Table 12: Patch Video Mode Commands



• Changing Data on the Screen Initially, when a sector of the file or record is displayed in full-screen video mode, the cursor is positioned to the first byte of the sector, in the ASCII display area of the screen. If the information that you want to change to is ASCII data, merely move the cursor to the position that you want changed and then type the replacement characters. (Patch only has replace mode. It is not possible to insert characters or bytes with Patch.) If you need to change one or more locations to some binary or hexadecimal values, make sure the cursor is positioned in the middle, hexadecimal columns. Use the (Transpose) or (Ctrl)+(O) to switch back and forth. Position the cursor to the location that you want changed and type the replacement values. Note, when moving left or right with the arrow keys you move by bytes, not “nibbles” (four-bit hexadecimal characters).



436 Patch



 Command Mode



The Patch command or NOVIDEO mode provides all of the functionality of the full-screen mode plus some other important capabilities that are not easily implemented in a full-screen video mode. In command mode, Patch displays the PATCH prompt ( / ) indicating that it is ready to accept a command. • Expressions



Numeric Constant ASCII String Constant Operator Variable Another expression enclosed within parentheses • Numeric Constants Numeric constants are numbers specified in hexadecimal or decimal. By default, a number is a hexadecimal value unless it is terminated with the letter “t” or “T.” 1234 1234t



This is the number for 4,66010 or 123416 This is the number for 1,23410 or 04D216



• ASCII String Constants A value may be specified in ASCII by enclosing the ASCII characters within a pair of single quotation marks. Numeric values are always limited to 32 bits which is four bytes or four characters. When more than four characters are specified only the last four are used. 'abcd' 'AbCdEfGh' 'EfGh'



This is the value 1,633,837,92410 or 6162636416 This is the value 1,164,330,85610 or 4566476816 This is the value 1,164,330,85610 or 4566476816



Patch



437



Commands



Most of the Patch commands require an address or data values to be specified. Although these addresses and data values are normally specified with a numeric constant, they can be specified with an expression. In Patch, an expression contains one or more of the following elements:



 • Operators



Commands



There are many operators that may be used in an expression to modify an element or to join two or more elements together. In the following table address, value1 and value2 may be any value including another expression. Operator



Meaning



@address



Indirection: Use value of location pointed to by address



*



Value of current address pointer



~value



Unary 1’s complement of value (NOT)



-value



Unary 2’s complement of value (NEG)



(expression)



Parenthesized subexpression



value1 | value2



value1 is OR’d with value2



value1 ^ value2



value1 is XOR’d with value2



value1 & value2



value1 is AND’d with value2



value1 << value2



Shift value1 left value2 bit positions



value1 >> value2



Shift value1 right value2 bit positions



value1 + value2



Add value1to value2



value1 - value2



Subtract value2 from value1



value1 * value2



Multiply value1 by value2



value1 / value2



Divide value1 by value2



value1 % value2



Compute the remainder of value1 divided by value2 Table 13: Patch Expression Operators



• Variables As many as 26 variables may be assigned values and used in expressions. Variable names are single letters, case insensitive (an uppercase “A” is the same as a lowercase “a”). A variable is assigned a value by using an assignment statement: variable



=



expression



A variable is used in an expression by using its name followed by the dollar sign character ( $ ).



438 Patch



 For instance: /a=2000 0x00002000 (hex), 8192 (dec) /b=a$+1000 0x00003000 (hex), 12288 (dec) /



When the Patch prompt is displayed the following commands may be used. Note that some of the commands have no meaning in certain situations. For instance, when patching a stream file the KEY command is invalid. „ Assemble Command Patch contains a built-in assembly language compiler that allows you to use Intel mnemonics when specifying changes to a program file. A A



address



The A command accepts assembly language commands and stores the assembled code starting at location address. If address is omitted, the next location following the last assembled code stored is used. /a 339d2 000339D2: 000339D4: 000339DA: 000339DB: 000339DC: 000339DD: /



7470 8D8551FFFFFF 50 90 90



jz lea push nop nop end



33a44 eax,(ebp-af) eax



In the above example only the boldface text is entered. Patch supplied all of the other information and assembled the instructions as indicated. To terminate the entry of assembly language instructions, use the end pseudo-op or merely enter a blank line. Use one or more spaces to separate the assembly language opcodes from the operand fields. Any valid Patch expression may be used in the operand.



Patch



439



Commands



Patch Commands



 „ Calculator An expression calculator is available whenever Patch is waiting for a command. To use the calculator merely enter an expression. To insure that the expression is not interpreted as a command, make sure that it starts with a digit, unary operator or a question mark. Commands



/?abcd 0x0000ABCD (hex), 43981 (dec) /?2000-23 0x00001FDD (hex), 8157 (dec) /?'abcd' 0x61626364 (hex), 1633837924 (dec) /



The calculator always displays the result in both hexadecimal and decimal. „ Checksum Command The CHECK command computes the checksum for the entire file or for a region specified. check check check check



checksum address-range address-range checksum



It either displays this checksum or compares it to the checksum specified. /check Checksum is /check 1000 Checksum is /check 1000 Mismatch. /



F602 2000 B75E 2000 abcd



„ Code Command Most programs have a code segment and a data segment. Initially, when Patch starts, it assumes that addresses requested and displayed are in the program’s code segment. This assumption can be changed with the Data Command. The CODE command returns to the code segment. Code



440 Patch



 „ Compare Command The C command compares what is in the file at a specified location with what you specify should be in the file at that location. C



address value-list



/d 1000 100f 001000: E8C70B07 006A0368 FB0F0000 E8BCC707 'ºÍ...j.h....º.Í.' /c 1000 e8 c7 b Match. /c 1000 e8 c7 c Mismatch. /



„ Data Command Most programs have a code segment and a data segment. Initially, when Patch starts, it assumes that addresses requested and displayed are in the program’s code segment. This assumption can be changed with the DATA command. The Code Command returns to the code segment. Data



To view or make any changes to the data portion of a program, you must use the video display mode. „ Delete Command This command is valid only when the file is a direct, indexed or keyed data file. It deletes the current record from the file. De



Only the current record is deleted from the file. To get the current record use the Key Command.



Patch



441



Commands



For instance:



 „ Display Command This command displays data from the file, record or sector. D D D



address address-range



Commands



This command displays one or more lines of 16 bytes each, starting with address. If address or address-range is not specified, the next line following the last line is displayed. When address-range is not specified, 16 lines of data are displayed. /d 2000 200f



002000: /d 2000 002000: 002010: 002020: 002030: 002040: 002050: 002060: 002070: 002080: 002090: 0020A0: 0020B0: 0020C0: 0020D0: 0020E0: 0020F0: /



055B3BD8 7E0C8B45 F4488945 F8E95700 '.[;«~..E.H.E.¾W.' 055B3BD8 0000FF35 0000005B B640055B 288B4508 8D048500 038B45F4 098B45F4 FCE9CCFE 000000E8 45088B00 8B45088B 0C8B000F 400450E8 45FCE93A 508B4508



7E0C8B45 3C51FFFF 8B04180F 3BD87D09 4050FF35 0000005B E91F0000 488945F8 FFFF33C0 34FB0600 FF308B45 000FB640 B64004EB 538A0700 0000008B 8B000FB6



F4488945 8B45F448 B6400450 8B45F440 3C51FFFF 8B04188B 00EB1683 EB078B45 8BE55DC2 8B450C8B 0C8B000F 045B3BD8 098B4508 8945FC85 450C8B00 40045B93



F8E95700 8D048500 8B45080F 8945FCEB 8B45F448 40055B89 7DF0007E F4408945 0400B804 00FF308B B6400450 7D0B8B45 8B000FB6 C074088B 0FB64004 2BC38945



'.[;«~..E.H.E.¾W.' '...5


„ End Command The E command saves the changes that have been made and exits Patch. E



Note that when direct, indexed and keyed data files are being patched, the Put Command must be used to save the changes made to a record.



442 Patch



 „ Fill Command This command fills a block of the file with a single value. F



address-range value



/d 2000 002000: /f 2000 /d 2000 002000: /



200f 055B3BD8 7E0C8B45 F4488945 F8E95700 '.[;«~..E.H.E.¾W.' 2008 0 200f 00000000 00000000 F4488945 F8E95700 '.........H.E.¾W.'



„ Get Command The G command reads and displays one sector of the disk. This command is only valid in Mode 2 of Patch (patching disk sectors). G G



sector



If sector is omitted, the next sector of the disk is read and displayed. „ Help Command The H command displays a brief summary of all of the commands and the expression operators and elements. H



(F1) „ Key Command The K command reads a record of a direct, indexed or keyed file. This command is valid only when patching those types of files. K K



key



The key must match in type with the type of file. That is, for direct files the key must be a record number, but for indexed and keyed files the key must be an alphanumeric string. Indexed and keyed file keys may not contain the space character. For direct files the record number specified is assumed to be a decimal number, even without the trailing “t” specifier.



Patch



443



Commands



Unlike the Set Command which can set a series of locations with a string of data, the F command sets the series of locations to a single value.



 „ Length Command The LEN command displays the length of the file (stream files), the length of the file and allocated record size (direct, indexed and keyed files), or the length and type of program (program files). For program files it also allows you to change the size of the heap and stack space used by the program. Commands



Len Len HEAP size Len STACK size



For instance: >patch sample.stream (novideo /len Length = 2,031 / >patch sample.direct (novideo /len Length = 280 Reclen = 28 / >patch sample.indexed (novideo /len Length = 3,593,330 Keylen = 10 /



Reclen = 36



>patch sample.command /len Length = 92,824 Code = 0x00012834 Data = 0x00004098 Stack = 0x00002000 Heap = 0x0000C350 Entry = 0x00000140 Type = 32 bit Program /len stack 3000 /len heap d000



A change to the heap or stack space is only saved when the End Command is used.



444 Patch



 „ Move Command The M command copies data from one location in the file, record or sector to another location. M



from-address to-address length



This move operation is done as a byte-by-byte copy, not a copy and paste. Therefore, when the source and destination address ranges overlap, the result may be undesirable. The following example wants to copy the first 32 characters of the file to location 0x10. The first attempt fails because the address ranges overlap. /d 0 30 000000: 000010: 000020: 000030: /m 0 10 /d 0 30 000000: 000010: 000020: 000030: /



54686973 65737420 73656420 20636F6D 20



20697320 66696C65 62792074 6D616E64



6A757374 20746F20 68652050 2E0D0D54



20612074 62652075 41544348 68697320



'This is just a t' 'est file to be u' 'sed by the PATCH' ' command...This '



54686973 54686973 54686973 20636F6D



20697320 20697320 20697320 6D616E64



6A757374 6A757374 6A757374 2E0D0D54



20612074 20612074 20612074 68697320



'This is just a t' 'This is just a t' 'This is just a t' ' command...This '



To perform this type of operation properly the move must be done in two stages. First the overlapped region must be copied and then the remaining region is copied. If a larger region were copied, there might be several stages to avoid specifying an overlapped region. /d 0 30 000000: 54686973 000010: 65737420 000020: 73656420 000030: 20636F6D /m 10 20 10 /m 0 10 10 /d 0 30 000000: 54686973 000010: 54686973 000020: 65737420 000030: 20636F6D /



20697320 66696C65 62792074 6D616E64



6A757374 20746F20 68652050 2E0D0D54



20612074 62652075 41544348 68697320



'This is just a t' 'est file to be u' 'sed by the PATCH' ' command...This '



20697320 20697320 66696C65 6D616E64



6A757374 6A757374 20746F20 2E0D0D54



20612074 20612074 62652075 68697320



'This is just a t' 'This is just a t' 'est file to be u' ' command...This '



Patch



445



Commands



The from-address, to-address, from-address+length and the to-address+ length must be within the bounds of the current file or record. This restriction does not apply when patching disk sectors.



 This operation of the M command is not entirely undesirable because it can be advantageous to repetitively duplicate a region of the file or sector.



Commands



/d 0 30 000000: 54686973 000010: 65737420 000020: 73656420 000030: 20636F6D /m 0 5 45t /d 0 30 000000: 54686973 000010: 68697320 000020: 69732054 000030: 73206F6D



20697320 66696C65 62792074 6D616E64



6A757374 20746F20 68652050 2E0D0D54



20612074 62652075 41544348 68697320



'This is just a t' 'est file to be u' 'sed by the PATCH' ' command...This '



20546869 54686973 68697320 6D616E64



73205468 20546869 54686973 2E0D0D54



69732054 73205468 20546869 68697320



'This This This T' 'his This This Th' 'is This This Thi' 's ommand...This '



„ Patch Level Command The PL command displays and sets the current patch level for a program file. PL PL



patch-level



Patch levels may only be assigned to program files. The PL command always displays the current patch level for the program. /pl Old New /pl Old /



patch level: patch level: 40001 40002 patch level: 40001



The patch-level must be a field using a format of @####### or #######. That is, a single letter followed by seven or fewer digits, or seven or fewer digits without the leading letter. A program’s patch level can also be set or changed with the Change command described on page 65 and it can be viewed with the FileList command described on page 229.



446 Patch



 „ Put Command The P command is the complement of the Get Command and Key Command. P writes a record or sector back to disk. P P P



key sector



Use the P sector when you are patching disk sectors and you want to write the current sector to a different location on the disk. To merely write the current record or sector back to the file or disk in the same place that it was read, use the P command with no argument. „ Quit Command The Q command exits the Patch command without updating the file or disk. Any unsaved changes are lost. Q



Use the End Command or Put Command to save changes before quitting. „ Replace Command The R command changes the contents of consecutive locations to values specified. R



address value-list



The values in value-list are assigned to the locations address, address+1, address+2, etc. until the list is exhausted. The range of locations from address to address plus the number of items in value-list must be within the bounds of the file, record or sector. /d 2000 002000: /r 2000 /d 2000 002000: /r 2000 /d 2000 002000:



200f 54686973 20697320 6A757374 20612074 'This is just a t' 15 23 0f 2d 200f 15230F2D 20697320 6A757374 20612074 '.#.- is just a t' 'Now is the time ' 200f 4E6F7720 69732074 68652074 696D6520 'Now is the time '



Patch



447



Commands



Use the P key when you are patching a direct, indexed or keyed file and you want to write the current record to the file with a different key. The key must match the file organization. That is, key must be numeric for direct files and alphanumeric for indexed and keyed files.



 „ Search Command The S command locates an occurrence of a specified series of values. S



address value-list



Commands



The file, record or sector is searched, starting at location address, for the next occurrence of the sequence of values indicated by value-list. The range of locations from address to address plus the number of items in value-list must be within the bounds of the file, record or sector. If a match is found, its location is displayed and you are asked if you want to search for the next occurrence. Any response other than (Y) is treated as (N). /s 0 'This' Match at 0x00000000, again? y Match at 0x0000003B, again? y /



„ Set Command The S command allows you to set a series of locations, one location at a time. S



address



When S starts, it displays address and its contents in both hexadecimal and ASCII and then it allows you to change the value at that location. /s 2000 0x00002000: 0F (.)



At this time you may enter a new value, terminate the S command or advance to the next or prior locations. Entry of (ÌÌSpaceÌÌ), (¤) or (˙) is interpreted as a request to advance to the next address. Entry of (˚) backs up to the prior address. The location may be set to any expression value as described in “Expressions” on page 437. You may set it to a string of ASCII characters by enclosing the characters within a pair of single quotation marks. Terminate the entry of a value with (ÌÌSpaceÌÌ), (¤), (˙) or (˚) and the locations are set to the values requested and the location pointer is advanced or backed up. Terminate entry with (EnterÌ˛) and the values are set and the S command terminates.



448 Patch



 „ Use Command The USE command tells Patch to use either 16-bit or 32-bit instructions when using the Assemble Command. Use 16 Use 32



This command will only be necessary when you are patching disk sectors (Mode 2). When patching a program file, Patch will know whether the program is a 16-bit program or a 32-bit program. „ Full-Screen Video Mode Command Entry of (Esc) switches Patch from the command mode to the full-screen video mode or vice versa. Patching Files



How Patch operates depends upon the type of file being patched. • Stream Files or BINARY Option Patching a stream file or using the BINARY option causes Patch to start in its video display mode. The entire file may be viewed or modified because all addresses are valid from zero through the length of the file. You must use the End Command (in command mode) or the (File) or (Save) commands (in video display mode) to save any changes made to a stream file. • Direct, Indexed and Keyed Files Patching a direct, indexed or keyed file starts Patch in the video display mode. You may only view and change one record at a time. The key to a record cannot be changed except by using the Put Command to write the record with a different key and the Delete Command to delete the old record (perform a DE first and then a P with the new key).



Patch



449



Commands



/s 2000(EnterÌ˛) 0x00002000: 0F (.) 0(ÌÌSpaceÌÌ) 0x00002001: 8B (.) 23(ÌÌSpaceÌÌ) 0x00002002: 5D (]) 14(ÌÌSpaceÌÌ) 0x00002003: 14 (.) 253t-48t(ÌÌSpaceÌÌ) 0x00002004: 81 (.) 0(ÌÌSpaceÌÌ) 0x00002005: FB (.) 'This is a test'(ÌÌSpaceÌÌ) 0x00002013: 95 (.) 0(EnterÌ˛) /d 2000 2013 002000: 002314CD 00546869 73206973 20612074 '.#.Ì.This is a t' 002010: 65737400 C083E001 741EA180 C0FFFFF6 'est.ƒ.™.t.¿.ƒ...' /



 Changes made to a record must be saved with the Put Command (in command mode) or the (Save) command (in video display mode). • Program Files Patching a program file causes Patch to start in command mode with the Commands



CODE segment selected.



You must use the End Command (in command mode) or the (File) or (Save) commands (in video display mode) to save any changes made to a program file. Patching Sectors



When Mode 2 of Patch is used you can view and change one sector at a time. Patch starts out in video display mode. After specifying the first sector number you may get the next sector of the disk with either the Get Command (in command mode) or the (PageDown) commands (in video display mode). In video display mode you may get the prior sector with the (PageUp) command. You must use the End Command (in command mode) or the (File) or (Save) commands (in video display mode) to save any changes made to a sector before getting a different sector.



Restrictions



file must not be read or write protected. The Patch command requires a privilege level of three.



450 Patch



 Peek Command The Peek command allows you to see what is displayed on another user’s console.



PEEK



name



2



PEEK



process



name



»



account name



process



»



process number



Operation



Commands



1



Mode 1—The first user that is logged onto name (other than yourself) is peeked at. Mode 2—The user on process number process is peeked at.



Notes



When you first peek at another user’s console, the current text displayed on that console is displayed on your console. After this initial display, all characters that are displayed on that user’s console are also displayed on your console. Users may notice a slight degradation in performance because every character displayed on their console has to be displayed twice. There may be a significant degradation if your console is slower than the other user’s, for instance, when you are connected via a slow-speed modem. You should always inform the user before peeking at their console. In some countries it may be illegal to peek at a user’s console without their permission. Peek is a good tool to use when training a user on how to use some piece of software or for technical support when the support person is not near the user needing assistance. Multiple users can peek at the same console which is often used in a training class.



Restrictions



The Peek command requires a privilege level of four.



See also



Show USER, VNC Client



Peek 451



 Commands



452 Peek



 Ping Client The Ping client allows you to broadcast a “Are you there?” or a “Who’s there?” query to a specific node or to all nodes on the local intranet.



PING



2



PING



address... ( options



3



PING



*



4



PING



* *



address



»



node IP address or name (may also be localhost)



localhost



»



LOCALHOST



options



»



NOTYPE



Operation



Commands



1



Mode 1—Invokes the interactive or windowed display mode of this command. This provides the most information about the queried node.



Entry is allowed for the “Host” field only. Enter the dotted IP address for a node or its name as defined in the host names database. Host names are defined in the /THEOS/CONFIG/HOSTS.TXT:S file. The “Host Name” and “Host Id” fields display the name and matching IP address for the specified host. In this mode, queries are repeatedly sent to the specified node until the operator terminates the operation with entry of any key, by using the mouse and selecting the “Stop” button, or when the node fails to respond. (The “Start” button changes to “Stop” after a host is specified.) As each query is sent, the information on the screen is updated to reflect the success rate and the response time for the node.



Ping



453



 Mode 2—With this form, Ping queries the network one time for a response from the specified host. The host is a dotted IP address or its name as defined in the host names database. >ping accounting



Commands



Host:



Accounting, address: 192.168.87.12 round-trip time = 2 milliseconds.



>ping 192.168.87.15 Host:



Executive, address: 192.168.87.15 round-trip time = 1 milliseconds.



If the NOTYPE option is used, the display is suppressed. However, the return code is set to a success/fail code of zero or one. Mode 3—The network is queried for responses from all nodes connected to the local intranet. This is the same operation performed by the Ping command. >ping * Network Broadcast Ping Name Accounting Executive Admin



Address 192.168.87.12 192.168.87.15 192.168.87.63



3 Network nodes responded.



Some network operating systems, such as Windows 95/98/Me, may not respond to this type of broadcast ping. Mode 4—Similar to Mode 3, the network is queried for responses from all nodes connected to the local intranet. This mode differs in that the network is continuously queried until the operator terminates the program by pressing (Esc) or (F9). This is the same operation performed by the Net PingAll command. Return Code



A return code (RC) of zero indicates a successful ping response. An RC of 1 indicates no ping response. An RC of 2 indicates that the address could not be resolved.



See also



Net



454 Ping



 Play Command The Play command plays WAV files through the system’s sound card.



PLAY file



2



PLAY wildcard-file



3



PLAY



4



PLAY STOP



Commands



1



file



»



file name with optional path; may contain wild cards



wildcard-file



»



file name using wildcard specifications with optional path



Operation



Mode 1—Play the sound file through the system’s sound card. Mode 2—If there are any files matching the wildcard-file specification, a menu of those matching files is displayed. (When no files match the specification the Play command merely exits.) >play c*



It is not necessary to specify the file-type unless you want to play wavformat sound files with a file-type other than WAV.



Play 455



 Using the menu, position to the desired sound file and press (EnterÌ˛) to play the sound. Once Play has initiated playing the sound file it returns to the menu with the next item highlighted. Only one sound file can play at a time, therefore requesting a new sound file when a sound is already playing causes the currently playing sound to be stopped and the new sound started. Commands



Mode 3—Operates the same as the Mode 2 command: >play *.wav



Mode 4—Any currently playing sound is stopped. Notes



Sound files with a file-type of WAV can also be played by merely entering the file name at the command prompt: >play mysound.wav >play mysound >mysound.wav



Each of the above commands play the file MYSOUND.WAV through the system’s configured sound card. It does this because the /THEOS/CONFIG/ TYPES.CFG:S file defines the open action for a WAV file to use the Play command to open the file. Defaults



Unless file or wildcard-file explicitly specify a file-type, the file-type used is always WAV.



Restrictions



This command can only play sounds when executed from the main console or from a TWS connection. When executed from the main console you must have a sound card configured on the THEOS system. Refer to the Setup SndCard command. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.) When executed from a TWS connection you must be using a connection to the TWindows server and the TWS must be configured to support Distributed Window Manager features for “Distributed Sound and Video.” The sound is played through the Windows machine’s speakers.



See also



456 Play



CDPlayer, Mixer



 POP3Test Command The POP3Test command tests an e-mail account on the email server (POP3 server).



POP3TEST



account@host



2



POP3TEST



account@host



3



POP3TEST



account



password



account



»



E-mail account name



host



»



Domain or host of account



password



»



Password for account



Operation



Commands



1



Mode 1—The POP3 server at host is contacted and queried about account mail status. The password is given to the server for validation. The status returned from the server is displayed on the console. This mode also updates the POP3Test configuration file with this account, host and password information. This configuration information is needed to use Mode 2 or Mode 3. Mode 2—The POP3Test configuration file is searched and the entry for account and host is used to contact the POP3 server for this account with the password read from the configuration file entry. Mode 3—The POP3Test configuration file is searched and the first entry matching account is used to contact the POP3 server for this account with the password read from the configuration file entry. This mode should only be used if account is unique in the configuration file.



Notes



Account names are case-sensitive on some servers. Passwords are casesensitive on most servers. To ensure that the account and password that you provide is the same as the ones given to the host, enclose each of the arguments in quotation marks. >POP3TEST "[email protected]" "MyPaSsWoRD"



The POP3Test configuration file is named /THEOS/CONFIG/POP3TEST.CFG:S. It is only maintained by Mode 1 of this command. There is no Setup program to create and maintain this configuration file as there is with most other configuration files.



POP3Test 457



 No text is displayed on the console when this command is executed from an EXEC program or a MultiUser BASIC language program using the SYSTEM or CSI statement or a C language program using the system() function.



Commands



Return Codes



Because this program is frequently invoked from within a program the return code is set to the number of messages read or an error code. A zero or positive return code indicates the number of messages waiting for account on the specified host. A negative return code indicates an error condition. The errors that might be detected and reported by this command are: RC



Error



-1



Invalid command-line arguments



-2



Missing host name



-3



Missing password



-4



Cannot create POP3Test configuration file



-5



Connect failure



-6



Account or password rejected by host



-7



Remote host disconnected with no reply



-8



Cannot resolve host name



-9



Socket error



Restrictions



You must have the network started and a Dial-up Networking profile defined or you an always-on connection to your network.



See also



TheoMail



Example



>POP3test "[email protected]" "PasSwORd99" 242 messages RC = 242, 11:46:44, ET = 0.01, CPU = 0.032



458 POP3Test



 Printer Command The Printer command is a complement to the CRT command. It tests the printer’s display capabilities with the attached class code for the printer.



PRINTER



2



PRINTER



PRTnn



Operation



Commands



1



PRTnn »



Attached printer



When Printer is invoked the “Printer Test Menu” is displayed.



Use the normal menu selection keys to select the desired tests. These keys are described in “Using Menus” on page 77. Options



PRTnn



Indicates that Printer is to test the attached printer number nn. When this option is not used the first attached printer is tested. The option keyword PRT may be specified as PRT, PRINT or PRINTER. As a convenience, PRINTER1 may be specified as P.



Printer



459



 Tests:



• Test Attributes Tests the printer attributes supported by THEOS including: boldface, underline, italics, second color or shading, compressed text, double-wide text and double-high text.



Commands



Class code: 135 Printer name: HP LaserJet II & III



Normal text (no attributes) 0x0E: Boldfaced text 0x0F 0x0B: Underline text 0x16 0x1D: Italics or alternate character set 0x1E 0x04: Second color or shading 0x05 0x02: Compressed text 0x03



0x17: Double-wide text 0x18 0x15: Double-high text 0x19



The display on your printer will, of course, be dependent upon your printer’s capabilities.



460 Printer



 • Ripple Pattern Displays a “ripple pattern” using the entire ASCII character set. This test can be used to check for dropped characters or improper column alignment.



• Column Registration Displays a columnar pattern.



!"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcde !"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcde !"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcde !"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcde !"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcde



• Line Registration Displays lines of repetitive characters. This pattern can be used to determine if lines of text are printed straight on the printer.



!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" ##################################################################### $$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%



Printer



461



Commands



!"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcde !"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdef "#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefg #$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefgh



 • Line Graphics



Commands



Displays all of the line-drawing graphics characters supported in the THEOS character set. See “THEOS Character Sets” on page 265. Also, a sample illustration of line graphics is printed. Ú = ULC



¿ = URC



Ù = LRC



À = LLC



à = LI



 = UI



´ = RI



Á = DI



Å = FWI



Ä = HORIZ



³ = VERT



Ú = RULC



¿ = RURC



Ù = RLRC



À = RLLC



É = DULC



» = DURC



¼ = DLRC



È = DLLC



Ì = DLI



Ë = DUI



¹ = DRI



Ê = DDI



Î = DFWI



Í = DHORIZ



º = DVERT



Most printers do not support the rounded corner characters. If your printer does not then define them with the normal square corner characters. • National Characters Displays all of the international characters supported by the THEOS character set. See “THEOS Character Sets” on page 265. Notes



The exact appearance of these tests depends upon the capabilities of your printer and the class code definition.



See also



Attach, ClassGen, CRT, Sysgen



462 Printer



 PutFile Command The PutFile command copies a file from this system to a DOS-formatted hard disk partition or diskette.



PUTFILE



file DOS-file ( options



2



PUTFILE



drive ( CLEAR



Commands



1



drive



»



attached drive letter



DOS-file



»



DOS file name with optional path; may contain wild cards



file



»



file name with optional path; may contain wild cards



options



»



BINARY EOF HIDDEN NOQUERY



QUERY RDONLY SUBDIR SYSTEM



This command’s function has been replaced with the DOSDiskA and DOSDiskC attachment capability. For information about this capability refer to the “Attaching DOSDiskA Floppy Disk Drives” on page 32. Operation



Mode 1—Copies the file from this system to a DOS formatted disk. >put sample.testfile sample.txt:f "SAMPLE.TEXTFILE:S" copied to "SAMPLE.TXT:F".



The DOS-file must be a valid DOS file description. >putfile *.txt:s =.=:f Ok to copy "LETTER1.TXT:S" (Yes,No,All) Y "LETTER1.TXT:S" copied to "LETTER1.TXT:F". Ok to copy "LETTER3.TXT:S" (Yes,No,All) Y "LETTER3.TXT:S" copied to "LETTER3.TXT:F". Ok to copy "LETTER2.TXT:S" (Yes,No,All) A "LETTER2.TXT:S" copied to "LETTER2.TXT:F". "LETTER4.TXT:S" copied to "LETTER4.TXT:F". "LETTER5.TXT:S" copied to "LETTER5.TXT:F". "LETTER6.TXT:S" copied to "LETTER6.TXT:F".



The DOS-file specification may be just the drive code for the DOS disk. This is equivalent to specifying =.=:drive. The destination name is the same as the source file name. Do not use this syntax when the THEOS file name is not a valid DOS file description. That is, do not copy library members or files whose file type is longer than three characters.



PutFile



463



 Mode 2—Clears the directory on the DOS formatted diskette. >putfile f (clear Enter disk label: DosXfer



Commands



Use this mode only when drive is a diskette drive. It is not designed to clear hard disks or removable hard disks. Options



BINARY



Tells PutFile that file may contain binary information and it is not to translate CR to CRLF. Whenever in doubt as to the content of the file, use this option.



EOF



Appends a ^Z to the end of the file. This is the standard DOS end-of-file mark character.



HIDDEN



Sets the “hidden” file attribute on the DOS disk for the files transferred.



NOQUERY



Tells PutFile to not ask for confirmation before copying each file. This is a default option when wild cards are not used. >putfile readme/*.txt:s f (noq "/README/LANMAN.TXT:S" copied to "LANMAN.TXT:F". "/README/VINES.TXT:S" copied to "VINES.TXT:F". "/README/PCTCP.TXT:S" copied to "PCTCP.TXT:F". "/README/IBMLAN.TXT:S" copied to "IBMLAN.TXT:F". 4 files copied.



To disable this option use the QUERY option. QUERY



Tells PutFile to “query” or ask if each file matching the file specifications is to be copied. This is a default option when wild cards are used. >putfile readme/*.txt:s f Ok to copy "/README/LANMAN.TXT:S" (Yes,No,All)



When the “Ok to copy” question is asked, you may respond with a (Y) for yes, (N) for no or (A) for all. Responding with (A) means yes to this file and all remaining files are copied without being queried. Respond with (Esc) to cancel the copy operation. To disable this option use the NOQUERY option. RDONLY



464 PutFile



Sets the “read only” file attribute on the DOS disk for the files transferred.



 If the path specified in DOS-file does not exist on the DOS disk, this option tells PutFile to create the subdirectories that are missing.



SYSTEM



Sets the “system” file attribute on the DOS disk for the files transferred.



Unless the BINARY option is used, the THEOS end-of-record mark (CR) is translated to the DOS end-of-record mark (CRLF).



DOS Partitions The disk drive specified by DOS-file or drive may be an attached removand Disks able disk such as a floppy or removable hard disk, or it may be a partition on an attached hard disk drive. This disk or partition may be a DOS-formatted partition (16-bit FAT) or a Windows 95 disk or partition (32-bit FAT). When it is a partition of an attached THEOS drive, the DOS partition is referenced by specifying the attached THEOS drive code, for instance S or C: for drive if the DOS partition is a partition of the same physical drive that is attached as the S drive in THEOS. >putfile special.txt /windows/*.*:s >putfile /dos/ansi.sys:s =.=:s (bin "SPECIAL.TXT:S" copied to "C:\SPECIAL.TXT".



Windows NTFS (NT File System) disks and partitions cannot be accessed with this command. Disks using Windows NT FAT can be used with this command. Cautions



THEOS direct, indexed and keyed files should not be transferred with this command. These file organizations are not usable by the DOS operating system. To transfer one of these types of files, first translate it into a normal stream file with the FileType and then copy the resulting file.



Restrictions



The destination disk must be a DOS-formatted disk. The DOS-file must be a valid DOS file description. DOS files have eight character file names and zero to three character file extensions. When a path is specified for the DOS-file, the path must already exist on the DOS disk. The path will only be created if the SUBDIR option is used.



See also



GetFile, FileType, Send, THEO+COM



PutFile



465



Commands



Notes



SUBDIR



 Commands



466 PutFile



 PWD Command This command displays the current working directory.



PWD The current working directory is displayed on the standard output device. >pwd /LETTERS/PERSONAL:S >show subdir SUBDIR = /LETTERS/PERSONAL:S



Notes



PWD stands for print working directory.



See also



Account, ChDir, FileManager, Logon, Show



PWD



467



Commands



Operation



 468 PWD



Commands



 Quote Client The Quote client queries a quote server for the next random quotation.



QUOTE



2



QUOTE server



localhost



»



LOCALHOST



server



»



network server name or id (may also be localhost)



Operation



Commands



1



Mode 1—Displays a random quotation from the /THEOS/CONFIG/NETQUOTE.TXT:S database. >quote The difference between the right word and the almost right word is the difference between lightning and a lightning bug. --Mark Twain



The quote server on this system must be started. The quote server is part of the TCP Simple Services. Mode 2—Accesses server and uses its quote server to display a random quotation from server’s database. server may be specified with: The dotted IP address for the TCP server. >quote 207.21.75.100



The host name as defined in the file /THEOS/CONFIG/HOSTS.TXT:S. This file can be maintained by you with WinWrite. >quote my-company



By the special name LOCALHOST, meaning that this machine’s server is queried. This is the equivalent of a Mode 1 command. Or the domain name as defined by the Domain Name Service specified in Setup Net Name Services. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.) >quote theos-software.com



Restrictions



The TCP Simple Services on this system must be enabled and started on this system to use Mode 1. The Quote server on the remote host must be enabled and started to use Mode 2.



Quote 469



 Examples



>quote



Life is so unlike theory. --Anthony Trollope



Commands



>quote Time is that quality of nature which keeps events from happening all at once. Lately it doesn’t seem to be working. --Anonymous



470 Quote



 Reboot Command The Reboot command shuts down and then reboots the computer.



REBOOT



2



REBOOT ( option



option



Operation



»



DOS FAST LINUX NOQUERY



NOTYPE QUERY REBOOT RESET



SHUTDOWN SINGLE THEOS TYPE



Commands



1



UPDATE WINDOWS



Mode 1—In this mode, you are presented with the reboot menu and allowed to select how you want the system rebooted:



Shut down. This selection shuts the computer down by stopping all servers and users and, if possible, turns the power off. The Shutdown Status is displayed during this process. This is the same as using the SHUTDOWN option with Mode 2. Restart in single user. Reboots the computer in single-user mode. Normal shutdown occurs and a flag in the hard disk’s MBR (Master Boot Record) is set causing the THEOS Multibooter to boot automatically with THEOS Corona in single-user mode. This is the same as using the SINGLE option with Mode 2.



Reboot



471



 Restart in THEOS Corona. The default selection. The system is shutdown by stopping all servers and users and then rebooting the system. A normal system restart is performed just as if you had pressed the system’s reset button. This is the same as using the REBOOT, RESET or THEOS option with Mode 2.



Commands



If a Mode 1 reboot is requested from an EXEC or application program, the Reboot Menu is not offered. The computer is restarted just as if a (Ctrl)+(Alt)+(Del) were entered from the main console. When used with a NetTerm connection to a remote system, you are warned with the message “You are about to reboot a remote system.” Mode 2—Instead of automatically displaying the Reboot Menu, the options specified control what is displayed and what reboot or shutdown process is performed. Options



472 Reboot



DOS



This and the WINDOWS option will boot the DOS or Windows primary disk partition without displaying the Reboot Menu. This option is only valid if there is a DOS/Windows primary partition on the disk drive. If the TYPE option is also specified, the Reboot Menu is displayed with the “Restart in Windows 98/ ME/2000” item preselected.



FAST



Performs a REBOOT without saving the console sessions locations and sizes. It is fast because the various servers and users are not stopped first, the system is merely rebooted.



LINUX



Boots the Linux primary disk partition without displaying the Reboot Menu. This option is only valid if there is a Linux primary partition on the disk drive. If the TYPE option is also specified, the Reboot Menu is displayed with the “Restart in Linux” item preselected.



NOQUERY



Do not display the Reboot Menu. This is a default option when the Reboot command is invoked from within an EXEC program.



NOTYPE



Do not show the Shutdown Status display. This is a default option when the Reboot command is invoked from within an EXEC program.



QUERY



Display the Reboot Menu . This is a default option unless the Reboot command is invoked from within an EXEC program.



 This option, the RESET and the THEOS option reboot the THEOS Corona primary disk partition without displaying the Reboot Menu. This is the default option unless DOS, LINUX, SHUTDOWN, SINGLE or WINDOWS option is used. If the TYPE option is also specified, the Reboot Menu is displayed with the “Restart in THEOS Corona” item preselected.



RESET



Synonym to the REBOOT option.



SHUTDOWN Shuts down the system without displaying the Reboot Menu.



After shutting down the system, this option specifies that the system is not automatically restarted. If APM (Advanced Power Manager) is available, the system is powered off. If APM is not available, a message displays informing you that it is okay to turn off the system. If the TYPE option is also specified, the Reboot Menu is displayed with the “Shut down” item preselected. SINGLE



Reboot the THEOS Corona primary disk partition without displaying the Reboot Menu. Normal shutdown occurs and a flag in the hard disk’s MBR (Master Boot Record) is set causing the THEOS Multibooter to automatically boot THEOS Corona in single-user mode. If the TYPE option is also specified, the Reboot Menu is displayed with the “Restart in single user” item preselected.



THEOS



This option, the REBOOT and the RESET option reboot the THEOS Corona primary disk partition without displaying the Reboot Menu. This is the default option unless DOS, LINUX, SHUTDOWN, SINGLE or WINDOWS option is used. If the TYPE option is also specified, the Reboot Menu is displayed with the “Restart in THEOS Corona” item preselected.



TYPE



Show the Shutdown Status display. This is a default option unless the Reboot command is invoked from within an EXEC program.



UPDATE



Reboot the THEOS Corona primary disk partition without displaying the Reboot Menu. Normal shutdown occurs and a flag in the hard disk’s MBR (Master Boot Record) is set causing the THEOS Multibooter to automatically boot THEOS Corona using the special, pseudo-account SYSUPDAT. Similar to the SINGLE option, the system is booted in single-user mode.



WINDOWS This and the DOS option will boot the DOS or Windows primary disk partition without displaying the Reboot Menu. This



option is only valid if there is a DOS/Windows primary partition on the disk drive. If the TYPE option is also specified, the



Reboot



473



Commands



REBOOT



 Reboot Menu is displayed with the “Restart in Windows 98/ME/ 2000” item preselected.



Note



A CACHE SYNC operation is performed before rebooting to maintain data integrity.



Commands



If history logging is enabled an entry is added reflecting that the system was rebooted. When this command is executed from an EXEC or another program, the options NOQUERY and NOTYPE are enabled unless specifically requested with the QUERY or TYPE options. When any of the options DOS, LINUX, SINGLE, UPDATE or WINDOWS is used, the THEOS Multibooter does not ask which partition to boot and the system will reboot in the requested mode. When that mode is rebooted, the THEOS Mutiboot will allow normal selection of boot partitions. Cautions



This is an extremely dangerous command because other users are terminated without notice. If another user is in the process of updating one or more files, those files will be inaccurate because the update was not completed. Always do a Show USERS or a Who command before using this command and verify that all other users are at a Logon, CSI or stopped.



474 Reboot



 Reboot Menu



If the computer has multiple operating systems installed on it, the reboot menu that is displayed will have additional options than those displayed on page 471. For instance, a system with both THEOS Corona installed and Microsoft Windows installed will display the following reboot menu:



Commands



A system with THEOS Corona, THEOS 4.2 and Microsoft Windows installed on it will display the following reboot menu:



Reboot



475



 For all reboot options including SHUTDOWN, the Reboot command must first shutdown the operating system. It also saves the main console session sizes and positions. It can display this shutdown process.



Commands



Shutdown Status



Users are stopped by issuing a Break,Q request to the user and forcing an Exit. It is possible that a server or user is busy or “hung” and cannot be



stopped with this process. If this should occur, the “End Task” button can be pressed to terminate the server or user. The “Restart” button can be used to shut the system down without going through the process of stopping each server and task. Restrictions



The Reboot command requires a privilege level of five.



See also



Exit, Show, ShutDown, Who



476 Reboot



 Receive Command EXEC The Receive command is an EXEC language program giving you convenient, command-line access to the THEO+COM command’s file receive capability.



file ( options



file



»



file name with optional path



options



»



ASCII COMnn THEOS



Operation



TRACE XMODEM XMODEM-1K TRACEFILE fn XMODEM-CRC YMODEM



Invokes the THEO+COM command in RECEIVE mode. The first attached COM device is used unless the COMnn option is specified. If no protocol option is specified, THEOS protocol is used. If the connection to the other computer is via a modem, it is assumed that the telephone connection has already been established with the Dial command or by using THEO+COM directly. >dial 1 800 123-4567 Dialing 1 800 123-4567 >receive updated.stocklst



Protocol..... File name.... File size.... Blocks....... Transmitted.. Byte count... Block count.. File count... Elapsed time. Errors....... Message...... Progress.....



Receive THEOS UPDATED.STOCKLST:S 1,235 5 0% 0 0 1 0:02 0 Waiting for sender



File transfer in process. Press ESC to cancel.



Receive 477



Commands



RECEIVE



 Commands



Options



ASCII



Use the ASCII file transfer protocol. Essentially, this is no protocol and should be used only for short text files.



COMnn



Use the currently attached COMnn for the communications port. When this option is not specified the first attached COM device is used.



THEOS



Use the THEOS SEND/RECEIVE protocol. This is the default protocol.



TRACE



Enables file transfer tracing. A window is opened in the upperright corner of the display, showing the protocol activity during a transfer.



TRACEFILE fn Similar to the TRACE option except that the protocol activ-



ity is output to the file fn. XMODEM



Use XMODEM checksum, 256-byte protocol.



XMODEM-CRC Use XMODEM CRC-16, 256-byte protocol. XMODEM-1K Use XMODEM-1K, CRC-16, 1024-byte protocol for single file



transfers. YMODEM



Use YMODEM CRC-16, 1024-byte protocol. This protocol might be called YMODEM-BATCH in the other computer’s communication program because it can receive multiple files.



Notes



Refer to the THEO+COM Installation and User’s Guide manual for a full description of the operation of file transfers and the protocols used.



Defaults



The first attached COM device is used by default and the THEOS protocol is the default.



Restrictions



A COM device must be attached.



See also



Dial, GetFile, Send , THEO+COM



478 Receive



 Reminder Command This command maintains reminder messages that can be displayed when a user logs on to an account.



The /SYSTEM.REMINDER and the account.REMINDER files are files accessed when you log onto an account. These are keyed access files with a calendar date for the key. When you log onto an account, these files are searched for a record with today’s date. If they are found, the message text for the date is displayed. Those message records are maintained by this command. Operation



A search is made for account.REMINDER file where account is the name of the account that you are currently logged onto. If the file is not found, then it is created. The program prompts you for a reminder date: >reminder Enter date (MMDDYY):



You may enter a specific date such as 07/04/02, or a “generic date” such as 07/04 without the year. A specific date means that the message appears on that date only; a generic date means that the message appears every year on that month and day. See “Notes” on the next page for additional information about entering dates. When a message already exists for the date entered, the message text is displayed and you can change it. Otherwise, you can enter the new message for the date. >reminder Enter date (MMDDYY): 07/19/02 Enter message text: This message displays every time that I log onto this account. Enter date (MMDDYY):



The message text may be as long as 256 characters, but it cannot contain any new-line characters or carriage returns. Entry of (EnterÌ˛) terminates the message text.



Reminder



479



Commands



REMINDER



 To delete an existing message, replace or add the word “DELETE” to the beginning of the message text. When the first six characters of a message are “delete” (uppercase or lowercase), the message is deleted from the file.



Commands



To exit from the Reminder command, respond with (EnterÌ˛), (Esc) or (F9) for the date. Notes



If you are logged onto an account with account number of 0 the /SYSTEM.REMINDER file is always the file maintained. Otherwise, the file maintained is account.REMINDER with account being the currently logged on account name. The date format requested by the Reminder command is dependent upon the current DATEFORM (see “Set” on page 541 and “Sysgen” on page 591). DATEFORM 1



DATEFORM 2



DATEFORM 3



MMDDYY



DDMMYY



YYMMDD



10/15/96 101596 10/15 1015



15-10-96 151096 15-10 1510



96.10.15 961015 15.10 1510



Format: Examples:



The delimiters between the date elements are optional and can be any non-numeric character. When you log onto a private account a maximum of four reminder messages may be displayed. 1. The first message searched for is today’s complete date in the /SYSTEM.REMINDER file. 2. The next messaged that might be displayed is the generic date for today in the /SYSTEM.REMINDER file. 3. Then today’s complete data is searched for in the account.REMINDER file. 4. The last message that might be displayed will be the generic date for today in the account.REMINDER file. For instance: >logon myaccount This message is for July 4, 2002 This message is for any July 4th This message is the myaccount message for July 4, 2002



480 Reminder



 This message is the myaccount message for any July 4th. >



See also



Logon



Commands



Reminder



481



 Commands



482 Reminder



 Remote Command The REMOTE command executes a command over a network connection.



REMOTE



REP://server command ( options



2



REMOTE



REP://acct@server command ( option



3



REMOTE



windows-command Corona-file-desc ( options



4



REMOTE



windows-command windows-file-desc ( options



5



REMOTE



Corona-file-desc ( options



6



REMOTE



windows-file-desc ( options



server



»



Name or address of ExecNet server



command



»



THEOS command name and arguments, options



acct



»



windows-command »



Program name with path if needed



Corona-file-desc



»



File name including drive code



windows-file-desc »



File name on Windows system



Operation



Commands



1



Mode 1—The ExecNet server operating on the machine identified by server is instructed to execute command. >remote rep://saturn eject r



Mode 2—Similar to Mode 1 but, after connecting to the server identified by server, it logs on to acct an executes command. >remote rep://private:password23@saturn "erase *.backup (not noq"



Mode 3, Mode 4, Mode 5 and Mode 6 are only valid when invoked from a



TWS console. Mode 3—When executed, it instructs the Corona system to transfer Corona-file-desc to the windows client system. It is saved on the Windows system as a tempory file and then the program windows-command is invoked with the temporary file name as a parameter for that program to operate on.



Remote 483



 If the temporary file is changed, upon exiting the windows-command, the temporary file is transferred back to the Corona system and replaces the original version of the Corona-file-desc.



Commands



Mode 4—Similar to Mode 3 except no file is transferred from the Corona system. Instead, the file is already on the Windows system and the windows-command is invoked with windows-file-desc as its argument. Mode 5—When executed, it instructs the Corona system to transfer Corona-file-desc to the windows client system. This file name is saved with a temporary file name on the windows system but the file extension is retained. The temporary file is then invoked as a command, relying upon the current file-type associations of the Windows system to choose the proper program to use with this data file. If the temporary file is changed, upon exiting the program the temporary file is transferred back to the Corona system and replaces the original version of the Corona-file-desc. Mode 6—Similar to Mode 5 except there is no file transfer between the systems. Instead, the windows-file-desc is used with the file already residing on the Windows system. Options



484 Remote



MAXIMIZE



When used with Mode 3, Mode 4, Mode 5 or Mode 6, this option instructs the window’s application to open in a maximized window.



MINIMIZE



When used with Mode 3, Mode 4, Mode 5 or Mode 6, this option instructs the window’s application to open in a minimized window.



NOTYPE



Suppresses any error message text display by the REMOTE command. Only the return code will indicate the result of the request.



NOWAIT



This option tells the REMOTE command to not wait for the completion of the execution of the remote command. Also, when used with Mode 3 or Mode 5, the file is not transferred back to the Corona system even when the file is changed on the remote system.



 Notes



When Corona-file-desc is used (Mode 3 and Mode 5) you must specify the drive code for the file. It is the colon and drive code at the end of the file description that identifies it as Corona file description instead of a Windows file description.



>remote rep://admin "tbackup s tape1 (backup verify full"



Restrictions



For Mode 1 and Mode 2, the server machine specified by server must, of course, be accessible from this machine and it must have an ExecNet server operating on it. Also for Mode 1 and Mode 2, the command executed must not require a console keyboard or display. You may, however, invoke commands that use the printer or other public device: >remote rep://private@saturn "list some.txt (prt2"



Mode 3, Mode 4, Mode 5 and Mode 6 are only valid when invoked from a



TWS console. See also



NetTerm, TWS



Remote 485



Commands



The options on this REMOTE command line are not passed as options to the command or Windows-command. The command may have options specified but to do so you must enclose the desired command name and its options within quotes. For instance:



 Commands



486 Remote



 Rename Command Rename changes the name of an existing file, library or directory.



RENAME



from-file to-file ( options



2



RENAME



file ( FILES options



3



RENAME



( options



Commands



1



file



»



file name with optional path



from-file



»



file name with optional path; may contain wild cards



to-file



»



file name with optional path; may contain wild cards



options



»



NOQUERY NOTYPE QUERY TYPE



Operation



Mode 1—Changes the name of from-file to to-file. >rename this.file that.file "THIS.FILE:S" renamed "THAT.FILE:S". 1 file renamed.



The from-file and to-file may contain wild-card specifications. See “Wild Card Specifications” on page 138. They may also contain complete or partial path specifications as long as the referenced file or directory is one that you have access to that location. Mode 2—file is an ASCII stream file containing two file descriptions per line. The first file description in the line is treated as a from-file and the second file description is the to-file. For each line in file, a Mode 1 Rename is performed. This mode of the Rename command is convenient when one or more sets of files are repetitively renamed. Merely edit a file containing file description pairs, such as: >edit daily.files customer.master:s /prior/customer.master:s customer.history:s /prior/customer.history:s general.ledger.*:s /prior/=.=.=:s check.*:s /prior/=.= >rename daily.files (file noquery notype



Rename



487



 Mode 3—This is the interactive mode of the Rename command. Since no files are specified on the command line you are prompted to enter the file descriptions to rename.



Commands



>rename (noquery Enter file name list, terminate with empty line. ?MENU.BASIC Destination file name missing. ?MENU.BASIC PROGRAM.BASIC.= "MENU.BASIC:S" renamed "PROGRAM.BASIC.MENU:S". ?SAMPLE.FILE* /COPIED/SAMPLES/=.= "SAMPLE.FILE1:S" renamed "/COPIES/SAMPLES/SAMPLE.FILE1:S". "SAMPLE.FILE2:S" renamed "/COPIES/SAMPLES/SAMPLE.FILE2:S". ?



Options



NOQUERY



Indicates that you do not want to be asked for confirmation before renaming each file. This is a default option when wild cards are not used. >rename gl.* general.ledger.= (noq "GL.MASTER:S" renamed "GENERAL.LEDGER.MASTER:S". "GL.JOURNAL:S" renamed "GENERAL.LEDGER.JOURNAL:S". "GL.HISTORY:S" renamed "GENERAL.LEDGER.HISTORY:S". 3 files renamed.



To disable this option use the QUERY option. NOTYPE



Tells Rename to not display the results of each file renamed on the standard output device. The general result message (the “nn files renamed.” message displayed before exiting Rename) is also suppressed with this option. >rename gl.* Ok to rename Ok to rename Ok to rename



gltest.= (not "GL.MASTER:S" (Yes,No,All) Y "GL.JOURNAL:S" (Yes,No,All) Y "GL.HISTORY:S" (Yes,No,All) Y



To disable this option use the TYPE option. QUERY



Tells Rename to “query” or ask if each file matching the file specifications is to be renamed. This is a default option when wild cards are used. >rename *.data =.testdata Ok to rename "CUSTOMER.DATA:S" (Yes,No,All)



When the “Ok to rename” question is asked, you may respond with a (Y) for yes, (N) for no or (A) for all. Responding with (A) means yes to this file and all remaining files are renamed without being queried. Respond with (Esc) to cancel the Rename operation. 488 Rename



 To disable this option use the NOQUERY option. TYPE



A default option that tells Rename to display the results of each file erased on the standard output device. This display can be redirected.



To disable this option use the NOTYPE option. Defaults



TYPE and QUERY are default options.



Restrictions



You cannot rename a file that is erase, read or write protected. You cannot rename a file to another drive. Use CopyFile or move Move for that. You cannot rename a file to a file description of an existing file. By default, only files owned by the current account are renamed. To rename a file owned by another account, you must specify the owning account name as part of the path: >rename private\his.file my.file



This command renames the file HIS.FILE owned by the account named PRIVATE to your account, current working directory, with the name MY.FILE. By default, the to-file is in your account in the current working directory but you may specify a path to the account and directory that you want to rename it to. >rename my.file account\textfile/samples/new.file "/MY.FILE:S" renamed to "ACCOUNT\TEXTFILE/SAMPLES/ NEW.FILE:S".



When the destination file specification includes a path, that path must exist. Rename does not create subdirectories. See also



Change, FileManager, CopyFile, Move



Rename



489



Commands



>rename program.source.* =.basic (noquery "PROGRAM.SOURCE.CUST:S" renamed "CUST.BASIC:S". "PROGRAM.SOURCE.LEDGER:S" renamed "LEDGER.BASIC:S". "PROGRAM.SOURCE.MENU:S" renamed "MENU.BASIC:S". "PROGRAM.SOURCE.REPORTS:S" renamed "REPORTS.BASIC:S". 4 files renamed.



 Commands



490 Rename



 Repeat Command EXEC The Repeat EXEC executes a command several times.



REPEAT



count command-line »



any valid THEOS command



count



»



number of times to execute command-line



Operation



Commands



command-line



This EXEC program merely repeats the execution of some command one or more times. >repeat 3 copyfile one.file to.another (append Repeat # 1 of 3 >COPYFILE ONE.FILE TO.ANOTHER (APPEND "ONE.FILE:S" appended to "TO.ANOTHER:S". One file copied. Repeat # 2 of 3 >COPYFILE ONE.FILE TO.ANOTHER (APPEND "ONE.FILE:S" appended to "TO.ANOTHER:S". One file copied. Repeat # 3 of 3 >COPYFILE ONE.FILE TO.ANOTHER (APPEND "ONE.FILE:S" appended to "TO.ANOTHER:S". One file copied. >



Repeat 491



 Commands



492 Repeat



 Replace Command Filter The Replace command modifies text files by changing (replacing) existing text strings with a new text strings.



REPLACE file ( option ... from-text to-text ...



2



REPLACE ( option ... from-text to-text ...



file



»



file name with optional path



from-text



»



text string specifying existing text in file



to-text



»



text string specifying the “change to” text



option



»



NOCASE



Operation



Commands



1



NODATA



Mode 1—The text file is opened and read. Every occurrence of the character sequence from-text is replaced with the character sequence to-text. If there are multiple from-text to-text pairs, then each occurrence of each of the from-text strings in the file is replaced with the corresponding to-text. The result is saved using the original file name. No backup copy of the original file is kept. Mode 2—Similar to Mode 1 except the source and destination files are stdin and stdout respectively.



Options



Because it is possible that an option keyword might be a desired from-text, to use one of the options you must specify a null or empty field first, followed by the option keyword. For example: >replace my.txt ("" nocase "existing text" "new text"



The above command uses the NOCASE option. If you had entered the command: >replace my.txt (nocase "existing text" "new text"



it will report a syntax error because the “nocase” token and the “new text” token are interpreted as from-text arguments but there is no matching totext argument for the “new text” token. NOCASE



Indicates that the case mode of the from-text item and the text in the file should be ignored when looking for matches. The case of the to-text item is used when text is replaced.



Replace 493



 NODATA



Commands



Notes



Indicates that, when a from-text item is replaced in the file, if the result is a blank line then the line should be deleted from the file.



The to-text argument may be a null or empty string. To specify an empty string use a pair of quotation marks with no characters between them. The return code is set to the total number of instances that from-text was found and replaced with to-text.



Cautions



No backup copy of the original file is made.



Restrictions



Because the from-text and to-text are specified with ASCII text strings, the file should be an ASCII text file. For instance, a MultiUser BASIC source program file can be used if it was saved with the SAVEA or SAVEU commands.



See also



LineEdit, WinWrite



494 Replace



 Restore Command The Restore command retrieves the “archive copy” of a file, set of files or an entire disk volume. This command is the complement of the TArchive command.



RESTORE



from-drive to-drive ( options



2



RESTORE



file to-drive ( options



3



RESTORE



from-drive ( SHOW options



4



RESTORE



from-drive ( VERIFY



Commands



1



aaa



»



account name



d



»



drive code or disk volume name



lll



»



disk volume name of first disk in archive



file



»



file name with optional path; may contain wild cards



from-drive



»



drive letter of archive source or logical tape name



name



»



archived file name



nnn



»



new directory size



to-drive



»



drive letter of destination disk



options



»



ACCOUNT ALL ASK CLEAR DRIVE d FROM aaa LABEL lll



MULTIUSE NAME name NEWFILE NOASK NOQUERY NOSYSFILE



NOTYPE OLDER OLDFILE PRTnn QUERY REPLACE



REWIND SHOW SIZE nnn SUBDIR TYPE VOLUME



The Restore command only restores files from an archive volume created with the TArchive command or the Archive command from a THEOS 4.x system. The archive volume contains special, compressed copies of files. See “TArchive” on page 601. The TArchive and Restore commands have been replaced with the TBackup command.



Restore 495



 Operation



Mode 1—Restores all of the files from the archive volume in from-drive to the disk in to-drive. >restore tape s



Commands



Mode 2—Restores file from the archive volume to the to-drive in the current account. Unless one or more options are used to indicate otherwise, the file in the archive volume must be owned by the current account name. >logon private >restore some.file:f s (noask Searching for account "PRIVATE". Searching for file "SOME.FILE". Restoring "SOME.FILE:S". >logon develop >restore those.files.*:f s (from private Source is Disk F Destination is Disk S Mount volumes now: Source is labeled "ArchiveD". Archive from disk "THEOS" on 10/15/96, at 08:36. Destination is labeled "THEOS". OK to start restore (Y/N) Y Searching Searching Restoring Restoring Restoring Restoring Restoring



for account "PRIVATE". for file "THOSE.FILES". "THOSE.FILES:S". "THOSE.FILES.FILE1:S". "THOSE.FILES.FILE2:S". "THOSE.FILES.FILE3:S". "THOSE.FILES.FILE4:S".



In this mode files are always restored to the current account. Mode 3—Displays a file listing of the files in the archive volume in fromdrive. >restore f (show Account: 10\PRIVATE Filename Filetype Member SOME THOSE



FILE FILES



FILE1 FILE2 FILE3 FILE4



28 Aug 2001 9:01am Page 1 Dr



Date 01/26/01 01/20/01 03/19/00 09/00/00 10/22/01 12/01/87



Time Org Protect



Size



12:46 13:34 17:09 11:28 11:34 05:00



1335 1280 1284 2257 31 9895



S L S S S S



..WR.... ........ ..W..... ..W..... ..W..... ..W.....



The SHOW option does not have to be specified. 496 Restore



Recl Keyl 20



 >restore f Account: 10\PRIVATE Filename Filetype Member SOME THOSE



FILE FILES



Dr



Date 01/26/01 01/20/01 03/19/00 09/00/00 10/22/00 12/01/87



Time Org Protect



Size



12:46 13:34 17:09 11:28 11:34 05:00



1335 1280 1284 2257 31 9895



S L S S S S



..WR.... ........ ..W..... ..W..... ..W..... ..W.....



Recl Keyl 20



Mode 4—Verifies the integrity and readability of the archive volume in from-drive. It also displays a listing of the files in the archive volume similar to the display output by the TArchive. This mode does not compare the archive volume to its original source disk. Options



ACCOUNT



Tells Restore to only restore those files from the archive volume that are owned by one account. This is a default option when Mode 2 is used. If the FROM account option is not specified, an implied FROM current-account is used. That is, only those files owned by the account that you are currently logged onto are restored. >restore tape s (account noask Searching for account "SYSTEM". Restoring "SYSTEM.B3220LIB:S". Restoring "SYSTEM.B3220LIB.ACCESS:S". ...



The ACCOUNT option is the opposite of the VOLUME option. ACCOUNT is the default option when Mode 2 is used; VOLUME is the default option when Mode 1 is used. ALL



Restores files from the archive volume even if the file already exists on the to-drive and even if the file has erase protection set. Also see the options NEWFILE, OLDFILE and REPLACE.



Restore 497



Commands



FILE1 FILE2 FILE3 FILE4



28 Aug 2001 9:01am Page 1



 ASK



This is a default option that instructs Restore to ask the operator to mount the source and destination volumes and waits for confirmation that the proper volumes are mounted. >restore tape s



Commands



Source is TAPE1 Destination is Disk S Mount volumes now: Source is labeled "Archived". Archive from disk "THEOS" on 10/15/96, at 08:36. Destination is labeled "THEOS". OK to start restore (Y/N)



The first question, “Mount volumes now,” must be answered with an (EnterÌ˛). All responses other than (EnterÌ˛) or (F9) are ignored. The second question, “OK to start restore (Y/N),” may be answered with any response. All responses other than (N) are treated as a (Y) response. CLEAR



Tells Restore that, before restoring the first file, the directory of to-drive is to be cleared. A current directory size is used unless the SIZE option is also specified. This option may only be used when option VOLUME is in effect with a Mode 1 Restore. When restoring to the S drive with this option you must be in single-user mode...the MULTIUSER option is ignored. Also, the NOASK option is ignored. After the restore you are prompted to reboot the system.



DRIVE d



Used with a multiple disk archive volume to specify that you want to restore only those files that were archived from drive d. d may be specified as a drive code or a volume name. >archive s a b tape (noask notype >restore tape c (drive a



This Restore command restores the files to the C drive that were archived from the A drive.



498 Restore



 FROM account Tells Restore to only select those files on the archive vol-



ume that were owned by account name account at the time the archive was created. See the second Mode 2 example. LABEL label Tells Restore that the multiple disk/tape archive volume uses



This label is used in the prompt messages only and is not related to the disk label written when a disk is formatted. MULTIUSER



Allows Restore to restore to a public drive even though other users may be logged on and active. Normally, when Restore is instructed to perform a full volume restore (option VOLUME) on a public disk, it requires single-user mode. If other users are logged onto the system, it displays the message: “Must be single-user or private volume.” Using this option tells Restore to not restrict the restore to single-user operation (the message is still displayed). THIS CAN BE EXTREMELY DANGEROUS! If another user changes some files while the restore is being done, the integrity of the files restored may be lost. Use this option only if you are sure that all other users are inactive.



NAME name Specifies the name of the archive volume set. When the file-



type is not specified in name the default file-type of ARCHIVE is used. When this option is not used the name of the archive volume must be ARCHIVE.VOLUME01. NEWFILE



Specifies that Restore will only attempt to restore a file if it does not already exist on to-drive.



NOASK



Disables the source and destination volume operator confirmation at the beginning of the restore and when subsequent disks or tapes are needed.



NOQUERY An option that tells Restore to not ask for confirmation on each



file being restored. In addition, this option suppresses the query when a file exists and the REPLACE option is not specified, as well as the query when a file exists, is protected and the ALL option is not specified.



Restore 499



Commands



disk/tape labels of label, with each disk/tape of the set incrementing the last character of label. For instance, disk one is labeled “Mon-1,” disk two is labeled “Mon-2” and so on.



 With NOQUERY in effect the following questions are never asked: Ok to restore "XXX" (Yes/No/All) File "XXX" exists, ok to restore (Yes,No,All) File "XXX" protected, ok to restore (Yes,No,All)



Commands



NOSYSFILES Do not restore operating system files. See “NOSYSFILES” on page 503. NOTYPE



Tells Restore to not display account names, subdirectory names, library names or file names on the standard output device as they are being restored.



OLDER



Only restore files if the file does not exist on the destination or if the existing file on the destination is older than the archived file.



OLDFILE



Specifies that Restore will only attempt to restore a file if it does exist on to-drive. This option implies the REPLACE option.



PRTnn



Indicates that Restore is to print the display of account names, subdirectory names, library names and file names on the attached printer number nn. The option keyword PRT may be specified as PRT, PRINT or PRINTER. PRINTER1 may be specified as P.



QUERY



Tells Restore that the operator is to be “queried” or asked if each file matching the selection criteria is to be restored. >restore f s (noask query notype Ok to restore "SAMPLE.FILE:S" (Yes/No/All) N Ok to restore "SELECTED.EXEC:S" (Yes/No/All) N



When the “Ok to restore” question is asked, you may respond with a (Y) for yes, (N) or (EnterÌ˛) for no or (A) for all. Responding with (A) means yes to this file and all remaining files are included without being queried. Respond with (Esc) to cancel the restore (files already restored remain restored).



500 Restore



 REPLACE



This option tells Restore that it is okay to attempt to restore a file even if it already exists on the to-drive. When this option is not used (and the NOQUERY option is not used), an attempt to restore an existing file causes you to be queried: File "XXX" exists, ok to restore (Yes,No,All)



REWIND



When source is tape, rewind to start of tape before beginning the restore operation. This is a default option.



SHOW



Display the contents of the archive volume without restoring any files.



SIZE nnnn Used in conjunction with the CLEAR option. This option tells Restore what size to make the newly cleared directory on the



to-drive. SUBDIR



Tells Restore to restore the files into the current working directory. When this option is not used, files are restored to the todrive’s root directory. This option is normally only used when restoring files that were archived from a root directory. When restoring a file that was in a subdirectory, it is restored to that same directory but subordinate to the current working directory. For instance: /SUBDIR/SOME.FILE:S is archived and then you CHDIR to the SUBDIR directory and perform a restore with the SUBDIR option. The file is restored to /SUBDIR/SUBDIR/SOME.FILE:S.



TYPE



A default option that tells Restore to display each account name, subdirectory name, library name and file name on the standard output device (normally the console) as it is being restored. This display can be redirected. The display with this option differs between an ACCOUNT restore and a VOLUME restore. A VOLUME restore displays like the TArchive display, showing the account names, subdirectory names, library names and file names with indentation to indicate the hierarchy of the account and directory structure.



Restore 501



Commands



Valid responses are identical to the QUERY option responses.



 For instance, the following is a typical display during a full volume restore:



Commands



ACCOUNT: 2=SAMPLES File: READ.ME File: SAMPLES.EXEC Subdirectory: C32 Library: C32.CMD32 Member: C32.CMD32.FINS Member: C32.CMD32.PRTF ...



An ACCOUNT restore displays a simple message for each file restored: Searching Restoring Restoring Restoring Restoring Restoring ...



for account "SAMPLES". "READ.ME:S". "SAMPLES.EXEC:S". "/C32/C32.CMD32:S". "/C32/C32.CMD32.FINS:S". "/C32/C32.CMD32.PRTF:S".



When a qualifying file cannot be restored for some reason, the TYPE option displays an appropriate message: File "XXX" not restored because file exists. File "XXX" not restored because disk full. File "XXX" not restored because directory full.



To disable this option use the NOTYPE option. VOLUME



Restores the entire archive volume to the to-drive. This is the default option with Mode 1 and can only be used with Mode 1.



Defaults



ASK and TYPE are default options. VOLUME is a default option with Mode 1, ACCOUNT is a default option with Mode 2.



Restrictions



The Restore command requires a privilege level of four. Individual files on a multivolume archive can only be restored with the Mode 2 form of this command if the files are on the first volume of the archive set. When the files are on secondary volumes of the set, use the Mode 1 form of the command with the QUERY option.



502 Restore



 NOSYSFILES



When the NOSYSFILES option is specified, the following sets of files are skipped if found on the archive volume. System command files System help files System menu files Commands



Device drivers Class code definitions etc. See also



TArchive, Backup, CopyFile, Disk, Tape, TBackup



Restore 503



 Commands



504 Restore



 RMCP Command Similar to the POP3Test command, the RMCP command checks a mail server to see if there is any mail available for a specified email account.



user@host



user



»



E-mail account name



host



»



Domain or host of account



Operation



Commands



RMCP



Using the Remote Mail Checking Protocall (RMCP) the host is contacted with user as the account name. The response code received from the mail server is interpreted and displayed on the console and the return code is set to reflect this response. The possible messages displayed by this command are: You have new mail. You have some old mail. You have no mail. There may also be error messages displayed.



Notes



Account names are case-sensitive on some servers. To ensure that the account that you provide is the same as the ones given to the host, enclose the argument in quotation marks. >RMCP "[email protected]"



No text is displayed on the console when this command is executed from an EXEC program or a MultiUser BASIC language program using the SYSTEM or CSI statement or a C language program using the system() function.



RMCP



505



 Return Codes



Because this program is frequently invoked from within a program the return code is set to specific code reflecting the status of mail for the user@host.



Commands



RC



See also



506 RMCP



Meaning



0



There is no mail on the server for this account.



1



Some connection error occurred or the server does did not respond.



2



There is no new mail for the user on the server but there is some old mail there.



3



There is some new mail for the user on the server.



POP3Test, TheoMail



 RmDir Command The RmDir or Remove Directory command erases a subdirectory and all of its files.



RMDIR



directory… ( options »



subdirectory name; may contain path; may contain wild cards



options



»



NOQUERY NOSAVE NOTYPE QUERY TYPE



Command synonym: Operation



RD



Note: This command does not normally remove directories from disk. Instead, it moves the requested directory and its files to the recycle bin. You must use the NOSAVE option to remove the directory from the disk with this command. Refer to Recycle Bin in the THEOS Corona Version 5 Operating System Reference manual. The directory or directories specified are erased. >rmdir subdir1 subdir2 "/SUBDIR1:S" erased. "/SUBDIR2:S" erased.



If a directory contains files or subordinate directories, you are asked to confirm that you want to remove the directory and all of its subordinate files and directories. >rd sample (notype



RmDir 507



Commands



directory



 Options



NOQUERY



Indicates that you do not want to be asked for confirmation before erasing a subdirectory containing files.



Commands



>rd subdir1 (noquery "/SUBDIR1/TEST1.FILE:S" erased. "/SUBDIR1/TEST2.FILE:S" erased. "/SUBDIR1/TEST3.FILE:S" erased. "/SUBDIR1/SUBDIR11/TEST1.FILE:S" erased. "/SUBDIR1/SUBDIR11/TEST2.FILE:S" erased. "/SUBDIR1/SUBDIR11/TEST3.FILE:S" erased. "/SUBDIR1/SUBDIR11:S" erased. "/SUBDIR1/SUBDIR12:S" erased. "/SUBDIR1:S" erased.



Subdirectories that do not contain files are not queried, even without this option. NOSAVE



Causes the directories to be erased from the disk at this time. When this option is not specified and the drive is an image drive or hard disk drive, the directories are simply moved to the recycle bin.



NOTYPE



Tells RmDir to not display the results of each file or directory erased on the standard output device. >tree / subdir1 subdir11 subdir12 subdir2 >rd subdir1 (noq >tree / subdir2



QUERY



508 RmDir



Tells RmDir to “query” or ask if each directory matching the file specifications is to be removed. This is a default option when wild cards are used.



 When the “Ok to remove” question is asked, you may respond with a (Y) for yes, (N) for no or (A) for all. Responding with (A) means yes to this directory and all remaining directories are removed without being queried. Respond with (C) or (Esc) to cancel the remove operation. TYPE



>rmdir * "/SUBDIR1:S" erased. "/SUBDIR2:S" erased.



To disable this option use the NOTYPE option. Notes



The command name RD is a synonym to the RmDir command. It is not a separate program but only an entry in the /THEOS/OS/MESSAGES/language/ SYNONYM.TXT file and, if standard synonyms are disabled (see “Account” on page 13 of this manual and “STDSYN” on page 110 of the THEOS Corona Version 5 Operating System Reference), this synonym name may not be allowed. This command does not normally remove the directory or its files from disk. Instead, it moves the requested directory and files to the recycle bin. You must use the NOSAVE option to remove the file from the disk with this command.



Recycle Bin



When the NOSAVE option is not used, all of the files erased by this command are not actually erased. Instead, the file is moved to the recycle bin which is a special, reserved directory on the SYSTEM account. Should the need arise, an erased directory and its files can be recovered from this recycle bin by using the UnErase command. However, due to space limitations, files in the recycle bin are not retained forever.



Defaults



TYPE is a default option.



See also



FileManager, Erase, UnErase



RmDir 509



Commands



A default option that tells RmDir to display the results of each file and directory erased on the standard output device. This display can be redirected.



 Commands



510 RmDir



 Route Command The Route command displays and maintains the routing tables used to establish network paths to various IP addresses. ROUTE



2



ROUTE ( PRTnn



3



ROUTE ( ADD net-addr net-mask gateway-addr host-addr



4



ROUTE ( DELETE net-addr net-mask



Commands



1



gateway-addr



»



dotted IP address of gateway machine



host-addr



»



dotted IP address of NIC in local machine used to access gateway-addr



net-addr



»



dotted IP address of destination network



net-mask



»



dotted subnet mask for the destination network



The routing table maintained by this command is the internal, memory-resident table. This table is created dynamically each time that the network is started. It is a combination of default entries, entries provided by a gateway (if any) and by dynamic network processes such as DialUp Networking. It is augmented by the routes defined with this command and by routes defined in the /THEOS/CONFIG/NETROUTE.CFG:S file. Operation



Mode 1—Displays the current internal routing table on stdout. >route Net Address



Subnet Mask



Gateway Address Host Address



127.0.0.1 127.255.255.255 127.0.0.0 192.168.100.1 192.168.100.255 192.168.100.0



255.255.255.255 255.255.255.255 255.0.0.0 255.255.255.255 255.255.255.255 255.255.255.0



127.0.0.1 127.0.0.1 127.0.0.1 127.0.0.1 192.168.100.1 192.168.100.1



127.0.0.1 127.0.0.1 127.0.0.1 127.0.0.1 192.168.100.1 192.168.100.1



Mode 2—Displays the current internal routing table on the designated printer. Mode 3—Adds another route definition to the internal routing table. >route (add 192.168.0.0 255.255.255.0 192.168.100.2 192.168.100.1



The above command adds another entry to the routing table. Route 511



 Mode 4—Deletes a route definition from the internal routing table. >route (delete 192.168.0.0 255.255.255.0



Notes



For most networks, it is not necessary to modify this table.



Commands



All IP addresses starting with 127 are “loopback addresses.” By convention, only the 127.0.0.1 address is used. Network packets addressed to this address are not sent to the network hardware. Instead, they are captured by the network software and handled internally on this machine. When the network on this machine wants to send a network packet to another node on the network the internal routing table is used to determine and control what path is used to find that machine. For instance, the following diagram shows a typical, small LAN with access to the Internet through an router. The router could be replaced with a DSL modem or a network modem-sharing device. It could even be a computer with a proxy server and modem connection to an ISP. .1



.3



.2



.5



.4



.7



.6



.9



.8



.100 router



The .1, .2 etc. references are to the last portion of the IP address of the node.



Each of the THEOS-machine nodes on the LAN can use the default routing tables generated when the network software is started. These default routes are identical with the exception that each machine’s routing table points to its own NIC address. Assuming that the LAN is a Class C network addressed with 192.168.100.*, the routing table for the .1 node is:



512 Route



Net Address



Subnet Mask



Gateway Address Host Address



0.0.0.0 127.0.0.1 127.255.255.255 127.0.0.0 192.168.100.1 192.168.100.255 192.168.100.0



0.0.0.0 255.255.255.255 255.255.255.255 255.0.0.0 255.255.255.255 255.255.255.255 255.255.255.0



192.168.100.100 127.0.0.1 127.0.0.1 127.0.0.1 127.0.0.1 192.168.100.1 192.168.100.1



192.168.100.1 127.0.0.1 127.0.0.1 127.0.0.1 127.0.0.1 192.168.100.1 192.168.100.1



 This table specifies: Line 1: All packets not routed by the other entries are sent to the router at 192.168.100.100 via the NIC addressed at 192.168.100.1. Line 2: All packets addressed to localhost are sent to the loopback address.



Line 5: All packets addressed to this machine (from this machine) are sent to the loopback address. Line 6: All packets broadcast to the local network are sent to this network via the NIC addressed at 192.168.100.1. Line 7: All packets broadcast to other machines on the subnet are sent to this network via the NIC addressed at 192.168.100.1. A more complex network might be: .1



.3



.2



.5



.4 .9



.7



.6



.9



.8



192.168.100.*



.100 router



192.168.50.*



.1



.2



This network is comprised of three networks: the 192.168.100.* LAN, the 192.168.50.* LAN and the Internet. One of machines has two NICs installed in it and acts as a “bridge” between the two LANs. Each of the machines on the 192.168.100.* LAN must be configured to route packets addressed to the other LAN through the .4 node. You could do this by using the Route command to add an additional route definition. On the .1 machine you would: >route (add 192.168.50.0 255.255.255.0 192.168.100.4 192.168.100.1



Route



513



Commands



Line 3 and 4: All packets broadcast to the localhost are sent to the loopback address.



 On the .2 machine you would: >route (add 192.168.50.0 255.255.255.0 192.168.100.4 192.168.100.2



Commands



Similar commands are done for each of the other machines except the .4 machine itself. On that machine the default routing is already different because the two NICs were configured in Setup NET. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.) Net Address



Subnet Mask



Gateway Address Host Address



0.0.0.0 127.0.0.1 127.255.255.255 127.0.0.0 192.168.50.9 192.168.50.255 192.168.50.0 192.168.100.4 192.168.100.255 192.168.100.0



0.0.0.0 255.255.255.255 255.255.255.255 255.0.0.0 255.255.255.255 255.255.255.255 255.255.255.0 255.255.255.255 255.255.255.255 255.255.255.0



192.168.100.100 127.0.0.1 127.0.0.1 127.0.0.1 127.0.0.1 192.168.50.9 192.168.50.9 127.0.0.1 192.168.100.4 192.168.100.4



192.168.100.4 127.0.0.1 127.0.0.1 127.0.0.1 127.0.0.1 192.168.50.9 192.168.50.9 127.0.0.1 192.168.100.4 192.168.100.4



These additional entries tell the network software to “forward” all packets received for the 192.168.50.* network to that network by transmitting them via the NIC at 192.168.50.9. No additional routing entries need to be added on this machine. Similar routing entries must be added to the machines on the 192.168.50.* LAN.



514 Route



 Initial Routing Table



When the network is first started at boot time or with the NET START NETWORK command, the internal routing tables are initialized to include: A path to the default gateway, if defined Three entries for loopback addresses Three entries for each NIC IP address defined



During the course of operation, additional entries are added and deleted from the routing table due to transient PPP connections. Restrictions



Routes added or deleted by this command are only defined until the network is restarted by a system reboot. If you want the changes made with this command to be used the next time that your network is restarted, you must manually add them to the /THEOS/CONFIG/NETROUTE.CFG:S file.



Route



515



Commands



Entries copied from the /THEOS/CONFIG/NETROUTE.CFG:S file, if any



 Commands



516 Route



 Script Command Process and format the text in a file including page headings, paragraph justification, chapters, contents, etc.



SCRIPT



filename ( options



2



SCRIPT



filename outfile ( FILE options



3



SCRIPT



filename readfile ( options



Commands



1



filename



»



Script text file with commands



outfile



»



Name of output file when FILE option used



readfile



»



File name for source of READ command variables



options



»



Cnn FILE



Operation



INDEX PRTnn



REPEAT nn TYPE



WAIT



nn mm



Mode 1—Process the text and commands in the file filename and output the result according to the options specified. Mode 2—Process the text and commands in the file filename and output the result to outfile according to the options specified. Mode 3—Process the text and commands in the file filename and output the result according to the options specified. If there are any READ commands in filename, they read their values from readfile.



Options



Cnn



Use printer class code nn for formatting the output.



FILE



Output the formatted result to outfile. outfile must be specified as the first parameter after filename.



INDEX



Only create and output the index information.



PRTnn



Output the result to printer nn.



REPEAT nn Producs nn copies of the output. TYPE



Output the result to the console.



WAIT



Pause at the end of each page for operator confirmation/ release.



Script



517



 nn mm Defaults



Only output from page nn through page mm.



The default output is to the console.



Commands



The initial definition of the special characters is: . (period) for start of command, @ for escape, _ for underline, & for boldface. Script Commands



ALIGN



Align following text lines to the left or to the right.



APPENDIX Start a new appendix. BIBLIOGRAPHY Start the bibliography. BREAK



Line break.



BOX



Draw a box.



CENTER



Center some text.



CHAPTER



Start a new chapter.



CONTENTS Insert table of contents here. COPY



Copy and process a file.



CPI



Set the character size.



EJECT



Start a new page.



END



End of this file.



FAX



Invoke THEO+Fax.



FILL



Set fill mode.



FOOTING



Set left and right footing text.



FORMAT



Format text.



FOREWARD Begin forward. GLOSSARY Begin glossary. GUTTER



Set inside and outside gutter character.



HEADING



Set left and right heading text.



HYPHENATE



518 Script



Enable word hyphenation or define hyphenation for a word.



 IGUTTER



Set inside gutter character.



INDENT



Set paragraph indent.



INDEX



Insert index here.



INPVAR



Read value of variable.



JUSTIFY



Commands



INTRODUCTION



Begin introduction.



Set justify mode.



LFOOTING Set left footing text. LHEADING Set left heading text. LINE



Create line of repeated characters.



LINK



Link to a new text file.



LPI



Set lines per inch.



LSIZE



Set left page size.



LMARGIN



Set left margin.



NOFILL



Turn off fill mode and justification.



NOHYPHENATE



Disable hyphenation mode.



NOJUST



Disable justification mode.



OGUTTER



Set outside gutter character.



PAGE



Conditional eject.



PARASKIP Set paragraph spacing. PART



Start a new part.



PAUSE



Wait for operator to respond.



PITCH



Define font sizes to use.



POSITION



Move to line position.



PREFACE



Begin preface.



READ



Read values for a variable from an external file.



Script



519



 REMARK



Comment line.



RFOOTING Set right footing text.



Commands



RHEADING Set right heading text. RMARGIN



Set right margin.



RSIZE



Set right page size.



SECTION



Start a new section.



SETAPPENDIX SETBOLD



Define next appendix letter.



Define boldface character. (&)



SETCHAPTER SETCOL



Define next chapter number.



Define tab character.



SETCOMM Define command character. (.) SETESCAPE SETHYPH



Define escape character. (@)



Define hyphenation character (-).



SETITALIC Define italics character. SETPAGE



Define next page number.



SETPART



Define next part number.



SETSPACE Define hard space character SETTAB



Define tab character.



SETUNDERLINE



520 Script



Define underline character. (_)



SETVAR



Define variable value.



SIZE



Set page size.



SKIP



Output blank lines.



SPACE



Set line spacing.



TABSET



Define tab stop columns.



TITLE



Define output as book and set book title.



 Variables and codes



Display text on console.



.



This character is used at the beginning of a line that is a command. The character can be changed with the SETCOMM command.



&



This character surrounds text that is to be boldfaced. Character can be changed with the SETBOLD command.



_



This character surrounds text that is to be underlined. Character can be changed with the SETUNDERLINE command.



@



The following character is to be interpreted differently than normal. This “escape” character can be changed with the SETESCAPE command.



@1 - @99



Variables.



@D



Date in mm/dd/yy format.



@d



Date in Monthname, dd, yyyy format.



@T



Time in hh:mm (24 hour) format.



@t



Time in hh:mm am/pm format.



@P



Current page number.



@S



Current chapter or appendix name.



@,



Tab to center or right zone (only in heading/footing/format text).



@;



Begin new line (only in heading/footing/format text)



Script



521



Commands



TYPE



 Commands



522 Script



 See Command Filter The See command copies a file to the standard output device, making all nonprintable characters visible.



SEE



2



SEE



file Operation



file...



»



Commands



1



file name with optional path; may contain wild cards



Mode 1—Each file in the list of files is copied to the standard output device. Each nonprintable character in file is displayed with two or three displayable characters: Nonprintable character values less than the space character (32) display with a leading up-caret ( ^ ) followed by the control character. For instance, a tab character displays as ^I. Nonprintable character values greater than 127 display with a leading tilde ( ~ ) followed by the display for the character value minus 128. For instance, the character value 137 displays as ~^I and the value 159 displays as ~^_. The DEL character (value 127) displays as ^?. The end-of-line character (carriage return) and NULL characters (0) display as a dollar sign ( $ ) unless the file specification is preceded with a minus sign character. >see system.cmd32.repeat system.cmd32.repeat:s: ; get type of first argument$ &t = &typ &1$ $ ; validate count and command$ &if (&index < 2) | (&t <> N)$ ^I&control off$ ^Ihelp repeat$ ...



Multiple files can be specified on the command line: >see file1 file2 file3



See



523



 Each file is displayed on the standard output device. The minus sign specification (Mode 2) can be used to indicate that the end-of-line character is not displayed as a dollar sign:



Commands



>see - system.cmd32.repeat system.cmd32.repeat:s: ; get type of first argument &t = &typ &1 ; validate count and command &if (&index < 2) | (&t <> N) ^I&control off ^Ihelp repeat ...



Multiple files can be specified, some without the minus sign specification and some with: >see file1 file2 file3 - file4 file5



In the above command, the first three files are output with the dollar sign character displayed and the last two files are displayed without this character. Mode 2—Copies the file from standard input to standard output, displaying the nonprintable characters as described above. This mode is normally used when the See command is part of a pipe. >upcase system.cmd32.repeat | see ; GET TYPE OF FIRST ARGUMENT$ &T = &TYP &1$ $ ; VALIDATE COUNT AND COMMAND$ &IF (&INDEX < 2) | (&T <> N)$ ^I&CONTROL OFF$ ...



The minus sign specification can be used with this mode: >upcase system.cmd32.repeat | see ; GET TYPE OF FIRST ARGUMENT &T = &TYP &1 ; VALIDATE COUNT AND COMMAND &IF (&INDEX < 2) | (&T <> N)



Restrictions



file must be a stream file.



See also



List, More



524 See



 Send Command EXEC The Send command is an EXEC language program that gives you convenient, command-line access to the THEO+COM command’s file send capability.



SEND



file ( options



2



SEND



file ( FILES options



file



»



file name with optional path; may contain wild cards



options



»



ASCII COMnn EOT



Operation



NOEOT THEOS TRACE



Commands



1



TRACEFILE fn XMODEM-1K XMODEM YMODEM XMODEM-CRC



Mode 1—Invokes the THEO+COM command in SEND mode. The first attached COM device is used unless the COMnn option is specified. If no protocol option is specified, the THEOS protocol is used. If the connection to the other computer is via a modem, it is assumed that the telephone connection has already been established with the Dial command or by using THEO+COM directly. >dial 1 800 123-4567 Dialing 1 800 123-4567 >send updated.stocklst



Mode 2—Similar to Mode 1, except file is an ASCII stream file that contains one file description per line. The SELECTED.FILES and SELECTED.EXEC files created by FileList and the FOUND.EXEC created by Look can be used for this specification file (see “The EXEC and FILES Options” on page 239). You may also create the file with an editor or application program. For instance, FileList is used to create a list of files to be sent: >filelist *.data:a (exec >filelist a not *.data:a (10/1/00 exec append



A file now exists that lists all of the “data” files and all files that have been changed since 10/01/2000. The following command sends these files to another computer connected via a COM attachment: >send selected.exec (file



Send



525



 The THEOS protocol must be used in this mode. The files are sent with NOEOT in effect for all files except the last file, which uses EOT.



Commands



Protocol..... File name.... File size.... Blocks....... Transmitted.. Byte count... Block count.. File count... Elapsed time. Errors....... Message...... Progress.....



Send THEOS MY.DATA:S 1,235 5 0% 0 0 1 0:02 0 Waiting for receiver



File transfer in process. Press ESC to cancel.



Options



ASCII



Use the ASCII file transfer protocol. Essentially, this is no protocol and should be used only for short text files.



COMnn



Use the currently attached COMnn for the communications port. When this option is not specified, the first attached COM device is used.



EOT



A default option that tells THEO+COM to send the end-of-transmission codes after the file is sent. To disable this option use the NOEOT option.



NOEOT



Tells THEO+COM to not send the end-of-transmission codes after the file is sent. This option is used when several files will be sent. >send this.file (theos noeot >send that.file (theos eot



The above two commands send the two files to another computer. The other computer used the Receive command only once because the first file used NOEOT and the transmission was not terminated.



526 Send



 THEOS



Use the THEOS SEND/RECEIVE protocol. This is the default protocol.



TRACE



Enables file transfer tracing. A window is opened in the upperright corner of the display, showing the protocol activity during a transfer.



ity is output to the file fn. XMODEM



Use XMODEM checksum, 256-byte protocol.



XMODEM-CRC Use XMODEM CRC-16, 256-byte protocol. XMODEM-1K Use XMODEM-1K, CRC-16, 1024-byte protocol for single file



transfers. YMODEM



Use YMODEM CRC-16, 1024-byte protocol. This protocol might be called YMODEM-BATCH in the other computer’s communication program because it can receive multiple files.



Notes



Refer to the THEO+COM Installation and User’s Guide manual for a full description of the operation of file transfers and the protocols used.



Defaults



The first attached COM device is used by default and the THEOS protocol is the default.



Restrictions



A COM device must be attached.



See also



Dial, PutFile, Receive, THEO+COM



Send



527



Commands



TRACEFILE fn Similar to the TRACE option except that the protocol activ-



 Commands



528 Send



 SendMail Client The SendMail client is a utility program that sends a text file as a mail message to a mail server on the network. This program is designed with a simple, command-line interface suitable for usage as a tool in application programs. For a mail client with a more userfriendly interface, use the TheoMail described on page 653.



SENDMAIL filename



Commands



1



( options



filename



»



name of file on local system



options



»



ATTACH BCC CC



FILES FROM HTML



RAW REPLYTO SMTP



SUBJECT TO



Operation



filename is sent to the SMTP Server specified in the THEOS E-mail configuration file (/THEOS/CONFIG/EMAIL). At a minimum, the TO and FROM option must be specified with valid e-mail addresses.



Options



ATTACH



Specifies that a file is attached to the message when it is sent. The file may be a text file or a non-text file such as a program or binary stream data file. The file must be accessible from the current account. Multiple files may be attached to a message by using the ATTACH option multiple times. >sendmail my.message (to [email protected] from [email protected] subject "example message w/attachments" attach sample.attach1 attach sample.attach2



The attached files may be of any type. As a THEOS command, it automatically converts formatted data files and compiled programs to a portable format. BCC



Indicates that a “blind carbon-copy” of the message is sent to the address specified. Recipient addresses specified with the BCC option receive a copy of the message. However, their address does not appear in any of the headers in any of the copies of the message sent. >sendmail my.message (to [email protected] from [email protected] bcc [email protected] subject "You're history"



SendMail



529



 The above command sends the my.message file to both [email protected] and [email protected]. However, both copies are received with [email protected] in the “To” field and nothing in the “CC” field. Received messages never have a “BCC” field. Compare with the CC option described next. Commands



Multiple BCC addresses may be specified by either using one BCC option with an argument containing multiple addresses separated by comma, space, or by using multiple BCC option specifications. For instance, the following two commands produce the same result: >sendmail my.message (to [email protected] from [email protected] bcc [email protected] bcc [email protected] subject "Your termination" >sendmail my.message (to [email protected] from [email protected] bcc "[email protected], [email protected]" subject "Your termination" CC



Indicates that a “carbon-copy” of the message is sent to the address specified. >sendmail my.message (to [email protected] from [email protected] cc [email protected] subject "You're history"



The above command sends the my.message file to both [email protected] and [email protected]. Both copies are received with [email protected] in the “To” field and [email protected] in the “CC” field. In other words, all recipients of the message see that the message was sent to the addresses specified with the TO option and the CC option. Compare with the BCC option described above. Multiple CC addresses may be specified by either using one CC option with an argument containing multiple addresses separated by comma, space, or by using multiple CC option specifications. FILES



530 SendMail



Indicates that filename is not the name of the file to be mailed, but is a file that contains a list of files to be mailed. The files SELECTED.EXEC, SELECTED.FILES and FOUND.EXEC created by the FileList, Look and FileManager commands can be used for this purpose.



 For instance, the FileList command is used to create a list of messages to be sent: >filelist *.message:a (01/20/01 exec



&1 ABC.MESSAGE:A &2 &3 &4 &5 &6 &7 &8 &9 &10 &1 GENERAL.MESSAGE:A &2 &3 &4 &5 &6 &7 &8 &9 &10 &1 GEORGE.MESSAGE:A &2 &3 &4 &5 &6 &7 &8 &9 &10



Only the file names in each line are used. Other characters are ignored. Assuming that these message files each start with the message headers necessary to send the message, they can be sent with this command: >sendmail selected.exec (files



Note that the SELECTED.FILES file created with the FileList command is only usable when the FD option is used also. For instance: >filelist *.message:a (01/20/01 files fd



FROM



Specifies the e-mail address of the author or creator of the message. This should be your e-mail address but, in fact, may be any valid-appearing address. The domain-name of this address must be valid because most mail servers will perform a DNS lookup on the domain-name specified. All e-mail messages must have a “From” field specified. It may be specified either with this command-line option or, if embedded mail headers are used, with one of those. >sendmail my.message (to [email protected] from [email protected] replyto [email protected] subject "Example message"



HTML



The text portion of the mail message is already formatted with HTML tags and SendMail should use the appropriate MIME headers to indicate this when it sends the message.



RAW



This option specifies that the filename already contains all of the necessary MIME headers and SendMail should send the message without examination or modification.



SendMail



531



Commands



This creates a SELECTED.EXEC file containing a list of all of the message files on the A drive that were created or modified after January 19, 2001. This file might look like:



 REPLYTO



Specifies the e-mail address you want replies sent to. This should be your e-mail address and should refer to an actual e-mail account. Use this option when you want replies to a message to be sent to a different address than the one specified in the “From” field.



Commands



>sendmail my.message (to [email protected] from [email protected] replyto [email protected] subject "New product release"



Most e-mail clients (TheoMail, for example) provide an easy method of addressing a response to a received message. The address used by those “reply-to” capabilities of e-mail clients is the address specified with this REPLYTO option. When a REPLYTO address is not specified, the FROM e-mail address is used by e-mail clients. SMTP server



This option causes server to be used as the SMTP server instead of any value that might have been defined in the SETUP SMTP configuration file.



SUBJECT



Specifies the general subject of the message. Although not required, every message should have a subject line. The subject text may appear on the recipient’s e-mail client’s mailbox summary screens.



TO



Perhaps the most important piece of information in a message header, this option specifies the recipient address for the message. The address specified must be a valid e-mail address. >sendmail my.message (to [email protected] from [email protected] subject "New product release"



Multiple destination addresses may be specified with the CC or BCC options (along with this TO option) or by specifying a TO argument containing multiple addresses separated by comma, space, or by specifying the option multiple times. For instance, the following three commands will each send the message to [email protected] and [email protected]: >sendmail my.message (to [email protected] from [email protected] cc [email protected] subject "Staff meeting at 1:00" >sendmail my.message (to "[email protected], [email protected]" from [email protected] subject "Staff meeting at 1:00"



532 SendMail



 >sendmail my.message (to [email protected] to [email protected] from [email protected] subject "Staff meeting at 1:00"



Embedded Mail Headers



The addressing headers for a message may be specified on the command line or with embedded headers at the beginning of the message file. For instance, a message file containing A staff meeting is scheduled at 1:00pm today in the 4th floor conference room. Your attendance is required. The Boss.



This file could be sent with the following command: >sendmail my.message (to "Alice " from "J.C. " subject "Staff meeting at 1:00"



If the message uses embedded headers, such as: To: Alice  From: J.C.  Subject: Staff meeting at 1:00 A staff meeting is scheduled at 1:00pm today in the 4th floor conference room. Your attendance is required. The Boss.



It can be sent with the following command: >sendmail my.message



SendMail



533



Commands



The difference between these messages will only be in the interpretation by the recipient. The first form sends the message to you with an informational copy to yourboss. The second and third forms send the message with equal importance to both recipients.



 The following headers may be embedded at the start of a message file:



Commands



To: Cc: Bcc: From: Subject: Reply-to: Attach: When used, the mail headers must be the first lines in the file, they must start on the first column of the line and there must be one or more spaces following the colon character. A blank line separates the mail headers from the body of the message. Do not include any blank lines between embedded mail header lines. The Attach embedded header is followed with the path to the desired attachment file. You may use more than one Attach header when you want to attach multiple files. Wild cards are not permitted. When a file uses embedded mail headers, do not use any of the following command-line options: BCC, CC, FROM, REPLYTO, SUBJECT or TO. You can use the command-line options ATTACH and FILES. E-mail addresses



The general form for an e-mail address specification is: accountname@domainname



For instance: [email protected] [email protected]



The domain name portion of an e-mail address must always be a valid domain name. Most mail servers validate the domain name for every address specified, prior to attempting to send the message. The account name portion of the e-mail address must also be valid if the address is used as a destination address. For instance, addresses specified with the TO, CC and BCC options are destination addresses. Addresses specified with the options FROM and REPLYTO should contain valid account names because they may be used by the recipient as destination addresses for replies to the message. Since many account names are cryptic, an e-mail address may include comment text that specifies a real person’s name or department. When comment text is included as part of the e-mail address, the actual address is enclosed within a pair of angle brackets. For instance:



534 SendMail



 "John Doe "



Comment text may appear before or after, or before and after the actual e-mail address. "John Doe  FYI only"



The message file may use an embedded command that causes another text file to be included in the message. For instance, • MESSAGE.TEXT file: %include /sendmail/staff.distrib% From: The Boss  Subject: Weekly Staff Meeting %include weekly.meeting% %include 010311.agenda% We will also be discussing plans for the company picnic and vacation schedules. %include signature.files.theboss%



• STAFF.DISTRIB file: To: Cc: Cc: Cc:



Tom  Shirley  Richard  Rebecca 



• WEEKLY.MEETING file: The weekly staff meeting is scheduled for Wednesday in the 4th floor conference room.



• 010311.AGENDA file: Agenda for March 11, 2001 meeting: Widget sales status Sales incentives Increased CEO bonus



• SIGNATURE.FILES.THEBOSS file: John Curtis (J.C.) President Widgets, Inc.



As illustrated in the above example, the %include command feature is very useful for creating “boilerplate” messages, for specifying e-mail distribution lists, etc. The referenced file is included only when the file is transmit-



SendMail



535



Commands



Including Text Files



 ted by SendMail. The above example transmits as if it contained the following text:



Commands



To: Tom  Cc: Shirley  Cc: Richard  Cc: Rebecca  From: The Boss  Subject: Weekly Staff Meeting The weekly staff meeting is scheduled for Wednesday in the 4th floor conference room. Agenda for March 11, 2001 meeting: Widget sales status Sales incentives Increased CEO bonus We will also be discussing plans for the company picnic and vacation schedules. John Curtis (J.C.) President Widgets, Inc.



When the %include command is used, it appears on a line by itself, starts on the first column of that line, and starts and ends with the percent symbol ( % ). It may be used at any location in the file, including the mail headers section. An included file may contain %include commands, with a maximum of 32 levels of nesting, including the original message file. The file name referenced in the %include command may include absolute or relative path specifications as long as the file is still accessible from the account used to actually send the message. Notes



The E-Mail configuration file is created and maintained with the Setup Email command which is described in the THEOS Corona Version 5 Operating System Installation and Setup Guide. Enclose the option arguments within quotation marks. Although not required, without quotation marks the arguments will be folded to uppercase and embedded commas or spaces will terminate the argument. When there are more than 50 addresses in the To, Cc and Bcc fields (command-line options or in the embedded addressing fields), multiple copies of the message are sent, 50 addresses per message.



536 SendMail



 SendMail Command Restrictions



The E-Mail Configuration file must have a SMTP Server defined (see Setup SMTP in the THEOS Corona Version 5 Operating System Installation and Setup Guide).



Every message must have a “To” field specified with the TO option and a “From” field specified with the FROM option or embedded mail headers. See also



EmailChk, EmailDel, EmailGet, EmailPut, TheoMail



Examples



The following is a simple MultiUser BASIC language program. It accepts the various fields of information for a message and then sends the message. OPTION BASE 1, CASE "M", PROMPT "" DIM MSG$(100) START: ! First, paint the screen WINDOW OPEN ADDROF(MAIN%),1,1,80,24; SELECT UPDATE ON PRINT AT(20,1);"Send Mail to Remote Recipient"; PRINT AT(1,4);"To:"; PRINT AT(1,5);"From:"; PRINT AT(1,6);"Subject:"; PRINT AT(1,8);"CC:"; PRINT AT(1,9);"BCC:"; PRINT AT(1,10);"Reply To:"; WINDOW OPEN ADDROF(MSG%),2,13,78,9;FRAME SINGLE; SELECT UPDATE TOP; TITLE " Message Text " TOP, CENTER ENTER.MESSAGE: WINDOW SELECT MAIN%, UPDATE ON ENTER.TO: ! Accept message header information PRINT AT(12,4); LINPUT USING RPAD(TO$,60), TO$ TO$ = TRIM(TO$) IF UCASE(TO$)="END" THEN GOTO END.JOB IF TO$="" THEN GOTO ENTER.TO ENTER.FROM: PRINT AT(12,5); LINPUT USING RPAD(FROM$,60), FROM$ FROM$ = TRIM(FROM$) IF FROM$="" THEN GOTO ENTER.FROM PRINT AT(12,6); LINPUT USING RPAD(SUBJ$,60), SUBJ$ SUBJ$ = TRIM(SUBJ$) PRINT AT(12,8); LINPUT USING RPAD(CC$,60), CC$ CC$ = TRIM(CC$)



SendMail



537



Commands



The file name specified for the message text file, and any %include files, must refer to ASCII text files. These files, and the optional attachment files, must be accessible from the current account. The file name specification may include the path specification.



 Commands



PRINT AT(12,9); LINPUT USING RPAD(BCC$,60), BCC$ BCC$ = TRIM(BCC$) PRINT AT(12,10); LINPUT USING RPAD(REPLYTO$,60), REPLYTO$ REPLYTO$ = TRIM(REPLYTO$) WINDOW EDIT MSG%, 100, MSG$ ! Get message body WINDOW SELECT MAIN%, UPDATE ON PRINT AT(1,23);"Okay to send? "; LINPUT USING "!", REPLY$ IF UCASE(REPLY$)="N" THEN GOTO ENTER.MESSAGE MSG.COUNT% = 0 FOR I% = 100 TO 1 STEP -1 ! Find out how many message lines IF TRIM(MSG$(I%))<>"" MSG.COUNT% = I% I% = 0 IFEND NEXT ! Make sure that there is a message IF MSG.COUNT% PRINT AT(1,23);"Creating message file...";CRT("EOL"); MSG.FILE$ = SYS.ENV$(20,"SENDMAIL.XXXXXX") ! Work name OPEN #1:MSG.FILE$, OUTPUT SEQUENTIAL ! Save msg in file PRINT #1:"To: ";tO$ PRINT #1:"From: ";FROM$ IF SUBJ$ THEN PRINT #1:"Subject: ";SUBJ$ IF CC$ THEN PRINT #1:"Cc: ";CC$ IF BCC$ THEN PRINT #1:"Bcc: ";BCC$ IF REPLYTO$ THEN PRINT #1:"ReplyTo: ";REPLYTO$ PRINT #1: ! Blank line separates headers from body FOR I% = 1 TO MSG.COUNT% PRINT #1:MSG$(I%) NEXT CLOSE #1 PRINT AT(1,23);"Sending message...";CRT("EOL"); SYSTEM "SENDMAIL "&MSG.FILE$ ! Send the message ELSE PRINT AT(1,23);"No message text...ignoring!";CRT("BELL"); SLEEP 2 IFEND ! Clear input areas on screen MAT MSG$ =("") \ WINDOW CLEAR MSG% WINDOW SELECT MAIN%, UPDATE ON REPLYTO$ = "" \ PRINT AT(12,10);CRT("EOL"); BCC$ = "" \ PRINT AT(12,9);CRT("EOL"); CC$ = "" \ PRINT AT(12,8);CRT("EOL"); SUBJ$ = "" \ PRINT AT(12,6);CRT("EOL"); FROM$ = "" \ PRINT AT(12,5);CRT("EOL"); TO$ = "" \ PRINT AT(12,4);CRT("EOL"); PRINT AT(1,23);CRT("EOL"); GOTO ENTER.MESSAGE END.JOB: QUIT



538 SendMail



 Session Command The Session command allows you to control the attributes, position and size of the session window.



function



»



CHANGE DISABLE ENABLE



FOCUS MAXIMIZE MINIMIZE



MOVE RESTORE



Commands



SESSION function SIZE TITLE



Operation



Set the session attribute or position as specified.



Options



CHANGE OFF Disable session-switching. Applies to the console and all



sessions of this console. CHANGE ON Enable session-switching ( (Break),n and (Break),Fn and



(Break),(Tab̢) and application program switching). CHANGE ? Display the current session-switching status. DISABLE attr Disable mouse changes of session attribute. attr may be one



of: MAXIMIZE MINIMIZE MOVE SIZE



The session attributes can still be changed with the Session command or with application programs using the appropriate API. ENABLE attr Enable mouse changes of session attribute. attr may be any



of the ones listed above. The attr are normally enabled by default are only disabled by a specific call to the Session command or with an application API call. FOCUS



Make this session the active session. Normally, this would only be invoked from an EXEC program or by a Force command.



MAXIMIZE



Maximize the session to the full console screen size. A maximized session has no frame and no title displayed.



MINIMIZE



Minimize the session to an icon.



Session



539



 MOVE col row Move the upper-left corner of the session window to col, row



position on the screen. RESTORE



Restore the session window to its normal size and position (not MINIMIZE or MAXIMIZE).



Commands



SIZE width height Set the session width to width columns and the session height to height lines. Similar to using the Attach command to



change the console size. >session size 80 24



TITLE text



Set the session title to text. text should be enclosed within quotation marks. When text is not specified (TITLE is the last option specified on the command line), the title is set to the default title which is the currently logged on account name.



Defaults



The session attributes are enabled when a session is first started. The position, size and maximize/minimize state are the last values saved when the system was last shutdown or rebooted.



See also



Attach, Reboot, ShutDown, TWS



540 Session



 Set Command The Set command sets and changes system and user-defined environment parameters.



SET



system-env-name value



2



SET



user-variable=value



3



SET



Commands



1



system-env-name



»



ABBREV on-off BREAK c COPYLIB lib CWD dir DATE date DATEFORM n DATEIN n DATEOUT n



user-variable



»



user-defined environment variable



value



»



value to assign to environment variable



Operation



HISTORY on-off LIBRARY lib LINKLIB lib MSG on-off OBJLIB lib PATH path PRIORITY n PROMPT string



QUIT on-off RDYMSG on-off SEARCH drive-seq SUBDIR dir SYNONYM file TIME time WORKVOL drive



Mode 1—Changes a system-defined environment parameter. These parameters are normally set in the Account environment for each user. >set rdymsg on RC = 0, 16:58:36, ET = 0:00, CPU = 0.088 >



A description for each of the system-defined environment names can be found in Chapter 7 “User Account Environments” of the THEOS Corona Version 5 Operating System Reference. Because setting the date and time is different than setting other environment variables, it is described separately, on page 542.



Set 541



 Mode 2—Changes a user-defined environment parameter. User-defined environment parameters may be any name that uses alphanumeric characters, does not contain a space character, and is not the same as a systemdefined environment parameter. >set MyName="Ralph Kramden"



Commands



>set showname="The Honeymooners"



The value of a user-defined environment parameter may be any string of characters. If the value contains characters that might be misinterpreted by the CSI, you should enclose the value in a pair of double quotation marks. To clear a user-defined environment parameter, specify nothing after the equal sign. >set username=(EnterÌ˛)



Mode 3—This mode displays all of the currently defined environment variables, system- and user-defined, along with their values. >set RDYMSG = OFF MSG = ON WORK = M SEARCH = S DESCRIPTION = System maintenance account USERNAME = Boss PROMPT = !14\a!15\ s !4!!\!!5> CLIST = YES HOME = /:S LANGNAME = English OSVER = 5.0 OSPL = 50099 PROFILE = Office



Date and Time



All of the system- and user-defined environment names are assigned values without any special input form or confirmation response. There are two exceptions: DATE and TIME. DATE. Changing this variable changes the system’s date which is used by the system and application programs. The date may be changed by entering the new date on the command line: >Set date 3/5/02 Date is set to Tuesday, March 5, 2002. >Set date 3.7 Date is set to Thursday, March 7, 2002.



542 Set



 The date is interpreted by the Set command using the currently set DATEFORM format.



The date may also be changed by using the Date Selection form: >Set date (Enter)



Commands Unlike most other parameters, changing the DATE or TIME requires a privilege level of five and it affects all users on the system. TIME. Changing this variable changes the current system time. When setting the time you must specify the hours and minutes. You may also specify the seconds. Since time can be set to the nearest second you are prompted to press a key when you want the system time set to the specified time. >Set time 12:15(Enter)



Set 543



 Notes



Environment variables have values that are strings, numeric values or Boolean values (true/false). Single-word strings are assigned normally: >Set UserName Fred



Commands



Multiple word strings are assigned by enclosing the string within quotation marks: >Set FullName "John Q. Adams"



For variables that are Boolean in nature, some have YES/NO values and others have ON/OFF values, depending upon their usage. Refer to their description in the Chapter 7 “User Account Environments” of the THEOS Corona Version 5 Operating System Reference. The syntax for assigning values may include the equal sign or you may omit it. The following commands are both acceptable for the same assignment: >Set FileType Basic >Set FileType=Basic



The Logoff command clears all user-defined and system-defined environments. The Logon command resets only those parameters that are defined in the Account environment. The parameters DATE, DATEFORM, DATEIN, DATEOUT, HISTORY and TIME affect all users on the system. These parameters (except for DATE and TIME) are normally only set in the system configuration file (Sysgen command). Defaults



The default or initial values for most of the environment variables are set during system boot using information from the Sysgen command or when you log onto an account.



Restrictions



User-defined environment parameter values may not contain a double quotation mark. That character is ignored when assigning the value to the name. Changing the DATE, DATEFORM, DATEIN, DATEOUT, HISTORY or TIME parameters requires a privilege level of five. Changing the PRIORITY for your process requires a privilege level of three.



See also



544 Set



Account, ChDir, Logon, Mailbox, Msg, Show, Sysgen



 Setup Command The Setup command provides a single command to configure and initialize the major components of THEOS Corona and various types of devices.



SETUP



2



SETUP function



3



SETUP NET subfunction



function



Operation



»



ACCOUNT CACHE CENTLP COLOR CRT CX DIGIXE DISK EMAIL



Commands



1



FAX FD950 FLOPPY FONT INSTALL MAKEBOOT MAXSPEED MIXER NET



PRINTER PROFILE RECYCLED RESTORE SIO SMTP SNDCARD SOUND SPOOLER



SYSGEN TIME TYPES UNINSTALL UPDATE UPS USERCOUNT VGA



Mode 1—Invokes Setup in its menu mode. See “Setup Menu” below. Mode 2—Bypassing the Setup Menu, the function screen is displayed. Refer to “Functions” on page 546. Mode 3—Invoking Setup with a function and a subfunction is only applicable when the function is NET. The Setup NET invoked with Mode 2 displays a menu of the subfunctions available when configuring your network. If you know you only want to configure one portion of the network and you know the subfunction name that you want to configure, then specify that subfunction on the command-line. For instance, >setup net dhcp



The above command invokes the configuration program for the DHCP server. Setup Menu



When Setup is invoked with Mode 1, the Setup Menu is displayed. This menu is dynamic because only those components installed on your system are presented in the menu. For instance, if you to not have the DigiBoard CX software installed on the system, the CX menu item is not offered.



Setup



545



 Commands



There may be additional items displayed on the menu, depending upon any add-on products that you may have installed on your system. Use the normal menu selection keys to select the desired function. These keys are described in “Using Menus” on page 77 of the THEOS Corona Version 5 Operating System Reference. Functions



The various functions that can be configured with the Setup command are described in the THEOS Corona Version 5 Operating System Installation and Setup Guide.



Setup Command Restrictions



The Setup command can only be used when you are logged onto the SYSTEM account (account id zero). Although the Setup command requires only a privilege level of one, some of the functions may require higher privilege levels. Although Setup may be invoked from any console, because it primarily configures the system it is intended to be used from the main console. Many changes in configuration will not be effective until the system is rebooted.



See also



546 Setup



Account, ClassGen, Disk, FileManager, Sysgen, Tape



 Shell Command The Shell command is designed to be called from another program. It provides access to the “CSI shell” so users may temporarily leave a program, enter commands and, upon completion, return to that program.



Operation



The current program’s environment is saved and the CSI Shell is entered. Upon entry, the CSI clears the currently active window and displays the reminder message: THEOS® Command SHELL Type "EXIT" to terminate.



If the current prompt string contains the default CSI prompt character ( > ), it is displayed with the blink attribute as a reminder to the operator that the user is in the CSI Shell and should return back to the calling program. An example usage from a MultiUser BASIC Version 2.1 program might be: 001000 001010 001020 001030 001040 001050 001060 ...



WINDOW WINDOW WINDOW WINDOW



OPEN 1,2,10,76,10; COLOR 7,4 FRAME 1, RAISED, RIGHT, COLOR 7,4 TITLE 1," CSI Shell ", CENTER TOP, COLOR 6,4 SELECT 1



SYSTEM "shell" PRINT "I'm back...";



CSI Shell THEOS® Command SHELL Type "EXIT" to terminate. >



Shell



547



Commands



SHELL



 Notes



As illustrated in the example, the Shell command uses the current window for its display and input. That window is cleared before Shell displays its reminder message.



Commands



Files are not closed by this command. However, the statement or function that you use to invoke the command in your program may. For instance, in a MultiUser Basic language program, if you use the SYSTEM statement to invoke the Shell command, no files are closed. If you use the CSI statement to invoke the Shell command, your files will be closed before invoking the Shell command. Use the Exit to exit the shell environment and return to the calling environment. The ability to use this command can be disabled by renaming or deleting the file /THEOS/COMMAND/SHELL.CMD:S. WindoWriter has a command-line option that can disable usage of the command during its editing session.



548 Shell



 Show Command The Show command displays the current value of system-parameters, user-variables and other information about the system.



SHOW



2



SHOW



env-name



3



SHOW



function



4



SHOW



*



Commands



1



env-name



»



ABBREV BREAK CALPHA CASE CLIST CMDLIB COPYLIB CREATE CWD DATEFORM



DATEIN DATEOUT DECIMAL DESCRIPTION FILETYPE FULLNAME HISTORY HOME LANG LANGNAME



LIBRARY LINKLIB MSG



PROMPT QUIT RDYMSG NOTLIBCOMPATIBLE SEARCH OBJLIB STDSYN OSPL SUBDIR OSVER SYNONYM PATH USERNAME PRIVLEV WORK name PROFILE



function



»



CLOCK DEVICE DISK IDE



IRQ MEMORY MEMORY * PCI



PCMCIA SCSI TAPE USB



USER USER n mm-nn VERSION WHO



Show 549



 Mode 1—Invokes the display showing all environment variables, IRQs, PCI devices, all disks, tapes and other devices. When this mode is used a form is displayed with a drop-down list of the various devices that it can show:



Commands



Operation



Settings. Shows the currently defined environment variables.



550 Show



 Interrupt Request Table (IRQ). Shows the 16 IRQ numbers and the devices that use these IRQ numbers and the addresses associated with them. When adding a new device to the computer, this information is useful in determining which IRQs are available for use by the new device.



Commands



A text-only, non-object display of this information can be obtained by using the command SHOW IRQ. Peripheral Component Interconnect (PCI). Shows the PCI devices currently configured on this system.



Show 551



 A text-only, non-object display of this information can be obtained by using the command SHOW PCI.



Commands



PCMCIA / PC-Card. This display will normally only be useful on laptop computers. It shows all of the currently installed PC-cards on the system.



A text-only, non-object display of this information can be obtained by using the command SHOW PCMCIA. Universal Serial Bus (USB). If the system supports USB ports, the hub, adapter and installed devices are displayed:



552 Show



 A text-only, non-object display of this information can be obtained by using the command SHOW USB. Disk/CD-ROM devices. This item displays all of the hard disk and CDROM disc devices that are currently connected to the system. These devices are listed whether they use IDE, SCSI, USB, PCMCIA, I2O or ATAPI technology. Commands



A text-only, non-object display of this information can be obtained by using the command SHOW DISK.



Show 553



 Commands



SCSI Devices. Shows the SCSI devices (Small Computer System Interface) currently configured on this system.



The “Rem” column indicates whether or not the device uses removable media. A text-only, non-object display of this information can be obtained by using the command SHOW SCSI. Tape Devices. Displays information about all, currently attached TAPE devices.



554 Show



 A text-only, non-object display of this information can be obtained by using the command SHOW TAPE. Device Properties. Displays information about all, currently attached devices.



Commands



The above display reports on the same devices that the Attach command lists but this display provides different information about those attached devices. A text-only, non-object display of this information can be obtained by using the command SHOW DEVICE. Mode 2—This mode displays a specific system-parameter or user-defined variable. >show search SEARCH = S >show fullname FULLNAME = John Doe



For a list and description of the system-defined environment names refer to Chapter 7 “User Account Environments” in the THEOS Corona Version 5 Operating System Reference. Mode 3—Display the requested function display. Each of the functions is described below in the Functions section.



Show 555



 Mode 4—Displays the following information:



Commands



>show * ACCOUNT USERNUM PORT PRIVLEV LOGON ABBREV MSG RDYMSG SEARCH WORKVOL SERIAL IDENT SYNONYM SUBDIR LIBRARY PATH OBJLIB COPYLIB LINKLIB



556 Show



= = = = = = = = = = = = = = = = = = =



SYSTEM 0 16 9 15:29:09 09/04/01 ON ON OFF S M 102-12345 "TheosServer" USER.SYNONYM /



 Functions



CLOCK



Displays the current time and date continuously. The time is updated once per second. Use the (Esc) or (F9) to quit. >show clock 16:12:24 PST Thursday, January 17, 2002.



Use the Clock command to display a graphic clock. Commands



DATE



Displays the current time and date, once. >show date 16:12:24 PDT Monday, April 20, 2002.



MEMORY



Displays a summary of the current memory usage.



MEMORY * Displays a map of all of memory, followed by the summary dis-



play above.



Show 557



 TIME



Displays the current time and date, once. This is synonymous to the DATE function. >show time 16:12:24 PDT Monday, April 20, 2002.



Commands



You can use the CLOCK function to display the time continuously or the Clock command to display it graphically. USER



Displays a continuous status report of all defined processes which is refreshed every second. The number of processes or tasks is defined in the system configuration with the Sysgen command. Unused processes are omitted.



The buttons “End Task,” “Stop,” “Peek” and “Exit” are only available if you have sufficient privilege. The privilege level required for these features is defined in the file /THEOS/CONFIG/ SHOWUSER.CFG:S file, in the entry “ButtonPriv=.” If this file or entry does not exist then the privilege level required is 5. These buttons may also be suppressed by using the option NOASK.



558 Show



 The “Status & Info” column uses codes for the status condition of the process: Code *



Indicates that this is the process performing the Show USERS . Process is waiting for semaphore nn to be set.



I



Waiting for interrupt. Usually, the program is waiting for another character from the console.



L



Waiting for a locked resource.



N



(Break),(Q) is disabled for the process.



O



(Break),(O) is in effect for the process.



P



Stopped by (Break),(S) or screen pause command.



R



The process is running a program.



Z



Process is “sleeping.”



This function can be used with the option PRIORITY. >show user (priority



When this option is used, the priority for the user (1-7) is displayed immediately following the status codes. USER n…



Displays a status report for process n. Multiple processes can be specified by listing the process numbers: >show user 1 2 5 6 7 10



The above command displays the status for the six processes listed. Any unused process is omitted from the display. Ranges of processes can be specified by using the syntax n-m where n is the from process number and m is the to process number. For instance: >show user 1-4 10 16-20



This command displays the status for processes 1, 2, 3, 4, 10, 16, 17, 18, 19 and 20. Any unused process is omitted from the display.



Show 559



Commands



E=nn



Meaning



 Displays the version and date for the operating system and all major components installed on your system.



Commands



VERSION



The list of programs displayed by the VERSION function comes from the file /THEOS/MENU/language/SHOW_VER.MNU. Note the display of the “THEOS Corona Operating System,” “Network Login Server” and “Twindows Server” items. In the “Version” column for these items, in addition to the version number the number of licensed users is also reported. For the TWindows Server this is reported as two numbers, the first number identifies the number of network TWS users and the second number the number of serial TWS users. WHO



Displays information identifying you and your process. >show who ACCOUNT = USERNUM = PORT = PRIVLEV = LOGON =



SYSTEM 0 16 5 15:29:09 01/04/02



Notes



When the environment variable LINEGRAPH is set to “N,” the line graphics used in the display for MEMORY and VERSION are suppressed.



Restrictions



The display for Show USER and the Show MEMORY * functions requires a privilege level of five.



See also



Account, Set, Sysgen, Who , WhoAmI



560 Show



 ShutDown Command The ShutDown command allows you to shutdown or reboot your computer.



SHUTDOWN



2



SHUTDOWN ( option



option



Operation



»



DOS FAST LINUX NOQUERY



NOTYPE QUERY REBOOT RESET



SHUTDOWN SINGLE THEOS TYPE



Commands



1



UPDATE WINDOWS



The ShutDown command operates identically to the Reboot command except for the default options enabled. Mode 1—This mode is identical to the following command: >Reboot (shutdown query



Mode 2—This mode is identical to the Reboot command. Options



Refer to the option description for the Reboot command.



Cautions



This is an extremely dangerous command because other users are terminated without notice. If another user is in the process of updating one or more files, those files will be inaccurate because the update was not completed. Always do a Show USERS or a Who command before using this command and verify that all other users are at a Logon, CSI or stopped.



Restrictions



The ShutDown command requires a privilege level of five.



See also



Reboot



ShutDown



561



 Commands



562 ShutDown



 Sleep Command The Sleep command causes your process to suspend execution for an interval of time or until a specified time-of-day.



SLEEP



seconds



2



SLEEP



time-of-day



seconds



»



number of seconds to sleep



time-of-day



»



time to wake up



Operation



Commands



1



Mode 1—Sleeps for seconds number of seconds. >sleep 30



This command puts your process to sleep for 30 seconds. Mode 2—Sleeps until the system clock is equal to time-of-day. >sleep 23:30



This command puts your process to sleep until 11:30 pm. Notes



Once “sleeping” has started with this command it may only be awakened early by entry of the (Break),(Q) or by a Force from another user. The EXEC language has its own &sleep statement, BASIC has its own SLEEP statement and C has its own sleep function. If you need to put the process to sleep while executing a program, it is more efficient to use one of these statements or functions.



Restrictions



seconds must be an integer number.



Sleep 563



 Commands



564 Sleep



 Sort Command Filter This command sorts a stream file using the entire record as a sort key or designated portions of each record as the sort key.



SORT -options -o output infile…



2



SORT -options +position1 -position2 -field-options -o output infile…



+position1



»



sort key start position



-position2



»



sort key end position



output



»



optional output file name with optional path



infile



»



file name with optional path



field-options



»



b d



f i



n r



options



»



b c d



f i m



n r tn



Commands



1



u



Sort is a filter program and, as such, defaults to using the standard input device for its input file and the standard output device for its output file. It is suitable for use in pipes. >list vendor.names | sort -d | more



The above command sorts the output of the LIST command using dictionary order and then displays the sorted output with the MORE command. Operation



Mode 1—Sorts the infiles into one output file using the entire record as the sort key. >sort -o sorted.data unsorted.data >sort -briu -o sorted.data unsorted.data



The above two commands sort the file UNSORTED.DATA. The result of the sort is output as SORTED.DATA. The first command sorts the file using the sort order of the ASCII collating sequence. The second command also sorts the file but it ignores leading blanks in the records and it ignores any characters outside the range of ASCII characters. It also ignores duplicate records and outputs the file in reverse sequence.



Sort



565



 Mode 2—Sorts the infiles into one file using the designated sort keys for determining the sort order of the records. Input Files



Sort can sort multiple input files into a single output file. Merely list the input files on the command line, one after the other.



Commands



>sort -o sort.output sort.input1 sort.input2 sort.input3



The sequence of the listed input files does not matter unless the -m option is used. If no input file is specified, the standard input device is used for the input file. Sort can sort as large an input file or files as will fit in available memory.



Sort Keys



Unless otherwise specified, the entire record is used as a sort key. By using the +position and -position fields, portions of the record can be specified as the sort key(s). The format for +position and -position is f.c where f is the number of fields to skip from the beginning of the record and c is the number of characters to skip from the beginning of the field. Fields are separated in records with a tab character. If a different character is used to separate fields, the -t option must be used to identify the separating character. For instance, a specification of +3.2 indicates that the sort key starts with the third character of the fourth field in the record. Multiple sort keys can be specified. For example: >sort +3.2 -3.10 +1.0 -1.20 sort.input -o sort.output



This command line states that the file SORT.INPUT is to be sorted using two keys, one starting with the third character of the fourth field through the eleventh character of the fourth field and the other using the first 21 characters of the second field. Each sort key may have its own field-options specified immediately following the sort key specifications. For example: >sort +3.2 -3.10 -ri +1.0 -1.20 -n sort.input -o sort.output



Sort keys that do not have their own field-options use the options specified for the entire sort. These options are specified before the sort key specifications.



566 Sort



 Options



b



Ignores leading blanks and other white space characters in the sort key for comparison purposes. Input Keys



Comparison Keys



John F. Kennedy



John F. Kennedy



John F. Kennedy F.



Kennedy



John F. Kennedy



c



Checks if input files are already sorted.



d



Uses dictionary order when comparing sort keys. In dictionary order the sort order is changed so that digits come last, preceded by letters. All other characters (punctuation and other nonalphanumeric characters) are ignored when comparing two sort keys.



f



For sort purposes, folds uppercase sort key characters to lowercase. Thus, “AARDVARK” sorts to the same location as “aardvark.”



i



Ignores characters outside of the ASCII set of 7-bit characters for sort purposes only. This ASCII set of characters includes all of the characters from character value 32 (space) through 127 (tilde).



m



Indicates that no sorting is to be done; the infiles are merged into the outfile in the sequence that the infiles are specified.



n



The key is a number and should be sorted according to the value of the number. Sort Keys



w/o -n option



with -n option



423



2



2



32



20



20



2



200



32



20



32



200



200



423



423



r



The key is sorted in descending order, not the normal ascending sequence.



tc



Specifies that the tab, or field delimiting character, is the character c. This option is used with the +position and -position



Sort



567



Commands



John



John F. Kennedy



 options to specify that a character other than (Tab) separates the fields in the record. >sort "-t," +2.0 +0.0 names.data



Commands



This command sorts a file of names and specifies that the comma character separates the fields in the records. It is placed in quotation marks to prevent the CSI from interpreting the comma as one of its characters. Input Keys



u



Defaults



Sorted Keys



Ken, E., Larvik



Joseph, William, Cone



Robert, G., Holbrook



Duncan, S., Holbrook



Michael, K., Malley



Robert, G., Holbrook



Robert, L., Lewison



Ken, E., Larvik



Shirley, L., McCartney



Robert, T., Lewis



Duncan, S., Holbrook



Robert, L., Lewison



Robert, T., Lewis



Michael, K., Malley



Joseph, William, Cone



Shirley, L., McCartney



Specifies that only records with unique keys are output. When this option is not used, records with duplicate sort keys are output in the sequence that they were found in the input file(s).



The default infile is the standard input device and the default outfile is the standard output device. The default sort sequence is ascending by character value. Refer to Appendix G: “THEOS Character Sets” of the THEOS Corona Version 5 Operating System Reference for a list of the characters and their values.



Restrictions



Only stream files are sorted with this command. The file is sorted using the currently available memory. Maximum line length of each record is 2,048 characters.



568 Sort



 Split Command Filter The Split command splits a stream file into multiple files, each one containing a portion of the original file.



SPLIT



infile outfile ( option



2



SPLIT -nnn infile outfile



infile



»



optional input file name with optional path



outfile



»



optional output file name with optional path



option



»



nnn



Operation



Commands



1



Both Modes 1 and 2 operate the same. The only difference is that Mode 2 is “UNIX-like” in syntax. The infile is read and output in nnn line chunks to the outfile. outfile name is modified with a two-letter suffix added. The first output file is outfileAA, the second is outfileAB, and so on. >split system.history system.hist (1000



This command divides the SYSTEM.HISTORY file into 1,000 line chunks. The first 1,000 lines are written to SYSTEM.HISTAA, the second 1,000 lines are written to SYSTEM.HISTAB, etc. Option



nnn



Defaults



The default number of lines for each of the output files is 100.



Specifies the number of lines each output file will contain. When not specified the default value of 100 is used.



When outfile is not specified the output file name is XAA. When infile is not specified the input comes from the standard input device. Restrictions



The infile must be a stream file. The nnn option must be a nonzero positive value.



See also



Cat



Split 569



 Commands



570 Split



 Spooler Command The Spooler command controls the print spooler.



SPOOLER printer



2



SPOOLER printer manager-function



3



SPOOLER printer function



4



SPOOLER



printer



»



Commands



1



optional spooled printer number



manager-function »



ATTACH options BUILD count drive FORM queue



INIT QUIT START



function



»



ABORT ALIGN report page BACKUP pages CHANGE report queue copies hold



report



»



nnn



page



»



page number



queue



»



letter



copies



»



number of copies to print



hold



»



HOLD NOHOLD



reports



»



report reports report-report reports *



STOP VERIFY KILL reports LIST PRINT report page STATUS



Spooler



571



 Operation



Mode 1—Displays the status of a spooled printer or on all of the spooled printers. >spooler 1 Printer #1 "CENTLP1" L80,P58,HPLASER,W8 -- is waiting for work -- and has form "A" mounted



Commands



>spool * Printer #1 --Printer #2 ----



"CENTLP1" L80,P58,HPLASER,W8 is waiting for work and has form "A" mounted "SIO3" L80,P58,CANON2 is printing report # 9 "CHECKREG" created by account ACCTNG - on page 7 of 9 and has form "B" mounted



Mode 2—Changes the status of a spooled printer or enables or disables the print spooler. >spooler 3 stop >spooler 3 Printer #3 "SIO4" L80,P58,EPSON -- is stopped -- and has form "C" mounted



Mode 3—Changes the attributes of a spooled report or performs print management of a spooled report. >spooler change 11 2 d hold >s list File Acc-name Rpt-name 11 SYSTEM



Date



Time



Q Pages C Status



DEVNAMES 09/05/96 16:25 D



9



2 Closed, Hold



Mode 4—Display form allowing interactive display of all spooled printers or spooled reports. Refer to “Spooler Status” on page 573 for a description of this mode.



572 Spooler



 Spooler Status When Mode 4 is used and the console is configured for graphics display, the following form is displayed:



Commands



Printer list box



This area displays each of the printers that are currently configured as spooled printers. The information displayed for each printer includes the printer number, printer name (see “Setup Printer” on page 173 of the THEOS Corona Version 5 Operating System Installation and Setup Guide), status, page and pages, report, report number, account, form device and attachment parameters. The values for page, pages, report, report number and account are only displayed when that printer is printing a report. The pages value refers to the total number of pages in the report.



Report



Pressing this button changes the display to the report listing form described on page 574.



Start



This button can be pressed to start the printer selected in the Printer list box. If the printer is already started, this button’s label is “Stop” and, when pressed, stops the selected printer.



Abort



If the printer selected in the Printer list box is printing a report this button is enabled. When pressed, report printing is aborted.



Form



Pressing this button allows you to change the form for the printer selected in the Printer list box. You are presented with a maintenance form allowing you to enter up to eight form letters for the selected printer.



Spooler



573



 Commands



Report Listing



When the Report button is used the display changes to:



Report list box



This area displays each of the reports that are currently queued. Use this area to select the report that you want to perform some action on with the buttons displayed on the right. Each report line shows the report number, account name that created the report, the report name, creation date, queue letter, printer to be used, pages in report, number of copies remaining to print and the current status of the report. You may have to scroll the list left or right to see all of these columns of information.



574 Spooler



Status



Pressing this button changes the display to the spooler status form described on page 573.



Order



Pressing this button changes the display order of the reports in the Report list box. There are four orders and each time the button is pressed the next order is used:



 Report number Queue letter then report number Creation date then report number Account name then report number Print



This button can be pressed to start printing the report selected in the Report list box. If the report is already printing or has been printed, this button is disabled. This button is labeled “Remove” or “Abort,” depending upon the status of the report selected in the Report list box. If the report is currently being printed the button is labeled “Abort” and pressing it aborts printing of that report. Otherwise, the button is labeled “Remove” and pressing it deletes the selected report from the queue.



Spooler Manager Functions



A Spooler Manager is a user who has sufficient privilege and is responsible for the printers controlled by the print spooler. The following functions are reserved for users logged onto the SYSTEM account with a privilege level of five. ATTACH options Changes the attachment parameters of the spooler’s



printer. Note that this attachment refers to the spooler’s printer and not the attachment of a logical printer to the spooler. You may change any of the attachment parameters except the actual device. For instance, if the printer is currently connected and attached to CENTLP1, you cannot change it to SIO4 with this function. To add or change the physical device used for a spooled printer, you must use the Sysgen command and then reboot the system. You may change any of the other parameters, such as baud rate, line and page length, class code, etc. >spooler 3 attach l132 p60 b38400 w8 e2 c135 >spooler 3 Printer #3 "SIO4" L132,P60,HPLASER,B38400,W8,XON/XOFF -- is waiting for work -- and has form "C" mounted



The printer must be either stopped or idle (waiting for work). You cannot change the attachment of a printer that is currently printing a report. BUILD nnn drv This function creates a new /THEOS/SPOOLER/SYSTEM.SPOOLER library. The only time that you might need to use



Spooler



575



Commands



Remove/Abort



 this function is when you are first installing the system and want to create a spooler queue library that is larger than the 400 member default size used when the spooler is first installed by the Sysgen command. >spooler build 2000 s



Commands



The nnn parameter specifies the size of the new /THEOS/ SPOOLER/SYSTEM.SPOOLER library and the drv specifies the drive used. If nnn is not specified, a library size of 400 is used. If drv is not specified, drive S is used. Make sure that the drv used here is the same drive specified in the INIT function or in the system configuration for the spooler. See “Sysgen” on page 591. Note: If you want to change the size of an existing /THEOS/ SPOOLER/SYSTEM.SPOOLER library, you must stop the print spooler, erase the existing library, and then use the BUILD option to create a new library. FORM queues Specifies which queues are printed on printer. >spooler 4 form r



This command tells the spooler that spooled printer 4 has form R mounted on it and that it can print any reports in the R queue. Refer to the description of “Forms and Queues” on page 581 for more information about form specifications. printer must be specified if there is more than one spooled printer. A printer may be printing from as many as eight queues. >spooler 3 form abcdefgh



This command tells the spooler that spooled printer 3 can print reports in queue A, B, C, D, E, F, G or H. >spooler 3 form "AX$g"



This command tells the spooler that spooled printer 3 can print reports in queue A, X, g or $. If a report is currently printing on printer, it will finish printing even if the report’s queue no longer matches the printer’s form. The queue of a report is only matched to the form of a printer when it first starts to print.



576 Spooler



 INIT drive



This function initializes and starts the print spooler. This initialization can also be done automatically at boot time if the “Enable Print Spooler” is set in the system configuration (see “Sysgen” on page 591).



At least one printer must be attached when this INIT function is performed. All printers that are currently attached are transferred to the print spooler. (Slave printers are not transferred and cannot be spooled.) For each physical printer that is transferred to the print spooler, a logical printer is attached to the spooler. These logical printers are available to you and to any other user when they logon to the system. (If they are already logged on they will have to Logon again to get these attachments.) Assuming that three printers are attached: >spooler init >spooler Printer #1 "CENTLP1" L80,P58,HPLASER,W8 -- is stopped -- and has form "A" mounted Printer #2 "SIO3" L80,P58,CANON2 -- is stopped -- and has form "B" mounted Printer #3 "SIO4" L80,P58,EPSON -- is stopped -- and has form "C" mounted QUIT



This function stops the print spooler. It is the opposite of the INIT function. You may only stop the spooler if the spooler is idle (not printing any reports) and the system is in single-user mode. In this case, single-user mode means that no other processs are started. >spooler quit



START



This function activates a specific spooled printer or all spooled printers. This is the opposite of the STOP function. >spooler 2 start



STOP



Stops a specific spooled printer. printer must be specified if there is more than one spooled printer. If a report is currently Spooler



577



Commands



drive is the disk drive code for the drive containing the /THEOS/ SPOOLER/SYSTEM.SPOOLER library. If drive is not specified, S is used.



 printing on printer, it is finished before that printer is actually stopped. >spooler 3 stop



Commands



>spooler Printer #1 "CENTLP1" L80,P58,HPLASER,W8 -- is waiting for work -- and has form "A" mounted Printer #2 "SIO3" L80,P58,CANON2 -- is waiting for work -- and has form "B" mounted Printer #3 "SIO4" L80,P58,EPSON -- is stopped -- and has form "C" mounted



It is best to STOP a printer before changing the paper in the printer. This insures that no report will print on the new paper until you tell the spooler that it is ready. Use the START function to restart the printer. VERIFY



Verifies that the spooler’s queue file matches the spooled reports that are in the spooler queue library and that the spooler queue library matches the spooler queue. This function can also be performed when the system is booted by enabling the “Check at system start” field in the system configuration (see Chapter 25 “Setup SysGen” of the THEOS Corona Version 5 Operating System Installation and Setup Guide). If errors are detected and it advises you to rebuild the spooler queue you must: 1. Use the QUIT function to stop the spooler (or boot the system in maintenance mode). 2. Erase the file /THEOS/SPOOLER/SYSTEM.SPOOLER:S and all of its member files. 3. Rebuild the file by using the BUILD nnn drv function. Or, if the spooler is configured and enabled in the system configuration file, reboot the system. The boot process will create a missing spooler library and queue when it starts the spooler (see “Setup SysGen” in the THEOS Corona Version 5 Operating System Installation and Setup Guide).



578 Spooler



 Functions



ABORT



Stops printing the current report on the specified printer. printer must be specified if there is more than one spooled printer.



To successfully abort a report may depend upon the printer’s status and the transmission protocol. If the printer is off-line or powered off and the transmission protocol requires a response from the printer, then the report will not abort until the printer is powered on and made ready to print. ALIGN report page Specifies that an alignment pattern is printed for



spooled report number report starting with page number page. If the page number is not specified, page one is assumed. printer must be specified if there is more than one spooled printer. The alignment pattern printed is a copy of the report’s page page with all letters on that page replaced with X’s and all digits on the page replaced with 9’s. After an alignment pattern is printed you are asked “Do you wish another alignment page (Y/N).” Respond with (N) to cause the report to print. Before responding with (Y) make any alignment adjustments on the printer. When the alignment pattern is accepted the report is printed starting with the same page number. A report is never printed nor is an alignment pattern created unless the report’s queue is the same as the requested printer’s form. If no printer is specified, the single spooled printer must have the proper form mounted. BACKUP pages After the current page of the current report being printed



on printer is printed, the report is backed up pages number of pages and printing resumes. Omitting pages causes the report printout to back up one page. printer must be specified if there is more than one spooled printer. CHANGE report queue copies hold Changes the attributes of spooled



report number report. You must be logged onto the same account, or a synonym account, as the account used to create Spooler



579



Commands



When a report is aborted, the spooler prints the message “**** A B O R T ****” and performs a form-feed. The report is marked as printed and the report copies is set to zero. If the report does not have HOLD status, it is deleted.



 the report. The queue, copies and hold attributes can be specified in any order and one or more may be omitted, indicating that that attribute is not changed.



Commands



The queue is a single character identifying one of the 64 possible queues. Refer to the description of “Forms and Queues” on page 581. copies is specified as one or two digits in the range 0–99. For descriptive purposes, you may specify the copies with the syntax COPIES=copies or COPY=copies. hold is specified with either HOLD or NOHOLD. If the report is currently printing and you change the queue to a letter that the printer is not set for, the report will continue to print on that printer. The queue of a report is only matched to the form of a printer when it first starts to print. KILL report Removes and deletes spooled report number report. If the



report is currently printing, it must be aborted first with the ABORT function. The ABORT function will kill the report unless it is marked as HOLD, in which case you must use the KILL function to remove it. report may be specified with * or it may specify a single report number, a range of report numbers, a list of reports numbers, or any combination of these. >spooler kill *



Removes all reports in the spooler queue. >spooler kill 8-11



Removes reports numbered 8, 9, 10, and 11. >spooler kill 2 6 7 33



Removes reports numbered 2, 6, 7 and 33. >spooler kill 1, 3, 30-33, 45, 50-55



Removes reports numbered 1, 3, 30, 31, 32, 33, 45, 50, 51, 52, 53, 54 and 55.



580 Spooler



 LIST



Displays a list of the spooled reports on the standard output device. The information displayed includes: Column File



Content The report number. Owning account name.



Rpt-name



Report name



Date Time



Date and time report created.



Q Pages



C Status



Queue of report. Number of pages in report. This is only an estimated number based upon the number of form-feeds in the report. Number of copies still to print. Current status of the report. Status messages include Open, Closed, Printing, Printed, Hold.



The return code is set to 1 if one or more reports listed. Otherwise it is set to zero. PRINT report page Specifies that spooled report number report is to be



printed on printer starting with page number page. If the page number is not specified, page one is assumed. printer must be specified if there is more than one spooled printer. The report is printed even if printer is currently stopped. A report is never printed unless the report’s queue is the same as the requested printer’s form. If no printer is specified, the single spooled printer must have the proper form mounted. STATUS



Forms and Queues



Reports on the status of the spooled printer or on all of the spooled printers. This is equivalent to a Mode 1 Spooler command.



Forms and queues are identified with single-characters. There are 64 possible forms and queues: A – Z



26 forms/queues



a – z



26 forms/queues



# $ % & * + - < = > ^ ~



12 forms/queues



Previous versions of the spooler only supported the first 26 forms and queues. To provide compatibility with programs and procedures designed for previous versions of the operating system, form and queue specifications default to the uppercase form and queue letters. Spooler



581



Commands



Acc-name



 To specify one of the lowercase form letters you must enclose the form within quotation marks. The 12 special character forms may be specified without quotation marks. For instance:



Commands



>spooler >spooler >spooler >spooler >spooler >spooler



1 1 1 1 1 1



form form form form form form



a "a" x % abc$ "Aix$%"



; ; ; ; ; ;



Refers Refers Refers Refers Refers Refers



to to to to to to



form A form a form X form % forms A, B C and $ forms A, i, x, $ and %



To specify one of the lowercase queue letters you must enclose the letter in quotation marks or use the special syntax “QUEUE=$queue.” >spooler >spooler >spooler >spooler >spooler >spooler



change change change change change change



2 2 2 2 2 2



a "a" $ queue=a queue=$a queue=$$



; ; ; ; ; ;



Refers Refers Refers Refers Refers Refers



to to to to to to



queue queue queue queue queue queue



A a $ A a $



When in doubt about how a form or queue specification will be interpreted by the Spooler command, always use quotes and then specify the desired character with the desired case. Restrictions



The functions ABORT, BACKUP, PRINT, ATTACH, FORM, START and STOP all require a privilege level of one. For all functions other than BUILD and INIT, the print spooler must be initialized before the function can be used.



See also



582 Spooler



Attach, Sysgen



 Start Command Stop Command The Start command starts a user, session or background task. The Stop command stops a user, session or background task. START process console ( attach-options



2



START process console ( attach-options ACCOUNT name PASSWORD password



3



START process console ( attach-options MODEM



4



START command



5



STOP



Commands



1



process



attach-options



»



console attachment parameters



command



»



any THEOS or user-supplied command name with parameters



console



»



physical device name for console attachment



name



»



account name for automatic logon



process



»



an unused process id number



password



»



account password



Operation



Mode 1—Starts a process as a user with console. process must be the number of an unused memory process. The number of memory processs is defined in the field “Maximum Number of Tasks” by the Sysgen. console must be a physical device name listed in /THEOS/CONFIG/ DEVNAMES.TXT. The attach-options are any valid console attachment parameters as defined by the Attach command (see “Attach” on page 21). >start 20 multi5 ( c190 b38400 w8 e5



When a user is started with this command, it has all publicly attached devices available and the privately attached console as specified in this command. Once the user environment is defined, it executes the Logon command and awaits the operator’s response to the “Logon please:” prompt. See “Session Management” on page 62 for a description of starting a new session on your console.



Start



583



 Mode 2—Identical in operation to Mode 1 except the new user is automatically logged onto account. The PASSWORD parameter is optional and is used when the account has a password. If the account has no password, the PASSWORD parameter is ignored. >start 20 multi5 ( c190 b38400 w8 e5 acc develop password "supreme"



Commands



If the PASSWORD parameter is not used and account has a password, the new user is started and Logon displays its “Password” prompt. Mode 3—This mode starts a user similar to Mode 1 and Mode 2. However, when the MODEM keyword is used it tells Start that the user is connected via a remote modem connection. A user started with this mode differs from both Mode 1 and Mode 2 in that the user’s console device is attached with this mode but no initialization strings are sent for the console class code. A special indicator is set that Logon uses. Instead of starting the user with the “Logon please” prompt, the Logon command programs the modem to auto-answer the telephone line. It then waits for an incoming call and connection. After the connection is established between the two modems Logon then sends the classcode initialization string and requests that the user logs on. When the remote user performs a Logoff (not lateral Logon), the connection is terminated and the modem is reinitialized to wait for the next incoming call. Mode 4—This mode starts a background task. A background task is a user process started without a console. command must be specified and may be any valid command line. >start archive s tape (multiuse noask noquery volume Task started as process #29



The process number used for the new background task is the highest numbered process currently available. It has all of the publicly attached devices available to it but does not have a console display or keyboard. Instead of executing the Logon command, command is executed. command must be a command that does not require any console input. command may be an EXEC language program that executes a series of commands before exiting. Whenever a background task command requests console input or exits to the CSI, it is stopped. Background tasks do have access to the standard input and standard output devices and can use i/o redirection to simulate console input. Background tasks are described on page 60. 584 Stop



 Mode 5—Stops user process number process. The process must be in the program Logon. If necessary, use the Force to force the user to Logoff first before stopping the process. >stop 20 Process is still active. >force 20 logoff



Before using the Force, you should first check to make sure that the user is not in the process of updating any files. If the user process was started with a Mode 3 start (modem server), the modem connection is first terminated before stopping the user. Notes



In Mode 1, Mode 2 and Mode 3, when a process is started with a console on a serial port, a modem initialization string is sent to the process’s console port. The specific string of characters transmitted is defined by a file in the /THEOS/CONFIG/SSYSTEM.MODEM library or by the file /THEOS/CONFIG/ MODEM.CFG. These files can be edited to customize the modem initialization string to that required by your modems. Refer to “Starting Users” on page 58 for a description of this user startup process. See also “SYSTEM.MODEM Library” on page 220 . For compatibility, the Start command accepts the command syntax used in prior versions: >Start



Defaults



process



(



console attach-options start-options



New users started with this command always have the devices that are defined in the system configuration file (see “Sysgen” on page 591) and any other devices that are publicly attached. Spooled printers defined by the system configuration file are assigned the queues defined in that file, other printers are assigned queues in a one-toone basis such as queue A to PRT1, queue B to PRT2, etc.



Return Codes



The Start command sets the return code to a non-zero value less than 1,000 when an error occurs and to a value greater than 1,000 when the process is successfully started. Return values greater than 1,000 specify that the process was started successfully and give the specific process number used for the new task. Subtract 1,000 from the return code to produce the process number.



Restrictions



The Stop command requires a privilege level of five. Mode 1 and Mode 2 of the Start command require a privilege level of five. Stop 585



Commands



>stop 20



 When attempting to Start a new user or task, the message “All available tasks are in use” indicates that all processs are already in use. You must either wait for a process to become availble (another tasks stops) or increase the number of processs available by setting a larger “Maximum Number of Tasks” in your system configuration (see “Sysgen” on page 591) and then reboot. Commands



When starting a new user, if the device specified as console is already in use by another user or task, the message “Device is attached to user ...” or “Device ... is already attached to process ...” is displayed. Either choose a different device for this user or free up the device by stopping the other users. See also



586 Stop



Attach, Net Start, Sysgen



 SUMode Command Test the system for single-user operation.



SUMODE



The system is examined to see if it has only one logged on user (this user). It performs this test by counting the number of logged on users, background tasks and servers running. It then subtracts the number of these tasks that are dedicated to print spooler operation and disk cache. If the remainder is not one then it reports that the system is not in single user mode by displaying the message:



If the system is in single user mode then no message is displayed. Return Code



Because this program would normally be called from an EXEC program or other program, the return code is set to indicate the results of the test. A return code of 0 indicates that the system is in single user mode. A return code of 1 indicates that one or more processes are still operating.



SUMode 587



Commands



Operation



 Commands



588 SUMode



 SysEd EXEC This command allows you to view and optionally modify some common system configuration data files.



SYSED



2



SYSED MODIFY



Operation



Mode 1—SysEd uses WindoWriter to open the following files in READONLY mode: /THEOS/CONFIG/SYSGEN.CFG:S /THEOS/CONFIG/DEVNAMES.TXT:S /THEOS/CONFIG/START.CFG:S /THEOS/CONFIG/MODEM.CFG:S /THEOS/CONFIG/NET.CFG:S



Mode 2—When MODIFY is specified, SysEd opens the above files without specifying READONLY and allows you to make changes and save the files.



SysEd



589



Commands



1



 Commands



590 SysEd



 Sysgen Command Sysgen maintains the system configuration file (/THEOS/CONFIG/SYSGEN.CFG:S).



SYSGEN



Operation



»



optional disk drive letter for /THEOS/CONFIG/SYSGEN.CFG file



Maintains the system configuration file on drive. If drive is not specified, S is assumed. Refer to the THEOS Corona Version 5 Operating System Installation and Setup Guide for a complete description of the operation of this configuration program. The drive parameter is used to change the system configuration file for a boot disk other than the current system disk. For instance, the Emergency Boot Floppy.



Notes



The system configuration file contains information used when THEOS is booted. Changes made to the configuration are not effective until the system is reset or rebooted.



Restrictions



The Sysgen command may only be used when you are logged onto the SYSTEM account (user number 0) with a privilege level of five.



See also



Attach, Load, Setup , Spooler, Start



Sysgen



591



Commands



drive



drive



 Commands



592 Sysgen



 System Command The System command changes the system disk drive.



SYSTEM



2



SYSTEM



drive Operation



Commands



1



drive »



optional drive letter code



Mode 1—This mode is used when the system disk is a removable disk drive and you want to change the disk volume in the drive. When the command is executed, you are prompted with: Mount new system disk on drive S[1:1:0]



Change the disk volume to another valid THEOS system disk and press (EnterÌ˛). Mode 2—This mode is used when you want to change the system disk to a different drive. For instance, after booting from an Emergency Boot Diskette, the System command is used to switch to the hard disk. >system m



Caution



You may change to a non-system disk. That is, you may change to a disk that does not contain an operating system or its support files. Although this may be desirable, in this situation there will be some limitations to the commands that you may execute. Any command that requires a file in the /THEOS/MENU/language, /THEOS/CONFIG or /THEOS/OS directories will not execute properly because these libraries are always assumed to be resident on the current system disk. Since command use files in those directories, there will not be much that you can do.



Notes



You must use this command to change the attachment of the system disk. The Attach cannot change the S disk assignment. The System command does not load any programs or files from the new system disk. Unless they are loaded into memory, it does check for the presence of the following files: /THEOS/OS.CSI, /THEOS/OS/MESSAGE/language/KEYWORD.BIN and /THEOS/OS/MESSAGE/language/MESSAGE.BIN. If WORK is S, all of the system work files are copied to the new system disk.



System



593



 Restrictions



The System command requires a privilege level of five. You must be in true single-user mode. That is, no users or background tasks started, including the print spooler or Network Login Server. The disk cache may be enabled.



Commands



See also



594 System



Reboot, Sysgen



 Tail Command Filter The Tail command displays the ending of a text file on the standard output device.



TAIL



file... ( options



2



TAIL



file ( options FOLLOW



file



»



file name with optional path; may contain wild cards



options



»



+nnn -nnn



Commands



1



CHARS FOLLOW LINE



Operation



Mode 1—The last lines or characters of file are output to the standard output device. When more than one file is specified, the last lines or characters of each of the files are output. >tail /theos/config/sysgen.cfg USER1 5:3:7:1 L80,P24,C90,ACCOUNT=SYSTEM USER2 5:3:7:2 L80,P24,C90 USER3 5:3:7:3 L80,P24,C90 USER4 5:3:7:4 L80,P24,C90 USER5 5:3:7:5 L80,P24,C90 USER6 5:3:7:8 L80,P24,C90 DATEFORM A NAME "Saturn" MAXPCB 40 LOWCASE



This mode outputs the tail of a file and then monitors the file for any growth in the file. When additional data is written to the file by another user or task, it is displayed and monitoring continues. You must use (Esc) or (F9) or (Break),(Q) to terminate this command. >tail system.history (-2 follow 09/08/96 15:55:06.579 1 End Program RC: 0 CPU: 0.380 09/08/ 96 15:56:16.078 16 Start Program Command: TAIL SYSTEM.HISTORY ( -2 FOLLOW



When another user causes additional records to be written to the history file, they are displayed here.



Tail



595



 Commands



Options



Notes



CHARS



Count characters instead of lines.



FOLLOW



Use Mode 2 of the Tail command. If multiple files are specified, only the first file is output and followed.



LINES



Count lines instead of characters. This is a default option.



+nnnn



Begin output nnnn lines or characters from the start of the file.



-nnnn



Begin output nnnn lines or characters from the end of the file. The default is -10.



When multiple files are displayed, each file’s output is identified with a line displaying the complete path to the file. A file specification can omit the file type if the environment variable FILETYPE is defined.



For more information about the FILETYPE variable, see “Environment Variables” on page 111 of the THEOS Corona Version 5 Operating System Reference. Defaults



LINES is a default option and -10 is the default count.



See also



Head, List, More



596 Tail



 Tape Command The Tape command initializes and manipulates a tape volume.



TAPE



2



TAPE



tape functions



tape



»



tape device name, such as TAP2 or TAP4



functions



»



EJECT FORMAT INIT label



Operation



Commands



1



LABEL REWIND RUN



SHOW TENSION UNLOAD



VERIFY WTM



Mode 1—Using the TAP1 device, this mode rewinds to the beginning of the tape volume and reads the header information. The tape label, the first file name and its creation date are displayed. >tape Tape TAPE1 label "TBACKUP". Tbackup from system "Production" on Wednesday, January 16, 2002, at 5:22pm. Data set name: "January 16, 2002 17:22:14" >



Mode 2—The requested function is performed on tape. If tape is not specified, TAP1 is assumed. >tape show Tape TAPE1 label "FRIDAY". Archived from disk "PRODUCTN" on 12/06/96, at 17:35. >



Tape 597



 Function



EJECT



If the tape device supports a programmable eject feature, the tape cartridge is ejected from the tape drive.



FORMAT



A TENSION function is performed on the tape and then new header labels are written. If the tape supports physical formatting, the tape is formatted instead of just being tensioned.



Commands



>tape format Enter tape label: Tuesday > INIT label



A REWIND operation is performed and then it writes a new volume label without tensioning or formatting the tape. >tape init "Monday"



Tape labels are one to eight characters in length. LABEL



A REWIND operation is performed and then all file labels are displayed and data blocks are counted. >tape label VOL1TSC002 HDR1ARCHIVE.DISKTAPE 0001000100000098316 HDR2F0409600128 ** Tape Mark ** Number of data blocks = 28917 ** Tape Mark ** EOF1ARCHIVE.DISKTAPE 0001000100000098316 EOF2F0409600128 ** Tape Mark ** ** Tape Mark **



000000



028917



REWIND



Rewinds to the start of the tape.



RUN



This function is synonymous with the EJECT function. If the tape device supports a programmable eject feature, the tape cartridge is ejected from the tape drive.



SHOW



Reads the next tape header. The header and the file name and creation date are displayed. If the tape is positioned to the end of the tape, then “Tape mark” is displayed.



>tape show Tape TAPE1 label "TBACKUP". Tbackup from system "Production" on Wednesday, January 16, 2002, at 5:22pm. Data set name: "January 16, 2002 17:22:14" >



598 Tape



 A “fast forward” and a “fast rewind” are performed on the tape to ensure uniform tension throughout the tape volume.



UNLOAD



This function is synonymous with the EJECT function. If the tape device supports a programmable eject feature, the tape cartridge is ejected from the tape drive.



VERIFY



Verifies the readability of the entire tape by rewinding to the start and then reading every block on the tape. >tape verify Block: 40, length: 0 >



WTM



Writes a tape mark on the volume. Every file on the tape is automatically terminated with a tape mark. The end of a tape is indicated by two consecutive tape marks.



Notes



Before a tape can be used by THEOS, it must be initialized with a tape label.



Restrictions



The Tape command requires a privilege level of four.



See also



TArchive, Attach, Backup, CopyFile, Eject, Restore, TBackup



Tape 599



Commands



TENSION



 Commands



600 Tape



 TArchive Command The TArchive command makes an “archive copy” of a file, a set of files, an entire disk volume or a set of disk volumes. This is a legacy command. The current version of software that should be used for archiving and backing up systems is TBackup.



TARCHIVE



from-drive to-drive ( options



2



TARCHIVE



file to-drive ( options



3



TARCHIVE



file from-drive to-drive ( FILES options



4



TARCHIVE



from-drive1 from-drive2 ... to-drive ( options



Commands



1



file



»



file name with optional path; may contain wild cards



from-drive



»



drive letter of source drive to archive



to-drive



»



drive letter of destination drive or logical tape name



options



»



ACCOUNT ASK



FILES INCREMENTAL date1 LABEL name date2 MULTIUSER DIFFERENTIAL NAME file



NOASK NOQUERY NOTYPE QUERY SHARE



SIZE file SUBDIR TYPE VOLUME



The TArchive command creates an archive volume that can be used by the Restore command. The TArchive and Restore commands have been replaced with the TBackup command as it is more capable and supports the latest storage devices. Operation



The file or files specified with file or from-drive are copied in a compressed form to an archive volume on the destination to-drive. The archive volume created can only be interpreted with the complementary Restore command described on page 495. Mode 1—Unless one or more options restrict the file selection, all of the files on the from-drive are archived to the to-drive. With this mode VOLUME is a default option. For instance, the following command archives all files in all accounts in all subdirectories on the S drive to the drive attached as TAPE1. >TARCHIVE S TAPE



TArchive 601



 Mode 2—The file(s) specified by file are archived to the to-drive. With this mode ACCOUNT is a default option. For instance, the following command archives a single file to the floppy diskette in drive F.



Commands



>TARCHIVE CUSTOMER.MASTER F



The following command archives all of the “master” files in the current account to the tape drive. >TARCHIVE *.MASTER TAPE



Mode 3—The files listed in file are archived to the to-drive. file must be an ASCII stream file containing one file description per line. The SELECTED.FILES and SELECTED.EXEC files created by the FileList command and the FOUND.EXEC created by the Look command can be used for this specification file (see “The EXEC and FILES Options” on page 239). You may also create the specification file with an editor or application program. For instance, FileList is used to create a list of files to be archived: >FILELIST *.DATA:A (EXEC >FILELIST A NOT *.DATA:A (10/1/01 EXEC APPEND



A file now exists that lists all of the “data” files and all files that have been changed since 10/01/2001. The following command will archive these files to tape: >TARCHIVE SELECTED.EXEC A TAPE (FILE



Mode 4—Similar to Mode 1 except that multiple volumes are archived onto to-drive. With this mode, VOLUME is a default option. For instance, the following command archives all files in all accounts in all subdirectories on the S drive, the A drive and the B drive to the F drive. >TARCHIVE S A B F



602 TArchive



 Options



The following options are available with the TArchive command. They can be used with any of the modes described above, either singly, or in combinations. ACCOUNT



Specifies that only the files owned by the current account are candidates for archiving. This is a default option when Mode 2 is used.



ASK



A default option that instructs TArchive to ask the operator to mount the source and destination volumes, and waits for confirmation that the proper volumes are mounted. For instance: >tarchive s f Source is Disk S Destination is Disk F Mount volumes now: Source is labeled "SYSTEM". Destination is labeled "ARCHIVE1". OK to start archive (Y/N)



Respond with a (EnterÌ˛) for the “Mount volumes now:” request and a (Y) or (N) for the “OK to start archive” question. Use the NOASK option to override this default. date1



The first token that looks like a date is interpreted as a selection date. Only files with a date stamp greater than or equal to this date (new files) are candidates for archiving. For instance: >tarchive s f (10/1/01



With this command only those files on the S drive that have been changed on or since 10/01/2001 will be archived. See also the INCREMENTAL and DIFFERENTIAL options. date2



A second token that looks like a date is interpreted as a selection date. Only files with a date stamp less than or equal to this date (old files) are candidates for archiving. >tarchive s f (1/1/86 9/30/01



TArchive 603



Commands



Use the VOLUME option to override this default.



 This command archives only those files on the S drive that have not been changed since 9/30/2001. The date 1/1/86 is the earliest date maintained by the THEOS file system and is interpreted as “from the earliest date.” DIFFERENTIAL Tells TArchive to include only those files that have their modified bit set. This is the only option that prevents TArchive



Commands



from resetting the modified bit for files that it archives. See “Differential Archives” on page 608. FILES



Indicates that Mode 3 of the TArchive command is to be used. The file specifies an ASCII stream file with each record in the file specifying a single file name. The file name specifications in this file may include the account name and path to the file. For instance, a line in the specification file might contain: develop\custom/programs/program.source.sample:s



If this file is used in an archive, the display will be: >tarchive selected.exec s f (file noask Account: 4=DEVELOP Subdirectory: CUSTOM Subdirectory: PROGRAMS Library: PROGRAM.SOURCE Member: PROGRAM.SOURCE.SAMPLE INCREMENTAL Tells TArchive to include only those files that have their



modified bit set. The modified bit is reset for each file archived. See “Incremental Archives” on page 609. LABEL label Specifies that the to-drive’s volume label is set to label. For



instance: >tarchive s f (label "Monday1" notype



sets the label of the diskette in drive F to “Monday1.” If additional disks are required, the last character of the label is incremented. When this might happen, try to use a starting label name that ends with a sequence identifier, such as “1” or “-A” etc.



604 TArchive



 MULTIUSER Allows TArchive to archive a public drive even though other users may be logged on and active. Normally, when TArchive is instructed to perform a full volume archive (option VOLUME)



on a public disk, it requires single-user mode. If other users are logged onto the system, it displays the message: “Must be single user or private volume.”



Use this option only if you are sure that all other users are inactive. NAME



Specifies that the archive volume file name is to be set to the token following this option. Additionally, the archive volume file will only use as much space as needed. None of the existing files on the to-drive are erased (an implied SHARE option). For instance: >tarchive s f ( account name "programs.archive"



This creates an archive volume file on drive of PROGRAMS.ARCHIVE.



F



with a file name



If the archive cannot fit in the space remaining on the destinatin drive, it will report that the disk is full and not create the archive volume. Use of this option sets the NOASK option. To reenable this option, you must specify ASK after the NAME option and its file name. One of the principal advantages of this option is that the resulting archive file uses only as much disk space as is needed for the actual archive volume. When this option is not used the archive volume name is ARCHIVE.VOLUME01, the archive volume uses the entire disk space of the to-drive and it may use multiple volumes for the output file. NOASK



Disables the source and destination volume operator confirmation at the beginning of the archive and when subsequent disks or tapes are needed.



TArchive 605



Commands



Using this option tells TArchive to not restrict the archive to single-user operation (the message is still displayed). THIS CAN BE EXTREMELY DANGEROUS! If another user changes some files while the archive is being created, the integrity of the archive is lost.



 Commands



NOQUERY



A default option that tells TArchive to not ask for confirmation on each file being archived.



NOTYPE



Tells TArchive to not display account names, subdirectory names, library names or file names on the standard output device as they are being archived.



QUERY



Tells TArchive that the operator is to be “queried” or asked if each file matching the selection criteria is to be included in the archive volume. >tarchive s f (query Source is Disk S Destination is Disk F Mount volumes now: Source is labeled "THEOS". Destination is labeled "ARCHIVE". OK to start archive (Y/N)? Y Ok to archive "SAMPLE.FILE:S" (Yes/No/All) N Ok to archive "SELECTED.EXEC:S" (Yes/No/All) N ... 94.3 MB, 8,834 files selected. ...



When the “Ok to archive” question is asked you may respond with a (Y) for yes, (N) for no or (A) for all. Responding with (A) means yes to this file and all remaining files are included without being queried. Respond with (Esc) to cancel to archive. SHARE



Tells TArchive that the archive volume is to share the space on the first disk with any existing files. This is a default option when to-drive is a removable hard disk. When this option is not used, TArchive clears the directory of the first disk and creates an archive volume file that uses the entire disk space. If multiple disks are required they will use the entire disk space for the archive file.



606 TArchive



SIZE file



The total size of all of the files selected for archiving is computed and appended to file. This is done before the archive is created.



SUBDIR



Tells TArchive that only files in the current working directory and all of its subordinate directories are included.



 TYPE



A default option that tells TArchive to display each account name, subdirectory name, library name and file name on the standard output device (normally the console) as it is being archived. This display can be redirected. For instance, the following is a typical display during an archive: Commands



ACCOUNT: 2=SAMPLES File: CHARSET.H File: LIBS.EXEC File: MAKE.FILE File: READ.ME File: SAMPLES.EXEC Subdirectory: C32 Library: C32.CMD32 Member: C32.CMD32.FINS Member: C32.CMD32.PRTF ...



The indentation of the display indicates the hierarchy of the directory structure. To disable this option use the NOTYPE option. VOLUME



Full Volume Archives



Specifies that all accounts, all subdirectories and all files on the from-drive are to be archived. This option requires that the from-drive be a private disk volume, that all other users be logged off or that the MULTIUSER option be used.



Full volume archives (option VOLUME in effect) are copies of the entire contents of disks. They should be created on a frequent and periodic basis to assure yourself of having adequate protection in the case of disk or computer failure. Since a full volume archive contains a copy of every file, subdirectory and account on a disk, it is the only archive volume that needs to be accessed if you must restore a system. Because full volume archives do include all of the files on a disk, it includes files that rarely change, such as the operating system programs and data files, application programs and other static data files.



TArchive 607



 Multivolume Archives



Mode 4 of this command archives multiple disk volumes onto a single archive volume. This allows you to archive your entire system in one operation. For instance, a system with four hard drives can be archived with the command:



Commands



>tarchive s a b c tape



Should the need ever arise where you want to restore a volume or a file from this archive volume, use the DRIVE option of the Restore command. >restore tape b (drive b



Differential Archives



A differential archive is an archive volume that includes only those files that have changed since the last full volume archive. For instance, if a disk contains three files: PROGRAM.COMMAND DATA1.FILE DATA2.FILE



A full volume archive will create an archive volume that contains all of these files. If DATA1.FILE is changed and a differential archive is performed, it will create an archive volume that contains only that file. The other files are not included in this differential archive volume because they have not changed and there is a current copy of those files in the last full volume archive. If DATA2.FILE is then changed and another differential archive is performed, it will create an archive volume that contains both the DATA1.FILE and the DATA2.FILE because both of those files have been changed since the last full volume archive was performed. Full Volume



Differential 1



Differential 2



DATA1.FILE



DATA1.FILE



PROGRAM.COMMAND DATA1.FILE DATA2.FILE



DATA2.FILE Differential Archives



Should a disk failure occur, the system could be restored by first restoring the full volume archive and then the last differential archive volume.



608 TArchive



 Incremental Archives



Full Volume



Incremental 1



Incremental 2



PROGRAM.COMMAND DATA1.FILE



DATA1.FILE



DATA2.FILE



DATA2.FILE Incremental Archives



Should a disk failure occur, the system could be restored by first restoring the full volume archive followed by the first incremental archive volume and then the second incremental archive volume. Notes



The output of the TArchive command is an archive volume. This is a special stream file that contains the compressed forms of the archived files along with their directory entries. This archive volume can be manipulated like any other file, and it can even be opened and read like any other file. However, since it is a compressed form of the original files and it contains the directory entries for the files, it is not usable except by programs that know how to interpret this information. The Restore command is a program that knows how to interpret the information and copy it back to its original, usable form. The files in an archive volume are sorted in ascending file name sequence within account number sequence. An archive volume is a single file named ARCHIVE.VOLUME01 (unless the NAME option is used). This single file contains all of the files included in this archive. Frequently a file or set of files being archived from hard disk to floppy, removable hard disk or tape will be larger than the disk or tape. In that situation the TArchive command will ask you to mount another disk or tape so that it can continue the archive of the file or files. In this situation each of the disks or tapes used will contain a single file named ARCHIVE.VOLUMEnn (see SHARE option for an exception to this situation). Unless the DIFFERENTIAL option is used, the modified bit for each file archived is reset by the archive process.



TArchive 609



Commands



An incremental archive is an archive volume that includes only those files that have changed since the last full volume or incremental archive was created. For instance, in the example used for the differential archive, a full volume archive is performed and then DATA1.FILE is changed. When the incremental archive is performed, it creates an archive volume that contains only the DATA1.FILE. When DATA2.FILE is changed and another incremental archive is performed, it creates an archive volume that contains only the DATA2.FILE. The DATA1.FILE is not included in this archive volume because it has not changed since the last incremental archive was created.



 ACCOUNT (Mode 2), ASK, NOQUERY, TYPE, VOLUME (Mode 1 and Mode 4).



Cautions



The MULTIUSER option tells the TArchive command to not check whether or not other users are logged on or active. It does not prevent those other users from performing operations that change the database being archived. If another user does change the database during the archive operation, the integrity of the archive volume is compromised.



Commands



Defaults



For instance, a disk volume being archived includes a customer master file with current balance fields and an invoice database. While the archive volume is being created, another user posts a transaction to the invoice database before it is included in the archive but after the customer master file is archived. If the archive volume is ever restored, the invoice database will not match the current balance fields in the customer master file. Restrictions



Unless the NAME option is used, the destination drive must be an image drive or some type of a removable mass-storage device such as a floppy diskette, removable hard disk or tape. The destination media must be preformatted. If the archive requires more disks or tapes than anticipated, you can use another session or terminal to format the disk while TArchive waits for you to confirm that the proper disk is mounted. To do this the ASK option must be in effect and the to-drive must be publicly attached. When option VOLUME is in effect and the from-drive is publicly attached, all other users must be logged off or the MULTIUSER option must be specified. See “Caution” notes above regarding the MULTIUSER option. The TArchive command requires a privilege level of four.



See also



610 TArchive



Backup, CopyFile, Disk, Restore, Tape, TBackup



 TBackup Command The TBackup command backs up files to another drive, or restores those files. It can also be used to verify or compare the backup files to their original source files.



TBACKUP



file-spec... backup ( BACKUP backup-options



2



TBACKUP



backup ( COMPARE compare-options



3



TBACKUP



backup file-spec... ( RESTORE restore-options



4



TBACKUP



backup ( VERIFY verify-options



5



TBACKUP



( PASSFILE filename



Commands



1



backup



»



drive letter of disk or tape volume containing backup or the file name specification for the backup data set



file-spec



»



drive letter of source drive for backup or specification of files for backup



backup-options



»



ACCOUNT ASK COMPARE DIFFERENTIAL EJECT ERROR FILES



FULL INCREMENTAL LABEL LIST MULTIUSER NOASK NOEJECT



PASSWORD PASSFILE PRTnn SETNAME SUBDIR VERIFY VOLUME



WAIT



date1 date2



compare-options



»



ASK DISKMAP EJECT ERROR



LIST NOASK NOEJECT NOWAIT



PASSFILE PASSWORD PRTnn SETNAME



WAIT



restore-options



»



ACCOUNT ASK DISKMAP EJECT ERROR FILES FROM



LIST NEWFILE NOASK NOEJECT NOQUERY NOSYSFILES NOWAIT



OLDER OLDFILE PASSFILE PASSWORD PRTnn QUERY



REPLACE SETNAME VOLUME WAIT



ASK ERROR EJECT



LIST NOASK NOEJECT



NOWAIT PASSFILE PASSWORD



PRTnn SETNAME WAIT



verify-options



»



date1 date2



TBackup 611



 Operation



Mode 1—Creates a backup data set on backup of the files specified by filespec. Although no options are required, you should specify the SETNAME for the data set. The backup destination may be specified in one of two ways:



Commands



1. With a drive code. When this is used, the backup data set is written to a file named TBACKUP.VOL00001:backup. The destination volume is cleared of all existing files before this data set is created. >tbackup s tape (backup setname "Weekly backup"



If the data set does not fit on a single volume, subsequent volumes will be requested and the file names used on those volumes will be TBACKUP.VOLnnnnn:backup, with nnnnn being a sequential number incremented for each volume. 2. With a file name specification. When this is used, the destination volume is not cleared and the backup data set is written to the file name specified. >tbackup s weekly.backup:d (backup differential



The data set must fit in the available space on the destination drive. If the data set does not fit in the space remaining on that volume, an error message will display. The file-spec may be a list of several file specifications. For instance: >tbackup *.data *.program *.notes tape (backup



With the above command, all files on all drives in the default search sequence with a file-type of “data,” “program” or “notes ” are backed up to tape. file-spec may be omitted, in which case it means that all files on all drives in the drive search sequence are candidates for the backup. The drive search sequence is defined in the account environment (see “Account” on page 13) or by the SEARCH environment variable (see “Set” on page 541). Unless specifically identified in file-spec the following sets of files are not backed up with this command: /SYSTEM.CSI* /SYSTEM.CSISV* /SYSTEM.EXEC* /SYSTEM.PIPE* /SYSTEM.WORK* /THEOS/TEMP/SYSTEM.CHIST*



612 TBackup



 Mode 2—Compares the contents of a backup data set specified by backup with the files that it was originally backed up from. For instance: >tbackup s tape (backup setname "Weekly Backup" >tbackup tape (compare setname "Weekly Backup"



Mode 3—Restores the files from the backup data set to the original location of the files. >tbackup tape s (restore >tbackup tape *.data:s *.data:a program.source.*:s (restore



The DISKMAP option may be used to instruct TBackup to restore the contents of the data set to a drive other than the original source of the backup. >tbackup s.file:s a.file:a tape (backup setname "Test" >tbackup tape (restore diskmap s-a diskmap a-s setname "Test"



After the restore operation is complete, the A drive will have the file named S.FILE and the S drive will have the file named A.FILE. Mode 4—Verifies the readability and integrity of the backup data set specified by backup. Verifying a data set does not test to see if the data set is an exact copy of the original file as the Mode 2 compare operation does. Instead, it does read every byte of the data set, verifies that all of the checksums are correct, and that every file and “record” in the data set starts and ends where it should. Mode 5—This mode creates a file containing an encrypted password. This file can then be used for any of the other modes of the TBackup command. When envoked, a form is displayed allowing you to enter a password and to confirm that you entered the desired password by requiring you to reenter it. The resulting password is encrypted and stored in the file named filename.



TBackup 613



Commands



If the source files have been changed since the backup data set was created, this compare operation will fail. Remember, in a multiuser environment, other users may be changing the database during the backup or between the start of the backup and the comparison operation.



 Backup Options



ACCOUNT



Only the files owned by the current account are candidates for the backup. This option sets SUBDIR option. Use the VOLUME option to override this default.



Commands



ASK



When TBackup is ready to begin writing the backup data, this option instructs TBackup to ask the operator to mount the destination volume and waits for confirmation that the proper volume is mounted.



After you load the proper volume in the disk or tape drive and acknowledge this message, TBackup looks for an existing file named TBACKUP.VOLnnnnn. If there is an existing file, TBackup displays the following information about it:



Select “Overwrite volume” to use this disk or tape as the backup volume. “Mount new volume” returns to the prior question, allowing you to insert a different disk or tape into the drive. ASK is a default option unless backup is a file name specification, in which case this option is ignored. Use the NOASK option to override this default. COMPARE Indicates that, after the backup data set is created, TBackup



should compare the data set against the original files. The NOASK option is in effect when the comparison starts.



614 TBackup



 DIFFERENTIAL



Only those files that have their modified bit set are included in the backup. This is the only option that prevents TBackup from resetting the modified bit for files that it copies. See “Differential Backups” on page 629. This option applies when the to-drive is a tape drive or a removable hard drive. It specifies that the final volume is ejected from the drive after the backup is complete.



ERROR



Specifies that all errors detected during the backup are written to the indicated file. For instance: >tbackup *.data:s tape (backup error backup.log:s



This command backs up all files with a file-type of DATA to the TAPE drive. Errors detected are logged to the file BACKUP.LOG:S. FILES



Indicates that file-spec is the name of an ASCII stream file with each record in the file specifying a single file name or a wild-card file specification. The file name specifications in this file may include the account name and path to the file. For instance, lines in the specification file might contain: *.data:s develop\custom/programs/program.source.sample:s



The SELECTED.FILES and SELECTED.EXEC files created by FileList and the FOUND.EXEC created by Look can be used for this specification file (see “The EXEC and FILES Options” on page 239). You may also create the file with an editor or application program. For instance, FileList is used to create a list of files to be backed up: >filelist *.data:a (exec >filelist a not *.data:a (10/1/01 exec append



A SELECTED.EXEC file now exists that lists all of the “data” files and all files that have been changed since 10/01/2001. The following command backs up these files: >tbackup selected.exec tape (backup file FULL



The modified bit of a file does not affect whether or not it is included in the data set. This is a default option that can be overridden by using the DIFFERENTIAL or INCREMENTAL option. TBackup 615



Commands



EJECT



 The modified bit is always reset when this option is in effect and the file is backed up. INCREMENTAL Tells TBackup to include only those files that have their



modified bit set. The modified bit is reset for each file copied. See “Incremental Backups” on page 630. Commands



LABEL



Specifies that the to-drive’s volume label is set to label. For instance: >tbackup s f (backup label "Monday1"



sets the label of the diskette in drive F to “Monday1.” If additional disk volumes are required, the last character of the label is incremented. When this might happen, try to use a starting label name that ends with a sequence identifier, such as “1.” Or use a label name with seven or less characters. MULTIUSER



Allows TBackup to back up files from a public drive even though other users may be logged on and active. Normally, when TBackup is instructed to perform a full-volume backup (VOLUME option) on a public disk, it requires single-user mode. If other users are logged onto the system, it displays the message: “Must be single user or private volume.” Using this option tells TBackup to not restrict the backup to single-user operation (the message is still displayed). THIS CAN BE EXTREMELY DANGEROUS! If another user changes some files while the backup is being created, the integrity of the backup is lost. Use this option only if you are sure that all other users are inactive and will remain so while the backup is created.



616 TBackup



NOASK



Disables the destination volume operator confirmation at the beginning of the backup. This option is useful for unattended backups.



NOEJECT



A default option that specifies that the last volume in backup is not ejected when the backup is complete.



NOWAIT



Disables the WAIT option and allows TBackup to terminate without waiting for the operator to acknowledge the status message upon completion of the backup operation.



PASSFILE



Specifies the file name containing the encrypted password. This password is used to encrypt the data set. When used, the



 data set cannot be used for COMPARE, RESTORE or VERIFY purposes without specifying the exact same password. PASSWORD Specifies the password to use for encrypting the data set. When used, the data set cannot be used for COMPARE, RESTORE or VERIFY purposes without specifying the exact



If PASSWORD is the last option specified on the command line and there is no password specified after the keyword, TBackup will prompt the operator for the password. SETNAME



Specifies the backup data set name. This name may be up to 64 characters in length and it may include letters, digits, spaces and other punctuation characters. Enclose the data set name in quotation marks. >tbackup s tape1 (backup volume setname "Full system backup"



The name for a backup data set can be used to ensure that the proper backup is being used later when it is restored When the data set is used at a later time, this data set name is displayed (unless NOASK is in effect). You can specify that the backup must have the same data set name as specified when you created it by using the SETNAME option with the Mode 3 command. SUBDIR



Tells TBackup that files in the current working directory and all of its subdirectories are included in the backup. When not specified, only the files in the current working directory are included. None of the files in subordinate directories are included in the backup.



VERIFY



Indicates that, after the backup data set is created, TBackup should verify the readability of the data set. The NOASK option is in effect when the verify operation starts. Verifying a data set does not test to see if the data set is an exact copy of the original file as the COMPARE option does. Instead, it does read every byte of the data set, verifies that all of the checksums are correct, and that every file and “record” in the data set starts and ends where it should.



VOLUME



Specifies that file-spec refers to files in all accounts, not just the current account. The default ACCOUNT option limits filespec to files on the current account. TBackup 617



Commands



same password. Passwords may be up to 32 characters in length, are case sensitive, and may contain spaces and other special characters.



 Commands



This option requires a privilege level of five, that you be currently logged onto the system account, and that the source disk be a private disk volume or, if it is a publicly attached disk, that all other users be logged off or that the MULTIUSER option be used. WAIT



A default option that specifies that TBackup should wait for an operator response before clearing the status message and exiting.



date1



The first token that looks like a date is interpreted as a selection date. Only files with a date stamp greater than or equal to this date are candidates for the backup. For instance: >tbackup s tape2 (backup 1/1/02



With this command only those files on the S drive that have been changed on or since January 1, 2002 will be backed up. See also the INCREMENTAL and DIFFERENTIAL options. date2



A second token that looks like a date is interpreted as a selection date. Only files with a date stamp less than or equal to this date are candidates for the backup. >tbackup s tape2 (backup 2/1/02 2/28/02



This command backs up only those files on the S drive that were changed between and including the beginning and ending of February, 2002. Files changed before February or since February are excluded.



618 TBackup



 Compare Options



ASK



This option operates the same as the ASK option on page 614.



DISKMAP



Changes the drive codes used during the comparison. For instance: >tbackup f (compare diskmap s-d



Multiple DISKMAP options may be used to map files on multiple drives: >tbackup s a b tape (backup >tbackup tape (compare diskmap s-d diskmap a-e diskmap b-f



Here, the files backed up from S are compared to files on the current D drive, files backed up from A are compared to files on the current E drive, and files backed up from B are compared to files on the current F drive. EJECT



This option operates the same as the EJECT option on page 615.



ERROR



This option operates the same as the ERROR option on page 615.



LIST



Lists the files in the backup to the specified file or device. For instance, to list the files in the backup to a disk file, use: >tbackup tape1 (compare list backup.listing:s



To list the files to a printer you would use: >tbackup tape1 (compare list prt5 NOASK



This option operates the same as the NOASK option on page 616.



NOEJECT



This option operates the same as the NOEJECT option on page 616.



NOWAIT



Disables the WAIT option and allows TBackup to terminate without waiting for the operator to acknowledge the status message upon completion of the backup operation.



TBackup 619



Commands



The specification “s-d” in the above command specifies that files originally backed up from the S drive are to be compared with the files on the current D drive.



 PASSFILE



Specifies the file name containing an encrypted password. This password is used to decrypt the data set so that it can be compared against the original data on disk. The data set must have been created with the exact same password that is specified here.



Commands



PASSWORD Specifies the password to use for decrypting the data set.



If PASSWORD is the last option specified on the command line and there is no password specified after the keyword, TBackup will prompt the operator for the password. The data set must have been created with the exact same password that is specified here.



620 TBackup



PRTnn



This option is a synonym to the LIST PRTnn option.



SETNAME



This option operates the same as the SETNAME option on page 617.



WAIT



Indicates that, after the backup data set is compared and the status message is displayed, TBackup should wait for an operator response before clearing the status message and exiting.



 Restore Options



ACCOUNT



Restores files matching the file-spec that were backed up from the current account. Compare with the VOLUME option. >logon data >tbackup tape (restore account



ASK



This option operates the same as the ASK option on page 614.



DISKMAP



This option operates the same as the DISKMAP option on page 619.



EJECT



This option operates the same as the EJECT option on page 615.



ERROR



This option operates the same as the ERROR option on page 615.



FROM



Tells TBackup to only select those files on the backup data set that were owned by account name account at the time the backup was created. The originating account name is specified immediately after the FROM keyword. >logon develop >tbackup tape (restore from project4



The above command restores all of the files that were backed up from the account “PROJECT4” into the current account “DEVELOP.” LIST



This option operates the same as the LIST option on page 619.



NEWFILE



Specifies that TBackup will only attempt to restore a file if it does not already exist on the destination drive. This option is mutually exclusive with the OLDFILE option (you may use one or the other, but not both).



NOASK



This option operates the same as the NOASK option on page 616.



NOEJECT



This option operates the same as the NOEJECT option on page 616.



NOQUERY A default option that tells TBackup to not ask for confirmation



on each new or existing file being restored. TBackup 621



Commands



In the above example, only files that were originally backed up from the DATA account are restored.



 To disable this option use the QUERY option. NOSYSFILES The standard, system-supplied files are omitted when files are restored. See “NOSYSFILES” on page 503 for a listing of



Commands



the files skipped with this option. NOWAIT



Disables the WAIT option and allows TBackup to terminate without waiting for the operator to acknowledge the status message upon completion of the backup operation.



OLDER



Qualifying files are restored only if the backed-up file is older than the same file on the destination. In other words, files are restored only if they have been changed since the backup was made.



OLDFILE



Specifies that TBackup will only attempt to restore a file if it does exist on the destination drive. This option implies the REPLACE option and is mutually exclusive with the NEWFILE option (you may use one or the other, but not both).



PASSFILE



Specifies the file name containing an encrypted password. This password is used to decrypt the data set before restoring it to disk. The data set must have been created with the exact same password that is specified here.



PASSWORD Specifies the password to use for decrypting the data set.



If PASSWORD is the last option specified on the command line and there is no password specified after the keyword, TBackup will prompt the operator for the password. The data set must have been created with the exact same password that is specified here. PRTnn



622 TBackup



This option is a synonym to the LIST PRTnn option.



 Tells TBackup that the operator is to be “queried” or asked if each file matching the selection criteria is to be restored.



REPLACE



This option tells TBackup that it is okay to attempt to restore a file even if it already exists on the destination drive. When this option is not used (and the NOQUERY option is not used), an attempt to restore an existing file causes you to be queried.



SETNAME



This option operates the same as the SETNAME option on page 617.



VOLUME



Specifies that all of the files on the data set may be restored if they match the file-spec and other options specified do not restrict them. Compare with the ACCOUNT option.



WAIT



Indicates that, after the backup data set is restored and the status message is displayed, TBackup should wait for an operator response before clearing the status message and exiting.



date1



The first token that looks like a date is interpreted as a selection date. Only files in the backup data set with a date stamp greater than or equal to this date (new files) are candidates for restoring. For instance:



Commands



QUERY



>tbackup tape a (restore 10/1/01



With this command only those files in the backup data set with a file change data of October 1, 2001 or later are restored to the A drive. date2



A second token that looks like a date is interpreted as a selection date. Only files in the backup data set with a date stamp less than or equal to this date (old files) are candidates for the restore operation. >tbackup tape a (restore 1/1/86 9/30/01



TBackup 623



 Commands



This command restores only those files from the data set with a file change date less than or equal to September 30, 2001, are restored to the A drive. The date 1/1/86 is the earliest date maintained by the THEOS file system and is interpreted as “from the earliest date.”



624 TBackup



 Verify Options



This option operates the same as the ASK option on page 614.



EJECT



This option operates the same as the EJECT option on page 615.



ERROR



This option operates the same as the ERROR option on page 615.



LIST



This option operates the same as the LIST option on page 619.



NOASK



This option operates the same as the NOASK option on page 616.



NOEJECT



This option operates the same as the NOEJECT option on page 616.



NOWAIT



Disables the WAIT option and allows TBackup to terminate without waiting for the operator to acknowledge the status message upon completion of the backup operation.



PASSFILE



Specifies the file name containing an encrypted password. This password is used to decrypt the data set so that it can be compared against the original data on disk. The data set must have been created with the exact same password that is specified here.



PASSWORD Specifies the password to use for decrypting the data set.



If PASSWORD is the last option specified on the command line and there is no password specified after the keyword, TBackup will prompt the operator for the password. The data set must have been created with the exact same password that is specified here. PRTnn



This option is a synonym to the LIST PRTnn option.



SETNAME



This option operates the same as the SETNAME option on page 617.



WAIT



Indicates that, after the backup data set is verified and the status message is displayed, TBackup should wait for an operator response before clearing the status message and exiting.



TBackup 625



Commands



ASK



 Defaults



Mode 1 (BACKUP) defaults are: ASK, FULL, NOEJECT. ACCOUNT is a default when file-spec specifies a drive code only. NOASK is the default and cannot



be overridden when backup is a file name specification. Mode 2 (COMPARE) defaults are: ASK and NOEJECT.



Commands



Mode 3 (RESTORE) defaults are: ASK, NOEJECT, NOQUERY, VOLUME. Mode 4 (VERIFY) defaults are: ASK and NOEJECT.



Notes



Because of the compression algorithm used, some files may be larger than the original source file. For instance, a backup of a zipped file or a file that has already been compressed with the Compress command will be larger than the original file. The compression percentage displayed refers to the difference in size between the original files and the resulting data set, including the data set catalog information and other data set overhead. When the original size is small, this compression percentage may be greater than 100%.



Backup Data Set



The output of the TBackup command is a backup data set. This is a special stream file that contains the compressed forms of the files along with a catalog of the files on the data set. This data set can be manipulated like any other file, and it can even be opened and read like any other file. However, since it is a compressed form of the original files and it contains the directory entries for the files, it is not usable except by programs that know how to interpret this information. TBackup is the only supplied program that knows how to interpret the information and copy it back to its original, usable form. A backup data set is a single file normally named TBACKUP.VOL00001. This single file contains all of the files included in this backup. Frequently a file or set of files being backed up from hard disk to floppy or tape will be larger than a single diskette or tape. In that situation the TBackup command will ask you to mount another diskette or tape so that it can continue the backup of the file or files. In this situation each of the diskettes or tapes used will contain a single file named TBACKUP.VOLnnnnn. Unless the DIFFERENTIAL option is used, the modified bit for each backedup file is reset by the TBackup process.



626 TBackup



 TBackup Screens



TBackup, invoked with Mode 1 (BACKUP) displays the following status



screen while it is collecting information about the files:



Commands



The file counts do not include libraries or directories, only files. After TBackup has collected all of the file names that it is going to copy, it is ready to start the first volume of the data set:



After mounting the tape it is read and you are asked to confirm that it is the proper tape to use:



TBackup 627



 TBackup, invoked with Mode 2 (COMPARE), Mode 3 (RESTORE) or Mode 4 (VERIFY), displays screens similar to the following status screen while it is



Commands



collecting information and comparing, verifying or restoring files:



The ECC counts refer to the number of errors detected using the error-correcting checksum fields in the data set. Full Volume Backups



A full volume backup of a drive can be made easily with the TBackup command by using the VOLUME option and using a file-spec that specifies a drive-code only. >tbackup s tape (backup volume



Full volume backups should be created on a frequent and periodic basis to assure yourself of having adequate protection in the case of disk or computer failure. Since a full volume backup contains a copy of every file, subdirectory and account on a disk, it is the only backup volume that needs to be accessed if you must restore a system. Multivolume Backups



You can backup your entire system in one operation by performing a full volume backup for all drives on the system. For instance, a system with four hard drives can be archived with the command: >tbackup s a b c tape (backup volume



An even more convenient method is to allow TBackup to backup all of the drives defined in the default search sequence. For instance: >show search SEARCH = SAB >tbackup tape (backup volume



628 TBackup



 When the file-spec is omitted, TBackup uses the default search sequence as the file-spec specification. The above command is identical to: >tbackup s a b tape (backup volume



Should the need every arise where you want to restore the files on this backup volume, use the restore mode of the TBackup command (Mode 3 ).



When file-spec is omitted with the restore mode, TBackup restores all of the files in the backup volume to their original locations. Differential Backups



A differential backup is a backup that includes only those files that have changed since the last full-volume backup. For instance, if a disk contains three files: PROGRAM.COMMAND DATA1.FILE DATA2.FILE



A full-volume backup will create a backup data set that contains all of these files. If DATA1.FILE is changed and a differential backup is performed, it will create a backup data set that contains only that file. The other files are not included in this differential backup because they have not changed and there is a current copy of those files in the last full-volume backup. If DATA2.FILE is then changed and another differential backup is performed, it will create a backup dadta set that contains both the DATA1.FILE and the DATA2.FILE because both of those files have been changed since the last fullvolume backup was performed. Full-volume



Differential 1



Differential 2



DATA1.FILE



DATA1.FILE



PROGRAM.COMMAND DATA1.FILE DATA2.FILE



DATA2.FILE



Should a disk failure occur, the system could be restored by first restoring the full-volume backup and then the last differential backup.



TBackup 629



Commands



>tbackup tape (restore



 Commands



Incremental Backups



An incremental backup is a backup that includes only those files that have changed since the last full-volume or incremental backup was created. For instance, in the example used for the differential backup, a full-volume backup is performed and then DATA1.FILE is changed. When the incremental backup is performed, it creates a backup data set that contains only the DATA1.FILE. When DATA2.FILE is changed and another incremental backup is performed, it creates a backup data set that contains only the DATA2.FILE. The DATA1.FILE is not included in this backup because it has not changed since the last incremental backup was created. Full-volume



Incremental 1



Incremental 2



PROGRAM.COMMAND DATA1.FILE DATA2.FILE



DATA1.FILE DATA2.FILE



Should a disk failure occur, the system could be restored by first restoring the full-volume backup followed by the first incremental backup and then the second incremental backup. Cautions



The MULTIUSER option tells the TBackup command to not check whether or not other users are logged on or are active. It does not prevent those other users from performing operations that change the database being backed up. If another user does change the database during the backup operation, the integrity of the backup data set is compromised. For instance, a disk volume being backed up includes a customer master file with current balance fields and an invoice database. While the backup data set is being created, another user posts a transaction to the invoice database before it is included in the backup but after the customer master file is copied. If the backup data set is ever restored (Mode 3) or compared (Mode 2), the invoice database will not match the current balance fields in the customer master file.



Automated Backups



To use the TBackup command for automated backups, be sure that you have mounted the proper backup volume before the backup is initiated and use the following options: COMPARE, to validate that the backup was accurate. ERROR, to output the error messages to a file that can be checked after the backup is complete. NOASK, to prevent the interruption of the backup process. SETNAME, to put an identifying label in the backup data set.



Use the ACCOUNT, DIFFERENTIAL, FULL, INCREMENTAL, SUBDIR and VOLUME as appropriate.



630 TBackup



 Restrictions



When creating a backup data set (Mode 1), the destination media must be preformatted. If the backup requires more disks or tapes than anticipated, you can use another session or terminal to format the disk or tape while TBackup waits for you to confirm that the proper volume is mounted. To do this, the ASK option must be in effect and the destination drive must be publicly attached.



The TBackup command requires a privilege level of four. To use the VOLUME option of the Mode 1 (BACKUP) requires a privilege level of five. See also



TArchive, Backup, Compress, CopyFile, Eject, Expand, Restore



TBackup 631



Commands



When creating a backup (Mode 1) with option VOLUME in effect and the drives specified in file-spec are publicly attached, all other users must be logged off or the MULTIUSER option must be specified. See “Caution” notes above regarding the MULTIUSER option.



 Commands



632 TBackup



 TBrowse Command The TBrowse command displays and allows you to browse the contents of HTML-encoded files.



TBROWSE url



2



TBROWSE file



url



»



Uniform Resource Locator (URL) for HTML-encoded file



file



»



file name with optional path; may contain wild cards



Operation



Mode 1—Open the HTML page defined by url and display the hypertext content. >tbrowse www.theos-software.com >tbrowse www.mydomain.com/private/page44.htm



Mode 2—Open the local file and display the hypertext content. >tbrowse /html_home/webpages/default.htm



HTM Files



1. It does support most HTML tags including: !DOCTYPE HTML HEAD TITLE BODY (with BGCOLOR LINK VLINK and TEXT attributes) H1 - H6 P, BR and HR FONT but only the COLOR attribute is used B, I, EM and STRONG OL, UL and LI BLOCKQUOTE PRE and CODE TABLE with BORDER, COLSPAN and WIDTH attributes TH, TR and TD DL, DT and DD CENTER A HREF



Comments 2. If your formatted document uses tables or the PRE tag, then the width of the page may be larger than the width of the viewing winTBrowse 633



Commands



1



 dow. In this case, a horizontal scroll bar will appear at the bottom of the window. Use your mouse to scroll left and right. Restrictions



1. The file or URL being viewed must fit in memory. 2. There is no JavaScript support. You should remember to hide SCRIPT information with HTML comments.



Commands



3. There is no FORM support (this means that you cannot use INPUT, SUBMIT, TEXTAREA, METHOD, MODE, SELECT, etc.) 4. There is no Cascading Style Sheet support. This means that you should include the HTML comments to hide the STYLE information. 5. There is no authorization support. This means that you cannot access documents that require a logon and password. 6. It does not recognize return status code 302 -- "Document has been moved/renamed". This is frequently used to deliver the correct URL back to the browser when the URL you requested is a directory name. For example, if you code an anchor href as "http:// www.theos-software.com", the THEOS server would return a 302 URL as "http://www.theos-software.com/default.htm". 7. Frames are not supported and will cause a trap. 8. Since it is text only, graphic images cannot be displayed. You should code ALT with images that are also hyperlink anchors. 9. The only way to execute your CGI applications is to code them in SSI or in a hyperlink (A HREF). For example: Click to show report See also



634 TBrowse



Help, Viewer



 Tee Command Filter The Tee command copies standard input to standard output and makes additional copies to a file.



file... ( option



file



»



file name with optional path



option



»



APPEND



Operation



Commands



TEE



The file from the standard input device is copied to both the standard output device and to file. If multiple files are specified, then multiple copies are made, one to each file. >filelist s | tee file.list:s | more



The above command line creates a directory listing of the S drive. The listing is piped to the Tee command, which makes a copy of it in the file FILE.LIST:S and also pipes it to the More command, which displays the directory listing on the console. stdin



tee



stdout



file Options



APPEND



Notes



The file specified with this command may have a complete path specification, including the account name. However, when file is on another account, it is created using default attributes which include shared read and shared write protection. Therefore, the file is created but data cannot be written to it from non-owning accounts. Use the CREATE environment variable to set default attributes allowing shared file write access. See “CREATE” on page 102.



See also



CopyFile



The output is appended to the end of file. Without this option, the output replaces file.



Tee



635



 636 Tee



Commands



 Telnet Client The Telnet command establishes a client/server connection between this THEOS system and a remote Telnet server system. The remote system need not be THEOS-based.



TELNET



server ( options



2



TELNET



server port ( options



Commands



1



localhost



»



LOCALHOST



server



»



network server name or id (may also be localhost)



port



»



numeric port number to use for this session



options



»



ANSI CLASSnnn CTL



Operation



ECHO FLOW NOPROXY



PCTERM PCTERM-aa PROXY



TRACE VT100 VT220



Mode 1—Invokes the Telnet client and connects to server using its standard Telnet port number (23). Refer to “Server Specification” on page 642 for information about the server parameter specification. Mode 2—Invokes the Telnet client and connects to server using its port number port. Do not use this mode unless you know that the remote server uses a nonstandard port for Telnet access. The port value may be specified with a numeric, such as 23, or a name. The name must be the name of a well-known service, such as FTP, HTTP, etc. Service names are defined in the file /THEOS/CONFIG/SERVICES.TXT:S.



Options



ANSI



Requests ANSI terminal emulation by the Telnet server.



CLASSnn



Emulate a PcTerm with the requested class file. The class code number is in the range 180–189 or 210–219. The 180 series does not support intense background colors; the 210 series does support intense background colors.



CTL



Sets control mode for display of control characters received from the server. Control mode causes all control characters received to be displayed visually. For instance, receipt of a CR is displayed as ^M.



ECHO



Displays characters typed on your keyboard. This is the default when Mode 2 is used with a port value other than 23.



Telnet



637



 This option tells the Telnet client to echo all outbound characters. This character-echo might be in addition to the remote server or the application running on the server. If characters are displayed twice, then terminate this session and reconnect without the ECHO option.



Commands



FLOW



Displays the commands interchanged between this Telnet client and the Telnet server. When used in conjunction with the TRACE option, the command interchange is also written to the TELNET.TRACE file. The flow-control commands may be useful for diagnostic purposes when there is some type of problem negotiating a proper connection with the remote server. These flow-control commands will generally only occur during the start-up phase of the connection: >telnet some.host (flow Connecting to 192.168.100.4 port 23 ..recv: DO TermType send: WILL TermType recv: SB TermType SEND send: SB TermType IS VT220 recv: SB TermType SEND send: SB TermType IS VT220 recv: WILL Echo send: DO Echo recv: DO Window-Size send: WILL Window-Size send: SB NAWS 80 24



session text begins here... For a description of the meanings of any flow-control commands displayed, refer to RFC 854. NOPROXY



638 Telnet



If the Telnet configuration file (/THEOS/CONFIG/TELNET.CFG:S) specifies a default proxy server, this option ignores that specification and connects to the requested Telnet server address directly.



 PCTERM PCTERM-aa Emulate PcTerm terminal display and specified language



keyboard. When -aa is not specified, the current default keyboard definition is used. -aa -UK



English (United Kingdom)



-FR



French



-GR



Greek



-IT



Italian



-SP



Spanish



-SG



Spanish, Catalan



-LA



Spanish, Latin American



-CF



Canadian/French



-BE



Belgium/Dutch



Indicates that, whether or not a proxy server is specified in the Telnet configuration file, the proxy server specified here is used as the proxy server for this Telnet session. The requested proxy server name or IP address is specified immediately following the PROXY option keyword: >telnet myip.com (proxy 128.24.100.0



A default proxy server can be specified in the Telnet configuration file (/THEOS/CONFIG/TELNET.CFG:S) which is maintained by the Setup Telnet Client screen. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.) When specified there you do not need to use this PROXY option...the proxy is always used unless the NOPROXY option is specified. TRACE



All characters displayed by the Telnet client are also copied to the file TELNET.TRACE. If FLOW is also specified, those characters are also copied to this file. The TELNET.TRACE file is written to the system disk, root directory, of the current account. This file will replace any file with the same name. All characters copied to the trace file are copied in CTL mode, even when the display uses interpreted control codes.



VT100



Requests VT-100 terminal emulation by the remote server. (Class code 100 on THEOS Telnet Server.) Telnet



639



Commands



PROXY



Language



 VT220



Notes



Requests VT-220 terminal emulation by the remote server. (Class code 220 on THEOS Telnet Server.)



Telnet is one of three clients used to connect as a user to another computer



system on the network. THEOS WorkStation Client - Used from a Windows system to estab-



Commands



lish a user terminal session on a THEOS Login Server system. NetTerm - Used from one THEOS system to establish a user termi-



nal session on another THEOS system’s Login Server. Telnet - Used from a THEOS system to establish a user terminal session on another system’s Telnet Server. The other system may be a THEOS system (a Telnet Server is included as part of the Login Server) or any other system with a Telnet server, such as provided by most Internet Service Providers (ISP). The other system may be on the local intranet or on the Internet. RFC 854. This Telnet client conforms to the standards proposed in RFC 854. That document can be found at many sites on the Internet, including: http://www.faqs.org/rfcs/



When connected to the remote server, you may execute any programs on that server that you have access to. The THEOS Telnet server supports additional terminal emulations not used by this Telnet client. When connecting to a THEOS server from another operating system’s Telnet client, you may be able to use: ANSIC, ANSICOLOR, SCOANSI, SCO-ANSI, VT320, DEC-VT220, VT220AM, DEC-VT100, WYSE-50, WYSE50, WYSE-60, WYSE60, PCTERM, PCTERM-US, PCTERM-UK and PCTERM-SP. Whether or not any of these are actually used will depend upon the Telnet client. „ Connecting to a THEOS Telnet Server Telnet can connect to a THEOS Login Server only if the THEOS system has



its Login Server started. When connected to a THEOS Telnet Server, you are emulating a “dumb terminal” connected to the THEOS system. You will not be able to use your local printer as a slave printer and you cannot transfer files back and forth with the Net command. Localhost: For testing purposes, you can connect to your own system’s Telnet server by using the server name of localhost. This is a reserved host name that always refers to the client system.



640 Telnet



 Console Attachment: When you first connect to the THEOS Telnet Server your console attachment will have a line and page size that is equal to your local system’s line and page size. After you logon you may change the console attachment to another size supported by your local system. If you change your console screen size during the Telnet session, when you terminate the session your console will be reset to its original width and depth.



Non-VT220 emulations can use the (Break) key itself to transmit a break signal. Terminating Session: Executing the LOGOFF command on the THEOS Telnet Server will log off of the account but it will not terminate the Telnet session. Use the EXIT command to logoff and disconnect from the server. „ Terminating Telnet Sessions A Telnet session is terminated and the Telnet program is exited when you either fail to make a connection to the Telnet Server or, after making the connection, you use the server’s “log off” command. The name of this command is dependent upon the server but will generally be LOGOUT, BYE, QUIT or something similar. Of course, when the server is a THEOS Telnet Server, use the EXIT command. During the Telnet session, characters are transmitted immediately.



Telnet



641



Commands



Break Signal: When using VT220 emulation, to transmit a break signal to the THEOS Telnet Server, use the (`) key (single back quote). For instance, to tell the THEOS Telnet Server to abort the program that it is running, press (`),(Q). To type a back quote that is not interpreted as a break signal, press (`),(`).



 „ Server Specification The specification of the server, for Mode 1 or Mode 2, may be accomplished by specifying: The dotted IP address for the server. Commands



>telnet 207.21.75.100



The host name as defined in the file /THEOS/CONFIG/HOSTS.TXT:S. This file can be maintained by you with Setup Net Name Services. >telnet my-company



Or the domain name as defined by the DNS servers specified in Setup Net Name Services. >telnet myisp.com



For instance, your company might be registered with Internic (http:// www.internic.net/index.html) with a domain name of my-company.com, with an IP address of 128.100.2.1. If you have specified a host name of “HEADQUARTERS” in the host names database with that IP address, you can specify your company’s Telnet site with any of the following server specifications: 128.100.2.1 headquarters my-company.com Domain names and host names are case-insensitive. Restrictions



When the remote server is THEOS-based, and the “Allow/Deny” capability is enabled, your IP address must pass those tests. Other servers may have similar access restrictions implemented. Also, when the remote server is a THEOS Login Server, it may have enabled its “Remote User Security,” in which case you will be required to enter your network user name and password as defined in the server’s Setup Net Network User Security database. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.)



See also



642 Telnet



Net, NetTerm, Setup , THEOS WorkStation Client



 Example



This first example shows a successful connection to an ISP. >telnet ispname.com Telnet Open >ISPNAME.COM Connecting... Possible introductory information messages from the remote Telnet server



Commands



login: cpw Password: Other information messages from the remote Telnet server, such as: For a menu driven interface type TERM was vt100 Setting default terminal size to pacifier:~% dir -l total 4 drwx------ 2 cpw user 512 Aug drwxr-xr-x 2 cpw user 512 Aug pacifier:~%exit logout



menu from the prompt 80x24.



13 12:11 mail 22 08:07 public_htm



In this second example, an attempt is made to connect to the THEOS Internet site. The server name “theos” is defined in the local host-names database so the server name is translated to the IP address defined there. However, this site does not support Telnet connections and the connection request is refused. >telnet theos Telnet Open >207.21.75.100 Connecting... 425 Unable to connect with remote host



Telnet



643



 In this final example, a connection is made to the home office system over the Internet. The name is defined in your host names database. This system is THEOS-based and has remote security enabled. (The screen is cleared before the Network login window is displayed and after you have successfully entered your user name and password.) >telnet home-office



Commands



Telnet Open >128.100.2.0 Connecting...



User name: [myname



]



Password:



]



[********



HOMEOFFICE>show who ACCOUNT = REMOTE USERNUM = 25 PORT = 36 PRIVLEV = 3 LOGON = 11:10:20 11/14/97 HOMEOFFICE>



644 Telnet



 Terminal Command EXEC The Terminal command is an EXEC language program that provides convenient, commandline access to the THEO_COM command’s terminal emulation capability.



options



Operation



Commands



TERMINAL



( options »



ALF ANSI ASCII COMnn CTL DIAL number EOF= EOT FILES



HALF HANGUP MASTER NOEOT NOLOGO PCTERM RECEIVE file REDIAL SCRIPT file



SEND file THEOS TRACE TRACEFILE file TVI TYPE VT100 VT220 VT220-8



WYSE50 WYSE60 XMODEM XMODEM-CRC XMODEM-1K YMODEM



This EXEC program merely invokes the THEO_COM command described described on page 649. It is provided for users upgrading to THEOS Corona from a prior version of THEOS that might have not included THEO+COM™. For operation and usage of this TERMINAL EXEC, refer to the THEO_COM command or to the THEO+COM Installation and User’s Guide.



Terminal



645



 Commands



646 Terminal



 TFTP Command The TFTP command is a Trivial File Transfer Protocol client that provides file transfer capabilities over a network between this client and any TFTP server available on the network.



TFTP RECEIVE host



2



TFTP SEND



filename



host filename



remote-filename



Commands



1



remote-filename



host



»



server server:port



filename



»



name of file on local client system containing FTP script



remote-filename



»



name of file on local client system containing FTP script



server



»



name or id of TFTP network server (may also be localhost)



port



»



port number on server for TFTP communication (default is 69)



Operation



Mode 1—Receive a file from a TFTP server. This client connects to the TFTP server located at host and receives the file named remote-filename from that server and saves it on this system with the name filename. If remote-filename is not specified then filename is used for requesting the remote file from the host. Mode 2—Send a file to a TFTP server. This client connects to the TFTP server located at host and sends the file named filename from this system to the remote host. The server is requested to receive the file and save it with the name remote-filename. If remote-filename is not specified then filename is used by the server when it saves the file.



Notes



TFTP is a simple protocol to transfer files using the Internet User Datagram protocol (UDP). Data is sent in fixed-length blocks of 512 bytes. Each data packet must be acknowledged by the recipient before the next packet is sent. Most errors will cause termination of the transfer.



Defaults



The default port number used by this client is 69. This is a “well-known” port for TFTP clients and servers. You should only specify a different port if you know that the server that you are attempting to connect to uses a different port number.



Restrictions



Only sequential files may be sent or received with this client.



See also



FTP, NetTerm, Receive, Send



Examples



>tftp send laptop my.file "recipient-filename.txt" >tftp receive 201.228.56.13:70 newtext.fil remote.name



TFTP 647



 Commands



648 TFTP



 THEO+COM Command THEO+COM is a communications program that allows your computer to communicate with another computer by sending and receiving files and emulating a terminal to provide access to the other system as a console.



( options



options



»



ALF ANSI ASCII COMnn CTL DIAL number EOF= EOT FILES



HALF HANGUP MASTER NOEOT NOLOGO PCTERM RECEIVE file REDIAL SCRIPT file



SEND file THEOS TRACE TRACEFILE file TVI TYPE VT100 VT220 VT220-8



WYSE50 WYSE60 XMODEM XMODEM-CRC XMODEM-1K YMODEM



Command synonyms: COM, TERMINAL Operation



Invokes THEO+COM in terminal emulation mode. The remote system must be connected to the first communications port on your system. Use command-line options or the built-in menu to perform any of the functions supported by THEO+COM or to change the configuration. The built-in menu is invoked by pressing (Break),(M). Refer to the THEO+COM Installation and User’s Guide for a complete description of the operation and usage of this command.



Options



ALF



Tells THEO+COM to add a line-feed at the end of every line transmitted. When this option is omitted, CR is used as the default End-of-Line character.



ANSI



Emulates an ANSI compatible terminal.



ASCII



Uses the ASCII protocol to send and receive files from the remote computer system.



C7



Synonym to the TVI option.



C55



Synonym to the WYSE50 option.



C58



Synonym to the WYSE60 option.



THEO+COM 649



Commands



THEO+COM



 C90-C99



Synonym to the PCTERM option.



C180-C189 Synonym to the PCTERM option. C100



Synonym to the VT100 option.



Commands



C210-C219 Synonym to the PCTERM option. C220



Synonym to the VT220 option.



COMnn



The currently attached COMnn is used for the communications port. When this option is not specified, the first attached COM device is used. Refer to the Attach and the Sysgen for information about attaching COM devices.



CTL



Sets control mode on. With control mode on every control character received in terminal emulation mode is displayed as two characters. For instance, Control-I is displayed as ^I.



DIAL number Using the modem connected to the communications port,



dials number and waits for a connection. After the connection is established, THEO+COM is exited, leaving the telephone connection open. DIAL must be the last option specified because characters following the word DIAL are treated as part of the number to dial.



Refer to “Dial” on page 163 for information about number. EOF=



Sets the character used to mark the end of a file transmitted with the ASCII protocol.



EOT



Used with the SEND file option to indicate that the end-oftransmission character is sent after all of the files are transmitted. This is a default option.



FILES



Can be used with the THEOS protocol and the SEND file option. It indicates that the file contains a list of files to be sent. This file is typically created by the FileList with its option FILES.



HALF



Uses half-duplex communications. Half-duplex is also called “Echoplex” because it causes every character transmitted to the remote system to be automatically echoed on your system. When this option is omitted, full-duplex communications is uses.



HANGUP



Using the modem connected to the communications port, issue the hang-up command.



650 THEO+COM



 Use master-mode duplex communications in terminal emulation. Each character typed is displayed on your screen. Each character received from the remote system is echoed back to that system.



NOEOT



Can be used with the THEOS protocol and the SEND file option. It indicates that no end-of-transmission character is sent after the last file is transmitted.



NOLOGO



Suppress the THEO+COM logo and copyright screen.



NOTYPE



Suppress the display of dialing messages and responses.



PCTERM



Emulate a PC Term or scan-code type keyboard and monitor. C90-C99 and C180-C189 may be used as synonyms to this option. C90-C99 selects a monochrome PC Term terminal emulation; C180-C189 selects a color PC Term terminal emulation.



RECEIVE file Receive file from the communications port. The transmis-



sion protocol is specified with other options or it uses the default THEOS protocol. REDIAL



Using the modem connected to the communications port, the last number dialed is redialed. After a connection is established, THEO+COM exits.



SCRIPT file Execute the Modem Script Language file file. Refer to the



THEO+COM Installation and User’s Guide for a description of the Modem Script Language. SEND file



Send file on the communications port. The transmission protocol is specified with other options or it uses the default THEOS protocol. file may contain wild cards.



THEOS



Use the THEOS protocol to send and receive files from the remote computer system.



TRACE



Enables file transfer tracing. A window is opened in the upper right corner of the display, showing the protocol activity during a transfer.



TRACEFILE file Similar to the TRACE option, except the protocol activity



is output to file. TVI



Emulate a TeleVideo model 910 or model 925+ compatible terminal. C7 may be used as a synonym to this option.



TYPE



Display dialing and redialing messages and responses. This is a default option. THEO+COM 651



Commands



MASTER



 Commands



VT100



Emulate a DEC VT100 compatible terminal. C100 may be used as a synonym to this option.



VT220



Emulate a DEC VT220 compatible terminal in 7-bit mode. C220 may be used as a synonym to this option.



VT220-8



Emulate a DEC VT220 compatible terminal in 8-bit mode.



WYSE50



Emulate a Wyse model 50 compatible terminal. C55 may be used as a synonym to this option.



WYSE60



Emulate a Wyse model 60 compatible terminal. C58 may be used as a synonym to this option.



XMODEM



Use the XMODEM checksum, 256-byte protocol to send and receive files from the remote computer system.



XMODEM-CRC Use the XMODEM CRC-16, 256-byte protocol to send and



receive files from the remote computer system. XMODEM-1K Use the XMODEM-1K CRC-16, 1024-byte protocol to send



and receive files from the remote computer system. YMODEM



Use the YMODEM, CRC-16, 1024-byte protocol to send and receive files from the remote computer system.



Notes



The command name COM is a synonym to the THEO+COM command. It is not a separate program but only an entry in the SYSTEM.THEOS32.SYNONYM file. If standard synonyms are disabled (see “Account” on page 13 and “STDSYN” on page 110), this synonym name may not be allowed.



Defaults



EOT, THEOS, TYPE



Restrictions



A communications port must be attached.



652 THEO+COM



 TheoMail Client The TheoMail command is the principal component of THEO+Mail. It is a client application program that allows you to create and send e-mail messages to other people and to receive, read and manage messages sent to you. .



THEOMAIL ( option



2



THEOMAIL



mailbox ( option



mailbox



»



name of the mailbox to check



option



»



CHECK COMPACT NOPROXY SEND



Command synonym: Operation



Commands



1



EMAIL



Mode 1—Invokes the TheoMail client program using the default mailbox for the account that you are currently logged on to. For information about mailboxes and default mailboxes, refer to the THEO+Mail User’s Guide and Reference manual. Mode 2—Invokes the TheoMail client program using the specified mailbox.



Options



CHECK



This option invokes TheoMail in non-interactive mode. It starts TheoMail with the mailbox selected according to the command line entered but it ignores the settings for Send on Check and Check for New Mail frequency. Instead, it checks each of the POP3 servers specified in the configuration and retrieves any mail waiting on those servers. After receiving the mail and possibly filtering it, TheoMail exits.



COMPACT



This option invokes TheoMail in non-interactive mode and performs a compact or reorganization of the mailbox database. The database is not checked for integrity first. This option should be used if the database is corrupted and you cannot start TheoMail normally because of the corruption. By compacting and reorganizing the database you should be able to invoke TheoMail normally afterward.



NOPROXY



This option invokes TheoMail and tells it to not use any Proxy Server setting from the SETUP SMTP configuration, even if one is specified there. You should not use this option unless you TheoMail 653



 have an alternate connection to your SMTP and POP3 servers available.



Commands



SEND



Notes



Similar to the CHECK option, this invokes TheoMail in noninteractive mode. However, instead of checking for new mail it sends any mail that has been queued and then exits.



If the mailbox has a password defined, you must enter the password for the mailbox before it can be opened. Unless the COMPACT option is used, when you start TheoMail the mailbox database is checked for integrity. If the database is large (tens or hundreds of megabytes), this may take some time. During this time the copyright message is displayed which lets you know that has started. If the database appears corrupt or has a lot of unused space in it, you are warned about the situation and, after acknowledging the warning, the database is rebuilt using the same function as the Tools Menu, Compact menu item. If this happens often it is an indication that something serious is wrong and you should contact your system administrator. After TheoMail checks the integrity of the database it checks the Sent and Deleted folders to see if there are any messages that should be removed. This is done during TheoMail exit and at startup time just in case TheoMail was exited abnormally the last time it was used. TheoMail first checks the Sent Expiration setting. If it is non-zero the messages in the Sent folder are examined to see if they qualify for deletion. Any messages in that folder that are older than the Sent Expiration value are moved to the Deleted folder.



Next, the Empty Deleted setting is checked. If it is enabled any messages in the Deleted folder are removed by erasing them. If the Empty Deleted item is not enabled, but the Deleted Expiration specifies a non-zero age, messages in the Deleted folder are removed if they are older than the number of days specified in that field. Unless the CHECK or SEND options are specified, if the Check for New Mail item in the Tools Menu, Options screen (see the THEO+Mail User’s Guide and Reference manual) specifies a time frequency for automatic mail checking, mail is checked as soon as TheoMail starts. • Invoking TheoMail with an EXEC When the TheoMail client is invoked from an EXEC program you may use the &Stack or &BegStack statements to initiate actions by the client program without operator input. When TheoMail is invoked with an EXEC it



654 TheoMail



 may operate differently depending upon whether there is data on the EXEC stack and what that data is.



&Stack Q\ TheoMail mymail EmailChk mymail &If &RetCode > 0 EmailGet mymail &IfEnd



In the above example, the “Q” in the first line is a Control-Q. This can be entered with WindoWriter by using the Tools menu, Control Characters font. Enter the letter “Q” and then use Tools menu, Normal Font to return to normal text input. The above EXEC invokes TheoMail using the “mymail” mailbox and gets any incoming mail. It then used EmailChk to see if there is any new mail and, if so, uses the EmailGet to extract that mail to a standard text file. If there is data on the EXEC stack but the first character is not a ControlQ, TheoMail will not try to perform any automatic check for incoming mail but will instead accept those stacked characters as normal input. For instance: &BegStack [CNTheos Support  Problem Report &End TheoMail mymail



In this example, the “[” character in the first line is a Control-[ or the Esc character. This EXEC invokes TheoMail and starts the composition of a new message to THEOS Technical Support. The cursor will be positioned to the body of the new message, ready for the operator to enter the text. Defaults



The default mailbox used when TheoMail is invoked without specifying a mailbox is determined by the current account name that you are logged on to. This relationship between account names and default mailboxes is defined in Setup Email, which is described in THEOS Corona Version 5 Operating System Installation and Setup Guide.



Restrictions



Only one user may use a mailbox at any one time.



See also



EmailChk, EmailDel, EmailGet, EmailPut, SendMail



TheoMail 655



Commands



If the first character on the EXEC stack is a Control-Q character, TheoMail will perform its automatic check for incoming mail and then exit. This is identical to the CHECK command-line option. This feature is useful if all you want to do is to get any mail and not stay in the TheoMail environment. For instance:



 Commands



656 TheoMail



 TIM Command The TIM command invokes the THEOS Instant Messenger and allows you to communicate with other users that are in your contact list.



TIM



2



TIM



passport password



3



TIM



passport



passport



»



Passport E-mail account and domain



password



»



Password to the passport account



Operation



Commands



1



Invokes the THEOS Instant Messenger using either the default passport account (Mode 1) or the requested account. Mode 1—This mode starts in one of two ways, depending upon whether or not the TIM_PROTO and TIM_AUTOLOGIN environment variables are defined. If these variables are defined then TIM signs onto the default account. Otherwise, it displays the Sign-In Form allowing you to specify the protocol, account and options desired for this session. Mode 2—Invoke TIM and display the sign-in form with passport and password filled in: >tim "[email protected]" "paSsWoRd"



TIM 657



 Click on “Ok” to sign in. Refer to User Interface for descriptions of the various fields. Mode 3—Similar to Mode 2 except the password is not typed in the command line and therefore is never displayed in clear text.



Commands



Notes



The TIM command uses a central configuration file to maintain the information about the passport account to use and the options desired for that account. You may have multiple accounts defined and there may be multiple instances of TIM in use on one system at any one time. During the normal operation of TIM, it may need to open several windows. Since the software does not know how you want your screen arranged, each of these windows is initially positioned in the center of your screen. You should drag the windows to other positions so that you can see each of the windows on your desktop. The position that you drag them to will be remembered by TIM during this session. When the TIM command is exited you are signed off of the passport account.



Defaults



There are two environment variables that can be used by TIM. If these variables are defined and have values then those values are used as the defaults. The variables are: TIM_AUTOLOGIN Specifies the default passport account name. Normally,



this name is a complete E-mail address such as [email protected]. TIM_PROTO Specifies the default protocol to be used by TIM. Set this variable to MSN, TIMP or YAHOO.



For ease of use, these variables can be defined in the Account profile Before defining these variables refer to “First-time Usage” on the next page. Restrictions



This program requires an internet connection. You must also have an account on one of the supported protocol servers.



See also



FileManager, FTP, Mailbox, Msg, Receive, Send, TFTP, TheoMail



658 TIM



 First-time Usage



Before using THEOS Instant Messenger for the first time you must have a passport account. Specifically, in order to use the MSN version 7 protocol you must have a passport account with the .NET service provided by Microsoft. If you do not have a passport account or if you want to have an additional account, use your web browser and connect to http://www.passport.com and click on the “Sign up for your free .NET Passport today” link.



After you have acquired a passport account you can define the environment variables TIM_PROTO and TIM_AUTOLOGIN. >set tim_proto=MSN >set [email protected]



Once this has been done and you invoke TIM it asks you to supply the password. After that initial sign-in TIM will remember the password for that account and you can invoke TIM and it will sign into that account automatically.



TIM 659



Commands



When signing up for the new passport account you are asked for an E-mail address and a password. The password it is asking for is the password that you want to use for the passport account and it should not be the same as your E-mail account password. The E-mail address will be used as your account name and, although you are not normally sending or receiving Email with TIM, the address must be a valid address at the time that you sign up for the passport account. After signing up for the account the passport system will send an E-mail message to the account asking the owner of the account to confirm that they (you) wanted this passport account.



 User Interface



When TIM is invoked without the environment variables TIM_PROTO and TIM_AUTOLOGIN defined or when this default account is bypassed, the TIM sign-in form is displayed allowing you to specify the protocol, account and password for that account.



Commands



Sign-In Form



Protocol



Select the protocol from the protocols supported by TIM: TIMP



This is the native TIM protocol which is used by the TIM server.



MSN V7 The Microsoft messenger protocol, version 7. Yahoo



The Yahoo instant messenger protocol.



The protocol selected tells TIM where to find the server for passport names and, at the server, it can find your list of contact names, etc.



660 TIM



Options



Select this button to set or change the options associated with this passport name. This option screen is described on page 661. You cannot change the options until there is a Passport and a Password defined.



Passport



Enter the passport account name. For the MSN V7 protocol, this is an E-mail account name and domain name. For instance, [email protected].



 Password



Enter the password for the passport account. This is a casesensitive field and the password is not displayed as you type it. Be careful to enter it correctly.



The above form is normally only displayed when you are signing in to a passport name that you have not used before. However, you may display this screen (to get to the Options button) by signing on to a passport and then changing your Status to “Offline.” This will cause the above form to display and you can either sign on to another passport, create a new sign on or change the options of an existing passport. „ TIM Options The options form is used to configure the various options that can be specific to an account.



Password



This field is used when you need to change the password that you have saved for this account. Making a change in this field does not change the password that has been recorded at the instant messenging protocol server for your account. It only changes the profile that is saved and used by TIM.



TIM 661



Commands



When you select the Ok button or the Options button for an account that has not been saved before, you will be asked if you want to add it to the database. If you have entered the name and password correctly respond with a “Yes.” Otherwise, respond with a “No” and you can make the necessary changes.



 Font



Selecting this button invokes the Fonts form described below.



Use EmotIcons When enabled you can send and receive emoticons during



chat conversations. Change to TIM session automatically This feature controls whether or not



Commands



the TIM session will “wake up” and make itself the active session when a message is received. Enable sound Enables the sounds capability of TIM. Show a message when someone logs in If enabled, when one of your regis-



tered contacts signs on a message will be displayed on the active session of this console. Download path The path specified in this field is used when you receive a



file. You can either type in the path that you want to use or use the Browse button to search for the desired location. Show away after xx minutes When your console is idle for a period of time, TIM will change your status to “Appear away.” The length of



that time is specified here. Fonts The font selection form is used to defined the font used to display the message text in the Message history and Message text boxes when chatting with a contact.



Font



This area lists the fonts that are available on this system and highlights the font that is currently defined as the display font. You can move this highlight bar to any of the available fonts. Changing the font is immediately reflected in the Sample area.



662 TIM



 Style



The style list box shows the various font styles that are available with the Font that is currently selected and it highlights the style that is currently selected. Changing the style is immediately reflected in the Sample area. This list box shows the font sizes that are supported by TIM and highlights the size that is currently selected. The sizes range from 8 pts to 72 pts. A point is 1/72 of an inch and is a standard unit of measurement in typography.



Effects



Strikeout



Checking this box will display the text with a line through the characters: The quick brown fox jumped...



Underline



Checking this box underlines the text: The quick brown fox jumped...



Color



This list box shows the colors that are supported by TIM and shows the currently selected color.



Changing the effects is immediately reflected in the Sample area. Sample



This area displays a sample using the selected Font, Style, Size and Effects.



Downloads The Download path in the TIM Options form allows you to specify the location where all received files are to be saved. You may either type in the path or use the Browse button to search for an existing directory to use. The path specified here is used when you receive a file from a contact during a chat session (see “XFile” on page 668).



TIM 663



Commands



Size



 Commands



The default location for downloads is /PROGRAMS/TIM/DOWNLOAD:S. „ Connection Options The connection options refers controls whether or not a proxy server is used to establish the connection between this system and the instant messaging server.



664 TIM



Use proxy



This field must be checked to enable the other fields on this form and to enable the usage of a proxy server.



Type



Use the drop-down list to select the type of proxy server.



Server



Enter the IP address of the proxy server that you are using.



 Port



The default port number is set when the Type of proxy is selected. You may override that default and set the port to another value if you wish.



Username



This field is required when using a Type of SOCKS Version 5.



Password



This field is required when using a Type of SOCKS Version 5. Commands TIM 665



 „ Using TIM



Commands



After you have signed on to your passport account TIM displays the contact list form:



Contact list The contact list is the large box in this form. It lists each of the



users that have been defined as your contacts and it shows each of the “nick names” or “screen names” that the contacts have defined, along with their current status. When any of these contacts change their status, you will see this list updated within seconds. Contacts are added to an account in one of two ways. You either add them using the Add button on this form or a remote user requests that you be added to their contact list and you agree. The actual list of contacts is maintained by and on the protocol server. Nick name



This is your “screen name” or nick name. It is the name that other users on your Contact list will see you as. For instance, in the above display, “Susan” is the nick name that she has chosen. Her actual account name might be [email protected]. In the above display, other users see the current user as “Chris @ home.”



666 TIM



 Status



This field defines your status as others see you.



Sort by



You can refresh or change the order of the displayed contacts by selecting this field.



Chat



Selecting this button initiates a chat session with the currently highlighted contact in the Contact list. When the button is pressed the chat form is displayed (shown on page 668). Refer to “Chatting with a contact” on page 668 for additional information about instant messenger chats.



Add



This button allows you to add another contact to your list. Refer to “Adding New Contacts” on page 670 for additional information about adding people to your contact list.



Delete



Selecting this button deletes the currently highlighted contact from your Contact list.



Block



Use this button if you want to block messages from the currently highlighted contact in the Contact list.



TIM 667



Commands



The status field is only an indicator to others of what you want them to see. Except for “Offline,” all of the status labels are just comments. Changing your status from “Online” to “Away” or “Busy” does not prevent others from trying to imitate a ‘conversation’ with you.



 „ Chatting with a contact



Commands



When you select the Chat button or when a user on your Contact list initiates a chat session with you, the following form is displayed allowing you to enter messages to be sent to the other user and allowing you to see the “conversion” as it progresses.



Message history



The top text box is an area that shows the message history. Every message from the contact to you and every message from you to the contact is displayed here. When the list of messages is longer than the display area a vertical scroll bar appears. You can you this scroll bar to look back in the conversation.



Message text



The bottom text box is the area that you use to type your message to the contact. When entering the text, do not press (Enter) until you are ready to send. Although the text might appear as a long line of characters, when it is sent and when it is displayed in the Message history field, it is formatted to fit the area available.



668 TIM



XFile



Selecting this button allows you to send a file to the contact that you are chatting with. Refer to “Sending and Receiving Files” on page 671 for information about sending and receiving files with contacts.



Font



Selecting this button invokes the Fonts form described on page 662.



 EmotIcons



This button allows you to ask another member of your contact list to join in the chat conversation. When selected you are presented with a form that allows you to select the contact name that you want to invite into the conversation. Only the contacts that are currently signed on are offered.



Send



The “Send” button causes any and all of the text that you have typed in the Message text field to be sent to the contact. It is also reformatted and displayed in the Message history field.



Exit



This button exits the chat session and offers you a chance to save the text of the session in a file:



TIM 669



Commands



Invite



 If you choose “Yes” you will be offered the standard file save dialog box and you can specify the location and name of the file to save this chat session text. „ Adding New Contacts



Commands



You can add a new contact to your contact list at any time. Merely select the Add button when the Contact List form has the focus.



Email address Enter the email address of the person that you want to add



to your contact list. Group



670 TIM



Select the group that you want this contact listed as.



 „ Sending and Receiving Files During a chat conversation you can send a file from your system to the contact’s system by selecting the XFile button of the chat form. When this is done you are presented with a standard file selection form allowing you to select the file that you want to send to the other party. Commands



After the file is selected and the Open button is pressed, a request is sent to the contact that you are chatting with asking them to either accept the file transmission or to decline it. At the same time your chat form displays a message stating that you are waiting for the other party. When they accept, the file is sent to them and messages are displayed on both chat forms reporting the progress and status of the transfer.



TIM 671



 Commands



A similar but reverse process occurs if the contact wants to send you a file. After they select the file that they want to send to you a message pops up asking if you want to accept the file.



672 TIM



 Touch Command Sets the date and time-stamp on a file.



TOUCH file ( options



2



TOUCH date



file



3



TOUCH date



time



Commands



1



file



file



»



file name with optional path; may contain wild cards



options



»



DATE reffile NOTYPE TYPE



date



»



date in current DATEFORM format



time



»



time specification using colon delimiters



Operation



date time



Mode 1—The date and time-stamp on file is changed and the modified attribute is set. If no options are used, the date is set to the current date and time. >touch example.file File "EXAMPLE.FILE:S" touched: 10/22/01 10:22:54 One file changed.



Mode 2—The date-stamp for file is changed to date. The time is set to 08:00. >touch 01/02/03 example.file File "EXAMPLE.FILE:S" touched: 01/02/03 08:00:00 One file changed.



Mode 3—The time-stamp for file is changed to date and time. >touch 01/02/03 04:05:06 *.txt File "EXAMPLE.TXT:S" touched: 01/02/03 04:05:06 File "EXAMPLE1.TXT:S" touched: 01/02/03 04:05:06 File "EXAMPLE2.TXT:S" touched: 01/02/03 04:05:06 3 files changed.



Touch



673



 Options



DATE reffile Set the date and time of file to the date and time of reffile. NOTYPE



Suppress the display of result messages and the summary line. >touch example.* (notype



Commands



TYPE



A default option that displays the results of each file changed and a summary line of the total number of files changed. >touch example.* File "EXAMPLE.BASIC:S" touched: 10/12/01 11:02:22 File "EXAMPLE.INDEXED:S" touched: 10/12/01 11:02:22 File "EXAMPLE.DIRECT:S" touched: 10/12/01 11:02:22 File "EXAMPLE.FILE:S" touched: 10/12/01 11:02:22 File "EXAMPLE.MAIL:S" touched: 10/12/01 11:02:22 File "EXAMPLE.DIRECT1:S" touched: 10/12/01 11:02:22 File "EXAMPLE.COMMAND:S" touched: 10/12/01 11:02:22 7 files changed.



date



Set the date of file to date. If time is not specified, the time is set to 08:00:00. >touch test.file (10/15/97 File "TEST.FILE:S" touched: 10/15/01 08:00:00 One file changed.



The earliest date that you can use in the THEOS file system is 01/01/86. time



Set the time of file to time. If date is not specified, date is set to the current date. >touch test.file (15:32 File "TEST.FILE:S" touched: 10/12/01 15:32:00 One file changed.



Notes



A file specification can omit the file-type if the environment variable FILETYPE is defined. For more information about the FILETYPE variable, see “Environment Variables” on page 111 of the THEOS Corona Version 5 Operating System Reference manual. The “modified” attribute for file is set with this command. The display of the Touch command (output when option TYPE is in effect), is output to stderr, not stdout. To redirect this output use the >& operator.



Defaults



The current date and time are used unless otherwise specified.



See also



Change, FileManager



674 Touch



 TraceRT Client The TraceRT client reports the path and the time taken for a message to be sent to and received from a remote host. “TRACERT” stands for “TRACE ROUTE.”



TRACERT



server



2



TRACERT



server ( options



server



»



network server name or id (may also be localhost)



localhost



»



LOCALHOST



options



»



HOPS



Operation



NORESOLVE



Commands



1



RESOLVE



Mode 1—Traces the route between you and server, using default options of RESOLVE, and HOPS 30. >tracert www.theos-software.com Tracing route to WWW.THEOS-SOFTWARE.COM (65.45.113.228) over a maximum of 30 hops. 1 2 3 4 5 6 7 8 9 10 11 12 13



20 20 14 23 23 24 106 24 26 28 28 33 48



ms ms ms ms ms ms ms ms ms ms ms ms ms



10.88.74.1 bb1-ge2-1.potlnd1.or.home.net (65.4.47.1) c1-pos5-2.ptldor1.home.net (24.7.75.229) c1-pos1-0.snfcca1.home.net (24.7.64.22) c2-pos1-0.snjsca1.home.net (24.7.65.161) above-athome.sjc2.above.net (208.185.175.133) core4-core3-oc48.sjc2.above.net (208.184.102.198) pao1-sjc2-oc48-2.pao1.above.net (208.185.175.162) allegainace-abovenet.allegiancetelecom.com (216.200.249.90) POS3-0.SNFECAEJ15W.core.algx.net (66.2.95.101) SNFECAEJ05W.gw.SFO.algx.net (216.99.234.11) 65-45-94-218.customer.algx.net (65.45.94.218) WWW.THEOS-SOFTWARE.COM (65.45.113.228)



Trace complete.



Mode 2—Traces the route between you and server, using the specified options. >tracert 199.2.117.161 (noresolve hops 10 Tracing route to 199.2.117.161 over a maximum of 10 hops. 1 2 3 4 5 6 7 8 9 10



11 10 11 23 25 25 24 25 28 27



ms ms ms ms ms ms ms ms ms ms



10.88.74.1 65.4.47.1 24.7.79.17 24.7.64.22 24.7.65.157 129.250.9.85 129.250.3.121 129.250.3.162 129.250.3.34 129.250.3.18



Trace complete.



TraceRT 675



 Options



HOPS count



Specifies the maximum number of segments or hops to report. If server is not reached within this number of hops, the trace is abandoned. The default number of HOPS is 30.



NORESOLVE Suppress the translation of IP addresses to domain names.



Commands



RESOLVE



Notes



Translate each IP address to its domain name. This is a default option.



TraceRT is used to determine how many routers are involved in a particular connection to a remote site. Often this will explain why access to some sites appears slow while others are quick to respond. Each router in the path requires additional time to transmit each packet of data. This is particularly noticeable when viewing web pages. Many HTML pages require hundreds of packets of data to be communicated back and forth before the page is completely displayed on the screen. TraceRT attempts to trace the route that an IP packet travels between you and server. It does this by sending a short packet to an unused port on server. The message is sent as many times as specified with the HOPS option, or a default value of 30. A field in the header of the packet is used to cause the packet to fail at each of the routers in the path of the message.



The time displayed by TraceRT for each of the hosts is the round trip time that it took for the message to get to that router and return to you. The times reported by TraceRT will be different, almost every time that it is run. The amount of traffic on the Internet is constantly changing, from millisecond to millisecond. Heavy traffic causes slow delivery because of message collisions and retransmissions over each of the various mediums between you and the destination. See also



676 TraceRT



Ping



 Tree Command Displays the subdirectory tree.



TREE



( options



2



TREE



path ( options



path



»



starting directory name; may not include account name



options



»



NOSORT PRTnn SIZE SORT



Operation



Commands



1



Mode 1—Starting at the current working directory, the directory tree structure is displayed on the standard output device. >pwd /VERTICAL:S >tree /vertical doc programs files programs



Mode 2—Starting with path, the directory tree structure is displayed on the standard output device. >pwd /VERTICAL:S >tree /package /package doc programs



Tree



677



 Options



NOSORT



Causes the directory tree to be displayed in the sequence it is found on disk. No sorting of the directory names is attempted.



Commands



>tree (nosort / data vertical doc programs files programs package doc programs misc programs doc



PRTnn



Indicates that Tree is to print the current directory tree structure on the attached printer number nn. The option keyword PRT may be specified as PRT, PRINT or PRINTER. As a convenience, PRINTER1 may be specified as P.



SIZE



Includes a count of the files in the subdirectory and the total disk space used by those files. >tree (size / ............................... data ......................... misc ......................... doc ....................... programs .................. package ...................... doc ....................... programs .................. vertical ..................... doc ....................... files .................. programs ............... programs ..................



678 Tree



(1186, 29012K) (219, 17205K) (27, 77K) (2, 16K) (23, 54K) (248, 3162K) (5, 4K) (240, 3150K) (648, 8401K) (33, 62K) (19, 27L) (11, 27K) (413, 4062K)



 SORT



A default option that sorts the directory tree structure in alphabetical sequence.



Commands



>tree (size / data misc doc programs package doc programs vertical doc files programs programs



Notes



The line-graphics characters used to show the directory hierarchy are suppressed if the environment variable LINEGRAPH is set to “N.”



Defaults



SORT is a default option.



Restrictions



You may only access directories in the current account.



Tree



679



 Commands



680 Tree



 TWS Command The TWS command allows users of the THEOS WorkStation Client on a Microsoft Windows system to control the behavior of the client session window or control the Gutenberg slave printer to the TWS client.



1



TWS



function



2



TWS



Gutenberg-function



function



»



Operation



FULL MAXIMIZE MINIMIZE ONTOP RECEIVE RESTORE



SEND SHELL TITLE TOP



TWS



Gutenberg-function »



ACCOUNT ALLOW CHANGE DISCONNECT EXEC FOCUS



ALIGN FONT PRINT_WINDOW BARCODES HAS_FONTS REC_PAGE CHANGE_AREA IMAGE ROTATE CHECK_PRINTERLIST_FILE SELECT_AREA CLOSE MODE SETPOS COLOR NEW_FILE SIZE DEFAULT_UNITSPICTURE STYLE ERASE_FILE PRINT_NEXT_PAGE TEXT_FILE FIELD PRINT_RECORD FILE_RECORDSPRINT_TXT



Mode 1—Performs function on the THEOS WorkStation Client session window. >tws disconnect off >tws change off >tws ontop on



The above commands prevent the operator from disconnecting from the THEOS Login Server and from changing the focus or size of the window used by the THEOS WorkStation Client. Additionally, the window will remain displayed on top of all other windows, even if the Net or Remote command is used to execute another program.



TWS 681



 Mode 2— Functions



These functions are used to control the TWS session and its display window:



Commands



ACCOUNT ALLOW



Synonym to the DISCONNECT option.



CHANGE



This option allows you to control whether or not the TWS session can lose the focus: CHANGE OFF



Disables the ability of the user to select another window, either manually with the mouse or keyboard or with the EXEC mode of the Net. This function also disables the ability to minimize the client session window with the mouse. The session may be minimized with the TWS MINIMIZE function.



CHANGE ON



Enables the ability to select another window on the client and to minimize and maximize the THEOS WorkStation Client window.



CLOSE



Closes an image that was displayed by the PICTURE function and removes it from the display.



DISCONNECT



This option either performs a disconnection operation or it controls whether or not the user is allowed to manually disconnect the TWS session from the THEOS server:



DISCONNECT OFF



Prevents the user from disconnecting this THEOS WorkStation Client session using the disconnect icon. The user may only disconnect under program control.



DISCONNECT ON



The user may disconnect this session by clicking on the disconnect icon.



EXEC



Execute a command on the Windows system. >TWS EXEC WINIPCFG



682 TWS



FOCUS



Causes the TWS program to become the active window on the client system. If the session window was minimized, it is restored to its prior size as it is activated.



FULL



The window used by the TWS session is set to full screen. Similar to MAXIMIZE except there is no frame, scroll bars, menu



 bar, title, etc. The entire screen of the Windows system is used for the display of the THEOS server session. The window used by the TWS session is set to its largest size.



MINIMIZE



The window used by the TWS session is minimized to an icon and the prior window is selected as the focus.



ONTOP



This option controls whether or not the display of the TWS session is on top of all other windows displayed on the Windows’ console, or not: ONTOP OFF Disables the “on-top” feature for the THEOS



WorkStation Client session window. That is, when the window is not the active window, other windows may overlay it. ONTOP ON Enables the “on-top” feature for the THEOS Work-



Station Client session window. That is, when the client session window is not the active window, it still is the topmost window displayed on the screen and might overlay the window that has the focus. If the client session window is currently minimized, the on-top feature is not evident until the window is restored. That is, the minimized icon is not displayed on top of other windows. The option TOP may be used as a synonym to ONTOP. RECEIVE RESTORE



The TWS session window is restored to its size before being set to maximized, minimized or full-screen.



SEND SHELL



Synonym to the EXEC option.



TITLE “title” Change the title used in the THEOS WorkStation Client ses-



sion window. TOP



This is a synonym to the ONTOP option.



TWS 683



Commands



MAXIMIZE



 Gutenberg Functions



The following functions are used, generally in an EXEC program, to format and print reports on the TWS slave printer or to an attached Gutenberg printer. These functions are generally used as a set in a programmed sequence.



Commands



TWS TWS TWS TWS TWS TWS TWS TWS TWS TWS TWS TWS



684 TWS



New_File ; start a new report Font "Times New Roman" ; set the font Style 2 ; boldface Size 240 ; 24 point Align 1 ; center Print_Txt "This is the Title" Align 3 ; left and right justified Style 0 ; normal Size 120 ; 12 point Print_Txt "Now is the time for all good men to come to" Print_Txt "the aid of their party." List_File prt3 ; print the report



 „ ALIGN Define the text alignment and text background for subsequent text written to the report.



TWS ALIGN



align-code »



Bit-mapped value indicating text alignment



The formatting specified by this function is only applied to subsequent text written to the report. If print windows are being used and the mode setting of extended is specified, then the alignment specified here only applies to the currently selected print window (see “SELECT_AREA” on page 702). If extended is not specified, which is the default, then the alignment specified here applies to all windows. Align codes The alignment attribute is specified using a bit-mapped code. This code is one or more of the following values: Code



Meaning



0x0000



0



Left



0x0001



1



Center



0x0002



2



Right



0x0003



3



Justified



0x0008



8



No wrap



0x0020



32



Frame



0x0040



64



Light gray background



0x0080



128



White background



0x00C0



192



Background color



The alignment codes listed above can be combined together by adding the desired values. tws align 3 tws align 2+8+32+64 tws align 106



; left and right alignment ; right, no wrap, frame and light gray bg ; right, no wrap, frame and light gray bg



TWS 685



Commands



align-code



 Commands



Each time that the align function is used it completely replaces any previous alignment specifications but it only applies to text that is subsequently written to the report.



686 TWS



 „ BARCODES Print text interpreted as barcode using the 3 of 9 barcode algorithm.



TWS BARCODES



text



width



height units



fontname



»



Text to print



width



»



Optional width of bar code in units



height



»



Optional height of bar code in units



units



»



Optional unit of measurement code



fontname



»



Optional name of font to use for



Commands



text



The text is printed using the default font for barcodes and size or using the parameters specified. The default width is 240 decipoints, the height is proportional to the width, units is decipoints and the fontname is “3 of 9 Barcode.” You may request the default width, height or units by specifying a value of zero for the parameter. When a fontname is specified, it should be the name of a font that conforms to the 3 of 9 barcode character set. The barcode interpretation of text is written to the report at the current position using the currently defined style (see “STYLE” on page 703). No line breaks or spacing is output before or after the barcode is printed. If you desire any line breaks or spacing you must specify it by using the PRINT_TXT function. Afterward printing the barcode, the prior font and size is restored. Unit codes The unit-of-measurement attribute is specified using a bit-mapped code. This code is one or more of the following values: Code



Meaning



0x0001



1



Pixels



0x0002



2



Columns and rows



0x0004



4



Millimeters



0x0008



8



Inches



0x0010



16



Decipoints



Table 1: Unit of Measurement Codes



TWS 687



 Multiple barcodes can be printed with one command by enclosing the string in quotation marks.



Commands



tws barcodes 12345-67890 tws barcodes "09876 54321" 10 0 4



688 TWS



 „ CHANGE_AREA Change some of the attributes of an existing window area.



TWS CHANGE_AREA



window



last-page



flags



»



Number of existing window



last-page



»



Optional last page number to use window



flags



»



Optional flags to change



To change a defined window, the window must exist on the page that is currently being built in the report. A last-page value of zero means that the window exists in all remaining pages of the report. Flag codes Code



Meaning



0x0020



16



Link to next window



0x0040



64



Accept links from other windows



0x0080



128



Repeat on all following even numbered pages



0x0100



256



Repeat on all following odd numbered pages



0x0180



384



Repeat on all following pages



0x0200



512



Rows in table are separated



0x0400



1024



Area is a column of a table



tws print_window 4 3 2 20 10 4+32+64+256 ; repeat odd pages ... tws change_area 4 384 ; repeat on all pages



TWS 689



Commands



window



 „ CHECK_PRINTER Test an attached printer to see if it is a Gutenberg-capable printer.



TWS CHECK_PRINTER Commands



TWS HAS_FONTS prt



prt



prt »



Attached printer name to test



Test printer prt to determine if it is a Gutenberg printer. If prt is not specified then the default PRT1 is tested. Sets the return code to a non-zero value if the result is true; otherwise, when the specified prt is not attached or not a Gutenberg printer the return code is set to zero. tws check_printer prt3 RC = 1, 09:10:23, ET = 0:01, CPU = 0.080



„ CLOSE Close the image displayed in a window in the report.



TWS CLOSE window



window »



Number of window containing image/picture



?????? Why, what does closing it do? It is hardcopy after all. tws align 0xC8



690 TWS



 „ COLOR Set the font color for subsequent text output to the report.



TWS COLOR



fg bg »



Foreground color code



bg



»



Background color code



Sets the color of text that is subsequently output to the report. The foreground (fg) and background (bg) colors are specified with RGB values (red. green, blue), which are normally specified in hexadecimal. If print windows are being used and the mode setting of extended is specified, then the colors specified here only applies to the currently selected print window (see “SELECT_AREA” on page 702). If extended is not specified, which is the default, then the colors specified here apply to all windows. tws color 0xFFFFFF 0xFF0000 ; white on red



Some common color definitions: Code



Color



0x000000



Black



0x000080



Blue



0x008080



Cyan (green+blue)



0x008000



Green



0x404040



Grey



0x0000FF



Intense blue



0x00FFFF



Intense cyan



0x00FF00



Intense green



0xFF00FF



Intense magenta



0xFF0000



Intense red



0xFFFF00



Intense yellow



0x800080



Magenta (red+blue)



0x800000 0x808080



Red White or light grey



0x808000



Yellow (red+green)



TWS 691



Commands



fg



 „ DEFAULT_UNITS Set the default unit-of-measurement to be used by functions that do not specify a U/M explicitly.



Commands



TWS DEFAULT_UNITS



unit-codes



columns



rows



unit-code



»



Unit of measurement code



columns



»



Optional number of columns



rows



»



Optional number of rows 1



When this function is not used the default U/M is decipoints which is ------ of 10 1 a point or --------- of an inch. 720



For unit-code description, refer to Table 1: “Unit of Measurement Codes” on page 687. When the U/M selected is columns and rows, this function may specify the desired column and/or row values. tws default_units 8 ... tws default_units 2 100 ... tws default_units 2 0 60



692 TWS



; set to inches ; set to 100 characters per line ; set to 60 lines per page



 „ FIELD Output a field containing the current value of a variable.



TWS FIELD



field



mask »



Field name



mask



»



String specifying formatting information



xxxx Variable field names Name



Meaning



PAGE



Current page number



DATE



Current date



TIME



Current time



ENV



Environment variable



Mask codes Field



Code



PAGE



%u



Current page number



d



Day number, one or two digits



dd



Day number, two digit



ddd



Day of week name (Mon, Tue, etc.)



dddd



Full weekday name (Monday, Tuesday, etc.)



M DATE



Meaning



MM MMM



Month number, one or two digits Month number, two digit Month name (Jan, Feb, etc.)



MMMM



Full month name (January, February, etc.)



y



Year number in century, one or two digits



yy



Year number in century, two digits



yyyy



Four-digit year number



TWS 693



Commands



field



 Field



Code hh



Two-digit hour number, 12-hour format



H



Hour number, 24-hour format, one or two digits



HH



Commands



m TIME



ENV



Meaning



mm



Hour number, 24-hour format, two digits Minute number, one or two digits Minute number, two digits



s



Second number, one or two digits



ss



Second number, two digits



t



‘a’ or ‘p’ for am or pm



tt



‘AM’ or ‘PM’ for am or pm



text



Environment name



>tws align 0xC8



694 TWS



 „ FILE_RECORDS TWS FILE_RECORDS »



flags



»



divider



»



first



»



lines



»



flags



divider



first lines



Commands



xxxx



xxxx



xxxx Flag codes Code



Meaning



0x0400



1024



0x0800



2048



>tws align 0xC8



„ FONT Select the font to use for subsequent text output.



TWS FONT font-name



font-name »



Complete name of font on client system



The default font is “Arial.” >tws font "Times Roman"



„ IMAGE Output the graphic image file to the report at the current position.



TWS 695



 Commands



TWS IMAGE



filename



flags



filename



»



Name of image file



flags



»



Code indicating image-type and scaling



xxxx Flag codes Code



Meaning



0x0000



0



Image type is defined by its file extension (BMP, GIF, JPG, PCX, TIF)



0x0001



1



Image type is BMP



0x0002



2



Image type is JPG



0x0100



256



Scale horizontal width to window width



0x0200



512



Scale vertical height to window width



0x0400



1024



Center the image horizontally in the window



0x0800



2048



Center the image vertically in the window



0x1000



4096



Scale the window to fit the image size



0x8000



32768



File is a local file on the client machine



>tws align 0xC8



„ LIST_FILE Close the current report and print it on an attached printer.



TWS LIST_FILE prt



prt »



Name of attached printer



xxxx >tws align 0xC8



„ MODE Define the page orientation for the report.



696 TWS



 TWS MODE



mode-code



mode-code



»



Orientation code



xxxx Commands



Mode codes Code



Meaning



0x0000



0



Portrait orientation



0x0100



256



Landscape orientation



0x0400



1024



Extended windows



0x1000



4096



Duplex horizontal



0x2000



8192



Duplex vertical



>tws align 0xC8



„ NEW_FILE Begin a new report.



TWS NEW_FILE TWS ERASE_FILE



Any existing report that has not been output to the printer (see “LIST_FILE” on page 696) is cleared and not printed.



TWS 697



 „ PICTURE



Commands



TWS PICTURE



window



window



»



x



»



y



»



width



»



height



»



filename



»



flags



»



x y



width



height



xxxx Flag codes Code 0x0000



>tws align 0xC8



„ PRINT_NEXT_PAGE Add a page break to the report.



TWS PRINT_NEXT_PAGE xxxx 698 TWS



Meaning



filename



flags



 >tws align 0xC8



„ PRINT_RECORD Output the fields of a table record to the printer.



record



»



divider



»



record



divider



Commands



TWS PRINT_RECORD



xxxx >tws align 0xC8



„ PRINT_TXT Output some text to the report.



TWS PRINT_TXT



text



text



»



Text string



When text is not blank, no CR is added to the report. If text is a blank or empty string a CR is output to the report. tws tws tws tws tws



print_txt print_txt print_txt print_txt print_txt



"This is some text in a paragraph." " This is another sentence in the same paragraph." "Second paragraph with a break but no blank line " "between the paragraphs when printed."



TWS 699



 „ PRINT_WINDOW Define a print area on the report.



Commands



TWS PRINT_WINDOW



window



x



y



width



height



flags



window



»



Window number to define



x



»



Top left corner of window, x position



y



»



Top left corner of window, y position



width



»



Width of window in U/M specified in flags



height



»



Height of window in U/M specified in flags



flags



»



Codes specifying U/M and other attributes



xxxx Flag codes Code



Meaning



0x0001



1



Pixels



0x0002



2



Columns and rows



0x0004



4



Millimeters



0x0008



8



Inches



0x0010



16



Decipoints



0x0020



32



Link to next window



0x0040



64



Accept links from other windows



0x0080



128



Repeat on all following even numbered pages



0x0100



256



Repeat on all following odd numbered pages



0x0180



384



Repeat on all following pages



0x0200



512



Rows in table are separated



0x0400



1024



Area is a column of a table



>tws align 0xC8



700 TWS



 „ REC_PAGE action



action



»



first



»



last



»



type



»



first



last



type



Commands



TWS REC_PAGE



xxxx Align codes Code



Meaning



0x0000



>tws align 0xC8



„ ROTATE Set the rotation angle for text that is subsequently output to the report.



TWS ROTATE angle



angle »



Angle in degrees



A positive angle value indicates a clockwise rotation direction; negative values are a counter-clockwise rotation direction.



TWS 701



 >tws align 0xC8



„ SELECT_AREA Select a previously defined window for subsequent text output.



Commands



TWS SELECT_AREA window



window



»



xxxx >tws align 0xC8



„ SETPOS Position the print-head cursor for subsequent text written to the report.



TWS SETPOS



x



y



x



»



y



»



units



»



window



»



units



window



xxxx Align codes Code



702 TWS



Meaning



 Code



Meaning



>tws align 0xC8



Commands



„ SIZE Set the font size for subsequent text output to the report.



TWS SIZE



width



height



units



width



»



Optional font width



height



»



Optional font height



units



»



Optional code for unit of measurement



xxxx Unit codes For unit code description, refer to Table 1: “Unit of Measurement Codes” on page 687. >tws align 0xC8 >tws size 100 ; 10pt



„ STYLE Set the font style for subsequent text output to the report.



TWS STYLE



style-code



style-code



»



Bit-mapped code for font style



xxxx Style codes Code 0x0000



Meaning 0



Normal TWS 703



 Commands



Code



Meaning



0x0001



1



Italic



0x0002



2



Boldface



0x0004



4



Underline



0x0008



8



Compressed



0x0010



16



Double-wide



0x0020



32



Double-high



0x0040



64



Use alternate color



0x0080



128



Crossout



0x0100



256



Transparent background



>tws align 0xC8 >tws style 0x101 ;



„ TEXT_FILE Include a text file in the printer output.



TWS TEXT_FILE



filename flags



filename



»



Name of file to print



flags



»



Codes controlling print actions



start-line



»



First line in file to print



lines



»



Number of lines to print



start-line



lines



xxxx Flags Code



704 TWS



Meaning



0x0001



1



Suppress any CR in the file.



0x0002



2



Suppress any FF in the file.



0x0400



1024



Translate characters in the file into ???



0x0800



2048



Interpret characters as ANSI characters



0x2000



8192



Print the file using client machine application associated with the file’s extension.



0x4000



16384



The file is printed by the client machine.



 Code 0x8000



Meaning



32768



File resides on client machine. The filename must conform to the syntax rules of the client machine.



>tws align 0xC8



Although this program can be executed from the command line, it is normally used in an EXEC language program or by an application program. The operator of the THEOS WorkStation Client has on-screen controls that can control most of these functions and operations. The CHANGE, DISCONNECT and ONTOP functions of the THEOS WorkStation Client session can only be enabled/disabled with this program. There are no comparable screen-buttons or menu items that the operator can use to access these functions.



Restrictions



This program is only effective when it is executed in a partition that has a THEOS WorkStation Client for a console.



See Also



Net



TWS 705



Commands



Notes



 706 TWS



Commands



 UnErase Command This command allows you to restore a file that has been previously erased and placed in the recycle bin.



UNERASE



2



UNERASE



drive



3



UNERASE



drive ( CLEAR



4



UNERASE



file ( options



Commands



1



drive



»



Drive code or label of attached hard disk or image drive



file



»



File name with optional path; may contain wild cards



options



»



NOTYPE TYPE



Operation



Mode 1—Invokes the User Interface of the Unerase command. The drive for this mode is the first drive in the currently defined search sequence. Mode 2—Similar to Mode 1, invokes the User Interface of the Unerase command but the drive for this mode is specified by drive. Mode 3—Clear the recycle bin from drive. Mode 4—Undeletes the requested file. The result of the unerase operation is displayed or not displayed according to the option in effect.



Options



Defaults



NOTYPE



Suppress the display of the unerase attempt for each of the files specified. The summary line is also suppressed with this option.



TYPE



A default option that displays the result of each unerase attempt and displays a summary line prior to exiting Unerase.



For Mode 4, TYPE is the default option. The drive used for Mode 1 is the first drive in the current search sequence. Normally, this will be the S drive.



Restrictions



To view or unerase an erased file you must be logged onto the same account that owned the file prior to the file being erased.



UnErase



707



 For Mode 3, you must be logged on to the SYSTEM account and have a privilege level of 5. When Mode 2 or Mode 4 is used, the UnErase command displays the user interface form. This form allows you to view the files that are in the recycle bin for a drive and selectively restore them, delete them or clear the entire recycle bin.



Commands



User Interface



At the bottom of the form is the information about the file that is currently highlighted in the list box above. The “Path” refers to the original location of the file which is also the location that the file would be restored to. Restore



Selecting this button restores or “unerases” the file highlighted in the list box to the left.



Delete



This button will delete the hightlighted file from the recycle bin. Once a file is deleted this way it cannot be restored or unerased. Before the highlighted file is actually removed, you are asked to confirm your request:



708 UnErase



 You can control the sequence of the recycle bin files displayed in the list box. The choices are: Name sequence Orders the deleted file names by their file



name. Path sequence Orders the deleted files by their original path



location. Within path, the names are ordered by their file name. Date ascending Orders the deleted files by the date and time



that they were erased, in ascending sequence. Date descending Orders the deleted files by the date and time



that they were erased, in descending sequence. Size Ascending Orders the deleted files by the file size, in



ascending sequence. Size Descending Orders the deleted files by the file size, in



descending sequence. Clear



See also



This button allows you to clear or delete all of the files in the recycle bin. Because this operation cannot be reversed, you are asked to confirm your request before the files are permanently removed from the recycle bin.



Erase, FileManager, RmDir



UnErase



709



Commands



Sequence



 Commands



710 UnErase



 UnInstall Command The UnInstall command removes all of the files associated with an installed product.



UNINSTALL If there are any products registered with an uninstall control file a menu displays allowing you to select the product that you want to uninstall:



Select the product by moving the highlight bar to the desired item and then either click on the “Remove” button or use the (TabÌ¢) key to move to the “Remove” button and press (EnterÌ˛). All of the files listed in the uninstall control file for the selected item are removed from the system, the uninstall control file for that item is removed and the item is removed from the menu. Control returns to the menu and you may select another product to uninstall or use the “Exit” button to exit the Uninstall command. Notes



The uninstall control files reside in the directory /THEOS/UNINSTALL:S. Only files listed in the uninstall control file for the selected product are erased. Sometimes the control file does not list all of the files. For instance, it is common for a product’s control file to not include the configuration file for the product. In this situation the configuration file is not erased. This is UnInstall



711



Commands



Operation



 Commands



convenient if you need to reinstall the product at a later time. After reinstallation, the prior configuration file is still there and will be used again. Some products require other products to operate. For instance, a networking product like THEO+Mail requires TCPIP networking to be installed on the system. If you uninstall a product that has other products dependent upon it, those other products are removed at the same time. For instance, uninstalling “THEOS TCP/IP Networking” causes all of the other products that depend upon networking to also be uninstalled. Cautions



All of the files registered in the uninstall control file for a product are erased from the system. There is no backup copy of these files made.



Restrictions



The Uninstall command can only remove files for a product that created an uninstall control file for the product when it was installed on the system.



See also



Install



712 UnInstall



 Unique Command Filter Unique copies standard input to standard output, or copies one file to another, omitting any



duplicated lines.



UNIQUE



infile outfile ( options



2



UNIQUE



infile ( options



3



UNIQUE



( options



infile



»



file name with optional path



outfile



»



file name with optional path



options



»



COUNT DUP UNIQUE +nnn



Commands



1



nnn The examples used in the descriptions that follow use an input file containing: >list sample.file The The The The And The The



Operation



1st line. 2nd line. 2nd line. 2nd line. the third line. last line. last line.



Mode 1—Each line in infile is examined and compared to the previous line. If it is different than the prior line, it is written to outfile. >unique sample.file The 1st line. The 2nd line. And the third line. The last line.



Mode 2—This mode is identical to Mode 1 except that the output is written to the standard output device. >unique sample.file > unique.lines



Unique 713



 Mode 3—This mode is normally used in a pipe command-line because the input file comes from the standard input device and the output is written to the standard output device. COUNT



Commands



Options



Each line in the file is output preceded by a count of the number of consecutive instances of the line. The duplicated instances of a line are not output. >unique sample.file (count 1 The 1st line. 3 The 2nd line. 1 And the third line. 2 The last line.



Option COUNT cannot be used in combination with the DUP or UNIQUE options. DUP



The UNIQUE command outputs only one copy of each duplicated line in the file. All unique lines in the input file are not copied to the output file. >unique sample.file (dup The 2nd line. The last line.



UNIQUE



This option causes the Unique command to output only the unique lines in the file. That is, only the lines that have no duplicate lines. >unique sample.file The 1st line. The 2nd line. And the third line. The last line. >unique sample.file (unique The 1st line. And the third line.



+nnn



With this option the first nnn characters of each line are not used when testing for duplicate lines. >unique sample.file (+7 The 1st line. And the third line. The last line.



714 Unique



 nnn



Specifies that the first nnn fields of each line are not used when testing for duplicate lines. A field is identified by a tab character or a space character. >unique sample.file (2 count 4 The 1st line. 1 And the third line. 2 The last line.



An infile or outfile specification can omit the file type if the environment variable FILETYPE is defined. For more information about the FILETYPE variable, see “Environment Variables” on page 111.



Restrictions



infile must be a stream file.



See also



List, Sort



Unique 715



Commands



Notes



 Commands



716 Unique



 Unload Command The Unload command unloads a program or data file from memory.



program



program



»



Commands



UNLOAD



name of program or file to load into memory



Operation



The program or data file is unloaded from memory.



Notes



If program is not currently loaded into memory, no message displays. If program is in memory but was not loaded during system startup or by Load, it is not unloaded by this command and no message displays.



Restrictions



The Unload command requires a privilege level of five. You may only Unload a program or data file from memory if it was loaded with Load or during system startup. If program is in use by another user, it is not unloaded at this time. However, its “use count” is decremented so when the other user finishes using the program it will be unloaded at that time.



See also



Load, Sysgen



Unload



717



 Commands



718 Unload



 Unnumber Command Filter Unnumber copies a file to the standard output device, removing any line number from each line as it is copied.



UNNUMBER



2



UNNUMBER



file Operation



file...



»



Commands



1



file name with optional path



Mode 1—Each file is copied to the standard output device and unnumbered as it is copied. Specifying multiple files causes the second and remaining files to be appended to the first file copied to the standard output device. >unnumber program1.basic ! Program: JULIAN Compute Julian date ! Programmer: Jane Doe OPTION VERSION 1.1,"Copyright 2001 by ABC Software." IF CMDARG$(1)="" GOSUB COMPUTE.JULIAN ELSE GOSUB COMPUTE.DATE IFEND ... >unnumber program1.basic program2.basic ! Program: JULIAN Compute Julian date ! Programmer: Jane Doe OPTION VERSION 1.1,"Copyright 2001 by ABC Software." IF CMDARG$(1)="" ... ! Program2: Compute late charge. INPUT "beginning balance",AMOUNT INPUT "month number",M% CUR.MONTH% = VAL(LEFT$(DATE$(0),2)) TOT.TOT.INT = TOT.TOT.INT+TOT.INT



This command is frequently used in a pipe: >unnumber numbered.text | tee some.text | more



Mode 2—Copies the file from the standard input device to the standard output device, unnumbering each line as it is copied. Notes



A line is considered numbered if the first non-space character is a digit. A line is unnumbered by removing all leading spaces and digits. If the resulting line is blank, it is not output.



Unnumber



719



 When a line contains multiple “line numbers,” only the first line number is removed. For instance: 10 10 This is line number 10.



The above line is unnumbered to: Commands



10 This is line number 10.



Restrictions



file must be a stream file. Compressed or encoded files, such as those used by MultiUser BASIC, cannot be unnumbered with this command.



See also



720 Unnumber



Number



 UnZip Command This command lists, tests or extracts compressed files from a ZIP archive.



UNZIP



zipfile



2



UNZIP



-options



zipfile



3



UNZIP



-options



zipfile



filelist



zipfile



»



Source of archived files



options



»



Options applied during extraction or list



filelist



»



List of file names to extract



Operation



Commands



1



Mode 1—The files in the zipfile are restored into the current working directory. >unzip cdrom Archive: CDROM.zip inflating: diskette.img inflating: theos.img inflating: pluspak.exc inflating: pluspak.instcmp



Because no options are used with this mode, the files are attempted to be restored whether they exist or not. If a file already exists in the destination directory you are asked: replace



filename?



[y]es, [n]o, [All], [N]one, [r]ename:



When this occurs you must respond with a (Y), (N), (Shift)+(A), (Shift)+(N) or (R). If an archived file name has a path specified, it is restored to that path of the destination disk. If the path is relative (does not start with a “/”) then it is restored to that path relative to the current working directory. If the path does not exist, it is created. These actions can be controlled by specifying options. Mode 2—The files in the zipfile archive are restored according to the options specified. Mode 3—The files specified in filelist are extracted from the zipfile archive according to the options specified.



UnZip



721



 Commands



Options



The following options may be combined into a single specification. For instance, to request quiet mode (-q) and replace mode (-o) you would specify -qo. -f



Similiar to the NEWER option of the CopyFile command, this option causes UnZip to only attempt to restore a file if the file does not exist in the destination directory of if the archived version of the file is newer than the existing version of the file in the destination directory.



-h



Display help text.



-j



Ignore the paths specified in the zipfile and restore the file into the current working directory.



-l



List the files in the archive. Compare with the -v option. >unzip -l cdrom Archive: CDROM.zip Length Date ----------1474560 02-16-02 26214400 02-16-02 748 01-30-02 3876 02-16-02 -------27693584



Time ---10:50 10:51 15:29 10:48



Name ---diskette.img theos.img pluspak.exc pluspak.instcmp ------4 files



-n



Similar to the NEWFILE option of the CopyFile command, files in the archive are only restored if the file does not exist in the destination directory.



-o



Equivalent to the REPLACE and NOQUERY option used by other THEOS commands, Any existing files are replaced if they have the same name as a file that is being exploded. You are not asked if you want to explode the archive file.



-p



This option causes UnZip to expand the contents of the archived files to stdout. Normally, this is a pipe to another command and is normally only useful when the archived files are plain text files. >unzip -p myfiles | list



In the above example, the contents of MYFILES.ZIP is displayed on the console by the List command.



722 UnZip



 -q



Quiet mode. This is the equivalent of the NOTYPE option used by other THEOS commands. >unzip -tq cdrom.zip No errors detected in compressed data of CDROM.ZIP.



-t



Test the zipfile by verifying the readability of the archive and by checking the integrity of each file in the archive.



Archive: CDROM.ZIP testing: diskette.img testing: theos.img testing: pluspak.exc testing: pluspak.instcmp No errors detected in compressed data



OK OK OK OK of CDROM.ZIP.



-u



Similiar to the NEWER option of the CopyFile command, this option causes UnZip to only attempt to restore a file if the file does not exist in the destination directory of if the archived version of the file is newer than the existing version of the file in the destination directory. Compare with the -f option, which only restores if the file exists and is older.



-v



Display the zipfile directory in verbose mode. Compare to the -Z option display. >unzip -v cdrom Archive: CDROM.zip Length Method Size Ratio Date Time CRC-32 Name -------- ------ ------- ----------- ------- ---1474560 Defl:N 1277225 13% 02-16-02 10:50 76c9056f diskette.img 26214400 Defl:N 21782773 17% 02-16-02 10:51 b480088c theos.img 748 Defl:N 396 47% 01-30-02 15:29 ad55cfc6 pluspak.exc 3876 Defl:N 1435 63% 02-16-02 10:48 a8b548b9 pluspak.instcmp -------------- --------27693584 23061829 17% 4 files



-z



Display the archive file name. >unzip -z foo Archive: FOO.zip



UnZip



723



Commands



>unzip -t cdrom.zip



 -Z



Display the zip file directory. Compare to the -v option. >unzip "-Z" cdrom Archive: CDROM.zip 23062393 bytes 4 files S.M...... 2.3 ths 1474560 bx defN 16-Feb-02 S.M...... 2.3 ths 26214400 bx defN 16-Feb-02 S........ 2.3 ths 748 tx defN 30-Jan-02 S.MW..... 2.3 ths 3876 bx defN 16-Feb-02 4 files, 27693584 bytes uncompressed, 23061829



10:50 10:51 15:29 10:48 bytes



diskette.img theos.img pluspak.exc pluspak.instcmp compressed: 16.7%



Commands



This option allows you to use additional options that are specific to this listing: -1



Display the file names only. >unzip -Z -1 cdrom diskette.img theos.img pluspak.exc pluspak.instcmp



-2



Display the file names only but allow and display other information if the -h, -t or -z sub-option is specified. >unzip -Z -2h cdrom Archive: CDROM.zip diskette.img theos.img pluspak.exc pluspak.instcmp



23062393 bytes



4 files



>unzip -Z -2ht cdrom Archive: CDROM.zip 23062393 bytes 4 files diskette.img theos.img pluspak.exc pluspak.instcmp 4 files, 27693584 bytes uncompressed, 23061829 bytes compressed: 16.7% -h



Display heading line. >unzip -Z -h cdrom Archive: CDROM.zip



-l



724 UnZip



23062393 bytes



4 files



Display the zip file directory in Unix “ls -l” long format. This display is identical to the plain -Z display. Compare with the -m and -s sub-option displays.



 -m Display the zip file directory in Unix “ls -l” medium format. >unzip -Z -m cdrom Archive: CDROM.zip 23062393 bytes 4 files S.M...... 2.3 ths 1474560 bx 13% defN 16-Feb-02 10:50 diskette.img S.M...... 2.3 ths 26214400 bx 17% defN 16-Feb-02 10:51 theos.img S........ 2.3 ths 748 tx 47% defN 30-Jan-02 15:29 pluspak.exc S.MW..... 2.3 ths 3876 bx 63% defN 16-Feb-02 10:48 pluspak.instcmp 4 files, 27693584 bytes uncompressed, 23061829 bytes compressed: 16.7%



Display the zip file directory in Unix “ls -l” short format. >unzip -Z -s cdrom Archive: CDROM.zip 23062393 bytes 4 files S.M...... 2.3 ths 1474560 bx defN 16-Feb-02 S.M...... 2.3 ths 26214400 bx defN 16-Feb-02 S........ 2.3 ths 748 tx defN 30-Jan-02 S.MW..... 2.3 ths 3876 bx defN 16-Feb-02 4 files, 27693584 bytes uncompressed, 23061829



-t



10:50 10:51 15:29 10:48 bytes



diskette.img theos.img pluspak.exc pluspak.instcmp compressed: 16.7%



Display the totals line. >unzip -Z -t cdrom 4 files, 27693584 bytes uncompressed, 23061829 bytes compressed:



16.7%



-T



Display the date/time information of each listing line in a sortable format. That is, the date/time is formatted as: yyyymmdd.hhmmss.



-v



Display the directory in verbose, multi-page mode. >unzip -Z -v cdrom pluspak.instcmp offset of local header from start of archive: bytes file system or operating system of origin: version of encoding software: minimum file system compatibility required: minimum software version required to extract: compression method: compression sub-type (deflation): file security status: extended local header: file last modified on (DOS date/time): 32-bit CRC value (hex): compressed size: uncompressed size: length of filename: length of extra field: length of file comment: disk number on which file begins: apparent file type: Theos file attributes (87FD hex): MS-DOS file attributes (00 hex):



23060570 (015FE05Ah) Theos 2.3 MS-DOS, OS/2 or NT FAT 2.0 deflated normal not encrypted no 2002 Feb 16 10:48:24 a8b548b9 1435 bytes 3876 bytes 15 characters 18 bytes 0 characters disk 1 binary Sequential .MW..... none



The central-directory extra field contains: - A subfield with ID 0x6854 (Theos) and 14 data bytes: 00 24 0f 00 00 10 00 00 00 00 00 e0 00 00. There is no file comment.



-z



Display the zipfile comment, if any.



UnZip



725



Commands



-s



 Commands



Notes



This program, and the Zip program, are implementations of the UnZip and Zip programs from Info-ZIP. Info-ZIP provides free, portable, high-quality versions of the Zip and UnZip compressor-archiver utilities that are compatible with the DOS-based PKZIP by PKWARE, Inc. This version is available for most other operating system platforms. Information about Info-ZIP may be found on the Internet at http://www.info-zip.org/.



See also



Zip



726 UnZip



 Upcase Command Filter Upcase copies a file to the standard output device, converting all letters to uppercase. Upcase can also change the names of files or library members to uppercase-only characters.



1



UPCASE



2



UPCASE



3



UPCASE



directory



4



UPCASE



library



Commands



file



file



»



file name with optional path; wild cards are not allowed



directory



»



path to file names



library



»



library name of member files



Command synonym: Operation



UC



Mode 1—file is copied to the standard output device with all lowercase letters converted to uppercase. The original file is unchanged. >upcase /theos/config/crt.cfg SCREENSAVER=0 YESSCANCODE=0X15 NOSCANCODE=0X31 RESETLITERAL=OK TO REBOOT? (Y/N) MOUSE=0 INTELLIMOUSE=FALSE KEYPADMODE=TRUE REPEATRATE=30 ... >upcase /theos/config/crt.cfg > crt.config



Mode 2—Copies standard input to standard output, converting all lowercase letters to uppercase. This form is normally used only in a pipe. However, if standard input is the console, records are copied until a (Ctrl)+(D) is encountered, signaling the end of the input file. >filelist *.* | upcase > file.list



Upcase



727



 Mode 3—All of the file names in directory are converted to use uppercaseonly characters. Files in subdirectories of directory and members of libraries in directory are not renamed. This mode of Upcase is not a filter.



Commands



>upcase myfiles /MYFILES/address.basic:S /MYFILES/browscap.basic:S /MYFILES/ctr.basic:S /MYFILES/cust1.basic:S /MYFILES/custbrws.basic:S /MYFILES/custjs.basic:S /MYFILES/customer.basic:S /MYFILES/mainmenu.basic:S /MYFILES/testit.basic:S



Only file names that are converted are displayed. Mode 4—All of the members of library are renamed to use uppercase-only characters. This mode of Upcase is not a filter. >upcase example.library /EXAMPLE.LIBRARY.customer:T /EXAMPLE.LIBRARY.cust1:T /EXAMPLE.LIBRARY.custjs:T



Only member names that are converted are displayed. Notes



The command name UC is a synonym to the Upcase command. It is not a separate program but only an entry in the /THEOS/OS/MESSAGE/language/ SYNONYM.TXT file. If standard synonyms are disabled (see “Account” on page 13 and “STDSYN” on page 110), this synonym name may not be allowed. Mode 3 and Mode 4 of the Upcase command are useful when you need to



ensure that the file names are usable when accessed by an operating system that does not recognize lowercase file names. Restrictions



file must be a stream file.



See also



Lowcase



728 Upcase



 Viewer Command The Viewer command displays and allows you to browse the contents of text files.



VIEWER file... ( options »



file name with optional path; may contain wild cards



options



»



FILES MAXIMIZE



Operation



NUMBER TITLE



WINDOW



The requested file is opened and displayed in a Viewer form: >view colors.basic



While viewing the file you can browse the contents with the normal navigation keys of (˜), (¤), (˚), (˙), (Home), (End), (PageUp) and (PageDown). To terminate viewing of a file press the (Esc) or (F9) key. If multiple files were specified on the command line then the current file is closed and the next file is viewed. Use (Break),(Q) to terminate viewing of the current file and to exit the Viewer command.



Viewer 729



Commands



file



 Options



FILES



Indicates that file is an ASCII stream file with each record in the file specifying a single file name. The file name specifications in this file may include the path and wild cards.



Commands



The SELECTED.FILES and SELECTED.EXEC files created by FileList and FileManager and the FOUND.EXEC created by Look and FileManager can be used for this specification file (see “The EXEC and FILES Options” on page 239). You may also create the file with an editor or application program. For instance, FileList is used to create a list of files to be examined: >filelist *.data:a (exec >filelist a not *.data:a (10/1/01 exec append



A SELECTED.EXEC file now exists that lists all of the “data” files and all files that have been changed since 10/01/2001. The following command lists these files: >viewer selected.exec (file



MAXIMIZE



The Viewer form is displayed in its maximum size.



NUMBER



Each line of the text file is numbered.



TITLE



Allows you to specify the title for the Viewer form. If this option is not used the title is set to the name of the file being viewed. When the TITLE option is used, the title text is specified immediately following the TITLE keyword. The title text should be enclosed within quotation mark characters.



730 Viewer



 >view selected.files (title "List of files to view"



Commands



WINDOW



This option allows you to specify the initial Viewer form position and size. When the option is not used the Viewer form’s initial position and size comes from the VIEWER.CFG file in Users and Configuration Files directory. To use the WINDOW option, follow the WINDOW keyword with the col, row, width and height values desired, in that sequence. >viewer somefile.txt (window 3 5 70 10



The above command specifies that the Viewer form is positioned with its upper-left corner at column 3, line 5 and it has a width of 70 characters and a height of 10 lines. Notes



This command uses a standard form and objects. Refer to Chapter 11 “Sessions, Forms and Objects” in the THEOS Corona Version 5 Operating



System Reference manual for information about manipulating the form’s size and position. The Viewer form’s initial position and size is comes from the VIEWER.CFG file in Users and Configuration Files directory. Any change in this position and size made during its operation is saved in that file for subsequent usage of the Viewer command with your UserName. The text file(s) are viewed in read-only mode. Although you can type characters into the viewer display, no change is made to the actual text file.



Viewer 731



 You may print the file that you are viewing by pressing the (F8) key while it is displayed. When this is done you are presented with a form allowing you to select the printer that you want to use for the printing.



HTM Files



The viewer command can display and navigate files encoded with HTML tags and hyperlinks. However, the TBrowse is better suited to this task.



Defaults



The default TITLE is the name of the file being viewed. The default WINDOW size and position is the saved values in the /THEOS/USERS/username/VIEWER.CFG:S file.



Restrictions



Only stream files can be viewed with this command. Only ASCII text files will display the contents meaningfully.



See also



Img, List, More, TBrowse, WinWrite



Commands



Printing Files



732 Viewer



 VNC Client Command The VNC command is the client portion of a VNC client/server protocol. It allows you to be a “Virtual Network Console” to another system on the network that is running a VNC server.



VNC



host Operation



host »



Commands



1



IP address or name of machine running VNC server



When VNC is executed you may provide the VNC server host IP address or name on the command-line. If you do not then you are asked to supply it:



After connecting to a server, that server’s IP name or address is remembered and will be used by default the next time that VNC is invoked. When you do supply the host name or address on the command line you are not asked to supply it with the above form nor are you allowed to change the options which are only accessible by selecting the Options button in that form. (See “Options” on page 735.) Most VNC servers require a password to connect to the server. If a password is required you will be asked:



Remember that passwords are case-sensitive.



VNC Client



733



 Commands



After a valid password is entered and accepted by the server the connection is completed and the desktop of the server is displayed on this console.



The above display is a VNC connection to a Windows VNC server. The resolution of the actual display is much better than shown here because of scaling and printing limitations. If you have not checked the View (inputs ignored) option then mouse and keyboard actions performed in this session of THEOS will be communicated to and will control the remote desktop. To exit from VNC use the (Break),(Q) sequence.



734 VNC Client



 Options



Options for the VNC client may be set by invoking VNC without specifying a host on the command line and then selecting the Options button in the connection form.



Commands



Preferred encoding. This set of options determine how this client handles the graphical data transmitted. Check one of the following encodings and this client will request that type of encoding from the server. The default Hextile is potentially the most efficient in transmission bandwidth. Hextile



Hextile is a variation on the CoRRE encoding. Rectangles are split up into 16x16 tiles, allowing the dimensions of the subrectangles to be specified in 4 bits each, 16 bits in total.



CoRRE



CoRRE is a variant of RRE, where it is guaranteed that the largest rectangle sent is no more than 255x255 pixels. A server which wants to send a rectangle larger than this simply splits it up and sends several smaller RFB rectangles. Within each of these smaller rectangles, a single byte can then be used to represent the dimensions of the subrectangles. For a typical desktop, this results in better compression than RRE.



RRE



RRE stands for rise-and-run-length encoding and is essentially a two-dimensional analogue of run-length encoding.



Raw



This is the simplest encoding of pixel data. With it, data consists of n pixel values where n is the width times the height of the rectangle.



Allow CopyRect encoding The copy rectangle encoding is a very simple and



efficient encoding which can be used when the client already has the same pixel data elsewhere in its framebuffer. You should always enable this option to optimize data transfer if and when possible.



VNC Client



735



 Misc. Miscellaneous options. Request shared session Normally, when you establish a VNC connection



Commands



to a remote server, any existing VNC connections to that server are terminated allowing you to be the only VNC on that server. By enabling this option, existing connections on the server are not terminated. Deiconify on Bell Disable clipboard transfer Clipboard changes caused by cutting or copying



at either the viewer or server end are normally transmitted to the other end. This option disables clipboard transfers. Mouse. The following options control how the mouse on the local console is interpreted and used by the remote host desktop. Emulate 3 Buttons This option allows a two-button mouse to emulate a



middle button by pressing both buttons at once. Swap mouse buttons 2 and 3 Normally the mouse buttons left-middle-right



are mapped on to buttons 1,2,3. This option causes them to be mapped onto buttons 1,3,2, which may be more useful for twobutton users who only have left and right mouse buttons because they will then get buttons 1 & 2 instead of 1 & 3. If combined with 3-button emulation, this also causes the middle button to emulate button 3 instead of button 2. Display. These options control how the VNC viewer displays the desktop of the remote host system. Restrict pixels to 8-bit The VNC client normally accepts whatever pixel for-



mat the server offers. This option requests 8-bit true-color pixels from the server, which reduces network traffic. View (inputs ignored) Checking this item prevents you from actually con-



trolling the remote host. Instead, you are allowed view-only access. Full-screen mode This option is useful if the local screen is smaller than



the remote host desktop. When not enabled, the larger desktop is displayed on the local screen with scroll bars on the right and bottom edges of the display. To view the portions that are not displayed you must use the mouse to drag the scroll bar buttons in the direction desired. With the Full-screen mode option enabled, the scroll bars are not displayed. Instead, moving the mouse to the edge of the



736 VNC Client



 screen causes the display to shift its viewing “window” of the desktop in that direction. Notes



This VNC client is based upon program code that is copyrighted by AT&T Laboratories Cambridge and is used under the conditions of the GNU General Public License. is a trademark of AT&T Labs-Cambridge Ltd.



Cautions



The normal cautions apply when accessing a computer that is remote to yourself. Since you cannot physically see the computer and you may not have physical access to the computer, do not perform opertions such as clearing diskettes, tapes, etc. or printing on any of the printers unless you are sure of the media loaded in the drive or printer.



Restrictions



The VNC client may only be used on a VGA display configured for graphics mode.



See also



NetTerm



VNC Client



737



Commands



The VNC logo



 Commands



738 VNC Client



 WhereIs Command This command searches the directory tree of the current account looking for all instances of a file name.



file... ( options



file



»



file name with optional path; may contain wild cards



options



»



date1 date2



Operation



Starting with the root directory of the current account, a search is made for all files that match file. If file specifies a path, the search starts at that path. All subdirectories subordinate to the starting search directory are examined. >tree / / data abc doc programs files programs Programs Backups doc Special



>whereis backups.c



As shown above, when a file is found that matches file, the complete path to the file is displayed and you are asked: “Continue searching?” You may select the Yes, No or Go buttons.



WhereIs 739



Commands



WHEREIS



 Selecting the Yes button means that you want to continue the search; the No button means that you do not want to continue searching and you want to exit WhereIs without changing anything.



Commands



Selecting the Go button means that you want to discontinue the search and that you want to set your current working directory to the path of the file found. Options



date1



Includes a file only if the file’s last change date is greater than or equal to this date. That is, if the file was changed on or after this date. This option may be used with the date2 option. >whereis *.*:s f (10/15/01



The above command will include in the search only those files that have been created or changed since October 14, 2001. date2



Includes a file only if the file’s last change date is less than or equal to this date. That is, if the file was changed on or before this date. May only be specified by first specifying the date1 option. >whereis *.*:s f (10/15/01 10/30/01



This command includes only those files that have been created or changed since October 14, 2001, but not any files that were created or changed after October 30, 2001. To specify a date2 when you don’t care about date1, use a date of 1/1/86 for the date1 option. This is the earliest date maintained by the THEOS file system. >whereis *.*:s f (1/1/86 11/20/01



Here, since the date1 specification is 1/1/86, only files created or changed prior to November 21, 2001, are included. Defaults



Unless a path is specified with file, the search starts with the root directory of the current account.



Restrictions



You may only search for files in the current account.



See also



ChDir, FileManager



740 WhereIs



 Which Command The Which command displays the complete path to a program. It searches in the current directory and in the standard locations for programs.



file Operation



»



Commands



WHICH file ... program name with optional file-type



Search for each of the files specified in the standard program locations including any defined PATH and user command libraries. This is the same search locations and search sequence used when file is executed as specified. As soon as a program file is found matching file its complete path is displayed. >which fileman SYSTEM\Programs/FileManager/FileMan.cmd:s >which fm makeimg SYSTEM\Programs/FileManager/FileMan.cmd:s /Theos/Command/MAKEIMG.EXC:S



Notes



The primary purpose of the Which command is to find the location of a program when there are multiple files with the same name. For instance, there may be files in the current account and directory named MYPROG.COMMAND, MYPROG.CMD, MYPROG.EXEC and there may be a file in the SYSTEM account named /THEOS/COMMANDS/M YPROG.CMD. When you enter the command name MYPROG on the command line you may wonder why it keeps executing a program that you did not expect or executes a different program depending upon what the current working directory is. The Which command will report the location and name of the program that is executed when the path and/or file extension is not specified.



See also



FileList, FileManager, Find, WhereIs



Which



741



 Commands



742 Which



 Who Command WhoAmI Command EXEC The Who command displays all started user processs and who is logged onto them. The WhoAmI command displays which account you are logged onto and other information about yourself.



WHO



2



WHO AM I



3



WHOAMI



Operation



Commands



1



Mode 1—The Who command shows all processs that have been started with consoles attached. For instance, the processs used by the print spooler, disk cache and network server programs are not displayed. >who



Mode 2—The Who Am I command displays the following information about yourself: Account Name: Account Number: User Name: Logon Date: Pid: Console: Description: Workgroup: Server Name: Server Address: Client Name:



SYSTEM 0 Myname 10 April 2002, 09:52 AM 10 NET1 C210,L80,P24,REMOTE=JUPITER Primary Corona system ACCOUNTING Saturn 192.168.1.100 JUPITER



Who



743



 Client Address: 192.168.1.104



Commands



The above information was produced when the user was using a network client as a user to the THEOS system. Mode 3—This mode is synonymous with Mode 2. It is actually an EXEC language program that invokes the Who Am I command. You could modify this EXEC program to supply other information if you choose. Notes



On non-graphic consoles, if the environment variable LINEGRAPH is defined to be “N,” the line graphics are suppressed. For instance: >who 1 SYSTEM 2 SYSTEM 3 SAMPLES 4 SYSTEM 5 SYSTEM 6 16 PRIVATE >



See also



744 WhoAmI



Show



HELP CSI CSI CSI CSI LOGON WHO



CRT1:1 CRT1:2 CRT1:3 CRT1:4 CRT1:5 CRT1:8 NET1



C90,L80,P29 C90,L80,P29 C90,L80,P33 C90,L80,P29 C90,L80,P33 C90,L80,P24 C210,L80,P28,REMOTE=DocSystem



 WhoIs Command Queries the Internet domain database regarding registered domain name and users.



WHOIS



domain



2



WHOIS



"user"



3



WHOIS



#handle



Commands



1



domain



»



second-level domain name



user



»



user name in form of “last-name, first-name”



handle



»



user handle



Operation



Mode 1—Issues a request to the Internet domain database to get the registered information about a second-level domain name. >whois theos-software.com Registrant: Theos Software (THEOS-SOFTWARE-DOM) 1801 Oakland Blvd, Suite 315 Walnut Creek, CA 94596 US Domain Name: THEOS-SOFTWARE.COM Administrative Contact, Technical Contact: THEOS Host Master (YGTAWDHKBO) [email protected] THEOS Software Corporation 1801 Oakland Blvd; Suite 315 Walnut Creek, CA 94596 USA 925 935-1118 Record expires on 13-Oct-2002. Record created on 12-Oct-1995. Database last updated on 10-Jul-2002 18:57:57 EDT. Domain servers in listed order: DNS1.THEOS-SOFTWARE.COM DNS2.THEOS-SOFTWARE.COM NS1.ALGX.NET NS2.ALGX.NET



65.45.113.228 65.45.113.229 216.99.225.30 216.99.225.31



WhoIs 745



 Mode 2—Issues a request to the Internet domain database to get the registered information about a user contact. Note that, in the Mode 1 example, the administrative contact is “THEOS Hostmaster:” >whois "THEOS Hostmaster"



Commands



No match for "THEOS HOSTMASTER"



Not all registrars support a query by contact name. Mode 3—Issues a request to the Internet domain database to get the registered information about a user handle. Note that, in the Mode 1 example, the administrative contact has a handle of YGTAWDHKBO: >whois #ygtawdhkbo THEOS Host Master (YGTAWDHKBO) [email protected] THEOS Software Corporation 1801 Oakland Blvd; Suite 315 Walnut Creek, CA 94596 USA 925 935-1118 Database last updated on 10-Jul-2002 20:00:57 EDT.



Not all registrars with a WhoIs server support the querying of contact handles. Notes



Although all second-level domains are registered, only the responsible parties to those domains are registered by name and handle. The format and content of the registration database may vary depending upon the administrator for the first-level domain of the requested domain.



See also



746 WhoIs



NsLookup



 Window Management Commands These 18 commands are primarily used by EXEC language programs to provide window and session management control.



mode



2 wClear



window char



3 wClip



window clip



4 wClose



window



5 wClose



ALL



6 wColor



window Fg Bg Rfg Rbg



Commands



1 wBypass



7 wFinish 8 wFrame



window frame shadow attribute



9 wInvert



window invert



10 wMenu



Count Col Row Title Invert Invert Color Fg Bg Rfg Rbg KEEP window HOT



11 wMove



window col row



12 wMsgBox



title message type ( WAIT seconds



13 wMsgBox



icon title message type ( WAIT seconds



14 wOpen



window col row columns rows



15 wRefresh



window



16 wRemove



window



17 wRestore



window file



18 wSave



window file



19 wSelect



window update display



20 wStat 21 wStat



window



22 wStat



?



23 wStat



? window field



24 wSwitch



switch



25 wSwitch



session



26 wTitle



window title top-bottom align attribute



747



 Commands



748



align



»



LEFT CENTER RIGHT



attribute



»



bg



»



char clip



» »



bit-mapped color and attributes fg bg background color code or name (black, blue, green, cyan, red, magenta, yellow and white) character or character value



col columns count display



» » » »



leftmost column number width of window (1–255) number of items in menu list



fg



»



file frame



» »



foreground color code or name (black, blue, green, cyan, red, magenta, yellow and white) file name with optional path



invert



»



OFF ON



mode



»



OFF ON



row rows session shadow



» » » »



topmost row number height of window (1–255) session number (1–8)



switch



»



OFF ON



title top-bottom



» »



text for window title



update



»



OFF ON



window



»



window number



OFF ON



TOP HIDDEN



NONE SINGLE DOUBLE RAISED SUNKEN



NONE LEFT RIGHT



BOTTOM TOP



 wBypass



The wBypass command enables or disables the window manager’s bypass mode. >wbypass off



>wbypass on



When window manager bypass mode is enabled, characters sent to the console are not intercepted by window manager. The character is displayed immediately on the console and it is not saved in any window in memory. Invoking wBypass with no parameter displays the current window manager bypass mode. >wbypass Bypass mode is not set



wClear



The wClear command clears the interior of an open window to a specified character or to spaces. >wclear 5 >wclear 8 176



The first command clears window five to spaces. The second clears window eight, filling it with the “stipple pattern” character. Refer to Appendix G: “THEOS Character Sets,” starting on page 265 of the THEOS Corona Version 5 Operating System Reference manual for a list of characters supported by THEOS. The window must be selected or refreshed to see the effects of this command. wClip



The wClip command changes the text clip attribute of a window. The clip attribute of a window controls whether text is truncated (clipped) or wrapped when it flows beyond the right edge of the window. The initial or default clip attribute is ON, meaning that text is truncated.



749



Commands



Normally, window manager bypass mode is off, meaning that all characters sent to the console are intercepted and processed by the window manager. Window manager saves the character and its attributes in the appropriate window in memory and transmits the character to the console if the window is selected and its update status is enabled.



 wClose



The wClose command closes and removes the specified window. If that window is the active window, then the next lower window is selected as the active window.



Commands



>wclose 4



The wClose ALL command selects window zero and then closes and removes all other open windows. >wclose all



wColor



Change the interior colors of an open window. The window does not have to be the active window. The display of the window might not be updated immediately, unless it is selected with update on. The colors may be specified with color numbers or with the the color name. Color names must be completely spelled out. Code



Name



Code



Name



0



Black



4



Red



1



Blue



5



Magenta



2



Green



6



Yellow



3



Cyan



7



White



wFinish



The wFinish command is synonymous with a wClose ALL command. It selects window zero and closes and removes all other windows.



wFrame



The wFrame command changes an existing window’s frame and shadow style. The window’s frame and shadow are set to the indicated styles with the requested colors and attributes. >wframe 3 single right >wframe 4 double none white red >wframe 30 single right 0x70



Both frame and shadow must be specified but the attribute or color of the frame can be omitted, in which case it is left unchanged. For a description of the attribute specification, refer to “Frame & Title Attributes” on page 151 of the THEOS Corona Version 5 Operating System Reference manual. The changed frame and shadow styles and attributes are not displayed until the window is selected or refreshed, unless it is the current window.



750



 wInvert



The wInvert command changes the normal video/reverse video status of the indicated window. Although this command can be used on color or monochrome displays, it is only effective on monochrome displays. Windows should be defined with color attributes and invert attributes. The color attributes are ignored on monochrome displays and the invert attributes are ignored on the color displays.



>winvert 23 off



The initial or default invert mode for a window depends upon its window number. Odd numbered windows default to invert ON, even numbered windows default to invert OFF. wMenu



The wMenu command can only be used in an EXEC program because it requires the menu item text to be placed in the EXEC program’s stack (&BEGSTACK or &STACK statements) before executing the command. This command displays a menu or choice list on the screen and lets the operator select one of the items. The count, col and row parameters must be supplied but the other fields are optional. &begstack Item 1 Item 2 Item 3 &end wmenu 3 5 10 Item 1 Item 2 Item 3



Blank items in the list of menu choices display as a horizontal line. For instance: &begstack Item 1 Item 2 Item 3 Last Item &end wmenu 5 5 10



751



Commands



>winvert 14 on



 Item 1 Item 2 Item 3 Last Item



Commands



The window used by wMenu is always double-line framed and has a drop shadow on the right, space permitting. col and row specify the upper-left corner of the interior of the window. The width and height of the menu depend upon the items displayed. The width of the window is the larger of the longest item in the list and the length of the menu title. The height of the window is the smaller of the remaining screen depth minus 4 and count. When the window height is less than count, a scroll bar is displayed on the right side of the menu frame. INVERT Parameter. Use this parameter if the EXEC program may be used on a monochrome display. It has the same effect on the menu window as the wInvert command has on user-defined windows. wmenu 10 3 3 invert on color white blue white red



COLOR Parameters. This parameter defines the colors used for the frame, title, menu item text and the selection highlight bar. It should be used if the EXEC program may be used on a color display. wmenu 10 3 3 invert on color white blue white red



The fg and bg colors are used for the menu item text, the frame and the title text. rvfg and rvbg colors are used for the selection highlight bar. When the COLOR phrase is not used and the display is capable of colors, the default colors are used for the menu window. Refer to “Window Colors and Invert Status” on page 150 of the THEOS Corona Version 5 Operating System Reference manual. KEEP Parameter. This parameter performs two functions: It specifies the window number used for the menu and it tells wMenu to not close or remove the window when a selection is made. When this parameter is not used the menu window is automatically closed and removed when the operator selects a menu item.



752



 Note: The menu window is always opened or reopened when wMenu starts, even if it is the same window number and menu item list used the last time that wMenu executed.



&begstack 6 Item 1 6 Item 2 6 Item 3 &end wmenu 3 5 10 HOT Item 1 Item 2 Item 3



In this list, the sixth character of each item is the hot-key character. Character positions are counted starting with the first non-space character following the hot-key character number. In the above example, the hot keys are the characters 1, 2 and 3, respectively. Item Selection. When the menu displays, the selection highlight bar is positioned on the first item in the menu. You may use the (˚) and (˙) keys to move the highlight bar up and down. The (Home) and (End) keys move the highlight bar to the first and last items in the list. The (ÌÌSpaceÌÌÌ) key advances the highlight bar to the next item. Unlike the (¤) key, the (ÌÌSpaceÌÌÌ) key wraps from the last item to the first. Pressing (EnterÌ˛) selects the highlighted item. You may also position to and/or select an item using a hot-key or soft hotkey. Hot-keys are enabled with the HOT parameter and are indicated with underlined characters in the item list. Soft hot-keys are enabled when the HOT parameter is not used. When hot-keys are enabled, you may press an underlined character. This causes the highlight bar to move to the first item containing the underlined character. If there is only one item with that hot-key, the item is automatically selected just as if you had pressed (EnterÌ˛). When soft hot-keys are enabled, pressing a character positions the highlight bar to the next item that starts with that character. If there are no



753



Commands



HOT Parameter. The HOT parameter tells wMenu that menu items can be selected using “hot-keys.” When this parameter is used, each item in the menu list must specify the position of the character used for hot-key selection of the item. For instance:



 more items starting with that character, then the highlight bar moves to the first item starting with the character.



Commands



Hot-key and soft hot-key selection is case-insensitive. Selecting an item sets the return code (EXEC &RETCODE variable) to the selected item’s number. Pressing (Esc) selects no item but exits wMenu, setting the return code to zero. wMove



The wMove command moves a window to a new location on the screen. col and row are the column and row numbers of the new location for the upper-left corner of the interior of the window. Note that windows can be moved by the operator using a mouse or a virtual mouse.



wMsgBox



Display a message box form. A message box form is a form with a title, message text and optional operator response buttons. For instance: >wmsgbox question "Title text" "Example message text" YNC



Icon. This is an optional parameter that can be used to specify that the message form has a graphical icon displayed on it. There are four icons available and they are specified with their icon names: Icon name



Displays



Exclamation Information Question Stop Title. The text specified in this position is displayed in the title bar of the form. Although you can specify an empty string, there will always be a title bar for the form. You should enclose the title text in quotation marks 754



 to ensure that it uses the text that you specify rather than just the first word. Message. This is the text that is displayed in the body of the form. You should enclose this text in quotation marks.



Code



Mneumonic



Buttons



0



O



1



OC



OK, Cancel



2



ARI



Abort, Retry and Cancel



3



YNC



Yes, No and Cancel



4



YN



Yes and No



5



RC



Retry and Cancel



6



C



7



YNAN



Yes, No, Yes to All and No to All



8



NONE



No buttons



OK



Cancel



WAIT seconds. This option allows you to display the message form and, if there is no response from the operator for seconds amount of time, the message form clears itself and exits.



755



Commands



Type. This parameter specifies the operator response buttons that are displayed in the message box form. It can be specified with a numeric code or a mneumonic code.



 Return code. The return code is set according to the way that the message form is exited. Return Code 0



Exited by The (Esc) key, mouse clicking on the (X) symbol or the



Commands



WAIT seconds timed out.



wOpen



1



The “OK” button.



2



The “Cancel” button.



3



The “Abort” button.



4



The “Retry” button.



5



The “Ignore” button.



6



The “Yes” button.



7



The “No” button.



8



The “Yes to All” button.



9



The “No to All” button.



The wOpen command defines a new window or redefines an existing window. window refers to the window number of the new or existing window. col and row are the column number and row number of the upper-left corner of the interior of the window (excluding the frame and shadow). columns and rows refer to the width and depth of the interior of the window. >wopen 1 10 5 58 10 >wframe 1 sunken right >wtitle 1 " Window 1 " top center >wselect 1



756



 >wopen 1 10 5 58 10 >wframe 1 sunken right



Window 1



> >wtitle 1 " Window 1 " top center >wselect 1



Commands



The window may be specified with a question mark. When this is done, the next available window number is used for the new window. The window number is returned as the return code of the wOpen command. This command does not select the new window, it only creates it in memory. The initial attributes of a new or reopened window are: double-line frame with no shadow or title; clip on and update on. It has neither the hidden nor top attribute set (see wSelect command on page 759). If there is insufficient space around the interior of the window for a frame, then the window has no frame. The interior of a new or reopened window is empty with the cursor location at the upper-left corner. The color and invert status of the window and its frame are dependent upon its window number, the capabilities of the console and the setup for session colors for this console. Refer to “Window Colors and Invert Status” on page 150 of the THEOS Corona Version 5 Operating System Reference manual for more information about default colors and invert status. wRefresh



The wRefresh command updates the display of a window on the console without making it the active window. This command updates the display of the window interior, frame, title and shadow. It does not change the order of the window. That is, if the window is covered by another window, then the portion that is covered is not displayed. The wSelect command changes the order of display for a window. 757



 wRemove



The wRemove command erases the display of a window from the screen. Any and all windows previously covered by window become visible. This command does not close the window.



Commands



wRestore



The wRestore command retrieves a window definition and contents that were previously saved to disk with the wSave command. wrestore 30 sample.copyrite



The above command restores the window saved in the file SAMPLE.COPYRITE (see wSave command example). A restored window has all of the attributes of the saved window including: Window location Window size Cursor location Frame style, attributes and color Shadow position Title position, alignment, attributes and color Clip status Invert status Display type (hidden, top or neither) Interior contents including text, attributes and color The window is restored with this command but not displayed. You must use the wRefresh command or the wSelect command to display the new window on the screen.



758



 wSave



The wSave command saves a window description and contents to a disk file.



Commands



wopen 1 46 4 30 3 wframe 1 double right 0x17 wclip 1 on wselect 1 top color white blue &crt pon &crt 7 1 &type SAMPLE Version 1.0 \ &crt 2 2 &type by ABC Software Corporation \ &crt 7 3 &type All rights reserved \ &crt poff wselect 1 on top wsave 1 sample.copyrite



The preceding EXEC statements and commands create a window and fills it with a copyright notice for the program SAMPLE. This window definition is saved in the disk file SAMPLE.COPYRITE. A window definition saved with the wSave command can be used by the wRestore command, the BASIC language WINDOW RESTORE statement or the C language wRestore function. wSelect



The wSelect command selects a window as the active window for text display and operator input, and it defines the display order of the window. For instance: wselect 3 on



This command specifies that window number three is the active window, that it is refreshed and that all text written to the window will appear on the screen if the window is not overlaid by windows with the TOP attribute. Selecting a window always makes it the active window. It also restores the display attributes in effect the last time that the window was selected. Specifically, the following attributes are restored: the cursor location, cursor on/off mode, video attributes (blink, underline, etc.) and normal and reverse video colors. The first time that a window is selected, its cursor location is 1,1. Selecting a window places it on top of all other windows except those that were last selected with the TOP display mode.



759



 Window zero is always open and can be selected with this command but it cannot be specified as TOP or HIDDEN.



Commands



Update ON. Selecting a window with update mode ON means that the window is refreshed on screen and subsequent text written to this active window is displayed on the screen. This is the default mode when selecting a window. Update OFF. Selecting a window with update mode OFF means that the window is not refreshed on screen. Text written to the window is not displayed on the screen but it is saved in memory and will appear the next time that the window is refreshed or selected with update ON status. Display TOP. Selecting a window with the TOP display attribute causes the window to be displayed on the screen on top of all other windows, including other windows marked as TOP. TOP implies an update ON status. >wselect 3 top >wselect 3 off top



The above two commands have identical effects: window three is selected as the active window, its display order is on top of all other windows, it is refreshed on screen and subsequent text written to the window appears on the screen. Display HIDDEN. Selecting a window with the HIDDEN display attribute causes the window to be removed from the screen. HIDDEN implies update OFF status. Although it is the active window, it does not appear on the screen until it is refreshed or reselected with update ON status. A hidden window has all the properties of non-hidden windows except it is not visible on the screen until it is refreshed or selected without the HIDDEN attribute.



760



 wStat



The wStat command displays the general status for all windows, the complete status for a specific window or it returns the currently active window number. General Window Status. Using wStat with no parameters displays a brief summary of all open windows. Commands



>wopen 1 2 2 70 20 >wopen 2 4 4 68 18 >wopen 3 6 6 66 16 >wstat 0* 80x24 1 70x20 2 68x18 3 66x16



beg=0,0 beg=1,1 beg=3,3 beg=5,5



cur=0,11 order=0 cur=0,0 order=-1 cur=0,0 order=-1 cur=0,0 order=-1



update=1 update=0 update=0 update=0



Each open window is listed with the following information: Window number. The active window is denoted with an asterisk. Window interior size using number base one. Window interior origin (upper-left corner) using number base zero. Current cursor location within the window using number base zero. Display order. An order number of -1 indicates that the window is not currently displayed on the screen. Either it has never been selected or refreshed, or it is HIDDEN. Window update status. A code of one means that text written to the window is displayed on the screen.



761



 Display Current Window Number. When wStat is invoked with a question mark, it sets the return code to the current window number. This return code is easily used in an EXEC program by referencing the &RETCODE variable.



Commands



wstat ? &type The current window number is &retcode &curr_window = &retcode



Specific Window Status. When wStat is given a window number, the complete status of that window is displayed. >wselect 2 >wstat 2 status: begin col,row: width: height: curr col,row: cursor: frame-type: shadow-type: title-type: title-align: title-attr: frame-attr: clip: update: curr-attr: order: color: invert:



762



1 3,3 68 18 0,6 0 2 1 2 2 0x1C5F 0x1C5F 1 0 0x1C5F 0 7,5,7,0 0



 Status Element



Meaning



status



Window status



Codes Used



width



Window interior width, base one



height



Window interior height, base one



curr col,row



Cursor location, base zero



cursor



Cursor display type



frame-type



shadow-type



title-type



title-align



title-attr



Commands



begin col,row



0 = Not open 1 = Open, not active 2 = Open, active Window interior origin, base zero



0 = Not displayed 1 = Blinking underline 2 = Blinking block 3 = Steady underline 4 = Steady block Frame style 0 = None 1 = Single line 2 = Double line 3 = Raised 4 = Sunken Shadow style 0 = None 1 = Right 2 = Left Title position 0 = None 1 = Top 2 = Bottom Title alignment 0 = Center 1 = Left 2 = Right Bit-mapped value indicating the foreground and background title colors and the attributes.



frame-attr



Bit-mapped value indicating the foreground and background frame colors and the attributes.



clip



Interior text clipping



update



Update and display status



0 = Off 1 = On 0 = Update OFF 1 = Update ON 2 = Update ON, TOP 4 = Update OFF, HIDDEN



763



 Commands



Status Element



Meaning



Codes Used



curr-attr



Bit-mapped value indicating the current window interior foreground and background colors and the attributes.



order



Window display sequence



color



Window interior color codes for fg, bg, rvfg, rvbg.



invert



Monochrome invert status



Lowest or bottom-most window is 0. A -1 means window is not displayed (hidden or has never been displayed). 0 = Off 1 = On



The bit-mapped values used for the title, frame and current attribute fields are not useful in an EXEC program. This same information is available by using the appropriate functions in a program. Refer to the language’s reference manual for a description of these codes.



Specific Window Field Status. You may get a specific parameter of a specific window’s status. When wStat is given a question mark followed by a window number and a status field number, the status of that window’s field is displayed. >wstat ? 3 4 RC = 30, 08:53:45, et = 0:00, cpu = 0.072 >



In the above example, a request is made for the width of window 3. The return code is set to 30 indicating that that is the width of the window. The field codes for window status are: Code



764



Field



0



Status



1



Top left column



2



Top left row



3



Width



4



Height



5



Current cursor column



6



Current cursor row



 Code 7



Cursor shape



8



Window frame type



9



Window shadow type



10



Title type



11



Title alignment



12



Title attributes



13



Frame attributes



14



Text clip



15



Window update mode



16



Current text attribute



17



Window display order



18



Text foreground color



19



Text background color



20



Text reverse video foreground color



21



Text reverse video background color



22



Invert



Commands



wSwitch



Field



The wSwitch command can enable or disable session-switching, or it can switch to another session on your console. Session-switching is normally enabled. The wSwitch command can disable it if, for some reason, you do not want the operator switching to a different session while your EXEC program continues to execute. wswitch OFF



The above command disables session-switching. wswitch ON



The above command enables session-switching. Session switching may also be controlled with the Session command. The wSwitch command can also switch to a different session running on your console. Merely enter the session number desired. wswitch 4



765



 Note that if you use wSwitch to switch to a session other than the one that this EXEC program is running on, you will not be able to see any display from this EXEC. It will continue to execute on its own session.



Commands



To determine which session you are using, use the wSwitch command with a question mark argument. This causes wSwitch to set the return code to the session number in use by this program. wswitch ? &type My session is &retcode



wTitle



The wTitle command defines the title for a window. With this command you may either specify that a window has no title, or specify the title and its position and attributes. A window must have a frame in order to have a title. >wtitle 3



The above command removes any title that window three might have. >wtitle 2 " Window Two " bottom right



When a title is defined without the top-bottom specified, the default of TOP is used. When defined without the align parameter specified, the default of CENTER is used. The attribute for the title can be omitted, in which case it uses the default attributes of the frame for the title text. For a description of the attribute specification, refer to “Frame & Title Attributes” on page 151 of the THEOS Corona Version 5 Operating System Reference manual. The changed title and attributes are not displayed until the window is selected or refreshed, unless it is the current window. Restrictions



wOpen and wRestore are the only window management commands that can create or define a new window. All other commands except wStat operate



on existing, open windows. See also



Session and Chapter 10 “Windows,” starting on page 147 of the THEOS



Corona Version 5 Operating System Reference manual



766



 WinWrite Command The WinWrite command invokes the WindoWriter program, which is a general purpose, fullscreen text editor.



file



»



file name with optional path; may contain wild cards



options



»



FILES NOBACKUP



Command synonym:



NOSHELL PASSWORD



READONLY



WW



For a complete description of the operation and usage of this program, refer to the WindoWriter User’s Guide. Operation



WindoWriter is loaded and the first file is opened as the current text file to



edit. The file specification may contain wild cards and there may be more than one file specified on the command-line. In either case, the first file is opened and, when you close that file, the next file is opened, and so on. Options



FILES



Indicates that file is an ASCII stream file with each record in the file specifying a single file name. The file name specifications in this file may include the path and wild cards. The SELECTED.FILES and SELECTED.EXEC files created by FileList and the FOUND.EXEC created by Look can be used for this specification file. See “The EXEC and FILES Options” on page 239 of the THEOS Corona Version 5 Operating System Reference manual. You may also create the file with an editor or application program. For instance, FileList is used to create a list of files to be examined: >filelist *.txt:a (exec >filelist a not *.txt:a (10/1/01 exec append



A SELECTED.EXEC file now exists that lists all of the “text” files and all files that have been changed since 10/01/2001. The following command edits these files:



WinWrite 767



Commands



WINWRITE file... ( options



 >ww selected.exec (file



The FileManager command can also create and add to SELECTED.EXEC, SELECTED.FILES and FOUND.EXEC files.



Commands



NOBACKUP



This option specifies that any and all files saved during this session will not have a backup version created. This NOBACKUP option also applies to automatic file-saves performed by WindoWriter. The NOBACKUP option, although it takes away a safeguard, is invaluable when disk space is at a premium. Editing a large file or a file that resides on a floppy diskette can use up large amounts of disk space, particularly when more than one level of backup is maintained.



NOSHELL



This option disables the CSI Shell... item of the File menu of WindoWriter. This option would normally be used when WindoWriter is invoked from an application program. By specifying NOSHELL, the user is prevented from using WindoWriter to gain easy access to system commands that might cause problems for the application.



PASSWORD pw Use pw to access the file using DES private key encryp-



tion. If the file is currently encrypted, the pw is used to decrypt the file and open it. When the file is saved, pw is used to encrypt the file. pw should be enclosed within quotation marks to ensure that it is passed to WinWrite unmodified. Refer to the Decrypt and Encrypt commands for more information about DES encrytion. READONLY Do not allow changes to the file. This causes WindoWriter to



operate just as if the file were read protected. Notes



The command name WW is a synonym to the WinWrite command. It is not a separate program but only an entry in the /THEOS/OS/MESSAGE/language/ SYNONYM file. If standard synonyms are disabled (see “Account” on page 13 and “STDSYN” on page 110), this synonym name may not be allowed. A file specification can omit the file type if the environment variable FILETYPE is defined.



For more information about the FILETYPE variable, see “Environment Variables” on page 111 of the THEOS Corona Version 5 Operating System Reference manual.



768 WinWrite



 The keys used while in WindoWriter may differ from the keys used in other programs. See “Function Key Remapping” in the WindoWriter User’s Guide. The default configuration of WindoWriter is determined by the configuration file for WindoWriter. Each account may have their own configuration file. Refer to the WindoWriter User’s Guide for more information about this configuration file.



Restrictions



file must be a stream text file.



See also



Decrypt, Encrypt, LineEdit, WindoWriter User’s Guide



WinWrite 769



Commands



Defaults



 Commands



770 WinWrite



 WordCount Command This command counts lines, words and characters in a stream file.



WORDCOUNT



file... ( options



2



WORDCOUNT



file... ( FILES options



file



»



file name with optional path; may contain wild cards



options



»



BYTES CHARS FILES LINES WORDS



Command synonym: Operation



WCOUNT



Mode 1—The file is analyzed and the total number of characters or bytes, words and lines is counted. The totals of these counts are displayed on the standard output device. >wordcount /theos/config/devnames.txt Lines 554



Words 14,537



Chars 31,694



File-name /THEOS/CONFIG/DEVNAMES.TXT



Omitting file means that the standard input device supplies the text of the file. This would normally be used in a pipe command-line. When the text comes from the console keyboard, it is terminated with a (Ctrl)+(D). >wc The quick brown fox jumped over the lazy gray dog. Now is the time for all good men to come to the aid of their party. (Ctrl)+(D) Lines 3



Words 26



Chars 119



File-name



WordCount 771



Commands



1



 Multiple files may be specified on the command-line. Each one of the files is analyzed separately and the totals are displayed. The total for all of the files is then displayed at the end. >wordcount first.file second.file third.file



Commands



Lines 55 120 32 207



Words 1,127 2,500 600 4,227



Chars 5,635 10,389 1,357 17,381



File-name first.file second.file third.file Totals 3



Mode 2—In this mode file is an ASCII stream file containing one file description per line. Each file description in file is counted. The file descriptions may contain wild-card specifications. This mode of the WordCount command is convenient when one or more sets of files are repetitively being counted. Merely edit a file containing the file description, such as: >list daily.counts system.history:s *.log:s >wc daily.counts (file Lines Words Chars 13,398 200,690 862,356 250 2,435 10,389 3,029 4,398 25,942 16,677 207,523 898,687



772 WordCount



File-name system.history private.log user.log Totals 3



 Options



BYTES



Count and display the total number of bytes in the file. This is synonymous with the CHARS option.



CHARS



Count and display the total number of characters in the file. This is synonymous with the BYTES option. >wordcount /theos/config/devnames.txt (chars



LINES



File-name /THEOS/CONFIG/DEVNAMES.TXT



Count and display the total number of lines or records in the file. >wordcount /theos/config/devnames.txt (lines Lines 554



WORDS



File-name /THEOS/CONFIG/DEVNAMES.TXT



Count and display the total number of words in the file. >wordcount /theos/config/devnames.txt (words Words 14,537



Notes



File-name /THEOS/CONFIG/DEVNAMES.TXT



The command name WCount is a synonym to the WordCount command. It is not a separate program but only an entry in the /THEOS/OS/MESSAGE/language/SYNONYM file. If standard synonyms are disabled (see “Account” on page 13 and “STDSYN” on page 110), this synonym name may not be allowed. A file specification can omit the file type if the environment variable FILETYPE is defined.



For more information about the FILETYPE variable, see “Environment Variables” on page 111 of the THEOS Corona Version 5 Operating System Reference manual. Defaults



Unless a specific option is specified, CHARS, LINES and WORDS are displayed by default.



Restrictions



file must be a stream file.



WordCount 773



Commands



Chars 31,694



 Commands



774 WordCount



 Zip Command This command lists, tests or creates compressed files in a ZIP archive.



ZIP



zipfile



2



ZIP



-options



filename... zipfile



filename...



zipfile



»



Archive file



filename



»



Name of file to add to archive file



options



»



Options for archiving



Operation



Commands



1



Mode 1—Add the list of files to the archive file zipfile. Mode 2—Perform the actions specified by options. The zipfile and the list of filenames may be necessary, depending upon the specific options requested.



Options



The following options may be combined into a single specification. For instance, to request comments (-c) and move mode (-m) you would specify -cm. -c



Allows you to add a one-line comment for each file that is added to the archive. >zip -c htms *.htm adding: beta2.htm (deflated adding: beta3.htm (deflated adding: beta4.htm (deflated adding: beta5.htm (deflated adding: beta6.htm (deflated Enter comment for beta2.htm: Comment for file one Enter comment for beta3.htm: Comment for the second file Enter comment for beta4.htm:



65%) 62%) 67%) 63%) 63%)



Enter comment for beta5.htm: This is my comment for the beta5.htm file Enter comment for beta6.htm: My last comment, for the beta6.htm file



Zip



775



 Commands



>unzip -l htms Archive: HTMS.zip Length Date Time Name ----------------34262 08-24-00 15:45 beta2.htm Comment for file one 23593 10-03-00 00:42 beta3.htm Comment for the second file 34194 03-07-01 11:27 beta4.htm 21651 08-30-01 11:03 beta5.htm This is my comment for the beta5.htm file 22811 12-12-01 13:58 beta6.htm My last comment, for the beta6.htm file -------------136511 5 files -d filelist



The list of file names in filelist is deleted from the zipfile. >zip htms -d beta3.htm beta6.htm deleting: beta3.htm deleting: beta6.htm >unzip -l htms Archive: HTMS.zip Length Date ----------34262 08-24-00 34194 03-07-01 21651 08-30-01 -------90107



Time ---15:45 11:27 11:03



Name ---beta2.htm beta4.htm beta5.htm ------3 files



-D



When the zipfile is created with the -r option (include subdirectories) this option suppresses the addition of the subdirectory names themselves. Each file will still have its path specified unless the -j option is used.



-f



Using the file names that are already compressed in zipfile, the original source locations are checked for newer versions of those files. Any file that is newer is updated by replacing the version that is archived. >zip -q example *.txt >ww some.txt ; update this file ... >zip -f example freshening: some.txt (deflated 71%)



776 Zip



 -F



Examine the archive file and correct any errors found. >zip zip: zip: zip: zip: zip:



-F example reading examplemenu.command reading examplescreen.command reading testgutenberg.command reading testit.command reading testprt.command



Display help text.



-j



Do not include the path when archiving a file. Compare the following two zips: >zip example /corona-cd/*.htm adding: corona-cd/beta2.htm adding: corona-cd/beta3.htm adding: corona-cd/beta4.htm adding: corona-cd/beta5.htm adding: corona-cd/beta6.htm



(deflated (deflated (deflated (deflated (deflated



65%) 62%) 67%) 63%) 63%)



>zip -j example2 /corona-cd/*.htm adding: beta2.htm (deflated 65%) adding: beta3.htm (deflated 62%) adding: beta4.htm (deflated 67%) adding: beta5.htm (deflated 63%) adding: beta6.htm (deflated 63%) -l



Convert CR to CR,LF while archiving each file. This option is useful if you are archiving a THEOS text file and you know that it will be used on a DOS/Windows system.



-ll



Convert CR,LF to CR while archiving each file. This option is useful if you are archiving a file that originated on a DOS/WIndows system and you know that it will be restored onto THEOS systems.



-m



Each file that is added to the zip archive is deleted from the source location.



-o



Set the date for the zipfile to the date of the newest file added to the zipfile.



-q



Quiet mode. This is the equivalent of the NOTYPE option used by other THEOS commands.



-r



Similar to the SUBDIR option of the CopyFile command, the subdirectories of the current working directory are included when Zip searches for the files to include in the archive.



Zip



777



Commands



-h



 -t mmddyyyy Of the files listed in filelist, only those files with a last



change date on or after the date specified here are added or updated in the zipfile. -T



Test integrity of the zip file.



Commands



>zip -T mailwavs test of MAILWAVS.zip OK -u



Update the files already compressed in the zipfile. When no filename list is provided, all of the current files in the zipfile are tested to see if they are older than the files in the original directory. >zip -q example *.* >touch some.file File "/MYDIRECTORY/SOME.FILE:S" touched: 02/20/2002 10:58:49 One file changed >zip -u example updating: some.file (deflated 53%)



-v



Enables verbose operation. Compare the following two commands: >zip example1 test.* adding: test.direct (deflated 99%) adding: test.indexed (deflated 100%) adding: test.keyed (deflated 99%) adding: test.lisam (deflated 87%) >zip -v example2 test.* adding: test.direct (in=1280) (out=12) (deflated 99%) adding: test.indexed (in=15996) (out=45) (deflated 100%) adding: test.keyed (in=4069) (out=21) (deflated 99%) adding: test.lisam.... (in=176560) (out=23125) (deflated 87%) total bytes=197905, compressed=23203 -> 88% savings



-z



Add a multiple-line comment to the zipfile. After the requested files are compressed and added to zipfile you are asked to enter your comment. Although it accepts and saves multiple lines of text, generally, only the last line will be displayed by the UnZip command when you list the contents. To terminate the comment, enter a line with a period character only. >zip -z example1 test.* adding: test.direct (deflated 99%) adding: test.indexed (deflated 100%) adding: test.keyed (deflated 99%) adding: test.lisam (deflated 87%) enter new zip file comment (end with .): This is just a test of the comment capability.



778 Zip



 .



-0



Do not compress the files, just store them in the zipfile.



-1



Compress the files into zipfile faster at the expense of the compression factor. That is, it doesn’t make it quite as small as it would if the -1 option were not used.



Notes



This program, and the UnZip program, are implementations of the UnZip and Zip programs from Info-ZIP. Info-ZIP provides free, portable, highquality versions of the Zip and UnZip compressor-archiver utilities that are compatible with the DOS-based PKZIP by PKWARE, Inc. This version is available for most other operating system platforms. Information about Info-ZIP may be found on the Internet at http://www.info-zip.org/.



See also



UnZip



Zip



779



Commands



A zip file may have only one comment. That is, when you are adding files to an existing zipfile and you specify a comment, the new comment replaces any comment that the zipfile may have had in it. However, the comments that may be added on a file-by-file basis (see the option -c) are not replaced unless the specific file is replaced.



 780 Zip



Commands



 A: Contacting THEOS Support for THEOS Corona and other THEOS products is provided to authorized dealers and reseller’s of THEOS products. End users should contact their THEOS dealer regarding questions or problems relating to installation or operation of the THEOS operating system and other THEOS products. THEOS Support Services for Resellers and Distributors are designed to provide the type of assistance best suited to your needs. Support options range from no-cost / low-cost information services on the World Wide Web to THEOS on-site training classes, fee-based direct support or an annual support contract. Depending upon your needs and budget, you may choose any one of these options or combine several into a custom program suitable to your requirements. When contacting Technical Support, include or be prepared to provide the following information: Product name and version number. Product patch level (use the SHOW VERSION command). Operating system serial number (displayed on bootup or use the SHOW SERIAL command).



Operating system version number (displayed on bootup or use the SHOW VERSION command). Type of hardware being used. What happened and what you were doing when the problem occurred. The exact wording of any messages that appeared on the screen(s). How you tried to solve the problem. If you are contacting support via the Internet help desk or email, attach the file created by the Config command. Dealers and THEOS resellers may contact THEOS Technical Support by mail, fax, telephone or the Internet. The following is a list of the help resources available to THEOS dealers and developers.



781



 On-line system helps. Virtually all THEOS software has some form of online help available. Because it is the easiest, this should be checked first to see if it has information or advice about the situation or feature that you are trying to use.



Commands



Manuals. Printed or on-line manuals should be checked before contacting THEOS. The current version of a manual may be downloaded from the internet in PDF form by accessing the THEOS web site at: http://www.theos-software.com/manual/ If the information in the manual does not answer your question then please inform technical support about that when you contact them. Internet help desk. For SDK dealers and developers, a knowledge base of previously reported problems is available on the Internet. http://helpdesk.theos-software.com http://www.theos-software.com/support/ If you cannot find the answer in the on-line help system or in the product manual then check this help desk to see if the problem or question has been asked by another dealer. If you cannot find a previous report that addresses the problem then post your query here. It will be answered promptly and the dialog about your problem will become available in the future to help other dealers and developers should they encounter a similar situation. Attachments can and should be included with your postings when appropriate. Typical attachments would be sample code, system configuration dumps, etc. Internet e-mail technical support representative. All THEOS dealers are assigned to a specific support representative. Questions posted on the Internet help desk are automatically forwarded to your assigned representative. Direct e-mail to your representative should only be done when the problem involves beta or pre-release software or when responding to a query from your representative. If you do not know your support representative’s email address, you can send your request to: [email protected]



782



 Internet “Dealer Forum” and “Corona Forum”. For SDK dealers and developers a general dealer-to-dealer forum and a Corona-specific dealerto-dealer forum are available on the THEOS web site. These forums should be monitored by all dealers and can be used by SDK dealers to inform other dealers about a situation that you have encountered or to report and ask other dealers about marketing opportunities, application design questions, hardware availability, etc.



This is a dealer-to-dealer forum and THEOS staff do not generally reply to questions posted in the forum. Internet “Ask THEOS Forum”. For SDK dealers and developers a forum is available on the THEOS web site that allows you to post questions to THEOS engineering staff. This forum should be used when you have questions that THEOS engineering staff or THEOS management might be able to answer about marketing, future directions of THEOS software, etc. http://www.theos-software.com/forums/ Telephone technical support representative. Telephone support is available to all dealers but should be used only when the problem you are encountering is of a very urgent or site-down situation. 1-925-935-1118 ext 211 Hours: Monday-Friday, 8:30am - 4:30pm, Pacific Time Fax technical support representative. Material may be faxed to THEOS support. This should be done when you have paperwork to communicate about a problem and the papers are not generated by computer or cannot be scanned in for transmission as e-mail/helpdesk attachments. 1-925-935-1177 Postal service mail, Package delivery services. Although dealers may mail questions and materials to THEOS support representatives, because of the time required for delivery you should only do so when there is a lot of paperwork involved in the question or there is product that needs to be returned to THEOS Software Corporation. When sending questions or product you should also send e-mail to your support representative informing them that the package is being sent. THEOS Technical Support THEOS Software Corporation 1801 Oakland Boulevard, Suite 315 Walnut Creek, CA 94596-7000



783



Commands



http://www.theos-software.com/forums/



 784



Commands