Professional UNIX User Manual - Blast Internet Services

R

R

Professional UNIX User Manual

The File Transfer Authority

©2000 by BLAST SOFTWARE, INC.49 Salisbury Street West

Pittsboro, NC 27312All Rights Reserved

Manual #2MNUNIX1/00

The information in this manual has been compiled with care, but BLAST, Inc,. makesno warranties as to accurateness or completeness, as the software described herein maybe changed or enhanced from time to time. This information does not constitute com-mitments or representations by BLAST, Inc., and is subject to change without notice.

BLAST® is a registered trademark, and BLAST Professional™, BLAST ProfessionalUNIX™ and TrueTerm™ are trademarks of BLAST, Inc. Any trademarks, trade-names, service marks, service names owned or registered by any other company andused in this manual are proprietary to that company.

Restricted Rights Legend

Use, duplication, or disclosure by the Government is subject to restrictions as set forthin subdivision (b) (3) (ii) of the Rights in Technical Data and Computer Softwareclause at 52.227-7013.

BLAST, Inc.49 Salisbury Street West

P.O. Box 818Pittsboro, North Carolina 27312

SALES: (800) 242 - 5278FAX: (919) 542 - 0161

Technical Support: (919) 542 - 3007E-mail: [email protected]

World Wide Web: http://www.blast.com

© Copyright 2000 by BLAST, Inc.

Table of Contents

1 Introduction 1

BLAST Software Registration . . . . . . . . . . . . . . . . . . . . . . . . . 1

The BLAST Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

BLAST Professional Features. . . . . . . . . . . . . . . . . . . . . . . . . . 2

How to Use This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Comments and Suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

BLAST Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 The BLAST Environment 7

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Command Line Switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Communications Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Accessing Serial Ports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Port Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Choosing a Serial Port for BLAST . . . . . . . . . . . . . . . . . . . . . 23

Special Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

International Keyboard for 10.7x . . . . . . . . . . . . . . . . . . . . . . 29

Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Integration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

3 BLAST Quickstart 39

Starting BLAST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

The BLAST Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Three Keys to Remember . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

The BLAST Menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

A Quickstart File Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

4 The Menus 51

Moving Through the Menus . . . . . . . . . . . . . . . . . . . . . . . . . . 51

The Keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

The Offline Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

The Online Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

The Filetransfer Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

The Local Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

The Remote Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Automation with BLASTscript. . . . . . . . . . . . . . . . . . . . . . . . 61

5 The Setup 63

What is a Setup? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Setup Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

DEC VT Emulation Subwindow for 10.7x. . . . . . . . . . . . . . . 74

PC ANSI Emulation Subwindow for 10.7x . . . . . . . . . . . . . . 78

WYSE Emulation Subwindow for 10.7x . . . . . . . . . . . . . . . . 78

BLAST Protocol Subwindow . . . . . . . . . . . . . . . . . . . . . . . . . 84

Kermit Protocol Subwindow. . . . . . . . . . . . . . . . . . . . . . . . . . 89

Xmodem and Ymodem Protocol Subwindow for 10.8x. . . . . 92

Zmodem Protocol Subwindow . . . . . . . . . . . . . . . . . . . . . . . . 94

6 BLAST Session Protocol 99

What is a Protocol? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

The BLAST Session Protocol. . . . . . . . . . . . . . . . . . . . . . . . 100

BLAST Protocol Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Starting a BLAST Session . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Ending a BLAST Session . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Performing Filetransfer Commands . . . . . . . . . . . . . . . . . . . 107

Transfer Command File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

BLAST Protocol Remote Menu . . . . . . . . . . . . . . . . . . . . . . 118

Automating the BLAST Session Protocol . . . . . . . . . . . . . . 119

Fine-Tuning the BLAST Session Protocol . . . . . . . . . . . . . . 119

Filetransfer Security with BLAST Protocol . . . . . . . . . . . . . 121

7 FTP with 10.8x 123

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Starting an FTP Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

FTP Filetransfer Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Sending and Receiving Files with FTP. . . . . . . . . . . . . . . . . 124

File Transfer Switches with FTP . . . . . . . . . . . . . . . . . . . . . 126

Filenames Restrictions with FTP . . . . . . . . . . . . . . . . . . . . . 127

Ending an FTP Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

FTP Remote Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

8 Kermit Protocol 129

Kermit Filetransfer Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Sending and Receiving Files with Kermit . . . . . . . . . . . . . . 130

File Transfer Switches with Kermit . . . . . . . . . . . . . . . . . . . 132

Filenames Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Kermit Remote Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

9 Xmodem, Ymodem, and Zmodem Protocols 137

Command Line Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Xmodem Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Ymodem Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Zmodem Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Filenames Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

10 Text Transfers 145

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Uploading Text to a Remote Computer . . . . . . . . . . . . . . . . 145

Downloading Text from a Remote Computer . . . . . . . . . . . 147

11 Secure BLAST 149

Securing Your System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

UNIX Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Using Secure BLAST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

blpasswd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

blsecure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

secure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Using the Password. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

12 Introduction To Scripting 171

Starting Out. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Learn Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

13 BLASTscript Topics 181

Scripting Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Manipulating Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Managing the Screen Display . . . . . . . . . . . . . . . . . . . . . . . . 191

Communicating with Other Programs . . . . . . . . . . . . . . . . . 193

File Transfers with BLAST Session Protocol. . . . . . . . . . . . 194

File Transfers with FTP Using 10.8x . . . . . . . . . . . . . . . . . . 197

File Transfers with Kermit . . . . . . . . . . . . . . . . . . . . . . . . . . 197

File Transfers with Xmodem and Xmodem1K. . . . . . . . . . . 200

File Transfers with Ymodem and Ymodem G . . . . . . . . . . . 201

File Transfers with Zmodem. . . . . . . . . . . . . . . . . . . . . . . . . 203

BLAST Operation as a Pseudohost With 10.8x . . . . . . . . . . 204

Using Log Files for Error Checking . . . . . . . . . . . . . . . . . . . 205

Text Transfers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

14 Connecting and Disconnecting 211

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

BLASTscript Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

The Index Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

15 BLASTscript Command Reference 219

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Syntax Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Commands That Set @STATUS . . . . . . . . . . . . . . . . . . . . . 223

10.8x Manipulation of Binary Data . . . . . . . . . . . . . . . . . . . 224

BLASTscript Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

16 BLASTscript Reserved Variables 263

17 Data Stream Control 305

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Data Stream Filtering and Alteration . . . . . . . . . . . . . . . . . . 305

Standard BLAST Terminals . . . . . . . . . . . . . . . . . . . . . . . . . 309

Terminal Emulation with 10.7x . . . . . . . . . . . . . . . . . . . . . . 311

Keyboard Mapping Utility for 10.7x . . . . . . . . . . . . . . . . . . 315

18 Remote Control with 10.7x 323

What Is Remote Control? . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Connecting to the Host PC . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Using Access Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Using File Transfer Only Mode with 10.7x and 10.8x . . . . . 329

Using Terminal Mode with 10.7x and 10.8x . . . . . . . . . . . . 330

Transferring Files to and from the Host PC . . . . . . . . . . . . . 331

Modifying BHOST Settings . . . . . . . . . . . . . . . . . . . . . . . . . 332

Appendix A Error Messages 339

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

BLAST Protocol Functions. . . . . . . . . . . . . . . . . . . . . . . . . . 339

Transfer File Management . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Utility File Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Command File Processing . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Memory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Script Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

Network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

Appendix B Key Definition Charts 345

BLAST Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Terminal Emulation Keys for 10.7x . . . . . . . . . . . . . . . . . . . 348

Appendix C Troubleshooting 351

Appendix D The ASCII Character Set 355

Appendix E Autopoll 357

The Autopoll Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Installing Autopoll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Starting Autopoll. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

The Site File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Transfer Command File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

Overview of Autopoll Script Actions . . . . . . . . . . . . . . . . . . 362

Configuration Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

Other Files Using the Filename Stub . . . . . . . . . . . . . . . . . . 366

Autopoll under cron . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

Tips and Tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

Modifying Autopoll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

Configuration Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . 373

Appendix F PAD Parameters 377

INDEX 383

Chapter 1

Introduction

BLAST Software Registration

Thank you for buying our communications software and welcome to the world of BLAST. Before doing anything else, it is very important that you complete the Warranty Registration Card. Without it, we cannot provide you with the complete support and continued service that comes with every copy of BLAST.

The services available to registered owners of BLAST include:

◊ A ninety-day warranty stating that the software will operate according to specifications in effect at the time of purchase.

◊ Professional help from our experienced Technical Support staff for a nominal fee.

◊ New product announcements.

◊ Discounts on product upgrades.

INTRODUCTION 1

Extended warranties, custom support, special training, and corporate licensing are also available. Please call BLAST, Inc. at (919) 542-3007 or refer to the enclosed literature for more information.

The BLAST Package

The BLAST package contains the following items:

◊ One media package containing the BLAST program and sup-port files.

◊ One BLAST Professional License Agreement and Warranty. It is important to read and understand the terms and conditions in this document before opening the media package.

◊ One Warranty Registration Card. The serial number of your BLAST program is printed on this card. When placing a call to BLAST Technical Support, please have this number available. Also, please read the card, fill it out, and send it immediately to BLAST, Inc.

◊ One Installation Guide and one User Manual.

If the package does not contain all of these items, please call the BLAST Customer Support staff.

BLAST Professional Features

BLAST Professional is designed to connect your computer with a variety of other computers. You may use one of the following con-nections:

◊ Communications devices such as modems, X.25 PADs, or ISDN Terminal Adaptors, and other virtual asynchronous cir-cuits attached to RS-232 ports.

◊ Hardwired RS-232 connections.

◊ Telnet sockets.

◊ Raw TCP/IP sockets.

2 CHAPTER ONE

BLAST transfers files to and from remote computers with the fast, 100% error-free BLAST Session protocol. Alternatively, you may choose from one of the following protocols: Xmodem, Ymodem, Zmodem, or Kermit. BLAST Professional UNIX 10.8x users may also choose FTP.

The BLAST scripting language is a powerful but simple-to-use pro-gramming language. It allows the automation of communications tasks. Creation of scripts is simplified by the Learn mode feature of BLAST. Activate Learn mode and let BLAST write the script for you as you perform a communications task!

All UNIX products support TTY and PASSTHRU modes, which en-sure complete and accurate transmission of control characters to the terminal hardware. BLAST Professional UNIX 10.7x supports sev-eral terminal emulations, including VT52, VT100, VT220, WYSE 50, WYSE 60, and ANSI.

10.7x also supports keyboard mapping and remote control that allows your computer to take complete control of a remote PC. Re-mote control works over modems and includes automatic translation between different video modes, password-protected dial-back secu-rity, and many other features.

How to Use This Manual

Parts of the Documentation SystemEach portion of the BLAST documentation system fulfills a specific need:

◊ Online Help is always available while you are using BLAST. It is context-sensitive so that the information you need is right at hand.

◊ The Installation Guide contains step-by-step instructions forinstalling and configuring BLAST.

◊ The User Manual contains all the information necessary for operating BLAST, including detailed descriptions of Terminal mode and filetransfer procedures. It also contains general infor-mation as well as a listing of all BLAST functions, BLAST-script reserved variables, and BLASTscript statements. The listing for each BLASTscript statement includes syntax, usage details, and examples.

INTRODUCTION 3

Documentation System ConventionsTo help reduce confusion, BLAST documentation shares several common name conventions, display conventions, and defined terms:

◊ Examples in the text indicate the actual keystrokes you should type to perform a function. For example,

send myfile.txt ENTER

instructs you to type “send myfile.txt” and then press the ENTER key. In early introductory chapters, “ENTER” is included to indicate the keystroke needed to execute input of typed data. In later chapters, it is assumed and omitted.

◊ Italics in code indicate that the item (for example, a command line argument or a string value) is generic and that a more spe-cific item is needed. For example, in the following lines of code,

ConnectFiletransferSendlocal_filenameremote_filenametoesc

specific filenames should be given for local_filename and remote_filename. An exception to this convention is the all-italic format used for command descriptions in Chapter 15.

◊ Differences between BLAST Professional UNIX 10.7x and BLAST Professional UNIX 10.8x and features unique to one or the other are indicated in headings and tables throughout the manual.

◊ The term “local” computer refers to the machine closest to you, whereas “remote” computer refers to the system to which your local machine is connected.

◊ The term “interactive” describes BLAST operation from the keyboard. When operating interactively, a user presses keys to control the program. Alternatively, a user may write a BLAST script to control the program.

◊ Finally, “Terminal mode” describes BLAST operation as a ter-minal to a remote computer. For example, if you are going to

4 CHAPTER ONE

use BLAST to connect to a remote UNIX system, then your keystrokes will be interpreted by the remote computer as if you were operating from an attached terminal.

Comments and Suggestions

Considerable time and effort have been spent in the development of this product and its documentation. If you are pleased, or not pleased, we would like to hear from you. Please see the pages fol-lowing the index of this manual for response forms that you may fill out.

BLAST Technical Support

If you have problems installing or running BLAST, first look for an-swers in your manual, particularly Appendix C, “Troubleshooting,” and in the Online Help. Double-check your communications set-tings, operating system paths, modem cables, and modem power switches.

If you are still unable to resolve the problem, contact BLAST Tech-nical Support. For a nominal fee, a technician will help you with your problem. Technical Support may be purchased on a per-inci-dent basis or annually. Contact our Sales Staff for details. If you pur-chased BLAST outside of the USA, please contact your authorized distributor for technical support.

What You Will Need To KnowBefore you contact us, please have the following information ready:

◊ Your BLAST version number and serial number. These num-bers appear in the opening banner (when you first start BLAST), in the Online Help window, and on your distribution media.

◊ Your operating system version number. To display your version number, type uname -a at the command line.

How to Contact UsTelephone support is available Monday through Friday. If voice support is inconvenient, you may FAX your questions to BLAST,

INTRODUCTION 5

24-hours-a-day. Please see the title page of this manual for contact numbers and the pages at the end of the manual for a sample FAX cover sheet.

6 CHAPTER ONE

Chapter 2

The BLAST Environment

Introduction

Multi-user environments are inherently complex. BLAST must work smoothly with all peripheral equipment and with other soft-ware programs loaded on your system. To help you integrate BLAST into your system, a set of environment variables and com-mand line switches can be specified that customize the operation of BLAST. These features are described in this chapter in addition to a general discussion of communications ports and flow control.

Environment Variables

When BLAST is installed, by default all BLAST files are placed in the same directory, but you may choose to move the files to separate directories. Within BLAST, there are three different types of files and a separate environment variable pointing to the directory con-taining each type:

THE BLAST ENVIRONMENT 7

◊ executable files – program files with execute permission; the PATH environment variable points to the directory containing these files.

◊ support files – files required for normal operation of the soft-ware, including access to Online Help and the modem control library; the BLASTDIR environment variable points to the di-rectory containing these files. BLASTDIR must exist in order for BLAST to execute.

◊ auxiliary files – setup files; the SETUPDIR environment vari-able points to the directory containing these files. If no SETUPDIR exists, BLAST will look to the BLASTDIR for setup files. Other files, such as script files, may reside in any di-rectory of your file system.

Each user must have these environment variables set correctly. Typ-ically you would edit each user’s .profile, .login, or .cshrc to reflect this information.

Setting PATH, BLASTDIR, and SETUPDIRTo update your path temporarily and set the BLASTDIR environ-ment variable, log in as a regular user and type the following at the shell prompt:

C Shell

set path=( $path executable_dirname )setenv BLASTDIR support_file_dirnamesetenv SETUPDIR auxiliary_dirname

Bourne Shell and Korn Shell

PATH=$PATH:executable_dirnameBLASTDIR=support_file_dirnameSETUPDIR=auxiliary_dirnameexport BLASTDIR SETUPDIR

where executable_dirname is the full path of the directory in which the BLAST files are stored, support_file_dirname is the full path of the directory in which the support files are stored, and auxiliary_dirname is the full path of the directory in which the aux-iliary files are stored.

For example, if the executable and support files are in /usr/blast and the auxiliary files are in /usr/john, under the Bourne/Korn shells you would type:

8 CHAPTER TWO

PATH=$PATH:/usr/blastBLASTDIR=/usr/blastSETUPDIR=/usr/johnexport BLASTDIR SETUPDIR

NOTE: This is only a temporary change. To set these values per-manently, add the above commands to your system login procedure.

Additional Environment VariablesBLAST recognizes a number of additional environment variables for customizing its operation. The information in bold and brackets indicates the default value. Examples use the Bourne shell syntax. As with BLASTDIR and SETUPDIR, these environment variables must be exported.

BANNERTIME=delay 0 – 99 [5]where delay is the time in seconds that the initial screen is dis-played.

EXAMPLE:

BANNERTIME=2

BLASTDIR=dirname [/usr/blast]where dirname is the directory that contains the BLAST support files such as systems.scr, modems.scr, blast.tdf, and blast.hlp. BLASTDIR must exist in order for BLAST to execute!

EXAMPLE:

BLASTDIR=/usr/blast

BPRINTER=drivername [/dev/lp]where drivername is the target for printer output; BPRINTER can be set to a device or a print spooler.

EXAMPLE:

BPRINTER="lp -c %s >/dev/null"

This will cause BLAST to issue the lp command, substituting the print filename for %s.


EDITOR=filename [vi]where filename is the name of the editor program that will be in-voked by the Edit command from the Local menu. The default is the program vi, which must be located in your path.

EXAMPLE:

EDITOR=vi

SETUPDIR=dirname [$BLASTDIR]

where dirname is the directory in which the BLAST setup files are stored. The default SETUPDIR is the same directory as BLASTDIR. If many different users need to access BLAST, you may wish to point SETUPDIR to the $HOME directory of each us-er. Users can then maintain individual libraries of setup files. This technique permits the BLAST administrator to restrict access to the BLAST directory without limiting the ability of other users to run the software and create their own setups.

EXAMPLE:

SETUPDIR=$HOME

TERM=terminal name [no default]where term_name is the entry in the terminfo library that BLAST will use to control the terminal from which BLAST is being run.

EXAMPLE:

TERM=vt100

TMP=dirname [/usr/tmp]where dirname is the directory in which temporary files will be stored.

EXAMPLE:

TMP=/usr/tmp

Command Line Switches

Command line switches allow you a number of options on startup. For example, you can automatically load a setup and run a BLAST

10 CHAPTER TWO

script that brings you directly into a communications session with-out interactive input. BLAST recognizes the following switches and parameters. Some switches are for BLAST Professional UNIX 10.7x only and some are for 10.8x only (see descriptions of specific switches below):

blast [setupname] [-sscriptname] [argument] [-2] [-b] [-c] [-dd] [-dt] [-e] [-f] [-h] [-k] [-n] [-p] [-q] [ -v or -?] [-x] [-y] [-z]

One space must precede each switch included on the command line. Do not insert a space between the switch and the parameter associ-ated with it. For example, -sscriptname is correct, but -s scriptname is not.

setupname specifies a setup file for BLAST to load. Note that it is not necessary to type the filename extension (.su). If a valid BLAST script is spec-ified in the Script File field of the setup, the script will automatically execute (unless BLAST is started with the -h switch, in which case the script specified in the setup will be ignored). If no script is spec-ified, BLAST will load the setup and display the Offline menu. If a setup is not specified on the command line, BLAST will automati-cally load the default setup (default.su). BLAST first checks for setups in the directory defined by SETUPDIR. If there is no SET-UPDIR, BLAST checks the directory defined by BLASTDIR.

-sscriptname specifies the BLAST script that will control the current session. Control will be passed automatically to the script instead of the reg-ular BLAST menus and will return to the menu system at completion unless the script specifies that BLAST exit. If a script is named in the Script File field of the setup, the script specified by the -s option will override the one specified in the setup. Please note that no spac-es are allowed between the -s and the script name. If no setup is spec-ified on the command line, the default setup is loaded.

BLAST first checks for scripts in the current directory or in the path specified on the command line, then in SETUPDIR.

argument

Specifies one of ten optional arguments (text strings) that can be passed to a BLAST script directly from the command line. These ar-guments are stored as BLASTscript reserved variables @ARG0 to


@ARG9. This option requires that a setup file be specified on the command line. If no setup is specified, BLAST will interpret the first argument as a setup name and will generate an error message if that setup does not exist.

-bforces BLAST to execute in batch mode, in which all displays are suppressed and the Local System shell is disabled. This switch al-lows BLAST to run with no output for batch operations. Local Sys-tem commands executed from within BLAST may still generate output.

10.7.5n-2specifies four-digit format for year.

10.7x

-cforces BLAST to operate as if it were being run from a terminal in-stead of the computer console. Access mode is disabled when us-ing this switch. This switch should be used if you experience problems running BLAST from the console of your system.

10.8x

-ddchanges the default date format globally (see @DATEFORMAT on page 268). For example,

-dd"%A:%B:%Y:%X"

If the -dd switch is used on the same command line as the -y switch, the last switch on the line will take precedence.

-dtchanges the default time format globally. For example,

-dt"%h:%m"

12 CHAPTER TWO

-fenables XON/XOFF flow control for the port the user logs into.

-hexecutes BLAST in host mode. In host mode, BLAST runs in File-transfer and Answer mode connected through the port that is already open.

This command is usually issued from Terminal mode to start BLAST on a remote system. The remote system does not actually start BLAST protocol until the local computer begins file transfer. If the local system does not enter Filetransfer mode within the time specified in the Logon Time Out field of the remote setup, the re-mote computer will time out before logging on.

If used with an appropriately modified setup, the -h switch allows a local operator to change certain BLAST protocol parameters on the remote system temporarily. For example, if you had a remote setup called “special” that specified a packet size of 1024, you could start BLAST with this parameter setting by specifying the setup “special” on the command line:

blast special -h

BLAST will look in BLASTDIR for this setup unless a SETUPDIR has been specified.

NOTE: In host mode, BLAST uses the login port parameters, ig-noring the Script File setting and port parameters of the setup, except

10.8x

-enumber

specifies the end-of-transmission (EOT) timeout for Xmodem and Ymodem where timeout equals number/100 seconds. The mini-mum timeout is .1 second (10), and the maximum is 60 seconds (6000). For example, -e1111 sets the timeout to 11.11 seconds. See Chapter 9 for more information on Xmodem and Ymodem.

EOT timeout for Xmodem and Ymodem may also be specified with the BLASTscript reserved variable @XYEOT.


for XON/XOFF Pacing. See “Using BLAST in Host Mode” on page 26.

-nforces BLAST to execute in no display mode. Displays may be se-lectively reenabled through BLASTscript commands. This switch allows you to integrate BLAST into your applications without losing the information previously written to the screen.

-qforces BLAST into quiet mode. Audible signals that normally call attention to prompts and errors are suppressed.

-v or -?displays the BLAST version, serial number, and command line switch usage.

-xenables Extended Logging, which writes detailed information about BLAST protocol sessions to your session log. Extended Logging may also be enabled with the BLASTscript reserved variable @XLOG.

10.8xUsing the -h switch, BLAST can perform X, Y, or Zmodem file transfers. See “BLAST Operation as a Pseudohost With 10.8x” on page 204.

10.7x

-kcountry.kbd

loads an international keyboard driver, where country.kbd is the name of the driver. (See “International Keyboard for 10.7x” on page 29.

10.8x

-px

specifies the pad character (x), expressed as a decimal value, to be be used with Xmodem transmissions. See Chapter 9 more informa-tion on Xmodem.

14 CHAPTER TWO

-zforces BLAST to attempt to open the communications port without changing the port’s status. BLAST will not disable getty or ttymon processes automatically (see “Accessing Serial Ports” on page 18).

Example Command LineThe example command line shown below starts BLAST with a setup named “dial,” a script named “newyork,” and “30,400” as an argu-ment to be used by the script, type:

blast dial -snewyork 30,400

Precedence for Specifying OptionsBecause the command line can specify options that may also be named in setups and scripts, BLAST follows a well-defined order of precedence:

◊ Whenever a command line switch conflicts with a value speci-fied in a setup also loaded from the command line, the com-mand line switch overrides the setup value.

◊ Whenever a command line switch conflicts with a setup value that has been loaded after starting BLAST (through interactive command or BLASTscript control), the setup value overrides the command line switch.

◊ Whenever a BLAST script changes a value specified in either the setup or the command line, the script change overrides the setup/command line value.

10.8x

-yspecifies four-digit format for year. If the -y switch is used on the same command line as the -dd switch, the last switch on the line takes precedence.

10.7x

-ynumber

specifies the end-of-transmission (EOT) timeout for X and Ymo-dem where timeout is equal to number/100 seconds. The minimum timeout is .1 second (10) and the maximum is 60 seconds (6000). For example, -y1111 sets the timeout to 11.11 seconds. See Chap-ter 9 for more information on Xmodem and Ymodem.


Communications Ports

BLAST can establish a communications session with asynchronous serial ports and TCP/IP socket services. The port that BLAST will use is specified in the Connection setup field (page 69) or in the BLASTscript reserved variable @COMMPORT (page 266).

BLAST does not communicate directly with the computer hardware; rather, it accesses the hardware through a device driver. The device driver is a character-special device file usually found in the /dev di-rectory. For network connections, BLAST talks to TCP/IP socket services.

In addition to device drivers, devices such as multi-port serial boards, terminal servers, and X.25 PADs permit software, like BLAST, to access the hardware. If the manufacturers of these devic-es do not provide a standard asynchronous interface, BLAST cannot open the device. If RS-232 capabilities are not correctly implement-ed in the device driver, those features will not be available during a BLAST session. For example, many drivers do not correctly imple-ment modem control signals like DTR, DCD, RTS, and CTS.

Accessing TCP/IP PortsBLAST makes network connections using TCP/IP socket services. Networking services must be correctly configured on your system for BLAST to make a network connection successfully, including having the host name in the/etc/hosts file or using Domain Name Services. Connecting to a specific port number requires that the port number be found in the /etc/services file. For more information on these configuration files, consult the hosts and services man pages.

Suppose that you have a modem connected to port 3001 on a termi-nal server called ts01. The terminal server’s name is resolved via the hosts file or Domain Name Services, while the port number is in the services file. You can connect to that port and access the modem by entering

ts01 3001

in the Connection setup field (page 69). The port number should be separated from the host name by a single space.

NOTE: Port number 23 is reserved for telnet. To use telnet, sim-ply enter the host name, and BLAST will default to port number 23.

16 CHAPTER TWO

To use telnet with a port other than port 23, enter the host name, the port number, and “telnet,” as in the example below: blaster.blast.com 12 telnet

X.25 Communications and PADsX.25 is a communications standard for transmitting data over packet switching public data networks. Public data networks provide long distance networking capabilities to users whose needs are not exten-sive enough to justify dedicated equipment and phone circuits.The interface to the public data networks is a PAD, which stands for Packet Assembler/Disassembler. If the PAD is directly attached to a system bus, the PAD manufacturer must provide a device driver that BLAST can open and set like a serial port. If the PAD is accessed through a modem or a standard serial port, BLAST can communi-cate with the PAD via a standard serial port device driver.

A PAD takes the data stream from a terminal or computer and as-sembles it into fixed length packets for transmission on a public data network. At the remote site, the packets are disassembled by the re-mote PAD and restored to the same form as the original data stream. A packet is transmitted when:

◊ Enough characters have been accumulated to form a complete X.25 packet. For many PADs, the default packet size is 128 bytes. Packet size is a modifiable PAD parameter.

◊ A “data-forwarding character” is encountered in the data stream. For many PADs, the default “data forwarding character” is a car-riage return. This is a modifiable PAD parameter.

◊ A certain amount of time has expired without receiving a new character. The idle timeout period is a modifiable parameter. For interactive usage, the idle timeout should be set to a small value in order to improve “responsiveness.” This may, however, in-crease the number of partially empty packets.

The BLAST protocol is inherently compatible with X.25 communi-cations: the BLAST packet size can be tuned to fit within an X.25 packet; by default, each BLAST packet is terminated with a carriage return; and the sliding window design of the BLAST protocol en-sures that data is constantly being transmitted.

Optimum BLAST Packet Size

To operate efficiently over an X.25 network, BLAST protocol pack-et size must be optimally configured. The Packet Size setup field


(page 90) or the reserved variable @PAKTSZ (page 279) specifies the number of bytes of data that BLAST will transmit in each BLAST packet. This specification does not include any bytes asso-ciated with BLAST’s encoding of data, packet headers, launch char-acters, and CRC characters.

To make most efficient use of the X.25 connection, a BLAST frame—the data and the bytes associated with packetizing the data—must fit within the X.25 frame size. If the BLAST frame is too large to fit into a single X.25 frame, you will be sending a full frame and a partial frame. If the BLAST frame is too small, you will be sending partial X.25 frames.

There is a simple formula to determine optimal BLAST packet size for a given X.25 frame size. If you are using the 8-bit channel setting in the BLAST Protocol subwindow of the setup, the formula is:

BLAST Packet = [(X.25 Frame - 4) x 7] - 9 4

If you are using the 7-bit channel setting, the formula is:

BLAST Packet = [(X.25 Frame - 5) x 3] - 9 4

For example, if you are using a X.25 frame size of 256 bytes and an 8-bit channel, the optimal BLAST packet size is 219.

219.4 = [(256 - 4) x 7] - 9 8

PAD Parameters

The X.3 standard specifies a set of parameters defining how the PAD is to perform its task of assembling and disassembling the data stream. The PAD must be properly configured for optimal perfor-mance. Please see Appendix F for a complete explanation of PAD Parameters.

Accessing Serial Ports

UNIX System V Release 3 and System V Release 4 use different methods for serial port configuration and control. The following sec-tions discuss the two methods.

18 CHAPTER TWO

System V Release 3 For System V Release 3 (SVR3), you need to be familiar with the system programs init, getty, and login, and with the inittab config-uration file. These programs operate in a loop called the IGLS cycle, init-getty-login-shell. In general, any attempt to control a serial port except through the IGLS cycle breaks the system’s control of its re-sources. There is no provision built into the UNIX system to handle anything other than login terminals on serial ports. This can signifi-cantly affect the operation of BLAST.

The IGLS Cycle

The init process, process number 0 or 1, runs all the time. Periodical-ly, it reads the file /etc/inittab to see if anything is pending. If the current UNIX system run level is 2 or 3 (UNIX is in a multi-user mode), and there is a line in inittab such as:

tty0:23:respawn:/etc/getty /dev/tty0

init will start a getty process using serial port /dev/tty0. The first field in the line, called a tag (tty0 in this example), is used as an ar-bitrary index into the inittab file. Tags must be unique.

getty is a simple process that reads /etc/gettydefs to find out how to configure serial port parameters, such as data bits, parity, and flow control, and then waits for activity on the port. As soon as the appro-priate signal is received (usually a carriage return), getty starts a login process and then exits.

After verifying a username and password, login consults /etc/gettydefs to set line parameters and then starts a shell program. The serial port is now said to be the “control terminal” for the shell started by login. Finally, login informs the UNIX kernel of its ac-tions and then terminates.

The shell program (e.g., sh and csh, etc.) is more properly called a command line interpreter and is capable of starting other programs, such as BLAST. When the user has finished and wants to exit the shell, an end-of-file signal (EOF) is sent. Exiting the shell notifies the UNIX kernel that the shell’s control terminal is no longer in use. Consequently, the kernel sends a message to init telling it that /dev/tty0 has been released. Init then reads /etc/inittab and the IGLS cycle repeats.

Breaking the IGLS Cycle

Within the IGLS scheme, there is no provision for processes to initiate outbound connections. Even the programs UNIX-to-UNIX-


copy (uucp) and Call UNIX (cu), long a standard part of UNIX dis-tributions, must break the IGLS cycle to perform the tasks for which they were written.

There are two ways to handle this situation. First, it may be possible to dedicate some serial ports for outbound connections and reserve others for the IGLS cycle. This is the best solution, but it requires at least two serial ports, two modems, and possibly two phone lines to implement correctly.

Alternatively, it is possible to share a given serial port for dial-in and dial-out processes. The IGLS cycle can be disabled on a serial port by making a simple change to inittab:

tty0:23:off:/etc/getty /dev/tty0

where off replaces respawn. This change tells init not to use /dev/tty0. As soon as init examines the inittab file, it will shut down a getty process that is running on that port. The port is now available for uses other than terminal login. When the alternate process is fin-ished, it can reenable the serial port for logins by restoring the orig-inal inittab entry.

As straightforward as this solution sounds, it poses a problem for the system because /etc/inittab is a system-level configuration file. If a user is permitted to start or stop the IGLS cycle on any serial port at any time, the integrity of the multi-user environment can be easily compromised. A number of mechanisms have been created to deal with this dilemma. For example, uugetty tries to distinguish auto-matically between inbound and outbound connections, setting up the serial port accordingly. For a number of reasons, however, it is dif-ficult to make this configuration work reliably.

Another approach is to create “lock” files in a special directory and require programs wanting to use a serial port to check for the pres-ence of a lock on the port before proceeding. Unfortunately, there is no way to enforce this procedure. Some programs do not check for locks at all, others do not interpret the lock information correctly, and there is no universally accepted location for the lock file direc-tory. This issue is discussed in more detail in the section on “Port Locking” (see next page).

System V Release 4System V Release 4 (SVR4) also attempts to control competition for serial ports. The IGLS cycle is essentially the same as in SVR3, but the functions of init and getty are now controlled by the port monitor

20 CHAPTER TWO

daemon ttymon. Ttymon can monitor several ports, simplifying port administration. The port monitor uses configuration informa-tion stored in an internal database managed by the Port Monitor Ad-ministration (pmadm) program. Serial ports are enabled or disabled through commands to pmadm, while the port monitor itself is ma-nipulated through commands to sacadm (the Service Access Con-trol Administration program). These commands, pmadm and sacadm, are members of a set of commands for handling both net-work and terminal connections, collectively called the Service Ac-cess Facility (SAF).

Under SVR4, a serial port is disabled by issuing a command to pmadm in the format:

pmadm -d -p pmtag -s svctag

where -d is the disable option and pmtag and svctag are identifiers for the serial port. The output of the command pmadm - l will dis-play these tags in addition to whether or not ttymon is monitoring a particular port:

PMTAG PMTYPE SVCTAG FLGS ID <PMSPECIFIC>zsmon ttymon ttya u root /dev/term/a I - /usr/bin/login - 9600zsmon ttymon ttyb ux root /dev/term/b I - /usr/bin/login - 9600

An “x” appears under the FLGS column when ttymon is not moni-toring a particular port. In the example above, ttymon is running on /dev/term/a but not on /dev/term/b. The pmtag for /dev/term/a is zsmon, and the svctag is ttya. Thus, the following command dis-ables the port:

pmadm -d -p zsmon -s ttya

To enable the port, you would type:

pmadm -e -p zsmon -s ttya

Unfortunately, ttymon may not always release the port gracefully. On some systems it may be necessary to kill the ttymon process (through sacadm) or reboot before the port is flushed completely.

Port Locking

BLAST uses two of its own processes, setgetty and ttymgr, to ma-nipulate system files directly and thereby lock and unlock serial


ports. When the user goes online through the BLAST software, BLAST checks to see if the device specified in the Connection field of the setup is a character-special device. If it is, BLAST calls setgetty with information about the serial port, the user’s UID, and other parameters.

setgetty and ttymgrSetgetty first checks for a file called blasttab in the BLAST direc-tory. If blasttab exists and is readable, setgetty will only allow ac-cess to ports listed in the file. The device named in the Connection field of the setup must match one of the entries in blasttab. After other checks are completed, setgetty calls ttymgr, the program that actually does the work of enabling and disabling the port. Owned by root, ttymgr runs with its set-uid bit enabled. It either modifies /etc/inittab (SVR3) or calls pmadm (SVR4).

If an error occurs, BLAST will display the message “can’t open the communications port.” In the event of an error, you can examine the contents of /usr/tmp/ttymgr.log to determine the cause of the prob-lem. A complete description of the log format is beyond the scope of this manual. If you need to call BLAST Technical Support to help solve the problem, the support staff may need information contained in the log. If the port is successfully opened, BLAST resumes exe-cution at the Online menu, and the user can select Connect, Termi-nal, or other Online functions.

Format of blasttabThe presence of blasttab, allows BLAST to prevent users from opening unauthorized ports on the system; blasttab must exist in the BLAST directory and have read permission enabled. The format of the file consists of the full path of the character-special device name that the user is allowed to open, one entry per line. Text following a “#” is treated as a comment and will not be used by setgetty. Blank lines are not permitted in the file. In the following file for example,

# Table of Ports For Use With BLAST#/dev/tty00 # High-speed 28.8 modem/dev/tty01 # Low-speed 2400 modem for use with

# old systems# /dev/ttyA16 --- this port not available## end of blasttab. Updated 03/21/96 by dcb

22 CHAPTER TWO

the comment character before /dev/ttyA16 makes the port unavail-able. Because of the special nature of this file, users other than root should not have write access to it.

Lock File ConventionsWhen BLAST gains access to a communications port, it creates lock files in appropriate system directories to make the port unavailable to other processes. Locations and naming conventions for lock files vary among UNIX systems. The following table illustrates the vari-ety of implementations; use the table as a guide for locating where locks are kept in your system. NamingPlatform Directory Convention Example

SCO /usr/spool/locks LCK..ttyn LCK..tty2a /usr/spool/uucp

AIX /etc/locks LK.lkmajmin LK.000.029.000 Solaris /var/spool/locks LK.lkmajmin LK.000.029.000

BLAST normally removes its lock when it terminates. If BLAST re-ceives certain UNIX signals, however, it may not be able to delete the lock file before exiting. In that case, you or your system admin-istrator should manually delete the lock file before restarting BLAST.

Problems with Port LocksBLAST’s port locking scheme is comprehensive, but some circum-stances can defeat it. For instance, multiple device drivers may refer to the same physical device, such as:

crw-rw-rw- 1 root sys 5, 1 Dec 12 16:29 ttyd1crw-rw-rw- 1 root sys 5, 97 Aug 12 1994 ttyf1

If inittab or ttymon refers to the port as ttyd1 but the BLAST setup refers to the port as ttyf1, port locking has no effect and BLAST will probably fail. One way to handle this problem is to have an entry in blasttab for /dev/ttyd1 and none for /dev/ttyf1, which would force users to specify /dev/ttyd1 within BLAST.

Choosing a Serial Port for BLAST

There is no standard naming convention for serial port device driv-ers; UNIX vendors and add-on board manufacturers have devised their own schemes. To add to the confusion, some vendors provide


separate device drivers for modem connections and terminal con-nections. For complete information, you must consult the documen-tation for your system. On the following page are some examples of serial port device drivers on an assortment of UNIX systems.

Operating System Device Driver

ATT System 5.4 /dev/term/aData General DG/UX /dev/tty0DEC Digital UNIX /dev/tty00Hewlett-Packard HP-UX /dev/tty00IBM AIX (also SCO 3.2.4.x, SCO Xenix) /dev/tty0SCO Open Server 5.0 /dev/tty1ASilicon Graphics IRIX /dev/ttyd1Sun Solaris 2.3 (or /dev/ttya, not /dev/cua/a) /dev/term/a

Serial port device drivers must have read and write permission in or-der for BLAST to access the port. You can check the permissions of a device driver by using the ls -l command. For example, to check the permission on /dev/tty01, type the following:

ls -l /dev/tty01

You should see output similar to the following:

crw-rw-rw- uucp uucp 77,128 Aug 24 10:47 /dev/tty01

The output “crw-rw-rw” indicates this file is a character-special de-vice that has universal read and write permissions.

If the port does not have these permissions, you can change them us-ing the chmod command. To change permissions, log in as root and type the following:

chmod 666 /dev/tty01

For more information on permissions and using chmod, consult the chmod man page and “Permissions” on page 150.

NOTE: These device names are often merely links to the actual character-special files. Other equivalent links may exist in a given system.

Using LinksBLAST supports links to serial port device drivers. A link can insu-late inexperienced users from complex device names. For example, to create a link named /dev/blast to the device driver /dev/term/a, type the following:

24 CHAPTER TWO

ln -s /dev/term/a /dev/blast

After creating the link, you can check its existence by typing:

ls -l /dev/blast


lrw-rw-rw- 2 uucp uucp 77,128 Aug 25 08:27 /dev/blast —> /dev/term/a

To use the link named /dev/blast, enter /dev/blast in the Connec-tion field of the setup instead of /dev/term/a. For more on creating and using links, consult the ln man page.

Posix Vs. Non-Posix DriversBLAST can only open device drivers that comply with POSIX com-mittee recommendations for serial port device drivers. In particular, device drivers conforming to BSD specifications may not be suc-cessfully opened by BLAST. For example, the device driver /dev/cua/a on a Sparc station running Solaris 2.x cannot be opened by BLAST, but the driver /dev/term/a, referring to the same physi-cal port, can be.

Automatic Serial Port SearchingBLAST features automatic port searching using a special “hunt file” to locate an available port. To use automatic port searching, specify the name of a hunt file (including path, if necessary) preceded by “<” in the Connection field of the setup. For example, if a hunt file called hunt.fil resides in the BLAST directory, a setting of

<hunt.fil

in the Connection setup field specifies that BLAST will search hunt.fil and open the first available port listed there.

When you enter the Online menu, BLAST:

◊ looks for the hunt file in the current directory, then in the direc-tory specified by the BLASTDIR environment variable.

◊ tests each listed port in the order specified until an available port (enabled or disabled) is found.

◊ returns the port to its previous condition when you exit BLAST.


If the hunt file is not found, or if none of the ports in the hunt file are available, you will receive the “Cannot open communications port” error message.

Hunt File Format

The hunt file is a standard ASCII text file in the following format:

setting device modem_type baud_rate

where:

setting is either try this device (1) or bypass this device (0). A setting of 0 effectively removes the device from the table.

device is the port name.

modem_type specifies the modem type in the same format used for the Modem Type setup field (page 70).

baud_rate specifies the baud rate in the same format used for the Baud Rate setup field (page 71).

IMPORTANT: The hunt file may not contain any extra spaces or lines. This applies to both the beginning and end of the file.

For example, BLAST would test the devices /dev/tty1 and /dev/tty3 listed in the following hunt file:

1 /dev/tty1 MICROCOM 19.20 /dev/tty2 USRCour 96001 /dev/tty3 Intel 9600

BLAST will ignore the entry for /dev/tty2 because it is preceded by a “0”. Note that hunt files serve a different purpose than blasttab, described earlier, which is used for port validation. When a blast-tab file is used, its entries must match all ports in a hunt file that are expected to be available.

Special Considerations

Using BLAST in Host ModeSerial port device drivers have many modifiable parameters. Having these parameters set correctly significantly affects filetransfer and

26 CHAPTER TWO

terminal scrolling speeds. In Answer or Originate mode, BLAST reads your setup file and attempts to set the device driver parameters accordingly when you go online.

When you log into a UNIX system, the system sets serial port pa-rameters according to values in the /etc/gettydefs file. When BLAST is run in host mode on that system (using the -h switch), it does not attempt to reset serial port parameters. This generally works well, but in rare circumstances it may be necessary to change the settings before BLAST is invoked. UNIX provides the command stty for this purpose.

Viewing Serial Port Parameters with stty

To view the serial port parameters for the port into which you are currently logged, type:

stty -a


speed 38.4 bps; eucw 1:0:0:0, scrw 1:0:0:0intr = ^c; quit = ^|; erase = ^?; kill = û;eof = ^d; eol = <undef>; eol2 = <undef>; swtch = <undef>;start = ^q; stop = ^s; susp = ^z; dsusp = ^y;rprnt = ^r; flush = ô; werase = ^w; lnext = ^v;-parenb -parodd cs8 -cstopb -hupcl cread -clocal -loblk -crtscts -parext -ignbrk brkint ignpar -parmrk -inpck -istrip -inlcr -igncr icrnl -iuclc ixon -ixany -ixoff imaxbel isig icanon -xcase echo echoe echok -echonl -noflsh -tostop echoctl -echoprt echoke -defecho -flusho -pendin iexten opost -olcuc onlcr -ocrnl -onocr -onlret -ofill -ofdel tab3

Unfortunately, there is no standard format for the output of stty. The output may have a substantially different appearance on your sys-tem; nevertheless, a number of important parameters are defined consistently across UNIX implementations:

stty Parameter Meaning

speed 38.4 bps The speed is 38.4 bits per second.intr = ^c The interrupt key is set to CTRL C.erase = ^? The erase character is set to CTRL ?.parenb (-parenb) Parity is enabled (disabled).parodd (-parodd) Parity is odd (even).cs8 (cs7) Data bits is 8 (7).cstopb (-cstopb) Use two (one) stop bits per character.ixon (-ixon) XON/XOFF [^Q/^S] output control is enabled (disabled).ixany (-ixany) Any character (only ^Q) restarts output.ixoff (-ixoff) XON/XOFF [^Q/^S] input queue control is enabled (dis-

abled).


Setting Serial Port Parameters with stty

Stty can also set serial port parameters. For example, to change data bits from 7 to 8, you would type:

stty cs8

It may be necessary to change some parameters for optimal perfor-mance; however, the modem and serial port must cooperate. If, for instance, the modem is configured for XON/XOFF flow control and you set the serial port for RST/CTS flow control, you will encounter performance problems.

IMPORTANT: It is possible to change serial parameters so that the port will no longer respond to your terminal! Before making changes, copy the current settings so that they can be restored if necessary. A UNIX environment variable is useful here:

OLD_STTY='stty -g'

To restore the old parameters, simply type

stty $OLD_STTY

For example, some UNIX systems are set on login for even parity, 7 data bits, and 1 stop bit. BLAST file transfers, however, proceed more quickly if an 8-bit data path is available. On such systems, it may be possible to change the port parameters temporarily and re-store them after file transfer is finished, as in the following com-mands:

OLD_STTY='stty -g'stty cs8 -parenb -cstopbblast -hstty $OLD_STTY

Using BLAST 10.7x under SCO UNIX OpenServer 5Executing BLAST 10.7x under SCO UNIX OpenServer5 requires null mapping of the character stream. Enter mapchan -n from the command line or add mapchan -n to the user’s .profile to allow the character stream to be handled without translation. Failing to set mapchan -n can cause display and functionality problems in BLAST when run under OpenServer 5. For more information, refer to the man page for mapchan.

28 CHAPTER TWO

Running BLAST Remotely from the Console Using 10.7xIn order to run BLAST in Access mode, the Special KBD Mode of BHOST running on the remote computer must be set to ON. Also, the NUM LOCK key on the console keyboard should be turned off for cor-rect cursor control. BLAST will reenable NUM LOCK on the console if NUM LOCK is engaged on a remote PC during remote control sessions. For information on configuring BHOST, see the BHOST User Man-ual.

International Keyboard for 10.7x

BLAST Professional UNIX 10.7x supports international keyboards through the -k command line switch. The following international keyboard driver files were copied to your system during the instal-lation process:

french.kbd italian.kbd spanish.kbdgerman.kbd uk.kbd

To load an international keyboard driver, add the following switch to the command line:

-kcountry.kbd

where country.kbd is one of files listed above.

File FormatThe format for these files is:

scan_code = base, shift, ctrl, ctrl_shift, alt, alt_shift

scan_code the key number of the key to be changedbase ASCII value of new KEY

shift ASCII value of SHIFT KEY

ctrl ASCII value of CTRL KEY

ctrl_shift ASCII value of CTRL SHIFT KEY

alt ASCII value of ALT KEY

alt_shift ASCII value of ALT SHIFT KEY

EXAMPLE:

2 = 49, 33, 0, 0, 96, 96


Refer to the actual files for more information. Lines that begin with the “#” character are comments.

Flow Control

Flow control paces the data stream between computers to prevent the loss of characters from data overruns. In serial communications, the primary factor adversely affecting transmission speed is an in-correct flow control setting. It is crucial to pace the data stream prop-erly between connected computers to maximize filetransfer and terminal scrolling speed.

When data is received more quickly than it can be processed, the se-rial port buffer fills up. When the buffer is full, the device driver must halt the flow of data. If the serial port is connected to a modem, for example, some form of signaling is required so that the port can halt the flow of data from the modem as the serial buffer approaches capacity. Likewise, the modem must be able to signal the port to stop sending data if its own buffers fill up.

RTS/CTS PacingThe RTS/CTS Pacing setup field (page 72) and the reserved variable @RTSCTS (page 284) enable a form of flow control that uses the RS-232 signals Request-To-Send (RTS) and Clear-To-Send (CTS). This type of flow control is sometimes referred to as hardware or “out-of-band” flow control. When the setup field is set to YES, BLAST at-tempts to set the serial port device driver to use RTS/CTS flow con-trol; NO disables RTS/CTS flow control.

Unfortunately, UNIX serial port device drivers do not implement RTS/CTS flow control uniformly. The RS-232 standard originally defined these control signals for uni-directional flow control only, which is not appropriate for controlling full-duplex or bi-directional data flow. Consequently, some UNIX systems implement uni-direc-tional RTS/CTS flow control in conformance with strict RS-232 specifications, whereas other UNIX systems offer a bi-directional form of RTS/CTS flow control that is compatible with modern high-speed modems. To make matters more confusing, some systems do not support any form of RTS/CTS flow control at all.

A device driver that supports bi-directional RTS/CTS flow control turns on RTS when the serial port buffer is ready to receive data and turns it off when the serial port buffer is full. Likewise, the modem

30 CHAPTER TWO

turns on CTS when it is ready to receive data from the device driver and turns it off when the modem buffers are full.

If the device driver supports uni-directional RTS/CTS flow control, it will turn on RTS when it is ready to transmit data to the modem. In response, the modem will turn on CTS to indicate that it is ready to accept data. Unfortunately, as “uni-directional” implies, this scheme only controls the flow of data from the computer to the mo-dem. There is no way for the device driver to halt the flow of data from the modem.

If you experience problems using RTS/CTS flow control, you should consult your system documentation (for example, man pages for stty and termio) to learn how RTS/CTS flow control is imple-mented in the device driver.

BLAST operates with greatest efficiency using bi-directional RTS/CTS flow control. If it is not available on your system, XON/XOFF flow control is the next best alternative. We do not recommend at-tempting to use uni-directional RTS/CTS flow control.

XON/XOFF PacingThe XON/XOFF Pacing setup field (page 72) and reserved variable @XONXOFF (page 299) enable flow control based on the ASCII DC1 (XON) and DC3 (XOFF) characters. This type of flow control is of-ten referred to as XON/XOFF flow control, software flow control, or “in-band” flow control. When the setup field is set to YES, BLAST attempts to set the serial port device driver to use XON/XOFF flow control; NO disables XON/XOFF flow control.

XON/XOFF flow control paces the flow of data by transmitting “start” and “stop” characters in the data stream. For example, when a modem receives an ASCII DC3 character, it stops transmitting data to the computer. When the modem receives an ASCII DC1 character, it restarts data transmission. This is analogous to starting and stopping terminal scrolling by pressing the CTRL S (XOFF) and CTRL Q (XON) keys.

XON/XOFF flow control is the most widely used form of flow con-trol and is generally quite reliable; however, there are some potential problems:

◊ The protocol must not use the ASCII DC1 and DC3 characters to transmit data. Because Xmodem and Ymodem protocols use these characters, XON/XOFF flow control should not be used


with these protocols. BLAST, Kermit, and Zmodem protocols are compatible with XON/XOFF flow control.

◊ The starting and stopping of data does not happen in real-time. Because the XON/XOFF characters are transmitted in the stream of data, there may be a substantial delay from the time when the XOFF is issued and when it is received by the trans-mitting device. This can cause data loss if buffers are overrun while the XOFF is being transmitted.

◊ If the XON character is lost, a protocol must implement a pro-cedure to restart transmission or the file transfer will be irrevo-cably halted. The BLAST protocol, for example, will reset the device driver to begin data transmission if it does not receive an XON within 30 seconds of receiving an XOFF.

◊ In complex communications environments, it is possible to have many different pieces of equipment attempting to control data flow. For example, the device driver for the serial port, mo-dems, terminal servers, and X.25 PADs can all be configured to assert flow control.

XON/XOFF flow control works most successfully in one of two ways, depending on the environment. In a simple environment, a lo-cal flow-control loop works best. In a more complex environment, an end-to-end flow control loop is most likely to work.

A local flow control loop is established when each modem is con-figured to act on the XON/XOFF characters sent by the attached computer. In this environment, the device driver will issue an XOFF when the serial port buffers are full. In response to the XOFF char-acter, the modem will halt the flow of data to the computer. The mo-dem will resume transmission when it receives an XON from the computer. Likewise, the modem will issue an XOFF to the serial port when its buffers are full.

The modems must be configured to act on flow control characters but not allow them to pass to the remote machine. No other devices should be configured to assert flow control. For best results, the mo-dems should have an error-detecting connection established. BLAST does not recommend using local XON/XOFF flow control without an error-detecting connection. By default, when XON/XOFF pacing is enabled, BLAST establishes error-detecting flow control.

In more complex environments, or if error-detecting modems are not available, end-to-end XON/XOFF flow control should be used. In

32 CHAPTER TWO

an end-to-end environment, the device driver will issue an XOFF when the serial port buffers are full. The XOFF character will pass through all devices to the remote computer, which will stop data transmission. When the buffers empty, an XON will be issued that causes the remote computer to restart the transmission. In similar fashion, if the remote machine’s serial port buffers fill up, the device driver will issue an XOFF that causes the local machine to halt data transmission until an XON is received.

In this environment, all flow control should be disabled in the mo-dems and all other equipment. You must manually configure the modems to do this or write your own entry in modems.scr (see “Sample Modem Script” on page 214).

Integration Options

This section discusses integrating BLAST with other applications. You need not read this section until you are familiar with the basic operation of BLAST described in the remainder of this manual. Af-ter you are comfortable using BLAST, you will find the following features very useful.

Shell ProgrammingBLAST is easy to run from UNIX shell scripts. In combination with the BLAST scripting language, many types of communications tasks can be automated.

The following example demonstrates running BLAST from a shell script. The example illustrates a Bourne/Korn shell; if you use an-other shell, please refer to your system documentation or other ref-erence materials for more information. Many excellent references on shell programming are available and should be consulted for more complicated tasks.

A Basic Shell Script to Run BLAST

The script run_blast is a basic shell script for running BLAST:

# run_blast# A demonstration script that sets environment variables, traps interrupts,# runs BLAST, and checks the return code generated by BLAST.#trap ' ' 2 # Trap any interrupts generated by BLAST on exit

# ' ' are two single quotation marksPATH=$PATH:/usr/blast # Append /usr/blast to the current PATH environ-


# ment variable.BLASTDIR=/usr/blast # Set BLASTDIR environment variable.SETUPDIR=/usr/blast # Set SETUPDIR environment variable.#export PATH BLASTDIR SETUPDIR # Export PATH, BLASTDIR, and SET-

# UPDIR environment variables to sub-# shells (Necessary in Bourne shell).

#blast caller -stest.scr -b # Run BLAST #RETURN_CODE=$? # Set RETURN_CODE environment

# variable to code returned by BLAST#if [ $RETURN_CODE -ne 0 ] # Test for a nonzero return codethen echo $RETURN_CODE # echo code to screen if it is nonzero.# fi## End of script#

To execute the run_blast script, it is necessary to give it execute permissions. Run chmod by typing the following:

chmod 711 run_blast

This will set permissions on the script to read, write, and execute for the owner and execute only for group and other users. For some old-er systems, read permissions are required as well to run the script. For these systems, set the permissions as follows:

chmod 755 run_blast

Explanation

BLAST generates an interrupt when exiting. The line,

trap ' ' 2 # ' ' are two single quotation marks

sets a trap for this interrupt, UNIX system Signal 2 (Terminal Inter-rupt). If this interrupt is not trapped, the shell script will terminate when BLAST exits, rather than continuing to completion. It is pos-sible to set traps for other UNIX signals as well. For example, if you set a trap for Signal 15 (Software Termination), it will prevent the script from being terminated. To capture Signal 15 and echo “Please stop interrupting me while I am thinking” to the screen, include the following command in the script:

34 CHAPTER TWO

trap 'echo "Please stop interrupting me while I am thinking"' 15

The block of script,

PATH=$PATH:/usr/blastBLASTDIR=/usr/blastSETUPDIR=/usr/blast#export PATH BLASTDIR SETUPDIR

sets environment variables and exports them to subshells. In this ex-ample, the directory /usr/blast is appended to the search path the shell uses to find the BLAST executable. BLASTDIR and SETUPDIR are set to /usr/blast. For more information on environ-ment variables and command line parameters used by BLAST, see “Environment Variables” on page 7.

The line,

blast caller -stest.scr -b

tells BLAST to load the setup caller.su, run the script test.scr, and execute BLAST in batch mode (no display). It is not necessary to run BLAST in batch mode from a script; however, if the script is going to be run in a non-attended mode or if it is going to run as a back-ground process from cron, BLAST should always be run in batch mode.

The statement,

RETURN_CODE=$?

saves the return code from BLAST into an environment variable that can be used for further operations. BLAST will return a nonzero er-ror code if an error occurs during processing (for a list of error codes, see Appendix A). It is also possible to use the BLAST scripting lan-guage to return error codes with the QUIT statement (for more on the QUIT script command, see page 250).

The following block of code tests the environment variable RETURN_CODE for a nonzero value. If RETURN_CODE is not equal to zero, the script will echo the return code to the screen.

if [ $RETURN_CODE -ne 0 ]then echo $RETURN_CODEfi


It may be useful to send the output of the return code to a log file along with a time stamp. For example, an environment variable called TIME_STAMP can be created by using cut to extract the time and date from the output of the date command by adding the following line to your shell script:

TIME_STAMP='date | cut -d " " -f 2-4'

The variable TIME_STAMP will contain information similar to the following:

Aug 21 11:16:56.

For more information, refer to the date and cut man pages. For more information on piping output from one command to another, refer to the man page of the shell you are using.

The time stamp and return code can be written out to the log file blast_error.log by including the following line in your script:

echo $TIME_STAMP "BLAST return code is: "$RETURN_CODE > blast_error.log

Running BLAST From cronThe need often arises to run BLAST on a regularly scheduled basis. A UNIX supplied clock utility, cron, executes jobs at specified dates and times, making it ideal for scheduling BLAST to run unattended. The following information on cron is applicable to many UNIX sys-tems; however, cron may be implemented differently on your sys-tem. Please refer to your system documentation and the cron and crontab man pages for more information.

cron Primer

The cron utility is a daemon that runs when the system is booted. To be sure that cron is running on your system, type the following:

ps -ef | grep cron

This should generate output similar to the following line if cron is running:

root 260 1 0 Aug 3 ? 0:11 /etc/cron

If cron is not running, please consult your system documentation.

Jobs are usually submitted to cron with the crontab command. A crontab job is placed into the user’s subdirectory of the

36 CHAPTER TWO

/usr/spool/cron/crontabs directory; thus, root’s crontab files will be in /usr/spool/cron/crontabs/root. It is also possible to edit a crontab file manually; however, cron only reads crontabs at the time of boot-up. A hand-edited crontab file will not be executed un-til the system is rebooted. Executing the crontab command will cause cron to re-read the crontab files immediately.

Not all users will necessarily be able to use crontab. On some sys-tems access may be controlled by two files: /usr/lib/cron/cron.allow and /usr/lib/cron/cron.deny. If cron.deny exists and cron.allow does not, then all users except those listed in cron.deny will be able to access crontab. In this situation, if cron.deny is an empty file, all users will be able to use crontab. If neither file exists, only root will be able to use crontab. If cron.allow exists, only users listed in it will be able to use crontab. Please refer to the crontab man page entry for more information.

A crontab file is a standard text file with tab- or space-separated fields. The first five fields specify the minute (0–59), hour (0–23), day of the month (1–31), month of the year (1–12), and day of the week (0–6, with 0=Sunday). Each field can have one of the follow-ing:

◊ A number within the appropriate range for the field.

◊ Two numbers separated by a hyphen to indicate a range.

◊ A comma separated list of numbers.

◊ An asterisk to indicate all legal values.

The sixth field indicates the actual command to execute.

The following is an example of an actual crontab file:

17 5 * * 0 /etc/cleanup > /dev/null0 2 * * 0,4 /usr/lib/cron/logchecker > /dev/null 2>&10 3 * * * /usr/lib/cleantmp > /dev/null3,33 * * * 1-5 /usr/lib/uucp/uudemon.poll > /dev/null

The lines in this example perform the following actions:

◊ execute /etc/cleanup on Sunday morning at 5:17. Any output from cleanup is redirected to the bit bucket, /dev/null.

◊ execute /usr/lib/cron/logchecker on Sunday and Wednesday mornings at 2:00. Output is redirected to /dev/null. Error mes-


sages generated by logchecker are redirected to /dev/null as well.

◊ execute /usr/lib/cleantmp every morning at 3:00. Any output is redirected to /dev/null.

◊ execute /usr/lib/uucp/uudemon.poll at 3 minutes and 33 min-utes past the hour every hour, Monday through Friday. Output is redirected to /dev/null.

BLAST under cron

Running BLAST from cron requires modifying your crontab file. To make a copy of your crontab file, type the following:

crontab -l > my_cron

This will make a copy of your current crontab file in my_cron, where my_cron is a valid filename. This copy of the crontab file can now be edited with any text editor. It would be a good idea to make a backup copy of the working crontab file prior to making any changes.

Your login configuration script (.profile, .login, .cshrc) will not be executed when cron executes your job; therefore, it is usually best to execute BLAST from a shell script that sets all of the necessary environment variables, including PATH, to run BLAST. Because cron runs in the background detached from any terminal, it is nec-essary to run BLAST with the -b switch in order to suppress screen output.

To execute the run_blast shell script (see “Shell Programming” on page 33) from cron at 2:30 a.m. Tuesday through Saturday, add the following line to the file my_cron:

30 2 * * 3-7 run_blast

To submit the new crontab file to cron, type the following:

crontab my_cron

38 CHAPTER TWO

Chapter 3

BLAST QuickstartIMPORTANT: The following section assumes that BLAST has been properly in-

stalled. Before proceeding, be sure to:

◊ Successfully complete the entire BLAST installation process as instructed in the BLAST Installation Guide.

◊ Connect the modem according to the instructions supplied by the modem manufacturer and turn on the modem.

Starting BLAST

The command to execute BLAST is issued at the operating system prompt. Type:

blast

and press the ENTER key.

Make sure that all environment variables are set prior to executing BLAST. Consult “Environment Variables” on page 7, your system documentation, and the man page for your shell for more informa-tion.

BLAST QUICKSTART 39

If this is the first time you have run BLAST, the Online Help screen appears automatically (only on the first time). You can either ex-plore the Help menu now or cancel it until needed. BLAST displays the Offline menu next. You can now control BLAST interactively.

The BLAST Screen

The BLAST screen (Figure 3-1) includes two sections: the Com-mand Area and the Scrolling Area.

FIGURE 3-1

Command AreaThe Command Area consists of three lines: the Location Line, the Command Line, and the Command Description.

Location Line

The Location Line provides the information about your “location” within BLAST (Figure 3-2):

FIGURE 3-2| | | |

Current Active Current RequiredMenu Setup Directory User Action

Current Menu – displays the BLAST menu currently in use. The possible values are Offline, Online, Filetransfer, Local, and Remote.

Active Setup – displays the setup that is currently loaded.

Current Directory – identifies the current directory. Use the Chdir command in the Local menu to change the current directory.

40 CHAPTER THREE

Required User Action – displays the action that BLAST expects from you. Possible values are:

MENU – select a command from the menu.

INPUT – type in data at the prompt.

ERROR – review the error message, then press any key.

WAIT – no action allowed, BLAST is busy.

SCRIPT – a BLAST script is executing.

ONLINE – BLAST is online.

Command Line

The Command Line (Figure 3-1) lists the commands available from the menu.

Command Description

The Command Description (Figure 3-1) gives a one-line explanation of the command currently highlighted by the cursor. If you need more information about the command, press the HELP key (for more on the HELP key, see page 43).

Scrolling RegionThe Scrolling Region is the area below the Command Area. De-pending on the menu selection, this area is either blank or displays status and data. The format of the display depends on the activity BLAST is performing.

File Transfer Status AreaDuring file transfers, the scrolling area displays information about files being transferred. This display, called the File Transfer Status Area (Figure 3-3, next page), differs slightly depending on the pro-tocol used.

Following is a description of each item, or status indicator, in the BLAST protocol File Transfer Status Area.

local – the name of the file that your system is sending or receiving.

opt – the optional transfer switches that you selected for this file.

%xfer – the percentage of the file that has been transferred to or from the remote machine.

file size – the total file size (in bytes).

BLAST QUICKSTART 41

byte count – the portion of the file that has been transferred to or from the remote machine (in bytes).

ln qual – a general description of the line quality of the connection between the computers. Possible values during a transfer are good, fair, poor, or dead.

Unlike BLAST protocol, other supported protocols do not make use of all the above status indicators.

FIGURE 3-3

Three Keys to Remember

A number of special keys are used within BLAST, but three are used frequently:

ATTN CTRL K is the default “Attention (ATTN) Key.” Press CTRL

K to abort script operations or initiate other special key combinations. Press CTRL K CTRL K to return to the Online menu from Terminal mode. (The ATTN key can be rede-fined; see “Attention Key” on page 73.)

CANCEL To cancel the current action, return to the previous menu, or exit BLAST:

10.7x Press ESC.

10.8x Press ESC or CTRL A.

42 CHAPTER THREE

HELP While in Terminal mode, press ATTN H,

The BLAST Menus

Within menus, move from one command to another by pressing SPACEBAR or BACKSPACE.

Select a command by pressing the capitalized letter in the command or by pressing ENTER when the cursor rests on the desired command. After opening a submenu, return to the previous menu by pressing CANCEL.

Below the menu is a one-line description of the current command (Command Description Line). To get more information, press the HELP key when the cursor highlights the appropriate command. Af-ter displaying text related to the command, BLAST displays a gen-eral Help section on other topics. See Chapter 4 for a detailed discussion of the menus.

Menu SummaryEach of the menus offers commands that are grouped together by function. For example, the Local menu allows you to manage your system while online with a remote system, whereas the Filetransfer menu provides functions connected with sending and receiving files.

Following is a brief summary of each major menu and its purpose:

Offline – Manages the setups that contain connection information.

10.7x

For context-sensitive Online Help when not in Termi-nal mode, press F1 from the main console or ? from at-tached terminals. While running BLAST, you can set HELP to any key using the keyboard mapping utility, blastkbd (see “Keyboard Mapping Utility for 10.7x” on page 315).

10.8x When not in Terminal mode, press ?.

10.8x Alternatively, you may use the cursor keys to move from one com-mand to another.

BLAST QUICKSTART 43

Online – Manages connecting to and disconnecting from a remote system; executes BLAST scripts; sends and captures text files; and starts Terminal mode.

Filetransfer – Sends and receives files using either BLAST, Ker-mit, Xmodem, Ymodem, or Zmodem protocol.

Remote – Available with BLAST protocol and Kermit protocol. Performs file management on the remote system.

Local – Performs file management on your local system and pro-vides access to the operating system command line.

A Quickstart File Transfer

The most common use of BLAST is communicating between two computers using standard asynchronous modems and ordinary tele-phone lines. BLAST provides “hands-on” experience in this envi-ronment through a computer system called Blaster. This system is available 24-hours-a-day, seven days a week for BLAST demonstra-tions and testing. You are encouraged to take advantage of this ser-vice to familiarize yourself with the many features of BLAST.

This section of Quickstart will guide you through:

◊ Selecting the Blaster setup.

◊ Connecting to Blaster.

◊ Performing BLAST protocol transfers.

◊ Logging off Blaster.

Although we recommend that you complete this section in one sit-ting, you may elect to stop by returning to the Online menu and choosing the Disconnect command.

10.8x Also sends and receives using FTP.

10.8x Also available with FTP.

44 CHAPTER THREE

Selecting the Blaster SetupSetups contain all the information that BLAST needs to connect to and communicate with remote computers. Each setup is a separate file, created and modified through the Setup window of the Offline menu. This process is described in detail in Chapter 5. For this dem-onstration, you will use the setup called blaster.su, which was copied to your disk during the installation process.

If you have been moving through the menus, press the CANCEL key until you return to the Offline menu. Press S for Select and then press the ENTER key. You should see “blaster” listed as one of the entries in the Setup Directory. Use the keys listed at the top of the Com-mand Area to highlight blaster and then press ENTER. You should see the Setup window shown in Figure 3-4 below.

FIGURE 3-4

Check to see that the following entries appear correctly on the screen:

Phone Number: 1-919-542-0939

System Type: UNIX

Userid: reliable

Password: XXXXXX (fast-transfer is the actual password, but it will be masked by “Xs”)

Parity: None

Data/Stop Bits: 8/1

Emulation: VT100 or PASSTHRU

Protocol: BLAST

BLAST QUICKSTART 45

If any of the entries are incorrect, press M for Modify and use the keys listed at the top of the Command Area to move to the appropri-ate field and enter the information. For the fields Phone Number, Userid, and Password, press CTRL T to clear the field and type in the correct information (remembering that the userid and password are case-sensitive) and press ENTER.

For the remaining fields shown above, you can cycle through the available choices by pressing the SPACEBAR. For the Emulation field, select PASSTHRU. For correct settings of the setup fields Connec-tion, Modem Type, Baud Rate, XON/XOFF Pacing, and RTS/CTS Pacing, see your hardware documentation, your system administra-tor, and the discussion of these setup fields in Chapter 5.

After you are satisfied that all of the setup information is correct, press the CANCEL key to exit to the Offline menu. If you made any changes to the setup, press W (for Write) to save the changes.

Blaster assumes that a dial-in user will be using a VT-100 terminal. If you are using a VT terminal or your console operates as a VT or ANSI terminal, you should not have problems. Problems such as the screen not clearing, improper positioning of characters, and strange character sequences indicate that you are not using a VT terminal.

If your terminal is incompatible with a VT100, the best solution is to reset the TERM environment variable on Blaster to match the type of terminal you are using. For example, if you are using a WYSE 60 terminal, type the following after logging into Blaster:

TERM=wy60

This will cause Blaster to send WYSE 60 controls to your terminal instead of VT100 controls.

It may also be possible to reset your console or terminal to emulate a VT100. For example, if you are running BLAST from an xterm session and experience the problems described above, your xterm may be defaulting to an emulation other than VT100. On many sys-tems, you can start xterm in VT100 mode by typing:

xterm +t

For more information on resetting your console or terminal, consult your system or hardware documentation. For more information on xterm, consult the xterm man page.

46 CHAPTER THREE

Connecting to BlasterYour system is now ready to begin talking to Blaster. You have al-ready loaded the blaster setup into memory with the Select com-mand described in the previous section. Now press O to go to the Online menu. Connect to Blaster by pressing C (Connect) which will automatically dial Blaster.

The screen will display messages for each of the steps in the Connect process. If your modem has a speaker, listen to make sure it dials the number. Also, watch the terminal dialogue between the computer and the modem. When the call is successful, a message displays in-dicating that the connection has been established:

CONNECT nnnn

where nnnn, if present, gives connection information and speed (Figure 3-5).

FIGURE 3-5

After recognizing the modem’s CONNECT message, Blaster’s ban-ner and request for login will be displayed. Your setup file will automatically enter the userid and password. When the login is com-plete, BLAST returns control to you by displaying the Online menu and waiting for your input (Figure 3-6, next page).

BLAST QUICKSTART 47

FIGURE 3-6

Performing BLAST Protocol TransfersTo begin file transfer, select the Filetransfer command from the On-line menu by pressing F. In a moment, Blaster will synchronize withyour system and display the Filetransfer menu (Figure 3-7).

FIGURE 3-7

Getting a File from BlasterTo get a file from Blaster, select Get by pressing G. BLAST will prompt with:

enter remote filename:

BLAST is asking for the name of the file to retrieve. Type:

blaster.msg ENTER

48 CHAPTER THREE

BLAST will prompt with:

enter local filename:

A name may be specified for the incoming file. Type:

news.msg ENTER


specify transfer options (t=text, o=overwrite, a=append):

To transfer this file using text format translation, type:

t ENTER

BLAST will begin retrieving the file, and the byte count in the File Transfer Status Area will increase.

After the file has been completely sent, the byte count will stop, a blank will appear in the byte count status indicator, and the follow-ing message will appear on your screen:

news.msg/T=TXT... receive completed

Sending a FileTo send a file to Blaster, select the Send option by pressing S. BLAST will prompt with:


Type:

news.msg ENTER

BLAST will then prompt with:


BLAST is asking for the name that will be given to the file when it is transferred to Blaster. Type:

news.msg ENTER


BLAST QUICKSTART 49

specify transfer options (t=text, o=overwrite, a=append):

Because this is a text file, press T for text translation and O to over-write any old versions of this file:

to ENTER

Again, notice that the status fields are updated as the file transfer progresses. At the end of the transfer, you will see the following line displayed on your screen:

news.msg/T=TXT news.msg/OVW/T=TXT... send completed

After the file transfer is complete, press CANCEL to return to the On-line menu. An orderly shutdown of the BLAST protocol will follow and the Online menu will appear.

Logging off BlasterSelect the Disconnect command by pressing D. To quit BLAST, press CANCEL twice. BLAST will prompt with:

No Yes

...do you really want to leave BLAST?

Press Y to quit.

50 CHAPTER THREE

Chapter 4

The MenusThis chapter guides you through the various BLAST command menus. Some items covered here are described in more detail in oth-er chapters; in such cases, you will be referred to the appropriate chapter. Each menu offers commands that are grouped together by function. For example, the Local menu allows you to manage your system while online with a remote system, whereas the Filetransfer menu provides functions connected with sending and receiving files.

Moving Through the Menus

Within the command line of a menu, you may move from one com-mand to another by pressing SPACEBAR or BACKSPACE.

Execute a command by pressing the capitalized letter in the com-mand or by pressing ENTER when the cursor rests on the desired com-mand. After opening a submenu, return to the previous menu by pressing CANCEL. For a discussion of selecting a setup and navigat-ing through a Setup window, see “What is a Setup?” on page 63.

10.8x Alternatively, you may use the cursor keys to move from one com-mand to another.

THE MENUS 51

The Keyboard

BLAST uses special key sequences to differentiate between local commands and characters meant for the remote system. The BLAST Keys perform local functions, such as exiting Terminal mode or dis-playing Online Help. BLAST Keys are most important in Terminal mode, when BLAST ordinarily sends all keystrokes directly to the remote computer. All of the BLAST keys are listed in Appendix B. In BLAST Professional UNIX 10.7x, some keys can be reassigned using the BLAST keyboard utility, blastkbd (see “Keyboard Map-ping Utility for 10.7x” on page 315 for details).

Three Keys to RememberYou will use three of the BLAST Keys most often:

ATTN CTRL K is the default “Attention (ATTN) Key.” Press CTRL

K to abort script operations or initiate other special key combinations. Press CTRL K CTRL K to return to the Online menu from Terminal mode. (The ATTN key can be rede-fined; see “Attention Key” on page 73).

CANCEL To cancel the current action, return to the previous menu, or exit BLAST:

HELP While in Terminal mode, press ATTN H,

The Attention KeyThe Attention Key alerts BLAST to prepare for a particular opera-tion. The Attention Key is actually two keys, CTRL plus another char-

10.7x Press ESC.

10.8x Press ESC or CTRL A.

10.7x

For context-sensitive Online Help when not in Termi-nal mode, press F1 from the main console or ? from at-tached terminals. While running BLAST, you can set HELP to any key using the keyboard mapping utility, blastkbd (see “Keyboard Mapping Utility for 10.7x” on page 315 for details).

10.8x When not in Terminal mode, press ?.

52 CHAPTER FOUR

acter, represented in this documentation by the symbol “ATTN.” The default Attention Key is CTRL K. Press CTRL K to abort script opera-tions or initiate other special key combinations. Press CTRL K CTRL K (ATTN ATTN) to return to the Online menu from Terminal mode. To transmit the control characters as ATTN to a remote system, press ATTN and then the character itself. For example, CTRL K K will trans-mit a CTRL K to the remote system.

You may change the default value of the Attention Key by altering the value of the Attention Key setup field (page 73) or by setting the BLASTscript reserved variable @ATTKEY (page 265).

NOTE: If it is necessary to change the Attention Key, be sure to choose a replacement value that will not interfere with your system’s designated control codes. In particular, do not use CTRL M, which is the control code for a carriage return. Check your system manual for more information about special control codes before you reassign the Attention Key.

The Attention Key can initiate many useful functions from Terminal mode. Please refer to Appendix B for all of the Attention Key se-quences.

The Cancel KeyThe CANCEL key is used to cancel the current action. It also returns to a previous menu from a lower level menu and is used to exit BLAST from the Offline menu. The exception to this rule is that you must press ATTN ATTN to escape from Terminal mode.

The Help KeyWhen the cursor rests on a command in the menu, pressing HELP will display Help about that particular topic. After displaying text re-lated to the command, BLAST displays a general Help section on other topics.

Other Special Keys with 10.7xOther special types of keys are available with BLAST Professional UNIX 10.7x. See “Keyboard Mapping Utility for 10.7x” on page 315 and Appendix B for details.

THE MENUS 53

The Offline Menu

The Offline menu (Figure 4-1) is the first one displayed when you execute the BLAST program. The display includes three sections: the Command Area, the Scrolling Area, and the Status Line. See “The BLAST Screen” on page 40 for a description of these sections. We will be concerned here primarily with the Command Area, spe-cifically the Command Line.

FIGURE 4-1

If this is the first time that BLAST has run, the Help screen will ap-pear; press CANCEL to leave the Help screen. For Online Help, press the HELP key when the cursor rests on the appropriate command.

Setup CommandsFive of the commands in the Command Line of the Offline menu af-fect the setups listed in the Setup Directory and displayed in the Set-up window (see “What is a Setup?” on page 63 more details).

Following is a brief description of each command.

Select – Displays an input field for entering the name of the setup file to load into memory. If you press ENTER while the field is empty, the Setup Directory will be displayed in the scroll-ing area. Use the SPACEBAR to highlight a setup in the direc-tory and press ENTER to load it.

New – Prompts you for a new setup name. Type the name, press ENTER, and BLAST will automatically enter the Modify

54 CHAPTER FOUR

mode, displaying in the Setup window the values of the setup currently loaded in memory.

Modify – Displays in the Setup window the current values of the set-up in memory and allows you to make changes. Upon ex-iting Modify mode, those values will be loaded into memory.

Write – Saves the current values in memory to the setup file named on the location line.

Remove – Prompts you for the name of a setup to delete. If you press ENTER while the field is empty, the Setup Directory will be displayed in the scrolling area. You can then use the SPACEBAR to highlight a setup in the directory and press ENTER to delete it.

Other Offline CommandsLocal – Allows you to perform local system commands by taking

you to the Local menu (described in detail on page 58).

Learn – Builds a script for you by starting Learn mode. When you execute the Learn command, you will be prompted for a script name. After you type the name and press ENTER, BLAST will record all of subsequent functions in the script file until you disable Learn mode by selecting the Learn command again. If you specify an existing filename for the script, BLAST will ask whether you want to append to or overwrite the original script file. See “Learn Mode” on page 176 for more details.

NOTE: Learn mode may not function consistently in PASSTHRU emulation.

Online – Takes you to the Online menu, described in the next sec-tion.

The Online Menu

Selecting Online from the Offline menu displays a menu like or sim-ilar to the one shown in Figure 4-2 (next page). All characters re-ceived and transmitted in Terminal, Capture, and Upload modes will be filtered by the translate file if one is specified in the Translate File

THE MENUS 55

setup field (page 73). See “Translate File Format” on page 306 for more information on translate files.

Following is a brief description of the commands of the Online menu.

Connect – Dials the phone number stored in memory from the cur-rent setup.

Terminal – Makes your system a terminal to the remote system. The menu commands will no longer be available to you. Remember that you must press ATTN ATTN in order to exit Terminal mode and return to the command menus. See “Standard BLAST Terminals” on page 309 and “Terminal Emulation with 10.7x” on page 311 for fur-ther information.

Capture – Causes all incoming text from the remote system to be captured to a file. When you enter Capture mode by ex-ecuting the Capture command, you will be prompted for a filename; type the name and press ENTER. BLAST will record in the capture file all subsequent text displayed in the Terminal window until you disable Capture mode by selecting the Capture command again. If you specify an existing filename for the capture file, BLAST will ask whether you want to append to or overwrite the original file. See “Downloading Text from a Remote Computer” on page 147 for further information.

Upload – Sends text from a local file to the remote computer and displays the text on your screen. See “Uploading Text to a Remote Computer” on page 145 for further information.

FIGURE 4-2

56 CHAPTER FOUR

Filetransfer – Takes you to the Filetransfer menu described in the next section. See also chapters on individual proto-cols.

Script – Executes a BLAST script after prompting you to enter the script name. See Chapters 12–14 for information on scripts.

Local – Allows you to perform local system commands. This com-mand takes you to the Local menu described on page 58.

The Filetransfer Menu

Selecting the Filetransfer command from the Online menu displays the Filetransfer menu. The Filetransfer menu for BLAST protocol is shown in Figure 4-3 below.

FIGURE 4-3

10.7x

Access – Begins a remote control session. After entering Access mode, ATTN takes you to an Access menu (see “The Ac-cess Menu” on page 327).

Disc – Logs off of the remote system cleanly and hangs up the modem using information from the System Type and Mo-dem Type setup fields.

10.8xDisconnect – Logs off of the remote system cleanly and hangs up

the modem using information from the System Type and Modem Type setup fields.

THE MENUS 57

The commands on the Command Line of the Filetransfer menu vary depending on the protocol used. For example, the X, Y, and Zmo-dem protocols will only display the Get and Send commands, whereas the Kermit protocol has additional options and its own spe-cial Remote submenu. Following is a brief description of the com-mands of the BLAST protocol Filetransfer menu. For more information on menu options for protocols other than BLAST pro-tocol, see chapters discussing individual protocols.

Send – Sends a file or files to the remote system.

Get – Retrieves a file or files from the remote system.

Message – Sends a message to the remote operator. Simply type the message and press ENTER. The message will be queued for transmission to the remote display.

Remote – Performs remote system commands allowing limited ac-cess to the remote computer. The BLAST protocol Re-mote menu commands, which are similar to the Local commands, are described on page 60; see also “FTP Re-mote Menu” on page 128 and “Kermit Remote Menu” on page 134.

Local – Performs local system commands. This command takes you to the Local menu, described in the next section. Note that all filetransfer activity is suspended while you are using the local system. This inactivity may exceed the interval speci-fied by the BLAST protocol Inactivity Timeout setup field (page 85) and terminate Filetransfer mode.

File – Executes a transfer command file that can control an entire BLAST protocol transfer unattended (see “Transfer Com-mand File” on page 115, “Transfer Command File” on page 361, and “Transfer Command Files” on page 364).

The Local Menu

The Local menu (Figure 4-4, next page) allows you to perform op-erations on your local computer, including escaping to a command shell. Local commands affect only files in the current directory un-less you specify a pathname.

58 CHAPTER FOUR

FIGURE 4-4

Following is a brief description of the commands of the Local menu.

List – Displays the contents of a directory. You will be prompted to choose either a detailed (long) or non-detailed (short) list and then to enter a filename; you may use a specific filename, a filename with wildcard characters (for example, “*”), or press ENTER to display all files in the current local directory.

Delete – Erases a single file or multiple files. You may use a spe-cific filename or a filename with wildcard characters (for example, “*”).

Edit – Invokes the editor specified in the EDITOR environment variable (see EDITOR on page 10). vi is the default editor.

Rename – Renames a local file.

Type – Displays a local file in the scrolling area.

Print –Prints a file to the local printer or print spooler as defined by the BPRINTER environment variable (see BPRINTER on page 9).

Chdir – Changes from the current local directory to one that you name. The current directory is displayed on the top line of the BLAST screen. BLAST will check this directory for any files that you specify with the Local menu commands.

10.7x View – Displays either a “snapshot” or a “movie” made using the Access menu (see “The Access Menu” on page 327).

THE MENUS 59

System – Performs a local system command. At the prompt, type a system command and press ENTER. Alternatively, you may simply press ENTER and escape to a system prompt that takes over the BLAST display. Typing EXIT and pressing ENTER returns you to BLAST. When BLAST is started with the -b switch (or with the -n switch if the display has not been re-enabled through a script), you cannot escape to a system prompt (see “Command Line Switches” on page 10).

The Remote Menu

If you are using BLAST protocol, FTP, or Kermit protocol, the File-transfer menu contains a Remote command, which takes you to the Remote menu. The Remote menu allows a user with no knowledge of the remote operating system to manage files on that system.

FIGURE 4-5

Figure 4-5 above shows the BLAST protocol Remote menu. The commands of this menu, which differ from the FTP and Kermit Re-mote menus, are described briefly below. For a fuller discussion of the commands of the Remote menus, see “BLAST Protocol Remote Menu” on page 118, “FTP Remote Menu” on page 128, and “Kermit Remote Menu” on page 134.

List –Lists a remote directory.

Delete – Deletes a single file or multiple files from the remote sys-tem.

60 CHAPTER FOUR

Rename – Renames a remote file.

Type – Displays a remote file on the screen.

Print – Prints a remote file to the remote printer.

Chdir – Changes the current remote directory.

More – Scrolls a page of data output from the List or Type com-mands.

Automation with BLASTscript

Up to this point, you have been learning about BLAST in interactive mode, manually pressing keys to perform tasks. To automate com-munications tasks that are repeated on a daily or weekly basis, use BLAST’s interpretive programming language, BLASTscript. BLAST scripts can:

◊ Automate the dial and logon sequences to another computer.

◊ Send and receive files.

◊ Control standard and nonstandard modems and communication devices.

◊ Customize the user interface.

◊ Perform error-checking for session validation.

◊ Access online information services to send and receive mail.

◊ Poll large numbers of unattended remote sites after regular busi-ness hours.

Refer to Chapters 12–14 and Appendix E of this manual for detailed information on the use of BLAST scripts.

THE MENUS 61

62 CHAPTER FOUR

Chapter 5

The Setup

What is a Setup?

Communication between computers requires a great deal of information: the phone number of the remote computer, the modem type and baud rate, basic communications parameters, and more. BLAST keeps this information in individual files called “setups,” one file for each different system connection. BLAST is distributed with blaster.su, a setup that contains the correct settings for you to call the BLAST demonstration line (see “Selecting the Blaster Set-up” on page 45). A setup containing default values, default.su, is cre-ated when BLAST is executed for the first time.

You can customize the setup by selecting the Modify command in the Offline menu. Although this chapter tells you how to create, edit, and save setups, the Online Help for some setup fields has more specific information.

We recommend that you make any changes to the setup through the Modify menu; however, setups are text files and can thus be edited with any text editor. Be sure to save the file as “text only” or “ASCII” and give it the extension “.su”; do not save it as a word pro-cessor file.

THE SETUP 63

Loading a SetupTo load a setup, choose the Select command from the Offline menu (Figure 5-1). You will be prompted to enter a setup name or to press

ENTER to see a Setup Directory of all available setup files. If you press ENTER to see the directory, use the keys listed at the top of the Command Area to highlight the setup that you want to load.

After highlighting a setup, press ENTER to load the selected setup.

FIGURE 5-1

The Default SetupBLAST creates default.su, a setup that contains default values for each setup field and is automatically loaded when you start BLAST (unless you specify another setup on the command line). If you un-intentionally overwrite the original default.su, you can restore its original settings by deleting or renaming the existing default.su and restarting BLAST. BLAST will create a new default.su.

Creating a New SetupTo create a new setup, select the New option from the Offline menu by pressing N. BLAST will prompt you for a new setup name. Note that BLAST may not display the entire filename in its Setup Direc-tory. (Some UNIX systems have a limit of 256 characters for a file-name; some UNIX systems have a limit of only 14 characters.) You may want to use the location of the remote site as the setup name, or some other easily remembered name. If you want to place the new setup in a subdirectory of the directory specified by the SETUPDIR

10.8x Alternatively, you may use the cursor keys to highlight a setup file.

64 CHAPTER FIVE

environment variable, you must enter the relative path along with the setup name. BLAST will automatically append the extension “.su” to the filename. After you have typed in the setup name and pressed ENTER, BLAST will automatically enter Modify mode (see next section) and display in the Setup window the values of the setup file currently in memory. After you modify these values and press CANCEL, BLAST will automatically save the new setup file, load its values into memory, and return to the Offline menu.

Modifying a SetupTo modify a setup file from the Offline menu, use the Select com-mand to load the setup into memory and then press M, for Modify. You will see a screen with a Setup window similar to the one shown in Figure 5-2 below:

FIGURE 5-2

A field must be highlighted before you can modify its value. Use the keys listed at the top of the Command Area to move from field to field.

The third line of the Command Area will indicate the type of action necessary to enter a value.

Most fields are multiple choice. Use the SPACEBAR to cycle forward (and the BACKSPACE to cycle backwards) through the available op-tions in these fields; then press ENTER to proceed to the next field. Some fields, like Phone Number, require your input. To correct a mistake while entering data, use BACKSPACE to delete the mistake and then continue typing, or press CTRL T to clear the field and start over.

10.8x You may also use the cursor keys to move from field to field.

THE SETUP 65

The Emulation and Protocol fields may require additional input. If the entry in the field is followed by three periods, it means that there is a subwindow of additional settings. Press ENTER to access a sub-window. After making the necessary changes to this subwindow, press the CANCEL key to return to the Modify menu.

The values to be used in this session are now stored in your system’s memory and are known as the “current” setup. The program can continue without saving these changes to disk or you may save the altered setup for future use by using the Write command, which is highlighted when you exit Modify mode.

Removing a SetupTo delete a setup, choose Remove from the Offline menu. At the prompt, either

◊ type in the name of the setup you want to delete and press ENTER, or

◊ press ENTER to display the Setup Directory, highlight the setup you want to delete, and press ENTER.

You will then be asked if you want to delete the setup. Select “Yes” to delete the setup or “No” to cancel the deletion and return to the Offline menu.

Setup Fields

This section briefly discusses the function of each setup field of the Setup window and indicates default values in brackets and corre-sponding BLASTscript variables in italics (For more on BLAST-script variables, see Chapter 16). The Online Help for each field also contains detailed information. The individual fields are discussed on the pages listed in the following table:

10.8xAlternatively, you can press CTRL P to bring up the field for editing at the top of your screen. Edit using the BACKSPACE, DELETE, and cursor (arrow) keys; then press ENTER.

66 CHAPTER FIVE

FIELD PAGE FIELD PAGEDESCRIPTION: 67 EMULATION: 74

PHONE NUMBER: 67 DEC VT SUBWINDOW: 74SYSTEM TYPE: 67 PC ANSI SUBWINDOW: 78

USERID: 68 WYSE SUBWINDOW: 78PASSWORD: 69 FULL SCREEN: 81

CONNECTION: 69 LOCAL ECHO: 82CONNECTION T/O: 69 AUTOLF IN: 82

ORIGINATE/ANSWER: 70 AUTOLF OUT: 82MODEM TYPE: 70 WAIT FOR ECHO: 82

BAUD RATE: 71 PROMPT CHAR: 83PARITY: 71 CHAR DELAY: 83

DATA/STOP BITS: 72 LINE DELAY: 83XON/XOFF PACING: 72 PROTOCOL: 84

RTS/CTS PACING: 72 BLAST SUBWINDOW: 84KEYBOARD FILE: 72 KERMIT SUBWINDOW: 89

SCRIPT FILE: 72 X/YMODEM SUBWINDOW: 92LOG FILE: 73 ZMODEM SUBWINDOW: 94

TRANSLATE FILE: 73 PACKET SIZE: 98ATTENTION KEY: 73

Description user-defined

Provides a detailed description of the setup. This is a free form com-ment; however, scripts can use the variable @SYSDESC for any pur-pose. For example, the program can take information from the description line as input or write to it to save status information.

BLASTscript variable: @SYSDESC

Phone Number user-defined

Stores the phone number of the remote computer. This field will al-low up to 40 characters. For a direct connection, leave the Phone Number field empty.

Although any alphanumeric characters may be entered, be careful to avoid using characters that may be misinterpreted by the modem. This string of characters is passed unchanged to the modem. See your modem manual for details.

BLASTscript variable: @PHONENO

System Type any valid system type

Identifies the computer type to which BLAST will connect. If you are connecting to a system that does not appear in the System Type field or to a single-user system, select NONE. (Mac and PC types are provided for consistency with BLAST scripts but are equivalent to

THE SETUP 67

NONE.) The CONNECT, DISCONNECT, FILETRANSFER, and UPLOAD processes use this information to automate your logons and file transfers.

The available system types are modified periodically by BLAST, Inc. The following example list may or may not include the system types available with your copy of BLAST. You may download the most recent system script from our FTP site at ftp://blast.com/dist/scripts/.

NONE – Single-user system such as IBM PC or Apple MacintoshPC – IBM PCMac – Apple MacintoshVMS – DEC VAX VMSAOS – Data General AOSBHost – BLAST HostUNIX – UNIX XENIX – Xenix AIX – IBM RS/6000A/UX – Apple UNIXHP-UX – Hewlett-Packard UNIXIRIX – Silicon Graphics UNIXQNX – QNX 4.2SCO – SCO UNIXSunOS – Sun UNIXUltrix – DEC VAX UltrixCEO – Data GeneralMVS/TSO – IBM MainframeVM/CMS – IBM MainframeWBHOST – WinBLAST

To specify a user-defined system type, enter into this field the name of the .scr file. See Chapter 14 for more details on systems.scr and user-defined system scripts.

BLASTscript variable: @SYSTYPE

Userid user-defined

Holds the login ID that you will use to log onto the remote system. With the value of this field, BLAST’s CONNECT command uses the systems.scr library to answer logon queries automatically.

BLASTscript variable: @USERID

68 CHAPTER FIVE

Password user-defined

Holds the password that you will use to log onto the remote system. With the value of this field, BLAST’s CONNECT command uses the systems.scr library to answer password queries automatically. To maintain security, this field is intentionally overwritten with Xs in the Setup window and encoded in the setup file on the disk.

As additional security, BLAST will prompt you for this password if this field is left blank; therefore, the password need not be on the disk at all. See the explanation of @PASSWORD on page 280.

BLASTscript variable: @PASSWORD

Connection any valid device

Specifies the communications port, host system for TCP/IP connec-tions, or hunt file that BLAST will use for the current session. Valid options are:

Device name – Any valid asynchronous port (e.g., /dev/tty1A).

Host name or address – The name or network address of the TCP/IP host system to which you want to connect (for example, “blaster.blast.com”). To establish a raw socket, enter the host name and any available port number except 23. Port number 23 is reserved for telnet. To use telnet, simply enter the host name, and BLAST will default to port number 23. To use telnet with a port other than port 23, enter the host name, the port number, and “telnet,” as in the ex-ample below: blaster.blast.com 12 telnet

See “Accessing TCP/IP Ports” on page 16.

Hunt filename – The name (including path) of a hunt file that lists available devices, preceded by the “<” character. Refer to “Auto-matic Serial Port Searching” on page 25 for details concerning hunt files.

BLASTscript variable: @COMMPORT

Connection T/O 0 – 999 [60]For networks, specifies the number of seconds that BLAST will wait for a network connection after entering the Online menu. This field has no effect on serial connections.

THE SETUP 69

If the specified amount of time passes and a connection has not been made, BLAST will display an error message, set @STATUS to a non-zero value, and return to the Online menu.

Values for this field range from 0 to 999 seconds. If set to 0, BLAST will not time out.

BLASTscript variable: @CONNTIMO

Originate/Answer [ORIGINATE] ANSWER

Specifies what BLAST will do during the automated connect and disconnect processes.

To dial out and initiate a connection, set the field to ORIGINATE. To set BLAST to wait for a caller to connect, set the field to ANSWER.

BLASTscript variable: @ORGANS

Modem Type any valid modem type

Identifies the modem connected to your communications port. When you select the Online Connect or Disconnect menu command, or use the CONNECT or DISCONNECT BLASTscript command, BLAST uses the modem type named in this field to execute pre-defined programs from the modems.scr library. These routines per-form various hardware-specific tasks, such as dialing the phone and disconnecting from the remote computer.

The available modem types are modified periodically by BLAST, Inc. The following list may or may not include the modem types available with your copy of BLAST. You may download the most recent modems.scr from our FTP site at ftp://blast.com/dist/scripts/.

NONE – no modem specifiedHARDWIRE – direct connectionAPEX – Apex Data modemsAT – Generic AT command set (does not set flow control)AT&T – AT&T Paradyne modemsBOCA – Boca modemsCARDINAL – Cardinal modemsCODEX – Codex modemsHAYES – Hayes modemsINTEL – Intel modems MEGAHZ – Megaherz modemsMICROCOM – Microcom modemsMOTOROLA – Motorola Universal Data Systems (UDS) modems

70 CHAPTER FIVE

MULTITEC – MultiTech modemsOPTIMA – Optima Hayes modemsOSITECH – Ositech modemsPRACTICL – Practical Peripherals modemsSUPRA – Supra modemsTELEBIT – Telebit modemsUDSFASTK – Motorola UDS FasTalkUDSV3229 – Motorola UDS V3229 USROBOT – U.S. Robotics modemsUSRV32 – U.S. Robotics Courier V.32, V.32bis, V.42, V.42bisZOOM – Zoom modemsZYXEL – ZyXEL modems

If your modem does not appear as a choice in the setup field, you may specify a user-defined modem type by entering into this field the name of the .scr file. See Chapter 14 for more details on mo-dems.scr and user-defined modem scripts.

BLASTscript variable: @MODEM

Baud Rate 300 600 1200 2400 4800[9600] 19.2 38.4 57.6 115K

Specifies the speed at which the serial port device driver communi-cates with the modem. This may or may not be the same speed at which the modems communicate with each other. Some older mo-dems are incapable of negotiating link speeds with other modems. A Hayes 2400, for example, will not operate at speeds any higher than 2400. If you have trouble connecting with other systems, match your Baud Rate setting with the highest Baud Rate supported by the re-mote system.

It is sometimes advantageous to run at a lower than maximum baud rate. If you have a slow computer, are running many applications si-multaneously, or have limited system memory, you may notice dropped characters at very high baud rates, causing garbled displays in Terminal mode and a high number of block retransmissions dur-ing file transfers. Throughput may be better at a slower rate.

BLASTscript variable: @BAUDRATE

Parity [NONE] ODD EVEN

Sets the device driver parity of the serial port. This setting should match that of the remote system.

BLASTscript variable: @PARITY

THE SETUP 71

Data/Stop Bits 7/1 7/2 [8/1] 8/2

Sets the number of data bits (7 or 8) and number of stop bits (1 or 2) for the device driver.

BLASTscript variable: @D/S_BITS

XON/XOFF Pacing YES [NO]Specifies whether BLAST will use software flow control during text uploading, Terminal mode operation, and file transfer. When one computer needs to stop the flow of incoming data, it transmits an XOFF (CTRL S) to the other computer. When the computer is again ready to receive data, it transmits an XON (CTRL Q).

During BLAST protocol transfer, BLAST will wait a maximum of 30 seconds for an XON from the remote. If the XON is not sent, BLAST will resume transfer. See “Flow Control” on page 30.

BLASTscript variable: @XONXOFF

RTS/CTS Pacing YES [NO]Enables hardware flow control. RTS/CTS pacing uses the RS-232 signals Request-to-Send and Clear-to-Send for optimized through-put over error-correcting modems. Not all systems support this type of flow control.

Set this field to NO unless error-correcting modems are on both ends of the connection. See “Flow Control” on page 30.

BLASTscript variable: @RTSCTS

Script File filename

Designates a BLAST script that will be executed immediately when the setup is loaded into memory. A script specified on the BLAST command line will override a script specified in this field.

10.7x

Keyboard File filename

Specifies a user-defined keyboard map for a particular keyboard or application (see “Keyboard Mapping Utility for 10.7x” on page 315).

BLASTscript variable: @KEYFILE

72 CHAPTER FIVE

Use BLAST scripts to automate part or all of a BLAST session.

BLASTscript variable: @SCRFILE

Log File filename

Names the log file that keeps a record of all session activity. When a file is transferred, a menu selection made, or a BLASTscript state-ment executed, the log file records the activity and the time that it occurred. Extended logging offers detailed information about file transfers. For more information on extended logging, see the de-scription of the @XLOG reserved variable on page 298.

If the filename that you enter already exists, BLAST appends the new session activity information to the existing file; otherwise the file is created. Log files do not need any particular extension and can be any combination of the normally accepted filename characters. You may specify a full path as part of the log filename.

BLASTscript variable: @LOGFILE

Translate File filename

Designates a control file to filter incoming or outgoing characters in Terminal mode and during text upload/capture. The Translate File is an ASCII text file that can be edited by a text processor or the BLAST editor. See “Translate File Format” on page 306 for more information.

BLASTscript variable: @XLTFILE

Attention Key any Control key [^K]Defines the key combination that will be interpreted as the Attention Key. This field accepts a single keystroke, which will be used in combination with the CTRL key. Throughout this manual, the Atten-tion Key is referred to as ATTN.

If it is necessary to change the attention key, be sure to choose a re-placement value that will not interfere with your system’s designat-ed control codes. In particular, do not use ^M, which is the control code for a carriage return. Check your system manual for more in-formation about special control codes before you reassign the atten-tion key.

THE SETUP 73

We recommend that you do not change this setting.

BLASTscript variable: @ATTKEY

Emulation

BLASTscript variable: @EMULATE

DEC VT Emulation Subwindow for 10.7x

Selecting any of the VT emulators and pressing ENTER will display a subwindow of extended configuration options. The VT320 subwin-dow is pictured in Figure 5-3; the VT220, VT100, and VT52 sub-windows are variations of the VT320 subwindow. Not all of the following setup fields will appear in every subwindow.

FIGURE 5-3

10.8xYou can turn off the attention key in a script by setting @ATTKEY to a null value (""). When the script terminates, its value is reset to its previous setting.

10.7x

PASSTHRU [VT320]any valid terminal emulator

The terminal values are PASSTHRU, in which the characters received by the serial port are displayed without change, TTY, and the following terminal emulators: VT320, VT220, VT100, VT52, PC ANSI, TV920, D80, ADM3A, WYSE50, and WYSE60.

10.8xTTY [PASSTHRU]

The terminal values are PASSTHRU, in which the characters re-ceived by the serial port are displayed without change, and TTY.

74 CHAPTER FIVE

7/8 Bit Controls [7] 8

Specifies whether “CI” control characters are represented in the 8-bit environment or as 7-bit escape sequences.

BLASTscript variable: @VT8BIT

80/132 Columns [80] 132

Toggles between 80-column and 132-column display for text.

BLASTscript variable: @VTDISP132

Horizontal Scroll [JUMP] NONE SMOOTH

Specifies how to scroll data on an 80-column display when the em-ulator is in 132-column mode. SMOOTH scroll will move the view of the display only as necessary to display the cursor position. JUMP scroll will adjust the view by showing either the first 80 columns or the last 80 columns. When NONE is selected, the display will not scroll and the cursor may disappear from view.

BLASTscript variable: @VTHSCROLL

Jump Scroll Inc 1 – 53 [10]Specifies the number of columns to scroll when the Scroll Left or Scroll Right keys are pressed and Jump has been selected as the set-ting for Horizontal Scroll. Acceptable values are 1–53.

BLASTscript variable: @VTHSCROLLN

Keypad Mode [NUMERIC] APPLICATION

Specifies whether the numeric keypad keys will send numbers (NUMERIC) or programming functions (APPLICATION) defined by the application.

BLASTscript variable: @VTKEYPAD

Cursor Keys Mode [NORMAL] APPLICATION

Specifies whether the cursor keys will control cursor movement (NORMAL) or send application control functions (APPLICATION).

BLASTscript variable: @VTCURSOR

THE SETUP 75

Reset Terminal YES [NO] Specifies resetting many of the VT320 operating features, such as scrolling regions and character attributes, to their factory default val-ues upon entering Terminal mode. YES resets these values; the value of this variable is then automatically reset to NO.

BLASTscript variable: @VTRESET

Clear Screen YES [NO]Specifies clearing of the terminal’s video display the next time you enter Terminal mode. YES clears the terminal’s video display; the value of this variable is then automatically reset to NO.

BLASTscript variable: @VTCLRSCRN

Answerback Msg up to 30 characters

Contains a message to be sent to the remote computer upon receiv-ing an inquiry (^ E). The message can be up to 30 characters in length.

BLASTscript variable: @VTANSBACK

User Def Keys [UNLOCKED] LOCKED

Specifies whether the host system can change user-defined key (UDK) definitions.

BLASTscript variable: @VTUSERKEYS

Text Cursor [YES] NO

Specifies whether to display the text cursor.

BLASTscript variable: @VTTEXTCURS

Cursor Type BLOCK [LINE]Specifies whether the cursor is displayed as a reverse-video block or as an underline character.

BLASTscript variable: @VTCURSTYPE

76 CHAPTER FIVE

Auto Wrap YES [NO]Specifies whether text typed at the right margin will automatically wrap to the next line.

BLASTscript variable: @VTAUTOWRAP

New Line YES [NO]Selects whether the ENTER key will move the cursor to a new line. Possible choices are NO (the ENTER key sends only a carriage return) and YES (both a carriage return and line feed are sent).

BLASTscript variable: @VTNEWLINE

Print Mode [NORMAL] AUTO CONTROLLER

Specifies when information is sent to the printer. In AUTO print mode, each line of received text is displayed and printed; in CONTROLLER mode, all received data is sent directly to the printer without displaying it on the screen; and in NORMAL mode, the user initiates printing from the keyboard.

BLASTscript variable: @VTPRINT

Print Screen [SCROLL REGION] FULL PAGE

Specifies how much of the screen to print when you press the PRINT

SCREEN key. Choices are FULL PAGE (entire page) and SCROLL REGION (only the currently defined VT scrolling region).

BLASTscript variable: @VTPRINTPAGE

Intl Char Set [USASCII] UK FRENCHGERMAN ITALIAN SPANISH DANISH

Specifies whether 7- or 8-bit data is used for international support. The default value is USASCII, which allows 8-bit data. The high-order values are used to represent international characters. If any other character set is selected, specific international characters re-place characters within the ASCII set.

BLASTscript variable: @VTINTL

THE SETUP 77

User Pref Char Set [DEC SUPPLEMENTAL]ISO LATIN-1

Selects either DEC SUPPLEMENTAL or ISO LATIN-1 as the user preferred character set.

BLASTscript variable: @VTUSERCHAR

PC ANSI Emulation Subwindow for 10.7x

Selecting the PC ANSI emulator and pressing ENTER displays a sub-window of extended configuration options shown in Figure 5-4:

FIGURE 5-4

ANSI Level 2.x [3.x]Specifies the level of ANSI for your system. Some applications re-quire ANSI Level 2.x.

BLASTscript variable: @ANSILEVEL

Auto Wrap YES [NO]Specifies automatic wrapping of lines longer than 80 characters.

BLASTscript variable: @ANSIAUTOWRAP

WYSE Emulation Subwindow for 10.7x

Selecting the WYSE60, WYSE50, TV920, D80, or ADM3A emula-tors and pressing ENTER will display a subwindow of extended con-figuration options shown in Figure 5-5 (next page).

78 CHAPTER FIVE

FIGURE 5-5

Page Length [1 * DATA LINES]2 * DATA LINES 4 * DATA LINES

Sets page length in number of screens of data. 2* DATA LINES sets the page length to 48 lines; 4* DATA LINES sets the page length to 96 lines.

BLASTscript variable: @WYPAGELEN

Auto Wrap [YES] NO

Specifies whether a new line is automatically performed when a character is placed in the last column of a row (column 80 or 132).

BLASTscript variable: @WYAUTOWRAP

Auto Scroll [YES]Specifies scrolling of the terminal display when the cursor reaches the bottom of a page. The default value of YES cannot be changed. (The Auto Scroll value is ignored if Auto Page is on.)

BLASTscript variable: @WYAUTOSCROLL

Auto Page YES [NO]Controls whether the cursor can move off the current page. If YES is selected, the cursor can move above the first line to the previous page or below the last line to the next page.

BLASTscript variable: @WYAUTOPAGE

THE SETUP 79

Wyseword YES [NO]Specifies whether keys send Wordstar™ functions (YES) or the standard key codes (NO). The only keys that are affected are the WYSE keys that can be mapped with the blastkbd utility (see “Key-board Mapping Utility for 10.7x” on page 315).

BLASTscript variable: @WYSEWORD

Expanded Memory YES [NO]Toggles “expanded” memory use. Note that this is not related to DOS “expanded memory.” Normally, the terminal emulator uses two pages of video display memory. If the maximum of four pages are required, expanded memory must be set to YES. Note, however, that more run-time memory will be required by BLAST, possibly adversely affecting throughput during file transfers.

BLASTscript variable: @WYEXPNDMEM

Write Protect [DIM] REVERSE NORMAL

Specifies the attributes used to display protected fields.

BLASTscript variable: @WYWRITEPROT

Answerback up to 20 characters

Contains a message to be sent to the remote computer upon receiv-ing an inquiry (Ê). The message can be up to 20 characters long.

BLASTscript variable: @WYANSBACK

Columns [80] 132

Specifies 80 or 132 columns per row.

BLASTscript variable: @WYDISP80

Horiz Scroll Inc 1 – 53 [10]Specifies the number of columns to scroll when the cursor reaches a column that is not currently displayed. This value is used when 132 columns per row has been selected and compressed display is not available. Note that a value of 1 implies smooth scrolling. Any other value implies jump scrolling.

BLASTscript variable: @WYSCROLLINC

80 CHAPTER FIVE

Display Cursor [YES]Specifies that the cursor is visible. The default of YES cannot be changed.

BLASTscript variable: @WYDSPCURSOR

Return [CR] CRLF TAB

Selects the character to send when the RETURN key is pressed. The default value is CR, which signifies a carriage return.

BLASTscript variable: @WYRETURN

Enter [CR] CRLF TAB

Selects the character to send when the keypad ENTER key is pressed.

BLASTscript variable: @WYENTER

Comm Mode [CHARACTER] BLOCK

Controls whether data is sent after each keystroke (CHARACTER mode) or grouped in blocks (BLOCK mode).

BLASTscript variable: @WYCOMMODE

Block End [US/CR] CRLF/ETX

Specifies what characters mark the end-of-line and end-of-block when the terminal is in block mode and sends a block of data. If US/CR is selected, a US character (\037) is sent at the end of each line and a CR character (\015) is sent to mark the end of the block.

BLASTscript variable: @WYBLOCKEND

END OF EMULATION SUBWINDOW DESCRIPTIONS

Full Screen [YES] NO

Indicates whether the top four lines of the menu display will be sup-pressed while in Terminal mode. The default value is YES, which suppresses the menu and allows the top 24 lines of the terminal screen to be used for data.

BLASTscript variable: @FULLSCR

THE SETUP 81

Local Echo YES [NO]Specifies whether BLAST will echo typed characters to the screen while in Terminal mode. If this field is set to YES, BLAST will dis-play typed characters before sending them out the communication port; if the field is set to NO, the characters will be displayed only if the remote computer sends them back.

If this field is set to YES and double characters are displayed on the screen, change the setting to NO.

BLASTscript variable: @LOCECHO

AutoLF In YES [NO]Controls the Terminal mode actions when receiving carriage re-turns. Some remote systems do not automatically supply line feeds, causing multiple lines of text written on top of each other on your monitor. Set to YES to read incoming text correctly from this com-puter type. The setting for AutoLF In has no effect on text received in Capture mode.

BLASTscript variable: @AUTOLFIN

AutoLF Out YES [NO]Controls Terminal mode actions when sending carriage returns. A setting of YES causes BLAST to append a line feed to each carriage return sent out from the communications port. Line feeds are often stripped from the data stream to increase throughput. Set this to YES if the remote system requires a line feed after the carriage return.

BLASTscript variable: @AUTOLFOUT

Wait for Echo YES [NO]During text uploads, forces BLAST to wait for the echo of the pre-viously sent character before sending another character; the setting has no effect on file transfers.

Wait for Echo “paces” text uploads to slow BLAST down when the remote computer operates more slowly than the local system. It is also useful when sending one-line commands to modems that cannot take bursts of high speed data while in Command mode.

BLASTscript variable: @WT4ECHO

82 CHAPTER FIVE

Prompt Char [NONE] any ASCII character

Defines the character that BLAST will use to determine when to re-sume sending text. After sending a line of text and a carriage return, BLAST pauses until the remote system sends the prompt character. Prompting is an effective form of flow control while uploading text.

Any single character, including a control character, is a valid entry. To enter a control character, prefix the character with a caret (^). NONE disables prompting.

BLASTscript variable: @PROMPTCH

Char Delay [0] – 999

Specifies the time period (in hundredths of a second) that BLAST pauses between sending characters to the remote computer. This pause slows down strings sent by BLAST scripts and text that is up-loaded.

Character delay is a form of flow control. Use this field when the re-mote computer is unable to keep pace with BLAST and no other form of flow control is available or to slow down the interaction with a modem or other simple hardware device that does not support oth-er forms of flow control. The default value, 0, specifies no delay. Character delay applies only to text uploads; it has no effect on file transfers.

BLASTscript variable: @CHARDLY

Line Delay [0] – 999

Specifies the length of time (in tenths of a second) to pause after sending a line of data. Line Delay provides a form of flow control while uploading text to the remote computer. Some remote systems may be unable to keep pace with BLAST; setting this field to a non-zero value can prevent overloading the remote computer. If 0 is en-tered, no delay will occur. Note that the setting for Line Delay ap-plies only to text uploads.

BLASTscript variable: LINEDLY

THE SETUP 83

Protocol [BLAST] KERMITXMODEM XMODEM1K

YMODEM YMODEM G ZMODEM

Selects the protocol that will be used for file transfers. The BLAST protocol generally runs faster and offers more features than other protocols.

BLASTscript variable: @PROTOCOL

BLAST Protocol Subwindow

Selecting BLAST and pressing ENTER displays the subwindow shown below in Figure 5-6:

FIGURE 5-6

Logon T/O 0 – 999 [120]Specifies the number of seconds that BLAST will attempt to estab-lish a filetransfer session with the remote computer. Logon Timeout affects BLAST protocol transfers and remote control sessions. Timeouts can happen if:

◊ There is excessive noise on the line.

◊ There are parity or data/stop bit mismatches.

◊ BLAST is terminated unexpectedly on the remote computer.

◊ The connection is lost.

If zero is entered, no timeout will occur and BLAST will attempt to establish a filetransfer session with the remote computer indefinite-ly.

BLASTscript variable: @LOGTIMO

10.8x FTP

84 CHAPTER FIVE

Inactivity T/O 0 – 999 [120]Defines the time interval (in seconds) that BLAST will stay connect-ed after the last valid data packet has been received from the remote computer. Timeouts happen if:

◊ The connection is lost.

◊ There is excessive noise on the line.

◊ The remote computer goes down.

◊ Flow control has not been released.

If zero is specified, BLAST never times out.

NOTE: In previous versions of BLAST, this field was named “Connect Timeout” and was associated with the BLASTscript re-served variable @CONTIMO.

BLASTscript variable: @INACTIMO

7-Bit Channel YES [NO]Defines the logical width of the data path to be used. YES specifies a 7-bit data encoding scheme; NO specifies an 8-bit encoding scheme.

Some networks, minicomputers, and asynchronous devices only support 7-bit path widths. The BLAST protocol operates more effi-ciently using 8-bit encoding; however, the data path width has noth-ing to do with the type of data that can be transferred. BLAST may transfer 8-bit binary or 7-bit ASCII over either 7- or 8-bit data paths.

BLASTscript variable: @7BITCHN

Window Size 1 – [16]Specifies the number of packets that can be sent to the remote with-out BLAST waiting for an acknowledgement from the remote. As packets are acknowledged, the starting point of the window adjusts, or “slides.” For example, if the window size is 12 and the first 6 of 8 packets sent have been acknowledged, the start point of the win-dow moves by 6, and 10 additional packets can be sent before BLAST must stop and wait for an acknowledgement. See “BLAST Protocol Design” on page 101 for a fuller discussion of window size.

BLASTscript variable: @WDWSIZ

THE SETUP 85

DCD Loss Response ABORT [IGNORE]Specifies the action BLAST will take after DCD loss during a file-transfer session:

ABORT –Sets @EFERROR on carrier loss and exits Filetransfer mode.

IGNORE –Ignores carrier loss. Filetransfer mode continues until the Inactivity T/O takes effect.

BLASTscript variable: @DCDLOSS

Use “A” Protocol YES [NO]Specifies whether the BLAST “A” Protocol will be used. YES spec-ifies communication with older BLAST products.

BLASTscript variable: @APROTO

Filtering ON [OFF]Specifies filtering out VT sequences sent from a remote computer or protocol converter. This filtering prevents BLAST protocol from la-beling these sequences as bad blocks received.

BLASTscript variable: @FILTER

Retransmit Timer 0 – 9999 [4]Sets the maximum number of seconds BLAST will pause before resending a packet. For example, if Window Size is set to 5 and Re-transmit Timer is set to 30, BLAST will attempt to resend the fifth packet every thirty seconds if it receives no acknowledgement.

NOTE: This setting should be less than the that for Inactivity Time-out.

BLASTscript variable: @RETRAN

ACK Request Frequency 1 – window size [4]Specifies the frequency at which an acknowledgement from the re-ceiving system is requested. The frequency is measured in number of packets sent. For example, if the ACK Request Frequency is 4, a request for an acknowledgement is sent to the receiving computer every four packets. Set this field higher for better performance with

86 CHAPTER FIVE

error-correcting modems. See also Window Size setup field (page 85).

BLASTscript variable: @ACKFREQ

Number of Disconnect Blocks 0 – 9 [3]Sets the number of additional disconnect blocks (after the first dis-connect block) that BLAST sends when exiting Filetransfer mode. The default value is 3, which indicates four total disconnect blocks.

BLASTscript variable: @NUMDISC

Launch String any ASCII string [\r]Specifies a string to be appended to BLAST protocol blocks. This will help communications to a mainframe through protocol convert-ers. Just as in BLASTscript, you may send any string of ASCII characters, including the same control characters used in string con-stants. Nonprintable characters can be represented with a back-slash followed by a three-digit octal number (for example, a line-feed may be represented as a \012). The string should not be enclosed in quotes. The default for this field is a carriage return (\r).

BLASTscript variable: @LAUNCHST

Transfer Password user-defined

Stores a case-sensitive password (up to eight characters) that re-stricts a remote user’s access. Requests to get files from a password-protected computer and to do file maintenance functions are not honored unless the password is received first. Without the password, the remote machine is limited to sending and receiving messages.

To send the Transfer Password, the remote user should select the Send menu command from the Filetransfer menu; then, at the local filename prompt, type the following:

!password=your_password

where your_password is the transfer password. The remote file-name field and transfer options should be left blank. In a BLAST script, the SEND statement should be followed by a line with the password and then two blank lines (See “Using the Transfer Pass-word” on page 121).

THE SETUP 87

The transfer password is superseded by the Secure BLAST password described in Chapter 11. See that chapter for further details.

NOTE: The Transfer Password is intended to validate remote us-ers logging onto your system. If a local operator uses a setup with a Transfer Password entered, he or she will not be able to receive files without the remote computer sending the password.

BLASTscript variable: @TRPASSWD

Enable /FWD and /STR YES [NO]Enables the /FWD and /STR file transfer switches. Note that dis-abling these switches affects only local files. For example, you will still be able to get a file with the /FWD switch, because the success-fully transferred file will be deleted from the remote system.

BLASTscript variable: @ENABLEFS

Enable /OVW and Remote Cmds [YES] NO

Enables the /OVW file transfer switch and system commands re-ceived during BLAST Protocol Filetransfer mode. Disabling /OVW affects only local files. For example, you will still be able to send a file with the /OVW switch because the file will be overwritten on the remote system. The List, Type, and More commands remain active when this field is set to NO; only potentially destructive commands are disabled.

BLASTscript variable: @ENABLERCMD

Send Compression Level 0 – 6 [4]Specifies the maximum compression level to be used while sending files to the remote computer. Level 0 specifies no compression; lev-el 6 specifies the highest compression level.

BLASTscript variable: @SCOMP_LEV

Receive Compression Level 0 – 6 [4]Specifies the maximum compression level to be used while receiv-ing files from the remote computer. Level 0 specifies no compres-sion; level 6 specifies the highest compression level.

BLASTscript variable: @RCOMP_LEV

88 CHAPTER FIVE

Kermit Protocol Subwindow

Selecting KERMIT and pressing ENTER displays the subwindow shown in Figure 5-7 below:

FIGURE 5-7

Start-of-Packet Char [Â] – ^Z

For sending files with Kermit: specifies a control character to pre-cede each packet sent from the local computer. The same control character must also be used by the remote Kermit.

BLASTscript variable: @KSSOPKT

For receiving files with Kermit: specifies a control character to pre-cede each packet received by the local computer. The same control character must also be used by the remote Kermit.

BLASTscript variable: @KRSOPKT

End-of-Packet Char Â – ^Z [^M]For sending files with Kermit: specifies a control character to termi-nate each packet sent from the local computer. The same control character must also be used by the remote Kermit.

BLASTscript variable: @KSEOPKT

For receiving files with Kermit: specifies a control character to ter-minate each packet received by the local computer. The same con-trol character must also be used by the remote Kermit.

BLASTscript variable: @KREOPKT

THE SETUP 89

Packet Size 10 – 2000 [90]For sending files with Kermit: specifies the packet size that your system will use when it transmits a file. Note that the remote Kermit server’s Receive Packet Size should also be set to this value. The larger the packet, the more efficient the transfer; however, larger packets will pose problems on a noisy connection. Set larger packet sizes when there is little line noise, you are communicating with a mainframe, or you are using V.29 “ping pong” modems.

BLASTscript variable: @KSPKTLEN

For receiving files with Kermit: specifies the packet size that your system will use when it receives a file. Note that the remote Kermit server’s Send Packet Size should also be set to this value. The larger the packet, the more efficient the transfer; however, larger packets will pose problems on a noisy connection. Set larger packet sizes when there is little line noise, you are communicating with a main-frame, or you are using V.29 “ping pong” modems.

BLASTscript variable: @KRPKTLEN

Pad Character [^@], Â – ^Z

For sending files with Kermit: specifies an alternate character to pad each packet transmitted by the local computer.

BLASTscript variable: @KSPADCH

For receiving files with Kermit: specifies an alternate character to pad each packet received by the local computer

BLASTscript variable: @KRPADCH

Padding [0] – 99

For sending files with Kermit: specifies the number of padding characters to send per packet. Padding can induce delays during a Kermit file transfer, allowing slower machines or older versions of Kermit more time to process the data you send.

BLASTscript variable: @KSPADDNG

For receiving files with Kermit: specifies the number of padding characters to request per packet. Padding can induce delays during a

90 CHAPTER FIVE

Kermit file transfer, allowing slower machines or older versions of Kermit more time to process the data you receive.

BLASTscript variable: @KRPADDNG

Transfer Type TEXT [BINARY]Specifies the type of file being transferred. Text files will be con-verted to local format.

BLASTscript variable: @KFILETYP

Delay 1 – 99 [5]Specifies the number of seconds of delay between the recognition of a Send command and the actual beginning of the transmission.

BLASTscript variable: @KDELAYOS

Block-Check-Type 1 – 3 [2]Specifies level of error detection. Kermit offers three levels of error detection, with 3 being the most secure. To decrease the chance of a bad packet being accepted by the receiving computer, set the level to 2 or 3. Higher levels of error detection will appreciably slow a file transfer. Use a lower block-check-type when using error-correcting modems or when transferring files at 9600 baud and above.

BLASTscript variable: @KBCHECK

Timeout 0 – 99 [10]Specifies the number of seconds that the computer will wait to re-ceive a packet before requesting that it be resent.

BLASTscript variable: @KRTIMEOUT

Filename Conversion [YES] NO

Specifies whether to convert a filename from local format to com-mon Kermit format. For example, lower case is changed to all up-percase; and “~”, “#”, and all periods after the initial one are converted to “x”s.

BLASTscript variable: @KFNAMCONV

THE SETUP 91

Incomplete File [DISCARD] KEEP

Specifies whether to KEEP or DISCARD files incompletely re-ceived, such as a file being transferred when you abort a Get com-mand. This insures that any file received is complete.

BLASTscript variable: @KSAVEINC

Warning [ON] OFF

For Kermit transfers, specifies whether Kermit will automatically rename a received file if another file with the same name already ex-ists in the current directory. If the field is set to ON, Kermit will re-name the file, adding a number (0001, 0002, etc.); if the field set to OFF, Kermit overwrites the file.

BLASTscript variable: @KWARNING

Xmodem and Ymodem Protocol Subwindow for 10.8x

In BLAST Professional UNIX 10.8x, selecting XMODEM, XMODEM1K, YMODEM, or YMODEM G and pressing ENTER displays the subwindow shown in Figure 5-8. Some fields apply to Xmodem only.

FIGURE 5-8

EOT Timeout 10 – 6000 [100]For Xmodem and Ymodem transfers, specifies EOT (end-of-trans-mission) timeout in hundredths of a second.

BLASTscript variable: @XYEOT

92 CHAPTER FIVE

Pad Character any character in decimal [00]For Xmodem transfers, specifies the pad character.

BLASTscript variable: @XPADC

File Conversion ASCII [BINARY]For sending Xmodem and Ymodem transfers, specifies conversion to ASCII.

BLASTscript variable: @XYCONVS

For receiving Xmodem and Ymodem transfers, specifies conversion to ASCII.

BLASTscript variable: @XYCONVR

Remote Line Termination CR [CR/LF]For sending files with Xmodem or Ymodem: specifies how line ter-mination is treated.

CR – For files sent, replaces line feeds (LF) with carriage returns (CR); for example, when ASCII files are sent to a Macintosh plat-form.

CR/LF – For files sent, adds a carriage return (CR) before a line feed (LF); for example, when ASCII files are sent to DOS or Windows platforms.

BLASTscript variable: @XYRLTS

For receiving Xmodem and Ymodem files: specifies how line ter-mination is treated.

CR – For files received, replaces all carriage returns (CR) with line-feeds (LF); for example, when ASCII files are received from a Mac-intosh platform.

CR/LF – For files received, deletes any carriage return (CR) that is followed by a line feed (LF); for example, when ASCII files are sent to DOS or Windows platforms.

BLASTscript variable: @XYRLTR

THE SETUP 93

Error Detection [CRC] CHECKSUM

For Xmodem transfers, specifies whether the error detection is CRC or CHECKSUM.

BLASTscript variable: @XCRC

Zmodem Protocol Subwindow

Selecting ZMODEM and pressing ENTER displays the subwindow shown in Figure 5-9 below.

FIGURE 5-9

Resume Interrupted File YES [NO]Continues an aborted binary file transfer from the point of interrup-tion. The destination file must already exist and be smaller than the source file.

BLASTscript variable: @ZMRESUME

File Must Already Exist YES [NO]Transfers the file only if it already exists on the destination system.

BLASTscript variable: @ZMEXIST

Conversion Override [NONE] ASCII BINARY

Allows the sender to specify to the receiver whether the data should be treated as BINARY or ASCII data, overriding the File Conver-sion setting of the receiving system. If NONE is selected, the data is handled according to the receiver’s file conversion parameter.

BLASTscript variable: @ZMCONVS

94 CHAPTER FIVE

Management Option [NONE] PROTECTCLOBBER NEWER

NEWER/LONGER DIFFERENT APPEND

Specifies a file management option for files sent. Possible values are:

NONE – The file is transferred if it does not already exist on the re-ceiving system.

PROTECT – The file is transferred only if it does not already exist on the receiving system, even if the receiving system has specified CLOBBER

CLOBBER – The file is transferred whether or not it already exists on the receiving system, unless the receiving system has specified PROTECT.

NEWER –The file is transferred if it does not already exist on the re-ceiving system, or if the source file is newer (by date).

NEWER/LONGER –The file is transferred if it does not already exist on the receiving system, or if the source file is newer (by date) or longer (in bytes).

DIFFERENT – The file is transferred if it does not already exist on the receiving system, or if the files have different lengths or dates. APPEND –The file is appended to a file of the same name on the re-ceiving system based on the value of the receiving system’s “File conversion” setting.

BLASTscript variable: @ZMMANAGS

10.8x

ASCII Line Termination [CR/LF] CR

For sending ASCII files to nonstandard implementations of Zmo-dem, specifies line-feed conversion for ASCII files. When @ZMCONVS = "ASCII", the default CR/LF specifies that line feeds be converted to CR/LF; CR specifies no conversion.

BLASTscript variable: @ZMALT

THE SETUP 95

Esc All Control Chars YES [NO]For sending files with Zmodem: specifies that all control characters sent will be link-escape encoded for transparency. By default, only the characters represented by hexadecimal 10, 11, 13, 90, 91, and 93, and the sequence “@-CR” are link-escape encoded.

BLASTscript variable: @ZMCTLESCS

For receiving files with Zmodem: specifies that all control charac-ters received will be link-escape encoded for transparency. By de-fault, only the characters represented by hexadecimal 10, 11, 13, 90, 91, and 93, and the sequence “@-CR” are link-escape encoded.

BLASTscript variable: @ZMCTLESCR

Limit Block Length [0] 24 – 1024

Overrides the default block length, which is determined by the Baud Rate of the connection. Baud Rate Block Length (in bytes)300 128 600, 1200 256 2400 512 4800 or greater 1024

Specifying a value between 24 and 1024 limits the block length to the new value. A value of 0 specifies the default block length as de-termined by the baud rate.

BLASTscript variable: @ZMBLKLN

Limit Frame Length [0] 24 – 1024

For Zmodem transfers, limits frame length and forces the sender to wait for a response from the receiver before sending the next frame. The default, 0, specifies no limit to frame length.

BLASTscript variable: @ZMFRMLEN

Size of Tx Window [0] – 9999

Specifies the size of the transmit window, which regulates how many data subpackets can be “outstanding” (unacknowledged) be-fore the sender quits sending and waits for acknowledgements. A value of 0 specifies no limit to window size.

BLASTscript variable: @ZMWINDOW

96 CHAPTER FIVE

CRC 16 [32]Specifies the CRC error-detection method to be used, either 16-bit or 32-bit.

BLASTscript variable: @ZMCRC

Auto Receive YES [NO]Specifies Auto Receive mode, which begins downloading immedi-ately after entering Filetransfer mode.

BLASTscript variable: @ZMAUTODOWN

File Conversion [ASCII] BINARY

Specifies whether received files will be treated as ASCII or BINARY. For correct file conversion to ASCII, the remote computer must send the files as ASCII.

BLASTscript variable: @ZMCONVR

File Management NONE PROTECT[CLOBBER] APPEND

Specifies a file management option for files received. Possible val-ues are:

NONE – The file is transferred if it does not already exist on the re-ceiving system.

PROTECT – The file is transferred only if it does not already exist on the receiving system, even if the sending system has specified CLOBBER.

CLOBBER – The file is transferred whether or not it already exists on the receiving system, unless the sending system has specified PROTECT.

APPEND – The file is appended to a file of the same name on the re-ceiving system based on the value of the receiving system’s “File conversion” setting.

BLASTscript variable: @ZMMANAGR

END OF PROTOCOL SUBWINDOW DESCRIPTIONS

THE SETUP 97

Packet Size 1 – 4085 [256]

For BLAST protocol transfers, specifies the packet size that your system will use when it transfers a file. The larger the packet, the more efficient the transfer; however, larger packets will pose prob-lems on a noisy connection. Use larger packet sizes when there is lit-tle line noise, you are communicating with a mainframe, or you are using V.29 “ping pong” modems.

This field “negotiates” down. The versions of BLAST running on the local computer and the remote computer will compare values and use the smaller of the two values.

While transferring files, watch the line quality and retry count in the upper right part of the screen. If the quality of the line varies, or there are a significant number of retries (more than one retry in 20–50 blocks), a smaller packet size will usually improve throughput. The default for this field is 256, which is the optimum setting for most users.

IMPORTANT: When transferring files with BHOST, always set the Packet Size to at least 200, which is BHOST’s minimum packet size.

BLASTscript variable: @PAKTSZ

98 CHAPTER FIVE

Chapter 6

BLAST Session Protocol

What is a Protocol?

In the serial communications world, a “protocol” is a set of rules that determines how two computers will communicate with each other. These rules define, for example, how to package data for transfer, how to detect damaged data, and how to optimize throughput. Both computers must use the same protocol for a communications session to succeed.

Simple ProtocolsDuring the early days of telecommunications, people who needed to transfer a file across a phone line or a hardwired asynchronous con-nection were limited to using text transfer. This is the simplest trans-fer method, involving only the capturing and transmission of the data stream with no error detection. To receive a file, a buffer is opened to save the information; to send a file, the characters from the chosen file are sent directly out of the communications port to the re-mote computer.

Of course, no telecommunications connection is perfect, and users soon found that line noise could easily corrupt a file. Thus, file trans-

BLAST SESSION PROTOCOL 99

fer protocols were developed to provide error control. Kermit, Xmo-dem, Ymodem, Zmodem, and FTP are examples of public domain protocols widely used by computer owners to transfer files. The public domain file transfer protocols are fully described the three chapters following this chapter.

The BLAST Session Protocol

The BLAST Session protocol defines a set of rules for performing file transfer and file management with a remote computer. Under the BLAST Session protocol, three kinds of tasks can be performed:

1. Files can be transferred between local and remote machines. The BLAST Session protocol permits files to be transferred bi-directionally—that is, data is sent and received at the same time with automatic error detection and data compression.

2. Files on the remote machine can be manipulated. For example, files can be deleted, renamed, or printed on the remote comput-er. Because these tasks are mediated by the BLAST Session protocol, the commands cannot be garbled by line noise. In ad-dition, the commands are automatically translated into the ap-propriate instructions on the remote computer. For example, when you give the “List Files” command using the BLAST Session protocol, you will receive a directory listing whether the remote machine is a Macintosh, a VAX, or a computer run-ning the UNIX operating system. You do not need to know the machine-specific instruction.

3. Messages can be exchanged between the local and remote com-puter. Between file transfers, if someone is present at the remote site, you can send messages to and receive messages from the remote operator.

The BLAST Session protocol is much more sophisticated than pub-lic domain file transfer protocols. No public domain protocol has all the characteristics of BLAST session protocol. BLAST is generally faster than public domain file transfer protocols because it offers all of the following features:

◊ Bi-directional transfers.

◊ Six levels of compression.

◊ Sliding-window design.

100 CHAPTER SIX

◊ Automatic translation of text files between the local file format and the format of the remote system.

◊ Resumption of interrupted file transfer from the point of inter-ruption.

◊ Security for validating remote users.

BLAST Protocol Design

Bi-Directional and Sliding-Window CapabilityThe BLAST protocol is capable of transmitting and receiving data packets simultaneously. This simultaneous bi-directional transfer saves time and online charges when files need to be both sent and received.

BLAST operates efficiently over circuits with high propagation de-lays (the length of time from when a character is transmitted to the time it is received). This resistance to delays is due to BLAST’s slid-ing-window design.

The size of a window is the number of packets that can be sent to the remote computer without BLAST’s having to wait for an acknowl-edgement from the remote. As the remote computer sends acknowl-edgements, the window slides so that more packets can be sent. For example, if the window size is set to 16, and the first 4 of 12 packets sent have been acknowledged, the window slides to allow 8 more packets to be sent. In this way, a continuous stream of packets can be sent without BLAST’s having to wait for an acknowlegement. The window size and frequency at which acknowledgements are re-quested can be specified by the user.

These two features—simultaneous bi-directional transfer and slid-ing-window design—combine to make BLAST a great time saver for long-distance callers. For example, BLAST can upload daily production figures to a host computer over a noisy telephone line at the same time that it downloads the next day’s production quotas.

CRC Error DetectionBLAST protocol uses the industry-standard CCITT CRC-16 tech-nique for detecting altered data packets. This is the same method used in IBM SNA/SDLC networks and X.25 packet-switching net-works.


Optimized AcknowledgementsWhen packets of data are transmitted, they must be acknowledged by the receiving computer so that the sender knows that the transfer is complete and accurate. When data is being transmitted in only one direction, the BLAST protocol uses a minimal number of acknowl-edgement packets flowing in the opposite direction. When data is being transferred in both directions, the data and acknowledgement packets are combined into a single packet. This efficient use of pack-ets is important when working with networks because network charges are often computed on a per-packet rather than a per-byte basis.

Adjustable Packet SizeThe BLAST packet size can be set from 1 to 4085 bytes according to the quality and type of connection. A small size minimizes the amount of data that must be retransmitted if line noise is a problem. With high quality connections or with error-detecting modems, packet size can be increased to reduce transmission overhead. Pack-et size can also be set to optimize network packet utilization.

BLAST Protocol Circuit RequirementsBLAST is flexible in its circuit requirements. Because BLAST does not use any of the ASCII control codes, it is compatible with the use of these control codes for other purposes. For example, BLAST can be employed on circuits where software flow control (CTRL Q/CTRL S) is in use. The XON/XOFF Pacing setup field allows the user to con-trol whether or not BLAST uses this feature. This is very important for load sharing on network virtual circuits and time-shared mini-computers.

BLAST can operate on 7-bit or 8-bit circuits. 7-bit operation allows BLAST to communicate with parity. This does not inhibit BLAST’s ability to transmit binary data—you may transfer either 7- or 8-bit data over both 7- and 8-bit circuits.

When using BLAST to communicate with computers that require 7-bit circuits, the setup parameter 7-Bit Channel must be set to YES. This setting slows the throughput of the transfer.

102 CHAPTER SIX

Starting a BLAST Session

Starting BLAST on a Multi-User SystemThere are three ways to start a BLAST Session on a remote multi-user computer. Note that you should already be logged into the re-mote system and appropriate directory.

Manual Method

◊ Select Terminal from the Online menu.

◊ Type the appropriate commands to the remote computer to start a BLAST session. For UNIX, this would be:

blast -h

at the command line.

◊ You should see either one of two messages from the remote:

;starting BLAST protocol.

or

ppp... (only for earlier versions of BLAST)

After the message appears, press ATTN ATTN to exit Terminal mode; then select Filetransfer from the Online menu.

Interactive Automatic Method

Select Filetransfer from the Online menu. Your system will auto-matically start the BLAST session on the remote system.

NOTE: The type of multi-user remote operating system must be identified in the System Type setup field for this method to work. BLAST will then know which automation information to retrieve from the systems.scr library program.

BLASTscript Automatic Method

◊ Write a BLAST script that includes the FILETRANSFER state-ment. This script can be executed from the command line or the Online menu.

◊ FILETRANSFER starts a BLAST Session on the remote sys-tem and initiates the BLAST Session locally.


NOTE: The type of multi-user remote operating system must be identified in the System Type setup field for this method to work. BLAST will then know which automation information to retrieve from the systems.scr library program.

Starting BLAST on a PC or Other Single-User ComputerIf the remote computer is a single-user system, such as a PC, you may start the BLAST Session in one of three ways:

Assisted Method

◊ Select Connect from the Online menu.

◊ Select Filetransfer from the Online menu.

◊ Have the operator on the remote machine select Filetransfer from the BLAST menu.

After the session has started, you can control both BLAST sessions from your keyboard; therefore, the remote operator is no longer nec-essary. In order for you to be able to complete all transfers and end the session without remote assistance, however, the remote operator must press CANCEL before leaving so that the remote system will terminate the session on your command.

Unattended Method

◊ Run the BLAST script slave.scr (found on your distribution me-dia) on the remote system. This script places the remote in “slave” mode, waiting for incoming calls.

◊ Select the Online menu Connect command.

◊ When connected, you have ten seconds to select Filetransfer from the Online menu. If Filetransfer is not selected within this time, the slave assumes the call is not for BLAST, hangs up the modem, and resets for the next call. When the remote receives your Filetransfer command, it automatically initiates the BLAST Session.

BHOST

◊ Run BHOST on the remote system if the remote system is a PC running DOS. BHOST occupies less than 100K of RAM and performs file transfers in background mode.

◊ After establishing a connection with the BHOST machine (see “Connecting to the Host PC” on page 324), select Filetransfer

104 CHAPTER SIX

from the Online menu. BHOST will automatically complete the protocol link.

Automatic Filetransfer HandshakingWhile entering Filetransfer mode, the two computers will communi-cate for a few seconds on their own—they will “shake hands” by ex-changing information. During handshaking, your system will:

◊ Send its BLAST version and type to be displayed and logged at the other end.

◊ Exchange filetransfer and communication parameters with the remote computer and adjust itself to the other machine’s lowest setup values. For instance, if your setup specifies a Packet Size of 256 bytes and the remote computer is set to 2048, then the lower value of 256 will be used.

◊ Display the Filetransfer menu and an initial assessment of com-munication line quality.

This process can fail if it does not occur within the time period spec-ified in the Logon Timeout setup field. If handshaking fails, BLAST displays “Logon Timeout” and returns to the Online menu.

BLAST Protocol TimeoutsThere are two types of timeouts in BLAST protocol: the Logon Timeout and the Inactivity Timeout. Both timeout values can be specified in fields in the BLAST Protocol Setup (see page 84).

The Logon Timeout is the maximum time in seconds after initiating the BLAST Session protocol that BLAST will wait for the initial handshake with another system. The default value is 120. If a Logon Timeout exists and the maximum time specified to establish the BLAST Session elapses, BLAST will return to the Online menu.

If the Logon Timeout is set to 0, the timeout is disabled. Setting the Logon Timeout to 0 at the remote site could “lock up” the remote system; however, BLAST allows you to force a disconnect by fol-lowing these steps:

◊ Select the Terminal command to enter Terminal mode.

◊ When you see the BLAST message

;starting BLAST protocol.


on the display, type:

;DISC.

This tells BLAST on the remote system to abort its attempt to enter a BLAST session. Because the message you type will not be echoed on the screen, repeat it several times if necessary. Note that the com-mand is case-sensitive.

The Inactivity Timeout is the maximum time in seconds allowed be-tween the transmission of valid BLAST protocol transfer packets. The default is 120 seconds. If BLAST times out, it will return to the Online menu. A setting of 0 disables the timeout.

NOTE: Using the Local menu during a file transfer suspends trans-fer activity, causing Filetransfer mode to terminate if the Inactivity Timeout interval is exceeded.

Ending a BLAST Session

The BLAST Session can be terminated in one of four ways:

Normal Menu EscapePress CANCEL at the Filetransfer menu or include an ESC statement in a BLAST script to end a filetransfer session.

◊ The files queued for transmission and the files currently being processed complete transmission normally.

◊ The computers complete an exit handshake, and display normal end messages.

◊ Control passes to the Online menu or to the BLASTscript state-ment following the ESC.

NOTE: For completion of the exit handshake, the remote operator must have pressed CANCEL unless the remote system is in host mode or is running a script with an ESC statement, in which case the re-mote system will automatically recognize your command.

Single-Attention AbortPress the ATTN key once to quit an interactive transfer or to abort a BLAST script performing a file transfer.

106 CHAPTER SIX

◊ The files queued for transmission will not be sent, and the file currently being transmitted will be marked on the receiving side as interrupted.

◊ The computers complete an exit handshake and display normal end messages.

◊ Control passes to the Online menu or to the BLAST script.

Double-Attention AbortPress the ATTN key twice to quit immediately.

◊ The files queued for transmission will not be sent, and the file currently being transmitted will be marked on the receiving side as interrupted.

◊ The computers do not complete an exit handshake.

◊ The remote is left to time out on its own. You may force a dis-connect by typing ;DISC. as described earlier.

◊ Control passes to the Online menu or to the BLAST script.

Timeout AbortIf a communications failure causes a timeout, the phone is discon-nected, or no activity takes place, both computers send an exit hand-shake when the timeout value is reached.

Performing Filetransfer Commands

Filetransfer MenuAfter the handshaking is completed, BLAST will display the Trans-fer Status Area and the Filetransfer menu (Figure 6-1 below).

FIGURE 6-1


The basic functions of a filetransfer session are controlled by the fol-lowing menu commands:

Send – Sends a file or files to the remote system.

Get – Receives a file or files from the remote system.

Message – Sends a text message of up to 67 characters in length to the remote operator. Simply type the message and press ENTER. The message will be queued for transmission to the remote display following completion of other pend-ing filetransfer commands.

Remote – Performs remote system commands. This option is simi-lar to the Local command but offers limited access to the remote computer. See “BLAST Protocol Remote Menu” on page 118 for more detailed information.

Local – Performs local system commands. This is identical to the Local command available from the Offline and Online menus. See “The Local Menu” on page 58 and the note con-cerning the Local menu and the Inactivity Timeout under the section “BLAST Protocol Timeouts” on page 105.

File – Executes a transfer command file that can control an entirefiletransfer session unattended (see “Transfer Command File” on page 115). This command is valid only for transfers using the BLAST protocol.

Transfer OptionsThree transfer options can be used in file transfers via the Filetrans-fer menu command or a BLASTscript FILETRANSFER statement:

t specifies text translation from the local file format to the desti-nation system’s text file format. This switch should only be used with ASCII files—do not send binary files using the t option.

o causes the transmitted file to overwrite an existing file with the same name on the receiving system. This will result in the de-struction of the original file on the receiving system, so use this option with caution. An error will result if this option is not used and the file already exists on the receiving system.

a appends the transmitted file to the end of an existing file with the same name on the receiving system. If the file does not exist on the receiving system, it will be created.

108 CHAPTER SIX

When using the Filetransfer menu command, you are prompted to type one or more of these letters (t, o, or a) to specify your transfer option(s). In a BLAST script, type the letter(s) on a separate line fol-lowing the name of the file or files to be transferred. For more on us-ing transfer options in a BLAST script, see “Getting and Sending Files” on page 194.

Sending a FileTo send a file,

◊ First, select Send from the Filetransfer menu.

S

◊ At the prompt:


enter a single filename from the current directory or a path spec-ification with a single filename; you may use wildcards (see the section “Wildcards” on the next page) and file transfer switches (see “File Transfer Switches” on page 111). After doing so, press ENTER.

◊ At the prompt:


Press ENTER only, type a single filename, or type a “%”, and any optional switches.

By default, BLAST will enter the filename (and path, if speci-fied) as you typed it at the local filename prompt. Pressing ENTER only will transfer the file to the remote system, using the local filename (and path if included with the local filename). Typing a different filename (and path, if necessary) will rename the file when it is created on the remote system. See “File Trans-fer Templates Using the ‘%’ Character” on page 110 for an ex-planation of “%”.

Some remote computers will interpret optional file transfer switches sent with the remote filename as file-handling and file-attribute controls. After specifying a remote filename, if any, press ENTER.

◊ At the prompt:


specify transfer options: (t=text, o=overwrite, a=append):

Type any combination of the letters t, o, and a or press ENTER

only to specify no options. For a fuller description of transfer options, see the preceding section, “Transfer Options.”

If you do not specify any options, the file will be transferred to the remote system byte-for-byte as a binary file. If the file exists on the remote system, the transfer will abort.

After specifying options, press ENTER; you will be returned to the Filetransfer menu, and the transfer will begin. The number of bytes sent will appear, as well as a percentage estimate of the amount of data transferred. When the file transfer completes, a message will be sent to your system.

Getting a FileReceiving a file differs only slightly from sending a file. Press G from the Filetransfer menu. You will be prompted for the remote filename first. Any switches added to the end of the remote filename must be valid for that operating system.

WildcardsBy using the wildcard characters “*” and “?”, you can transfer mul-tiple source files with similar names. The source files must reside in the same directory and path. The wildcard specifications are as fol-lows:

? Substitutes for a single character.

* Substitutes for multiple characters.

File Transfer Templates Using the “%” CharacterWhen a “%” is entered in the filename field for the target drive, file-name(s) from the source drive are transferred to the target drive without the source drive path specification(s).

IMPORTANT: “%” is REQUIRED for the target filename when the source filename contains a “?” or an “*” or when the source filename includes a path and the target filename does not (that is, the target directory is the current working directory).

Some examples are:

110 CHAPTER SIX

Source Name Target Name Resulttest1.asc C:\test1.asc one file in the current source

directory, sent to the target (DOS) directory C:\

/tst/test1.asc % one file in the source directo-ry /tst, sent to the current tar-get directory

/tst/test1.asc /tst/test1.asc one file in the source directo-ry/tst, sent to the target direc-tory /tst (/tst must exist in the current target directory)

test?.asc % multiple files in the current source directory—for exam-ple, test1.asc, test2.asc, and test3.asc—sent to the current target directory, retaining their source names

test1.* % multiple files in the current source directory—for exam-ple, test1.asc, test1.lst, and test1.txt—sent to the current target directory, retaining their source names

* /bin/% all files in the current source directory sent to the target di-rectory/bin/, retaining their source names.

File Transfer SwitchesInstead of specifying transfer options at the prompt, you can append the appropriate file transfer switches to both the local and remote filename specifications. Some remote computers will recognize switches sent with the remote filename as file-handling and file-attribute controls. Experiment with the transfer switches until you obtain the correct results. The valid switches are:

/APP Append to a file with the same name, if it exists.

/COMP=n Switch compression level value from the value in the compression field of the setup. Use the /COMP=n switch at the end of the filename where


n equals the level of compression (0–6). Setting the level to 0 turns off compression.

/FOLLOW=nn Allow data to be transferred from files to which data is being continuously or periodically append-ed. The /FOLLOW switch is appended to the local filename if being sent, or to the remote filename if being received.

/FWD Delete file from sending system if the transfer was successful. The /FWD switch is disabled by de-fault. To enable it, toggle the Enable /FWD and /STR setup field (page 88) in the BLAST Protocol subwindow to YES. For the /FWD switch to work, it must be enabled on the sending system.

NOTE: The /FWD switch is a very powerful fea-ture of BLAST. Because it allows files to be auto-matically deleted from the sending system, always exercise caution when using it.

/GROUP=nn Preserve or set the group of the file where nn is an positive decimal integer that specifies the file group ID.

/OVW Overwrite a file with the same name if it exists. The ability to use the /OVW switch is enabled by

10.7x

For /FOLLOW=nn, nn specifies the amount of time in seconds that BLAST will wait before checking for an end-of-file marker when trans-ferring a file that is being continuously updated.

When /FOLLOW is used and BLAST detects an end-of-file marker for the file being transferred, the file’s creation date and time are examined to see if they are set to the operating system’s cre-ation date and time. If so, BLAST will wait for the /FOLLOW timeout value before attempting to read the file again. If the date and time are set to any other valid date and time, normal end-of-file processing will occur.

10.8xBLAST will transfer additions to the file as they occur until nn seconds have elapsed from the last addition to the file.

112 CHAPTER SIX

default. To disable use of it, toggle the Enable /OVW and Remote Cmds setup field (page 88) in the BLAST Protocol subwindow to NO.

NOTE: If use of the /OVW switch is disabled on the receiving system, BLAST protocol will not al-low the file to be overwritten.

/OWNER=nn Preserve or set the owner of the file, where nn is a positive decimal integer that specifies the file owner ID.

/PERMS=nnnn Preserve or set file permissions where nnnn is an octal number that contains the file permissions for the target file. This switch is automatically ap-pended to files sent from the local system and can also be specified by the remote system. See “Per-missions” on page 150 and your system documen-tation for more information about permissions.

4000 Set user ID on execution20#0 Set user ID on execution if “#” is 7, 5, 3,

or 1 (grant execute permission); enable mandatory locking if “#” is 6, 4, 2, or 0.

1000 Set the sticky bit 0400 Read by owner0200 Write by owner0100 Execute (search in directory) by owner0040 Read by group0020 Write by group0010 Execute (search in directory) by group0004 Read by others0002 Write by others0001 Execute (search in directory) by others0000 No permissions

If the account on the receiving system does not have all of the necessary permissions to create the file as specified by this switch, BLAST will create the file with as many permissions as the account allows.

/STR Delete file from receiving system if transfer was unsuccessful. The /STR switch is disabled by de-fault. To enable it, toggle the Enable /FWD and /STR setup field (page 88) in the BLAST Protocol subwindow to YES on the receiving system.


/TXT Perform text translation. BLAST will convert car-riage returns, line feeds, and end-of-file markers to the receiving system’s text format.

You might, for example, specify text translation and overwriting of an existing file with the following filename:

test1.doc/TXT/OVW

Or you might specify that the file will be automatically deleted from your system after it has been successfully sent and that it will be sent with a compression level of 6:

test1.doc/FWD/COMP=6

Filenames Restrictions with BLAST ProtocolWith BLAST protocol, you should not give a file the same name as a switch since BLAST protocol will assume that the file is a switch and look for a file with the name of the folder containing the file. Thus, the transfer of the file will not occur and you will get an error message. Filenames (uppercase or lowercase) to avoid are: app, comp=n, follow=nn, fwd, group, ovw, owner=nn, perms=nnnn, str, and txt (where n is a number from 0 to 9).

You can work around this restriction by changing your local and re-mote working directories to the ones containing the file you want to transfer and giving the filename without a path. To change your lo-cal working directory interactively, choose Chdir command from the Local menu. To change your remote working directory interac-tively, choose the Chdir command from the Remote menu.

Alternatively, you may do a scripting workaround:

FILETRANSFERLCHDIR "/u/Pat/work" # Change local directoryREMOTE Chdir # Change working directory /usr/customer # Name of new directory ESCSENDApp # Filename only--no path;retain file-

# name on remote;no transfer options

ESC

114 CHAPTER SIX

If, on the receiving system, you give the file a new name that is not that of a switch, you can give a path. For instance, if in the script above, App was given the new name Sales.txt on the receiving ma-chine, you could change the script to the following:

FILETRANSFERLCHDIR "/u/Pat/work" # Change local directorySendApp # Filename only--no path/usr/customer/Sales.txt # Give new name and full path

Esc

Restarting an Interrupted File TransferDisconnections and interruptions in sending long files can be costly and time-consuming. BLAST can restart transfer of files from the point of interruption without having to restart transmission from the beginning of the file.

If a filetransfer session is interrupted and you wish to restart from the point of interruption, both local and remote systems must time out or be interrupted by ATTN ATTN. After the session has been interrupt-ed or aborted, you may restart the session by following these steps:

◊ Reconnect, if necessary, and restart the filetransfer session.

◊ Send the EXACT file that was being sent when interrupted.

◊ Do NOT indicate the overwrite or append options.

BLAST restarts from the last point at which its buffers were flushed to disk. This may be right at the interrupt point or as much as 10K before the interrupt point.

NOTE: Adding the /STR switch to a filename eliminates the possi-bility of resuming an interrupted transfer of that file.

Transfer Command File

A transfer command file is a text file that contains line-by-line in-structions describing functions to be performed during a BLAST protocol filetransfer session. Any word processor or editor can cre-ate a transfer command file, but it must be saved in text only or


ASCII format under any name that you choose. Transfer command files are also called error-free command files.

A transfer command file can be invoked interactively by selecting the File command from the Filetransfer menu, or from within a BLAST script by using the following BLASTscript commands:

FILETRANSFERFILEFilename # name of the transfer command fileESC

If the transfer command file is in the current directory, you only have to specify the filename; if it is in any other directory, you must spec-ify the full path.

The command file contains an unlimited number of commands, each as a separate line of text. Files, messages, and remote system com-mands can be sent and remote files can be received. Filetransfer commands are entered as one line, with the source and destination specifiers separated by a space. If any file transfer switches are re-quired, they are entered following the file specifier(s).

Command FormatsThe text in a transfer command file must begin in the first column of every line. Commands in a transfer command file accomplish one of four tasks:

1) Send a File:

No special character is required; simply type the name of the lo-cal file to send and, separated by a space, the name for the file on the remote system. If no remote name is given, BLAST will use the local name. Any file transfer switches must be typed im-mediately following the filename:

local_filename[switches] [remote_filename[switches]]

2) Get a File:

The first character in the line must be a plus sign (+). Immedi-ately following the “+”, enter the name of the file to receive from the remote system and, with no intervening space, any file transfer switches. If a different name is desired for the local file, type a single space after the remote filename and then type the local filename with any switches immediately following:

116 CHAPTER SIX

+remote_filename[switches] [local_filename[switches]]

Note that it is more efficient to put all Gets (lines beginning with “+”) first, so that the remote file requests queue up on the re-mote. This allows for true bi-directional transfer during com-mand file operations.

3) Send a Display Message:

The first character in the line must be a semicolon (;). Immedi-ately following the semicolon, type the desired message, which will be transmitted to the remote display and the remote log.

;Now Sending Sales Reports

4) Send a Command to the Remote System:

The character in the first column must be an exclamation point (!). Immediately following the exclamation point, type one of the following commands:

!dir

The valid remote operating system commands are:

DIRDisplay the contents of the current remote directory.

TYPE filenameType the contents of the specified remote file to the screen.

CDisplay the next page of a multi-page display.

PRINT filenamePrint the specified file on the remote printer.

REN oldname newnameRename the specified remote file to the new name.

ERA filenameErase the specified remote file.

CHDIR pathChange from the current remote directory to the specified re-mote directory.


ExampleTo understand the use of transfer command files, imagine that a salesman named Joe is using BLAST to keep track of current pricing changes and to send in current orders. He will always get the file called curprice.fil and send the file called joeorder.fil. Joe can create an error-free command file named joe.cmd, which looks like this:

;I want to get current price lists+curprice.fil/txt joeprice.fil/txt/ovw;Now I am about to send in today's ordersjoeorder.fil/txt todayord.fil/txt/ovw!dir

To use this command file, Joe would choose File from the Filetrans-fer menu and type in the name joe.cmd at the prompt. The following sequence of events then takes place:

◊ The first message in the command file appears on the screen.

◊ The file curprice.fil is retrieved and overwrites the old joeprice.fil.

◊ The second message appears.

◊ Joeorder.fil is sent and overwrites the old todayord.fil.

◊ Finally, the contents of the current directory of the remote com-puter are displayed on Joe’s screen.

BLAST Protocol Remote Menu

The Filetransfer menu contains a Remote command that takes you to the Remote menu. The Remote menu allows a user with no knowledge of the remote operating system to manage files on that system. For example, a UNIX user can delete a file on a VMS re-mote system without actually typing theVMS delete command. BLAST will “translate” the command automatically. Remote com-mands affect only files in the current remote directory unless you specify a pathname.

NOTE: The Enable /OVW and Remote Cmds setup field (page 88) in the BLAST protocol subwindow must be enabled on the re-mote system in order for you to delete, rename, or print files on the remote system.

118 CHAPTER SIX

Following is a description Remote menu commands:

List – Operates like the Local List command, except that it displays the contents of the current remote directory. You will be prompted to choose either a detailed (long) or non-detailed (short) list and then to specify a filename; you may use a spe-cific filename, a filename with wildcard characters (for exam-ple, “*”), or press ENTER to display all files in the current remote directory.

Delete – Deletes a single file or multiple files from the remote sys-tem. You may use a specific filename or a filename with wildcard characters (for example, “*”).

Rename – Renames a remote file.

Type – Displays a remote file on the BLAST screen.

Print – Prints a remote file to the remote printer.

Chdir – Changes the current remote directory to one that you name. BLAST will check this directory for any files that you spec-ify with the Remote menu commands.

More – Scrolls a page of data when either the List or Type com-mands cause more than one full screen of data to be re-ceived. You will be prompted to execute the More command in order to see the remaining pages, one page at a time.

Automating the BLAST Session Protocol

The BLAST Session protocol can be fully automated through script-ing. For information on writing scripts using the BLAST protocol, see “File Transfers with BLAST Session Protocol” on page 194.

Fine-Tuning the BLAST Session Protocol

Packet SizeMost computers can process packets of 256 characters. Set the Pack-et Size setup field (page 90) to 256 or higher unless the phone line quality is poor. Small packet sizes reduce the number of bytes re-


quiring retransmission over noisy lines. Computers connected di-rectly by cables will benefit from a much larger packet size, such as 4085. In a BLAST script, the reserved variable for packet size, @PAKTSZ, can be set anytime before entering a filetransfer session.

Compression LevelsBLAST performs automatic data compression during file transfers with the BLAST protocol, reducing the number of characters sent and the transfer time.

Compression level is specified in BLAST Protocol subwindow set-up fields (pages 88 – 88). Possible values for Receive Compression Level and Send Compression Level are 0 (no compression) to 6. The default is 4, which provides the best performance for average-sized files. Compression can also be selected by the @RCOMP_LEV (receive) and @SCOMP_LEV (send) BLASTscript reserved vari-ables.

Data compression requires additional RAM during file transfers. The amount of RAM necessary varies with the compression level.

Compression Level 0 – Level 0 specifies that no compression will be used. Choose level 0 when your CPU is slow and the baud rate is high. In this situation, the overhead needed for compression can ac-tually increase transfer time.

IMPORTANT: Always use compression level 0 when transferring pre-compressed files.

Compression Level 1 – Use level 1 when your data has strings of duplicate characters. Such data could include row and column re-ports, which have many embedded blanks, and executable files with blocks of nulls. In some cases, compression level 1 improves perfor-mance over high-speed modems with hardware data compression enabled.

Compression Level 2 – Starting with level 2, compression requires more work by both computers. With a standard modem and two fast machines, however, levels 2–4 will save transmission time.

Compression Level 3 and 4 – Levels 3 and 4 of compression are most effective when a limited character set is used or there are rep-etitious patterns. Because spreadsheets and databases have many repetitious patterns and a limited character set, they are highly com-pressible.

120 CHAPTER SIX

Compression Level 5 and 6 – Levels 5 and 6 compression are most effective for very large files (above 500 K). On large files (above 500K), the receiving computer may notice a significant delay before the first block is received while the sending computer calculates maximum compression.

Filetransfer Security with BLAST Protocol

Disabling File Overwrites and Remote CommandsThe Enable /OVW and Remote Cmds setup field (page 88) and the script variable @ENABLERCMD (page 272) control whether or not remote commands and file overwrites are allowed during Filetrans-fer mode. Note that disabling /OVW affects only local files. For ex-ample, you will still be able to send a file with the /OVW switch because the file will be overwritten on the remote system.

Disabling the /FWD and /STR SwitchesThe Enable /FWD and /STR setup field (page 88) and the @ENABLEFS (page 271) script variable control whether or not the /FWD and /STR file transfer switches are allowed during Filetrans-fer mode. Note that disabling these switches affects only local files. For example, you will still be able to get a file with the /FWD switch because the successfully transferred file will be deleted from the re-mote system. See “File Transfer Switches” on page 111.

NOTE: Adding the /STR switch to a filename eliminates the possi-bility of resuming an interrupted transfer of that file.

Using the Transfer Password If you have limited a remote user’s access so that BLAST automat-ically run’s a specific BLAST setup when a user logs into your sys-tem (see “Limiting Access” on page 154), you can insure additional security by specifying a Transfer Password for that setup. Without the password, the remote user may only send and receive messages while in Filetransfer mode. The Transfer Password can be set by en-tering it into the Transfer Password setup field (page 87) or by set-ting the reserved variable @TRPASSWD (page 290) in a slave script on the remote system.

NOTE: The transfer password is superseded by the Secure BLAST password (see “Using Secure BLAST” on page 155).


After entering a filetransfer session, the remote user must send the transfer password to the host machine using the Send command from the Filetransfer menu or a FILETRANSFER statement in a script. If the user issues a Send command from the Filetransfer menu, the following special format for the local filename must be used:


where your_password represents the password stored on the host system. The remote filename field is left blank as are the text, overwrite, and append options. If the correct password is successful-ly sent, the remote user will see a message stating that the password has been validated. The password must be typed exactly as it is set on the host system!

If a BLAST script is used, the same special local filename format must be sent to the host computer, for example:

FILETRANSFERSEND!password=blue2

SENDmyfile.rptyourfile.rpttaESC

Because the remote filename and send transfer options are not used, two blank lines must follow the !password=your_password statement. See “Getting and Sending Files” on page 194 for infor-mation on scripting file transfers.

Since the remote user has to enter the password through BLAST in-teractively or through a script, the use of Transfer Password deters an unauthorized user from breaking your security by submitting a rapid series of passwords.

NOTE: The Transfer Password is intended to validate remote users logging onto your system. If a local operator uses a setup with a Transfer Password entered, he or she will not be able to receive files without the remote user sending the password.

122 CHAPTER SIX

Chapter 7

FTP with 10.8x

Introduction

BLAST includes FTP for transferring files with systems via TCP networks.

To choose FTP, select FTP from the Protocol setup field (page 84) or set the reserved variable @PROTOCOL (page 281) to FTP in a script.

Starting an FTP Session

If you have selected FTP as your protocol, choose Filetransfer from the Online menu—BLAST will automatically log into the remote system using the values from the Userid and Password setup fields.

FTP WITH 10.8X 123

FTP Filetransfer Menu

You will notice from the screen shown in Figure 7-1 below that the FTP Filetransfer menu is slightly different from the menu displayed during a BLAST protocol session. Following is a brief description of the command options of this menu:

Send – Sends a file to the remote system.

Get – Retrieves a file from the remote system.

Local – Performs local system commands. This command takes you to the Local menu. Note that all filetransfer activity is suspended while you are using the local system.

Remote – Performs remote system commands. This option allows a user with no specific knowledge of the remote operating system to manage remote files. For example, a user can delete a file without actually typing the delete command of the remote operating system (see “FTP Remote Menu” on page 128).

FIGURE 7-1

Sending and Receiving Files with FTP

The following two sections describe interactive file transfers. For a discussion of scripting FTP file transfers, see “File Transfers with FTP Using 10.8x” on page 197.

124 CHAPTER SEVEN

Sending Files with FTP To send a file,

◊ Select Send from the Filetransfer menu.

◊ At the prompt:


enter a filename from the current directory or a filename with a fullpath. You may use wildcards (see “Wildcards” on page 110) and any supported switches (see “File Transfer Switches with FTP” on page 126). After doing this, press ENTER.

◊ At the prompt:


Press ENTER only, type a single filename, or type a “%”, and any optional switches.

By default, FTP will enter the filename (and path, if specified) as you typed it at the Local Filename prompt. Pressing ENTER

only will transfer the file to the remote system using the local filename (and path if included with the local filename). Typing a different filename (and path, if necessary) will rename the file when it is created on the remote system. Alternatively, you may use a file transfer template using the “%” (see “File Transfer Templates Using the “%” Character” on page 110). For a list of supported switches, see “File Transfer Switches with FTP” on page 126.

When the FTP transfer completes, a message will be sent to your system and you will be returned to the Filetransfer menu.

Getting Files with FTPReceiving files with FTP differs only slightly from sending files.

◊ Press G from the Filetransfer menu.

◊ At the prompt, enter the remote filename or filename with full path; you may use wildcards (see “Wildcards” on page 110).

◊ At the prompt, enter the local filename, filename with full path, or file transfer template (see “File Transfer Templates Using the

FTP WITH 10.8X 125

“%” Character” on page 110), and any supported switches (see “File Transfer Switches with FTP” on page 126). When the FTP transfer completes, a message will be sent to your system and you will be returned to the Filetransfer menu.

NOTE: FTP GETs should be used with caution. In the FTP proto-col, the markers for end-of-file and for close-connection are the same. Thus, incomplete file receives resulting from connection fail-ures are reported as successful file transfers in both the File Transfer Status Area and the log file.

File Transfer Switches with FTP

FTP supports the file transfer switches listed below; all other file transfer switches are ignored by FTP:

/APP Append to a file with the same name if it exists. Without this switch, a file is automatically over-written.

/FWD Delete file from sending system if transfer was successful.

NOTE: The /FWD switch is a very powerful feature of FTP. Because it allows files to be auto-matically deleted from the sending system, al-ways exercise caution when using it.

/STR Delete file from receiving system if transfer was unsuccessful.

/TXT Perform text translation. BLAST will convert car-riage returns, line feeds, and end-of-file markers to the receiving system’s text format.

You might, for example, specify appending and text translation of an existing file with the following filename:

test1.doc/APP/TXT

126 CHAPTER SEVEN

Filenames Restrictions with FTP

With FTP, you should not give a file the same name as a switch since FTP will assume that the file is a switch and either ignore it (if the switch is unsupported by FTP) or look for a file with the name of the folder containing the file (if the switch is supported by FTP). In ei-ther case, the transfer of the file will not occur and you will get an error message. Filenames (uppercase or lowercase) to avoid are: app, comp=n, follow=nn, fwd, group, ovw, owner=nn, perms=nnnn, str, and txt (where n is a number from 0 to 9).

You can work around this restriction by changing your local and re-mote working directories to the ones containing the file you want to transfer and giving the filename without a path. To change your lo-cal working directory interactively, choose Chdir command from the Local menu. To change your remote working directory interac-tively, choose the Cwd command from the Remote menu.

Alternatively, you may do a scripting workaround:

FILETRANSFERLCHDIR "/u/Pat/work" # Change local directoryREMOTE Cwd # Change working dir /usr/customer # Name of new directory ESCSENDApp # Filename only--no path

ESC

If, on the receiving system, you give the file a new name that is not that of a switch, you can give a path. For instance, if in the script above, App was given the new name Sales.txt on the receiving ma-chine, you could change the script to the following:

FILETRANSFERLCHDIR "/u/Pat/work" # Change local directorySendApp # Filename only--no path/usr/customer/Sales.txt # Give new name and full pathEsc

FTP WITH 10.8X 127

Ending an FTP Session

FTP sessions end automatically when all specified files are trans-ferred and you press ESC.

FTP Remote Menu

The Remote menu allows a user with no knowledge of the remote operating system to do limited file management on the remote sys-tem. Following is a brief description of the three command options of the FTP Remote menu:

List – Operates like the Local List command, except that it displays the contents of the remote current directory. You will be prompted to choose either a detailed (long) or non-detailed (short) list and then to specify a filename, a filename using wildcard characters (see “Wildcards” on page 110), or all files.

Delete – Deletes a single file or multiple files from the remote sys-tem. You may use a specific filename or a filename with wildcard characters (for example, “*”).

Cwd – Changes the server’s working directory. You will be prompted for the new directory name.

128 CHAPTER SEVEN

Chapter 8

Kermit ProtocolMany communication products support Kermit protocol on a wide range of computers, but there are different versions of Kermit, two of which BLAST supports. The simplest version is a file transfer program that requires commands to be entered at both the sending and receiving computers (using the Send and Receive commands). The more sophisticated version is the Kermit server. The Kermit server accepts commands from a remote user and performs specified operations (using the Send, Get, and Remote commands).

Kermit Filetransfer Menu

You will notice from the screen shown in Figure 8-1 on the next page that the Kermit Filetransfer menu is slightly different from the menu displayed during a BLAST protocol session. Below is a brief description of the command options of this menu.

Send – Sends a file to a Kermit program. You will be prompted for the local and remote filenames.

Get –Receives a file from a Kermit server. You will be prompted for the remote and local filenames.

KERMIT PROTOCOL 129

FIGURE 8-1

Receive – Receives a file from a simple Kermit. You must specify a local filename.

Remote –Performs remote Kermit server commands. This option allows a user with no specific knowledge of the remote operating system to manage its files. For example, a user can delete a file without actually typing the delete com-mand of the remote operating system (see “Kermit Re-mote Menu” on page 134).

Finish – Returns you to the Online menu. Kermit server finishes transfer and exits without logging off; thus, you may con-tinue the session.

Bye – Ends Kermit server mode and logs off of the remote system. Depending on the remote modem settings, the connection may or may not be broken. You will be returned to the Online menu.

NOTE: Once you begin Kermit server, you can continue to do file transfers until you exit the server by selecting Finish or Bye from the Filetransfer menu.

Sending and Receiving Files with Kermit

The following two sections describe interactive file transfers. For a discussion of scripting Kermit file transfers, see “File Transfers with Kermit” on page 197.

130 CHAPTER EIGHT

Sending Files with KermitFollowing are directions for sending a file to a remote computer:

Kermit Server

◊ In Terminal mode, begin the Kermit program on the remote sys-tem.

◊ Exit Terminal mode, select the Filetransfer command from the Online menu, and then select the Send command. You will be prompted for the local and remote filenames. For the local file-name, you may enter a single filename from the current directo-ry or a path specification with a single filename. You may use wildcards (see “Wildcards” on page 110), but you cannot use file transfer switches.

◊ The transfer will begin, and the number of bytes sent will be dis-played in the File Transfer Status Area.

Simple Kermit

◊ In Terminal mode, begin the simple Kermit program on the re-mote system.

◊ In simple Kermit on the remote system, issue a receive com-mand.

◊ Exit Terminal mode, select Filetransfer, and then select Send. You will be prompted for local and remote filenames. If you designate a remote filename with the simple Kermit receive command, a filename entered at the remote filename prompt will be ignored.

Receiving Files with KermitBLAST’s implementation of Kermit supports both the Kermit server Get command and the simple Kermit Receive command to transfer files from a remote computer. Following are directions for transfers from a remote computer:

Kermit Server

◊ In Terminal mode, begin the Kermit server program on the re-mote system.

◊ Exit Terminal mode, select the Filetransfer command from the Online menu, and then select the Get command. You will first be prompted for the remote filename—you may enter a single filename from the current directory or a path specification with

KERMIT PROTOCOL 131

a single filename; you may include wildcards (see “Wildcards” on page 110). You will then be prompted for a local filename. Optionally, you may add any supported file transfer switches (see “File Transfer Switches with Kermit” on page 132). Once you have entered the filenames and any switches, the transfer request is automatically sent to the remote.

◊ Unless you specify otherwise, the received file will be saved to your current directory.

NOTE: If you have an existing file with the same name, the file will be renamed when the Warning setup field (page 92) is set to ON. When this field is set to OFF, the existing file will be automaticallyoverwritten.

Simple Kermit

◊ In Terminal mode, begin the simple Kermit program on the re-mote system.

◊ In Kermit on the remote system, send the file by invoking the send command.

◊ Exit Terminal mode, select Filetransfer, and then select Re-ceive. You will then be prompted for a local filename; option-ally, you may add any supported file transfer switches (see the next section “File Transfer Switches with Kermit”).

◊ Unless you specify otherwise, the received file will be saved to your current directory.

NOTE: If you have an existing file with the same name, the file will be renamed when the Warning setup field (page 92) is set to ON. When this field is set to OFF, the existing file will be automaticallyoverwritten.

File Transfer Switches with Kermit

Kermit ignores all file transfer switches on sending filenames and supports the following file transfer switches on receiving filenames:

/APP Append to a file with the same name if it exists.

/GROUP=nn Preserve or set the group of the file where nn is a positive decimal integer that specifies the file

132 CHAPTER EIGHT

group ID. Note that on some systems only the user root can change the group attribute.

/OVW Overwrite a file with the same name if it exists.

/OWNER=nn Preserve or set the owner of the file, where nn is a positive decimal integer that specifies the file owner ID. Note that on some systems only the user root can change the owner attribute.

/PERMS=nnnn Preserve or set file permissions where nnnn is an octal number that contains the original file per-missions. This switch is automatically appended to files sent from the local system and can also be specified by the remote system. See “Permis-sions” on page 150 and your system documenta-tion for more information about permissions.

4000 Set user ID on execution20#0 Set user ID on execution if “#” is 7, 5, 3,

or 1 (grant execute permission); enable mandatory locking if “#” is 6, 4, 2, or 0.

1000 Set the sticky bit 0400 Read by owner0200 Write by owner0100 Execute (search in directory) by owner0040 Read by group0020 Write by group0010 Execute (search in directory) by group0004 Read by others0002 Write by others0001 Execute (search in directory) by others0000 No permissions


Filenames Restrictions

With Kermit Protocol, you should not give a file the same name as a switch since BLAST will assume that the file is a switch and either ignore it (if the switch is unsupported by Kermit) or look for a file

KERMIT PROTOCOL 133

with the name of the folder containing the file (if the switch is sup-ported by Kermit). In either case, the transfer of the file will not oc-cur and you will get an error message. Filenames (uppercase or lowercase) to avoid are: app, comp=n, follow=nn, fwd, group, ovw, owner=nn, perms=nnnn, str, and txt (where n is a number from 0 to 9).

You may work around this restriction by changing your local current and remote current directory to the one containing the file you want to transfer and giving the filename without a path. To change your local working directory interactively, choose the Chdir command of the Local menu. To change your remote directory interactively using Kermit server, choose Remote from the Kermit Filetransfer menu and then select the Cwd (Change Working Directory) command. To change your remote directory interactively using simple Kermit, ac-cess Terminal mode and give the “change current directory” com-mand for that operating system.

Alternatively, you may do a scripting workaround. To change the lo-cal working directory, use the LCHDIR command. To change the re-mote working directory using the Kermit server, issue a FILETRANSFER/REMOTE/Cwd multi-line command statement. To change the remote working directory using simple Kermit or Kermit server, TSEND a “change working directory” command to the remote. For example, the following script fragment changes the current remote directory on a UNIX machine to /u/sales.

TSEND "cd /u/sales", CR

See “File Transfers with Kermit” on page 197 for more on scripting for Kermit.

Kermit Remote Menu

Notice that the Kermit Remote menu (Figure 8-2, next page) offers a selection of commands different than those of the BLAST proto-col. These functions operate on the remote system in Kermit server mode. Unreliable results can occur, however, if you use a command that is not directly supported by the server. The Remote menu com-mands are:

Directory – Displays the server’s current working directory or a directory you specify; wildcards can be used.

134 CHAPTER EIGHT

FIGURE 8-2

Erase –Deletes a file in the server’s current working directory or in a directory you specify by giving the full path of the file; wildcards can be used.

Type – Displays a remote file on your screen. Kermit does not sup-port a page pause, so you must use CTRL S to pause and CTRL

Q to resume the flow of text.

Cwd – Changes the server’s working directory. You will be prompted for the new directory name.

Space – Displays the server’s free drive space.

Who – Displays users currently logged onto the remote. If you specify a user name, information on that name only will ap-pear.

Message – Sends a one-line message to be displayed to the remote operator.

Host – Sends an operating system command to the remote. The command is executed immediately.

Kermit – Sends a Kermit language command to modify session pa-rameters, for example, SET FILE TYPE BINARY.

Help – Displays a short list of the commands currently available on the Kermit server. Because servers can support different commands, the Help command can be a valuable reminder of what is available through the Kermit server.

KERMIT PROTOCOL 135

The Kermit DISABLE command can lock most of these menu com-mands. For example, the command DISABLE ERASE will prevent files from being deleted on the remote system.

136 CHAPTER EIGHT

Chapter 9

Xmodem, Ymodem, and Zmodem Protocols

BLAST includes the public domain protocols Xmodem, Ymodem, and Zmodem for transferring files as an alternative to BLAST pro-tocol.

Before choosing Xmodem, Ymodem, or Zmodem for a major appli-cation, ask yourself:

◊ Will you need to transfer files with computers using other oper-ating systems?

◊ Do your transfers need to be fast and 100% error free?

◊ Do you want the ability to execute commands on the remote system without special knowledge of the command syntax?

If you have answered “Yes” to any of these questions, you should use BLAST protocol on your remote system if it is available; Xmo-dem, Ymodem, and Zmodem protocols do not support both near-transparent remote access to other operating systems nor fast, 100% error-free transfers.

XMODEM, YMODEM, AND ZMODEM PROTOCOLS 137

The following instructions are very general. Actual procedures for using Xmodem, Ymodem, and Zmodem will vary depending on the implementation of these protocols on the remote system. Many com-munications products support the standard implementation of these protocols; nevertheless, you should be aware that there are different, incompatible versions that might not work successfully with BLAST.

Command Line Features

If you have chosen the Xmodem or Ymodem protocol in your setup, you can specify an end-of-transmission (EOT) timeout parameter using a command line switch in the following format:

where timeout is equal to number/100 seconds. The minimum time-out is .1 second (10) and the maximum is 60 seconds (6000). For example, -y1111 or -e1111 sets the timeout to 11.11 seconds.

Invoking a command line parameter affects these protocols only for the duration of that communications session.

10.7x blast -ynumber

10.8x blast -enumber

10.8x

You can also select the pad character for Xmodem using the fol-lowing format:

blast -px

where x specifies the character expressed as a hexadecimal value. For example, -p21 specifies “21” as the pad character.

The -h command line switch may also be used for Xmodem, Ymo-dem, and Zmodem file transfers from a remote system not running BLAST. See “BLAST Operation as a Pseudohost With 10.8x” on page 204 for details.

138 CHAPTER NINE

Xmodem Protocol

BLAST supports Xmodem1K CRC as well as Xmodem CRC and the standard Xmodem checksum protocol. When you select Xmo-dem as your protocol, BLAST will automatically determine which implementation of Xmodem is on the remote system and choose the correct counterpart on your local system.

NOTE: Xmodem is only compatible with 8-bit connections.

The following two sections describe interactive file transfers. For a discussion of scripting Xmodem file transfers, see “File Transfers with Xmodem and Xmodem1K” on page 200.

Sending Files with XmodemTo send a file using Xmodem:

◊ In Terminal mode, begin the Xmodem or Xmodem1K receive program on the remote computer, specifying a filename if need-ed.

◊ Exit Terminal mode, select the Filetransfer command from the Online menu, and then select the Send command. You will be prompted for the local filename.

Receiving Files with XmodemTo receive a file using Xmodem:

◊ In Terminal mode, begin the Xmodem or Xmodem1K send pro-gram on the remote computer.

◊ Exit Terminal mode, select the Filetransfer command from the Online menu, and then select the Get command. You will be prompted for the filename. If the file already exists on the local machine, you will get an error message.

10.8x You may change your error-detection setting through the Error De-tection setup field (page 94) of the Xmodem protocol subwindow.

10.8x Optionally, you may add the /TXT file transfer switch (see “File Transfer Switches Using 10.8x with Xmodem” on page 140).


File Transfer Switches Using 10.8x with XmodemWith Professional UNIX 10.8x, Xmodem supports several file trans-fer switches; it ignores all switches that it does not support.

10.8x

Optionally, you may add any supported file transfer switches (see “File Transfer Switches Using 10.8x with Xmodem” on page 140). For example, you may overwrite an existing file (and avoid an er-ror message) by adding the /OVW switch to the local filename when prompted for the name.

File Transfer Switches for 10.8x Using Xmodem

/APP Receive Append to a file with same name if it exists.

/FWD Send Delete file from sending system if the transfer was successful.

/GROUP=nn Receive

Preserve or set the group of the file where nn is a positive decimal integer that specifies the file group ID. Note that on some systems only the user root can change the group attribute.

/OVW Receive Overwrite a file with same name if it exists.

/OWNER=nn Receive

Reserve or set the owner of the file, where nn is a positive decimal integer that specifies the file owner ID. Note that on some systems only the user root can change the owner attribute.

/PERMS=nnnn Receive

Preserve or set file permissions where nnnn is an octal number that contains the original file permissions. This switch is automatically ap-pended to files sent from the local system and can also be specified by the remote system. See “Permissions” on page 150 and your sys-tem documentation for more information about permissions

4000 Set user ID on execution 20#0 Set user ID on execution if “#” is 7, 5,

3, or 1 (grant execute permission); en-able mandatory locking if “#” is 6, 4, 2, or 0.

1000 Set the sticky bit 0400 Read by owner

140 CHAPTER NINE

Ymodem Protocol

BLAST supports the standard Ymodem and Ymodem G protocols. Do not use Ymodem G protocol unless there are properly configured error-correcting modems on both ends of the connection.

.The following two sections describe interactive file transfers. For a discussion of scripting Ymodem file transfers, see “File Transfers with Ymodem and Ymodem G” on page 201.

Sending Files with YmodemTo send a file using Ymodem:

◊ In Terminal mode, begin the Ymodem or Ymodem G receive program on the remote computer.

◊ Exit Terminal mode, select the Filetransfer command from the Online menu, and then select the Send command. You will be prompted for the filename. You may enter a single filename

0200 Write by owner 0100 Execute (search in directory) by owner 0040 Read by group0020 Write by group 0010 Execute (search in directory) by group 0004 Read by others0002 Write by others0001 Execute (search in directory) by others 0000 No permissions


/STR Receive Delete file from receiving system if transfer was unsuccessful.

/TXT

Send Send file as ASCII using the value stored in @XYRLTS.

Receive Receive file as ASCII using the value stored in @XYRLTR.


from the current directory or a path specification with a single filename; you may use wildcards (see “Wildcards” on page 110).

Receiving Files with YmodemTo receive a file using Ymodem:

◊ In Terminal mode, begin the Ymodem or Ymodem G send pro-gram on the remote computer.

◊ Exit Terminal mode, select the Filetransfer command from the Online menu, and then select the Get command. The transfer will begin immediately without prompting for a local filename.

File Transfer Switches Using 10.8x with YmodemWith Professional UNIX 10.8x, Ymodem cannot set switches on re-ceiving filenames and ignores all switches on sending filenames ex-cept the /TXT, which specifies that the file be sent as ASCII using the value stored in @XYRLTS (page 300), and the /FWD switch.

Zmodem Protocol

BLAST supports the standard Zmodem protocol in both single-file and batch modes. BLAST also supports a variety of special Zmodem features that can be activated through the setup fields of the Zmodem protocol subwindow (page 94).

The following two sections describe interactive file transfers. For a discussion of scripting Zmodem file transfers, see “File Transfers with Zmodem” on page 203.

Sending Files with ZmodemTo send a file using Zmodem:

◊ In Terminal mode, begin the Zmodem receive program on the remote computer

10.8xOptionally, you may add the /TXT file transfer switch. You will not be able to add any other file transfer switches (see “/TXT Switch Using 10.8x with Ymodem” below).

142 CHAPTER NINE

◊ Exit Terminal mode, select the Filetransfer command from the Online menu, and then select the Send command. You will be prompted for the filename. You may enter a single filename from the current directory or a path specification with a single filename; you may use wildcards (see “Wildcards” on page 110).

Receiving Files with ZmodemTo receive a file using Zmodem:

◊ In Terminal mode, begin the Zmodem send program on the re-mote computer.

◊ Exit Terminal mode, select the Filetransfer command from the Online menu, and then select the Get command. The transfer will begin immediately without prompting for a local filename.

NOTE: If the Auto Receive setup field (@ZMAUTODOWN) is set to YES, you do not have to select the Get command; Zmodem transfers the file automatically when you enter Filetransfer mode.

File Transfer Switches Using 10.8x with ZmodemWith Professional UNIX 10.8x, Zmodem supports several file trans-fer switches for sending filenames (see table below). Zmodem can-not set switches on receiving filenames and ignores all unsupported switches.

10.8x Optionally, you may add supported file transfer switches (see “File Transfer Switches Using 10.8x with Zmodem” below).

File Transfer Switches for 10.8x Using Zmodem

/APP Send Specify APPEND as File Management option.

/OVW Send Specify CLOBBER as File Management op-tion.

/TXT Send Send file as ASCII with value stored in @ZMALT.


Filenames Restrictions

With Xmodem, Ymodem, and Zmodem, you should not give a file the same name as a switch since BLAST will assume that the file is a switch and either ignore it (if the switch is unsupported by the cur-rent protocol) or look for a file with the name of the folder contain-ing the file (if the switch is supported by the current protocol). In either case, the transfer of the file will not occur and you will get an error message. Filenames (uppercase or lowercase) to avoid are: app, comp=n, follow=nn, fwd, group, ovw, owner=nn, perms=nnnn, str, and txt (where n is a number from 0 to 9).

You may work around this restriction by changing your local current or remote current directory to the one containing the file you want to transfer and giving the filename without a path. For interactive sends, change your local working directory by accessing the Local menu and choosing the Chdir command. For interactive gets, change your remote working directory by accessing Terminal mode and giving the “change current directory” command for that operating system.

Alternatively, you may do a scripting workaround. For SENDs, change the local working directory by using the LCHDIR command. For GETs, TSEND a “change working directory” command for that operating system. For example, the following script fragment will change the current remote directory on a UNIX machine to /u/sales.

TSEND "cd /u/sales", CR

144 CHAPTER NINE

Chapter 10

Text Transfers

Introduction

In BLAST session protocol, you may transfer text directly to and from a remote computer using the respective Online commands Up-load and Capture.

Uploading Text to a Remote Computer

Uploading is the process of sending text from your system to a re-mote computer. When you upload, the text being uploaded will dis-play on your screen. The receiving computer does not need to be running BLAST, but it must have a program capable of capturing text and responding to flow control.

Because there is no error detection, characters may be dropped or noise may change the characters in the data stream. The following setup fields, however, can assist in regulating the flow of data during text uploads to help prevent the receiving computer from losing characters: Wait for Echo, Prompt Char, Char Delay, and Line De-lay. See Chapter 5 for details on using these functions.

TEXT TRANSFERS 145

After you have connected, there are three ways to start the upload process with another system:

Manual Method◊ Select Terminal from the Online menu.

◊ Type the appropriate commands for the remote computer to start a text capture program. On a UNIX system, for example, you might type:

vi remote.fil

which instructs vi to open a new file named remote.fil. You can then use the a command to tell vi to append the uploaded text to remote.fil. Note that an entry is not required in the System Type setup field for this method.

◊ When the remote capture program is ready, press ATTN ATTN to exit Terminal mode and then select Upload from the Online menu. Specify the desired local filename, but not a remote file-name.

◊ After the upload is completed, you will be returned to Terminal mode. Save the file containing the newly captured text, specify-ing a name if you have not already done so on the command line, and then quit the capture program.

Interactive Automatic MethodSelect the Upload command from the Online menu. You must spec-ify both the local and remote filenames. Your computer will auto-matically send the file to the remote system, if text capture is supported by that system.

NOTE: The remote computer type must be entered in the System Type setup field for this method to work because BLAST uses the system.scr library to automate the process. BLAST will start the re-mote text capture program for you.

BLASTscript Automatic MethodSee “Text Transfers” on page 207 for details on scripting uploads.

146 CHAPTER TEN

Downloading Text from a Remote Computer

Downloading is the process of capturing text sent from another sys-tem to your computer. When you capture text from a remote com-puter, the text being downloaded will display on your screen. The sending computer does not need to be running BLAST, but it must have a program capable of sending text and responding to flow con-trol. If flow control is specified in the setup, BLAST will pause transmission for a few moments when the buffers are full. After con-necting, there are two ways to start the download process:

Manual Method◊ Select the Capture command from the Online menu and specify

the desired filename for the capture file.

◊ Select Terminal from the Online menu. Type the appropriate command for the remote computer to start typing the text. For example, at the “$” prompt of a UNIX system, you might type:

cat test.fil

◊ When the download has completed, press ATTN ATTN to exit Terminal mode. Turn Capture off by selecting it again.

BLASTscript Automatic MethodSee “Text Transfers” on page 207 for details on scripting down-loads.

TEXT TRANSFERS 147

148 CHAPTER TEN

Chapter 11

Secure BLAST

Securing Your System

Securing your system against intrusion is a complex task. “Secure BLAST” is a security tool that provides access for authorized users only. Before discussing the BLAST security utilities in detail, we will examine standard UNIX methods of security.

IMPORTANT: There are many tools for securing a UNIX system, but none of them are foolproof. At best, they will significantly reduce the risk that well-intentioned people will inadvertently access restricted data. These mechanisms will not safeguard your data against a systematic, continuous attempt to “hack” your computer. For more detailed in-formation on system security, please refer to your system documen-tation or any of the excellent references available concerning UNIX security.

SECURE BLAST 149

UNIX Tools

LoginThe front line of defense against unwanted intrusion is a properly configured getty or ttymon process running on all dial-in lines. At a minimum, this will force the dial-in user to enter a valid login name and password (or attempt to hack the login process) to gain ac-cess. Presuming that the user provides a valid login and password combination, login will start a shell, set the group to which the user belongs, and put the user into his or her home directory. The default shell, group ID, and home directory are all specified in the /etc/passwd file.

To maintain security, each person logging into your UNIX system should have his or her own login and home directory. If logins and home directories are shared, it is impossible to limit directory access only to one user. For more information on setting up logins, refer to your system documentation.

GroupsEach user on the system will belong to one or more groups. Segre-gating users into groups can help secure your system. For more in-formation on setting up groups, refer to your system documentation and the group, newgrp, and chgrp man pages.

PermissionsThe basic operations performed on a file are “read,” “write,” and, for executable files, “execute.” The system can grant or deny access to a file for any of these operations. Read, write, and execute permis-sion can be set for the owner of the file, for users in a particular group, and for all other users on the system.

When you list the files in a directory, the permissions assigned to each file appear as a series of letters. “Read,” “write,” and “execute” are denoted by the mnemonics “r”, “w”, and “x.” The permissions indicator can contain up to 10 characters, but not every space will necessarily contain a letter. You should think of the permissions in-dicator as a single initial character plus three groups of three charac-ters. For example, “-rwxr--r--” should be interpreted as:

Owner Group Others- {rwx} {r--} {r--}

150 CHAPTER ELEVEN

The owner of the file has all three permissions, users in a particular group have only read permission, and all other users have only read permission. If the file is a directory, the initial character will be a “d”. Other specifiers for the initial character and other file permis-sions exist as well but are beyond the scope of this discussion.

As a general rule, set default permissions for newly created files as restrictively as possible. The tool for setting default permissions is umask, discussed later in this section. If the owner of a file wants to allow expanded access to his files later, he can manually reset the permissions using the chmod command. For more information on changing file permissions, please refer to the chmod man page.

Another parameter that affects permissions is the set-uid bit, which allows a program file to execute with the permissions of its owner rather than the permissions of the user running the program. For more information on the set-uid bit, see your system documentation.

DirectoriesTo the UNIX operating system, a directory is just a file. The same read, write, and execute permissions apply to directories; however, interpretation of execute permission is different. If a directory has execute permission, it is possible to search the directory. As a gen-eral rule, a user’s home directory should have read, write, and exe-cute permission for the owner only. This will allow the owner of the directory complete access to his or her files but disallow access to all others.

umaskThe umask (user mask) tool is used to establish default permissions when a file is created. If umask has never been set, the operating system will create a set of default permissions, but you should exam-ine them carefully. It is important that you use umask to set default permissions as restrictively as possible while still allowing neces-sary access to your files. You can use umask to set permissions per-manently or to change them for a particular shell session.

Permissions can be denoted both mnemonically and numerically (see table on the next page), where the mnemonic indicates what is permissible, and the numeric indicates what is not permissible.

Permission Mnemonic NumericRead r 4Write w 2Execute x 1

SECURE BLAST 151

Permissions are restricted according to the numeric values specified in the umask. For example, to deny write access, the umask should have a “2” in it. Numeric values are added together to express the to-tal restriction of permissions set for an owner, group, or others. For example, denial of read, write, and execute permissions is denoted by the number “7”. Conversely, read, write, and execute permission is denoted by a “0”.

To display the default umask type:

umask

The output of umask will be a three-digit number such as:

022

The “0” in the first position indicates that no permissions will be re-stricted for the owner of the file. The “2” in the second and third po-sitions indicates that write permission will be restricted for both the group and all other users, respectively. This is not a particularly se-cure umask setting because read and execute permissions are not re-stricted.

The most restrictive umask is 077, which allows all permissions for the owner but removes read, write, and execute permissions for the group and all other users.

To set your umask for the session to 077, type:

umask 077

To reset your umask permanently, add the above line to your .profile, .cshrc, or other login script. To effect a umask change across the entire system, you can set umask in the /etc/profile file. For more information, refer to your system documentation as well as the umask and profile man pages.

BLAST Protocol File Transfer and PermissionsWhen a file is transmitted using the BLAST protocol, permissions are set according to the rules described below (see “File Transfer Switches” on page 111 for information on the /PERMS switch and other switches that affect owner and group permissions):

◊ If the file is being transmitted from a UNIX system, and the /PERMS switch is not used, BLAST will attempt to transfer the file with the same permissions as it has on the source machine.

152 CHAPTER ELEVEN

◊ If the file is transmitted using the /PERMS switch, BLAST will attempt to set file permissions on the destination machine ac-cording to the permissions specified by the /PERMS switch.

◊ If the file is transferred from a system that does not have a per-mission structure comparable to the UNIX permission struc-ture, permissions will be set according to the umask equivalent on the receiving system.

Running BLAST from a Restricted ShellIt is possible to set up user accounts with a restricted shell like rsh or rksh. With a restricted shell, a user is unable to edit .profile, change directories, or set the PATH environment variable. Thus, once a user is logged into a restricted shell, he has very limited ca-pabilities.

A restricted shell account normally contains a bin subdirectory and a work subdirectory. The .profile login script will place the user into the work subdirectory. Scripts and executables that the user will be allowed to run should be put into the bin subdirectory.

The system administrator must set the PATH in .profile to point to the user’s bin subdirectory. The user’s PATH can point to other sub-directories but should not point to /bin. If the user’s PATH is set to /bin, the user will be able to start an unrestricted shell and defeat the restrictions imposed by rsh.

Run BLAST from a restricted shell account by setting the PATH and BLASTDIR environment variables to the actual BLAST directory. For example, if BLAST is in the /usr/blast directory and the user’s home directory is /usr/jo, add the following to the user’s .profile:

PATH=$PATH:/usr/blastBLASTDIR=/usr/blastSETUPDIR=/usr/jo/workexport PATH BLASTDIR SETUPDIR

Alternatively, BLAST can be run from a restricted shell account by creating links to the appropriate files in the user’s bin subdirectory and setting the environment variables appropriately. If BLAST is in /usr/blast and the user’s home directory is /usr/jo, create the fol-lowing link:

ln -s /usr/blast/blast /usr/jo/bin/blast

SECURE BLAST 153

If the user is going to be running BLAST interactively, you need to make the following links:

ln -s /usr/blast/blast.hlp /usr/jo/bin/blast.hlpln -s /usr/blast/setgetty /usr/jo/bin/setgettyln -s /usr/blast/modems.scr /usr/jo/bin/modems.scrln -s /usr/blast/systems.scr /usr/jo/bin/systems.scr

The environment variables should be set to:

PATH=/usr/jo/binBLASTDIR=/usr/jo/binSETUPDIR=/usr/jo/workexport PATH BLASTDIR SETUPDIR

Limiting AccessCertain procedures are required to ensure data security when using BLAST. These procedures include limiting access to other file trans-fer protocols and limiting shell access.

Other file transfer protocols do not offer the same data security that the BLAST protocol offers; therefore, you must control access to these other protocols. Common file transfer programs include ker-mit, ckermit, sx, rx, sz, and rz. If these or any other file transfer pro-grams are on your system, you should segregate dial-in users into groups that do not have execute permission for these programs.

You must also prohibit running the BLAST product in pseudohost mode (host mode using protocols other than BLAST; see “BLAST Operation as a Pseudohost With 10.8x” on page 204).

BLAST can be executed from a restricted shell or in a manner deny-ing a remote user terminal access to the UNIX shell. A shell script that sets the appropriate environment variables and executes BLAST can be run by the user’s .profile or other login script.

The following script called go_blast is an example of a shell script that executes BLAST in host mode using the default setup. In this example, the BLAST executable is in the directory /usr/blast/secure and the BLAST support files are in /usr/blast.

# go_blast# A script that sets environment variables and runs BLAST in host mode using# the default setup#PATH=$PATH:/usr/blast/secure # Append /usr/blast/secure to the

154 CHAPTER ELEVEN

# current PATH environment variable. BLASTDIR=/usr/blast # Set BLASTDIR environment variable. SETUPDIR=/usr/blast # Set SETUPDIR environment variable.

#export PATH BLASTDIR SETUPDIR # Export environment variables to

# subshells--necessary in bourne shell. blast default -h # Run blast in host mode.exit## End of script.

This script should have execute permission and be located in the search path. The following line should be added to the end of the us-er’s .profile or other login script:

exec go_blast

The exec command substitutes the new process for the calling pro-cess. In essence, the process running the .profile or other login script that calls go_blast is transformed into the process running the go_blast shell script. Nothing following the above exec command in the .profile will be executed. Once BLAST finishes running in host mode, the user will be logged off the system.

Using Secure BLAST

Secure BLAST was developed to provide an extra layer of security over existing UNIX restrictions. Secure BLAST not only recognizes UNIX file permissions but can also further restrict access to partic-ular files as well as insuring that a user executes only authorized ver-sions of BLAST on both the local and remote systems. Authorized users can be limited to a very narrow range of available options in transferring files and performing remote operations.

Secure BLAST allows the BLAST administrator to create a database of user passwords, each with individual security options. Authorized users must provide one of these valid passwords in order to gain ac-cess to the “secured” version of BLAST. The permissions associated with individual passwords in the database control what files and commands are available to the user. For information about how to transmit user passwords, see “Using the Password” on page 168.

The BLAST administrator can use either the blpasswd or blsecure application provided with BLAST to create and maintain the pass-word database. Whereas blpasswd provides a complete user inter-

SECURE BLAST 155

face for setup and maintenance of the BLAST password database file, blsecure is a command line utility that is particularly useful when you want to manipulate the password file via a shell or BLAST script.

“Securing” BLAST is a two-step process that consists of creating the password database file and then linking it to a particular BLAST ex-ecutable file. After creating the password file using either blpasswd or blsecure, another utility, secure, is used to create the link be-tween the password file and the BLAST executable file.

Throughout this chapter the computer running secure BLAST will be referred to as the “host” system, and the computer logging onto the host will be referred to as the “remote” system.

IMPORTANT: Although it is possible to create a password file and link it to a par-ticular BLAST executable file without specifying a full pathname for either file, it is not advisable. You should specify a full pathname for the BLAST executable and password file when using the Secure BLAST utilities. A higher level of security is maintained if neither the password file nor the BLAST file are located in the same direc-tory as blpasswd, blsecure, and secure.

blpasswd

The first step in securing BLAST is to create the password file. The application blpasswd provides a full-screen user interface for setup and maintenance of the password database. The BLAST installation program normally copies blpasswd to the same directory as the BLAST executable. For increased security, blpasswd should be moved to a directory that is accessible only to the BLAST adminis-trator.

Creating and Modifying a Password FileTo create a new password database file, execute blpasswd from the command line by typing blpasswd and pressing ENTER. You will be prompted for a filename (Figure 11-1). Type the filename and press ENTER.

FIGURE 11-1

156 CHAPTER ELEVEN

Next, you will be prompted to create a master password, which will control future access to the file; type the password and press ENTER. You will then be asked if you want to create the new file (Figure 11-2). Press Y to create the file, or N or C to cancel and exit blpasswd.

FIGURE 11-2

After creating a new password file, blpasswd will display the main screen (Figure 11-3).

To open an existing password file for modification, from the com-mand line type blpasswd followed by a space and the name of the file you want to open. You will then be asked for the master pass-word. Typing the password and pressing ENTER will take you to the main screen (Figure 11-3). If the filename you type does not exist, you will be asked if you want to create the file. Press Y to create the file, or N or C to cancel and exit blpasswd.

FIGURE 11-3

The next step in creating or modifying a password file is to enter data into the file, which consists of two parts: header information and record information. Header information includes master data for the password file; record information includes data in each individual password record.

SECURE BLAST 157

Header InformationHeader information consists of the following master data for the password file: the master password for file edit access; the serial number, name, and location of the BLAST executable to which the file will be secured; and optional comments about the password file.

To enter header information into a newly created file or to edit head-er information in an existing file, press H from the main screen. You will see a screen similar to the one in Figure 11-4 below:

FIGURE 11-4

Type the appropriate information into the field highlighted. To move from field to field, press ENTER. After typing data into the Comment field and pressing ENTER, you will be asked if the data you have typed is correct. If it is, press Y; if not, either press C to return to the main screen without saving changes, or press N to move through the fields again for editing. If you do not enter data into any of the fields, pressing ENTER from the Comment field will return you to the main screen. In order to use a newly created file, you must first fill in the header information fields.

Following is a detailed description of each field:


Specifies the master password, which controls editing access to the database file. You must enter this password in order to edit any part of the database file, either header or record information. The Pass-word field will contain the master password that you entered when creating the file, although it will not be displayed. Press ENTER to re-tain this password and move to the Serial Number field. If you want to change the master password, type in the new password and press

158 CHAPTER ELEVEN

ENTER. You will be prompted to retype the new password for confir-mation.

Serial Number XXXXXXXXXX-X-XXXXX

Specifies the serial number of the BLAST executable that you want to secure on the host system. Type in the 16-digit serial number with dashes after the 10th and 11th characters exactly as it appears on the BLAST executable, for example, 0123456789-0-00000. The serial number and version of BLAST are visible when you press the HELP key while running BLAST. If the serial number of the secured executable and the number in the header information do not match, access will not be allowed.

BLAST filename user-defined Specifies the name and path of the BLAST executable file that you are securing on the host system. You must specify the complete path and filename, for example, /usr/joe/blast where /usr/joe/ is the directory location and blast is the name of the secured execut-able.

Comment user-defined

Specifies optional comments regarding the password file.

Record InformationRecord information includes the data in each individual password record. This information will determine who is allowed access to the secured version of BLAST and what permissions that user will have. Record information includes: a user password for access to the se-cured version of BLAST; the permissions associated with that pass-word; the serial number of the remote BLAST executable associated with that password; the directory where files will be transferred; masks to control what files can be transferred; and optional com-ments about the record.

Adding, selecting, and editing records are all controlled by the fol-lowing set of command keys issued from the main screen:

A Add a new record. All edit fields will be blank.

T Select the top (first) record.

D Move down one record.

U Move up one record.

SECURE BLAST 159

B Select the bottom (final) record.

F Find a record by password and select it; blpasswd will prompt you to enter the password.

E Edit an existing record (also accessed by selecting a record and pressing ENTER).

H Edit the header information.

Z Zap a record (mark it for deletion). The record will be marked as unused but not physically removed. This command has the effect of disabling that record and its password. When a record is “zapped,” a “z” is displayed after the permissions.

Zapped passwords cannot be used for a new record until they have been “reclaimed” (see R). When the zap command is used on an already zapped record, the record is “unzapped” and the password and record are enabled once again.

R Reclaim zapped password for possible reuse and delete zapped record. Record numbers may change after use of the reclaim command.

Q Quit blpasswd. You will be prompted to save any changes.

After you have designated a file for creation or editing using the command keys and pressed ENTER, blpasswd will display a screen similar to the one shown in Figure 11-5 below:

FIGURE 11-5

Type the appropriate information into the field highlighted. To move from field to field, press ENTER. After typing data into the Comment field and pressing ENTER, you will be asked if the data you have typed is correct. If it is, press Y; if not, either press C to return to the main screen without saving changes, or press N to move through the

160 CHAPTER ELEVEN

fields again for editing. If you make no changes in any of the edit fields, pressing ENTER from the Comment field will return you to the main screen.

Following is a detailed description of each field:


Specifies the user password for an individual record. This field is blank only for new records. A password cannot be altered once it has been saved in the database, but it can be deleted and made available for reuse with a new record by applying the reclaim command to a “zapped” file (see R command on preceding page).

Permissions GSTLERPCOA or M

Specifies the permissions allowed by the user during a BLAST ses-sion on the host system. Type in the letter or letters that specify the permission(s) allowed (see list below).

IMPORTANT: BLAST does not override standard UNIX permissions. For exam-ple, even though a user may have BLAST permission to rename a file, he cannot do so if he does not have UNIX write permission for that file. Likewise, he cannot change directories if he does not have UNIX permission to do so.

The following permissions are available:

A Append – User can append to a file.

C Change directory – User can change directories.

E Delete – User can delete a file.

G Get – User can get a file.

L List – User can list directory contents.

M Master – User can perform all available operations.

O Overwrite – User can overwrite a file.

P Print – User can print a file.

R Rename – User can rename a file.

S Send – User can send a file.

T Type – User can type a file.

SECURE BLAST 161

Serial Number XXXXXXXXXX-X-XXXXX

Specifies the serial number of the BLAST program that the user is executing on the remote system. Type in the 16-digit serial number with dashes after the 10th and 11th characters exactly as it appears on the remote BLAST executable, such as 0123456789-0-00000. The serial number and version of BLAST are visible when you press the HELP key while running BLAST.

This field may contain the wildcards “?” and “*” to match single or multiple numbers, respectively. For example, 0123456789-?-* will accept any serial number that begins with 0123456789, has any number as the eleventh digit, and has any combination of numbers for the last five digits.

If the serial number of the remote executable and the serial number in the record do not match, access will not be allowed.

Home Directory user-defined

Specifies the directory to which the host computer changes upon validating the password. Files will be transferred into and out of this directory unless the user has permission to change to another direc-tory. The user must have normal UNIX permission for the directory named as the home directory or he will see the error message “In-valid Home directory!” when sending his password. If this field is left blank, access will not be allowed.

Include mask user-defined

Specifies the files that can be accessed by the remote user. If a direc-tory is specified in the include mask, the user must have both BLAST chdir permission and UNIX permission for that directory. The wildcards “?” and “*” may be included anywhere in the include mask. For example file?.dat would allow a user to transfer file1.dat and file2.dat, while *.dbf would allow access to all .dbf files in any directory. If this field is left blank, no files can be access-ed.

IMPORTANT: The include mask will never override your operating system’s per-mission or access system. The user will not be able to access a file or directory using BLAST unless UNIX read, write, and execute permissions are correctly set.

162 CHAPTER ELEVEN

Exclude mask user-defined

Specifies files to be excluded from the include mask. For example, if the include mask is set to file*.* and the exclude mask is set to *.c, a file named file34.a would pass through, but a file named file34.c would not be accessible to the remote user. If this field is left blank, all files matching the include mask will be accessible.

IMPORTANT: The exclude mask will override your operating system’s permission or access system. Even if UNIX read, write, and execute permis-sions normally allow access to a file or directory, BLAST will deny access if it matches the exclude mask.

Comment user-defined

Specifies optional comments regarding each record.

blsecure

The application blsecure is a command line utility that, like blpasswd, sets up and maintains passwords and permissions for BLAST users. Unlike blpasswd, it does not have an interface and does not require interactive input from the BLAST administrator, thereby making it ideal for use from a shell script or a BLAST script.

blsecure Command Line ParametersThe BLAST installation program normally copies blsecure to the same directory as the BLAST executable. For increased security, it should be moved to a directory that is accessible only to the BLAST administrator. To run blsecure, use the following format:

blsecure passwordfile masterpassword { c | h | g | f | p | a | z | r } [options]

where passwordfile is the filename of the password file; masterpassword is the master password that grants editing access to the password file; c, h, g, f, p, a, z, and r are parameters that allow the user to create, search for, and modify password files; and options are arguments of the single-letter parameter.

The single-letter parameters and their accompanying arguments are described in detail below. Note that only one single-letter parameter and its arguments can be used on a command line.

SECURE BLAST 163

c sn blastexe [comment]creates a new password file with the filename and master password specified on the command line.

sn Serial number of the host BLAST executable.

blastexe Full path and name of the host BLAST executable.

comment Optional comment.

h [newmast sn blastexe [comment]]allows you to modify header information. You can change one or more of the data fields with one of the arguments listed below; how-ever, all of the arguments except the comment must be included on the command line. Any argument that you want to remain un-changed must be typed on the command line exactly as it is in the existing header.

newmast New master password for the password file.

sn New serial number of the host BLAST executable.

blastexe New path and name of the host BLAST executable.

comment New comments.

If you do not specify information for each argument (except comment), blsecure will return an error. If no comment currently exists in the password file header, you can leave out this argument or specify a new comment. If a comment does exist in the header, you can replace it with this argument or, if you leave the argument blank, blsecure will delete the currently existing comment.

When specifying the h parameter alone, as in blsecure passwordfile masterpassword h, the header information for that password file will be displayed as shown in Figure 11-6 below:

FIGURE 11-6

TEST3 (master password)

10.7.6 (password file version)

0123456789-0-00000 (host BLAST serial number)

newfile (password filename)

usr/local/blast (host BLAST filename)

This is a new comment (comment)

164 CHAPTER ELEVEN

a pwd perm sn home inc exc [comment]adds a new record. You must have an entry for each argument (see description of the h parameter). This must be a new entry with a new password. See “blpasswd” on page 156 for complete descriptions of the data fields associated with the following arguments.

pwd Password of the existing record.

perm Permission specifier as described below.

sn Serial number of the remote BLAST executable.

home Directory to which the host computer changes upon linking in Filetransfer mode.

inc Include mask for specifying files that may be obtained by the remote user.

exc Exclude mask for screening files that pass the in-clude mask. If you do not want an exclude mask, substitute double quotation marks (" ") on the com-mand line.

comment Optional comment.

The following are the possible hexidecimal values for the perm ar-gument; they can be added together to form the total permission val-ue:

0001 User can get a file.0002 User can send a file.0004 User can type a file.0008 User can list directory contents.0010 User can delete a file.0020 User can rename a file.0040 User can print a file.0080 User can change directories.0100 User can overwrite a file.0200 User can append to a file.7FFF User can use all functions.

For example, if you wanted to create a new record with the data il-lustrated in Figures 11-6 (preceding page) and 11-7 (next page), you would type the following:

blsecure newfile TEST3 a site23 0001 1234567891-0-00000 \/usr/sites *23.dat mast*.* Password for site23

SECURE BLAST 165

p pwd perm sn home inc exc [comment]puts information into an existing record. The arguments are identical to the a command above.

g recnumsearches a record by its number and displays the record as shown in Figure 11-7 below.

recnum Record number for a particular entry. The record number of the first entry is zero.

NOTE: After reclaiming a password for possible reuse (see r), records may have different numbers.

f pwdsearches for a record by its password and displays the record as shown in Figure 11–7 below.

pwd Password for the individual record.

FIGURE 11-7

z pwdmarks a record for deletion but does not physically remove it. A zapped record can be “un-zapped” and reactivated if it is the target

of a subsequent z command. A zapped password cannot be reused until it is reclaimed and the zapped file deleted (see r).

pwd Password of the record to be deleted.

site23 (password)

0001 (permission in hexadecimal)

1234567891-0-00000 (remote serial number)

/usr/sites (home directory on host)

*23.dat (include file mask)

mast*.* (exclude file mask)

Password for site 23 (comment)

166 CHAPTER ELEVEN

rreclaims a “zapped” password for possible reuse and deletes the zapped record. Record numbers, used by the g command, may be re-ordered by using r.

blsecure Error CodesErrors that occur while running blsecure are due to physical causes, such as the file not being found, or read and data errors, such as g failing to locate a specified record. To help prevent unauthorized ac-cess to the password database, returned error codes do not indicate anything other than a general failure.

secure

After you create a password file, use secure to establish a link be-tween the BLAST executable and the password file. In order to use this utility, the BLAST executable must exist with “write” privileges for the administrator. secure should be made accessible only to the BLAST administrator by means of operating system permissions or privileges.

Running secureThe BLAST installation program normally copies secure to the same directory as the BLAST executable. For increased security, secure should be moved to a directory that is only accessible to the BLAST administrator.

Execute secure from the command line by using the -s switch in the following format:

secure blastexecutable -s passwordfile

where blastexecutable specifies the complete path and filename of the BLAST executable, and passwordfile specifies the complete path and name of the password file you wish to secure, as in the fol-lowing example:

secure /local/blast -s /private/password.fil

In this example, /local/blast is the pathname for the BLAST execut-able contained in the directory /local, and password.fil is the name

SECURE BLAST 167

of the password file located in the /private directory. The -s switch links the password file to the executable.

After BLAST is secured, you can determine the name of the pass-word file attached to it by using the -d switch in the following syn-tax:

secure blastexecutable -d

For example,

secure /local/blast -d

will respond with a message similar to the following:

Secure - Version 2.0private/password.fil (/local/blast)

Using the Password

After you have created a password file and secured your host sys-tem, a remote user must use one of the passwords in the password file in order to access the host through the BLAST Session protocol. The password is transmitted from the remote to the host system by the same method used for transmitting a transfer password in the BLAST Session protocol. Note, however, that the secure password supersedes the transfer password; therefore, the remote user will only be prompted for the secure password even though a particular setup may also contain a transfer password.

The password is sent from the remote system with the Send command of the Filetransfer menu or with a BLASTscript FILETRANSFER statement. If a Send command is issued, the following special format for the local filename must be used,


where your_password represents one of the passwords stored in the database file on the host system. The remote filename field is left blank as are the text, overwrite, and append options. If the correct password is successfully sent, the remote user will see a message stating that the password has been validated. The user must type the password exactly as it appears in the password record, and the serial number of BLAST being executed must match the serial number in the password record.

168 CHAPTER ELEVEN

In a BLAST script, the same special local filename format must be sent to the host computer. For example:

FILETRANSFERSEND!password=blue2

SENDmyfile.rptyourfile.rpttaESC

Since no remote filename or Send options are used, two blank lines follow the password line. See “File Transfers with BLAST Session Protocol” on page 194 for information on scripting file transfers.

SECURE BLAST 169

170 CHAPTER ELEVEN

Chapter 12

Introduction To Scripting

Starting Out

Scripts allow BLAST to automate communications tasks. Scripts are often used for tasks such as logging into remote hosts and handling the details of communications sessions that are repetitive or that in-experienced users would find overwhelming. This chapter introduc-es the BLASTscript language and describes an important feature of BLAST that aids scripting—Learn mode. With Learn, BLAST writes your scripts so that learning scripting is made easier.

Executing BLAST ScriptsBLAST scripts can be invoked using one of three different methods.

◊ From the Online menu, select the Script command. When prompted for the script name, enter the name of the file. This in-teractive method of starting a script is preferable when you wish to automate only a portion of your communications session.

◊ In a setup, enter the name of a BLAST script in the Script File field. After the setup is loaded into memory and the Online command is selected from the Offline menu, the script named

INTRODUCTION TO SCRIPTING 171

in the setup will execute automatically. This is useful if you al-ways use a specific script with a particular setup.

◊ From the operating system command line, specify a BLAST script name with the -s switch (see “Command Line Switches” on page 10). The script specified on the command line takes precedence over a script listed in the setup Script File field.

You can include a directory path when you specify a script filename. If you do not name a directory, BLAST will first search the current directory and then the SETUPDIR directory.

To abort a script completely, press ATTN ATTN. To abort a script af-ter the currently executing statement completes execution, press ATTN once.

Writing a ScriptThe best way to learn how to write a script is by doing it. First, start a word processing program or a text editor on your computer. If you prefer to use a word processor for creating script files, be aware that your scripts must always be saved as text files, not word processor documents. Your scripts should be saved in the directory from which you will execute BLAST, or in the SETUPDIR directory. These are the only two locations in which BLAST searches for script files if you have not specified a search path.

After starting the editor, type in the following short script:

# hello.scr## Just wanted to say hi#.begin display "Hello, world!" return## End of script.

Save this file under the name “hello.scr” and go to BLAST’s Online menu. Choose the Script option and enter the filename

hello ENTER

When hello.scr executes, it displays the message

Hello, world!

172 CHAPTER TWELVE

on your screen and then returns control to you.

About hello.scrAs simple as hello.scr is, it illustrates several important scripting concepts. All the lines starting with “#” are comments explaining the functions of the script commands and are not displayed. You may be surprised how quickly you can forget why you wrote a particular script or how an especially difficult section of code actually works. Comments can clarify what you are trying to accomplish with your script.

In hello.scr, the line beginning with a period, .begin, is called a label. A label serves not only as a supplemental comment but also as a destination for the script to go to in a GOTO command, discussed later. Labels can be eight characters in length, not counting the initial period.

The DISPLAY command causes text to be displayed on your local computer screen; it does not cause text to be transmitted through the serial port. Another script command, introduced later, performs this task.

Finally, the RETURN command returns control of BLAST to you.

A Sample ScriptTo learn more about scripting, it is helpful to imagine a problem that can be solved through scripting. For instance, suppose a medical of-fice needs to call an insurance company each evening to file insur-ance claims on behalf of patients who have visited the doctor that day. Pam, the system administrator for the medical office, collects the claims into a single file called pt_claims. Since the insurance company also uses BLAST software for data communications, Pam will use the BLAST Session protocol to transfer pt_claims to the in-surance company. The company has determined that Pam’s daily claims file should be given the name logan56021.dat on the insur-ance company system. Therefore, Pam wants a script to perform the following tasks:

1. Connect to the remote system.

2. Send the claims file as a text file.

3. Disconnect.


A script that meets these requirements is illustrated below. The script dailyrpt.scr is certainly more complicated than hello.scr, but the same sections that were originally outlined are present. To make it easier to discuss the script, we will refer to the line numbers shown in brackets next to the script statements. You would not include these numbers in an actual script.

[ 1] # dailyrpt.scr[ 2] #[ 3] # A script to send daily medical reports to[ 4] # the insurance company[ 5] #[ 6] # Section 1: CONNECTING[ 7] #[ 8] .begin[ 9] set @ONERROR = "CONTINUE"[10] connect[11] if @STATUS = "0" goto .xfer[12] display "No Connection! Error code: ", @STATUS[13] return[14] #[15] # Section 2: TRANSFERRING[16] #[17] .xfer[18] filetransfer # enter BLAST protocol[19] send # prepare to send a file[20] /usr/accounts/pt_claims # local filename[21] logan56021.dat # remote filename[22] t # specify text file[23] esc # exit Filetransfer mode[24] if @EFERROR not = "0"[25] display "An error occurred during file transfer."[26] display "Please examine the log file."[27] end[28] #[29] # Section 3: DISCONNECTING[30] #[31] .finish[32] disconnect[33] return[34] #[35] # End of script.

CONNECTING (Section 1)

The first section of the script (.begin) establishes the connection with the insurance company. Line 9 sets a variable called @ONERROR. In a BLAST script, all variables begin with “@”. Some variables are

174 CHAPTER TWELVE

reserved, meaning that they are defined by BLAST for special pur-poses; other variables can be created by you (see BLASTscript Re-served Variables on page 263). @ONERROR is a reserved variable that determines how BLAST will respond to routine (nonfatal) er-rors. By giving @ONERROR the value CONTINUE, Pam is telling BLAST to skip error messages rather than pause and wait for a hu-man operator to respond.

Line 10, the CONNECT statement, is responsible for a great deal of work. The CONNECT statement, like Connect from BLAST’s inter-active menus, initializes the modem, dials the insurance company, and logs into the company system. All of this information—the mo-dem type, phone number, remote system type, and account informa-tion—is taken from the setup (see Connecting and Disconnecting on page 211).

Line 11 demonstrates how scripts are programmed to make choices with the IF (conditional) statement. After the CONNECT command executes, it sets the value of @STATUS to indicate whether or not the connection was successful. The IF statement tests the value of @STATUS in its conditional clause. If @STATUS equals 0, the con-nection was successful and the script performs the GOTO command, sending the script to the section labeled .xfer, which controls file transfer.

if @STATUS = "0" goto .xfer

conditional executes if conditional statement clause is true

If @STATUS equals any value other than 0, script execution contin-ues on line 12, displaying “No Connection” and an error code. At this point, RETURN aborts further execution of the script and control is returned to the user.

TRANSFERRING (Section 2)

The second section, under the .xfer label, begins with the FILETRANSFER statement. The FILETRANSFER statement works like the Filetransfer command of the Online menu. When it is executed, BLAST attempts to start the BLAST software on the re-mote computer, and the script pauses until Filetransfer mode is en-tered or a time limit expires. The exact events that occur when the FILETRANSFER command is executed depend on the setting of the System Type setup field (page 67).

The next four lines (19–22) provide the information BLAST proto-col needs to send the required file as a text file. If another protocol


were used, this section would be scripted differently (for more infor-mation on scripting for alternative protocols, see Chapter 13). Line 23, ESC, ends the filetransfer session.

Lines 24–27 illustrate another form of the IF command, IF-END. With IF-END, several lines of script can be executed in a block if the conditional clause is true. In line 24, the @EFERROR reserved variable is tested, which indicates if any errors occurred during a BLAST protocol file transfer. If @EFERROR equals 0, no errors were encountered. For any value other than 0, two messages (lines 25–26) are displayed and the IF statement ends. In either case, the script advances to the .finish label.

DISCONNECTING (Section 3)

The final section of the script, under the .finish label, begins with the DISCONNECT command. Like CONNECT and FILETRANSFER, DISCONNECT performs the same operation as the corresponding command of the Online menu. As you become more familiar with BLAST’s scripting language, you will discover that many script commands are similar to the options on BLAST’s interactive menus. RETURN ends the script and returns control of BLAST to you.

Learn Mode

An important aid to writing your own scripts is BLAST’s Learn mode. With Learn, you perform a communications task exactly as the script should perform it, and BLAST creates the script from the actions you take. Typically, the Learn script serves as a “rough draft” of the final script. To start Learn mode, select Learn from the Offline menu. BLAST prompts you to name the Learn script. Note that Learn mode does not function with PASSTHRU.

Suppose that you wanted to write a script to log into a computer for which there is no standard system type in the BLAST setup. A bank’s computerized account service, for example, may have an un-usual login. Assume that after the modems connect, the bank issues the prompt “MIDAS>,” waits for your user identification(AlbertyArtCo), and then issues the prompt “?:”.

To help you write your login script, start Learn mode and then pro-ceed to log in as usual, being careful to avoid spelling errors and oth-er trivial mistakes. When you finish, return to the Offline menu and select Learn again to turn off Learn mode.

176 CHAPTER TWELVE

The following is an example of what the Learn script might look like:

# BLAST Learn mode script# Original filename: bank.scr# Date: 09/1/95# Time: 11:00:00#CONNECT# entering TERMINAL mode#ttrap 6, "\012\015MIDAS>"tsend "Alber"tsend "tyArtCo", CRttrap 3, "\012\015\012\015\?:"# exiting TERMINAL mode# RETURN commented out for appending

Even though the script has a strange appearance, you can decipher it. TSEND is the script command for transmitting text through the se-rial port. This command is used for sending the user ID to the bank. TTRAP is used for checking text coming into the serial port, so it is used for detecting the prompts issued by the bank’s system. Without doing any more work, this script will actually perform the login.

Editing the Learn ScriptBecause BLAST cannot distinguish the meaning of any of the data entering or leaving the serial port, Learn mode may “break” strings of text inappropriately. Editing the Learn script to make the TSEND statements meaningful to human readers is a good idea, but it is not necessary. Likewise, TTRAP statements may contain unneeded characters when scripted by Learn mode. In the example above, \012 is the octal representation of the line feed and \015 is the octal form of the return character. These characters are not needed to detect the prompts issued by the bank, so they may be edited for clarity.

After your have cleaned up the Learn script, it could look like this:

# bank.scr## A script to log into the bank#.begin CONNECT ttrap 6, "MIDAS>" tsend "AlbertyArtCo", CR


ttrap 3, "?:" return## End of script.

Now the script can be read more easily. After connecting, the script will wait for up to six seconds for the string “MIDAS>.” Next, the script sends the string “AlbertyArtCo” and a carriage return. Finally, the script waits for up to three seconds for the “?:” prompt and then returns control to you.

Polishing the Learn ScriptAfter being edited, the Learn script makes better sense to human readers, but it can still be improved. Take a moment to assess it. What’s left to be done?

One area for improvement is in error handling. You saw earlier that @STATUS could be tested after the CONNECT command to deter-mine whether a connection was established. Similar error checking should be added to the Learn script.

Another area for improvement is in the use of variables. At present, the user ID is “hard-coded” into the script, meaning that it has a fixed value. If the userid is placed in the appropriate field of the set-up, the script can access it with the @USERID reserved variable. Thus, a more polished version of the Learn script might look like:

# bank.scr## A script to log into the bank#.begin CONNECT if @STATUS not = "0" return ttrap 6, "MIDAS>" tsend @USERID, CR ttrap 3, "?:" return## End of script.

As you can see, Learn mode and your own knowledge of BLAST’s scripting language simplify the process of automating your commu-nications tasks.

178 CHAPTER TWELVE

Writing Your Own Scripts You have now seen enough of the scripting language to begin writ-ing your own scripts. You may wish to read Chapter 13, which de-scribes techniques for working with disk files, manipulating strings, and interacting with programs in your system. Chapter 14 discusses the BLAST method of connecting and disconnecting, which relies heavily on scripts. Chapters 15 and 16 serve as reference guides for all scripting commands and reserved variables. Many examples are included in these chapters to help you get started. In addition, sample scripts are available for download from Blaster (see “Connecting to Blaster” on page 47).


180 CHAPTER TWELVE

Chapter 13

BLASTscript Topics

Scripting Basics

Although scripts can address a wide range of communications needs, most scripts handle a limited number of common tasks, such as capturing text to a file, displaying information on the screen, and communicating with other programs in the computer. In this chapter we will demonstrate scripting techniques for such tasks.

Programming StyleIt may sound strange to say that a script should conform to a certain “style,” but following a logical style will make it easier for others to understand your script. For example, indenting sections of script that execute together, such as the code in a conditional (IF-END) block, is a simple stylistic convention that helps readability, as in the fol-lowing script:

BLASTSCRIPT TOPICS 181

# Start of script#.begin display "Hello, world!" if @EMULATE = "TTY" display "Your emulation is set correctly" end else set @EMULATE = "TTY" display "Your emulation is now TTY" end return## End of script

Your programming style also affects how efficiently the script will execute. BLAST scripts are interpreted, meaning that BLAST deci-phers the instructions in each line of your script as it executes. To make your script run most efficiently, you should:

◊ Use spaces between expressions. For instance, the script inter-preter can evaluate the first line in the example below more eas-ily than it can the second line because of the spaces placed around “=”.

if @STATUS = "0" set @mystat = "GO"

if @STATUS="0" set @mystat="GO"

◊ If certain labels in your script will be frequent destinations for the GOTO command, place those labels near the beginning of the script. BLAST looks for labels from the start of the script and works down.

Legal and Illegal ExpressionsAn error that you may encounter during script development is “ille-gal menu selection.” This error indicates that BLAST has encoun-tered a command in your script that it could not execute. Every line in a script must be executable or contain a comment preceded by #. Blank lines are almost never executable (except for special cases discussed later); thus, do not use blank lines in a script to separate lines of code visually. If BLAST encounters a blank line in a script where it is unexpected, the script interpreter will generate the “ille-gal menu selection” error.

182 CHAPTER THIRTEEN

ILLEGAL LEGAL

if @STATUS = "0" if @STATUS = "0" #disconnect disconnect #end endreturn return

A typing mistake in a script line can also generate an error message. For example, a line such as

ig @STATUS = "0"

will generate the “illegal menu selection” error because “ig” is not a valid script command.

The Status of @STATUSThe result of many script operations is reported in the reserved vari-able @STATUS, which has a number of functions, including indicat-ing whether an error occurred during the CONNECT command and identifying which item in a list of target strings was detected by TTRAP. Because @STATUS is affected by so many script opera-tions, you may need to save the value of @STATUS in a “safe” vari-able so that you can refer to it later in your script, as in the following example:

# Following is the target list:# ttrap 5, "Apples", "Oranges", "Peaches"## Save @STATUS in a user-defined variable.# set @fruit = @STATUS## @STATUS will be changed below by the DISCONNECT statement# disconnect if @STATUS = "0" display "Disconnected OK" else display "Disconnect failure!" if @fruit = "0" display "No fruit was selected" if @fruit = "1" display "Apples are delicious" if @fruit = "2" display "Oranges are tasty" if @fruit = "3" display "Peaches are nice, too" return## End


For a list of all the commands that set @STATUS, see “Commands That Set @STATUS” on page 223.

The CALL CommandWhen you set out to write a complicated script, ask yourself whether the script is made up of logically distinct sections. If so, you may be able to code each section as a separate script and write a “master” script that calls each section as required, checking for errors. Work-ing with several small scripts is generally preferable to a single large one because it is easier to follow the logic of the program and find errors. The CALL command is used to transfer execution to another script, for example

call "getdata"

calls the script named “getdata.” When the RETURN command is ex-ecuted in the called script, control returns to the calling script:

return [exit_code]

The exit code is optional. When control is returned to the calling script, the value of @STATUS in the calling script will be equal to the value of the exit code. For example, the script testone.scr would call the script testtwo.scr as follows:

# testone.scr# display "This script calls testtwo.scr” call "testtwo.scr"# ...

At this point, testtwo.scr executes:

# testtwo.scr# ask "Enter a number: ", @input return @input## End

The value of @STATUS in testone.scr has now been set to the value of @input entered in testtwo.scr, and testone.scr continues with the remainder of its commands:


# ... display "Now @STATUS = ", @STATUS return## End

A script that has been called may call another script, a process known as “nesting.” Scripts may be called recursively to the limit of available system resources.

All variables in a script are global, meaning that they can be read and changed anywhere. For example, you can write a script that only sets the variables you will use. Your “master” script then calls this script at the beginning of execution. The master script and any other scripts you call afterward will “see” the variables that you created.

Executing in a LoopTo create a loop, you can write a script to keep track of a loop counter and use the GOTO command:

# looping demo number 1# set @count = "10".loop display "Countdown: ", @count let @count = @count - "1" if @count not = "0" goto .loop display "BLAST off!" return

Running the script would result in the following display on your screen:

Countdown: 10Countdown: 9Countdown: 8Countdown: 7Countdown: 6Countdown: 5Countdown: 4Countdown: 3Countdown: 2Countdown: 1BLAST off!


An alternative method of looping uses the REPS command. With REPS, the previous script could be written as:

# looping demo number 2# reps 10.loop display "Counting down..." if reps goto .loop display "BLAST off!" return

Since testing the value of REPS in an IF statement automatically decrements it, REPS is a more compact way of executing a loop than a loop counter. In the example above, the GOTO statement is execut-ed while REPS is greater than zero, so that the loop is exited after the message “Counting down...” has been displayed 10 times. As shown in the illustration below, this method of writing the script pro-duces a different display than that of a loop counter. Note that if the number of repetitions is taken from a variable, the countdown oc-curs, but the variable retains its initial value.

Counting down...Counting down...Counting down...Counting down...Counting down...Counting down...Counting down...Counting down...Counting down...Counting down...BLAST off!

Manipulating Text

A number of script commands are available for manipulating text files and text strings. The commands that work with text strings in-clude:

STRCAT string1, string2, [, ...] – Combine two or more strings to make a single, longer string. The longer string re-places string1.


STRINX string1, string2 – Find the first occurrence of string2 in string1. @STATUS holds the position of the first character in string1 where a match was found.

STRLEN string1 – Find the length of a string. @STATUS is set to the value of the length.

STRRINX string1, string2 – Find the last occurrence of string2 in string1. @STATUS holds the starting character po-sition of the last occurrence in string1 where a match was found.

STRTRIM, string1, position1, position2 – Extract a substring of string1 beginning at position1 and ending at position2. After the substring has been extracted, the value of string1 is set to substring.

There are other commands for string manipulation, such as the com-mands to find the ASCII value of a character, to convert all charac-ters in a string to upper or lower case, and to request interactive string input from the user. These and other commands for string ma-nipulation are discussed in Chapter 15.

The following example illustrates the use of string commands:

# String demo - extract first and last name from a string## Set variables# set @name = "Johnson, Alfred" set @first = @name set @last = @name## Find the comma in the name string# strinx @name, ","## Move to last char of last name and extract last name# let @STATUS = @STATUS - "1" strtrim @last, 1, @STATUS display "Client's last name: ", @last# # Move forward to first char of first name and extract# everything from there to the end of the string# let @STATUS = @STATUS + "2" strtrim @first, @STATUS


display "Client's first name: ", @first# # Rebuild full name by concatenating first and last names# strcat @first, " ", @last display "Client's full name: ", @first return## End of script.

Capturing TextTwo commands, TCAPTURE and SETTRAP, are available for cap-turing text as it enters the serial port. The TCAPTURE command is used if the text is to be placed in a disk file. The following script il-lustrates a simple implementation of TCAPTURE.

# Capture demo# tcapture on "sales.rpt"## Pause script until 4 sec of "quiet" elapses# wait 4 idle tcapture off## End of script.

The TCAPTURE command itself does not initiate the text capture. Text capture starts when a WAIT, TSEND, TTRAP, or TUPLOAD command is executed.

The second method, SETTRAP, allows incoming text to be captured into a script variable. The SETTRAP command itself does not cause any text to be captured, but it prepares TTRAP to capture text by set-ting a variable into which the captured text is to be saved and speci-fying a limit on the number of characters saved into the variable. A simple form of SETTRAP/TTRAP is:

# Settrap/ttrap demo#settrap @input, 65 # Capture up to 65 char till end of # line reachedttrap 30, "^M^J"## End of script.


In this example, up to 65 characters are saved into the variable @INPUT. The string ^M^J (carriage return/line feed) triggers the end of the captured text, which includes the trigger string and any text preceding the trigger—up to 65 characters. If no incoming char-acters match the trigger within 30 seconds, the last 65 characters of text are saved to the variable @INPUT.

More complex forms of the TCAPTURE and SETTRAP commands are described in Chapter 15.

Reading and Writing Text FilesA script can read and write entire lines of text from a text file. As many files can be open at a time as there are file handles available in your system. The commands for opening a file are:

FOPENA handle, filename – Open a file for appending.

FOPENR handle, filename – Open a file for reading.

FOPENW handle, filename – Open a new file for writing (de-letes existing file).

These commands must specify two pieces of information: the file-name and a file handle. The file handle is an integer that other com-mands in the script will use to refer to the file. @STATUS is set to the value 0 if the file is opened successfully.

The commands for reading, writing, and closing files are:

FREAD handle, variable – Read a line of text.

FWRITE handle, string [, string] – Write a line oftext.

FCLOSE handle – Close the file.

To be read properly, a line of text cannot be longer than the maxi-mum length of a variable, which is

10.7x 139 characters.

10.8x 1,024 characters.


When read and write operations are successful, @STATUS is set to 0. If they are unsuccessful—for example, a script attempts to read past the end of a file—@STATUS is set to a nonzero value.

Following is an example of a script that uses the file handling com-mands:

# File read/write demo## Open modems.scr and count the number of lines.# Write the result in a new file called line.cnt.#.begin clear set @file = "modems.scr" fopenr 1, @file if @STATUS not = "0" werror "Can't open modems.scr" return end fopenw 2, "line.cnt" set @count = "0" display "One moment, please." cursor 10, 6 put "Reading line #".loop fread 1, @input # # If @STATUS is 0, count line and return for another # if @STATUS = "0" let @count = @count + "1" cursor 10, 21 put @count goto .loop end.continue # end of file! fwrite 2, @count, " lines in modems.scr." fclose 1 fclose 2 display "Done! Check line.cnt for line count." return# End of script.


Managing the Screen Display

Thoughtful screen displays help users gain a sense of being “in good hands.” Informing users of the progress of a lengthy job, such as a file transfer, frees them to do other things while the software does its job. Displaying too much text onto the screen at once or neglecting the screen completely, however, can make users wonder instead if their session has malfunctioned. BLAST’s scripting language pro-vides a number of commands and reserved variables for controlling the screen to present the right amount of information.

Turning Off the ScreenFor some applications, you may wish to turn off regions of the screen while running a script. (To disable screen displays altogether, include the -n switch on the command line when you start BLAST; see “Command Line Switches” on page 10) The following reserved variables control particular regions of the display:

@USERIF – The user interface area, or menu area, at the top of the screen.

@SCRLREG – The scrolling region in the middle of the screen.

@TRANSTAT – The File Transfer Status Area of the screen.

Set these variables to 0 or OFF to disable the corresponding screen areas. Set the variables to 1 or ON to enable them. For example, if you do not want the BLAST menus to be displayed while your script is running, you would put the statement

set @USERIF = "0"

in your script. The top four lines of the display would then become part of the scrolling region. You must remember to turn the menu re-gion back “ON” in the script or the user will NOT be able to see the BLAST menus after the script is finished.

Displaying Text in the Menu RegionTwo script commands permit you to display text in the menu region:

WRITE string [, string] – Prints a message.


WERROR string [, string] – Prints a message in the menu region and then waits for the user to press a key. (The script will not pause if @ONERROR is set to CONTINUE.)

These commands are normally used for displaying errors or progress messages.

Displaying Text in the Scrolling RegionThe most common way to display text in the scrolling region is with the DISPLAY statement described on page 228. The DISPLAY command prints a string or a list of strings at the current cursor po-sition; depending on the emulation you have chosen, the cursor may or may not advance to the next display line.

Another method of displaying text uses a pair of commands, CURSOR and PUT:

CURSOR row, column – Position cursor.

PUT string [, string] – Print string.

The following script demonstrates an application of these com-mands:

# Screen Display Demo# Hide modem control strings from the user#.begin set @ONERROR = "CONTINUE" set @USERIF = "OFF" clear # Erase the screen cursor 12, 30 put "Now connecting, please wait." set @SCRLREG = "OFF" connect set @SCRLREG = "ON" if @STATUS not = "0" set @USERIF = "ON" clear write "Can't connect or log in." return end terminal # enter Terminal mode set @USERIF = "ON" # don't forget this! return# End of script.


Communicating with Other Programs

In some BLAST applications, the end user is not even aware that BLAST is operating in the system. BLAST provides a simple inter-face that lets other programs control BLAST, hiding the existence of BLAST completely from the user if necessary.

Passing Information to BLASTThe command line can contain up to ten “arguments,” or parameters, that pass information to a BLAST script. Command line arguments follow the setup name on the command line (see “Command Line Switches” on page 10). For example, consider the following BLAST command line:

blast chicago -ssales 12:05 midwest

This command line will start BLAST with the chicago.su setup, ex-ecute the script called sales.scr using the -s switch, and store the ar-guments “12:05” and “midwest” in the reserved variables @ARG0 and @ARG1, respectively.

A program can also pass information to a script by writing a text file that the script opens and interprets. Alternatively, because a script it-self is just a text file, your controlling software can write a script that can be executed by BLAST “on the fly.”

Controlling Other Programs from BLASTWhile a script is executing, it can start other programs in your com-puter with the LOCAL/SYSTEM command. This command allows your script to execute a single command as you would type it on the command line. The following script demonstrates use of the LOCAL/SYSTEM command:

# Local System demo# Copy a file.begin set @syscmd = "cp modems.scr modems.txt" local system @syscmd esc return# End of script.


File Transfers with BLAST Session Protocol

Chapter 6 describes the BLAST Session protocol, including some information about scripting file transfers. This section provides de-tailed information about writing these scripts.

The coding that performs a file transfer in a script closely follows the sequence of menu choices and prompts that BLAST uses when the same task is performed manually. Thus, it makes sense to practice a communications task interactively before attempting to write the script that will automate the task. Learn mode (page 176) provides another means of getting an idea about how a particular task can be coded in a script.

Getting and Sending FilesA simple GET and SEND could be coded like this (remember, you would not include the numbers in brackets):

[ 1] filetransfer[ 2] get[ 3] yourfile.rpt[ 4] myfile.rpt[ 5] ta[ 6] send[ 7] labdata.dat[ 8][ 9][10] esc

In this script, yourfile.rpt (line 3) is the response to the Remote File-name prompt that BLAST issues when the GET command is given, and myfile.rpt (line 4) is the response to the Local Filename prompt. The transfer options t and a (line 5) specify “text” and “append” in this example—the same symbols you would use if you were per-forming the file transfer interactively. In the SEND example, two blank lines (lines 8 and 9) are entered to indicate that BLAST should use default values for these responses. Thus, the remote filename will be the same as the local filename, and no transfer options are specified (the file transfer will be binary). Blank lines representing default filenames and file attributes (t, o, a) cannot contain com-ments. Other than the preceding exceptions, you should not have blank lines in a script unless they do contain the comment character, #. The ESC statement represents pressing the CANCEL key, which is the action that you normally take to exit Filetransfer mode.


Performing Remote CommandsThe BLAST session protocol allows you to perform remote system commands without special knowledge of the command syntax on the remote machine. Remote commands are coded in a script like this:

filetransferremote chdir /usr/customer escesc

The first ESC represents the escape keystroke that will move you from the Remote menu to the Filetransfer menu. The second ESC terminates the session in the usual manner.

Using Transfer Command FilesA powerful feature of the BLAST Session protocol is the ability to take its commands from a transfer command file (see “Transfer Command File” on page 115). To use a transfer command file in a script, the following syntax is used:

filetransferfiletransfer.tcfesc

where transfer.tcf is the command filename. The extension .tcf is of-ten used to identify a transfer command file, but this convention is not required.

Sending MessagesBLAST protocol can send messages between systems during a BLAST session (see the description of the Message menu option on page 108). String-variables may be substituted for all elements ex-cept ESC.

filetransfer # issue the transfer commandmessage # sending a message Sending Sales Reports # the messageesc # exit Filetransfer mode


Special ConsiderationsTo take full advantage of the BLAST Session protocol, keep the fol-lowing points in mind:

◊ BLAST attempts to queue as many remote commands as possi-ble (like GETs) before issuing local commands (like SENDs). This behavior permits BLAST to transmit files in both direc-tions simultaneously, but it also means that files may not be transmitted in the order specified in the script.

◊ Many filetransfer and file management commands can be com-bined into one FILETRANSFER-ESC block, as in the follow-ing example:

filetransfer # begin Filetransfer modesend # send files that*.txt # match the template %taremote # begin remote file mgmt chdir /usr/customer print client.log esc # leave remote file mgmtfile # use a command filesite3.tcfesc # exit Filetransfer mode

Combining operations allows BLAST to work more efficiently, saving online charges or other long-distance telephone costs.

◊ Errors that occur during file transfer can be checked by testing the value of @EFERROR or by examining an @EFLOG file after exiting Filetransfer mode. If extended logging is enabled, addi-tional reserved variables give information about the number of successful transfers and the number of failures. These reserved variables are described in Chapter 15. See also “Using Log Files for Error Checking” on page 205.

If the line is dropped during a file transfer, BLAST can either ignore the problem or abort Filetransfer mode immediately. The action BLAST takes is determined by the setting of the DCD Loss Response setup field, but the ability of BLAST to react to changes in DCD depends on the serial port device driver. If BLAST does not react to changes in DCD as expected, consult


your system documentation for an alternate device driver that tracks DCD.

File Transfers with FTP Using 10.8x

The syntax for FTP file transfers is the same as for BLAST protocol except that there are no transfer options; therefore, there is no line for transfer options in FTP scripts. You may, however, add support-ed file transfer switches to receiving filenames (see “File Transfer Switches with FTP” on page 126). The basic file transfer syntax is: filetransfersendlocal_filenameremote_filenamegetremote_filenamelocal_filenameesc

As with BLAST protocol, a blank line for the receiving filename in-dicates that the file will retain its original name. For example, in the following script

FiletransfergetNewinventory.txt esc

the local filename will remain the same as the remote filename—Newinventory.txt.

File transfer scripts can be improved by adding error-checking fea-tures. For a discussion of error checking in file transfer scripts, see “Using Log Files for Error Checking” on page 205.

File Transfers with Kermit

Before writing scripts for Kermit, you may want to review the gen-eral information in Chapter 8, Kermit Protocol, on page 129. Learn mode (page 176) is also a good tool for obtaining a rough draft of a script you will need in a particular case.


Sending FilesBefore issuing a SEND command, you must start simple Kermit or Kermit server on the remote machine.

Simple Kermit

After starting simple Kermit, you must issue a SEND command on the remote machine. The basic syntax for sending files using simple Kermit is as follows (the actual receive command depends on the specific implementation of simple Kermit) ConnectTSEND "kermit", CR TSEND "receive_command local_filename", CRFiletransferSENDlocal_filenameESC

Kermit Server

Before issuing a SEND command, you must start Kermit server on the remote machine. For most UNIX machines, this command is “kermit -x.” The basic syntax for sending files using Kermit server is as follows:

ConnectTSEND "kermit -x", CRFiletransferSENDlocal_filenameremote_filenameESC

Receiving FilesKermit has been implemented on many computer systems. BLAST’s implementation of Kermit supports both “receiving” and “getting” files from remote computers. The RECEIVE command is used to transfer a file from simple Kermit, whereas a GET command is used for transferring a file from a Kermit server.

Simple Kermit

Before issuing a RECEIVE command, you must start simple Kermit on the remote machine and issue a send command. The basic syntax for receiving files using simple Kermit is as follows (the actual send command depends on the specific implementation of simple Ker-mit):


ConnectTSEND "kermit", CRTSEND "send_command remote_filename", CRFiletransferReceivelocal_filenameESC

Kermit Server

Before issuing a GET command, you must start Kermit server on the remote machine. For most UNIX machines, this command is “ker-mit -x.” The basic syntax for GETs using Kermit server is as follows:

ConnectTSEND "kermit -x", CRFiletransferGETlocal_filenameremote_filenameESC

Transferring More Than One FileUnless you exit simple Kermit or Kermit server on the remote com-puter, you do not have to issue the command to start Kermit for ev-ery transfer block, only the first one. For example, you could run the following script:

ConnectTSEND "kermit -x”, CRGETSalesReport.txtStore1Sales.txtSENDStore1Inventory.txtInventory.txtESCTSEND "quit", CR

For simple Kermit, however, you do have to issue the simple Kermit send or get command each time you transfer a file, as in the follow-ing example:

ConnectTSEND "kermit", CRTSEND "send SalesReport.txt", CRFiletransfer


ReceiveStore1Sales.txtESCTSEND "receive Store1Inventory.txt", CRFiletransferSendInventory.txtESCTSEND "quit", CR


File Transfers with Xmodem and Xmodem1K

Before writing scripts for Xmodem and Xmodem1K, you may want to review the general information in Chapter 9 on the use of these protocols. Learn mode (page 176) is also a good tool for obtaining a rough draft of the script you will need in a particular case.

Sending FilesBefore issuing a SEND command, you must issue the Xmodem re-ceive command on the remote computer for the remote system’s im-plementation of Xmodem. The basic syntax for sending a file using Xmodem is:

ConnectTSEND "receive_command remote_filename", CR FiletransferSENDlocal_filenameESC

Receiving FilesThe syntax for receiving files is:

ConnectTSEND "send_command remote_filename", CR FiletransferGETlocal_filenameESC


Transferring More Than One FileA separate FILETRANSFER-ESC block is required for each file that is transferred. For example, to send two files and get one file, three FILETRANSFER-ESC blocks are needed, as in the following example:

# 3-File Xmodem TransferConnectTSEND "rx Sales", CRFiletransferSENDS1SalesESCTSEND "rx Order", CRFiletransferSENDS1OrderESCTSEND "sx Inventory", CRFiletransferGETS1InventoryESC


File Transfers with Ymodem and Ymodem G

Before writing scripts for Ymodem and Ymodem G, you may want to review the general information in Chapter 9 on the use of these protocols. Learn mode (page 176) is also a good tool for obtaining a rough draft of the script you will need in a particular case. Because the filename is passed to the receiving computer, a filename is not needed when receiving a file.

Sending FilesBefore issuing a SEND command, you must issue the Ymodem re-ceive command on the remote computer for the remote system’s im-plementation of Ymodem. The basic syntax for sending a file using Ymodem is:


ConnectTSEND "receive_command", CR FiletransferSENDlocal_filenameESC

Receiving FilesThe syntax for receiving files is:

ConnectTSEND "send_command remote_filename", CR FiletransferGETESC

Transferring More Than One FileA separate FILETRANSFER-ESC block is required for each file that is transferred. For example, to send two files and get one file, three FILETRANSFER-ESC blocks are needed, as in the following example:

# 3-File Ymodem TransferConnectTSEND "rb", CRFiletransferSENDSalesESCTSEND "rb", CRFiletransferSENDOrderESCTSEND "sb Inventory", CRFiletransferGETESC



File Transfers with Zmodem

Before writing scripts for Zmodem, you may want to review the gen-eral information in Chapter 9. Learn mode (page 176) is also a good tool for obtaining a rough draft of a script.

The Zmodem protocol is configured through the Zmodem setup sub-window. An important parameter for scripting purposes is Auto Re-ceive. With Auto Receive set to YES in the setup file or the reserved variable @ZMAUTODOWN set to YES in a script, Zmodem will only receive files. Note that a setting for @ZMAUTODOWN in a script over-rides the setting of Auto Receive in the setup file.

Because the filename is passed to the receiving computer, a filename is not needed when receiving a file.

Sending FilesBefore issuing a SEND command, you must issue the Zmodem re-ceive command on the remote computer for the remote system’s im-plementation of Zmodem. In the basic syntax for sending a file using Zmodem below, the reserved variable for Auto Receive, @ZMAUTODOWN, is set to NO in case the Setup file has Auto Receive set to YES or @ZMAUTODOWN has been set to YES earlier in the ses-sion:

set @ZMAUTODOWN = "No"ConnectTSEND "receive_command", CR FiletransferSENDlocal_filenameESC

Receiving FilesThe syntax for receiving files depends on the how you set @ZMAUTODOWN. If @ZMAUTODOWN is set to NO, you need a GET statement:

set @ZMAUTODOWN = "No"ConnectTSEND "send_command remote_filename", CR FiletransferGETESC


If @ZMAUTODOWN is set to YES, you do not need a GET statement

set @ZMAUTODOWN = "Yes"ConnectTSEND "send_command remote_filename", CR FiletransferESC

Transferring More Than One FileAs with Xmodem and Ymodem protocols, with Zmodem protocol each FILETRANSFER-ESC block can specify only one file, as in the following example:

set @ZMAUTODOWN = "No"ConnectTSEND "rz", CRFiletransferSEND Sales.txtESCTSEND "sz Inventory.txt", CRFiletransferGETESC


BLAST Operation as a Pseudohost With 10.8x

If a remote user logs onto your UNIX system and wants to perform a file transfer, the immediate question is: “What file transfer proto-col will the remote operator use?” If he is running BLAST on his system, the best choice would be the BLAST Session protocol. In this case, the user starts BLAST with the command

blast -h

and then enters Filetransfer mode on his local system (see “Com-mand Line Switches” on page 10). However, if the remote operator is not running BLAST but a session package that uses a public do-main protocol, a “pseudohost” mode must be used. This mode is available for Xmodem, Ymodem, and Zmodem.


Pseudohost operation requires a special command line to start BLAST on the host system and to execute file transfers. The format of the command line for the remote user is:

blast [setup] -hs{x|k|y|g|z}filenameblast [setup] -hr{x|k|y|g|z}[filename]

where

setup – specifies setup file. Use this optional switch if you want to change the filetransfer parameters on the remote system.

-h – specifies host mode.

s or r – specifies either Send or Receive.

x|k|y|g|z – specifies either Xmodem, Xmodem1K, Ymodem, Ymo-dem G, or Zmodem protocol.

filename – specifies the file to be sent or received from the host UNIX. The filename must be specified for a Send. Wildcards can be used for Ymodem, Ymodem G, and Zmodem Sends. For Xmodem, the filename can be specified for a Receive; if it is not, the default filename will be /usr/tmp/XYZfile.

The following are examples of command line usage:

blast -hsxwill sends the file named “will” using Xmodem.

blast -hrx receives a file using Xmodem and saves it with the filename /usr/tmp/XYZfile.

blast ymg -hrg starts BLAST on the remote system with the setup file named “ymg” loaded and receives a file using Ymodem G.

NOTE: If the remote user accidently enters the wrong command line, there is no “graceful” exit as provided by the BLAST protocol. The terminal appears to hang until the protocol times out, which may take several minutes.

Using Log Files for Error Checking

Checking for errors after a file transfer is an important part of a good script. Messages generated during a file transfer are written to the session log file, which you can open and read as you would any other file. For example, the following script automates a BLAST session and checks for errors:


set @ftlog = "session.log" if exist @ftlog ldelete @ftlog set @LOGFILE = @ftlog filetransfer send orange fruit esc set @xferok = "NO" # initialize user flag set @LOGFILE = "" # close session log fopenr 1, @ftlog # now open it for reading.check fread 1, @logline if @STATUS = "0" # successful read strinx @logline, "send complete" # crucial! if @STATUS = "0" goto .check # no match set @xferok = "YES" # matched, set user flag end fclose 1 if @xferok = "YES" display "Transfer successful" else display "Could not transfer the file" return # or whatever else

Another log file, the error-free log, is available for similar error checking. The error-free log, or “eflog,” contains just the status mes-sages generated during a file transfer and is overwritten each time a FILETRANSFER-ESC block is executed, unlike the session log, which is always appended. Consequently, an eflog can be scanned more quickly than a session log because there are fewer lines to read and discard (see @EFLOG on page 270).

The following script fragment demonstrates how @EFLOG may be used to check for errors.

set @EFLOG = "xmodem.log"filetransfergetportland.datescfopenr 1, @EFLOG # check the logfread 1, @input # only 1 line to look at!fclose 1strinx @input, "ERROR"if @STATUS = "0" display "No error occurred."else display "Error!"


Text Transfers

The following section describes scripting for text transfers. See Text Transfers on page 145 for more information about text transfers.

Uploading TextTo upload a text file from within a script, write a BLAST script that includes: ◊ a TSEND command to start an editor to capture the data on the

remote system and any commands needed for overwriting or appending the file.

◊ a TUPLOAD statement (this will honor the setup fields for flow control—XON/XOFF, Wait for Echo, Line Delay, Character Delay, Prompt Character—and linefeed handling). The TUPLOAD command sets @STATUS to 0 if successful; it re-turns some file I/O errors.

◊ a TSEND command to exit the editor on the remote system.

When uploading to a remote computer, remember that some of the data may be buffered. This means that the upload may complete well before all the characters have passed completely to the remote sys-tem. Any activity immediately following a TUPLOAD may have to deal with both the trailing characters of the uploaded file and the de-lay before other activity can be initiated. To avoid these problems, you can:

◊ TTRAP for the characters issued by the remote system upon ex-iting the text editor.

◊ Use a WAIT IDLE statement to be sure the buffers have a chance to clear.

The sample script below assumes that the remote computer is run-ning UNIX using the text editor vi. The script TTRAPs for the file-name in quotation marks used in vi’s exit status line; the WAIT command gives the buffers on the local and remote computers time to clear.

connectTSEND "vi cih4", CR # Send cmd to start editor on remotewait 3TSEND "G", CR # Moves cursor to end of file


TSEND "o", CR # Starts new line for appendingTUPLOAD "cih4"wait 3 idleTSEND "\033", CR # Send escape cmd to remote systemwait 1TSEND ":x", CR # Send cmd to exit editor on remoteTTRAP 30, "\042cih4\042"set @hold = @statuswait 3 idleif @hold = "0" display "Tupload not completed." returnendelse display "Tupload successful."wait 10

For more specific error checking, you can check @STATUS for TUPLOAD:

connectTSEND "vi cih4", CRwait 3TSEND "G", CRTSEND "o", CRTUPLOAD "cih4"set @hold1 = @statuswait 3 idleif @hold1 = "0" display "Tupload cmd execution complete."else display "Tupload cmd failure; error ", @hold1 TSEND "\033", CR TSEND ":q!", CR # Quit editor without saving file returnendTSEND "\033", CRwait 1TSEND ":x", CRTTRAP 30, "\042cih4\042"set @hold2 = @statuswait 3 idleif @hold2 = "0" display "Tupload not completed." returnendelse display "Tupload completed."wait 5


Downloading TextTo download a text file from within a script, write a BLAST script that includes a TCAPTURE statement. TCAPTURE will receive the specified file from the remote system and activate capture to receive it.

While TTRAP handles a small number of characters for processing by a BLAST script, TCAPTURE accepts large amounts of data and saves it to a disk file. The APPEND option writes the captured data to the end of an existing file or creates a new file. The OVERWRITE option deletes and recreates an existing file or creates a new file. If BLAST is unable to use the specified file, the statement will set @STATUS to an error code.

Once capture has been enabled, the program must execute one of the following statements before capture begins: TERMINAL, TTRAP, TUPLOAD, or WAIT (with CARRIER or IDLE option). To close the file and save any data that has been captured, use TCAPTURE OFF. The following example shows how a file can be displayed and cap-tured from a remote computer:

connectTSEND "cat payroll.dat", CRTCAPTURE ON "payroll.cap" # turn capture onwait 5 idle # wait for data to stopTCAPTURE OFF # end capture, close file



Chapter 14

Connecting and Disconnecting

Introduction

Connecting and disconnecting are crucial operations. Normally, BLAST initializes the modem and dials a remote system under the control of a specialized script called “modems.scr.” Logging into a remote system, such as a VMS or a UNIX-based computer, is like-wise handled by a special script called “systems.scr.” These scripts are called by BLAST when the Connect command is issued from a menu or the CONNECT statement is executed in a script. Disconnect-ing is managed in a similar way by modems.scr and systems.scr. It’s important to understand the structure and operation of these two scripts—and how you can modify them.

BLASTscript Libraries

Modems.scr and systems.scr are called script “libraries” and provide the information that BLAST needs to control your modem and to log

CONNECTING AND DISCONNECTING 211

onto remote computers. These libraries are collections of scripts combined into large files and indexed for rapid access. BLAST au-tomatically chooses the proper scripts from these libraries based on the values of the System Type and Modem Type setup fields. If you should choose to modify either modems.scr or systems.scr, be sure to make a backup copy of the file first under another name. As with any other script file, modems.scr and systems.scr should always be saved as text-only or ASCII files. Do not save them as word-proces-sor files.

These script libraries are activated through menu commands or script commands, as follows:

Connect – Uses commands in modems.scr and systems.scr to dial out and log onto the remote system.

Upload – Uses commands in systems.scr to prepare the remote com-puter for the text upload.

Filetransfer – Uses commands in systems.scr to start BLAST on the remote computer.

Disconnect – Uses commands in modems.scr and systems.scr to log off the remote system and hang up the modem.

By automating these processes, BLAST allows you to exchange in-formation between many different computer types without requiring technical proficiency in each system.

Modem ControlThe modems.scr library handles a wide range of different modems, some of which may use proprietary commands to perform functions under computer control. BLAST uses the Modem Type setup field or the @MODEM reserved variable to select the proper script from this library and the Originate/Answer setup field or the @ORGANS re-served variable to tell the modem either to originate or to wait for calls.

Remote System ControlThe systems.scr library controls the commands sent to the remote computer. By using this library, your system can start BLAST in host mode on the remote computer. BLAST also uses this library to control text uploading. BLAST uses the System Type setup field or the @SYSTYPE reserved variable to select the proper script from this library.

212 CHAPTER FOURTEEN

Creating New LibrariesYou can create alternate system and modem control files that con-tain only the necessary commands for your particular hardware—this is more efficient than the standard libraries that include many modems and systems that you are not likely to need. BLAST will al-ways look for individual files in the directory specified by the BLASTDIR environment variable before using the standard librar-ies. For example, if you specify tblazer in the Modem Type setup field or set @MODEM to tblazer, CONNECT will use a stand alone script named tblazer.scr, if it exists, to control modem handling in-stead of the tblazer entry in modems.scr.

The Connection Process in DetailThe modems.scr library can be used to automate the connect pro-cess. If the Modem Type setup field is empty or set to “hardwire,” BLAST assumes that your system is hardwired to the remote com-puter and modems.scr is not opened.

When a Modem Type has been selected and the Originate/Answer setup field is set to ANSWER, control is passed to the .ANSWER sec-tion in modems.scr, which initializes the modem and waits for the call.

When the Originate/Answer field is set to ORIGINATE and the Connect command or CONNECT statement is used, control is passed to the .DIAL section. If a phone number is specified in the phone number field, .DIAL sends the phone number characters field to the modem as a dial command. If the Phone Number field is empty, .DIAL prompts the user to enter a number. After dialing, it waits for a message from the modem indicating a successful connection has been made.

If a System Type is specified, the corresponding .LOGON section in systems.scr is called for logging onto the remote system. If System Type is empty, BLAST assumes that you do not want system han-dling and the Connect process ends, returning you to the Online menu or the calling script with @STATUS set to 0.

If an error is detected by modems.scr or systems.scr, the scripts re-turn to BLAST with @STATUS set to reflect one of the errors listed below:

0 No error1 Unable to initialize the modem (modems.scr)2 No answer (modems.scr)


3 Can't log in: wrong userid, password (systems.scr)4 No Carrier (modems.scr and systems.scr)5 Busy (modems.scr)6 No Dialtone (modems.scr)7 Error (modems.scr)8 OK unexpected (modems.scr)

Your script can check @STATUS to determine whether a connection is successful.

The Disconnection Process in DetailThere are four ways to disconnect from another system:

◊ You can select Terminal from the Online menu and manually type the appropriate commands to the modem and the remote computer.

◊ You can select Disconnect from the Online menu and allow BLAST to automate the process through the systems.scr and modems.scr libraries.

◊ You can write a BLAST script that uses the DISCONNECT statement, which operates similarly to the Disconnect com-mand.

◊ You can physically hang up the modem by powering off. This is, of course, not recommended.

The Disconnect process attempts to log off the remote computer us-ing the .LOGOFF section in systems.scr. Control is then transferred to the .HANGUP section in modems.scr to hang up the modem.

If an error is detected by modems.scr or systems.scr, the scripts re-turn to BLAST with @STATUS set to reflect one of the errors listed below:

0 No error1 Unable to initialize the modem (modems.scr)3 Can't log out correctly (systems.scr)

Sample Modem ScriptThe following script illustrates the parts of a modem script. You can incorporate this script into modems.scr or keep it as a separate file, quick.scr. If you incorporate the script into modems.scr, you must index the script (see “The Index Utility” on page 216). If you incor-


porate and index the script, it will appear automatically as a new mo-dem type in the Modem Type setup field. Otherwise, you must enter it manually into the Modem Type setup field.

:QUICK# A sample modem control script illustrating the# required sections .DIAL, .ANSWER, .HANGUP, and# .END.#.DIAL if NULL @PHONENO ask "enter phone number", @PHONENO if NULL @PHONENO or @STATUS = "-1" return 1 end tsend "ATDT", @PHONENO, CR ttrap 45, "CONNECT", "NO CARRIER", "BUSY", "NO DIAL" if @STATUS = "1" ttrap "\015" return 0 end let @STATUS = @STATUS + 2" # set up return code return @STATUS#.ANSWER tsend "ATS0=1", CR ttrap "CONNECT" return 0#.HANGUP drop dtr wait 2 raise dtr return 0#.END:## End of quick.scr

The required sections for a modem script are .DIAL, .ANSWER, .HANGUP, and .END. The appropriate section is activated when the Connect or Disconnect commands are given. The .END section ter-minates the script (or separates the script from the next one in mo-dems.scr) and requires a final colon(:). With this sample, you should be able to write your own modem scripts or modify the scripts in modems.scr. Likewise, you can modify or enhance the system scripts in systems.scr.


The Index Utility

Three files used by BLAST contain an index at the beginning of the file: blast.hlp, modems.scr, and systems.scr. Each index contains references to specific sections in the file. For instance, modems.scr contains a BLASTscript section to control the US Robotics Courier modem. The index at the beginning of modems.scr contains a refer-ence to this section.

Indexing a file allows BLAST to jump to a particular section of a file quickly. Each section of the file should begin with a label in the form:

:LABEL

The index itself is in the form of lines of text, each beginning with the greater-than sign (>). The Index utility adds the numeric refer-ences that send control to the referenced section of the file.

If you modify any of these three files, the index must be recalculated so that BLAST can read the file properly. For example, if you add a new system type to systems.scr or add your own Online Help text to blast.hlp, you must run the index utility copied to your BLAST di-rectory during installation to re-index the file. Indexing should only be performed on these three files. Before modifying or re-indexing any of these files, however, be sure to make a backup copy of the file under another name and save the file you are modifying as text-only or ASCII.

If you create a separate modem script, such as mymodem.scr and en-ter mymodem as the Modem Type in a setup, indexing is not re-quired. If you modify any of the three standard files, however, you must re-index them. Follow this procedure to index a file:

1. Make a backup copy of the original file under another name.

2. Make the required changes to the original file.

3. Delete the old index lines from the file.

4. Save the file as text-only.

5. Rename the file.

6. Type the following command:


index oldfile newfile

where oldfile is the modified file and newfile is the name of the new indexed file. For example, if you modified systems.scr and saved it under the name sys.scr, you would type the follow-ing:

index sys.scr systems.scr

Remember also that BLAST will not operate properly if the fi-nal name of the file is not exactly as described above, that is, ei-ther systems.scr, modems.scr, or blast.hlp.



Chapter 15

BLASTscriptCommand Reference

Introduction

As you learned in Chapter 12, BLAST’s script commands are En-glish-like statements that automate communications functions. This chapter defines and illustrates the use of BLAST’s script commands.

To use the script commands correctly, you must understand the data types supported by BLASTscript and the syntax rules defining a le-gal script statement.

Data Types

All data is stored as strings. The number of characters in a string is limited to the following:

BLASTSCRIPT COMMAND REFERENCE 219

VariablesVariables start with “@”, followed by up to eight characters. For ex-ample:

@X@Fred@123

Names are not case-sensitive. Thus @Fred, @fred, and @FRED all refer to the same variable.

Numeric ConstantsNumeric constants are sequences of digits enclosed in double quota-tion marks. They may not be preceded by a minus sign. For example:

"4""4789""56"

Numeric StringsNumeric strings are sequences of digits enclosed in double quotation marks. Numeric strings may be preceded by a minus sign. For exam-ple:

"-4""4789""-56"

Numeric ValuesNumeric values may be variables, numeric constants, or numeric strings as defined above.

String ConstantsString constants are alpha-numeric sequences enclosed in double quotation marks. For example:

10.7x 139 characters

10.8x 1,024 characters

220 CHAPTER FIFTEEN

"THIS IS A STRING CONSTANT""12345"".123ABC"

String constants may contain special control characters:

\r carriage return\l linefeed\f formfeed\b backspace\t tab\\ backslash character\xxx where xxx is the three-digit octal value of the character ex-

cept for the octal value of null (\000), which is not permit-ted because null characters are treated as end-of-string characters. When encountered, nulls stop string processing.

Specifically, keep the backslash character in mind in writing scripts when your remote computer is a PC running DOS. If you quote a pathname, you will need to use double backslashes, as in the follow-ing example:

set @mydir = "\\DOS\\cih"filetransfersendcih@mydir

esc

If you want to include quotation marks in a DISPLAY or WRITE statement, a backslash must precede the quotation marks; otherwise, BLAST interprets the second quotation mark as the end of the string. For example, to display the following

Processing “Weekly Reports” -- please wait.

your script statement would be:

display "Processing \"Weekly Reports\" -- please wait."

Control characters may be coded in a string by preceding the char-acter with “^”. For example, ^M is equivalent to \r and \015:

set @msg = "3 carriage returns: ^M, \r, \015"

To code a single ^ in a string, two ^ characters are coded together.


String ValuesString values may be string constants or variables as defined above.

Reserved VariablesReserved variable values correspond to setup fields and physical or logical program conditions. See Chapter 16 for more information.

Syntax Rules

The number of characters in a script statement is limited to:

Indentation makes code easier to read and has no effect on operation. Commands and variable names are not case-sensitive. Thus,

SET @FILENAME = "default.su"

is equivalent to

set @filename = "default.su"

If strings are numeric values, mathematical operations (+, -, *, /) can be performed in a LET statement. Parentheses are not allowed, how-ever, and expressions are evaluated left to right without precedence.

Comment lines begin with “#”. Comments may also be placed on the same line as a BLASTscript statement by putting a # in the line; all characters from the # to the end of the line are treated as a com-ment.

10.8x

Binary VariablesBinary variables contain binary data. For example, the variable specified in a HEX2BIN command statement is a binary variable. Because these variables can contain nonprintable characters (nulls, for example), the contents of the variables may not display correct-ly on the screen.

10.7x 131 characters

10.8x 1,024 characters

222 CHAPTER FIFTEEN

Every line in a script must be executable or contain a comment. As a consequence, blank lines, which are rarely executable, cannot be used to separate script code visually.

BLASTscript is highly space-sensitive. When in doubt, separate all elements of a statement with spaces and enclose all constants, strings, or numerals in quotation marks. For example:

set @variable = "hello, world"

Commands That Set @STATUS

A number of script commands set the value of @STATUS, indicat-ing whether the command was executed successfully. In general, @STATUS is set to 0 to indicate success. Some commands that re-turn numeric results (e.g., STRINX, TTRAP) set @STATUS to 0 to indicate a null condition. The following commands set @STATUS:

SET Statements that Set @STATUSAdditionally, @STATUS is set when you issue a SET command for a reserved variable that has a corresponding setup field; in this case, the change in the variable will occur immediately and will set @STATUS based on the success or failure of the change. For exam-ple, if you issue the following command:

set @PARITY = "ODD"

@STATUS will be set based on the success or failure of setting @PARITY to ODD.

ASCIIASKCALLCONNECTDISCONNECTDROPFCLOSEFILETRANSFERFOPENAFOPENR

FOPENWFREADFREADBFREWINDFWRITEFWRITEBLCHDIRLDELETELLISTLOAD

LOCAL SYSTEMLPRINTLRENAMELTYPENEWRAISEREMOVERETURNSELECTSTRINX

STRRINXSTRLENSYMTYPETCAPTURETSENDTSENDBINTTRAPTUPLOADWAIT CARRIERWAIT IDLE


10.8x Manipulation of Binary Data

BLAST Professional UNIX 10.8x permits manipulation of binary data using the reserved variables @FILECNT, @SYMTYPE, and @TRAPCNT (see Chapter 16) and the following BLASTscript com-mands— BIN2HEX, CHECKSUM, FREADB, FWRITEB, HEX2BIN, SYMTYPE, TRAPNULLS_ON, and TSENDBIN. For a full discus-sion of the function of these commands, see the description of spe-cific commands below.

BLASTscript Commands

This section is organized alphabetically by command. The following conventions are used throughout:

[ ] Indicates that enclosed phrases or characters are op-tional.

... Indicates that the preceding statement or line may be repeated.

{ xx | yy } Indicates that either the xx or yy phrase is required. Choose only one.

10.8x Following the name of the command, indicates that the command is supported by 10.8x only.

ASCII

get ASCII value of a character

FORMAT: ASCII string_value, numeric_value

ASCII sets @STATUS to the ASCII value of the character at posi-tion numeric_value within string_value. The first position is 1. The ASCII value is the decimal value given to the ASCII character. For these values, see Appendix D.

EXAMPLE:

set @filename = "\\path\\filename"ASCII @filename, 1 # get ASCII value for first

# character in @filename--# ASCII 92 is a backslash (\)

if @STATUS = "92" display @filename, " is a full pathname"

224 CHAPTER FIFTEEN

ASK

prompt for a string from the user

FORMAT: ASK [NOECHO] string_value, variable

ASK prompts the user with string_value displayed at the top left of the screen. The input from the user will be placed in variable. Be-cause of display limitations, the combined length of string_value and variable should not exceed 80 characters.

The NOECHO option causes BLAST to suppress user input. Use NOECHO when entering a password or other sensitive data. If the user replies to the ASK prompt by pressing ESC, @STATUS will be set to a nonzero value. If the input ends with ENTER, @STATUS will be set to 0 unless variable is a reserved variable that sets @STATUSin a SET statement. In this case, @STATUS is set based on the suc-cess or failure of the SET command. (see “SET Statements that Set @STATUS” on page 223).

EXAMPLE:

ASK "what month", @monthASK NOECHO "Password?", @secret # no display

BIN2HEX 10.8x

convert binary byte count to hexadecimal

FORMAT: BIN2HEX numeric_value, variable1, variable2

BIN2HEX converts the first number of bytes (numeric_value) in variable2 into the hexadecimal equivalent of an ASCII string and stores the result in variable1.

NOTE: If numeric_value is larger than 512 bytes, the result of BIN2HEX will be too large for variable1. The size of variable1 will always be twice as large as numeric_value because a binary charac-ter becomes a two-byte pair in hexadecimal.

EXAMPLE:

BIN2HEX 10, @buf, @arg1 # converts first 10 bytes of # @arg1; stores result in @buf.


CALL

call another script

FORMAT: CALL string_value

CALL loads and executes another BLAST script, after which the called script returns to the calling script. String_value contains the filename of the called program. On return, @STATUS is set to the value of the exit code in the called program’s RETURN statement or to 0 if no exit code value is given. Since all values are global, any values set in the calling script will be retained in the called script and vice versa. CALL searches for the script name in the following order:

1. Files without “.scr” extension in current working directory.

2. Files with “.scr” extension in current working directory.

3. Files without “.scr” extension in SETUPDIR directory.

4. Files with “.scr” extension in SETUPDIR directory.

EXAMPLE:

CALL "BACKUP.SCR"if @STATUS = "0" display "Backup Successful"

CHECKSUM 10.8x

generate checksum of a string

FORMAT: CHECKSUM numeric_value1, numeric_value2, var1, var2 , [var3...]NOTE: var=variable

CHECKSUM generates a checksum or CRC from a string (variable2 and any additional variables) and stores it as the hexadecimal equiv-alent of ASCII data in variable1. Numeric_value1 specifies the type (checksum or CRC); numeric_value2 specifies the compliment (0 or 1):

TYPE COMPLIMENT1 = 8-bit envoy LRC 0 = normal2 = 16-bit CRC 1 = one’s compliment3 = 32-bit CRC4 = 8 checksum5 = 16 checksum6 = 32 checksum7 = Motorola pager 3-byte ASCII checksum

226 CHAPTER FIFTEEN

EXAMPLE:

CHECKSUM 2, 0, @mylrc, @reply, @etx## 16-bit CRC; 0 compliment; hexadecimal checksum of @reply# and @etx is stored in @mylrc.

CLEAR

clear the scrolling region

FORMAT: CLEAR

CLEAR clears the scrolling region of the screen.

EXAMPLE:

CLEAR

CLEOL

clear to the end of the line

FORMAT: CLEOL

CLEOL clears from the current cursor position to the end of the cur-rent line in the scrolling region.

EXAMPLE:

CLEOL

CONNECT

connect to a remote

FORMAT: CONNECT

CONNECT directs BLAST to execute routines in the modems.scr and systems.scr libraries to dial the modem and log on if the Modem and System Type setup fields are specified. For more information about the operation of the CONNECT command, see Chapter 14.

EXAMPLE:

CONNECTif @STATUS = "0" display "OK"


CURSOR

position the cursor within the scrolling region

FORMAT: CURSOR numeric_value1, numeric_value2

CURSOR positions the cursor to a given row (numeric_value1) and column (numeric_value2) in the 20 x 80 scrolling region. The row ranges from 0 to 19, and the column ranges from 0 to 79. If @USERIF is set to 0 or OFF, the full 24 x 80 screen will be ad-dressed.

Use PUT statements following cursor position to write on the screen.

EXAMPLE:

CURSOR 4, 10 # move to row 4, column 10put "1. Get sales figures"CURSOR 6, 10put "2. Send pricing"ask "enter option (1 or 2)", @opt

DISCONNECT

disconnect from a remote

FORMAT: DISCONNECT

DISCONNECT directs BLAST to execute routines in systems.scr and modems.scr to log off and hang up the modem if the System and Modem Type setup fields are specified. See Chapter 14 for a full dis-cussion.

EXAMPLE:

DISCONNECTif @STATUS = "0" display "OK"

DISPLAY

display strings to display region

FORMAT: DISPLAY string_value, ...

DISPLAY displays messages in the scrolling region of the screen. If a log file has been specified, these messages will also be sent to the log file.

EXAMPLE:

DISPLAY "Dialing...", @PHONENO

228 CHAPTER FIFTEEN

DROP

drop DTR / RTS

FORMAT: DROP { DTR | RTS }

DROP terminates signals on the RS-232 interface. If the value is DTR, the Data-Terminal-Ready signal drops, hanging up most mo-dems (cable and modem configuration permitting). If the value is RTS, the Request-to-Send signal drops, causing some devices to stop transmitting. The success of the DROP DTR and DROP RTS commands are dependent on the device driver being able to drop the signal on the serial port hardware.

EXAMPLE:

DROP DTR # drop DTR signalDROP RTS # drop RTS signal

ECHO

enable/disable script display

FORMAT: ECHO { ON | OFF }

ECHO traces BLASTscript statements and displays them on the screen as they are executed. They are also echoed to the log file, if one is specified.

When executing CONNECT and DISCONNECT statements, the statements in the modems.scr and systems.scr libraries will also echo. If you do not wish to see all these statements, turn ECHO ON only as needed.

Because the statements displayed by ECHO are interspersed with the standard interactive dialog, ECHO is particularly useful in under-standing what activity is triggered by what response within a BLAST script.

EXAMPLE:

ECHO ON # set echo onECHO OFF # set echo off


ERRSTR

store script error text

FORMAT: ERRSTR numeric_value, string _variable

ERRSTR puts the English language error message corresponding to numeric_value in string_variable. This statement is commonly used in association with the reserved variable @SCRIPTERR, which con-tains the number of the last BLASTscript error encountered.

For a list of error messages, see Appendix A. Note that not all error messages listed are possible errors in all versions of BLAST; some are operating system specific.

EXAMPLE:

fopenr 1, "nonexist.fil"if @STATUS not = "0" ERRSTR @SCRIPTERR, @MESSAGE display "ERROR #", @SCRIPTERR, "-", @MESSAGEend

FCLOSE

close an open file

FORMAT: FCLOSE numeric_constant

FCLOSE closes an open file. Numeric_constant is a number, called a handle, that other file statements use to refer to the file. The file handle can range from 1 to the number of file handles available through the operating system. If FCLOSE is successful, @STATUS is set to 0.

EXAMPLE:

fopenr 1, "input.fil" # open file 1 for readingFCLOSE 1 # close file 1

FILETRANSFER FILE

perform commands from a BLAST TCF

FORMAT: FILETRANSFERFILEfilenameESC

230 CHAPTER FIFTEEN

In BLAST protocol, this multi-line statement performs commands read from a transfer command file (TCF). Filename is the name of a transfer command file, which may be specified with a string vari-able. See “Transfer Command File” on page 115 for a complete de-scription of the transfer command file format.

EXAMPLE:

FILETRANSFERFILEcommand.filESCdisconnectquit

FILETRANSFER GET / SEND

get/send file

FORMAT: FILETRANSFER FILETRANSFERGET SEND{protocol-dependent string(s) ...} {protocol-dependent string(s) ...}ESC ESC

These statements transfer files to and from the remote computer. The exact syntax is protocol-dependent. For a full description of the syntax of the individual protocols, see “File Transfers with BLAST Session Protocol” on page 194 and the sections on scripting file transfers for the other supported protocols in Chapter 13.

EXAMPLE:

set @protocol = "BLAST"set @new = "usr/blast/readme"FILETRANSFER # enter Filetransfer modeGET # get a file with BLASTgetme.fil # remote filename@new # local filename stored in a variableto # text conversion and overwriteSEND # send a file with BLAST*.DOC # might be lots of these files...% # resolve multiple names with %

SEND # send a file with no remote filenamesamename.fil # this will also be the remote name

t # send as text fileESC # end BLAST protocol session


FILETRANSFER LOCAL

perform local commands using BLAST protocol

FORMAT:

FILETRANSFER

This multi-line statement performs Local menu commands within a FILETRANSFER-ESC block using BLAST protocol or, in BLAST Professional UNIX 10.8x, using FTP. Note that Local menu com-mands may also be performed with the LLIST, LDELETE, LPRINT, LTYPE, LRENAME, and LCHDIR statements.

LOCAL is followed by one or more commands. Most of the com-mands are followed by a filename, which may include wildcards or a string variable. Please note that lengthy local functions may force either the remote system or your system to time out, so keep local functions as short as possible or change the Inactivity T/O setup field to allow more time.

LIST – Display your local directory listing. The line after LIST must specify either SHORT or LONG. The second line after LIST can be left blank to display all files or it can be a file-name, which may include wildcards (e.g., *.txt).

DELETE – Delete a file or files on your system. The line following DELETE is the filename, which may include wildcards.

RENAME – Rename a file on your system. The line after RENAME is the old filename; the second line after RENAME is the new filename.

TYPE – Type a file on your system’s display. The line following TYPE is the filename.

PRINT – Print a file to the device specified in the BPRINTER en-vironment variable. The line following PRINT is the file-name (see LPRINT on page 247).

CHDIR – Change the working directory of your system. The line following CHDIR is the pathname of the new working di-rectory.

10.8x perform local commands using FTP

LOCAL{LIST | DELETE | RENAME | TYPE | PRINT | CHDIR | SYSTEM}{SHORT | LONG} filename oldname filename filename pathname commandfilename ESC newname ESC ESC ESC ESCESC ESC ESC ESC ESC ESC ESCESC ESC

232 CHAPTER FIFTEEN

SYSTEM – Perform a local system command. The line following SYSTEM is a system command. If this line is left blank, BLAST invokes the operating system interactively. When you are finished with the command interpreter, you must return to BLAST by typing exit and pressing ENTER. When BLAST is started with the -b switch (or with the -n switch if the display has not been re-enabled through a script), you cannot escape to a system prompt (see “Command Line Switches” on page 10).

EXAMPLE:

set @protocol = "BLAST"FILETRANSFER # start BLAST session protocolgetdaily.datnew.dattoLOCAL # begin LOCAL commands PRINT new.dat RENAME new.dat old.dat ESC # end LOCAL commandssendsendme.filtoyou.filtESC # end BLAST protocol session

FILETRANSFER MESSAGE

send messages using BLAST Protocol

FORMAT: FILETRANSFERMESSAGEmessageESC

Using BLAST protocol, MESSAGE sends a text string that is dis-played in the scrolling region of both computers’ displays. The line after MESSAGE is a message—a line of text up to 67 characters or a variable containing a line of text up to 67 characters.


EXAMPLE:

FILETRANSFER # enter Filetransfer modeMESSAGE # send a messageSending Sales Reports # specify the messageESC

FILETRANSFER REMOTE

perform remote commands

FORMAT for BLAST protocol:

FILETRANSFER

This multi-line statement performs error-free file management on the remote computer during a BLAST protocol session. Multiple commands may follow the REMOTE command, and filenames (valid pathnames for the remote computer) or string variables may follow each command. Some older versions of BLAST do not support REMOTE commands.

During a BLAST session, the following commands are available:

LIST – Display the remote directory listing. The line after LIST must specify either SHORT or LONG. The second line after LIST can be left blank to display all files or it can be a file-name, which may include wildcards (e.g., *.txt).

DELETE – Delete a file or files on the remote system. The line fol-lowing DELETE is the filename, which may include wildcards.

RENAME – Rename a remote file. The line after RENAME is the old filename; the second line after RENAME is the new file-name.

TYPE – Type a remote file on your system’s display. The line fol-lowing TYPE is the filename.

PRINT – Print a remote file to the remote printer. The line follow-ing PRINT is the filename.

REMOTE{LIST | DELETE | RENAME | TYPE | PRINT | CHDIR | MORE}{SHORT | LONG} filename oldname filename filename pathname ESCfilename ESC newname ESC ESC ESC ESCESC ESC ESC ESC ESC ESCESC ESC

234 CHAPTER FIFTEEN

CHDIR – Change the working directory on the remote computer. The line following CHDIR is the pathname of the new working directory

MORE – Continue displaying data from the remote computer after a page pause.

FORMAT for Kermit server protocol:

FILETRANSFER

During a Kermit server protocol session, the available commands depend upon both the version and the configuration of the remote Kermit server. A command may fail if the remote Kermit server does not support the command. You must start Kermit remote server on the remote system before entering Kermit Filetransfer mode. Kermit remote commands include:

DIRECTORY – Display a directory on the remote server. The line after DIRECTORY is the pathname (with or without

10.8x

FORMAT for FTP:

FILETRANSFERREMOTE{LIST | DELETE | CWD}{SHORT | LONG} filename pathnamefilename ESC ESCESC ESC ESCESC

During an FTP session, the following commands are available:

LIST – Display the remote directory listing. The line after LIST must specify either SHORT or LONG. The second line after LIST can be left blank to display all files or it can be a filename, which may include wildcards.

DELETE – Delete a file or files on the remote system. The line following DELETE is the filename, which may include wildcards.

CWD – Change the working directory on the remote computer. The line following CWD is the pathname of the new working directory.

REMOTE{DIRECTORY | ERASE | TYPE | CWD | SPACE | WHO | MESSAGE | HOST | KERMIT | HELP}pathname filename filename pathname pathname user message command message ESCpassword ESC ESC ESC ESC ESC ESC ESC ESC ESCESC ESC ESC ESC ESC ESC ESC ESC ESCESC


wildcards) of the remote directory for which you want a listing; if you leave this line blank, the cur-rent working directory listing of the remote server will be displayed. The second line after DIRECTORY is the password that may be required to gain access to the directory listing. If no password is required, leave this line blank.

ERASE – Delete a file on the server. The line following ERASE is the filename (with or without wildcards) of the file to be erased. If you do not specify a full path for the file, the file (if it exists) will be removed from the current working di-rectory of the remote server.

TYPE – Display a remote-server file on your screen. The line fol-lowing TYPE is the filename of the file to be displayed. Kermit does not support a page pause, so you must use CTRL

S to pause and CTRL Q to resume the flow of data.

CWD – Change the server’s working directory. The line following CWD is the pathname of the new working directory.

SPACE – Display unused drive space of a directory on the remote server. The line following SPACE is the pathname (with or without wildcards) of the directory for which unused drive space is to be reported.

WHO – Display information on user(s) currently logged onto the server. The line following WHO is the user for whom you want information. If you leave this line blank, information on all users logged onto the server will be displayed.

MESSAGE – Send a one-line message to be displayed to the remote operator. The line following MESSAGE is the one-line message to be displayed to the remote operator.

HOST – Send an operating system command to the server. The line following HOST is the operating system command sent to the remote server. The command is executed immediately.

KERMIT – Send a Kermit language command to modify session pa-rameters. The line following KERMIT is the message (Kermit language command) to be issued to the Kermit server, for example, SET FILE TYPE BINARY.

HELP – Display a short list of the available commands on the server.

EXAMPLE:

tsend "kermit -x", CR # start kermit server on remoteFILETRANSFER # enter Filetransfer modeget

236 CHAPTER FIFTEEN

daily.datnew.datREMOTE # start REMOTE commands CWD /usr/customer TYPE contactlist.txt ESC # end REMOTE commandssendsendme.filtoyou.filESC # end Kermit protocol session

FLUSH

clear the input buffer

FORMAT: FLUSH

FLUSH clears the communications port input buffer. Only charac-ters received after the FLUSH command has been executed will be available.

EXAMPLE:

FLUSH # empty bufferttrap 10, "@" # trap for "@"

FOPENA

open a file for appending

FORMAT: FOPENA numeric_constant, string_value

FOPENA opens a file for appending. If the file does not exist, it will be created. If it does exist, it will be opened and subsequent writes will append data to the end of the file. String_value is the filename of the file to be opened. Numeric_constant is a number, called a han-dle, that other file statements use to refer to the file. The file handle can range from 1 to the number of file handles available through the operating system. If FOPENA is successful, @STATUS is set to 0.

EXAMPLE:

FOPENA 1, "script.log" # open file 1 for appendingfwrite 1, "got this far" # adds string to the filefclose 1 # close file 1


FOPENR

open a file for reading

FORMAT: FOPENR numeric_constant, string_value

FOPENR opens a file for reading. The file must already exist. String_value is the filename of the file to be opened. Numeric_constant is a number, called a handle, that other file state-ments use to refer to the file. The file handle can range from 1 to the number of file handles available through the operating system. If FOPENR is successful, @STATUS is set to 0.

EXAMPLE:

FOPENR 1, "command.fil" # open file 1 for reading fread 1, @input # read the first line fclose 1 # close file 1

FOPENW

open a file for writing

FORMAT: FOPENW numeric_constant, string_value

FOPENW opens a file for writing. If the file does not exist, it will be created. If it does exist, all data in the file is overwritten. String_value is the filename of the file to be opened. Numeric_constant is a number, called a handle, that other file state-ments use to refer to the file. The file handle can range from 1 to the number of file handles available through the operating system. If FOPENW is successful, @STATUS is set to 0.

EXAMPLE:

FOPENW 1, "cscript.log" # open file 1 for writingfwrite 1, "got this far" # write string to file 1fclose 1 # close file 1

FREAD

read a line from a file

FORMAT: FREAD numeric_constant, variable

After an FOPENR command, FREAD reads a line of text into a vari-able. Numeric_constant is the file handle assigned the file in the FOPENR statement. If FREAD is successful, @STATUS is set to 0. A nonzero value indicates an error reading the file or end of file.

238 CHAPTER FIFTEEN

EXAMPLE:

fopenr 1, "command.fil" # open file 1 for readingFREAD 1, @input # read line into @inputif @STATUS not = "0" display "End of file reached"endfclose 1 # close file

FREADB 10.8x

read a file as binary data

FORMAT: FREADB numeric_value1, variable, numeric_value2

FREADB reads up to a maximum number of bytes (numeric_value2) from the file specified by numeric_value1 (the file handle assigned the file in the FOPENR statement) and stores the result in variable. The reserved variable @FILECNT stores the actual number of bytes read.

EXAMPLE:

FREADB 2, @line, 100 # reads up to 100 bytes from file # handle 2 into @line.

FREE

release a variable from memory

FORMAT: FREE variable

FREE releases memory allocated to the specified variable. To recov-er all memory, you must FREE variables in the reverse order in which they were defined.

EXAMPLE:

FREE @input

FREWIND

rewind a file

FORMAT: FREWIND numeric_constant

FREWIND “rewinds” a file by resetting the file pointer to the begin-ning of the file. Numeric_constant is the file handle assigned the file in an FOPENR, FOPENW, or FOPENA statement. If FREWIND is successful, @STATUS is set to 0.


EXAMPLE:

fopenr 1, "commands.fil" # open file 1 for readingfread 1, @input # read first line of file 1FREWIND 1 # rewind file 1fread 1, @also # read first line againfclose 1 # close file 1

FWRITE

write a line to a file

FORMAT: FWRITE numeric_constant, string_value,...

After an FOPENW command, FWRITE writes out a series of one or more strings to a file as a single line of text. Numeric_constant is the file handle assigned the file in an FOPENW or FOPENA statement. If FWRITE is successful, @STATUS is set to 0.

EXAMPLE:

fopenw 1, "output.fil"FWRITE 1, "the userid is: ", @USERIDfclose 1

FWRITEB 10.8x

write a file as binary data

FORMAT: FWRITEB numeric_value1, variable, numeric_value2

FWRITEB writes up to a maximum number of bytes (numeric_value2) from variable into the file specified by numeric_value1—the file handle assigned the file in an FOPENA or FOPENW statement. The reserved variable @FILECNT stores the ac-tual number of bytes written.

EXAMPLE:

FOPENA 2, "sales.txt"FWRITEB 2, @line, 100 # writes up to 100 bytes from @line # into file 2.

GETENV

store the value of an environment variable

FORMAT: GETENV string_value, variable

GETENV writes the value of an environment variable (string_value) to variable.

240 CHAPTER FIFTEEN

EXAMPLE:

GETENV "BLASTDIR", @result

GOTO

branch to another point in program

FORMAT: GOTO .LABEL

GOTO branches unconditionally to another location in the program. GOTO will abort the program if .label cannot be found. The label is not case-sensitive and consists of eight characters or less, not counting the initial period.

EXAMPLE:

.PWD ask "enter the secret word", @pword if @pword = "rosebud" GOTO .CONT werror "invalid name" GOTO .PWD.CONT display "Good morning, Mr. Phelps"

HEX2BIN 10.8x

convert hexadecimal to binary

FORMAT: HEX2BIN numeric_value, variable1, variable2

HEX2BIN converts the first number of bytes (numeric_value) in a hexadecimal string (variable2) into binary data and stores the result in variable1. Variable1 will be one-half the size of variable2 be-cause each byte-pair will be reduced to one character.

EXAMPLE:

HEX2BIN 10, @buf, @arg1 # converts 1st 10 bytes of @arg1;# stores result in @buf.

IF

perform single action if condition is true

FORMAT: IF condition [{and / or}...] statement

IF performs statement when condition is true. Evaluation is from left to right. Parentheses and arithmetic functions are not permitted in the condition.


The syntax of condition can be one of two forms. The first form is valid for string values only:

string_value1 [NOT][>|>=|<|<=|=] string_value2

The condition is true when string_value1 is:

> greater than

>= greater than or equal to

< less than

<= less than or equal to

= equal to

string_value2.

The comparison is based on the ASCII values and the length of the strings. If the strings are not equal, the comparison is performed on the first different character in the strings.

The second form of the conditional clause is valid for numeric val-ues only:

numeric_value1 [NOT][GT|GE|LT|LE|EQ] numeric_value2

The condition is true when numeric_value1 is:

GT greater than

GE greater than or equal to

LT less than

LE less than or equal to

EQ equal to numeric_value2.

Some special qualifiers provide an implied condition:

[NOT]NULL string_valueTrue [False] when string_value is of zero length.

[NOT]numeric_constant True [False] when numeric_constant equals @STATUS.

[NOT]REPSTrue [False] when the REPS counter is not zero (see page 186 for more information on using REPS and loops).

242 CHAPTER FIFTEEN

BLASTSCRIPT COMMAND

[NOT]True [F

[NOT]True [F

EXAMPLE:

IF EXIST "file.onIF NOT NULL @VAR IF @USERID = "FRE

The fol

IF OK GOTO .RUNIF @STATUS = "0" IF 0 GOTO .RUN

IF – ELSE

FORMAT: IF condELSE s

IF-ELdition iconditimust be

EXAMPLE:

connectIF @STATUS = "0" ELSE write "Logon

IF – END

FORMAT: IF condstatemEND

This mdition. END ar

10.8x [NOT]True [F

EXIST string_valuealse] when a file named the value of string_value exists.

OKalse] when @STATUS = "0".

e" LDELETE "file.one"Display "@VAR is not empty"D" GOTO .sendfiles

lowing three statements are all equivalent:

GOTO .RUN

perform action for true or false conditions

ition [{and / or}...] statementtatement

SE performs statement based upon condition. When the con-s true, the statement following the condition executes. When on is false, the statement after ELSE executes. Statement on the same line as condition.

write "Logged on successfully." failed!"

perform multiple actions if condition is true

ISDIR string_valuealse] when string_value is a directory.

REFERENCE 243

ition [{and / or} condition...]ent

ulti-line clause performs several statements based upon con-When the condition is true, subsequent statements up to the e executed.

EXAMPLE:

IF @USERID NOT = "Annie" display "You can't run this script!" return 1END

IF – END / ELSE – END

perform several actions for true or false conditions

FORMAT: IF condition [{and / or} condition...]statement ENDELSEstatementEND

This multi-line clause performs several statements based upon con-dition. When the condition is true, the statements up to the first END are executed. When the condition is false, the statements following ELSE and up to the END are executed.

When execution speed is important, use this statement instead of GOTO. Also, programs using this programming structure are gener-ally easier to understand and maintain than programs using GOTO.

EXAMPLE:

ask "Ok to Log on?", @answerIF @answer = "YES" display "Now Logging on" tsend @USERID, CRENDELSE display "Will not attempt to Log on" tsend "BYE", CREND

LCHDIR

change working directory

FORMAT: LCHDIR string_value

LCHDIR changes the current working directory on the local comput-er to the directory specified in the string_value. If LCHDIR is suc-cessful, @STATUS is set to 0.

244 CHAPTER FIFTEEN

EXAMPLE:

LCHDIR "work" # change directory to workif @STATUS = "0" # if the return status is 0 display "CHDIR ok" # success!end

LDELETE

delete a file on the local system

FORMAT: LDELETE string_value

LDELETE deletes from the local computer the file specified in string_value. If LDELETE is successful, @STATUS is set to 0.

EXAMPLE:

LDELETE "sales.jun"if @STATUS = "0" display "sales.jun deleted"

LET

perform simple arithmetic

FORMAT: LET variable = numeric value [{+ | – | * | /} numeric value]...

LET does simple integer arithmetic. The expression is evaluated from left to right, with no grouping or precedence. The result is placed into a variable. The maximum and minimum integer values are 32,767 and negative 32,768.

When an integer becomes too large, the high order part of the num-ber is discarded, resulting in unpredictable values. Fractional values after a division are always truncated.

EXAMPLE:

display "Polling statistics:"LET @total = @numbad + @numgooddisplay "Total sites polled: ", @totalLET @next = @next + "1"display "Next site is site number: ", @next


LLIST

display a listing of files on the system

FORMAT: LLIST [LONG] string_value

LLIST displays a directory listing on the local computer as speci-fied by string_value. Wildcards may be used. If no path is given, items from the local current directory are listed. If LONG is speci-fied, the listing will give all accompanying data rather than just the filenames and directory names.

EXAMPLE:

LLIST LONG "*"Display @STATUS, " items are in the current directory."

LOAD

load a system setup

FORMAT: LOAD string_value

LOAD loads a setup from the directory specified by the SETUPDIR environment variable. String_value is the name of the setup. If the setup is in a subdirectory of the directory specified by SETUPDIR, the relative path must be included with the filename. The setup name should not include the .su extension. This statement operates like the Offline menu Select command and the SELECT statement. If the setup has been successfully loaded, @STATUS is set to 0.

EXAMPLE:

LOAD "Blaster"if @STATUS = "0" display "Setup Blaster is the current setup"endelse display "can't load the setup Blaster"end

10.7x If the LLIST is successful, @STATUS is set to 0.

10.8x @STATUS returns the number of items that match string_value.

246 CHAPTER FIFTEEN

LOCAL SYSTEM

perform operating system command

FORMAT: LOCALSYSTEMstring_valueESC

This multi-line statement performs local operating system com-mands. The line following SYSTEM is a system command. If this line is left blank, BLAST invokes the operating system interactively. When you are finished with the command interpreter, you must re-turn to BLAST by typing exit and pressing ENTER. When BLAST is started with the -b switch (or with the -n switch if the display has not been re-enabled through a script), you cannot escape to a system prompt (see “Command Line Switches” on page 10).

EXAMPLE:

set @syscmd = "ls -l > catalog.txt"LOCALSYSTEM@syscmdESC

LOWER

convert variable to lowercase

FORMAT: LOWER variable

LOWER changes all uppercase characters in a variable to lowercase.

EXAMPLE:

ask "Enter your name:", @nameLOWER @name

LPRINT

print a file on the local printer

FORMAT: LPRINT string_value

LPRINT executes the command specified by the BPRINTER envi-ronment variable (see page 9). When BPRINTER specifies a target for printer output, LPRINT prints the file specified by string_value to that target. If the printer and file are found, @STATUS is set to 0


when the command specified by BPRINTER has been successfully executed.

EXAMPLE:

LPRINT "salesdata"if @STATUS = "0" display "print worked ok"

LRENAME

rename a file on the local system

FORMAT: LRENAME string_value1, string_value2

LRENAME renames the local file specified in string_value1 to the name specified in string_value2 on the local computer. If the rename is successful, @STATUS is set to 0.

EXAMPLE:

LRENAME "f1.dat", "f2.dat"if @STATUS = "0" display "Rename worked"

LTYPE

type a file on the local screen

FORMAT: LTYPE string_value

LTYPE types the local file specified in string_value on the screen. If the LTYPE is successful, @STATUS is set to 0.

EXAMPLE:

LTYPE "salesdata" # display salesdataif @STATUS = "0" display "LTYPE worked"

MENU

enable/disable menu display during script execution

FORMAT: MENU {ON | OFF}

MENU ON leaves the menu displayed for debugging purposes while a BLAST script is executing. Normally, menu display is suppressed during script execution.

EXAMPLE:

MENU ON # set the menu display on

248 CHAPTER FIFTEEN

NEW

create a new BLAST setup

FORMAT: NEW string_value

NEW creates a new setup in the directory specified by the SETUPDIR environment variable (see page 10) based on the current values in memory. String_value is the name of the setup. If you want to put the setup in a subdirectory of the directory specified by SETUP-DIR, the relative path must be included with the filename. The setup name should not include the .su extension.

The NEW statement operates like the Offline menu New command. If you specify a setup name that already exists, NEW will load that setup instead of creating a new one. If the setup has been successful-ly created, @STATUS is set to 0; if an already existing setup has been loaded or there has been an error creating a new setup, @STATUS is set to 1.

EXAMPLE:

NEW "CIS" # create setup named cis.suif ok display "New setup created."else display "Couldn’t create new setup."

PUT

output strings to the scrolling region

FORMAT: PUT string_value,...

PUT outputs one or more strings to the scrolling region. There is no implicit carriage return or new line after the output. This command is usually used in conjunction with the CURSOR statement.

EXAMPLE:

cursor 9, 30 # put cursor in row 9,col 30PUT "The winner is ", @win # display string at

# cursor position

PWD

store the current path in a variable

FORMAT: PWD variable

PWD writes the present working directory location to a script vari-able.


EXAMPLE:

PWD @whereami

QUIT

quit BLAST and return to system with exit code

FORMAT: QUIT numeric_constant

QUIT aborts BLAST and returns to the operating system. Numeric_constant is an exit code that can be tested by the operating system.

EXAMPLE:

QUIT 123 # exit to operating system, exit status 123

RAISE

raise DTR/RTS

FORMAT: RAISE {DTR | RTS}

RAISE raises the Data-Terminal-Ready signal (DTR) or the Re-quest-to-Send signal (RTS) on the RS-232 interface. These signals are normally used with modems. Some systems have DTR and RTS tied together so that raising either one affects both signals. The suc-cess of the RAISE DTR and RAISE RTS commands are dependent on the device driver being able to raise the signal on the serial port hardware.

EXAMPLE:

RAISE DTR # raise the DTR signalRAISE RTS # raise the RTS signal

REMOVE

remove a system setup

FORMAT: REMOVE string_value

REMOVE deletes a setup from the directory specified by the SETUPDIR environment variable. String_value is the name of the setup. If the setup is in a subdirectory of the directory specified by SETUPDIR, the relative path must be included with the filename. The setup name should not include the .su extension. If the setup has been successfully removed, @STATUS is set to 0.

250 CHAPTER FIFTEEN

EXAMPLE:

REMOVE "blaster" # delete blaster.suif @STATUS = "0" display "Setup blaster has been removed."

REPS

set repetition counter

FORMAT: REPS numeric_value

REPS creates loops in BLAST scripts. When REPS is used in an IF statement, it keeps track of the number of repetitions performed. The REPS numeric value is decremented and then tested for a value of zero. If numeric_value is a variable, the countdown occurs, but the variable retains its initial value.

EXAMPLE:

REPS 3 # loop three times.loop display "hello" IF REPS GOTO .loop # decrement; if REPS greater display "goodbye" # than 0, branch to .loop;

RETURN

return to a calling program

FORMAT: RETURN numeric_constant

RETURN returns control to the menu system or the calling BLAST script. @STATUS of the calling script is set to numeric_constant, or 0 if no numeric constant is specified.

EXAMPLE:

RETURN 1 # return with @STATUS set to 1

SAVE

save a BLAST setup

FORMAT: SAVE

SAVE saves the current setup.

EXAMPLE:

SAVE # save current setup


SELECT

select a system setup

FORMAT: SELECT string_value

SELECT loads a setup from the directory specified by the SETUPDIR environment variable. String_value is the name of the setup. If the setup is in a subdirectory of the directory specified by SETUPDIR, the relative path must be included with the filename. The setup name should not include the .su extension. This statement operates like the Offline menu Select command. If the setup has been successfully loaded, @STATUS is set to 0.

EXAMPLE:

SELECT "Blaster"If OK display "Setup successfully loaded."Else display "Couldn’t load setup."

SET

set script variables to a string

FORMAT: SET variable = string_value

SET assigns a value to a variable. SET differs from the LET state-ment in that mathematical operations cannot be performed in a SET.

EXAMPLE:

SET @command = "blast -h"SET @BAUDRATE = "9600" # set baud rate in setupSET @PARITY = "NONE" # set parity in setup

SETTRAP

capture commport data to a script variable

FORMAT: SETTRAP variable, numeric_constant1 [, numeric_constant2]

SETTRAP prepares a TTRAP command to capture incoming data into a user-defined variable. Note that SETTRAP will not perform the capture itself—one or more TTRAPs must follow. Once a SETTRAP is issued, it remains in effect until another SETTRAP is issued; therefore, one SETTRAP can be used for multiple TTRAPs.

Variable specifies the destination for the TTRAP data. It may be ei-ther a new or previously used variable.

252 CHAPTER FIFTEEN

Numeric_constant1 defines the maximum number of characters to save into the variable. It must be greater than 0 and may be up to

Only the last incoming characters, specified by numeric_constant1, will be saved. When set to 0, SETTRAP is disabled completely and the TTRAP(s) following will operate normally.

Numeric_constant2 contains the maximum amount of characters the TTRAP(s) will check for a match. If this value is reached, the TTRAP(s) will return to the calling script with @STATUS set to -5, and the TTRAP internal counter will be reset. Note that this is not on a per-TTRAP basis; the value is accumulated over one or more TTRAPs. This feature may be disabled by setting numeric_constant2 to 0 or omitting it.

EXAMPLE:

# set TTRAP to capture data into @CAP--10 chars maximum;# TTRAP exits if 85 chars are received before the TTRAP# matches a string or times outSETTRAP @CAP, 10, 85TTRAP 6, "\015" # trap next carriage returnSETTRAP @CAP, 20 # 20 chars placed in @CAP; no char TTRAP 45, "Logout" # count, so TTRAP will time out or # match a string

STRCAT

combine strings

FORMAT: STRCAT variable, string_value1[, string_value2...]

STRCAT appends string_value1 (and any additional string values) to variable.

EXAMPLE:

set @string1 = "abc"set @string2 = "xyz"STRCAT @string1, @string2 # append string2 to string1display "alpha=", @string1 # display abcxyz

10.7x 139 characters.

10.8x 1,024 characters.


STRINX

find the first occurrence of one string in another

FORMAT: STRINX string_value1, string_value2

STRINX finds the first occurrence of string_value2 in string_value1. @STATUS is set to the starting character position of string_value2 in string_value1, or set to 0 if there is no match.

EXAMPLE:

set @string1 = "0123456"STRINX @string1, "3" # look for pattern "3" display "The number 3 occurs at position ", @STATUS

STRLEN

determine the length of a string

FORMAT: STRLEN variable

STRLEN sets @STATUS to the length of variable.

EXAMPLE:

STRLEN @stringdisplay "The length of @string is", @STATUS

STRRINX 10.8x

find the last occurrence of one string in another

FORMAT: STRRINX string_value1, string_value2

STRRINX finds the last occurrence of string_value2 in string_value1. @STATUS is set to the starting character position of the last occurrence of string_value2 in string_value1, or set to 0 if there is no match.

EXAMPLE:

set @string1 = "01234567890123456"STRRINX @string1, "3" # look for last occurrence of "3"display "The number 3 occurs last at position ", @STATUS

254 CHAPTER FIFTEEN

STRTRIM

extract part of a string

FORMAT: STRTRIM variable, numeric_value1, numeric_value2

STRTRIM extracts a substring from variable. Variable is reset to the substring that begins at position numeric_value1 and ends at posi-tion numeric_value2. If the original string will be required for fur-ther processing, a copy of it should be made before operating with STRTRIM, because STRTRIM changes the contents of variable.

NOTE: Make sure to include numeric_value2; if it is omitted, variable will contain nothing.

EXAMPLE:

set @name = "Anemometer"STRTRIM @name, 4, 6display "Hi,", @name

SYMTYPE 10.8x

reports the variable type

FORMAT: SYMTYPE variable

SYMTYPE determines the type (NONE, BINARY, STRING) of vari-able and reports the results in both @SYMBOLTYPE and @STATUS. @STATUS reports as follows:

0 = NONE (No variable of that name exists.)1 = BINARY2 = STRING

EXAMPLE:

SYMTYPE @arg1

TCAPTURE

enable text file capture

FORMAT: TCAPTURE {ON [APPEND | OVERWRITE] | OFF} string_value

TCAPTURE enables or disables text capturing while in Terminal mode. TCAPTURE ON enables Capture mode, and TCAPTURE OFF disables it. APPEND and OVERWRITE are used only with ON to in-dicate whether an existing file should be appended or overwritten. If neither is specified, APPEND is assumed.


@STATUS is set to 0 if string_value is a valid filename that can be written to; otherwise, @STATUS is set to an error code. TCAPTURE OFF does not affect @STATUS. No data is captured until one of the following is executed: TSEND, TTRAP, TUPLOAD, or WAIT with the CARRIER or IDLE option.

IMPORTANT: After issuing a TCAPTURE command, you should perform a WAIT IDLE or TTRAP to be sure that a stopping point has been reached in the data stream before exiting.

EXAMPLE:

TCAPTURE ON APPEND "test.cap" # capture on; append # to file test.capif @STATUS not = "0" # if not OK display "can't enable capture" # write to screen return 1 # return error codeendtsend "cat bob.mail", CR # send command to # the remote systemwait 10 idle # wait till no comm # port activityTCAPTURE OFF # turn capture off

TERMINAL

become a terminal

FORMAT: TERMINAL

TERMINAL puts BLAST into Terminal mode, allowing the user to interact with the remote computer. Control cannot return to the script until the user types ATTN ATTN.TERMINAL will not function if BLAST is started with the -b switch (batch mode) or -n switch (no display, unless the -n switch setting has been reset in the session—for example, in a script with the fol-lowing command: SET @SCRLREG = "ON").

EXAMPLE:

display "Script paused..."TERMINALdisplay "Script continuing..."

256 CHAPTER FIFTEEN

TRAPNULLS_OFF 10.8x

disable null traps

FORMAT: TRAPNULLS_OFF

TRAPNULLS_OFF disables the trapping of nulls; disabling null traps is the default mode.

EXAMPLE:

TRAPNULLS_OFF

TRAPNULLS_ON 10.8x

enable null traps

FORMAT: TRAPNULLS_ON

TRAPNULLS_ON enables trapping of nulls (0x00's) in order to trap binary CRC's or checksums.

EXAMPLE:

TRAPNULLS_ON

TSEND

send strings to the remote computer

FORMAT: TSEND {BREAK | CR | LF | string_value},...

TSEND sends breaks, carriage returns, line feeds, or strings to the re-mote computer. Any combination of strings, line terminating char-acters, and/or breaks can be sent.

NOTE: Some operating systems (including DOS) expect a CR/LF instead of a LF at the end of a line. Take this into consideration and use CR/LF instead of LF for these systems. You might define an end-of-line variable at the beginning of a BLAST script to make these programs easily transportable to other systems.

EXAMPLE:

set @endline = "CR"TSEND BREAK # send break signalTSEND "ATDT", @PHONENO, @endline # dial the modem


TSENDBIN 10.8x

convert hexadecimal to binary while transmitting to remote

FORMAT: TSENDBIN variable1 [,variable2...]

TSENDBIN converts the hexadecimal equivalents of an ASCII string (variable) to binary code as they are sent to the remote system. Variables must contain hexadecimal strings.

EXAMPLE:

TSENDBIN @arg1, @arg2

TTRAP

trap for output from the remote computer

FORMAT: TTRAP [MM:SS | SS,] string_value1 [,...string_value8]

TTRAP pauses the BLAST script in Terminal mode, testing data flow to the communications port. When TTRAP sees one of the string values, it continues to the next statement. If mm:ss (min-utes:seconds) is given and none of the string values is received in that length of time, TTRAP times out. TTRAP sets @STATUS to the number of the string that was found, or sets @STATUS to 0 if TTRAP timed out.

EXAMPLE:

set @x = "NO CARRIER"TTRAP 30, "CONNECT", @xif @STATUS = "0" write "Timeout on trap"if @STATUS = "1" write "Connected!"if @STATUS = "2" write "No carrier!"

TUPLOAD

upload a text file to the remote system

FORMAT: TUPLOAD string_value

TUPLOAD opens the file specified by string_value and sends the text to the remote computer. The transmission is paced by any flow con-trol options specified in the setup. TUPLOAD sets @STATUS to 0 on completion of the text upload. If the upload is unsuccessful, @STATUS is set to the applicable BLAST error code. For example, if the file could not be found, @STATUS is set to 51 (error opening data file).

258 CHAPTER FIFTEEN

Some device drivers buffer the flow of data extensively. This means the TUPLOAD statement may complete well before all the characters clear the local and remote computer buffers.

NOTE: After a TUPLOAD command has been issued, it is a good idea to TTRAP for characters signaling the end of the upload or do a WAIT mm:ss IDLE. Exiting BLAST before the buffers are emptied may cause BLAST to terminate abnormally. See “Uploading Text” on page 207.

EXAMPLE:

connecttsend "vi Sal", CR # Send cmd to start editor on remotewait 3tsend "G", CR # Moves cursor to end of filetsend "o", CR # Starts new line for appendingTUPLOAD "Sal"wait 3 idletsend "\033" # Send escape cmd to remote systemwait 1tsend ":x", CR # Send cmd to exit editor on remotettrap 30, "\042Sal\042" # trap filename in exit status lineset @hold = @statuswait 3 idleif @hold = "0" display "Tupload not completed; error ", @hold returnendelse display "Tupload successful"wait 10

UPPER

convert a variable to uppercase

FORMAT: UPPER variable

UPPER changes all lowercase characters in variable to uppercase.

EXAMPLE:

UPPER @salesdata


WAIT

wait for time to pass

FORMAT: WAIT {MM:SS | string_value}

WAIT pauses the BLAST script for mm minutes and ss seconds. String_value must be in the format mm:ss. The maximum value is 60 minutes (60:00).

EXAMPLE:

WAIT 2:02 # wait two minutes, two secondsWAIT 2 # wait two secondsWAIT 60:00 # wait one hour

WAIT CARRIER

wait for a phone call

FORMAT: WAIT {MM:SS | string_value} CARRIER

WAIT CARRIER pauses the BLAST script mm minutes and ss sec-onds, or until the modem raises carrier detect. If the modem raises carrier detect, @STATUS is set to 0. If the statement times out, @STATUS is set to a nonzero value. The maximum value is 60 min-utes (60:00). Carrier detection may not be available on some com-munications ports if the device driver does not provide the signal. Make sure that the modem and cable are configured to indicate when the carrier signal is present.

EXAMPLE:

WAIT 2:02 CARRIER # wait two minutes and # two seconds for a callWAIT 12:00 CARRIER # wait 12 minutes for a callWAIT 12 CARRIER # wait 12 seconds for a call

WAIT IDLE

wait for communications port activity to finish

FORMAT: WAIT {MM:SS | string_value} IDLE

WAIT IDLE pauses the script until no characters are received on the communications port for mm minutes and ss seconds. The maximum value is 60 minutes (60:00).

260 CHAPTER FIFTEEN

EXAMPLE:

WAIT 2:02 IDLE # wait for two minutes and # two seconds of idleWAIT 1:00 IDLE # wait for one minute of idleWAIT 1 IDLE # wait for one second of idle

WAIT UNTIL

wait for a specified time of day

FORMAT: WAIT UNTIL {HH:MM | string_value}

WAIT UNTIL pauses the script until the time is hh hours (24-hour clock) and mm minutes.

EXAMPLE:

WAIT UNTIL 2:02 # wait till 2:02 amWAIT UNTIL 1:00 # wait till 1:00 am WAIT UNTIL 13:30 # wait until 1:30 pm

WERROR

write an error message to the second menu line

FORMAT: WERROR string_constant

WERROR writes an error message to the operator and the log file. If @ONERROR is set to the default setting, STOP, WERROR pauses for a key to be pressed before continuing. Do not use this statement when writing a BLAST script that will be unattended unless @ONERROR is set to CONTINUE.

EXAMPLE:

WERROR "no response" # display error message return 1 # return with @STATUS set to 1.

WRITE

write a message to the second menu line

FORMAT: WRITE string_constant

WRITE displays a message to the operator and the log file (without pausing as in WERROR).

EXAMPLE:

WRITE "dialing CHICAGO"


262 CHAPTER FIFTEEN

Chapter 16

BLASTscript Reserved Variables

BLASTscript reserved variables are an important part of any pro-gram that tests the condition of the communication session or the re-sults of other statements.

There are two types of BLASTscript reserved variables: read-only and read/write. BLAST scripts can test a physical signal or logical condition using read-only variables. With read/write variables, scripts may not only test but also change a condition by using the SET command.

Reserved variables that reflect multiple-choice setup fields may be SET by using the value offered by the setup field. For example,

SET @DCDLOSS = "ABORT"

will change the value of the DCD Loss Response setup parameter in the BLAST protocol to ABORT.

In the following descriptions, if the reserved variable is associated with a setup field, the setup field will be indicated by italic print as the last line of the variable description. The characteristics of such

BLASTSCRIPT RESERVED VARIABLES 263

fields are described in Chapter 5. The default value of the reserved variable is indicated by bold print and brackets.

@7BITCHN read/writeYES [NO]

For BLAST protocol transfers, defines the data-path width.

BLAST Protocol subwindow: 7-Bit Channel

@ACKFREQ read/write1 – window size [4]

For BLAST protocol transfers, specifies the frequency at which an acknowledgement from the receiving system is requested. The fre-quency is measured in number of packets sent. See also @WDWSIZ (page 295).

BLAST Protocol subwindow: Ack Request Frequency

@APROTO read/writeYES [NO]

For BLAST protocol transfers, specifies whether the BLAST “A” Protocol will be used. Set this field to YES to communicate with old-er versions of BLAST.

BLAST Protocol subwindow: Use “A” Protocol

10.7x

@ANSIAUTOWRAP read/writeYES [NO]

For PC ANSI emulation, selects automatic wrapping of lines long-er than 80 characters.

ANSI Emulation subwindow: Auto Wrap

@ANSILEVEL read/write2.x [3.x]

For PC ANSI emulation, selects the correct level of ANSI for your system. Some applications require ANSI Level 2.x.

ANSI Emulation subwindow: ANSI Level

264 CHAPTER SIXTEEN

@ARGn read/writeuser-defined

Stores variables passed from the operating system command line. This variable is a read-only variable where n specifies the argument, from 0 to 9 (@ARG0, @ARG1, etc.). The command line must include a setup name before the first command line parameter is given (see “Command Line Switches” on page 10).

@ATTKEY read/writeany Control Key [^K]

Defines the attention key (ATTN).

Setup field: Attention Key

@AUTOLFIN read/writeYES [NO]

When set to YES, forces BLAST—while in Terminal mode—to in-sert a linefeed character after every carriage return character dis-played.

Setup field: AutoLF In

@AUTOLFOUT read/writeYES [NO]

When set to YES, forces BLAST—while in Terminal mode—to in-sert a linefeed character after every carriage return that leaves the communications port.

Setup field: AutoLF Out

10.8x

Setting this variable to null (@ATTKEY = ""), turns off the ATTN key, for example during the running of a script. The ATTN key re-mains off until @ATTKEY is reset or until the script ends (or until the masterscript ends if one or more scripts are called), at which time BLAST resets @ATTKEY to its previous setting.


@BAUDRATE read/write300 600 1200 2400 4800

[9600] 19.2 38.4 57.6 115K

Specifies the serial port device driver speed. The default value of this variable is set during the BLAST installation process. Some sys-tems may not support higher baud rates.

Setup field: Baud Rate

@BLASTDIR read-only

Specifies the directory path for the BLAST support files as defined in the BLASTDIR environment variable (see “Environment Vari-ables” on page 7).

@CHARDLY read/write[0] – 999

Specifies the time delay (in hundredths of a second) between each character sent to the remote computer when uploading text or exe-cuting TSEND commands.

Setup field: Char Delay

@CLASS read-only

Stores the BLAST class number of the local system.

@COMMPORT read/writeany valid device

Stores the specification for the communications port, host system for TCP/IP connections, or hunt file that BLAST will use for the current session. Valid options are:

Device name – Any valid asynchronous port (e.g., /dev/tty1A).

Host name or address – The name or network address of the TCP/IP host system to which you want to connect (for example, “blaster.blast.com”). To establish a raw socket, set @COMMPORT to the host name and any available port number except 23. Port number 23 is reserved for telnet. To use telnet, simply give the host name, and BLAST will default to port number 23. To use telnet with a port other than port 23, give the host name, the port number, and “telnet,” as in the example below:

266 CHAPTER SIXTEEN

set @COMMPORT = "blaster.blast.com 12 telnet"

See “Accessing TCP/IP Ports” on page 16.

Hunt filename – The name (including path) of a hunt file that lists available devices preceded by the “<” character. Refer to “Au-tomatic Serial Port Searching” on page 25 for details about hunt files.

Setup field: Connection

@COMP_LVL read/write0 – 6 [4]

For BLAST protocol transfers, specifies the maximum sending and receiving compression levels to be used. Level 0 specifies no com-pression; level 6 specifies the highest level of compression. Setting this variable is effectively equal to setting both the @RCOMP_LEV and @SCOMP_LEV reserved variables.

@CONNTIMO read/write0 – 999 [60]

Specifies the number of seconds BLAST will wait for a network connection. This field has no effect on serial connections.

Setup field: Connection T/O

@CONTIMO read/write0 – 999 [120]

Used with older versions of BLAST. For BLAST protocol transfers, specifies the time interval (in seconds) that BLAST will wait for a packet of data from the remote computer before timing out.

IMPORTANT: This reserved variable has been replaced by the reserved variable @INACTIMO and should not be used. Do not confuse it with the @CONNTIMO reserved variable described directly above.

@CTS read-only

Stores the Clear-to-Send (CTS) device status. If @CTS is set to 1, the device, usually a modem, is ready to receive characters. @CTS is set to 0 if the device is not ready to receive characters. The value of this variable is valid only if the serial port device driver returns the cor-rect code.


@D/S_BITS read/write7/1 7/2 [8/1] 8/2

Sets data and stop bits for the communications port.

Setup field: Data/Stop Bits

@DATE read-only

Contains the current date. By default the format is mm/dd/yy. This format may be changed using the reserved variable @DATEFORMAT or one of the following switches:

See “Command Line Switches” on page 10.

This is a read-only variable; an error message will be displayed if a script attempts to write to it.

@DATEFORMAT read/writetemplate

Sets the format of the @DATE variable. Setting the @DATEFORMAT reserved variable overrides the format in which BLAST was started. The format of the output of the @DATE reserved variable will be de-termined by the @DATEFORMAT template set by the user. The value of the replacement sequences are as follows:

%A full weekday name (Monday)%a abbreviated weekday name (Mon)%B full month name (January)%b abbreviated month name (Jan)%c standard date/time representation (%a %b %d %H:%M:%S %Y)%d day-of-month (01-31)%H hour (24 hour clock) (00-23)%I hour (12 hour clock) (01-12)%j day-of-year (001-366)%M minute (00-59)%m month (01-12)%p local equivalent of AM or PM%S second (00-59)%U week-of-year, first day Sunday (00-53)%W week-of-year, first day Monday (00-53)

10.7x -2

10.8x -dd or -y

268 CHAPTER SIXTEEN

%w weekday (0-6, Sunday is 0)%X standard time representation (%H:%M:%S)%x standard date representation (%a %b %d %Y)%Y year with century%y year without century (00-99)%Z time zone name%% percent sign

For example, to set @DATEFORMAT to generate a date in the format of 19-March-1998, your script would read

set @DATEFORMAT = "%d-%B-%Y"

@DCD read-only

Stores the Carrier-Detect status from the modem. If @DCD is set to 1, the carrier is detected by the modem. If @DCD is set to 0, the mo-dem does not sense a carrier from another modem. The modem must be set appropriately for this variable to reflect the state of the data carrier; and the modem cable, if present, must have the appropriate conductor. The value of this variable is valid only if the serial port device driver returns the correct code.

@DCDLOSS read/writeABORT [IGNORE]

For BLAST protocol transfers, specifies whether BLAST will ABORT after or IGNORE DCD loss. This feature requires appropri-ate modem initialization and recognition of the signal by the serial port device driver (see discussion of @DCD above).

BLAST Protocol subwindow: DCD Loss Response

@EFERROR read/write

For BLAST protocol, returns the error code of the last error in a file transfer (see Appendix A). If no error occurs during the BLAST ses-sion, @EFERROR will remain set at 0. @EFERROR should be reset to 0 for continued testing during a session. Because BLAST queues filetransfer requests and then continues execution until ESC is en-countered, testing @EFERROR within a FILETRANSFER-ESC block may not produce expected results.

Following completion of a BLAST protocol file transfer, @EFERROR will be set to a transfer file management error (error 31–49; see


“Transfer File Management” on page 340) or one of the following values reflecting the way in which Filetransfer mode was exited:

0 No errors-1 Initialization error-2 Local operator ended activity with ATTN-3 Remote disconnect-4 Never got starting message (Logon Timeout)-5 Lost communications with remote system (In- activity Timeout)-6 Private network error; private network version of BLAST

required-7 DCD loss during Filetransfer logon-8 DCD loss during Filetransfer session

Example:

connectset @protocol = "BLAST" # BLAST protocol only!!set @EFERROR = "0"filetransfersendtest1.filrecv1.filtoescif @EFERROR not = "0" display "Error number = ", @EFERROR, "occurred" display "See Chapter 16 and Appendix A for details." set @EFERROR = "0"enddisconnectreturn 0

@EFLOG read/writefilename

Specifies a separate error-free log file that will log all filetransfer session errors or completions, or both, depending on the setting of @EFLOGGING. The default of @EFLOGGING is BOTH. Setting @EFLOG to a valid filename starts filetransfer session logging in BOTH mode. Setting @EFLOG = "" (null) turns off filetransfer ses-sion logging. The information written to the file appears exactly as it does on the user’s screen, allowing easier parsing of a filetransfer session.

270 CHAPTER SIXTEEN

@EFLOGGING read/write[BOTH] ERRORS

COMPLETIONS

Specifies whether the log file named in @EFLOG will log filetransfer ERRORS, COMPLETIONS, or BOTH. Refer to @EFLOG above for further information.

@ELAPTIME read-only

Contains the current elapsed online time for a BLAST communica-tions session. The value is in hh:mm:ss format. This variable can be reset within a BLAST script by any SET statement, for example:

set @ELAPTIME = "it doesn't matter"

The current value is not checked and is simply reset to 00:00:00.

@EMULATE read/write

Setup field: Emulation

@ENABLEFS read/writeYES [NO]

For BLAST protocol transfers, enables the /FWD and /STR file transfer switches, which automatically delete files.

BLAST Protocol subwindow: Enable /FWD and /STR

10.7x

[VT320]any valid terminal emulator

Specifies the terminal type to emulate in Terminal mode. Accept-able values are VT320, VT220, VT100, VT52, PC ANSI, TV920, D80, ADM3A, WYSE60, WYSE50, TTY, and PASSTHRU.

10.8x

TTY and [PASSTHRU]Specifies the terminal type to emulate in Terminal mode. Accept-able values are TTY and PASSTHRU.


@ENABLERCMD read/write[YES] NO

For BLAST protocol transfers, enables the /OVW (overwrite) file transfer switch and allows system commands to be sent from the re-mote system.

BLAST Protocol subwindow: Enable /OVW and Remote Cmds

@FILTER read/writeON [OFF]

For BLAST protocol transfers, specifies whether the protocol filter is turned on. When @FILTER is set to ON, BLAST strips VT se-quences sent from a mainframe protocol converter, preventing BLAST protocol from labeling these as bad blocks.

BLAST Protocol subwindow: Filtering

@FULLSCR read/write[YES] NO

Specifies whether the top four lines of the BLAST menu region will be suppressed while in Terminal mode. Set to YES to suppress the menu and NO to enable it.

Setup field: Full Screen

@INACTIMO read/write0 – 999 [120]

For BLAST protocol transfers, specifies the time interval (in sec-onds) that BLAST will wait for a packet of data from the remote computer before timing out.

NOTE: This variable replaces the @CONTIMO variable of previ-ous versions.

BLAST Protocol subwindow: Inactivity T/O

10.8x@FILECNT read-only

Returns the number of bytes either written or read during FREAD, FWRITE, FREADB, and FWRITEB.

272 CHAPTER SIXTEEN

@KBCHECK read/write1 – 3 [2]

For Kermit transfers, specifies the level of error-detection.

Kermit Protocol subwindow: Block-Check-Type

@KDELAYOS read/write1 – 99 [5]

For Kermit transfers, specifies the number of seconds of delay be-tween the recognition of a Send command and the actual beginning of the transmission.

Kermit Protocol subwindow: Delay

@KEYBOARD read/write[ON] OFF

Controls the ability to enter data from the keyboard. If ON, the key-board is unlocked and may be used. If OFF, BLAST ignores any keyboard characters, for example, during the running of a script to prevent extra characters from being sent in Terminal mode. After the script has run (or the masterscript ends if one or more scripts are called), BLAST resets the value of @KEYBOARD to the default, ON. When started in video-suppress mode (-n command line switch), BLAST sets this variable to OFF (see “Command Line Switches” on page 10).

NOTE: If @KEYBOARD is set to ON, it returns the value 1; if it is set to OFF, it returns the value 0.

10.7x

@KEYFILE read/writefilename

Specifies a user-defined keyboard map for a particular keyboard or application. Keyboard maps are created with blastkbd, the BLAST keyboard remapping utility (see “Keyboard Mapping Util-ity for 10.7x” on page 315).

Setup field: Keyboard File


@KFILETYP read/writeTEXT [BINARY]

For Kermit transfers, specifies the type of file being transferred.

Kermit Protocol subwindow: Transfer Type

@KFNAMCONV read/write[YES] NO

For Kermit transfers, converts a filename from local format to com-mon format.

Kermit Protocol subwindow: Filename Conversion

@KREOPKT read/writeÂ – ^Z [^M]

For Kermit transfers, specifies a control character to terminate each packet received. The same control character must also be used by the remote Kermit.

Kermit Protocol subwindow: End-of-Packet Char

@KRPADCH read/writeÂ – ^Z [^@]

For Kermit transfers, specifies an alternate character to pad each packet received.

Kermit Protocol subwindow: Pad Character

@KRPADDNG read/write[0] – 99

For Kermit transfers, specifies the number of padding characters to request per packet.

Kermit Protocol subwindow: Padding

274 CHAPTER SIXTEEN

@KRPKTLEN read/write10 – 2000 [90]

For Kermit transfers, specifies the packet size your system will use when it receives a file. Note that the remote Kermit’s Send packet size should also be set to this length.

Kermit Protocol subwindow: Packet Size

@KRSOPKT read/write[Â] – ^Z

For Kermit transfers, specifies the control character that marks the start of each packet received by your system. The same control char-acter must also be used by the remote Kermit.

Kermit Protocol subwindow: Start-of-Packet Char

@KRTIMEOUT read/write0 – 99 [10]

For Kermit transfers, specifies the number of seconds that the com-puter will wait to receive a packet before requesting that it be resent.

Kermit Protocol subwindow: Timeout

@KSAVEINC read/write[DISCARD] KEEP

For Kermit transfers, specifies whether to KEEP or DISCARD files not completely received, such as a file being transferred when you abort a Get command.

Kermit Protocol subwindow: Incomplete File

@KSEOPKT read/writeÂ – ^Z [^M]

For Kermit transfers, specifies a control character to terminate each packet sent by your system. The same control character must also be used by the remote Kermit.

Kermit Protocol subwindow: End-of-Packet Char


@KSPADCH read/writeÂ – ^Z [^@]

For Kermit transfers, specifies an alternate character to pad each packet sent by your system.

Kermit Protocol subwindow: Pad Character

@KSPADDNG read/write[0] – 99

For Kermit transfers, specifies the number of padding characters to send per packet.

Kermit Protocol subwindow: Padding

@KSPKTLEN read/write10 – 2000 [90]

For Kermit transfers, specifies the packet size your system will use when it sends a file. Note that the packet size of the remote Kermit must also be set to this length.

Kermit Protocol subwindow: Packet Size

@KSSOPKT read/write[Â] – ^Z

For Kermit transfers, specifies the control character that marks the start of each packet sent by your system. The same control character must also be used by the remote Kermit.

Kermit Protocol subwindow: Start-of-Packet Char

@KWARNING read/write[ON] OFF

For Kermit transfers, specifies whether Kermit will automatically rename a received file if another file with the same name already ex-ists in the current directory. If @KWARNING is set to ON, Kermit au-tomatically renames the file by adding a number (0001, 0002, etc.) to the filename; if it set to OFF, Kermit overwrites the file.

Kermit Protocol subwindow: Warning

276 CHAPTER SIXTEEN

@LAUNCHST read/writeany ASCII string [\r]

For BLAST protocol transfers, specifies the launch string to be ap-pended to BLAST protocol blocks. Any ASCII string may be used, with control characters represented by a backslash followed by a three-digit octal number (see the discussion of special control char-acters on page 221). The default is a carriage return (\r). This vari-able may be necessary for protocol converter connections.

BLAST Protocol subwindow: Launch String

@LINEDLY read/write[0] – 999

Specifies the length of time (in tenths of a second) that BLAST paus-es after sending a line of characters and a carriage return during a text upload.

Setup field: Line Delay

@LOCECHO read/writeYES [NO]

Specifies whether BLAST will echo typed characters to the screen while in Terminal mode. If @LOCECHO is set to YES, BLAST will display typed characters before sending them out the communica-tion port; if @LOCECHO is set to NO, the characters will be displayed only if the remote computer sends them back.

If @LOCECHO is set to YES and double characters are displayed on the screen, change the setting to NO.

Setup field: Local Echo

@LOGDATEFORMAT read/writetemplate

Sets the format of the date written in the date stamp of the log file. Setting @LOGDATEFORMAT overrides the format in which BLAST was started. The format of dates written in the log file will be deter-mined by the template set by the user. The value of the replacement sequences are the same as those described above in the @DATEFOR-MAT reserved variable.


@LOGFILE read/writefilename

Stores the name of the log file that will record all communications session activity. Setting @LOGFILE = @LOGFILE flushes the log file buffers to disk. Setting @LOGFILE = "" closes the current log file.

Setup field: Log File

@LOGTIMEFORMAT read/writetemplate

Sets the format of the time written in the time stamp of the log file. Setting @LOGTIMEFORMAT overrides the format in which BLAST was started.The format of times written in the log file will be deter-mined by @LOGTIMEFORMAT template set by the user. The value of the replacement sequences are the same as those described above in the @DATEFORMAT reserved variable.

@LOGTIMO read/write0 – 999 [120]

For BLAST protocol, specifies the number of seconds that BLAST will attempt to establish a filetransfer session with the remote com-puter before aborting. Logon Timeout affects BLAST protocol File-transfer and Access modes. If zero is entered, no timeout will occur and BLAST will attempt to establish a filetransfer session with the remote computer indefinitely.

BLAST Protocol subwindow: Logon T/O

@MODEM read/writeany valid modem type

Stores the modem type on the local computer. The name must be de-fined in the modems.scr library or exist as a separate script.

Setup field: Modem Type

@NUMDISC read/write0 – 9 [3]

For BLAST protocol, sets the number of additional disconnect blocks (after the first disconnect block) that BLAST sends when ex-

278 CHAPTER SIXTEEN

iting Filetransfer mode. Possible values are 0–9. The default value of 3 indicates four total disconnect blocks.

BLAST Protocol subwindow: Number of Disconnect Blocks

@ONERROR read/write[STOP] CONTINUE

Specifies BLAST’s response to nonfatal BLASTscript errors. A nonfatal error is one that results in the message “Press any key to continue.”

When @ONERROR is set to STOP, BLAST will pause when an error is encountered, display the appropriate message, and wait for the user to press a key before continuing. When @ONERROR is set to CONTINUE, BLAST will display the same message, pause for one second, and then automatically continue script execution.

@ORGANS read/write[ORIGINATE] ANSWER

Specifies how the Connect command will operate. If @ORGANS is set to ANSWER, Connect will wait for a remote computer to establish the communications link. If it is set to ORIGINATE, Connect will try to dial a number.

Setup field: Originate/Answer

@PAKTSZ read/write1 – 4085 [256]

For BLAST protocol transfers, specifies the size of the packet.

Setup field: Packet Size

@PARITY read/write[NONE] ODD EVEN

Sets the device driver parity of the serial port. This setting should match that of the remote system

Setup field: Parity


@PASSWORD write-onlyuser-defined

Stores the user’s password for the remote computer. The systems.scr library program uses @PASSWORD to answer prompts from a multi-user computer. The CONNECT command will prompt the user to enter a password if none is specified in the Setup. Thereafter, the variable @PASSWORD contains the value entered by the user. For se-curity, the value of @PASSWORD cannot be displayed to the screen. This feature applies to all string values that match @PASSWORD. Thus, script commands such as

set @trick = @PASSWORDdisplay @trick

will not display the value of the password.

BLAST makes an effort to keep stored passwords secure. Unfortu-nately, it is a very simple task to echo a stored password off either a modem or a remote system that has echo enabled. A script as simple as “tsend @password” can compromise stored passwords. If the security of a password is vital, BLAST recommends not storing it in the setup. If a password must be stored in the setup, you should take other measures to keep the setup secure. For more information on se-curity, consult your system documentation and Chapter 11.

Setup field: Password

@PHONENO read/writeuser-defined

Specifies the phone number of the remote computer. The CONNECT statement uses this number to dial out.

Setup field: Phone Number

@PROMPTCH read/write[NONE] any ASCII character

Defines the prompt character used during text uploads to half-du-plex systems. BLAST waits after each line for the remote computerto send the prompt before sending the next line.

Setup field: Prompt Char

280 CHAPTER SIXTEEN

@PROTOCOL read/write[BLAST] KERMIT

XMODEM XMODEM1K YMODEM YMODEM G ZMODEM

Specifies the protocol for a communications session.

Setup field: Protocol

@RBTOT read-only

If Extended Logging is enabled, holds the total number of bytes re-ceived during the file transfer session. You must write a display statement (e.g. Display "@RBTOT is ", @RBTOT) for this variable to be displayed in the Extended Log file. See the description of @XLOG for more information.

@RBYTES read-only

In the BLAST Extended Log, holds the number of bytes received in the current transfer. Note that this value can be different than the ac-tual file size. You must have Extended Logging enabled for this variable to return a value. See @XLOG for more information.

@RCLASS read-only

For BLAST protocol, stores the BLAST class number of the remote system. This is valid during and after file transfer.

@RCOMP_LEV read/write0 – 6 [4]

For BLAST protocol transfers, specifies the maximum receiving level of compression that can be used during a session. Level 0 spec-ifies no compression; level 6 specifies the highest compression lev-el.

BLAST Protocol subwindow: Receive Compression Level

@RETRAN read/write0 – 9999 [4]

For BLAST protocol transfers, sets the maximum number of sec-onds BLAST will pause before resending a packet. For example, if

10.8x FTP


@WDWSIZ is set to 5 and @RETRAN is set to 30, BLAST will at-tempt to resend the fifth packet every 30 seconds if no acknowledge-ment is received.

BLAST Protocol subwindow: Retransmit Timer

@RFAILURE read-only

For BLAST protocol, stores the number of files unsuccessfully re-ceived during a file transfer session.

@RLINEQ read-only

For BLAST protocol transfers, stores the current receiving line qual-ity. Possible values are GOOD, FAIR, POOR, or DEAD.

@RLQ read-only

In the BLAST Extended Log, holds the line quality for the file being received. You must have Extended Logging enabled for this variable to return a value. Possible values are GOOD, FAIR, POOR, or DEAD. See the description of @XLOG for more information.

@RNAME read-only

In the BLAST Extended Log, holds the name of the file being re-ceived. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more informa-tion.

@ROPTIONS read-only

In the BLAST Extended Log, holds the value of the options for the file being received. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more information.

@RPACK read-only

In the BLAST Extended Log, holds the number of packets received in the transfer. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more in-formation.

282 CHAPTER SIXTEEN

@RPTOT read-only

In the BLAST Extended Log, holds the total number of packets re-ceived during the file transfer session. You must have Extended Logging enabled for this variable to return a value. See the descrip-tion of @XLOG for more information.

@RRET read-only

In the BLAST Extended Log, holds the number of retries for the file being received. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more in-formation.

@RRTOT read-only

In the BLAST Extended Log, holds the total number of retries for files being received during the file transfer session. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more information.

@RSERIAL read-only

For BLAST protocol, stores the serial number of the BLAST version running on the remote system.

@RSITE read-only

For BLAST protocol, stores the BLAST site number of the remote system. This is valid during and after file transfer.

@RSIZE read-only

In the BLAST Extended Log, holds the size of the file being re-ceived. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more informa-tion.

@RSTART read-only

In the BLAST Extended Log, holds the interrupt start point for an interrupted received file. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more information.


@RSTATUS read-only

In the BLAST Extended Log, holds the completion status of the file being received. Possible values are:

RCOMP – Receive completed.

LERROR – Receive not completed, due to local error.

RERROR – Receive not completed, due to remote error.

RINTR – Receive not completed, due to operator interruption.

You must have Extended Logging enabled for this variable to returna value. See the description of @XLOG for more information.

@RSUCCESS read-only

For BLAST protocol, stores the number of files successfully re-ceived during a file transfer session.

@RTIME read-only

In the BLAST Extended Log, holds the elapsed time for the file be-ing received. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more in-formation.

@RTSCTS read/write[YES] NO

Specifies whether hardware flow control is enabled. Not all comput-ers support RTS/CTS flow control. The value of this variable is valid only if the serial port device driver returns the correct code.

Setup field: RTS/CTS Pacing

@SBTOT read-only

If Extended Logging is enabled, holds the total number of bytes sent during the file transfer session. You must write a display statement (e.g. Display "@SBTOT is ", @SBTOT) for this variable to be displayed in the Extended Log file. See the description of @XLOG for more information.

284 CHAPTER SIXTEEN

@SBYTES read-only

In the BLAST Extended Log, holds the number of bytes sent in the current transfer. Note that this value can be different than the actual file size. You must have Extended Logging enabled for this variable to return a value. See @XLOG for more information.

@SCOMP_LEV read/write0 – 6 [4]

For BLAST protocol transfers, specifies the maximum sending compression level that can be used during a session. Level 0 speci-fies no compression; level 6 specifies the highest compression level.

BLAST Protocol subwindow: Send Compression Level

@SCRFILE read/writefilename

Specifies the name of a BLAST script that will start immediately af-ter BLAST begins execution.

Setup field: Script File

@SCRIPTERR read/writeany integer

Returns the numeric value of the last error that occurred in the BLAST script.

@SCRLREG read/write[ON] OFF

Controls data display in the scrolling region (lines 5–24). If @SCRLREG is set to ON, characters received in Terminal mode will be displayed and BLAST scripts can use the DISPLAY statement. If BLAST is started in video-suppress mode (-n switch on the operat-ing system command line), @SCRLREG is set to OFF (see “Com-mand Line Switches” on page 10).

NOTE: If @SCRLREG is set to ON, it returns the value 1; if it is set to OFF, it returns the value 0.


@SERIAL read-only

Stores the serial number of the BLAST version running on the local system.

@SETUPDIR read-only

Specifies the directory path in which BLAST setup files are stored, as specified in the SETUPDIR environment variable (see “Environ-ment Variables” on page 7).

@SFAILURE read-only

For BLAST protocol, stores the number of files unsuccessfully sent during a file transfer session.

@SITE read-only

Stores the BLAST site number of the local system.

@SLINEQ read-only

For BLAST protocol, stores the current sending line quality during a file transfer. Increase packet size to take advantage of clean lines, or decrease packet size to avoid problems with noisy lines. Possible values are GOOD, FAIR, POOR, or DEAD.

@SLQ read-only

In the BLAST Extended Log, holds the line quality for the file beingsent. You must have Extended Logging enabled for this variable toreturn a value. See the description of @XLOG for more information.

@SNAME read-only

In the BLAST Extended Log, holds the name of the file being sent.You must have Extended Logging enabled for this variable to returna value. See the description of @XLOG for more information.

@SOPTIONS read-only

In the BLAST Extended Log, holds the value of the options for the file being sent. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more in-formation.

286 CHAPTER SIXTEEN

@SPACK read-only

In the BLAST Extended Log, holds the number of packets sent in the transfer. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more informa-tion.

@SPTOT read-only

In the BLAST Extended Log, holds the total number of packets sent during the file transfer session. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more information.

@SRET read-only

In the BLAST Extended Log, holds the number of retries for the file being sent. You must have Extended Logging enabled for this vari-able to return a value. See the description of @XLOG for more infor-mation.

@SRTOT read-only

In the BLAST Extended Log, holds the total number of retries for files being sent during the file transfer session. You must have Ex-tended Logging enabled for this variable to return a value. See the description of @XLOG for more information.

@SSIZE read-only

In the BLAST Extended Log, holds the size of the file being sent. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more information.

@SSTART read-only

In the BLAST Extended Log, holds the interrupt start point for an interrupted sent file. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more information.

@SSTATUS read-only

In the BLAST Extended Log, holds the completion status of the file being sent. Possible values are:


SCOMP – Send completed.

LERROR – Send not completed, due to local error.

RERROR – Send not completed, due to remote error.

SINTR – Send not completed, due to operator interruption.

You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more information.

@SSUCESS read-only

For BLAST protocol, stores the number of files successfully sent during a file transfer session.

@STATUS read/writecommand-specific

Returns a condition code set by the last statement that reported a completion status. Most statements that succeed set @STATUS to 0 and return a nonzero value for an error. For example, the FILETRANSFER command sets @STATUS to 0 if Filetransfer mode was successfully entered. @STATUS does not, however, re-flect the success of an entire FILETRANSFER block, but rather the @STATUS setting of the last command in the block capable of set-ting @STATUS. (To check the overall success of a FILETRANSFER block, use the reserved variable @EFERROR).

Some commands that return numeric results (e.g., STRINX, TTRAP) set @STATUS to 0 to indicate a null condition.

On returning from a called script, @STATUS is set to the numeric constant given in the RETURN statement, or to 0 if no numeric con-stant is given.

For a list of commands that set @STATUS, see “Commands That Set @STATUS” on page 223.

@STIME read-only

In the BLAST Extended Log, holds the elapsed time for the file be-ing sent. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more informa-tion.

288 CHAPTER SIXTEEN

@SYSDESC read/writeuser-defined

Stores a user-defined description of the remote computer. This field may be up to 40 characters. No special processing is done based on the information in this field.

Setup field: Description

@SYSTYPE read/writeany valid system type

Specifies the remote computer type (UNIX, VMS, etc.). The systems.scr library uses this variable to determine how to perform certain system functions, such as logging on and disconnecting from remote multi-user computers.

Setup field: System Type

@TIME read-only

Contains the current time in hh:mm:ss format. This is a read-only variable; an error message will be displayed if a script attempts to write to it.

@TIMEFORMAT read/writetemplate

Sets the format of the @TIME variable. Setting the @TIMEFORMAT reserved variable overrides the format in which BLAST was started. The format of the output of the @TIME reserved variable will be de-termined by the template set by the user. The value of the replace-ment sequences are the same as those described above in the @DATEFORMAT reserved variable.

@TRANSTAT read/write[ON] OFF

Controls the display of the File Transfer Status Area. If @TRAN-STAT is set to ON, the area is active. This variable is set to OFF when

10.8x@SYMBOLTYPE read-only

Returns the results of the last SYMTYPE command—NONE, BINARY, or STRING.


BLAST is started in video-suppress mode (-n on the operating sys-tem command line; see “Command Line Switches” on page 10).

NOTE: If @TRANSTAT is set to ON, it returns the value 1; if it is set to OFF, it returns the value 0.

@TRPASSWD write-onlyup to 8 characters

For BLAST protocol, stores a password that a remote user must send before a file transfer is allowed. If this variable is set to other than null, then the remote computer must send the password before a file can be transferred to or from your computer.

NOTE: @TRPASSWD is intended to validate remote users logging onto your system. If the BLAST running on the local system exe-cutes a script that sets @TRPASSWORD to something other than a null, the local computer will not be able to receive files without the remote computer sending the password.

BLAST Protocol subwindow: Transfer Password

@TTIME read-only

In the BLAST Extended Log, holds the total elapsed time of the file transfer session. You must have Extended Logging enabled for this variable to return a value. See the description of @XLOG for more in-formation.

@USERID read/writeuser-defined

Stores the user’s identification for the remote computer. The systems.scr library uses this variable in answering the logon prompts from a multi-user computer.

Setup field: Userid

10.8x@TRAPCNT read-only

Returns the number of bytes read from the last TTRAP. TTRAP must be preceded by SETTRAP.

290 CHAPTER SIXTEEN

@USERIF read/write[ON] OFF

Controls data display in the menu region (lines 1–4). If @USERIF is set to ON, the menu region is displayed; if it is set to OFF, lines 1–4 become part of the scrolling region. When BLAST is started in the video-suppress mode (-n on the operating system command line), this variable is turned OFF (see “Command Line Switches” on page 10).

NOTE: If @USERIF is set to ON, it returns the value 1; if it is set to OFF, it returns the value 0.

@VERSION read-only

Stores the version of BLAST that is running.

10.7x

@VT8BIT read/write[7] 8

For VT220 and VT320 emulation, specifies whether “C1” control characters are represented in the 8-bit environment or as 7-bit es-cape sequences.

VT Emulation subwindows: 7/8 Bit Controls

@VTANSBACK read/writeuser-defined ASCII string

For VT emulation, contains a message to be sent to the remote computer upon receiving an inquiry (Ê). The field can be up to 30 characters in length. The default value is an empty string—nothing is sent.

VT Emulation subwindows: Answerback Msg

@VTAUTOWRAP read/writeYES [NO]

For VT emulation, specifies whether text typed at the right margin will automatically wrap to the next line.

VT Emulation subwindows: Auto Wrap


10.7x

@VTCLRSCRN read/writeYES [NO]

For VT emulation, clears the terminal’s video display. Setting @VTCLRSCRN to YES clears the display; the value is then reset to NO.

VT Emulation subwindows: Clear Screen

@VTCURSOR read/write[NORMAL] APPLICATION

For VT emulation, specifies whether the cursor keys will control cursor movement or send application control functions.

VT Emulation subwindows: Cursor Keys Mode

@VTCURSTYPE read/writeBLOCK [LINE]

For VT100/52 and VT220 emulation, specifies whether the cursor is displayed as a reverse-video block or as an underline character.

VT Emulation subwindows: Cursor Type

@VTDISP132 read/write[80] 132

For VT emulation, specifies column display for text.

VT Emulation subwindows: 80/132 Columns

@VTHSCROLL [JUMP] SMOOTH NONE

For VT emulation, specifies how to scroll data on an 80-column display when the emulator is in 132-column mode. SMOOTH scroll will change the view of the display only as necessary to display the cursor position. JUMP scroll will adjust the view by showing either the first 80 columns or the last 80 columns. When NONE is select-ed, the display will not scroll and the cursor may disappear from view. This value is ignored if @VTCOMPRESSED is set to YES.

VT Emulation subwindows: Horizontal Scroll

292 CHAPTER SIXTEEN

10.7x

@VTHSCROLLN 1 – 53 [10]For VT emulation, specifies the number of columns to move when the Scroll Left or Scroll Right keys are pressed. The value is used when Jump Scroll has been selected as the scroll mode.

VT Emulation subwindows: Jump Scroll Inc

@VTINTL [USASCII] UKFRENCH GERMAN

ITALIAN SPANISH DANISH

For VT220 and VT320 emulation, specifies whether 7- or 8-bit data is used for international support. The default value, US-ASCII, allows 8-bit data with the high-order data used for inter-national characters.

VT Emulation subwindows: Intl Char Set

@VTKEYPAD [NUMERIC] APPLICATION

For VT emulation, specifies whether the numeric keypad keys will send numbers or programming functions defined by the applica-tion.

VT Emulation subwindows: Keypad Mode

@VTNEWLINE read/writeYES [NO]

For VT emulation, selects whether the ENTER key will move the cursor to a new line.

VT Emulation subwindows: New Line

@VTPRINT read/write[NORMAL] AUTO

CONTROLLER

For VT emulation, specifies when information is sent to the print-er. In AUTO print mode, each line of received text is displayed and printed; in CONTROLLER mode, all received data is sent directly to the printer without displaying it on the screen; in NORMAL mode, the user initiates printing from the keyboard.

VT Emulation subwindows: Print Mode


10.7x

@VTPRINTPAGE read/write[SCROLL REGION]

FULL PAGE

For VT emulation, specifies how much of the screen to print when you press the PRINT SCREEN key.

VT Emulation subwindows: Print Screen

@VTRESET read/writeYES [NO]

For VT emulation, specifies whether many of the VT operating features are reset to their factory default values. If @VTRESET is set to YES, the features are reset; the value of this variable is then authomatically reset to NO.

VT Emulation subwindows: Reset Terminal

@VTTEXTCURS read/write[YES] NO

For VT emulation, specifies whether to display the text cursor.

VT Emulation subwindows: Text Cursor

@VTUSERCHAR read/write[DEC SUPPLEMENTAL]

ISO LATIN-1

For VT320 emulation, specifies either DEC SUPPLEMENTAL or ISO LATIN-1 character set as the user preferred character set.

VT Emulation subwindows: User Pref Char Set

@VTUSERKEYS read/write[UNLOCKED] LOCKED

For VT200 and VT320 emulation, selects whether the host system can change user-defined key definitions.

VT Emulation subwindows: User Def Keys.

294 CHAPTER SIXTEEN

@WDWSIZ read/write1 – [16]

For BLAST protocol, specifies the window size of the “B” protocol. “Window” refers to the number of BLAST protocol packets that can be sent to the remote without BLAST waiting for an acknowledge-ment from the remote. As packets are acknowledged, the start point of the window is adjusted, or “slides.” See “BLAST Protocol De-sign” on page 101 for a fuller discussion of window size.

BLAST Protocol subwindow: Window Size

@WT4ECHO read/writeYES [NO]

Specifies whether BLAST will wait for the remote computer to echo each character of uploaded text before sending the next character.

Setup field: Wait For Echo

10.7x

@WYANSBACK read/writeuser-defined

For WYSE emulation, contains a user-created message to be sent to the host when an inquiry is received.

WYSE Emulation subwindow: Answerback

@WYAUTOPAGE read/writeYES [NO]

For WYSE emulation, specifies whether the cursor can move off the current page when an attempt is made to move the cursor before the home position or beyond the end of the page.

WYSE Emulation subwindow: Auto Page

@WYAUTOSCROLL read-only[YES]

For WYSE emulation, specifies scrolling of the terminal display when the cursor reaches the bottom of a page. This field is read-only and cannot be changed.

WYSE Emulation subwindow: Auto Scroll


10.7x

@WYAUTOWRAP read/write[YES] NO

For WYSE emulation, specifies whether a new line is automatical-ly performed when a character is placed in the last column of a row (column 80 or 132).

WYSE Emulation subwindow: Auto Wrap

@WYBLOCKEND read/write[US/CR] CRLF/ETX

For WYSE emulation, specifies which characters are used to mark the end-of-line and end-of-block when the terminal is in block mode.

WYSE Emulation subwindow: Block End

@WYCOMMODE [CHARACTER] BLOCK

For Wyse emulation, specifies whether data is sent after each key-stroke (character mode) or packaged into blocks.

WYSE Emulation subwindow: Comm Mode

@WYDISP80 read/write[80] 132

For WYSE emulation, specifies a display of 80 or 132 columns per row.

WYSE Emulation subwindow: Columns

@WYDSPCURSOR read-only[YES]

For WYSE emulation, specifies that the cursor is visible. This field is read-only and cannot be changed.

WYSE Emulation subwindow: Display Cursor

296 CHAPTER SIXTEEN

10.7x

@WYENTER read/write[CR] CRLF TAB

For WYSE emulation, specifies the character to send when the keypad ENTER key is pressed.

WYSE Emulation subwindow: Enter

@WYEXPNDMEM read/writeYES [NO]

For WYSE emulation, specifies expanded memory use.

WYSE Emulation subwindow: Expanded Memory

@WYPAGELEN read/write[1*DATA LINES]

2*DATA LINES 4*DATA LINES

For WYSE emulation, specifies the length of a screen page.

WYSE Emulation subwindow: Page Length

@WYRETURN read/write[CR] CRLF TAB

For WYSE emulation, specifies the character to send when the RETURN key is pressed.

WYSE Emulation subwindow: Return

@WYSCROLLINC read/write1– 53 [10]

For Wyse emulation, specifies the scroll increment. This value is used when 132 columns per row has been selected and compressed display is not utilized.

Wyse Emulation subwindow: Horiz Scroll Inc


@XLOG read/writeON [OFF]

Enables Extended Logging, which provides detailed information about BLAST protocol file transfers. Extended Log values may be read from the variables listed below. When Extended Logging is en-abled, all the values below are listed in the log file except for @RBTOT and @SBTOT, which may be written to the log file by issuing a dis-play statement (e.g. display "@RBTOT is ", @RBTOT).

@SNAME @RNAME @STIME @RTIME@SOPTIONS @ROPTIONS @SPACK @RPACK@SSTATUS @RSTATUS @SRET @RRET@SSIZE @RSIZE @SPTOT @RPTOT@SSTART @RSTART @SRTOT @RRTOT@SBYTES @RBYTES @SBTOT @RBTOT@SLQ @RLQ @TTIME

Extended Logging may also be enabled with the -x command line switch (see “Command Line Switches” on page 10).

10.7x

@WYSEWORD read/writeYES [NO]

For WYSE emulation, specifies whether keys send Wordstar™ functions instead of standard key codes. The only keys affected are WYSE keys that can be remapped with the blastkbd utility (see “Keyboard Mapping Utility for 10.7x” on page 315).

WYSE Emulation subwindow: Wyseword

@WYWRITEPROT read/write[DIM] REVERSE NORMAL

For WYSE emulation, specifies the attribute used to display pro-tected fields.

WYSE Emulation subwindow: Write Protect

10.8x

@XCRC read/write[CRC] CHECKSUM

For Xmodem transfers, specifies whether the error detection is CRC or CHECKSUM.

Setup field: Error Detection

298 CHAPTER SIXTEEN

@XLTFILE read/writefilename

Stores the name of the Translate File used in Terminal mode to filter, translate, or substitute characters (see “Translate File Format” on page 306).

Setup field: Translate File

@XONXOFF read/writeYES [NO]

Specifies whether software flow control is enabled. Not all comput-ers support XON/XOFF flow control.

Setup field: XON/XOFF Pacing

10.8x

@XPADC read/writeany character in decimal [00]

For Xmodem transfers, specifies the pad character. This parameter may also be set from the command line with -p command line switch (“Command Line Switches” on page 10).

XYmodem Protocol subwindow: Pad character

@XYCONVR read/writeASCII [BINARY]

For Xmodem and Ymodem transfers, specifies whether received files will be treated as ASCII or BINARY.

XYmodem Protocol subwindow: File Conversion

@XYCONVS read/writeASCII [BINARY]

For Xmodem and Ymodem transfers, specifies whether files sent will be treated as ASCII or BINARY.

XYmodem Protocol subwindow: File Conversion


10.8x

@XYEOT read/write10 – 6000 [100]

For Xmodem and Ymodem transfers, specifies EOT (end-of-trans-mission) timeout in hundredths of a second.

EOT timeout for Xmodem and Ymodem may also be specified with the -e command line switch (see “Command Line Switches” on page 10)

XYmodem Protocol subwindow: EOT Timeout

@XYRLTR read/writeCR [CR/LF]

For Xmodem and Ymodem transfers, specifies how line termina-tion is treated if @XYCONVS is set to ASCII.

CR – for files received, replaces all carriage returns (CR) with line-feeds (LF); e.g., for ASCII files received from Macintosh platform.

CR/LF – for files received, deletes any carriage return (CR) that is followed by a line feed (LF); e.g., for ASCII files sent to DOS and Windows platforms.

XYmodem Protocol subwindow: Remote Line Termination

@XYRLTS read/writeCR [CR/LF]

For Xmodem and Ymodem transfers, specifies how line termina-tion is treated if @XYCONVS is set to ASCII.

CR – for files sent, replaces line feeds (LF) with carriage returns (CR); e.g., for ASCII files sent to Macintosh platform.

CR/LF – for files sent, adds a carriage return (CR) before a line feed (LF); e.g., for ASCII files sent to DOS and Windows plat-forms.

XYmodem Protocol subwindow: Remote Line Termination

300 CHAPTER SIXTEEN

@ZMAUTODOWN read/writeYES [NO]

For Zmodem transfers, specifies Auto Receive mode, which begins downloading immediately after entering Filetransfer mode.

Zmodem Protocol subwindow: Auto Receive

@ZMBLKLN read/write[0] 24 – 1024

For Zmodem transfers, overrides the default block length, which is determined by the baud rate of the connection. The default, 0, spec-ifies no limit to block length.

Zmodem Protocol subwindow: Limit Block Length

@ZMCONVR read/write[ASCII] BINARY

For Zmodem transfers, specifies whether received files will be treat-ed as ASCII or BINARY. For correct file conversion to ASCII, the remote computer must send the files as ASCII.

Zmodem Protocol subwindow: File Conversion

@ZMCONVS read/write[NONE] ASCII BINARY

For Zmodem transfers, specifies whether files sent are to be treated as BINARY or ASCII, overriding the File Conversion setting of the receiving system. NONE specifies no override.

Zmodem Protocol subwindow: Conversion Override

10.8x

@ZMALT read/write[CR/LF] LF

For sending ASCII files to nonstandard implementations of Zmo-dem, specifies line-feed conversion for ASCII files. When @ZMCONVS = "ASCII", the default CR/LF specifies that line feeds be converted to CR/LF; LF specifies no conversion.

Zmodem Protocol subwindow: ASCII Line Termination


@ZMCRC read/write16 BITS [32 BITS]

For Zmodem transfers, specifies which CRC error-detection is to be used.

Zmodem Protocol subwindow: CRC

@ZMCTLESCR read/writeYES [NO]

For Zmodem transfers, specifies whether all control characters re-ceived will be link-escape encoded for transparency.

Zmodem Protocol subwindow: Esc All Control Chars

@ZMCTLESCS read/writeYES [NO]

For Zmodem transfers, specifies whether all control characters sent will be link-escape encoded for transparency.

Zmodem Protocol subwindow: Esc All Control Chars

@ZMEXIST read/writeYES [NO]

For Zmodem transfers, specifies whether transfers will occur only if the file already exists on the destination system.

Zmodem Protocol subwindow: File Must Already Exist

@ZMFRMLEN read/write[0] 24 – 1024

For Zmodem transfers, limits frame length and forces the sender to wait for a response from the receiver before sending the next frame. The default, 0, specifies no limit to frame length.

Zmodem Protocol subwindow: Limit Frame Length

302 CHAPTER SIXTEEN

@ZMMANAGR read/writeNONE PROTECT

[CLOBBER] APPEND

For Zmodem transfers, specifies a file management option for files received. See the File Management setup field on page 97 for a de-scription of each option.

Zmodem Protocol subwindow: File Management

@ZMMANAGS read/write[NONE] PROTECT CLOBBER NEWER

NEWER/LONGER DIFFERENT APPEND

For Zmodem transfers, specifies a file management option for files sent. See the Management Option setup field on page 95 for a de-scription of each option.

Zmodem Protocol subwindow: Management Option

@ZMRESUME read/writeYES [NO]

For Zmodem transfers, specifies continuation of an aborted file transfer from point of interruption. The destination file must already exist and must be smaller than the source file.

Zmodem Protocol subwindow: Resume Interrupted File

@ZMWINDOW read/write[0] – 9999

For Zmodem transfers, specifies the size of the transmit window. The default, 0, specifies no limit to the size of the transmit window.

Zmodem Protocol subwindow: Size of Tx Window


304 CHAPTER SIXTEEN

Chapter 17

Data Stream Control

Introduction

All versions of BLAST support data filtering and translation of in-coming and outgoing data streams. This chapter describes these fea-tures as well as the standard BLAST terminals, TTY and PASSTHRU. In addition, this chapter describes terminal emulation and keyboard mapping, which are available with BLAST Profes-sional UNIX 10.7x. Through terminal emulation, BLAST provides terminal functionality for a range of popular character terminals. With keyboard mapping, you can reassign the functions of the stan-dard keyboard keys as well as the “BLAST keys” that control BLAST functions.

Data Stream Filtering and Alteration

BLAST allows for the translation, substitution, or filtering (remov-al) of individual characters in the data stream during terminal ses-sions. This character manipulation can be used to:

DATA STREAM CONTROL 305

◊ Prevent the display of unwanted characters.

◊ Display international character sets.

◊ Prevent the transmission of certain key codes.

◊ Remap keys to send characters other than their defaults.

◊ Prevent characters from being saved in the capture file.

◊ Prevent characters from being sent with a file upload.

For example, Dow Jones News Service sends special start- and end-of-record characters that print non-ASCII characters on the screen. The standard translate file supplied with BLAST filters out these characters so that they do not appear on your display. If you wanted to automate your access to Dow Jones by writing a script, you might need to TTRAP for these filtered characters. For the TTRAP to see them, you would have to change the filter in order to allow these characters to pass.

Translate File FormatA copy of the standard translate file is on your distribution media as “translat.tbl.” This file is distributed with the defaults used when the Translate File setup field (page 73) is empty. The BLAST translate file contains two tables: the receive table, which operates on char-acters received from the remote system, and the transmit table, which operates on characters sent to the remote system.

The receive and transmit tables within a BLAST translate file con-tain an array of 256 hexadecimal values. These values correspond to the 8-bit ASCII character set. The decimal value of a character rang-ing from 0 to 255 is used as an index to the character positions in the table. The hexadecimal value at that location in the table is substitut-ed for the hexadecimal value of the original character.

Translat.tbl contains the following receive and transmit default ta-bles:

:RECVTABL-00, -01, -02, -03, -04, -05, -06, 07,08, 09, 0A, 0B, 0C, 0D, 0E, 0F,

-10, -11, -12, -13, -14, -15, -16, -17,-18, -19, -1A, -1B, -1C, -1D, -1E, -1F,20, 21, 22, 23, 24, 25, 26, 27,28, 29, 2A, 2B, 2C, 2D, 2E, 2F,30, 31, 32, 33, 34, 35, 36, 37,38, 39, 3A, 3B, 3C, 3D, 3E, 3F,40, 41, 42, 43, 44, 45, 46, 47,

306 CHAPTER SEVENTEEN

48, 49, 4A, 4B, 4C, 4D, 4E, 4F,50, 51, 52, 53, 54, 55, 56, 57,58, 59, 5A, 5B, 5C, 5D, 5E, 5F,60, 61, 62, 63, 64, 65, 66, 67,68, 69, 6A, 6B, 6C, 6D, 6E, 6F,70, 71, 72, 73, 74, 75, 76, 77,78, 79, 7A, 7B, 7C, 7D, 7E, 7F,

-00, -01, -02, -03, -04, -05, -06, 07,08, 09, 0A, 0B, 0C, 0D, 0E, 0F,

-10, -11, -12, -13, -14, -15, -16, -17,-18, -19, -1A, 1B, -1C, -1D, -1E, -1F,20, 21, 22, 23, 24, 25, 26, 27,28, 29, 2A, 2B, 2C, 2D, 2E, 2F,30, 31, 32, 33, 34, 35, 36, 37,38, 39, 3A, 3B, 3C, 3D, 3E, 3F,40, 41, 42, 43, 44, 45, 46, 47,48, 49, 4A, 4B, 4C, 4D, 4E, 4F,50, 51, 52, 53, 54, 55, 56, 57,58, 59, 5A, 5B, 5C, 5D, 5E, 5F,60, 61, 62, 63, 64, 65, 66, 67,68, 69, 6A, 6B, 6C, 6D, 6E, 6F,70, 71, 72, 73, 74, 75, 76, 77,78, 79, 7A, 7B, 7C, 7D, 7E, 7F,

:XMITTABL00, 01, 02, 03, 04, 05, 06, 07,08, 09, 0A, 0B, 0C, 0D, 0E, 0F,10, 11, 12, 13, 14, 15, 16, 17,18, 19, 1A, 1B, 1C, 1D, 1E, 1F,20, 21, 22, 23, 24, 25, 26, 27,28, 29, 2A, 2B, 2C, 2D, 2E, 2F,30, 31, 32, 33, 34, 35, 36, 37,38, 39, 3A, 3B, 3C, 3D, 3E, 3F,40, 41, 42, 43, 44, 45, 46, 47,48, 49, 4A, 4B, 4C, 4D, 4E, 4F,50, 51, 52, 53, 54, 55, 56, 57,58, 59, 5A, 5B, 5C, 5D, 5E, 5F,60, 61, 62, 63, 64, 65, 66, 67,68, 69, 6A, 6B, 6C, 6D, 6E, 6F,70, 71, 72, 73, 74, 75, 76, 77,78, 79, 7A, 7B, 7C, 7D, 7E, 7F,80, 81, 82, 83, 84, 85, 86, 87,88, 89, 8A, 8B, 8C, 8D, 8E, 8F,90, 91, 92, 93, 94, 95, 96, 97,98, 99, 9A, 9B, 9C, 9D, 9E, 9F,A0, A1, A2, A3, A4, A5, A6, A7,A8, A9, AA, AB, AC, AD, AE, AF,B0, B1, B2, B3, B4, B5, B6, B7,B8, B9, BA, BB, BC, BD, BE, BF,C0, C1, C2, C3, C4, C5, C6, C7,C8, C9, CA, CB, CC, CD, CD, CF,D0, D1, D2, D3, D4, D5, D6, D7,D8, D9, DA, DB, DC, DD, DE, DF,E0, E1, E2, E3, E4, E5, E6, E7,E8, E9, EA, EB, EC, ED, EE, EF,F0, F1, F2, F3, F4, F5, F6, F7,F8, F9, FA, FB, FC, FD, FE, FF,

Translat.tbl can either filter, translate, or substitute characters.

Filtering – The default values of the receive table cause it to filter the following characters (next page):


NUL (00) ACK (06) NAK (15) ESC (1B)SOH (01) DLE (10) SYN (16) FS (1C)STX (02) DC1 (11) ETB (17) GS (1D)ETX (03) DC2 (12) CAN (18) RS (1E)EOT (04) DC3 (13) EM (19) US (1F)ENQ (05) DC4 (14) SUB (1A)

Values to be filtered from the transmitting or receiving data stream are preceded by a minus sign. A minus sign indicates that the value following it is ignored.

Translation – The default receive table also translates all “high” ASCII characters (8-bit characters above 127 [decimal] or 7F [hexa-decimal] in value) to “low” ASCII (7-bit) characters by stripping the 8th bit. You will notice in the :RECVTABL illustrated above that the 17th row of the table begins, as does the 1st row, with “-00” and that the lower half of the table duplicates the upper half.

Substitution – You can substitute a new hexadecimal value for any existing default value in either the receive or transmit table. For ex-ample, suppose that you want to replace all upper case “A”s from the received data stream with lower case “b”s. You would:

◊ Find the character “A” in the ASCII table in Appendix D. You will see that the decimal value of “A” is 65 whereas the hexa-decimal value is 41.

◊ Now find the hexadecimal value located in the 65th position of the translate table. Begin counting at the upper left-hand corner of the table (“-00” or “00”), moving from left to right and count-ing down the rows. Start your count from zero, and count until you reach the 65th position. The value in the 65th position is 41, the hexadecimal value for “A”.

◊ Look in Appendix D again and determine the hexadecimal val-ue for “b”. That value is 62.

◊ Replace the value 41 in the translate table with 62. From now on, all “A”s in the received data stream will be translated to “b”s.

NOTE: The default transmit table transmits all characters without filtering, translation, or substitution.


Creating and Editing a Translate FileWhen specifying new values for a translate file, be sure not to delete an entry in the table completely. This will cause all entries in the ta-ble to shift values. To modify the file:

◊ Make a copy of the translat.tbl file.

◊ Modify the new file using a word processor or ASCII text edi-tor. Save the file in text format only.

◊ Locate the desired character position in the table and either en-ter a new value or place a minus in front of the existing value in the table.

◊ Save the new table where BLAST can access it. BLAST will look in the current directory first and then in BLASTDIR.

Text Translation Using a Translate FileCharacters are altered as they are received from the remote system; therefore, what you see on the terminal screen or in a captured file is the altered data. Likewise, transmitted characters are altered after all other processing; the remote system receives altered instead of orig-inal data. It is sometimes necessary to perform text translation while receiving from or transmitting to a remote system when a file trans-fer protocol is not available. For example, a text file on a DOS ma-chine has a carriage return (ASCII 13) and a line feed (ASCII 10) at the end of each line. A UNIX text file only has a line feed at the end of each line. The carriage return can easily be filtered from the data stream by placing a minus sign (-) in front of the 0D character in po-sition 13 of the receive table.

Specifying a Translate File in Your SetupTo specify a translate file for use during a session, type its name in the Translate File setup field.

Standard BLAST Terminals

All versions of BLAST for UNIX provide two terminal types, TTY emulator and PASSTHRU. In addition, BLAST Professional UNIX 10.7x provides other terminal emulators, described in “Terminal Emulation with 10.7x” on page 311.


TTYThe BLAST TTY terminal emulator is a “generic terminal emula-tor” using the character values of the default translate file that allows characters to be sent without any translation or other special han-dling. Received characters are either displayed as text, filtered out, or interpreted as command sequences. For complete character trans-parency, use the PASSTHRU terminal, described in the next section.


During TTY emulation, the following received ASCII characters are interpreted as command sequences (numeric values are in hexadec-imal):

BEL (07) BellBS (08) BackspaceHT (09) Horizontal tabLF (0A) Line feedCR (0D) Carriage return

The TTY emulator filters the following characters:

NUL (00) ACK (06) NAK (15) ESC (1B)SOH (01) DLE (10) SYN (16) FS (1C)STX (02) DC1 (11) ETB (17) GS (1D)ETX (03) DC2 (12) CAN (18) RS (1E)EOT (04) DC3 (13) EM (19) US (1F)ENQ (05) DC4 (14) SUB (1A)

The TTY emulator also converts all 8-bit ASCII characters (above 7F in value) to 7-bit characters.

NOTE: You may change the characters filtered by the TTY emu-lator by modifying and using a translate file. See the preceding sec-tion, “Data Stream Filtering and Alteration,” for complete details.

PASSTHRUThe BLAST PASSTHRU terminal is a “transparent terminal” that allows characters to be sent and received without any filtering, trans-lation, or other special handling. PASSTHRU may be required to re-ceive international characters or to operate a graphics terminal.



There are some special considerations when using PASSTHRU:

◊ XON/XOFF flow control will still be honored.

◊ Setup functions normally available in Terminal mode are ig-nored; for instance, AutoLF IN and AutoLF OUT will not work.

◊ Local Echo will still work.

◊ BLAST will operate in either 7- or 8-bit mode.

◊ Hot Keys and ATTN Key sequences normally available in Ter-minal mode are ignored and will be sent as data (for a discussion of Hot Keys and a list of ATTN Key sequences, see “Keyboard Mapping Utility for 10.7x” on page 315 and “Attention Key Se-quences” on page 346, respectively).

To interrupt Terminal mode and return to the BLAST menu system while in PASSTHRU, type:

ATTN ATTN (pause)

where “pause” indicates no keyboard input for a minimum of two seconds. This will allow the CTRL K sequence to be used in PASS-THRU Terminal mode.

Terminal Emulation with 10.7x

A “terminal” is a video monitor and keyboard that has been custom configured to generate and respond to formatting codes used by a particular computer system. For example, the VT100 terminal was originally designed to operate with Digital Equipment Corporation’s VAX and PDP computers. Particular sequences of ASCII characters were defined to signal special actions, such as cursor movement, printer activation, and screen display behavior. In order to use your system as a terminal to a multi-user host like a VAX, your system must be able to produce and respond to the host’s terminal control codes a process called “terminal emulation.” VT100 terminal em-ulation under BLAST Professional UNIX 10.7x allows your system to operate like a VT100 terminal.

The following emulators are available in BLAST Professional UNIX 10.7x:


BLAST Emulator Terminal EmulatedPC ANSI PC ANSI Color VT52 DEC VT52VT100 DEC VT100VT220 DEC VT220VT320 DEC VT320ADM3A Lear Siegler ADM3AD80 Ampex Dialog 80TV920 Televideo 920 seriesWYSE50 WYSE 50+WYSE60 WYSE 60

Most of these terminals feature unique keys to perform certain func-tions, such as the DO key on a VT220 terminal. Often it is possible to assign a standard key to perform the same task as a special termi-nal key. In other cases, it may be necessary to assign a combination of keys to perform the function—the DO key is mapped to CTRL F5, for example. Thus, your keystrokes are “mapped” or “routed” through BLAST’s software to generate the required sequence of ASCII code for each terminal function. The default keyboard maps for all of BLAST’s emulators are in Appendix B.

The default emulator for a session is specified in the Emulation setup field. To choose an emulator, use SPACEBAR to scroll through the available choices, then press ENTER to accept your choice. The VT, WYSE, and PC ANSI emulators have subwindows that appear auto-matically when you press ENTER. See Chapter 5 for more information on these setup subwindows.

PC ANSI EmulationThe BLAST ANSI emulator provides functional emulation of the IBM PC ANSI standard, including full color and extended attribute support. Choose PC ANSI for dialing Bulletin Board Systems or other computers that offer ANSI support.

DEC VT320, VT220, VT100, and VT52 EmulationThe BLAST VT emulators provide precise emulation of the DEC VT320, VT220, VT100, and VT52 terminals.

Supported Features

These emulators support the following features:

◊ All cursor positioning sequences and tab settings.


◊ All of the software-selectable operating states (or modes) avail-able for the VT series of terminals, including standard ANSI and DEC private modes.

◊ The USASCII, UK, FRENCH, GERMAN, ITALIAN, SPANISH, and DANISH character sets. The default value is USASCII, which allows 8-bit data; the other character sets al-low only 7-bit data.

◊ The DEC Supplemental Graphics and ISO Latin-1 character sets.

◊ Scrolling regions, line and character editing, and character at-tribute commands.

◊ All print operations, including Autoprint, Print Screen, and Printer controller (printer pass-through).

◊ Horizontal Scrolling control to accommodate 132-column dis-play on a standard 80-column screen. The Scroll Left, Scroll Right, and Scroll mode keys may be used within Terminal mode and may be redefined with the blastkbd utility. To set the de-fault mode for the number of columns to scroll, specify the col-umn width in the VT Emulation setup subwindow.


The following features are not supported by these emulators:

◊ Smooth scrolling.

◊ Downloadable character sets. These will be ignored by the ap-plication.

The following features are supported in the specified limited man-ner:

◊ Double-width characters are handled by displaying a single-width character and a space in a double-width position.

◊ Double-height characters are displayed in the top half of a dou-ble-height position.

◊ 132-column mode is supported by scrolling to the left or right on the screen as required to permit viewing of the entire 132 characters.

Refer to Appendix B for the Key Definition Chart.


WYSE 60/50, TV920, D80, and ADM3A EmulationThe WYSE 60/50, TV920, D80, and ADM3A emulators are the functional equivalent of the WYSE 60, WYSE 50+, Televideo fam-ily, Ampex D80, and the Lear Siegler ADM 3A terminals.

Supported Features

These emulators support the following terminal features:

◊ 80- or 132-column modes.

◊ Horizontal scrolling control using the cursor movement keys to accommodate a 132-column display on a standard 80-column screen. To set the default mode for the number of columns to scroll, specify the column width in the WYSE Emulation setup subwindow.

◊ Multiple pages (up to 4 pages; the default is 1).

◊ Split screens.

◊ Normal, dim, blink, blank, underline, and reverse attributes. (These attributes are embedded in the WYSE50+ emulation. They do not occupy a video position in the WYSE60 emula-tion.)

◊ Protected fields and display attributes of write-protected fields.

◊ Graphics characters.

◊ Print functions, including auxiliary and transparent modes.

◊ Editing functions.

◊ Block and character modes.


These emulators do not support programming and displaying func-tion-key labels and label lines.

Refer to Appendix B for the Key Definition Chart.

Transparent Print/Auxiliary PrintBLAST Professional UNIX 10.7x supports Transparent Print mode (data redirected to an attached printer as well as displayed on the screen) under the VT series, PC ANSI, WYSE 60/50, TV, D80, and


ADM3A emulations. In addition, the WYSE 60/50, TV, D80, ADM3A series supports Auxiliary Print mode (data redirected to an attached printer only).

BLAST Professional UNIX 10.7x recognizes the following codes for these functions:

WYSE 60/50, TV, D80, ADM3ATransparent Print mode on: ESC d #Auxiliary Print mode on: CTRL RTransparent and Auxiliary Print mode off: CTRL T

PC ANSI/VTTransparent Print mode on: ESC [5iTransparent Print mode off: ESC [4i

Keyboard Mapping Utility for 10.7x

Computer users sometimes encounter difficulties when emulating a terminal. For example:

◊ A key sequence meant to be passed to the remote computer is instead intercepted by an application (or the operating system).

◊ An emulator keymap is awkward for a particular application.

◊ Repetitive keystrokes are required for a particular application.

◊ A required key does not exist on the user’s keyboard.

For BLAST Professional UNIX 10.7x, the keyboard mapping utili-ty, blastkbd, helps address these problems. In blastkbd, there are three types of specially assigned key subsets in the BLAST key set: Soft Keys, BLAST Keys, and Hot Keys. In addition, blastkbd includes Emulator Maps and User-Defined Maps. Below is a brief description of each, followed by sections giving instructions on mapping and/or remapping each key set:

Soft Keys – Soft Keys allow you to send often-used character strings to a remote system with a single keystroke. The use of Soft Keys is described later in this chapter.

BLAST Keys – BLAST uses special key sequences to differentiate between local commands and characters meant for the remote sys-


tem. The BLAST Keys perform local functions, such as exiting Ter-minal mode. The BLAST Keys are listed in Appendix B.

Hot Keys – Hot Keys access often-used functions from Terminal, Filetransfer, and Access modes. Hot Keys are essentially macros that activate BLAST menu commands and return you to your start-ing point with just a few keystrokes. Typing ALT F from a console in Terminal mode, for example, starts Filetransfer mode and automat-ically returns you to Terminal mode when file transfer is completed. The Hot Keys are listed in Appendix B.

Emulator Maps – These are the keyboard maps for the existing em-ulators within the BLAST program. With blastkbd, you can reroute existing functions to different keys on your keyboard. For a list of keys for the existing emulators, see “Terminal Emulation Keys for 10.7x” on page 348.

User-Defined Maps – You can create your own keyboard maps for different applications, keyboards, or users. Unlike the emulator maps, user-defined maps can specify functions as well as keys.

Running blastkbdYou can start blastkbd by typing blastkbd on the command line or, during a terminal session, by pressing ATTN M or ATTN E. ATTN M will display the main selection window (Figure 17-1) while ATTN E will take you directly to the specific map subwindow for the current em-ulator. From the emulator map, pressing ESC will return you to Ter-minal mode if that is where you started. If you started blastkbd from the command line, pressing ESC from the main blastkbd window will return you to the command line.

FIGURE 17-1


After you have edited a keyboard map or one of the BLAST special key sets, press S to save your changes. Press ESC if you wish to exit without saving the changes.

To select a BLAST special assigned key subset or a map from the blastkbd main window, use the commands described at the bottom of the window to highlight the desired selection and press ENTER.

NOTE: In the subwindows discussed below, some characters can-not be entered merely by pressing the corresponding key on the key-board. The following table indicates how these characters are entered:

ESC CTRL [TAB CTRL IENTER CTRL M^ ^^

For example, to include the escape character in a key sequence, press CTRL [ instead of pressing ESC. Some characters may appear in octal form, for example, CTRL^ may appear as \036.

Soft KeysMany terminals offer a way of storing a set of often-used character strings that can be sent to the remote system with a single keystroke. BLAST provides this capability with Soft Keys. If you highlight Soft Keys in the main window and press ENTER, the Soft Key win-dow (Figure 17-2) will appear:

FIGURE 17-2

To create a Soft Key, highlight the sequence for the Soft Key you have selected (0–9) and enter the text string to be sent to the remote


system when that Soft Key is pressed. Each string can be up to 69 characters long.

BLAST allows ten Soft Keys. A Soft Key is activated from within Terminal mode with the following combination:

ATTN Soft_Key_number

where Soft_Key_number is the number key corresponding to the number of the text string. For example, 0 corresponds to .00 text string, 1 to the .01 text string, and 2 to the .02 text string.

BLAST KeysYou can also use blastkbd to modify the BLAST key subset. When you select BLAST from the BLAST Key set in the blastkbd main window and press ENTER, the BLAST Key subwindow (Figure 17-3) will appear.

FIGURE 17-3

There are four columns the first displays the functions supported by the BLAST Keys and the other three contain the key sequences you choose to perform that function. Up to three key sequences may-be specified for the same function. To remap a function, highlight one of the three key sequences to the right of the function and press ENTER. The message “Press any key to remap function...” is dis-played. Type the key (or combination of keys) that will serve as this function. Repeat this process until you have remapped all the func-tions that you want; then press S to save your remappings and return to the blastkbd main window.

NOTE: BLAST keys do not change from emulator to emulator. For example, if you map the Cursor Down function as CTRL 2 in the


BLAST Keys subwindow while using the VT320 emulator, that se-quence will also perform the same function if you switch to WYSE60 emulation.

You cannot use blastkbd to remap Attention (ATTN) Key sequences. The Attention Key can be remapped via the Attention Key setup field (page 73).

Hot KeysIf you select Hot Keys from the BLAST Key set in the blastkbd main window and press ENTER, the Hot Key subwindow will appear (Figure 17-4). Hot Keys override all other functions. For example, if you map both the VT Find key and the Filetransfer Hot Key to ALT

F, pressing ALT F will always start Filetransfer mode and never act as the VT Find key.

To map or remap a function, highlight the first key sequence to the right of the function and press enter. The message “Press any key to remap function...” is displayed. Type the key (or combination of keys) that will serve as this function. Repeat this process until you have remapped all the functions that you want; then press S to save your remappings and return to the blastkbd main window.

NOTE: A Hot Key can only be mapped to a single keystroke. Any keystrokes entered into the second column will be ignored by BLAST.

FIGURE 17-4

Emulator MapsEmulator maps act as links between your keyboard and the terminal you are emulating. For example, if you are using an AT extended


keyboard through the VT320 emulator to a VAX minicomputer, the keymap will link the FI key to the VT320 PF1 function. To select an emulator, highlight the emulator in the blastkbd main window and press ENTER; the emulator subwindow will then appear. For example, if you select VT320/VT220, the subwindow in Figure 17-5 will ap-pear.

FIGURE 17-5

To remap a function, highlight one of the three key sequences to the right of the function and press ENTER. The message “Press any key to remap function...” is displayed. Type the key (or combination of keys) that will serve as this function. Repeat this process until you have remapped all the functions that you want; then press S to save your remappings and return to the blastkbd main window. Up to three key sequences maybe specified for the same function.

User-Defined MapsA powerful feature of blastkbd is the option to create your own key-board maps for different applications, keyboards, or users. For ex-ample, you can customize a map for a remote database application and save it under the name “data,” ready for use with BLAST. Once you have finished working with the database, you can load another map for another application.

To create a map, press A at the blastkbd main window. You will be prompted for the name of the new map. Pressing ENTER will add the new map name to the list of maps in the blastkbd main window (the map name will also appear as a selection in the Keyboard File setup field). Pressing ENTER again will display the mapping subwindow (Figure 17-6, next page). Unlike the emulator maps, user-defined maps allow you to specify the function as well as the keys.


The first step in assigning a function is to type the name of the func-tion. If no functions have been assigned, simply type the name of the function in the field highlighted.To add a function, type A and then the name of the function you would like to add. After typing the name of the function, press ENTER. The first key sequence will automatical-ly be highlighted. Type the key sequence for the function you have just added and press ENTER. At the bottom of your screen, you will be prompted for the ASCII control sequence. Type either the ASCII control sequence or octal value for that function (for a list, see Ap-pendix D) and press ENTER. If you would like to add a second key sequence for the function or change an existing key sequence, high-light the desired key sequence to the right of the function and follow the same steps as you followed in entering the first key sequence. After you have finished mapping functions, press S to save your map.

FIGURE 17-6

Keyboard Map Selection in the SetupAll maps that you create are saved in a file called “blast.tdf.” Each time that you start BLAST, it will search the current directory for blast.tdf. If it cannot be located, BLAST then checks BLASTDIR. You can easily assign separate keymaps for several users or applica-tions by copying different blast.tdf files into each directory. When you run BLAST from within an application directory, the proper blast.tdf file will automatically be loaded.

To select a specific user map from within a given .tdf file, highlight the Keyboard File setup field and use the SPACEBAR to cycle through the map choices. If you would like a map to be loaded automatically on startup, save it as a part of the setup.



Chapter 18

Remote Control with 10.7x

What Is Remote Control?

For computers running BLAST Professional UNIX 10.7x from the console, the Remote Control features allow you to access and con-trol the screen, keyboard, disk drives, and printer of a remote DOS PC running the BHOST program. Remote control is ideal for trou-bleshooting remote sites, training and supporting DOS operators, us-ing DOS software—any time that you need complete control over a remote computer running DOS.

This chapter introduces basic concepts and guides you through the features of BLAST remote control. The BHOST User Manual de-scribes how to set up the remote computer for control by BLAST. Workstation users cannot remotely control a PC, but they can oper-ate as limited DOS terminals and can transfer files through BHOST.

Remote control allows a UNIX computer (the Controller) to com-pletely control a DOS PC (the Host PC). The two systems can use a hardwire connection, a null modem cable, or modems communicat-ing over a telephone circuit.

REMOTE CONTROL 323

The Controller can run programs on the Host PC’s hard drive, print documents, edit files, and more, as if the user were typing on the Host PC’s keyboard. All video output and graphics are displayed si-multaneously on both systems, with automatic translation between different video modes.

The Host PCThe Host PC runs the BHOST program, which operates transparent-ly in the background. BHOST “watches” the communications port and, when a call comes in, prompts the caller for a user identification and password. Once the caller is logged in, BHOST makes the Host PC’s services available to the Controller.

The Host PC has access to a number of security features, including login accounts, multiple control levels, call-back security, and a log file to record system activity.

Nearly all of the configuration for a remote control session takes place on the Host PC through SETBHOST, a special administration program that sets system defaults and keeps track of login accounts.

The ControllerThe Controller runs BLAST and dials into a Host PC just as in an ordinary terminal session except that, once connected, the user of the Controller selects Access from the Online menu. Access mode al-lows complete control. (File Transfer Only and Terminal modes, discussed later, offer more limited control.)

In Access mode, the Controller can access a number of security fea-tures, including the ability to disable the Host keyboard, mouse, and screen during a session to prevent unauthorized operation.

Connecting to the Host PC

Connecting to the Host PC is the same as connecting to any other re-mote system. BLAST can automatically dial the phone and send your login ID and password to the Host PC. You may also perform this process manually.

Be sure that BHOST has been installed and configured on the Host PC before attempting to connect. See the BHOST User Manual for more information on installing and configuring BHOST.

324 CHAPTER EIGHTEEN

Creating a BLAST Setup for BHOSTTo automate your connection to a Host PC, create and save a new BLAST setup for your sessions with the Host PC (see Chapter 5 for a detailed description of setups). In the new setup:

◊ If you are using a modem, set the Phone Number to the phone number of the Host PC.

◊ Set the System Type field to BHOST if your BHOST account re-quires a login ID and password; set System Type to PC or NONE if your BHOST account does not require a login ID or pass-word.

◊ If your BHOST account requires a login ID and password, enter these into the Userid and Password setup fields, respectively, exactly as they appear in SETBHOST on the Host PC. These fields are case-sensitive.

◊ Set Emulation to TTY or VT320.

◊ Set Protocol to BLAST.

◊ Set Packet Size to at least 200, BHOST’s minumum setting; the maximum setting is 4085.

◊ In the BLAST protocol setup subwindow, set Compression Level according to the type of data you will transfer. Note that BHOST’s compression level defaults to 1. Any additional com-pression is determined by the amount of memory allocated by a COMPBUF assignment in BLAST.OPT on the Host PC. BHOST supports compression levels 0–4.

Use the Write command from the Online menu to save the new setup.

Making the Connection and Logging OnChoose the new Host PC setup in your Setup Directory and select Connect from the Online menu. BLAST will make the connection, log onto the Host PC, and return to the Online menu.

NOTE: If your BHOST Account is set to Dial Back, BLAST will not return to the Online menu immediately. Instead, BHOST will disconnect after you log in and then dial your phone number from the Host PC. Once the connection has been re-established, BLAST will return to the Online menu.

REMOTE CONTROL 325

Taking ControlHow you take control of the Host PC depends on the Control mode setting in your BHOST Account. The possible settings are Access, File Transfer Only, and Terminal. The default Control mode is Access, which provides complete control over the Host PC.

Access mode – If your Control mode is set to Access, then press A from the Online menu to enter Access mode. You will then have complete control over the Host PC. All of your keystrokes are sent to the Host PC, and all of the Host PC’s screen displays are sent to your system. Access mode offers a number of powerful features. See “Using Access Mode” below for complete details.

File Transfer Only mode – If your Control mode is set to File Transfer Only, then press F from the Online menu to enter BLAST Filetransfer mode. The BLAST Filetransfer menu will then appear, and you will be able to Send and Get files and execute oper-ating system commands from the Local and Remote menus.

Terminal mode – If your Control mode is set to Terminal, then press T from the Online menu to enter Terminal mode. Terminal mode is limited to ASCII text display. Programs using graphics or full-screen text modes will execute, but the screen display will be corrupted and no error detection will be performed. Terminal mode requires special keyboard sequences to send control characters. See “Using Terminal Mode with 10.7x and 10.8x” on page 330.

Disconnecting from the Host PCFrom Access mode – Press ATTN ESC to return to the Online menu.

From File Transfer Only mode – Press ESC to return to the Online menu.

From Terminal mode – Press ESC CTRL L to log off of the Host PC and then press ATTN ATTN to return to the Online menu. Select the Disconnect command to disconnect from the Host PC.

Using Access Mode

Access mode is very intuitive—all you have to do is type commands as if you were seated at the Host PC. Through the Access menu, BHOST provides several easy-to-use support features, such as:


◊ Split-screen Chat mode, for communicating interactively with the Host PC user.

◊ Two camera modes, one for taking “snapshots” of individual screens and one for recording “movies” of your session.

◊ A simple menu for fine-tuning your remote control settings.

◊ Hot Keys to start file transfers, exit to a local system shell, re-boot the Host PC, and more.

The Access MenuFrom Access mode, press ATTN to display the Access menu shown below in Figure 18-1.

FIGURE 18-1

To select a command, press the capitalized letter in the command name or move the cursor over the command and press ENTER. Fol-lowing is a description of each command:

Resume – Press R to return to Access mode.

Chat – Press C to start Chat mode. Chat mode allows the Host and Controller to type messages to each other on the Chat screen (Figure 18-2, next page), which is displayed on both the Controller and the Host screens. Either side may initiate a Chat unless the Host keyboard has been disabled. Once the Controller initiates a Chat, a disabled Host keyboard be-comes active for the duration of the Chat.

REMOTE CONTROL 327

FIGURE 18-2

The Chat screen contains two windows, one for the Control-ler’s messages and one for the Host’s messages. Both sides may type at the same time. Chat mode will terminate when either user presses ESC.

Parameters – Press P to display the Session Parameters window containing parameter fields that can be adjusted to improve BHOST performance (see “Modifying BHOST Settings with 10.7x” on page 332).

Snapshot – Press S to take a snapshot of the current screen. You will be prompted for a filename. After typing the filename and pressing ENTER, you will be returned to the Access menu. The current screen image will be saved to your current directory. If you type in a filename without an extension, BLAST automatically uses the extension “.001.” Then, each time you take another snapshot, BLAST increments the extension by one (up to .099) and prompts you to save the new file.

BLAST saves text screens in standard ASCII file format and graphic screens in the .PCX format, which can be displayed with the View command from the Local menu or by a variety of third-party applications.

Record – Press E to record a “movie” of the screen appearance dur-ing your session (except Chat mode displays). You will be prompted for a filename. Type the filename and press ENTER. BLAST will then begin recording from the Host PC similar to VCR recording from a television. Escaping from the remote session screen for any reason will termi-nate the movie.


Movies can be replayed with the View command from the Local menu. By default, a movie is replayed at the same speed at which it was recorded. Press the up or down cur-sor keys during replay to speed up or slow down the mov-ie. Note that movies can take up large amounts of disk space.

Local – Press L to display the Local menu for local system com-mands. This command is identical to the Local command available from the Offline and Online menus (see “The Lo-cal Menu” on page 58 for details).

Access Mode Hot KeysThe following subset of the regular BLAST Hot Keys are active dur-ing Access mode:

Function Default Key SequenceChat mode *Local View *Local System *Remote Reboot *Snapshot *Parameters *Record a movie *Filetransfer mode ALT F

* To avoid potential conflicts with the programs running on the Host PC, these keys do not have default values. When you assign keys through the blastkbd utility, remember that the values you pick will not be available to the Host PC programs. For example, if you assign the ALT V key combination to the Local View function, then ALT V will never be sent to the Host PC, because it will be interpreted as a local command.

See “Hot Keys” on page 319 and Appendix B for more information on remapping Hot Keys.

Using File Transfer Only Mode with 10.7x and 10.8x

File Transfer Only mode allows more limited control of the remote PC than Access mode. This mode is available for both BLAST Pro-fessional UNIX 10.7x and 10.8x. In File Transfer Only mode, the lo-cal user can transfer files between the local computer and the PC using the Filetransfer menu and can perform remote commands us-

REMOTE CONTROL 329

ing the Remote menu (page 60). To enter Filetransfer mode, press F from the Online menu.

Using Terminal Mode with 10.7x and 10.8x

If you are running 10.8x or are running 10.7x at an attached terminal, Terminal mode via BHOST allows you to act as a terminal to the Host PC. In Terminal mode, you will be able to run programs with line-mode ASCII text displays. Programs using graphics or full-screen text modes will execute, but the screen display will be cor-rupted and no error detection will be performed.

Starting and Ending Terminal ModeIf you are running 10.8x or are running 10.7x at an attached terminal, the Host PC Control mode should be set to Terminal. To begin Terminal mode, select Terminal from the Online menu. You can re-turn to the Online menu at any time by pressing ATTN ATTN.

When you are ready to log out, you must log out of Terminal mode correctly: Press ESC CTRL L—you will automatically be logged out of BHOST on the Host PC. You can then return to the Online menu by pressing ATTN ATTN; then hang up the modem by selecting Dis-connect.

Escape SequencesTerminal mode requires special escape sequences to represent cer-tain keys to the Host PC:

PC Key Escape SequenceLeft Arrow ESC FRight Arrow ESC GUp Arrow ESC TDown Arrow ESC VHome ESC HEnd ESC EPage Up ESC PPage Down ESC QInsert ESC IDelete ESC DNumeric Keypad 5 ESC . (period)Numeric Keypad * ESC *Break ESC SCaps Lock ESC KNum Lock ESC N


PC Key Escape SequenceNumeric Keypad + ESC +Numeric Keypad - ESC -F1–F10 ESC 1 ESC 0Esc ESC ESC Esc ESC ESC All keys released ESC SPACECtrl ESC CAlt ESC ALeft Shift ESC ZRight Shift ESC /

The following escape sequences send special commands to BHOST:

PC Key ESCape SequenceFiletransfer mode ESC CTRL XRepaint Screen ESC CTRL ROpen Session Command window ESC CTRL MLog off ESC CTRL L

Transferring Files to and from the Host PC

The BLAST protocol is available for transferring files to and from the Host PC. Your transfers will take place in the background on the Host PC, transparent to the Host PC user.

Starting Filetransfer ModeThere are several ways to initiate a file transfer to or from the Host PC. In each case, the BLAST Filetransfer menu appears, and you will be able to Send and Get files and execute operating system com-mands from the Local and Remote menus.

From the Online menu — Press F to start Filetransfer mode. Use this method if your BHOST account is set to File Transfer Only.

From Access mode — Press the ALT F Hot Key, or press ATTN ESC to return to the Online menu and then press F to start Filetransfer mode.

From Terminal mode — Press ESC CTRL X to start Filetransfer mode on the Host PC; then use one of the above methods to start Filetrans-fer locally.

REMOTE CONTROL 331

Transferring FilesYou may transfer files interactively (see “Performing Filetransfer Commands” on page 107) or via BLAST scripts (see “File Transfers with BLAST Session Protocol” on page 194).

Ending Filetransfer ModeWhen you have finished transferring files, press ESC to end File-transfer mode. If you started Filetransfer mode with a Hot Key, you will be returned to Access or Terminal mode. Otherwise, you will be returned to the Online menu.

Modifying BHOST Settings

Modifying BHOST Settings with 10.7xIf you are running 10.7x in Access mode, you may alter BHOST pa-rameter settings by starting SETBHOST from the console. To start SETBHOST, type SETBHOST at the command line. For details on configuring BHOST via SETBHOST, see the BHOST User Manual. Note that the new settings will not take effect until BHOST has been restarted.

If you are in Access mode and have a Superuser account, you may alter BHOST session parameters by choosing Parameter from the Access Menu. The Session Parameters window (Figure 18-3) will then appear. Move through the fields by pressing the arrow keys; move through the options of a field by pressing SPACE or BACK-

SPACE.

FIGURE 18-3


If you have a User account, you may change all of the settings on the Session Parameters screen except Inactivity T/O, Timeout Re-sponse, and DCD Loss Response. If you have a Restricted ac-count, you will not be able to change any of the session parameter settings. If you change any of the settings via the Session Parameters window, the new settings will be in effect only for the duration of the session. Following is a description of the Session Parameter fields.

Scaling Ratio [1:1] 1:4 1:16 1:64

Specifies how the Host PC’s graphics are scaled for screen updates. BHOST usually sends the entire Host screen to the Control PC. The Scaling Ratio allows certain portions of the screen to be omitted, re-sulting in much faster performance. Scaling Ratio only applies to graphics screens.

When Scaling Ratio is set to a value other than 1:1, BHOST divides the Host PC screen into square grids and sends only the value of the first pixel in the grid. The Control PC then substitutes that value for each of the remaining pixels in the grid.

For example, when Scaling Ratio is set to 1:4, BHOST sends only the first pixel of a 4-pixel grid. The Control PC writes that value for all four of the pixels in the grid.

1:1 – the entire Host screen is sent to the Control PC. 1:4 – the Host PC sends 1 pixel from a 4-pixel grid. (25% of the Host PC screen).

1:16 – the Host PC sends 1 pixel from a 16-pixel grid. (6.25% of the Host PC screen).

1:64 – the Host PC sends 1 pixel from a 64-pixel grid. (1.5% of the Host PC screen).

Use a higher Scaling Ratio (1:4, 1:16, or 1:64) when you want to see screens as quickly and image quality is not important.

Scan Interval NONE HIGH[MEDIUM] LOW

Specifies how often BHOST scans the Host PC’s display to see if the display has changed since the last scan. If it has, BHOST rescans the display and sends the new screen to the Control PC.

REMOTE CONTROL 333

The higher the Scan Interval, the more often the display is updated. A higher Scan Interval, however, usually means slower program speed since the foreground application on the Host PC must be in-terrupted for the scan, and each image must be sent to the Control PC.

HIGH – The Host screen is scanned 18.2 times per second (after each PC clock tick).

MEDIUM – The Host screen is scanned twice per second (after each 8 PC clock ticks).

LOW – The Host screen is scanned once per second (after each 18 PC clock ticks).

NONE – The Host screen is scanned only when the operating system is not updating the screen.

Sync Mode [ON] OFF

Specifies whether the Host PC and the Control PC screens will be synchronized.

When this field is set to ON, the Host PC screen is frozen while screen updates are sent to the Control PC. This mode completely synchronizes the two displays, but it slows the application speed.

When this field is set to OFF, the Host PC screen is not frozen, re-sulting in significantly faster performance. The Control PC, howev-er, may miss some intermittent screen images.

Special KBD Handling ON [OFF]Enables/disables Special Keyboard Handling.

IMPORTANT: This field should be set to ON.

Inactivity T/O 0 - 999 [120]Specifies the number of seconds the Host PC will wait after no data has been sent or received before performing the action specified in the Timeout Response field (RESTART or REBOOT).

If this field is set to 0, the Host PC will not time out.


If this field is set to 0 and the DCD Loss Response field is set to IG-NORE, the Host PC modem may reset itself immediately after carrier is lost, even though BHOST is not ready to process incoming calls. In this case, BHOST will not restart without manual intervention, but the modem will continue to answer calls. To restart BHOST manually from the Control PC, first connect to the Host PC’s mo-dem; then enter Terminal mode and type:

;DISC.

Note that you will not be able to see your keystrokes. This sequence will interrupt the BLAST protocol and allow BHOST to restart—it may also cause the Host PC’s modem to hang up. After BHOST has restarted, you may log on as usual.

Timeout Response [RESTART] REBOOT

Specifies the action that the Host PC will take if an Inactivity Time-out occurs. RESTART prepares the Host PC for the next caller, dis-connecting the current user. REBOOT forces the Host PC to perform a warm boot just as if it had been physically rebooted with the CTRL ALT DEL sequence.

NOTE: If this field is set to REBOOT, the Host PC will not neces-sarily reload BHOST—you must specify BHOST in the Host PC’s AUTOEXEC.BAT file to insure that the Host PC will be ready to answer incoming calls.

DCD Loss Response RESTARTREBOOT [IGNORE]

Specifies the Host PC’s actions if the modem’s Data Carrier Detect (DCD) signal is lost during a session.

RESTART – restarts BHOST after DCD loss and prepares for the next caller. This is the recommended setting if you are using a mo-dem and have an appropriate connection between the system and modem.

REBOOT – reboots the Host PC after DCD loss. Note that, with this setting, BHOST will not necessarily be reloaded. If BHOST is not loaded from the Host PC’s AUTOEXEC.BAT file, the Host PC will remain at the DOS prompt when rebooted.

REMOTE CONTROL 335

IGNORE – ignores DCD loss. In order for BHOST to detect DCD Loss through an external modem, the modem cable must support the DCD signal. All standard modem cables support this signal.

IMPORTANT: If DCD Loss Response is set to IGNORE and carrier is lost during a session, the Host PC modem may reset itself immediately, even though BHOST is not ready to process incoming calls. In this case, BHOST will not restart and the Host PC will not be able to process incoming calls until the Logon T/O or Inactivity T/O takes effect.

Host Keyboard [ON] OFF

Enables/disables the Host PC’s keyboard. When this field is set to OFF, the Host Keyboard is completely disabled from the time BHOST is run; to regain control of the keyboard, you must reboot the Host PC or change this setting remotely. The Control PC may still initiate Chat Mode with the Host PC; in this case, the Host key-board is enabled for the duration of the Chat.

IMPORTANT: If Host Keyboard is set to OFF and BHOST is started from the Host PC’s AUTOEXEC.BAT, the Host PC’s keyboard will remain dis-abled, even after rebooting. If this situation occurs, dial into the Host PC and change the Host Keyboard setting through SETBHOST.

This feature prevents unauthorized interference with a Control ses-sion.

Host Mouse [ON] OFF

Enables/disables the Host PC’s mouse. When this field is set to OFF, the Host mouse is completely disabled, preventing unauthorized in-terference with a Control session.

Host Screen [ON] OFF

Enables/disables the Host PC’s screen. When this field is set to OFF, the Host screen is completely disabled from the time BHOST is run, preventing anyone from seeing what is being sent to the Control PC’s display.

When Host Screen is set to OFF, the Control PC may still initiate Chat Mode with the Host PC; in this case, the Host screen is enabled for the duration of the Chat.

IMPORTANT: If Host Screen is set to OFF and BHOST is started from the Host PC’s AUTOEXEC.BAT, the Host PC’s screen will remain disabled


even after rebooting. If this situation occurs, try typing BHOST /k at the DOS prompt (you will not be able to see the characters on the screen). If that does not work, dial into the Host PC and change the Host Screen setting through SETBHOST.

This feature prevents unauthorized interference with a Control ses-sion.

Host Printer [NONE] LPT1 LPT2 LPT3

Specifies the Host PC printer to be used during a session. BHOST will monitor the printer port you specify here and redirect printing to the locations listed in the Printer(s) Enabled field.

If you plan to print during a session, set this field to the Host PC’s printer port. You may notice a slight performance decrease.

If you do not plan to print during a session, set this field to NONE.

Printer(s) Enabled [NONE]CONTROL HOST BOTH

Specifies which printers will be active during a session. When an ap-plication issues a print command, the command will be executed on the printers specified here.

NONE – printing is disabled.

CONTROL – enables only the Control PC’s default printer.

HOST – enables only the Host PC’s printer as specified in the Host Printer field.

BOTH – enables both Host and Control printers.

Modifying BHOST Settings with 10.8xIf you are using a version of BLAST that does not support Access mode, such as 10.8x, you may alter the BHOST session parameters via the Session Command window (Figure 18-4, next page). To open the Session Command window, go to Terminal mode and press ESC CTRL M. Commands are entered as lines of text using the follow-ing format:

parameter_command=value

REMOTE CONTROL 337

where parameter_command is one of the parameter commands listed in the table below and value is a valid setting for the param-eter (see preceding section for setting options).

To check the current value of a session parameter, simply type the parameter_command for the parameter. For example, to display the current value for the Host Keyboard parameter, type:

keyboard

To see the values for all session parameters, type:

settings

Each parameter will be listed along with its current value. The fol-lowing commands are available:

Parameter Command ParameterDCDResp DCD Loss Response Inactimo Inactivity T/O Keyboard Host KeyboardMouse Host Mouse Print Printer(s) EnabledPMouse Precision Mouse (unsupported; set to OFF) Printer Host Printer Screen Host Screen Scale Scaling Ratio Scan Scan Interval SKeyboard Special KBD ModeSync Sync Mode TimoResp Timeout Response

To close the Session Command window, press ESC.

FIGURE 18-4


Appendix A

Error Messages

Introduction

The following is a list of BLAST error codes and a brief description of the cause of each error. Error messages for most versions of BLAST are included in this list. Even though they may not apply to the version running on the local computer, they may occur on the re-mote system.

BLAST Protocol Functions

20 loss of carrier during protocol logon21 logon timeout

(A BLAST protocol session was not established within the time specified by the BLAST Protocol Logon Tim-eout. See the Logon Timeout setup field description on page 84 for details.)

22 console interruptthe ATTN key was typed

23 inactivity timeout

ERROR MESSAGES 339

(A BLAST protocol session was terminated because of inactivity. See the Inactivity Timeout setup field de-scription on page 85 for details.)

24 error in processing command file25 cannot start BLAST on remote system26 remote disconnect

(The remote system timed out during a BLAST proto-col session or the remote operator pressed the ATTN key.)

27 attempt to connect with an incompatible private net-work(There are special versions of BLAST that are limited to use within a particular network of systems. Use of these special versions outside of the network or use of a standard BLAST version within the network will give this message.)

29 connection control string timeout30 loss of carrier during protocol connection

Transfer File Management

31 error-free file not found, or cannot be accessed(Often occurs because the file or directory does not have read permission.)

32 error-free file cannot be created(Often occurs because the file or directory does not have write permission.)

33 error-free file cannot be deleted(Check permissions on the directory.)

34 error occurred while closing the error-free file(This error occurs whenever BLAST cannot close an open file during Filetransfer mode.)

35 cannot position within the error-free file(This error occurs when BLAST cannot close an open file during Filetransfer mode.)

36 error occurred while reading the error-free file37 error occurred while writing to the error-free file

(Running out of disk space is a common cause of this error.)

38 size conflict39 filename is too long or invalid40 a file already exists with that name41 error reading file directory

(Check the permissions of the directory.)42 error writing to disk; disk is full

340 APPENDIX A

48 permission denied(Your user profile on a multi-user system or the file at-tributes do not permit the current BLAST operation.)

49 transfer not allowed

Utility File Management

51 error opening a data file52 error creating a data file53 error deleting a data file54 error closing a data file55 error positioning within a data file56 error reading from a data file57 error writing to a data file58 error in the size of a data file59 error renaming a data file60 directory specified in environment is invalid61 SETUPDIR is not a directory62 OPTDIR is not a directory

Scripting

65 script variable is READ-only66 user-defined script error command67 cannot find entry in modems.scr or systems.scr68 no matching label for GOTO70 error executing COMMAND.COM71 all local commands complete72 invalid file transfer switch specified73 cannot overwrite or append74 unknown file type75 file already exists76 too many open scripts77 cannot load setup78 setup already exists or cannot be created79 not a valid directory80 no setups found81 no setup has been selected82 upload cancelled83 8-bit protocol requires an 8-bit channel; switching to

7-bit84 packet size is too large; packet size too small for Ac-

cess

ERROR MESSAGES 341

85 remote control terminated by remote system86 incompatible video mode88 cannot initialize emulator89 error printing, cannot open file

Command File Processing

90 error processing a command file(Syntax error in a BLAST script file while using vid-eo-suppress mode.)

Memory

105 error allocating memory

Initialization

100 error allocating memory from the BLAST memory pool

101 environment variable TERM is too large102 cannot extract control strings from terminal informa-

tion database(The TERM environment variable is not defined or the specified terminal type in TERM is incorrect.)

103 terminfo control string is too large104 environment variable TERM is empty

(Set the TERM environment variable. Depending on operating system you may have to “export” TERM.)

105 error allocating memory from the system108 cannot load specified setup file

(The setup file specified does not exist in either the current directory or the directory specified by the SET-UPDIR environment variable.)

109 error in processing translate table update file110 compression error111 cannot execute a child process112 error creating a pipe113 cannot fork 117 cannot ioctl () the console port118 cannot open the console port119 cannot ioctl () the communications port

342 APPENDIX A

120 cannot open the communications port1)You may have selected an invalid communications port.2)Check the physical connection to the port. Make sure that the port specified is the actual port set up for communications.3)The port may be in use or may not have been re-leased by another system process. Reboot the comput-er and load only BLAST to test the physical connection.4)The computer may be using an interrupt and/or base address that is not standard. Edit the BLAST.OPT to include proper address and IRQ.5)The hardware flow control (RTS/CTS) or Carrier Detect signals may not be configured to handle the port signals directly.6)Other applications may not have closed all ports when exiting. From the BLAST directory, type BLAST /I so that BLAST bypasses any checking of ports done by other applications.

121 a lock file exists for the communications port(Check the /usr/spool/uucp and/or /usr/spool/locks directories for a LCK.Portname file. Delete the lock file if appropriate. This is a System Ad-ministrator function.)

122 error in terminal definition123 function not available in background mode124 network error occurred125 BLASTNMP.EXE not loaded126 network drivers not loaded

(If using TCP/IP, be sure that the name of the TCP/IP TSR matches the one specified in BLAST.OPT.)

127 Read error128 unexpected signal129–144 UNIX signal. Signal number is determined by sub-

tracting 128 from the BLAST error number. This cor-responds to UNIX signals 1–16.

150 Read error on comm port151 Write error on comm port210 compression error253 internal error

Script Processor

300–399 syntax error in command

ERROR MESSAGES 343

400 too many strings

Network

502 fatal network error; BHOST terminated

344 APPENDIX A

Appendix B

Key Definition Charts

BLAST Keys

BLAST menu functions are selected and controlled by the following keys.

Function 10.7x Console 10.7x Terminal 10.8xCursor Up UP (↑ ) CTRL E CTRL ECursor Down DOWN (↓ ) CTRL X CTRL XCursor Left LEFT (←) ——— ———Cursor Right RIGHT (→) ——— ———Move to First Field PGUP CTRL R CTRL RMove to Last Field PGDN CTRL C CTRL CClear text in Field CTRL T CTRL T CTRL TCANCEL ESC ESC ESC or CTRL AHELP F1 ? ?HELP (Terminal mode) ATTN H ATTN H ATTN H

10.7xBLAST menu functions can be remapped with the BLAST Key-board Utility, blastkbd (see “Keyboard Mapping Utility for 10.7x” on page 315).

KEY DEFINITION CHARTS 345

Attention Key SequencesAttention Key sequences are only active from Terminal mode. For BLAST Professional UNIX 10.8x, terminal emulation must be set to TTY. The sequences cannot be remapped, but the Attention key can be redefined by entering a new setting in the Attention Key setup field (page 73).

ATTN ATTN Return to the Online menu.ATTN B Send a break signal (also interrupts an active

BLAST script).ATTN C Toggle Capture mode on or off.ATTN H Display Online Help

Hot Keys BLAST features Hot Keys for accessing certain functions from Ter-minal and Filetransfer modes (and Access mode in 10.7x). Not all functions are available from all modes (see chart below). Hot Keys are essentially macros that activate BLAST menu commands and re-turn you to your starting point with just a few keystrokes. For exam-ple, in Terminal mode, typing ALT F in 10.7x and CTRL F in 10.8x starts Filetransfer mode and automatically returns you to Terminal mode when file transfer is completed.

Hot Keys are not available while BLAST scripts are running. To make Hot Keys active after an automated logon, be sure that the script command after TERMINAL is either QUIT or RETURN.

10.7x

ATTN E Start blastkbd, the BLAST keyboard remapping utility, with the current emulator selected.

ATTN M Start blastkbd, the BLAST keyboard remapping utility.

ATTN N Reset XON/XOFF Pacing.ATTN P Toggle printer logging on or off.ATTN 0–9 Start a BLAST Soft Key (digit is the Soft Key num-

ber).

10.7x

Function Key Available Mode

Abort BLAST ALT X TerminalConnect ALT C TerminalDisconnect ALT D TerminalLearn ALT R TerminalSelect setup ALT S Terminal

346 APPENDIX B

10.7x

Function Key Available ModeModify setup ALT M TerminalNew setup ALT N TerminalWrite setup ALT W TerminalAccess ALT A TerminalLocal Edit ALT E Terminal, FT Local Print * Terminal, FTLocal Type * Terminal, FTLocal List ALT L Terminal, FTLocal View * Terminal, FT, AccessLocal System * Terminal, FT, AccessFiletransfer ALT F Terminal, AccessRemote Reboot * AccessSnapshot * AccessChat * AccessParameters * AccessRecord * Access

FT=Filetransfer

* To avoid potential conflicts during remote control sessions, these keys do not have default values. When you assign keys through the BLAST keyboard mapping utility, blastkbd, remember that the values you pick will not be available to the Host PC programs dur-ing remote control sessions.

You can remap Hot Keys with blastkbd (see “Hot Keys” on page 319).

10.8x

Function Key Available Mode

Filetransfer CTRL F TerminalLocal System CTRL N TerminalLearn CTRL R Terminal

Terminal emulation must be set to TTY.


Terminal Emulation Keys for 10.7x

Press ATTN E or ATTN M from Terminal mode to view the blastkbd screen for these emulators (see “Terminal Emulation with 10.7x” on page 311).

DEC VT320 and VT220 KeysFunction PC Key

Shift Tab SHIFT TAB

Backspace CTRL BACKSPACE

Del BACKSPACE

Cursor Up UP Cursor Down DOWN Cursor Left LEFT Cursor Right RIGHT Keypad 0 – 9 keypad 0 – 9 Keypad - keypad - Keypad , keypad * Keypad Enter Key keypad + Keypad . keypad . PF1 – PF4 F1 – F4Hold Screen F5Print Screen ALT PToggle Auto Print CTRL PRTSC

Scroll Left CTRL LEFT

Scroll Right CTRL RIGHT

Scroll mode (not mapped)Find INS

Ins Here HOME

Remove PGUP

Select DEL

Prev Screen END

Next Screen PGDN

F6 – F12 F6 – F12F13 – F20 CTRL F3 – CTRL F10Help CTRL F5Do CTRLF6Shift 6 – F12 SHIFT F6 – F12Shift F13 – F20 (not mapped)

348 APPENDIX B

DEC VT100 and VT52 KeysFunction PC Key

Shift Tab SHIFT TAB

Backspace CTRL BACKSPACE

Del BACKSPACE

Cursor Up UP Cursor Down DOWN Cursor Left LEFT Cursor Right RIGHT Keypad 0–9 keypad 0–9 Keypad - keypad - Keypad , keypad * Keypad Enter Key keypad + Keypad . keypad . PF1–PF4 F1–F4Hold Screen F5Print Screen ALT PToggle Auto Print CTRL PRTSC

Scroll Left CTRL LEFT

Scroll Right CTRL RIGHT

Scroll mode (not mapped)

PC ANSI KeysFunction PC Key

Backspace BACKSPACE

Del DEL

Cursor Up UP Cursor Down DOWN Cursor Left LEFT Cursor Right RIGHT PF1–PF4 F1–F4

WYSE 60, WYSE 50, TV920, D80, and ADM3A Keys Function PC Key

Backspace CTRL BACK

Del BACK

Enter ENTER

Return keypad +


Function PC KeyBack Tab SHIFT TAB

Print ALT PSend ALT BScroll Lock ALT ZUnlock Kybd ALT UCursor Up ESC [ACursor Down ESC [B

Cursor Left ESC [D

Cursor Right ESC [C

Home HOME

Shift Home CTRL HOME

Page Up PGUP

Page Down PGDN

Clear Line END

Clear Screen CTRL END

Del Char DEL

Del Line CTRL DEL

Ins Char INS

Ins Line CTRL INS

Ins/Replace ALT IF1–F12 F1–F12

F13–F16 CTRL F3–CTRL F6

Shift F1–Shift F12 SHIFT F1–F12

Shift F13–Shift F16 (not mapped)

350 APPENDIX B

Appendix C

Troubleshooting

1. “I’m getting the message ‘A lock file exists for the comm port’ when I try to go online. What’s wrong?”

The communications port, or more specifically the serial port, is probably locked so that only one program at a time can use it. If a lock file exists for the serial port, BLAST assumes that another pro-cess is using it. Sometimes a lock file is left by a process that termi-nates abnormally. In this case, you must delete the lock file before BLAST can take control of the port. Lock files are kept in direc-tories such as /etc, /var/spool/locks, /usr/spool/uucp, and /usr/spool/locks, depending on the particular version of UNIX that you have. Consult your System Administrator for the correct loca-tion of the lock file directory. Deleting lock files is normally a Sys-tem Administrator function. See Chapter 2 for additional information.

2. “I get the message ‘Unable to open communications port’ when I try to go online. What’s wrong?”

Make sure that you have specified the port correctly in your setup and that another process is not currently using the port. For example, a getty might be running on the communications port or a lock file

TROUBLESHOOTING 351

might exist even though the process that created the lock file has ter-minated. See Chapter 2 for additional information.

3. “Soon after going online I get the message ‘Read error’ or ‘read error on port’ and BLAST is terminated. What happened?”

The most common reason for this error is that another process in your system has tried to access the serial port while BLAST was us-ing it. Check to be sure that programs like cu, uucp, getty, or ttymon are not attempting to run simultaneously on the same port as BLAST. Make sure that these programs are set up to recognize lock files and share system resources smoothly. For more information on ttymon, refer to Chapter 2 of this manual. Occasionally, this error can occur if BLAST is unable to communicate with the tty from which BLAST is being run.

4. “Can someone log onto my system and exchange files with my system without my help?”

The user must have a legitimate ID and password on your system and the environment variables must be properly set to allow the user to execute BLAST. For more information on login, see Chapter 2. After logging in, the remote user should invoke BLAST in host mode, with the -h switch:

blast -h

When the message

;starting BLAST protocol

appears, the user should initiate BLAST Filetransfer mode on the re-mote system (see Chapter 6). This feature is available in BLAST protocol only. Several of the other supported protocols can operate in a much more limited pseudohost mode (see “BLAST Operation as a Pseudohost With 10.8x” on page 204).

5. “I can connect and log in normally, but when I enter BLAST Filetransfer mode, my files won’t transfer. Why is this happen-ing?”

You may have either a mismatched filetransfer channel or a flow control problem. Both sides of the connection must use the identical channel width. The 7-Bit Channel setup field must have the same setting on both sides of the connection. Flow control must be estab-lished correctly between each computer and its modem and between modems (see “Flow Control” on page 30).

352 APPENDIX C

6. “What’s a quick way to get started with scripting?”

Use BLAST’s Learn mode (page 176) to build a script as you go through the steps of a process interactively.

7. “After making a connection, the line goes dead. I can tell that the modems are still connected, but no data is being transmitted.”

Make sure that both sides of the connection are using the same com-munications parameters, such as parity, data/stop bits, and flow con-trol. If you cannot see anything that you type on your screen but your data is being transmitted correctly, change the Local Echo setting to YES.

8. “Is there a way to send my own initialization string to the mo-dem?”

You can communicate directly with the modem while in Terminal mode, or you can write your own script (see “Sample Modem Script” on page 214).

9. “What are typical modem settings required by BLAST?”

DTR NormalCD NormalVerbal Result CodesDisplay Result CodesModem Echoes CommandsEnable AT Command Set

TROUBLESHOOTING 353

354 APPENDIX C

D – decimal; H – hexadecimal; O – octal; M – mnemonic

Appendix D

The ASCII Character SetD H O M 0 00 00 nul 1 01 01 soh 2 02 02 stx 3 03 03 etx 4 04 04 eot 5 05 05 enq 6 06 06 ack 7 07 07 bel 8 08 10 bs 9 09 11 ht10 0A 12 lf11 0B 13 vt12 0C 14 ff13 0D 15 cr14 0E 16 so15 0F 17 si16 10 20 dle17 11 21 dc118 12 22 dc219 13 23 dc320 14 24 dc421 15 25 nak22 16 26 syn23 17 27 etb24 18 30 can25 19 31 em26 1A 32 sub27 1B 33 esc28 1C 34 fs29 1D 35 gs30 1E 36 rs31 1F 37 us

D H O M32 20 40 space

33 21 41 !34 22 42 ”35 23 43 #36 24 44 $37 25 45 %38 26 46 &39 27 47 ’40 28 50 (41 29 51 )42 2A 52 *43 2B 53 +44 2C 54 ,45 2D 55 -46 2E 56 .47 2F 57 /48 30 60 049 31 61 150 32 62 251 33 63 352 34 64 453 35 65 554 36 66 655 37 67 756 38 70 857 39 71 958 3A 72 :59 3B 73 ;60 3C 74 <61 3D 75 =62 3E 76 >63 3F 77 ?

D H O M64 40 100 @65 41 101 A66 42 102 B67 43 103 C68 44 104 D69 45 105 E70 46 106 F71 47 107 G72 48 110 H73 49 111 I74 4A 112 J75 4B 113 K76 4C 114 L77 4D 115 M78 4E 116 N79 4F 117 O80 50 120 P81 51 121 Q82 52 122 R83 53 123 S84 54 124 T85 55 125 U86 56 126 V87 57 127 W88 58 130 X89 59 131 Y90 5A 132 Z91 5B 133 [92 5C 134 \93 5D 135 ]94 5E 136 ^95 5F 137 -

D H O M96 60 140 ‘97 61 141 a98 62 142 b99 63 143 c100 64 144 d101 65 145 e102 66 146 f103 67 147 g104 68 150 h105 69 151 i106 6A 152 j107 6B 153 k108 6C 154 l109 6D 155 m110 6E 156 n111 6F 157 o112 70 160 p113 71 161 q114 72 162 r115 73 163 s116 74 164 t117 75 165 u118 76 166 v119 77 167 w120 78 170 x121 79 171 y122 7A 172 z123 7B 173 {124 7C 174 |125 7D 175 }126 7E 176 ~127 7F 177 del

THE ASCII CHARACTER SET 355

The chart below is a list of the standard ASCII control codes—with the decimal, hexa-decimal, and octal values; the ASCII mnemonic; the key sequence, and a short expla-nation.

D H O M Sequence Explanation0 00 00 nul <ctrl> @ used for padding1 01 01 soh <ctrl> A start of header2 02 02 stx <ctrl> B start of text3 03 03 etx <ctrl> C end of text4 04 04 eot <ctrl> D end of transmission5 05 05 enq <ctrl> E enquire6 06 06 ack <ctrl> F positive acknowledgement7 07 07 bel <ctrl> G audible alarm8 08 10 bs <ctrl> H backspace9 09 11 ht <ctrl> I horizontal tab10 0A 12 1f <ctrl> J line feed11 0B 13 vt <ctrl> K vertical tab12 0C 14 ff <ctrl> L form feed13 0D 15 cr <ctrl> M carriage return14 0E 16 so <ctrl> N shift out15 0F 17 si <ctrl> O shift in16 10 20 dle <ctrl> P data link escape17 11 21 dcl <ctrl> Q device control 1 (resume output)18 12 22 dc2 <ctrl> R device control 219 13 23 dc3 <ctrl> S device control 3 (pause output)20 14 24 dc4 <ctrl> T device control 421 15 25 nak <ctrl> U negative acknowledgement22 16 26 syn <ctrl> V synchronization character23 17 27 etb <ctrl> W end of text block24 18 30 can <ctrl> X cancel25 19 31 em <ctrl> Y end of medium26 1A 32 sub <ctrl> Z substitute27 1B 33 esc <ctrl> [ escape28 1C 34 fs <ctrl> \ frame separator29 1D 35 gs <ctrl> ] group separator30 1E 36 rs <ctrl> ^ record separator31 1F 37 us <ctrl> _ unit separator

D – decimal; H – hexadecimal; O – octal; M – mnemonic

356 APPENDIX D

Appendix E

Autopoll

The Autopoll Script

BLAST features Autopoll, a sample script that allows your unat-tended system to call a series of remote computers and exchange in-formation. Autopoll performs the following tasks:

◊ reads a list of sites to be polled,

◊ connects to each site,

◊ executes a transfer command file to transfer files,

◊ disconnects,

◊ scans the log file to determine which transfers were successful,

◊ builds retry files as required,

◊ and adds the results to a status file.

AUTOPOLL 357

Autopoll checks carefully for errors while polling. If an error is found, the problem site is scheduled to be retried. Only the file trans-fer commands that failed are attempted again.

Installing Autopoll

Autopoll consists of eight scripts that were copied into your BLAST directory when the BLAST program was installed on your system. The scripts are:

autopoll.scr – master script.autoinit.scr – initializes variables and files.autoierr.scr – reports initialization errors.autodisp.scr – draws screen displays.autoline.scr – reads site information.autopsnd.scr – checks log for status of SENDs.autoprcv.scr – checks log for status of GETs.autoparx.scr – updates status files.autosw.scr – strips file transfer switches off @filename. (10.8x only)

The scripts may be moved to any convenient directory in your sys-tem. For instance, you could segregate Autopoll from other BLAST files by creating a poll directory:

cd /usr/blastmkdir pollmv auto*scr poll

In addition to these script files, you must have a BLAST setup called “autopoll” located in the BLAST Setup Directory. It must include a valid communications port or hunt file and other connection infor-mation such as modem type and baud rate. You may also specify the script autopoll.scr in the Script File field of the setup, simplifying the command line to start Autopoll.

Starting Autopoll

Autopoll must be started from the directory in which the Autopoll scripts and support files (site and transfer command files) are found. If blast.exe is not in this directory, you need to add the full path for blast.exe to your PATH (see “Setting PATH, BLASTDIR, and SET-UPDIR” on page 8) or give the full path in the command line. If

358 APPENDIX E

autopoll.scr has been entered in the Script File field of the au-topoll setup, the format for invoking Autopoll from the command line is:

blast autopoll max_cycles site_file [start_time]

If autopoll.scr has not been entered in the Script File field of the setup, the command line must explicitly include the script:

blast autopoll -sautopoll.scr max_cycles site_file [start_time]

Other command line switches may be required under certain condi-tions. For example, if you intend to run Autopoll from cron, you must disable terminal output by including the -b or -n switch on the command line (see “Autopoll under cron” on page 368).

The command line parameters have the following meaning:

autopoll the autopoll setup.

-sautopoll.scr the autopoll script.

max_cycles the maximum number of attempts to complete all specified transfers.

site_file the filename “stub” (the part of the filename before the extension) of the site description file.

[start_time] [optional] the time, in 24-hour format, that Au-topoll will begin polling. The WAIT UNTIL command in BLASTscript requires the 24-hour format. If this parameter is omitted, Auto-poll begins polling immediately.

[TRACE] [optional] the command to enable a capture file of the entire polling session. The capture file contains the text of login dialogs, modem ini-tialization commands, and so forth. This fea-ture is used primarily for troubleshooting.

Here are some example command lines:

blast autopoll 3 retail 10:45blast autopoll 1 northwest -n &blast autopoll 2 daily 1:05 TRACE

AUTOPOLL 359

In the first example, a maximum of three attempts will be made to poll the sites listed in the site file retail.dat starting at 10:45 am. No-tice that the command line specifies just the stub “retail” of the sitefilename retail.dat. (Autopoll appends a variety of extensions to the filename stub to specify the names of special files.)

In the second example, one attempt will be made immediately to poll the sites in northwest.dat, BLAST will suppress its terminal output (-n), and UNIX will place the BLAST job in the background (&).

In the third example, a maximum of two attempts will be made to poll the sites listed in the site file daily.dat starting at 1:05 am, and a trace of the polling session will be made.

NOTE: Versions of BLAST before 10.7.5 do not support the @SETUPDIR reserved variable. If you are running an earlier BLAST version, you must include a reference to SETUPDIR on the command line:

blast autopoll -sautopoll ${SETUPDIR}/ max_cycles site_file [start_time]

The Site File

The site file is the “master list” of information about the sites to be polled. Site files may use any valid filename, but the extension must be .dat. Each line in the site file holds the parameters needed to con-nect to and transfer files to and from one site. Each line, or site record, consists of five fields separated by exclamation marks, also called “bangs,” in the form:

setup_name!site_name!phone_number!baud_rate!TCF_name

where

setup_name specifies a setup to be used for polling. If omitted, the field defaults to autopoll.

site_name contains a descriptive label for the site. If omitted, the field defaults to the Description field of setup_name.

phone_number specifies the phone number to be used for the site. If omitted, Autopoll uses the Phone Number field of setup_name.

360 APPENDIX E

baud_rate specifies the baud rate to be used for this site. If omitted, Autopoll uses the Baud Rate field of setup_name.

TCF_name specifies the transfer command file (TCF) to be used for this site. If omitted, this field de-faults to autopoll.tcf.

Each line must contain four bangs. Any fields that are to be skipped must be indicated by consecutive bangs (!!). Blank lines and lines beginning with a space, tab, or pound sign (#) will be skipped, so you may freely comment your site file using these characters. Lines may not exceed 100 characters in length. Some example record lines are as follows:

[the ruler is shown to indicate column position]

1 10 20 30 40 50|...|....|....|....|....|....|....|....|....|....|!Blaster!1(919)542-0939!!store06!!!!nightly.tcfNewYork!Albany!782-8311!19.2!ny.tcf

In the first site record, no setup is specified, so autopoll.su will be loaded. The site name will be “Blaster,” overriding the Description field of the setup. The phone number will be 1(919)542-0939. The baud rate will be taken from the setup because that field is blank, and the transfer command file will default to autopoll.tcf.

In the second record, the setup store06.su will be loaded. The site name, phone number, and baud rate will default to the values given in store06.su. The transfer command file will be nightly.tcf.

In the last record, the file NewYork.su will be loaded. The site name will be “Albany,” the phone number will be 782-8311, the baud rate will be set to 19.2 kbps, and the transfer command file will be ny.tcf.

Transfer Command File

Autopoll uses a standard transfer command file (TCF) to specify files to be sent and received. You may use a unique TCF for each site listed in your site file, or you may use one TCF for multiple sites. For a complete description of the Transfer Command File, see “Transfer Command File” on page 115.

AUTOPOLL 361

IMPORTANT: Autopoll treats wildcards and remote commands (such as remote print and remote rename) as “try once” specifications. These trans-fers and commands are attempted during the first cycle only. Even if errors occur, Autopoll does not attempt the transfers or commands again. For this reason, wildcards and remote commands should be used with caution.

Overview of Autopoll Script Actions

A brief overview of the basic actions of the autopoll scripts follows to give users a clearer understanding of the Autopoll process. Much of the error checking, which comprises most of the scripts, is not in-cluded.

1. Autopoll.scr starts, reads the command line parameters, and puts them into variables.

2. If an error is found, autopoll.scr calls autoierr.scr, which reports errors and terminates the Autopoll session.

3. If no errors are found, autopoll.scr calls autoinit.scr, which ini-tializes variables and files. Specifically, using the stub of the site file, autoinit.scr sets variables that allow Autopoll to create retry and summary files and to find stop and banner files (see “Other Files Using the Filename Stub” on page 366) to be used in the Autopoll session. Autoinit.scr then returns control to autopoll.scr.

4. Autopoll.scr calls autoline.scr, which reads and interprets the site file line by line for @SYSDESC, @PHONENO, @WORKTCF, and @LOGFILE and returns control to autopoll.scr.

5. Autopoll.scr calls autodisp.scr, which then displays on-screen status information during polling and then returns control to autopoll.scr.

6. Autopoll.scr uses variables gleaned from the site file by autoline.scr to begin file transfer of the first site. After it fin-ishes the first filetransfer session, autopoll.scr loops back to call autoline.scr to get information for the next filetransfer session until it finishes attempting the complete cycle of file transfers.

7. Autopoll.scr calls autoprcv.scr (which calls autosw.scr) and au-tosnd.scr to check the error-free log file for errors generated in the filetransfer sessions.

362 APPENDIX E

8. Autopoll.scr calls autoparx.scr (which calls autosw.scr) to up-date the screen and status file.

9. If more than one cycle is designated in the command line, autopoll.scr uses the updated status file to retry any files that failed in the first cycle.

10. Steps 7–9 are repeated until all files have been successfully

transferred or until the number of cycles designated in the com-mand line has been completed.

11. Autopoll.scr quits

NOTE: Autopoll.scr also calls any userscripts that may be created. See “User-Supplied Scripts” on page 370 for details on creating these scripts and on the points at which autopoll.scr calls these scripts.

Configuration Example

Assume that you have been asked to set up a polling network for a client who has a central UNIX system and two remote UNIX sites. How do you set up Autopoll for this configuration? First, you install BLAST on the central and remote sites and verify that connections can be made reliably. This step is best performed interactively, that is, while you are at the central system issuing commands directly to BLAST. When you are satisfied that BLAST is correctly installed, you need to create the following:

◊ setup files

◊ the site file

◊ transfer command files

The Setup FilesSuppose the sites are configured as follows:

Site name Phone Login, password

Sam’s Discount Mart 542-0307 buz, apollo11Metro Army Surplus 542-5694 neil, saturn5

Because the logins are different, different BLAST setup files are needed for each site. The setups, called “sam” and “metro,” are cre-

AUTOPOLL 363

ated by running BLAST at the central site (see “Creating a New Set-up” on page 64).

The Site FileUsing the setups, you could write a site file named retail.dat:

1 10 20 30 40 50|...|....|....|....|....|....|....|....|....|....| Retail Site List for My Polling Networksam!Sam's Discount!542-0307!!sams.tcfmetro!Metro Army Surplus!542-5694!!metro.tcf

The first line of the file is treated as a comment because it begins with a space. The last two lines are the actual site records. In this case, the site records may be duplicating information already speci-fied in the Phone Number and Description fields of the setups. If so, the site records could be simplified:

1 10 20 30 40 50|...|....|....|....|....|....|....|....|....|....| Retail Site List for My Polling Network (Phone number and Description loaded from setups)

sam!!!!sams.tcfmetro!!!!metro.tcf

The site file now has an additional comment line (five lines altogeth-er); otherwise it is equivalent to the previous site list.

Transfer Command FilesAccording to the site list, a transfer command file called sams.tcf will be executed when Autopoll connects to Sam’s Discount Mart, and the transfer command file metro.tcf will be executed when Autopoll connects to Metro Army Surplus.

Suppose you need to get two files from Sam and send one to him. The file sams.tcf might look like this:

1 10 20 30 40 50|...|....|....|....|....|....|....|....|....|....|+/usr/buz/acq12.txt /usr/client/sam1+/usr/buz/wk_82 /usr/client/sam2/usr/tmp/message /usr/tmp/read_me/OVW

364 APPENDIX E

As explained in “Transfer Command File” on page 115, the “+” sign in column 1 of a line signifies that BLAST will perform a GET. Thus, in the file sams.tcf above, BLAST will get /usr/buz/acq12.txt and give it the local filename usr/client/sam1. BLAST will also get /usr/buz/wk_82 and give it the local filename /usr/client/sam2. The absence of a “+” in the last line of the TCF signifies that BLAST will perform a SEND. Thus, BLAST will send usr/tmp/message and give it the filename /usr/tmp/read_me on the remote system. The added /OVW switch signifies that BLAST will overwrite an existing file of the same name on the remote system (see “File Transfer Switches” on page 111 for more information about filetransfer switches).

Metro.tcf is similar to sams.tcf:

1 10 20 30 40 50|...|....|....|....|....|....|....|....|....|....|+/usr/neil/acq12.txt /usr/client/metro1+/usr/neil/wk_82 /usr/client/metro2/usr/tmp/message /usr/tmp/read_me/OVW

Where to Save Autopoll FilesThe site file retail.dat and transfer command files sams.tcf and metro.tcf are created using a standard text editor and saved as text files only in the same directory as the Autopoll scripts.

IMPORTANT: Autopoll script files, transfer command files, and site files must be stored in the same directory, which must be your current working di-rectory.

.

Starting AutopollWith the required files ready, the BLAST command line to start Autopoll might be:

blast autopoll 3 retail

which specifies a maximum of three attempts to complete the poll-ing session with retail.dat.

AUTOPOLL 365

Other Files Using the Filename Stub

Autopoll distinguishes several special files by appending different extensions to the site filename stub. The extensions for retail.dat are listed below:

Extension Created by Meaning Example.dat user (required) Site file retail.dat.stp user (optional) Stop file retail.stp.hdr user (optional) Banner file retail.hdr.log Autopoll Short summary file retail.log.prn Autopoll Long summary file retail.prn

Site FileThe site file (retail.dat) is the master list of information about the sites to be polled.

Stop FileThe stop file (retail.stp) is an optional file the user can create that al-lows BLAST to exit prematurely but gracefully from a polling ses-sion. Autopoll checks for the existence of the stop file in the Autopoll directory before each connection to a site. If the file is found, the polling session is terminated.

For example, suppose you want to halt Autopoll because you have found out that the files to be transferred to the last 10 sites of a poll-ing session have been corrupted as a result of an error in database re-porting. Creating a stop file—a file with the stub of the site file and the extension “.stp”—will allow BLAST to quit the polling session gracefully instead of connecting to the last 10 sites.

Since the existence of the stop file—and not its contents—signify to BLAST that a session should be terminated, the contents of the file are irrelevant. A convenient way to create a stop file is with the UNIX touch command:

touch retail.stp

To ensure the completion of future transfers for the site file, Auto-poll deletes the stop file before exiting.

366 APPENDIX E

Banner FileThe banner file (retail.hdr) is an optional file created by the user. Au-topoll prints the banner file prior to printing the summary file at the end of polling. Printing is performed by the BLASTscript LPRINT command. You might want this file to contain special text or graph-ics to distinguish the summary file within a large queue of printouts.

Long and Short Summary FilesAutopoll maintains two summary files, a long summary file and a short summary file. Prepared by Autopoll but not printed, the long summary file (retail.prn) is helpful for troubleshooting. Printed au-tomatically at the end of polling, the short summary file (retail.log) is most helpful when polling goes well because a quick glance will confirm a successful polling session. The files are saved in the Au-topoll directory.

A typical short summary file looks like this:

********************* 02/09/96 11:15:29 *********************Cycle 11. FAILED:Sam's Discount < Error transferring 3 file(s). >2. success: Metro Army Surplus

Cycle 2 1. success: Sam's Discount****************************************************************Note: check retail.prn for complete session information.

A typical long summary file looks like this:

02/09/96 **************************************************************11:15:33 * Cycle: 1 Site: 1 * * Name: Sam's Discount * Phone: 542-0307 * TCF: sams.tcf * Log: C1S001.log * *———————— SESSION INFORMATION ———————— * Filetransfer error -8: DCD lost during transfer * Error transferring 3 file(s). Log file follows: * * **** BLAST Professional UNIX 10.7.3 on remote system [uov] * LOSS OF CARRIER, ending Filetransfer * File transfer interrupted, 12% of file acq12.txt received ************************************************************** 02/09/96 **************************************************************11:16:30 * Cycle: 1 Site: 2 * * Name: Metro Army Surplus * Phone: 542-5694

AUTOPOLL 367

* TCF: metro.tcf * Log: C1S002.log * *—————————— SESSION INFORMATION ————————— * No errors encountered. * Log file has been deleted. ************************************************************** 02/09/96 **************************************************************11:18:49 * Cycle: 2 Site: 1 * * Name: Sam's Discount * Phone: 542-0307 * TCF: C1S001.tcf * Log: C2S001.log * *—————————— SESSION INFORMATION ————————— * No errors encountered. * Log file has been deleted. ************************************************************** 02/09/96 **************************************************************11:20:41 * Polling complete: all sites polled successfully. **************************************************************

Autopoll under cron

cron is a UNIX scheduler. To run Autopoll under cron, you will need to create a crontab that launches BLAST. The crontab usually specifies a shell procedure that starts BLAST after setting some en-vironment variables like BLASTDIR and SETUPDIR.

A typical crontab could consist of a single entry:

10 2 * * * /usr/doug/gopoll

This line instructs cron to start the program /usr/doug/gopoll at 2:10 every day. The gopoll program may be a shell procedure, such as:

PATH=$PATH:/usr/blastBLASTDIR=/usr/blastSETUPDIR=/usr/dougBPRINTER=“lp -d laser %s”export PATH BLASTDIR SETUPDIR BPRINTERcd /usr/blast/pollblast autopoll 6 nightly -b

This shell procedure sets environment variables needed by BLAST and ensures that the correct directory has been entered before start-ing BLAST. Of course, on your system these environment variables probably have different values. The -b switch disables terminal out-

368 APPENDIX E

put. Consult the cron man page of your UNIX system for more in-formation about cron and crontab.

Tips and Tricks

Following are a few tips and tricks to help insure successful execu-tion of Autopoll:

Keep it Simple

Polling sessions can quickly become complicated if several file transfers must be performed over a large network of remote sites. Create simple but sensible directory structures to support the polling network. As a rule of thumb, command files should contain lines no longer than 80 characters so that they can be easily viewed and edit-ed on standard terminals.

Go Step by Step

Build your network methodically. It may be worthwhile to set up only a few remote sites initially and use them to test the features of Autopoll. Add sites to the network in groups of five or ten, eliminat-ing problems as you go, until the complete network is installed.

Problems Do Not “Just Go Away”

In a large polling network, it is not uncommon to have problems with a few remote sites; intermittent problems are especially frus-trating. Take some time to examine these difficulties carefully be-cause they can point to problems that actually affect the entire network. Following are some questions to ask in helping to identify a problem:

◊ Are the phone lines reliable?

◊ Could fax machines, answering machines, call waiting (or other phone company services) be interfering with modems making connections?

◊ Are the modems compatible with each other?

◊ Is BLAST or BHOST being initiated correctly on the remote?

◊ Are the expected files consistently present (on both sides)?

◊ Are directory and file permissions set appropriately?

AUTOPOLL 369

Tune BLAST Protocol Parameters

Some BLAST protocol parameters, such as the following, can be tuned for better performance with Autopoll:

Logon Timeout: 20

Inactivity Timeout: 20

DCD Loss Response: ABORT

These settings permit Autopoll to react more quickly to lost connec-tions than do the default settings. You may also wish to experiment with compression levels and packet size to find settings for best throughput. If your remote sites are running BHOST, bear in mind that the highest compression level supported by BHOST is 1 unless additional memory is allocated for compression buffers. Consult the BHOST User Manual for further information.

Use BPRINTER

The summary file is printed by the BLASTscript LPRINT com-mand, which is tied to the BPRINTER environment variable. You can alter the behavior of LPRINT by changing the definition of BPRINTER in the shell environment. For example, if you set up BPRINTER to perform a concatenation as shown below, Autopoll will append summaries to an archive instead of printing them:

BPRINTER="cat %s >> /usr/blast/summaries"export BPRINTER

BLAST substitutes the name of the short summary for the %s when the command is executed. For more information about BPRINTER, see “Additional Environment Variables” on page 9.

Modifying Autopoll

Because Autopoll is written in BLAST’s scripting language, it is easy to customize and is thoroughly commented.

User-Supplied ScriptsThe behavior of Autopoll can also be changed by writing one or more user-supplied scripts. Because Autopoll checks for the exist-ence of these scripts at various points during execution, the scripts should be named as shown below. If Autopoll finds a user-supplied script, the script is executed by the BLASTscript CALL command. Autopoll tests the value of @STATUS when the called script returns

370 APPENDIX E

command to Autopoll; polling continues normally if @STATUS equals 0; otherwise the site is marked as failed.

User-supplied scripts reside in the same directory as the Autopoll scripts. They are called at the following points during execution:

autousr0.scr before the first site is polled (polling is aborted if this script fails).

autousr1.scr before every attempt to CONNECT.

autousr2.scr before every attempt to start FILETRANSFER.

autousr3.scr before every attempt to DISCONNECT.

autousr4.scr before Autopoll terminates.

Because BLASTscript variables are global, a user-supplied script must not disturb the contents of any variables needed by Autopoll. The following variables may be changed freely by any user-supplied script:

@STATUS @EFERROR

@input @temp

@xferok @msg

@start @filename

You can also create new variables if you wish. To help prevent con-fusion, begin new variables with “u”, for example, @uvar2.

File I/O with User-Supplied ScriptsAutopoll opens files specified by file handles 1 through 7 at various points during execution. The handles have the following functions:

1 read-only current site (or retry) file.

2 utility I/O.

3 utility I/O.

4 utility I/O.

5 write-only complete polling results.

6 write-only retry file for next cycle.

7 write-only brief polling results (printed out).

Any of the handles reserved for utility I/O may be opened by user-supplied scripts as long as the handles are freed before the scripts re-

AUTOPOLL 371

turn to Autopoll (i.e., each user script must close its own files). User scripts may also write to the status files, handles 5 and 7. An exam-ple of this is shown in the next section.

Autopoll closes the standard BLAST log file before calling user-supplied scripts. If a user script opens a log of its own, the log must be closed before execution returns to Autopoll.

Sample User-Supplied ScriptThe following user-supplied script creates a transfer command file on a remote UNIX system that contains all of the files in a given tar-get directory. The file is retrieved for use by Autopoll in the normal way. This script provides a way to get an unspecified number of files from the remote system without sacrificing Autopoll’s ability to re-cover from filetransfer errors.

# autousr2.scr## Autopoll user-supplied script## This script assumes that Autopoll is logged into a UNIX-based system!## The script creates a command file on the remote UNIX machine# that contains all of files in the given directory. The# command file is then retrieved so that Autopoll can use it# in the normal way.## To create the command file, awk processes the# output from ls. Because we will be getting each file in# the listing, a '+' is inserted at the front of each# filename. The /FWD switch is appended to the filename# so the file will be deleted from the remote system if the# transfer is successful. On the local (Autopoll) side, /OVW is# appended to the filename so the file will overwrite an existing# file. Assuming the target directory is /u/out and the command# file is x.tcf, the necessary command is:## ls /u/out | awk '{printf("+/u/out/%s/FWD %s/OVW\n", $1, $1)}' > x.tcf## The script returns the following error codes:## 0 - no error# 1 - unable to detect remote shell prompt ($, %, or #)# 2 - target directory is empty# 3 - can't start BLAST on remote system# set @upath = "/u/out" # adjust path to suit! set @temp = "ls " strcat @temp, @upath strcat @temp, " | " # e.g, "ls /u/out | " strcat @temp, "awk ‘{printf(\"+" # attach awk command strcat @temp, @upath strcat @temp, "/%s/FWD %s/OVW\\n\", $1, $1)}' > " strcat @temp, @worktcf # @worktcf is Autopoll variable tsend cr # get the attention of the remote ttrap 2, "$", "#", "%" if @STATUS = "0" return 1 # return error wait 1 idle

372 APPENDIX E

tsend "ls ", @upath, " | wc -l", cr # how many files? ttrap 2, " 0" # no files in directory? if @STATUS = "1" fwrite 5, @b, " Remote directory ", @upath, " is empty." write "remote directory ", @upath, " is empty!" return 2 # dir is empty, nothing to do end write "preparing command file remotely" # inform user wait 1 idle tsend @temp, cr # run the awk script ttrap 2, "$", "#", "%" if @STATUS = "0" return 1 filetransfer # now retrieve the command file if @STATUS not = "0" return 3 # can't start BLAST on remote get @worktcf @worktcf to esc return @EFERROR # returns 0 if no error## End of script.

Configuration Worksheets

The following worksheets may help you organize the large amount of information needed to set up a polling network successfully.

A. List Machines

List the machines in your polling network. For completeness, in-clude information for the central site as well.

Site Name Phone Modem Type Port BLAST Version System Type

Central

1. 2.

3.

B. Decide on Setups

Decide whether or not different setup files will be needed for each site. If so, create the setups and list their names. Remember, Auto-poll loads the setup autopoll.su by default.

AUTOPOLL 373

Site Name Setup Name

1.

2.

3.

C. Set Up the Remote Sites

Set up the remote sites and test each connection manually. Make sure the following sequence of keyboard commands work flawless-ly:

Connect dials the modem and logs in if necessary.

Filetransfer enters BLAST filetransfer.

ESC exits BLAST filetransfer.

Disconnect logs off and hangs up the phone.

D. Create the Site File

Build the entries in the site file with any standard text editor, select-ing appropriate name(s) for the TCF files.

site filename: __________.dat

Setup Name Phone Baud TCF

E. Create the Transfer Command Files

List the files to be transferred to and from each site and the direction of transfer (S=SEND, G=GET). Afterward, write the various TCF files and put them in the autopoll directory.

Site S/G Remote Name Local Name Options

1.

2.

3.

F. Decide on Cycles

Decide how many cycles to allow for polling and when to start:

374 APPENDIX E

Cycles:

Start time:

G. Build the Command Line to Start Autopoll

Use the following format:

blast autopoll -sautopoll max_cycles site_file [start_time]

H. Check Environment Variables

Check the values of BLASTDIR, SETUPDIR, PATH, and BPRINTER. When they are correct, change to the autopoll directo-ry, type in the command line, and let Autopoll take over!

AUTOPOLL 375

376 APPENDIX E

Appendix F

PAD ParametersThe X.3 standard specifies a set of parameters defining how a PAD is to perform its task of assembling and disassembling the data stream. Each parameter is identified by a number and has several op-tional values. For example, Parameter 2 specifies whether or not the PAD is to echo input characters. A value of 0 specifies no echo, and a value of 1 specifies echo. This parameter can be set manually from the terminal in the form Parameter 2 = 0, or, in some cases, the pa-rameters can be downloaded automatically from the X.25 host sys-tem to the PAD.

In the following discussion of the parameters relevant to BLAST op-eration, the word “must” refers to critical settings while “should” re-fers to non-critical ones. “DTE” (Data Terminal Equipment) refers to the BLAST terminal or computer that is generating the data stream being processed by the PAD.

Parameter 1 Escape to Command Level

0 = Escape not possible1 = Escape possible (default)

This parameter allows an escape to command level. If escape is enabled, the occurrence in the terminal data stream of two carriage returns (CR) in the sequence “CR@CR” will cause

PAD PARAMETERS 377

the PAD to go into command mode; this sequence is similar to the AT “+++” sequence. Because BLAST encoding does not use the “@” character, the setting of this parameter is ir-relevant.

Parameter 2 Echo

0 = No echo1 = Echo (default)

This parameter specifies whether or not the PAD echoes input characters. This parameter must be set to 0 (no echo) for BLAST operation.

Parameter 3 Data Forwarding Character(s)

NOTE: Values may be combined with the or operator

0 = No data forwarding character1 = Alphanumerics2 = Carriage Return [CR] (default)4 = Escape [ESC]8 = Editing characters

16 = Terminators32 = Form effectors64 = Control characters

This parameter specifies the character(s) that will trigger the PAD to transmit all currently accumulated data as a packet. Because BLAST appends a CR to each packet, BLAST’s ef-ficiency over X.25 networks is greatly improved if “2” is the setting for Parameter 3.

Parameter 4 Idle Timer

0 = Timer disabledN = Multiples of .05 seconds (default = 80 [4 secs])

This parameter enables the PAD to transmit all currently ac-cumulated characters as a packet if the interval between suc-cessive characters received from the terminal exceeds the specified Idle Timer delay. This parameter does not normally affect BLAST operation unless the parameter is set to an ex-tremely small value. Such a setting could cause the PAD to send an incomplete BLAST packet if the BLAST computer pauses momentarily.

378 APPENDIX F

Parameter 5 XON/XOFF Flow Control of DTE by the PAD

0 = PAD may not exert flow control (default)1 = PAD may exert flow control

This parameter specifies whether or not the PAD can exert flow control. Under heavy network traffic conditions, a PAD may not always be able to keep pace with the incoming data stream, in which case it is preferable to exert flow control on the DTE. If the PAD is not allowed to exert flow control, it will occasionally drop incoming characters (see “XON/XOFF Pacing” on page 31). Because BLAST encoding does not use control characters, including the CTRL S and CTRL Q flow control characters, it is compatible with XON/XOFF flow control by the PAD.

Unfortunately, some PADs are not intelligent in their use of flow control, generating XON/XOFF sequences as often as every five characters. This frequent generation of XON/XOFF sequences significantly reduces BLAST throughput and in-creases the possibility that an XON or XOFF will be lost. BLAST can be set to unilaterally resume transmission after a fixed delay period (typically 30 seconds) in the event that an XON from the PAD is lost; however, it is not desirable to rely on this mechanism.

Because BLAST is an error-free protocol, it compensates for lost characters through retransmission of data blocks. If this is an occasional occurrence, it may be preferable to disable PAD to DTE flow control. On the other hand, if the PAD is very heavily loaded and/or the PAD uses XON/XOFF intelli-gently, it is better to enable flow control.

The XON/XOFF setting of the computer running BLAST should always match that of the PAD.

Parameter 6 Suppression of Service Signals

0 = Messages not sent1 = Messages sent (default)

Must be set to 0.

PAD PARAMETERS 379

Parameter 7 Break Options

0 = Do nothing (default)1 = Send interrupt packet to host2 = Send reset packet to host8 = Escape to PAD command state

21 = Flush

Should be set to 0.

Parameter 8 Discard Output

0 = Normal data delivery (default)1 = Discard all output to DTE

Must be set to 0.

Parameter 9 Carriage Return Padding

0 = No padding (default)1–31 = Character delay times

Should be set to 0.

Parameter 10 Line Folding

0 = No line folding (default)N = Characters per line before folding

This parameter specifies if and how often the PAD is to insert a carriage return and line feed automatically to break long text lines into shorter ones. It must be set to 0.

Parameter 11 Binary Speed

0 = 110 bps

↓18 = 64000 bps

This parameter is transparent to BLAST.

380 APPENDIX F

Parameter 12 XON/XOFF Flow Control of PAD by the DTE

0 = DTE may not exert flow control (default)1 = DTE may exert flow control

See discussion under Parameter 5.

Parameter 13 Linefeed (LF) Insertion

0 = No linefeed insertion (default)1 = Insert LF after CR on output to DTE2 = Insert LF after CR on input from DTE4 = Insert LF after CR on echo to DTE

Should be set to 0.

Parameter 14 Linefeed Padding

0 = No padding (default)1–15 = Number of null characters

Should be set to 0.

Parameter 15 Editing

0 = Editing disabled (default)1 = Editing enabled

This parameter enables local editing of text within the PAD before transmission through the network. If editing is en-abled, transmission of the timer is disabled. Must be set to 0.

Parameters 16–18 Editing Options

[Does not apply if Parameter 15 = 0, editing disabled.]

Parameter 19 Editing PAD Service Signals

[Does not apply if Parameter 6 = 0, service signals disabled.]

Parameter 20 Echo Mask

[Does not apply if Parameter 2 = 0, no echo.]

PAD PARAMETERS 381

Parameter 21 Parity

0 = No parity checking or generation (default)1 = Check parity only

12 = Parity generation only13 = Both parity checking and generation

Should be set to 0.

Parameter 22 Page Wait

0 = Page wait disabled (default) 1–255 = Wait after the specified number of lines are displayed

Must be set to 0.

382 APPENDIX F

IndexSymbols/APP

BLAST Protocol 111FTP 126Kermit Protocol 132Xmodem Protocol 140Zmodem Protocol 143

/COMP=n 111–112/FOLLOW=nn 112/FWD

BLAST Protocol 112Enabling/Disabling 88, 121, 271FTP 126Xmodem Protocol 140

/GROUP=nnBLAST protocol 112Kermit Protocol 132–133Xmodem Protocol 140

/OVWBLAST Protocol 112–113Enabling/Disabling 88, 272Xmodem Protocol 140Zmodem Protocol 143

/OWNER=nnBLAST Protocol 113Xmodem Protocol 140

/PERMS=nnnnBLAST Protocol 113Kermit Protocol 133Permissions Rules 152–153Xmodem Protocol 140–141

/STRBLAST Protocol 113Enabling/Disabling 88, 121, 271FTP 126Xmodem Protocol 141

/TXTBLAST Protocol 114FTP 126Xmodem Protocol 141Ymodem Protocol 142Zmodem Protocol 143

@STATUS 288

Commands Set by 223Saving Value of 183–184

AAccess Menu 327–329

Chat 327–328Parameters 328, 332–337Record 328–329Snapshot 328

Access Mode 326–329Filetransfer Mode from 331Hot Keys 329Modifying BHOST Settings 332–337See also Access Menu

ASCIICharacter Set 355Control Codes 356Script Command 224

Attention Key. See ATTN KeyATTN Key 42, 52–53

Aborting Scripts 172Sequences 346Setup Field 73–74

AutomationBLAST Protocol 119Scripting 61See also Autopoll

Autopoll 357–375Banner File 367Command Line 358–360Configuration 363–365, 373–375cron 368–369Installing 358Modifying 370–373Remote Commands 362Setup 358–359, 360–361, 363–364Site File 360–361, 364Starting 358–360, 365Stop File 366Summary Files 367–368Tips 369–370Transfer Command Files 361–362, 364–365User-Supplied Scripts 370–373Wildcards 362

INDEX 383

BBANNERTIME 9Batch Mode 12Baud Rate Setup Field 71BHOST 323–338

BLAST Setup 325Compression Level 325Login 325Modifying Settings 332–338Packet Size 98, 325Security Features 324Starting BLAST 104–105Transferring Files 331–332See also Remote Control and BHOST Set-tings

BHOST Settings 332–338DCD Loss Response 335–336Host Keyboard 336Host Mouse 336Host Printer 337Host Screen 336–337Inactivity T/O 334–335Printer(s) Enabled 337Scaling Ratio 333Scan Interval 333–334Special KBD Handling 334Sync Mode 334Timeout Response 335

Binary Data Manipulation 224Binary Variables, Defined 222BLAST

Application Integration 33–38Batch Mode 12Environment Variables 7–10File Types 7–8Host Mode 13–14, 323–338Quiet Mode 14Run from cron 36–38Run from Restricted Shell 153–154Screen 40–42Shell Programming 33–36Starting 39–40Unattended 36–38, 357–375

BLAST Keys 315–319Definition Charts 345–347Frequently Used 52Terminal Emulation 318–319

BLAST Protocol 99–122Advantages 100–101Automating 119Circuit Requirements 102Compression Level 120–121CRC Error Detection 101Design 101–102Ending File Transfer 106–107Extended Logging 14, 298File Transfer 107–122, 194–197File Transfer Switches 111–114File Transfer Templates 110–111Filetransfer Menu 57–58Fine-Tuning 119–121Getting Files 110, 194Message 58, 195, 233–234Packet Acknowledgement 86–87, 102,264Packet Size 17–18, 102, 119–120, 279Remote Commands 195, 234–235Remote Menu 108, 118–119Restarting Interrupted Transfer 115Scripting Considerations 196–197Security 121–122, 149–169Sending Files 109–110, 194Setup Subwindow 84–88Starting File Transfer 103–106Timeouts 105–106

See also main entry TimeoutsTransfer Command Files 115–118, 195Transfer Options 108–109Transfer Password 87–88, 121–122, 290Wildcards 110Window Size 85, 295XON/XOFF Pacing 32

BLAST Session Protocol. See BLAST Proto-colBLASTDIR 8–9, 9, 35, 153–154, 309Blaster (Online Demonstration and TestingService) 44–50

Connecting to 47–48File Transfer 48–50Logging Off 50Setup 45

blastkbd 315–321BLASTscript. See Script Commands andScripting

384 INDEX

blasttab 22–23Hunt Files and 26

blpassword 156–163Header Information 158–159Record Information 159–163

blsecure 163–167BPRINTER 9

CCALL Statement 184–185, 226CANCEL Key 42, 52, 53Capture 56, 147, 255–256Chat, Access Menu Option 327–328chmod 34Command Area 40–41Command Line Arguments 11–12, 193

Autopoll 358–360blsecure 163–167

Command Line Switches 10–15-? 14-2 12argument 11–12, 193, 358–360Autopoll 358–360-b 12, 359-c 12-dd 12-dt 12-e 13-f 13-h 13–14, 204–205, 352-k 14, 29-n 14, 191, 273, 285, 359-p 14-q 14-s 11, 172, 193setupname 11-v 14-x 14, 298Xmodem Protocol 138, 204–205-y 15Ymodem Protocol 138, 204–205-z 15Zmodem Protocol 138, 204–205

Communication with Other Programs 193Compression Level

BHOST 325

BLAST Protocol 120–121Reserved Variables 267, 281, 285Setup Fields 88

CONNECT Statement 175, 227Connecting 175, 211–214Connection Timeout 69–70CRC Error Detection 101cron 36–38crontab 36–38cut 36

DData Stream

Alteration 305–309Control 305–321Filtering 305–309Substitution 308Translate File 306–309Translation 308

date 36Date Format@DATE 268@DATEFORMAT 268–269@LOGDATEFORMAT 277-2 12-dd 12

DCD Loss Response 86, 196–197, 335–336Default

Setup 64Values for Reserved Variables 264

Demo Line. See BlasterDemonstration Service. See BlasterDisconnecting 211–212, 214–215DISPLAY Statement 192, 228Documentation 3–5Downloading Text 147, 209

EEcho

Local 82, 277, 353PAD Parameter 378Password Security and 280Script Command 229UNIX command 36Wait for 82, 295

Edit 59

INDEX 385

EDITOR 10, 59Emulation. See Terminal EmulationEmulator Maps 316, 319–320Environment Variables 7–10

BANNERTIME 9BLASTDIR 8–9, 9, 35, 153–154, 309BPRINTER 9EDITOR 10OLD_STTY 28PATH 8–9, 35, 153–154RETURN_CODE 34SETUPDIR 8–9, 10, 35, 153–154TERM 10, 46TIME_STAMP 36TMP 10

Error Checking 205–206Error Detection

CRC 97, 101, 302Modem 32Setup Field 94XON/XOFF Pacing 32

Error Messages 339–344BLAST Protocol Functions 339–340blsecure 167Command File Processing 342Initialization 342–343Memory 342Network 344Script Processor 343–344Scripting 341–342Transfer File Management 340–341Utility File Management 341

Extended Logging 298Command Line Switch 14Reserved Variable 298

FFile Transfer

BHOST 331–332BLAST Protocol 107–122, 194–197Blaster, with 48–50Error Checking 205–206FTP 124–128, 197Kermit Protocol 129–134, 197–200Xmodem Protocol 139–141, 200–201Ymodem Protocol 141–142, 201–202

Zmodem Protocol 142–143, 203–204File Transfer Status Area 41–42File Transfer Switches

BLAST Protocol 111–114FTP 126Kermit Protocol 132–133Security with 121Setup Fields for Enabling 88Xmodem Protocol 140–141Ymodem Protocol 142Zmodem Protocol 143–144See also Filename Restrictions and specif-ic file transfer switches

File Transfer TemplatesBLAST Protocol 110–111FTP 125

Filename RestrictionsBLAST Protocol 114–115FTP 127Kermit Protocol 133–134X, Y, and Zmodem Protocols 144

Filetransfer Menu 57–58BLAST Protocol 107–108FTP 124Kermit Protocol 129–130Xmodem Protocol 58Ymodem Protocol 58Zmodem Protocol 58

FILETRANSFER Statement 175–176,230–237

See also File TransferFiltering

Data Stream 305–309VT Sequences 86, 272

Flow Control 30–33Command Line Switch 13Downloading Text 147RTS/CTS Pacing 30–31Uploading Text 145XON/XOFF Pacing 31–33

FTP 123–128Ending a Session 128File Transfer 124–128, 197File Transfer Switches 126File Transfer Templates 125Filename Restrictions 127Filetransfer Menu 124

386 INDEX

Getting Files 125–126, 197Remote Commands 128, 235Remote Menu 124, 128Sending Files 124–125, 197Starting a Session 123Wildcards 125

Ggetty 19–21Global Variables, Defined 185

HHELP 43, 52, 54

Automatic Display 40Context-Sensitive 41, 43, 53

Host Mode 13–14See also BHOST and Pseudohost

Hot Keys 316, 319Access Mode 329Definition Chart 346–347PASSTHRU and 311

Hunt File 25–26, 69, 358

IIF Statement 175, 176, 241–244Inactivity Timeout

Reserved Variable 272Setup Field 85

Index Utility 216–217

KKermit Protocol 129–136

File Transfer 129–134, 197–200File Transfer Switches 132–133Filetransfer Menu 129–130Packet Size 90, 275, 276Receiving Files 131–132, 198–199Remote Commands 134–136, 235–237Remote Menu 130, 134–136Sending Files 131, 198Setup Subwindow 89–92Timeout 91, 275Versions 129Wildcards 131, 132

XON/XOFF Pacing 32Keyboard 52–53

ATTN Key 52–53BHOST Settings 334, 336BLAST Keys 52, 315–319, 345–347CANCEL Key 52, 53Definition Charts 345–350Emulation Keys 348–350Emulator Maps 316, 319–320Frequently Used Keys 42–43, 52Hot Keys 316, 319, 346–347International 14, 29–30Mapping 315–321Soft Keys 315, 317–318User-Defined Maps 316, 320–321

Keyboard FileCreation 320–321Reserved Variable 273Setup Field 72See also Keyboard

Keyboard Mapping. See KeyboardKeys. See Keyboard

LLearn Mode 55, 176–178Local Commands 58–60, 232–233Local Menu 58–60Lock Files 23, 351–352Log File

Error Checking 205–206Reserved Variables 270, 278Setup Field 73

LoginBHOST 325Password 69, 280System Scripts 211, 213UNIX Shell and 150Userid 68, 290, 325

Mmapchan 28Menus 51–61

Access 327–329Filetransfer 57–58, 107–108, 129–130Local 58–60Navigation through 43, 51

INDEX 387

Offline 54–55Online 55–57Remote 60–61, 118–119, 128, 134–136Summary of 43–44

Message 58, 108, 195, 233–234Modem

Error Detection 32RTS/CTS Pacing 30–31Scripts 211, 214–215Settings 353Setup Field 70–71XON/XOFF Pacing 31–33

NNumeric Constant, Defined 220Numeric String, Defined 220Numeric Value, Defined 220

OOffline Menu 54–55Online Demonstration and Testing Service.See BlasterOnline Menu 55–57

PPacket Acknowledgement 102

Request Frequency 86–87, 264Window Size 85, 295

Packet SizeBHOST 98, 325BLAST Protocol 17–18, 102, 119–120,279Kermit Protocol 90, 275, 276Line Quality and 286Setup Field 90, 98

PADS 17–18X.3 Standard Parameters 377–382

Parity7-Bit Operation and 102Blaster Setup Field 45PAD Parameter 382Reserved Variable 279Setup Field 71stty 27, 28Troubleshooting and 353

PASSTHRU 310–311Password

File, Secure BLAST 155–169Reserved Variable 280Security 155–169, 280Setup Field 69See also Transfer Password

PATH 8–9, 35, 153–154Permissions 150–153

blpassword 161blsecure 165See also /PERMS=nnnn

pmadm (Port Monitor Administration) 21Ports

Automatic Searching 25–26Communications 16–29, 30–33TCP/IP 16–17Telnet 16Troubleshooting Access to 351–352X.25 Communications 17–18See also Serial Ports

PrintingAuto Print Command 348, 349Autopoll Banner Files 367Autopoll Summary Files 367, 370BHOST Settings 337BPRINTER 9Error Message 342Hot Keys 347Local PRINT Command 232LPRINT Command 247–248Print Command 59, 61, 119, 350Print Mode Setup Field 77Print Screen Command 77, 348, 349Printer Logging 346Remote 61, 117, 118, 119, 234Terminal Emulation 293, 294, 313, 314–315, 348

ProtocolsDefinition 99Limiting Access to 154–155Reserved Variable 281Setup Field 84Setup Subwindows 84–97See also individual protocols: BLASTProtocol, FTP, Kermit Protocol, XmodemProtocol, Ymodem Protocol, and Zmodem

388 INDEX

ProtocolPseudohost 204–205

Limiting Access to 154

QQuiet Mode 14

RRecord, Access Menu Option 328–329Registration 1Remote Commands

Autopoll 362BLAST Protocol 118–119, 195, 234–235Enabling/Disabling 88, 271FTP 128, 235Kermit Protocol 134–136, 235–237

Remote Control 323–338Access Menu 327–329Access Mode 326–329Connecting to Host PC 324–326Disconnecting from Host PC 326File Transfer Only Mode 326, 329–330Terminal Mode 326, 330–331

Remote Line Termination 93Remote Menu 60–61

BLAST Protocol 108, 118–119FTP 124, 128Kermit Protocol 130, 134–136

Reserved Variables 263–303@7BITCHN 264@ACKFREQ 264@ANSIAUTOWRAP 264@ANSILEVEL 264@APROTO 264@ARGn 11–12, 265@ATTKEY 265@AUTOLFIN 265@AUTOLFOUT 265@BAUDRATE 266@BLASTDIR 266@CHARDLY 266@CLASS 266@COMMPORT 266–267@COMP_LVL 267@CONNTIMO 267@CONTIMO 267

@CTS 267@D/S_BITS 268@DATE 268@DATEFORMAT 268–269@DCD 269@DCDLOSS 269@EFERROR 176, 269–270@EFLOG 206, 270@EFLOGGING 271@ELAPTIME 271@EMULATE 271@ENABLEFS 271@ENABLERCMD 272@FILECNT 272@FILTER 272@FULLSCR 272@INACTIMO 272@KBCHECK 273@KDELAYOS 273@KEYBOARD 273@KEYFILE 273@KFILETYP 274@KFNAMCONV 274@KREOPKT 274@KRPADCH 274@KRPADDNG 274@KRPKTLEN 275@KRSOPKT 275@KRTIMEOUT 275@KSAVEINC 275@KSEOPKT 275@KSPADCH 276@KSPADDNG 276@KSPKTLEN 276@KSSOPKT 276@KWARNING 276@LAUNCHST 277@LINEDLY 277@LOCECHO 277@LOGDATEFORMAT 277@LOGFILE 205–206, 278@LOGTIMEFORMAT 278@LOGTIMO 278@MODEM 278@NUMDISC 278–279@ONERROR 174–175, 279@ORGANS 279

INDEX 389

@PAKTSZ 17–18, 279@PARITY 279@PASSWORD 280@PHONENO 280@PROMPTCH 280@PROTOCOL 281@RBTOT 281@RBYTES 281@RCLASS 281@RCOMP_LEV 281@RETRAN 281–282@RFAILURE 282@RLINEQ 282@RLQ 282@RNAME 282@ROPTIONS 282@RPACK 282@RPTOT 283@RRET 283@RRTOT 283@RSERIAL 283@RSITE 283@RSIZE 283@RSTART 283@RSTATUS 284@RSUCCESS 284@RTIME 284@RTSCTS 30, 284@SBTOT 284@SBYTES 285@SCOMP_LEV 285@SCRFILE 285@SCRIPTERR 285@SCRLREG 191, 285@SERIAL 286@SETUPDIR 286@SFAILURE 286@SITE 286@SLINEQ 286@SLQ 286@SNAME 286@SOPTIONS 286@SPACK 287@SPTOT 287@SRET 287@SRTOT 287@SSIZE 287

@SSTART 287@SSTATUS 287–288@SSUCCESS 288@STATUS 183–184, 223, 288@STIME 288@SYMBOLTYPE 289@SYSDESC 289@SYSTYPE 289@TIME 289@TIMEFORMAT 289@TRANSTAT 191, 289–290@TRAPCNT 290@TRPASSWD 290@TTIME 290@USERID 290@USERIF 191, 291@VERSION 291@VT8BIT 291@VTANSBACK 291@VTAUTOWRAP 291@VTCLRSCRN 292@VTCURSOR 292@VTCURSTYPE 292@VTDISP132 292@VTHSCROLL 292@VTHSCROLLN 293@VTINTL 293@VTKEYPAD 293@VTNEWLINE 293@VTPRINT 293@VTPRINTPAGE 294@VTRESET 294@VTTEXTCURS 294@VTUSERCHAR 294@VTUSERKEYS 294@WDWSIZ 295@WT4ECHO 295@WYANSBACK 295@WYAUTOPAGE 295@WYAUTOSCROLL 295@WYAUTOWRAP 296@WYBLOCKEND 296@WYCOMMODE 296@WYDISP80 296@WYDSPCURSOR 296@WYENTER 297@WYEXPNDMEM 297

390 INDEX

@WYPAGELEN 297@WYRETURN 297@WYSCROLLINC 297@WYSEWORD 298@WYWRITEPROT 298@XCRC 298@XLOG 298@XLTFILE 299@XONXOFF 31, 299@XPADC 299@XYCONVR 299@XYCONVS 299@XYEOT 300@XYRLTR 300@XYRLTS 300@ZMALT 301@ZMAUTODOWN 143, 203–204, 301@ZMBLKLN 301@ZMCONVR 301@ZMCONVS 301@ZMCRC 302@ZMCTLESCR 302@ZMCTLESCS 302@ZMEXIST 302@ZMFRMLEN 302@ZMMANAGR 303@ZMMANAGS 303@ZMRESUME 303@ZMWINDOW 303

RETURN_CODE 34RTS/CTS Pacing 30–31


SSCO UNIX OpenServer 5 Character StreamMapping 28Screen

Command Area 40–41Description of 40–42File Transfer Status Area 41–42Host PC 336–337Scrolling Region 41, 192

Script Commands 219–261ASCII 224ASK 225

BIN2HEX 225CALL 184–185, 226CHECKSUM 226–227CLEAR 227CLEOL 227CONNECT 175, 227CURSOR 228DISCONNECT 176, 228DISPLAY 173, 192, 228DROP 229ECHO 229ERRSTR 230FCLOSE 189–190, 230FILETRANSFER FILE 230–231FILETRANSFER GET/SEND 231FILETRANSFER LOCAL 232–233FILETRANSFER MESSAGE 233–234FILETRANSFER REMOTE 234–237FLUSH 237FOPENA 189, 237FOPENR 189–190, 238FOPENW 189–190, 238FREAD 189–190, 238–239FREADB 239FREE 239FREWIND 239–240FWRITE 189–190, 240FWRITEB 240GETENV 240–241GOTO 185, 241HEX2BIN 241IF 175, 241–243IF-ELSE 243IF-END 176, 243–244IF-END/ELSE-END 244LCHDIR 244–245LDELETE 245LET 245LLIST 246LOAD 246LOCAL SYSTEM 193, 247LOWER 247LPRINT 247–248LRENAME 248LTYPE 248MENU 248

INDEX 391

NEW 249PUT 249PWD 249–250QUIT 250RAISE 250REMOVE 250–251REPS 186, 251RETURN 251SAVE 251SELECT 252SET 252, 263SETTRAP 188–189, 252–253STRCAT 186–188, 253STRINX 187, 254STRLEN 187, 254STRRINX 187, 254STRTRIM 187, 255SYMTYPE 255TCAPTURE 188–189, 255–256TERMINAL 256That Set @STATUS 223TRAPNULLS_OFF 257TRAPNULLS_ON 257TSEND 177, 257TSENDBIN 258TTRAP 177, 258TUPLOAD 207–208, 258–259UPPER 259WAIT 260WAIT CARRIER 260WAIT IDLE 260–261WAIT UNTIL 261WERROR 192, 261WRITE 191–192, 261

Script FileReserved Variable 285Setup Field 72–73

Scripting 171–209Automation with 61, 357–375Blank Lines in 182–183, 194, 197, 223CALL Statement 184–185, 226Capturing Text 188–189Comments in 173, 222–223Communication with Other Programs 193CONNECT Statement 175, 227Data Types 219–222Downloading Text 209

Error Checking 178, 205–206FILETRANSFER Statement 175–176,230–237IF Statement 175, 176, 241–244Labels 173, 182Learn Mode 176–178Legal and Illegal Expressions 182–183Loop in 185–186Messages 195, 233–234Programming Style 181–182Reading Files 189–190Remote Commands 195, 234–237Sample 173–178Screen Display 191–192Syntax Rules 222–223Text Manipulation 186–190Text Transfers 207–209Transfer Command Files 115–118, 195Uploading Text 207–208Writing Files 189–190See also Script Commands, Scripting FileTransfers, and Scripts

Scripting File Transfers 194–206BLAST Protocol 194–197Error Checking 205–206FTP 197Kermit Protocol 197–200Pseudohost 204–205Xmodem Protocol 200–201Ymodem Protocol 201–202Zmodem Protocol 203–204See also Script Commands, Scripting, andScripts

ScriptsAborting 172Index Utility 216–217Invoking 171–172Modem 211, 214–215Slave 104, 121System 211, 212Writing 172–179See also Script Commands, Scripting, andScripting File Transfers

Scrolling Region 41Display Control 191, 285Displaying Text 192

secure 167–168

392 INDEX

Secure BLAST 155–169blpassword 156–163blsecure 163–167Password File 155–169secure 167–168See also Security

Security 149–169@PASSWORD and 280BLAST Protocol 121–122Login 150Permissions 150–153Protocols and 154–155Restricted Shell 153–154umask 151–152See also Secure BLAST

Serial PortsAccessing 18–21Automatic Searching 25–26Choosing 23–26Configuration 18–21Flow Control 30–33IGLS Cycle 19–20Links to 24–25Lock Files 23, 351–352Locking 21–23PADs and 17Parameters for Host Mode 26–28System V Release 3 19–20System V Release 4 20–21

Session Command Window 337–338setgetty 21–22Setup 63–98

Autopoll 358–359, 360–361, 363–364BHOST 325BLAST Protocol Subwindow 84–88Blaster 45Creating 64–65DEC VT Emulation Subwindow 74–78Default 64Directory 64Kermit Protocol Subwindow 89–92Loading 64Modifying 65–66PC ANSI Emulation Subwindow 78Protocol Subwindows 84–97Removing 66Subwindows 66, 74–81, 84–97

Terminal Emulation Subwindows 74–81Window, Described 65–66Wyse Emulation Subwindow 78–81Xmodem and Ymodem Protocol Subwin-dow 92–94Zmodem Protocol Subwindow 94–97See also Setup Fields

Setup Fields 66–987/8 Bit Controls 757-Bit Channel 8580/132 Columns 75ACK Request Frequency 86–87ANSI Level 78Answerback 80Answerback Msg 76ASCII Line Termination 95Attention Key 73–74Auto Page 79Auto Receive 97, 143Auto Scroll 79Auto Wrap 77, 78, 79AutoLF In 82AutoLF Out 82Baud Rate 71Block End 81Block-Check-Type 91Character Delay 83Clear Screen 76Columns 80Comm Mode 81Connection 69Connection T/O 69–70Conversion Override 94CRC 97Cursor Keys Mode 75Cursor Type 76Data/Stop Bits 72DCD Loss Response 86Delay 91Description 67Display Cursor 81Emulation 74, 312Enable /FWD and /STR 88Enable /OVW and Remote Cmds 88End-of-Packet Char 89Enter 81EOT Timeout 92

INDEX 393

Error Detection 94Esc All Control Chars 96Expanded Memory 80File Conversion 93, 97File Management 97File Must Already Exist 94Filename Conversion 91Filtering 86Full Screen 81Horiz Scroll Inc 80Horizontal Scroll 75Inactivity Timeout 85Incomplete File 92Intl Char Set 77Jump Scroll Inc 75Keyboard File 72, 320, 321Launch String 87Limit Block Length 96Limit Frame Length 96Line Delay 83Local Echo 82Log File 73Logon T/O 84Management Option 95Modem Type 70–71New Line 77Number of Disconnect Blocks 87Originate/Answer 70Packet Size 17–18, 90, 98Pad Character 90, 93Padding 90–91Page Length 79Parity 71Password 69Phone Number 67Print Mode 77Print Screen 77Prompt Char 83Protocol 84Receive Compression Level 88Reset Terminal 76Resume Interrupted File 94Retransmit Timer 86Return 81RTS/CTS Pacing 30, 72Script File 72–73Send Compression Level 88

Size of Tx Window 96Start-of-Packet Char 89System Type 67–68Text Cursor 76Timeout 91Transfer Password 87–88Transfer Type 91Translate File 73, 306, 309Use “A” Protocol 86User Def Keys 76User Pref Char Set 78Userid 68Wait for Echo 82Warning 92Window Size 85Write Protect 80Wyseword 80XON/XOFF Pacing 31, 72See also Setup

Setup Subwindow. See Setup and SetupFieldsSetup Window. See Setup and Setup FieldsSETUPDIR 8–9, 10, 35, 153–154Shell Programming 33–36Slave Script 104, 121Sliding-Window Design 101Snapshot, Access Menu Option 328Soft Keys 315, 317–318Starting BLAST 39–40String Constant, Defined 220–221String Values, Defined 222stty 27–28System Scripts 211, 212System V Release 3 Serial Port Configura-tion 19–20System V Release 4 Serial Port Configura-tion 20–21

TTCP/IP 16–18, 69, 266–267Technical Support 5–6Telnet 16, 69, 266–267TERM 10, 46Terminal Emulation 309–315

ADM3A 314–315, 349–350BLAST Keys 318–319

394 INDEX

D80 314–315, 349–350DEC VT 74–78, 312–313, 348–349Keyboard Mapping 316, 319–320PASSTHRU 310–311PC ANSI 78, 312, 349Printing 314–315Reserved Variable 271Setup Field 74Setup Subwindows 74–81TTY 310TV920 314–315, 349–350WYSE 78–81, 314–315, 349–350

Terminal Mode 56BHOST 326, 330–331Hot Keys 311Local Echo 82, 277Script Command 256

TerminalsStandard BLAST 309–311See also Terminal Emulation and TerminalMode

Testing Service. See BlasterText Transfers 145–147

Downloading Text 147, 209Scripting 207–209Uploading Text 145–146, 207–208

Text Translation 309Time Format@LOGTIMEFORMAT 278@TIME 289@TIMEFORMAT 289-dt 12

TIME_STAMP 36Timeout

BHOST Settings 334–335BLAST Protocol 105–106Connection 69–70, 267Inactivity 85, 272Kermit Protocol 91, 275Logon 84, 278Xmodem Protocol 92, 300Ymodem Protocol 92, 300

TMP 10Transfer Command Files 115–118, 195

Autopoll 361–362, 364–365Transfer Password 121–122

Reserved Variable 290

Setup Field 87–88Translate File 306–309


Troubleshooting 351–353ttymgr 21–22ttymon 20–21

Uumask 151–152Uploading Text 145–146, 207–208

Error Detection 145Flow Control 145Scripting 207–208Upload Command 56

User-Defined Maps 316, 320–321

VVariables

Defined 220See also Reserved Variables

vi 10, 59View Command 59

WWildcards 110

Autopoll 362BLAST Protocol 110FTP 125Kermit Protocol 131, 132Pseudohost Mode 205Ymodem Protocol 142Zmodem Protocol 143

XXmodem Protocol 139–141

Command Line Switches 138, 204–205Connection Restriction 139File Transfer 139–141, 200–201File Transfer Switches 140–141Filename Restrictions 144Filetransfer Menu 58Limitations 137Pseudohost 204–205

INDEX 395

Receiving Files 139–140, 200Sending Files 139, 200Setup Subwindow 92–94Timeout 92, 300XON/XOFF Pacing 31–32

XON/XOFF Pacing 31–33ATTN Key Sequence for 346End-to-End 32–33Individual Protocols and 31–32Local 32PAD Parameter 379, 381PASSTHRU and 311Problems with 31–32Reserved Variable 299Setup Field 72

YYmodem Protocol 141–142

Command Line Switches 138, 204–205File Transfer 141–142, 201–202File Transfer Switches 142Filename Restrictions 144Filetransfer Menu 58Limitations 137Pseudohost 204–205Receiving Files 142, 202Sending Files 141–142, 201–202Setup Subwindow 92–94Timeout 92, 300Wildcards 142XON/XOFF Pacing 31–32

ZZmodem Protocol 142–144

Auto Receive 97, 143, 203–204, 301Command Line Switches 138, 204–205File Transfer 142–144, 203–204File Transfer Switches 143–144Filename Restrictions 144Filetransfer Menu 58Limitations 137Pseudohost 204–205Receiving Files 143, 203–204Sending Files 142–143, 203Setup Subwindow 94–97Wildcards 143

XON/XOFF Pacing 32

396 INDEX

TO: BLAST Technical Support FAX #: 919-542-0161

FROM: Voice #:COMPANY: FAX #:

DATE:

IMPORTANT: Please provide us with the following information:

Your BLAST version # Serial #

Your operating system Version #

Where does the problem occur? (please circle)

Installation Filetransfer Terminal Emulation Scripting

Background Remote Control Other

Please describe the problem:

How Was It?

We would like to hear your feedback on the usefulness of this document. Your opin-ions can help us improve it in the future.

BLAST Professional UNIX User Manual 2MNUNIX October 1999

1. Please rate the following: Excellent Good Fair

Ease of finding information

Clarity

Completeness

Accuracy

Organization

Appearance

Examples

Illustrations

Overall satisfaction

2. Please check areas that could be improved:

Introduction More step-by-step proceduresOrganization Make it more conciseInclude more figures Make it less technicalInclude more examples More quick reference aidsAdd more detail Improve the index

3. Please elaborate on specific concerns and feel free to comment on any topics not raised previously:

Please FAX or mail these comments to us. Our contact information is listed on the title page of this manual. Thank you for your input.

Documents

Professional UNIX User Manual - Blast Internet Services