Apple® IIGS Spectrum™ 2.5.6 Reference Manual Notes on Freeware Edition From an initial inception as a IIgs communications program called Impala, Spectrum was developed and released under the guidance of Dave Hecker of Seven Hills International. Originally released back in 1991, it was sold by Seven Hills until their eventual closure. Seven Hills agreed I could continue to sell Spectrum, so I asked Eric Shepherd of Syndicomm to sell Spectrum on my behalf. In 2011 Tony Diaz took over Syndicomm and continued to sell it for me. With the declining sales over the years, I finally decided that the time had come in 2012 to make Spectrum Freeware. To coincide with its reclassification, this PDF manual has been compiled from the original Seven Hills manuals. I have changed a few words and links here and there, and added new screen shots and illustrations. Ewen Wannop - 2012 2 Spectrum About Seven Hills Software No Copy Protection We don’t believe in copy protection—all it does is impair the honest user’s ability to use software to its fullest. We strive to provide high quality products at reasonable prices. We hope you will support our efforts by not allowing your family or friends to copy this software. Questions and Comments We always welcome feedback—if you have any questions, or suggestions for improving this product, please let us know. In addition, we would like to hear your ideas for new programs. Copyrights and Trademarks This manual and the software (computer program) described in it are copyrighted with all rights reserved. No part of the Spectrum software or documentation may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording or otherwise, without the prior written permission of Seven Hills Software Corporation. SEVEN HILLS SOFTWARE CORPORATION’S LICENSOR(S) MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THE SOFTWARE. SEVEN HILLS SOFTWARE CORPORATION’S LICENSOR(S) DOES NOT WARRANT, GUARANTEE OR MAKE ANY REPRESENTATIONS REGARDING THE USE OR THE RESULTS OF THE USE OF THE SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY, CURRENTNESS OR OTHERWISE. THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE SOFTWARE IS ASSUMED BY YOU. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. IN NO EVENT WILL SEVEN HILLS SOFTWARE CORPORATION OR ITS LICENSOR(S), AND ITS DIRECTORS, OFFICERS, EMPLOYEES OR AGENTS BE LIABLE TO YOU FOR ANY CONSEQUENTIAL, INCIDENTAL OR INDIRECT DAMAGES (INCLUDING DAMAGES FOR LOSS OF BUSINESS INFORMATION, AND THE LIKE) ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE EVEN IF SEVEN HILLS SOFTWARE CORPORATION OR ITS LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU. SEVEN HILLS SOFTWARE CORPORATION OR ITS LICENSOR(S) LIABILITY TO YOU FOR ACTUAL DAMAGES FROM ANY CAUSE WHATSOEVER, AND REGARDLESS OF THE FORM OF THE ACTION (WHETHER IN CONTRACT, TORT (INCLUDING NEGLIGENCE), PRODUCT LIABILITY OR OTHERWISE), WILL BE LIMITED TO $50. Apple, IIgs, GS and GS/OS are trademarks of Apple Computer, Inc. Spectrum © 1991-2020 Ewen Wannop Spectrum is a trademark of Seven Hills Software Corporation 3 Contents Table Of Contents Spectrum Scripting Working With Spectrum!5 XCMDs!5 References & Parameters!5 XCMDs The BatchXfer XCMD!6 The BinHQX XCMD!8 The Browser XDisplay !13 The ChatterBox XCMD!27 The Database XCMD!31 The Debug XCMD!38 The Diary XCMD!40 The Freezer XCMD!42 The HodgePodge XCMD!44 The Kermit XCMD!54 The Library XCMD!62 The Lister XCMD!64 The ResEdit XCMD!69 The ScriptEditor II XCMD!72 The Speech XCMD!81 The TopCat XCMD!84 The Twilight II XCMD!91 The WindowMgr XCMD!93 The WorkBench XCMD!114 Programming Information XCMDs Programming Information!123 XCMDs Sample Code!139 Spectrum Port Driver!152 Spectrum Parameter Block!157 Writing Spectrum Online Displays!174 !Help! NDA Documentation!195 Table of Contents 4 Reference Working With Spectrum From its inception, Spectrum was designed in a modular fashion, allowing Add.Ons such as port drivers, online displays, and from v2.0 onwards, XCMDs, and even XDisplays! These expanded on the powerful capabilities of Spectrum itself, allowing it to keep up with ongoing events such as Marinetti and the Internet. Programming information for these Add.Ons was until now only available on request. With the release of Spectrum as Freeware, I am now making this information available to all. XCMDs Spectrum’s scripting language is extremely powerful, and covered most all of the things we thought at the time people might wish to do. As time went on, we realised we needed more, so the XCMD came into being. The XCMD added additional capability to an already powerful application. An XCMD allows a script to pass control to an external module, which running at full code speed, can do most anything you can think of! With the Browser XDisplay, we even created an online HTML display that thought it was an XCMD. This allowed rendering of HTML data passed to it from the Spectrum Internet Suite (SIS) scripts. The base code from the Browser XDisplay has now had a further lease of life within the HTML Tool Set. You will find here the scripting documentation for the various XCMDs, including some of the legacy XCMDs, such as Freezer and TopCat. If you wish to write your own XCMD, check out the XCMD Programming Information, and the XCMD Sample Code at the end. References & Parameters If you want to know how to interface with Spectrum, either to write your own Online Display, or to interface from your own XCMD, check out the documentation at the end of this PDF. For completeness, I have also included programming information for the !Help! NDA. © 2012 Ewen Wannop Reference 5 Spectrum XCMD Technical Notes Copyright © 1995 by Ewen Wannop and Seven Hills Software Corp. Written by: Ewen Wannop January 1995 Updated by: Ewen Wannop May 1996 This technical note describes the BatchXfer XCMD The BatchXfer XCMD The BatchXfer XCMD adds batch Ymodem and Zmodem file transfers to script commands. This allows batch uploading of files to hosts which do not recognize automatic transfers. The BatchXfer can be controlled either directly from a list of files provided by a script, or by retrieving a list of files manually from an _SFMultiGet2 dialog. Function = 0 (get version number) Function 0 gets the version number, the Failed flag is set if the XCMD is not active or present: EXT BatchXfer 0 <VarName> The VarName, if present, will return the version number of the XCMD. Function = 1 (Sends single or batch files) Function 1 sends single or batch files: EXT BatchXfer 1 <Method> {Prefix} “FileName1” {“FileName2”} etc. EXT BatchXfer 1 <Method> {Prefix} {EditorHandle} EXT BatchXfer 1 2 10 “File1” {“File2”} etc. EXT BatchXfer 1 2 “:Ram5:” “File1” {“File2”} etc. EXT BatchXfer 1 2 ~E01234 If the optional Prefix is present it will be added to each file to make the complete path for sending the files. Files are first checked for the presence of a full path indicated by a colon within the FileName. The Prefix is not added if a full path is found. The Prefix can be a number, or a path enclosed by colons. If the Prefix is a number, the script should first set this prefix by using ‘Set GSPrefix <PrefixNumber> “FolderName”’ before making the XCMD call. Any prefix may be used that is not reserved. Spectrum does not directly use any of the prefixes above 10. If the optional ScriptEditorHandle is present, the command will use this as the source of FileNames. The Handle is checked to see if it is valid, the Failed flag being set if it does not exist. ScriptEditorHandles are in the form of ‘~E01234’. Use the script substitution ‘$EditorHandle#’ to retrieve a ScriptEditorHandle as input to this command. If a ScriptEditorHandle is given, the rest of the command line will be ignored. If the optional Prefix is present, this will be added to the filenames extracted from the EditorHandle. The input to the EditorHandle may be from any of the usual sources. FileNames must be bracketed by the current QuoteCharacter if they contain any spaces. If they are not bracketed, the FileNames will be delimited by the first space character or carriage return. Carriage returns and linefeeds may be freely used between entries. BatchXfer XCMD 6 If the optional EditorHandle is not given, the FileNames listed on the command line will be sent. If the optional Prefix is present, this will be added to the filenames extracted from the EditorHandle. As many files can be listed as will fit into the script command. Note: The current Quote character must be used to enclose filenames. The<Method> indicates: 1 Ymodem batch upload 2 Zmodem batch upload Valid filenames must be specified. If a file does not exists, or has a resource fork, the transfer will be stopped and the Failed flag set, any remaining files will not be sent. You may determine how many files were sent sucessfully by calling Function 3. Function = 2 (Send Multiple Files) Function 2 allows manual selection of files: EXT BatchXfer 2 <Method> A standard _SFMultiGet2 dialog will be shown. Multiple files can be selected from this dialog. If the SHR desktop is not showing when this call is made, the call will do nothing and the Failed flag will be set.