manual de theos corona
TRANSCRIPT
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 soft-ware 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 Corporation1801 Oakland Boulevard, Suite 315Walnut Creek, CA 94596-7000
Telephone: 925-935-1118Fax: 925-935-1177E-mail: [email protected]: 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
3
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Documentation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Account. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Attach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Calculator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Calendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Cat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55CDPlayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65ChDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71ClassGen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Compress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109CopyFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131CRLF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139CRT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Decrypt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Dial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163DialNet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173Echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Eject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199EmailChk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201EmailDel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203EmailGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205EmailPut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Encrypt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Erase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Expand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
4
File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227FileList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229FileManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243FileType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Finger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251Force . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257FTP Script File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280GetFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283Head. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Ident . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295Img . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299IXDiag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307Keyword. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309Killfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317LineEdit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331LogName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333Logoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Logon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Look . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339Lowcase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349MakeBoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357Mixer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361MkDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363More . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365Mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367Move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369Msg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373Net . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377Net Interactive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379Net ARP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388Net Browse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390Net Exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391Net Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393Net Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393Net Share . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399Net Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
5
Net Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401Net Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402Net Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402Net IPCFG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408Net . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409Net service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411NetTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421NsLookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431Patch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433Peek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451Ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453Play. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455POP3Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457Printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459PutFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463PWD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467Quote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469Reboot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477Reminder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479Remote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483Rename. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487Repeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493Restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495RMCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505RmDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507Route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517See . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525SendMail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547Show . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549ShutDown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565Split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569Spooler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
6
Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583SUMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587SysEd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589Sysgen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593Tail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595Tape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597TArchive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601TBackup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611TBrowse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633Tee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635Telnet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637Terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645TFTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647THEO+COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649TheoMail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653TIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657Using TIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666Touch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673TraceRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677TWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
ALIGN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685BARCODES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687CHANGE_AREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689CHECK_PRINTER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690COLOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691DEFAULT_UNITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692FIELD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693FILE_RECORDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695FONT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695IMAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695LIST_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696NEW_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697PICTURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698PRINT_NEXT_PAGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698PRINT_RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699PRINT_TXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699PRINT_WINDOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700REC_PAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701ROTATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701SELECT_AREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702SETPOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
7
STYLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703TEXT_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
UnErase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707UnInstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711Unique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713Unload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717Unnumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719UnZip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721Upcase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729VNC Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733WhereIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739Which . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741Who. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743WhoAmI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743WhoIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745wBypass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749wClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749wClip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749wClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750wColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750wFinish. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750wFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750wInvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751wMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751wMove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754wMsgBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754wOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756wRefresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757wRemove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758wRestore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758wSave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759wSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759wStat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761wSwitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765wTitle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766WinWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767WordCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771Zip. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
AppendicesA Contacting THEOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781
8
List of Tables
9
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
10
Introduction 11
Introduction
This manual describes each of the commands provided with the THEOS 32 operating system. They are arranged in alphabetical order by thier com-mand 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 con-ventions used here and throughout this manual.
12 Documentation Conventions
Documentation Conventions
Throughout this manual, syntax is used that looks like:
MAILBOX user MAILBOX user textMAILBOX user fileMAILBOX ( optionLIST file ( FILES option…
These symbols are used to show the correct syntax for typing the com-mand.
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 com-mand 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 type-face. For instance: When a report is aborted, the spooler prints the message “**** A B O R T ****” and performs a form-feed.
Commands 13
Co
mm
an
ds
1 C ommands
Account Command
The Account command maintains or displays user accounts.
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 exist-ing 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.
1 ACCOUNT drive
2 ACCOUNT drive ( option
3 ACCOUNT drive ( ADD name add-options
drive » optional disk drive code
name » account name
option » DELETE name PRTnnIDENT SORTIMPORT filename TYPE
add-options » COPY name PROMPT prompt-textFULLNAME name SUBDIR directoryHOME directory SYNONYM namePASSWORD password USER namePRIVLEV nn
14 Account
Co
mm
an
ds
Options DELETE account Deletes an existing account definition. Specify the account name immediately following the DELETE keyword.
>account ( delete accnts
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 sys-tems, the account definition file is /SYSTEM.THEOS32.ACCOUNT:S; for Corona systems, the account definition file is in /THEOS/CON-FIG/ACCOUNT.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 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 num-ber sequence. Refer to “Listing Accounts” on page 18.
Account 15
Co
mm
an
ds
Add Options COPY acct-name Specifies that the new account definition will default to 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 speci-fied in the current definition of acct-name are copied to this new account definition.
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 direc-tory 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 pass-word 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 priv-ilege 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.
16 Account
Co
mm
an
ds
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.
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 descrip-tion of USER names, refer to the UserName description in the THEOS Corona Version 5 Operating System Reference.
Account 17
Co
mm
an
ds
Notes Refer to Appendix D: “System Files” in the THEOS Corona Version 5 Oper-ating System Reference for a description of the file “Account.bin”.
The Account command can also be invoked via the Setup command.
Adding Accounts
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.
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.
18 Account
Co
mm
an
ds
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
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 (type sort
Account User Synonym Prv Password
SYSTEM 0 9
BACKUPS 0 SYSTEM 5
BASIC 0 SYSTEM 5
INCLUDES 0 SYSTEM 5
MAIL 0 SYSTEM 5
PRIVATE 1 5 YesJOHN 1 PRIVATE 5 Yes
TEST 2 2
TESTIT 2 TEST 2
Account User Synonym Prv Password
BACKUPS 0 SYSTEM 5
BASIC 0 SYSTEM 5
INCLUDES 0 SYSTEM 5
JOHN 1 PRIVATE 5 YesMAIL 0 SYSTEM 5
PRIVATE 1 5 YesSYSTEM 0 9
TEST 2 2
TESTIT 2 TEST 2
Account 19
Co
mm
an
ds
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:
>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
20 Account
Co
mm
an
ds
Attach 21
Co
mm
an
ds
Attach Command
This command associates logical device names such as PRINTER with physical device driv-ers and specifies the attachment options for a device.
System commands and application programs perform input and output to devices by speci-fying 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, con-sole 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.
1 ATTACH logical physical ( options
2 ATTACH logical ( options
3 ATTACH logical
4 ATTACH
logical » logical device nameCON consolePRTnn printerCOMnn comTAPEn tapeA–Z disk
physical » device drive name as defined in /THEOS/CONFIG/DEVNAMES.TXT:S
options » ALF DTR NOHOLD PZ XPCBnnnnnn En NP PUBLICBIDIR ETX Onnn QUEUE=aCnnn FFnnn Pnnn STPnnnCOPIES=nn HOLD PE VnnnCOPY=nn Lnnn PN WnCTS LFnnn PO XON
22 Attach
Co
mm
an
ds
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 attach-ment of logical TAPE2 to a 250MB streaming tape drive.
>attach a disk2
>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 col-umns. The line graphics characters can be suppressed if the LINEGRAPH environment variable is set to N (see “Environment Variables” on page 111).
Attach 23
Co
mm
an
ds
When the standard output device is not the console, the title, column head-ings and line graphics are not output.
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.
24 Attach
Co
mm
an
ds
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 charac-ter.
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).
ETX Specifies ETX/ACK software handshaking (serial devices only). The device driver sends blocks of characters. After a pre-defined number of characters are transmitted, an ETX (End of Transmission) code is sent and the driver waits for the periph-eral 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 Applies to console and printer attachments only. Specifies the displayable line length for the peripheral device. The default line length value is 80.
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 hand-
shaking. Similar to XON/XOFF handshaking except that scan codes 103 and 101 are used to enable/disable transmission.
Attach 25
Co
mm
an
ds
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.
To change the line length of a session on the main console, use the Session command.
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 print-able 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 charac-ters 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 appro-priate 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.
26 Attach
Co
mm
an
ds
The page length value for printers may be any value in the range 1–254.
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.
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.
Attach 27
Co
mm
an
ds
If the device is a console with a PC Term class code specified, then an XON request is interpreted as an XPC request.
XPC 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 char-acter is 0x67.
Spooler Options
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 upper-case queue identifier.
QUEUE=$a Specifies the queue letter that is assigned to subsequent reports. The queue letter a is always interpreted as an lower-case queue identifier or as one of the 12 special character queues.
a Synonymous with the QUEUE=a option. To designate a lower-case queue letter you must enclose it in quotation marks.
There are 64 possible single-characters queues:
Previous versions of the spooler supported only the first 26 queues. To pro-vide compatibility with programs and procedures designed for previous versions of the operating system, queue specifications default to the upper-case queue letters.
A – Z 26 forms/queues
a – z 26 forms/queues
# $ % & * + - < = > ^ ~ 12 forms/queues
28 Attach
Co
mm
an
ds
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 ; Refers to queue A>attach prt2 (queue=x ; Refers to queue X>attach prt2 (% ; Refers to queue %
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" ; Refers to queue a>attach prt2 (queue=$x ; Refers to queue x>attach prt2 (queue=$$ ; 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 hap-pens, 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.
Attach 29
Co
mm
an
ds
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.
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 interna-tional character sets.
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 “Sys-gen” 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
30 Attach
Co
mm
an
ds
Attaching Remote Network Printers
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 con-nection 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 informa-tion 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.
Attach 31
Co
mm
an
ds
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:
DosDiskA floppy: 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
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.
32 Attach
Co
mm
an
ds
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.
>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 refer-enced 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 Win-dows partition. In a dual-boot system, you could access the Windows’ parti-tion 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/CON-FIG/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 attach-ments you can copy files from or two a DOS-formatted diskette or hard disk partition. You can perform directory listings of those drives, etc.
Attach 33
Co
mm
an
ds
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.
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.
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 pre-vents 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.
RAM Disk Name Size RAM Disk Name Size
RAM64K 64KB RAM8MB 8MBRAM128K 128KB RAM10MB 10MBRAM192K 192KB RAM12MB 12MBRAM256K 256KB RAM16MB 16MBRAM384K 384KB RAM32MB 32MBRAM512K 512KB RAM48MB 48MBRAM640K 640KB RAM64MB 64MBRAM768K 768KB RAM96MB 96MBRAM1MB 1MB RAM128MB 128MBRAM1536K 1.5MB RAM160MB 160MBRAM2MB 2MB RAM192MB 192MBRAM3MB 3MB RAM224MB 224MBRAM4MB 4MB
Table 1: RAM Disk Names and Sizes
34 Attach
Co
mm
an
ds
Attaching Image Disk Drives
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.
Attach 35
Co
mm
an
ds
Size MB. Enter a value here to create an image drive with a capacity mea-sured in megabytes.
Size GB. Enter a value here to create an image drive with a capacity mea-sured in gigabytes.
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 spec-ify 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.
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 gen-eral, 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 Ver-sion 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 deter-mines this usability is whether or not the other computer has given per-mission 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.
36 Attach
Co
mm
an
ds
Attaching CD-ROM Drives
CD-ROM drives are accessed using the CDROM Installable File System and they are attached similar to hard disk drives.
>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 initial-ization prior to creating a new backup.)
Attaching COM Ports
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. 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 con-sole. 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 configura-tion file. Refer to the Sysgen command for a description of this setting.
Attach 37
Co
mm
an
ds
“Self Testing” Communications
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 per-forming self-testing. That is, testing of the communications by communi-cating with another user on the system. This device has four names of SELF1 through SELF4 and they operate in pairs.
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 trans-mitted by the first user to SELF1 will be received by the other user on SELF2, and vice versa.
38 Attach
Co
mm
an
ds
Attaching VDI Graphics
A VDI or Virtual Device Interface device is a peripheral capable of display-ing 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).
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: “Sys-tem 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
Backup 39
Co
mm
an
ds
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.
Operation Mode 1—This syntax causes BACKUP to copy the entire contents of from-drive 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 to-tape. 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-
1 BACKUP from-drive to-drive ( options
2 BACKUP from-drive to-tape ( options
3 BACKUP from-tape to-drive ( options
4 BACKUP drive ( options
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 NOASKBUFFER NOVERIFYFROM file TO fileMULTIUSER VERIFY
40 Backup
Co
mm
an
ds
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.
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 con-firmation that the proper volumes are mounted. For instance:
>backup f i
Source is Disk FDestination is Disk IMount 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.
Backup 41
Co
mm
an
ds
MULTIUSER Allows Backup to copy a public drive even though other users may be logged on and active. When Backup is instructed to per-form a backup of a public disk, it requires single user mode. If other users are logged onto the system, it displays the mes-sage: “Must be single user or private volume.”
Using this option tells Backup to not restrict the backup to sin-gle-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.
NOASK Disables the source and destination volume operator confirma-tion 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.
42 Backup
Co
mm
an
ds
Notes When a backup is performed, both the from-drive and the to-drive are mod-ified to reflect that the disk was the source or destination of a backup. For instance, after a backup of the F drive:
>disk fDisk 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 TArchive, CopyFile, Disk, Restore, Tape, TBackup
Cache 43
Co
mm
an
ds
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.
Operation 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 mem-ory 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.
1 CACHE
2 CACHE function
function » DELAY OFF STATUSDELAY ON SYNCOFF WBDIR OFFON WBDIR ON
44 Cache
Co
mm
an
ds
Cache Status and Statistics Display
When the STATUS command line option is used, or when Mode 1 of the Cache command is used, the following screen appears.
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.
Cache 45
Co
mm
an
ds
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 Meaning and Source
Cache size (kilo-bytes)
The value shown here indicates the amount of mem-ory 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 configu-ration and the Cache command enables disk cach-ing. 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 configura-tion.
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
46 Cache
Co
mm
an
ds
Cache Statistics Display
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 reflect-ing the percentage of the times a disk access request was satisfied since disk caching was enabled
Number of modified blocks: Shows the number of blocks of data cur-rently in the disk cache that have not been written to the physical disk yet.
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 syn-chronize 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 physi-cal disk.
Number of writes: Shows the number of times the disk cache system was asked to write informa-tion to the disk. This includes the number of blocks still in the cache memory wait-ing to be written to the physical disk (dirty blocks).
Number of bypasses Indicates the number of times that the disk cache system was bypassed, proba-bly due to a request from a large read or write operation for “one time only” data.
Cache Statistics Display
Cache 47
Co
mm
an
ds
Cache Control 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 soft-ware actually performs the write to the physical disk, the data cannot be written.
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 on-line 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
48 Cache
Co
mm
an
ds
Calculator 49
Co
mm
an
ds
Calculator Command
Calculator displays a calculator that can be used to perform basic arithmetic.
Operation The displayed calculator is:
Notes With the calculator displayed you may perform the following actions:
CALCULATOR
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.†
50 Calculator
Co
mm
an
ds
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 pre-cision and must be in a range of ±9.999999999999×10126.
(%) 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 dis-played 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 cur-rent entry to be 6.
Mouse Keyboard Action
Calendar 51
Co
mm
an
ds
Calendar Command
Calendar displays a calendar for a single month or for an entire year.
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 com-mand 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.
1 CALENDAR
2 CALENDAR month
3 CALENDAR month year
4 CALENDAR year
month » calendar month number, month name or abbreviation
year » calendar year number, with or without century number
52 Calendar
Co
mm
an
ds
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 speci-fied as a month number of the year (1–12), a month name (January, Feb-ruary, etc.) or with a month name abbreviation (Jan, Feb, Mar, etc.). For example:
>calendar 3
>calendar March
>calendar mar
The above three commands will display the calendar for March of the cur-rent 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:
>calendar 0 ; Display 2000
>calendar 1903 ; Display 1903
>calendar 3 ; Display March, current year
>calendar 2010 ; Display 2010
Date Limitations
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.
Calendar 53
Co
mm
an
ds
Month Display When a single month is displayed by Calendar (Mode 2 and Mode 3), a simu-lated calendar page is drawn on the screen. For instance:
Year Display 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.
April 2002
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
54 Calendar
Co
mm
an
ds
Notes The month names are defined in the /THEOS/OS/MESSAGE/language/MES-SAGE.BIN file, numbers 260–261. For a description of this file, refer to Appendix D: “System Files,” starting on page 209.
If the calendar display is redirected to a device or file other than the con-sole, month displays are output in a format similar to the year display, but for one month only.
Restrictions See “Date Limitations” on page 52.
Cat 55
Co
mm
an
ds
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, Stan-dard Output and I/O Redirection” on page 53 of the THEOS Corona Version 5 Operating System Reference.
Operation 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.
1 CAT ( options
2 CAT file… ( options
file » file name with optional path; may contain wild cards
options » NOTYPETYPE
56 Cat
Co
mm
an
ds
When one or more of file contains a wild card specification, the files match-ing the specification are sorted in alphabetical sequence and then pro-cessed as if they were specified individually. For instance, assume that there are files named LETTER.DOCUMENT, MEMO.DOCUMENT and SPECIAL.DOCU-MENT:
>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 FILE-TYPE is defined.
For more information about the FILETYPE variable, see “Environment Vari-ables” on page 111 of the THEOS Corona Version 5 Operating System Ref-erence.
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 output-ing 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
Cat 57
Co
mm
an
ds
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
58 Cat
Co
mm
an
ds
CDPlayer 59
Co
mm
an
ds
CDPlayer Command
The CDPlayer command plays an audio CD in the CD-ROM 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 cat-alog for the disc in drive, that information is displayed as each track plays
1 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
10 CDPLAYER drive RANDOM LOOP
drive » drive code letter of an attached CD-ROM drive
track » track number of audio CD in drive
60 CDPlayer
Co
mm
an
ds
(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 num-ber, time remaining in the track and the title if known.
>cdplayer d1: [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 pro-gram 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 playDon 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, simi-lar to Mode 1. However, in this mode, the audio CD is played in random order.
>cdplayer d randomLawrence Welk: His Greatest Hits10: [-03:21] Beer Barrel Polka
If the artist, title and track titles have been entered into the CD-ROM cat-alog 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.
CDPlayer 61
Co
mm
an
ds
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.
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 One11: [03:35] Honey, I’m Home12: [03:38] That Don’t Impress Me Much13: [03:39] Black Eyes, Blue Tears14: [04:12] I Won’t Leave You Lonely15: [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).
62 CDPlayer
Co
mm
an
ds
Defaults 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/CON-FIG/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 infor-mation about this disc. That information, if available, is saved in the CDDB.BIN file for subsequent playing of this disc.
The FREEDB.ORG is a free, public database of CD titles and track informa-tion. The server and database is implemented with GNU software copy-righted by the Free Software Foundation.
Not all discs are cataloged with FREEDB.ORG, although it is updated con-stantly. Some discs will display no disc or track titles.
Graphics Display
When CDPlayer is invoked from a graphics console, a graphic representa-tion of a CD player is displayed with controls. These controls may be manipulated with the mouse pointer.
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.
Help
Mixer
Intro
Repeat
Random
Eject
Disc selectTrack information
PlayPause
Previous trackNext track
Stop
Disc title
CDPlayer 63
Co
mm
an
ds
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
64 CDPlayer
Co
mm
an
ds
Change 65
Co
mm
an
ds
Change Command
The Change command changes a file’s attributes.
Operation Mode 1—Changes file according to options.
>change *.data (touchOk to change "FILE1.DATA:S" (Yes,No,All) Y"FILE1.DATA:S" changed.Ok to change "FILE2.DATA:S" (Yes,No,All) NOk 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 owner-ship of these files to another account:
1 CHANGE file ( options
2 CHANGE file ( FILES options
3 CHANGE ( options
file » file name with optional path; may contain wild cards
options » ACCOUNT name PRIVATE codesFILES PRIVLEV nnGROW n.m QUERYNOQUERY SHARED codesNOTYPE TOUCHOWNER name TYPEPATCH nnnnnnn
66 Change
Co
mm
an
ds
>change selected.exec (file account develop
Mode 3—Enters the interactive mode for selecting files to be changed.
>change (touchEnter file name list, terminate with empty line.?
You may enter any file name desired, with optional path and possibly wild card specifications. For instance:
>change (touch noqueryEnter 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 direc-tory. 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:
Change 67
Co
mm
an
ds
>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
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 por-tion is used. Program and stream files do not have growth fac-tors.
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 protec-tion 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
68 Change
Co
mm
an
ds
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.
>change *.data (touchOk to change "FILE1.DATA:S" (Yes,No,All) Y"FILE1.DATA:S" changed.Ok to change "FILE2.DATA:S" (Yes,No,All) NOk 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 protec-tion 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 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 protec-tion codes and its file date. However, you may not use the ACCOUNT or OWNER option with any other option.
Change 69
Co
mm
an
ds
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:
There are two other codes that may be specified here although they are not really protection codes:
Shared access protection codes include:
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
Code 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.
Code Meaning
m Set the “modified” attribute.
h Set the “hidden” attribute.
Code Meaning
w Write protection. The file cannot be written to.
r Read protection. The file cannot be read.
70 Change
Co
mm
an
ds
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 Touch
ChDir 71
Co
mm
an
ds
ChDir Command
The ChDir command changes the current working directory.
Operation 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 refer-ence 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 ref-erence 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
1 CHDIR directory
2 CHDIR
directory » path to new directory
Command synonym: CD
72 ChDir
Co
mm
an
ds
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 specifi-cation and add additional dots to it, one for each additional parent. The above reference could be specified with:
...../some.file
A directory name may be specified with less than the complete name. For example:
The ChDir command above specified a directory name that does not exist (there is no directory named “D” under DEVELOP, the current working direc-tory). 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.
>tree/developdoc
filesscreens
programsdoc
>cd d
ChDir 73
Co
mm
an
ds
>show homeHOME=/DEVELOP:S
>pwd/DEVELOP/PROGRAMS/DOC:S
>cd
>pwd/DEVELOP:S
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
74 ChDir
Co
mm
an
ds
ClassGen 75
Co
mm
an
ds
ClassGen Command
The ClassGen command creates or changes a console or printer class code specification file.
Operation 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 defi-nition 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 number ( option
number » console or printer class code number (1–255)
option » PRTnn
76 ClassGen
Co
mm
an
ds
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.
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.
The “Setup” field is output to the console when it is first attached.
Figure 1: ClassGen, Consoles, Screen 1
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... ESC - 0x82 0x83Home.................... RSUp...................... VTDown.................... SYNLeft.................... BSRight................... FF
ClassGen 77
Co
mm
an
ds
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 follow-ing codes:
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 charac-ter 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.
Row Number Column Number
128 (0x80) Absolute 129 (0x81) Absolute
130 (0x82) Standard 131 (0x83) Standard
132 (0x84) ASCII 133 (0x85) ASCII
78 ClassGen
Co
mm
an
ds
The second screen shows display attribute fields.
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:
Figure 2: ClassGen, Consoles, Screen 2
Bit 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.
THEOS® Classgen - version 5.0
CONSOLE Output attributes for class: 90 PcTerm U.S.A.
Reverse video on........ 0xBD ESC G 0x81 @ 0x84 '4' 0x88 '2' 0x90 '8'Reverse video off....... 0xBD ESC G 0x80 '0' 0x81 @ 0x84 '4' 0x88 '2' 0x90 '8'Underline on............ 0xBD ESC G 0x81 @ 0x84 '4' 0x88 '2' 0x90 '8'Underline off........... 0xBD ESC G 0x80 '0' 0x81 @ 0x84 '4' 0x88 '2' 0x90 '8'Blink on................ 0xBD ESC G 0x81 @ 0x84 '4' 0x88 '2' 0x90 '8'Blink off............... 0xBD ESC G 0x80 '0' 0x81 @ 0x84 '4' 0x88 '2' 0x90 '8'Half intensity on....... 0xBD ESC G 0x81 @ 0x84 '4' 0x88 '2' 0x90 '8'Half intensity off...... 0xBD ESC G 0x80 '0' 0x81 @ 0x84 '4' 0x88 '2' 0x90 '8'Format mode on.......... ESC &Format mode off......... ESC 0x27Cursor off.............. ESC . '0'Cursor on............... ESC . '1'
ClassGen 79
Co
mm
an
ds
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
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 charac-ter string, where the specific attribute is specified, precede the attribute code with a special code derived from the following table:
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 cod-ing.
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:
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 Character following applies to FORMAT attribute.0 Character following applies to HALF INTENSITY attribute.
80 ClassGen
Co
mm
an
ds
“ClassGen, Consoles, Screen 2” on page 78 shows an example of this tech-nique.
• ANSI X3.64 Attribute Coding
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 capa-bility 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 underlin-ing, blink, reverse video and half- intensity.
ClassGen 81
Co
mm
an
ds
The third screen shows the fields used for screen editing commands.
These fields are fairly obvious in their nature and the manual for your ter-minal 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 “transpar-ent” 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 chang-ing colors. In this command string substitute the following codes in the appropriate character positions:
Figure 3: ClassGen, Consoles, Screen 3
THEOS® Classgen - version 5.0
CONSOLE Output attributes for class: 90 PcTerm U.S.A.
Insert character........ ESC QDelete character........ ESC WInsert line............. ESC EDelete line............. ESC RClear screen............ ESC *Erase unprotected....... ESC & ESC ; ESC 0x27Erase to end of line.... ESC TErase to end of screen.. ESC YMonitor mode on......... ESC UMonitor mode off........ ESC uSend to status on....... ESC g ESC fSend to status off...... CREnable Slave Printer.... ESC `Disable Slave Printer... ESC aSet alpha color......... ESC ETX 0x88 0x90 0xA0 0xC0
82 ClassGen
Co
mm
an
ds When a color change is requested, THEOS changes these codes to the cor-
responding color code. The color codes used by THEOS are:
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 char-acter 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
Code Meaning
136 or 0x88 Foreground color144 or 0x90 Background color160 or 0xA0 Reverse Video foreground color192 or 0xC0 Reverse Video background color
Code Color Code Color
0 Black 4 Red1 Blue 5 Magenta2 Green 6 Yellow3 Cyan 7 White
ClassGen 83
Co
mm
an
ds
Screens four and five show the fields defining the keyboard input key translation values.
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 combi-nation. (See above figure.)
Figure 4: ClassGen, Consoles, Screen 4
THEOS® Classgen - version 5.0
CONSOLE Input function keys for class: 90 PcTerm U.S.A.
Up...................... 0xFF HDown.................... 0xFF PLeft.................... 0xFF KRight................... 0xFF MEscape.................. ESCTop..................... 0xFF GBottom.................. 0xFF ODelete character........ 0xFF SDelete left character... DELPage forward............ 0xFF QPage backward........... 0xFF IWord right.............. 0xFF 0xD2Word left............... 0xFF 0xD3Search forward.......... 0xFF 0xC1Search backward......... 0xFF 0xD1
84 ClassGen
Co
mm
an
ds
Screens six and seven show the line graphics character definitions for the terminal.
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 charac-ters 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.
Figure 5: ClassGen, Consoles, Screen 6
THEOS® Classgen - version 5.0
CONSOLE Line Drawing Graphics for class: 90 PcTerm U.S.A.
Upper left corner....... 0xDAUpper right corner...... 0xBFLower right corner...... 0xD9Lower left corner....... 0xC0Four way intersection... 0xC5Left intersection....... 0xC3Right intersection...... 0xB4Up intersection......... 0xC2Down intersection....... 0xC1Horizontal.............. 0xC4Vertical................ 0xB3Round upper left........ 0xDARound upper right....... 0xBFRound lower right....... 0xD9Round lower left........ 0xC0
ClassGen 85
Co
mm
an
ds
Screens eight, nine and ten show the fields defining the codes used to dis-play international characters.
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 charac-ter. Example: ç, Ç.
Tilde A diacritical mark that looks like a “squiggle” ( ~ ) over the character. Example: Ñ, ñ.
Figure 6: ClassGen, Consoles, Screen 8
THEOS® Classgen - version 5.0
CONSOLE Output International Symbols for class: 90 PcTerm U.S.A.
Uppercase A dieresis.... 0x8ELowercase a dieresis.... 0x84Lowercase a circumflex.. 0x83Lowercase a grave accent 0x85Lowercase a acute accent 0xA0Uppercase E acute accent 0x90Lowercase e dieresis.... 0x89Lowercase e circumflex.. 0x88Lowercase e grave accent 0x8ALowercase e acute accent 0x82Lowercase i dieresis.... 0x8BLowercase i circumflex.. 0x8CLowercase i grave accent 0x8DLowercase i acute accent 0xA1Uppercase O dieresis.... 0x99Lowercase o dieresis.... 0x94Lowercase o circumflex.. 0x93Lowercase o grave accent 0x95Lowercase o acute accent 0xA2
86 ClassGen
Co
mm
an
ds
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.
PrinterClass 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.
ClassGen 87
Co
mm
an
ds
Printer Class Code Maintenance Screens
The following shows the fields used in each of the maintenance screens used for printer class codes.
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.
Figure 7: ClassGen, Printers, Screen 1
THEOS® Classgen - version 5.0
PRINTER Attributes for class: 135 HP LaserJet II & III
Printer name............ HP LaserJet II & IIISetup................... ESC E ESC ( '1' '0' U
Boldface on............. ESC ( s '1' BBoldface off............ ESC ( s '0' BUnderline on............ ESC & d '0' DUnderline off........... ESC & d @Italics on.............. ESC ( s '1' SItalics off............. ESC ( s '0' SSecondary color on...... Secondary color off..... Compress on............. ESC ( s '1' '6' . '6' '6' HCompress off............ ESC ( s '1' '0' HDouble wide on.......... Double wide off......... Double high on.......... Double high off.........
88 ClassGen
Co
mm
an
ds
• Entering Characters
Each character in a field is separated by a space from the next character in the field.
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 dec-imal or hexadecimal.
Char ASCII Dec Hex Char ASCII Dec Hex
^@ NUL 0 0x0 ^P DLE 16 0x10
^A SOH 1 0x1 ^Q DC1 17 0x11
^B STX 2 0x2 ^R DC2 18 0x12
^C ETX 3 0x3 ^S DC3 19 0x13
^D EOT 4 0x4 ^T DC4 20 0x14
^E ENQ 5 0x5 ^U NAK 21 0x15
^F ACK 6 0x6 ^V SYN 22 0x16
^G BEL 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
ClassGen 89
Co
mm
an
ds
Control characters are always displayed with the ASCII name.
Example:
ESC &27 &ESC g ESC f0xFC ESC G 132 '4' 136 '2' 144 '8'
Restrictions 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
90 ClassGen
Co
mm
an
ds
Cleanup 91
Co
mm
an
ds
Cleanup Command
The Cleanup command erases backup, work and other temporary files.
Operation 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 con-figuration for this UserName (see “Environment Variables” on page 111).
Cleanup is not started until the “Start” button is pressed.
1 CLEANUP
2 CLEANUP ( options
options » ACCOUNTS QUERYALL SUBDIRNOQUERY TYPENOTYPE
92 Cleanup
Co
mm
an
ds
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 up. Requires a high privilege level and you must be logged on to the system account (account id = 0).
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.
Defaults This command uses the /THEOS/USERS directory to save and get its configu-ration. The default actions will depend upon the saved settings for the cur-rent user as defined in the account environment variable UserName.
Cleanup 93
Co
mm
an
ds
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.
Restrictions The ACCOUNTS option requires a high privilege level and that you be logged onto the system account.
See also FileManager
94 Cleanup
Co
mm
an
ds
Clear 95
Co
mm
an
ds
Clear Command
The Clear command clears the console and positions the cursor to the upper left corner.
Operation The console screen is cleared.
Notes The console status line is also cleared.
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
96 Clear
Co
mm
an
ds
Clock 97
Co
mm
an
ds
Clock Command
The Clock command displays a clock on the screen.
Operation Mode 1—Displays a clock using the last mode requested (analog or digi-tal).
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
1 CLOCK
2 CLOCK Analog
3 CLOCK Digital
98 Clock
Co
mm
an
ds
position and size used by this user and it is saved in the /THEOS/USERS/user-name/CLOCK.CFG:S file.
See also Date, Show CLOCK, Show TIME
Color 99
Co
mm
an
ds
Color Command
The Color command sets the default colors used on the console.
Operation Mode 1—Display the current colors in effect for this console.
>colorNormal: WHITE on BLUEReverse: 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 dis-played 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
>colorNormal: WHITE on CYANReverse: WHITE on BLUE
>color white red
>colorNormal: WHITE on REDReverse: RED on WHITE
1 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
100 Color
Co
mm
an
ds
If fewer than four colors are specified the colors are set accordingly:
Omit rvbg: The reverse video background is set to BLACK.
>color white blue cyan
Omit rvfg, rvbg: The reverse video colors are set to the reverse of the nor-mal video colors specified.
>color green black
>colorNormal: GREEN on BLACKReverse: 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
>colorNormal: BLUE on BLACKReverse: 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.
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
Code Name Abbrev Code Name Abbrev
0 Black N 4 Red R
1 Blue B 5 Magenta M
2 Green G 6 Yellow Y
3 Cyan C 7 White W
Table 2: Color Codes & Names
Compare 101
Co
mm
an
ds
Compare Command
This command compares two files and reports any differences.
Operation 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 dis-played 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:sprogram.source.program4:s programs.original.program4:sprogram.source.programx:s programs.original.programx:s
>compare compare.files (filePROGRAM.SOURCE.PROGRAM1:S PROGRAMS.ORIGINAL.PROGRAM1:SFiles are not equivalent.
PROGRAM.SOURCE.PROGRAM4:S PROGRAMS.ORIGINAL.PROGRAM4:SFiles are equivalent.
PROGRAM.SOURCE.PROGRAMX:S PROGRAMS.ORIGINAL.PROGRAMX:SFiles are not equivalent.
1 COMPARE file1 file2 ( options
2 COMPARE file ( FILE options
3 COMPARE file drive ( FILE options
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 NOTYPENOCASE PRTnnNOSPACE TYPE
102 Compare
Co
mm
an
ds
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 com-mand line.
>filelist sample.*:s (exec
>compare selected.exec a (file
File: /SAMPLE.FILE1:S, AFiles are equivalent.
File: /SAMPLE.FILE2:S, AFiles are not equivalent.
File: /SAMPLE.FILE3:S, AFiles 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 signifi-cant in the comparison.
NOSPACE Extra white space in the two files is not significant in the com-parison.
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 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.
Compare 103
Co
mm
an
ds
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.
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.
>compare julian.basic julian.backup (type1+000001 ! Program: JULIAN Compute Julian date2+0000023+000003 ! Programmer: John Doe4+0000045+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 match-ing 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 approxi-mately 40 lines of text.
104 Compare
Co
mm
an
ds
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.
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 julian.command julian.oldcmd (type00000105 52 5300000107 20 2100000109 8D 8C00000115 31 3000005A1D 4A 6A00005A5D 6E 6100005A5E 6E 6100005A5F 6D 6Eetc.
Each line of the display shows a location in the files, the value of that loca-tion 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 with-out using the BINARY option might produce erroneous results. When in doubt, always use the BINARY option.
Compress 105
Co
mm
an
ds
Compress Command
The Compress command compresses a file and saves the compressed form in a “compression library file.”
Operation 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.addrsort48% original.source.dflt46% original.source.entity46% original.source.eod138% original.source.eom147% original.source.eom247% original.source.eom347% original.source.eom440% 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.)
1 COMPRESS compress-file file... ( options
2 COMPRESS compress-file file ( FILES options
3 COMPRESS compress-file - file
4 COMPRESS compress-file
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 PRESERVEFILES SELFEXPANDMODIFIED SUBDIRNOTYPE TYPEPASSWORD
106 Compress
Co
mm
an
ds
Mode 2—The files listed in file are compressed and copied into compress-file. 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 specifica-tion file with an editor or application program.
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 preserve91% dat.acc14% dat.def82% dat.inccod85% dat.ass92% dat.def74% 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.ticketsretail.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 Date Time Size Ratedat.acc 12May88 11:41 1,024 91%dat.def 31Dec89 16:00 1,024 14%dat.inccod 31Jul00 19:31 1,804 82%dat.ass 13Apr98 19:07 1,668 85%dat.def 15Sep96 18:49 1,024 92%frn.anldat 28Mar01 08:39 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 compres-sion ratio of the file.
Compress 107
Co
mm
an
ds
Options DELETE 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 com-pressed and also to suppress the progress bar. Only error mes-sages 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 key-word. All of the files added to the compress-file are encoded with this password and they cannot be expanded without spec-ifying the same password.
>compress private.files *.text (notype password aard-vark
PRESERVED Tells Compress to not clear the modified attribute from a file that is compressed. Without this option, every file that is com-pressed 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, COM-MAND 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 infor-mation to extract and restore the file to its original location.
108 Compress
Co
mm
an
ds
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 mes-sages but does not display the names of the files being com-pressed. Specifying TYPE displays the names of the files being compressed. NOTYPE displays only error messages. This dis-play can be redirected.
>compress old.files selected.exec (file91% dat.acc14% dat.def82% 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 com-press-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
Config 109
Co
mm
an
ds
Config EXEC
This command is used to save the various system configuration files in a format that is suit-able for sending to THEOS customer support.
Operation 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 Initializes the menu so that the less-important files are included in the result.
Notes 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 infor-mation from the various configuration files relating to the system.
All Network-related config. Causes the file generated to include the infor-mation from the various network configuration files.
1 CONFIG
2 CONFIG options
options » NAME filenameNOBRIEF
110 Config
Co
mm
an
ds
All System and Network configs. Causes the file generated to include the information from all of the system and network related configuration files.
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 informa-tion.
Defaults The standard set of configuration information saved by this command includes:
Current attachments (Attach)
Current software versions (Show Version)
Config 111
Co
mm
an
ds
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)
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.
112 Config
Co
mm
an
ds
CopyFile 113
Co
mm
an
ds
CopyFile Command
The CopyFile command copies a file from one location to another.
1 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
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-driveCOMnnCONPRTnnTAPn
to-drive » disk drive letter for destination files
options » APPEND LOWCASE OLDFILE TRANSBYREC MODIFIED PRESERVE TRUNCATE nnnEOFSENT NEWDATE PUBLIC TYPEEXPORT NEWFILE QUERY UPCASEFILES NOQUERY REPLACE VERIFYFOR nnn NOSORT SORT date1FRKEY kkk NOTYPE SPECS date2FRLABEL lll NOVERIFY SUBDIRFROM nnn OLDDATE TOKEY kkkIMPORT OLDER TOLABEL lll
114 CopyFile
Co
mm
an
ds
Operation Mode 1—Copies from-file to the to-file.
>copyfile one.file another.file
>copyfile *.data =.datacopy
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 cur-rent 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
CopyFile 115
Co
mm
an
ds
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.
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:
>edit daily.filescustomer.master:s /backup/customer.master:scustomer.history:s /backup/customer.history:scustomer.invoices:s /backup/customer.invoices:sgeneral.legder.*:s /backup/=.=.=:scheck.*: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 specifica-tions 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.filescustomer.mastercustomer.historycustomer.invoicesgeneral.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
116 CopyFile
Co
mm
an
ds
>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
>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 (noqueryEnter 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 cre-ated and the records in the source file are copied to the new destination file one record at a time. Although this copy pro-cess is slower than a file copy, the destination is a “clean” ver-sion 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 max-imum 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.
CopyFile 117
Co
mm
an
ds
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 for-matted records, or direct, indexed or keyed organization files.
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.
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 specifica-tions 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
118 CopyFile
Co
mm
an
ds
must be used or the FOR option will be ignored (the entire file is copied).
>copyfile last.letter customer.= (from 1 for 8
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 num-ber 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 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.
CopyFile 119
Co
mm
an
ds
This option is ignored if to-file is not a direct, indexed or keyed file.
The from-file is imported by copying the records in the from-file 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.
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 char-acters are copied without any translation.
Most of the multinational characters (Ä, É, Ñ, etc.) are trans-lated 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 every-day:
>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 cur-rent 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
120 CopyFile
Co
mm
an
ds
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.
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 sup-pressed with this option.
>copyfile gl.* f (notOk to copy "GL.MASTER:S" (Yes,No,All) YOk to copy "GL.JOURNAL:S" (Yes,No,All) YOk 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 Copies the source file to the destination file only if the destina-tion file’s last change date is older than the source file’s or if
CopyFile 121
Co
mm
an
ds
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 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 que-ried 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 pro-gram 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 cur-rent 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 iOk 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.
122 CopyFile
Co
mm
an
ds
REPLACE Allows a file to be copied even if it already exists on the desti-nation 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 exist-ing file and replace it with a copy of the source file.
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 OLD-FILE 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 alphabet-ical 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" copiedto "/GENERAL/PROGRAM.NOTES.CONVERSN:J"....
CopyFile 123
Co
mm
an
ds
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 encoun-tered, it is copied along with all files in that subdirectory. If a subdirectory contains a subdirectory, its files will also be cop-ied, and so on.
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.
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 Charac-ter Translation” on page 128.
TRUNCATE Used with stream files to truncate each record in the destina-tion file to nnn characters.
124 CopyFile
Co
mm
an
ds
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.
>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 charac-ters to their uppercase equivalents. All non-alphabetic charac-ters are copied without any translation.
Most of the multinational characters (Ä, É, Ñ, etc.) are trans-lated with this option. See “Upcase” on page 727 for more infor-mation.
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 cre-ated or changed after October 30, 2001.
CopyFile 125
Co
mm
an
ds
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 main-tained by the THEOS file system.
>copy *.*: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 copied.
126 CopyFile
Co
mm
an
ds
Copying Stream Files
Many of the CopyFile options apply only to the copying of stream or sequen-tial 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.
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 (specsEnter 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 hexadec-imal can be specified. Merely type the character you want added to each record. To specify the character value in hexadecimal, termi-nate 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 char-acter typed is always treated as the delimiter and must be matched with an identical delimiter at the end of the string of characters.)
CopyFile 127
Co
mm
an
ds
?"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:
?1-10 10?11-12 48?13-13 47?14-99 50
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 (specsEnter 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 (specsEnter specification list:?* 1?"New " 3?10-99 10?
128 CopyFile
Co
mm
an
ds
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.
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 (transEnter 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 (transEnter 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”
CopyFile 129
Co
mm
an
ds
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.
Copying Indexed and Keyed Files
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 com-pletely 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 Files
Similar to indexed and keyed files, the BYREC option can reorganize a direct file.
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 jOk 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.
130 CopyFile
Co
mm
an
ds
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
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 direc-tory 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 Backup, FileManager, FileType, IXDiag, Move, Receive, Rename, Net, Restore, Send, TArchive, TBackup, THEO+COM
Create 131
Co
mm
an
ds
Create Command
The Create command creates direct, indexed and keyed files, libraries of files and subdirec-tories.
1 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
file » file name with optional path
library-options » REPLACE NOTYPESIZE nnnn TYPE
direct-options » CONTIG NOTYPEFILESIZE nnnnnn TYPEGROW n.mRECLEN nnnnn
indexed-options » CONTIG NOTYPEFILESIZE nnnnnn TYPEGROW n.mKEYLEN nnnRECLEN nnnnn
lisam-options » BINARY KEYLEN nnnCONTIG NOCASEDICTIONARY NOTYPEFILESIZE nnnnnn RECLEN nnnnnGROW n.m TYPE
recreate-options » CLEANCLEAR
132 Create
Co
mm
an
ds
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
>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 spec-ified 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 con-taining a file-name. It may have a file-type but it cannot have a member-name because subdirectories may not be a member of a library.
>create source (subdir
Although the Create command can create subdirectories, the MkDir com-mand 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 mem-bers 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).
Create 133
Co
mm
an
ds
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
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).
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 recreat-ing 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.
134 Create
Co
mm
an
ds
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 por-tion 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 com-puted 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.
Create 135
Co
mm
an
ds
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.
DICTIONARY The file is maintained in dictionary order. With this 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 val-ues are not changed on updates, the initial creation of a record determines the value of the key.
Recreate Options
CLEAN May only be used with the CLEAR option. It causes the con-tents 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 point-ers to the existing keys are cleared, effectively erasing all of the records.
Notes 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:
136 Create
Co
mm
an
ds
>create private\program.source (library size 44
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 com-mand 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 vari-able 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 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 exist-ing 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.
Create 137
Co
mm
an
ds
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:
See also Change, MkDir
Item 4GB LFS
Library size 262,100 Limited by disk space only
Indexed, key length 128 128
Indexed, record length 65,535
Indexed, file size 1.7GB 4GB
Direct, record length 65,535
Direct, file size 1.7GB 4GB
LISAM, key length 256
LISAM, record length 65,535, or > 16MB if using LISAM-specific i/o statements
LISAM, file size 1.7GB Limited by disk space only
138 Create
Co
mm
an
ds
CRLF 139
Co
mm
an
ds
CRLF Command
The CRLF command operates on stream files and converts the end-of-record mark and national characters.
Operation 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 con-verted to the THEOS format using CR only.
Mode 2—The record terminators in the file are converted to the termina-tors used by the operating system specified. The normal end-of-record ter-mination character for the common operating systems is:
OS 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.
1 CRLF file... ( options
2 CRLF file... ( os options
file » file name with optional path, may contain wild cards
options » NOTYPE TYPE XLATE OEMNOXLATE XLATE DOS
os » DOSTHEOSUNIX
Operating System Terminator
THEOS CR
DOS CR,LF
UNIX LF
140 CRLF
Co
mm
an
ds
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 effec-tive 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 effec-tive 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 charac-ter 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
CRT 141
Co
mm
an
ds
CRT Command
The CRT command demonstrates and tests the console’s display capabilities and keyboard definitions.
Operation When CRT is invoked the “CRT Test Menu” is displayed.
Use the normal menu selection keys to select the desired tests.
CRT
THEOS® 32 CRT Test
Display all attribute combinations.
Video Attributes
Direct Cursor AddressingRelative Cursor AddressingScroll Up and DownInsert/Delete Line/Char
Character Sets...Screen Sizes...Throughput Performance
Window Manager...Mouse and ON-Key...Keyboard
Exit to THEOS
Video Attributes
142 CRT
Co
mm
an
ds
Video Attributes
This test shows the video attributes supported by THEOS and how they are displayed on this console with the current class code.
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 dis-play 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.
Test Video Attributes
Press ENTER for next screen.
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 S
Black Blue Green Cyan Red Magenta Yellow WhiteNormal = Black on White; Reverse = White on Black.
CRT 143
Co
mm
an
ds
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 aster-isk ( * ) 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.
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 com-munication’s line (baud rate, parity, etc.).
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.
144 CRT
Co
mm
an
ds
Scroll Up and Down
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 dis-play which should cause the lines above this to scroll up.
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 dis-play to scroll down.
Observe these patterns as they display. Because scrolling takes a rela-tively long time for a terminal to perform, if there are any handshake prob-lems with your communication’s line, they will show up here with a pattern that does not appear uniform.
!"#$%&'()*+,-./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[\]^_`abcdefghijklmnopqr0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrs123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrst23456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstu3456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuv456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvw56789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwx
CRT 145
Co
mm
an
ds
Insert/Delete Line/Char
This display tests the console’s and class code’s insert and delete capabili-ties. First, the screen is filled with rows of numbers. Then the six insert and delete commands are performed on this displayed text:
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.
01234567890123456789012345678901234567890123456789012345678901234112356789012345678901234567890123456789012345678901234567890123421234567890123456789012345678901234567890123456789012345678901234312345 678901234567890123456789012345678901234567890123456789012341234567890123456789012345678901234567890123456789012345678901234
5123456789012345678901234567890123456789012345678901234567890123471234567890123456789012345678901234567890123456789012345678901234812345678901234567890123456789012345678901234567890123456789012349123456789010123456789012345678901234567890123456789012345678901234567890123411234567890123
4,1 = DC 6,3 = IC8,5 = IL 10,7 = DL
12,9 = EOL 14,11 = EOS
Press ENTER for menu.
146 CRT
Co
mm
an
ds
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:
Use the normal menu selection keys to select the desired tests.
Note: Not all consoles support all of the character sets.
THEOS® 32 CRT Test
Display all line graphics characters.
National CharactersTHEOS CharactersIBM PC Characters
Exit to Main Menu
Line Drawing Graphics
Character Sets
CRT 147
Co
mm
an
ds
Line Drawing Graphics
The two screens displayed by this menu item show the characters dis-played when line-drawing graphics are used and a sample of the graphics display.
= 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
Press ENTER for next screen.
Press ENTER for menu.
148 CRT
Co
mm
an
ds
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.”
A special help text file is supplied that shows how to compose these charac-ters from the keyboard.
>help compose
THEOS Characters
This display shows the THEOS character set. It includes the ASCII char-acters, the line-drawing graphics characters and the multinational charac-ters.
0 1 2 3 4 5 6 7 8 9 A B C D E F0: . . . . . . . . . . . . . . . .1: . . . . . . . . . . . . . . . .2: ! " # $ % & ' ( ) * + , - . /3: 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
4: @ A B C D E F G H I J K L M N O5: P Q R S T U V W X Y Z [ \ ] ^ _6: ` a b c d e f g h i j k l m n o7: p q r s t u v w x y z | ~ .
8: . . . . . . . . . . . . . . . .9: . . . . . . . . . . . . . . . .A:B: . . . . . .
C: Ä ä â à á É ë ê è é ï î ì í Ö öD: ô ò ó Ü ü û ù ú Ç ç Ñ ñ Æ æ Å åE: ß ¿ ¡ ¢ £ ¥ l ¼ ½ ÿ § a ² . .F: . . . . . . . . . . . . . . . .
C=
Press ENTER for menu.
THEOS Character Set
CRT 149
Co
mm
an
ds
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 pro-gram by enabling monitor mode.
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 termi-nals (see “CLASSnnn (Class Codes)” on page 213).
0 1 2 3 4 5 6 7 8 9 A B C D E F0: v u ä ã å ç b T ` U J K M N1: P d e Q S 2: ! " # $ % & ' ( ) * + , - . /3: 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
4: @ A B C D E F G H I J K L M N O5: P Q R S T U V W X Y Z [ \ ] ^ _6: ` a b c d e f g h i j k l m n o7: p q r s t u v w x y z | ~ O
8: Ç ü é â ä à å ç ê ë è ï î ì Ä Å9: É æ Æ ô ö ò û ù ÿ Ö Ü ¢ £ ¥ ₧ ƒA: á í ó ú ñ Ñ ª º ¿ ¬ ½ ¼ ¡ « »B:
C:D: ' E: α ß Γ π ∑ σ µ τ Φ Θ Ω δ ∞ ø ε ∩F: ≡ ± ≥ ≤ ⌠ ⌡ ÷ ≈ ˚ • · √ ⁿ ²
C=
Press ENTER for menu.
IBM-PC Character Set
150 CRT
Co
mm
an
ds
Screen Sizes
Some terminals support multiple screen sizes. For instance, most VGA dis-play 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.
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.”
THEOS® 32 CRT Test
Use SYSGEN/ATTACH to set screen sizes.
40 columns X 24 rows80 columns X 24 rows80 columns X 29 rows80 columns X 33 rows80 columns X 42 rows80 columns X 49 rows80 columns X 59 rows
100 columns X 39 rows132 columns X 24 rows132 columns X 27 rows132 columns X 43 rows
Exit to main menu
Screen Size Selections - Super VGA color: Video7
CRT 151
Co
mm
an
ds
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 NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollNoscroll Noscroll Noscroll Noscroll Noscroll Noscroll Noscroll NoscrollFull page: 81 msec; 28,000 cps (280,000) throughput bps)
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 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 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: 1,066 msec; 54 lines/sec
Press ENTER for menu.
152 CRT
Co
mm
an
ds
Window Manager
This function of the CRT command tests and demonstrates the capabilities of window management on the console.
Use the normal menu selection keys to select the desired demonstrations.
THEOS® 32 CRT Test
Open and display some windows, reorder them, then remove and close.
Window FramesWindow TitlesText ClippingWindow Text Copy/TransferWindow Menu Functions
Exit to Main Menu
Open, Close and Reorder Windows
Window Management Function Selections
CRT 153
Co
mm
an
ds
Mouse and ON-Key
This function presents a menu that allows you to test the mouse and the “ON-KEY” capabilities of the console.
Use the normal menu selection keys to select the desired demonstrations.
THEOS® 32 CRT Test
Mouse reports are standard mouse packets.
Window Manager Mouse API
ON-Key Events
Exit to Main Menu
Window Manager Mouse API
Supported Mouse APIs
154 CRT
Co
mm
an
ds
Window Manager Mouse API
This screen tests the Window Manager Mouse capability.
The four windows in this display screen are used to report various infor-mation 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).
Window Manager Mouse API
Window 1Window 2
Window 3
Window 4
EXIT
Left-clickLeft-downLeft-dclickLeft-drag
Row: 12 Col: 28Button 0804
Win: 1 Button 0804Row: 12 Col: 28
CRT 155
Co
mm
an
ds
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 soft-ware. Merely press the keys you are interested in to determine if the ON-KEY mechanism can detect it. If nothing displays on the screen, then ON-KEY could not detect the key or key combination.
To exit from this test press (Esc) twice.
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 associ-ated with that console.
See also Attach, ClassGen, Printer, Setup, Sysgen
156 CRT
Co
mm
an
ds
Date 157
Co
mm
an
ds
Date Command
The Date command displays the current system date and time on the standard output device (normally the console).
Operation Mode 1—Outputs the current date and time.
>dateThursday, 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:02TIME: 10:02:15
>date "+DATE: %D%nTIME: %r"DATE: 2002.07.04TIME: 10:02:15AM
>date "+Event occurred on %B %d, %Y at %H:%M"Event occurred on July 04, 2002 at 15:42
1 DATE
2 DATE +format
format » codes specifying the format of the date and time
158 Date
Co
mm
an
ds
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 char-acter ( % ) 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 DATEFORM = 104-07-2002 DATEFORM = 22002.07.04 DATEFORM = 3
Note that the date is always displayed with a four-digit year.
%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 sys-tem message #423.
Date 159
Co
mm
an
ds
%d 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 sys-tem 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).
Notes 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
160 Date
Co
mm
an
ds
Decrypt 161
Co
mm
an
ds
Decrypt CommandThe Decrypt command decrypts a sequential file using public key/private key Data Encryp-tion Standard (DES) 56-bit or 128-bit encryption algorithms.
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 quota-tion 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
1 DECRYPT source destination ( password
2 DECRYPT source ( password > destination
3 DECRYPT ( password < source > destination
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 DES128DES56 TDES
162 Decrypt
Co
mm
an
ds
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.
ENCRYPT source ( TDES password1 | ENCRYPT ( TDES password2 > dest...DECRYPT source ( password2 | DECRYPT ( password1 > dest
This last command might be used to decrypt the file generated in the pre-vious 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 differ-ent 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
Dial 163
Co
mm
an
ds
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.
Operation Mode 1—Invokes THEO+COM in DIAL mode. The first attached communi-cations 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 selec-tion of a number. Any modem or telephone connection remains connected.
Mode 2—Invokes THEO+COM in DIAL mode. The first attached communi-cations port is used and number is dialed via the device connected to that port.
>dial 1 800 123-4567Dialing 1 800 123-4567
The number may contain any of the following characters.
1 DIAL
2 DIAL number
number » telephone number to dial
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.
164 Dial
Co
mm
an
ds
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 COMn 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 THEO+COM
letters A–Z Generates the tones or pulses corresponding to the tele-phone 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.
The letters A–D may not be specified with spaces sur-rounding each letter or they will be interpreted as the DTMF codes described next.
* # A B C D Generates the corresponding telephone tones if tone dial-ing 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 sur-rounded by space characters.
T Switch to tone dialing mode. This code must be sur-rounded 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 dial-ing string and it must be part of a string enclosed in quo-tation marks (otherwise the CSI will treat it as a comment).
Character Meaning or Effect
DialNet 165
DIA
LN
ET
DialNet Command
The DialNet command is used to control and monitor Dial-Up Networking connections (DUN).
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.
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 defini-tion 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 com-mand:
>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.
1 DIALNET function profile
2 DIALNET
function » STARTSTOPSTATUS
profile » name of profile defined in SETUP NET
166 DialNet
Co
mm
an
ds
Mode 2—This is the windowed interface to the DialNet command.
Windowed Interface
When Mode 2 is used, it displays the following screen and menu:
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 pro-files defined, you are offered a list of the profiles available for that func-tion. 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 auto-matically 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.
DialNet 167
Co
mm
an
ds
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.
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 discon-nected. 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.
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 connec-tion.
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 dis-played. Press (Esc) if you do not want to see the status of any of those pro-files at this time. If there are no profiles connected, an error message displays.
The status display for a connected profile appears as:
Most of the meanings of the fields in this display are apparent. To clarify those that might not be apparent:
Profile: PACIFIERHost IP: 206.163.58.6Remote IP: 204.245.231.131Connected on: 03/12/2001 08:02:45 for: 00:06:12Bytes sent: 1,591 received: 2,611Packets sent: 34 received: 27Packets rejected: 2Largest packet sent: 133 received: 576Handshake: CTS/RTS Baud rate: 38,400Inactivity time-out: 00:10:00 remaining: 00:07:39Modem phone speed: 28,800
Connection Status
168 DialNet
Co
mm
an
ds
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 dis-played 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.
DialNet 169
Co
mm
an
ds
Command-Line 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.
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 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 myispProfile "MYISP" connected successfully,Host IP address: 206.163.58.53Remote 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 defini-tion is invalid. Remember that some PPP servers use case-sensi-tive account names and almost all use case-sensitive passwords.
170 DialNet
Co
mm
an
ds
• DialNet Stop
The DialNet Stop function disconnects this system from a currently con-nected remote PPP server. For instance:
>dialnet stop myispProfile "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 myisp2Dial-Up Network Profile "MYISP2" is not started.
>dialnet status myispDial-Up Network Profile "MYISP" is connected.
Connection task: 13Host IP address: 206.163.58.17Remote IP address: 204.245.231.131Bytes sent: 0Bytes received: 0Packets sent: 0Packets received: 0Packets rejected: 2Largest 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: 1Connect time: 00:08:53Serial port speed: 19200 bpsThis connection is the default gateway.
The fields displayed in this status report have the following meanings:
DialNet 171
Co
mm
an
ds
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 sent The number of bytes transmitted over this connection.
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 discon-nected, 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.)
172 DialNet
Co
mm
an
ds
Dynamic IP Addresses
Because dial-up connections to ISPs cause your IP address to be dynami-cally 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.
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 pro-grams. 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 Net-working 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.
Disk 173
Co
mm
an
ds
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.
Operation 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 256116 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.
1 DISK
2 DISK /:drive
3 DISK drive ( options
4 DISK drive ( FORMAT format-options
5 DISK file ( options
drive » disk drive attachment letter
file » file name with optional path
options » ACCOUNT FAST LABEL PRTnnBADMAP FIX MAP SEEKBOOT FREE MULTIUSER SIZE nnCLEAN FRAGMENT NOASK SHOWCLEAR HEX OPTIMIZE VERIFY
format-options » BOOT NOASKCYLINDERS nnnn SECTORS nnnDENSITY n SIZE nnHEADS nn TRACKS nnnnINCREMENT nn
174 Disk
Co
mm
an
ds
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.
>disk iDisk 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.
Disk 175
Co
mm
an
ds
Mode 4—Formats a disk volume. Formatting involves the physical for-matting of every sector on the disk volume and the building of a THEOS disk volume, including the disk label information and an empty root direc-tory. See “Formatting Disks” on page 186.
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.
>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,5164 19,898
"JULIAN.ORIGINAL:S" directory is at sector 203; offset 05 9,157
"JULIAN.OLDCMD:S" directory is at sector 245; offset 128174 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 Count Ext File-name486 4 ACCT9\SAMPLE.DIRECT490 37 ACCT9\SAMPLE.INDEXED527 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.
176 Disk
Co
mm
an
ds
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.
This option destroys the contents of all erased files.
CLEAR Clears the disk of all files and directory entries. The root direc-tory 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 con-firm 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 jDisk 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 File name2 SYSTEM\ATTACH.OUTPUT3 SYSTEM\B20UPD.IMG2 SYSTEM\DIALDIR/COMPUSRV.BACKUP...
Total fragmented files: 165 out of 9,939.2 percent of files on disk are fragmented.
Disk 177
Co
mm
an
ds
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.
There is a slight performance degradation with fragmented files but it is insignificant in most situations.
FREE Displays the list of available sectors for the disk.
>disk j (free
Sector Count867 79
2,189 3082,891 274,092 4
HEX This option can be used with the MAP and FREE options to cause the numbers to display in hexadecimal.
>disk k (map hex
Sectaddr Count Ext File-name
0 4 ** boot4 1 ** label5 0x35 ** main directory
0x3A 1 ** free space map0x3B 0x1FC5 ** available sectors
LABEL 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.
178 Disk
Co
mm
an
ds
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 Count Ext File-name
0 4 ** boot4 1 ** label5 241 ** main directory
246 1 ** free space map247 4 SYSTEM\TEST.DIRECT251 37 SYSTEM\TEST.INDEXED288 198 SYSTEM\TEST.KEYED486 4 ACCT9\SAMPLE.DIRECT490 37 ACCT9\SAMPLE.INDEXED527 198 ACCT9\SAMPLE.KEYED725 7,467 ** 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.
Message Meaning
** boot The first four sectors of every disk are reserved for a “bootstrap loader” pro-gram.
** 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 iden-tifying 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.
Disk 179
Co
mm
an
dsIf disk errors are reported, they should be corrected as soon as
possible!
MULTIUSER Tells Disk not to check for multiuser operation before perform-ing 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 sin-gle-user operation (the message is still displayed). See “Cau-tions” 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 continu-ous 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 cach-ing should be disabled. See “Cache” on page 43.
** missing sectors THIS IS AN ERROR MESSAGE! It iden-tifies an area of the disk that is not accounted for by any file or free space map.
** overlaps THIS IS AN ERROR MESSAGE! It iden-tifies an area of the disk that is “owned” by two or more files.
Message Meaning
180 Disk
Co
mm
an
ds
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.
>disk s (showDisk 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 files56 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
The drive may be specified with the wild card *.
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
Disk 181
Co
mm
an
ds
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
>disk aDisk 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.
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 ver-ify 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.
182 Disk
Co
mm
an
ds
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 key-word. Refer to “Formatting Disks” on page 186 for recommenda-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 imme-diately following the DENSITY keyword.
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 sec-tors 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 tech-nology drives. Most newer drives use “on-board logic” that automatically sets the increment or interleave values.
Removable Fixed Meaning
1 128 bytes per sector, all surfaces.
2 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.
13 2048 bytes per sector, all surfaces.
14 1024 bytes per sector, all surfaces.
7 15 512 bytes per sector, all surfaces. (IBM PC format)
Table 3: Disk Density Format Codes
Disk 183
Co
mm
an
ds
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.
Disk labels may use upper and lowercase letters, digits and the underscore character.
This is a default option whenever a disk is formatted or built.
SECTORS Specifies the number of sectors on each track. Refer to “Format-ting 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.
184 Disk
Co
mm
an
ds
Disk Menu When no drive code or options are specified, the Disk command menu is displayed:
Select Drive... Selects the drive that will be used in this next menu selec-tion. 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.
Disk 185
Co
mm
an
ds
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.
Clean Unused Disk Space. Performs a Disk (CLEAN on the selected drive and then exits. Refer to the CLEAN option description on page 175.
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.
186 Disk
Co
mm
an
ds
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.
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:
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 Cyls Hds Sects Capacity1 80 2 36 1.44 MB 3¾"2 80 2 30 1.2 MB 3¾"3 80 2 18 720 MB 3¾"
Enter format code: 1
Cylinders Heads Sectors Capacity
80 2 72 2.88MB 3½"80 2 36 1.44MB 3½"80 2 30 1.2MB 3½"80 2 18 720KB 3½"
Table 4: Floppy Disk Formats
Disk 187
Co
mm
an
ds
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
After the diskette is formatted, Disk needs a label. This label can be speci-fied 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.
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 format-ted.
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 com-mand 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.
7%
188 Disk
Co
mm
an
ds
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.
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 Attach, MakeBoot, Setup, System, Tape
Echo 189
Co
mm
an
ds
Echo Command
The Echo command defines a file or device that will be used for subsequent echoing of con-sole displays. Alternately, it echoes the remainder of the command line to the standard out-put device.
Operation Mode 1—Indicates that file is to be opened to receive console display ech-oes. To specify a file that has no file type, be sure to use the period termi-nator 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.
1 ECHO file
2 ECHO device
3 ECHO
4 ECHO text
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
190 Echo
Co
mm
an
ds
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 onlyThe following is for demonstration purposes only
>echo exampleexample
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 neces-sary, add a “dummy” token.
>echo "" prt1prt1
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 pro-grams to add text to a log file.
>echo "Begin daily archive" >> activity.log
See also I/O redirection, described on page 53 in the “Fundamentals” section of the THEOS Corona Version 5 Operating System Reference.
Edit 191
Co
mm
an
ds
Edit Command
The Edit command is a full-screen text file editor.
Operation This command edits an existing text file or creates a new text file.
>edit sample.textTop of file "/SAMPLE.TEXT:S".End of file "/SAMPLE.TEXT:S".
>edit _chdir.msgTop 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 filepointing to it.End of file "/THEOS/COMMAND/_ChDir.msg:S".
Options NOBACKUP Does not make a backup file when changes to this file are saved.
Notes WinWrite is a more modern full-screen text file editor and should be used 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:
1 EDIT filename
2 EDIT filename ( option
filename » file name with optional path
option » NOBACKUP
Command Meaning
(F1) Search forward
(ShiftÌñ)+(F1) Search backward
(F2) Move to start of next word
(ShiftÌñ)+(F2) Move to start of previous word
(F3) Repeat last find or search
(F4) Find line starting with specified text
192 Edit
Co
mm
an
ds
Edit Commands
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.
(F5) Erase from cursor to end of line
(F6) Insert line above current line
(ShiftÌñ)+(F6) Delete current line
(F7) Change case of character under cursor
(ShiftÌñ)+(F7) 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) Move to end of file (Bottom)
(PageÌUp) Move to and display previous page
(PageÌDown) 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
Command Meaning
BOTTOM
Edit 193
Co
mm
an
ds
CHANGE
Change text in the file. The syntax is:
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.
1 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
194 Edit
Co
mm
an
ds
DELETE
Delete lines from the text file.
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.
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.
CSI command
command » Command-line text to execute
1 DELETE
2 DELETE lines
3 DELETE /string/
lines » Number of lines to delete
string » Text to delete down to
1 DUP
2 DUP lines
lines » Number of times to duplicate current line
Edit 195
Co
mm
an
ds
GET
Get text from another file and add it to this file.
Mode 1—Get and insert the text in the clipboard into this file at the cur-rent 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.
1 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
196 Edit
Co
mm
an
ds
GOTO
Change the current line to a different line in the text file.
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.
Mode 1—Displays the current name of the text file.
Mode 2—Changes the name of the text file to filename.
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.
GOTO line
line » Number of line to move to
1 NAME
2 NAME filename
filename »
Edit 197
Co
mm
an
ds
Mode 1—Copy the current line to the clipboard.
Mode 2—Copy text to the clipboard starting with the current line and con-tinuing 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, start-ing 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.
1 PUT
2 PUT to
3 PUT filename to
filename » Name of file to put text to
to » /string/line
198 Edit
Co
mm
an
ds
QUIT
Exit without saving any changes.
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.
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
1 PUTD
2 PUTD to
3 PUTD filename to
filename » Name of file to put text to
to » /string/line
QUIT
TOP
Eject 199
Co
mm
an
ds
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.
Operation 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 “forgot-ten.”
Cautions If the device is publicly attached, you may be interfering with the opera-tion 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 per-formed 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-con-trolled ejecting.
See also Mount
1 EJECT device
device » name of tape or CD-ROM device or output device such as PRT3
200 Eject
Co
mm
an
ds
EmailChk 201
Co
mm
an
ds
EmailChk Command
The EmailChk command checks a folder in a mailbox for unread mail.
Operation Mode 1—The default Inbox folder in mailbox is tested for unread mes-sages. 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 mes-sages 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 suc-cessful 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.
Restrictions As indicated by the error return codes, EmailChk can only access mailboxes that exist and are configured properly.
1 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
RC 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.
202 EmailChk
Co
mm
an
ds
If mailbox is password-protected, you can only access it if the PASSWORD option is specified on the command line.
See also EmailDel, EmailGet, EmailPut, SendMail, TheoMail
Examples The following MultiUser BASIC language program segment checks a spe-cific folder in a mailbox for incoming, unread messages.
1000 WHILE 1 ! Repeat forever1010 SYSTEM "EMAILCHK SALES ORDERS"10201030 IF CSI.RETURN.CODE<0! Errors?1040 PRINT "Error encountered when checking for mail."1050 PRINT "Return code =";CSI.RETURN.CODE1060 QUIT 11070 IFEND10801090 IF CSI.RETURN.CODE=0! No messages?1100 SLEEP 10*60! Wait for ten minutes1110 CONTINUE ! Check again1120 IFEND11301140 ! At least one message is available. Get and process.11501160 SYSTEM "EMAILGET SALES ORDERS"11701180 IF CSI.RETURN.CODE<0! Error?1190 PRINT "Error encountered when getting mail."1200 PRINT "Return code =";CSI.RETURN.CODE1210 QUIT 11220 IFEND12301240 ! Process message file...1990 WEND
EmailDel 203
Co
mm
an
ds
EmailDel Command
The EmailDel command deletes messages from the Inbox folder of a 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 mailbox must refer to an existing THEO+Mail mailbox and that mailbox must not be currently in use by TheoMail.
Example >EmailDel Sales
>EmailDel Orders (Password "PriVatE"
>EmailDel General
See also EmailChk, EmailGet, EmailPut, SendMail, TheoMail
1 EMAILDEL mailbox ( options
mailbox » name of mailbox to be checked
options » PASSWORD
204 EmailDel
Co
mm
an
ds
EmailGet 205
Co
mm
an
ds
EmailGet Command
The EmailGet command gets the next unread message from a folder in a mailbox.
Operation 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. Addi-tionally, 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.
1 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 FN PASSWORD
206 EmailGet
Co
mm
an
ds
FN This option specifies the saved message’s file-name. The file-type of a saved message is always TEXT. Attached files also use this file-name.
>EmailGet sales (fn george
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 file-name 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 mail-box 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 configura-tion and checks for incoming mail one time and then exits. Message filter-ing may occur on those messages according to the filter rules defined in the mailbox.
EmailGet 207
Co
mm
an
ds
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.
Also, when there are attachments for the message, an additional file is cre-ated 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.
For instance, the original message was:
From: Fred Flintstone <[email protected]>To: Priscilla <[email protected]>Date: Thursday, 18 March 2002, 2:08 PMSubject: Example message with attachments----------------------------------------------------------
Attached are two files for your enjoyment.
Fred Flintstone<<Attachment: archive.test>><<Attachment: cleanup.exe>>
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 <[email protected]>To: Priscilla <[email protected]>Date: Thursday, 18 March 2002, 2:08 PMSubject: 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 <[email protected]>Date: Thu, 18 Mar 2002 14:08:11 -0800Subject: Example message with attachmentsAttachment: "archive.test" saved as "PRIVATE.ATTACH1"Attachment: "cleanup.exe" saved as "PRIVATE.ATTACH2"
208 EmailGet
Co
mm
an
ds
PRIVATE.ATTACH1 Contains the first attached file from the message.
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 suc-cessful and the return code specifies the number of attachment files con-verted. A negative return code value indicates an error was encountered.
Restrictions 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 pre-vious 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
RC 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.
EmailGet 209
Co
mm
an
ds
Example The following MultiUser BASIC language program segment is the continu-ation of the example segment used for the EmailChk on page 201.
1000 WHILE 1 ! Repeat forever1010 SYSTEM "EMAILCHK SALES ORDERS"...1140 ! At least one message is available. Get and process.11501160 SYSTEM "EMAILGET SALES ORDERS"11701180 IF CSI.RETURN.CODE<0 ! Error?1190 PRINT "Error encountered when getting mail."1200 PRINT "Return code =";CSI.RETURN.CODE1210 QUIT 11220 IFEND12301240 ! Process message file12501260 ATTACH.COUNT% = CSI.RETURN.CODE! Number of attachments12701280 OPEN #16: "PRINTER" OUTPUT SEQUENTIAL1290 OPEN #1: "SALES.TEXT" INPUT SEQUENTIAL1300 LINPUT #1: TEXT.LINE$1310 WHILE NOT EOF(1)1320 PRINT #16: TEXT.LINE$1330 LINPUT #1: TEXT.LINE$1340 WEND1350 PRINT #16:1360 CLOSE #113701380 FOR ATTACH% = 1 TO ATTACH.COUNT%1390 PRINT #16: "Attached file: ";CRT$("EOL");1400 PRINT #16: "SALES.ATTACH"&STR$(ATTACH%);CRT$("EOS")1410 NEXT1420 CLOSE #1614301440 WEND...
210 EmailGet
Co
mm
an
ds
EmailPut 211
Co
mm
an
ds
EmailPut Command
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 inter-face, use the TheoMail command described on page 143.
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 mes-sage.
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 pass-word.
REPLYTO addr Use addr as the “Reply To” address of this message. The default reply-to is the FROM addr.
SUBJECT text Use text as the subject line of this message.
TO addr 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.
1 EMAILPUT mailbox filename ( options
filename » name of file on local system
mailbox » name of mailbox to be checked
options » ATTACH CC PASSWORD SUBJECTBCC FROM REPLYTO TO
212 EmailPut
Co
mm
an
ds
Embedded Mail Headers
The filename may contain embedded mail headers.
Refer to the SendMail command description of Embedded Mail Headers on page 533.
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 upper-case and embedded commas or spaces will terminate the argument.
When there are more than 50 addresses in the To, Cc and Bcc fields (com-mand-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 specifica-tions may include the path specification.
Every message must have a To field and a From field specified with com-mand-line options or embedded headers.
See also EmailChk, EmailDel, EmailGet, SendMail, TheoMail
Example >EmailPut mymail message.one
>EmailPut mymail message.two
...
>TheoMail mymail (send
Encrypt 213
Co
mm
an
ds
Encrypt Command
The Encrypt command encrypts a sequential file using public key/private key Data Encryp-tion Standard (DES) 56-bit or 128-bit encryption algorithms.
Operation Using the public key built into the Encrypt command and the private key password specified, the source file is encrypted using the requested algo-rithm 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 Fed-eral 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 encryp-tion 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
1 ENCRYPT source destination ( option password
2 ENCRYPT source ( option password > destination
3 ENCRYPT ( option password < source > destination
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 DES128DES56 TDES
214 Encrypt
Co
mm
an
ds
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 quota-tion 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 differ-ent 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
Erase 215
Co
mm
an
ds
Erase Command
This command erases one or more files from disk.
Operation 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.
>eraseEnter file name list, terminate with empty line.?OUTPUT.LOG"OUTPUT.LOG:S" erased.?SAMPLE.OUTPUT"SAMPLE.OUTPUT:S" erased.?*.BACKUP
1 ERASE file ( options
2 ERASE ( options
3 ERASE file ( FILES options
file » file name with optional path; may contain wild cards
options » CLEAN NOTYPENOQUERY QUERYNOSAVE TYPE
216 Erase
Co
mm
an
ds
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.erasework.master:swork.history:swork.invoices:swork.ledger.*:stemp*.*:ssort*.*: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.
Erase 217
Co
mm
an
ds
NOSAVE 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.* (notOk to erase "GL.MASTER:S" (Yes,No,All) YOk to erase "GL.JOURNAL:S" (Yes,No,All) YOk to erase "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 speci-fications 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 oper-ation.
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.
218 Erase
Co
mm
an
ds
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 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 com-mand 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 recy-cle 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 FileManager, Rename, RmDir, UnErase
Exit 219
Co
mm
an
ds
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 envi-ronment:
In a Shell environment: Exits the shell, returning to the prior envi-ronment.
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
220 Exit
Co
mm
an
ds
Expand 221
Co
mm
an
ds
Expand Command
The Expand command extracts and expands a file from a “compression library” created with the Compress command.
Operation 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.
1 EXPAND compress-file
2 EXPAND compress-file destination ( options
3 EXPAND compress-file destination file... ( options
4 EXPAND compress-file destination file ( FILES options
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 OLDER QUERY date1NOQUERY OLDFILE REPLACE date2NOTYPE PASSWORD TYPE
222 Expand
Co
mm
an
ds
Mode 3—Each file specified on the command line is extracted from com-press-file, expanded and stored on destination.
>expand programs s menu.basic paint.basic (replace/menu.basic:s/paint.basic:s
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 specifi-cation 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
Expand 223
Co
mm
an
ds
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.
>expand gl.compress s gl.* (notOk to replace "/GL.MASTER:S" (Y|N|A|G)? YOk to replace "/GL.JOURNAL:S" (Y|N|A|G)? YOk 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 destina-tion file name already exists. This is the opposite of the NEW-FILE 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 pro-gram 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 key-word. The files are expanded only if they were originally com-pressed 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 noqFatal error: File: "mydata.text:a" was corrupted or incor-rect password.
224 Expand
Co
mm
an
ds
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.
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 des-tination 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 speci-fied.
>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 OLD-FILE options. However, the OLDFILE option will not copy a file unless the destination file name already exists.
Expand 225
Co
mm
an
ds
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 mes-sages but does not display the names of the files being com-pressed. Specifying TYPE displays the names of the files being compressed. NOTYPE displays only error messages. This dis-play can be redirected.
>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 ; display compressed files
Date Time Size Rate File name13Jan2002 11:29 774 32% bmenu.basic01Oct2001 19:06 1,339 68% _func_key.basic20Dec2001 14:41 2,709 43% menu.basic11Nov2001 11:53 1,618 69% model.basic17Jan2001 12:56 356 25% paint.basic25Jun2001 14:17 6,726 48% phonenbr.basic
>expand programs s (1/1/02bmenu.basicpaint.basicphonenbr.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
226 Expand
Co
mm
an
ds
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.
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 main-tained by the THEOS file system.
>expand programs s (1/1/86 12/31/00func_key.basicmenu.basicmodel.basic
Here, since the date1 specification is 1/1/86, all files created or changed prior to January 1, 2001, are expanded.
See also Compress, CopyFile, FileManager, Restore, TArchive, TBackup
File 227
Co
mm
an
ds
File Command
The File command analyzes a file and reports on its organization and general function.
Operation Mode 1—Each file specified on the command line is examined for its orga-nization (program command, stream, indexed, etc.) and its contents (pro-gram 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
1 FILE file...
2 FILE file ( FILES
file » file name with optional path
228 File
Co
mm
an
ds
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.
The file types recognized by the File command include:
LISAM files are reported as indexed files.
See also FileList, FileManager
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.
FileList 229
Co
mm
an
ds
FileList Command
The FileList command displays a listing of a disk’s directory.
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.
1 FILELIST ( options
2 FILELIST file... ( options
3 FILELIST file1... NOT file2... NOT file3... ( options
4 FILELIST drive... ( options
drive » optional disk drive attachment letter
file » optional file name with optional path; may contain wild cards
options » ACCOUNT GROWPROTECT SORT5APPEND HIDDENPRTnn SORT6ASCII KEYPUBLIC SORT7CHECKSUM MNSERIAL SORT8COUNT NEWESTSIZE SORT sequenceEXEC NOTYPESORT1 TYPEFD OFFSORT2 VERSIONFILES OWNER nameSORT3date1FN PRIVLEVSORT4 date2FT
230 FileList
Co
mm
an
ds
Operation Mode 1—Displays a directory listing of all “flat files” in the current direc-tory of the current account. A flat file is a file that is not a member of a library.
>Filelist
If a default library is defined, then a directory listing of that library is pro-duced.
>set library system.b3220lib
>filelist
FileList 231
Co
mm
an
ds
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
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 cur-rent account on the S drive.
>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 pro-duced includes files that match the file specification before the keyword NOT as long as they don’t match the file specification following the key-word 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.
This displays all files with a file type of COMMAND or EXEC excluding those programs with a file name starting with TEST.
>filelist *.command NOT test*.command *.exec NOT test*.exec
Include Exclude ExcludeInclude
232 FileList
Co
mm
an
ds
The NOT file specifications exclude files that might match the specifica-tions. For instance,
>filelist test.* example.* NOT *.data
This command only excludes the “*.DATA” files from the “EXAMPLE.*” specifi-cation. All files matching “TEST.*” are still included. Also, you may not spec-ify 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.
APPEND Used with option EXEC or FILES to append an additional direc-tory 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.
FileList 233
Co
mm
an
ds
CUSTOMER.ROUTE1 CUSTOMER.ROUTE1CUSTOMER.ROUTE2 CUSTOMER.ROUTE10CUSTOMER.ROUTE10 CUSTOMER.ROUTE102CUSTOMER.ROUTE20 CUSTOMER.ROUTE2CUSTOMER.ROUTE102 CUSTOMER.ROUTE20
CHECKSUM Compute and display the checksum for each file. A checksum is a 16-bit value computed by adding the values of each byte in a file.
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 descrip-tion 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 descrip-tion 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.
234 FileList
Co
mm
an
ds
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 pro-grams 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 infor-mation 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 speci-fied.
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.
FileList 235
Co
mm
an
ds
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.
The protection codes displayed use single, position-dependent letters:
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 privi-lege level, version number and version date are output, replac-ing 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 kilo-bytes (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 line-graphics around the list and between the columns.
M W R E X W R
Owner read protectedOwner write protectedExecute protectedErase protectedShared access read protectShared access write protectModified
236 FileList
Co
mm
an
ds
SORT2 Sorts the output by file-drive, file-name, file-type and member-name.
SORT3 Sorts the output by file-name, file-type, file-drive and member-name.
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, member-name 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, member-name and file-drive. The sequence used for sorting organiza-tion is: indexed, keyed, relative, stream, 16-bit real mode pro-grams, 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.
TYPE A default option that outputs the directory listing to the con-sole.
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.
FileList 237
Co
mm
an
ds
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.
>filelist *.*:s (10/15/01
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 main-tained 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.
238 FileList
Co
mm
an
ds
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.
The columns Keyl, Recl and Gr are not output to a redirected file.
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. 48
Vers Version number of program. 50-55
V-date Version date of program. 57-63
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.
Check-sum
File’s checksum. 71-76
FileList 239
Co
mm
an
ds
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.
• SELECTED.EXEC
Option APPEND and EXEC create a special file named SELECTED.EXEC. This file contains only the file description information with command line vari-ables 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 pro-gram:
>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.
240 FileList
Co
mm
an
ds
The same program could be used in another command:
>selected.exec change (ne
>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 informa-tion, 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 01/06/2002 19:23 SD ....... 14336Charset.Basic:S 10/24/1994 04:53 S .W..X.. 4062Custmnt.O:S 04/14/2001 07:57 S .WR.... 157186disk.image1:S 01/07/2002 16:25 S ....... 1048576Loan.basic:S 02/07/2001 17:16 S .WR.... 21194...
FileList 241
Co
mm
an
ds
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 informa-tion is output as a packed file description:
>filelist s (files fd
>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 recog-nized. Refer to “Multiple-page Display Browsing” on page 79of the THEOS Corona Version 5 Operating System Reference. When the display is termi-nated 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
242 FileList
Co
mm
an
ds
FileManager 243
Co
mm
an
ds
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.
Operation 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
1 FILEMANAGER ( options
2 FILEMANAGER :drive ( options
3 FILEMANAGER directory ( options
drive » drive code of an attached drive
directory » path to desired directory
options » BACKUP LOWCASE NOOBJ OBJFT NOBACKUP NOTYPE TYPEHIDDEN
Command synonym: FM
244 FileManager
Co
mm
an
ds
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 configu-ration. The default actions will depend upon the saved settings for the cur-rent 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.
FileType 245
Co
mm
an
ds
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.
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 recog-nized 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 con-verted 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.
1 FILETYPE file... ( SAVE options
2 FILETYPE file... ( RESTORE options
file » file name with optional path; may contain wild cards
options » NOQUERY QUERYNOTYPE TYPE
246 FileType
Co
mm
an
ds
Options NOQUERY Tells FileType to not ask for confirmation before converting each file. This is a default option when wild cards are not used.
>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 sup-pressed with this option.
>filetype *.data f (notOk to copy "INDEXED.DATA:S" (Yes,No,All) YOk to copy "DIRECT.DATA:S" (Yes,No,All) YOk to copy "KEYED.DATA:S" (Yes,No,All) YOk 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 *.dataOk 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 oper-ation. 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
Find 247
Co
mm
an
ds
Find Command
The Find command searches a directory path and locates files.
Operation The current working directory, or the path specified in file, and all directo-ries subordinate to it, are searched. All files matching the file specification are output to the standard output device.
Any Find command executed in this example will search all of the subdirec-tories 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 file... ( options
file » file name with optional path; may contain wild cards
options » APPEND SUBDIREXEC date1PRTnn date2SORT
>tree/
datamisc
doc programs
package doc programs
vertical doc
files programs
programs
248 Find
Co
mm
an
ds
In the next command, the directories are searched for all backup files, with the list of files piped to the Erase command.
>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 pro-duced 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
Find 249
Co
mm
an
ds
When the SORT option is used the lines are sorted in alphabet-ical order, including any path specification.
SUBDIR Includes the names of all subdirectories searched. The subdi-rectory names are output after a subdirectory and all subordi-nate directories to this directory are searched. This option is particularly useful when you want to remove a branch of a directory tree:
>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 subdirec-tories 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 main-tained 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.
250 Find
Co
mm
an
ds
Restrictions The SUBDIR and SORT options cannot both be specified.
See also ChDir, FileManager, FileList, Tree, WhereIs
Finger 251
Co
mm
an
ds
Finger Client
The Finger client queries a server for the status of a specific account or for other information about accounts on a server.
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 deter-mine 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] user "acavallo" at host "pacifier.com". Login: acavallo Name: Allen CavalloDirectory: /admin/acavallo Shell: /usr/local/bin/tcshNever logged in.No Mail.No Plan.
Mode 2—Requests information about all users logged onto server. Many finger servers do not support this request.
>finger @theos-software.comQuerying user "" at host "theos-software.com".
Finger online user list request denied.
>finger @ccnet.comQuerying user "" at host "ccnet.com".
Login Name TTY Idle When Whereroot Operator co 10 Tue 09:54texas Verio Customer Care p0 Tue 16:01 oz.onramp.net...
1 FINGER user-name@server
2 FINGER @server
server » server name or IP address
user-name » user account name
252 Finger
Co
mm
an
ds
>finger @netcom.comQuerying user "" at host "netcom.com".
User Real Name Idle TTY Host Console Locationabenamer Allan Benamer 1:43 r9 netcom (unknown-8-127.ju)acapela Michael H. Collier p6 netcom21 (uswgco2.uswest.c)aci 0:59 pe netcom (aci.vip.best.com)...715 active login sessions.
Notes 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 guaran-tee 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] user "president" at host "whitehouse.gov".
Finger service for arbitrary addresses on whitehouse.gov is notsupported. If you wish to send electronic mail, valid addresses are"[email protected]", and "[email protected]".
>finger [email protected] user "me" at host "myisp.com".
Login: me Name: My NameDirectory: /home/c/me Shell: /bin/tcshMail forwarded to: Someone Else <[email protected]>New Mail received Wed Nov 26 10:15 2001 (PST)
Unread since Wed Nov 26 10:00 2001 (PST)No PlanYou have new mail.
>finger [email protected] 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.
Finger 253
Co
mm
an
ds
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
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.
>finger @my-company
Or the domain name as defined by the Domain Name Service spec-ified 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 “HEAD-QUARTERS” 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.
254 Finger
Co
mm
an
ds
Force 255
Co
mm
an
ds
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.
Operation Mode 1—Starting with process number one, all logged-on users are exam-ined. 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 speci-fied, 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.
1 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
256 Force
Co
mm
an
ds
The following two commands perform identical functions:
>force 5 basic test (print (noquery>force -nq 5 basic test (print
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 success-ful unless you use specify a command with the Force command. In that sit-uation, 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 pro-gram 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 Show USERS, Who
FTP 257
Co
mm
an
ds
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.
Operation 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.
1 FTP ( options
2 FTP host ( options send-rec-options
3 FTP host user-password ( options send-rec-options
4 FTP site ( options send-rec-options
5 FTP filename ( FILE options
filename » name of file on local client system containing FTP script
host » serverserver:port
localhost » LOCALHOST
options » ASCII NOPROXY VERBOSEBINARY PROXY host
port » port number on server for FTP communication (default is 21)
send-rec-options » RECEIVE remote-nameSEND 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
258 FTP
Co
mm
an
ds
Mode 3—Similar to Mode 2 except that, after a connection to host is estab-lished, you are logged onto user account with password. See “User Account Specification” for information about user accounts on the FTP server.
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 con-nection parameters. Site definitions are created with the Setup Net FTP Client command. (See THEOS Corona Version 5 Operating System Instal-lation and Setup Guide.) All site definition names are simple names with-out 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 con-tents 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 main-tained by the Setup Net FTP Client screen. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.)
VERBOSE Enables verbose mode. With verbose mode on, commands sent to and responses received from the remote FTP server are dis-played. With verbose mode off, these commands are not dis-played.
FTP 259
Co
mm
an
ds
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).
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.
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 specifica-tions 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 doc-ument 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 Appen-dix D: “Using a Proxy Server,” starting on page 203 of the THEOS Corona Version 5 Operating System Reference.
260 FTP
Co
mm
an
ds
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.
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 spec-ified 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 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 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.
FTP 261
Co
mm
an
ds
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 dis-played by the FTP client.
For instance, one server might display:
FTP? cd tempCWD command successful
FTP? remove test.fileDELE command successful
While another server might display:
FTP? cd tempDirectory changed to "/temp"
FTP? remove test.fileFile "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 directo-ries 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 speci-fied with enclosing quotes. This was done because some servers use case-sensitive 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.
262 FTP
Co
mm
an
ds
>ftpFTP? open headquartersConnecting to my-company.com (172.20.2.1)--------------------------------------------------User-name: my-namePassword: (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 connec-tion is made by either not specifying a user name, or by specifying the spe-cial 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 userConnecting to my-company.com (172.20.2.1)--------------------------------------------------Welcome to My Company FTP site.Anonymous user logged in.--------------------------------------------------FTP?
or
>ftpFTP? open headquartersConnecting to my-company.com (172.20.2.1)--------------------------------------------------User-name: anonymousPassword: [email protected] to My Company FTP site.Anonymous user logged in.--------------------------------------------------FTP?
When connecting as an anonymous user, the password entered is dis-played 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@your-domain” or, if your system is not part of a domain, then “account-name@local-name” is used for the password.
FTP 263
Co
mm
an
ds
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
Many FTP servers are implemented on systems which use case-sensitive user names, passwords, directory names and file names. Other FTP serv-ers 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.
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 des-tination is a THEOS-based FTP server, the received stream data is con-verted 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 subse-quent 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 subse-quently 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.
264 FTP
Co
mm
an
ds
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
FTP? verboseVerbose 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 connec-tion 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 com-mands 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 com-mand 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 KeyControl
KeyFunction
(Home) (Ctrl)+(G) Move to the beginning of the command line.
(End) (Ctrl)+(E) Move to the end of the command line.
(Backspace) Delete the character to the left of the cursor.
(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
FTP 265
Co
mm
an
ds
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:
APPEND local-nameAPPEND local-name remote-name
local-name may contain path specifications, which refer to the location of the file on the local client system. When remote-name 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 con-tain 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 line-ending 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 com-mands. Use the CLOSE command if you want to terminate the session with the FTP site but remain in the FTP client pro-gram.
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/twoDirectory changed to "/one/two"
FTP? cd ..Directory changed to "/one"
266 FTP
Co
mm
an
ds
CLOSE Terminate the current FTP session without exiting from the FTP client. Some servers may display an informational mes-sage when you terminate the session.
FTP? closeGoodbye.
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.commandDELE command successful.
FTP? remove myfile.helpDELE command successful.
FTP? delete temp/myfile.txtDELE 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 for-mat, the information is reformatted before displaying it. Spe-cifically, directory names are either underlined or colored, the file name is moved to the beginning of the line, access permis-sion 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 dis-played exactly as received from the remote server.
This command has three different forms:
DIRDIR filenameDIR dirname
The first form (DIR) displays the directory listing of the current working directory on the remote FTP server.
FTP 267
Co
mm
an
ds
FTP? diraccounts 16 May 2001 5:58pfiles 11 Aug 2001 7:29pprograms 29 Jul 2001 11:37a
FTP? vVerbose mode ON
FTP? dird--------- 1 owner group 0 May 16 15:58 accountsd--------- 1 owner group 0 Aug 11 19:29 filesd--------- 1 owner group 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.cmpConfig.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 dis-played, not the current working directory.
FTP? dir programsprogram1.command 89,020 12 Oct 2001 1:15pprogram2.command 113,920 12 Oct 2001 1:20pprogram3.command 77,160 2 Nov 2001 8:12a
See also: LS, SAVEDIR and SAVELS commands.
EXIT Terminate the current FTP session and exit the FTP environ-ment. 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:
HELPHELP cmd-name
The first form displays all command names and abbreviations available in the FTP client environment.
268 FTP
Co
mm
an
ds
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.
APPEND CLOSE LCD MODE RD SENDASCII DELETE LMD OPEN RECV SHELL
...
The second form displays the specific help text for cmd-name.
FTP? h lcdSyntax: LCD <directory> (change local directory)
LCD Change the current working directory on the local client sys-tem and display the new current working directory. The com-mand name must be followed by the path to the new directory.
FTP? lpwdLocal directory: (null)
FTP? lcd faxLocal directory: /FAX:S
Note: When the FTP client exits, your current working direc-tory is restored to the directory in use at the time that FTP was invoked.
LDIR Similar to the DIR command, this command displays a direc-tory 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:
LDIRLDIR filename
The first form (DLIR) displays the directory listing of the cur-rent working directory on the local system.
FTP 269
Co
mm
an
ds
FTP? lcd tipsLocal directory: /TIPS:S
FTP? ldiraol.tip 1,454 2 Sep 2000 12:06pconfig.tip 2,950 12 Nov 2000 2:04pftp.tip 557 2 Sep 2000 11:54a...
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.
FTP? ldir /data/*.*misc 15 Sep 2001 1:29p
See also: LLS command.
LLS Display the directory listing from the local system for the cur-rent working directory, a specific file or group of files. This is similar to the LDIR command but only the file names or direc-tory names are displayed, without any detail about the files or directories.
Like the LDIR command, there are two forms of this command:
LLSLLS filename
The first form displays the files and directories in the current working directory of the local system.
FTP? llsaol.tipconfig.tipftp.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.
270 FTP
Co
mm
an
ds
LMD Creates a new directory on the local client system. The new directory name is specified with the command:
LMD dirname
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 exampleLocal directory: /FAX/EXAMPLE:S
LPWD Display the current working directory of the local client sys-tem.
FTP? lpwdLocal 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 inclu-sion 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 com-mand:
LSLS filenameLS dirname
The first form displays the files and directories in the current working directory of the remote server.
FTP? ls.loginpublic_html.historymail.pinerc
The second form (LS filename) displays a list of files matching filename, which may contain path specifications or wild cards.
FTP 271
Co
mm
an
ds
The third form (LS dirname) displays the files in the specified dirname.
See also: DIR, SAVEDIR and SAVELS commands.
MD 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? lsmyip.htm
FTP? mkdir example
FTP? lsmyip.htmexample
MODE Display the current file transfer mode (ASCII or BINARY). This command is synonymous with the TYPE command.
>ftp (binary
FTP? modeUsing Binary mode to transfer files.
OPEN Establish a new FTP session. Any current FTP session is closed. There are five forms of the command:
OPENOPEN hostOPEN host userOPEN host user passwordOPEN site
Basically, these are all the same command. You are prompted for any information omitted from the command or the site defi-nition. For a description of the host parameter, refer to “Server Specification” on page 260. For a description of user and pass-word, 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.)
272 FTP
Co
mm
an
ds
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.
FTP? openHost-name: ftp.theos-software.comConnecting to ftp.theos-software.com (207.21.75.100)-------------------------------------------------User-name: anonymousPassword: [email protected] 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.comConnecting to ftp.somesite.com (128.100.1.2)--------------------------------------------User-name: mePassword: information messages from ftp serverUser me logged in.
As described in “User Account Specification”, anonymous connec-tions are made by specifying a user name of “anonymous.”
Some servers allow you to use a dash at the start of the pass-word to suppress any information messages. This may not work for all servers.
To terminate the connection, use the QUIT or CLOSE command.
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.
FTP 273
Co
mm
an
ds
QUIT Terminate the current FTP session and exit the FTP environ-ment. This command is synonymous with the BYE and EXIT commands.
FTP? quitThanks for visiting our site.You were online for 0 minutes.
>
The actual text displayed after the QUIT command is depen-dent 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-nameRECV remote-name local-name
remote-name may contain a path specification or wild cards. When no path specification is included, only the current work-ing 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 *.htmReceiving 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 SEC-ONDFI.HTM, respectively.
274 FTP
Co
mm
an
ds
FTP? cd ..Directory change to "/"
FTP? recv WebPages/firstfile.htm5,536 bytes received in 2.3 seconds (2.37 Kbytes/sec)
When the second form of the command is used (RECV remote-name 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.html5,536 bytes received in 5.0 seconds (1,117.48 bytes/sec)
FTP? recv ../WebPages/firstfile.htm webpage1.html5,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 help214-The following commands are recognized
(* => umimplemented)ABOR DELE NLST QUIT RNTO STOUACCT* HELP NOOP REIN SITE* STRUALLO LIST PASS REST* SIZE SYSTAPPE MDTM PASV RETR SMNT* TYPECDUP MKD PORT RDM STAT USERCWD MODE PWD RNFR STOR XCUP
XCWD214 Direct comments to [email protected].
FTP? remote help stat214 Syntax: STAT [<directory>] (status)
FTP? remote stat211-THEOS FTP Server status:
Version 1.0Connected to 209.95.32.4Logged in as PRIVATETYPE: ASCII, FORM: Nonprint; STRUcture: File;
FTP 275
Co
mm
an
ds
transfer MODE: StreamNo data connection
211 End of status.
Responses from the REMOTE command are always displayed with response codes included, independent of the current set-ting of the VERBOSE mode.
The remote SITE command may have additional, site-specific commands available.
REMOVE Synonym to the DELETE command.
RENAME Renames a file on the remote FTP server. There are three forms of this command:
RENAMERENAME old-filenameRENAME 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? renameOld-filename: example.filFile exists, ready for destination nameNew-filename: example.txtFile "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.
276 FTP
Co
mm
an
ds
FTP? rmdir temptemp: File exists.
FTP? cd tempDirectory change to "/temp"
FTP? delete myfile.commandDELE command successful.
FTP? cd ..Directory change to "/"
FTP? rd tempDirectory "temp" removed.
SAVEDIR Similar to the DIR command except that the output is saved in a file. The format of the command is:
SAVEDIR filenameSAVEDIR filespec filenameSAVEDIR 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 list-ing format used the LS command format. The format of the command is:
SAVELS filenameSAVELS filespec filenameSAVELS 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-nameSEND local-name remote-name
FTP 277
Co
mm
an
ds
In the first form (SEND local-name), the local-name may con-tain 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 specifi-cation, the files are located on the local client system using that path specification.
The file or files are sent to the remote server and saved in its current working directory (PWD).
FTP? send path/file.name
is equivalent to:
FTP? send path/file.name file.name
If local-name includes wild-card specifications, all files match-ing 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 remote-name), both names may include path specifications. However, wild cards are not allowed. The remote-name specifies the spe-cific location and name used to save the file on the remote sys-tem.
FTP? send *.htmSending "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.one139 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.
278 FTP
Co
mm
an
ds
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:
SHELLSHELL 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 SHELLType "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 datathe 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:
USERUSER nameUSER 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.”
FTP 279
Co
mm
an
ds
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? userUser-name: mynamePassword:User MYNAME logged in.
VERBOSE 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? verboseVerbose mode ON
FTP? pwd257 "/e/download/os/" is current directory.
FTP? recv ftp.cmp200 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? vVerbose mode OFF
FTP? recv ftp.cmp63,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 12-hour form with an “a” or “p” indicator.
With VERBOSE mode ON, the directory information is dis-played exactly as received from the remote server. For exam-ple:
280 FTP
Co
mm
an
ds
FTP? vVerbose mode OFF
FTP? dirConfig.cmp 336 26 Feb 2001 6:21pFAX.C 13,080 30 Jan 2001 5:05pFTP.CMP 63,632 16 Jul 2001 12:08p
FTP? vVerbose mode ON
FTP? dir200 PORT command successful.150 Opening ASCII mode data connection for /bin/ls.-rwxrwxrwx 1 owner group 336 Feb 26 18:21 Config.cmp-rwxrwxrwx 1 owner group 13080 Jan 30 17:05 FAX.C-rwxrwxrwx 1 owner group 63632 Jul 16 12:08 FTP.CMP226 Transfer complete.
VIEW 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 com-plete, 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] /downloadscd theos/theos32recv sp*.zipquit
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.
FTP 281
Co
mm
an
ds
>ftp example.ftp (file
open ftp.theos-software.com anonymous [email protected] to ftp.theos-software.com (207.21.75.100)------------------------------------------------------Welcome to THEOS Software Corporation FTP site.Anonymous user logged in.------------------------------------------------------
binaryUsing Binary mode to transfer files.
lcd /downloadsLocal directory: /DOWNLOADS:S
cd theos/theos32CWD command successful.
recv sp*.zipReceiving SP40210.ZIP (1 of 1)477,742 bytes received in 161.8 seconds (2.95 Kbytes/sec)
quitGoodbye
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] (receivetheos/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-passwordbinarylcd /databasecd /master.files/databaseget *.*cd /private.files/databaseget *.*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 direc-tory 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 ter-minated 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 exe-cuted, interactive mode is entered. At this point you can perform other operations and exit when you desire.
282 FTP
Co
mm
an
ds
GetFile 283
Co
mm
an
ds
GetFile Command
This command accesses a DOS-formatted disk or partition and copies files from it.
This command’s function has been replaced with the DOSDiskA and DOS-DiskC 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: *.*:FFilename Size Date TimeINSTALL.BAT 1 10/25/01 14:36OEMSETUP.INF 1 10/25/01 14:51README DIR 10/25/01 14:28README.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/*.*:FFilename Size Date TimeDECNET.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:
1 GETFILE drive ( DIR
2 GETFILE DOS-file:drive file ( dos-options options
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 QUERYOWN=nn NOQUERY
dos-options » BINARYHIDDEN
284 GetFile
Co
mm
an
ds
>getfile a: (dir
>getfile f (dir
Similarly, the following two commands are interpreted identically:
>getfile /dos/:f (dir
>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 termi-nated 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:
GetFile 285
Co
mm
an
ds
>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 file. This is a default option when wild cards are not used.
>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 sOk 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.
286 GetFile
Co
mm
an
ds
Notes • Wild-Card Specifications
Similar to the CopyFile command, the destination file specification may use the equal sign character ( = ) to indicate that the destination file descrip-tion 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 descrip-tion uses a wild card then the equal sign is replaced with the portion repre-sented 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 corre-sponding 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 and Disks
The disk drive specified by drive may be an attached removable 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.
>getfile s (dir
>getfile /windows/*.*:s
>getfile /dos/ansi.sys:s =.=:s (bin"/DOS/ANSI.SYS:S" copied to "ANSI.SYS:S".
GetFile 287
Co
mm
an
ds
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 fail-ure.
See also CopyFile, CRLF, PutFile, Receive, THEO+COM
288 GetFile
Co
mm
an
ds
Head 289
Co
mm
an
ds
Head Command Filter
The Head command displays the beginning of a text file on the standard output device.
Operation 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 nor-mally be used in a pipe command line:
>calendar 2001 | headJanuary 2001 February 2001 March 2001 Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 1 2 3 1 2 3 7 8 9 10 11 12 13 4 5 6 7 8 9 10 4 5 6 7 8 9 10 14 15 16 17 18 19 20 11 12 13 14 15 16 17 11 12 13 14 15 16 17 21 22 23 24 25 26 27 18 19 20 21 22 23 24 18 19 20 21 22 23 24 28 29 30 31 25 26 27 28 25 26 27 28 29 30 31
April 2001 May 2001 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 (4ACCOUNT 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 Specifies the number of lines of each file to output. This specifi-cation must be in the range 1–999. The default value is 10.
Notes When the standard output device is the console and multiple files are spec-ified, 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.
1 HEAD ( option
2 HEAD file... ( option
file » file name with optional path
option » nnn
290 Head
Co
mm
an
ds
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
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
Help 291
Co
mm
an
ds
Help Command
The Help command displays a summary of all THEOS commands or a detailed description about a specific command.
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 descrip-tion.
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.
1 HELP
2 (F1)
3 HELP program
4 program(F1)
5 HELP *
program » command name or valid abbreviation
292 Help
Co
mm
an
ds
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.
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.
Help 293
Co
mm
an
ds
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 provid-ing information about:
Subject 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.
* This information is normally displayed from within the indicated program. It can be displayed at any time with the Help command.
294 Help
Co
mm
an
ds
Ident 295
Co
mm
an
ds
Ident Command
This command displays the current account number on the standard output device.
Operation The account number of the current account is output to the standard output device (normally the console).
>ident5
See also Show WHO, WhoAmI
IDENT
296 Ident
Co
mm
an
ds
Img 297
Co
mm
an
ds
Img Command
The Img command displays graphic image files on the graphics console.
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 dis-played 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 win-dow. 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 file ( options
file » file name with optional path; may contain wild cards
options » CENTER FRAME MAXIMIZE SLIDESHOWCYCLE KEEP NOFRAME WAIT
298 Img
Co
mm
an
ds
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.
SLIDESHOW This option is effective only when file is omitted or uses wild-cards. 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:
WAIT nn When displaying a SLIDESHOW, wait nn seconds before auto-matically 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
Key Action
(EnterÌ˛)(PageDown)
Advance to next image.
(PageUp) Backup to prior image.
(Home) Display first image.
(End) Display last image.
(Space) Pause or resume slide show.
(Esc) Terminate slide show.
Install 299
Co
mm
an
ds
Install Command
The Install command installs software from a removable disk or disc drive.
Operation 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 pro-gram 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, CD-ROM, etc.).
When an Install program is found the search is terminated and that Install program is executed.
See also UnInstall
INSTALL drive
drive » optional disk drive letter
300 Install
Co
mm
an
ds
IXDiag 301
Co
mm
an
ds
IXDiag Command
This command checks the integrity of indexed files.
Operation 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 infor-mation about the error condition.
1 IXDIAG file... ( options
file » file name with optional path; may include wildcards
options » APPEND EXEC NOWAIT SUBDIRDATA BASIC FILES RECLEN TYPEDATA BINARY KEYLEN REPAIR VERIFY DATADETAILS LOGFILE REPLACE VOLUMEEXCEPTIONS NOTYPE SAVE WAIT
302 IXDiag
Co
mm
an
ds
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
>ixdiag *.* (detailExamining 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:SIndexed file has 62.9% wasted space which could be recovered if rebuilt
...
>ixdiag *.* (details waitExamining indexed file /DATA/CHECK.DETAIL:S
Bad blocks on freelist - File should be rebuilt?(F1)
Examining indexed file /DATA/CHECK.MASTER:S
Examining indexed file /DATA/EXPENSE.JOURNAL:SIndexed file has 62.9% wasted space which could be recovered if rebuilt
?(F1)
...
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 Indicates that file is an ASCII stream file with each record in the file specifying a single file name. The file name specifica-tions in this file may include the path and wild cards.
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
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.
IXDiag 303
Co
mm
an
ds
The SELECTED.FILES and SELECTED.EXEC files created by FileList and the FOUND.EXEC created by Look can be used for this specifi-cation 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 exam-ined:
>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 fol-lowing 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 key-word. This option tells IXDiag that, when it rebuilds the file it should use the new record-length specified, not the record-length of the existing file.
304 IXDiag
Co
mm
an
ds
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.
Note: This is potentially dangerous operation. The file should be backed up first or copied to another location.
>ixdiag telephon.numbers (repair detailsExamining 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.errorsRecovering SUSPECT.FILE on 23 Nov 2001 02:10PM :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 1717297 records copied, 0 records skipped (17297 total records).
SUBDIR Tells IXDiag to check all subdirectories starting with the direc-tory for file.
>ixdiag s (subdir detailsExamining indexed file /CGI/DATA/CUSTOMER.MASTER:SExamining indexed file /CGI/DATA/ORDERS.DETAIL:SExamining indexed file /CGI/DATA/ORDERS.MASTER:SExamining indexed file /FAX/FAX.LOG:S
Indexed file in use -- diagnostic check skippedExamining indexed file /SAMPLES/SAMPLE.DATA.CUSTOMER:SExamining indexed file /SYSTEM.CALANDAR:S...
TYPE A default option that tells IXDiag to display summary informa-tion 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.
IXDiag 305
Co
mm
an
ds
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:
>ixdiag s (volumePACKAGE\SYSPECT.FILE:S has serious problemsSYSTEM\TELEPHON.NUMBERS needs minor repairs
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 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.
Defaults 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.
306 IXDiag
Co
mm
an
ds
Keyboard 307
Co
mm
an
ds
Keyboard Command
The Keyboard command replaces the current keyboard driver with a different or modified driver.
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:
Restrictions 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 number name
number » Language code number (1–9)
name » Simple file name for new keyboard driver program
Code Language Name Language
1 English (UK) KEYBBE Belgium2 French KEYBCF Canadian French3 German KEYBDK Denmark4 Italian KEYBFR French5 Spanish KEYBGR German6 Swiss KEYBIT Italian7 Spanish (Latin American) KEYBLA Spanish (Latin American)8 French (Canadian) KEYBSF Swiss (French)9 Belgium KEYBSG Swiss (German)
KEYBSP SpanishKEYBUK English (UK)KEYBUS English (United States)
308 Keyboard
Co
mm
an
ds
Keyword 309
Co
mm
an
ds
Keyword Command
The Keyword command displays or maintains the SYSTEM.THEOS32.KEYWORD file.
Operation Mode 1—Display keyword nnn from the /THEOS/OS/MESSAGE/language/KEY-WORD.BIN:S file.
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 Keyword Code Keyword Code Keyword Code Keyword0 Yes 26 TRANs 52 NOSORT 78 HIStory1 No 27 SPECs 53 NOMain 79 ABbrev2 Type 28 TRuncate 54 ATTach 80 RDYmsg3 NOTtype 29 NEWFile 55 TOUch 81 MSG
...
The keywords are shown in mixed case. The uppercase letters in each key-word 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.
1 KEYWORD nnn ( option
2 KEYWORD * ( option
3 KEYWORD
option » NOSORTPRTnnSORTTYPE
310 Keyword
Co
mm
an
ds
When a number is entered, the current definition is displayed and you are asked for the new definition:
>keyword
Enter keyword id: 3
Old text: NOTypeNew 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 con-text.
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 num-ber 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 ABbrev192 ABORT109 ACCount253 ADD179 Alf193 ALign
TYPE A default option that causes Keyword to display the keywords on the console.
Keyword 311
Co
mm
an
ds
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 key-word may affect many commands.
Restrictions You must be logged onto the SYSTEM account and you must have a privilege level of five.
Keywords may be a maximum of eight characters in length.
See also List, Message
312 Keyword
Co
mm
an
ds
Killfile 313
Co
mm
an
ds
Killfile Command
This command erases one or more files from disk.
Although similar to the Erase command the Killfile command is quite differ-ent and potentially very dangerous. Killfile erases a file’s directory entry without deallocating the file’s disk space. You should only use this com-mand 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 direc-tory 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).
1 KILLFILE file ( options
2 KILLFILE file ( FILES options
3 KILLFILE ( options
file » file name with optional path; may contain wild cards
options » NOQUERY QUERYNOTYPE TYPE
314 Killfile
Co
mm
an
ds
This mode of the Killfile command is convenient when one or more sets of files are repetitively being killed.
>edit daily.killwork.master:swork.history:swork.invoices:swork.ledger.*:stemp*.*:ssort*.*: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.
>killfileEnter 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.
Killfile 315
Co
mm
an
ds
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.
NOTYPE 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 speci-fications 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.
316 Killfile
Co
mm
an
ds
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.
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 Erase, FileManager, Rename, RmDir
Line 317
Co
mm
an
ds
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 stan-dard 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.outputThe 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, fol-lowed 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
318 Line
Co
mm
an
ds
LineEdit 319
Co
mm
an
ds
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.
Operation 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.textNew file "SAMPLE.TEXT".Edit:*
or
>ledit system.theos32.devnamesOld 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 com-mand.
There is an internal help display available in LineEdit that can be invoked by pressing (F1). This help display summarizes all of the commands avail-able while using the LineEdit command.
LINEEDIT file ( option
file » file name with optional path; wild cards not allowed
option » BACKUPNOBACKUP
Command synonym: LEDIT
320 LineEdit
Co
mm
an
ds
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
Help Ask for help
Input [text] Insert a line or Insert mode
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
TOp Go to top of file
Type [#lines] Display lines
Up [#lines|/str/] Go up
VErify [on|off] Verify (display) status
X,Y,Z [#lines|statement|"filename" [line#]]
Macro
Table 6: LINEEDIT Command Summary
LineEdit 321
Co
mm
an
ds
Options BACKUP A default option that tells LineEdit to make a backup copy of the prior version of the text file.
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:
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.
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-writ-ten without renaming it to be a backup of the original.
File: TEXT.FILE LIBNAME.LIBTYPE.TEXT
1st choice: account.BACKLIB.TEXT LIBNAME.BACKLIB.TEXT
2nd choice: TEXT.BACKUP account.BACKLIB.TEXT
3rd choice: TEXT.BACKUP
Table 7: LINEEDIT Backups
322 LineEdit
Co
mm
an
ds
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;&begstackfind DATEup 1input CUSTOMER 2file&end
lineedit system.theos32.synonym
>updsynOld file "SYSTEM.THEOS32.SYNONYM:S".Edit:*f DATEDATE 4*u 1CRT 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.
List 323
Co
mm
an
ds
List Command
List displays the contents of any data or program file on the standard output device.
Operation 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 spec-ified 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.”
1 LIST file... ( option
2 LIST - ( option
file » file name with optional path; may contain wild cards
option » BINARY HEAD OLDDATE TRUNC nnnCOMnn HEX PAGE nnn fromlineFILES INDENT nn PRTnn tolineFORMAT NOHEAD TITLE tttFROM kkk NUMBERED TO kkk
324 List
Co
mm
an
ds
Options 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 specifica-tions 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 specifi-cation 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 exam-ined:
>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 fol-lowing 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 format-ting 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 char-acter 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.
List 325
Co
mm
an
ds
These codes are:
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 dis-play.
This option can be used with or without the TO option.
>list keyword.bin (from 20 nohead
020: 1QUERY021: 2NOQUERY022: 5PRIVATE...
>list customer.master (from "Conc" trunc 47 noh
Concrete Consultants, Inc.: "1300 Southwest EveContinental 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 dis-play. 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.
Code Meaning
1 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
326 List
Co
mm
an
ds
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.
>list /theos/help/english/list.hlp (numbered nohead
1 <html>2 <head>3 <title> THEOS Help for List Command </title>4 <BODY>5 <a name=”TOP”><center><h2><font color=#FF0000>
...
>list /theos/help/english/list.hlp (nohead
<html><head><title> THEOS Help for List Command </title><BODY><a name=”TOP”><center><h2><font color=#FF0000>...
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 num-ber 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 23 Mar 2002 11:55am Page 1
GUTENB1 12:136:0 SPO C241,W8;Jupiter.cpw.lan - HP LJ 4 PlusGUTENB2 21:136:1 SPO C241,W8;Jupiter.cpw.lan - HP DeskJet 690CGUTENB3 22:136:2 SPO C241,W8;Jupiter.cpw.lan - Phaser 860DP...
List 327
Co
mm
an
ds
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 dis-play.
This option can be used with or without the FROM option.
TRUNCATE Each line output is truncated at column nnn. If used in com-bination with the INDENT nn option, the truncation is per-formed 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.
328 List
Co
mm
an
ds
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
<html><head><title> THEOS Help for Cat Command </title><BODY><a name="TOP"<center><h2><font color=#FF0000>Cat Command</font></h2></center><pre>...
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 redi-rected 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 recog-nized. Refer to “Multiple-page Display Browsing” on page 79 of the THEOS Corona Version 5 Operating System Reference. In addition to these stan-dard 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.
List 329
Co
mm
an
ds
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
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 23 Oct 2001 8:26am Page 1
KEY:0000: 41414120 56656E64 696E6720 53706563 'AAA Vending Spec'0010: 69616C69 73747300 00000000 00000000 'ialists.........'0020: 00000000 00000000 '........'DATA:0000: 041A3132 38323820 536F7574 68776573 '..12828 Southwes'0010: 74205061 726B2050 6C616365 0400040D 't Park Place....'0020: 43617374 726F2056 616C6C65 79040243 'Castro Valley..C'...
or
>list system.theos32.keyword (hex
SYSTEM.THEOS32.KEYWORD 23 Oct 2001 8:26am Page 1
Direct record: 1, reclen: 100000: 31594553 20202020 200D '1YES .'Direct record: 2, reclen: 100000: 314E4F20 20202020 200D '1NO .'...
330 List
Co
mm
an
ds
This HEX display is similar to the BINARY display except each record is dis-played 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.
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 envi-ronment 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.
Load 331
Co
mm
an
ds
Load Command
The Load command loads a program or data file into memory for subsequent usage.
Operation The program is loaded into memory. When program is a simple name, the following locations are searched:
/THEOS/COMMAND/program.CMDprogram.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 program...
program » name of program or file to load into memory
332 Load
Co
mm
an
ds
Caution Do not make changes to programs or files (with LineEdit, Patch, recompila-tion, 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
LogName 333
Co
mm
an
ds
LogName Command
Displays the account name that you are logged onto.
Operation The current account name is output to the standard output device.
>logon develop
>lognameDEVELOP
See also Ident, Show WHO, WhoAmI
LOGNAME
334 LogName
Co
mm
an
ds
Logoff 335
Co
mm
an
ds
Logoff CommandLogon Command
The Logoff command logs off of the current account; the Logon command logs onto a new account.
Operation 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 “Sys-tem History File” on page 217 of the THEOS Corona Version 5 Operating System Reference.
All privately attached devices (other than the console, slave print-ers 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.
1 LOGOFF
2 LOGON account ( option
account » account name
option » NOEXEC NOTERM TERM
336 Logon
Co
mm
an
ds
>logoff
Logoff at 9:12am PDT on Wednesday, October 16, 2001.
Duration 1:48:36, cpu 53.780.
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 pass-word.
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 spec-ify 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
Logon 337
Co
mm
an
ds
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 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.
The system’s time-of-day clock is adjusted for any change in day-light 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 termi-nated.
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 “Sys-tem 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).
338 Logon
Co
mm
an
ds
Options NOEXEC Do not execute the account EXEC.
NOTERM Do not terminate execution of the EXEC calling the Logon com-mand. This is a default option.
TERM Terminates execution of an EXEC program if it was executing when Logon was invoked.
Notes When the user is connected via a network connection, use the Exit com-mand to log off and disconnect the user.
Neither the Logoff nor the Logon commands clear the console display. How-ever, 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
Look 339
Co
mm
an
ds
Look Command
The Look command searches files for specific text.
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:S3 <title> Help for Look Command </title>
17 Unlike other commands, the options38 >LOOK SYSTEM. 32.DEVNAMES ("Wyse"
1 LOOK file ( pattern ...
2 LOOK file ( option pattern ...
3 LOOK pattern
file » file name with optional path; may include wild cards
pattern » text string to look for; may contain “regular expressions”
option » APPENDEXECFILES
THEOSTHEOS
THEOS
340 Look
Co
mm
an
ds
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.”
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 exist-ing 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 /THEOS/HELP/ENGLISH/B3220.HLP:S &2 &3 &4 &5 &6 &7 &8 &9 &10&1 /THEOS/HELP/ENGLISH/BASIC32.HLP:S &2 &3 &4 &5 &6 &7 &8 &9 &10&1 /THEOS/HELP/ENGLISH/CHANGE.HLP:S &2 &3 &4 &5 &6 &7 &8 &9 &10&1 /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 specifica-tions 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 pro-gram.
For instance, the FileList is used to create a list of files to be examined:
>filelist /Theos/Help/English/*.* (10/1/01 exec append
Look 341
Co
mm
an
ds
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.”
>look selected.exec (files exec "PRT"
>look found.exec (files "SORT"
File: /THEOS/HELP/ENGLISH/ACCOUNT.HLP:S40 SORT When used with the TYPE or PRT
...
Notes When one or more options are used, they must be specified before any pat-tern. 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 non-stream 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 reg-ular expression is a sequence of characters consisting of literal charac-ters and metacharacters.
Literal characters are characters that match in a one-for-one relation-ship with the text in the file. For instance, the search pattern “abc” is com-
342 Look
Co
mm
an
ds
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.’
In addition to the normal ASCII characters, you may specify certain con-trol characters as literal characters. These control characters must be specified with the following codes:
A metacharacter is a character or group of characters that represents something other than themselves. The wild cards allowed for file specifica-tions by most of the THEOS commands are examples of metacharacters.
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
Look 343
Co
mm
an
ds
The following table shows all of the metacharacters allowed in regular expressions.
• 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.
Specification Meaning
\^ Anchor to start of line.
\$ Anchor to end of line.
\. or \? 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
344 Look
Co
mm
an
ds
• 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:
"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 speci-fied 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 begin-ning 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\]"
Look 345
Co
mm
an
ds
means a match on any character except uppercase letters. When the cir-cumflex is used in a position other than at the start, it is merely a charac-ter included in the set.
• Regular Expression Repeat Counts
A search pattern may be repeated by using the repeat metacharacters “\” and “\” to enclose the minimum and maximum repeat counts. For instance, the pattern:
" \@\4,6\\[ .\]"
means that you want a match on a space, followed by four to six letters, fol-lowed 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 specifica-tion 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.
346 Look
Co
mm
an
ds
Lowcase 347
Co
mm
an
ds
Lowcase Command Filter
Lowcase copies a file to the standard output device, converting all letters to lowercase.
Operation 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.txtaccount 3archive 2asm32 3attach 1...
>lowcase /Theos/OS/Message/English/synonym.txt > synonym.list
Mode 2—Copies standard input to standard output, converting all upper-case letters to lowercase. This form is normally used only in a pipe. How-ever, 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
1 LOWCASE file
2 LOWCASE
file » file name with optional path; wild cards are not allowed
Command synonym: LC
348 Lowcase
Co
mm
an
ds
Mailbox 349
Co
mm
an
ds
Mailbox Command
The Mailbox command sends a message to another user’s mailbox or retrieves your mes-sages.
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 shirleyEnter 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.
1 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 » PURGEPURGE *
350 Mailbox
Co
mm
an
ds
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, quota-tion 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.
>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
Mailbox 351
Co
mm
an
ds
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.
Options 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.
Notes 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
352 Mailbox
Co
mm
an
ds
MakeBoot 353
Co
mm
an
ds
MakeBoot Command EXEC
MakeBoot creates an Emergency Boot Diskette using the current operating system and configuration.
Operation 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 for-matted. MakeBoot formats the diskettes using the highest capacity avail-able 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 dis-kette (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 addi-tional files and programs if there is sufficient room for them.
MAKEBOOT drive
drive » optional disk drive attachment letter
354 MakeBoot
Co
mm
an
ds
MAKEBOOT Files:
The files copied to this “Emergency Boot Diskette” include:
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/DRIVER/FORM2.SYS
SYSGEN configuration /THEOS/CONFIG/SYSGEN.CFG/THEOS/CONFIG/INSTLIST.CFG
/THEOS/CONFIG/LANGCODE.CFG
Accounting structure /THEOS/CONFIG/ACCOUNT.BIN
System support files /THEOS/OS/LOADER3.SYS
/THEOS/OS/LOADER4.SYS
/THEOS/OS/LOADER5.SYS
/THEOS/OS/PCMCIA.SYS/THEOS/OS/CLOCK.SYS
/THEOS/CONFIG/DEVNAMES.TXT
/THEOS/OS/RESMGR.SYS
/THEOS/OS/MBR.SYS/THEOS/OS/LOAD04GB.SYS
/THEOS/OS/LOAD0LFS.SYS
/THEOS/OS/SESSMAN.SYS
/THEOS/OS/WM.SYS/THEOS/OS/MESSAGE/ENGLISH/KEYWORD.BIN
/THEOS/OS/MESSAGE/ENGLISH/MESSAGE.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/MESSAGE/ENGLISH/SYNONYM.TXT
Commands /THEOS/COMMAND/ATTACH.CMD/THEOS/COMMAND/COPYFILE.CMD
/THEOS/COMMAND/DISK.CMD
/THEOS/COMMAND/FILELIST.CMD
/THEOS/COMMAND/LOGON.CMD/THEOS/COMMAND/MOUNT.CMD
/THEOS/COMMAND/SETUP.CMD
/THEOS/COMMAND/SYSTEM.CMD
/THEOS/COMMAND/TBACKUP.CMD
MakeBoot 355
Co
mm
an
ds
When this “Emergency Boot Diskette” is booted, there are sufficient com-mands 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 com-mands. 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 envi-ronments, 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
Command support files /THEOS/MENU/ENGLISH/ATTACH.MNU
/THEOS/MENU/ENGLISH/DISK.MNU/THEOS/MENU/ENGLISH/FILELIST.MNU
/THEOS/MENU/ENGLISH/FORM2.MNU
/THEOS/MENU/ENGLISH/RESTORE.MNU
/THEOS/MENU/ENGLISH/SETUP.MNU/THEOS/MENU/ENGLISH/TBACKUP.MNU
/THEOS/MENU/ENGLISH/TLOGON.MNU
/THEOS/MENU/ENGLISH/LOADER5.MNU
1. The specific class code currently attached to the main console.
File
356 MakeBoot
Co
mm
an
ds
Message 357
Co
mm
an
ds
Message Command
The Message command displays or maintains the /THEOS/OS/MESSAGE/language/MESSAGE.BIN file.
Operation Mode 1—Displays all of the messages defined in /THEOS/OS/MESSAGE/lan-guage/MESSAGE.BIN.
>message *
0: Logon please: \a1: Password?2: Command not found.\n3: 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.\nNew text:
1 MESSAGE * ( PRTnn
2 MESSAGE
3 MESSAGE nnn operand...
nnn » message number to display
operand » optional argument used by the message
358 Message
Co
mm
an
ds
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 con-tent and codes used, refer to “Message File Syntax” below.
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 ellip-sis.
>message 7Invalid command syntax.
>message 19File "..." not found.
>message 19 abc.def:gFile "ABC.DEF:G" not found.
>message 117 "Wednesday" "August" 7 2001Date is set to Wednesday, August 7, 2001.
Options PRTnn 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.
Message File Syntax
Message text may contain plain text, display codes, video attributes, vari-able arguments and conditional expressions. Plain text includes all of the ASCII displayable characters (letters, digits, punctuation, etc.).
• Display Codes
There are four display codes that can be embedded in a message:
Code Meaning
\a Sound the console bell.
\n Start a new display line.
\t Output spaces to next tab stop.
\\ Output a single backslant character.
Message 359
Co
mm
an
ds
• 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:
• 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.\n34: Device "1" is already attached to process 2.\n
• Conditional Expressions
Messages can use conditional expressions to evaluate the value of a vari-able 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
Code 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.
360 Message
Co
mm
an
ds
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 origi-nal value of variable is used. For instance, message 105 is defined as:
105: 0?0=No,1=One,* file0?1=,s changed.\n
This message will be displayed three different ways depending upon the value of the variable zero.
>message 105 0No files changed.
>message 105 1One file changed.
>message 105 22 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 pro-grams 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 mes-sage text used by the operating system and its utilities. Changing an exist-ing 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 Keyword
Mixer 361
Co
mm
an
ds
Mixer Command
The Mixer command allows you to set the volume for various sound devices and files.
Operation 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
362 Mixer
Co
mm
an
ds
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 com-puter and software on the client system.
Restrictions You must have a sound card configured. Refer to the THEOS Corona Ver-sion 5 Operating System Installation and Setup Guide for a description of Setup SndCard.
See also CDPlayer, Play
MkDir 363
Co
mm
an
ds
MkDir Command
The MkDir command creates a new subdirectory.
Operation Creates a new, empty subdirectory named directory.
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 suffi-
MKDIR directory ( option
directory » new subdirectory name; may include path
option » SIZE
Command synonym: MD
>tree/
>mkdir subdir
>tree/
subdir
>md subdir/sub
>tree/
subdirsub
364 MkDir
Co
mm
an
ds
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.
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.
More 365
Co
mm
an
ds
More Command Filter
More copies a text file to the standard output device with page wait and browse capabilities.
Operation 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.
1 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
366 More
Co
mm
an
ds
Browse Keys When the More prompt is displayed at the bottom of the screen you may use the special More 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
Key Action
(EnterÌ˛) Display next line of file.
(ÌÌSpaceÌÌ) Display next screenful of file.
(D) Display next half-screenful of file.
nnn(F) 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 regu-lar expression as described on page 341.
(!)command Execute CSI command and return.
(?) Display browse help screen.
Table 11: More Command Browse Keys
Mount 367
Co
mm
an
ds
Mount Command
Mount tells the operating system to reread the label information from a drive because the disk might have been changed.
Operation 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:
Restrictions You cannot Mount the S drive. Use the System command instead.
See also Attach, Disk, Reboot, System
MOUNT drive
drive » disk drive letter
Return Code Meaning/Message
0 THEOS disk, mounted successfully201 Disk not ready203 Disk not initialized204 Data transfer error205 Sector not found206 Track not found207 Sector address error563 Disk does not have a THEOS file system on it
368 Mount
Co
mm
an
ds
Move 369
Co
mm
an
ds
Move Command
Move a file or group of files from one location to another.
Operation 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 spec-ification. For each line in file, a Move is performed. Wild cards may be used.
>Move listof.files (files
1 MOVE from-file to-file ( options
2 MOVE from-file to-drive ( options
3 MOVE file ( FILES options
4 MOVE ( options
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 REPLACENOQUERY SUBDIRNOTYPE TYPEQUERY
370 Move
Co
mm
an
ds
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:
>edit daily.filescustomer.master:s /prior/customer.master:scustomer.history:s /prior/customer.history:sgeneral.ledger.*:s /prior/=.=.=:scheck.*: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 ter-minated 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 cop-ied.” message displayed prior to exiting Move) is also sup-pressed with this option.
>move gl.* f (notOk to move "GL.MASTER:S" (Yes,No,All) YOk to move "GL.JOURNAL:S" (Yes,No,All) YOk to move "GL.HISTORY:S" (Yes,No,All) Y
To disable this option use the TYPE option.
Move 371
Co
mm
an
ds
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 iOk to move "CUSTOMER.DATA:S" (Yes,No,All)
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 with-out being queried. Respond with (Esc) to cancel the copy opera-tion.
To disable this option use the NOQUERY option.
REPLACE Allows a file to be moved even if it already exists at the desti-nation 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 spec-ifies 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 keepSYSTEM\samples/tws/images/animals/bear.jpg:S moved to
/COPY/tws/images/animals/bear.jpg:ISYSTEM\samples/tws/images/animals/bird.jpg:S moved to
/COPY/tws/images/animals/bird.jpg:ISYSTEM\samples/tws/images/animals/buttfly.jpg:S moved to
/COPY/tws/images/animals/buttfly.jpg:ISYSTEM\samples/tws/images/animals/wolf2.jpg:S moved to
/COPY/tws/images/animals/wolf2.jpg:ISYSTEM\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.
372 Move
Co
mm
an
ds
Notes 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
Msg 373
Co
mm
an
ds
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.
Operation Mode 1—This is the multi-line mode of the Msg command. When the com-mand 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 TedEnter 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Ì˛).
1 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
374 Msg
Co
mm
an
ds
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.
>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 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.
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 hap-pens, the operation is identical to the Mailbox command.
>msg accounts "Where is my pay check?"
The “Receive messages” field in the account environment prevents mes-sages 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.
Msg 375
Co
mm
an
dsThe “Receive messages” field status is ignored in Mode 3 and Mode 4: The
message is sent to all users that are currently logged on.
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 multi-ple-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 mes-sage.
Restrictions Mode 3 and Mode 4 require a privilege level of five.
You cannot send a message to yourself.
See also Mailbox
376 Msg
Co
mm
an
ds
Net 377
Co
mm
an
ds
Net Command
The Net command controls Corona networking and provides a common interface for many of the functions and simple clients available Corona.
Operation 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.
1 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 program ( program-options exec-options
7 NET RECEIVE file destination-file ( send-rec-options
8 NET SEND file destination-file ( send-rec-options
9 NET SHARE share-name path password access-mode comment
10 NET USE unc-name password
11 NET SERVER
12 NET START server-name
13 NET STOP server-name
14 NET IPCFG
15 NET function parameters
16 NET service host parameters
378 Net
Co
mm
an
ds
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.
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 connec-tion, 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 privi-lege levels may be required of specific functions of the command.
See also DialNet, FTP, NetTerm, Ping, Quote, Setup, Telnet, THEOS WorkStation Client
Net Interactive 379
Co
mm
an
ds
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.
The Ping button provides a means of testing if a host can be accessed over the network or whether or not it is responding.
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
380 Net Interactive
Co
mm
an
ds
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
Net Interactive 381
Co
mm
an
ds
The Trace button traces the route that a packet takes to get from this machine to a target host.
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
382 Net Interactive
Co
mm
an
ds
The IP Cfg button displays the basic configuration information for this sys-tem.
The IPCFG display shows the information for this computer system’s net-work configuration.
See also Net IPCFG
Net Interactive 383
Co
mm
an
ds
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.
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 automati-cally.
384 Net Interactive
Co
mm
an
ds
The information displayed by this function is always in the general form:
Id................ nnnnLength............ length of responseCode.............. xxxxxxxxxxxxxxxxxxxxxxxxQdCount........... number-of-questionsAnCount........... number-of-answer-recordsNsCount........... number-of-nameserver-recordsArCount........... number-of-address-records
Question 1: domain-nameType: n=recordClass: 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.
Net Interactive 385
Co
mm
an
ds
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.
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
386 Net Interactive
Co
mm
an
ds
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 This syntax requests information about the list of user accounts on the mail server.
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.
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
Net Interactive 387
Co
mm
an
ds
The Scan button allows you to perform a scan of a network computer look-ing for active servers.
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 com-mon, known port numbers between From and To.
Each port that responds is reported with the server name associated with that port number.
388 Net ARP
Co
mm
an
ds
Net ARP Command
The Net ARP command displays the Address Resolution Protocol table and allows you to assign an IP address to a network interface card.
Operation Mode 1—Display the Address Resolution Protocol table.
>net arp -a
Interface: 192.168.100Internet Address Physical Address192.168.1.105 00-03-47-D5-24-E1192.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.
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
Net ARP 389
Co
mm
an
ds
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
>net arp -d 192.168.1.103 00-1a-c9-9d-45-df
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.
390 Net Browse
Co
mm
an
ds
Net Browse Command
The Net Browse command scans the local network computers and reports on the systems cur-rently available for network file system access.
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 dis-played.
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
NET BROWSE
Net Exec 391
Co
mm
an
ds
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.
Operation Forces the client system to execute program. You must already be con-nected 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 spec-ifying 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 con-trol to you as soon as the task is started.
NET EXEC program ( program-options exec-options
program » program to execute on client, with parameters
exec-options » MAXIMIZE NORMAL WAITMINIMIZE NOWAIT
392 Net Exec
Co
mm
an
ds
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 pro-gram 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 pro-gram 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 com-pletion 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
Net Receive 393
Co
mm
an
ds
Net Receive CommandNet 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 con-nected to a network.
Operation 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 =.=
1 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
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 NEWFILE OLDER SKIPFILES NOTYPE REPLACE TRANSLATE
url » Uniform Resource Locator of file to receive or send
394 Net Send
Co
mm
an
ds
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
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 mem-ber-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 con-ventions 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 accessi-ble to this client. The remote system and the file to be transmitted is iden-tified 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, cur-rent 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
Net Send 395
Co
mm
an
ds
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.
Files may only be received from an FTP or HTTP server and the appropri-ate 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 pass-word of the owning account on the remote server. When the account is not specified the “anonymous” account is used.
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 Operat-ing 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.
396 Net Send
Co
mm
an
ds
>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.
>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 sys-tem. 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 con-ventions 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 pro-tocol 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.
Net Send 397
Co
mm
an
ds
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 Operat-ing 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.
Abort 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 cre-ated 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 sys-tem.
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 receiv-ing 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
398 Net Send
Co
mm
an
ds
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 sys-tem 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 con-tinue 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 sys-tem’s syntax (CR for THEOS, CRLF for DOS/Windows).
Restrictions This command may only be used when you are connected to the host com-puter using NetTerm, Telnet or THEOS WorkStation client software.
See also DialNet, FTP, NetTerm, Ping, Quote, Setup, Telnet, THEOS WorkStation Client
Net Share 399
Co
mm
an
ds
Net Share CommandNet 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).
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.
1 NET SHARE share-name path password access-mode comment
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
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
400 Net Use
Co
mm
an
ds
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 pass-word 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
Net Server 401
Co
mm
an
ds
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.
Operation 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
402 Net Start
Co
mm
an
ds
Net Start CommandNet Stop Command
The Net Start and Net Stop commands start or stop network servers on this system.
Operation 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 configu-ration 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 mes-sage “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 serv-ers installed on this system. See “Servers” on page 403 for a list and description of these servers.
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 » DHCP LPD NETTAPE THEOPOSTDNS PPP TCP TNFSFTP NETALIVE TDBS TWINDOWSHTTP NETEXEC TELNET WEBMAINTLOGIN NETPRT TFTP
Net Stop 403
Co
mm
an
ds
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 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.
Mode 5—Stops all of the servers that are currently running on this sys-tem. 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 com-mands 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
404 Net Stop
Co
mm
an
ds
The THEOS FTP Server is an optional product available with the WebServer Plus Pak or the NetServer Plus Paks.
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 net-work 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 Cli-ent (Windows-based clients) or the NetTerm (THEOS-based cli-ents).
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
Net Stop 405
Co
mm
an
ds
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.
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.
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.
406 Net Stop
Co
mm
an
ds
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 sim-ple TCP services on this computer. See “Services” on page 412 for a list of these services.
>net start tcp
>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 Ser-vices 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 sys-tem 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 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.
Net Stop 407
Co
mm
an
ds
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.
WebMaint 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
408 Net IPCFG
Co
mm
an
ds
Net IPCFG Command
The Net IPCFG command display various configuration information about the network.
Operation Reports the current network configuration information:
>net ipcfg
Host Name: Saturn
Domain: my.lan
NIC-1: Realtek 8139 10/100 Fast EthernetMAC = 00-00-21-C3-1E-44IP = 192.168.1.100 / 255.255.255.0
Gateway: 192.168.1.1
DNS: 24.0.53.5524.0.53.56
See also WhoAmI
NET IPCFG
Net 409
Co
mm
an
ds
Net function Command
The Net function commands display various configuration information about the network and who is currently connected to the network.
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 Discon-nect 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 AddressAccounting 192.168.87.12Executive 192.168.87.15Administration 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 function
function » DISCONNECT PINGALLPING WHO
410 Net
Co
mm
an
ds
Who All THEOS login servers that this system can access are dis-played along with the client nodes that are actively connected to those servers.
>net who
Restrictions A privilege level of five is required to use the Who function.
See also DialNet, Exit, NetTerm, Ping, Setup, Telnet, THEOS WorkStation Client
Server/Client Connect Date&Time Pid Account
AdministrationExecutiveAccountingPlant
DevelopmentDocumentation
1 Sep 2001 8:15am1 Sep 2001 7:48am1 Sep 2001 5:00am
1 Sep 2001 10:15am
678
9
BradPayrollProducts
Develop
Net service 411
Co
mm
an
ds
Net service Command
The Net service commands establish a client-server relationship between this system (client) and a TCP/IP Simple Services server.
Operation 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.
1 NET service host parameters
2 NET service host parameters
service » CHARGEN ECHO TIME DAYTIME
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
412 Net service
Co
mm
an
ds
Services Chargen Generates a continuous sequence of characters until termi-nated by entry of (Esc). Although trivial, this service is valuable when testing and debugging network applications that use data from a server.
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 charac-ter by one.
>net chargen!"#$&’()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQ...!"#$&’()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQR...
>net chargen 192.168.1.102CHARGEN 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 gener-ate 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 generat-ing 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 daytimeTuesday, 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 informa-tion from another server by specifying a host.
>net daytime time-nw.nist.gov52219 01-11-06 17:54:13 00 0 0 224.7 UTC(NIST) *
Net service 413
Co
mm
an
ds
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.
>net echo>This is a test of the TCP/IP echo command.<This is a test of the TCP/IP echo command.
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 timeTue 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.govTue Nov 06 15:24:45 2001
Note: The above host name is for the National Institute of Standards and Technology (NIST), located in Boulder, Colo-rado. 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 vis-iting the NIST web page at HTTP://WWW.BOULDER.NIST.GOV/TIME-FREQ/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 sys-tem’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.
414 Net service
Co
mm
an
ds
>show time15:11:32 Monday, November 05, 2001.
>net time time-nw.nist.gov (set
>show time15:26:23 Tuesday, November 06, 2001.
See also DialNet, FTP, NetTerm, Ping, Setup, Telnet, THEOS WorkStation Client
NetTerm 415
Co
mm
an
ds
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 net-work.
Operation Mode 1—Invokes the NetTerm command without connecting to any server. NetTerm queries the network to find all of the THEOS servers that are con-nected to the network.
When no other THEOS servers are present on the network, an error mes-sage displays and the program exits.
The names of the available servers are displayed in a menu.
1 NETTERM ( options
2 NETTERM server ( options
3 NETTERM server account ( options
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 accountCTLNOPRTPRTnn
Command synonym: NT
416 NetTerm
Co
mm
an
ds
The list of servers is updated approximately once per second to reflect servers that are joining or leaving the network and servers whose permis-sion 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 Connec-tions” 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 permis-sion 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.
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.
NetTerm 417
Co
mm
an
ds
PRTnn 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.
Default Connections
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 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.NTCFGenviron/SYSTEM.NTCFGaccount.NTCFGSYSTEM.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.”
418 NetTerm
Co
mm
an
ds
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.
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 avail-able 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 neces-sary.
NetTerm 419
Co
mm
an
ds
Unless a different path is specified, the file is received on the server system into the current account, current working directory. An informa-tion window and status bar displays during the transfer.
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 Net-Term 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 exe-cuting 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 pro-grams on that server that you have access to. While connected, the pro-grams 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 connec-tion and you did not use the NOPRT option.
420 NetTerm
Co
mm
an
ds
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.
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 permis-sion to connect to it. Refer to Chapter 5 “Network Security,” starting on page 63 of the THEOS Corona Version 5 Operating System Reference for addi-tional information about access permissions and security issues.
See also Net, Setup, Telnet, THEOS WorkStation Client
Notes 421
Co
mm
an
ds
Notes Command
The Notes command displays and maintains a user’s database of notes and messages to themselves.
Operation 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,
1 NOTES
2 NOTES folder
folder » Directory name for notes files
422 Notes
Co
mm
an
ds
Miscellaneous, Personal, To Do and Unfiled. You may also define your own categories.
The category selected here determines which notes are dis-played in the Notes list box. It also determines the category to be assigned to a New note that you create.
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 Cate-gory 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.
Open This button allows you to change or review an existing note.
Print Prints the selected note on one of the attached printers.
Notes 423
Co
mm
an
ds
Send This button displays another form allowing you to send this note as an e-mail message to someone:
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 cate-gory for the note.
424 Notes
Co
mm
an
ds
Creating New Categories
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:
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 cat-egory 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
NsLookup 425
Co
mm
an
ds
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.
Operation 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.comServer: teleport.comAddress: 192.108.254.10
192.108.254.12
>nslookup www.microsoft.comServer: www.microsoft.comAddress: 207.68.137.62
207.68.156.53207.68.156.54207.68.156.61207.68.156.16207.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.
1 NSLOOKUP domain
2 NSLOOKUP
domain » domain name or IP address or host name
426 NsLookup
Co
mm
an
ds
Mode 2—Enters an interactive mode where you can specify more than one domain before exiting.
>nslookup
Enter name to lookup: ftp.theos-software.comServer: ftp.theos-software.comAddress: 207.21.75.100
Enter name to lookup: ibm.com"ibm.com" not found.
Enter name to lookup: www.ibm.comServer: www.ibm.comAddress: 204.146.17.33
Enter name to lookup: laptopServer: LaptopAlias: Laptop.Documentation-systemAddress: 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 loca-tions until a match is found or until all locations have been searched with-out 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.100Server: theos-software.comAddress: 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 my-companyServer: my-companyAlias: my-company.theos-systemAddress: 192.12826.30
NsLookup 427
Co
mm
an
ds
When domain is found in the host names database, the alias entry is displayed with the host name, dot, your-computer-name. Your-computer-name is defined in the Setup Net Identification. (See THEOS Corona Version 5 Operating System Installation and Setup Guide.)
Or the domain name as defined by the Domain Name Service spec-ified in Setup Net Name Services.
>nslookup www.theos-software.comServer: www.theos-software.comAddress: 207.21.75.100
428 NsLookup
Co
mm
an
ds
Number 429
Co
mm
an
ds
Number Command Filter
Number copies a file to the standard output device, numbering each line as it is copied.
Operation 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.file1 Line one2 Line two3 Line three
>number one.file one.file1 Line one2 Line two3 Line three4 Line one5 Line two6 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.
1 NUMBER file... ( options
2 NUMBER
file » file name with optional path
options » startincrement
430 Number
Co
mm
an
ds
Options start The starting number to use for the first file copied to standard output. The default starting number is one.
increment This option may only be used in combination with start. Speci-fies the increment value for each line number used. The default increment is one.
>number one.file (100 100100 Line one200 Line two300 Line three
Defaults start and increment have default values of one and one.
Restrictions file must be an ASCII stream file.
See also Unnumber
Password 431
Co
mm
an
ds
Password Command
The Password command allows you to change the password to your account.
Operation 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 pass-word 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 com-mand 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 adminis-trator 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
432 Password
Co
mm
an
ds
Patch 433
Co
mm
an
ds
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.
Operation 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. Essen-tially, 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 full-screen display mode. This option is useful when Patch is being invoked from an EXEC program that has &STACK data that automatically updated a file.
1 PATCH file ( options
2 PATCH drive ( options
file » file name with optional path
drive » disk drive letter
options » BINARYNOVIDEO
434 Patch
Co
mm
an
ds
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.
>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 rela-tive 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:
Patch 435
Co
mm
an
ds
Key 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 exit-ing 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, sec-ond 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 dis-played. 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
436 Patch
Co
mm
an
ds
• 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 col-umns. 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 val-ues. Note, when moving left or right with the arrow keys you move by bytes, not “nibbles” (four-bit hexadecimal characters).
(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 opera-tion being performed.
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.
Key Meaning
Table 12: Patch Video Mode Commands
Patch 437
Co
mm
an
ds
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
Most of the Patch commands require an address or data values to be speci-fied. 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:
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 This is the number for 4,66010 or 1234161234t 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 lim-ited to 32 bits which is four bytes or four characters. When more than four characters are specified only the last four are used.
'abcd' This is the value 1,633,837,92410 or 6162636416'AbCdEfGh' This is the value 1,164,330,85610 or 4566476816'EfGh' This is the value 1,164,330,85610 or 4566476816
438 Patch
Co
mm
an
ds
• Operators
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.
• 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 ( $ ).
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
Patch 439
Co
mm
an
ds
For instance:
/a=20000x00002000 (hex), 8192 (dec)/b=a$+10000x00003000 (hex), 12288 (dec)/
Patch Commands
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 addressA
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 339d2000339D2: 7470 jz 33a44000339D4: 8D8551FFFFFF lea eax,(ebp-af)000339DA: 50 push eax000339DB: 90 nop000339DC: 90 nop000339DD: end/
In the above example only the boldface text is entered. Patch supplied all of the other information and assembled the instructions as indicated. To ter-minate 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.
440 Patch
Co
mm
an
ds
Calculator
An expression calculator is available whenever Patch is waiting for a com-mand. 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.
/?abcd0x0000ABCD (hex), 43981 (dec)/?2000-230x00001FDD (hex), 8157 (dec)/?'abcd' 0x61626364 (hex), 1633837924 (dec)/
The calculator always displays the result in both hexadecimal and deci-mal.
Checksum Command
The CHECK command computes the checksum for the entire file or for a region specified.
checkcheck checksumcheck address-rangecheck address-range checksum
It either displays this checksum or compares it to the checksum specified.
/checkChecksum is F602/check 1000 2000Checksum is B75E/check 1000 2000 abcdMismatch./
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
Patch 441
Co
mm
an
ds
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
For instance:
/d 1000 100f001000: E8C70B07 006A0368 FB0F0000 E8BCC707 'ºÍ...j.h....º.Í.'/c 1000 e8 c7 bMatch./c 1000 e8 c7 cMismatch./
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.
442 Patch
Co
mm
an
ds
Display Command
This command displays data from the file, record or sector.
D addressD address-rangeD
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 follow-ing the last line is displayed.
When address-range is not specified, 16 lines of data are displayed.
/d 2000 200f 002000: 055B3BD8 7E0C8B45 F4488945 F8E95700 '.[;«~..E.H.E.¾W.'/d 2000 002000: 055B3BD8 7E0C8B45 F4488945 F8E95700 '.[;«~..E.H.E.¾W.'002010: 0000FF35 3C51FFFF 8B45F448 8D048500 '...5<Q...E.H....'002020: 0000005B 8B04180F B6400450 8B45080F '...[....Ë@.P.E..'002030: B640055B 3BD87D09 8B45F440 8945FCEB 'Ë@.[;«[email protected].ß'002040: 288B4508 4050FF35 3C51FFFF 8B45F448 '([email protected]<Q...E.H'002050: 8D048500 0000005B 8B04188B 40055B89 '.......[....@.[.'002060: 038B45F4 E91F0000 00EB1683 7DF0007E '..E.¾....ß....~'002070: 098B45F4 488945F8 EB078B45 F4408945 '..E.H.E.ß[email protected]'002080: FCE9CCFE FFFF33C0 8BE55DC2 0400B804 '.¾Ï...3ƒ.•]‚..=.'002090: 000000E8 34FB0600 8B450C8B 00FF308B '...º4....E....0.'0020A0: 45088B00 FF308B45 0C8B000F B6400450 'E....0.E....Ë@.P'0020B0: 8B45088B 000FB640 045B3BD8 7D0B8B45 '.E....Ë@.[;«..E'0020C0: 0C8B000F B64004EB 098B4508 8B000FB6 '....Ë@.ß..E....Ë'0020D0: 400450E8 538A0700 8945FC85 C074088B '@.PºS....E..ƒt..'0020E0: 45FCE93A 0000008B 450C8B00 0FB64004 'E.¾:....E....Ë@.'0020F0: 508B4508 8B000FB6 40045B93 2BC38945 'P.E....Ë@.[.+‡.E'/
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.
Patch 443
Co
mm
an
ds
Fill Command
This command fills a block of the file with a single value.
F address-range value
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.
/d 2000 200f002000: 055B3BD8 7E0C8B45 F4488945 F8E95700 '.[;«~..E.H.E.¾W.'/f 2000 2008 0/d 2000 200f002000: 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 sectorG
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 com-mand is valid only when patching those types of files.
K keyK
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.
444 Patch
Co
mm
an
ds
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.
LenLen HEAP sizeLen STACK size
For instance:
>patch sample.stream (novideo/lenLength = 2,031/
>patch sample.direct (novideo/lenLength = 280 Reclen = 28/
>patch sample.indexed (novideo/lenLength = 3,593,330 Keylen = 10 Reclen = 36/
>patch sample.command/lenLength = 92,824
Code = 0x00012834Data = 0x00004098Stack = 0x00002000Heap = 0x0000C350Entry = 0x00000140Type = 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.
Patch 445
Co
mm
an
ds
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
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 restric-tion does not apply when patching disk sectors.
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 30000000: 54686973 20697320 6A757374 20612074 'This is just a t'000010: 65737420 66696C65 20746F20 62652075 'est file to be u'000020: 73656420 62792074 68652050 41544348 'sed by the PATCH'000030: 20636F6D 6D616E64 2E0D0D54 68697320 ' command...This '/m 0 10 20/d 0 30000000: 54686973 20697320 6A757374 20612074 'This is just a t'000010: 54686973 20697320 6A757374 20612074 'This is just a t'000020: 54686973 20697320 6A757374 20612074 'This is just a t'000030: 20636F6D 6D616E64 2E0D0D54 68697320 ' 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 30000000: 54686973 20697320 6A757374 20612074 'This is just a t'000010: 65737420 66696C65 20746F20 62652075 'est file to be u'000020: 73656420 62792074 68652050 41544348 'sed by the PATCH'000030: 20636F6D 6D616E64 2E0D0D54 68697320 ' command...This '/m 10 20 10/m 0 10 10/d 0 30000000: 54686973 20697320 6A757374 20612074 'This is just a t'000010: 54686973 20697320 6A757374 20612074 'This is just a t'000020: 65737420 66696C65 20746F20 62652075 'est file to be u'000030: 20636F6D 6D616E64 2E0D0D54 68697320 ' command...This '/
446 Patch
Co
mm
an
ds
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.
/d 0 30000000: 54686973 20697320 6A757374 20612074 'This is just a t'000010: 65737420 66696C65 20746F20 62652075 'est file to be u'000020: 73656420 62792074 68652050 41544348 'sed by the PATCH'000030: 20636F6D 6D616E64 2E0D0D54 68697320 ' command...This '/m 0 5 45t/d 0 30000000: 54686973 20546869 73205468 69732054 'This This This T'000010: 68697320 54686973 20546869 73205468 'his This This Th'000020: 69732054 68697320 54686973 20546869 'is This This Thi'000030: 73206F6D 6D616E64 2E0D0D54 68697320 's ommand...This '
Patch Level Command
The PL command displays and sets the current patch level for a program file.
PL patch-levelPL
Patch levels may only be assigned to program files. The PL command always displays the current patch level for the program.
/plOld patch level:New patch level: 40001/pl 40002Old 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 com-mand described on page 65 and it can be viewed with the FileList command described on page 229.
Patch 447
Co
mm
an
ds
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 keyP sectorP
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.
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 200f002000: 54686973 20697320 6A757374 20612074 'This is just a t'/r 2000 15 23 0f 2d/d 2000 200f002000: 15230F2D 20697320 6A757374 20612074 '.#.- is just a t'/r 2000 'Now is the time '/d 2000 200f002000: 4E6F7720 69732074 68652074 696D6520 'Now is the time '
448 Patch
Co
mm
an
ds
Search Command
The S command locates an occurrence of a specified series of values.
S address value-list
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? yMatch 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 20000x00002000: 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 inter-preted 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 “Expres-sions” on page 437. You may set it to a string of ASCII characters by enclos-ing 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. Termi-nate entry with (EnterÌ˛) and the values are set and the S command termi-nates.
Patch 449
Co
mm
an
ds
/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 2013002000: 002314CD 00546869 73206973 20612074 '.#.Ì.This is a t'002010: 65737400 C083E001 741EA180 C0FFFFF6 'est.ƒ.™.t.¿.ƒ...'/
Use Command
The USE command tells Patch to use either 16-bit or 32-bit instructions when using the Assemble Command.
Use 16Use 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 pro-gram 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).
450 Patch
Co
mm
an
ds
Changes made to a record must be saved with the Put Command (in com-mand mode) or the (Save) command (in video display mode).
• Program Files
Patching a program file causes Patch to start in command mode with the 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 Com-mand (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.
Peek 451
Co
mm
an
ds
Peek Command
The Peek command allows you to see what is displayed on another user’s console.
Operation 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 char-acter 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 permis-sion.
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
1 PEEK name
2 PEEK process
name » account name
process » process number
452 Peek
Co
mm
an
ds
Ping 453
Co
mm
an
ds
Ping Client
The Ping client allows you to broadcast a “Are you there?” or a “Who’s there?” query to a spe-cific node or to all nodes on the local intranet.
Operation Mode 1—Invokes the interactive or windowed display mode of this com-mand. 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.
1 PING
2 PING address... ( options
3 PING *
4 PING * *
address » node IP address or name (may also be localhost)
localhost » LOCALHOST
options » NOTYPE
454 Ping
Co
mm
an
ds
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
Host: Accounting, address: 192.168.87.12round-trip time = 2 milliseconds.
>ping 192.168.87.15
Host: Executive, address: 192.168.87.15round-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 com-mand.
>ping *
Network Broadcast Ping
Name AddressAccounting 192.168.87.12Executive 192.168.87.15Admin 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 net-work 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
Play 455
Co
mm
an
ds
Play Command
The Play command plays WAV files through the system’s sound card.
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 speci-fication the Play command merely exits.)
>play c*
It is not necessary to specify the file-type unless you want to play wav-format sound files with a file-type other than WAV.
1 PLAY file
2 PLAY wildcard-file
3 PLAY
4 PLAY STOP
file » file name with optional path; may contain wild cards
wildcard-file » file name using wildcard specifications with optional path
456 Play
Co
mm
an
ds
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 play-ing causes the currently playing sound to be stopped and the new sound started.
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 sys-tem’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 com-mand 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 Distrib-uted Window Manager features for “Distributed Sound and Video.” The sound is played through the Windows machine’s speakers.
See also CDPlayer, Mixer
POP3Test 457
Co
mm
an
ds
POP3Test Command
The POP3Test command tests an e-mail account on the email server (POP3 server).
Operation 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 case-sensitive 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 pro-gram to create and maintain this configuration file as there is with most other configuration files.
1 POP3TEST account@host password
2 POP3TEST account@host
3 POP3TEST account
account » E-mail account name
host » Domain or host of account
password » Password for account
458 POP3Test
Co
mm
an
ds
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.
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 com-mand are:
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
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
Printer 459
Co
mm
an
ds
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.
Operation 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.
1 PRINTER
2 PRINTER PRTnn
PRTnn » Attached printer
460 Printer
Co
mm
an
ds
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.
The display on your printer will, of course, be dependent upon your printer’s capabilities.
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
Printer 461
Co
mm
an
ds
• 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 align-ment.
• Column Registration
Displays a columnar pattern.
• Line Registration
Displays lines of repetitive characters. This pattern can be used to deter-mine if lines of text are printed straight on the printer.
!"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcde!"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdef"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefg#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefgh
!"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcde!"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcde!"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcde!"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcde!"#$%&'()*+,-./0123456789:;<=>?ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcde
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""#####################################################################$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
462 Printer
Co
mm
an
ds
• Line Graphics
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.
Most printers do not support the rounded corner characters. If your printer does not then define them with the normal square corner charac-ters.
• National Characters
Displays all of the international characters supported by the THEOS char-acter 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
Ú = 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
PutFile 463
Co
mm
an
ds
PutFile Command
The PutFile command copies a file from this system to a DOS-formatted hard disk partition or diskette.
This command’s function has been replaced with the DOSDiskA and DOS-DiskC 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 =.=:fOk 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 mem-bers or files whose file type is longer than three characters.
1 PUTFILE file DOS-file ( options
2 PUTFILE drive ( CLEAR
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 QUERYEOF RDONLYHIDDEN SUBDIRNOQUERY SYSTEM
464 PutFile
Co
mm
an
ds
Mode 2—Clears the directory on the DOS formatted diskette.
>putfile f (clearEnter disk label: DosXfer
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 con-tent 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 spec-ifications is to be copied. This is a default option when wild cards are used.
>putfile readme/*.txt:s fOk 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 with-out being queried. Respond with (Esc) to cancel the copy opera-tion.
To disable this option use the NOQUERY option.
RDONLY Sets the “read only” file attribute on the DOS disk for the files transferred.
PutFile 465
Co
mm
an
ds
SUBDIR 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.
Notes 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 and Disks
The disk drive specified by DOS-file or drive may be an attached remov-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-for-matted 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
466 PutFile
Co
mm
an
ds
PWD 467
Co
mm
an
ds
PWD Command
This command displays the current working directory.
Operation The current working directory is displayed on the standard output device.
>pwd/LETTERS/PERSONAL:S
>show subdirSUBDIR = /LETTERS/PERSONAL:S
Notes PWD stands for print working directory.
See also Account, ChDir, FileManager, Logon, Show
PWD
468 PWD
Co
mm
an
ds
Quote 469
Co
mm
an
ds
Quote Client
The Quote client queries a quote server for the next random quotation.
Operation Mode 1—Displays a random quotation from the /THEOS/CONFIG/NET-QUOTE.TXT:S database.
>quoteThe difference between the right word and the almostright word is the difference between lightning anda 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 spec-ified 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.
1 QUOTE
2 QUOTE server
localhost » LOCALHOST
server » network server name or id (may also be localhost)
470 Quote
Co
mm
an
ds
Examples >quoteLife is so unlike theory.--Anthony Trollope
>quoteTime is that quality of nature which keeps eventsfrom happening all at once. Lately it doesn’t seem tobe working.--Anonymous
Reboot 471
Co
mm
an
ds
Reboot Command
The Reboot command shuts down and then reboots the computer.
Operation 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 serv-ers 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.
1 REBOOT
2 REBOOT ( option
option » DOS NOTYPE SHUTDOWN UPDATEFAST QUERY SINGLE WINDOWSLINUX REBOOT THEOSNOQUERY RESET TYPE
472 Reboot
Co
mm
an
ds
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.
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 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 loca-tions 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 pri-mary 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 pro-gram.
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.
Reboot 473
Co
mm
an
ds
REBOOT 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 speci-fied, the Reboot Menu is displayed with the “Shut down” item preselected.
SINGLE Reboot the THEOS Corona primary disk partition without dis-playing 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 dis-playing 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 pri-mary disk partition without displaying the Reboot Menu. This option is only valid if there is a DOS/Windows primary parti-tion on the disk drive. If the TYPE option is also specified, the
474 Reboot
Co
mm
an
ds
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.
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 termi-nated 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 com-pleted.
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.
Reboot 475
Co
mm
an
ds
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:
A system with THEOS Corona, THEOS 4.2 and Microsoft Windows installed on it will display the following reboot menu:
476 Reboot
Co
mm
an
ds
Shutdown Status
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.
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 stop-ping each server and task.
Restrictions The Reboot command requires a privilege level of five.
See also Exit, Show, ShutDown, Who
Receive 477
Co
mm
an
ds
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.
Operation 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 com-mand or by using THEO+COM directly.
>dial 1 800 123-4567Dialing 1 800 123-4567
>receive updated.stocklst
RECEIVE file ( options
file » file name with optional path
options » ASCII TRACE XMODEM XMODEM-1KCOMnn TRACEFILE fn XMODEM-CRC YMODEMTHEOS
Protocol..... THEOSFile name.... UPDATED.STOCKLST:SFile size.... 1,235Blocks....... 5Transmitted.. 0%Byte count... 0Block count.. 0File count... 1Elapsed time. 0:02Errors....... 0Message...... Waiting for senderProgress.....
File transfer in process. Press ESC to cancel.
Receive
478 Receive
Co
mm
an
ds
Options ASCII Use the ASCII file transfer protocol. Essentially, this is no pro-tocol 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 upper-right 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
Reminder 479
Co
mm
an
ds
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 com-mand.
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 infor-mation 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 mes-sage for the date.
>reminder
Enter date (MMDDYY): 07/19/02Enter 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
480 Reminder
Co
mm
an
ds
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.
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).
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 mes-sages 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
DATEFORM 1 DATEFORM 2 DATEFORM 3
Format: MMDDYY DDMMYY YYMMDD
Examples: 10/15/9610159610/151015
15-10-9615109615-101510
96.10.1596101515.101510
Reminder 481
Co
mm
an
ds
This message is the myaccount message for any July 4th.
>
See also Logon
482 Reminder
Co
mm
an
ds
Remote 483
Co
mm
an
ds
Remote Command
The REMOTE command executes a command over a network connection.
Operation 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.
1 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
484 Remote
Co
mm
an
ds
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.
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 win-dows-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 ver-sion 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 resid-ing on the Windows system.
Options 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 win-dow.
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 win-dow.
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.
Remote 485
Co
mm
an
ds
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 Win-dows file description.
The options on this REMOTE command line are not passed as options to the command or Windows-command. The command may have options speci-fied but to do so you must enclose the desired command name and its options within quotes. For instance:
>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 con-sole 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
486 Remote
Co
mm
an
ds
Rename 487
Co
mm
an
ds
Rename Command
Rename changes the name of an existing file, library or directory.
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 par-tial 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.filescustomer.master:s /prior/customer.master:scustomer.history:s /prior/customer.history:sgeneral.ledger.*:s /prior/=.=.=:scheck.*:s /prior/=.=
>rename daily.files (file noquery notype
1 RENAME from-file to-file ( options
2 RENAME file ( FILES options
3 RENAME ( options
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 » NOQUERYNOTYPEQUERYTYPE
488 Rename
Co
mm
an
ds
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.
>rename (noqueryEnter file name list, terminate with empty line.?MENU.BASICDestination 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.* gltest.= (notOk to rename "GL.MASTER:S" (Yes,No,All) YOk to rename "GL.JOURNAL:S" (Yes,No,All) YOk to rename "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 =.testdataOk 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.
Rename 489
Co
mm
an
ds
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.
>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.
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 PRI-VATE 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
490 Rename
Co
mm
an
ds
Repeat 491
Co
mm
an
ds
Repeat Command EXEC
The Repeat EXEC executes a command several times.
Operation 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 count command-line
command-line » any valid THEOS command
count » number of times to execute command-line
492 Repeat
Co
mm
an
ds
Replace 493
Co
mm
an
ds
Replace Command Filter
The Replace command modifies text files by changing (replacing) existing text strings with a new text strings.
Operation Mode 1—The text file is opened and read. Every occurrence of the charac-ter 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, fol-lowed 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 com-mand:
>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 to-text 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.
1 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 NODATA
494 Replace
Co
mm
an
ds
NODATA 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.
Notes 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 com-mands.
See also LineEdit, WinWrite
Restore 495
Co
mm
an
ds
Restore Command
The Restore command retrieves the “archive copy” of a file, set of files or an entire disk vol-ume. This command is the complement of the TArchive command.
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.
1 RESTORE from-drive to-drive ( options
2 RESTORE file to-drive ( options
3 RESTORE from-drive ( SHOW options
4 RESTORE from-drive ( VERIFY
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 MULTIUSE NOTYPE REWINDALL NAME name OLDER SHOWASK NEWFILE OLDFILE SIZE nnnCLEAR NOASK PRTnn SUBDIRDRIVE d NOQUERY QUERY TYPEFROM aaa NOSYSFILE REPLACE VOLUMELABEL lll
496 Restore
Co
mm
an
ds
Operation Mode 1—Restores all of the files from the archive volume in from-drive to the disk in to-drive.
>restore tape s
Mode 2—Restores file from the archive volume to the to-drive in the cur-rent 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 FDestination is Disk SMount 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 for account "PRIVATE".Searching for file "THOSE.FILES".Restoring "THOSE.FILES:S".Restoring "THOSE.FILES.FILE1:S".Restoring "THOSE.FILES.FILE2:S".Restoring "THOSE.FILES.FILE3:S".Restoring "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 from-drive.
>restore f (show
Account: 10\PRIVATE 28 Aug 2001 9:01am Page 1
Filename Filetype Member Dr Date Time Org Protect Size Recl Keyl
SOME FILE 01/26/01 12:46 S ..WR.... 1335THOSE FILES 01/20/01 13:34 L ........ 1280 20
FILE1 03/19/00 17:09 S ..W..... 1284FILE2 09/00/00 11:28 S ..W..... 2257FILE3 10/22/01 11:34 S ..W..... 31FILE4 12/01/87 05:00 S ..W..... 9895
The SHOW option does not have to be specified.
Restore 497
Co
mm
an
ds
>restore f
Account: 10\PRIVATE 28 Aug 2001 9:01am Page 1
Filename Filetype Member Dr Date Time Org Protect Size Recl Keyl
SOME FILE 01/26/01 12:46 S ..WR.... 1335THOSE FILES 01/20/01 13:34 L ........ 1280 20
FILE1 03/19/00 17:09 S ..W..... 1284FILE2 09/00/00 11:28 S ..W..... 2257FILE3 10/22/00 11:34 S ..W..... 31FILE4 12/01/87 05:00 S ..W..... 9895
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 simi-lar 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.
498 Restore
Co
mm
an
ds
ASK This is a default option that instructs Restore to ask the opera-tor to mount the source and destination volumes and waits for confirmation that the proper volumes are mounted.
>restore tape s
Source is TAPE1Destination is Disk SMount 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.
Restore 499
Co
mm
an
ds
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 disk/tape labels of label, with each disk/tape of the set incre-menting the last character of label. For instance, disk one is labeled “Mon-1,” disk two is labeled “Mon-2” and so on.
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 sin-gle-user or private volume.”
Using this option tells Restore to not restrict the restore to sin-gle-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 confirma-tion 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 speci-fied, as well as the query when a file exists, is protected and the ALL option is not specified.
500 Restore
Co
mm
an
ds
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)
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) NOk 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).
Restore 501
Co
mm
an
ds
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)
Valid responses are identical to the QUERY option responses.
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 direc-tory. When this option is not used, files are restored to the to-drive’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 indi-cate the hierarchy of the account and directory structure.
502 Restore
Co
mm
an
ds
For instance, the following is a typical display during a full vol-ume restore:
ACCOUNT: 2=SAMPLESFile: READ.MEFile: SAMPLES.EXECSubdirectory: C32
Library: C32.CMD32Member: C32.CMD32.FINSMember: C32.CMD32.PRTF
...
An ACCOUNT restore displays a simple message for each file restored:
Searching for account "SAMPLES".Restoring "READ.ME:S".Restoring "SAMPLES.EXEC:S".Restoring "/C32/C32.CMD32:S".Restoring "/C32/C32.CMD32.FINS:S".Restoring "/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.
Restore 503
Co
mm
an
ds
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
Device drivers
Class code definitions
etc.
See also TArchive, Backup, CopyFile, Disk, Tape, TBackup
504 Restore
Co
mm
an
ds
RMCP 505
Co
mm
an
ds
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.
Operation 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 user@host
user » E-mail account name
host » Domain or host of account
506 RMCP
Co
mm
an
ds
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.
See also POP3Test, TheoMail
RC 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.
RmDir 507
Co
mm
an
ds
RmDir Command
The RmDir or Remove Directory command erases a subdirectory and all of its files.
Operation 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 directory… ( options
directory » subdirectory name; may contain path; may contain wild cards
options » NOQUERYNOSAVENOTYPEQUERYTYPE
Command synonym: RD
508 RmDir
Co
mm
an
ds
Options NOQUERY Indicates that you do not want to be asked for confirmation before erasing a subdirectory containing files.
>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.
QUERY 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.
>tree/
subdir1subdir11subdir12
subdir2
>rd subdir1 (noq
>tree /
subdir2
RmDir 509
Co
mm
an
ds
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 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.
>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 com-mand 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 limita-tions, files in the recycle bin are not retained forever.
Defaults TYPE is a default option.
See also FileManager, Erase, UnErase
510 RmDir
Co
mm
an
ds
Route 511
Co
mm
an
ds
Route Command
The Route command displays and maintains the routing tables used to establish network paths to various IP addresses.
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 255.255.255.255 127.0.0.1 127.0.0.1127.255.255.255 255.255.255.255 127.0.0.1 127.0.0.1127.0.0.0 255.0.0.0 127.0.0.1 127.0.0.1192.168.100.1 255.255.255.255 127.0.0.1 127.0.0.1192.168.100.255 255.255.255.255 192.168.100.1 192.168.100.1192.168.100.0 255.255.255.0 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.
1 ROUTE
2 ROUTE ( PRTnn
3 ROUTE ( ADD net-addr net-mask gateway-addr host-addr
4 ROUTE ( DELETE net-addr net-mask
gateway-addr » dotted IP address of gateway machine
host-addr » dotted IP address of NIC in local machine used to access gate-way-addr
net-addr » dotted IP address of destination network
net-mask » dotted subnet mask for the destination network
512 Route
Co
mm
an
ds
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.
All IP addresses starting with 127 are “loopback addresses.” By conven-tion, 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 deter-mine 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 com-puter with a proxy server and modem connection to an ISP.
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:
Net Address Subnet Mask Gateway Address Host Address
0.0.0.0 0.0.0.0 192.168.100.100 192.168.100.1127.0.0.1 255.255.255.255 127.0.0.1 127.0.0.1127.255.255.255 255.255.255.255 127.0.0.1 127.0.0.1127.0.0.0 255.0.0.0 127.0.0.1 127.0.0.1192.168.100.1 255.255.255.255 127.0.0.1 127.0.0.1192.168.100.255 255.255.255.255 192.168.100.1 192.168.100.1192.168.100.0 255.255.255.0 192.168.100.1 192.168.100.1
.1 .3 .5 .7 .9
.8.6.4.2 .100router
The .1, .2 etc. references are to the last portion of the IP address of the node.
Route 513
Co
mm
an
ds
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 3 and 4: All packets broadcast to the localhost are sent to the loop-back 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:
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
.1 .3 .5 .7 .9
.8.6.4.2 .100router
.2.1
192.168.100.*
192.168.50.*
.9
514 Route
Co
mm
an
ds
On the .2 machine you would:
>route (add 192.168.50.0 255.255.255.0 192.168.100.4 192.168.100.2
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 0.0.0.0 192.168.100.100 192.168.100.4127.0.0.1 255.255.255.255 127.0.0.1 127.0.0.1127.255.255.255 255.255.255.255 127.0.0.1 127.0.0.1127.0.0.0 255.0.0.0 127.0.0.1 127.0.0.1192.168.50.9 255.255.255.255 127.0.0.1 127.0.0.1192.168.50.255 255.255.255.255 192.168.50.9 192.168.50.9192.168.50.0 255.255.255.0 192.168.50.9 192.168.50.9192.168.100.4 255.255.255.255 127.0.0.1 127.0.0.1192.168.100.255 255.255.255.255 192.168.100.4 192.168.100.4192.168.100.0 255.255.255.0 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.
Route 515
Co
mm
an
ds
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
Entries copied from the /THEOS/CONFIG/NETROUTE.CFG:S file, if any
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 net-work 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.
516 Route
Co
mm
an
ds
Script 517
Co
mm
an
ds
Script Command
Process and format the text in a file including page headings, paragraph justification, chap-ters, contents, etc.
Operation 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 com-mands 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.
1 SCRIPT filename ( options
2 SCRIPT filename outfile ( FILE options
3 SCRIPT filename readfile ( options
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 INDEX REPEAT nn WAITFILE PRTnn TYPE nn mm
518 Script
Co
mm
an
ds
nn mm Only output from page nn through page mm.
Defaults The default output is to the console.
The initial definition of the special characters is: . (period) for start of com-mand, @ 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 Enable word hyphenation or define hyphenation for a word.
Script 519
Co
mm
an
ds
IGUTTER Set inside gutter character.
INDENT Set paragraph indent.
INDEX Insert index here.
INPVAR Read value of variable.
INTRODUCTION Begin introduction.
JUSTIFY 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.
520 Script
Co
mm
an
ds
REMARK Comment line.
RFOOTING Set right footing text.
RHEADING Set right heading text.
RMARGIN Set right margin.
RSIZE Set right page size.
SECTION Start a new section.
SETAPPENDIX Define next appendix letter.
SETBOLD Define boldface character. (&)
SETCHAPTER Define next chapter number.
SETCOL Define tab character.
SETCOMM Define command character. (.)
SETESCAPE Define escape character. (@)
SETHYPH 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 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.
Script 521
Co
mm
an
ds
TYPE Display text on console.
Variables and codes
. This character is used at the beginning of a line that is a com-mand. The character can be changed with the SETCOMM com-mand.
& This character surrounds text that is to be boldfaced. Charac-ter can be changed with the SETBOLD command.
_ This character surrounds text that is to be underlined. Charac-ter 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 SET-ESCAPE 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)
522 Script
Co
mm
an
ds
See 523
Co
mm
an
ds
See Command Filter
The See command copies a file to the standard output device, making all nonprintable char-acters visible.
Operation 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 dis-plays 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.repeatsystem.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
1 SEE file...
2 SEE
file » file name with optional path; may contain wild cards
524 See
Co
mm
an
ds
Each file is displayed on the standard output device. The minus sign speci-fication (Mode 2) can be used to indicate that the end-of-line character is not displayed as a dollar sign:
>see - system.cmd32.repeatsystem.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 char-acter.
Mode 2—Copies the file from standard input to standard output, display-ing 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
Send 525
Co
mm
an
ds
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.
Operation 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 com-mand or by using THEO+COM directly.
>dial 1 800 123-4567Dialing 1 800 123-4567
>send updated.stocklst
Mode 2—Similar to Mode 1, except file is an ASCII stream file that con-tains 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
1 SEND file ( options
2 SEND file ( FILES options
file » file name with optional path; may contain wild cards
options » ASCII NOEOT TRACEFILE fn XMODEM-1KCOMnn THEOS XMODEM YMODEMEOT TRACE XMODEM-CRC
526 Send
Co
mm
an
ds
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.
Options ASCII Use the ASCII file transfer protocol. Essentially, this is no pro-tocol 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-trans-mission 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 com-puter. The other computer used the Receive command only once because the first file used NOEOT and the transmission was not terminated.
Protocol..... THEOSFile name.... MY.DATA:SFile size.... 1,235Blocks....... 5Transmitted.. 0%Byte count... 0Block count.. 0File count... 1Elapsed time. 0:02Errors....... 0Message...... Waiting for receiverProgress.....
File transfer in process. Press ESC to cancel.
Send
Send 527
Co
mm
an
ds
THEOS Use the THEOS SEND/RECEIVE protocol. This is the default protocol.
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 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, PutFile, Receive, THEO+COM
528 Send
Co
mm
an
ds
SendMail 529
Co
mm
an
ds
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 user-friendly interface, use the TheoMail described on page 653.
Operation filename is sent to the SMTP Server specified in the THEOS E-mail configu-ration 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] [email protected] subject "example message w/attach-ments"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 cop-ies of the message sent.
>sendmail my.message (to [email protected] [email protected] bcc [email protected] sub-ject"You're history"
1 SENDMAIL filename ( options
filename » name of file on local system
options » ATTACH FILES RAW SUBJECTBCC FROM REPLYTO TOCC HTML SMTP
530 SendMail
Co
mm
an
ds
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 mes-sages never have a “BCC” field. Compare with the CC option described next.
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 pro-duce the same result:
>sendmail my.message (to [email protected] [email protected] bcc [email protected] [email protected] subject "Your termination"
>sendmail my.message (to [email protected] [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] [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 mes-sage 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 sepa-rated by comma, space, or by using multiple CC option specifi-cations.
FILES 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.
SendMail 531
Co
mm
an
ds
For instance, the FileList command is used to create a list of messages to be sent:
>filelist *.message:a (01/20/01 exec
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:
&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 com-mand 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 mes-sage. 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 embed-ded mail headers are used, with one of those.
>sendmail my.message (to [email protected] from [email protected] replyto [email protected] "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.
532 SendMail
Co
mm
an
ds
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.
>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 sub-ject 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 mes-sage. The address specified must be a valid e-mail address.
>sendmail my.message (to [email protected] [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] [email protected] cc [email protected] subject"Staff meeting at 1:00"
>sendmail my.message (to "[email protected], [email protected]" from [email protected] "Staff meeting at 1:00"
SendMail 533
Co
mm
an
ds
>sendmail my.message (to [email protected] to [email protected] from [email protected] "Staff meeting at 1:00"
The difference between these messages will only be in the interpretation by the recipient. The first form sends the mes-sage to you with an informational copy to yourboss. The sec-ond and third forms send the message with equal importance to both recipients.
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 4thfloor conference room.
Your attendance is required.
The Boss.
This file could be sent with the following command:
>sendmail my.message (to "Alice <[email protected]>" from "J.C. <[email protected]>" subject "Staff meeting at 1:00"
If the message uses embedded headers, such as:
To: Alice <[email protected]>From: J.C. <[email protected]>Subject: Staff meeting at 1:00
A staff meeting is scheduled at 1:00pm today in the 4thfloor conference room.
Your attendance is required.
The Boss.
It can be sent with the following command:
>sendmail my.message
534 SendMail
Co
mm
an
ds
The following headers may be embedded at the start of a message file:
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]@quadralay.com
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:
SendMail 535
Co
mm
an
ds
"John Doe <[email protected]>"
Comment text may appear before or after, or before and after the actual e-mail address.
"John Doe <[email protected]> FYI only"
Including Text Files
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 <[email protected]>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: Tom <[email protected]>Cc: Shirley <[email protected]>Cc: Richard <[email protected]>Cc: Rebecca <[email protected]>
• 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 statusSales incentivesIncreased CEO bonus
• SIGNATURE.FILES.THEBOSS file:
John Curtis (J.C.)PresidentWidgets, Inc.
As illustrated in the above example, the %include command feature is very useful for creating “boilerplate” messages, for specifying e-mail distribu-tion lists, etc. The referenced file is included only when the file is transmit-
536 SendMail
Co
mm
an
ds
ted by SendMail. The above example transmits as if it contained the following text:
To: Tom <[email protected]>Cc: Shirley <[email protected]>Cc: Richard <[email protected]>Cc: Rebecca <[email protected]>From: The Boss <[email protected]>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 statusSales incentivesIncreased CEO bonus
We will also be discussing plans for the company picnic and vacation schedules.
John Curtis (J.C.)PresidentWidgets, 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 Oper-ating System Installation and Setup Guide.
Enclose the option arguments within quotation marks. Although not required, without quotation marks the arguments will be folded to upper-case and embedded commas or spaces will terminate the argument.
When there are more than 50 addresses in the To, Cc and Bcc fields (com-mand-line options or in the embedded addressing fields), multiple copies of the message are sent, 50 addresses per message.
SendMail 537
Co
mm
an
ds
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).
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 specifica-tion may include the path specification.
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 mes-sage.
OPTION BASE 1, CASE "M", PROMPT ""DIM MSG$(100)
START:! First, paint the screenWINDOW OPEN ADDROF(MAIN%),1,1,80,24; SELECT UPDATE ONPRINT 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, CENTERENTER.MESSAGE:
WINDOW SELECT MAIN%, UPDATE ONENTER.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.JOBIF 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.FROMPRINT 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$)
538 SendMail
Co
mm
an
ds
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 bodyWINDOW SELECT MAIN%, UPDATE ONPRINT AT(1,23);"Okay to send? ";LINPUT USING "!", REPLY$IF UCASE(REPLY$)="N" THEN GOTO ENTER.MESSAGEMSG.COUNT% = 0FOR I% = 100 TO 1 STEP -1 ! Find out how many message lines
IF TRIM(MSG$(I%))<>""MSG.COUNT% = I%I% = 0
IFENDNEXT! Make sure that there is a messageIF MSG.COUNT%
PRINT AT(1,23);"Creating message file...";CRT("EOL");MSG.FILE$ = SYS.ENV$(20,"SENDMAIL.XXXXXX") ! Work nameOPEN #1:MSG.FILE$, OUTPUT SEQUENTIAL ! Save msg in filePRINT #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 bodyFOR I% = 1 TO MSG.COUNT%
PRINT #1:MSG$(I%)NEXTCLOSE #1PRINT AT(1,23);"Sending message...";CRT("EOL");SYSTEM "SENDMAIL "&MSG.FILE$ ! Send the message
ELSEPRINT AT(1,23);"No message text...ignoring!";CRT("BELL");SLEEP 2
IFEND! Clear input areas on screenMAT MSG$ =("") \ WINDOW CLEAR MSG%WINDOW SELECT MAIN%, UPDATE ONREPLYTO$ = "" \ 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
Session 539
Co
mm
an
ds
Session Command
The Session command allows you to control the attributes, position and size of the session window.
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:
MAXIMIZEMINIMIZEMOVESIZE
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 com-mand 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 maxi-mized session has no frame and no title displayed.
MINIMIZE Minimize the session to an icon.
SESSION function
function » CHANGE FOCUS MOVE SIZEDISABLE MAXIMIZE RESTORE TITLEENABLE MINIMIZE
540 Session
Co
mm
an
ds
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).
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 quo-tation 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
Set 541
Co
mm
an
ds
Set Command
The Set command sets and changes system and user-defined environment parameters.
Operation 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 Ver-sion 5 Operating System Reference.
Because setting the date and time is different than setting other environ-ment variables, it is described separately, on page 542.
1 SET system-env-name value
2 SET user-variable=value
3 SET
system-env-name » ABBREV on-off HISTORY on-off QUIT on-offBREAK c LIBRARY lib RDYMSG on-offCOPYLIB lib LINKLIB lib SEARCH drive-seqCWD dir MSG on-off SUBDIR dirDATE date OBJLIB lib SYNONYM fileDATEFORM n PATH path TIME timeDATEIN n PRIORITY n WORKVOL driveDATEOUT n PROMPT string
user-variable » user-defined environment variable
value » value to assign to environment variable
542 Set
Co
mm
an
ds
Mode 2—Changes a user-defined environment parameter. User-defined environment parameters may be any name that uses alphanumeric char-acters, does not contain a space character, and is not the same as a system-defined environment parameter.
>set MyName="Ralph Kramden"
>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.
>setRDYMSG = OFFMSG = ONWORK = MSEARCH = SDESCRIPTION = System maintenance accountUSERNAME = BossPROMPT = !14\a!15\ s !4!!\!!5>CLIST = YESHOME = /:SLANGNAME = EnglishOSVER = 5.0OSPL = 50099PROFILE = 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 enter-ing the new date on the command line:
>Set date 3/5/02Date is set to Tuesday, March 5, 2002.
>Set date 3.7Date is set to Thursday, March 7, 2002.
Set 543
Co
mm
an
ds
The date is interpreted by the Set command using the currently set DATE-FORM format.
The date may also be changed by using the Date Selection form:
>Set date(Enter)
Unlike most other parameters, changing the DATE or TIME requires a priv-ilege level of five and it affects all users on the system.
TIME. Changing this variable changes the current system time. When set-ting the time you must specify the hours and minutes. You may also spec-ify 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 speci-fied time.
>Set time 12:15(Enter)
544 Set
Co
mm
an
ds
Notes Environment variables have values that are strings, numeric values or Boolean values (true/false). Single-word strings are assigned normally:
>Set UserName Fred
Multiple word strings are assigned by enclosing the string within quota-tion 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 assign-ment:
>Set FileType Basic
>Set FileType=Basic
The Logoff command clears all user-defined and system-defined environ-ments. 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 com-mand).
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 Account, ChDir, Logon, Mailbox, Msg, Show, Sysgen
Setup 545
Co
mm
an
ds
Setup Command
The Setup command provides a single command to configure and initialize the major compo-nents of THEOS Corona and various types of devices.
Operation 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 applica-ble 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.
1 SETUP
2 SETUP function
3 SETUP NET subfunction
function » ACCOUNT FAX PRINTER SYSGENCACHE FD950 PROFILE TIMECENTLP FLOPPY RECYCLED TYPESCOLOR FONT RESTORE UNINSTALLCRT INSTALL SIO UPDATECX MAKEBOOT SMTP UPSDIGIXE MAXSPEED SNDCARD USERCOUNTDISK MIXER SOUND VGAEMAIL NET SPOOLER
546 Setup
Co
mm
an
ds
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 Ver-sion 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 con-figures 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 Account, ClassGen, Disk, FileManager, Sysgen, Tape
Shell 547
Co
mm
an
ds
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 comple-tion, 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 SHELLType "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 pro-gram.
An example usage from a MultiUser BASIC Version 2.1 program might be:
001000 WINDOW OPEN 1,2,10,76,10; COLOR 7,4001010 WINDOW FRAME 1, RAISED, RIGHT, COLOR 7,4001020 WINDOW TITLE 1," CSI Shell ", CENTER TOP, COLOR 6,4001030 WINDOW SELECT 1001040001050 SYSTEM "shell"001060 PRINT "I'm back...";...
SHELL
CSI Shell
THEOS® Command SHELLType "EXIT" to terminate.
>
548 Shell
Co
mm
an
ds
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.
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 envi-ronment.
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.
Show 549
Co
mm
an
ds
Show Command
The Show command displays the current value of system-parameters, user-variables and other information about the system.
1 SHOW
2 SHOW env-name
3 SHOW function
4 SHOW *
env-name » ABBREV DATEIN LIBRARY PROMPTBREAK DATEOUT LINKLIB QUITCALPHA DECIMAL MSG RDYMSGCASE DESCRIPTION NOTLIBCOMPATIBLE SEARCHCLIST FILETYPE OBJLIB STDSYNCMDLIB FULLNAME OSPL SUBDIRCOPYLIB HISTORY OSVER SYNONYMCREATE HOME PATH USERNAMECWD LANG PRIVLEV WORKDATEFORM LANGNAME PROFILE name
function » CLOCK IRQ PCMCIA USERDEVICE MEMORY SCSI USER n mm-nnDISK MEMORY * TAPE VERSIONIDE PCI USB WHO
550 Show
Co
mm
an
ds
Operation 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:
Settings. Shows the currently defined environment variables.
Show 551
Co
mm
an
ds
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.
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 cur-rently configured on this system.
552 Show
Co
mm
an
ds
A text-only, non-object display of this information can be obtained by using the command SHOW PCI.
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:
Show 553
Co
mm
an
ds
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 CD-ROM disc devices that are currently connected to the system. These devices are listed whether they use IDE, SCSI, USB, PCMCIA, I2O or ATAPI technology.
A text-only, non-object display of this information can be obtained by using the command SHOW DISK.
554 Show
Co
mm
an
ds
SCSI Devices. Shows the SCSI devices (Small Computer System Inter-face) 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.
Show 555
Co
mm
an
ds
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.
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 searchSEARCH = S
>show fullnameFULLNAME = 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.
556 Show
Co
mm
an
ds
Mode 4—Displays the following information:
>show *ACCOUNT = SYSTEMUSERNUM = 0PORT = 16PRIVLEV = 9LOGON = 15:29:09 09/04/01ABBREV = ONMSG = ONRDYMSG = OFFSEARCH = SWORKVOL = MSERIAL = 102-12345IDENT = "TheosServer"SYNONYM = USER.SYNONYMSUBDIR = /LIBRARY =PATH =OBJLIB =COPYLIB =LINKLIB =
Show 557
Co
mm
an
ds
Functions CLOCK Displays the current time and date continuously. The time is updated once per second. Use the (Esc) or (F9) to quit.
>show clock16:12:24 PST Thursday, January 17, 2002.
Use the Clock command to display a graphic clock.
DATE Displays the current time and date, once.
>show date16: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.
558 Show
Co
mm
an
ds
TIME Displays the current time and date, once. This is synonymous to the DATE function.
>show time16:12:24 PDT Monday, April 20, 2002.
You can use the CLOCK function to display the time continu-ously 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.
Show 559
Co
mm
an
ds
The “Status & Info” column uses codes for the status condition of the process:
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 dis-played 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.
Code Meaning
* Indicates that this is the process performing the Show USERS.
E=nn 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.”
560 Show
Co
mm
an
ds
VERSION Displays the version and date for the operating system and all major components installed on your system.
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 whoACCOUNT = SYSTEMUSERNUM = 0PORT = 16PRIVLEV = 5LOGON = 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
ShutDown 561
Co
mm
an
ds
ShutDown Command
The ShutDown command allows you to shutdown or reboot your computer.
Operation 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 termi-nated 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 com-pleted.
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
1 SHUTDOWN
2 SHUTDOWN ( option
option » DOS NOTYPE SHUTDOWN UPDATEFAST QUERY SINGLE WINDOWSLINUX REBOOT THEOSNOQUERY RESET TYPE
562 ShutDown
Co
mm
an
ds
Sleep 563
Co
mm
an
ds
Sleep Command
The Sleep command causes your process to suspend execution for an interval of time or until a specified time-of-day.
Operation 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.
1 SLEEP seconds
2 SLEEP time-of-day
seconds » number of seconds to sleep
time-of-day » time to wake up
564 Sleep
Co
mm
an
ds
Sort 565
Co
mm
an
ds
Sort Command Filter
This command sorts a stream file using the entire record as a sort key or designated por-tions of each record as the sort key.
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 dictio-nary 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 charac-ters outside the range of ASCII characters. It also ignores duplicate records and outputs the file in reverse sequence.
1 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 f nd i r
options » b f n uc i rd m tn
566 Sort
Co
mm
an
ds
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.
>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 char-acters of the second field.
Each sort key may have its own field-options specified immediately follow-ing 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 specifica-tions.
Sort 567
Co
mm
an
ds
Options b Ignores leading blanks and other white space characters in the sort key for comparison purposes.
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, pre-ceded 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 lower-case. Thus, “AARDVARK” sorts to the same location as “aard-vark.”
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.
r The key is sorted in descending order, not the normal ascend-ing sequence.
tc Specifies that the tab, or field delimiting character, is the char-acter c. This option is used with the +position and -position
Input Keys Comparison Keys
John F. Kennedy John F. Kennedy
John F. Kennedy John F. Kennedy
John F. Kennedy John F. Kennedy
Sort Keys w/o -n option with -n option
423 2 2
32 20 20
2 200 32
20 32 200
200 423 423
568 Sort
Co
mm
an
ds
options to specify that a character other than (Tab) separates the fields in the record.
>sort "-t," +2.0 +0.0 names.data
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 interpret-ing the comma as one of its characters.
u 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).
Defaults 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 Appen-dix 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.
Input Keys 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
Split 569
Co
mm
an
ds
Split Command Filter
The Split command splits a stream file into multiple files, each one containing a portion of the original file.
Operation 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 Specifies the number of lines each output file will contain. When not specified the default value of 100 is used.
Defaults The default number of lines for each of the output files is 100.
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
1 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
570 Split
Co
mm
an
ds
Spooler 571
Co
mm
an
ds
Spooler Command
The Spooler command controls the print spooler.
1 SPOOLER printer
2 SPOOLER printer manager-function
3 SPOOLER printer function
4 SPOOLER
printer » optional spooled printer number
manager-function » ATTACH options INIT STOPBUILD count drive QUIT VERIFYFORM queue START
function » ABORT KILL reportsALIGN report page LISTBACKUP pages PRINT report pageCHANGE report queue copies hold STATUS
report » nnn
page » page number
queue » letter
copies » number of copies to print
hold » HOLDNOHOLD
reports » report reportsreport-report reports*
572 Spooler
Co
mm
an
ds
Operation Mode 1—Displays the status of a spooled printer or on all of the spooled printers.
>spooler 1Printer #1 "CENTLP1" L80,P58,HPLASER,W8
-- is waiting for work-- and has form "A" mounted
>spool *Printer #1 "CENTLP1" L80,P58,HPLASER,W8
-- is waiting for work-- and has form "A" mounted
Printer #2 "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 3Printer #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 Date Time Q Pages C Status
11 SYSTEM 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.
Spooler 573
Co
mm
an
ds
Spooler Status When Mode 4 is used and the console is configured for graphics display, the following form is displayed:
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 let-ters for the selected printer.
574 Spooler
Co
mm
an
ds
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 per-form 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 let-ter, 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 col-umns of information.
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 but-ton is pressed the next order is used:
Spooler 575
Co
mm
an
ds
Report numberQueue letter then report numberCreation date then report numberAccount 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.
Remove/Abort 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. Other-wise, 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 con-nected 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 3Printer #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 cur-rently printing a report.
BUILD nnn drv This function creates a new /THEOS/SPOOLER/SYS-TEM.SPOOLER library. The only time that you might need to use
576 Spooler
Co
mm
an
ds
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
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 print-ing 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.
Spooler 577
Co
mm
an
ds
INIT drive This function initializes and starts the print spooler. This ini-tialization can also be done automatically at boot time if the “Enable Print Spooler” is set in the system configuration (see “Sysgen” on page 591).
drive is the disk drive code for the drive containing the /THEOS/SPOOLER/SYSTEM.SPOOLER library. If drive is not specified, S is used.
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 trans-ferred and cannot be spooled.)
For each physical printer that is transferred to the print spooler, a logical printer is attached to the spooler. These logi-cal 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
>spoolerPrinter #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 pro-cesss 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
578 Spooler
Co
mm
an
ds
printing on printer, it is finished before that printer is actually stopped.
>spooler 3 stop
>spoolerPrinter #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 func-tion 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 con-figuration (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 sys-tem 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 config-uration 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).
Spooler 579
Co
mm
an
ds
Functions ABORT Stops printing the current report on the specified printer. printer must be specified if there is more than one spooled printer.
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.
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 dig-its 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 align-ment 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
580 Spooler
Co
mm
an
ds
the report. The queue, copies and hold attributes can be speci-fied in any order and one or more may be omitted, indicating that that attribute is not changed.
The queue is a single character identifying one of the 64 possi-ble 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 syn-tax 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.
Spooler 581
Co
mm
an
ds
LIST Displays a list of the spooled reports on the standard output device. The information displayed includes:
The return code is set to 1 if one or more reports listed. Other-wise 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 Reports on the status of the spooled printer or on all of the spooled printers. This is equivalent to a Mode 1 Spooler com-mand.
Forms and Queues
Forms and queues are identified with single-characters. There are 64 pos-sible forms and 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 specifica-tions default to the uppercase form and queue letters.
Column Content
File The report number.
Acc-name Owning account name.
Rpt-name Report name
Date Time Date and time report created.
Q Queue of report.
Pages Number of pages in report. This is only an estimated number based upon the number of form-feeds in the report.
C Number of copies still to print.
Status Current status of the report. Status messages include Open, Closed, Printing, Printed, Hold.
A – Z 26 forms/queues
a – z 26 forms/queues
# $ % & * + - < = > ^ ~ 12 forms/queues
582 Spooler
Co
mm
an
ds
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:
>spooler 1 form a ; Refers to form A>spooler 1 form "a" ; Refers to form a>spooler 1 form x ; Refers to form X>spooler 1 form % ; Refers to form %>spooler 1 form abc$ ; Refers to forms A, B C and $>spooler 1 form "Aix$%" ; Refers to 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 change 2 a ; Refers to queue A>spooler change 2 "a" ; Refers to queue a>spooler change 2 $ ; Refers to queue $>spooler change 2 queue=a ; Refers to queue A>spooler change 2 queue=$a ; Refers to queue a>spooler change 2 queue=$$ ; Refers to queue $
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 ini-tialized before the function can be used.
See also Attach, Sysgen
Start 583
Co
mm
an
ds
Start CommandStop Command
The Start command starts a user, session or background task. The Stop command stops a user, session or background task.
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 param-eters 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.
1 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 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
584 Stop
Co
mm
an
ds
Mode 2—Identical in operation to Mode 1 except the new user is automat-ically 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"
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 estab-lished between the two modems Logon then sends the classcode initializa-tion 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 volumeTask started as process #29
The process number used for the new background task is the highest num-bered 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.
Stop 585
Co
mm
an
ds
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 20Process is still active.
>force 20 logoff
>stop 20
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 process ( console attach-options start-options
Defaults 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-to-one 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 suc-cessfully and give the specific process number used for the new task. Sub-tract 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.
586 Stop
Co
mm
an
ds
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.
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 Attach, Net Start, Sysgen
SUMode 587
Co
mm
an
ds
SUMode Command
Test the system for single-user operation.
Operation 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, back-ground 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
588 SUMode
Co
mm
an
ds
SysEd 589
Co
mm
an
ds
SysEd EXEC
This command allows you to view and optionally modify some common system configuration data files.
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.
1 SYSED
2 SYSED MODIFY
590 SysEd
Co
mm
an
ds
Sysgen 591
Co
mm
an
ds
Sysgen Command
Sysgen maintains the system configuration file (/THEOS/CONFIG/SYSGEN.CFG:S).
Operation 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 drive
drive » optional disk drive letter for /THEOS/CONFIG/SYSGEN.CFG file
592 Sysgen
Co
mm
an
ds
System 593
Co
mm
an
ds
System Command
The System command changes the system disk drive.
Operation 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 com-mand 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 Dis-kette, 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/lan-guage/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.
1 SYSTEM
2 SYSTEM drive
drive » optional drive letter code
594 System
Co
mm
an
ds
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.
See also Reboot, Sysgen
Tail 595
Co
mm
an
ds
Tail Command Filter
The Tail command displays the ending of a text file on the standard output device.
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 char-acters of each of the files are output.
>tail /theos/config/sysgen.cfgUSER1 5:3:7:1 L80,P24,C90,ACCOUNT=SYSTEMUSER2 5:3:7:2 L80,P24,C90USER3 5:3:7:3 L80,P24,C90USER4 5:3:7:4 L80,P24,C90USER5 5:3:7:5 L80,P24,C90USER6 5:3:7:8 L80,P24,C90DATEFORM ANAME "Saturn"MAXPCB 40LOWCASE
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 follow09/08/96 15:55:06.579 1 End Program RC: 0 CPU: 0.38009/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.
1 TAIL file... ( options
2 TAIL file ( options FOLLOW
file » file name with optional path; may contain wild cards
options » +nnn-nnnCHARSFOLLOWLINE
596 Tail
Co
mm
an
ds
Options 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.
Notes 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 Vari-ables” on page 111 of the THEOS Corona Version 5 Operating System Ref-erence.
Defaults LINES is a default option and -10 is the default count.
See also Head, List, More
Tape 597
Co
mm
an
ds
Tape Command
The Tape command initializes and manipulates a tape volume.
Operation 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.
>tapeTape 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 speci-fied, TAP1 is assumed.
>tape showTape TAPE1 label "FRIDAY".Archived from disk "PRODUCTN" on 12/06/96, at 17:35.
>
1 TAPE
2 TAPE tape functions
tape » tape device name, such as TAP2 or TAP4
functions » EJECT LABEL SHOW VERIFYFORMAT REWIND TENSION WTMINIT label RUN UNLOAD
598 Tape
Co
mm
an
ds
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 format-ting, the tape is formatted instead of just being tensioned.
>tape format
Enter tape label: Tuesday
>
INIT label A REWIND operation is performed and then it writes a new vol-ume 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 labelVOL1TSC002HDR1ARCHIVE.DISKTAPE 0001000100000098316 000000HDR2F0409600128** Tape Mark **Number of data blocks = 28917** Tape Mark **EOF1ARCHIVE.DISKTAPE 0001000100000098316 028917EOF2F0409600128** Tape Mark **** Tape Mark **
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 showTape TAPE1 label "TBACKUP".Tbackup from system "Production" on Wednesday, January 16, 2002, at 5:22pm.Data set name: "January 16, 2002 17:22:14"
>
Tape 599
Co
mm
an
ds
TENSION 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 verifyBlock: 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
600 Tape
Co
mm
an
ds
TArchive 601
Co
mm
an
ds
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.
The TArchive command creates an archive volume that can be used by the Restore com-mand.
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
1 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
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 FILES NOASK SIZE fileASK INCREMENTAL NOQUERY SUBDIRdate1 LABEL name NOTYPE TYPEdate2 MULTIUSER QUERY VOLUMEDIFFERENTIAL NAME file SHARE
602 TArchive
Co
mm
an
ds
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.
>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 spec-ification 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
TArchive 603
Co
mm
an
ds
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 combi-nations.
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.
Use the VOLUME option to override this default.
ASK A default option that instructs TArchive to ask the operator to mount the source and destination volumes, and waits for con-firmation that the proper volumes are mounted.
For instance:
>tarchive s f
Source is Disk SDestination is Disk FMount 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 selec-tion 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 selec-tion 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
604 TArchive
Co
mm
an
ds
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 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=DEVELOPSubdirectory: CUSTOMSubdirectory: PROGRAMSLibrary: PROGRAM.SOURCEMember: 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.
TArchive 605
Co
mm
an
ds
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 sin-gle user or private volume.”
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.
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 F with a file name of PROGRAMS.ARCHIVE.
If the archive cannot fit in the space remaining on the destina-tin 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 multi-ple volumes for the output file.
NOASK Disables the source and destination volume operator confirma-tion at the beginning of the archive and when subsequent disks or tapes are needed.
606 TArchive
Co
mm
an
ds
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 SDestination is Disk FMount 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) NOk 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 with-out 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.
SIZE file The total size of all of the files selected for archiving is com-puted 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.
TArchive 607
Co
mm
an
ds
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:
ACCOUNT: 2=SAMPLESFile: CHARSET.HFile: LIBS.EXECFile: MAKE.FILEFile: READ.MEFile: SAMPLES.EXECSubdirectory: C32
Library: C32.CMD32Member: C32.CMD32.FINSMember: C32.CMD32.PRTF
...
The indentation of the display indicates the hierarchy of the directory structure.
To disable this option use the NOTYPE option.
VOLUME 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
Full volume archives (option VOLUME in effect) are copies of the entire con-tents 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 com-puter failure. Since a full volume archive contains a copy of every file, sub-directory 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.
608 TArchive
Co
mm
an
ds
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 oper-ation. For instance, a system with four hard drives can be archived with the command:
>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.COMMANDDATA1.FILEDATA2.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.
Should a disk failure occur, the system could be restored by first restoring the full volume archive and then the last differential archive volume.
Full Volume Differential 1 Differential 2
PROGRAM.COMMAND
DATA1.FILE DATA1.FILE DATA1.FILE
DATA2.FILE DATA2.FILE
Differential Archives
TArchive 609
Co
mm
an
ds
Incremental Archives
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 con-tains only the DATA1.FILE. When DATA2.FILE is changed and another incre-mental 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.
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 spe-cial 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 pro-gram 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.VOLU-MEnn (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.
Full Volume Incremental 1 Incremental 2
PROGRAM.COMMAND
DATA1.FILE DATA1.FILE
DATA2.FILE DATA2.FILE
Incremental Archives
610 TArchive
Co
mm
an
ds
Defaults 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.
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 dis-kette, 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 speci-fied. See “Caution” notes above regarding the MULTIUSER option.
The TArchive command requires a privilege level of four.
See also Backup, CopyFile, Disk, Restore, Tape, TBackup
TBackup 611
Co
mm
an
ds
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.
1 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
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 FULL PASSWORD WAITASK INCREMENTAL PASSFILE date1COMPARE LABEL PRTnn date2DIFFERENTIAL LIST SETNAMEEJECT MULTIUSER SUBDIRERROR NOASK VERIFYFILES NOEJECT VOLUME
compare-options » ASK LIST PASSFILE WAITDISKMAP NOASK PASSWORDEJECT NOEJECT PRTnnERROR NOWAIT SETNAME
restore-options » ACCOUNT LIST OLDER REPLACEASK NEWFILE OLDFILE SETNAMEDISKMAP NOASK PASSFILE VOLUMEEJECT NOEJECT PASSWORD WAITERROR NOQUERY PRTnn date1FILES NOSYSFILES QUERY date2FROM NOWAIT
verify-options » ASK LIST NOWAIT PRTnnERROR NOASK PASSFILE SETNAMEEJECT NOEJECT PASSWORD WAIT
612 TBackup
Co
mm
an
ds
Operation Mode 1—Creates a backup data set on backup of the files specified by file-spec. 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:
1. With a drive code. When this is used, the backup data set is writ-ten to a file named TBACKUP.VOL00001:backup. The destination vol-ume 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*
TBackup 613
Co
mm
an
ds
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"
If the source files have been changed since the backup data set was cre-ated, this compare operation will fail. Remember, in a multiuser environ-ment, other users may be changing the database during the backup or between the start of the backup and the comparison operation.
Mode 3—Restores the files from the backup data set to the original loca-tion 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 con-tents 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 reen-ter it. The resulting password is encrypted and stored in the file named filename.
614 TBackup
Co
mm
an
ds
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.
ASK When TBackup is ready to begin writing the backup data, this option instructs TBackup to ask the operator to mount the des-tination volume and waits for confirmation that the proper vol-ume 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 ques-tion, allowing you to insert a different disk or tape into the drive.
ASK is a default option unless backup is a file name specifica-tion, 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.
TBackup 615
Co
mm
an
ds
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.
EJECT 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:sdevelop\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 specifi-cation 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 fol-lowing 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.
616 TBackup
Co
mm
an
ds
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.
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 mes-sage: “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.
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
TBackup 617
Co
mm
an
ds
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 same password. Passwords may be up to 32 characters in length, are case sensitive, and may contain spaces and other special characters.
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 cre-ated it by using the SETNAME option with the Mode 3 com-mand.
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 direc-tory 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 file-spec to files on the current account.
618 TBackup
Co
mm
an
ds
This option requires a privilege level of five, that you be cur-rently 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 exit-ing.
date1 The first token that looks like a date is interpreted as a selec-tion 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 selec-tion 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 Feb-ruary are excluded.
TBackup 619
Co
mm
an
ds
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
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.
Multiple DISKMAP options may be used to map files on multi-ple 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.
620 TBackup
Co
mm
an
ds
PASSFILE Specifies the file name containing an encrypted password. This password is used to decrypt the data set so that it can be com-pared against the original data on disk.
The data set must have been created with the exact same pass-word 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 pass-word 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 compared and the status message is displayed, TBackup should wait for an opera-tor response before clearing the status message and exiting.
TBackup 621
Co
mm
an
ds
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
In the above example, only files that were originally backed up from the DATA account are restored.
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.
622 TBackup
Co
mm
an
ds
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 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 pass-word 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 pass-word that is specified here.
PRTnn This option is a synonym to the LIST PRTnn option.
TBackup 623
Co
mm
an
ds
QUERY 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 opera-tor response before clearing the status message and exiting.
date1 The first token that looks like a date is interpreted as a selec-tion 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:
>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 selec-tion 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
624 TBackup
Co
mm
an
ds
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.”
TBackup 625
Co
mm
an
ds
Verify Options ASK 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 com-pared against the original data on disk.
The data set must have been created with the exact same pass-word 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 pass-word 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 sta-tus message is displayed, TBackup should wait for an operator response before clearing the status message and exiting.
626 TBackup
Co
mm
an
ds
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.
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 spe-cial 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. How-ever, 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 pro-gram 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 dis-kettes or tapes used will contain a single file named TBACKUP.VOLnnnnn.
Unless the DIFFERENTIAL option is used, the modified bit for each backed-up file is reset by the TBackup process.
TBackup 627
Co
mm
an
ds
TBackup Screens
TBackup, invoked with Mode 1 (BACKUP) displays the following status screen while it is collecting information about the files:
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:
628 TBackup
Co
mm
an
ds
TBackup, invoked with Mode 2 (COMPARE), Mode 3 (RESTORE) or Mode 4 (VERIFY), displays screens similar to the following status screen while it is collecting information and comparing, verifying or restoring files:
The ECC counts refer to the number of errors detected using the error-cor-recting checksum fields in the data set.
Full Volume Backups
A full volume backup of a drive can be made easily with the TBackup com-mand 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 com-puter failure. Since a full volume backup contains a copy of every file, sub-directory 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 searchSEARCH = SAB
>tbackup tape (backup volume
TBackup 629
Co
mm
an
ds
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).
>tbackup tape (restore
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.COMMANDDATA1.FILEDATA2.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 full-volume backup was performed.
Should a disk failure occur, the system could be restored by first restoring the full-volume backup and then the last differential backup.
Full-volume Differential 1 Differential 2
PROGRAM.COMMAND
DATA1.FILE DATA1.FILE DATA1.FILE
DATA2.FILE DATA2.FILE
630 TBackup
Co
mm
an
ds
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 incremen-tal 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.
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.
Full-volume Incremental 1 Incremental 2
PROGRAM.COMMAND
DATA1.FILE DATA1.FILE
DATA2.FILE DATA2.FILE
TBackup 631
Co
mm
an
ds
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.
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.
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
632 TBackup
Co
mm
an
ds
TBrowse 633
Co
mm
an
ds
TBrowse Command
The TBrowse command displays and allows you to browse the contents of HTML-encoded files.
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:
!DOCTYPEHTMLHEADTITLEBODY (with BGCOLOR LINK VLINK and TEXT attributes)H1 - H6P, BR and HRFONT but only the COLOR attribute is usedB, I, EM and STRONGOL, UL and LIBLOCKQUOTEPRE and CODETABLE with BORDER, COLSPAN and WIDTH attributesTH, TR and TDDL, DT and DDCENTERA HREFComments
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 win-
1 TBROWSE url
2 TBROWSE file
url » Uniform Resource Locator (URL) for HTML-encoded file
file » file name with optional path; may contain wild cards
634 TBrowse
Co
mm
an
ds
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.
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 informa-tion.
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 direc-tory 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:
<A HREF="/cgi/myprog?">Click to show report</A>
See also Help, Viewer
Tee 635
Co
mm
an
ds
Tee Command Filter
The Tee command copies standard input to standard output and makes additional copies to a file.
Operation 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 list-ing 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 direc-tory listing on the console.
Options APPEND The output is appended to the end of file. Without this option, the output replaces file.
Notes The file specified with this command may have a complete path specifica-tion, 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
TEE file... ( option
file » file name with optional path
option » APPEND
stdin stdout
file
tee
636 Tee
Co
mm
an
ds
Telnet 637
Co
mm
an
ds
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.
Operation Mode 1—Invokes the Telnet client and connects to server using its stan-dard 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.
1 TELNET server ( options
2 TELNET server port ( options
localhost » LOCALHOST
server » network server name or id (may also be localhost)
port » numeric port number to use for this session
options » ANSI ECHO PCTERM TRACECLASSnnn FLOW PCTERM-aa VT100CTL NOPROXY PROXY VT220
638 Telnet
Co
mm
an
ds
This option tells the Telnet client to echo all outbound charac-ters. 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.
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 pur-poses when there is some type of problem negotiating a proper connection with the remote server. These flow-control com-mands will generally only occur during the start-up phase of the connection:
>telnet some.host (flowConnecting to 192.168.100.4 port 23..recv: DO TermTypesend: WILL TermTyperecv: SB TermType SENDsend: SB TermType IS VT220recv: SB TermType SENDsend: SB TermType IS VT220recv: WILL Echosend: DO Echorecv: DO Window-Sizesend: WILL Window-Sizesend: SB NAWS 80 24session text begins here...
For a description of the meanings of any flow-control com-mands displayed, refer to RFC 854.
NOPROXY If the Telnet configuration file (/THEOS/CONFIG/TELNET.CFG:S) specifies a default proxy server, this option ignores that speci-fication and connects to the requested Telnet server address directly.
Telnet 639
Co
mm
an
ds
PCTERMPCTERM-aa Emulate PcTerm terminal display and specified language
keyboard. When -aa is not specified, the current default key-board definition is used.
PROXY 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 fol-lowing the PROXY option keyword:
>telnet myip.com (proxy 128.24.100.0
A default proxy server can be specified in the Telnet configura-tion 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 speci-fied 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 charac-ters are also copied to this file.
The TELNET.TRACE file is written to the system disk, root direc-tory, 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.)
-aa Language
-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
640 Telnet
Co
mm
an
ds
VT220 Requests VT-220 terminal emulation by the remote server. (Class code 220 on THEOS Telnet Server.)
Notes 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-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 sys-tem 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.
Telnet 641
Co
mm
an
ds
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 con-sole attachment to another size supported by your local system. If you change your console screen size during the Telnet session, when you termi-nate the session your console will be reset to its original width and depth.
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 (`),(`).
Non-VT220 emulations can use the (Break) key itself to transmit a break sig-nal.
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 com-mand 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.
642 Telnet
Co
mm
an
ds
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.
>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 Net, NetTerm, Setup, THEOS WorkStation Client
Telnet 643
Co
mm
an
ds
Example This first example shows a successful connection to an ISP.
>telnet ispname.com
Telnet Open >ISPNAME.COMConnecting...
Possible introductory information messages from the remote Telnet server
login: cpwPassword:
Other information messages from the remote Telnet server, such as:
For a menu driven interface type menu from the promptTERM was vt100Setting default terminal size to 80x24.pacifier:~% dir -ltotal 4drwx------ 2 cpw user 512 Aug 13 12:11 maildrwxr-xr-x 2 cpw user 512 Aug 22 08:07 public_htmpacifier:~%exitlogout
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.100Connecting...425 Unable to connect with remote host
644 Telnet
Co
mm
an
ds
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
Telnet Open >128.100.2.0Connecting...
HOMEOFFICE>show whoACCOUNT = REMOTEUSERNUM = 25PORT = 36PRIVLEV = 3LOGON = 11:10:20 11/14/97
HOMEOFFICE>
User name: [myname ]
Password: [******** ]
Terminal 645
Co
mm
an
ds
Terminal Command EXEC
The Terminal command is an EXEC language program that provides convenient, command-line access to the THEO_COM command’s terminal emulation capability.
Operation 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 ( options
options » ALF HALF SEND file WYSE50ANSI HANGUP THEOS WYSE60ASCII MASTER TRACE XMODEMCOMnn NOEOT TRACEFILE file XMODEM-CRCCTL NOLOGO TVI XMODEM-1KDIAL number PCTERM TYPE YMODEMEOF= RECEIVE file VT100EOT REDIAL VT220FILES SCRIPT file VT220-8
646 Terminal
Co
mm
an
ds
TFTP 647
Co
mm
an
ds
TFTP Command
The TFTP command is a Trivial File Transfer Protocol client that provides file transfer capa-bilities over a network between this client and any TFTP server available on the network.
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 Data-gram 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
1 TFTP RECEIVE host filename remote-filename
2 TFTP SEND host filename remote-filename
host » serverserver: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)
648 TFTP
Co
mm
an
ds
THEO+COM 649
Co
mm
an
ds
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.
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 func-tions 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 ( options
options » ALF HALF SEND file WYSE50ANSI HANGUP THEOS WYSE60ASCII MASTER TRACE XMODEMCOMnn NOEOT TRACEFILE file XMODEM-CRCCTL NOLOGO TVI XMODEM-1KDIAL number PCTERM TYPE YMODEMEOF= RECEIVE file VT100EOT REDIAL VT220FILES SCRIPT file VT220-8
Command synonyms: COM, TERMINAL
650 THEO+COM
Co
mm
an
ds
C90-C99 Synonym to the PCTERM option.
C180-C189 Synonym to the PCTERM option.
C100 Synonym to the VT100 option.
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 informa-tion about attaching COM devices.
CTL Sets control mode on. With control mode on every control char-acter 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 con-nection open.
DIAL must be the last option specified because characters fol-lowing 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-of-transmission character is sent after all of the files are trans-mitted. 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.
THEO+COM 651
Co
mm
an
ds
MASTER Use master-mode duplex communications in terminal emula-tion. 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 emu-lation; 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 estab-lished, 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 proto-col 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 ter-minal. C7 may be used as a synonym to this option.
TYPE Display dialing and redialing messages and responses. This is a default option.
652 THEO+COM
Co
mm
an
ds
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.
TheoMail 653
Co
mm
an
ds
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.
.
Operation 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 per-forms 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
1 THEOMAIL ( option
2 THEOMAIL mailbox ( option
mailbox » name of the mailbox to check
option » CHECKCOMPACTNOPROXYSEND
Command synonym: EMAIL
654 TheoMail
Co
mm
an
ds
have an alternate connection to your SMTP and POP3 servers available.
SEND Similar to the CHECK option, this invokes TheoMail in non-interactive mode. However, instead of checking for new mail it sends any mail that has been queued and then exits.
Notes 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 mes-sages 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 pro-gram without operator input. When TheoMail is invoked with an EXEC it
TheoMail 655
Co
mm
an
ds
may operate differently depending upon whether there is data on the EXEC stack and what that data is.
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:
&Stack Q\TheoMail mymailEmailChk 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 stan-dard text file.
If there is data on the EXEC stack but the first character is not a Control-Q, 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 <[email protected]>
Problem Report&EndTheoMail 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
656 TheoMail
Co
mm
an
ds
TIM 657
Co
mm
an
ds
TIM Command
The TIM command invokes the THEOS Instant Messenger and allows you to communicate with other users that are in your contact list.
Operation 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 pass-word filled in:
>tim "[email protected]" "paSsWoRd"
1 TIM
2 TIM passport password
3 TIM passport
passport » Passport E-mail account and domain
password » Password to the passport account
658 TIM
Co
mm
an
ds
Click on “Ok” to sign in. Refer to User Interface for descriptions of the vari-ous fields.
Mode 3—Similar to Mode 2 except the password is not typed in the com-mand line and therefore is never displayed in clear text.
Notes The TIM command uses a central configuration file to maintain the infor-mation about the passport account to use and the options desired for that account. You may have multiple accounts defined and there may be multi-ple 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 vari-able 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
TIM 659
Co
mm
an
ds
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.
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 E-mail 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 pass-port 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.
After you have acquired a passport account you can define the environ-ment 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 pass-word. 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 automat-ically.
660 TIM
Co
mm
an
ds
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.
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 con-tact names, etc.
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].
TIM 661
Co
mm
an
ds
Password Enter the password for the passport account. This is a case-sensitive field and the password is not displayed as you type it. Be careful to enter it correctly.
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 neces-sary changes.
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 spe-cific 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.
662 TIM
Co
mm
an
ds
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 the TIM session will “wake up” and make itself the active ses-sion 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 mes-sage 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.
TIM 663
Co
mm
an
ds
Style The style list box shows the various font styles that are avail-able 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.
Size 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 loca-tion 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).
664 TIM
Co
mm
an
ds
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 mes-saging server.
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.
TIM 665
Co
mm
an
ds
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.
666 TIM
Co
mm
an
ds
Using TIM
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.”
TIM 667
Co
mm
an
ds
Status This field defines your status as others see you.
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 ‘con-versation’ with 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 infor-mation 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 infor-mation 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 cur-rently highlighted contact in the Contact list.
668 TIM
Co
mm
an
ds
Chatting with a contact
When you select the Chat button or when a user on your Contact list ini-tiates 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 his-tory. Every message from the contact to you and every mes-sage 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 conver-sation.
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.
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.
TIM 669
Co
mm
an
ds
EmotIcons
Invite This button allows you to ask another member of your contact list to join in the chat conversation. When selected you are pre-sented 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:
670 TIM
Co
mm
an
ds
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
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 Select the group that you want this contact listed as.
TIM 671
Co
mm
an
ds
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.
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.
672 TIM
Co
mm
an
ds
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.
Touch 673
Co
mm
an
ds
Touch Command
Sets the date and time-stamp on a file.
Operation 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.fileFile "EXAMPLE.FILE:S" touched: 10/22/01 10:22:54One 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.fileFile "EXAMPLE.FILE:S" touched: 01/02/03 08:00:00One file changed.
Mode 3—The time-stamp for file is changed to date and time.
>touch 01/02/03 04:05:06 *.txtFile "EXAMPLE.TXT:S" touched: 01/02/03 04:05:06File "EXAMPLE1.TXT:S" touched: 01/02/03 04:05:06File "EXAMPLE2.TXT:S" touched: 01/02/03 04:05:063 files changed.
1 TOUCH file ( options
2 TOUCH date file
3 TOUCH date time file
file » file name with optional path; may contain wild cards
options » DATE reffile dateNOTYPE timeTYPE
date » date in current DATEFORM format
time » time specification using colon delimiters
674 Touch
Co
mm
an
ds
Options DATE reffileSet 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
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/97File "TEST.FILE:S" touched: 10/15/01 08:00:00One 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:32File "TEST.FILE:S" touched: 10/12/01 15:32:00One 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 Vari-ables” on page 111 of the THEOS Corona Version 5 Operating System Ref-erence 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
TraceRT 675
Co
mm
an
ds
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.”
Operation Mode 1—Traces the route between you and server, using default options of RESOLVE, and HOPS 30.
>tracert www.theos-software.comTracing route to WWW.THEOS-SOFTWARE.COM (65.45.113.228)over a maximum of 30 hops. 1 20 ms 10.88.74.1 2 20 ms bb1-ge2-1.potlnd1.or.home.net (65.4.47.1) 3 14 ms c1-pos5-2.ptldor1.home.net (24.7.75.229) 4 23 ms c1-pos1-0.snfcca1.home.net (24.7.64.22) 5 23 ms c2-pos1-0.snjsca1.home.net (24.7.65.161) 6 24 ms above-athome.sjc2.above.net (208.185.175.133) 7 106 ms core4-core3-oc48.sjc2.above.net (208.184.102.198) 8 24 ms pao1-sjc2-oc48-2.pao1.above.net (208.185.175.162) 9 26 ms allegainace-abovenet.allegiancetelecom.com (216.200.249.90)10 28 ms POS3-0.SNFECAEJ15W.core.algx.net (66.2.95.101)11 28 ms SNFECAEJ05W.gw.SFO.algx.net (216.99.234.11)12 33 ms 65-45-94-218.customer.algx.net (65.45.94.218)13 48 ms 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 10Tracing route to 199.2.117.161over a maximum of 10 hops. 1 11 ms 10.88.74.1 2 10 ms 65.4.47.1 3 11 ms 24.7.79.17 4 23 ms 24.7.64.22 5 25 ms 24.7.65.157 6 25 ms 129.250.9.85 7 24 ms 129.250.3.121 8 25 ms 129.250.3.162 9 28 ms 129.250.3.3410 27 ms 129.250.3.18 Trace complete.
1 TRACERT server
2 TRACERT server ( options
server » network server name or id (may also be localhost)
localhost » LOCALHOST
options » HOPS NORESOLVE RESOLVE
676 TraceRT
Co
mm
an
ds
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.
RESOLVE Translate each IP address to its domain name. This is a default option.
Notes TraceRT is used to determine how many routers are involved in a particu-lar 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 par-ticularly 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 Ping
Tree 677
Co
mm
an
ds
Tree Command
Displays the subdirectory tree.
Operation Mode 1—Starting at the current working directory, the directory tree structure is displayed on the standard output device.
Mode 2—Starting with path, the directory tree structure is displayed on the standard output device.
1 TREE ( options
2 TREE path ( options
path » starting directory name; may not include account name
options » NOSORTPRTnnSIZESORT
>pwd/VERTICAL:S
>tree/vertical
docprogramsfiles
programs
>pwd/VERTICAL:S
>tree /package/package
docprograms
678 Tree
Co
mm
an
ds
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.
PRTnn Indicates that Tree is to print the current directory tree struc-ture 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 (nosort/
datavertical
docprogramsfiles
programspackage
docprograms
miscprogramsdoc
>tree (size/ ............................... (1186, 29012K)
data ......................... (219, 17205K)misc ......................... (27, 77K)
doc ....................... (2, 16K)programs .................. (23, 54K)
package ...................... (248, 3162K)doc ....................... (5, 4K)programs .................. (240, 3150K)
vertical ..................... (648, 8401K)doc ....................... (33, 62K)
files .................. (19, 27L)programs ............... (11, 27K)
programs .................. (413, 4062K)
Tree 679
Co
mm
an
ds
SORT A default option that sorts the directory tree structure in alphabetical sequence.
Notes The line-graphics characters used to show the directory hierarchy are sup-pressed 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 (size/
datamisc
docprograms
packagedocprograms
verticaldoc
filesprograms
programs
680 Tree
Co
mm
an
ds
TWS 681
TW
STWS 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.
Operation Mode 1—Performs function on the THEOS WorkStation Client session win-dow.
>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 com-mand is used to execute another program.
1 TWS function
2 TWS Gutenberg-function
function » ACCOUNT FULL SENDALLOW MAXIMIZE SHELLCHANGE MINIMIZE TITLEDISCONNECT ONTOP TOPEXEC RECEIVEFOCUS RESTORE
Gutenberg-function» ALIGN FONT PRINT_WINDOWBARCODES HAS_FONTS REC_PAGECHANGE_AREAIMAGE ROTATECHECK_PRINTERLIST_FILE SELECT_AREACLOSE MODE SETPOSCOLOR NEW_FILE SIZEDEFAULT_UNITSPICTURE STYLEERASE_FILE PRINT_NEXT_PAGE TEXT_FILEFIELD PRINT_RECORDFILE_RECORDSPRINT_TXT
682 TWS
Co
mm
an
ds
Mode 2—
Functions These functions are used to control the TWS session and its display win-dow:
ACCOUNT
ALLOW Synonym to the DISCONNECT option.
CHANGE This option allows you to control whether or not the TWS ses-sion can lose the focus:
CHANGE OFF Disables the ability of the user to select another window, either manually with the mouse or key-board or with the EXEC mode of the Net. This func-tion 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 discon-nect the TWS session from the THEOS server:
DISCONNECT OFF Prevents the user from disconnecting this THEOS WorkStation Client session using the dis-connect 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
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. Sim-ilar to MAXIMIZE except there is no frame, scroll bars, menu
TWS 683
Co
mm
an
ds
bar, title, etc. The entire screen of the Windows system is used for the display of the THEOS server session.
MAXIMIZE 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 ses-sion 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 win-dows 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 mini-mized, 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.
684 TWS
Co
mm
an
ds
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.
TWS New_File ; start a new reportTWS Font "Times New Roman" ; set the fontTWS Style 2 ; boldfaceTWS Size 240 ; 24 pointTWS Align 1 ; centerTWS Print_Txt "This is the Title"TWS Align 3 ; left and right justifiedTWS Style 0 ; normalTWS Size 120 ; 12 pointTWS Print_Txt "Now is the time for all good men to come to"TWS Print_Txt "the aid of their party."TWS List_File prt3 ; print the report
TWS 685
Co
mm
an
ds
ALIGN
Define the text alignment and text background for subsequent text written to the report.
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 speci-fied, 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:
The alignment codes listed above can be combined together by adding the desired values.
tws align 3 ; left and right alignmenttws align 2+8+32+64 ; right, no wrap, frame and light gray bgtws align 106 ; right, no wrap, frame and light gray bg
Code Meaning
0x0000 0 Left0x0001 1 Center0x0002 2 Right0x0003 3 Justified0x0008 8 No wrap0x0020 32 Frame0x0040 64 Light gray background0x0080 128 White background0x00C0 192 Background color
TWS ALIGN align-code
align-code » Bit-mapped value indicating text alignment
686 TWS
Co
mm
an
ds
Each time that the align function is used it completely replaces any previ-ous alignment specifications but it only applies to text that is subsequently written to the report.
TWS 687
Co
mm
an
ds
BARCODES
Print text interpreted as barcode using the 3 of 9 barcode algorithm.
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:
Table 1: Unit of Measurement Codes
Code Meaning
0x0001 1 Pixels
0x0002 2 Columns and rows
0x0004 4 Millimeters
0x0008 8 Inches
0x0010 16 Decipoints
TWS BARCODES text width height units fontname
text » 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
688 TWS
Co
mm
an
ds
Multiple barcodes can be printed with one command by enclosing the string in quotation marks.
tws barcodes 12345-67890tws barcodes "09876 54321" 10 0 4
TWS 689
Co
mm
an
ds
CHANGE_AREA
Change some of the attributes of an existing window area.
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
tws print_window 4 3 2 20 10 4+32+64+256 ; repeat odd pages...tws change_area 4 384 ; repeat on all pages
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 CHANGE_AREA window last-page flags
window » Number of existing window
last-page » Optional last page number to use window
flags » Optional flags to change
690 TWS
Co
mm
an
ds
CHECK_PRINTER
Test an attached printer to see if it is a Gutenberg-capable printer.
Test printer prt to determine if it is a Gutenberg printer. If prt is not spec-ified 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.
?????? Why, what does closing it do? It is hardcopy after all.
tws align 0xC8
TWS CHECK_PRINTER prt
TWS HAS_FONTS prt
prt » Attached printer name to test
TWS CLOSE window
window » Number of window containing image/picture
TWS 691
Co
mm
an
ds
COLOR
Set the font color for subsequent text output to the report.
Sets the color of text that is subsequently output to the report. The fore-ground (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 speci-fied, then the colors specified here only applies to the currently selected print window (see “SELECT_AREA” on page 702). If extended is not speci-fied, which is the default, then the colors specified here apply to all win-dows.
tws color 0xFFFFFF 0xFF0000 ; white on red
Some common color definitions:
Code Color
0x000000 Black0x000080 Blue0x008080 Cyan (green+blue)0x008000 Green0x404040 Grey0x0000FF Intense blue0x00FFFF Intense cyan0x00FF00 Intense green0xFF00FF Intense magenta0xFF0000 Intense red0xFFFF00 Intense yellow0x800080 Magenta (red+blue)0x800000 Red0x808080 White or light grey0x808000 Yellow (red+green)
TWS COLOR fg bg
fg » Foreground color code
bg » Background color code
692 TWS
Co
mm
an
ds
DEFAULT_UNITS
Set the default unit-of-measurement to be used by functions that do not specify a U/M explicitly.
When this function is not used the default U/M is decipoints which is of a point or of an inch.
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 ; set to inches...tws default_units 2 100 ; set to 100 characters per line...tws default_units 2 0 60 ; set to 60 lines per page
TWS DEFAULT_UNITS unit-codes columns rows
unit-code » Unit of measurement code
columns » Optional number of columns
rows » Optional number of rows
110------
1720---------
TWS 693
Co
mm
an
ds
FIELD
Output a field containing the current value of a variable.
xxxx
Variable field names
Mask codes
Name Meaning
PAGE Current page number
DATE Current date
TIME Current time
ENV Environment variable
Field Code Meaning
PAGE %u Current page number
DATE
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 Month number, one or two digits
MM Month number, two digit
MMM 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 FIELD field mask
field » Field name
mask » String specifying formatting information
694 TWS
Co
mm
an
ds
>tws align 0xC8
TIME
hh Two-digit hour number, 12-hour format
H Hour number, 24-hour format, one or two digits
HH Hour number, 24-hour format, two digits
m Minute number, one or two digits
mm 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
ENV text Environment name
Field Code Meaning
TWS 695
Co
mm
an
ds
FILE_RECORDS
xxxx
Flag codes
>tws align 0xC8
FONT
Select the font to use for subsequent text output.
The default font is “Arial.”
>tws font "Times Roman"
IMAGE
Output the graphic image file to the report at the current position.
Code Meaning
0x0400 1024
0x0800 2048
TWS FILE_RECORDS xxxx flags divider first lines
xxxx »
flags »
divider »
first »
lines »
TWS FONT font-name
font-name » Complete name of font on client system
696 TWS
Co
mm
an
ds xxxx
Flag codes
>tws align 0xC8
LIST_FILE
Close the current report and print it on an attached printer.
xxxx
>tws align 0xC8
MODE
Define the page orientation for the report.
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 IMAGE filename flags
filename » Name of image file
flags » Code indicating image-type and scaling
TWS LIST_FILE prt
prt » Name of attached printer
TWS 697
Co
mm
an
ds
xxxx
Mode codes
>tws align 0xC8
NEW_FILE
Begin a new report.
Any existing report that has not been output to the printer (see “LIST_FILE” on page 696) is cleared and not printed.
Code Meaning
0x0000 0 Portrait orientation
0x0100 256 Landscape orientation
0x0400 1024 Extended windows
0x1000 4096 Duplex horizontal
0x2000 8192 Duplex vertical
TWS MODE mode-code
mode-code » Orientation code
TWS NEW_FILE
TWS ERASE_FILE
698 TWS
Co
mm
an
ds
PICTURE
xxxx
Flag codes
>tws align 0xC8
PRINT_NEXT_PAGE
Add a page break to the report.
xxxx
Code Meaning
0x0000
TWS PICTURE window x y width height filename flags
window »
x »
y »
width »
height »
filename »
flags »
TWS PRINT_NEXT_PAGE
TWS 699
Co
mm
an
ds
>tws align 0xC8
PRINT_RECORD
Output the fields of a table record to the printer.
xxxx
>tws align 0xC8
PRINT_TXT
Output some text to the report.
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 print_txt "This is some text in a paragraph."tws print_txt " This is another sentence in the same paragraph."tws print_txttws print_txt "Second paragraph with a break but no blank line "tws print_txt "between the paragraphs when printed."
TWS PRINT_RECORD record divider
record »
divider »
TWS PRINT_TXT text
text » Text string
700 TWS
Co
mm
an
ds
PRINT_WINDOW
Define a print area on the report.
xxxx
Flag codes
>tws align 0xC8
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 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
TWS 701
Co
mm
an
ds
REC_PAGE
xxxx
Align codes
>tws align 0xC8
ROTATE
Set the rotation angle for text that is subsequently output to the report.
A positive angle value indicates a clockwise rotation direction; negative values are a counter-clockwise rotation direction.
Code Meaning
0x0000
TWS REC_PAGE action first last type
action »
first »
last »
type »
TWS ROTATE angle
angle » Angle in degrees
702 TWS
Co
mm
an
ds
>tws align 0xC8
SELECT_AREA
Select a previously defined window for subsequent text output.
xxxx
>tws align 0xC8
SETPOS
Position the print-head cursor for subsequent text written to the report.
xxxx
Align codes
Code Meaning
TWS SELECT_AREA window
window »
TWS SETPOS x y units window
x »
y »
units »
window »
TWS 703
Co
mm
an
ds
>tws align 0xC8
SIZE
Set the font size for subsequent text output to the report.
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.
xxxx
Style codes
Code Meaning
0x0000 0 Normal
Code Meaning
TWS SIZE width height units
width » Optional font width
height » Optional font height
units » Optional code for unit of measurement
TWS STYLE style-code
style-code » Bit-mapped code for font style
704 TWS
Co
mm
an
ds
>tws align 0xC8>tws style 0x101 ;
TEXT_FILE
Include a text file in the printer output.
xxxx
Flags
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
Code 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 associ-ated with the file’s extension.
0x4000 16384 The file is printed by the client machine.
Code Meaning
TWS TEXT_FILE filename flags start-line lines
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
TWS 705
Co
mm
an
ds
>tws align 0xC8
Notes Although this program can be executed from the command line, it is nor-mally 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 WorkSta-tion 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
0x8000 32768 File resides on client machine. The filename must conform to the syntax rules of the client machine.
Code Meaning
706 TWS
Co
mm
an
ds
UnErase 707
Co
mm
an
ds
UnErase Command
This command allows you to restore a file that has been previously erased and placed in the recycle bin.
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 com-mand 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 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.
Defaults 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.
1 UNERASE
2 UNERASE drive
3 UNERASE drive ( CLEAR
4 UNERASE file ( options
drive » Drive code or label of attached hard disk or image drive
file » File name with optional path; may contain wild cards
options » NOTYPETYPE
708 UnErase
Co
mm
an
ds
For Mode 3, you must be logged on to the SYSTEM account and have a privi-lege level of 5.
User Interface 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.
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:
UnErase 709
Co
mm
an
ds
Sequence 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 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.
See also Erase, FileManager, RmDir
710 UnErase
Co
mm
an
ds
UnInstall 711
Co
mm
an
ds
UnInstall Command
The UnInstall command removes all of the files associated with an installed product.
Operation 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 unin-stall 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 prod-uct 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
712 UnInstall
Co
mm
an
ds
convenient if you need to reinstall the product at a later time. After rein-stallation, the prior configuration file is still there and will be used again.
Some products require other products to operate. For instance, a network-ing 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
Unique 713
Co
mm
an
ds
Unique Command Filter
Unique copies standard input to standard output, or copies one file to another, omitting any duplicated lines.
The examples used in the descriptions that follow use an input file con-taining:
>list sample.file
The 1st line.The 2nd line.The 2nd line.The 2nd line.And the third line.The last line.The last line.
Operation 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.fileThe 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 writ-ten to the standard output device.
>unique sample.file > unique.lines
1 UNIQUE infile outfile ( options
2 UNIQUE infile ( options
3 UNIQUE ( options
infile » file name with optional path
outfile » file name with optional path
options » COUNTDUPUNIQUE+nnnnnn
714 Unique
Co
mm
an
ds
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.
Options COUNT Each line in the file is output preceded by a count of the num-ber 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 dupli-cated line in the file. All unique lines in the input file are not copied to the output file.
>unique sample.file (dupThe 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.fileThe 1st line.The 2nd line.And the third line.The last line.
>unique sample.file (uniqueThe 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 (+7The 1st line.And the third line.The last line.
Unique 715
Co
mm
an
ds
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 count4 The 1st line.1 And the third line.2 The last line.
Notes 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 Vari-ables” on page 111.
Restrictions infile must be a stream file.
See also List, Sort
716 Unique
Co
mm
an
ds
Unload 717
Co
mm
an
ds
Unload Command
The Unload command unloads a program or data file from 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. How-ever, 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 program
program » name of program or file to load into memory
718 Unload
Co
mm
an
ds
Unnumber 719
Co
mm
an
ds
Unnumber Command Filter
Unnumber copies a file to the standard output device, removing any line number from each line as it is copied.
Operation Mode 1—Each file is copied to the standard output device and unnum-bered 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 DoeOPTION VERSION 1.1,"Copyright 2001 by ABC Software."IF CMDARG$(1)=""GOSUB COMPUTE.JULIANELSE GOSUB COMPUTE.DATEIFEND...
>unnumber program1.basic program2.basic! Program: JULIAN Compute Julian date! Programmer: Jane DoeOPTION VERSION 1.1,"Copyright 2001 by ABC Software."IF CMDARG$(1)=""...! Program2: Compute late charge.INPUT "beginning balance",AMOUNTINPUT "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 result-ing line is blank, it is not output.
1 UNNUMBER file...
2 UNNUMBER
file » file name with optional path
720 Unnumber
Co
mm
an
ds
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:
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 Number
UnZip 721
Co
mm
an
ds
UnZip Command
This command lists, tests or extracts compressed files from a ZIP archive.
Operation Mode 1—The files in the zipfile are restored into the current working directory.
>unzip cdromArchive: 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 destina-tion 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 speci-fying 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.
1 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
722 UnZip
Co
mm
an
ds
Options The following options may be combined into a single specification. For instance, to request quiet mode (-q) and replace mode (-o) you would spec-ify -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 cdromArchive: CDROM.zip Length Date Time Name -------- ---- ---- ---- 1474560 02-16-02 10:50 diskette.img 26214400 02-16-02 10:51 theos.img 748 01-30-02 15:29 pluspak.exc 3876 02-16-02 10:48 pluspak.instcmp -------- ------- 27693584 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.
UnZip 723
Co
mm
an
ds
-q Quiet mode. This is the equivalent of the NOTYPE option used by other THEOS commands.
>unzip -tq cdrom.zipNo 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.
>unzip -t cdrom.zip
Archive: CDROM.ZIP testing: diskette.img OK testing: theos.img OK testing: pluspak.exc OK testing: pluspak.instcmp OKNo errors detected in compressed data 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 cdromArchive: 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 fooArchive: FOO.zip
724 UnZip
Co
mm
an
ds
-Z Display the zip file directory. Compare to the -v option.
>unzip "-Z" cdromArchive: CDROM.zip 23062393 bytes 4 filesS.M...... 2.3 ths 1474560 bx defN 16-Feb-02 10:50 diskette.imgS.M...... 2.3 ths 26214400 bx defN 16-Feb-02 10:51 theos.imgS........ 2.3 ths 748 tx defN 30-Jan-02 15:29 pluspak.excS.MW..... 2.3 ths 3876 bx defN 16-Feb-02 10:48 pluspak.instcmp4 files, 27693584 bytes uncompressed, 23061829 bytes compressed: 16.7%
This option allows you to use additional options that are spe-cific to this listing:
-1 Display the file names only.
>unzip -Z -1 cdromdiskette.imgtheos.imgpluspak.excpluspak.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 cdromArchive: CDROM.zip 23062393 bytes 4 filesdiskette.imgtheos.imgpluspak.excpluspak.instcmp
>unzip -Z -2ht cdromArchive: CDROM.zip 23062393 bytes 4 filesdiskette.imgtheos.imgpluspak.excpluspak.instcmp4 files, 27693584 bytes uncompressed, 23061829 bytes compressed: 16.7%
-h Display heading line.
>unzip -Z -h cdromArchive: CDROM.zip 23062393 bytes 4 files
-l 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.
UnZip 725
Co
mm
an
ds
-m Display the zip file directory in Unix “ls -l” medium format.
>unzip -Z -m cdromArchive: CDROM.zip 23062393 bytes 4 filesS.M...... 2.3 ths 1474560 bx 13% defN 16-Feb-02 10:50 diskette.imgS.M...... 2.3 ths 26214400 bx 17% defN 16-Feb-02 10:51 theos.imgS........ 2.3 ths 748 tx 47% defN 30-Jan-02 15:29 pluspak.excS.MW..... 2.3 ths 3876 bx 63% defN 16-Feb-02 10:48 pluspak.instcmp4 files, 27693584 bytes uncompressed, 23061829 bytes compressed: 16.7%
-s Display the zip file directory in Unix “ls -l” short format.
>unzip -Z -s cdromArchive: CDROM.zip 23062393 bytes 4 filesS.M...... 2.3 ths 1474560 bx defN 16-Feb-02 10:50 diskette.imgS.M...... 2.3 ths 26214400 bx defN 16-Feb-02 10:51 theos.imgS........ 2.3 ths 748 tx defN 30-Jan-02 15:29 pluspak.excS.MW..... 2.3 ths 3876 bx defN 16-Feb-02 10:48 pluspak.instcmp4 files, 27693584 bytes uncompressed, 23061829 bytes compressed: 16.7%
-t Display the totals line.
>unzip -Z -t cdrom4 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: 23060570 (015FE05Ah) bytes file system or operating system of origin: Theos version of encoding software: 2.3 minimum file system compatibility required: MS-DOS, OS/2 or NT FAT minimum software version required to extract: 2.0 compression method: deflated compression sub-type (deflation): normal file security status: not encrypted extended local header: no file last modified on (DOS date/time): 2002 Feb 16 10:48:24 32-bit CRC value (hex): a8b548b9 compressed size: 1435 bytes uncompressed size: 3876 bytes length of filename: 15 characters length of extra field: 18 bytes length of file comment: 0 characters disk number on which file begins: disk 1 apparent file type: binary Theos file attributes (87FD hex): Sequential .MW..... MS-DOS file attributes (00 hex): 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.
726 UnZip
Co
mm
an
ds
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 com-patible with the DOS-based PKZIP by PKWARE, Inc. This version is avail-able 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
Upcase 727
Co
mm
an
ds
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.
Operation Mode 1—file is copied to the standard output device with all lowercase let-ters converted to uppercase. The original file is unchanged.
>upcase /theos/config/crt.cfgSCREENSAVER=0YESSCANCODE=0X15NOSCANCODE=0X31RESETLITERAL=OK TO REBOOT? (Y/N)MOUSE=0INTELLIMOUSE=FALSEKEYPADMODE=TRUEREPEATRATE=30...
>upcase /theos/config/crt.cfg > crt.config
Mode 2—Copies standard input to standard output, converting all lower-case letters to uppercase. This form is normally used only in a pipe. How-ever, 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
1 UPCASE file
2 UPCASE
3 UPCASE directory
4 UPCASE library
file » file name with optional path; wild cards are not allowed
directory » path to file names
library » library name of member files
Command synonym: UC
728 Upcase
Co
mm
an
ds
Mode 3—All of the file names in directory are converted to use uppercase-only characters. Files in subdirectories of directory and members of librar-ies in directory are not renamed. This mode of Upcase is not a filter.
>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
Viewer 729
Co
mm
an
ds
Viewer Command
The Viewer command displays and allows you to browse the contents of text files.
Operation 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 navi-gation 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 file... ( options
file » file name with optional path; may contain wild cards
options » FILES NUMBER WINDOWMAXIMIZE TITLE
730 Viewer
Co
mm
an
ds
Options FILES Indicates that file is an ASCII stream file with each record in the file specifying a single file name. The file name specifica-tions in this file may include the path and wild cards.
The SELECTED.FILES and SELECTED.EXEC files created by FileList and FileManager and the FOUND.EXEC created by Look and FileM-anager 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 exam-ined:
>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 fol-lowing 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 imme-diately following the TITLE keyword. The title text should be enclosed within quotation mark characters.
Viewer 731
Co
mm
an
ds
>view selected.files (title "List of files to view"
WINDOW This option allows you to specify the initial Viewer form posi-tion and size. When the option is not used the Viewer form’s ini-tial 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 posi-tioned 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 “Ses-sions, 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 char-acters into the viewer display, no change is made to the actual text file.
732 Viewer
Co
mm
an
ds
Printing Files 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/user-name/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
VNC Client 733
Co
mm
an
ds
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.
Operation 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 remem-bered 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 pass-word is required you will be asked:
Remember that passwords are case-sensitive.
1 VNC host
host » IP address or name of machine running VNC server
734 VNC Client
Co
mm
an
ds
After a valid password is entered and accepted by the server the connec-tion 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 res-olution 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 communi-cated to and will control the remote desktop. To exit from VNC use the (Break),(Q) sequence.
VNC Client 735
Co
mm
an
ds
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.
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 sub-rectangles 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 rep-resent the dimensions of the subrectangles. For a typical desk-top, 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 con-sists 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.
736 VNC Client
Co
mm
an
ds
Misc. Miscellaneous options.
Request shared session Normally, when you establish a VNC connection 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 two-button 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 mid-dle 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 pix-els 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
VNC Client 737
Co
mm
an
ds
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 Gen-eral Public License.
The VNC logo 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
738 VNC Client
Co
mm
an
ds
WhereIs 739
Co
mm
an
ds
WhereIs Command
This command searches the directory tree of the current account looking for all instances of a file name.
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.
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 file... ( options
file » file name with optional path; may contain wild cards
options » date1date2
>tree //
dataabc
docprogramsfiles
programsPrograms
BackupsdocSpecial
>whereis backups.c
740 WhereIs
Co
mm
an
ds
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.
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 main-tained 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 direc-tory of the current account.
Restrictions You may only search for files in the current account.
See also ChDir, FileManager
Which 741
Co
mm
an
ds
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.
Operation 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 speci-fied. As soon as a program file is found matching file its complete path is displayed.
>which filemanSYSTEM\Programs/FileManager/FileMan.cmd:s
>which fm makeimgSYSTEM\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 pro-gram 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/MYPROG.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 exe-cuted when the path and/or file extension is not specified.
See also FileList, FileManager, Find, WhereIs
WHICH file ...
file » program name with optional file-type
742 Which
Co
mm
an
ds
Who 743
Co
mm
an
ds
Who CommandWhoAmI 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.
Operation 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: SYSTEMAccount Number: 0
User Name: MynameLogon Date: 10 April 2002, 09:52 AM
Pid: 10Console: NET1 C210,L80,P24,REMOTE=JUPITER
Description: Primary Corona system Workgroup: ACCOUNTING Server Name: SaturnServer Address: 192.168.1.100 Client Name: JUPITER
1 WHO
2 WHO AM I
3 WHOAMI
744 WhoAmI
Co
mm
an
ds
Client Address: 192.168.1.104
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 HELP CRT1:1 C90,L80,P292 SYSTEM CSI CRT1:2 C90,L80,P293 SAMPLES CSI CRT1:3 C90,L80,P334 SYSTEM CSI CRT1:4 C90,L80,P295 SYSTEM CSI CRT1:5 C90,L80,P336 LOGON CRT1:8 C90,L80,P24
16 PRIVATE WHO NET1 C210,L80,P28,REMOTE=DocSystem
>
See also Show
WhoIs 745
Co
mm
an
ds
WhoIs Command
Queries the Internet domain database regarding registered domain name and users.
Operation Mode 1—Issues a request to the Internet domain database to get the reg-istered information about a second-level domain name.
>whois theos-software.comRegistrant: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 65.45.113.228 DNS2.THEOS-SOFTWARE.COM 65.45.113.229 NS1.ALGX.NET 216.99.225.30 NS2.ALGX.NET 216.99.225.31
1 WHOIS domain
2 WHOIS "user"
3 WHOIS #handle
domain » second-level domain name
user » user name in form of “last-name, first-name”
handle » user handle
746 WhoIs
Co
mm
an
ds
Mode 2—Issues a request to the Internet domain database to get the reg-istered information about a user contact.
Note that, in the Mode 1 example, the administrative contact is “THEOS Hostmaster:”
>whois "THEOS Hostmaster"
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 reg-istered 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 han-dles.
Notes Although all second-level domains are registered, only the responsible par-ties 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 NsLookup
747
Co
mm
an
ds
Window Management Commands
These 18 commands are primarily used by EXEC language programs to provide window and session management control.
1 wBypass mode
2 wClear window char
3 wClip window clip
4 wClose window
5 wClose ALL
6 wColor window Fg Bg Rfg Rbg
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
748
Co
mm
an
ds
align » LEFTCENTERRIGHT
attribute » bit-mapped color and attributesfg bg
bg » background color code or name (black, blue, green, cyan, red, magenta, yellow and white)
char » character or character valueclip » OFF
ON
col » leftmost column numbercolumns » width of window (1–255)count » number of items in menu listdisplay » TOP
HIDDEN
fg » foreground color code or name (black, blue, green, cyan, red, magenta, yellow and white)
file » file name with optional pathframe » NONE
SINGLEDOUBLERAISEDSUNKEN
invert » OFFON
mode » OFFON
row » topmost row numberrows » height of window (1–255)session » session number (1–8)shadow » NONE
LEFTRIGHT
switch » OFFON
title » text for window titletop-bottom » BOTTOM
TOP
update » OFFON
window » window number
749
Co
mm
an
ds
wBypass The wBypass command enables or disables the window manager’s bypass mode.
>wbypass off
Normally, window manager bypass mode is off, meaning that all charac-ters sent to the console are intercepted and processed by the window man-ager. 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.
>wbypass on
When window manager bypass mode is enabled, characters sent to the console are not intercepted by window manager. The character is dis-played immediately on the console and it is not saved in any window in memory.
Invoking wBypass with no parameter displays the current window man-ager bypass mode.
>wbypassBypass 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 Ver-sion 5 Operating System Reference manual for a list of characters sup-ported by THEOS.
The window must be selected or refreshed to see the effects of this com-mand.
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.
750
Co
mm
an
ds
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.
>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.
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.
Code Name Code Name
0 Black 4 Red
1 Blue 5 Magenta
2 Green 6 Yellow
3 Cyan 7 White
751
Co
mm
an
ds
wInvert The wInvert command changes the normal video/reverse video status of the indicated window. Although this command can be used on color or mono-chrome 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 14 on
>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.
&begstackItem 1Item 2Item 3&end
wmenu 3 5 10
Blank items in the list of menu choices display as a horizontal line. For instance:
&begstackItem 1Item 2Item 3
Last Item&end
wmenu 5 5 10
Item 1Item 2Item 3
Item 1
752
Co
mm
an
ds 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.
Item 1Item 2Item 3
Last Item
Item 1
753
Co
mm
an
ds
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.
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 selec-tion of the item. For instance:
&begstack6 Item 16 Item 26 Item 3&end
wmenu 3 5 10 HOT
In this list, the sixth character of each item is the hot-key character. Char-acter positions are counted starting with the first non-space character fol-lowing 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 hot-key. 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 under-lined 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 high-light bar to the next item that starts with that character. If there are no
Item 1Item 2Item 3
Item 1
754
Co
mm
an
ds
more items starting with that character, then the highlight bar moves to the first item starting with the character.
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, set-ting 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 vir-tual 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:
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
Icon name Displays
Exclamation
Information
Question
Stop
755
Co
mm
an
ds
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.
Type. This parameter specifies the operator response buttons that are dis-played in the message box form. It can be specified with a numeric code or a mneumonic code.
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.
Code Mneumonic Buttons
0 O OK
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 Cancel
7 YNAN Yes, No, Yes to All and No to All
8 NONE No buttons
756
Co
mm
an
ds
Return code. The return code is set according to the way that the message form is exited.
wOpen The wOpen command defines a new window or redefines an existing win-dow. 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). col-umns 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
Return Code Exited by
0 The (Esc) key, mouse clicking on the (X) symbol or the WAIT seconds timed out.
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.
757
Co
mm
an
ds
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 mem-ory.
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 insuffi-cient 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 dis-played. The wSelect command changes the order of display for a window.
>wopen 1 10 5 58 10
>wframe 1 sunken right
>wtitle 1 " Window 1 " top center
>wselect 1
Window 1
>
758
Co
mm
an
ds
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.
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.
759
Co
mm
an
ds
wSave The wSave command saves a window description and contents to a disk file.
wopen 1 46 4 30 3wframe 1 double right 0x17wclip 1 onwselect 1 topcolor 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 poffwselect 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 dis-play 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.
760
Co
mm
an
ds
Window zero is always open and can be selected with this command but it cannot be specified as TOP or HIDDEN.
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 dis-played 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 sta-tus.
>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.
761
Co
mm
an
ds
wStat The wStat command displays the general status for all windows, the com-plete 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.
>wopen 1 2 2 70 20
>wopen 2 4 4 68 18
>wopen 3 6 6 66 16
>wstat0* 80x24 beg=0,0 cur=0,11 order=0 update=11 70x20 beg=1,1 cur=0,0 order=-1 update=02 68x18 beg=3,3 cur=0,0 order=-1 update=03 66x16 beg=5,5 cur=0,0 order=-1 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.
762
Co
mm
an
ds
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.
wstat ?&type The current window number is &retcode&curr_window = &retcode
Specific Window Status. When wStat is given a window number, the com-plete status of that window is displayed.
>wselect 2 >wstat 2status: 1begin col,row: 3,3width: 68height: 18curr col,row: 0,6cursor: 0frame-type: 2shadow-type: 1title-type: 2title-align: 2title-attr: 0x1C5Fframe-attr: 0x1C5Fclip: 1update: 0curr-attr: 0x1C5Forder: 0color: 7,5,7,0invert: 0
763
Co
mm
an
ds
Status Element Meaning Codes Used
status Window status 0 = Not open1 = Open, not active2 = Open, active
begin col,row Window interior origin, base zero
width Window interior width, base one
height Window interior height, base one
curr col,row Cursor location, base zero
cursor Cursor display type 0 = Not displayed1 = Blinking underline2 = Blinking block3 = Steady underline4 = Steady block
frame-type Frame style 0 = None1 = Single line2 = Double line3 = Raised4 = Sunken
shadow-type Shadow style 0 = None1 = Right2 = Left
title-type Title position 0 = None1 = Top2 = Bottom
title-align Title alignment 0 = Center1 = Left2 = Right
title-attr 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 0 = Off1 = On
update Update and display status
0 = Update OFF
1 = Update ON
2 = Update ON, TOP
4 = Update OFF, HIDDEN
764
Co
mm
an
ds
Specific Window Field Status. You may get a specific parameter of a spe-cific 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:
curr-attr Bit-mapped value indicating the current window interior foreground and background colors and the attributes.
order Window display sequence
Lowest or bottom-most win-dow is 0. A -1 means win-dow is not displayed (hidden or has never been displayed).
color Window interior color codes for fg, bg, rvfg, rvbg.
invert Monochrome invert status
0 = Off1 = 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 func-tions in a program. Refer to the language’s reference manual for a description of these codes.
Code Field
0 Status
1 Top left column
2 Top left row
3 Width
4 Height
5 Current cursor column
6 Current cursor row
Status Element Meaning Codes Used
765
Co
mm
an
ds
wSwitch 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
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
Code Field
766
Co
mm
an
ds
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.
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
WinWrite 767
Co
mm
an
ds
WinWrite Command
The WinWrite command invokes the WindoWriter program, which is a general purpose, full-screen text editor.
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 specifica-tions 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 specifi-cation 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 applica-tion program.
For instance, FileList is used to create a list of files to be exam-ined:
>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 fol-lowing command edits these files:
WINWRITE file... ( options
file » file name with optional path; may contain wild cards
options » FILES NOSHELL READONLYNOBACKUP PASSWORD
Command synonym: WW
768 WinWrite
Co
mm
an
ds
>ww selected.exec (file
The FileManager command can also create and add to SELECTED.EXEC, SELECTED.FILES and FOUND.EXEC files.
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 per-formed 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 Win-doWriter 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 informa-tion 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 FILE-TYPE is defined.
For more information about the FILETYPE variable, see “Environment Vari-ables” on page 111 of the THEOS Corona Version 5 Operating System Ref-erence manual.
WinWrite 769
Co
mm
an
ds
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.
Defaults 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
770 WinWrite
Co
mm
an
ds
WordCount 771
Co
mm
an
ds
WordCount Command
This command counts lines, words and characters in a stream file.
Operation 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 Words Chars File-name554 14,537 31,694 /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 aidof their party.(Ctrl)+(D)
Lines Words Chars File-name 3 26 119
1 WORDCOUNT file... ( options
2 WORDCOUNT file... ( FILES options
file » file name with optional path; may contain wild cards
options » BYTESCHARSFILESLINESWORDS
Command synonym: WCOUNT
772 WordCount
Co
mm
an
ds
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
Lines Words Chars File-name 55 1,127 5,635 first.file
120 2,500 10,389 second.file32 600 1,357 third.file
207 4,227 17,381 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.countssystem.history:s*.log:s
>wc daily.counts (file Lines Words Chars File-name
13,398 200,690 862,356 system.history250 2,435 10,389 private.log
3,029 4,398 25,942 user.log16,677 207,523 898,687 Totals 3
WordCount 773
Co
mm
an
ds
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
Chars File-name 31,694 /THEOS/CONFIG/DEVNAMES.TXT
LINES Count and display the total number of lines or records in the file.
>wordcount /theos/config/devnames.txt (lines
Lines File-name 554 /THEOS/CONFIG/DEVNAMES.TXT
WORDS Count and display the total number of words in the file.
>wordcount /theos/config/devnames.txt (words
Words File-name 14,537 /THEOS/CONFIG/DEVNAMES.TXT
Notes 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/lan-guage/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 Vari-ables” on page 111 of the THEOS Corona Version 5 Operating System Ref-erence manual.
Defaults Unless a specific option is specified, CHARS, LINES and WORDS are dis-played by default.
Restrictions file must be a stream file.
774 WordCount
Co
mm
an
ds
Zip 775
Co
mm
an
ds
Zip Command
This command lists, tests or creates compressed files in a ZIP archive.
Operation 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 65%) adding: beta3.htm (deflated 62%) adding: beta4.htm (deflated 67%) adding: beta5.htm (deflated 63%) adding: beta6.htm (deflated 63%)Enter comment for beta2.htm:Comment for file oneEnter comment for beta3.htm:Comment for the second fileEnter comment for beta4.htm: Enter comment for beta5.htm:This is my comment for the beta5.htm fileEnter comment for beta6.htm:My last comment, for the beta6.htm file
1 ZIP zipfile filename...
2 ZIP -options zipfile filename...
zipfile » Archive file
filename » Name of file to add to archive file
options » Options for archiving
776 Zip
Co
mm
an
ds
>unzip -l htmsArchive: HTMS.zip Length Date Time Name -------- ---- ---- ---- 34262 08-24-00 15:45 beta2.htmComment for file one 23593 10-03-00 00:42 beta3.htmComment for the second file 34194 03-07-01 11:27 beta4.htm 21651 08-30-01 11:03 beta5.htmThis is my comment for the beta5.htm file 22811 12-12-01 13:58 beta6.htmMy 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.htmdeleting: beta3.htmdeleting: beta6.htm
>unzip -l htmsArchive: HTMS.zip Length Date Time Name -------- ---- ---- ---- 34262 08-24-00 15:45 beta2.htm 34194 03-07-01 11:27 beta4.htm 21651 08-30-01 11:03 beta5.htm -------- ------- 90107 3 files
-D When the zipfile is created with the -r option (include subdirec-tories) 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 examplefreshening: some.txt (deflated 71%)
Zip 777
Co
mm
an
ds
-F Examine the archive file and correct any errors found.
>zip -F examplezip: reading examplemenu.commandzip: reading examplescreen.commandzip: reading testgutenberg.commandzip: reading testit.commandzip: reading testprt.command
-h Display help text.
-j Do not include the path when archiving a file. Compare the fol-lowing two zips:
>zip example /corona-cd/*.htm adding: corona-cd/beta2.htm (deflated 65%) adding: corona-cd/beta3.htm (deflated 62%) adding: corona-cd/beta4.htm (deflated 67%) adding: corona-cd/beta5.htm (deflated 63%) adding: corona-cd/beta6.htm (deflated 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/WIn-dows 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.
778 Zip
Co
mm
an
ds
-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.
>zip -T mailwavstest 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.fileFile "/MYDIRECTORY/SOME.FILE:S" touched: 02/20/2002 10:58:49One file changed
>zip -u exampleupdating: some.file (deflated 53%)
-v Enables verbose operation. Compare the following two com-mands:
>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.
Zip 779
Co
mm
an
ds
.
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.
-0 Do not compress the files, just store them in the zipfile.
-1 Compress the files into zipfile faster at the expense of the com-pression 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, 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 UnZip
780 Zip
Co
mm
an
ds
781
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 con-tact their THEOS dealer regarding questions or problems relating to instal-lation or operation of the THEOS operating system and other THEOS products.
THEOS Support Services for Resellers and Distributors are designed to pro-vide 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 sup-port 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.
782
Co
mm
an
ds
On-line system helps. Virtually all THEOS software has some form of on-line 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.
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.comhttp://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 simi-lar situation.
Attachments can and should be included with your postings when appro-priate. 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 Inter-net 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:
783
Co
mm
an
ds
Internet “Dealer Forum” and “Corona Forum”. For SDK dealers and developers a general dealer-to-dealer forum and a Corona-specific dealer-to-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.
http://www.theos-software.com/forums/
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 ques-tions 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 avail-able 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 211Hours: 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 inform-ing them that the package is being sent.
THEOS Technical SupportTHEOS Software Corporation1801 Oakland Boulevard, Suite 315Walnut Creek, CA 94596-7000
784
Co
mm
an
ds