IBM 4690 Programming Guide

 

   

4690 Store System:

 



Programming Guide

 

SC30-3602-02

 

 

Note Before using this information and the product it supports, be sure to read the general information under “Notices” on pag page e vi vii. i.

|

Third Edition (July 1996) This edition applies to Version 1 Release 2 of the licensed licensed program IBM 4690 Operating System, program program number 5696-538, and to all subsequent releases releases and modifications until otherwise indicated indicated in new editions. Changes are made periodically to the information herein. Order publications through your your IBM representative or the IBM IBM branch office serving your your locality. Publications are not stocked stocked at the address given below. A form for readers’ comments comments is provided at the back of this public publication. ation. If the form has been removed, removed, address your comments comments to: IBM Corporation Information Development, Department CJMA PO Box 12195 RESEARCH TRIANGLE PARK, NC 27709 USA When you send information to IBM, you grant IBM a nonexclusive right to use or distribute whatever information you supply in any way it believes appropriate without incurring any obligation to you. ©  Copyright

International Business Machines Corporation 1994, 1996. All rights reserved. Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

 

 

Contents Notices   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Trademarks   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preface   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Who Should Read This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Use This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Termin Ter minal al Mode Models ls   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where to Find More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Store System Related Publications — Software . . . . . . . . . . . . . . . . . . . . . . . . . . . Store System Related Publications — Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . General Gene ral Publica Publication tions s  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . | Summary of Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . .

vii vii viii .  viii .  viii ix .  ix .  ix .  x xii .  xiii

Part 1: The IBM 4690 Operati Operating ng S System ystem Enviro Environment nment Chapter 1. The IBM 4690 Chapter 4690 System Sys tem Capabil Capabilitie ities s  . . . Concurrent Concur rent Operations Operations   . . Operat Ope rator or Interfa Interface ce   . . . .

Oper Operating ating System System Enviro Environment nment . . . . . . . . . . . . . . . . . . . . . . .  1-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Changing the Signon Screen Communications   . . . . . . Files   . . . . . . . . . . . . . Problem Determination Aids Utilities   . . . . . . . . . . . . Additio Add itional nal Pro Produc ducts ts   . . . . . Store Controller Backup . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapte Chap terr 2. Mana Managi ging ng Fi File les s  . . . . . . . . . . . . . . Selecting File Types . . . . . . . . . . . . . . . . . . . Naming Files and Subdirectories . . . . . . . . . . . . Rules for Naming Subdirectories and Files . . . . . . Using Logical Names . . . . . . . . . . . . . . . . . . Logical File Names on a LAN (MCF Network) System

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Accessing Distributed Files in Store Controller and Terminal Applications Using File Names in Store Controller Applications . . . . . . . . . . . . . Using File Names in Terminal Applications . . . . . . . . . . . . . . . . . Using Node Names to Access Files . . . . . . . . . . . . . . . . . . . . . Performing File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . Design Considerations for File Performance . . . . . . . . . . . . . . . . Chapter 3. Programmin Chapter Programming g | 2x2 2x20 0 Display Displays s  . . . . . . . Shoppe pperr Display Display   . . . . . | Sho | Vide Video o Display Display   . . . . . . . Cash Drawer Driver . . . Coin Dispenser Driver . . I/O Proces Processor sor   . . . . . . . |

Terminal Terminal I/O I/O Devices Devices

 1-2 1-2 . . . 1-3 . . . .  1-3 . . . 1-3 . . . 1-4 . . . .  1-4 2-1 .  2-2 .  2-7 .  2-8  2-11  2-13

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 2-14  2-17  2-17  2-18  2-18  2-28

 3-1 . . . . . . 3-6 3-10 . . . . . . . . . . 3-12 . . . . . .  3-27 . . . . . .  3-29 . . . . . 3-31

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Magnetic Stripe Reader Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3-48 Printer Driver Model 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3-60 Printer Driver Model 3 or 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3-67

© Copyright

IBM Corp. 1994, 1996

iii

 

 

|

Magnetic Ink Character Recognition Support for Printers Model 3 and 4 . . . . . . . . . . . . . . . Fiscal Printer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scale Sca le Driv Driver er   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Serial I/O Communications Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tone Tone Dr Driv iver er   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Totals Retention Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter Chapt er 4. Using Error Error Recovery Recovery Procedure Procedures s and Facilities Facilities Error Recovery Options . . . . . . Error Functions and Statements . Logging System Errors . . . . . . Audibl Aud ible e Alarm Alarm   . . . . . . . . . . . . Distribution Exception Log . . . . . Power Line Disturbance Recovery Storag Sto rage e Retentio Retention n  . . . . . . . . . Terminal Power ON/OFF . . . . . Disk and File Error Recovery . . . Error Recovery for I/O Devices . .

 3-79 .  3-82 3-87 .  3-89 3-96 .  3-98

.

. . . . . . . . . . . . . . . . . . . . .

 4-1

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 4-1  4-2 .  4-4 4-6 .  4-9 .  4-9 4-10  4-10  4-10  4-13

Chapter 5. User Applicati Chapter Application on Considerati Considerations ons with a LAN (MCF Net Network) work) . . . . . . . . . . . . . .  5-1 Using TCLOSE to Close Application Data Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5-1 Application Read Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5-1 Spool Files on a LAN (MCF Network) System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Effects of Activating the Alternate File Server on Despooling . . . . . . . . . . . . . . . . . . . . Record Rec ord Siz Sizes es   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Application Program Interface (OS/2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Application Program Interface (DOS) . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . .

 5-2  5-3 5-4 . . . . .  5-4 . . .  5-6

Part Pa rt 2: Util Utilit itie ies s Chapter 6. Using the Keyed Chapter Keyed File Util Utility ity . . . Accessing the Keyed File Utility . . . . . . . . . Using the Keyed File Utility from the Host . . . Using the Keyed File Utility in a Batch File . . . Keyed File Utility Working Files . . . . . . . . . .

 6-1 .  6-2 .  6-2 .  6-4  6-10

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Hashin Has hing gProcesses Algorit Algorithms hmsof  .Keyed 6-10 Internal Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  6-12

|

Chapter 7. Using the Chapter the Input S Sequenc equence e Table Bu Build ild Utilit Utility y Input Sequence Tables . . . . . . . . . . . . . . . . . . . . . . Using the Input State Table Utility . . . . . . . . . . . . . . . . Running the Input Sequence Table Utility . . . . . . . . . . . . Input Sequence Table Utility on a LAN (MCF Network) System Chapter 8. Using the LIB86 Chapter LIB86 Library Library Util Utility ity Using LIB86 Command-Line Options . . . . Creating a Library File . . . . . . . . . . . . . Appending an Existing Library . . . . . . . . Replacing Library Modules . . . . . . . . . . . . . . . . . . . Deleting Modules Select Sel ecting ingLibrary Modules Modules  . . . . . . . . . . . . . Displaying Library Information . . . . . . Accessing Files in Other Directories . . .

iv

4690 Store System: Programming Guide

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 7-1  7-1  7-1  7-2  7-2  8-1  8-2  8-3  8-3  8-4

 8-4 8-5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  8-5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  8-6

 

 

Chapter 9. Using Chapter Using the Linker Utilit Utility y and the POSTLINK POSTLINK Utilit Utility y Introduction to the Linker Utility . . . . . . . . . . . . . . . . . . . . LINK86 Command Syntax . . . . . . . . . . . . . . . . . . . . . . . Linking With Shared Runtime Libraries . . . . . . . . . . . . . . . LINK86 Command Options . . . . . . . . . . . . . . . . . . . . . . Use of Link Path Variables to Search Other Directories . . . . . How Various Search Priorities Relate . . . . . . . . . . . . . . . . Use of ERRORLEVEL Test . . . . . . . . . . . . . . . . . . . . . .

 9-1 .  9-2 .  9-3 .  9-4 .  9-4  9-11  9-12  9-12

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Overlays   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12 The POSTLINK Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9-15 Chapter Chapt er 10. Using Using the Print Print Spool Spooler er Utilit Utility y Obtaining Job Status after a TCLOSE . . . . Issuing a Command to the Print Spooler . . Using Special Commands . . . . . . . . . . . Error Return Codes for the Print Spooler . .

 10-1  10-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10-2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10-3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10-5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 11. Using Chapter Using the Disk Surfac Surface e Analys Analysis is Utility Utility Introduction to the Disk Surface Analysis Utility . . . . IPL Command Processor . . . . . . . . . . . . . . . . . Disk Surface Analysis Utility . . . . . . . . . . . . . . . Parameter Descriptions for ADXCSW0L . . . . . . . . Command Formats for ADXCSW0L . . Using the Disk Surface Analysis Utility to Using the Time Frame Indicators . . . . Case Examples of Disk Recovery . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 11-4  11-7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  11-8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  11-8

Recover Data

Chapter Chapt er 12. Using Using the Loop Status Status Applicat Application ion Utility Utility

. . . . . . . . . . . . . . . . . . . . . . . .

Chapter 13. Using Chapter Using the Staged Staged IPL U Utili tility ty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Capabilities   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Application Applica tion Interfa Interface ce   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading Terminal Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Messages   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ASM History File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . | | | | | | |

 11-1  11-1  11-1  11-3  11-4

Chapter Chapt er 14. Using Using the Multiple Multiple Fi File le Archiver Archiver Ut Utilit ility y . . . . . . . . . . . . . . . . . . . . . . Compressing, Combining, and Archiving Files . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping the Combine File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Splitting Files Out of a Combine File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Splitting a Given List of Files from a Combine File . . . . . . . . . . . . . . . . . . . . . . . . Log Log Fi File les s  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Re Retur turn n Co Code des s  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

 12-1  13-1 13-1 13-2 13-3  13-7 13-8  13-10

 14-1  14-2 . . . .  14-3 . . . .  14-4 . . . .  14-4 . . . 14-5 14-5 . . .

. . . .

. . . .

Part 3: App Applic licatio ations ns (De (Desig signin ning g and Usi Using) ng) Chapter 15. Designing Chapter Designing Applicat Applications ions with with IBM 4680 BASIC BASIC . . . . . . . . . . . . . . . . . . . . .  15-1 Types of Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  15-2 . . . . . . . . . . . . . . App Applica lication tion Size e  ties Application Applica tion Siz Priori Priorities  . . . . . . . . . . . Starting a Background Application . . . System Authorization Authorization   . . . . . . . . . .

 

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

15-3 15-5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  15-6 15-8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Contents 

v

 

 

Communicating between Applications . . Using Application Services . . . . . . . . Chaining Chaini ng Applica Applications tions   . . . . . . . . . . . RAM Disk Files . . . . . . . . . . . . . . .

 15-11  15-17 15-30 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  15-31 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 16. Designing Chapter Designing Applicat Applications ions with with Other Languages Languages . . . . . . . . . . . . . . . . . . . . .  16-1 4690 Operating System Interfaces for C and COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . .  16-2 Guidelines and Restrictions for Assembly Language Applications . . . . . . . . . . . . . . . . . . . .  16-48 Chapter 17. Using IBM DOS Applicati Chapter Applications ons . . . Starting Applications in the IBM DOS Environment IBM DOS Program Memory Allocation . . . . . . Allocating Memory Using ADDMEM . . . . . . . . Optional Emulator Reports . . . . . . . . . . . . . Selecting Reports Using EOPTIONS . . . . . . . IBM DOS BIOS Calls and Software Interrupts . . DOS Function Calls . . . . . . . . . . . . . . . . . Emulato Emu latorr Messag Messages es   . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 17-1  17-1  17-2  17-3  17-3  17-3  17-4  17-6 17-6

Appendixes Appen Appendix dix the A. IBM IBM 4690-Provided 4690 4690 Operating Operating System System Disk Disk Director Dir ectory y . . Protecting Subdirectories . . . . . . . . . Naming Conventions for 4690 Operating System Files . . . . . . Dictionary of 4690 Operating System Files . . . . . . . . . . . . . Append Appe ndix ix B. Erro Errorr Mess Messag ages es LIB86 Error Messages . . . . . POSTLINK Error Messages . . LINK86 Error Messages . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 A-1  A-1 . . . . . . . . . . . . . . . . . . . . .  A-2 . . . . . . . . . . . . . . . . . . . . .  A-3

B-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  B-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  B-4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  B-8  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Appendix C. Character Appendix Character Se Sets ts and Check Printi Printing ng Appli Applicatio cation n Example of a Normal Width Character Set . . . . . . . . . . . . . Example of a Double Width Character Set . . . . . . . . . . . . . Example Application for Printing Checks on the Model 2 Printer

 C-1 . . . . . . . . . . . . . . . . . . . . .  C-1 . . . . . . . . . . . . . . . . . . . . .  C-2 . . . . . . . . . . . . . . . . . . . . .  C-3

. . . . . . . . . . . . . . . . . . . . .

Glossary   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

vi

4690 Store System: Programming Guide

X-1 X-23

 

 

Notices References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available available in all countries countries in which IBM operates. operates. Any refer reference ence to an IBM produc product, t, program, program, or service in this publication is not intended to state or imply that only IBM’s product, program, or service may be used. Any functionally functionally equivalent equivalent product, product, program, program, or service service that does not infr infringe inge any of IBM’s intellectual intellec tual property property rights may be used used instead of the IBM prod product, uct, program, program, or servic service. e. Evalua Evaluation tion and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user’s responsibility. IBM may have patents patents or pending patent patent applica applications tions covering covering subject subject matter in this doc document. ument. The furnishing furnis hing of this document document does not give you any license license to these pat patents. ents. You can send lice license nse inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue THORN TH ORNWO WOOD, OD, NY NY 105 10594 94 USA. USA.

Trademarks T   rademarks The following terms are trademarks of the IBM Corporation in the United States or other countries or both: AS/400

C/2

COBOL/2

Display Manager NetView Personal System/2 System/370 XT

IBM Operating System/2 PS/2 Systems Application Architecture

Micro Channel OS/2 SAA AIX

Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others.

© Copyright

IBM Corp. 1994, 1996

vii

 

 

Preface This book describes how to program the IBM 4690 Operating System and the interfaces for application programs.

Who Should Read This Book This book is written for the programmer who uses system services or writes application programs to run on the 4690 Operating System.

How to Use This Book The book is organized into the following parts:

 Part 1—The IBM 4690 Operating System Environment  – Chapter 1 contains an overview of the t he 4690 Operating System environment and describes the system capabilities, terminal models, and problem determination aids.  – Chapter 2 describes how you can manage your files. fil es. It provides information on naming files and subdirectories, and performing file functions.  – Chapter 3 contains information on programming terminal input/output input /output (I/O) devices.  – Chapter 4 provides information error system recovery procedures and facilities. facil ities. This iinformation nformation includes error recovery options, on logging errors, and storage retention.  – Chapter 5 describes options you should consider when using an applicati application on with a local area network (LAN).    Par Partt 2—Utili 2—Utilities ties  – Chapter 6 describes the Keyed File Utility Ut ility (KFU) and provides instructions for using the util utility. ity.  – Chapter 7 describes the input i nput sequence tables and provides example worksheets for you to use when designing the input sequence tables.  – Chapter 8 describes the Library Li brary Utility (LIB86). The chapter contains information inf ormation on using command-line options, creating a library file, and displaying library information.  – Chapter 9 describes the Linker Li nker and Postlink utilities. ut ilities. This inf information ormation includes incl udes using link path variables, input file options, and command syntax.  – Chapter 10 describes the Print Spooler Uti Utility, lity, which allows all ows you to send files tto o one of eight queues for printing on one of eight printers.  – descriptions Chapter 11 provides information on the Disk Surface Analysis Utility, Ut ility, including parameter and time-frame indicators.  – Chapter 12 describes the Loop Status Application Appl ication Ut Utility, ility, including formats to use to invoke the utility.  – Chapter 13 describes the Staged St aged IPL Utility. The chapter contains the requirements, capabili capabilities, ties, and application interface for using the utility.  Part 3—Applications (Designing and Using)  – Chapter 15 contains information for designing applications with IIBM BM 4680 BASIC.  – Chapter 16 contains information for designing applications with ot other her programming languages.

viii

4690 Store System: Programming Guide

 

 

 Appendixes  – Appendix A describes the 4690 Operating System hierarchical directory structure. This appendix includes information on naming conventions for 4690 Operating System files.  – Appendix B provides error messages for the Library, Postli Postlink, nk, and Linker utili utilities. ties.  – Appendix C describes character sets and the check printing application.  – The glossary defines new, unique, and unfamiliar terms and abbreviations used in this thi s book.  – The index provides a quick reference to the t he contents of the book.

 Ter4683/4693-xx  Termin minal al Mod Models els terminals are called Mod1 The 4683/4693xx 1/4694 1/4694 Mod1 termi  terminals. nals. Although Although all are c called alled M Mod1 od1 terminals terminals,, | each terminal model supports some features that other models do not support. |

The 4683/4693-xx  4683/4693-xx 2 terminals terminals are called called Mod2 terminals. terminals. These te terminals rminals a attach ttach to a Mod1 te terminal rminal an and d | dep depend end up upon on that that Mod1 ter termina minall for contro controll and com commun munica ication tion with with the st store ore co contr ntrolle oller. r. Tab Table le 0-1 shows the different Mod1 and Mod2 terminals. | Table Tab le 0-1 0-1.. Mod1 Mod1 and and M Mod2 od2 Ter Termin minals als by M Mach achine ine Typ Type  e 

|

4683 Terminals

|

4693 Terminals

4694 Terminals

|

Mod1

Mod2

Mod1

Mod2

Mod1

Mod2

| |

4683-P11 4683-P21

4683-xx 2 4683-xx  4683-xx  4683xx 2

4693-7x 1 4693-7x  4693-5x  4693-5 x 1

4693-xx 2 4693-xx  4693-xx  4693xx 2

4694-144

Not supported

| | | |

4683-P41 4683-001 4683-A01 4683-421

4683-xx 2 4683-xx  4683-xx  4683xx 2 4683-xx  4683xx 2 4683-xx  4683xx 2

4693-4x  4693-4 x 1 4693-3x 1 4693-3x 

4693-xx  4693xx 2 Not supported

Note: A 4683-xx  4683-xx 2 terminal terminal cannot cannot attach attach to a 4693 Mod1 Mod1 terminal. terminal. A 4693-xx  4693-xx 2 terminal cannot attach to a 4683 Mod1 terminal. The controller/terminal (for example, a 4684 or 4693-5x  4693-5 x 1 controller/terminal) combines the function of the store controller controller and point-of-sal point-of-sale e terminal in a single product. product. The terminal terminal portion of a controller/termina controller/terminall is considered to be a Mod1 terminal.

Where to Find More Information A CD-ROM is available that contains the online books that are a part of the IBM Store Systems Library Collection, SK2T-0331.

Store System Related Publications — Software IBM 4690 Store System Library IBM 4690 Store System: Touch Screen Support for 4690 OS Programming Guide , Guide , SGC30-3780 IBM 4690 Store System: Planning, Installation, and Configuration Guide , GC30-3600 IBM 4690 Store System: User’s Guide , SC30-3597 IBM 4690 Store System: Communications Programming Reference , SC30-3582 IBM 4690 Store System: Messages Guide , SC30-3598 IBM 4680 Store System: Preparing Your Site , GA27-3692 IBM 4680 BASIC: Language Reference , SC30-3356 IBM 4680 Store System: Display Manager User’s Guide , SC30-3404 IBM 4690 Store System: 4690 Terminal Services for DOS User’s Guide , Guide , SC30-3688 The CAPITPGP.DOC file included with AISPO product number, 5764-091 Version 1.1 or later, the IBM C  Programming Interface for the 4690 Terminals .  

Notices 

ix

 

 

IBM 4680 and 4680-90 General Sales Application IBM 4680-90 General Sales Application: Planning and Installation Guide , GC30-3630 IBM 4680-90 General Sales Application: Guide to Operations , SC30-3632 IBM 4680-90 General Sales Application: Programming Guide , SC30-3631 IBM 4680 General Sales Application – Price Management Feature: User’s Guide , SC30-3461 IBM 4680 General Sales Application – Terminal Offline Feature: User’s Guide , SC30-3499 IBM 4680-90 General Sales Application: Full Screen – Guide to Operations , SC30-3664 IBM 4680-90 General Sales Application: Master Index, GX27-3958 Index, GX27-3958 IBM 4680 and 4680-90 Supermarket Application IBM 4680-90 Supermarket Application: Planning and Installation Guide , GC30-3633 IBM 4680-90 Supermarket Application: Guide to Operations , SC30-3635 IBM 4680-90 Supermarket Application: Programming Guide , SC30-3634 IBM 4680 Supermarket Application – Terminal Offline Feature: User’s Guide , SC30-3512 IBM 4680 Supermarket Application – Electronic Funds Transfer Feature: User’s Guide , Guide , SC30-3513 IBM 4680-4690 Supermarket Application – Electronic Funds Transfer Feature Enhancement: User’s Guide , Guide ,   SC30-3718 IBM 4680-90 Supermarket Application: Master Index, GX27-3957 Index, GX27-3957 IBM 4680 Chain Drug Sales Application IBM 4680 Chain Drug Sales Application: Planning and Installation Guide , GC30-3412 IBM 4680 Chain Drug Sales Application: Guide to Operations , SC30-3413 IBM 4680 Chain Drug Sales Application: Programming Guide , SC30-3414 IBM 4680 Store Management Application IBM 4680 Store Management Application: Planning and Installation Guide , GC30-3483 IBM 4680 Store Management Application: Guide to Operations , SC30-3484 IBM 4680 Store Management Application: Programming Guide , SC30-3487 IBM 4680 Store Management Application – Inventory Control Feature: User’s Guide , SC30-3485 IBM 4680 Store Management Application – Price Management Feature: User’s Guide , SC30-3486 IBM Systems Application Architecture IBM Systems Application Architecture: Common Programming Interface Communications Reference ,   SC26-4399 In-Store Processing In-Store Processing: Application Development Guide , SC30-3534 In-Store Processing: IBM AIX – Application Development Guide , SC30-3537 In-Store Processing: IBM OS/2 Extended Edition – Application Development Guide , SC30-3538 In-Store Processing: IBM OS/400 – Application Development Guide , SC30-3535 In-Store Processing: IBM 4680 OS – Application Development Guide , SC30-3536

Store System Related Publications — Hardware | | | | | |

IBM 4694 Point-of-Sale Terminals IBM 4694 Point-of-Sale Terminals: Installation and Operation Guide , SA27-4005 IBM Store Systems: Installation and Operation for Point-of-Sale Input/Output Devices , GA27-4028 IBM 4693, 4694, and 4695 Point-of-Sale Terminals: Hardware Service Manual , Manual , SY27-0337 IBM Store Systems: Hardware Service Manual for Point-of-Sale Input/Output Devices , SY27-0339 IBM Store Systems: Parts Catalog , S131-0097 IBM 4693 Point-of-Sale Terminals IBM 4693 Point-of-Sale Terminals: Installation and Operation Guide , SA27-3978 IBM Store Systems: Installation and Operation for Point-of-Sale Input/Output Devices , GA27-4028

x

4690 Store System: Programming Guide

 

 

IBM IBM IBM IBM IBM IBM IBM IBM

4693 Point-of-Sale Terminals: Setup Instructions , P/N 73G1012 4693 Point-of-Sale Terminals: Quick Reference Card , P/N 73G1022 4693, 4694, and 4695 Point-of-Sale Terminals: Maintenance and Test Summary , SX27-3919 4693, 4694, and 4695 Point-of-Sale Terminals: Hardware Service Manual , Manual , SY27-0337 Store Systems: Hardware Service Manual for Point-of-Sale Input/Output Devices , SY27-0339 Store Systems: Parts Catalog , S131-0097 4693 Point-of-Sale Terminals: Reference Diskette , SX27-3918 4693 Point-of-Sale Terminals: Diagnostic Diskette , SX27-3928

IBM 4693 Point-of-Sale Terminals: Support Diskette for Medialess Terminals , SX27-3929 IBM 4683/4684 Point-of-Sale Terminals IBM 4683 Point-of-Sale Terminal: Installation Guide , SA27-3783 IBM 4684 Point-of-Sale Terminal: Installation Guide , SA27-3837 IBM 4684 Point-of-Sale Terminal: Introduction and Planning Guide , SA27-3835 IBM 4684 Store Loop Adapter/A: Installation, Testing, Problem Determination, and Technical Reference , SD21-0045 IBM 4683/4684 Point-of-Sale Terminal: Operations Guide , SA27-3704 IBM 4680 Store System and IBM 4683/4684 Point-of-Sale Terminal:  Problem Determination Guide , SY27-0330 IBM 4684 Point-of-Sale Terminal: Maintenance Summary Card , SX27-3885 IBM 4680 Store System: Terminal Test Procedures Reference Summary , GX27-3779 IBM 4683/4684 Point-of-Sale Terminal: Maintenance Manual , SY27-0295 IBM Store Systems: Hardware Service Manual for Point-of-Sale Input/Output Devices , SY27-0339 IBM Store Systems: Hardware Technical Reference , SY27-0336 IBM Store Systems: Parts Catalog , S131-0097 Scanners IBM 1520 Hand-Held Scanner User’s Guide , GA27-3685 IBM 4686 Retail Point-of-Sale Scanner: Physical Planning, Installation, and Operation Guide , SA27-3854 IBM 4686 Retail Point-of-Sale Scanner: Maintenance Manual , SY27-0319 IBM 4687 Point-of-Sale Scanner Model 1: Physical Planning, Installation, and Operation Guide ,   SA27-3855 IBM 4687 Point-of-Sale Scanner Model 1: Maintenance Manual , SY27-0317 IBM 4687 Point-of-Sale Scanner Model 2: Physical Planning Guide , SA27-3882 IBM 4687 Point-of-Sale Scanner Model 2: Operator’s Guide , SA27-3884 IBM 4687 Point-of-Sale Scanner Model 2: Maintenance Manual , SY27-0324 IBM 4696 Point-of-Sale IBM 4696 Point-of-Sale IBM 4696 Point-of-Sale IBM 4697 Point-of-Sale IBM 4697 Point-of-Sale   SY27-3990

Scanner Scanner Scanner Scanner Scanner

Scale: Physical Planning, Installation, and Operation Guide , GA27-3965 Scale: Maintenance Manual , SY27-0333 Scale: Specification Sheet , G221-3361 Model 001: Maintenance Manual , SY27-0338 Model 001: Physical Planning, Installation, and Operations Guide ,

IBM Personal Computer and IBM Personal System/2 IBM Personal System/2 – Model 50 Quick Reference and Reference Diskette , Diskette , S68X-2247 IBM Personal System/2 – Model 60 Quick Reference and Reference Diskette , Diskette , S68X-2213 IBM Personal System/2 – Model 70 Quick Reference and Reference Diskette , Diskette , S68X-2308 IBM Personal System/2 – Model 80 Quick Reference and Reference Diskette , Diskette , S68X-2284 IBM Personal System/2 – Store Loop Adapter/A – Supplements for the Hardware Maintenance Library , Library , SK2T-0319

 

Notices 

xi

 

 

Cabling A Building Planning Guide for Communication Wiring , G320-8059 IBM Cabling System Planning and Installation Guide , GA27-3361 IBM Cabling System Catalog , G570-2040 Using the IBM Cabling System with Communication Products , GA27-3620 Networks IBM Local Area Network Support Program , IBM P/N 83X7873 IBM Token-Ring Network Introduction and Planning Guide , GA27-3677 IBM Personal System/2 Store Loop Adapter/A: Installation and Setup Instructions , SK2T-0318

 General Gener al Pub Public licati ations ons Advanced Data Communications for Stores – General Information , GH20-2188 Distributed Systems Executive – General Information , GH19-6394 Communications Manager X.25 Programming Guide , SC31-6167 IBM Disk Operating System 4.0 Command Reference , S628-0253 IBM Proprinters , SC31-3793 IBM 4680 Support for COBOL Version 2  (Softcopy   (Softcopy provided with the product) IBM 4680 Store System Regression Tester  (Softcopy   (Softcopy provided with the product) IBM 4680 X.25 Application Programming Interface , GG24-3952 NetView Distribution Distribution Manager: Manager: General General Informatio Information  n , GH19-6587 Systems Network Architecture: General Overview , GC30-3073 IBM Local Area Network Administrator’s Guide , GA27-6367 DSX Preparing and Tracking Transmission Plans , SH19-6399 IBM Dictionary of Computing  (New   (New York; McGraw-Hill, Inc., 1993) IBM Local Area Network Support Program , IBM P/N 83X7873 The Ethernet Management Guide – Keeping the Link, Second Edition  (McGraw-Hill,   (McGraw-Hill, Inc.,   ISBN 0-07-04632 0-07-046320-4) 0-4)

xii

4690 Store System: Programming Guide

 

 

|

Summary of Changes

|

The following information has been added or modified in this edition of the manual:

|

   4694

|

   Touch Screen Support

|

   Programming I/O Devices

|

   Full-Screen Enhanced I/O Processor

| |

   Fis Fiscal cal Printe Printers rs

   Multiple File Archiver Utility

 

Notices 

xiii

 

 

xiv

4690 Store System: Programming Guide

 

 

Partt 1: The IBM Par IBM 4690 4690 Opera Operating ting Syst System em Envir Environm onment ent

© Copyright

IBM Corp. 1994, 1996

 

 

4690 Store System: Programming Guide

 

 

Chapte Cha pterr 1. The IBM IBM 4690 4690 Operat Operating ing Syst System em Envir Environm onment ent System Capabil System Capabilitie ities s  . . . . Concurrent Concur rent Operations Operations   . . . Operat Ope rator or Interfa Interface ce   . . . . . Changing the Signon Screen Communications   . . . . . . Files   . . . . . . . . . . . . . Problem Determination Aids Utilities   . . . . . . . . . . . . Additio Add itional nal Pro Produc ducts ts   . . . . . Store Controller Backup . .

1-1 1-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1-2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1-3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 1-4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1-4

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

This chapter chapter is an overview overview of the IBM 4690 Operating Operating System envir environment onment.. It provide provides s the capabili capabilities ties of the system and refers you to other chapters for more detailed information.

Syste m Cap Capabi abilit lities ies  System The IBM 4690 Operating System is a multitasking and multiuser environment that runs in the store controller, contro ller, the point-of-sale point-of-sale terminals, terminals, and the contro controller/te ller/terminals rminals.. The operating operating system can handle store controller communications with point-of-sale terminals, other controllers, the controller/terminal, and the host processor processor.. The following following section sections s briefly describe describe the sys system’s tem’s capabilities capabilities..

Concur rentt Operat Operation ions s  Concurren The following functions of the 4690 Operating System allow concurrent operations: operating system system allows you to run your batch batch and intera interactive ctive programs programs at the same time. One  The operating program does not have to finish before another program can start.

 The operating operating system system allows several several operators operators to use the system at the same time. time. Your operators operators can be authorized authorized to run run one program program at a time or several several at a time. time. Operato Operators rs are au authorize thorized d through the system authorization file . See Chap Chapter ter 15 fo forr inf inform ormatio ation n on ho how w to author authorize ize user users s on the system.

 Multiple users on the system can run multiple interactive applications through the use of windows . An operator can switch from window to window, start or stop an application running on a window, or check the status status of an application application running running on a window. Windows Windows are possible possible through a windo window w contro con troll facilit facility. y. Refer Refer to the IBM 4690 Store System: User’s Guide  for   for an explanation on how windows are used on the system.

 You can communicate with a host site at the same time your in-store communications are taking place.

 You can attach attach multiple serial serial devices to your your store contr controller. oller. The Multiple Co Console nsole facility facility handles the management of these devices as additional system consoles.

© Copyright

IBM Corp. 1994, 1996

1-1

 

 

Operat Ope rator or Interf Interfac ace e For some system functions (for example, configuration) you communicate with the system through a menu-driven menu-d riven interface interface at the store controller controller console console.. For other functions functions (for exampl example, e, copying files files)) you enter commands commands directly directly into into the system. system. You can attach auxilia auxiliary ry con consoles soles tto o the s store tore controll controller. er. For information on how to use system functions and auxiliary consoles, refer to the IBM 4690 Store System:  User’s Guide .

Changing the Signon Screen You can change the signon screen displayed during signon by creating an alternate logo in the file C:\ADX_IPGM\ADXL C:\ADX_ IPGM\ADXLOGOD.DAT OGOD.DAT.. If this file exists during during system startup, startup, the firs firstt 10 rows of data on the signon screen are replaced with the first 10 lines of alternate logo data in this file. ADXLOGOD.DAT should ADXLOGOD.DAT should reside in the ADX_IPGM ADX_IPGM subdir subdirectory ectory.. This file can be appl applied ied using Appl Apply y Softwar Sof tware e Maintena Maintenance nce (A (ASM) SM).. See the the IBM 4690 4690 Store Store Syste System: m: User’s User’s Gui Guide  de  for   for information on the ASM utility program. program. When using using ASM, the Advanced Advanced Data Communications Communications Systems Systems (ADCS) (ADCS) Host Command Processor Proce ssor (HCP) six-char six-character acter name should should be ?LOGOD. You maintain the contents contents and distribu distribution tion attributes of this file. The alternate alternate logo can can be a maximum of 10 rows rows with 79 columns columns in each row. row. Each row should should be terminated termin ated with a carriage carriage return and and a line feed. The 4690 syst system em editor DR EDIX autom automatically atically terminates lines with these characters.

Communications  Communications The following list contains communications-related information:

 The communication interfaces that support Systems Network Architecture (SNA) protocols are logical unit (LU) 0 and and LU 6.2 as node types types 2.0 and 2. 2.1. 1. The line connectio connections ns supported supported on the no non-SNA n-SNA interface interfa ce are asynchronous asynchronous (ASYNC) (ASYNC) and Binary Synchronou Synchronous s Communicat Communication ion (BSC). The line connections supported on the SNA interface are BSC, Synchronous Data Link Control (SDLC), token ring, ring, Ethe Etherne rnet, t, local local link, link, and X.25. X.25. The IBM 4690 4690 Store Store System: Communi Communications cations Progr Programming  amming  Reference  explains   explains how to use host and peer communications.

 LU 6.2 allows user-written transaction programs (TPs) on the 4690 store controller to communicate

with Advanced program-to-program communications (APPC) applications on a host node (type 4 or 5) or on a peer node (type 2.1). 2.1). The TP accesses accesses the LU 6.2 communications communications fun functions ctions by cal calling ling APPC functions. functio ns. These functions functions are known known as calls (verbs) (verbs) from a set of library library routines tha thatt are linked to the TP. TP. CPI Communication Communication is the LU 6.2 commun communication ications s interface interface used by the 4690 Operati Operating ng Syst System em.. Th The e IBM 4690 Store Store System: System: Communications Communications Programming Programming Re Referenc ference  e  explains   explains LU 6.2 communications.

 Application-to-application communications are processed through in-memory files called pipes . For information informa tion on how pipes pipes work work with y your our ap applicati plications, ons, se see e Chapter Chapter 15 and Chapter 16.

 You can optionally link your store controllers together by the token ring or Ethernet and they can communicate with each oth communicate other er using the Multiple Multiple Control Controller ler Feature Feature (MCF). A store controller controller configured as the master store controller serves as the central point of control on this type of system.

 On a system using the MCF, files are updated and distributed as you specify to other store controllers on the network. network. For more more informati information, on, refer refer to the IBM 4690 Store System: User’s Guide .

1-2

4690 Store System: Programming Guide

 

 

Files This list briefly describes file security, file types, and file structures: operating system system provides protection protection for your your files by limiting limiting access to only authorize authorized d users. To  The operating control file access, control access, you assign each user user to one of three categories. categories. See “Prot “Protecting ecting Files” Files” on page 2-23 for a descr description iption of these categori categories es and their uses. uses. spec specify and manage way fi disk dis files s. are shar shared ed with other use users. rs. See “Sharing “Sharing Files” on  You pagecan 2-21 forify information informa tion on allowing athe llowing file le kaccess. acces

 You can create create and manage keyed keyed files and other files. files. A utility allows you you to change keye keyed d files into direct files or direct direct direct files files into keyed keyed file files. s. See “Keyed” “Keyed” on page 2-4 for informa information tion abo about ut keyed ffiles iles and how to change these these files into direct direct files, or dire direct ct files into keyed file files. s. “Crea “Creating ting Files” on page 2-19 exp explains lains how files files are cre created ated on the system. system.

 The system uses a hierarchical file structure similar to the IBM Personal Computer Disk Operating System (IBM DOS).

Problem Determination Aids The 4690 Operating System provides the following problem determination aids:

 The operating system provides several problem determination aids to help you analyze problems in

your programs programs or or on your sy system. stem. One of the aids allows allows you to collect collect data a about bout a problem, problem, then print, display, display, or file the data. You can also create create a diskette for documentin documenting g and analyzing analyzing a prob problem lem.. Re Refe ferr to the IBM 4690 Store System: Messages Guide  for   for information on collecting problem analysis data.

 A system error error log provides provides a record of system system errors tha thatt occurred. occurred. You can use this data to help identify identif y and resolv resolve e problems. problems. For iinformat nformation ion on the system system e error rror log, s see ee Ch Chapter apter 4.

Utilities  Utilities The 4690 Operating System provides the following utilities:

 A utility is available available to help you develop develop the input seque sequence nce table. The input sequ sequence ence table lets lets you edit operator operator iinput nput from from variou various s input devices devices.. Chapter 7 descr describes ibes the input sequence sequence ttable able util utility. ity.  The Apply Software Maintenance (ASM) Utility allows you to update system or user programs through a menu-dr menu-drive iven n interfa interface. ce. Refer Refer to the IBM 4690 Store System: User’s Guide  for   for information about this utility. The Staged IPL Utility Utility lets you apply maintenance maintenance using using ASM when one controller controller is up and able to to run TCC Networks Networks.. See Chapter Chapter 13 for information information o on n the Staged IPL Utility. Utility. Speciall write operations operations protect protect your data in the event event of a power line disturbance. disturbance. For information information on  Specia recovering recov ering from from power line disturbance disturbances, s, see Chapter 4.

 You can use the Distributed File utility to distribute files to other nodes on a multiple-controller system. Refer to the IBM 4690 Store System: User’s Guide  for   for a complete description of this utility. editing facility facility lets you you create create and edit edit files. Refer to the the IBM 4690 Store System: User’s Guide   A text editing for information on the text editing facility.

 

Chapter Chapt er 1. The IBM 4690 Operating Operating System System Environme Environment nt

1-3

 

 

Additi Add itiona onall Pro Produc ducts ts The following list contains information about other products related to the IBM 4690 Operating System:

 The IBM 4690 Operating System supports an optional high-level debugging aid called the IBM 4680  Application Debugger . It iis s avail available able by R RPQ PQ P851 P85154. 54.

 The IBM 4690 Operating System includes a Display Manager program that allows you to create, modify, manage manage information informaUser’s tion displayed displa yed oninformation the store controlle con troller r screen. Refer to the IBM 4680 Store  System:or Display Manager Guide    for  for about this program.

Store Controller Backup You specify the store controller backup  during   during configur configuration. ation. This backup backup aut automatica omatically lly back backs s up your primary primar y controller when activa activated. ted. The function provides provides continuous continuous control for your terminal operations operations.. When you configure and prepare a store controller for backup, it can assume control of the TCC Network when the store store controller controller for that TCC Network Network is not operational. operational. For information information on confi configuring guring an and d preparing store controller backup, refer to the IBM 4690 Store System: User’s Guide . The IBM 4690 Operating Operating System System also provid provides es data backup. backup. A multiple-contro multiple-controller ller syste system m provides provides Data   Data  Backup , the capability for file file redundancy. redundancy. This capability capability allows allows store controllers controllers to comm communicate unicate wit with h each other ically other acrossupdated theted local local area network networ k (LAN). With this feature feature specify specify when yourrefe file files are to be automatically automat upda and distributed. distr ibuted. For more information info rmation onyou data datacan backup with a LAN, refer rs to the IBM 4690 Store System: User’s Guide .

1-4

4690 Store System: Programming Guide

 

 

Chapter 2. Managing Files Selecting File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Random   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Direct   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Keyed   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sequential   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Naming Files and Subdirectories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rules for Naming Subdirectories and Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Logical Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining Logical File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Logical File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Application Logical File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining User Logical File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logical File Names on a LAN (MCF Network) System . . . . . . . . . . . . . . . . . . . . . . . . . . Logical Names Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Logical Names Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying the Logical Names Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Logical Names Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Distributed Files in Store Controller and Terminal Applications . . . . . . . . . . . . . . . Step Ste p1 1.. De Defin fine e the the File File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step Ste p 2. Cr Crea eate te the the File File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 3. 3. Access Access the File ffrom rom the the User Program Program . . . . . . . . . . . . . . . . . . . . . . . . . . Using File Names in Store Controller Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using File Names in Terminal Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Node Names to Access Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging Distribution Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creatin Cre ating g Files Files   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Space Spa ce Allocati Allocation on   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Access Rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting Dele ting File Files s  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access Acc essing ing Files Files   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ending Access to Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sharing Shar ing Files Files   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copyin Cop ying g Files Files   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Renami Ren aming ng Files Files   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Protec Pro tecting ting File Files s  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Protecting Protec ting Subdir Subdirectori ectories es   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling and Disabling File and Subdirectory Security . . . . . . . . . . . . . . . . . . . . . . . . Reading a File Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing a File Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ensuring Data Integrity across Power Line Disturbances . . . . . . . . . . . . . . . . . . . . . . . PLD Protection for Writing One Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PLD Protection for Writing Two Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Design Considerations for File Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Keyed Key ed Fi Files les   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 2-2 2-2 2-3 2-4 2-5 .  2-7 .  2-8  2-11  2-12  2-12  2-12  2-12  2-13  2-13  2-14  2-14  2-14  2-14  2-15  2-16  2-16  2-17  2-17  2-18  2-18  2-18 2-19 2-19  2-19 2-20 2-20  2-21 2-21 2-23 2-23 2-23 2-24  2-25  2-25  2-26  2-27  2-27  2-27  2-28 2-28 .

This chapter chapter shows you how to handle handle files. It gives you infor information mation abo about ut file types and desc describes ribes how to manage your files and subdirectories.

© Copyright

IBM Corp. 1994, 1996

2-1

 

 

Selecting File Types You can choose from four types of files when building the files for your store system: random, direct, keyed,, and sequential. keyed sequential. You create all files files using variations variations of the CREATE CREATE statement and accompany accompanying ing parameters.

 Random Random Random files files have fixed record record lengths. lengths. The system uses uses the last two bytes in each record record for the carriage carri age retur return n and line feed char characters acters (CR/LF). (CR/LF). The system pad pads s the data space between between the last field of the record and the CR/LF. Random files files offer random random access, which which allows direct direct access to any record record in a file. This ability ability makes random rando m and direct files an idea ideall type for files that can be reference referenced d by a relative reco record rd number number.. If you need a name or a specific number (such as a telephone number) to reference a record, use Keyed File Services. Servic es. You ensure ensure that the number of bytes bytes occupied by the field field delimiters delimiters and CR/LF do not exceed exceed the spec specifie ified d record record lengt length. h. Fig Figure ure 2-1 s show hows s a random random file file compose composed d of three three re recor cords. ds. The d data ata is in in ASCII characters.

FILE.1

RECORD 1

"FIELD ONE","FIELD TWO","FIELD THREE" CR/LF

RECORD 2

"FIELD 1","FIELD 2"," "

CR/LF

RECORD 3

111,222,3.3,444,5.5

CR/LF

Record lengths fixed

Figu Figure re 22-1. 1. Exa Examp mple le of a R Ran ando dom m F Filile  e 

IBM 4680 BASIC locates each record of a randomly accessed file by taking the record number, subtracting subtr acting 1, and then multiplying multiplying that that result by the record record length. The result result is a byte displaceme displacement nt value for the the record record measure measured d from from the beginning beginning of the file file.. Record Records s can span s sector ectors. s. You mu must st specify specif y the record to be accessed accessed in each READ READ#, #, PRINT#, or WRITE# WRITE# statement statement executed executed.. The following followi ng BASIC program program creates creates the random file diagrammed diagrammed in Figure Figure 2-1.

   

   

2-2

CREA CREATE TE "FIL "FILE. E.1" 1" RECL RECL 40 AS 2 A$ = "FIELD ONE" B$ = "FIELD TWO" C$ = "FIE "FIELLD THRE THREE" E" D$ = "Field 1" E$ = "Field 2" F$ = "" G% = 111 H% = 222 I = 3.3 J% = 444 K = 5.5 WRITE #2,1; A$, B$, C$ WRITE #2,2; D$, E$, F$ WRITE #2,3; G%, H%, I, J%, K CLOSE 2 CL END

4690 Store System: Programming Guide

 

 

The following program reads the first three fields from record 3 in FILE.1.

 

IF END END #20 #20 THEN HEN 200 200 OPEN OPEN "FIL "FILE. E.1" 1" RECL RECL 40 AS 20 READ #20,3; FIELD1%, FIELD2%, FIELD3 PRINT FIELD1%, FIELD2%, FIELD3 200 END 20

The preceding program results in the following output.

111

222

3.3

For applications written for the terminal, you must use the WRITE statement to send data to a random file.

 Direct Direct Direct files are like random files except that direct files contain no delimiting characters (quotes, commas, and CR/LF). CR/LF). Direct files contain no data data form formatting atting information. information. Becaus Because e of this, you you must must spe specify cify a speciall format string when specia when you want to access the data data in a direct file. See “Perf “Performing orming File Functions Functions”” on page 2-18 to lea learn rn more about about accessing accessing a dire direct ct file. The following following program program creates a direct direct file named DIRECT.DAT DIRECT.DAT that cons consists ists of one 15-by 15-byte te record record.. The variable D represents the format string used in the WRITE FORM# statement.

   

STRING INTEGER*A, IN 2 DB REAL C RE CREATE CRE ATE "DIR "DIRECT ECT.DA .DAT" T" DIREC DIRECTT RECL RECL 15 AS 3 LOCKED LOCKED A = "ABC" B = 32767 C = 27.35 D = "C3, I2, R" WRITE FORM D; #3,1; A,B,C

   

CCLLOSE 3 END

Figure 2-2 shows shows the direct file created created by by the precedi preceding ng program. program. The dat data a in the figure is in hexadecimal.

RECORD 1

414243FF7F42000000000000003527

ABC

32 7 67

27.35

Record length = 15 bytes

Fi Figu gure re 22-2. 2. Exam Exampl ple e o off a Dire Direct ct File  File 

 

Chapte Cha pterr 2. Managi Managing ng Files Files

2-3

 

 

Keyed Keyed files are composed of fixed-length records that are accessed by using a key, which can be any combination of characters that can be used in an IBM 4680 BASIC string. A keyed keyed file consists consists of bloc blocks ks that contai contain n keyed recor records. ds. A block is a 51 512-byte 2-byte sector sector.. Each bl block ock uses uses the first four bytes bytes for chain pointers pointers and the next next 508 bytes for records. records. A block can conta contain in multiple records, recor ds, but records records are not split across across blocks. Each record record contains contains its key and data, with the key always being first. A record record c can an be a maxim maximum um of 508 b bytes. ytes. The key key can be as many b bytes ytes of the record as you need. You should should use keyed files for files files accessed accessed by a name or a number. Exampl Examples es of such number numbers s are a Universal Univer sal Product Product Code (UPC), (UPC), a label, a telephone number, number, or a check auth authorizat orization ion number number.. These types of names and and numbers do not have have any contiguous contiguous nature an and d are random in their oc occurr currence. ence. You can use numbers that have a contiguous nature to access a random or direct file. You access keyed files by hashing the key to obtain a relative position within the file to locate the record. Keyed files files do not have indexes. indexes. The more uniq unique ue each key is with respect respect to all of the other keys used used in a keyed file, the better the hashing technique works. To access a keyed keyed file sequentially, sequentially, use the keyed keyed file as a direct file. You can obtain inf informatio ormation n about the keyed file from from the first block, which which is used only for cont control rol information. information. The format of this first first block is: Relative Byte Offset (in Decimal)

Number of Bytes (in Decimal)

Keyed File Information

42

4

Number of blocks in keyed file

46

2

Keyed record size

48

4

Randomizing divisor

54

2

Key length

56

4

Chaining threshold

You can create keyed files directly with an IBM 4680 BASIC program, or you can use the Keyed File Utility program program prov provided ided with the IBM 4690 Operating Operating Sys System. tem. The utility pro provides vides an effic efficient ient two-p two-pass ass method of conver of converting ting a direct direct file into into a keye keyed d file. See “Keyed “Keyed Files” Files” on page 2-28 fo forr an expl explanation anation of this utility. Like direct direct files, keyed files files use no delimiting delimiting characters. characters. You use a format string string to map the data to and fro from m the recor record. d. Figure Figure 2-3 s show hows s a keyed keyed file file record record with with a 19-by 19-byte te len length gth.. The data data in the the figure figure is is in hexadecimal.

RECORD 1

4B455931414243FF7F42000000000000003527

key1

ABC 32767

Record length = 19 bytes

Figu Figure re 22-3. 3. Exa Examp mple le of a Ke Keye yed d File  File 

2-4

4690 Store System: Programming Guide

27.35

 

 

The follow following ing progr program am create creates s the 19-byte 19-byte keye keyed d file sh shown own in the the Figu Figure re 2-3 on pa page ge 2-4 2-4.. The ke keyed yed file consists of one 19-byte record.

     

   

STRING A, D, KEY INTEG INT EGER ER B REAL C RE CREATE POSF CREATE POSFILE ILE "KEYFI "KEYFILE. LE.DAT DAT"" KEYED KEYED 4 , , , 200 200 \ R ECL 19 AS 4 LOCKED RE KEY = "key1" A = "ABC" B = 32767 C = 27.35 D = "C4, C3, I2, R" WRITE FORM D; #4; KEY,A,B,C CLOSE 4 CL END

In this program:

 The numeral 4 after the reserved word KEYED specifies a key length of 4 bytes.  The three commas after the numeral 4 indicate that no randomizing divisor or chaining threshold value is specified; therefore, the defaults are used. The numeral 200 after the three commas specifies a total of 200 records in the keyed file.  The variable D represents the format string used in the WRITE FORM# statement.

 Sequential Sequential Sequential files are composed of variable-length records accessed in a first-record-to-last-record sequence. sequen ce. A record in a sequential sequential file consi consists sts of one or more fields delimited delimited by commas commas between the fields. fiel ds. A CR/LF CR/LF follow follows s the last last field field.. A string string d data ata ffield ield iis s also also del delimit imited ed by quot quotatio ation n mar marks. ks. A num numeri eric c data field is converted to an ASCII representation. A record in a sequential sequential file can cont contain ain up to 64 KB long. Individual Individual recor record d lengths var vary y accord according ing to the size of the fields in the record. record. Each field occ occupies upies only the number number of bytes required required by the data in the field and the delimiters. delimiters. Data recor records ds are written one one after another another and can span disk se sectors. ctors. You can open sequential sequential files files for reading or wr writing iting but not for both. You can, howev however, er, use two OPEN statements stateme nts to access a sequential sequential file, one for reading reading and one for writing. writing. Each open processe processes s the file sequentially. sequen tially. When you you ope open n a sequential sequential file for reading, reading, you start at at the be beginnin ginning g of the file. When y you ou open a sequential sequential file for for writing, writing, you must specify specify the APPE APPEND ND option in the the OPEN statem statement. ent. The data that you write is appended to the end of the existing file. Although sequential files are normally accessed from beginning to end, IBM 4680 BASIC provides a way to re-establish a reference within a sequential file for reprocessing a sequential file from a saved reference. refere nce. You mi might ght fin find d this useful as a check checkpoint point when when process processing ing lar large ge sequentia sequentiall files. files. After re-establish re-es tablishing ing a sequential file reference, reference, the file access access is again a next-record next-record sequence. sequence. Note that you cannot re-establish a reference when writing to a sequential file. A special form of the WRITE command, WRITE MATRIX, enables you to write a record to a sequential file from a terminal terminal application. application. The WRITE MATRIX MATRIX command sup supports ports writing writing recor records ds longer tha than n 512 bytes.several It also supports suppor ts the simultan simultaneous eous writing of record records recordsinfrom more tthan han on one e The terminal. terminal. WRITE MATRIX uses seve ral file writes to place pla ce all the data in the the seq sequentia uential l file. first write writ e specifies some of the fields and filler filler data for the remainder remainder of the record. record. After the first first write, the recor record d contains the fields that fit into 512 bytes, and the remainder of the fields are empty (the record is filled with commas  

Chapte Cha pterr 2. Managi Managing ng Files Files

2-5

 

 

and a terminating terminating CR/LF). CR/LF). The other writes writes fill the remainder remainder of the fields in increments increments of 512 or fewer fewer bytes. The entire entire re record cord is locked until all all of the writes are finished. finished. The re record cord is is unloc unlocked ked if the connection conne ction between between the store controller controller and the the terminal is lost. The syste system m writes a WRITE MATRIX record recor d this way to keep an application application from rea reading ding the record record until it is complete complete.. It also allows an application applic ation to determine determine whether whether the record has been been completed completed or not. Record Records s placed in a sequen sequential tial file by WRITE MATRIX are not guaranteed to be in the sequence in which they occur. You should should use sequential sequential files for data that is collected collected in a serial manner. manner. Examples Examples are the sales data collected in the terminal that is associated with each sales transaction, a listing of events as they occur, and data to be saved in a file to be printed later. Figure 2-4 shows shows a sequential sequential file file compos composed ed of thre three e records. records. The data in the figure figure is in hexadec hexadecimal. imal.

FILE.2

RECORD 1

"FIELD ONE","FIELD TWO","FIELD THREE"CR/LF

RECORD 2

"FIELD 1","FIELD 2"," "CR/LF

RECORD 3

111,222,3.3,444,5.5CR/LF

Record lengths vary

Figu Figure re 22-4. 4. Exa Examp mple le of a Se Sequ quen entia tiall Fi File  le 

The third field field in RECORD 2 is a null null string. Commas and quotatio quotation n marks ser serve ve as delimi delimiters ters but may also appear appear in a field as long as they are imbedded imbedded within quotation quotation mark marks. s. The only exce exception ption is that a quotation quotati on mark followed followed by a comma must serve as a string string delimiter. delimiter. The followi following ng progra program m creates the sequential seque ntial file file diagrammed diagrammed in in Figure Figure 2-4.

CREATE CRE ATE "FILE. "FILE.2" 2" AS 2 A$ = "FIELD ZERO, ONE" B$ = "FIELD TWO" C$ = "FIELD THREE" D$ = "Field 1" E$ = "Field 2" F$ = "" G% = 111    

   

WRITE WRITE WRITE CLOSE CL END

IH% J% K #2; #2; #2; 2

== 222 3.3 = 444 = 5.5 A$, B$, C$ D$, E$, F$ G%, H%, I, J%, K

The three WRITE# statements correspond to the three records, and each variable corresponds to a field. When you access access sequenti sequential al files, eac each h field is read one one at a time from the fir first st to the last. The READ# statement considers a field complete when it encounters a comma or CR/LF for numeric fields, and a quotation mark followed by a comma or carriage return for string fields.

2-6

4690 Store System: Programming Guide

 

 

The following program reads the fields in FILE.2 sequentially and prints them on the display device, one field for each line.

     

IF END END #19 #19 THEN HEN 100 100 OPEN "FILE.2" AS 19 FOR I% = 1 TO 11 READ #19; FIELDS$ PRINT PRI NT FIEL FIELDS DS$$ NEXT I% NE 100 END 10

The data type should match the variable type on a field-by-field basis. The preceding program results in the following output:

         

FFIE IELD LD FIELD FIE LD FIELDD FIEL Field Fi Field Fi

     

111 222 3.3

 

444 5.5

ONE TWO THRE THREEE 1 2

Note: Applications written for the terminal can send data to a sequential file using the WRITE MATRIX statement only.

Naming Files and Subdirectories A complete name for a file contains the name of the file, the disk or diskette drive that contains the file, the subdirectory path for the file, and the node name if you have MCF and want to access a file on anotherr store anothe store controller. controller. Some of the inf informatio ormation n in the file name name is optional. optional. If it is not not pres present, ent, the system either either treats it as blanks or substitutes substitutes default values values.. Genera Generally, lly, you should spec specify ify values rathe ratherr than rely on defaults. The general format for a complete file name is: nodename::\drivename:\subdirectory\filename.extension  where: nodename 

The name used used to identify identify a store con controller troller on on the network. network. You can use th this is name to access acces s files on a differe different nt store controller controller on the the LAN. The nodename  must   must be followed by two colons (::). See “Using “Using Node Names Names to Access Files” on pa page ge 2-18 for more more information.

drivename 

The name name for for the disk or di diskette skette drive drive.. A is for the the firs firstt disk diskette ette dr drive. ive. B is for the the second secon d diskette diskette drive. drive. C is for th the e first first fixed disk d drive. rive. D is for th the e seco second nd fix fixed ed dis disk k driv drive. e. Th The e drivename  must   must be followed by one colon (:).

subdirectory 

The names names of tthe he subdirecto subdirectories ries in in the path path for this file. file. See App Appendix endix A for d determin etermining ing the use of these names. names. Subdirector Subdirectory y names can contain contain one to eight chara characters cters and are are delimited delimite d by backsl backslashes. ashes. You can specify multiple subdir subdirectory ectory names. If you do no nott specify specif y a subdirectory subdirectory name, the system system uses the root directory directory.. The IBM 4690 Oper Operating ating System generally uses the first level of the subdirectory and not the root.

 

Chapte Cha pterr 2. Managi Managing ng Files Files

2-7

 

 

filename 

The actual actual name of the file. The file nam name e can conta contain in one to eight ch charact aracters. ers.

extension 

The extension extension of the file name. name. You use the extension extension a as s an additio additional nal set of characters characters to uniquely uniquely define a file. file. The extension extension can contain contain one to three three character characters s and is separated by a period from the file name.

In an application program, you should use a logical name  to   to repres represent ent the complet complete e file name. The llogical ogical name is easier to use and allows the file to be placed on the desired drive without changing the application applic ation progra program. m. See “Us “Using ing Logical Logical Names” Names” on on page 2-11 fo forr infor information mation o on n logic logical al names. names.

Rules for Naming Subdirectories and Files The general rules for naming subdirectories and files are: 1. Do not start start a subdirecto subdirectory ry or file name with ADX. The pre prefix fix ADX is rreserv eserved ed for the IBM 4690 Operating System files. 2. Avoid using using a name for a file that matches a name of an IBM 4690 Opera Operating ting System command. command. 3. Characters Characters allowed in subdirectorie subdirectories, s, file names, and extensions are:    Upp Upperc ercase ase A–Z    0–9  Specia Speciall chara characters cters @ # ( ) { } Note: Do not use these special characters in the first, fourth, fifth, or eighth position of a file name because these conflict with Host Command Processor (HCP) and input sequence table build file names. 4. The following characters are not allowed in subdirectories, file names, and extensions: ? * : . $ & _ ; , [ ] ! + = < > " - / \ │ 5. In terminal applications, you can use a maximum of 24 characters in a statement for a file name, including includi ng its extensi extension. on. This maximu maximum m includes a mandatory mandatory node node name (for examp example, le, R::) of three characters prior to all file names. 6. In the store controller, you can use a maximum of 127 characters in a statement for a file name, including its extension. 7. File names with a .BSX extension are symbol files for programs with the same file name. 8. The file extension .$$$ represents a temporary file that the data distribution application (DDA) uses when distributing an entire file across the LAN (MCF Network). For example, when distributing the file ABC.DAT to a remote node, the application creates a new version versio n named ABC.$$$. ABC.$$$. The application application dele deletes tes the ABC.DAT cop copy y and renames th the e temporar temporary y file (ABC.$$$) to ABC.DAT. 9. The file extension extension .C0 is a temporary temporary input file to the Keyed File Utility. Utility. 10 10.. All All ADX ADXxxxxx  xxxxx  names  names are not files or subdirecto subdirectories. ries. Some ADX file names represe represent nt functions, functions, pipes, proces pro cesses ses,, or node names. names. For exampl example: e: ADXFILES ADXLN ADX LNDA DAP P ADXL AD XLND ND1L 1L ADXLX ADX LXCC CCN:: N:: ADXLXAA ADXL XAAN:: N::

Function ffo or a forced c cllose Pipe Pipe indic indicat atin ing g th that at a sto store re c con ontr trol oller ler is the the a acti cting ng m mas aste terr LA LAN N dis distr trib ibut ute ep per er up upda date te proc proces ess s LAN LAN no node de name name for stor store e co cont ntro rolle llerr CC LAN node node n name ame for act acting ing master master sto store re contro controlle llerr

11. All 4690 fi files les are found found in director directories. ies. Some file files s are pla placed ced in the root dir director ectory, y, but most most are loca located ted in subdirectories that are one level below the root directory.

2-8

4690 Store System: Programming Guide

 

 

12. 4690 Operat Operating ing System subdirectory subdirectory names have the following gene general ral form:

 

ADX_ yzzz

Where: y 

= Intended user of the subdirectory: I = IIB BM ap applicatio tions S =O Ope pera rati ting ng syst system em K = St Store ore Sys System tems s Re Regre gressio ssion n Te Teste sterr U = Us User er

zzz  = Contents of the subdirectory: PGM = Active programs and associated data DT1 DT 1 = Dat Data a fil files es DT4 DT 4 = Dat Data a fil files es MNT = Maintenance modules BUL = Backup Backup le level vel of maintenance maintenance modules modules 13. The following subdirectories do not follow the 4690 Operating System naming conventions: ADX_APGM User subdirectory that allows application data files to be system-mirrored files Subdirectory for .BSX symbol files that are not currently being used ADX_BSX ADX_IOSS 4690 Operating System print spooler data files and control blocks Use these rules for file names and extensions. Part of determining how to name a file is knowing the intended use of the file and the subdirectory containing contain ing the file. Genera Generally, lly, files files are either progr programs ams or data. Some da data ta files are really really a logical logical extension of programs such as files that contain messages, screen definitions, or personalization values. Other data files contain data that is referred to or modified as a result of the sales activity. Table 2-1 descr describes ibes the naming rules for the various various types of files and subdirectories subdirectories.. Ta Tabl ble e 22-1 1 ((Pa Page ge 1 o off 2) 2).. Nam Namin ing g File Files s on th the e IB IBM M 46 4690 90 Op Oper erat atin ing g Syst System  em  Subdirectory

File Name

Extension

ADX_IPGM ADX_IMNT

 Must be 8 characters.  First 3 characters must be the same as

Must be 3 characters and must be determined according to the file use table based on the last

ADX_IBUL

defined ADX. in configuration and cannot be  Last character must be D, F, L, O, S, V, or W. See See Ta Tabl ble e 22-2 2 on page page 22-10 10..  Any of the valid name characters, but do not use special characters in the 5th character position.

character charact er of the fil file e name (s (see ee Tabl Table e 2-2 on page 2-10).

ADX_IDT1

 

 Must be 8 characters.  First 3 characters must be the same as the files in ADX_IPGM.

 Other 5 characters can be any of the

 Should be DAT.  Exception might be files that are only referred to by the application and HCP using logical file name (LFN).

valid name characters. ADX_IDT4

 

 Must be 8 characters.  First 3 characters must be the same as the files in ADX_IPGM.

 Other 5 characters can be any of the valid name characters.

 

 Should be DAT.  Exception might be files that are only referred to by the application and HCP using LFN.

Chapte Cha pterr 2. Managi Managing ng Files Files

2-9

 

 

Ta Tabl ble e 22-1 1 ((Pa Page ge 2 o off 2). 2). N Nam amin ing g File Files s on th the e IB IBM M 4690 4690 Op Oper erat atin ing g Sy Syst stem  em  Subdirectory

File Name

Extension

ADX_SPGM ADX_SMNT ADX_SBUL ADX_SDT1

These subdirectories are for use only by the IBM 4690 Operating System and must not contain any application files.

ADX_UPGM

Must be 4 characters.

ADX_UMNT ADX_UBUL See note  below.   below. ADX_UDT1 See note  below.   below.

Must be 3 characters and must be determined according accord ing to the fi file le use tab table le (see Ta Table ble 2-2 on page 2-1 page 2-10). 0). The last last cha charac racter ter of th the e file file n name ame is not used to determine the extension for these subdirectories.

Must be 4 characters.

Must be 3 characters according to what type of translation should be done by HCP when exchanging this file with the host: ASC   = ASCII to EBCDIC BIN   = No translation XLT   = User translation

Note: To be exchanged with the host processor through HCP, names in the ADX_UPGM, ADX_UMNT, ADX_UBUL, ADX_UBU L, and ADX_UDT1 ADX_UDT1 subdirectorie subdirectories s must follow these guidelines guidelines.. If the files in these subdirectories are used only for local use, such as for program development, follow the general file naming rules. rules. When loca locall files need to be exchanged exchanged with the host, you can re rename name them according according to the renaming rules for these subdirectories. Ta Tabl ble e 22-2 2 (P (Pag age e 1 of of 2) 2).. Fi File le Us Use e Ta Tabl ble  e  File Name Character

  Extension

  Intended File Use

A

A86

Assembler source code

B

BAS

4690 source code

C

C

C source code

D

DAT

Product control files

E F

Reserved; do not use DAT

G H

Messages, input sequence tables, and similar files Reserved; do not use

H

I

C source code include files Reserved; do not use

J

J86

4690 source code include files

K

L86

Library files

L

286

4690-executable file

M

MAP

Linkage editor map file

MF

DAT

Data files (messages)

N

INP

Linkage editor input file

O

OBJ

Relocatable object file

P Q

LST LIS

Language translator listing file 4690 interlisting file

R

LIN

4690 line number file

2 10

4690 Store System: Programming Guide

 

 

Ta Tabl ble e 22-2 2 (Pag (Page e 2 o off 2) 2).. File File Use Use Tabl Table  e  File Name Character

  Extension

  Intended File Use

S

DAT

Display Manager screen files

T

SYM

Linkage editor symbol table file

U

BSX

Symbols file

V W

OVR SRL

4690-executable overlay file Shareable runtime libraries

X

XRF

Cross-reference file

Y

SYS

4690 non-relocatable file

Z

BAT

Batch files

For example, the LOAD ALL TERMINALS function uses these files: ADXCS20L.286 ADXCS3AS.DAT ADXCS3MF.DAT

The executable module or program The Display Manager screens for running the utility interactively The message file used by the utility

Using Logical Names A logical name  is   is a way to abbreviate abbreviate a file name. name. You can us use e logical names names to repr represent esent eith either er the entire file name name (LFN type) or the drive drive and subdirectory subdirectory path path of the file name (LDSN type). type). You can use LFN, which represen represents ts the logical file name name as the entire file name. You can use LDSN LDSN,, which repre represents sents the logical drive and subdirectory name, as the drive and subdirectory path part of the file name. Table 2-3 illu illustrates strates the use of of these ter terms: ms: Ta Tabl ble e 22-3. 3. LDSN LDSN an and d LFN LFN Te Term rms  s    Type

General Form for Using This Type

Example of a Name Using This Type

LDSN

LDSN:filename.extension 

ADX_IDT1:EALABCDE.DAT

LFN

LFN

C:\ADX_IDT1\EALPQRST

The operating system provides LDSN forms of logical names for all of the supported subdirectories. Table Tab le 2-4 llist ists s the LDSN LDSNs. s. Tabl Table e 22-4 4 (Pa (Page ge 1 of 2). 2). Syste Systemm-Pr Prov ovid ided ed LDSN LDSN Form Format  at  LDSN

for DRIVE: \SUBDIRECTORY\  

ADX_SPGM:

C:\ADX_SPGM\  

ADX_SMNT:

C:\ADX_SMNT\  

ADX_SBUL:

C:\ADX_SBUL\  

ADX_SDT1:

C:\ADX_SDT1\  

ADX_IPGM:

C:\ADX_IPGM\  

ADX_IMNT:

C:\ADX_IMNT\  

ADX_IBUL: ADX_IDT1:

C:\ADX_IBUL\   C:\ADX_IDT1\  

ADX_IDT4:

C:\ADX_IDT4\  

 

2 11

Chapte Cha pterr 2. Managi Managing ng Files Files

 

 

Ta Tabl ble e 22-4 4 (Pa (Page ge 2 of 2). 2). Syste Systemm-Pro Provi vide ded d LDSN LDSN Fo Form rmat  at  LDSN

for DRIVE: \SUBDIRECTORY\  

ADX_UPGM:

C:\ADX_UPGM\  

ADX_UMNT:

C:\ADX_UMNT\  

ADX_UBUL:

C:\ADX_UBUL\  

ADX_UDT1:

C:\ADX_UDT1\  

Defining Logical File Names You can create, create, display, or modify logical logical file names during the configu configuration ration pro process. cess. Configu Configuration ration screens allow you to define three types of logical file names:    Sy Syste stem m fi files les    Applica Application tion file files s    Us User er fil files es Note: You must not use the same name for any type of communications line or SNA link that you use for any system, application, or user logical file name.

System Sys tem L Logi ogical cal F File ile N Name ames: s: Sy Syst stem em logi logica call file file name names s are are rese reserv rved ed name names s used used for for oper operat atin ing g system files and subdirectori subdirectories. es. The ADXDAxy  ADXDAxy F.DAT F.DAT file (where xy  is   is the store controller ID) in the ADX_SPGM subdirectory contains the system logical file names. Using the configuration screens, you can change the disk drive name defined in the LFN forms of these system files. files. You cannot cannot change th the e LDSN forms of th the e system log logical ical names names and you cannot cannot add new system logical names. IBM lilice cens nsed ed prog progra ram m or anot anothe herr prog progra ram m defi define nes s Applic App licati ation on Logi Logical cal Fi File le Nam Names: es: An IBM applicatio applic ation n logic logical al file names. names. The ADXDC ADXDCxy  xy F.DAT F.DAT file (where xy  is   is the store controller ID) in the ADX_SPGM subdirectory contains the application logical file name. Use the configuration screens to change the disk drive name specified in the LFN form of the application logicall names. You cannot logica cannot change the LDSN form forms s of the applicatio application n logical name names s and you cannot add new application logical names.

Defining Defini ng U User ser Logica Logicall F File ile Names: Yo You u can can comp comple lete tely ly defi define ne user user logi logica call fi file le name names s thro throug ugh h configuration.. You can define these configuration these file names as any allowed allowed logica logicall names that are not reserved reserved by the operating opera ting system system or an IBM licensed program. program. You can define either either LFN or LDSN types of use userr logical na name mes. s. The The ADX ADXDE DExy  xy F.DAT F.DAT file (where xy   is is the store controller ID) in the ADX_SPGM subdirectory contains the user logical file names. You can define logical names whenever you choose, but the changes do not become effective until you activate activa te them. To activate activate logical logical names, use th the e Supplemental Supplemental Disk Diskettes. ettes. | | | |

To have more displayable characters available on your store controller applications, define the logical name disp4680  name  disp4680  to   to any value. Setting a value causes 4690 OS to use the 4680 Controller Video Display Charac Cha racter ter set. set. Refer Refer to the the IBM 4680 Basic Language Reference  for   for a description of the 4680 and 4690 Controller Video Display Character Sets.

2 12

4690 Store System: Programming Guide

 

 

Logical File Names on a LAN (MCF Network) System Logical file names make accessing files on other store controllers on the LAN (MCF Network) easier by letting you abbreviate abbreviate lengthy lengthy file names. names. The system system expands you yourr abbreviated abbreviated file name to the full file name when accessing the file. For example, example, MYITEMS is a logical name name used by your sales sales applicat application ion for an item recor record d file. The system expands this name to its full file name, ADXLXAAN::C:\ADX_IDT1\MYITEMS.DAT, when another node nod e refe referen rences ces MYITEMS MYITEMS.. (Refer (Refer to the IBM 4690 Store System: User’s Guide  for   for a discussion of nodes and node IDs.) IDs.) In this example, example, the expanded expanded nam name e gets the version version of the MYI MYITEMS.DAT TEMS.DAT fi file le that is on the master store controller (ADXLXAAN::), on the C drive (C:), in the ADX_IDT1 subdirectory (\ADX_IDT1\). You can use a logical logical name to refer refer to a unique unique node, a unique unique subd subdirector irectory, y, or to a file. For examp example, le, ADX_IPGM: is a logical name ADX_IPGM: name for the subdirecto subdirectory ry C:\ADX_IPGM\. C:\ADX_IPGM\. Likewise, Likewise, the logical logical name ADX_IPGM:MYMOD.286 refers to a module whose full file name is C:\ADX_IPGM\MYMOD.286. More than one one logical logical name can ref refer er to the same file. file. For exam example, ple, if you defi define ne both ABC and DEF DEF as logical names for C:\ADX_UPGM\YOURMOD.286, any reference to ABC or DEF translates to the same file name. You could then define ABCD to be the logical name for the file ADXLXCCN::C:\ADX_UPGM\YOURMOD.286, and ABCDE to be the logical name for the file ADXLXAAN::C:\ADX ADXLXAA N::C:\ADX_UPGM\YO _UPGM\YOURMOD.28 URMOD.286. 6. A reference reference to ABC or DEF would look for YOURMOD.286 YOURMOD.286 only on the local controller controller.. A referen reference ce to ABCD would look for the file only only on the store controller controller node with the ID of CC. A reference reference to ABCDE wo would uld look for th the e file on the acting acting master store store con controller troller (ADXLXAAN::) (ADXLX AAN::) wher wherever ever it is and whatever whatever its ID is. If there was no acting acting master at that time, the system system returns a file error message. Every distributed file must have a logical name defined in the application logical names file or the user logical names names file. The format format of the logical logical name in the Logi Logical cal Names File File is: For a compound file:

 

ADXLXAAN::drive\subdirectory\ filename.extension

Logical name format for a mirrored file:

 

ADXLXACN::drive\subdirectory\ filename.extension

Note: The system allows only one level of a subdirectory in a logical name expansion. You can access prime versions of compound or mirrored files to read, write, delete, or rename files. However, Howeve r, you can only read an ima image ge version. version. You canno cannott access image ve versions rsions of dist distribute ributed d files that are distribute distribute at close. If you try to write, delete, delete, rename or lock an imag image e version of a distr distributed ibuted file, you will receive an error message.

Logical Names Table The operating system uses a single table of logical names for its files, store controller node names, subdirectori subdir ectories, es, and for most I/O devices devices such as print printers ers and displays. displays. A default logical logical names table is supplied supplie d with the operating operating system at installation installation.. The system adds adds applica application tion and user log logical ical names from the application application and the user logical logical names files files to the system table at IPL. (See “Using “Using Logical Names” on page page 2-11 for information information on app applicatio lication n and user logic logical al names files.)

 

2-13

Chapte Cha pterr 2. Managi Managing ng Files Files

 

 

These application files can be unique for each store controller so the logical names table can also be unique for each each store controller controller.. The files used in the buil building ding of the logical logical names table are: ADXDAxy F.DAT ADXDAxy  F.DAT Operating system logical names file (initially the system default table) xy F.DAT ADXDCxy  ADXDC F.DAT Application logical names file ADXDExy  ADXDE xy F.DAT F.DAT User logical names file Note: xy  is   is the node ID. The e op oper erat atin ing g syst system em bu buil ilds ds a lo logi gic cal na name mes s tabl table e at IP IPL L time time Buildi Bui lding ng a Logi Logical cal Na Names mes Ta Table ble:: Th by combining the operating system, application, and user logical file names. The operating system uses these steps to create the table: 1. The system starts starts with the default default operating operating system logical logical names file. 2. The system adds adds any new names from the applicatio application n logical name names s file. 3. If any of the application logical file names duplicate an operating system logical file name, the operating system logical file name is overlaid with the application logical file name. 4. The system uses the user logical names file to add new names or overlay existing existing names. Because the user logical names file is the last to be scanned, it has precedence over both the application and operating system logical names files. displa lay y the the lo logi gica call na name mes s tabl table, e, from from the the SY SYST STEM EM Displaying Displ aying the L Logical ogical Names Table: To disp MAIN MENU, select the Command Mode option by typing 7 and press Enter Enter.. In the the root root d dire irecto ctory, ry, type type DEFINE -S -N (S -N (S for system, N for logical names table) and the system displays the logical names tables. To display the logical logical names table table one screen screen at a time, you can use the MORE paramet parameter. er. For example: example:

C:>define -s -n |more

Changi Cha nging ng the Lo Logic gical al Nam Names es Tab Table: le: Yo You u can can chan change ge appl applic icat atio ion n logi logica call name names s usin using g the the DEFINE command. command. However, However, it is rrecommen ecommended ded that these names not b be e ch changed. anged. Refer to the the IBM   IBM  4690 Store System: User’s Guide  for   for a description of the DEFINE command. You cannot change change application application logical names through through the configuration configuration process. process. You can change the disk drive identification for some of these names to provide disk space and better performance. You can define user logical logical names during store store controller controller configuration. configuration. Use these names to override override application logical names if desired.

Accessing Distributed Files in Store Controller and Terminal Applications This section section shows how to access access distributed distributed files from from terminal nodes nodes using logical logical names. The sectio section n uses an example to show how to define the file in the user logical names table and how to distribute the file to other nodes. The example shows how a terminal user program can access a user-defined distributed file called MYFILE.DAT. MYFILE. DAT. The file file is a comp compound ound file tha thatt is Distrib Distribute ute Pe Perr Update. Update. The system system distrib distributes utes a compound compou nd file to all store controllers controllers.. The example example shows how to put the prime ver version sion of the file on drive D of the master store controller in the ADX_IDT4: directory. In the example, the user program reads the local image version of the file, which reduces response time and improves improves performance performance.. To update the file, file, the user progr program am opens the prime version version of the file on the master store controller.

2-14

4690 Store System: Programming Guide

 

 

Setting up the file on the LAN (MCF Network) and opening the file in the user program is a three-part process. proce ss. This process process consists consists of defining the file file,, creating it, and accessing accessing it thro through ugh the user pro program. gram. Defi fine ne the the file file MYFI MYFIL LE.DA E.DAT T in the the us user er lo logi gica call na name mes s tabl tables es.. Yo You u mu must st Step Step 1. De Defi fine ne the the Fi File le:: De define the file file in the logical logical names file on each each eligible eligible store controll controller. er. (Refer to th the e IBM 4690 Store  System: Planning, Installation, and Configuration Guide  for   for information on worksheets and designating eligible LAN store controllers.) When the file is defined in the user logical names tables, the table will have two entries placed in it for the MYFILE.DAT user file as follows:

1 2

$YFILE = D:\ADX_IDT4\MYFILE.DAT ! Lo Local ve version MYFILE = ADXLXxxN::$YFILE ! Prime version

where the actual node ID of the current acting master store controller replaces xx . The first entry gives the path to the local image version of the file for each store controller (for example, on drive D in the ADX_IDT4 ADX_IDT4 subdirec subdirectory, tory, with the the file name of MYFILE.DAT) MYFILE.DAT).. Open this file when when you wan wantt to access the local local version of the distribute distributed d file. Your application application can only only read this vers version. ion. The second entry gives the path to the prime version of MYFILE on the master store controller (ADXLXxxN::). (ADXLX xxN::). Open this file when when you want want to update the prime prime vers version ion of the distr distributed ibuted file file.. When the prime version of MYFILE.DAT is updated or deleted, DDA updates the local image versions on the other nodes nodes using the the LFN $YFILE. $YFILE. Since each each eligibl eligible e store controlle controllerr on the LAN has its own own | definition of $YFILE, the drive and subdirectory of the local image versions may be different from the path | of the local version on the master store controller.

|

|

| | | | |

Note: When updating any distributed file named MYFILE.DAT using the LDSN or complete file name formats, DDA will continue to use the LFN $YFILE on the other nodes if LFN MYFILE is defined on the master master store controlle controller. r. If the LFN $YFI $YFILE LE is not defined defined on the other nodes, nodes, DDA wi willll assume $YFILE is the expanded full file name and place the updates in the file C:\$YFILE on the other store controllers.

Attention: Undesirable operations may be performed on the image versions if two or more files named Attention: Undesirable | MYFILE.DAT exist in separate directories on the master store controller. |

To define the file in the logical logical names file, perform perform the following following steps at the master store store contr controller. oller. You must repeat these steps for each eligible store controller on the LAN. 1. On the SYSTEM SYSTEM MA MAIN IN MENU screen, screen, type 4 and press Enter Enter.. 2. When the INSTALLATION INSTALLATION AND UPDATE UPDATE AIDS screen screen appears, appears, type 1 and press Enter Enter.. 3. On the CONFIGURA CONFIGURATION TION screen, screen, type 2 and press Enter prompted “Are “Are you you c configur onfiguring ing fo forr a Enter.. When prompted LAN system?”, type Y. 4. When the CONTROLLER CONTROLLER CONFIGURATION CONFIGURATION screen appears, appears, press press Enter Enter.. 5. At the next configuration screen, select a store controller by moving the highlighted cursor to the appropriate node ID and press Enter return to this this screen screen to sel select ect an ID fo forr each e eligible ligible Enter.. You must return store controller. 6. When the next CONTROLLER CONTROLLER CONFIGURATI CONFIGURATION ON screen appears, appears, use the Tab the Tab key  key to move the cursorr next curso next to User User Logical Logical File Names. Names. Type X and press Enter Enter.. 7. When the USER LOGICAL LOGICAL FILE NAMES screen screen appears, appears, type 1 and press Enter Enter.. 8. On the same screen in the file name window, enter the user logical name to be used to access this file.. (The file (The sample sample prob problem lem uses uses MYFIL MYFILE E as th the e log logica icall name.) name.) Pre Press ss Enter Enter..

 

2-15

Chapte Cha pterr 2. Managi Managing ng Files Files

 

 

9. On the DEFINE LOGICAL FILE NAMES screen, type in the expanded name to define the logical name for the distributed user file, and press Enter Enter.. The The sa samp mple le prob proble lem m uses uses ADXLXAAN::D:\\ADX_IDT4\MYFILE.DAT. The node name name ADXLXAAN:: ADXLXAAN:: defines defines this file to be on the master master stor store e control controller. ler. The D:\\ defi defines nes it on drive D and the double backslash ensures that drive D is accessed while operating in any subdirectory subdir ectory.. The remaining remaining portion portion of the node name, ADX_IDT4\MYFIL ADX_IDT4\MYFILE.DAT, E.DAT, is the stand standard ard subdirectory/filename.extension naming convention. 10 10.. Pr Pres ess s F3 to F3 to go back through the configuration screens until you return to the CONTROLLER CONFIGURATION CONFIGUR ATION screen. screen. On this screen, screen, select select another another controller controller node ID ID.. 11. Repeat steps 5 through 10 until you have defined the user logical name MYFILE on all store controllers on your network. 12 12.. Pr Pres ess s F3 again F3 again to back out of the configuration process until you get to the CONFIGURATION screen. On this screen, type 5, and press Enter Enter.. 13. On the next screen screen,, type 2 (Controller Configurations) and press Enter Enter to  to activate the changes just made. 14. After yo you u have verified, verified, distrib distributed, uted, and activat activated ed the changes, changes, y you ou must IP IPL L the cont controller rollers. s. To do this, press the SysRq  key, then type C to select select cont controller roller function functions. s. On the n next ext sc screen, reen, ttype ype 2 SysRq key, (Controller functions) again and press Enter Enter.. On the the n next ext scr screen een,, type type 9 (Load Controller Storage) and press Enter Enter.. In the highlighted highlighted box that appears, appears, type an asterisk asterisk (*) to IPL all store controlle controllers. rs. Answer Y to the prompt about stopping background programs. If you do not want background programs stopped now, press F3 to F3 to process, and wait until all background backgr ound proc processing essing is finished finished before co continuin ntinuing. g. Before the next next steps can be compl completed, eted, the controllers must controllers  be IPLed. IPLed. You can can choose choose the the time to do that.  must be

Step Step 2. Cr Crea eate te th the e Fi Fille: Cre Create ate the the file file MY MYFI FILE LE.D .DAT AT in on one e of the the foll follow owin ing g ways ways:: user-written en program program that creates a POS file statement. statement. For examp example, le, if you are using an  Create a user-writt IBM 4680 BASIC BASIC program, program, include a CREATE CREATE POSFILE POSFILE statement. statement. Be sure the st statement atement in includes cludes the parameters COMPOUND and PERUPDATE to give the file the correct attributes.

 At the master store controller from the host specifying either CREATE or CLOD (Create and Load) using ADCS. Be sure you specify specify the correct correct attributes attributes on the CREATE or CLOD statements statements (tha (thatt is, SHARE=NO, VOL=3) to get the correct distribution attributes.  Use another supported means instead of ADCS to send HCP commands to create the file.

 Use the 4690 Operating System COPY command to copy the file from a diskette to the fixed disk. You can create the version on the diskette as a distributed file and then the proper attributes are transferred transfe rred during during the copy process. process. If you copy a nondist nondistributed ributed version, version, use the Dis Distribute tributed d File Utility (DFU) (DFU) to define the the file as distributed distributed after after you copy copy it. Refer to the IBM 4690 Store System:  User’s Guide  for   for more information about the DFU. The file is distribute distributed d to the proper proper store controlle controllers rs by the DDA. Refer to the IBM 4690 Store System:  User’s Guide  for   for more information.

Step Step 3 3.. Ac Acces cess s th the e Fi File le ffro rom m th the e Us User er P Pro rogr gram am:: Th The e us user er prog progra ram m us uses es the the MY MYFI FILE LE us use er logical name to open the prime version of MYFILE.DAT on the master store controller for a READ or READ-WRITE. The program uses the $YFILE file to open the local version of the file on the store controller that is supporting the TCC Network that the terminal is on.

2-16

4690 Store System: Programming Guide

 

 

You can open the local file only for READ, because an application cannot update an image version of a file. If you create the file with a file attr attribute ibute of distribute distribute at close, the app applicatio lication n cannot open $YF $YFILE ILE because an application cannot read a file with the distribute at close attribute.

Using File Names in Store Controller Applications In store controller applications, the IBM 4680 BASIC statements that use file names are OPEN, CREATE, RENAME, SIZE, SIZE, and CHAIN. For all statements statements except except the CHAIN CHAIN stateme statement, nt, use any of the fo following llowing formats:      

LFN  LDSN:filename.extension  drivename:\subdirectory\...\filename.extension 

The LFN allows you you to place the refere referenced nced file on any driv drive e without modif modifying ying the applic application. ation. You should define define the LFN to be a complete file name with the subdirec subdirectory tory bein being g ADX_IDT1. (There (There should be an ADX_IDT1 subdirec subdirectory tory on each drive.) drive.) If you use the LDSN format, format, you should define define the LDSN as a drive and subdirector subdirectory y path. You can use the complete complete file name format format for cases that are no nott supported by the LFN or LDSN format, such as a special testing environment. When you are using the CHAIN statement, use a file name and extension with a drive and subdirectory, or use the LDSN for the drive drive and subdirectory subdirectory.. Whichever Whichever format format you use, you must spec specify ify the drive and subdirectory subdir ectory.. The possible possible formats are:    

LDSN:filename.extension  drivename:\subdirectory\...\filename.extension 

Using File Names in Terminal Applications In terminal applications, the IBM 4680 BASIC statements that use file names are OPEN, CREATE, RENAME, LOAD, LOAD, SIZE, and CHAIN. CHAIN. Each of thes these e statements statements requi requires res that the no node de name R:: pr precede ecede the file name. When using the OPEN, CREATE, RENAME, or LOAD statements, use the LFN format for the file name. This allows you you to place the referenced referenced file on any disk drive drive without modi modifying fying the appl application ication.. You should define the logical file name to be a complete file name with the subdirectory being ADX_IDT1. (There (Ther e should be an ADX_ID ADX_IDT1 T1 subdirectory subdirectory on each each disk drive.) drive.) An example of a file name usin using g this format is:

 

R::EALABCDE

  the R:: node node name. name. The terminal terminal applica application tion c can an Note: The LFN represents all of the file name except  the access any any drive except except the diskette diskette drives drives for OPE OPEN, N, CREATE, or RENAME. RENAME. CHAIN and LOAD LOAD can access any drive. The IBM 4690 Operating System converts logical file names to their fully qualified names that you defined in configuration. When using the CHAIN statement, use a file name and extension without a drive or subdirectory because the IBM 4690 Operating Operating Syste System m automatically automatically uses the ADX_IPGM ADX_IPGM subdirectory subdirectory.. An example of a file name using this format is:

 

R::EALPQRSL.286

 

2-17

Chapte Cha pterr 2. Managi Managing ng Files Files

 

 

Using Node Names to Access Files To access a file on another store controller, an application must use a file specification that includes the node name when when opening opening a file. (Refer to the IBM 4690 Store System: User’s Guide  for   for a discussion of nodes and node node IDs.) If file specification specification does not not include the node na name, me, the reques requestt tries to locate the file on the local store controller. The complete file specification should follow the format:   nodename:: pathname\ filespec N:: where xy  where xy  is   is the store control controller ler ID. Note th that at you end end nod node e Every node name has the form ADXLXxy  ADXLX xy N:: names with a double double colon. Use a single colon colon to indicate physical physical devic devices es on the same contr controller, oller, such such as C:, D:, LPT1:, LPT1:, COM1:, and so on. on. Use the double double colon to indicate indicate different different no nodes des on the net network. work. R:: is required in a terminal application application when addressing addressing an external external (any contro controller) ller) file. For example example,, when opening the XYZ file on the file server, the terminal application refers to this file as R::XYZ, where the XYZ logical name might be defined in the logical names table as ADXLXACN::C:\AD ADXLXA CN::C:\ADX_IDT1\E X_IDT1\EAL__XY AL__XYZ.DAT. Z.DAT. ADXLXACN ADXLXACN is the system name for the file server. server. In addition to the unique node name, some store controllers also have a logical  node   node name name.. Thes These e st stor ore e controllers contr ollers are the master, master, alternate master, master, file server, and alternate alternate file server server.. The logical node name provides a quick means of identifying provides identifying the mos mostt important store store controllers controllers on your sy system. stem. The logical logical node name is updated whenever the acting master or file server changes. The following list shows how the operating system names the logical nodes on your system: Store Controller Acting master Acting alternate master Acting file server Acting alternate file server

Logical Node Name ADXLXAAN:: ADXLXABN:: ADXLXACN:: ADXLXADN::

You can access files using either the unique node name or the logical node name.

Logging Distribution Errors The system enters errors that are made when updating copies of distributed files in the Distribution Except Exc eption ion Log. Log. Refer Refer to the IBM 4690 Store System: User’s Guide  for   for information about this log.

Performing File Functions IBM 4680 BASIC provides statements to perform such file functions as creating, deleting, and using data files. These statements statements help help you you manage manage data data files within your applic applications. ations. Both ttermina erminall and store controller applications can use these statements. You can also also perform perform file functions functions using commands commands in Command Command Mode. Mode. Refer to the IBM 4690 Store  System: User’s Guide  for   for an explanation of these commands. Note: The term disk is used throughout the remainder of this section to indicate both a fixed disk and a diskette.

2-18

4690 Store System: Programming Guide

 

 

Crea Cr eati ting ng File Files s You can create create files using either either the text editor or IBM 4680 4680 BASIC stateme statements. nts. For inform information ation on creating files with the text editor, refer to the IBM the IBM 4690 Store System: User’s Guide . Warning: Creatin Creating g a file using a 4680 4680 BASIC state statement ment esta establishes blishes a new new file on a disk. If you crea create te a file with a name that already exists, the system erases the existing file before the new file is created. Use the CREATE statement statement to create create sequential, sequential, random random,, and direct files. You can execu execute te this statement stateme nt in both terminal and store store contr controller oller application applications. s. If the disk does not have the space space required required for the file, the CREATE statement fails. Use the CREATE POSFILE POSFILE KEYED state statement ment to create keyed keyed files. You can execute execute this statement statement only in the store store control controller. ler. Once you you create create a ke keyed yed file, file, you cannot cannot in increas crease e its s size. ize. To incr increase ease the the keye keyed d file, you you must rebuild rebuild it. it. See “Keyed “Keyed Files” Files” on on page 2-28 ffor or an e explana xplanation tion of rebuilding rebuilding files. files. On a LAN (MCF Network) Network) sy system, stem, use the CREATE CREATE POSFILE POSFILE statement statement to creat create e files. You must spe specify cify a distribution distribution mode and a file type for files created created with this sta statement. tement. For information information on distr distribution ibution modes and file types, refer to the IBM the IBM 4690 Store System: User’s Guide .

Space Spa ce All Alloca ocation tion:: When you create a file, the operating system keeps track of the available disk space in the File Allocation Allocation Tab Table le (FAT). As your application application creates, creates, dele deletes, tes, or expan expands ds files, the system updates updates the available available space in the table. table. When you cre create ate a random or dire direct ct file, the system allocates allocat es only one cluster cluster on on the di disk. sk. This space space is not init initialized ialized.. If the s space pace mu must st be initializ initialized ed to use use the file, your applicatio application n should write all of the initi initial al records. records. You can increase increase the size of a rando random m or direct file by writing records past the end of the created file. When you create a keyed file, the system allocates disk space for the requested number of records; it also initializes the space to binary zeros. When you create create a sequential sequential file, the system allocates allocates onl only y one cluster on the disk. disk. The space all allocated ocated is not initialized. initialized. The size of a sequential sequential file is increased increased as your application application write writes s data to the file.

Fi File le A Acc cces ess s Ri Right ghts: s: Wh When en yo you u crea create te a file file,, the the op oper erat atin ing g syst syste em as assi sign gns s the the us user er ID ID,, grou group p ID, ID, and access access rights of the executing executing applic application ation to the file. The opera operating ting system system places this info information rmation in the directory directory entry entry of the the file. See “Protectin “Protecting g Files” on page 2-23 for for infor information mation on u user ser ID, g group roup ID, and access access rights. You cannot change change this infor information mation with a 4680 BASIC ap applicatio plication n after the file is created. create d. To change the the access rights, rights, use use the FSET comm command and in Command Command Mode. You set up the user ID and group ID for applications executed in Command Mode in the system authorization author ization file file.. Applications Applications started started as primary primary or secondary secondary from the SYSTEM MAIN MENU MENU are always assigned assigned user user ID=1 and gr group oup ID=2 ID=2.. See “System “System Authoriz Authorization” ation” on pag page e 15-8 for for mor more e information. The system starts an IBM 4680 BASIC application with access rights that allow READ, WRITE, and DELETE access access for owners owners and requesters requesters for group group or world rights. rights. Use the ACCESS statement statement to modify the access rights. Creating Creatin g a file also also performs performs the s same ame func function tion as opening opening a file. file. See “Ac “Accessin cessing g Files” on page 2-20 for a description of these functions.

 

2-19

Chapte Cha pterr 2. Managi Managing ng Files Files

 

 

Dele De leti ting ng File Files s IBM 4680 BASIC BASIC provides provides a DELETE statement statement for d deleting eleting a file file from the disk. disk. To delete a file file,, the application applic ation must have have the file open and have DELETE DELETE access rights rights for the file. To ensure tha thatt the file is deleted, delete d, the file must not be opened by another another applic application. ation. You can ensure ensure that your applic application ation is the only user user by opening opening the fi file le as LOCKED. LOCKED. See “Sharing “Sharing Files” on page 2-21 for for info information rmation on the LOCKED option.

 Accessing Access ing Fil Files es Your applicatio application n gains access access to a file on a disk by by using the OP OPEN EN statement. statement. Both the terminal terminal and th the e store controller can use this statement. The values values on the OPEN statement determine determine how the applicatio application n opens the file. You normal normally ly open a file according according to the way it was create created. d. For example, example, you open a direct file by specifying specifying direct direct with the OPEN statemen statement. t. You can, can, however, however, open ffiles iles d differen ifferently. tly. To sequentia sequentially lly re read ad all the records records in a keyed file, you can open the file in direct mode by specifying direct with the OPEN statement and specifying specif ying a record record length of 512. When an OPEN stat statement ement specifies specifies keye keyed, d, the IBM 4680 BASIC runtime library checks that you created the file as a keyed file. The OPEN statement statement requests requests acces access s for the file function functions s that the applica application tion will perform. perform. This statement stateme nt request reques access, to perform perfousers, rm read, write , oruser delete functions. functi ons.4690 These acc access ess System rights rightsmdefine the allowed opcan operatio erations ns fort owners, owners group user s, andwrite, world users. s. The IBM Operating Oper ating Syste checks the file’s access access rights against against the requested requested functions functions when the applicatio application n uses the OPEN statem statement. ent. If the kind of functions functions requested requested are not allowed allowed for your application application,, the OPEN statement fai fails. ls. You should specify specif y only the needed functions functions to avoid avoid OPEN statement statement failures. For terminal terminal applica applications, tions, OPEN statements that request only the read function are more efficient than OPEN statements requesting the write function function.. See “Protectin “Protecting g Files” on page page 2-23 for for more more information information o on n file access access rights rights.. The OPEN statement also specifies the type of file sharing that the executing application is requesting. The type type specified specified remains remains in effect effect for as long as the the file is open. open. See “Sharing “Sharing Files” Files” on page 2-21 for information inform ation on file sharing sharing types. If the OPEN statemen statementt requests a file sharing sharing value tha thatt conflicts with current file opens, the OPEN statement fails. If your application application is opening opening a sequential sequential file to write, use the APPEND reserve reserved d word. APPEND cau causes ses data written written to the file to be added added at the end of the fi file. le. The WRITE s statement tatement can can only add da data ta to a sequential seque ntial file. If you want to remove the data in a sequential sequential file, you must must delete the entire entire file or create the file again. For keyed, keyed, random, and direct direct files, do not spec specify ify the BUFF and BUFFSIZE BUFFSIZE reser reserved ved words words.. For these file types, types, the 4680 BASIC BASIC runtime buffer buffer size is equal equal to the value value of the RECL re reserve served d word. The IBM 4690 Operating System provides file record level data integrity for file writes of 512 or fewer bytes only. For sequential files, the RECL reserved word is not valid, and the BUFF and BUFFSIZE reserved words determine determ ine the 4680 BASIC runtime runtime buffer size. size. If you specify BUFFSIZE, BUFFSIZE, the system system ignore ignores s BUFF, and the buffer size size is equal to the value specified specified with BUFFS BUFFSIZE. IZE. If you do not specify BUFFSIZE, BUFFSIZE, the buffer buffer size is equal to the value specified for BUFF multiplied by 128 bytes. You should should select the sequential sequential file buffer buffer size according according to your intended intended use of the file. When you are reading a sequential file, the 4680 BASIC runtime library requests file reads in increments of the buffer size. When you are writing writing to a sequential sequential file with a WRITE# statement, statement, the 4680 BASIC ru runtime ntime library library uses the buffer buffer to request request a file write. write. If you open the the sequen sequential tial file as LOCKED, LOCKED, the IBM 4680 BASIC BASIC runtime library places as much data as fits into the buffer, independent of record size, before requesting a

2-20

4690 Store System: Programming Guide

 

 

file write. write. If you open the sequent sequential ial file as other other than LOCKED, LOCKED, then IBM 4680 BASIC BASIC runti runtime me library library requests a file write for each application WRITE statement. The IBM 4690 Operating System provides file record level integrity only for file writes of 512 or fewer bytes. To prevent prevent record fragmentin fragmenting g when using a LOCKED sequential sequential file, file, force a file write in increments of complete records by using the TCLOSE statement. The 4680 BASIC runtime runtime buffer used used for file I/O is allocated allocated from your application application hea heap. p. Each file has its own buffer allocated. Terminal applications Terminal applications can use a PRIORITY PRIORITY reserv reserved ed word on the OPEN and CREAT CREATE E statements. statements. The PRIORITY reserved word causes the READ or WRITE requests for this file to have a higher priority for disk service service at the store controller controller tha than n a file not opened with the PRIORITY PRIORITY reserv reserved ed word. Use this function only for files that are accessed in the critical response time paths in your terminal application.

Ending Access to Files Use the CLOSE statement in the store controller and the terminal when your application has no further use for a file. Because the store controller and terminal can lose communications with each other, the IBM 4690 Operating Operat ing System provides provides a periodic periodic check of the terminals. terminals. A terminal can sto stop p communic communicating ating with the store controller when a TCC Network is broken or disconnected, when the terminal is powered-OFF, or when you have defective defective terminal hardware hardware or software. software. Periodically, Periodically, the operating operating system in the store controller exchanges a message with the operating system in the terminal to determine that each terminal with open files is still still communicating. communicating. If a terminal does no nott respond, the IBM 469 4690 0 Operating Operating System in the store controller controller executes executes a close close function for the files files that are opened by that that terminal. The close function functio n also releases any outstanding outstanding record record locks for that termin terminal. al. If the terminal returns returns to operation without having to IPL, the operating system in the terminal reopens the files for that terminal.

 Sharin Shar ing g File Files s The IBM 4690 Operating System and IBM 4680 BASIC provide facilities for specifying and managing the way several several applications applications share share a disk file. Your application application can request request READ and WR WRITE ITE access to a file. In addition addition,, when your application application accesses accesses a file it can request request that the system re restrict strict the READ and WRITE access for other applications. File security security attributes attributes control control whether an application application can can access a specified specified file. This acce access ss is based on the access rights rights of the specified specified file and the type of access access requeste requested d by the applicat application. ion. See “Protecting “Protecting Files” on on page 2-23 fo forr inform information ation on ffile ile secu security. rity. File sharing sharing controls controls h how ow many ap applicati plications ons acc access ess one file. A terminal application cannot access a keyed file in direct mode if another terminal is currently accessing the file as a keyed file. The terminal terminal application application trying to access access the file in direc directt mode receive receives s errors from the store controlle controllerr file system as a result. result. The terminal terminal applicat application ion access accessing ing the file in keyed mode must close the file before access to the file in direct mode functions correctly. On the OPEN and CREATE statements, you can specify how you want your application to share a file. You can use three three different values values on these statements statements to specify specify the three type types s of sharing. The shari sharing ng type is in effect as long as your application has the file open.

 

2-21

Chapte Cha pterr 2. Managi Managing ng Files Files

 

 

The following list describes the sharing values and their meaning: Option

Description

LOCK LO CKED ED

Requ Reques ests ts a acc cces ess s tto o th this is fil file e as the the onl only y appl applic icat atio ion n to use use th this is fil file. e. Th The e req reque uest st iis s no nott allowed if another another applicatio application n has this file open. open. If the request request is allowe allowed, d, no other application can open this file for any kind of access.

READONL REA DONLY Y

Reques Requests ts acc access ess to to this file file that that allows allows all othe otherr app applica lication tions s to hav have e only R READ EAD ac acces cess s to this file. The request is not allowed:

 If another application has this file open as LOCKED  If another application has this file open as READONLY or UNLOCKED and has WRITE access If this request is allowed, another application cannot open this file as:    LOCKED  READONLY and request WRITE access  UNLOCKED and request WRITE access UNLOCKE UNL OCKED D

Reques Requests ts acc access ess to to this file, file, which which allow allows s all other other a appli pplicat cation ions s to hav have e both R READ EAD and and WRITE access access to this file. file. This is the lea least st restrictive restrictive access access type a and nd you shou should ld use this type whenever possible. The request is not allowed:

 If another application has this file open as LOCKED  If another application has this file open as READONLY and this request specifies WRITE access If this request is allowed, another application cannot open this file as:    LOCKED  READONLY if this request specified WRITE access When your application opens a file as LOCKED or READONLY, it does not need to provide for sharing write access with other applications. When your your application application opens a file as UNLOCKED, UNLOCKED, it should lock records records that it inten intends ds to modify. This serializes seria lizes all the changes changes to a record of a random, random, direct, or keyed keyed file. You can use sequential sequential files UNLOCKED without the application use of record locking because the system appends each record write to the end of the file. In a store controller application, you can lock and unlock records for random and direct files by using the LOCK and UNLOCK functions or the AUTOLOCK and AUTOUNLOCK reserved words on the READ and WRITE statements. statements. The preferred preferred way is the AUTOLOCK AUTOLOCK and AUTOUNLO AUTOUNLOCK. CK. In a terminal terminal app applicatio lication n you can use only the AUTOLOCK and AUTOUNLOCK. If your application opens the same file many times, you should include only one LOCK or READ AUTOLOCK at a time for the file. For keyed files, you can use only the AUTOLOCK and AUTOUNLOCK in both the store controller and the terminal applications. If you have many applications that lock a record in more than one file, use the same sequence of locking in each application. application. This prevents prevents applications applications from deadl deadlocking ocking by having having some records lock locked ed that another application is trying to lock.

2-22

4690 Store System: Programming Guide

 

 

An application is not allowed to lock more than five records for each keyed file at the same time. The system might reject a request to lock a record because another application has already locked the record. recor d. When this occurs, occurs, the application application should should wait and try the record record lock again; again; if the application ha has s an operator interface, it should notify the operator that the record is temporarily not available. Locking a record in a keyed file actually locks all of the records in the file sector containing that record. Therefore, you should avoid application designs that would require high-performance use of keyed file record locks by two or more applications.

 C opyin Copy ing g File Files s You can use the the COPY command command in Command Mode Mode to copy a file file.. The COPY comm command and creates creates a new file with the name name you specify. specify. Because Because the COPY command command is crea creating ting a new file, th the e new file has the user ID and group group ID assigned assigned to the COPY command command when it be began. gan. The access access rights fo forr the new file are the same as the access access rights of the original original file. The user requestin requesting g the COPY command must must have READ access access rights to the original original file. If a file with the new name already already exists, the user needs needs DELETE access to that file so that COPY can delete that file.

 R enami Rena ming ng File Files s You can rename a file with BASIC RENAME function or you can use the RENAME command in Command in Mode. Modthe e. IBM Both4680 methods metho ds chang change e the name of the file and a nd leave the user user ID, grou group p ID, and access access rights unchanged. unchanged. The requester requester of the RENAME must have have either WRIT WRITE E or DELETE access rights.

 Protectin Protec ting g Fil Files es The IBM 4690 Operating System and IBM 4680 BASIC provide facilities to limit file access to only authorized author ized user users. s. The facilities facilities provide provide for contro controlling lling READ, WRITE, WRITE, DELETE, and EXECUTE EXECUTE access access to a file for for three three categ categories ories of users. users. The categori categories es of user user are owner owner,, group group,, and w world. orld. The system system bases file security functions on how the user ID and group ID of the requesting application match the user ID and group ID of the requested file. The system assigns assigns an application application a user ID and group group ID when the applica application tion start starts. s. The syste system m assigns the IDs for an operator interactive application in the store controller according to the system authorization author ization file. This includes includes Command Mode commands commands.. For your your b backgr ackground ound a applica pplication, tion, tthe he user user ID is one and the group ID is two. For operating operating system system background background applic applications, ations, the user user ID and group ID are either one, one, one and zero, or zero. zero. The terminal terminal 4680 BASIC application application IDs are always always treate treated d as a user ID of one and a group ID of two. You assign a file a user ID, group group ID, and access ri rights ghts when you create create the file. This sectio section n explains the access access rights. rights. The section section “Fi “File le Access Access Rights” Rights” on page page 2-19 co contains ntains in informat formation ion on how you assign assign access rights to the file. The system performs performs file security security checking checking when when a file is opened. The first part of sec security urity checking checking compares the user ID and group ID of the requesting application and the user ID and group ID of the requested reques ted file. Based on this comparison, comparison, the requesting requesting application application falls into one of three categor categories: ies: owner, group, or world.

 For the requesting application to become an owner, the user ID of that application must be equal to

the user ID of the file, and the group ID of the requesting application must be equal to the group ID of the file.

 

2-23

Chapte Cha pterr 2. Managi Managing ng Files Files

 

 

 

Group = Group ----- OWNER access User = User -Us

 For the requesting application to become a group requester, the group ID of the requesting application must be equal to the group ID of the file without the user ID of the requesting application being equal to the user ID of the file.

Group = Group -User ≠ User ------- GROUP access  For the requesting application to become a world requester, the group ID of the requesting application must not be equal to the group ID of the file.

Group ≠ Group ------ WORLD access User = User -When a requesting application has a user ID of zero and a group ID of zero, the system bypasses the file security checking. The second part of security checking compares the type of access requested by the application with the type of access access allowed for this file. file. A 4680 BASIC applic application ation can request request READ, WRITE, WRITE, and DELETE access acces s on the OPEN statement. statement. A 4680 BASIC applicat application ion requests requests EXECU EXECUTE TE access access to a file by attempting attempt ing to chain to that file. The access access rights for each fil file e define whethe whetherr this file can be acces accessed sed to read, write, write, delete, or execute execute for each category category of user. user. Owner, group, group, and world use userr access rig rights hts are independent indepe ndent and do not have to pro provide vide diminishing diminishing levels levels of access. For examp example, le, the access ri rights ghts of the operating system data files allow an owner to read, write, delete, and execute; a group user to read and execute; execute; and a world user to read read and execute execute.. For a 4680 BASIC application application to be allowed allowed access to a file, all of the access types requested on the OPEN statement must be allowed for the application’s requester reque ster categ category. ory. If any of the access types types for the file are not allowed, allowed, the OPEN reques requestt fails. To rename a file, a requesting application must have either WRITE or DELETE access rights.

 Protecting Subdir Protecting Subdirecto ectories ries Subdirectories Subdirector ies can contain contain multiple files and can can be protecte protected d in similar ways to individual individual files. files. You assign a user user ID, group ID, and access access rights to each subdirect subdirectory ory when you cre create ate it. You assign the subdirectory subdir ectory the user user ID and the group ID of the creating creating applica application. tion. The creat creating ing applic application ation can be the MKDIR command or a 4680 BASIC application. The MKDIR command sets the access rights as READ, WRITE, DELETE, and EXECUTE for the owner, nothing nothin g for the group user, user, and nothing for the wor world ld user. You can change change the access rig rights hts with the FSET command. When a 4680 BASIC application uses the MKDIR command to create a subdirectory, the access rights are set according according to the ACCESS ACCESS statement. statement. The EXECUT EXECUTE E access is always always set fo forr the owner a and nd is set for the group user and the world user if any other access right is set for that user.

2-24

4690 Store System: Programming Guide

 

 

The access rights for a subdirectory have a different meaning than they do for a file: Access Ri Right

Description

READ

Allows the use of SIZE and DIR commands for files in the subdirectory

WRITE

Allows the use of CREATE, DELETE, and RENAME commands for files in the subdirectory

EXECUTE

Allows a program to open files in the subdirectory

DELETE

Allows the use of the FSET command in Command Mode for files in the subdirectory

The access rights and restrictions described for subdirectories do not apply to the root directory.

Enabling and Disabling File and Subdirectory Security Each disk can can have a disk disk label. The disk lab label el contains contains the volu volume me name for the disk, disk, the user ID, ID, the group ID of the label’s label’s creator creator,, access rights rights for the label, and mode flags. flags. The mode flags con control trol the enabling enablin g and disabling disabling of security for files files and subdirector subdirectories ies for the entire disk. disk. When you ena enable ble security, secur ity, you control application application access access to files and subdirectories subdirectories.. When you disab disable le security security,, all applications have full READ, WRITE, EXECUTE, and DELETE access to all files and subdirectories on the disk. You use thinformation e DISKSET DISKSE command comman toe create crea te a diskYou label. label. to the IBM 4690 Store User’s  Guide    forthe  for inform ationTon how toduse us DISKSET. canRefer also also use DISKSET to e enable nableSystem: and d disable isable file security for a disk if you have WRITE or DELETE access rights to the disk label. The installation process for the IBM 4690 Operating System creates the disk label for the fixed disks with a user ID of zero, a group ID of zero, and security security ena enabled. bled. File secur security ity on the fixed disks pr provides ovides protection of the system files from applications and protection of the application files from other applications.

Reading a File Record You read the data from a disk file record into BASIC variables with the READ#, READ# LINE, READ FORM#, and READ READ MATRIX statements statements.. The READ# statement statement specifie specifies s the file to read by tthe he I/O session number, the variables to assign the data to, the format for mapping the data record into the variables, and whether variables, whether to lock lock the record record from use by oth other er applications applications.. Refer to the the IBM  IBM 4680 BASIC:  Language Reference  for   for a description of the format string items used with the READ FORM# statement. You read sequenti sequential al file reco records rds with the RE READ#, AD#, READ# LINE, LINE, and READ MATRIX MATRIX statements. statements. The READ# LINE statement assigns all of the data in the current record to a single variable, and the READ# statement assigns the individual fields of the record to the individual variables specified on the READ# statement. stateme nt. You can also also use the READ FORM# FORM# statement statement for sequ sequential ential file files, s, but it is less practical practical because the records in sequential files usually vary in length. The READ MATRIX statement, which is used only for sequential files, allows one-dimensional string arrays array s to be read from disk efficiently. efficiently. READ MATRIX reads reads a sequential sequential file record an and d parses the record into an array. You can read read random file file records records with the same same statemen statements ts as seque sequential ntial files files.. The READ FOR FORM# M# statement is less practical for random file records because the fields of a random file can vary in length. Keyed and direct direct file records records can be read only with the READ READ FORM# statement. statement. The format str string ing items are necessary because there are no field or record delimiters within the data record.

 

2-25

Chapte Cha pterr 2. Managi Managing ng Files Files

 

 

The reads of a sequential file normally proceed from the first record of the file to the last record of the file. By using the PTRRTN function, you can save the relative position of a record within a sequential file so that you can can use it to reread reread from that position position in the file file.. You use the POINT POINT statement statement to re-e re-establis stablish h the saved saved relative relative position. position. You cannot cannot issue a WRIT WRITE# E# statement statement after a POINT POINT.. The reads of a keyed, keyed, direct, and random random file are for records records at any posi position tion in the file. For direc directt and random files, the record number determines the relative position in the file when it is multiplied by the record recor d length. For keyed files, files, the key is transformed transformed into a relative relative sector within within the keyed file and tha thatt sector and and any sectors sectors chained to that sector sector are scann scanned ed for the record. record. See “Keyed “Keyed Files” on page 2-28 for more informatio information n about sectors sectors..

Writing a File Record You write the data to a disk file record from IBM 4680 BASIC variables with the WRITE#, WRITE FORM# (described (desc ribed as part part of WRITE#), and WRITE WRITE MATRIX statements. statements. You can also use the PRI PRINT NT USING# statement stateme nt in the store store controller controller to write data data to a disk record. record. The WRITE st statement atements s are the recommended recom mended statements. statements. The WRITE statement statement specifies specifies the file to write by the I/O session session number, the variables to get the data from, the format to map the data from the variables into the record data, and whetherr to unlock the whethe the record for for use by other other applic applications. ations. Refer to the IBM 4680 BASIC: Language  Reference  for   for a description of the format string items used with the WRITE FORM#. The IBM 4690 Operating System provides record integrity support to ensure that a record is written to the file corr correctl ectly. y. The reco record rd int integr egrity ity suppo support rt is de depen penden dentt on a rec record ord b bein eing g no mor more e than 512 512 bytes. bytes. The only exception to this is the WRITE MATRIX statement, which can write records larger than 512 bytes. Both terminal and store controller applications can use the WRITE MATRIX statement. A store controller controller application application writes writes sequential sequential file records records with the WRITE# WRITE# statement. statement. The WRITE# statement stateme nt assigns the individua individuall variable variables s of the statement to the field fields s in the record. String exp expressio ressions ns are placed into the record with a starting quotation mark and ending quotation mark followed by a comma. Numeric expressions are placed into the record after being converted to their ASCII representation and are followed followed by a comma. comma. The last express expression ion in the record record is follo followed wed by a CR/LF instead instead of a comma. The WRITE FORM# statement can also be used in a store controller application to write a sequential record, but it is not very convenient because the application must provide all of the sequential file record delimiters. When using a WRITE# statement to write a shared sequential file, the BUFFSIZE value in the 4680 BASIC OPEN statement should be as large as the largest record that you are going to write to that file. This value should take into consideration the quotes enclosing the fields and the two bytes for the CR/LF. Failure to do this could cause the record being written to be split if another application writes to that file at the same time. A terminal applicatio application n writes sequential sequential file records records with the WRITE WRITE MATRIX stateme statement. nt. The WRITE MATRIX statement assigns the string array elements to the fields in the record in the same way that a WRITE# statement assigns strings to a field. The records written to a sequential file by a WRITE MATRIX statement might not be in the same chronologic chron ological al sequence in which they were requested requested.. Any applica application tion reading reading a sequential file should provide for this sequence. You can write random random file records records with the WRITE# WRITE# statement. statement. The varia variables bles are mapp mapped ed to the fields within a data record the same as sequential files, except that a comma is placed after the last field and the records records are padded padded to fill the record record size. size. You can use the the WRITE FORM# s statemen tatementt to write a random record, but it is not very convenient because the application must provide all of the random file record delimiters.

2-26

4690 Store System: Programming Guide

 

 

You can write keyed keyed and direct direct file records on only ly with the WRITE FORM# statement. statement. The format string string items are necessary because there are no field or record delimiters recorded with the data. The writes writes to a sequential sequential file proceed proceed from the the first reco record rd of the file to the last last record of the the file. By using the PTRRTN function, you can save the relative position of a record within a sequential file to use at a later time to read read from that position position in the the file. You cannot cannot use PTRRTN PTRRTN to write for files files that are opened,, UNLOCKED. opened UNLOCKED. Use th the e POINT statement statement to re-establish re-establish the saved saved rrelative elative position. position. You c can an also also use a POINT statement to truncate a sequential file to zero size if the file is opened LOCKED or READONLY. READONL Y. See the the description description of the POINT statement. statement. The writes of a keyed, keyed, direct, and random random file are for rec records ords at any position position in the file. For direct direct and random files, the record number determines the relative position in the file when it is multiplied by the record recor d length. For keyed files, files, the key is transformed transformed into a relative relative sector within within the keyed file and tha thatt sector and and any sectors chained chained to that sector sector are scann scanned ed for the record. record. If the record cannot cannot be found in those sectors sectors,, it is added added to the file. file. See “Keyed “Keyed Files” Files” on page page 2-28 for more inf informatio ormation n about s sectors ectors..

Ensuring Data Integrity across Power Line Disturbances The IBM 4690 Operating Operating Syste System m saves the data in NVRAM. If a power line distur disturbance bance (PLD) (PLD) occurs during a disk write and prevents the completion of the disk write, the system uses the saved data to complete the disk write when the power is restored.

PLD Protecti Protection on fo forr Wr Writing iting One R Record: ecord: All file type writes of 512 bytes or less and the WRITE MATRIX MATRIX are protected protected by this feature. feature. There are no reserved reserved words words on the 4680 BASIC statements stateme nts to invoke or disable disable PLD suppo support. rt. The PLD recovery recovery routine routine writes the entir entire e record independent of whether the record spans disk sectors. Any disk write that is queued in the store controller and has not been started prior to the PLD is lost when a PLD occurs. occurs. Because Because the terminal memory memory is battery-powe battery-powered, red, a termina terminall program can mak make e the WRITE request again after the power is restored. the HOL OLD D reserved word on a WRIT RITE PLD Protecti Protection on fo forr Wr Writing iting Two R Records: ecords: You can use the statement in the store controller to PLD protect a pair of record writes issued by the same application. The HOLD function ensures that either both of the records are written or that both of the records are not written with respect respect to the occurrenc occurrence e of a PLD. You can use the HOLD function function only for rec records ords of 512 bytes or less for random, direct, and keyed files. You should use this function when an application needs to ensure that modifications are made to two files. For example, getting a current total from one file and updating a running total in another file requires that the current current total be wr written itten to zero zero and that the running running total total be written to the the sum of the two total totals. s. You can also use the HOLD function to control the modification of more than two files by using a status file for one of the files. When an application requests a write with a HOLD, the IBM 4690 Operating System actually queues the request in the store controller memory and informs the requesting application that the write is complete. When the same application requests a second write with a HOLD, the system saves both of the write requests reques ts and then performs performs both writes. writes. If a PLD prevents the writes writes from compl completing, eting, it comple completes tes the writes when the power is restored. Because the writes with HOLD are queued in the store controller memory, you can use the HOLD function in concurrently concurrently executing executing applications applications that are shar sharing ing files. Before upd updating ating a record, your applicatio application n must do do a read read with with autolock autolock for the the record. record. The wr write ite with HOLD mu must st AUTOUNLOCK AUTOUNLOCK the record. record. When the first write with HOLD is issued, it is queued and that means that the AUTOUNLOCK is not executed until the write is executed. executed. Your application application should should follow the locking locking guidel guidelines ines in “Sharing “Sharing Files” on

 

2-27

Chapte Cha pterr 2. Managi Managing ng Files Files

 

 

page 2-21 to prevent prevent deadlocks. deadlocks. It shou should ld also minimize the time that re records cords are be being ing loc locked ked when when using the HOLD function. WRITE HOLD provides PLD protection only if both files being written reside on the same store controller. The WRITE HOLD function ensures that either both or neither of the disk requests occurs if a PLD occurs. However, if other types of failures prevent the disk requests from occurring, the second WRITE HOLD indicates indica tes the failure. failure. Because Because the return code code cannot distinguish, distinguish, the failure failure indicated indicated on the secon second d WRITE HOLD might might be for the first or second disk disk operati operation. on. You should look look at the error results results as appropriate for either disk request.

Design Considerations for File Performance When your application applications s use files, the functions they perform perform are synchr synchronous onous oper operations. ations. Your applications should begin any necessary I/O functions, which are asynchronous, before they begin file functions. functio ns. For example, example, in the terminal, terminal, printing printing should should be started started first. In your terminal applications, any file function that issues a WRITE statement forces the data to be written to the media. In store controller controller application applications, s, all file functions functions force the data to be written written to the media. The one exception is a sequential file opened in LOCKED mode. In your store controller applications, use as few file functions as possible that cause store controller files to be locked. This is recommended recommended because because as the number of terminals for each store con controller troller increase increases, s, the number of locks locks on files increases. increases. Each terminal terminal program program might have to wait for the LOCK request request to be granted. In general, general, your applications applications should should minimize minimize the number of file requests requests they make. make. For examp example, le, if you need two data fields from the same record, read the file once and save the second field until you need it.

 K eyed Keye d File Files s Two alternate hashing algorithms are provided to improve performance in large files having more than 40K records recor ds and a randomizing randomizing divisor greater greater than 6000, and where ASCII keys are required. required. See “Hashi “Hashing ng Algorithms” Algori thms” on page 6-10 for more more information information about these algo algorithms. rithms. You can improve the performance of keyed files in your system by following some basic guidelines:

 Ensure that all of your keyed files contain an adequate amount of free space. In keyed files files of more than 1000 1000 records, records, at leas leastt 25% of the spa space ce should b be e free. If the record record length is greater greater than than 169, then only only one or two re records cords will will fit into one sector sector or 508 by bytes. tes. Allow up to 50% of free space space for these these files to re reduce duce chaining chaining of these these files. When you c create reate a keyed keyed file, the Keyed File Utility allows you to check the amount of free space by giving you the packing factor. The packing factor gives you the percentage of records occupied.

 Eliminate long chains in a keyed file. The system checks checks chain lengths lengths against against the chainin chaining g threshold. threshold. When chai chains ns greater than than the threshold thresh old are reached, reached, the system system logs a message in the system system error log. Use the Keyed Fil File e Utility to determine determine and to reduce the chain chain lengths. Reduce chain chain lengths by all allocating ocating mo more re space, changing changi ng the hashing algorithm, algorithm, or changing the randomizin randomizing g divisor. See “Hashi “Hashing ng Algorith Algorithms” ms” on page 6-10 for more information. information.

2-28

4690 Store System: Programming Guide

 

 

 When the system is writing or reading a record from a keyed file, it processes the record to find out to which block block in the file the record belongs. belongs. The system system should need to acce access ss the file only once to find the correct correct record. record. If many overflow overflow chains are present, present, the system system might need mor more e than one read from the file. By ensuring ensuring that the records records are evenly distribut distributed ed throughout throughout a keyed file, you can reduce the number of disk accesses needed to get to a particular record.

 Keyed file performance improves when the file is placed on the disk in 10 or fewer contiguous extensions. extens ions. Use the CHKDSK command command to determine determine the number of contiguous contiguous extension extensions s of a file. Refer to the IBM 4690 Store System: User’s Guide  for   for information on the CHKDSK command.

 

2-29

Chapte Cha pterr 2. Managi Managing ng Files Files

 

 

2-30

4690 Store System: Programming Guide

 

 

|

Chapte Cha pterr 3. Progra Programmi mming ng Termi Terminal nal I/O Devi Devices ces

2x20 Display 2x20 Displays s  . . . . . . . . . . . . . . . Characteristics   . . . . . . . . . . . . . | | Functions Your Application Performs Accessing the Display | . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

| |

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

|

| | | | | | | | | | | | | |

. . . . . . . . . Clearing the Display Writing Characters to the Display . . Current Character Location . . . . Character Charac ter Wrapping Wrapping   . . . . . . . . 2x20 Display Character Sets . . . Determining Display information . . . Reading from the Display . . . . . . Programming Hints for 2x20 Displays Example   . . . . . . . . . . . . . . . . Shoppe Sho pperr Display Display   . . . . . . . . . . . . . Characteristics   . . . . . . . . . . . . . Functions Your Application Performs Accessing the Shopper Display . . . Clearing the Shopper Display . . . .

3-6 3-6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3-6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3-7

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 3-10  3-11  3-11  3-11  3-11 3-11 3-12 3-13  3-13  3-14  3-15  3-16  3-16  3-16

|

Special Considerations for a Feature A Video Driver . . . . . . . . . . . . . . . . . . . . . . . . Writing to the Video Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Current Character Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Current Character Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Character Location Wrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Video Display Character Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing Characters Without Changing Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing Attributes Without Changing Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining Video Display Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reading from the Video Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reading Attributes from the Video Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running a 2x20 Display Application on the Video Display . . . . . . . . . . . . . . . . . . . . . . . Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Feature A Video Driver Command Stacking to Improve Performance . . . . . . . . . . . .

 3-16  3-17  3-17  3-17  3-18  3-18  3-18  3-18  3-18  3-19  3-19  3-19 3-20  3-24

| |

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

| | | | | | | | | | | | | | | | | | | | | | | | |

Writing Characters to the Shopper Display Shopper Display Character Set . . . . Setting the Guidance Lights on the Display Reading from the Display . . . . . . . . . Determining Shopper Display Status . . . Example   . . . . . . . . . . . . . . . . . . . Video Vide o Display Display   . . . . . . . . . . . . . . . . . . Characteristics   . . . . . . . . . . . . . . . . Feature A video driver . . . . . . . . . . VGA Video Driver . . . . . . . . . . . . Functions Your Application Performs . . . Accessing the Video Display . . . . . . . . Clearing the Video Display . . . . . . . . . Changing the Video Display Format . . .

 3-7  3-7 .  3-7 3-7 .  3-7 .  3-8 .  3-8 .  3-8 3-9 3-10 3-10  3-10  3-10  3-10

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Restrictions Using Command Stacking . . . . . . . Example Program Using Command Stacking . . . | Example Program Source Code . . . . . . . . . . . Cash Drawer Driver . . . . . . . . . . . . . . . . . . . . .

 3-25  3-25 . . . . . . . . . . . . . . . . . . . . . . . . .  3-26 . . . . . . . . . . . . . . . . . . . . . . . . .  3-27

© Copyright

3-1

IBM Corp. 1994, 1996

 

 

| | | | | | | | | | | | | | | | | | | | | |

Characteristics   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Functions Your Application Performs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing the Cash Drawer or Alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling a Cash Drawer or Alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Obtaining Cash Drawer or Alarm Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Coin Dispenser Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Characteristics   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing the Coin Dispenser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dispen Dis pensing sing Coins Coins   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I/O Proces Processor sor   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Characteristics   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input Devices on Your System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I/O Processor Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input Sequence Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Definitions and Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input State Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Label Format Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modulo Check Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Functions Your Application Performs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading the Input Sequence Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing the I/O Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparing to Receive Data from the I/O Processor . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Operator Input Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Waiting for Received Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiv Rec eiving ing Dat Data a  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Allowing and Disallowing Operator Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining Status of the I/O Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preloading Input Sequence Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Non-Full-Sc Non-F ull-Screen reen Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional I/O Processor Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Da Data ta Ed Editi iting ng   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customization of Message Display ( Enhanced Full-Screen mode only ) . . . . . . . . . . . . Large Input Sequences (Enhanced Full-Screen mode only) . . . . . . . . . . . . . . . . . . . . Magnetic Stripe Reader Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Characteristics of the Single-Track Magnetic Stripe Reader . . . . . . . . . . . . . . . . . . . . . . Characteristics of the Dual-Track Magnetic Stripe Reader . . . . . . . . . . . . . . . . . . . . . . Characteristics of the Three-Track Magnetic Stripe Reader . . . . . . . . . . . . . . . . . . . . . . Data Formats and Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Restrictions of Single- and Multi-Track MSRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Functions Your Application Performs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing the MSR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparing to Receive Data from the MSR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Waiting for Received Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiv Rec eiving ing Data   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Characteristics Common to all MSRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disallowing MSR Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining Status of the MSR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integer Format for Single-Track MSR Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integer Format for Dual-Track MSR Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integer Format for Three-Track MSR Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Single-Track MSR Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dual-Track MSR Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-27  3-27  3-27  3-28  3-28 3-28  3-29 3-29  3-29 3-30 3-30 3-31 3-31  3-32  3-32  3-32  3-33  3-33  3-37  3-37  3-39  3-39  3-40  3-40  3-40  3-40 3-41  3-41  3-42  3-42 3-44  3-45 3-45  3-46  3-48  3-48  3-48  3-49  3-49  3-49  3-52  3-52  3-52  3-52  3-53 3-53  3-53  3-53  3-54  3-54  3-54  3-54  3-55  3-56

3-2

4690 Store System: Programming Guide

 

 

Three-Track MSR Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printer Driver Model 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Characteristics   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Functions Your Application Performs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing the Printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparing a Line To Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printing a Line of Text at the Printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling the Document Insert Station . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining the Printer Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printin Prin ting g Checks Checks   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Formatting the Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Charact Char acter er Sets Sets   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Problem Proble m Determination Determination   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Programming Progr amming Consideration Considerations s  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logo Log o Printin Printing g  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining When Printing is Complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance Perfor mance Consideratio Considerations ns   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printer Driver Model 3 or 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Characteristics   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compatibility with Applications Written for the Model 1 and 2 Printers . . . . . . . . . . . . . . . . Functions Your Application Performs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing the Printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparing a Line to Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printing a Line of Text at the Printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Emphas Emp hasize ized d Printin Printing g  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Emphasized Printing Programming Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fontt Specifi Fon Specificat cation ion   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Font Change Programming Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling the Document Insert Station . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Top or Front Loaded Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manual or Automatic Document Insertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing and Replacing a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Journal Buffering When Printing on Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . Reinserting Documents for Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Eject Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Positioning the Print Head . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reversible Document Station Motor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Station Character Line Lengths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining the Printer Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preventing Unnecessary Reprints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receipt Paper Cutter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receipt Paper Cutter Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printer Home Sensors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Left Home Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printin Prin ting g Checks Checks   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logo Log o Printin Printing g  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining When Printing is Complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance Perfor mance Consideratio Considerations ns   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Magnetic Ink Character Recognition Support for Printers Model 3 and 4 . . . . . . . . . . . . . . . . MICR Data Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the MICR Reader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining If a MICR Is Installed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 3-58  3-60 3-60  3-60  3-61  3-61  3-61  3-61  3-62 3-62  3-63 3-64 3-64 3-64 3-64 3-65  3-65 3-65 3-66  3-67 3-67  3-68  3-69  3-69  3-69  3-70 3-70  3-70 3-71  3-71  3-72  3-72  3-72  3-73  3-74  3-75  3-75  3-75  3-76  3-76  3-76  3-76  3-76  3-77  3-77  3-77 3-77 3-78  3-78 3-78  3-79  3-80  3-80  3-80

 

Chapter Chapt er 3. Programm Programming ing Term Terminal inal I/O Devic Devices es

3-3

 

 

| | | | | | | |

Reading from the MICR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding MICR Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding MICR Parsing Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fiscal Printer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Application Programming for the 4690 OS Fiscal System . . . . . . . . . . . . . . . . . . . . . . . Error Handling and Recovery Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Read Rea d Com Command mands s  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GETLONG GET LONG Fun Functio ction n  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PUTLON PUT LONG G Functio Function n  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reading from the Model 3 Fiscal Printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the FISREAD call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scale Sca le Driv Driver er   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Characteristics   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing the Scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiv Rec eiving ing Data   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Serial I/O Communications Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Characteristics   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Functions Your Application Performs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing the Serial I/O Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Receiving Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparing to Receive Data from the Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Waiting for Received Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Receiving Data from the Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining Serial I/O Port Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparing to Transmit Data to the Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transmitting Data to the Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending a Break to the Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Simultaneous Receive and Transmit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tone Tone Dr Driv iver er   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Characteristics   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Functions Your Application Performs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing the Tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating a Tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Totals Retention Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Characteristics   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing the Totals Retention Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Totals Retention in Direct Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reading Data in Direct Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing Data in Direct Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Totals Retention in Sequential Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Address in Sequential Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reading Data in Sequential Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing Data in Sequential Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 3-80  3-81  3-81  3-82  3-82  3-82 3-83 3-83 3-84  3-85  3-86 3-87 3-87  3-87 3-87 3-87  3-89 3-89  3-89  3-90  3-90  3-91  3-91  3-91  3-92  3-92  3-92  3-93  3-93 3-93 3-96 3-96  3-96  3-96  3-96 3-97  3-98 3-98  3-98  3-98  3-99  3-99  3-99  3-99  3-99  3-99 3-100

3-4

4690 Store System: Programming Guide

 

 

This chapter chapter shows how to program program termin terminal al I/O devices. devices. It provides provides general info informatio rmation n as well as | specifi specific c informat information ion about each device. device. Each devic device e has a section containing containing information information on: on: |

| | | | |

   Device characterist characteristics ics    How to access the device    How to end access to the device    Specific programming information about the device    A code example for the device to perform a basic task, such as printing lines

4690 controls controls each device device through a device device driver. Various Various input and output statements statements ar are e used to | communi communicate cate with each dev device ice driver. driver. This chapter chapter uses IBM 4680 BASIC BASIC to explain the method methods s for | communi communicating cating with each devi device ce driver. For syntax and further further informat information ion on these statemen statements, ts, refer to | the IBM 4680 BASIC Language Reference .

|

Terminal Termin al I/O devices can also also be programmed programmed using the C language. language. For syntax and and more informa information tion refer to the CAPITPGP.DOC file included with AISPO product number, 5764-081, Version 1.1 or later, the | IBM C Programming Interface for 4690 Terminals. |

|

 

Chapter Chapt er 3. Programm Programming ing Term Terminal inal I/O Devic Devices es

3-5

 

 

|

2x20 Displa lays ys  2 x20 Disp

|

This section describes all the displays that fall into the 2x20 (2 rows x 20 columns) category and provides guidelines for using these displays.

|

The following are 2x20 displays:

|

| | | | |

  Alphanumeric    Operator    40-character Liquid Crystal Display (LCD)    40-character Vacuum Fluorescent Display II (VFD II)    Two-sided VFD II

|

Two different different 4690 drivers drivers provide provide 2x20 display display support support for a terminal. The alpha alphanumeric numeric display display is handled by the alphanumeric display driver and all of the other 2x20 displays are handled by the operator display driver.

|

 Characteristics Characteristics

| |

|

   Up to three of these displays can be attached to a terminal.

|

To support three 2x20 displays, you must configure one as ANDISPLAY, the second as ANDISPLAY2,

| |

and the third as ANDISPLAY3 in the Terminal Device Group for your terminal. There are are some restrictio restrictions ns when con configurin figuring g these displays. displays. Refer to the 4690 Store System:  Planning, Installation, and Configuration Guide   for for the valid combinations of 2x20 displays that can be configured.

| | |

   2x20 display format (2 rows by 20 columns)

|

   Display character sets representing different code pages

|

There are some differences in the character sets for each of the 2x20 displays.

|

Refer to the IBM 4680 BASIC Language Reference  display character sets.

|

. for a desc descrip ription tion o off the avail availabl able e

|

The alphanumeric alphanumeric display display is unique because because you can can customize its display display char character acter set. See “Customizing “Custo mizing the Alphanumeric Alphanumeric Display Display Character Character Set” on page 3-7 for more information. information.

| |

The other displays displays have a fixed set set of characters characters contain contained ed within the electronics electronics of the dis display. play. The characters that can be displayed are determined by the country selected during installation.

|

|

Functions Your Application Performs

|

Your application can perform the following functions with the 2x20 displays:

         

    

|

Select which display to use. Write characters to any character location. Read characters from any character location. Clear the display. Determine whether the driver handling your 2x20 display is the alphanumeric or operator display driver.

|

If the 2x20 display is configured as the system display in the terminal device group for your terminal:

| | | | |

| | |

   Your application shares the display with the I/O Processor. The I/O processor uses the display to display keyboard data that is specified as display-as-keyed and to display operator operator prompts. prompts. Your input sequence sequence table specifies specifies the starting cha character racter loc location ation and

3-6

4690 Store System: Programming Guide

 

 

| | |

length of these these display fields. fields. Your application application should should be designed designed to coordinate coordinate its display data with your input sequence table.

   Other system functions use the 2x20 display but with a separate display buffer

If the 2x20 display is not configured as the system display, then the only system use of the 2x20 display is | to display progress indicators during IPL. |

|

Accessing the Display

|

Use the OPEN statement to gain access to the display.

| |

Use the CLOSE statement statement to end your application application’s ’s use of the display. display. The CLOSE statement statement does not clear the display.

|

Clearing the Display

Use the CLEARS statement statement to clear the dis display. play. The CLEARS statement statement writes writes a space chara character cter to | each character location and sets the current character location to (1,1).

|

|

Writing Characters to the Display

|

Use the WRITE statement to display characters on the display.

|

Before writing data to the display, you can set the current character location.

After the WRITE statement completes, the current character location is set to the next character location | after the last character location that was written to.

|

|

char arac acte terr lo loc catio ation n is de defi fine ned d as a row an and d co colu lumn mn co coor ordi dina nate te Current Cur rent C Char haracte acterr Loc Locatio ation: n: A ch

|

(row,column).

|

The current character location is the (row,column) of the next character to be written or read.

|

You use the LOCATE statement to change the current character location.

|

Valid row values values are 1 and and 2 (top to bottom). bottom). Valid column column values values are from 1 to 20 (Left (Left to right). right).

|

Charact Cha racter er Wra Wrappi pping: ng: If the number of characters you write is greater than the number of character

locations remaining locations remaining on the current current row, the charac characters ters are written written on the next row. If the current row row is | the last row of the display, display, then the characters characters are wr written itten to row 1. The chara characters cters will co continue ntinue to wrap | until all of the characters are written. |

|

2x20 Dis Displa play y Cha Charact racter er Set Sets: s: Th The e di disp spla lay y char charac acte terr set set dete determ rmin ines es wh what at is disp displa laye yed d on the the

display for each each character character written by your application. application. There are some diffe differences rences in the chara character cter sets | for each of the 2x20 displays.

|

Refer to the IBM 4680 BASIC Language Reference   for for a description of the available display character | sets.

|

| |

Customizing the Alphanumer Customizing Alphanumeric ic Display Character Character Set: Set: You can customize your alphanumeric display character set using the Alphanumeric Display Character Set option in the configuration for your terminal.

|

Each character location in the character set contains a 5 x 12 dot matrix, which is used to form the

 

Chapter Chapt er 3. Programm Programming ing Term Terminal inal I/O Devic Devices es

3-7

 

 

| | | | |

character. You can redefine character. redefine any charact character er location location except except ‘blank’. ‘blank’. Most of the def default ault characte characters rs are defined define d using 5 x 9 dots of the 5 x 12 matrix. matrix. You can define define no more than than 36 dots on the mat matrix rix for any given character character.. The display display has a blank space between between chara character cter locations locations and betw between een the two rows. You should consider these blank spaces if you use multiple character locations to produce a graphic display.

|

Refer to the 4690 the 4690 Store System: Planning, Installation and Configuration Guide  for   for more information on customizing the alphanumeric display character set.

|

Determining Display information

|

You use the GETLONG function to determine the following information about the 2x20 display:

|

|

   Current character location (row and column)

|

   Whether the driver handling your 2x20 display is the alphanumeric or the operator display

|

Reading from the Display

|

Use the READ statement to read the characters that have been written to your application's display buffer.

|

Before reading reading from the display, display, you can set set the current character character location. location. This is the row and colum column n

| |

where you want you start reading re from fromvariable display. display. Seeon “Current “Cur Cha Character racter Locati Location” on” on page pa ge mines 3-7 forthe more information. inform ation. Thetolength ofading the data vathe riable specified specified therent READ FORM # statement state ment deter determines number of character character locations locations read read from the displ display. ay. If the length requested requested exce exceeds eds the remai remaining ning character locations on a row, wrapping is done as described in “Character “Character Wrapping” on page 3-7.

| |

|

After the READ FORM # is complete, the current character location is set to the next character location after the last character that was read.

|

Programming Hints for 2x20 Displays

|

| | | |

An application written for a 2x20 display will run on any other display in the 2x20 family with the following considerations:

   Differences in display character sets Refer to the IBM 4680 BASIC Language Reference  for   for a description of each of the character sets.

3-8

4690 Store System: Programming Guide

 

 

|

 Example Example

This example example contains contains code for operating operating a 2x20 display. display. The progr program am writes text to each lin line e of the | display and clears the display.

|

|

%ENVIRON T

|

! Declare a two-byte integer.

| | |

INTEGER*2 DISPLAY ! 20-character message for line 1. LINE.ONE$ = "ROW ONE SAMPLE "

| | |

! Message for line two. LINE.TWO$ = "ROW TWO SAMPLE ON ERROR GOTO ERR.HNDLR

| | |

! Open the display. DISPLAY = 1 OPEN "ANDISPLAY:" AS DISPLAY

| |

! Clear the display. CLEARS DISPLAY

| |

! Write a greeting. WRITE #DISPLAY; " 2x20 DISPLAY SAMPLE"

| |

! Pause. WAIT;2000

| |

! Clear the greeting. CLEARS DISPLAY

| |

! Display the string. WRITE FORM "C20";#DISPLAY; LINE.ONE$

| |

! Pause. WAIT;2000

| | |

! Set character location (2,1) and display the second line LOCATE #DISPLAY ;2,1 WRITE #DISPLAY; LINE.TWO$

| |

! Pause. WAIT;2000

| | | | |

! Clear the display then write sample ending message CLEARS DISPLAY WRITE #DISPLAY; "END OF 2x20 SAMPLE" CLOSE DISPLAY STOP

|

ERR.HNDLR:

| | | | |

!ONPrevent recursion. ERROR GOTO END.PROG ! Determine error type ! and perform appropriate ! recovery and resume steps.

"

 

Chapter Chapt er 3. Programm Programming ing Term Terminal inal I/O Devic Devices es

3-9

 

 

| | |

END.PROG: STOP END

|

Shoppe S Displa play y   hopperr Dis

|

This section describes characteristics of the shopper display and provides guidelines for using this display.

|

 Characteristics Characteristics

|

The shopper display has the following characteristics:

| | |

   You can attach one of these displays (SDISPLAY:) to a terminal    1x8 display format with six guidance lights    Fixed display character set

|

Functions Your Application Performs

|

Your application can perform the following functions with the shopper display:

|

   Write characters to the display and display guidance lights.

| |

Clear the display.     Read data from the display.    Get guidance light information from the display

|

|

Because the shopper display cannot be configured as the system display in the terminal device group for your terminal, terminal, your applicatio application n has exclusive exclusive use of the shopper shopper display. The only syst system em use of the shopper display is to display IPL progress indicators during IPL.

|

Accessing the Shopper Display

|

Use the OPEN statement to gain access to the shopper display device driver.

| |

Use the CLOSE statement statement to end your applicatio application’s n’s use of the shoppe shopperr display dr driver. iver. The CLOSE statement does not clear the characters from the shopper display.

|

Clearing the Shopper Display

| |

|

Use the CLEARS statement statement to clear th the e display. The CLEARS statement statement writes writes a space chara character cter to each of the character locations.

|

Writing Characters to the Shopper Display

|

| | | |

The WRITE statement statement allows allows you to write to all or part of the shopper shopper display and guidance guidance ligh lights. ts. The specified number of characters are written right-adjusted to the display, padded on the left with blanks. Guidance lights data, established by the most recently issued PUTLONG statement, is simultaneously displayed.

3-10

4690 Store System: Programming Guide

 

 

Shoppe Sho pperr Disp Display lay C Chara haracter cter S Set: et: Th The e disp displa lay y char charac acte terr set set dete determ rmin ines es wh what at is di disp spla laye yed d on the the display for each each character character written by your application. application. The shoppe shopperr display chara character cter set includ includes es the | numerals and a limited number of alphabetic and special characters. |

|

Each character character location location contains seven seven bar-segments bar-segments used to form the charac character. ter. Some locatio locations ns also | contain a comma comma or decimal point segments. segments. The barbar-segmen segmentt pattern for each characte characterr is defined | within the shopper shopper display display electroni electronics. cs. You cannot cannot modify this c charact haracter er set.

|

|

Refer to the IBM 4680 BASIC Language Reference   for for the definition of the shopper display character set.

|

Setting the Guidance Lights on the Display

Use the PUTLONG statement statement to set up the guidance guidance lights on the sho shopper pper disp display. lay. The guidan guidance ce lights arranged in two columns columns of three lights each. each. The six low-o low-order rder bits of the byte control control the guidan guidance ce | are arranged | lights. Bit 5 controls the upper-le upper-left ft light, bit 4 controls controls the middle-left middle-left light, bit 3 controls controls the lower-left lower-left light, | bit 2 controls the upper-right light, and so on. |

|

Reading from the Display

|

Use the READ statement to read the characters that are specified in your application display buffer.

|

Determining Shopper Display Status

|

Use the GETLONG statement to get the current status of the guidance lights from the shopper display.

|

 Example Example

|

This example contains code operating the shopper display.

| | | | | | | | | | | | | | | | | | | | | | | | | |

%ENVIRON T INTEGER*4 LIGHTS DISPLAY1=1 DISPLAY2=2 ON ERROR GOTO ENDPROG ! Open video display. OPEN "VDISPLAY:" AS DISPLAY2 CLEARS DISPLAY2 WRITE FORM "C20"; #DISPLAY2; "video is open" WAIT;500 ! Open shopper display. OPEN "SDISPLAY:" AS DISPLAY1 WRITE FORM "C20"; #DISPLAY2; "shopper is open" WAIT;500 ! Clear shopper display. CLEARS DISPLAY1 WAIT;500 ! Set pointer data. LIGHTS = 00000001h PUTLONG DISPLAY1,LIGHTS ! Write data. WRITE FORM "C6"; #DISPLAY1;"111.11" WAIT;500 ! Set pointer data. LIGHTS = 00000002h PUTLONG DISPLAY1,LIGHTS

 

3-11

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

| | | | | | | |

! write data WRITE FORM "C10"; #DISPLAY1;"22,222,222" WAIT;500 ! set pointer data LIGHTS = 00000004h PUTLONG DISPLAY1,LIGHTS ! Write data. WRITE WRI TE FORM FORM C6"; C6"; #DISPL #DISPLAY1 AY1;"3 ;"333. 33.33" 33"

| | | | | | | | | | | | | | |

WAIT;500 ! Set pointer data. LIGHTS = 00000008h PUTLONG DISPLAY1,LIGHTS ! Write data. WRITE FORM "C6"; #DISPLAY1;"444.44" WAIT;500 ! Set pointer data. LIGHTS = 00000010h PUTLONG DISPLAY1,LIGHTS ! Write data. WRITE FORM "C8"; #DISPLAY1;"5,555,55" WAIT;500 ! Set pointer data. LIGHTS = 00000020h

| | | | | | | | | | | | |

PUTLONG ! Write DISPLAY1,LIGHTS data. WRITE FORM "C12"; #DISPLAY1;"66.666.66" ! Clear displays. CLEARS DISPLAY1 CLEARS DISPLAY2 WRITE FORM "C30"; #DISPLAY2;" SHOPPER CLEARED - END TEST " STOP ENDPROG: ! Display error messages and perform appropriate recovery ! and resume steps. STOP END

|

 Video Vide o Disp Displa lay y

|

This section describes the video display and provides guidelines for using this display.

|

Two different 4690 drivers provide video display support for the terminals.

|

When the video display is connected using a Feature A expansion card (4683 terminal only), the Feature A video driver driver is used. used. When the video video display display is conne connected cted to the vid video eo port or to a VGA ((Video Video Graphics Array) adapter, the VGA video driver is used.

| |

|

Although the application programming interface (API) to these drivers is the same, there are some restrictions restr ictions when when using the Feature Feature A attribute with the VGA vid video eo driver driver.. There ar are e extensio extensions ns to the API for the VGA video driver driver that over overcome come these restrict restrictions ions as well as prov providing iding addit additional ional function. function. See “VGA Video Video Driver” Driver” on page 3-14 for more more information. information.

|

Note: These extensions are available with 4690 OS maintenance level 9620 or higher.

| | |

3-12

4690 Store System: Programming Guide

 

 

Use ADXSERVE ADXSERVE to determine determine whether whether your video video displ display ay is a Feature Feature A or VGA. See “ADXSERVE “ADXSERVE | (Reque (Requesting sting an an Appli Application cation Servic Service)” e)” on page 15-17 for more more information. information. See the “Example” “Example” on an n example of how how to use this applicatio application n servic service. e. | page 3-20 for a

|

|

 Characteristics Characteristics

|

The video display has the following characteristics for each of the video display drivers:

|

Feature A video driver

| | | |

   You can attach up to two video displays To support two displays you must configure one of the video displays as VDISPLAY and the other as VDISPLAY2 in the Terminal Device Group for your terminal.

   Programmable video display format

|

The video display can have one of four video display formats.

|

You configure the default video display format in the Terminal Device Group for your terminal.

|

The following table shows the 4 video display formats that are available:

|

Table Tab le 3-1 3-1.. Featur Feature e A Video Video Displa Display y Form Format at Types  Types 

| |

Video Display Format

Number of Rows

Number of Columns

  Restrictions

|

25 x 80

25

80

12 and 9 inch displays only

|

16 x 60

16

60

12 and 9 inch displays only

|

12 x 40

12

40

None

|

6 x 20

6

20

5 inch display only

|

   Video character sets representing different code pages

|

Refer to the IBM 4680 BASIC Language Reference  for   for a description of the available Feature A video display character sets.

|

   A cursor in the form of a blinking line can appear at the bottom of any character location on the video

|

|

display.

 

3-13

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

|

   You can select any of eight attribute specifications for every character location on the display:

|

 –  –  –  –  –  –

| |

  – Blue   – Green

|

Note: If reverse video is selected the foreground color (the character) is black and the color and intensify intensi fy bits apply to the background background color. color. If revers reverse e video is not selected selected then the background background color is black, and the color and intensify bits apply to the foreground color.

| | | | |

| | | |

| |

Reverse Video Blink Blank Inte ten nsify Underline Red

Refer to the IBM 4680 BASIC Language Reference  the combinations of color bits and the intensify bit.

. for a list list of the colo colors rs av availa ailable ble using using

VGA Video Driver    You can attach only one video display

|

You configure this video display as either VDISPLAY or VDISPLAY2 in the Terminal Device Group for your terminal.

|

Note: In a controller/terminal the video display is VDISPLAY.

|

|

   Programmable video display format

|

The video can have one of four video display formats.

|

You configure the default video display format in the Terminal Device Group for your terminal.

|

The following table shows the 4 video display formats that are available:

|

Ta Tabl ble e 33-2. 2. Vi Vide deo o D Dis ispl play ay Form Format at Ty Type pes  s 

| |

Video Display Format

Number of Rows

Number of Columns

  Restrictions

|

25 x 80

25

80

None

|

16 x 60

16

60

This is a 16 row x 60 column character window centered on a 16 row row x 80 c column olumn charact character er scre screen. en. Chara Character cter positions 1-10 and 61-80 are blank and are not accessible access ible by your your appl applicatio ication. n. Access Accessing ing char character acter location locati on (1,1) iis s actual actually ly chara character cter pos position ition (1 (11,1). 1,1). VGA supports only 40 or 80 columns while in character mode.

| | | | | | | |

16 x 80

16

80

This video display format is available only through the API. It cannot cannot be config configured ured as th the e defaul defaultt video di display splay format in the Terminal Device Group for your terminal.

|

12 x 40

12

40

None

|

   Video character sets representing different code pages

|

There are differences between the VGA and Feature A video character sets.

|

Refer to the IBM 4680 BASIC Language Reference  for   for a description of the available video display

|

character sets.

| |

   A cursor in the form of a blinking line can appear at the bottom of any character location on the video display.

3-14

4690 Store System: Programming Guide

 

 

Note: See restrictions restrictions for the 16x60 16x60 video display display format in Table Table 3-2.

| | | | |

   You can use the Feature A attribute or with VGA video extensions you can use the VGA attribute Feature Featur e A At Attri tribut bute: e: The Feature A attribute is the same as described in “Feature A video driver” on page 3-13 w with ith the following following restriction restrictions: s:

   No underline support

|

The underline bit is ignored. |    No background intensified colors supported The intensify bit is ignored when the reverse video bit is set to 1

| |

VGA att attrib ribut ute: e: If using the VGA attribute, the following attribute specifications are provided:

|

   Red, green, blue and intensify for foreground color

|

   Red, green, and blue for background color

|

   Underline for monochrome displays

|

   Choice of blinking or intensify for background color

Refer to the IBM 4680 BASIC Language Reference  for   for a list of the colors and underlining available using | the combinations of color bits and the intensify bit.

|

|

Functions Your Application Performs

|

Your application can perform the following functions with the video display:

| | | | | | | | | | | | | | | | | | | | | | | | |

                 

        

Control the video display format. Determine the video display format. Determine whether the attached video display is monochrome or color. Write characters and attributes to any character location. Write characters to any character location without changing the attributes. Write attributes to any character location without changing the characters. Read characters from any character location. Read attributes from any character location. Control the type of attribute for each character location (VGA extension)

                   

         

Control the attribute for each character location. Determine the type of attribute for the current character attribute (VGA extension) Determine the current character attribute Control whether underlining is enabled on monochrome displays (VGA extension) Determine whether underlining is enabled on monochrome displays (VGA extension) Control whether blinking or background intensified colors are enabled (VGA extension) Determine whether blinking or background intensified colors are enabled (VGA extension) Control current character location Control whether the cursor is visible at a current character location Clear the video display.

If the video display is configured as the system display in the terminal device group for your terminal:

   Your application shares its video display buffer with the I/O Processor The I/O processor uses your applications video display buffer to display keyboard data that is specified as display-as-k display-as-keyed eyed and to display oper operator ator prompt prompts. s. Your input sequence sequence table specifies specifies the startin starting g character chara cter location location and length of these these display fields. fields. Your application application should should be design designed ed to coordinate its video display data with your input sequence table.

 

3-15

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

|

   Other system functions use the video display but with a separate video display buffer

|

If the video display is not configured as the system display, then the only system use of the video display is to display IPL progress indicators during IPL.

|

Accessing the Video Display

|

| | | |

Use the OPEN statement statement to gain access access to the video display de device vice driv driver. er. OPEN sets the curr current ent character location to row 1, column 1 (1,1). You use the GETLONG function to determine the default video display format and whether the attached video display is color or monochrome.

|

Use the CLOSE CLOSE statement statement to end your applicati application’s on’s use of the v video ideo disp display lay drive driver. r. The CLOSE statement does not clear the video display.

|

Clearing the Video Display

|

|

Use the CLEARS statement statement to clear th the e video displa display. y. The CLEARS statement statement writes writes a space chara character cter with the default attribute (Feature A 0xE0) to each character location and sets the current character location to (1,1).

|

Changing the Video Display Format

| |

| | | | | | | | | | |

The video display display format format sets the size and number number of character character locations locations on the video displa display. y. For example, a 12 x 40 video display format defines a video display that has 12 horizontal lines (rows) with 40 characters (columns) in each line. Use byte MM in the PUTLONG statement statement to chang change e the video displ display ay format. The Featur Feature e A video driver uses three bits and the VGA video driver uses four bits to specify a change in the video display format. If none of the video display format bits are set in the PUTLONG statement, then the video display format does not change. change. If you set one of the b bits its to 1, the video d display isplay ch changes anges to the v video ideo disp display lay format format specified by that bit. If more than one of the video display format bits is set to 1, an error is returned to your application and the video display display format does does not change. If you select the current current video dis display play forma format, t, success is re returned turned to your application, but the video display format does not change.

|

The video display is cleared and the current character location is set to (1,1) when the video display format is changed.

|

Speciall Consi Specia Consideratio derations ns for a Fea Feature ture A Vid Video eo Driv Driver: er: If yo you u se sele lect ct a vid ideo eo dis display play for format mat

|

that is not valid for the video display type that is configured, an error is returned to your application and the video display format is not changed.

|

| | | | | | |

If you select a video display format that is larger than the default video display format, the driver must allocate alloca te additional additional memory. If memory is not available available to satisfy thi this s request request,, an error is retur returned ned to your application applic ation and the video video display format format is not changed. changed. For this reason, reason, it is recommend recommended ed that you configure the default video display format for the largest video display format that your application uses. This prevents the need to allocate additional memory when your application changes the video display format.

3-16

4690 Store System: Programming Guide

 

 

|

Writing to the Video Display

Use the WRITE statement statement to display display characters characters and/or attribute attributes s on the video display. display. The default mod mode e of writing characters to the video display automatically changes the attribute associated with each | character written to the current character attribute.

|

|

|

Use byte CC in the PUTLONG statement to change the way characters are written to the video display.

| |

To write characters without having the attribute updated see “Writing Characters Without Changing Attributes” on page Attributes” page 3-18. To write attribu attributes tes without without having having the character character updated see “Wr “Writing iting Attr Attributes ibutes Withoutt Changing Changing Characters” Characters” on page 3-18. | Withou Before writing data to the video display, you can set the current character location and the current character cter attribute. attribute. After the WRITE WRITE statement is comp complete, lete, the current current chara character cter loca location tion is set to the first | chara | character location after the last character location written.

|

|

Current Cur rent C Char haracte acterr Attr Attribu ibute: te: Th The e defa defaul ultt curr curren entt char charac acte terr attr attrib ibut ute e is the the Fe Feat atur ure e A attr attrib ibut ute e

|

0xE0.

You can change change the current current character character attribute attribute by using byte AA of the PUTLONG statement. statement. If using | video extensions, you can also use byte VV to select that byte AA contains a VGA attribute, whether | blinking or background intensified colors are enabled and whether underlining is enabled for monochrome |

|

video displays.

This attribute is used by the video display driver for all default mode writes performed by your application | until your application changes it with another PUTLONG statement. |

If the current character attribute is a Feature A attribute, then it does not effect the attribute of characters | written by the I/O processor. |

The I/O Processor Processor full screen screen function function support supports s only the Featur Feature e A attribute. If the current current characte characterr | attribute is a VGA attribute, then the following must be considered: |

| | |

   If a blinking Feature A attribute is chosen in your input sequence table and your application has enabled intensified background colors, then the input sequence table attribute will display with its background color intensified rather than blinking.

|

   If a blue Feature A attribute is chosen in your input sequence table and your application has enabled

|

underlining, then the input sequence table attribute will display underlined if the video display is monochrome.

|

|

char arac acte terr lo loc catio ation n is de defi fine ned d as a row an and d co colu lumn mn co coor ordi dina nate te Current Cur rent C Char haracte acterr Loc Locatio ation: n: A ch

(row,column).. Each character (row,column) character location location contains contains a charac character ter and and an attribu attribute. te. The de default fault current current | character location is (1,1). |

Use the LOCATE statement statement to chang change e the curren currentt characte characterr location. location. This is the row and colu column mn where | you want to start writing characters on the video display. |

The current video display format determines the valid row and column values for each character location. | Valid values range from one to the maximum row and column for the current video display format.

|

The location location of the cursor is the same as the current current char character acter location. location. You also use the LOCAT LOCATE E | stateme statement nt to control whether whether or not the curso cursorr is visible. The curr current ent charac character ter locatio location n does not affect the | location of characters written by the I/O processor.

|

 

3-17

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

|

Charac Cha racter ter Loc Locati ation on Wra Wrappi pping: ng: If the the nu numb mber er of cha hara ract cter ers s or attr attrib ibut ute es yo you u writ write e is grea greate terr tha than

|

|

the number of character locations remaining on the current row of the video display, the characters or attributes attrib utes are written written on the next row. If the curren currentt row is the last row, then the char characters acters or att attributes ributes are written written to row 1. The characters characters or attributes attributes continue continue to wrap around around until all of the char characters acters or attributes are written.

|

Video Vid eo Di Displ splay ay Ch Charac aracter ter S Set: et: Th The e vi vide deo o di disp spla lay y char charac acte terr set set dete determ rmin ines es wh what at is di disp spla laye yed d on

| | |

the video display display for each character character written written by your application application.. Each video dis display play driver driver has its own set of video character character sets sets for the different different code pages supported supported.. Differe Differences nces exis existt between the vide video o display character sets used by the Feature A and VGA video drivers.

|

Refer to the IBM 4680 BASIC Language Reference   for for a description of each of the video character sets.

|

Writing Writi ng Char Characters acters W Without ithout Changi Changing ng Attri Attributes: butes: Use Use by byte te CC in the the PU PUTL TLON ONG G state tateme ment nt

|

to change the write mode to write characters without changing the attribute.

| |

If you select to have characters written without changing the attribute, then the current character attribute is not used on all subsequent WRITE statements until your application changes the write mode with anotherr PUTLONG statement. anothe statement. The attrib attribute ute remains the the same as it was before the character character was wr written. itten.

|

See the “Example” on page 3-20 where this mode of writing characters is used to restore a screen.

|

Writing Writi ng Attri Attributes butes W Without ithout Changi Changing ng Cha Characters: racters: Use Use by byte te CC in the the PU PUTL TLON ONG G state tateme ment nt

|

to change the write write mode to write attributes attributes withou withoutt changing the characte character. r. Also use byte VV in the PUTLONG statement to change the current character attribute type.

| |

|

| | | |

If you select to have attributes written without changing the character, then the data variable is interpreted as attribute data on all subsequent WRITE statements until your application changes the write mode with another PUTLONG statement.

|

Although the current character attribute is not used, the type of the current character attribute is used to determine whether the data variable contains Feature A or VGA attributes.

|

See the “Example” on page 3-20 where this mode of writing attributes is used to restore a screen.

|

Determining Video Display Information

|

You use the GETLONG function to determine the following information about the video display:

|

| | | | | | | |

               

       

Current character attribute Current character attribute type (VGA extension) Current character location (row and column) Whether the cursor is visible Current video display format Whether the attached video display is monochrome or color Whether underlining is enabled (VGA extension) Whether blinking or background intensified colors are enabled (VGA extension)

3-18

4690 Store System: Programming Guide

 

 

|

Reading from the Video Display

Use the the READ FORM FORM # statem statement ent to rread ead the the cha charac racter ters s or attrib attributes utes that that have b been een wr writte itten n by yo your ur | applica application tion and the I/O Processor. Processor. The default mode mode of reading from the video video display is to read the | characters that have been written. |

|

Use byte CC in the PUTLONG PUTLONG statement statement to change change the read read mode. To read attributes attributes instead instead of

|

characters chara cters see “Reading “Reading Attributes Attributes from the Video Display” on page 3-19.

Before reading reading from the video video display, display, you can set the current current charac character ter locatio location. n. This is the row and where you want to start reading reading from the video video display. See “Current “Current Character Character Loca Location” tion” on | column where | pag page e 3-1 3-17 7 for for detail details. s. |

The length of the data variable specified on the READ FORM # statement determines the number of | chara character cter locations locations read from the video display. display. If the length requested requested exceeds the remaining remaining chara character cter described in “Character Location Wrapping” on page 3-18 | locations on a row, wrapping is done as described |

After the READ FORM # statement is complete, the current character location is set to the first character | location after the last character location that was read. |

|

See the “Example” “Example” on page 3-20 where where this mode of reading reading characters characters is used to save a scre screen. en.

|

Reading Readin g Attri Attributes butes from th the e Vid Video eo Di Display: splay: Use byte CC in the PUTLONG stat tateme men nt to

change the the read mode to read read attributes attributes from from the video dis display. play. Also use by byte te VV in the PUTLON PUTLONG G | statement to change the current character attribute type. |

If you select to read attributes, then all subsequent READ FORM # statements will return attributes until | your application application changes changes the read read mode with another PUTLONG PUTLONG state statement. ment. The type of the curr current ent | character attribute is used to determine whether the attributes being returned are Feature A or VGA | attributes. |

|

See the “Example” “Example” on page 3-20 where where this mode of reading reading attributes attributes is used to save a screen. screen.

|

|

Special Considerat Considerations ions When Using VGA Video Drive Driverr and Feature A Attributes: Attributes: Feature A attributes attribu tes read from the video video display are are not guaranteed guaranteed to match the attributes attributes orig originally inally written. written. This is because the VGA video driver must map the Feature A attribute internally to a VGA attribute, and there are some characteri characteristics stics of the Feature Feature A attribute that are not supporte supported. d. See “Feature “Feature A Attribute Attribute”” on page 3-15 for more information information

|

However, rewriting these previously read attributes produces the same original result.

|

Running a 2x20 Display Application on the Video Display

|

An application written for a 2x20 display runs on a video display with the following considerations:

| | |

|

   The application must change the OPEN statement to access VDISPLAY or VDISPLAY2

|

   Character location wrapping is different

| | | | | |

On 2x20 displays displays wrapping wrapping occurs occurs to the next row when 20 character character locat locations ions are exce exceeded. eded. On video displays it is dependent on the current video display format. For example, a write to the alphanumeric display of 40 characters starting at character location (1,1) appears appear s as two lines on the alphanumeric alphanumeric display. display. The same write to the video video display app appears ears as one line.

   Display character sets are different

 

3-19

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

| | | |

|

Refer to the IBM 4680 BASIC Language Reference  for   for a description of the display character sets.

   GETLONG returns different information Only the CC (current column) and RR (current row) bytes of the GETLONG are consistent between the video and 2x20 displays.

 Example Example

|

The following following example contains contains a BASIC application application for th the e video displa display. y. This exam example ple writes to the video display using Feature A attributes, writes to the video display using VGA attributes, saves the screen, clears the video display, then restores the saved screen.

|

%ENVIRON T

| | |

INTEGER*4 PUTLDATA INTEGER*2 VDISP, VGADRIVER STRING TSTATUS, CHARS, FAATTRS, VGAATTRS

| | | | | |

! ADXSERVE subroutine SUB ADXSERVE (RET,FUNC,PARM1,PARM2) EXTERNAL INTEGER*4 RET INTEGER*2 FUNC,PARM1 STRING PARM2 END SUB

| |

! Establish an error routine. ON ERROR GOTO ERROR1

| | |

! Open the video display. VDISP = 2 OPEN "VDISPLAY:" AS VDISP

| | |

! Change video display format to 25x80, and grey Feature A attribute PUTLDATA = 000800E0H PUTLONG VDISP, PUTLDATA

| |

! Display Feature A attribute examples title line WRITE #VDISP; "Following are examples of Feature A attributes:"

| | | | | |

! Set character location to (3,1), set green blinking Feature A attribute ! and display test line LOCATE #VDISP; 3,1,OFF PUTLDATA = 00000082H PUTLONG VDISP, PUTLDATA WRITE #VDISP; "Green blinking characters on black background"

| | | | | |

! Set character location to (4,1), set red reverse Feature A attribute ! and and dis displ play ay test test line line LOCATE #VDISP; 4,1,OFF PUTLDATA = 00000021H PUTLONG VDISP, PUTLDATA WRITE #VDISP; "Black characters on red background"

| | | |

! Set character location to (5,1), set blue Feature A attribute ! and and dis displ play ay test test line line LOCATE #VDISP; 5,1,OFF PUTLDATA = 00000040H

| |

3-20

4690 Store System: Programming Guide

 

 

| |

PUTLONG VDISP, PUTLDATA WRITE #VDISP; "Blue characters on black background"

| | | | | |

! Set character location to (6,1), set magenta Feature A attribute ! and and dis displ play ay test test line line LOCATE #VDISP; 6,1,OFF PUTLDATA = 00000060H PUTLONG VDISP, PUTLDATA WRITE #VDISP; "Magenta characters on black background"

| | | | | |

! Set character location to (7,1), set magenta intensified Feature A attribute ! and and dis displ play ay test test line line LOCATE #VDISP; 7,1,OFF PUTLDATA = 00000068H PUTLONG VDISP, PUTLDATA WRITE #VDISP; "Light magenta characters on black background"

| | | | | | |

! Set character location to (8,1), set white underlined Feature A attribute ! and and dis displ play ay test test line line ! Note: Will not be underlined on VGA video display LOCATE #VDISP; 8,1,OFF PUTLDATA = 000000F0H PUTLONG VDISP, PUTLDATA WRITE #VDISP; "White underlined characters on black background"

| | | | |

! If have a VGA video display then display test lines for some VGA attributes VGADRIVER = 0 CALL ADXSERVE(RET,4,0,TSTATUS) IF (RET = 0) AND (MID$(TSTATUS,48,1) = "1") THEN \ BEGIN

| | | | | | | |

! Set we have a VGA video driver VGADRIVER = 1 ! Set character location (10,1), set grey VGA attribute   ! an andd display VGA attribute examples title line LOCATE #VDISP; 10,1,OFF PUTLDATA = 01000007H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Following are examples of VGA attributes:"

| | | | | |

! Set character location (12,1), set green foreground and black   ! back backgr grou ound nd VGA attr attrib ibut utee an andd dis display play test est lin line LOCATE #VDISP; 12,1,OFF PUTLDATA = 01000002H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Green characters on a black background"

| | | | |

! Set green foreground and brown   ! back backgr grou ound nd VGA attr attrib ibut utee an andd dis display play test est lin line PUTLDATA = 01000062H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Green characters on a brown background"

| | | |

! Set cyan foreground and red background   ! VG VGA attribute and display test line PUTLDATA = 01000043H PUTLONG VDISP, PUTLDATA

 

3-21

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

|

WRITE FORM "C80"; #VDISP; "Cyan characters on a red background"

| | | | |

! Set blue foreground, grey background,   ! bl bliinking VGA attribute and display test line PUTLDATA = 010000F1H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Blue blinking characters on grey background"

| | | | |

! Set magenta background, white foregound   ! VG VGA attribute and display test line PUTLDATA = 0100005FH PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "White characters on magenta background"

| | | | |

! Set red foreground, green background   ! VG VGA attribute and display test line PUTLDATA = 01000024H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Red characters on green background"

| | | |

! Announce about to enable background intensified colors WRITE FORM "C80"; #VDISP; "About to enable background intensified colors" ! Wait 5 seconds   WAIT WAIT;; 5000 5000

| | | | | | | |

! Set character location to (18,1), set light red foreground,   ! yell yellow ow back backgr grou ound nd VGA VGA attr attrib ibut ute, e, enab enable le inte intens nsif ifyy back backgr grou ound nd colo colors rs   ! and and display test lines LOCATE #VDISP; 18,1,OFF PUTLDATA = 050000ECH PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Background intensified colors enabled and blinking disabled" WRITE FORM "C80"; #VDISP; " for entire screen - light red characters on yellow background"

| |

! Announce about to enable underlining WRITE FORM "C80"; #VDISP; "About to enable underlining"

|

! Wait 5 seconds

|

  WAIT WAIT;; 5000 5000

| | | | | | | | |

! Set character location to (20,1), set light blue foreground, grey background ! VGA attribute, enable intensify background colors and underlining ! and display test lines ! Note: Will be light blue characters without underlining on color display LOCATE #VDISP; 20,1,OFF PUTLDATA = 07000079H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Underlining enabled for entire screen -" WRITE FORM "C80"; #VDISP; " white underlined characters on grey background"

| |

! Announce about to disable underlining and background intensified colors WRITE FORM "C80"; #VDISP; "About to disable underlining and background intensified colors"

| |

! Wait 5 seconds   WA WAIT IT;; 5000 5000

| |

! Set character location to (22,1), set light magenta foreground,   ! blue blue back backgr grou ound nd VGA VGA attr attrib ibut ute, e, disa disabl blee inte intens nsif ifyy back backgr grou ound nd colo colors rs

3-22

4690 Store System: Programming Guide

 

 

| | | | | | |

  ! and and unde underl rlin inin ingg and and disp displlay test test line liness LOCATE #VDISP; 22,1,OFF PUTLDATA = 0100001DH PUTLONG VDISP, PUTLDATA WRITE WRI TE FORM FORM "C80 "C80"; "; #VDISP #VDISP;; "Bac "Backgr kgroun oundd inte intensi nsifie fiedd colo colors rs disabl disabled, ed, blinki blinking ng enable enabled, d, WRITE FORM "C80"; #VDISP; " and underlining disabled for entire screen - " WRITE FORM "C80"; #VDISP; " light magenta characters on blue background"

|

ENDIF

| | | | | |

! Set grey Feature A attribute ! and displa displayy about about to clear clear the screen screen LOCATE #VDISP; 25,1,OFF PUTLDATA = 000000E0H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Now let's clear the screen"

| | |

!********************************************************************* ! Save the screen for restoring later !*********************************************************************

| | |

! Read Read char charact acters ers from from vide videoo disp display lay LOCATE #VDISP; 1,1,OFF READ FORM "C2000"; #VDISP; CHARS

| | | | | |

! Set read mode to read Feature A attributes, set character location ! to (1, (1,1) 1) and and rea readd the the attr attrib ibut utes es PUTLDATA = 000002E0H PUTLONG VDISP, PUTLDATA LOCATE #VDISP; 1,1,OFF READ FORM "C720"; #VDISP; FAATTRS

| | | | | | | | |

! If have a VGA driver then save VGA attributes IF (VGADRIVER = 1) THEN \ BEGIN   ! SSeet read mode to read VGA attributes then read PUTLDATA = 01000207H PUTLONG VDISP, PUTLDATA LOCATE #VDISP; 10,1,OFF READ FORM "C1200"; #VDISP; VGAATTRS ENDIF

| | |

! Wait 5 seconds then clear WAIT; 5000 CLEARS VDISP

| | |

!********************************************************************* ! Restore the screen !*********************************************************************

| |

LOCATE #VDISP; 1,1,OFF WRITE FORM "C80"; #VDISP; "Now let's restore the screen"

| |

! Wait 3 seconds WAIT; 3000

| |

! Set write write mode to write write Feature Feature A attributes attributes then then write write them PUTLDATA = 000008E0H

"

 

3-23

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

| | |

PUTLONG VDISP, PUTLDATA LOCATE #VDISP; 1,1,OFF WRITE FORM "C720"; #VDISP; FAATTRS

| | |

! If have a VGA driver then restore VGA attributes IF (VGADRIVER = 1) THEN \ BEGIN

| | | | | |

  ! Set write mode to write VGA attributes then write them PUTLDATA = 01000807H PUTLONG VDISP, PUTLDATA LOCATE #VDISP; 10,1,OFF WRITE FORM "C1200"; #VDISP; VGAATTRS ENDIF

| |

! Wait 2 se seconds WAIT; 2000

| | | | | |

! Set write write mode mode to to write write charact characters ers without without updating updating attrib attribute, ute, ! set set gre greyy Fe Featur aturee A att attri ribu bute te PUTLDATA = 000004E0H PUTLONG VDISP, PUTLDATA LOCATE #VDISP; 1,1,OFF WRITE FORM "C2000"; #VDISP; CHARS

| |

! Wait 2 se seconds WAIT; 2000

| | |

! Set character location to (25,1) and display test end line LOCATE #VDISP; 25,1,OFF WRITE FORM "C80"; #VDISP; "End of Video display sample program

| |

CLOSE VDISP STOP

| | |

ERROR1: ! Prevent recursion. ON ERROR GOTO END.PROG ! Determine error type and perform appropriate recovery ! and resume steps. END.PROG: STOP END

| | | | |

| | | |

"

Using Feature A Video Driver Command Stacking to Improve Performance You can use command stacking to further improve system performance when using video displays with the Feature A video driver.

|

The VGA video driver driver does not support support command command stacking. stacking. Command sta stacking cking sele selection ction on the PUTLONG statement statement is ignored ignored by the VGA video driver. driver. Howeve However, r, this method re requires quires min minor or changes changes

|

to your application programs.

|

Command stacking reduces the system overhead that is associated with sending the application program’s WRITE, LOCATE, LOCATE, and PUTLONG PUTLONG statements. statements. Command stacking stacking combines combines or pack packages ages a number of

|

|

3-24

4690 Store System: Programming Guide

 

 

these statements statements into a single single video adapter adapter command command.. Using this packaging packaging or sta stacking cking tech technique, nique, you | can send a group of application statements to the video adapter with no more overhead than a single | command.

|

In some cases, the video driver automatically combines the statements sent from an application program sending the statements statements to the video ada adapter. pter. However, However, you can gain bette betterr video perfo performance rmance by | before sending | using the application program to signal the video driver when it is safe to combine application statements. |

| |

The program can use bit 0 of byte CC of the PUTLONG statement to convey this information to theapplication driver.

An application program must set bit 0 of byte CC to 1 to allow the driver to begin stacking application | stateme statements. nts. The driver driver continues continues to stack application application state statements ments for maximum maximum perform performance ance until bit 0 of | byte CC is reset to zero. |

| | | | | | | |

The video driver determines the amount of information that can be combined into one video adapter command.. When bit 0 is set to 1, the video driver co command continues ntinues to combine combine applic application ation state statements ments until the maximum adapter adapter command command size is reached. reached. When this maximum maximum size is reac reached, hed, the video dr driver iver send sends s the command to the adapter and combines subsequent application statements in a second adapter command.. This process command process continue continues s independent independently ly of the the appli application cation p progra rogram. m. If you reset bit bit 0 from from 1 to 0, the video driver driver sends all application application statements statements in the vide video o command buff buffer er to the adapter adapter.. If bit 0 is not reset, the driver continues to wait for additional application program statements until the maximum adapter command size is reached.

When bit 0 is set to 1, it signals signals the driver driver to begin begin combining combining application application statements. statements. Bit 0 must be | maintained as 1 on subsequent statements until the application issues a PUTLONG that resets bit 0 to | zero. See the “Example “Example Program Program Using Command Command Stacking” Stacking” for additional additional informat information. ion. |

| | | | | | | | |

You ca can n us use e com omma mand nd stack tackin ing g on only ly with with othe otherr Restrictions Restric tions Using Comma Command nd Stackin Stacking: g: You application WRITE statements application statements of a similar type. type. For example, example, command commands s to write charac characters ters while updating attributes can be stacked only with other commands that write characters while updating attributes, write character only commands with other write character only commands, and write attribute only commands commands with other write write attribute attribute only commands. commands. Switchin Switching g from writing only only attribute attributes s to writing only characters characters causes causes the system to flush the stack buffer. There Therefore, fore, when writing writing both characte characters rs and attributes, it is more efficient to set the attributes using a PUTLONG command (leaving bits 2 and 3 of byte CC 0) and then issue a WRITE command to send the character data, rather than sending separate write attribute and write character commands.

|

Any data the I/O processor sends to the video driver results in the command stacking buffer being cleared and the data sent to the screen. screen. Examples Examples of data written by the I/O processor processor inc include lude displ displaying aying keyboard input using the display-as-keyed feature of the input sequence table, and displaying operator prompt messages messages defined defined in the input sequence sequence table. Since infor information mation displayed displayed this way is con considere sidered d to be immediately required by the user, the video driver forces it to the screen automatically instead of waiting for the application to flush the command stacking buffer.

|

Example Exampl e Prog Program ram U Using sing Comman Command d Stac Stacking: king: Th The e foll follow owin ing g exam exampl ple e show shows s an appl applic icat atio ion n

| | | | |

program that uses command program command stackin stacking. g. The progr program am displays displays a box on the screen with a calend calendar ar included d inside the box. This program program shows how to turn on command command stackin stacking g and how to leave the | include | stacki stacking ng bit turned on until a grou group p of statements have have been issued. issued. Command st stacking acking is optio optional, nal, but | might result in faster screen response when using the video display.

|

The source code following shows how to use the PUTLONG command to stack or combine all of the program am statements statements required required to display the calendar. calendar. Bit 1 of byte CC in the PUTLONG statement statement is set | progr | to 1 before any any of the WRITE statements statements a are re issued. issued. This same bit bit is maintain maintained ed as 1 during during all of the |

 

3-25

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

| |

PUTLONG commands commands used used to change the screen screen attribu attributes. tes. After all of the WRITE stat statements ements hav have e been issued, a final PUTLONG command clears the video buffer, thus sending the data to the screen.

| | | | |

Example Program Source Code ! ****** ********* ****** ***** ** Comman Commandd Stacki Stacking ng Progra Programm Exam Example ple ****** ********* ****** ****** ***** ** ! ! This This prog progra ramm disp displa lays ys the the Dec Decem embe berr 199 19955 cale calend ndar ar on the the ! 468 4683 vid video eo disp displlay. ay. It util utiliizes zes the the comm commaand stac stacki king ng ! feat featur uree of the the Feat Featur uree A vid video eo dri drive verr to ens ensur uree the the best best scr scree eenn ! response is is at attained. ! ! *****************************************************************

|

%ENVIRON T

| | | |

! Establish an error routine. ON ERROR GOTO ERROR1 OPEN OPEN ""VD VDIS ISPL PLAY AY:" :" AS 2 ! Ope Openn vide videoo disp displa layy dri drive verr CLEARS 2 ! Clear display before displaying the calendar

| |

! Change video display format to 25x80, and set grey attribute PUTLONG 2, 000800E0H

| |

! Start command stacking, bit zero byte CC = 1 PUTLONG 2, 000001E0H

| | | | | | |

! *** ****** ****** *** Form Form the box box that that surrou surrounds nds the the calen calendar dar LOCATE #2; 2, 4, OFF WRITE FORM "C31"; #2; CHR$(6)+STRING$(29, CHR$(12))+CHR$(7) FOR II = 3 To 13 LOCATE #2; II, 4, OFF WRITE FORM "C31"; #2; CHR$(25) + STRING$(29, CHR$(32)) + CHR$(24)   NE NEXT II

| | | |

| |

LOCATE #2; 14, 4, OFF WRITE FORM "C31"; #2; CHR$(4) + STRING$(29, CHR$(12)) + CHR$(5)

| | | | | | | |

!******** Write the Month and Year using the intensify and underscore attribute PUTL PUTLON ONGG 2, 000 00000 001F 1F8H 8H ! Ch Chan ange ge to to inte intens nsif ifyy and and unde unders rsco core re,, leav leavin ingg stac stackk bit bit on LOCATE #2; 4, 13, OFF WRITE #2; "DECEMBER 1995" !******** Write days of the week in highlighted attribute PUTL PUTLON ONGG 2, 2, 000 00000 001E 1E8H 8H ! Cha Chang ngee to to hig highl hlig ight hted ed,, lea leavi ving ng stac stackk bit bit on LOCATE #2; 6, 6, OFF WRITE #2; "SUN MON TUE WED THU FRI SAT"

| | | | | |

!******** Write the days of the month using a normal attribute PUTL PUTLON ONGG 2, 0000 000001 01E0 E0HH ! CCha hang ngee to norm normal al,, lea leavi ving ng stac stackk bit bit on on LOCATE #2; 8, 28, OFF   WR WRITE #2; "1 2" LOCATE #2; 9, 8, OFF   WRITE WRITE #2; #2; "3 4 5 6 7 8 9"

| | | |

LOCATE   WRIT WRITEE LOCATE   WRITE WRITE

#2; #2; #2; #2;

10, "10 11, "17

7, OFF 11 11 12 13 14 15 16" 16" 7, OFF 18 18 19 20 21 22 23" 23"

LOCATE #2; 12, 7, OFF

|

3-26

4690 Store System: Programming Guide

 

 

| | |

  WRIT WRITEE #2; "24 25 25 26 27 28 29 30" 30" LOCATE #2; 13, 7, OFF   WRIT WRITEE #2; #2; "31" "31"

| | | |

!******** Make the day of the month blink for emphasis and also intensify PUTL PUTLON ONGG 2, 2, 000 00000 001E 1EAH AH ! Cha Chang ngee to to bli blink nkin ingg and and inte intens nsif ifie ied, d, leav leavin ingg sta stack ck bit bit on on LOCATE #2; 9, 11, OFF WRITE #2; "4"

|

PUTL PUTLON ONGG 2, 2, 000 00000 000E 0E0H 0H

! Flu Flush sh vide videoo buf buffe ferr - forc forcee dat dataa to to scr scree eenn

| |

  CL CLOSE 2   STOP

| | | | | | | |

ERROR1: ! Prevent recursion. ON ERROR GOTO END.PROG ! Determine error type and perform appropriate recovery ! and resume steps. END.PROG: STOP END

Cash Drawer Driver This section describes the cash drawer driver and provides guidelines for using it.

 Characteristics Characteristics The cash drawer has the following characteristics:

 Each terminal supports a maximum of two cash drawers or one cash drawer and one alarm. attach an external alarm alarm using a set of relay contacts. contacts. Your appli application cation program program cont controls rols  You can attach whether the contacts whether contacts are open o orr closed. closed. The ca cash sh drawers drawers are n numbere umbered d1a and nd 2. You must must connect the alarm in place of cash drawer number 2.  To open a cash drawer, your application must send a pulse of a minimum duration to the cash drawer to cause cause it to open. open. If yo you u us use e an IIBM BM cash cash draw drawer, er, the p pulse ulse time is 80 ms. If yo you u us use e a no non-I n-IBM BM cash drawer, drawer, you might need need other pulse times. times. You request request these pulse times du during ring confi configuratio guration. n. The cash drawer driver supports pulse times from 1 ms to 1048 ms; the default is 80 ms.

Functions Your Application Performs An application program can perform the following functions with the cash drawer or alarm:

 Open a cash drawer.  Turn an alarm on or off.  Obtain cash drawer or alarm status.

Accessing the Cash Drawer or Alarm Use the OPEN statement to gain access to the cash drawer driver. Use the CLOSE statement to end your application’s use of the cash drawer driver.

 

3-27

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Controlling a Cash Drawer or Alarm Use the WRITE WRITE FORM statement statement to control control a cash drawer drawer or the alarm. alarm. With a single single WRITE FORM statement you can perform one of the following operations:

   

Open cash drawer 1. Open cash drawer 2. Turn the alarm on. Turn the alarm off.

Obtaining Cash Drawer or Alarm Status Use the GETLONG GETLONG statement to determine determine the status of the cash cash drawers an and d alarm. Cash drawer drawer status provides the following information:

      

Cash drawer 1 open Cash drawer 1 closed Cash drawer 1 not connected Cash drawer 2 open or alarm on Cash drawer 2 closed or alarm off Cash drawer 2 or alarm not connected No cash drawer or alarm connected

When you issue a WRITE FORM statement to open a cash drawer, the cash drawer sensor (part of the cash drawer drawer assembly) assembly) detects detects the status change. change. Following Following a WRITE FORM to open a cash drawer, drawer, give the drawer time to open before requesting a cash drawer status.

 Example Example This example example contains contains code for operating operating a cash drawer. drawer. This prog program ram writes a mess message age to the display display,, opens the cash drawer, writes another message, and then waits for the operator to close the drawer.

%ENVIRON T ! Declare work integers. INTEGER*4 I4,S4 INTEGER*1 DRAWER.ONE ! Constant to open drawer 1. DRAWER.ONE = 1 ON ERROR GOTO ERR.HNDLR ! Open the display as #2. OPEN "ANDISPLAY:" AS 2 CLEARS 2 ! Open cash drawer driver as #1. OPEN "CDRAWER:" AS 1 WRITE #2;"CASHDRAWER DRIVER OPEN" WAIT;2000 START.DRAWER.CONTROL: CLEARS 2 WRITE #2; "OPEN DRAWER 1" WAIT;2000 ! Open cash drawer number 1. WRITE FORM "I1";#1;DRAWER.ONE DRAWER.OPEN: ! Loop while the drawer is open. CLEARS 2 WRITE #2; "CLOSE DRAWER"

3-28

4690 Store System: Programming Guide

 

 

WAIT;1000 ! Get the status. I4 = GETLONG(1) !Shift status. S4 = SHIFT(I4,8) ! Turn off all but status. STAT% = S4 and 000000FFH !Return until cash drawer is closed. IF STAT% 0 THEN GOTO DRAWER.OPEN \ ELSE\ ! End the execution. CLEARS 2 WRITE #2; "end of sample" WAIT;1000 CLOSE 1 CLOSE 2 STOP ERR.HNDLR: ! Prevent recursion. ON ERROR GOTO END.PROG ! Determine error type ! and perform appropriate ! recovery and resume steps. END.PROG: STOP END

Coin Dispenser Driver This section describes the coin dispenser driver and provides guidelines for using it.

 Characteristics Characteristics The coin dispenser has the following characteristics:

 Each 4683 terminal terminal supports supports a maximum of two feature feature expans expansion ion cards. You can attach a nonnon-IBM IBM coin dispenser to one of these feature expansion cards.

application should should specify the amount amount of money to be dispen dispensed sed as a four-digit four-digit integer integer.. This  Your application number represe represents nts the number of monetary monetary units to be disp dispensed ensed (c (cents, ents, for exam example). ple). The definition definition of the term monetary unit   depends depends on the country in which the coin dispenser is designed to operate.

 The 4690 Operating System supports the coin dispenser and feature expansion cards only on 4683 terminals.

Accessing the Coin Dispenser Use the OPEN statement to gain access to the coin dispenser driver. Use the CLOSE statement to end communication with the coin dispenser driver.

 

3-29

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Dispen Dis pensin sing g Coi Coins ns To dispense dispense coins, issue issue a WRITE FORM statement. statement. You can specify specify the number of monet monetary ary units to be dispensed dispen sed as a variable variable or a constant in the WRITE FORM statement. statement. If an error occurs, occurs, contr control ol passes to the ON ASYNC ERROR subprogram. subprogram. Your application application should should allow the coin dispenser dispenser en enough ough time between writes to complete coin dispensing.

 Example Example This example program runs through one time, dispenses 47 cents, and then stops.

%ENVIRON T ! Declare variables. INTEGER*4 hx%,sx% INTEGER*2 COIN%,ANDSP% SUB ASYNC.ERR(RFLAG,OVER) INTEGER*2 RFLAG STRING OVER RFLAG = 0 OVER = "" hx% = ERRN ERRFX$ = "" FORsx%s%==SHIFT(hx%,s%) 28 TO 0 STEP -4 THE.SUM% = sx% AND 000fh IF THE.SUM% > 9 THEN \   THE.SU THE.SUM%= M%=THE THE.SU .SUM%+ M%+55 55 \   EL ELSE \   THE.SUM%=THE.SUM%+48   A$=CHR$(THE.SUM%) ERRFX$ = ERRFX$ + A$ NEXT s% CLEARS ANDSP% WRIT WRITEE #AN #ANDS DSP% P%;" ;"ER ERR= R=", ",ER ERR, R,"" ERRL ERRL=" =",E ,ERR RRLL LOCATE #ANDSP%;2,1 WRITE #ANDSP%;"ERRF= #ANDSP%;"ERRF=",ERRF ",ERRF%," %," ERRN=",ERR ERRN=",ERRFX$ FX$ WAIT ;15000 RESUME END SUB ON ERROR GOTO ERRORA ! Set ON ERROR routine. ON ASYNC ERROR CALL ASYNC.ERR ! Set ON ASYNC ERROR routine. COIN% = 3 ! Initialize session numbers. ANDSP% = 1 OPEN "ANDISPLAY:" as ANDSP% ! Open alphanumeric display. CLEARS ANDSP% ! Clear alphanumeric display. WRITE #ANDSP% ; "SAMPLE COIN PROG" ! Indicate start of application. WAIT;5000 ! Wait 5 seconds. OPEN "COIN:" AS COIN% ! Open coin dispenser.

LOCATE #ANDSP% ; 2,1 3-30

4690 Store System: Programming Guide

 

 

! Locate to 2nd line of display. WRITE #ANDSP% ; "COIN DISPENSER OPEN" WAIT;5000 AMOUNT% = 47 ! Load amount to be dispensed. CLEARS ANDSP% ! Clear display WRITE FORM "C8 PIC(####) C8" ;#ANDSP% ; "WRITING ",AMOUNT%," CENTS." WRITE FORM "I4" ; #COIN% ; AMOUNT% ! Dispense coins command. WAIT;5000 ! Wait 5 seconds. LOCATE #ANDSP% ; 2,1 WRITE #ANDSP% ; "END OF SAMPLE" STOP ERRORA: ! Error assembly routine. hx% = ERRN ERRFX$ = "" FOR s% = 28 TO 0 STEP -4 sx% = shift(hx%,s%) THE.SUM% = sx% AND 000fh IF THE.SUM% > 9 THEN \   THE.SU THE.SUM%= M%=THE THE.SU .SUM%+ M%+55 55 \   EL ELSE \   THE.SUM%=THE.SUM%+48   A$=CHR$(THE.SUM%) ERRFX$ = ERRFX$ + A$ NEXT s% CLEARS ANDSP% WRIT WRITEE #AN #ANDS DSP% P%;" ;"ER ERR= R=", ",ER ERR, R,"" ERRL ERRL=" =",E ,ERR RRLL LOCATE #ANDSP%;2,1 WRITE #ANDSP%;"ERRF= #ANDSP%;"ERRF=",ERR ",ERRF%," F%," ERRN=",ERRFX ERRN=",ERRFX$$ WAIT;15000 RESUME END

/O Proc Proces esso sorr  II/O This section describes the I/O processor and provides guidelines for using it.

 Characteristics Characteristics The I/O processor and the input sequence tables work together to allow the accumulation and validation of operator input from the keyboard, optical character reader (OCR) or bar code reader, magnetic wand, or scanner. scanne r. This accumul accumulation ation and validatio validation n can occur simultaneousl simultaneously y with your applic application. ation. When the operator enters specified amounts of input, you can have the input forwarded to your application for further processing. proce ssing. The input from the various various devic devices es can be formatted formatted so that your appli application cation rec receives eives onl only y one format regardless of the source device. The accumulation and validation of operator input at the I/O processor level allows rapid response to operator operat or input. For example, example, during point-of-sale point-of-sale checkout, checkout, the opera operator tor can enter item informa information tion that the I/O processor processes while your application finishes a previous item by performing a price lookup.

 

3-31

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

The I/O processor processor is a driver that that process processes es operator operator input acco according rding to the inpu inputt sequence tab tables. les. You must build build the input input sequence sequence tables tables according according to the the requiremen requirements ts of your applic application. ation. See Chapter Chapter 7 for more information. information. You must load the input input sequence tables tables into termi terminal nal memory bef before ore using the I/O processor. |

Input Devices on Your System

| |

The system system device driver driver for the I/O processor processor is named IOPRO IOPROC: C: Your application application accesses accesses the following input devices via the I/O Processor driver.

|

 

| |

 

|

Keyboard Magnetic wand ( 4683 only ) Scanner Optical Character Reader (OCR)

|

These devices devices are all optional optional attachments attachments for the IBM Point of Sale Terminals. Terminals. For infor information mation on attaching and configuring them refer to the section on Terminal Configuration Keywords in the 4690 Store  System: Planning, Installation, and Configuration Guide.

|

I/O Processor Functions

| |

| | | | | | | | | | | | |

The I/O processor and input sequence tables provide the following general capabilities:  Display messages to prompt the operator for input.  Validate operator input sequences.  Edit, modulo-check, and convert data.  Display data as entered.  Map input into buffers.  Issue error tones and display messages for valid input.  Allow automatic end-of-field sequences.  Queue input to the application for processing.  Allow CLEAR CLEAR key  key processing without application action required.

                 

If the terminal has a primary display configured that is larger than 2x20, a set of Enhanced I/O Processor functions functio ns can be used. These are known known as the Enhance Enhanced d Full-Scr Full-Screen een I/O Processor Processor functions functions as shown in the following list:

|

           

|

Input Sequence Tables

|

The input sequence tables consist of three tables:

| | | | | | | |

| | |

           

Customization of Message Display. Three Display Attributes Per Field. Large Input Sequences. Header Field Extensions. Upper Case Display-As-Keyed. Additional Tab Keys Definition. WRITE WRIT E Statemen Statement. t. PUTLONG PUTL ONG Statemen Statement. t. Double-Quote DoubleQuote Substitution. Substitution.

   Input state table    Label format table    Modulo check table

3-32

4690 Store System: Programming Guide

 

 

The input state table is always required to allow operator input from the keyboard, OCR, magnetic wand, | or scanner. scanner. The label format format table and modulo modulo check table are op optional tional depending depending on your applicati application on | requirements. |

The input sequence tables are used by the I/O processor to determine what operator input is allowed and | how to process it. |

| |

The e foll follow owin ing g term terms s are are us used ed to de desc scrribe ibe the the I/O I/O proc proces esso sorr an and d in inpu putt Definit Defi nition ions s and Con Concep cepts: ts: Th

sequence tables:

A state  is   is a condition condition of the terminal terminal for which there there is a set of allowed allowed inputs. inputs. A state is identified identified by an ID (1 through 300). 300). The state is set by an application application pro program, gram, and the term terminal inal can move from from one state | to another state based on operator input occurring in a state. |

|

| | | | | | |

A function code  is   is a value from 61 to 255 255 that delimits delimits an input data field. field. For keyed keyed input, a func function tion code correspond corresponds s to a non-data key ( such as “enter” “enter” or “tot “total”). al”). The functio function n code values for ke keys ys are defined in the the keyboard keyboard layout layout in Termina Terminall Configuration. Configuration. For example, example, the Enter  key is assigned a Enter key function functio n code of 95 (function codes can be reassigned reassigned during during configuration). configuration). You can associa associate te numeric or alphanumeric alphanumeric dat data a with a function code. code. Data is concatenated concatenated to function function codes in the mess messages ages passed from from the I/O Processor Processor to the application. application. It is possible to have a function function code without without any accompanying data.

A function code code can result from other other than a physical physical key being pressed. pressed. For examp example, le, an option is | availab available le to pass numeric numeric values entered entered withou withoutt a function key to an application. application. This is called the | automat automatic ic end-ofend-of-field field option. option. You can specify specify a function code code to be associated wit with h this data.

|

Function codes can represent Function represent fields fields on labels. The data from labels labels is formatted formatted into fields cons consisting isting of | functio function n codes and data. This allows the ap applicatio plication n to handle input from from scanners scanners and reader readers s with the | same processing as used for keyed input. |

A motor function code  is   is a function code that causes all of the accumulated data and function codes entered d since the begin beginning ning of the input sequence sequence to be queued to the application application.. A motor function function code | entere | is also called a motor key .

|

|

An input sequence   is is a series of one or more operator inputs that initially starts in a state that allows an operator operat or to begin input. The input sequence sequence ends in a motor function function code or er error ror spec specified ified to be given to the application. application. The input sequence sequence can contain contain up to 10 function cod codes es with their ass associated ociated da data ta if the Enhanced Full-Screen support is not being used, or up to 127 function codes with their data if the Enhanced Full-Screen support is being used.

|

In Inpu putt St State ate Tab Table le:: Th The e in inpu putt stat state e tabl table e is req equi uirred to all llow ow an and d proc proces ess s op oper erat ator or in inpu putt from from the the

| | | |

keyboard, OCR reader, keyboard, reader, magnetic wand, wand, or scanner. scanner. The input state tab table le consists consists of informatio information n common | to all states and information defined specifically for each state.

|

Note: Where you can define an action in the following descriptions, you can specify a message to be | displayed and whether to remain in the current state, go to another state, or lock (disallow) input.

|

|

Information Common to All States

|

The following information is common to all states:

| | |

information to use when display-asdisplay-as-keyed keyed is used for numeric numeric data. Display Display-as-k -as-keyed eyed    Data editing information means the numeric numeric keys appear appear on the displa display y as they are entered. entered. You can define the tho thousand usands s separator character, decimal point character, and the number of decimal digits to use to format the

 

3-33

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

|

field on the display display after the complete complete field is entered. entered. Use of display display-as-k -as-keyed eyed is speci specified fied in the function functio n code information. information. The positio position n to use on the display is specified specified in the state information. information.

|

   A function code (key) to clear a system busy condition and a message to display when a system busy

|

| | | | | | | | | | | |

condition occurs. condition occurs. The system busy busy condition condition occurs when when all buffers available available to hold inpu inputt sequences sequen ces are full and queued queued to the applica application. tion. This cond condition ition can occu occurr when the opera operator tor enter enters s information informa tion faster than than the application application can proce process ss it. If you define a function function code to clear a system busy condition, condition, the operator operator must press press this key before before any other operator operator input is allow allowed. ed. This is useful if you want the operator to slow down the input and verify that all items entered were processed.  key should return the terminal to the state that is defined as the    Whether a double entry of the Clear Clear key beginning of the current beginning current input sequence. sequence. Refer to the information information for eac each h state for the speci specification fication of a beginning state.

   Tone type and duration to sound for errors based on device source (keyboard, OCR reader, magnetic wand, and scanner).

   Functio Function n codes that that are valid in al alll states. You can define define a functi function on code to be va valid lid in all states a and nd

|

also valid in in one or more specific specific states. states. In this case case,, the definiti definition on of the function function code in a spe specific cific state takes precedence when in that state.

|

   If you have an alphanumeric or ANPOS keyboard, a field passed to the application can be a function

|

|

code and zero or more numeric digits, or it can be a function code and zero or more alphanumeric

|

characters. |    Whether Enhanced Full-Screen mode is being used.

|

Double-Quote Quote Substitution Substitution character character ( Enhance Enhanced d Full-Screen Full-Screen mode only ). Within an input sequence, sequence,    Double-

|

fields are enclosed in double quotes and delimited by commas. Alphanumeric and ANPOS keyboards have a double-quote character that would conflict with the double-quote used to enclose data passed from the I/O Processor Processor to the application. application. To preven preventt such a conflict a character character must be defi defined ned to be used as a substitute substitute for doubledouble-quotes quotes within within fields. This enab enables les the applic application ation and the I/O Processor Proces sor to distinguish distinguish between between the two classe classes s of double-q double-quotes. uotes. The substitution substitution is in the input sequence sequen ce that is passed to or from the applicatio application; n; it is not apparent to the oper operator. ator. Substitution Substitution occurs occur s for both the function function code and the data within the fie field. ld. The value selected selected for the substitution substitution byte should be different than any function code and any keyable value.

| | | | | | | |

   Additional Tab Keys Definition ( Enhanced Full-Screen mode only ) You may define any configurable

|

key as an additional additional tab forward forward o orr tab backward backward key. The definition definition is in effect effect for all sta states. tes. This technique also allows you to define tab keys on keyboards that don't have any tab keys, such as the 50-key keyboard.

| | | | | |

Information Infor mation for Each State: State: For each state, you can specify the following:

ID and name. The s state tate ID must b be e a value value ffrom rom 1 to 300. 300. State n names ames are are us used ed on only ly in the    State ID utility used to build build the input sequence sequence table. State IDs are used used by the I/O processo processorr and passed to an application.

|

   Valid function codes.

|

Whetherr this state be begins gins an input input sequence. sequence. This is related related to the double double Clear  key usage definition    Whethe Clear key

|

in the common information.

| |

Note: When the double Clear Clear key  key usage is selected in the common information, and the terminal operator presses Clear Clear twice  twice consecutively, the application is notified.

|

Notification means that the input fields entered up to this point are queued to the application.

|

   Allowed input devices in the state.

3-34

4690 Store System: Programming Guide

 

 

| | | |

   Whether data should display-as-keyed and whether to edit the data (editing information is in the common information information section). section). Display Display-as-k -as-keyed eyed is defined in both state and functio function n code definitions. definitions. If a function code has not yet been received in a state, the state definition determines the display-as-keyed properties until a function code is received.

|

   A message to be displayed when the terminal enters this state.

|

   Whethe Whetherr to support aut automatic omatic end-of-fie end-of-field ld in this state. If supported, supported, you can also spe specify cify the numbe numberr

| |

   The action to take for function codes entered but not defined in this state.

|

   Whether to allow data to be keyed and assigned to a function code that will be keyed following other

of data keys defined to cause end-of-field and the function code to be associated with this field.

|

function codes. function codes. You can can do this o one ne of two ways. ways. You can can indi indicate cate “Data “Data no nott allowed” allowed” or “Data “Data follows function function code” code” for the function code code key that will be press pressed ed followin following g the data. You can also indicate “Assign saved data” for the function code to which the data is to be assigned.

|

Whetherr or not the state is a full-scr full-screen een state. A non-full-scre non-full-screen en is restric restricted ted to the top left 2x20 area    Whethe

| |

| | | | | | | |

of the display for displaydisplay-as-ke as-keyed yed data and messages messages defin defined ed in the state table. A full-screen full-screen state does not have this restriction. display the data data on the display, display, if the stat state e is not a full-s full-screen creen sta state. te. If the state is a    Where to display full-screen state, the locations for displaying data are specified in the function code definitions (display-as-keyed locations) and in the common information section (message locations).

   Whether data is displayed in normal or reverse order (non-full-screen states only). Information for Information for Each Function Function Code Code:: For each function code allowed in a state and for each function code common to all states, you can define the following:

|

   Function code value (61 through 255).

|

Whetherr this functio function n code is a motor function function code. A motor function function code cause causes s the applicat application ion to    Whethe

|

be notified.

|

 key.    Whether this function code is a Clear Clear key.

|

   Whether to notify the application if an error is detected in the data associated with this function code.

|

   The action to take if no error is detected in the data entered.

|

   Whether data is allowed, required, or optional, and the action to take if this data requirement is not

|

met.

|

   Whether data associated with this function code precedes or follows entry of the function code.

|

   Whethe Whetherr to assign save saved d data to this function code. code. This option option is used in conjunc conjunction tion with the state

| | | | | | | | | | | | |

option to allow allow saving saving of such data. Saved data data is data that was e entered ntered bu butt could not be as assigned signed to the function function code immediately immediately preceding preceding or follow following ing the data (if the state option option is in effect). This option is useful if a desired input sequence contains several function codes, and a particular function code is entered separately from its associated data.

   Whether data should display-as-keyed and whether to edit the data (editing information is in the common part of the table).

   Minimum and maximum number of data digits (0 through 64) allowed and action to take if minimum and maximum requirements are not met.

   Whether to check the value of the data entered using a defined range (0 through 99999999) and the action to take if the range check is not met.

   Whether to modulo-check the data entered using the name of a modulo-check definition in the modulo check table table (see “Modulo “Modulo Check Table” Table” on page 3-37), 3-37), and the action to take if the modulo check check fails.

 

3-35

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

|

   The relative variable position in the read buffer of the field occupied by this function code and

|

associated data. You can allow up to 10 function associated function codes during during an input sequence, sequence, if Enhanc Enhanced ed Full-Screen Full-Sc reen mode is not being being used, or up to 127 if Enhanced Enhanced Full-Scr Full-Screen een mode is being used. used. The relative position defines the order of placement for a function code and its associated data in the input sequence buffer that will be queued to your application.

|

other positions positions are mutually exclusiv exclusive e with this function code’s code’s relative relative positio position n in the buffer. If    Which other

| |

any of the positions specified are already filled during this input sequence when the function code is entered, entere d, an error is assu assumed. med. You also can define define the action to take if the mutual exc exclusive lusive check check is not met.

|

   Whether the manager’s key must be turned on to enter this function code and the action to take if the

| | |

|

|

manager’s key requirement is not met.

|

   Whether to assign previously saved data to this function code.

|

   For full-screen states, additional information is in each function code:

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

 –  –  –  –  –

Location on the display Display attribute at tribute byte Whether data is displayed in normal or reverse order. The data type (numeric, alphabetic, or alphanumeric). Field order This option option specifies specifies the orde orderr in which the fields fields of a state are are access accessed. ed. The first first field is accessed when the state is entered, tab forward accesses the next field, and tab backward accesses the previous field.

    –  Aut Automa omatic tic Tab This option specifies whether the cursor automatically moves to the next field when a field is full of data. If this option option is not selected, selected, the cursor cursor remains remains in the current current field an and d can be moved backward for reentry of previously keyed data.    –  Upper Case Display-As-Keyed (Enhanced Full-Screen mode only) An additional option in the function code definitions of full-screen states allows you to flag the field as an upper-case-only field. For an input field thus defined, the I/O Processor will convert any lower-case character keyed to upper-case. The data appears as upper-case on the video display and in the input sequence passed to the application.    –  Three Display Attributes per Field (Enhanced Full-Screen mode only) You may may specify specify 3 attribu attributes tes per per input input fiel field. d. They a are: re: The attribute attribute in effe effect ct when when the input field is current; current; the attribute attribute in effect when the inpu inputt field is non-cur non-current rent and nonnon-empty; empty; and the attribute attribu te in effect when the input input field is non-current non-current and empty. empty. The reason reason for a 2nd non-cur non-current rent field attribute is to enable highlighting of required fields via the ‘non-current and empty’ attribute. Note: When a full-screen state is entered, the display’s cursor is placed in the position defined for the state’s first first data-entry data-entry field. The other dat data-entr a-entry y fields of the state are accessed accessed by the tab forward and tab backward keys. The values of function codes assigned to the data-entry fields can be assigned according to the convenience of the application—their purpose is to identify the field to the application; they are not necessarily necess arily a value assigned assigned to a key position. position. The non-d non-data-en ata-entry try functio function n codes of the state (su (such ch as an Enter Enter key)  key) provide a recommended and relatively simple means to control routing previously entered fields to the application or transfer to another state, although you can define the function codes assigned to the data-entry fields to accomplish this.

3-36

4690 Store System: Programming Guide

 

 

|

Labe La bell For Forma matt Tab Table le:: Th The e labe labell form format at tabl table e defi define nes s the the info inform rmat atio ion n requ requir ired ed to pr proc oces ess s OC OCR R labe labels ls,,

magnetic ticket labels, magnetic labels, and bar code labels labels (UPC, EAN, CODE39 CODE39,, Interleaved Interleaved Two of Five [ITF]). This | table is divided into information common to all label formats and information about specific label types.

|

| | | |

Information Common to All Label Formats

   Function code required for keying bar code labels.    Function code (key) required to indicate modulus 11 when keying a label. Predominant minant label label type (UPC or EAN). EAN). Specify the the label type if you you have both UP UPC C and EAN labels, labels,    Predo

and the operator operator is allowed to bypass bypass leading leading zeros when keying keying one of the label types types.. Leading Leading | zeros are not required in the predominant label type. |    Whether to convert UPC-E label format to UPC-A label format. |    Display message for errors detected while keying labels. |

|

OCR Label Format

   Format Format identif identifier ier |    Number of subfields in the format |    Length of each subfield (specific or variable) |    Function code to assign to each subfield

|

| | | | | | | | | | | | | | |

Magnetic Ticket Label Format    Format Format identif identifier ier  Number of fields in this format  Length of each field  Function code to be assigned to each field  Whether each field is numeric or alphanumeric  Order in which fields are to be processed

         

Bar Code Label Format    Format Format identif identifier ier    Specific label type (UPC-A, UPC-E, UPC-A+2, UPC-A+5, UPC-E+2, UPC-E+5, UPC-D1, UPC-D2, UPC-D3, UPC-D4, UPC-D5, EAN-13, EAN-8, EAN-13+2, EAN-13+5, EAN-8+2, EAN-8+5, CODE39, CODE93, CODE128, ITF)    Number of fields in this format    Length of each field    Function code to assign to each field

|

Modu Mo dulo lo C Che heck ck Ta Tabl ble: e: Th The e modu modulo lo che heck ck tabl table e allo allows ws you you to de defi fine ne the the ch char arac acte teri rist stic ics s of a modu modulo lo

|

check to be performed performed on key-entere key-entered d or scanner scanner-enter -entered ed data fields. fields. You can define as man many y differen differentt modulo-check modulocheck defi definitions nitions as required required.. When you build build a modulo-check modulo-check defini definition, tion, you assi assign gn an eight-charac eightcharacter ter name to each definition. definition. You reque request st modulo checking checking of a field by refer referencing encing the name name of the modulo-check modulo-check definition definition in the input state state table. The modulo check check table is defin defined ed by the following information:

| | | | | | | | | |

           

     

Name of the the definition. definition. The name referen referenced ced by th the e input state state table. table. Algorithm Algori thm typ type. e. IBM, USER, USER, or UPC/EAN price field. Formula. Formul a. Product Product Add Add or Produ Product ct Digit Digit Add. Add. Modulus. Modulu s. The divisor divisor value value to use iin n calculating calculating the modulo. Weight Wei ghts. s. Def Default ault or UserUser-def define ined. d. User-defined Userdefined weights. weights. The weigh weightt assigned assigned to each digi digitt in the field to be checked. checked.

All fields are not required required for each each algorit algorithm. hm. You can define as many many differen differentt modulo check tab tables les as | required.

|

 

3-37

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

|

User-Defined Modulo-Check Algorithm

| |

If you choose a user-defined modulo-check algorithm, you must choose either the Product Add or Product Digit Add formula. formula. The Product Product Add formula formula assumes assumes that the sum sum of the produ product ct of each field d digit igit and its assigned weight, divided by the modulus factor, results in a zero remainder.

|

For example, if the field being modulo checked is:

|

|

1 2 3 4 5 4

|

where the last digit (4) is the check digit and the weights are:

|

 

|

and and the the modu modulus lus va valu lue e is 5, 5, the su sum m of the the pr prod oduc ucts ts b bec ecome omes: s:

|

 

(1x4)+(2x3)+(3x6)+(4x6)+(5x2)+(4x2)

|

 

= 4+6+ 4+6+18 18+2 +24+ 4+10 10+8 +8

|

 

= 70

|

Then 70 divided by 5 equals 14, which has a zero remainder, and the field passes the modulo check.

| | |

The Product Digit Add is the same as the Product Add format, except that after all digit weight products have been formed, the sum of all of the digits in the products, rather than the sum of the products is calculated. calcul ated. As in the preceding preceding example, example, the sum divided by the modulus modulus value must result result in a zero remainder to pass the modulo check.

|

For example, if the field to be checked is:

|

4,3,6,6,2,2 .

1 2 3 4 5 2

| |

where the last digit (2) is the check digit and the weights are:

|

 

|

and the modulus value is 5, the products resulting are:

4,3,6,6,2,2

1x4=4, 2x3=6, 3x6=18, 4x6=24, 5x2=10, 2x2=4

| |

and the sum of the resulting products are:

|

 

=4+6+1+8+2+4+1+0+4

|

 

=30

|

Then 30 divided by 5 equals 6, which has a zero remainder, and the field passes the modulo check.

|

IBM Modulo-Check Algorithm

|

The IBM modulo-check algorithm uses a modulus value of 10, the Product Digit Add format, and a series of weights, beginning with 1 for the least significant digit and alternating in a 1,2,1,2,1,2,... series.

| | |

The maximum maximum length of a field field to be modulo checked checked is 64 d digits igits incl including uding the ch check eck digit. digit. The check check digit must be the last digit.

3-38

4690 Store System: Programming Guide

 

 

|

UPC/EAN Modulo-Check Algorithm

|

|

The UPC/EAN modulo-ch modulo-check eck algorithm algorithm is used for checking checking pric price e fields on the bar code lab labels. els. The UPC/EAN modulo-check algorithm multiplies each digit of the field to be checked by its assigned weight. The 10’s position value of each product is then added to that product if the transform sign is plus; or subtracted subtra cted from that product product if the transform transform sign is minus minus.. If no transfor transform m sign is specifie specified, d, the produc productt is left unchanged. unchanged. The unit’s position position value of each each transformed transformed product product is added to the check val value ue

| |

accumulation. After the accumulation. the check value accumul accumulation ation is complete, complete, it is divided by the m modulus odulus.. If there there is no remainder from the division, the check is complete with no error.

|

For example, if the field to be checked is:

| | |

4 2 5 0 9 9

| |

where the first digit (4) is the check digit, and the defined weights are:

|

 

|

and the modulus value is 11, the products values are:

| | | | | | | | | | | | | |

   

+7,-2,2,+3,-6,+4

4x7 22xx2 5x2 0x3 0x 9x6 9x4

= = = = = =

28 4 10 0 54 36

The transformed products are:

 

28+2 4-0 10 10 0+0 54-5 36+3

= = = = = =

30 4 10 10 0 49 39

The accumulated check value is:

0+4+0+0+9+9 = 22

| |

Then 22 divided by 11 equals 2, which has a zero remainder, and the field passes the modulo check.

|

Functions Your Application Performs

|

An application program can perform the following functions with the I/O processor:

| | | | | |

       

        

Load the input sequence tables. Wait for accumulated input. Read accumulated operator input. Allow or disallow operator input. Obtain Obta in status. status. Preload input sequence data via WRITE Statement ( Enhanced Full-Screen only )

|

Loadin Loa ding g the Inp Input ut Seq Sequenc uence e Tabl Tables: es: Befo Before re yo you u ob obta tain in ac acce ces ss to the the I/O I/O proc proces esso sorr, you you mu must st

| |

load the input sequence sequence tables tables into memory using using a LOAD statement. statement. The input state tab table le is required, required, and the label format table and modulo-check table are optional.

 

3-39

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

|

Access Acc essing ing tthe he I/ I/O O Pro Process cessor: or: Us Use e the the OPEN OPEN state tateme ment nt to ga gain in ac acce cess ss to the the I/O I/O proc proces esso sorr

|

|

driver, specifying the parameters for the maximum buffer size and the maximum number of buffers the driverr can use to queue input sequence drive sequences s to the applicatio application. n. The buffer size size must be large enou enough gh to contain contai n the largest input input sequence sequence that can be generat generated ed accord according ing to the input state tab table. le. See “Receiving “Rece iving Data” on page page 3-41 for the format format of the input sequence sequence data.

|

Use the CLOSE statement statement to end communication communication with with the I/O processor. processor. The CLOSE func function tion locks the

|

I/O processor and discards any data available.

|

Preparing Prepari ng to Re Receive ceive D Data ata from the I/ I/O O Proce Processor: ssor: Th The e I/O I/O proc proces esso sorr ca can n be lo loc cke ked d or

|

|

unlocked. unlock ed. In the locked locked stat state, e, da data ta ca canno nnott be re read. ad. In the the unl unlock ocked ed st state ate,, data data can b be e rea read. d. Fol Followi lowing ng an OPEN statement, statement, the I/O processo processorr is unlocked unlocked and in state state ID number 1. You shou should ld always build build your input state table so that state 1 is a valid state and is the initial state you expect the terminal to be in, following an OPEN statement issued to the I/O processor.

|

Overvi Ove rview ew of Op Operat erator or Inp Input ut Fl Flow: ow: Fo Follllow owin ing g an OP OPEN EN stat statem emen ent, t, the the I/O I/O proc proces esso sorr is unlo unlock cked ed

|

and state state 1 is set. The operator operator can then then enter data. The fol following lowing steps steps de describe scribe the flow of oper operator ator input through the I/O processor and to the application:

| |

| |

| | | | | | | | | | | | | | | | | | |

1. Operator Operator input consist consists s of data (optiona (optional) l) and function function codes. codes. Input from from the key keyboard board c consists onsists of data keys and function function keys. keys. Label input input from readers readers and scanners scanners gener generates ates data and func function tion codes separated into fields according to the label format table. 2. The I/O processor gets one of the buffers allocated for operator input sequences. 3. The I/O processor receives the data and function codes and processes them accor according ding to the definition definiti on of the state and and function code code in the input input state table. table. The input se sequence quence ta tables bles tell the I/ I/O O processor where to place the input fields in the driver buffer. 4. As you enter function codes, different state IDs can be set according to the action defined in the input state table. table. Each d differen ifferentt state can alter alter the the allowed allowed input input sequenc sequence. e. Each function function code can a also lso alter the allowed input sequence by defining mutually exclusive function codes. 5. When you enter a function code that is a motor function code, the system queues the buffer that holds the current input sequence information to the application. 6. The motor function function code indicates indicates if input can can continu continue. e. If the acti action on of the mo motor tor function function cod code e is to remain in the current state or set a new state, operator input remains unlocked, and input can continue. If the action is to lock the I/O processor, continue. processor, inp input ut cannot occur occur until the applic application ation unlo unlocks cks the I/O processor. 7. The application can wait for operator operator input, read the input sequence buffer, and unlock the I/O processor as described in the following sections.

|

Waitin Wai ting g for Rec Receiv eived ed D Data: ata: You You can use a WAIT statem tement to wait for data to be avail ila able from

|

the I/O processor processor.. In many cases cases you need to wait wait for data fr from om multiple s sources ources such such as the I/O processor proce ssor and the magnetic magnetic stripe stripe reader (MSR). (MSR). The WAIT statement statement allows you to wait for inp input ut from multiple devices devices.. The system system uses a timer to to monitor the length length of time that it has has not recei received ved data. When valid data is available from the I/O processor, the system runs the statement following the WAIT. When you are waiting on feedback from multiple devices, use the EVENT% statement to determine if the I/O processor is the device responding to the WAIT.

| | | | |

| | | |

If an error occurs during WAIT (suchsequence, as uence, keyboard the system gives control to your ON ERROR routin routine. e. Errors Error s that occura in the input seq which whioffline), ch you defined to be pas passed sed to your appli application, cation, do not cause entry entry to the ON ERROR routine. routine. The system system passes thes these e errors to you in the inpu inputt sequence buffer queued to your application.

3-40

4690 Store System: Programming Guide

 

 

|

Receiv Rec eiving ing Data Data:: An input sequence buffer consists of a header field followed by up to 10 function

code/data fie code/data fields. lds. ASCII q quotatio uotation n mark marks s enclose enclose each each field, field, and and ASCII ASCII commas commas separate separate each ffield. ield. The | header field is 14 bytes long if the Enhanced Full-Screen functions are not being used or 26 bytes long if | the Enhanced Enhanced functions functions are being used. used. The header fi field eld contains contains the following inf informatio ormation: n:

|

| | | | | | | | | | | | | | | |

                   

         

State ID that began the input sequence Current state ID Input device source (last contributing device if input was from multiple devices) Manager’s key status Keyed label status Last function code received Error associated with the last function code Tab order of the last active input field (Enhanced Full-Screen mode only) Cursor Position ( Enhanced Full-Screen mode only) Number of input fields in the sequence (Enhanced Full-Screen mode only)

Note: If you specify the double CLEAR usage in the common information, the state ID that began the input sequence is the last state specified as one that begins an input sequence for which the application issued an UNLOCKDEV. UNLOCKDEV. Otherwise, Otherwise, the state ID that began the inp input ut sequence sequence is the last state for which the application application issued issued an UNLOCKDEV. UNLOCKDEV. Thus, if you spec specify ify double CLEAR CLEAR usage, the application application can issue UNLOCKDEVs (to states that do not begin an input sequence), following its initial UNLOCKDEV for the sequence, and the state ID for the UNLOCKDEV is preserved.

Each function code/data field consists of the function code followed by any data associated with that | func function tion cod code. e. Refer Refer tto o the the IBM 4680 BASIC: Language Reference  for   for the details of the header field.

|

You can issue either a READ or a READ LINE statement to receive an input sequence queued to the | application. |

| | | | | | |

The READ statement statement reads each each field into the string string variables variables named on your READ sta statement. tement. You must specify specify 11 string variables variables if you are not using using the Enhanced Enhanced Full-Scr Full-Screen een functions. functions. The READ statement reads the header field into the first variable, and reads the function code/data fields into the variable corresponding to the relative position you specified for the function code in the input state table. Relative positions 1 through 10 correspond to variables 2 through 11 because the header occupies the first variable. variable. The READ statem statement ent removes removes the double quotes quotes around each each field and the comma between each field before placing the fields into your string variables.

If you issue a READ LINE statement, the statement places all fields in the input sequence in your string variable. variab le. The header header fi field eld is ffirst irst fo followed llowed by by 10 function function code/d code/data ata field fields. s. Enclos Enclose e each field in double separate them them with a comma. Your appli application cation must must parse the input seq sequence uence into separate separate | quotes and separate | fields as required. | |

|

Allowing Allow ing a and nd Di Disallow sallowing ing O Operator perator Input: Th The e UNLO UNLOCK CKDE DEV V stat statem emen entt unlo unlock cks s the the I/O I/O

|

processor. When the I/O processor processor. processor is unlocked, it can receiv receive e the keyboard, reader, reader, and scanner scanner input as specified specifi ed for the cur current rent state of of the terminal. terminal. You can also also specify a st state ate ID to be set and a PRIO PRIORITY RITY parameter. parame ter. The I/O processor processor has has two queues for op operator erator input: a normal normal queu queue e and a priori priority ty queu queue. e. You control which queue the operator input is placed in by setting the active queue to either the normal or priority prior ity queue. An UNLOCKDEV UNLOCKDEV statement without without the PRIORITY parameter parameter set sets s the normal queu queue, e, and UNLOCKDEV UNLOCKD EV with PRIORITY sets the priority priority que queue. ue. One use for the priority priority queue is when ope operator rator input is queued queued and an error is detected. detected. You might want to receive receive new input from from the operator be before fore

| | | | | | | |

reading readin g the queued input. input. In this case, you could could set the priority priority queue and commu communicate nicate with the operator. You could then return operator. return to the normal normal queue with an UNLOCKDEV UNLOCKDEV statement statement to read the queued | input and continue normal processing.

 

3-41

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

| | |

The LOCKDEV LOCKDEV statement locks locks the I/O processor. processor. When locked, locked, the I/O proces processor sor rejec rejects ts all keyboar keyboard, d, reader, reade r, and scanne scannerr input. If you specify the PUR PURGE GE parameter parameter on an LOCKDEV statement, statement, all data queued to your your application application is discarded. discarded. The data is discarded discarded from the currentl currently y active queue queue..

|

The PUTLONG statement can be used in place of UNLOCKDEV when additional function not provided by UNLOCKDEV is needed. This allows a particular field within a state to be made the current field. PUTLONG is typically used in conjunction with the WRITE statement.

|

Determining Determ ining Status of the I/O Process Processor: or: Use Use the the GETL GETLON ONG G stat statem emen entt to dete determ rmin ine e the the

|

following I/O processor status:

| |

| | |

   I/O processor locked or unlocked    Normal or priority queue    If PURGE was specified on the last LOCKDEV statement executed

|

Preloa Pre loadin ding g Inpu Inputt Sequ Sequenc ence e Data: An ap appl plic icat atio ion n can can us use e the the WRITE RITE St Stat atem emen entt ( En Enha hanc nced ed

|

|

Full-Screen Full-S creen mode mode only ) to preload input input sequence data. data. This is useful whe when n an applicati application on reads an input sequence, sequence, detects detects an error, error, and needs the operator operator to correct correct the error error.. The I/O Proces Processor sor place places s the input sequence into its internal input sequence buffer, which is where complete, validated fields are assembled assemb led into an input sequence. sequence. The I/O Processor Processor assum assumes es that data in the buffer is vali valid. d.

| |

Data written the must I/O Processor be ofdefault the same read from the I/O Processor. In particular, thetoyou be sure tomust precede dataform withas thedata field's function code.

|

The WRITE statement statement also helps the application application perfor perform m error recov recovery. ery. For example example,, if the applica application tion detects something wrong with the data in one of the fields of a received input sequence, the following produces a look and feel similar to the I/O Processor’s recovery of data validation errors.

| |

| |

|

                      

| |

     

| | | | | | |

1. Clear the field in error from the received input sequence. 2. Be Beep ep.. 3. Display an operator guidance message. 4. Write the problem field’s data to the video display using current field attributes. 5. LOCATE the cursor appropriately. 6. WRITE the input sequence back to the I/O Processor. 7. PUTLONG to the I/O Processor Processor (des (described cribed below). below). The argume argument nt to PUTLONG shou should ld specify specify:: - The The stat state e to unlo unlock ck tto. o. - That iinput nput ffields ields a are re not not to be be initialized initialized.. - Tha Thatt the field field in error error is is to be cu curre rrent. nt.

|

(If I/O Processor style error correction is not desired, steps 1, 4, and 5 are not required, and step 7 should allow initialization of input fields.)

|

From the operators point of view, this is what occurs (if all steps are implemented):

|

| | | | | | |

         

    

1. Data is keyed into several fields on the video display, then a motor key is pressed. 2. The terminal beeps. 3. A message is displayed indicating a problem with one of the fields. 4. The field in error is current, and is displaying residual keyed data. 5. The operator enters the correct data. The first key pressed causes the residual data to be cleared from the display display and the newly newly keyed keyed data to appear appear in its place place.. This is the sam same e way that the operator corrects errors detected via the I/O Processor’s data validation.

Note that all of the fields that were not in error are still displayed and they do not need to be re-keyed. | The operator may tab to them and edit them as usual. |    6. The operator presses a motor key, and the corrected input sequence is queued to the application. |

3-42

4690 Store System: Programming Guide

 

 

| | |

WRITE Pro WRITE Proces cessin sing: g: Input sequences written to the I/O Processor must be of the same form as input sequences sequen ces read from from the I/O Processor. Processor. A write to the I/O Process Processor or always causes causes the I/O Proce Processor ssor to lock and any residual data in the input sequence buffer to be cleared.

The I/O Processors input sequence buffer has fixed size slots for each relative position possible with the input state table. Each slot is of the size required required to hold the func function tion code and data data of the longest | loaded input | input field defined defined for that relative relative position position anywher anywhere e in the input state table. An application application may write any

|

|

length data up to the slot length.

If an application attempts to write field data that is too long for a slot, the data is truncated to the slot length. It is possible to write field data of a length greater than the input field length of the current state. | |

An application may write fewer fields to the I/O Processor than an input sequence for the loaded input sequence ce table would dictate. dictate. In this case, the I/O Proc Processor essor fills its input input sequen sequence ce buffer with as many | sequen | fields as were provided. Any remaining slots are left empty. |

An application may write more fields to the I/O Processor than an input sequence for the loaded input | sequen sequence ce table would dictate. dictate. In this case, the I/O Proc Processor essor fills its input input sequen sequence ce buffer as usua usuall and | ignores the extra data. |

The application is required to provide a status field (the first field) in a write to the I/O Processor. Although | requir required, ed, the data in this status field field is not actually used used by the I/O Processor. Processor. Any string, string, even a null | string, can be specified. |

|

Coding the WR Coding WRITE ITE Statem Statement ent:: The following 4680 BASIC code fragments illustrate how to write input sequences to the I/O Processor:

| | | | | | | | | |

Example 1: ! ! This is how to WRITE an input sequence that ! was read via READ LINE. ! The format string "PIC(&)" is required to prevent ! BASIC from surrounding the input sequence with an ! additional pair of double-quotes. ! STRING INPUT.SEQUENCE$ INTEGER*2 IOP%

| | | | |

IOP% = 20 READ#IOP;LINE INPUT.SEQUENCE$ . . WRITE FORM "PIC(&)";#IOP%;INPUT.SEQUENCE$

| | | | | | | | |

Example 2: ! ! This is how to WRITE an input sequence that ! was read via READ. ! STRING STATUS$,A$,B$,C$,D$,E$,F$,G$,H$,I$,J$ STATUS$,A$,B$,C$,D$,E$,F$,G$,H$,I$,J$ INTEGER*2 IOP% IOP% = 20 READ#IOP%;STATUS$,A$,B$,C$,D$,E$,F$,G$,H$,I$,J$

| | |

.. WRITE#IOP%;STATUS$,A$,B$,C$,D$,E$,F$,G$,H$,I$,J$

|

 

3-43

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

|

Non-Full-Scr Non-Fu ll-Screen een Exampl Example: e: The code shown here writes a message to the display, loads an input

|

sequence table, waits for scanner input, checks the input, and writes it in readable form to the display.

| | | | |

| | | | | | |

! This routine requires that an input sequence table be created. ! In this example the table is loaded from the fixed disk in drive C. ! The table should have at least one function code, which is a motor ! function code. ! The relative position should be 3, 2, or 1 for this routine to ! display the input. %ENVIRON T ! Declare integers. INTEGER*2 DISPLAY INTEGER*2 OPERIN DISPLAY = 1 OPERIN = 2 ON ERROR GOTO ERR.HNDLR ! Open the display. OPEN "ANDISPLAY:" AS DISPLAY ! Write a greeting. CLEARS DISPLAY WRITE #DISPLAY; "I/O PROCESSOR SAMPLE" WAIT;2000 ! Open the I/O processor and load an ! Input sequence table. LOAD "ISTBL=R::C:[email protected], FMTTBL= R::[email protected],MODTBL=R::C:[email protected]" OPEN "IOPROC:" AS OPERIN BUFFSIZE 70 ! Prompting is displayed by the I/O processor ! as specified in the input sequence table. KBWAIT:

| | | | | | | | | | | | | | | | | | | |

! Wait for input. WAIT;5000 ! You would normally test ! for a timeout condition. ! Read the available input data. READ #OPERIN; IOPDATA$,B$,C$,D$,E$,F$,G$,H$,I$,J$,K$ IOPDATA$,B$,C$,D$,E$,F$,G$,H$,I$,J$,K$ ! Display 14 status bytes. CLEARS DISPLAY WAIT;2000 WRITE #DISPLAY;"IOP=", IOPDATA$ WAIT;2000 ! Check byte 14 for I/O processor flagged edit condition. ! Return for reentry by user if error in data. IF MID$(IOPDATA$,14,1) " " THEN GOTO KBWAIT ! Display three of the relative variables. CLEARS DISPLAY WRITE #DISPLAY;"B=", B$ WAIT;2000 CLEARS DISPLAY WRITE #DISPLAY;"C=", C$

| |

WAIT;2000 CLEARS DISPLAY

| | | |

WRITE #DISPLAY;"D=", D$ WAIT;2000 CLEARS DISPLAY WRITE #DISPLAY; "END OF SAMPLE"

| | | | | | | | | | | | | | |

|

CLOSE DISPLAY, OPERIN 3-44

4690 Store System: Programming Guide

 

 

| | | | | | | | | |

! STOP ERR.HNDLR: ! Prevent recursion. ON ERROR GOTO END.PROG ! Determine error type ! and perform appropriate ! recovery and resume steps. END.PROG: STOP END

|

Additional I/O Processor Features

|

Data Da ta Ed Edit itin ing g Data input fields are considered to be one-dimensional arrays up to 80 characters long.

|

|

They can start on one row and continue on the following rows, but in terms of data entry and cursor movement, movemen t, only left and right movement movement is allowed. allowed. When the last position position of a row is reache reached, d, the next position positio n is the first position of the next next row. The positio position n that precedes precedes the first posit position ion of a row is the last position position of the previous previous row. For cursor cursor movement movement keys, the cursor cursor wraps from the las lastt position of a field to the first position. position. For data entry entry keys, wraparound wraparound does does not occur— occur—the the curso cursorr remains at the last position positio n of a field when the field field is full and automatic automatic ta tab b is not in effect. Entry of mor more e data results results in an error tone.

|

   Da Data ta keys keys

| | | | |

| | | | | | | | | |

The data keys insert insert characters characters and move move the cursor to the right right within the current current field. The space  is considered a data key that inserts a blank. bar is bar If the field is displayed in reverse order of entry, the cursor stays in the same position, data is inserted in that position, and previously entered data moves to the left.    Backspace key The Backspace Backspace key  key moves the cursor to the left and sets the moved-from position to null if no data follows it, it, or to blank if data follows follows it. The cursor cursor stops at the first first posi position tion of the field field.. If the field is displayed in reverse order of entry, the cursor stays in the same position and the data to the left of that position, if any, is shifted to the right to remove the data previously at the cursor position. positio n. If there is no data data located to the the left of the curs cursor or posit position, ion, the data at th the e cursor p position osition

|

becomes null.

| | | | | | | | | |

   Cursor right key The cursor cursor right key moves moves the cursor to the right right if there is previou previously sly entere entered d data to the right. If there is no previously entered data to the right, or if the end of the field is reached, wraparound to the first position of the field occurs. If the field is displayed in reverse order of entry, wraparound occurs to the position preceding the leftmostt character leftmos character previou previously sly entered. entered. You can can enter data re regardl gardless ess of the the cur cursor sor po position. sition. If the cursorr has been moved from curso from the rightmos rightmostt position, data data is inserted at the curs cursor or positio position. n. Data to the right of that that cursor position position is not not shifted. Any data at or to the the left of that cur cursor sor posi position tion is shifte shifted d left.

   Cursor left key

|

The cursor cursor left key moves moves the cursor cursor to the left if it is not at the the beginni beginning ng of the field. If it reaches the the

| |

beginning of the field, wraparound occurs to the rightmost position in the field that contains previously entered data. If there is no previo entered previously usly enter entered ed data, the curs cursor or remain remains s at the first position of the fiel field. d.

|

If the field is displayed in reverse order of entry, wraparound occurs from the leftmost position

containing previously entered data to the rightmost position of the field.

|

 

3-45

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

| | | | | | | | | | |

   Insert key The Insert Insert key  key is a toggle toggle.. Data k keys eys follo following wing the the Insert Insert key  key (until it is pressed again) are inserted into the field at the cursor position, the cursor moves to the right, and data to the right of the cursor’s previous position is moved to the right. If the field is displayed in reverse order of entry, the Insert key has no effect—data to the left of the cursor is moved to the left as data is inserted at the cursor position.    Delete key The Delete Delete key  key causes causes the data at the cursor cursor position position to be deleted. deleted. All data to the ri right ght of the curs cursor or is moved to the left left to occupy the the vacated position position.. The cursor cursor remain remains s in the same pos position. ition. If the field appears in reverse order of entry, data to the left of the cursor is moved to the right to occupy the vacated position.

|

Note: The cursor up, cursor down, PgUp, PgDn, Home Home,, and End End keys  keys are processed as any other configurable function keys.

|

The e I/O I/O Customizatio Custom ization n of Message D Display isplay ( En Enhanced hanced Fu Full-Scr ll-Screen een mode onl only y ): Th

| |

Processor writes Processor writes data to the display display in three general categories: categories: state promp promptt messages, err error or message messages, s, and display-as-k display-as-keyed eyed data. If the enhanced full-scree full-screen n support is not selected, selected, this data is always written to the top left 2x20 area of the video video display. If the enhanced full-scr full-screen een suppo support rt is selected an and d the state

| |

definition specifies that the display fields are defined in the function code definitions, the data written by the I/O Processor may be customized in the following ways:

|

   Location

|

|

| | | | | | | | | | | | | | | | | | | | | | | |

You specify the row and column of the upper left character of the message area. In the case of a bordered message, this would be the location of the top left corner character.

   Width of display area You may specify the width of the display area. If a border was specified (see below), this width includes include s the 2 positions occupied occupied by the left and right right border ch characte aracters. rs. The specif specified ied displa display y width may be narrower or wider than the actual message. If it is narrower, then the message text is clipped to the display width (if bordered, it is clipped to within the borders). If the display width is specified as being wider than the message, then the unwritten area of the display width is written with blanks.    Border You may specify specify that a border surrounds surrounds the message. message. You specify specify the border characte characters rs as eight hex values for the eight parts of the border: top left corner, top, top right corner, left, right, bottom left corner, bottom, bottom right corner.

   Attributes (colors, blink, etc.) You may specify specify a hex attribute attribute byte to be be used for the message message area. area. This byte mu must st be define defined d in the Feature Feature A attribute format format of the video video drive driver. r. See the video video section in th the e 4680 Basic Language  Reference  for   for a description of the Feature A attribute format.

   Single or Double Line Formatting You may specify whether the message text is to be displayed in a 2x20 format or a single line format. Although messages are no longer necessarily displayed in a 2x20 format, the method of defining this data remains unchanged. That is, the IST Build Utility presents you with a 2x20 box in which to specify the message text. If the single line format is selected, the I/O Processor concatenates the line-1 text and the line-2 text such that there is exactly one blank between the last non-blank character preceding column 20 and the first non-blank non-blank character character at or after after column 20. This is so that messages messages formatted formatted for 2x20

display appear correctly without requiring redefinition.

|

3-46

4690 Store System: Programming Guide

 

 

| | | | | | | | | | | | | |

   Centering You may specify specify that the message message text text is to be centered centered within the defined defined dis display play are area. a. The centering option is ignored for display-as-keyed messages and 2x20 formatted messages. Note: Customization information is specified in the Common Information section of the State Table. There is one specification for prompt messages, one specification for error messages, and one specification for display-as- keyed data associated with non-full-screen states ( for full-screen states, there are separate separate display-asdisplay-as-keyed keyed spec specificati ifications ons for each field in each full-screen full-screen state). The prompt and error message message specifications specifications are in effect for all states. The display display-as-k -as-keyed eyed speci specification fication is in effect for all non-full-screen states. The I/O Processor Processor does does not save save and restore restore the area areas s of the screen screen to which it wri writes tes data. It is the application’s applic ation’s responsib responsibility ility to clear any undesirable undesirable residu residual al data from the screen. The I/O Processo Processorr writes to the the display accordin according g to information information in the State State Table. The State Table Table part of the application and the executable part of the application should be developed to work in harmony with each other.

|

If the display-as-keyed area is a 2x20 box at the top left of the display with default attributes and with no border, no change to this area occurs until the operator starts keying in a non-full-screen state (no change chang e from the behavior when enhan enhanced ced full-screen full-screen support support is not used). If the display-as display-as-keyed -keyed area is anything other than the default 2x20 box, it is initialized when an unlock to a non-full-screen state occurs occurs (the same behavior behavior as fields fields of a full-screen full-screen state). This implem implementatio entation n allows you to

| |

add full-screen function to that an application that was but previously preserve behavior of parts of the application were not changed, improvenon-full-screen the behavior ofand parts that arethe changed.

|

Of concern to the application programmer is the fact that all unwritten positions of the defined display area are written with blanks in order for their attributes to be visible. If the display-as-keyed area and the prompt area are both configured to occupy the same 2x20 area on the screen, the display-as-keyed area will overlay the prompt.

| | | |

| | | | | | | | | | | | |

As an example, consider implementing a 2x30 area to be used for both prompts and display-as-keyed data. You could configure configure the prompt prompt messag messages es as single-line, single-line, 30 characters characters wide wide,, originat originating ing at row 1 column 1, and the display-as-keyed messages as single line, 30 characters wide, originating at row 2 column column 1. The displaydisplay-as-ke as-keyed yed area area no lo longer nger interfe interferes res wit with h the pr prompt ompt ar area. ea. Note that that for this this case, the asterisks defining the location of keyed data must not be placed beyond column 10 of the 2nd line, as this is offset 30 into the defined display area. Any data that spills out of the defined display area is clipped (not displayed). An Example: Example: Implementing Implementing a Shared Shared Message Message Line: Assume that you are using a 16x60 display, and that you want to use the bottom bottom line of the video for both appli application cation and I/O Processor Processor messages messages.. Using the IST Build Utility, define the error messages location and attributes as follows:

|

   Display at row 16, column 1.

|

   Format for single line display.

|

   The display area is 60 characters wide.

|

   The text is to be centered within the display area.

| | | | | | |

When the I/O Processor detects an error, it displays the message text on the defined message line. There is a problem here, here, however. however. The error error message is not cleared cleared from the mess message age line after the er error ror condition conditi on has been corrected. corrected. The solution solution is to define a blank message message to be displayed when when a function code is received without error. Use the IST Build utility to define this message for each function code definition definiti on (it is necessary necessary to type spaces spaces over the underscore underscores s to create a blank mess message). age). The function function code for an input field field is received when when a tab or motor key is pressed. pressed. This is a reason reasonable able time to clear the message.

 

3-47

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

|

The application application is free to write to the same message message line. line. To prevent prevent the I/O Processo Processorr from writing to the message line at the same time as the application, the application should ensure that the I/O Processor is locked.. The application locked application does does a PUTLONG to the video video display display to set the colo color, r, then a LOCA LOCATE TE to row 16 column 1, then then a WRITE to the video. video. Since the operator operator does does not need need to be aware of the s source ource of th the e message, the application and the I/O Processor form a more integrated solution than that which is possible without using the enhanced full-screen support.

|

When en the the enha enhanc nced ed Large Input Input Sequ Sequences ences (E (Enhanced nhanced Full-S Full-Screen creen mo mode de only) only):: Wh

| | | | |

| | | | | | | | | | | | | | | | | | |

full-screen sup full-screen support port is not selected, selected, the maximum maximum number of input fields fields per state is limited to 10 (not including includ ing the status field). field). The maximum has be been en raised to 127 when when enhanced ful full-scr l-screen een suppo support rt is selected. select ed. Relativ Relative e positions positions 1 through through 127 ma may y be defined. defined. The actual actual number number of relati relative ve positions positions th that at are received by an application on a read of the I/O Processor depends on the highest relative position defined define d for any state in the input sequence sequence table table.. If the highest numb number er define defined d is 10 or less, then there will be 10 relative relative positions positions in the input sequence sequence (not including including the status field). field). Otherwise, Otherwise, the number of relative positions in the input sequence will be equal to the highest relative position defined for any state. This is the number of relative relative posi positions tions that an application application will re receive ceive for EACH read read of the I/O Processor, regardless of which state is current. Specifying too few or too many variables on a READ FORM statement is an error. For this reason, READ LINE is now the recommended method of reading from the I/O Processor. The 3-character ASCII representation of the number of relative positions contained in the input input sequenc sequence e is av available ailable in the status status ffield. ield. See Status Field Extensions  below   below ffor or det detail ails. s. The The buffer size specified in the BASIC OPEN statement previously limited the input sequence buffer size to 200 bytes. This limit has been removed. There is no artificial limit imposed on the buffer size. EXAMPLE 1: An input input sequence sequence table defines 3 states. states. State 1 defines function codes with rrelative elative positions positio ns 1,2,3,4, 1,2,3,4, and and 5. State 2 d defines efines functio function n codes codes with relative relative positio positions ns 1,6, and 9. State 3 defines function codes with relative positions 3 and 4. On each read of the I/O Processor, regardless of which state is current, the I/O Processor will provide an input sequence containing 10 relative positions (not including the status field).

|

EXAMPLE 2: An input input sequence sequence table defines 3 states. states. State 1 defines function codes with rrelative elative positions positio ns 1,2,3,4, 1,2,3,4, and and 5. State 2 d defines efines functio function n codes codes with relative relative positio positions ns 1,6, and 9. State 3 defines function codes with relative positions 9,10,11,12 and 13.

|

On each read of the I/O Processor, regardless of which state is current, the I/O Processor will provide an

|

input sequence containing 13 relative positions (not including the status field).

| |

Magnetic Stripe Reader Driver This section describes the single-, dual-, and three-track magnetic stripe reader drivers and provides guidelines for using them.

Characteristics of the Single-Track Magnetic Stripe Reader The single-track MSR has the following characteristics:

 The single-track MSR attaches to the top of the keyboard and connects to the keyboard by a cable.

3-48

4690 Store System: Programming Guide

 

 

 The MSR can read data encoded on a card (credit card or badge) as the card is passed through a slot in the reader. reader. The single-track single-track MSR re reads ads track 2 data as specified specified in the follo following wing standa standards: rds:  – “The American National Standards Institute Insti tute (ANSI) (ANSI ) Specifications Specificati ons for Magnetic-Stripe Encoding for Credit Cards”, ANSI X4.16-1983  – “The American National Standards Institute Insti tute (ANSI) (ANSI ) Specifications Specificati ons for Credit Cards”, C ards”, ANSI X4.13-1983.  The data available to your application consists of the account number field, a separator character, and a discretion discretionary ary data field. The accoun accountt number number can can be be a maximum of 19 charac characters. ters. The discretionary discretionar y data field can be up to 36 characters. characters. The total number number of characters characters occup occupied ied by the account number field, the separator character, and the discretionary data field cannot exceed 37.

Characteristics of the Dual-Track Magnetic Stripe Reader The dual-track MSR has the following characteristics:

 The dual-track MSR attaches to the top of the keyboard or connects directly to slot 5B on the back of the base unit. are two models available available:: one reads reads tracks 1 and and 2 data and the other other reads tr tracks acks 2 and 3  There are data. returned data consist consists s of a buffer of 144 bytes. bytes. The first first 37 bytes of data fr from om track 2 are in th the e  The returned same format as the single-track MSR (the 37 bytes are padded with X '00' cha  charac racter ters s if nee needed ded). ). The data followedan byerror one-byte field data in the first 37 bytesfrom (or Xtrack earror on tr track ack 2). containing Following Following the thatlength field isofathe one-byte oneactual -byte fie field ld with the len length gth 'FF'2 toisindicate of the data from track 1 or 3 (or X 'FF' for error) followed by 105 bytes of data from track 1 or 3 (the 105 bytes are padded with X '00' if needed).  When receiving data, the dual-track MSR formats track 1 data as alphanumeric using only the lower 6 bits of each byte. byte. The maximum maximum number number of data ch charact aracters ers on track 1 is 80 chara characters. cters. Track 3 data is numeric numeric only and has has the same format format as track 2 binary binary coded coded decima decimall (BCD). The maxim maximum um number of data characters on track 3 is 105 characters. X'FF' in either length length field is the same same as retur return n code 80A5000B 80A5000B for the the track with the the error error.. The 80A5000B 80A500 0B code is retur returned ned if both tracks contain contain read errors. errors. If an error is encountered encountered on tra track ck 2, and track 1 or 3 is valid, the track 2 data starts with 1 byte of X '00' followed by the separator X '0D' then padded with X'00' to 37 bytes.

Characteristics of the Three-Track Magnetic Stripe Reader The three-track MSR has the following characteristics: The three-track MSR can read all or any combination of the three tracks.

 Track 1 data is alphanumer alphanumeric. ic. The driver returns returns a maximum maximum of 98 data characters characters from track track 1. Track 2 data is numer numeric ic only. The driver drive r returns a maxi maximum mum of 46 data characters charac ters from tra track ck 2.  However, if operating in single- or dual-track mode, the maximum number of data characters returned is 37. numeric only. The driver driver returns a maxi maximum mum of 139 data characters characters from from track 3.  Track 3 data is numeric

Data Formats and Error Reporting The data formats for the various MSR devices supported by the three-track MSR are:    Sin Singlegle-tra track ck MSR Single-track Singletrack MSRs support support reading reading data from tra track ck 2 only. The retur return n code from the READ state statement ment

provid pro vides es the the act actual ual n numb umber er of b bytes ytes read. read. See Form Format at 01 in in Figure Figure 3 1 o on n page page 3 5 51. 1.

 

3-49

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

If an error occurs, the first byte of the returned buffer contains a X '00', followed by the separator character X'0D'. The rema remaind inder er of th the e buffer buffer is pa padde dded d with X'00'    Dua Dual-tr l-track ack MSR  – Dual-track MSRs read data from track t rack 2 and either track 1 or track 3. The data is returned in a single buffer. buffer. The return return code of the READ s statemen tatementt prov provides ides the si size ze of the bu buffer. ffer. See Fo Format rmat 02 in Fig Figur ure e 3-1 3-1 on on pag page e 3-51 3-51..  – The dual-track MSR driver supports single-track emulation. The single-track MSR description applies when operating in this mode.  – The length field of each track contains the actual number of characters read from that track. t rack. If a read error occurs on either track, but not both, the length field for the track on which the error occurred has a value of X'FF', and the buffer is padded with X '00'. If a rea read d erro errorr occu occurs rs on both tracks, the return code from the READ statement is 80A5000B, and the entire buffer is padded with X'00'. Refe Referr to to the the IBM 4690 Store System: Messages Guide  for   for a description of the 80A5000B return code.    Thr Threeee-tra track ck MSR Three-track MSRs read data from all tracks. If the device is configured for single-track emulation (track 2 only), or as a dual-track device (tracks 1 and 2 or tracks 2 and 3), the amount and format of the data is identical to that previously described. The three-track three-track device device provides additional additional indiv individual idual track capacities capacities and capa capabilities bilities.. The various various for formats mats are are descr describe ibed d in Fi Figur gure e 3-1 on on page page 3-5 3-51. 1. Error reportin reporting g is done the same as with the dual-track dual-track MSR. If one or more, but not all, configured configured tracks report a read error, the length field for each track in error has a value of X 'FF', and the buffer for each track is padded with X '00'. If a read error error occurs occurs on all con configure figured d tracks, tracks, the ret return urn cod code e from the READ statement is 80A5000B, and the entire buffer is padded with X'00'. Refe Referr to the the IBM  4690 Store System: Messages Guide  for   for a description of the 80A5000B return code.

3-50

4690 Store System: Programming Guide

 

 

Format of the Data in the Applications Buffer

Format 01 - Single-track - Track 2 data returned retur ned T2 Data 37 bytes maximum

Format 02 - Multi-track - Track 2 data and Track 1 or 3 data retur ned T2 Data

T2 Len

Tn Len

Tn Data

37 bytes

1 byte

1 byte

n bytes

n = Track Track 1 or 3 (98 or 139 respectively)

Format 04 - Single-track - Track 1 data returned retur ned T1 Len

T1 Data

1 byte

98 bytes

Format 08 - Single-track - Track 3 data returned retur ned T3 Len 1 byte

T3 Data 139 bytes

Format 10 - Multi-track - Tracks 1 and 3 data retur ned T1 Len

T1 Data

T3 Len

T3 Data

1 byte

98 bytes

1 byte

139 bytes

Format 20 - Multi-track - All tracks data returned T1 Len

T1 Data

T2 Len

T2 Data

T3 Len

T3 Data

1 byte

98 bytes

1 byte

46 bytes

1 byte

139 bytes

Tn = track number

Fi Figu gure re 33-1. 1. Mult Multii-Tr Trac ack k Rea Reade derr Data Data Forma Formats  ts 

 

3-51

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Table 3-3 shows the applic applicable able formats formats of returned data as a function of MSR configuration. configuration. Table Tab le 3-3 3-3.. Applic Applicabl able e Format Formats s o off Retu Returne rned d Data  Data  Device Type

Configuration

Format

Number of Tracks

Which Tracks

Dual-Track

1

2

01

Dual-Track

2

1 and 2

02

Dual-Track

2

2 and 3

02

Three-Track

1

1

04

Three-Track

1

2

01

Three-Track

1

3

08

Three-Track

2

1 and 2

02

Three-Track

2

2 and 3

02

Three-Track

2

1 and 3

10

Three-Track

3

1, 2, and 3

20

Restrictions of Single- and Multi-Track MSRs Only one is allowed allowed per terminal. terminal. Mod1 and Mod2 terminal terminal pairs cannot cannot have diff different erent type types s of MSRs attached.

Functions Your Application Performs Your application program can perform the following functions with the MSR:

    

Allow or disallow data to be read from a card. Wait until data is available. Read card data. Determine data-allowed or data-disallowed status. Determine format of the data returned by the MSR.

Accessing the MSR Use the OPEN statement to gain access to the MSR driver. The CLOSE statement statement ends ends communication communication with with the MSR. CLOSE locks locks the MSR and dis discards cards a any ny data available.

Preparing to Receive Data from the MSR The MSR can be in two states, locked  states,  locked  and   and unlocked . In the the loc locke ked d st stat ate, e, d dat ata a ca cann nnot ot b be e read read.. In th the e unlocked unlock ed state, state, data data can be read. read. Initially Initially the MSR is in the locked state. You must must issue issue an UNLOCKDEV UNLOCKD EV statement statement to put the MSR in the unlocked unlocked s state. tate. After being being read by the MS MSR, R, data is available availa ble but not passed to the applicatio application n until a READ LINE statemen statementt is executed. If your applic application ation issues an UNLOCKDEV statement when the MSR has data available, the data is discarded.

3-52

4690 Store System: Programming Guide

 

 

The MSR changes from unlocked to locked when one of the following occurs:

 Valid data is read from a card.  Your application issues a LOCKDEV statement.  Your application ends communication with the MSR by a CLOSE statement. Issue the UNLOCKDEV statement each time you prepare to read data from the MSR.

Waiting for Received Data Your application application should should issue issue a WAIT statement statement to wait for data data available available from th the e MSR. The WAIT statement stateme nt allows the application application to wait for input input from multiple dev devices. ices. These devi devices ces include include a timer to indicate indicat e that no input was received received durin during g a specific time. When valid data data is available from from the MSR, the | stateme statement nt following the WAIT WAIT is executed executed.. Follow Following ing the WAIT, use the EVENT% EVENT% function to determine determine if available to be read read from the MSR. MSR. If an error occurs occurs du during ring a WAIT, c control ontrol is gi given ven to your ON | data is available ERROR routine.

 Receiving Receiv ing Dat Data a Issue a READ LINE statemen statementt to rreceive eceive data from from th the e MSR. READ LINE LINE is a synchron synchronous ous operatio operation. n. If valid data is available from the MSR, the READ LINE is completed, and the variable specified on the READ LINE statement statement contains contains the data. If an error occurs, occurs, control control is given to the ON ERROR routin routine. e. The driver driver validates validates the buffer size passed passed to it. If the buffer size is insu insufficien fficientt to handle all potenti potential al data for the active active configuration configuration,, the driver driver returns returns 80A50004. 80A50004. Refer to the IBM 4690 Store System: Messages  Guide   for for a detailed description of the 80A50004 return code. After good data is received, the MSR is locked.

Data Characteristics Common to all MSRs The data characters characters in the applicatio application’s n’s buffer ar are e in BCD format. Only the characters characters 0 thro through ugh 9 and a separator character separator character can appear appear in the buffer. buffer. Zero is 00H, nine is 09H, 09H, and the separato separatorr is 0DH. Parity checking checking and other other data used by the har hardware dware are not pa passed ssed to the application. application. The return return code from the READ LINE statement contains the amount of data returned. The characteristics specific to single-track or multi-track MSRs are:    Sin Singlegle-tra track ck MSRs The total number of bytes returned to the application cannot exceed 37.    Mul Multi-t ti-trac rack k MSRs  – The maximum maxim um number of data dat a characters on track 1 is 102.  – The maximum maxim um number of data dat a characters available to the appli application cation from track 2 is increased to 46 when operating operating a three-tr three-track ack device device in specif specific ic configuration configurations s (see Figure Figure 3-1 on pag page e 3-51) 3-51)..  – The maximum maxim um number of data dat a characters on track 3 is 103 for a dual-track device and 139 for a three-track device.

Disallowing MSR Data Issue the LOCKDEV LOCKDEV statement statement to prevent the MSR from rec receiving eiving card card data. If data is already ava available ilable when you issue the LOCKDEV statement, the data is discarded.

 

3-53

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Determining Status of the MSR Use the GETLONG statement to make the following determinations:

 The state of the MSR – Locked or Unlocked  Which of tracks 1 or 3 is connected for a dual-track MSR  The format of the returned data for a three-track MSR

Integerr Form Intege Format at for Single Single-Track -Track MSR D Driver: river: Th The e inte intege gerr repr repres esen ents ts info inform rmat atio ion n in the the form form RRRRRRLL. RR, RR, RR , and LL repr RRRRRRLL. LL represe esent nt one o off the four four bytes. bytes. The RRRRRR  bytes   bytes are reserved for system use. The LL bytes LL bytes represent the following state information: LL = LL = LL = LL =

0 if the MSR is unlocked. 1 if the MSR is locked.

Integerr Form Intege Format at for Dual-Tr Dual-Track ack MS MSR R Dri Driver: ver: The The inte intege gerr repr repres esen ents ts info inform rmat atio ion n in the the form form of RRSSRRLL, where RR, SS, RR , and LL each RRSSRRLL, LL each represe represent nt one of the the four by bytes. tes. The only differe difference nce between the single and dual-track data is SS  is  SS , which which represe represents nts the the st status atus informa information. tion. The RR  bytes   bytes are reserved for system use. The LL byte LL byte represents the following state information: LL = LL = LL = LL =

0 if the MSR is unlocked. 1 if the MSR is locked.

Integerr Form Intege Format at for Three-Tr Three-Track ack MS MSR R Dri Driver: ver: Th The e inte intege gerr repr repres esen ents ts info inform rmat atio ion n in the the form form RRSSFFLL, where RR, SS, FF , and LL each RRSSFFLL, LL each repre represent sent one one of the fou fourr bytes. bytes. The RR  bytes   bytes is reserved for system use. The LL byte LL byte represents the following state information: LL = LL = LL = LL =

0 if the MSR is unlocked. 1 if the MSR is locked.

The SS  byte   byte represents the following status information: Bit Bit Bit Bit Bit Bit Bit Bit

0 1 2 3 4 5 6 7

= = = = = = = =

0 0 1 1 1 1 0 0

RESERVED RESERVED Track 1 Enabled Track 2 Enabled Track 3 Enabled EC Level Response RESERVED RESERVED

3-54

4690 Store System: Programming Guide

 

 

The FF  byte   byte represents the following formatting information: Bit Bit Bit Bit Bit Bit Bit Bit Bit

0 1 2 3 4 5 6 7 7

= = = = = = = = =

1 1 1 1 1 1 0 0 1

Format 01 Format 03 Format 04 Format 08 Format 10 Format 20 RESERVED Dual-Track Device Three-Track Device

Single-Track MSR Example This example example reads data from from a card passed through through the MSR. The data is conve converted rted and disp displayed. layed. The example processes three card reads before ending.

%ENVIRON T ! Declare integers. INTEGER*2 DISPLAY INTEGER*2 MSREADER ! Convert data to display characters. FUNCTION CONVERT.TO.HEX$(THE.SUM%)  IF THE.SUM% > 9 THEN \  THE.SUM%=THE.SUM%+55\  EL  ELSE \  THE.SUM%=THE.SUM%+48  CONVERT.TO.HEX$=CHR$(THE.SUM%)  EXIT FUNCTION END FUNCTION DISPLAY = 1 MSREADER = 2 ON ERROR GOTO ERR.HNDLR ! Open the display. OPEN "ANDISPLAY:" AS DISPLAY ! Write a greeting and wait 2 seconds. CLEARS DISPLAY WRITE #DISPLAY; "MS READER SAMPLE" WAIT;2000 ! Open the magnetic stripe reader driver. OPEN OPEN "MSR "MSR:" :" AS MSR MSREA EADE DERR ! Loop and read three cards. FOR I% = 1 to 3  UNLOCKDEV MSREADER ! Display instructions.  CLEARS DISPLAY  WRITE #DISPLAY;"PASS A CARD THROUGH"  MSRWAIT: ! Wait for input 5 seconds.  WAIT MSREADER;5000 ! You would normally test for a timeout condition.input data. ! Read the available  READ #MSREADER; LINE MSRDATA$ ! Convert the input to characters that can be displayed

 

3-55

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

DISPL.DATA$ = " " ! Loop through the input data and convert ! each character.  FOR J% = 1 to LEN(MSRDATA$)   A$=MID$(MSRDATA$,J%,1) THE.SUM% = ASC(A$)   A$=CONVERT.TO.HEX$(THE.SUM%) DISPL.DATA$ = DISPL.DATA$ + A$  NEXT J% ! Display input data and wait 2 seconds.  CLEARS DISPLAY  WRITE #DISPLAY;DISPL.DATA$  WAIT;2000 NEXT I% CLEARS DISPLAY WRITE #DISPLAY; "END OF SAMPLE" CLOSE DISPLAY,MSREADER STOP ERR.HNDLR: ! Prevent recursion. ON ERROR GOTO END.PROG ! Determine error type and perform appropriate !END.PROG: recovery and resume steps. STOP END

Dual-Track MSR Example This example example reads data from from a card passed through through the MSR. The data is conve converted rted and disp displayed. layed. The example processes three card reads before ending.

%ENVIRON T ! Declare variables. INTEGER*2 DISPLAY INTEGER*2 MSR2.READER STRING MSR2.DATA STRING MSR2.DATA.TRACK2 STRING MSR2.DATA.TRACK13 INTEGER*2 L1,L2 DISPLAY=1 MSR2.READER=2 ON ERROR GOTO ERR.HNDLR ! Open the display. OPEN "ANDISPLAY:" AS DISPLAY ! Write greeting and wait 2 seconds. CLEARS DISPLAY WRITE #DISPLAY; "MSR2 SAMPLE" WAIT;2000 ! Open the MSR driver. OPEN "MSR:" AS MSR2.READER ! Loop and read 3 cards. FOR I%=1 TOMSR2.READER 3  UNLOCKDEV ! Display instructions.

 CLEARS DISPLAY  WRITE #DISPLAY; "PASS A CARD THROUGH ",I% 3-56

4690 Store System: Programming Guide

 

 

MSRWAIT: ! Wait for 5 seconds.  WAIT MSR2.READER;5000 ! You would normally test for a timeout condition. ! Read the available input data. READ #MSR2.READER; LINE MSRDATA$ ! Get the length of the track 2 data (255 indicates error). !L1=ASC(MID$(MSRDATA$,38,1)) Get the length of the track 1 or 3 data (255 indicates error). L2=ASC(MID$(MSRDATA$,39,1)) ! Process track 2 data. IF L1 = 255 THEN \   BEGIN ! Display error message.   CLEAR CLEARSS DISP DISPLA LAYY WRITE #DISPLAY; "TRACK 2 ERROR"   WAIT;3000   EN ENDIF \ ELSE \   BE BEGIN \ MSR2.DATA.TRACK2 = MID$(MSRDATA$,1,L1) ! Here you would convert the input to ! characters and display it.   ENDIF ! Process track 1/3 data. IF L2 = 255 THEN \   BEGIN ! Display error message.   CLEAR CLEARSS DISP DISPLA LAYY WRITE #DISPLAY; "TRACK 1/3 ERROR"   WAIT;3000   EN ENDIF \ ELSE \   BE BEGIN \ MSR2.DATA.TRACK13 = MID$(MSRDATA$,40,L2) ! Here you would convert the input to ! characters and display it.  NEXT ENDIF I% CLEARS DISPLAY WRITE #DISPLAY; "END OF SAMPLE" CLOSE MSR2.READER,DISPLAY STOP ERR.HNDLR: ! Prevent recursion. ON ERROR GOTO ERR.EXIT ! Determine error type and ! perform appropriate recovery ! and resume steps. ERR.EXIT: STOP END

 

3-57

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Three-Track MSR Example The following following example reads reads data from a card passed passed through through the MSR. The data is converted converted and displayed. displa yed. The example example processe processes s three cards cards be before fore ending. ending.

%ENVIRON T ! Declare variables. INTEGER*2 DISPLAY INTEGER*2 MSR2.READER INTEGER*2 L1, L2, L3 INTEGER*4 CONFIG,MSRTYPE,MSRFMT,MSRSTA STRING MSRDATA$,MSRDATA1$,MSRDATA2$,MSRDATA3$,DISPLINE$ STRING MSRSTA$ DISPLAY=1 MSR2.READER=2 ON ERROR GOTO PROGERR ! Open the display. OPEN "ANDISPLAY:" AS DISPLAY ! Write greeting and wait 2 seconds. CLEARS DISPLAY DISPLINE$="MSR3 SAMPLE" WRITE #DISPLAY; DISPLINE$ WAIT;2000 ! Open the MSR driver. OPEN "MSR:" AS MSR ! Get device information. CONFIG=GETLONG(MSR) ! Isolate device type. MSRTYPE=CONFIG AND 00008000H MSRTYPE=SHIFT(MSRTYPE,8) ! Here you would determine if operating with a dual-track ! or 3-track device. ! Isolate data format. MSRFMT=CONFIG AND 00007F00h MSRFMT=SHIFT(MSRFMT,8) ! Here you would determine the format of the data ! to be received. ! Isolate status. MSRSTA=CONFIG AND 00FF0000H MSRSTA=SHIFT(MSRSTA,16) ! Here you would determine the status of the device. ! Loop and read three cards. FOR I%=1 TO 3  UNLOCKDEV MSR  CLEARS DISPLAY  DISPLINE$= "PASS A CARD THROUGH",I%  WRITE #DISPLAY; DISPLINE$  MSRWAIT: ! Wait for 5 seconds.  WAIT MSR;5000 ! You would normally test for a timeout condition. ! Read the available input data. READ #MSR; LINE MSRDATA$ ! Get the length of the data on each track - this example ! assumes all three tracks are configured L1=ASC(MID$(MSRDATA$,1,1))

L2=ASC(MID$(MSRDATA$,100,1)) L3=ASC(MID$(MSRDATA$,147,1)) 3-58

4690 Store System: Programming Guide

 

 

! Process track 1 data. IF L1 = 255 THEN \   BEGIN ! Display track error message.   CLEAR CLEARSS DISP DISPLA LAYY DISPLINE$= "TRACK 1 ERROR" WRITE #DISPLAY; DISPLINE$   EN E\NDIF \ ELSE   BE BEGIN \ MSRDATA1$ = MID$(MSRDATA$,2,L1) ! Here you would convert the input to ! displayable characters and display it.   ENDIF ! Process track 2 data. IF L2 = 255 THEN \   BEGIN ! Display track error message.   CLEAR CLEARSS DISP DISPLA LAYY DISPLINE$= "TRACK 2 ERROR" WRITE #DISPLAY; DISPLINE$   EN ENDIF \ ELSE \   BE BEGIN \ MSRDATA1$ = MID$(MSRDATA$,101,L2) ! Here you would convert the input to ! displayable characters and display it.   ENDIF ! Process track 3 data. IF L3 = 255 THEN   BEGIN ! Display track error message.   CLEAR CLEARSS DISP DISPLA LAYY DISPLINE$= "TRACK 3 ERROR"   WRITE WRITE #DISPL #DISPLAY; AY;DIS DISPLI PLINE$ NE$   EN ENDIF \ ELSE \   BE BEGIN \ MSRDATA1$ = MID$(MSRDATA$,148,L3) ! Here you would convert the input to ! displayable characters and display it.   ENDIF NEXT I% CLEARS DISPLAY DISPLINE$= "END OF SAMPLE" WRITE #DISPLAY; DISPLINE$ CLOSE MSR STOP PROGERR: ! Prevent recursion. ON ERROR GOTO ERR.EXIT ! Determine error type and ! perform appropriate recovery ! and resume steps. ERR.EXIT:

STOP END  

3-59

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Printer Driver Model 2 This section describes the model 2 printer driver and provides information on accessing and using it.

 Characteristics Characteristics The printer is composed of a single bidirectional print head and two stations that provide three logical stations. The first station stations. station is called the customer customer receipt/doc receipt/document ument insert insert (CR/DI) station; station; the second is called the summary journal (SJ) station. You can use the CR/DI station station to print on a custome customerr receipt or an inse inserted rted document. document. When a docume document nt is used, it is positioned positioned between between the customer receipt receipt and the print print head. You cannot cannot use the CR/DI station to print on the customer receipt tape and a document at the same time. At each each station station,, the pr print int head head can can print print 38 cha charac racter ters s on a lin line. e. It prints prints ea each ch ch chara aracte cterr on a 7 x 8 dot matrix.. Three columns matrix columns of dots dots to the right of each character character are are res reserved erved for sp spacing. acing. The pr print int line for each station measures 380 dots across. One line feed advances advances the paper paper 11 vertica verticall dots. A printed line becomes becomes visib visible le to the operator at eith either er station after the printed line is advanced eight line feeds. Printing one line takes app Printing approxima roximately tely 0.5 seconds. seconds. One line feed takes takes approximately approximately 0.07 0.075 5 seconds in the CR/DI station and up to 0.158 seconds in the SJ station. The operating operating system supports supports logo printing, printing, characte characterr printing, and chec check k printing. This facilit facility y allows you to print any any dot in the middle 300 300 dots of a 380-dot 380-dot line at the CR/DI CR/DI station. Logos cannot cannot be pri printed nted at the SJ station. station. Partial Partial line feeds feeds are are avai available lable fo forr the CR/DI CR/DI station. station. Each partial partial lline ine fee feed d advan advances ces th the e line by one dot. You can print logos logos taller than 8 dots by using using partial line feeds feeds to print adjoin adjoining ing logo patterns. A default dot matrix matrix is supplied for many many of the available 25 256 6 code points. You can rede redefine fine the dot matrix configuration config uration for most most characte characters. rs. You cannot cannot d define efine horizontally horizontally adjacent adjacent dots. dots. The sy system stem p prints rints undefined undefi ned characte characters rs as a single dot. Refer to the IBM 4680 BASIC: Language Reference  for   for the definition of the default character set.

Functions Your Application Performs Your application program can perform the following functions with the printer:

     

Write characters to any station. Write all-points-addressable data to the CR/DI station. Control document insertion and sensing. Obtain Obta in status. status. Wait for outstanding print lines to print.

3-60

4690 Store System: Programming Guide

 

 

Accessing the Printer Use the OPEN statement statement to gain access access to the printer device device driver driver.. The name for eac each h print station is is:: CR: SJ: DI:

Cus Custo tom mer re receipt s sttati tio on Summary journal station Document iin nsert st station

Note: The colon is part of the name, and you must open each station before it will print. The CLOSE statement statement ends communicati communication on with a printer station. station. You must issue a CLOS CLOSE E statement for each print station to which your application has issued an OPEN.

Preparing a Line To Print You can specify specify the data to be printed on a line in one or more exp expressio ressions. ns. Each expression expression ca can n be a string or of of numeric type. type. The format format string on the WRITE WRITE FORM sta statement tement defines defines how these these expressions expre ssions are formatted formatted for a print print line. line. Refer tto o the IBM 4680 BASIC: Language Reference  for   for a description of a format string.

Printing a Line of Text at the Printer Use the WRITE WRITE FORM statement statement to print one one line in the CR/DI or SJ SJ station. station. An I/O sessi session on number number,, specified specifi ed in the OPEN statemen statement, t, indicate indicates s which printer printer station to use. Specify lin line e feed information information in the format string. The printer driver driver prints the line asynchrono asynchronously usly to execution execution of your application. application. You can issue multiple multiple WRITE FORM statement statements s to queue more more than one print print line to the pr printer inter dri driver. ver. If you attemp attemptt to queue more than five statements, your application must wait until buffer space becomes available in the queue. Each print print line must contain 38 bytes bytes of data. The system per performs forms line feed feeds s after the data is prin printed. ted. To line feed before printing a line, execute a WRITE FORM specifying the number of line feeds required with data of all blanks. blanks. If the data in a print print line is all blank blanks, s, the syste system m moves the pr print int head onl only y if necessary necess ary to return return the head to home position. position. Home positi position on is between the CR/DI and SJ stations. stations.

Controlling the Document Insert Station Use the PUTLONG PUTLONG statement statement to control control the DI station o options. ptions. The follow following ing bit values values refer to byt byte e MM, which contains the DI control bits. Bit 4 controls whether whether manual manual or automatic document document insertion insertion mode is selec selected. ted. If manual mode is selected (bit 4=0), the document is inserted from the side of the DI station, manually aligned, and the station manually manually closed closed using a printer printer button. Keyboa Keyboard rd input can be used to let the application application know know that the document document is ready for printing. printing. If automatic mod mode e is selected (bit (bit 4=1), the docume document nt is inserted from the front front until the document document is stopped stopped by the gat gate. e. When printing printing is started started at the DI sta station, tion, the station closes closes and performs performs the print operation operation.. The differ difference ence betwe between en manual and aut automatic omatic mode as viewed from the application program is that the printer driver closes the station in automatic mode when printing printin g is started started at the DI station. station. In manual mode, mode, the operator operator mus mustt close the sta station. tion. If a document is pulled from the top of the DI station, the station can be left closed without a document insert inserted. ed. can open station ion by using prin printer ter and clo close se button, bystation. usin using g the CR/DI station lineYou line feed button. butto n. the Yourstat application app lication can canthe also issue iss ueopen a WRITE FORM to th the eor CR

Bit 5 controls whether the application is notified if a document is removed and replaced between print lines at the DI station. station. If a document document is not in the DI station station when a print at th the e DI station is being being perfo performed, rmed,

 

3-61

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

your application application receives receives an error notification notification that the docum document ent is missing. If your applicati application on needs notification notific ation on document document removal removal (bit 5=0), the driver driver rememb remembers ers that the document document was remov removed. ed. The driverr remembers drive remembers this even if the document document was removed while while no print operation operation was being done. done. After removal, on the next print at the DI station, the application receives an error stating the document is not inserted. inser ted. This error error occurs occurs even if the do document cument w was as replaced replaced before the pr print int oper operation. ation. The error error notification notific ation allows allows your application application to take action action on this condition. condition. This actio action n could be to void the transaction trans action or to log the occurrence. occurrence. The status is reset from document-in document-inserted serted to not-i not-inserte nserted d when either the error is passed to the application or when a print is done at the CR station. Bits 6 and 7 control control options options for use of a document document while while printing printing at the CR station. station. Docume Documents nts can be inserted from the front inserted front or side of the the DI station. If the document document is inserted inserted from the si side, de, it can be aligned to reach above the print head path so that any printing at the CR station is printed on the document docume nt because because it is physically in fron frontt of the CR paper. If the document document is inserted from the fro front, nt, it stops when the gate is reached, and printing at the CR station is done on the CR paper (not the document). docume nt). If the document is inserted inserted from the fro front nt before a DI print, the document document is ready for pr printing inting without having having to prompt the operator operator to insert insert the document. document. The printer printer control controls s the use of a document during CR printing as follows:

 If bit 6=0 and bit 7=0, 7=0, a documen documentt cannot be ins inserted erted if pr printing inting is done done at the CR statio station. n. A print to the CR station results in an error if a document is inserted.  Bit 6=0 and bit 7=1 7=1 is not a valid combinatio combination. n. If a PUTLONG is issued issued with thi this s combina combination, tion, the PUTLONG results in an error.  If bit 6=1 and bit 7=0, 7=0, a documen documentt can be inser inserted ted even if a print print is issue issued d to the CR station station.. No erro errorr results because a document is inserted. 7=1, a documen documentt must be place placed d in the DI station when when print printing ing at the CR stati station. on. If  If bit 6=1 and bit 7=1, a print to the CR station is issued and a document is not inserted, an error results stating that a document docume nt is missing. This option option is normally use used d to ensure that a document document is inserte inserted d before printing printin g on the CR receipt receipt tape. The document document can be pr printed inted afte afterr the CR receipt receipt is printe printed. d. When your application issues a PUTLONG statement, the options specified affect all WRITE FORM statements stateme nts issued after after the PUTLONG. PUTLONG. The new PUTLON PUTLONG G options do not affect affect queued print ope operation rations s resulting from WRITE FORM statements that were issued before the PUTLONG.

Determining the Printer Status Use the GETLON GETLONG function determine deter mine print printer status information information. . Thisation. function function returns ns the current t settings setting s of the DI G control bitsto set by PUTLONG PUTLO NGerand printer st status atus information. inform Theretur status information infocurren rmation includes:

     

Printer status (reset or not reset) Paper status for SJ station (low or paper jam or not low and no paper jam) Document insertion status (inserted or not inserted) DI station status (open or closed) Printer head status (at home or not home) Printer cover status (open or closed)

 Printing Printi ng Check Checks s Checks are are inserted vertically vertically and the characters characters printed printed sideways. sideways. Check prin printing ting can be done only at the DI station station of a Model 2 printer. printer. The chec check k must conform conform to the United Kingdom Kingdom Associatio Association n for Payment Clearing Services (APACS) standard, or all of the data to be printed on the check must fit into the area between the 84th print position to the right of the left margin and the 156th print position to the

left of the the right right marg margin. in. (A total total of 380 print position positions s are available.) available.) To print print an APACS APACS check, check, the check is inserted with the amount field at the top.

3-62

4690 Store System: Programming Guide

 

 

Check printing printing is useful because because the customer customer does not not have to write out the check check.. A blank check is handed to the cashier cashier by the customer. customer. The cashier cashier inserts the check check into the docum document ent insert sta station, tion, and the printer printer types types the date, amount, amount, and payee. payee. Then the customer customer signs signs the che check. ck.

Formatting the Data Your application application can can detect if a Model Model 2 printer iis s attached attached by check checking ing bit 3 of GETLON GETLONG G byte SS. If bit 3 is 1, the printer supports supports chec check k printing. To use check printing, printing, the application application iss issues ues a PUTLONG to any of the printer stations stations with bit 3 of byte MM set to one. This instructs instructs the print printer er driver to inte interpret rpret the next WRITE WRITE LOGO to the DI station station as a check printing printing command. command. The WRITE LOGO LOGO statement statement is used to print checks. The format of the data array specified on the WRITE LOGO statement is similar to normal WRITE LOGO data. The printing printing field is variable variable in size size and smaller smaller than the 300 300 dot print fie field ld of a normal W WRITE RITE LOGO statement statement.. The first first th three ree a array rray elements contain some control control inform information. ation. The applicat application ion ca can n give more than than one line of check check data to the the driver on on one WRITE LOGO. LOGO. This function function allow allows s the printe printerr driver to print print the check faster. faster. The maximum maximum amount of check data must must fit into the 381 array elements elements used by the WRITE WRITE LOGO statement. statement. The check data data passed passed to the drive driverr with the WRIT WRITE E LOGO statement is in slice form, which means that each byte represents a column of eight dots on the paper. The data on a normal normal WRITE LOGO LOGO statement statement is also in slice slice form. The appli application cation is respons responsible ible for translation transl ation of character character data to slice data data and the rotatio rotation n of the data for vertical vertical printing. The system sends the data to the printer horizontally. The printer printer has a total of 380 380 print position positions: s: there are are 190 called called primary  and   and 190 called secondary  called secondary . The even-numbered print positions are primary beginning at zero, and the odd-numbered positions are secondary. second ary. The first byte in the buffer buffer is the number of primary primary print positions positions betw between een the home posit position ion and the first right position of the data to be printed. counting print positions, positions, begin begin counting counting from right to left. The lowest num number ber is the print Note: When counting position positio n closest closest to home. The highest highest number is the the print position position closest closest to the mar margin. gin. Check data can can be printed only from from primary position position 78 to primary primary position 14 148. 8. Use cautio caution n in changing the value of this this byte. If one WRITE LOGO LOGO contain contains s a different different value in this byte byte than the pr previous evious WRITE LOGO for the same check, the printer moves the print head to home before printing the new data with the new offset. offset. Check printing printing can s slow low if small cha changes nges are frequent frequently ly made to this byte. byte. Performance Perfor mance is improved improved if the application application does not revert revert to the previous previous offset. Howeve However, r, increa increasing sing the value in this byte decreases the area where the print head is moved, which can improve performance. The following control information must be contained in the first three array elements (bytes 1, 2, and 3):

 Byte 1 plus the dividend of byte 2 divided by 2 equals the number of primary print positions taken up by the print print line. Byte 1 divided divided by 2 is is less than than or equ equal al to 148.  Byte 2 in the buffer equals the length of the data (that is, the number of bytes of data for one line of the check check data). Byte 2 cannot cannot be less than 50 bytes bytes and sh should ould be an even even integer integer..  Byte 3 equals equals the number number of lines buffered buffered in the WR WRITE ITE LOGO buff buffer. er. The buffe bufferr that pass passes es to the printerr driver on printe on a WRITE LOGO always always has 380 380 bytes for print print data. One line of che check ck data is always less less than 377 bytes. bytes. Byte 3 should should always be le less ss than or eq equal ual to 377 when iitt is divided by the value of byte 2 and rounded to the nearest integer. Note: To reduce processing time, the application can pass multiple check print lines to the driver simultaneously.

 

3-63

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Charac Cha racter ter Set Sets s Character sets are used Character used to print the check data. data. Byte 381 cont contains ains the numbe numberr of dots to advance the paper after each each line line is printed. printed. If the 5 x 8 dot chara character cter set set is being being use used, d, the byte byte should should be set to 6. 6. If the 8 x 8 dot character set is being being used, the byte should should be set to 9. Charac Characters ters cann cannot ot be split acros across s print lines. lines. You should should move the print head to the home position position after the ch check eck is printed printed to ensure that the check printed printed correctly. correctly. There ar are e two ways to code the application application to move the print print head:

 Perform a TCLOSE after the last line of the check is printed.  On the last WRITE WRITE LOGO, set the high-or high-order der bit of byte 381 381 to ON. The driver driver looks at the h high-or igh-order der bit of byte 381. 381. On the last printed printed line of the W WRITE RITE LOGO, the the driver commands commands th the e printer to return the print head to the home position. This procedure is faster than a TCLOSE because a TCLOSE forces the application to wait until all queued prints have completed the procedure.

 Problem Determina Problem Determination tion To perform problem determination, an ASYNC error with the error number 80900524 results from one of the following conditions:

 The first three bytes of the data in the WRITE LOGO buffer do not conform.  There are adjacent wire-fires in the print data.  The printer does not support check printing. Your application application can can determine the cause cause of the error by checking checking bit 3 of byte SS. The retur return n code is ERRN=80900524H. Your application application must must verify that no adjacent adjacent wirewire-fires fires are in check check data. For example, example, if bytes 34 and 35 are part of the same print pass, ANDing the two should give you zero. Warning: Adjace Adjacent nt wire-fires wire-fires can result result in the de destruct struction ion of the print print head. If the desig design n of the character-to-slice translation table is correct, the application should not have to check for adjacent wire-fires.

 Programming Consi Programming Considerat derations ions The following following procedures procedures are not not checked by the prin printer ter driver. driver. They shou should ld be perform performed ed by the application.

 After any document insert line feed commands, a blank APACS print should be done before printing the check. check. Otherwise Otherwise line feed feeding ing is incomplete incomplete after the the first print print pass.

 The value in the low-order four bits of byte 381 of the logo buffer should not be greater than 9.  One pass of the print print head must must be used to print print one, and on only ly one, column column of chara characters. cters. If columns of characters are split between print passes, print quality is not readable.

 Example Example See Appendix Appendix C for an example application application using using check printing. printing.

3-64

4690 Store System: Programming Guide

 

 

Logo Lo go Prin Printi ting ng Logo printing printing can be done only at the CR/DI sta station. tion. Use the WRITE LOGO stat statement ement for printing printing logos logos.. The WRITE LOGO statement statement prin prints ts all-points-ad all-points-address dressable able data at the CR/DI station. station. The dots to be printed printe d are specified specified in an array with this statement. statement. The number of ele elements ments in the array array must be a multiple of of 381. Each set of 381 381 bytes has 38 380 0 bytes of log logo o print data fo followed llowed by on one e byte that co contains ntains the number of dots that that the paper is advan advanced ced after printing. printing. Only the first 300 bytes bytes of the 380 bytes of print data data can be printed. printed. These bytes are are printed printed in the cen center ter 300 300-dot -dot c columns olumns of the line. line. The system system ignores ignore s the last last 80 bytes bytes of print data. Each byte byte con controls trols the printing printing o off one 8-dot 8-dot colu column. mn. The first first byte in the array correspo corresponds nds to the leftmost print print position. position. Bit zero of each byte correspon corresponds ds to the topmost dot of each each dot column. column. If a bit=1, the the correspond corresponding ing dot is printed. printed. Only one WRITE WRITE LOGO statement statement can be queued. queued. If a WRITE LOGO is is issued sued befo before re the pre previous vious log logo o print ends, ends, execution execution is suspended suspended until the previous previous logo print is complete. complete. The system pas passes ses error errors s to the ON ASYNC ERROR subprogra subprogram. m. The error c can an be bypasse bypassed d or the entire logo can be re reprinted printed.. Requests for retries of logo prints should not be made.

Determining When Printing is Complete If you have print lines queued and want them printed before continuing application execution, use the TCLOSE statement. statement. This statement statement causes your application application to suspend suspend executio execution n until all outstandin outstanding g print lines have have been printed printed at all printer stations stations or until an err error or is detected. detected. If an error is detec detected ted during the completion of any queued prints, the system gives control to the ON ASYNC ERROR subprogram. subpr ogram. When the TCLOSE TCLOSE is complete, the print print queue is empty and the pr print int head returns returns to the home position.

 Performance Performanc e Consi Considerat derations ions There is a margin margin to the left of the CR/DI CR/DI station an and d a margin to the right right of the SJ station. station. When printing is done at a station, the print head first moves from the home position to the station margin or from the margin margin to the home position depending depending on where where the head was left from the previous previous pri print. nt. If the print head is in the margin of one station and the next print request is for the other station, the print head must move back to the home position position befo before re it reaches the the station at which the print print is requeste requested. d. In such a case the print head travels across one station without printing. To maximize performa performance, nce, your applicatio application n can print so that prin printt head travel time is minimi minimized. zed. Your application should start with the head in the home position (following TCLOSE) and print an even number of times at one station before before printi printing ng at the other station. station. In some cases your your applica application tion print prints s the same data at both the the CR/DI station station and the SJ station. station. In such cases, cases, you sho should uld alter alternate nate which s station tation is printed printe d at first (CR, SJ, SJ, SJ, CR, CR, SJ, and so on). on). This res results ults in an even n number umber of pr prints ints at one station before moving to the other. For logo printing, printing, the print print head must travel across across the print line either either two or four times. times. Only two passes passes are required required if you compose compose the logo by using every every other column of dots dots.. You should use use either all odd dot columns or all even dot columns.

 

3-65

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Example This example example contains contains code for operating operating a printer. printer. The program program writes mess messages ages to the displa display, y, sets up the synchronous and asynchronous error handlers, and prints lines at the CR and DI stations.

%ENVIRON T ! Declare integers. INTEGER*2 INTEGER*4 DISPLAY.NUMA REQ%,STAT% ! Async error handling subprogram. SUB ASYNCSUB(RFLAG,OVER) INTEGER*2 RFLAG STRING OVER ! Set up synchronous error handler ! for async subprogram. ON ERROR GOTO SERROR ! See the error recovery example ! for the ON ASYNC ERROR CALL ! statement in the IBM 4680 BASIC ! Language Reference. EXIT SUB END SUB Start execution. ! The alphanumeric display is opened for display of prompt. DISPLAY = 4 OPEN "ANDISPLAY:" AS DISPLAY CLEARS DISPLAY WRITE #DISPLAY; "PRINTER SAMPLE" WAIT;2000 ! Branch around called routines. GOTO START.OF.PRINTS ! Open the print station designated in the variables. FUNCTION PRINTER  OPEN STATIONS$ AS NUMA  CLEARS DISPLAY  WRITE  WRI TE #DIS #DISPLA PLAY; Y; "OPE "OPENN PRINTE PRINTERR ", STAT STATION IONS$ S$  EXIT FUNCTION END FUNCTION ! TCLOSEs to clear all the print requests, ! then display and close the print station. FUNCTION CLOSEA  TCLOSE NUMA  CLEARS DISPLAY  WRITE #4; "CLOSE = ", NUMA  CLOSE NUMA  EXIT FUNCTION END FUNCTION ! Start printing. START.OF.PRINTS: ! Set up the asynchronous error handler ! and the synchronous error handler. ON ASYNC ERROR CALL ASYNCSUB ON ERROR GOTO ERR.HNDLR ! Print and space at the customer receipt station.

3-66

4690 Store System: Programming Guide

 

 

CR.PRINTER:  NUMA = 3  STATION$ = "CR:" CALL PRINTER WRITE FORM "C38 A1";#NUMA; "PRINT CASH RECEIPT AND SPACE 1 AFTER " WRITE FORM "C38 A2";#NUMA; "PRINT CASH RECEIPT AND SPACE 2 AFTER " WRITE FORM "C38 A3";#NUMA; "PRINT CASH RECEIPT AND SPACE 3 AFTER " WRITE FORM "C38 A4";#NUMA; A5";#NUMA; "PRINT CASH RECEIPT AND SPACE 45 AFTER " CALL CLOSEA ! Print and space at the document insert station. DI.PRINTER: NUMA = 2 STATIONS$ = "DI:"   CALL CALL PRIN PRINTE TERR REQ% = 00000H ! Set manual document insert. ! Requires operator to press Close button. PUTLONG NUMA , REQ% INSERT.DOC: CLEARS DISPLAY WRITE #DISPLAY; "INSERT DOCUMENT" !REQ% Test= for document GETLONG (NUMA)present. STAT% = REQ% AND 00000030H IF STAT% 00000010H THEN GO TO INSERT.DOC WRITE FORM "C38 A1";#NUMA; "PRINT ON DOCUMENT WRITE FORM "C38 A2";#NUMA; "PRINT ON DOCUMENT WRITE FORM "C38 A3";#NUMA; "PRINT ON DOCUMENT WRITE FORM "C38 A4";#NUMA; "PRINT ON DOCUMENT   CALL CALL CLOS CLOSEA EA CLEARS DISPLAY WRITE #DISPLAY; "END OF PRINT SAMPLE" CLOSE DISPLAY GOTO END.PROG ERR.HNDLR: ! Prevent recursion. ON ERROR GOTO END.PROG ! Determine error type and perform appropriate ! recovery and resume steps. END.PROG: STOP END

AND AND AND AND

SPACE SPACE SPACE SPACE

1 2 3 5

AFTER AFTER AFTER AFTER

" " " "

Printer Driver Model 3 or 4 This section describes the model 3 and 4 printer drivers and provides guidelines for using them.

 Characteristics Characteristics The Model 3 or 4 printer is a two-station two-station impa impact ct printer that that provides provides three functions. functions. It provide provides s a CR function in one station, an SJ function in a second station, and a DI function in the same CR and SJ stations. station s. The CR function function provides provides a hard copy copy of the transactio transaction. n. It also can fun function ction as a gene general ral

output device device to provide data data to the operator. operator. The SJ function function records da data ta on every tran transaction saction for an audit trail or performs performs any other other printing printing function that the user user progra program m dictates. The DI function all allows ows  

3-67

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

insertion inser tion of a form, document, document, or check directly directly into the printer printer from the front or from from the top. Use this function to print a variety of forms such function such as store char charge ge accoun accountt forms, or to print or endorse endorse check checks. s. The printerr mechanism is a 9-wire printe 9-wire dot matrix, matrix, bidirectional, bidirectional, all-points-addr all-points-addressabl essable, e, high-spee high-speed d device. The number 9 print wire can be used for an underscore or descenders. The CR and SJ stations stations each print up to 38 chara characters cters at 15 characters characters pe perr inch (CPI). The DI station prints up up to 86 characters characters at 15 CPI. Other fonts fonts are stor stored ed in the prin printer ter that inc include lude 12 CPI, an and d 7.5 CPI. The 7.5 CPI character characters s also can be printed printed double double high. Lowercase Lowercase c charact haracters ers ca can n be pr printed inted in addition additio n to normal characters characters.. Double strike strike is available available in all stations for emphasis, emphasis, but at a reduced reduced rate because of unidirectional printing. The default default line spacing spacing for the CR, SJ, SJ, and DI stations stations is six lines per per inch. The line spa spacing cing for each each station can be changed by the PUTLONG statement and the current line spacing is returned by the GETLONG GET LONG functio function. n. Refer Refer to tthe he IBM 4680 BASIC: Language Reference  for   for additional information on the PUTLONG and GETLONG functions. The application program can specify how the printer driver is to interpret the line feed specification (A value) of the WRITE WRITE statement. statement. The application application can advance advance the paper in the va various rious stations stations in increments incre ments of full lines or motor motor steps. (There (There are 9 motor steps per lin line e at a line spacing of 8 lines per inch and there there are 12 motor motor steps per per line at a line spacing spacing of 6 lines lines per inch.) inch.) If PUTLONG an and d GETLONG bit 4 of byte LL is zero, the driver interprets the A value of the WRITE statement as a full line feed. If bit 4 of byte LL is 1, 1, the driver driver interpr interprets ets the A value value in motor motor step steps. s. For co compatibil mpatibility ity with curre current nt applications, the driver defaults to interpreting the WRITE A value in full line feeds. Logo printing is supported in the printer code, but at approximately half the speed because of unidirection unidir ectional al printing. printing. Double high fonts fonts are are also printed at a lower lower speed. speed. (Singl (Single-line e-line logos print a att full speed.) speed .) However, However, the driver code d does oes not support support logo printi printing ng in the the SJ station. station. See “L “Logo ogo Pr Printing” inting” on page 3-78 for additiona additionall information. information. While printing in the normal mode, the print speed is up to 250 lines per minute, depending on the application.

Compatibility with Applications Written for the Model 1 and 2 Printers The Model 3 or 4 printer is compatible with applications written for the Model 1 and 2 printers, but some minor changes changes to existing applications applications will be necess necessary ary due to printer hardware hardware differences. differences. The following list identifies the application changes required for compatibility with the Model 3 or 4 printer:

 The number of line spaces to advance the paper at the end of a transaction must be increased from 8 to 10 lines. See “Receip “Receiptt Paper Paper Cutter” Cutter” on pa page ge 3-76 for more inform information. ation.  A receipt paper cutter command must be issued after advancing the paper at the end of a transaction. See “Receipt “Receipt Paper Cutter” Cutter” on page 3-76 for more more information. information. printer driver return return codes must must be added to the application application async asynchronou hronous s error routine. routine. See  Two new printer “Journal Buffering When Printing on Documents” on page 3-74, “Preventing Unnecessary Unnecessary Reprints” on page 3-76, and also also rrefer efer tto o the IBM 4690 Messages Guide  for   for more information.

3-68

4690 Store System: Programming Guide

 

 

Depending on how the application program has been designed to position documents, the following changes might also be required:

 The number of line spaces a document is advanced after being inserted in the document station might need to be changed. changed. See “Ma “Manual nual or or Automatic Automatic Document Document Insertio Insertion” n” on page 3-72 ffor or mor more e information. eject command might might be required to remove remove a document from from the document sta station. tion. See  A document eject “Document ment Eject Command” Cothat mmand” on page p age be 3-75 for more mo information. infor mation. It is recommended the print head moved torethe center home position before inserting a  “Docu document. If the application document. application w was as not originally originally designe designed d to do do so, this c change hange might be be req required. uired. See “Positioning “Posit ioning the Print Print Head” on page 3-75 for mor more e information. information. If a single application program is used with both the Model 3 and 4 printers and the existing Model 1 and Model 2 printers, the application program needs to determine which printer is being used and execute the preceding prece ding changes changes only only for the M Model odel 3 or 4 printer. printer. See “Determinin “Determining g the Printer Printer Status” Status” on page page 3-76 for more information. If you are not familiar with 4680 BASIC or the methods used to interface to these printers, refer to the IBM  4680 BASIC: Language Reference .

Functions Your Application Performs Your application program can perform the following functions with the printer:

      

Write characters to any station using four different character fonts. Write characters to any station using emphasized print. Write all-points-addressable data to the CR and DI stations. Sense documents and control document positioning. Change line spacing in all stations. Execute a cut of the receipt station paper. Obtain the printer status and printer type.

Accessing the Printer Use the OPEN statement statement to gain access access to the printer device device driver driver.. The name for eac each h print station is is:: CR: SJ: DI:

Cus Custo tom mer re receipt s sttati tio on Summary journal station Document iin nsert st station

Note: The colon is part of the name, and you must open each station before it will print. Use the CLOSE CLOSE statement statement to end communication communication with with a printer station. station. You must issue issue a CLOSE statement for each print station to which your application has issued an OPEN.

Preparing a Line to Print You can specify specify the data to be printed on a line in one or more exp expressio ressions. ns. Each expression expression ca can n be a string or of of numeric type. type. The format format string on the WRITE WRITE FORM sta statement tement defines defines how these these expressions expre ssions are formatted formatted for a print print line. line. Refer tto o the IBM 4680 BASIC: Language Reference  for   for a description of a format string.

 

3-69

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Printing a Line of Text at the Printer Use the WRITE WRITE FORM statement statement to print one one line in the CR, DI, or SJ s stations tations.. An I/O session session number number,, specified in the OPEN statement, specified statement, indicate indicates s which printer printer station to use. Specif Specify y line feed information information in the format string. The printer printer driver prints the line asynchron asynchronously ously to execution execution of your application. application. You can issue multiple WRITE FORM statements statements to queue queue more than one prin printt line to the printer driv driver. er. When the pri printer nter drive driverr queue becomes becomes full, your applicati application on must wait until buffe bufferr space beco becomes mes availa available ble in the queue. The system performs performs line feeds feeds after the data is printed. printed. To line feed before before printing a line, iss issue ue a WRITE FORM specifying specifying the number number of line line feeds required required with data data of all blanks. blanks. If the data in a prin printt line is all blanks,, the system moves the print blanks print head only if nece necessary ssary to return return the head to a home positio position. n. The home position is between the CR and SJ stations and to the left of the CR station.

Emphasi Emp hasized zed Pri Printi nting: ng: Emphasized, or double strike printing, is available in all printer stations at a speed that that is one-third the normal normal printing printing speed. In emphasi emphasized zed print mode, mode, the line is printed onc once, e, the print head head is returned to the starting starting posit position, ion, and the line is printed printed a second time. There Therefore, fore, ever every y line of print requires three passes of the print head. Emphasized printing Emphasized printing is primarily primarily intended intended to be used when printing printing on thick multiple multiple-part -part for forms. ms. A second strike of the print head wires on most forms results in the copies having darker, more easily readable print. An application program puts the printer in emphasized mode by imbedding control characters at the beginning beginn ing of tthe he print print data sent sent by the the WRITE WRITE statement. statement. Table 3-4 sh shows ows the charac character ter se sequence quences s for emphasized emphas ized printing. printing. Emphasized Emphasized mode must be used used for the entire line and remains remains in effect for only only one line. line. Emphasized Emphasized printing printing is availabl available e with all p printer rinter fonts. fonts. Table Tab le 3-4 3-4.. Model Model 3 or 4 Printer— Printer—Emp Emphas hasize ized d Print Print Defi Definit nition ion Ch Chara aracter cters  s    Description

Control Character Designator

  Comments

Start Emphasized Print

CHR$(27), CHR$(69)

Results in one-third print speed

Emphasized Empha sized Printi Printing ng Pro Programmi gramming ng Exa Example: mple: The The follow followin ing g examp example le ilillus lustr trat ates es the metho method d used to print a line using emphasized printing:

OPEN "CR:" as 5 ! REM ESTART$ = CHR$(27) + CHR$(69) ! REM   LINE LINE$$ = ESTA ESTART RT$$ +" +" Welc Welcom omee to to BRO BROOK OKSS Dep Depar artm tmen entt WRITE FORM "C40 A2"; #5; LINE$ ! REM ! REM WRITE FORM "C38 A1"; #5; " January 29, 1995

Open Printer Receipt Station Start Flag - Emphasized Printing Sto Store re " Print Welcome line on Receipt and space 2 lines. 10:10 a.m. "

Output of Example Program

 

│ Welcome to BROOKS Department Store │ │ │ │January 29, 1995 10:10 a.m. │

3-70

4690 Store System: Programming Guide

 

 

Fontt Spe Fon Specif cifica icatio tion: n: The pitch pitch of the de default fault font ffor or the Model Model 3 or 4 printer printer is is 15 CPI. You can specify a font change by imbedding a control character, followed by a character designating the font type desired, desire d, in the data field sent to the printer printer by the WRITE state statement. ment. (For exa example, mple, CHR$( CHR$(27), 27), CHR$( CHR$(58) 58) results in a 12 CPI font.) After receiving the character sequence denoting a font change, the printer continues to print in that font until the end of the line is reached reached or until another another font chang change e charact character er sequen sequence ce is found. At the end of the line, the printer resets to the default font of 15 CPI. Only 15 CPI and 7.5 7.5 CPI fonts can be be mixed in one WR WRITE ITE statem statement. ent. However, However, single h high igh and doub double le high characters characters cannot cannot be mixed in one WRITE WRITE statement. If different pitch pitch characters characters must be prin printed ted on the same line, the application can print the line using two WRITE statements with no line feed between the two statements. statements. This technique technique require requires s two passes passes to pri print nt one line. line. The application program should ensure that the number of characters specified in a WRITE statement for a given font can be printed printed on the station being being used. The printer printer driver returns returns an illeg illegal al data error (ERR=ID; ERRN = X'80900524') if the line width exceeds the width of the station. Table 3-5 sh shows ows the maximum number of printable printable c charac haracters ters for for each font typ type e and s station tation ttype. ype. The table also shows the fonts supported by the Model 3 or 4 printer and the control characters used to designate design ate the fonts. Each font control control char character acter pair inserted inserted in the WRITE data data field increa increases ses the size of the field by two bytes. bytes. To account account for the larger data field field size, the 4680 BASIC runtime runtime subroutines subroutines support data fields support fields greater greater than than 38 charac characters. ters. However, However, the Model 1 and Mod Model el 2 pr printer inter d driver rivers s retu return rn an error if more than 38 characters are used. Table Tab le 3-5 3-5.. Model Model 3 or 4 Printer Printer Font Font Defin Definiti ition on C Char haract acters  ers  Font Description

  Control Character Designator

  Maximum Characters Per Line

  Comments

15 CPI

CHR$(27),CHR$(59)

38 CR, SJ; 86 DI

Default Font

12 CPI

CHR$(27),CHR$(58)

30 CR, SJ; 68 DI

7.5 CPI

CHR$(27),CHR$(14)

19 CR, SJ; 43 DI

15 CPI Double Wide Font

7.5 CPI Double High

CHR$(27),CHR$(23)

19 CR, SJ; 43 DI

Double High, Double Wide

Fontt Chang Fon Change e Progr Programm amming ing Ex Examp ample: le: Th The e foll follow owin ing g exam exampl ple e ilillu lust stra rate tes s the the meth method od used used to change fonts with the Model 3 or 4 printer:

OPEN "CR:" as 5 ! REM Open Printer Receipt Station FONT15$ = CHR$(27) + CHR$(59) ! REM 15 char/inch Control String FONT75$ = CHR$(27) + CHR$(14) ! REM 7.5 char/inch Control String   LINE$ = " Welcome Welcome to " + FONT75$ FONT75$ + "BROOKS "BROOKS"" + FONT15$ FONT15$ + " Dept. Dept. Store Store " WRITE FORM "C36 A1"; #5; LINE$ ! REM Print Welcome line on Receipt Output of Example Program  Program 

│ Welcome to B R O O K S  Dept. Store │ In the preceding example, the 7.5 CPI pitch characters used for the word BROOKS take twice the space of characters printed at 15 CPI (the highlighted characters in the example are used to simulate a

double-wide font) double-wide font).. This extra width results results in only 32 data characters characters filling the 38 character-wide character-wide receipt receipt paper. It is important when when mixing fonts in a single line of print print that the line width of the individual individual print printer er station not be exceeded.  

3-71

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Controlling the Document Insert Station The document station on the Model 3 or 4 printer covers both the CR and SJ stations (on the Model 2 printer, printe r, only the CR station is blocked blocked when a document document is being printed). printed). The docume document nt sensor sensors s are positioned at the far right of the DI station, so the document must be aligned to a fixed guide located at the right edge edge of the SJ station. For additi additional onal inform information ation about about positioni positioning ng forms, refe referr to the the IBM   IBM  4683/4684 Point of Sale Terminal: Operations Guide , the IBM 4680 Store System: Preparing Your Site , and the IBM Store Systems: Installation and Operation Guide for Point-of-Sale Input/Output Devices . Note: The fixed guide guide is provided provided for alignment alignment similar similar to the Mod Model el 1 and 2 printers. printers. For wide widerr documents, the document is inserted over the top of the guide and aligned against the right wall of the DI station. When your application issues a PUTLONG statement, the options specified affect all WRITE FORM statements stateme nts issued after after the PUTLONG. PUTLONG. The new PUTLON PUTLONG G options do not affect affect queued print ope operations rations resulting resul ting from WRITE WRITE FORM statements statements that that were issued issued before th the e PUTLONG. Refer to the IBM 4680  BASIC: Language Reference  for   for additional information on the PUTLONG statement.

Top or or Fron Frontt Loa Loaded ded D Docu ocumen ments: ts: Documen ments can be ins inserted from the top or the front on the the Model 3 or 4 printer. printer. A sensor is activ activated ated as the operator operator inserts inserts the documen documentt to the positive stop feed rollers and a light emitting diode (LED) on the front of the printer lights when the sensor is activated. An application application can us use e the GE GETLONG TLONG fu function nction to deter determine mine the presen presence ce of a docume document. nt. Bit 0 of byte byte SS is 1 when a document has been inserted in the top document station or the top of the form has been detected detect ed for a document document inserted inserted in the front front document document station. Bit 4 of byte SS is 1 when a document document has been inserted in the front document station or the bottom of form has been detected for a document loaded in the top document document statio station. n. Both top and bottom do document cument sensors sensors must be activ activated ated befor before e printing can begin at the document station. An application application can use the two document document sensors sensors to sense how a document document was inserted. inserted. Based on this determination, the application can order the print lines accordingly, for example, either printing the lines in reverse order for top-inserted forms or standard order for forms inserted from the front.

Manual or A Automati utomatic c Do Document cument Inserti Insertion: on: GE GETL TLON ONG G or PU PUTL TLON ONG G by byte te MM MM,, bi bitt 4, con ontr trol ols s whetherr manual or automatic whethe automatic document document insertion insertion mode is used. If manual mode is selected, selected, the document is inserted to the feed rollers, and the station is activated using the document station ready button on the front front of the printer. Pressing Pressing the printe printerr document station station ready bu button tton cause causes s the document to be fed into the printer until until the first print printable able positi position on is in the print field. If the operato operatorr wants to start printing in a position other than the top of form, the operator can use the printer line feed buttons to further position the document, or the application can advance the document. If automatic mode is selected (bit 4=1), the document is again inserted to the feed rollers, but the station is automatically activated and the document is automatically positioned to the first print position when the first WRITE WRITE statement is sent to the document document statio station. n. The applic application ation can advance advance the document document additional spaces before printing the first line by issuing a WRITE statement with the desired line feed information. inform ation. The difference difference between between manual and auto automatic matic mode as viewed viewed from the applic application ation pro program gram is that the printer driver gets the station ready in automatic mode when printing is started at the document station.. In manual mode, the operator station operator must must get the station ready ready by pressing pressing the document sta station tion ready button. Documents inserted from the top block the CR and SJ stations when the form is stopped against the feed

rollers. The operator rollers. operator must not insert insert a form from the top until printin printing g at the CR station has completed. completed. An error is returned if a WRITE statement is issued to the CR station when a document is in place.

3-72

4690 Store System: Programming Guide

 

 

Documents inserted from the front will not block the CR or SJ stations until manually fed into the station using the document ready button or automatically from a WRITE statement to the document station. Since users can insert documents from either the top or the front of the Model 3 or 4 printer, designing an application to accommodate application accommodate both insertion insertion meth methods ods is not trivial. trivial. Mistakes Mistakes could be made even if a message messag e is displayed prompting prompting you you on the method of insertion. insertion. To compen compensate sate for user er error ror and to make the process of designing applications easier for the programmer, the printer is designed to automatically interpret the intended insertion direction and automatically correct for user errors. The document will be automatically registered at the top-of-form if an application program is designed for automatic automat ic front inser insertion tion of documents. documents. The following following is an example of an applic application ation program program that is designed for automatic front insertion of documents:

 The document motor direction is front-to-top (bit 1 of PUTLONG byte MM is zero).  The automatic insert bit is 1 (bit 4 of byte MM).  The document is inserted from the front. If, however, you insert the document from the top, the printer automatically advances the document through throug h the printer unt untilil the document is registere registered d at the top-of-form. top-of-form. The advan advantage tage to this method is that even though the application was designed for front insertion, the result of inserting the document from the top is exactly the same as inserting from the front. The operation operation of the opposite opposite insertion insertion method is also autom automatic. atic. If an application application is designed for automatic top document insertion and you place the document in the front opening, the printer automatically advances the form through the printer, registering the document at the bottom-of-form. This feature of the printer should allow for more efficient application programs and improved usability.

Removing Removi ng and Repla Replacing cing a D Documen ocument: t: Bit Bit 5 of by byte te MM co cont ntro rols ls wh whet ethe herr the the ap appl plic icat atio ion n is notified if a document document is removed removed and replace replaced d between print print lines at the DI st station. ation. If a document document is not in the DI station when a print at the DI station is being performed, your application receives an error notification notifica tion that the document document is missing. missing. If your application application needs no notificati tification on on documen documentt removal (bit 5=0), the driver driver remembers remembers that the document document was remo removed. ved. The drive driverr remembe remembers rs this even if the document docume nt was removed removed while no print operation operation was being being done. After remo removal, val, on the next print at the DI station, the application application receives receives an error error stating stating the documen documentt is not inserted. This erro errorr occurs ev even en if the document document was replaced before before the print operatio operation. n. The error noti notification fication allo allows ws your application application to take action action on this condition condition.. Such action action could could be to void the tra transacti nsaction on or tto o log the the occurrenc occurrence. e. The status is reset from document-inserted to not-inserted when either the error is passed to the application or when a print occurs at the CR station. Document Docume nt Option Options: s: Bits 6 and 7 control options for use of a document while printing at the CR station. These options options can be used only with with document documents s inserted fro from m the front of the DI station. If the document is inserted from the front, it stops when the rollers are reached, and printing at the CR station is done on the CR paper (not (not the document). document). If the document document is inserted inserted from the fr front ont befor before e a DI print, the document docume nt is ready for printing printing withou withoutt having to prompt the ope operator rator to inse insert rt the documen document. t. The printe printerr controls the use of a document during CR printing as follows:

 If bit 6=0 and bit 7=0, 7=0, a document document cannot be inserted inserted if printing printing is don done e at the CR statio station. n. A print to the CR station results in an error if a document is inserted.

 Bit 6=0 and bit 7=1 7=1 is not a valid combinatio combination. n. If a PUTLONG is issued issued with this c combinat ombination, ion, the PUTLONG results in an error. 7=0, a document document can be inserted inserted even if a print print is issued to th the e CR station station.. No error  If bit 6=1 and bit 7=0, results because a document is inserted.

7=1, a document document must be placed placed in the DI station station when prin printing ting at the CR stat station. ion. If  If bit 6=1 and bit 7=1, a print to the CR station is issued and a document is not inserted, an error results stating that a

 

3-73

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

document is missing. This option document option is normally use used d to ensure that a document document is inserte inserted d before printing printin g on the CR receipt receipt tape. The document document can be pr printed inted afte afterr the CR receipt receipt is printe printed. d.

Journall Buffe Journa Buffering ring W When hen Pri Printing nting o on n Docu Documents: ments: The SJ station of the Model 3 or 4 printer is blocked blocked when a document is being being printed. Therefore, Therefore, simultaneou simultaneous s printing on the DI and SJ stations stations is not possible. possible. To minimize the impact impact to the applicati application on program, program, the printer dr driver iver buffe buffers rs all data written to the SJ station when a document is being printed. Note: Buffering of the journal data is not required when printing on the CR. The default method of journal buffering is transparent to the application and is activated from the document docume nt sensors. sensors. The driver buffers buffers all data sent sent to the SJ station after a form has been been detected by the top document sensor and prints the data following the removal of the document. The application program can control when the buffered journal data is printed by setting bit 2 of byte LL in the PUTLONG statement. statement. When this bit is zero, zero, the buffered jou journal rnal data is printed printed after the doc document ument has been been removed. removed. If bit 2 is 1, th the e buffer buffered ed data is held until this this bit is reset tto o zero zero.. This me method thod of controlling the print execution of the buffered journal data can be advantageous when a transaction requires more than one document (for example, the driver continues to buffer the data until all of the documents docume nts have been printed) printed).. Immedia Immediately tely after resetting resetting bit 2 from 1 to zero, the prin printer ter drive driverr begins printing printi ng the journal data. There Therefore, fore, the application application should ensure ensure that the user has completely completely removed the document from the printer before resetting this bit to zero. Use terminal terminal configuration configuration to specify specify the maximum number number of journa journall lines the driver buffers. buffers. The drive driverr reads the configuration data and allocates the memory required to store the number of lines specified. The driver holds this memory in reserve at all times to ensure it is available when required. Note: For planning purposes, 64 bytes of memory are reserved for each line specified in configuration. This value includes 38 bytes for data and 26 bytes for line feed and other control information. If more lines are sent to the SJ station than specified during configuration, the driver logs error message W354. The application application program program receives receives a return code, code, ERRN=8090052F ERRN=8090052F ERR=BO, ERR=BO, in response response to WRITE statements statements to the SJ station station after the journa journall buffer is excee exceeded. ded. If the application application receiv receives es this return code, it should eject the document and display a message indicating the journal buffer was exceeded. excee ded. When the document document is ejected, ejected, the data is printed (assuming (assuming bit 2 of byte LL is zero), zero), and the  journal buffer is cleared. An application appli cation program can issue a GETLONG command to t o determine the status of the journal journal buffer. If bit 0 of byte LL is zero, zero, th the e jour journal nal buf buffer fer is empty. empty. After clearin clearing g the bu buffer, ffer, a message can be displayed prompting the operator to reinsert the document and complete the transaction. trans action. No data is lost if the document document is ejec ejected ted when when this error error is firs firstt rece received. ived. Retries Retries are not not allowed in response to the journal buffer overflow return code.

3-74

4690 Store System: Programming Guide

 

 

As a visual indicator that the buffer was exceeded, a line of asterisks with an error message number is also printed printed on the journal station station following following the printed data. data. This messa message ge alerts stor store e personn personnel el that an error occurred occurred and that that the journal journal buffer buffer size size must be in increas creased ed usin using g the configurat configuration ion utility. utility. Figure 3-2 is an example of how the journal station appears after the buffer has been exceeded.

 

1 LAYAWAY LAYAWAY OPENED ON

         

ACCOU ACC OUNT NT 5384 5384 1 8 5 4 **************** W354

0182 0001 110 2/05/95 MDS 1 25.00 MDS 1 50.00 MDS 1 30.00 MDS 2 5.00 ****************

Fig Figure ure 3-2. 3-2. Exceed Exceeding ing the Journa Journall Buff Buffer er Exam Example  ple 

Reinse Rei nserti rting ng Docum Document ents s for Pri Printi nting: ng: So Some me tran transa sact ctio ions ns requ requir ire e that that a do docu cume ment nt be inse insert rted ed into the printer many times for printing at a different location each time (for example, documenting exception except ion conditions conditions or for voiding transactions transactions). ). These documents documents can be position positioned ed for printing using the automatic method method described described in “Manual or Automatic Document Document Inser Insertion” tion” on page 3-72, or they can be positioned positioned using a manual manual method for the Model 3 or 4 printer. printer. The followi following ng steps are req required uired for reinserting a document using the manual method: 1. Insert the document to the feed rollers and press the printer line advance button until the desired print location is positioned just above the printer cover. 2. Press the the document document stati station on read ready y button tto o rever reverse se feed th the e document document into the printer printer.. The doc document ument is now correctly positioned for printing and the application can issue WRITE statements to the DI station. This feature makes the Model 3 or 4 printer compatible with existing application programs that require documents to be inserted from the side and manually positioned for printing.

Docume Doc ument nt E Ejec jectt Co Comma mmand: nd: Th The e do docu cume ment nt stat statio ion n of the the Mo Mode dell 3 or 4 prin printe terr ho hold lds s do docu cume ment nts s tightly in place, preventing preventing manual manual repositioning. repositioning. This method allow allows s for more accurate posi positioning tioning when advancing a document under program control, but it also prevents an operator from pulling a document out of the printer after printing has completed. For fast removal removal of documents documents after printing, printing, use the document document eject comma command. nd. Issuin Issuing g this command results in the document being fed rapidly out of the printer until it is free from the document feed rollers. The document eject command is initiated by sending the control character sequence “CHR$(27), CHR$(12)” CHR$(1 2)” in a WRIT WRITE E statement statement to the DI station. The direc direction tion the docu document ment is advanced advanced out of th the e printer is controlled by the document line feed setting specified by PUTLONG or GETLONG byte MM, bit 1. The TCLOSE co command mmand ensures ensures that the document document eject is completed completed befor before e the applicati application on is able to issue another printer command, and it is recommended that this command be used after the document eject command. Before re in inse sert rtin ing g do docu cume ment nts, s, the the prin printt he head ad sh shou ould ld be mo move ved d to the the Positi Pos itioni oning ng th the e Pri Print nt He Head: ad: Befo center home position. position. Inserting Inserting documents documents is easi easier er if the the prin printt head iis s at the center home position position.. To center the print head at the home position, the application should issue a TCLOSE command before inserting the document. Note: Some forms might insert more easily with the print head positioned at the far left sensor position. Testing your application with the various print head locations is highly recommended.

 

3-75

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Reversi Rev ersible ble Doc Docume ument nt Stati Station on Moto Motor: r: Th The e de defa faul ultt do docu cume men nt mo moto torr dir directi ection on is the the same same as that that used to feed the receipt receipt paper during during printing printing (bottom-to-top) (bottom-to-top).. The direction direction of the documen documentt motor is changed chang ed by the PUTLONG statement. statement. The curre current nt setting of the document document motor is found found by using the GETLONG GET LONG functio function. n. Refer Refer to tthe he IBM 4680 BASIC: Language Reference  to   to determine the appropriate bit mapping.

Fo Forr maxi maximu mum m pe perf orma manc nce, e, how the the Mo Mode l 3print or 4 Document Docum ent checks S Station tation Character Line ne sent Le Lengths: ngths: printer driver theCharac length ofter the Li data to the document station to rfor determine fardel the head should should travel. If 38 characters characters or less are written written to the document document station, the pri print nt head travel travels s only half the the width of the station. station. The data data is pr printed inted rright-j ight-justified ustified over th the e jour journal nal sta station. tion. If more than 38 characters characters ar are e printed, printed, the print print head travels travels the the entire entire width of th the e document document statio station. n. Using the larger character chara cter fonts, fonts, some blanks can be truncated truncated to meet the 3838-chara character cter limit. If this occurs occurs,, increas increase e the length of the data string to greater than 38 characters to force the print head to travel the entire distance.

Determining the Printer Status Use the GETLONG GETLONG statement to determine determine printer printer status information. information. This statem statement ent retur returns ns the curren currentt settings setting s of the DI control bits set by the PUTLONG PUTLONG statement statement and other printer printer status infor information. mation. The status information includes:

          

Printer type (Model 2, Model 3, or Model 4) Paper status for the SJ station (out-of-paper or paper jam) Document insertion status (present or not present, top or front insert) DI station status (document ready or not ready) Document station line feed direction (bottom-to-top or top-to-bottom) Line spacing mode for any station (6 lines per inch or 8 lines per inch) Line spacing setting (line feeds or motor steps) Journal buffer status (holding buffered data or not holding buffered data) Current LOGO setting (300 or 380 slices to be printed) Printer head status (at center or left home or not at center or left home) Printer cover status (open or closed)

Refer to the IBM 4680 BASIC: Language Reference  for   for additional information.

Preventing Unnecessary Reprints The following return code indicates that the printer cover of the Model 3 or 4 printer has been opened:

ERRN = 8090052D

ERR = DO

The printer driver issues this return code whenever the printer cover has been opened and the outstanding print line completed completed successfully successfully.. No retries are required required by the application application in response to this return return code, but the application may display an informational message indicating the printer cover is open. Note: If printing is in progress progress when the co cover ver is opened, opened, the line in progress progress completes. completes. Howeve However, r, no additional printing can occur until the cover has been closed.

Receipt Paper Cutter A receipt paper cutter is provided on all Model 3 and 4 printers and the application interface provides control characters control characters for executing executing a partial partial cut of the paper. Since the tear ba barr on the Model 3 or 4 printer is intended only for occasional use (for example, when tearing off the excess paper after paper loading),

every application must be changed to use the cutter at all times.

3-76

4690 Store System: Programming Guide

 

 

Table 3-6 shows the ch characte aracters rs that have been defined defined to initiate a partial partial cut. Table Tab le 3-6 3-6.. Model Model 3 or 4 Printer Printer—Re —Recei ceipt pt Pap Paper er Cutter Cutter Contro Controll Charac Characters  ters  Description

Control Characters

Comments

Partial Cut

CHR$(27), CHR$(80)

Must be only characters in WRITE statement

The cutter control characters must be included in a WRITE statement following the last line before the cut. These character characters s must be the only characters characters inc included luded in the WRITE sta statement. tement. No line advance advance occurs as part of the cutter command, and therefore, the A value in the WRITE FORM statement is ignored on a cutter command. The application must advance the paper at the end of the transaction so that the last line clears the cutter. Ten line feeds are needed needed to clear the tear bar when the receipt station line spacing is set to 6 lines per inch. Twelve line feeds feeds are are require required d when the lin line e spa spacing cing is is set to 8 lines per in inch. ch.

Receip Rec eiptt Pape Paperr Cutt Cutter er Exa Exampl mple: e: Th The e foll follow owin ing g ex exam ampl ple e il illu lust stra rate tes s the the meth method od us used ed to issu issue ea paper cut command.

OPEN "CR:" as 5 WRITE FORM "C38 A10"; #5; "THIS IS LAST LINE OF THE TRANSACTION " WRIT WRITEE FOR FORMM "2C "2C11 A0" A0";; #5; #5; CHR$ CHR$(2 (27) 7),, CHR CHR$( $(80 80))

!! REM REM REM 'A' Issu Issueline e cut cutadvance comm comman anddvalue ignored

Printer Home Sensors The Model 3 or 4 printer has two home sensors: one located between the CR and SJ stations, and the other located located to the left left of the CR station. Bit 6 of byte SS of the GET GETLONG LONG indicates indicates when the the print head is is at the center center home home sensor. sensor. This iis s the same for the the Model Model 1 and and Mod Model el 2 p printer rinters. s. The information for the left sensor of Model 3 or 4 printers is made available to an application using bit 3 of byte MM.

Left Home Command A control character sequence is available to move the print head to the left home sensor (left of the receipt station). station ). To move the print head head to the far left, issue a WRITE statement statement that includes includes a left home control control character chara cter sequen sequence. ce. The left left home character character sequenc sequence e is CHR$(27 CHR$(27), ), CHR CHR$(76) $(76) or CHR$(27) CHR$(27),, “L” “L”.. No other data characters can be included in a WRITE statement that includes the left home control characters.

 Printing Printi ng Checks Checks Checks can be printed in normal mode (horizontally) in the document station of the Model 3 or 4 printer. Therefore, Theref ore, the Model 2 check check printing fea feature ture is not supported supported on the Model 3 or 4 printer. printer. For addit additional ional information informa tion on the Model 2 check printing feature, feature, see “Printing “Printing Checks” on page 3-62. A check printing utility is available from IBM for users of IBM application programs (for example, General Sales Application Application or Supermar Supermarket) ket) and also for users users not using an IBMIBM-suppli supplied ed application. application. For additional information, contact your IBM marketing representative.

 

3-77

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Logo Lo go Prin Printi ting ng You can print print logos only only at the CR and DI stations. stations. Use the WRITE WRITE LOGO statem statement ent for printing printing logo logos. s. The WRITE LOGO statement statement prints prints all-points-ad all-points-address dressable able data at the CR and DI stations. stations. The dots to be printed printe d are specified specified in an array with this statement. statement. The number number of elements in the array array must be a multiple of of 381. Each set of 381 381 bytes has 380 380 bytes of logo logo print data fo followed llowed by o one ne byte that contains contains the number of dots dots that the paper is advanced advanced after printing. printing. Each byte controls controls the prin printing ting of one 8-dot column.. The first column first byte in the array array corres corresponds ponds to to the le leftmost ftmost print print po position. sition. Bit zero zero of ea each ch byte correspond corre sponds s to the topmost topmost dot of each do dott colum column. n. If a bit=1, bit=1, the corres correspondin ponding g dot is printe printed. d. Due to hardware limitations, only the first 300 bytes of the 380 bytes of print data can be printed with the Model 1 and 2 printers. No hardware restriction exists with the Model 3 or 4 printer to limit the width of logo printing to 300 slices. However, to maintain compatibility with current 4680 or 4690 application programs, the Model 3 or 4 printerr drivers printe drivers default to the current current logo width of 300 columns. columns. To use the full 380-c 380-column olumn width of the receipt recei pt or document document station, station, set bit 1 of byte LL of the PUTLONG PUTLONG stat statement ement to 1. Use the GETL GETLONG ONG statement to determine the current bit value. There is no provision in the Model 3 or 4 printer drivers for logo printing across the entire width of the 86-characte 86-ch aracterr wide document station. station. Therefore, Therefore, the maximum logo width in either the receipt receipt or document station is 380 slices. Only one WRITE WRITE LOGO statement statement can be queued. queued. If a WRITE LOGO is iss issued ued before before the previ previous ous logo print ends, ends, execution execution is suspended suspended until the previous previous logo print print is complete. The syste system m passes err errors ors to the ON ASYNC ERROR subprogra subprogram. m. The error error can be bypassed bypassed or the entire logo ca can n be reprinte reprinted. d. Requests for retries of logo prints should not be made.

Determining When Printing is Complete If you have print lines queued and want them printed before continuing application execution, use the TCLOSE statement. statement. This stateme statement nt causes your application application to suspend suspend executio execution n until all outstanding print lines lines have been printed printed at the CR or DI stations or until an error error is detected. detected. If an error is detec detected ted during the completion of any queued prints, the system gives control to the ON ASYNC ERROR subprogram. subpr ogram. When the TCLOSE TCLOSE is complete, the print print queue is empty and the print print head returns returns to the home position.

 Performance Performanc e Consi Considerat derations ions There is a margin margin to the left left of the CR station and and a margin to the rright ight of the SJ station. station. When pr printing inting is done at a station, the print head first moves from the home position to the station margin or from the margin to the home position position depending depending on where where the head was left from the previous previous prin print. t. If the print head is in the margin of one station and the next print request is for the other station, the print head must move back to the home position position before before it reaches the station station at which the print print is requeste requested. d. In such a case, the print head travels across one station without printing. To maximize maximize performance, performance, your applicatio application n can print so that print print head travel time is minim minimized. ized. Your application should start with the head in the home position (following TCLOSE) and print an even number of times at one station before before printing printing at the other station. station. In some cases your your application application prints the sa same me data at both the the CR station and and the SJ station. station. In such cases, cases, you sho should uld alter alternate nate whic which h station is printed printe d at first (CR, SJ, SJ, SJ, CR, CR, SJ, and so on). on). This results results in an eve even n number of pr prints ints at one

station before moving to the other.

3-78

4690 Store System: Programming Guide

 

 

For logo printing, printing, the print print head must travel across across the print line either either one or three times. times. Only one pass is required required if you compose the log logo o by using every other other column of dots dots.. To maximize pe performa rformance, nce, you should use either all odd dot columns or all even dot columns.

Magnetic Ink Character Recognition Support for Printers Model 3 and 4 The Magnetic Inkthe Character Recognition (MICR) feature lets you read thedocument account number andstation other of a information from check. You do this by placing the document into the insert (DI) 4680 model 3R printer, or a 4690 model 4R printer that is equipped with the appropriate hardware. Note: For your application to access the parsing routines described in this section, you must define the logical name ADXMICRF in the system logical names as ADX_IDT1:ADXMICRF.DAT.

 

3-79

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

MICR Data Format The MICR hardware returns an ASCII string of up to 65 bytes that may include the following:

  00--9   Tr Transit Character On Us Character   Da Dash

ASCII ASCII ASCII ASCII

0-9 T A -

   UAnmroeuandtabClhearCahcatrearcter   blank

AASSCCIIII ?$ ASCII blank

(30H - 39H) (54H) (41H) (2DH) ((32F4HH)) (20H)

Using the MICR Reader You must place checks face down in the far right of the MICR reader for the MICR line to be read properly. prope rly. You must place place the check in the the DI station and make make the DI stati station on ready pr prior ior to the MICR read command being sent to the device (prior to the WAIT to the DI station or the READ LINE from the DI stat statio ion) n).. Se See e the the IBM Store Systems: Systems: Install Installation ation and Operation Operation Gui Guide de for Poin Point-of-Sa t-of-Sale le Input/O Input/Output  utput  Devices  for   for complete information about how to use the MICR reader.   Note You can perform printing (franking) on the back of a check when you insert it in the far right of the DI station. station However, However , only theposition. last 20 characters characters of the narrow narrow documen documentt print command command can be printed on the .check while in that From the time that the check is inserted in the far right position and the MICR command is sent, until the check is removed from the printer, all DI print commands must be DI narrow print with the first 18 characters chara cters buffered buffered with blanks. The application application is responsible responsible for ensurin ensuring g that this restricti restriction on is followed. followe d. No checking checking will will be done done by the printer printer driver driver..

Determining If a MICR Is Installed The MICR present bit is 0X04 of the GETLONG MM byte.

Reading from the MICR There are two ways to do a MICR read:

 Issue a READ LINE to the DI station. READ # PRTDI%; LINE MICRDATA$ This causes the application to wait until the MICR read has completed, or an error has occurred before the application regains control. the DI station. When the WAIT WAIT completes, completes, issue a READ READ LINE to obtai obtain n the MICR  Issue a WAIT to the data.

WAIT PRTDI%;2000 ! wait 2 for MICR or 2 seconds ! save the completed event SAVE.EVENT = EVENT% ! if the MICR event completed IF SAVE.EVENT = PRTDI% THEN BEGIN READ # PRTDI%; LINE MICRDATA$

 

ENDIF

As with any other WAIT statement, when the first event being waited on completes, all others will be cancelled. cance lled. For example, example, if a DI wait and a timer timer wait are ini initiated tiated and the the timer even eventt complete completes, s, the DI

3-80

4690 Store System: Programming Guide

 

 

wait will be canceled canceled and and no data will be available available for for a READ LINE at that time. time. If a READ LINE is issued when the DI event was canceled, the MICR read command will again be passed to the hardware. The application will not regain control until it completes. After the application obtains the MICR data, it can use the optional MICR data parsing routines described in this section or can can parse the data using using proprietary proprietary routines. routines. The printe printerr driver ret returns urns the data as passed by the hardware and performs no manipulation on the data.

Underst Und erstand anding ing M MICR ICR E Error rrors: s: Any Any err error en enco coun unte tere red d on eith either er the the WAI AIT T for for the the prin printe terr or the the READ LINE to the printer printer will trigger the ON ERROR ERROR statement cur currently rently in effec effect. t. Only erro errors rs on printer WRITE statements will trigger the ON ASYNC ERROR in effect. Any of the defined printer driver driver errors errors may be encountered encountered during MICR actions actions.. Printe Printerr driver return return codes can be determined by checking the first two bytes of the four byte return code for 8090nnnnH, where nnnn is the unique portion of the return code, and the 8090 signifies that the error is from the printerr driver. printe driver. The following following table contains contains the most most common MICR MICR error errors. s. Ta Tabl ble e 33-7. 7. Comm Common on MI MICR CR Erro Errors  rs  4 By Byte R Re eturn C Co ode

Description

80900002H

No MICR present

80900528H

No document present in DI

80900521H

Head movement error

Understanding MICR Parsing Routines The MICR parsing routines provided by the system provide a terminal application with the ability to extract the following fields from the MICR line read from a check:

 Transit or routing number    Acc Accoun ountt number number  Check sequence number The MICR function is included by adding the following line to your link input file:

ADXMICRK.L86[S],

(for medium memory model)

  or ADXMICRB.L86[S],

(for big memory model)

To use the MICR parsing parsing function, function, your application application must first first initialize the parsing parsing table. Use the followin following g functions to perform the initialization:

FUNCTION MICRINIT EXTERNAL   IN INTEG TEGER* ER*44 MICRIN MICRINIT IT   END FUNC FUNCTI TION ON The function function reads the the MICR parsing parsing table from from the ADXMICRF ADXMICRF file using se session ssion number number 64. The function returns 0 if initialization was OK. If the initialization was not OK, it returns the ERRN value of any error encountered.

 

3-81

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

After initialization you can parse MICR information read from a check using the following subprogram:

SUB MICRPARS(RC,MICRLine$,MICRTransit$,MICRAccount$, \   MICR MICRSe Sequ quen ence ce$) $) EXTE EXTERN RNAL AL INTEGER*1 RC !* MICR PARSING OK = -1, !* NO MATCH = 0 STRING MI MICRLine$ !* MI MICR li line re read fr from ch check STRI STRING NG MICR MICRTr Tran ansi sit$ t$ !* Tran Transi sitt numbe numberr extra extract cted ed STRI STRING NG MICR MICRAc Acco coun unt$ t$ !* Acco Accoun untt numbe numberr extra extract cted ed STRING STR ING MICRS MICRSequ equenc ence$ e$ !* Check Check Sequ Sequenc encee number number   !* extracted !*   EN END SUB

| | | |

Fiscal Printer Support The fiscal printer executes fiscal commands in accordance with the tax laws of the particular country supported. suppo rted. Every fiscal command starts with X'1B66' (ESC∧f in ASCII) that is unique to fiscal commands.

|

Applications written for the standard Model 3 printer are compatible with the Fiscal Printer Model 3A and Model 3F. Logo commands commands cannot be printed printed by the fiscal printer, printer, but no err error or occur occurs s if a logo print

| |

comman com mand d is ex execu ecuted ted.. Refer Refer to th the e IBM Fiscal Printer Software Supplement  for   for your specific country, for a detailed description of the fiscal commands.

|

Application Programming for the 4690 OS Fiscal System

|

| | | | | |

The command used to print lines on both the customer receipt and summary journal stations is the IBM 4680 BASIC WRITE WRITE FORM command. command. This command command remains unchange unchanged d for any existing print print option application. applic ation. Application Application programs programs issue fiscal commands commands using using the the W WRITE RITE F FORM ORM command. command. These commands provide the capability to release sales slips, daily closing vouchers, and fiscal documents. Fiscal vouchers are printed on the customer receipt station and then duplicated on the summary journal print station. station. The non-fiscal non-fiscal print print command is used to provide provide a line feed or eject at the print stations. stations.

|

The application application opens opens the document document insert station station when issuing fis fiscal cal comman commands. ds. Openin Opening g the document insertt station allows 115 inser 115 bytes of data to be sent with the fiscal commands. commands. Opening Opening the customer receipt receipt

| |

or summary journal station only allows 75 bytes of data and may not be enough for some fiscal commands.

|

Note: The IBM 4680 BASIC WRITE LOGO command and special characters are not supported by the 4680 Fiscal System.

|

|

|

Error Handli Handling ng a and nd Re Recovery covery Procedu Procedures: res: Fo Forr user user prog progra ramm mmin ing g erro errors rs,, see see the the IBM IBM 4680  4680  BASIC: Langua BASIC: Language ge Refere Reference  nce  for   for details regard regarding ing erro errorr repor reporting ting proc procedure edures s and user ac actions. tions. For functional hardware errors, see the IBM Fiscal Printer Hardware Supplement  for   for your specific country.

|

Lines reprinted by the fiscal unit (when applicable) are identified by the number sign (#).

| |

3-82

4690 Store System: Programming Guide

 

 

|

 R ead Co Read Comm mman ands ds

The following two sections describe the extensions to the 4680 BASIC GETLONG and PUTLONG | sta stateme tements nts for tthe he Model Model 3 printer printer.. See IBM 4680 BASIC: Language Reference , for more information on | the other statements used to communicate with the 4683 printer drivers. |

| |

GETLON GET LONG G Fun Functi ction: on: Use the GETLONG function to get status information from the impact printer driver.

|

The statement statement format format is: is: i4 = GETLONG GETLONG ----(numb -(number)er)---i4 = A 4-byte 4-byte integer integer that that represents represents the driver driver status. status. The integer integer repres represents ents in informati formation on in th the e form RRLLMMSS, where RR, LL, MM, and SS each represent one of the four bytes.

| |

number = The same 2-by 2-byte te integer variable variable or con constant stant assigned assigned to any one of the printe printerr stations in the OPEN statement.

| | |

Note: The changes made to support the Model 3 printer have been marked with an asterisk (*).

|

Byte RR is reserved for system use:

|

bit 0

(X'01') = Reserved – This bit is used by the 4680 BASIC runtime subroutines and varies in value.

|

bit bit bit bit bit bit bit

It should be ignored by all application programs. = 0 Reserved = 0 Reserved = 0 Reserved = 0 Reserved = 0 Reserved = 0 Reserved = 0 Reserved

|

Byte LL represents status information:

|

|

* bit 0 (X'01') = Journal buffer is empty = 1 Journal Journal buffer buffer contains contains data tto o be printed * bit 1 = 0 Print only only first first 300 slices of LOGO d data ata = 1 Print Print fu fullll 380 slices slices of LOGO LOGO data data * bit 2 = 0 Print Print bu buffer ffered ed journ journal al data data = 1 Hold Hold bu buffer ffered ed jour journal nal dat data a * bit 3 = 1 Reserved Reserved for future future optional optional pa paper per cutter. cutter. Value Value set to 1. * bit 4 = 0 WRITE FORM statement statement line feed sp specifica ecification tion (A value) re represe presents nts line feeds (d (default) efault) = 1 WRITE FORM FORM statement statement line feed spe specificati cification on (A value) value) repre represents sents moto motorr steps * bit 5 = 0 6 lines/inch lines/inch line spacing spacing mode in the the customer customer receipt receipt station (default) (default) = 1 8 lines/inch lines/inch line spacin spacing g mode in the the customer customer receipt receipt stati station on * bit 6 = 0 6 lines/inch lines/inch line spacing spacing mode in the the summary journal journal station station (de (default) fault) = 1 8 lines/inch lines/inch line spacin spacing g mode in the the summary summary journal journal statio station n * bit 7 = 0 6 lines/inch lines/inch line spacing spacing mode in the the document document insert station station (de (default) fault) = 1 8 lines/inch lines/inch line spacin spacing g mode in the the document document insert insert station

|

Byte MM represents mode information:

| | | | | | |

| | | | | | | | | | | | |

1 2 3 4 5 6 7

| |

* bit 0==10Model Model31printer or Model 2 printer installed installed.

bit 1 = 0 Document line feed is in normal mode, bottom to top (default) = 1 Document line feed is in reverse mode, top-to-bottom | | * bit 2 = 0 Reserved

|

 

3-83

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

|

* bit 3 = 0 Print head not at left position sensor = 1 Print head at left position sensor * bit 4 = 0 Manual document insert (Documents can only be inserted from the top or front.) = 1 Automatic Automatic document document insert. insert. Documents Documents can can be inserted inserted fro from m the top or front. The printer printer closes the document feed rollers on the document when the first print line on the document insert station station is issued. issued. The document document must must cover the the sens sensor. or. * bit 5 = 0 Document cannot be removed and replaced between print lines on the document insert station. If you remove a document between print lines, an error occurs. = 1 Document can be removed and replaced between print lines on the document insert station. * bit 6 = 0 Document cannot be placed in the document insert station during printing on the customer receiptt station. If you insert a document receip document while printing printing on the customer customer receipt receipt station, an erro errorr occurs. = 1 Document can be placed in the document insert station during printing on the customer receipt station. * bit 7 = 0 Document sensing not required by the document insert station for printing on the customer receipt station. = 1 Document sensing required by the document insert station for printing on the customer receipt station.. Or, the document station document must be sensed sensed during during customer customer receipt receipt station p printing rinting..

|

Byte SS represents status information as follows:

| |

* bit 0 (X Docume nt in nottop present t in topstation document document station '01Document ') = 0 Document =1 Documen t present present topresen p doc document ument bit 1 = 0 Reserved = 1 Paper error error at the summary summary journal journal station station (check (check bit 2 for more informati information) on) bit 2 = 0 No paper error = 1 Paper error error at the summary journal journal station station (for examp example, le, out-ofout-of-paper paper or pap paper er jammed) bi bitt 3 = 0 Reser Reserve ved d for for Mode Modell 2 pr prin inter ter ch chec eck k pr print inting ing fea featu ture re * bit 4 = 0 Document Document not present present in in front document document station station = 1 Document Document present present in in front front document document station station bit bit 5 = 0 Docu Docume ment nt inse insert rt stat statio ion n rea ready dy = 1 Documen Documentt insert insert station station n not ot ready ready bit bit 6 = 0 Pr Prin intt head head not not at at cent center er home home p pos osit itio ion n = 1 Print Print he head ad at cent center er home home positi position on bit bit 7 = 0 Prin Printe terr cove coverr cl clos osed ed

| | | | | | | | | | | | | | | | |

| | | | | | | | | | | | |

= 1 Pr Prin inter ter co cove verr open open

|

PUTLON PUT LONG G Func Functio tion: n: Use the PUTLONG function to make changes to the customer receipt,

|

summary journal, and document insert station mode.

|

The statement statement format format is: is: i4 = PUTLONG PUTLONG ---(nu ---(number) mber)-----

| | | | |

number = the same 2-byte integer variable or constant assigned to any one of the printer stations in the OPEN statement. i4 = a 4-byte integer that that represe represents nts the driver driver status. The integer integer represents represents infor information mation in the form RRRRLLMM, RRRRLLM M, where RR, RR, LL, LL, and MM each represent represent one one of the four byt bytes. es. The firs firstt two bytes are reserved for system use.

|

Note: The changes made to support the Model 3 printer have been marked with an asterisk (*).

|

Byte LL represents mode information:

| | |

bit 0 (X' 01 ') = 0 Res Reserve erved d * bit 1 = 0 Print only only first first 300 slices slices of LOGO data data = 1 Print Print ful fulll 380 s slic lices es of LOGO LOGO data data

3-84

4690 Store System: Programming Guide

 

 

|

* bit 2 = 0 Print Print bu buffer ffered ed journ journal al data data = 1 Hold Hold bu buffer ffered ed jour journal nal dat data a bit 3 = R Re eserved * bit 4 = 0 WRITE FORM FORM statement statement line feed spe specificati cification on (A value) value) repre represents sents lin line e feeds = 1 WRITE FORM FORM statement statement line feed spe specificati cification on (A value) value) repre represents sents moto motorr steps * bit 5 = 0 6 lines/inch lines/inch line spacin spacing g mode in the the customer customer receipt receipt stati station on = 1 8 lines/inch lines/inch line spacin spacing g mode in the the customer customer receipt receipt stati station on * bit 6 = 0 6 lines/inch lines/inch line spacin spacing g mode in the the summary summary journal journal statio station n = 1 8 lines/inch lines/inch line spacin spacing g mode in the the summary summary journal journal statio station n * bit 7 = 0 6 lines/inch lines/inch line spacin spacing g mode in the the document document insert insert station = 1 8 lines/inch lines/inch line spacin spacing g mode in the the document document insert insert station

|

Notes:

| | | | | | | | | |

| | |

1. The function function provided provided by bit 1 is not supported by the Model 3A fiscal fiscal printer printer.. 2. The function function provided provided by bit 6 is not supported by the Model 3A fiscal fiscal printer printer.. 3. The function provided by bits 5 and 7 is not supported by the Model 3A fiscal printer in fiscal mode.

|

Byte MM represents mode information as follows:

|

bit 0 (X'01') = 0 Rese Reserv rve ed * bit 1 = 0 Docume Document nt liline ne fe feed ed is in norma normall mode, mode, bottom bottom-to -to-to -top p (d (defau efault) lt)

| | |

|

* bit bit 1 bit 2 * bit 3 bit 4 bit 4 bi bitt 5 bi bitt 5 bi bitt 6 bit bit 6 bi bitt 7 bi bitt 7

|

Note: The functions provided by bits 4, 5, 6, and 7 are not supported by the Model 3A fiscal printer.

| | | | | | | |

= = = = = = = = = = =

1 0 0 0 1 0 1 0 1 0 1

Docume Document nt lline ine feed is iin n rever reverse se mode mode,, top top-to -to-bo -bottom ttom Reserved Reserved Manual do document in insert Automat matic document in insert Do Docu cume ment nt can canno nott be rrem emov oved ed and and rep replac laced ed betw betwee een n prin printt lin lines es o on n th the e DI: DI: Do Docu cume ment nt can can b be e remov removed ed and and rep repla lace ced d betw betwee een n pr print int liline nes s on the DI: Do Docu cume ment nt ca cann nnot ot be place placed d iin n DI: DI: d dur urin ing g pri print nting ing on CR: CR: Docu Docume ment nt can can be pla place ced d in DI: DI: du duri ring ng pr prin inti ting ng o on n CR: CR: Do Docu cume ment nt se sens nsin ing gn not ot re requ quir ired ed by DI DI:: for for p pri rint nting ing on CR: CR: Do Docu cume ment nt se sens nsin ing g req requi uire red db by y DI: DI: for prin printin ting g on on CR: CR:

| |

Th The e CBAS CBASIC IC lang langua uage ge does does not not perm permit it read readin ing g from from Reading Readin theion Mo Model 3 ed Fiscal Printer Printer: : tine the printeg printer. r. from This function funct isdel provided provid by a library rou routine in the file ADXFISRL.286 ADXFISRL.286 (for medium medium memory | models) or ADXFISBL.286 (for big memory models), that must be linked with applications using the fiscal | printer. |

The function is called FISREAD and has the following definition:

|

|

SUB FISREAD(FISRC,FISERR,FISDATA) EXTERNAL INTEGER*4 FISRC INTEGER*2 FISERR STRING FISDATA END SUB

|

FISRC is a 4-byte return code from the printer driver.

|

FISERR is a 2-byte error code with the following possible values:

| | |

| |

 

|

 

 0 = no error −1 = error on open −2 = error on read

 

3-85

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

|

FISDATA is a string variable with the format:

|

   Bytes 0 – 3 are the first 4 bytes of printer status

|

   Bytes 4 – 5 are reserved for service personnel

|

   By Byte te 6 is is a re read ad fla flag g

|

 – X'0' indicate  indicates s this data has not not been read read by the applic application ation before. before. This is the fir first st time data is

| |

read from the buffer, and the status matches the read data.  – X'1' indicates the data data has been read by the application application pr previous eviously. ly. This occu occurs rs if no fiscal read commands (X'DA' or X'DB') were processed by the printer since the last FISREAD command was issued. issued. This data has been been read from the buffer buffer previou previously sly and the status mat matches ches the read data.  – X'2' indicates this is the first time data is read from the buffer, but the status bytes have been updated after the read data was received.  – X'3' indicates this data has been read from the buffer previously, but the status bytes have been updated after the read data was received.

| | | | | | | |

   Byte 7 is the Microcode EC (engineering change) level.

|

contain the length of of the fiscal read read response. response. These two by bytes tes are in INT INTEGER*2 EGER*2 fo format. rmat.    Bytes 8 – 9 contain

|

   Bytes 10 – 265 contain the response to the fiscal read command.

|

Using Usi ng tthe he F FISR ISREAD EAD cal call: l: To rea ead d the the prin printe terr da data ta,, the the foll follow owin ing g se sequ quen ence ce sh shou ould ld be us used ed::

|

1. Write the the FISCAL FISCAL READ command command (X (X'DA' or X'DB') to the printer with a WRITE statement.

|

2. Issue a TCLOSE TCLOSE to the printer printer to flush the p print rint buffer. buffer.

|

3. Call the FISREAD routine routine to retrieve the fiscal data into the application application buffer.

|

4. Check the FISERR FISERR value for for an error error indication. indication.

|

5. For an error, obtain the return code from the FISRC variable, or if no error, extract the needed data from the FISDATA string variable.

| |

An example of a CBASIC FISREAD call is:

|

 

CALL FISREAD(FISRC, FISREAD(FISRC,FISERR,F FISERR,FISDATA) ISDATA)

3-86

4690 Store System: Programming Guide

 

 

Scal Sc ale e Dr Driv iver er This section describes the scale driver and provides guidelines for using it.

 Characteristics Characteristics |

   One scale can be attached to a terminal and can be one of the following:

|

 – Non-IBM scale attached to Feat Feature ure Expansion Card B or C (4683 only)

|

 – Integrated scanner/scale attached to a terminal socket

| | | | | | | | |

Refer to the 4690 the 4690 Store System: Planning, Installation, and Configuration Guide  for   for the terminal sockets that support a scanner/scale on your terminal

   You can select to have either English or Metric weight English - weight returned is: maximum of four digits hundredths of pounds Metric - weight returned is:: maximum of five digits thousandths of kilograms

Accessing the Scale Use the OPEN statement to gain access to the scale driver. Use the CLOSE statement to end communication with the scale driver.

 Receiving Receiv ing Dat Data a Issue a READ FORM FORM statement statement to receive receive data from the s scale. cale. If valid data is availab available, le, the variable variable specified specifi ed in the READ FORM stateme statement nt contains the weight. weight. If an error occ occurs, urs, contr control ol passes to the ON ERROR routine.

 Example Example To run the following following example, example, put a weight on the scale. The program program reads the sca scale, le, display displays s the weight one time, and then stops.

%ENVIRON T ! Declare variables. INTEGER*4 hx%,sx%,WEIGHT% INTEGER*2 SCALE%,ANDSP% ON ERROR GOTO ERRORA ! Indicate "ON ERROR" label. ANDSP% = 1 ! Set alphanumeric display session number to 1. SCALE% = 2 ! Set scale session number to 2. OPEN "ANDISPLAY:" as ANDSP%

! Open alphanumeric display. CLEARS ANDSP% ! Clear alphanumeric display.  

3-87

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

WRITE #ANDSP WRITE #ANDSP%% ; "SAMPL "SAMPLEE SCAL SCALEE PROG PROG"" WAIT;5000 ! Wait 5 seconds so display can be read. CLEARS ANDSP% ! Clear alphanumeric display. OPEN "SCALE:" AS SCALE% ! Open the scale. WRITE #ANDSP% "SCALEwasOPEN" ! Indicate the;scale opened. WAIT;5000 ! Wait 5 seconds so display can be read. CLEARS ANDSP% ! Clear display. WRITE #ANDSP% ; "READ THE SCALE NOW!" READ FORM "I4" ; #SCALE% ; WEIGHT% WRITE FORM "C10 PIC(####)" ; #ANDSP% ; " WEIGHT = ",WEIGHT% WAIT;6000 ! Wait 6 seconds so weight can be read. LOCATE #ANDSP% ; 2,1 ! Locate to second line. CLOSE SCALE% ! Close scale. WRITE #ANDSP% ; "SCALE IS CLOSED" WAIT ; 5000 ! Wait 5 seconds so message can be read. STOP ERRORA: ERROR ASSEMBLY ROUTINE hx% = ERRN ERRFX$ = "" for s% = 28 to zero STEP -4 sx% = shift(hx%,s%) THE.SUM% = sx% AND 000fh IF THE.SUM% > 9 THEN \   THE.SU THE.SUM%= M%=THE THE.SU .SUM%+ M%+55 55 \ ELSE \   THE.SUM%=THE.SUM%+48   A$=CHR$(THE.SUM%) ERRFX$ = ERRFX$ + A$ NEXT s% CLEARS ANDSP% WRIT WRITEE #AN #ANDS DSP% P%;" ;"ER ERR= R=", ",ER ERR, R,"" ERRL ERRL=" =",E ,ERR RRLL LOCATE #ANDSP%;2,1 WRITE #ANDSP%;"ERRF=",ERRF%," ERRN=",ERRFX$ WAIT ;15000 RESUME END

3-88

4690 Store System: Programming Guide

 

 

Serial I/O Communications Driver This section describes the serial I/O communications driver and provides guidelines for using it.

 Characteristics Characteristics The serial I/O communications driver has the following characteristics: Point of Sale Terminal supports supports a maxim maximum um of two feature expa expansion nsion car cards. ds. Each of  Each IBM 4683 Point these can contain contain two ports to attach attach serial communicati communication on I/O devices. devices. One port can atta attach ch an I/O device that is compatible with an Electronics Industries Association (EIA) RS232C interface and the other port can attach an I/O device compatible with an EIA RS232C interface or an asynchronous 20-milliampere current-loop interface.

 Each port can be used in either a half-duplex or full-duplex mode.  The terminal serial I/O port functions as Data Communications Equipment (DCE) and the serial communication device functions as Data Terminal Equipment (DTE) in terms of RS232C interface. |

   4684 terminals support serial ports COM1 and COM8 on the native serial ports and the ports on the dual asynchron asynchronous ous adapter. adapter. 4693 terminals terminals support support serial ports ports COM1 and COM2 on the native se serial rial ports and COM1 COM1 through COM8 on the Dual Dual Async adapter. adapter. 4694 termi terminals nals and 4683-4x1 4683-4x1 termi terminal nal upgrades upgra des suppo support rt serial ports ports COM1 through through COM2 on the native serial serial ports. These ser serial ial I/O ports function as DTEs, and the serial communication device functions as DCEs as related to an RS232C interface.

| | | | |

To attach a device to the serial I/O port, you need the interface requirements of the particular device and the EIA RS232C or asynchronous asynchronous current-l current-loop oop interface interface requirements. requirements. Curren Currentt loop is supported on 4683 terminals. Commands allow you to communicate Commands communicate with the device. device. Your application application has respons responsibility ibility for any protocol requirements such as checkpointing, pacing, positive or negative response, or error recovery.

Functions Your Application Performs An application program can perform the following functions with the device attached to the serial I/O port (depending on the capability of the device):

    

Transmit data to the device Receive data from the device Set communication parameters Obtain Obta in status status

 

3-89

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Accessing the Serial I/O Port Use the OPEN SERIAL statement statement to gain acc access ess to the serial I/O driver. driver. Specify the fol following lowing par parameters ameters on the OPEN SERIAL statement: |

     

Serial I/O port to open (1 through 4). Transmit or receive speed (110, 300, 1200, 2400, 4800, 9600, or 19200 bits per second). Parity (even, odd, or none). Number of data bits per character (5 through 8).

If the bits-per-character is less than eight, the significant bits are placed in the rightmost bits of each byte in the application buffer on a READ, and taken from the rightmost bits on a WRITE. Number of stop bits (1, 1.5, or 2).   Maximum application buffer size (1 through 247). You determine how to set these parameters by the interface requirements of the device attached to the seriall I/O port. The maximum seria maximum application application buffer buffer size is the maximum maximum number number of bytes th that at you will transmit or receive from the device on a single write or read operation. Once you have issued the OPEN SERIAL to a port, you cannot change any of the parameters associated with the OPEN SERIAL unless you issue a CLOSE to delete your I/O session and then issue another OPEN SERIAL with different parameters. Use the CLOSE statement to end your application's use of the serial I/O port.

Overview of Receiving Data Your application must enable receive mode on the serial I/O feature expansion to allow data to be received. recei ved. You should should al also so set a an n appr appropria opriate te interchara intercharacter cter timeout timeout value. value. An inter intercharac character ter time timerr is started starte d (using this value value as the upper limit) each each time a charact character er is receiv received. ed. As data characters characters are received, they are placed in a 247-byte driver buffer. Data in the driver buffer becomes available to your application when any of the following conditions occur:

 Data has been received and the timer expires before the next character is received.  The driver buffer is full. has been received and an error or special event is detected (see “Waiting for Received Data” for  Data a list of the errors or events). The normal condition that causes data to be available to your application should be the expiration of the intercharac interc haracter ter timer. This value must must be compatible with with the device send sending ing the data so that the timer expires expir es before 247 bytes bytes are received. received. If the driver buffe bufferr is filled, data is lost if more data is received received before the application reads the driver buffer data. If your device can send multiple blocks of data without a response from your application, you should read the driver driver buffer promptly promptly following following the availability availability of data. If data becomes available available because because the timer expired, and new data characters are received before the application performs a read operation, the new characters chara cters are added added to the driver buffer buffer data. This could result result in a buffer overrun overrun condi condition tion if the driver buffer data is not read promptly. If data has been and anr is error is detected, thetime error is applica not reported untilrms theaapplication reads the data alre already ady received. receireceived ved. The error erro reported the next next the application tion perfo performs wait or read

operation. opera tion. Any data received received following following the error error is discarde discarded d until the application application is notified notified of the error.

3-90

4690 Store System: Programming Guide

 

 

If the driver buffer is empty and an error occurs, the application is notified of the error on the next wait or read operati operation. on. Any data data rece received ived before before tthe he appl application ication is notified notified of the the error error is discar discarded. ded. Note that that data detected to be in error is never passed to the application; only the error status is passed.

Preparing to Receive Data from the Device Issue a PUTLONG to set up the following parameters in preparation for receiving data from the device:  Interc Intercharac haracter ter timeout timeout value. value. Choose a valu value e comp compatible atible with yo your ur de device. vice. The de default fault v value alue is 100 milliseconds.  Enable receive (byte CC, bit 2=1).  For a 4683 terminal feature expansion card I/O port, condition Data Set Ready (DSR) (byte CC, bit 1) and Clear To Send (CTS) (byte CC, bit 5) according to the requirements of your device.  For a 4683 terminal feature expansion card I/O port, Data Terminal Ready (DTR) must be active to receive recei ve data (byte CC, bit 6). Choose this this paramete parameterr according according to the requir requirements ements of your device. device.  For an I/O port not on a feature expansion card, condition DTR (byte CC, bit 1) and Request To Send (RTS) (byte CC, bit 5) according to the requirements of your device.  For an I/O port not on a feature expansion card, DSR must be active to receive data (byte CC, bit 6). Choose this this parameter parameter according according to the rrequire equirements ments of your your device device..

Waiting for Received Data Your application application should should issue a WAIT statement statement to wait for data from the device. device. In most cases you nee need d to wait for data from from multiple sources sources such such as the serial serial devi device ce and the I/O pr processo ocessor. r. The WAIT statement allows you to wait for input from multiple devices including a timer to indicate no input received during a specific specific time. When good data data is available from from the device, the statement statement following following the WAIT is executed. execut ed. When you wait on multiple multiple devices, devices, use the EVENT% statement statement to determine determine if the serial device was the device device satisfying satisfying the WAIT. If an error occu occurs rs during a WAIT, WAIT, control is given to your your ON ERROR routine. Any of the following conditions causes a WAIT to be satisfied by the serial I/O driver:

 The intercharacter timer expires.  The 247-byte system buffer is full.  One of the following errors or events occurs:  – not A fframing raming error is detected. det ected.time A framing fduring ramingreception error results the asynchronous character stop bit is detected at the proper of awhen character.  – A parity error is detected. Feature Expansion hardware error is detected.  – A break is received from the device.  – For a 4683 feature expansion card I/O port, DTR is iinactive nactive when DTR m monitoring onitoring is requested with a PUTLONG, and not configured as a current TCC Network.  – For an I/O port not on a feature expansion card, DSR is inact inactive ive when DSR monitoring moni toring is requested with a PUTLONG.

Receiving Data from the Device Issue READ LINE LINE to receive receive data from th the e dev device. ice. READ L LINE INE is a syn synchrono chronous us op operatio eration. n. If goo good d data is available from the device, the READ LINE is completed and the data is placed in your string variable specified specifi ed on the READ LIN LINE E statemen statement. t. You can use the the LEN functio function n to check the n number umber of byt bytes es received. receiv ed. If an error occurr occurred, ed, contr control ol is given to the O ON N ERROR routine. routine.

 

3-91

Chapter Chapt er 3. Programmi Programming ng Terminal Terminal I/O Devices Devices

 

 

Determining Serial I/O Port Status

|

The GETLONG statement returns the current settings of the control parameters that can be set with PUTLONG.. GETLONG also returns PUTLONG returns status informa information tion related related to the device and th the e ser serial ial I/O port. The status information contains the following information for a 4683 feature card serial port:    Data availab available le    Data Data lost lost  DTR status (at the time GETLONG is executed)  RTS status (at the time GETLONG is executed)    Par Parity ity err error or    Fra Framing ming err error or    Bre Break ak receiv received ed  Transmit buffer empty

| |

The status information contains the following information for 4684 and 4693 ports (both native and on Dual Async adapters), 4694, and 4683-421 terminal upgrade native serial ports.    Data availab available le    Data Data lost lost  DSR status (at the time GETLONG is executed)  CTS status (at the time GETLONG is executed)  Transmit buffer empty

Preparing to Transmit Data to the Device For a 4683 feature expansion card I/O port, issue a PUTLONG to condition DSR, CTS, and to set the option that that causes the driver driver to wait or not wait for DTR on transmit transmit (byte CC, bit zero). zero). These settings settings must be according to the requirements of your device. For an I/O port not on a feature expansion card, issue a PUTLONG to condition DTR, RTS, and to set the option that that causes the driver driver to wait or not wait for DSR on transmi transmitt (byte CC, bit zero). zero). These settings settings must be according to the requirements of your device.

Transmitting Data to the Device Issue a WRITE WRITE statement statement to transmit transmit data from your your applic application ation to the device. device. A WRITE is an asynchronou async hronous s operation. operation. The serial serial I/O drive driverr has one one tra transmit nsmit buffer. buffer. If all pr previous evious write o operati perations ons are are complete when you issue a WRITE statement, the driver fills its transmit buffer and returns control to the statement stateme nt following following the WRITE command. command. If a previous write write operation operation is not complete when you issue issue a WRITE, execution execution of your applicati application on is suspend suspended ed until the previous previous write ope operation ration end ends. s. You can see if a write operation is complete by checking the transmit buffer empty bit in the status returned on a GETLONG statement. A write operation is complete when any of the following conditions occur:

 All data specified on a WRITE has been sent to the device.  For a 4683 feature expansion card I/O port, DTR goes inactive for at least 30 seconds and wait for DTR active was set with a PUTLONG statement (byte CC, bit zero=1), and not configured as a current TCC Network.  A serial I/O feature expansion hardware error has been detected.

For a 4683 feature expansion card I/O port, RTS goes inactive for at least 30 seconds and not configured as a current TCC Network.  For an I/O port not on a feature expansion card, DSR goes inactive for at least 30 seconds and wait for DSR active was set with a PUTLONG statement (byte CC, bit zero=1).

3-92

4690 Store System: Programming Guide

 

 

 For an I/O port not on a feature expansion card, CTS goes inactive for at least 30 seconds. If an error is detected on a write operation, control is given to your ON ASYNC ERROR routine.

Sending a Break to the Device You can send a break to te theCC, device that attached an specifying  onuea a  on PUTLONG statement stateme nt (byte (by bit 3=1). 3= 1). isYou do nottohave ha veI/O to port resetbythe bi bit. t. Eachsend timebreak  you you issue iss PUTLONG statement statement with the send send break bit set, the driver driver sends a brea break k to the device. The seria seriall I/O feature expansion causes a break by generating 10 consecutive framing errors.

Simultaneous Receive and Transmit Your application can perform receive and transmit operations simultaneously by issuing a WRITE, which is executed asynchronously, and then a WAIT to wait for received data.

 Example Example This sample program uses the serial I/O interface to print the following 59-byte character set in a rippled pattern on a serial printer or video display using the RS232-EIA port. "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789&*:;'""@?,.$=!>327 >32767 67 then then 1500 1500 ! EXIT EXIT PROG PROGRA RAMM IF IF FIL FILEE IS IS GRE GREAT ATER ER THAN THAN MAX MAX if fsize% > 0 then 250 ! FILE IS VALID KEEP PROCESSING print "THIS PROGRAM COPIES FILES WITH A SIZE RANGE OF 1 - 32767 BYTES " print "THE FILE YOU SPECIFIED TO BE COPIED IS EMPTY " goto 2000 ! EXIT PROGRAM BECAUSE INPUT FILE IS EMPTY prin printt " THER THEREE ARE ARE"; "; fsiz fsize% e%;; "BY "BYTE TESS IN IN THE THE INPU INPUTT FIL FILEE "

5-7

num numcha "c"+str CON SIZE CHA READ/WRIT RITEE opechars$ n srs$ ende=r$ "c"+ restr$(f cl $(fsiz fsisize%) ze%e%) as i!os1CONVER % VERTT! SIZE OPENTOINCHARAC PUTRACTER FITER LE FOR READ/W openin% = 1 ! SUCCESSFUL OPEN INDICATOR crea create te rec recei eive ver$ r$ rec recll fsiz fsize% e% as as ios2 ios2%% ! CREA CREATE TE A NEW NEW OUTP OUTPUT UT FIL FILEE openout% = 1 ! SUCCESSFUL OPEN INDICATOR read read form form numc numcha hars rs$; $; #ios #ios1% 1%,r ,rnu num% m%;; dat data1 a1$$ ! READ READ THE THE DAT DATAA FRO FROMM SEN SENDE DERR 5-8

4690 Store System: Programming Guide

 

 

    1000 1000

1200 1500 2000    

write form write form numc numchar hars$ s$ ;#ios2 ;#ios2%,r %,rnum num%; %; data1$ data1$ ! WRITE WRITE THE DATA DATA TO TO RECE RECEIVE IVERR print " " print " COPY COMPLETE " pr close ios1% ! CLOSE INPUT FILE close ios2% ! CLOSE OUTPUT FILE wait;5000 wa ! PAUSE goto 100 ! GO BACK TO THE BEGINNING prin printt " AN ERR ERROR OR HAS HAS OCC OCCUR URRE REDD " print " CHECK THE DATA YOU INPUT FOR THE SENDER/RECEIVER" wait;5000 ! PAUSE SO THAT MESSAGE CAN BE READ if open openin in%% LIB86 MATHLIB=MULT,DIVIDE.L86 The preceding example creates a library file named MATHLIB.L86 from the input files MULT.OBJ and DIVIDE.L86.

Appending an Existing Library To add a module to an existing library, specify the existing library file name on both sides of the equal sign. Then, list list the input files files you want to append append.. Include the L86 file extension extension for the the libra library ry file name on the right side of the equal sign. The following example appends the files ONE.OBJ and LIB1.L86 to the existing library file TESTLIB.L86:

A:>LIB86 TESTLIB=TESTLIB.L86,ONE,LIB1.L86 You can rename an appended library file, as shown in the following example:

A:>LIB86 NEWTEST=TESTLIB.L86,ONE,LIB1.L86 The preceding example appends the files ONE.OBJ and LIB1.L86 to the existing library TESTLIB.L86, creating a new library file named NEWTEST.L86.

 

Chapter Chapt er 8. Using the LIB86 LIB86 Library Library Utili Utility ty

8-3

 

 

Replacing Library Modules Use the REPLACE option to replace a module in an existing library file. The following command line replaces the module ONE with the file NEWONE.OBJ in the library file TESTLIB.L86. Note: See the correct use of brackets in the command line.

A:>LIB86 TESTLIB=TESTLIB.L86 [REPLACE [ONE=NEWONE]] If you want to replace a module but maintain the same module name, specify the name only once after the REPLACE option. The following example replaces the module ONE with a new ONE.OBJ file in the library TESTLIB.L86, and renames the library NEWLIB.L86:

A:>LIB86 NEWLIB=TESTLIB.L86 [REPLACE [ONE]] You can replace replace several several modules with one one command line. Separate Separate the REPLACE option option specifi specifications cations with commas, as shown in the following example:

A:>LIB86 NEWLIB=TESTLIB.L86 [REPLACE [ONE=NEW1, TWO=NEW2]] You cannot use the command-line options DELETE and SELECT with REPLACE in the same command line. LIB86 displays an error message if it cannot find a specified module in the library file.

Deleting Library Modules Use the DELETE option to delete modules from an existing library file as shown in the following example. Module TWO is deleted from the library file TESTLIB.L86:

A:>LIB86 TESTLIB=TESTLIB.L86 [DELETE [TWO]] You can delete delete several modules modules with one command command line. Separa Separate te modules after after the option DELETE DELETE with commas. The following example deletes three modules to create a new library named NEWLIB.L86:

A:>LIB86 NEWLIB=TESTLIB.L86 [DELETE [ONE, TWO, FIVE]] You can delete a group of contiguous library modules using a hyphen, as shown in the following example:

A:>LIB86 NEWLIB=TESTLIB.L86 [DELETE [ONE - FIVE]] The preceding command line deletes all modules from module ONE through module FIVE. You cannot use the command-line options REPLACE and SELECT with the DELETE option in one command line.

LIB86 displays an error message if it cannot find a specified module in a library file.

8-4

4690 Store System: Programming Guide

 

 

Select Sel ecting ing Mod Module ules s Use the SELECT option to select specific modules from an existing library to create a new library. The following example creates a new library named NEWLIB.L86 that consists of three modules selected from OLDLIB.L86: A:>LIB86 NEWLIB=OLDLIB.L86 [SELECT [TWO, FOUR, FIVE]] You can select a group of contiguous library modules using a hyphen, as shown in the following example. A new library is created that consists of five modules selected from an existing library, assuming modules ONE, TWO, THREE, FOUR, and FIVE are contiguous in the library file.

A:>LIB86 NEWLIB=OLDLIB.L86 [SELECT [ONE - FIVE]] You cannot use the command-line options DELETE and REPLACE with the SELECT option in the same command line. LIB86 displays an error message if it cannot find a specified module in a library file.

Displaying Library Information LIB86 can produce produce listing files of of two types: a cro cross-r ss-referen eference ce file and a librar library y modu module le map map.. A cross-reference file contains an alphabetized list of all public, external, and segment name symbols a library librar y file file.. Following Following each each symbol symbol is a list of all modules that contain contain the symbol. symbol. LIB86 marks the module or modules modules that define the symbol symbol with a pound (#) sign. sign. LIB86 encloses encloses segment segment names in slashes slashe s (//). For example, example, the s segment egment C CODE ODE would appear as /CODE/ /CODE/.. Use the XREF option to create a cross-reference listing for a specified library file. The following example creates a cross-reference file named TESTLIB.XRF for the TESTLIB.L86 library file:

A:>LIB86 TESTLIB.L86 [XREF] A module map contains contains an alphabetized alphabetized list of all modules modules in a library file. Followi Following ng each module name name is a list of all segments segments in the mod module ule and the len length gth of each segment. segment. A module map also also include includes s a list of all public and external symbols specified in the module. Use the MAP option to create a module map for a specified library file. The following example creates a module map named TESTLIB.MAP for the TESTLIB.L86 library file:

A:>LIB86 TESTLIB.L86 [MAP] Usually, LIB86 alphabetize Usually, alphabetizes s the names of modules modules in a mod module ule map listin listing. g. Use the NOAL NOALPHA PHA option to produce a module map that lists module names in order of occurrence, as shown in the following example:

A:>LIB86 TESTLIB.L86 [MAP, NOALPHA]

You can use LIB86 to create partial library information maps using the MODULES, SEGMENTS, PUBLICS,, and EXTERNALS PUBLICS EXTERNALS options. options. You can use the the four opti options ons in any com combinatio bination. n. The following example creates a module map that contains only public and external symbols:

A:>LIB86 TESTLIB.L86 [PUBLICS, EXTERNALS]

 

Chapter Chapt er 8. Using the LIB86 LIB86 Library Library Utili Utility ty

8-5

 

 

You can combine the SELECT option with any of the options previously described to generate partial library information maps, as shown in the following examples:

A:>LIB86 TESTLIB.L86 [XREF, [SELECT [ONE, + TWO, THREE]]] A:>LIB86 MATHLIB.L86 [MAP, NOALPHA, SELECT [MULT, + DIVIDE]] A:>LIB86 LIBRARY1.L86 [MODULES, SEGMENTS, SELECT + [ONE - FIVE]]

Accessing Files in Other Directories | |

LIB86 assumes assumes that all files specified specified on a command command line (or INP file) are in the defa default ult directory. directory. You can access acces s files in other directorie directories s in several ways. ways. These opti options ons are listed in their their order of prec precedence edence:: 1. A fully specified specified path path name can can be included included with with each L86 L86 or OBJ ffile ile name. The following following exa example mple shows how to specify locations of L86 or OBJ files that are not contained in the default directory:

|

A:>LIB86 C:\LIBA\NEW1=LIB1.L86,C:OBJ1\ONE,C:\OBJ2\TWO In this case, a new library, library, NEW1.L86, NEW1.L86, will be created in the C:\LIBA C:\LIBA directory. directory. The compon components ents of the new library will be LIB1.L86 (default directory), ONE.OBJ (C:\OBJ1 directory), and TWO.OBJ (C:\OBJ2 directory). 2. Options $M, $M, $O, and $X $X can be used used on the command line (or in an INP fil file). e). These o options ptions ov override erride the default default directory directory.. They must must be specifie specified d as follows: follows:

 $Ofilespec  $Ofilespec  specifies   specifies input OBJ or L86 file location. $Xfilespec  specifies   specifies output XRF file destination.  $Xfilespec   $M $Mfilespec  filespec  specifies   specifies output MAP file destination. The $O option remains in effect as the library utility processes a command line from left to right, until it encounters encoun ters another another $O. This feature feature is useful when you create create a library library from groups of file files s in different directories. The following command causes a MAP file to be placed in C:\MAPS, an XRF file to be placed in C:\XREFS, and looks for OBJ files only in the C:\OBJS subdirectory.

A:>LIB86 TEST.L86[X,MA,$XC:\MAPS,$MC:\XREFS,$OC:\OBJS] Note: The $O option is selectively ignored if a fully specified file name is used for any OBJ, INP, or L86 input file. | |

3. LIB86 recognizes 4690 logical file names, but does not supply the .OBJ file extension when an extension is not specified. 4. A search path can be set up to look for OBJ, L86, or INP files if they are not found in the default directory. direct ory. Environment Environment vari variable, able, LIB86PATH, LIB86PATH, shoul should d be set (or defined) defined) in the current DOS, OS/2, OS/2, or 4680 session before running the LIB86 utility. If you want the library utility to search for OBJ, INP, or L86 components first in the C:\NEWCODE, then in the C:\OLDCODE directories, establish that search path by issuing the following command: OS/2 or DOS:

A:>SET LIB86PATH=C:\NEWCODE;C:\OLDCODE 4680:

A:>DEFINE LIB86PATH=C:\NEWCODE;C:\OLDCODE When the library utility is subsequently run, OBJ, INP, and L86 files will be searched for along this path if they are not found in the default directory. Note: This option is selectively overridden if either option 1 or option 2 is specified for specific input files.

8-6

4690 Store System: Programming Guide

 

 

Chapterr 9. Chapte 9. Using the Linker Linker Utility Utility and the POSTLINK POSTLINK Utility Utility Introduction to the Linker Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9-2 LINK86 Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9-3 . Linking SharedOptions Runtime .Libraries LINK86 With Command . . . . . . . Command Comm and-Fi -File le Options Options   . . . . . . . . . CODE/DATA/STACK/EXTRA   . . . . SYM File Options . . . . . . . . . . . . NOSYMS   . . . . . . . . . . . . . . . LOCALS and NOLOCALS . . . . . LIBSYMS and NOLIBSYMS . . . . LIN File Options . . . . . . . . . . . . . MAP File Options . . . . . . . . . . . . L86 File Options . . . . . . . . . . . . . SEARCH and NOSEARCH Options SHARED and NOSHARED Options CODESHARED   . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

INPUT File Inpu Input/Ou t/Output tputOptions Option Option   .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. $C (Command) Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . | $D (Debug Information) Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . $L (Library) Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . $M (Map) Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . $N (Line Number) Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . $O (Object) Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . $S (Symbol) Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DBINFO DBIN FO Option Option   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . | Use of Link Path Variables to Search Other Directories . . . . . . . . . . . . . . . . . . . . . . . . . How Various Search Priorities Relate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use of ERRORLEVEL Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overlays   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overlay Command The POSTLINK Utility Line . . Syntax . . . . . . . Invoking the POSTLINK Utility . . . Use of ERRORLEVEL Test . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

.

 9-4  9-4 9-5 9-5  9-6 9-6  9-7  9-7  9-7  9-7  9-8  9-8  9-8 9-9  9-9 9-9  9-10  9-10  9-10  9-10  9-10  9-11  9-11 9-11  9-11  9-12  9-12 9-12

 9-13  9-15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9-15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9-15

© Copyright

9-1

IBM Corp. 1994, 1996

 

 

Introduction to the Linker Utility The linker utility, LINK86, is a linkage editor that combines relocatable object files into a load module that runs on the IBM 4690 Operating Operating Sys System. tem. Any IBM 4690-compatib 4690-compatible le compiler or assemble assemblerr can produc produce e the objec objectt file files. s. See Table Table 9-2 on on page 9-5 fo forr a summary summary of of command command-fi -file le opt option ion param paramete eters. rs. The linker linker is available available to run in a DOS, OS/2, OS/2, or 4690 Operating Operating Sy System stem environmen environment. t. The file LINK86.286 LINK86 .286 runs in the 4690 Operating Operating System System environment. environment. LINK86. LINK86.EXE EXE runs in either a DOS (Ve (Version rsion 3.3 or higher) higher) or OS/2 (Version (Version 1.2 or higher) environme environment. nt. The linker utility utility is shippe shipped d in the 4690 Optional Programs diskette. LINK86 accepts the following types of files as input: Object (OBJ) file A language source file that has been translated by the compiler or assembler into a machine-readable object code. Library (L86) file An indexed library library of commonly commonly used object object modules. modules. The library library utility LIB86 gen generates erates library files. Input (INP) file A file that contains file names and options, the same as a command line you enter from the keyboard. LINK86 creates the following types of files: Executable Load Module (286) file Contains a memory image of a program and runs directly under the operating system. Overlay (OVR) file Contains information that is loaded into memory when it is needed by the program. Symbol Table (SYM) file Contains a list of symbols from the object files and their offsets. Line Number (LIN) file Contains Contain s a list of code offs offsets ets of program program sourc source e lines. This file is created created on only ly when the compiler puts line number information into the object files being linked. Map (MAP) file Contains segment information about the load module. | |

Debug Information (DBG) file Contains information used by the 4690 application debugger. During processin processing, g, LINK86 displa displays ys unresolved unresolved symbols. symbols. An unresolved unresolved symbol is declar declared ed to be external in one or more modules, but is not publicly defined in any module.

|

When processin processing g is complete, LINK LINK86 86 displays displays the size of each section section of the load module. See Fi Figu gure re 99-1 1o on n pag page e 99-3. 3.

9-2

4690 Store System: Programming Guide

 

 

LIN (LineNumberFile)

OBJ1 (Ob (ObjectFile jectFile)) . . . OBJn (Ob (ObjectFile jectFile))

286(Command File) 286(Command or OV OVR R (OverlayFile) (OverlayFile)

L861(LibraryFile) . . . L86n(LibraryFile)

LINK86

INP (Inpu (Inputt Command Command File)

SYM (Symbol (Symb ol TableFile)

MAP(MapFile)

DBG(DebugFile)

Fig Figure ure 9-1. 9-1. LINK86 LINK86 Operati Operation  on 

LINK86 Command Syntax You invoke LINK86 with the following command format: LINK86 [filespec  [filespec   =] =] filespec1 filespec1 [  [,filespec2, ,filespec2,... ...,filespecn  ,filespecn ] filespec   is is a file specification, consisting of an optional path specification and a file name with optional file extension. extens ion. If you enter a file file name to the left of the equal equal sign sign,, LINK86 cre creates ates outp output ut files with tha thatt file name and the appropriate file extensions. For example, using the files PARTA, PARTB, and PARTC, the following command creates MYFILE.286:

A:>LINK86 MYFILE = PARTA,PARTB,PARTC PARTA, PARTB, PARTB, and PARTC can be be a combination combination of object object files and library library files files.. If no Note: The files PARTA, file extension is specified, the linker assumes a file extension of OBJ. If you do not specify an output file name, LINK86 creates the output files using the first file name in the command line. For example, the following command creates the file PARTA.286:

A:>LINK86 PARTA,PARTB,PARTC Note: If you specify a library file in your link command, do not enter the library file as the first file in the command line.

 

Chapter 9. Using the Linker Utility and the POSTLINK Utility

9-3

 

 

You can also instruct LINK86 to read its command line from a file, thus making it possible to store long or commonly used link commands on disk:

A:>LINK86 LINKFIL[I] Additional linker options are discussed later in this chapter.

Linking With Shared Runtime Libraries LINK86 supports supports store controller-s controller-shared hared runtime runtime libraries libraries.. Shared Shared runtime libraries libraries (SRTLs) allow multiple users to share share a single copy of library library code at runtime. runtime. It is not necessary necessary for each user to sto store re librar library y code in their load load module. When libraries libraries are shared, shared, only referenc references es to the library co code de are linked with with a user’s object files. | |

No extra steps steps are required required when linking linking BASIC object files files with SRTL files. Do not specify the ru runtime ntime libraries librar ies SB286L.L86 SB286L.L86 or SB286TVL.L86. SB286TVL.L86. They are automatically automatically requested requested by the compile compiler. r. “SHARED and NOSHARED Options” Options” on page 9-8 for information information on linki linking ng with share shared d Note: See “SHARED runtime libraries.

LINK86 Command Options When you invoke invoke LINK86, LINK86, you can specify com command mand options options that control control the link operatio operation. n. Command options are in one of three categories, depending on the type of file affected. Command options in the first category affect the contents of the command file and apply to the entire link operation. opera tion. Command Command options options in the second second category category aff affect ect th the e SYM and MAP MAP files. files. These options turn on and off as LINK86 LINK86 processes processes the command command line line from left to right. right. Command o options ptions in the th third ird category affect the library and input files and apply to one file in the command line. When you specify command options, enclose them in square brackets following the file name. A command option is specified using the following command format:

A:>LINK86  file[option] For example, to specify the command option MAP for the file TEST1 and the NOLOCALS option for the file TEST2, enter the following:

A:>LINK86 TEST1[MAP],TEST2[NOLOCALS] You can use spaces to improve the readability of the command line, and you can put more than one option in square brackets by separating them with commas. The following example specifies that the MAP and NOLOCALS options be used for the TEST1 file and the option LOCALS for the TEST2 file:

A:>LINK86 TEST1 [MAP, NOLOCALS], TEST2 [LOCALS]

Ta Tabl ble e 99-1 1 (P (Pag age e 1 of 2 2). ). LI LINK NK86 86 Co Comm mman and d Opti Option ons s an and d abbr abbrev evia iati tion ons  s  Option

Abbreviation

Meaning

CODE

C

Controls contents of CODE section of load module.

DATA

D

Controls contents of DATA section of load module.

EXTRA

E

Controls contents of EXTRA section of load module.

9-4

4690 Store System: Programming Guide

 

 

Tabl Table e 99-1 1 (Pa (Page ge 2 of of 2). LINK LINK86 86 Comm Comman and d Opti Option ons s and and abbr abbrev evia iatio tions  ns  Option

Abbreviation

Meaning

STACK

ST

Controls contents of STACK section of load module.

LIBSYMS

LI

Include symbols from library files in SYM file.

NOLIBSYMS **

NOLI

Do not include symbols from library files in SYM file.

LOCALS **

LO

Include local symbols in SYM file.

NOLOCALS

NOLO

Do not include local symbols in SYM file.

NOSYMS

NOSY

Inhibits generation of a SYM file.

LINES **

LIN

Create LIN file with line number information.

NOLINES

NOLIN

Do not create LIN file.

NOSEARCH

NOSE

Link all library modules whether referenced or not.

MAP

M

Create a MAP file.

SEARCH **

S

Search library and only link referenced modules.

SHARED

SH

Force an SRTL to be treated as shared.

NOSHARED

NOSH

Force an SRTL to be treated as a normal unshared library.

CODESHARED

CODESH

Designates that this load module’s code can be shared by multiple processes. process es. After a load load modul module e is link linked ed CODE CODESHARED, SHARED, th the e load module must be POSTLINKed using the POSTLINK Utility.

INPUT

I

Read command line from disk file.

ECHO

ECHO

Echo contents of INP file to the screen.

DBI

DBI

Create a DBG file that contains debug information.

Note: ** = Default Value

Comman Com mand-F d-File ile Option Options s The options described in this section affect the contents of the command file created by LINK86. Table 9-2 lists th the e command-file command-file option option parameters. parameters. Tabl Table e 99-2. 2. Comm Comman andd-Fi File le Op Opti tion on Param Paramete eters  rs  Parameter

Abbreviation

Meaning

GROUP

G

Groups to be included in load module section

SEGMENT

S

Segments to be included in load module section

ADDITIONAL

AD

Additional memory allocation for the load module section

MAXIMUM

M

Maximum memory allocation for load module section

CODE/DATA/STACK/EXTRA: A load module consists of a 128-byte header record ordinarily followed followe d by four section sections. s. The sections sections are called called CODE, DATA, DATA, ST STACK, ACK, and and EXTRA. EXTRA. Each of of the sections correspond sections correspond to a LINK86 command command option of the same name name.. The heade headerr contains the len length gth of

each section section of the load module and its minimum minimum and maximum mem memory ory requi requirements rements.. The opera operating ting system uses the header to load the file.

 

Chapter 9. Using the Linker Utility and the POSTLINK Utility

 

 

GROUP and SEGMENT The GROUP and SEGMENT parameters each contain a list of groups or segments that you want LINK86 to put into a specified section of the load module. For example, the following command instructs LINK86 to put the segments CODE1, CODE2, and all the segments in group XYZ into the CODE section of the file TEST.286: A:>LINK86 TEST [CODE [SEGMENT [CODE1, CODE2], BGROUP [XYZ]]] ADDITIONAL and MAXIMUM The ADDITIONAL and MAXIMUM parameters tell LINK86 the values to put in the load module header. These parameters override the default values that LINK86 uses. Each parameter is a hexadecimal number enclosed in square brackets. The ADDITIONAL parameter specifies the amount of additional memory, in paragraphs, required by the specified section of the load module. Note: A paragraph is 16 (X'10') bytes. The MAXIMUM parameter specifies the maximum amount of memory needed by the section of the load module.. The program module program loader attempts attempts to allocate as much much of the requeste requested d maximum as poss possible. ible. In the following example, the command creates the file TEST.286: |

A:>LINK86 TEST [DATA [ADD [100], MAX[FFF]]] The TEST.286 file header contains the following information:

 The DATA section requires at least X '100' paragraphs in addition to the data in the load module.  The DATA section can use up to X 'FFF' paragraphs of memory.

SYM File Options The following command options affect the contents of the SYM file that LINK86 creates:          

    

NOSYMS LOCALS NOLOCALS LIBSYMS NOLIBSYMS

These options options must appear appear in the command line after after the specific specific file or files to which they appl apply. y. When you specify specify one of these options, options, it remains in effect effect until you specify an another other opti option. on. Theref Therefore, ore, if a command line or input file (INP) contains two options, the leftmost option affects all of the listed files until the next option option is encountered. encountered. The next option option affects all remaining remaining files spe specified cified on the command command line or input file.

9-5

NOSYMS: The NOSYMS option option prevents prevents the ge generati neration on of a SYM file. In this case case,, all other SYM fil file e options are ignored.

9-6

4690 Store System: Programming Guide

 

 

LOCALS LOC ALS and NOL NOLOCA OCALS: LS: Th The e LO LOCA CALS LS op opti tion on dir direc ects ts LINK LINK86 86 to in incl clud ude e lo loca call symb symbol ols s in the the SYM file if they are are in the object object files being linked. linked. The NOLOCALS NOLOCALS option in instruc structs ts LINK86 to ign ignore ore local symbols symbols in the object object files. files. The default default is LOCALS. LOCALS. For example, the following command creates a SYM file containing local symbols from TEST2.OBJ and TEST3.OBJ, but not from TEST1.OBJ:

A:>LINK86 TEST1 [NOLOCALS], TEST2 [LOCALS], TEST3

LIBSYM LIB SYMS S an and dN NOLI OLIBSY BSYMS: MS: Th The e LIBS LIBSYM YMS S op opti tio on in inst strruc ucts ts LINK LINK86 86 to in inc clu lude de in the the SYM SYM file file symbols from a library sea symbols searched rched during during the link operation. operation. The NOLIBSYMS NOLIBSYMS option instructs instructs LINK86 LINK86 not to include library library symbols symbols in the SYM file. A library sea search rch usually usually involves involves the runtime sub subroutin routine e library of a high-level high-level language such such as IBM 4680 BASIC. Becau Because se the symbols in such such a library are usu usually ally of no interest to the programmer, the default is NOLIBSYMS. The following example disables library symbol generation for ADXADMBL.L86:

A:>LINK86 TEST,ADXACRCL.L86,ADXADMBL.L86 [NOLI]

LIN File Options The IBM 4680 BASIC compiler compiler provides provides an option that that puts line numbers numbers into object files files.. If line numbers numbers are present in the object file, LINK86 can create a file containing line numbers and their code offsets. The LINES and NOLINES options specify whether or not LINK86 creates a LIN file. The LINES option, option, which which is active by default, default, instructs instructs LIN LINK86 K86 to create create a LIN file, if poss possible. ible. If no line information informa tion is present present in the object object file, LINK LINK86 86 does not cr create eate the LIN file file.. The NOLINE NOLINES S option instructs LINK86 not to create a LIN file, even if line numbers are present in the object file:

A:>LINK86 TEST [NOLIN]

MAP File Options The MAP option instructs LINK86 to create a MAP file containing information about segments in the load module. The amount of information that LINK86 puts into the MAP file is controlled by the following optional parameters: OBJMAP NOOBJMAP L86MAP NOL86MAP ALL NOCOMMON The optional optional parameters parameters are enclosed enclosed in brackets brackets following the MAP option. option. The OBJMAP parameter parameter directs direct s LINK86 to put segment segment information information about about OBJ file files s in the MAP file. The NOOBJM NOOBJMAP AP parameter parameter suppresses suppr esses this information. information. The L86MAP parameter parameter instr instructs ucts LINK86 to put segment information information from L86 files files into into the MAP file. file. The NOL86MAP NOL86MAP parame parameter ter suppres suppresses ses th this is inf informatio ormation. n. The A ALL LL parameter parameter instructs instru cts LINK86 to put all the information information into the MAP file file.. The NOCOMMON pa parameter rameter s suppres uppresses ses all

common segments from the MAP file.

 

Chapter 9. Using the Linker Utility and the POSTLINK Utility

9-7

 

 

When you instruct LINK86 to create a MAP file, you can change the parameters to the MAP option at different differ ent points in the command command line. For example, example, the following following command directs directs LINK86 to cre create ate a map file containing segment information from FINANCE.OBJ and SCREEN.L86:

A:>LINK86 FINANCE [MAP[ALL]],SCREEN.L86,GRAPH.L86 [MAP[NOL86MAP]] Notes: 1. Segment information information for GRAPH.L86 GRAPH.L86 is suppressed suppressed by the NOL86MAP option. 2. If you specify the MAP option with no parameters, LINK86 uses OBJMAP and NOL86MAP as defaults.

L86 File Options The following command options determine how the library files are used by LINK86:        

   

SEARCH NOSEARCH SHARED NOSHARED

SEARCH SEA RCH an and d NOS NOSEAR EARCH CH Op Optio tions: ns: Th The e SEAR SEARCH CH opti option on inst instru ruct cts s LINK LINK86 86 to sear search ch the the preceding library, and include in the load module only those modules that satisfy external references from other modules. modules. Because Because SEARCH SEARCH is the de default fault v value, alue, u using sing it as a value value is redund redundant. ant. The NOSEARCH NOSEARCH option instructs the linker to include in the load module all modules whether an external reference is satisfied or not. Note: LINK86 searches L86 files automatically. The NOSHARE option must be specified for each module to be linked. For example, the following command creates the file TEST1.286 by combining the object files TEST1.OBJ, TEST2.OBJ, and modules from MATH.L86 that are referenced in TEST1.OBJ or TEST2.OBJ:

A:>LINK86 TEST1, TEST2, MATH.L86 The modules modules in the library file do not have have to be in any special order order.. LINK86 mak makes es multiple passes passes through the library index when attempting to resolve references from other modules.

SHARED SHA RED an and d NOS NOSHAR HARED ED Op Optio tions: ns: Th The e SHAR SHARED ED and and NOSH NOSHAR ARED ED opti option ons s dete determ rmin ine e whet whethe herr a library library file is to be used as an an SRTL. When a run runtime time libra library ry is NOSHARED, NOSHARED, both the co code de and the data from that library library are linked linked with the object files. files. When a runtime library library is SHARE SHARED, D, only the data from that library is linked with the object files, and a single copy of the library code resides in a special load module module called an executable executable shared shared runtime library library (XSRTL). (XSRTL). The code stor stored ed in an XSRTL file can be accessed by any file linked as a user of the SRTL. When an SRTL is created, it is given an attribute that determines whether the library is to be treated as a SHARED or a NOSHARED option. The store controller runtime library for IBM 4680 BASIC (SB286L.L86) was created with the SHARED

attribute. If an SRTL has a default attribute of SHARED, you can force LINK86 to treat it as a normal library by specifying specif ying the NOSHARED NOSHARED option. This forces forces the referenced referenced SRTL routines routines to be resident resident in the user’s code file, and the loader does not have to perform a load-time resolution of external references.

9-8

4690 Store System: Programming Guide

 

 

As an example of the NOSHARED option, the following command format causes LINK86 to treat the shareable runtime library as an unshared library:

A:>LINK86 MYPROG=MAIN,PART1,PART2[NOSHARED]

CODESHARED: Normally a load module created by the linker has a bit set in the header that identifies identifi es to the loader that only only one process process can use the code segments segments at one time. By specify specifying ing the CODESHARED option, you can force the loader to use the same copy of the module’s code segments for multiple processes. Note: A load module that has been linked with the CODESHARED option must be POSTLINKed using the POSTLINK Utility before the 4690 Operating System will allow it to run. If you are executing the same application program in both the Model 1 and Model 2 terminals, you should use this option option because it saves saves a significant significant amount of storag storage. e. If your application application uses the Dis Display play Manager* product, you must NOT  use   use this option because the Display Manager’s code is not shareable.

INPUT File Options The INPUT and ECHO command options determine how LINK86 uses the input file. The INPUT option option instructs instructs LINK86 to obtain further further command-lin command-line e input from the file. Other files ca can n appear in in the command command line, but the input input file must be the last last file name on the the command liline. ne. When LINK86 encounters the INPUT option, it stops scanning the command line entered from the keyboard. Note: You cannot cannot nest command command input files. files. A command in input put file cannot cannot contai contain n the INPUT opti option. on.

|

The input file consists of file names and options the same as a command line entered from the keyboard. An input file can contain contain up to 4096 chara characters, cters, including including spaces spaces but excluding excluding commen comments. ts. Comment delimiters recognized by LINK86 are ; are  ; and  and * **.. When LINK86 LINK86 e encount ncounters ers eit either her of these delimiter delimiters s in an input file, the remaining remaining character characters s on that line are ignor ignored. ed. Use commen comments ts as often as you like to make the input file easier to understand and maintain.

|

In the following example, the file TEST.INP might include the lines:

|

;This is a comment

| | |

MEMTEST=TEST1,TEST2,TEST3, IOLIB.L86[S],MATH.L86[S], **This is another comment TEST4,TEST5[LOCALS]

| | |

To direct LINK86 to use this file for input, enter the following command format:

A:>LINK86 TEST.INP [INPUT] If no file extension is specified for an input file, LINK86 assumes INP. The ECHO option causes LINK86 to display the contents of the INP file on the display:

A:>LINK86 TEST [ECHO,I]

 Input/Out Input/ Output put Option Option The $ option controls controls the source source and destination destination device devices s under LINK86. LINK86. The general general form of the $ option is:

$tpathname   is a file type, and pathname  is   is a fully specified path or a drive letter followed by a colon. Note: t  is

 

Chapter 9. Using the Linker Utility and the POSTLINK Utility

9-9

 

 

| | | | | | | |

File File T Typ ypes es:: LINK86 recognizes the following seven file types:

C D L M N O S

-

Load Load Modu Module le (286 (286 or OVR) OVR) Debu Debugg Info Inform rmat atio ionn File File (DB (DBG) G) Libr Librar aryy Fil Filee (L86 (L86)) Map Map File File (MA (MAP) Line Line Num Numbe berr Fil Filee (LIN (LIN)) Obje Object ct File File (OBJ (OBJ or L86) L86) Symb Symbol ol File File (SYM (SYM))

The value of a $ option remains in effect until LINK86 encounters a countermanding option as it processes the command command line from left left to right. For example, example, the following following command command will link TEST1.OBJ TEST1.OBJ and and TEST2.OBJ files from subdirectory C:\OBJ1 with the TEST3.OBJ file in subdirectory C:\OBJ2:

C:>LINK86 TEST.286=TEST1 [$OC:\OBJ1],TEST2,TEST3[ $OC:\OBJ2]

$C (Co (Comma mmand) nd) Opt Option ion:: Th The e $C op opti tion on us uses es the the foll follow owin ing g form format at:: $C pathname LINK86 usually creates the load module in the same subdirectory as the first object file in the command line. The $C option instructs instructs LINK86 LINK86 to place place the load module module in the spe specified cified directory. directory. The $C option also applies to OVR files when you use LINK86 to create overlays. A:>LINK86 TEST [$CC:\286S] | |

$D (Debug (Debug In Inform formati ation) on) Op Optio tion: n: Th The e $D op opti tion on us uses es the the foll follow owin ing g for forma mat: t: $D pathname

|

LINK86 normally normally creates creates the DBG file in the default directory directory.. The $D option instructs instructs LINK86 LINK86 to place the DBG file in the directory you specified with the pathname.

|

A:>LINK86 TEST [$D:\DBGS]

|

$L (Lib (Librar rary) y) Op Opti tion on:: Th The e $L op opti tion on us uses es the the foll follow owin ing g for forma mat: t: $L pathname LINK86 searches searches the default directory directory for runti runtime me subroutine subroutine librarie libraries s that are linked automati automatically. cally. The $L option instructs LINK86 to search the specified pathname  for   for the runtime subroutine libraries.

A:>LINK86 TEST [$LC:\LIBS] The e $M op opti tion on us uses es the the foll follow owin ing g for format: mat: $M (M (Map ap)) O Opt ptio ion: n: Th $M pathname LINK86 normally normally creates creates the MAP file in the default directory directory.. The $M option instructs instructs LINK LINK86 86 to place the MAP file in the specified directory.

A:>LINK86 TEST [$MC:\MAPS]

$N (Lin (Line e Nu Numbe mber) r) O Opti ption: on: Th The e $N op opti tion on us uses es the the foll follow owin ing g form format at:: $N pathname

9-10

4690 Store System: Programming Guide

 

 

LINK86 normally normally creates creates the LIN file in the same subdirector subdirectory y as the load module. The $L option dir directs ects the linker to place the LIN file in the directory specified by the pathname  that   that follows the $N option:

A:>LINK86 TEST [$NC:\LINS]

$O (Ob (Obje ject ct)) Op Opti tion on:: Th The e $O op opti tion on us uses es the the foll follow owin ing g for forma mat: t: $O pathname LINK86 searches for the OBJ or L86 files that you specify in the command line on the default drive, unless such files have have drive prefixes. prefixes. The $O option allows allows you to specify the drive drive locatio location n of multiple OBJ or L86 files without adding a path name prefix to each file name. In the following example, the command instructs LINK86 that all the object files except the last one are located in subdirectory D:\OBJS.

A:>LINK86 P [$OD:\OBJS],Q,R,S,T,U.L86,B:V Note: This does does not apply to libraries libraries tthat hat are linked linked automa automatically tically.. See the $L opti option. on.

$S (Sym (Symbo bol) l) O Opti ption on:: Th The e $S op opti tion on us uses es the the foll follow owin ing g for forma mat: t: $S pathname LINK86 normally normally creates creates the symbol file in the same same subdirectory subdirectory as the load module. module. The $S option directs LINK86 to place this file in the subdirectory specified by the pathname  that   that follows the $S option.

A:>LINK86 TEST [$SC:\SYMS] |

DBINFO DBI NFO Opti Option: on: The DBINFO option instructs LINK86 to create a DBG file containing necessary

information for the 4680/4690 information 4680/4690 Application Application Debugger. Debugger. If you are combining combining sever several al OBJ and/or L86 | modules, specify the DBI option on the first OBJ file listed on the command line or in the INP file. |

Refer to the IBM 4680-4690 Application Debugger User’s Guide  for   for additional information about compiling | and linking an application to prepare it for debugging.

|

|

A:>LINK86 TEST fflDBI“

Use of Link Path Variables to Search Other Directories Sometimes you might want Sometimes want to search a particul particular ar path to find OB OBJ, J, L86, or INP fil files. es. If a file is not found in the first directory, directory, the search search continues continues to other directories directories in the specified specified path path.. Using this method, method, you can make modifications to a base set of OBJ files and keep the modified OBJ files in a separate directory or series of directories. Using the LNK86PATH environment variable, you can define the search order so the linker looks first in the changed files directory and, if not found, then looks in the base directory. The LNK86PATH environment variable is defined using the SET command (DOS or OS/2) or the DEFINE

command (4690). (4690). This variable variable must be set at least once before before runn running ing the linker uti utility, lity, and it must be set during the same session. Under DOS or OS/2, use the following command:

A:>SET LNK86PATH= path1;path2;path3; where pathn  represents   represents the directories that you intend to search for files to be read by the linker.  

9-11

Chapter 9. Using the Linker Utility and the POSTLINK Utility

 

 

Under 4690 Operating System, use the following command:

A:>DEFINE LNK86PATH= path1;path2;path3  intend to search for files to be read by the linker.

How Various Search Priorities Relate The following search order is used when linking with files in remote directories: 1. A path name name specified specified as part part of a file name name on the c command ommand line line or in an INP file. If the file is not found, the search is abandoned. 2. The $ directives directives $O and $L $L.. If an OBJ, INP, INP, or L86 file file is not found found in the the specif specified ied dire directory, ctory, tthe he search is abandoned. 3. The default directory. directory. 4. The path specified specified by the environment environment variable variable LNK86PATH. LNK86PATH.

Use of ERRORLEVEL Test When runisning running the LINK86 program program from from avalue batch theisresults of the ca n be for errors. erro If the link step succ successful essful, , an ERRORLEVEL val ue offile, zero return returned. ed. Tolink testcan for an tested error, error, use the rs. batch file statement “IF ERRORLEVEL 1....” The following is an example within a batch file:

LINK86 TEST IF ERROR ERRORLEV LEVEL EL 1 ECHO ECHO We have have a probl problem em >> RESU RESULTS LTS In the above example, if the link of the TEST file fails the message “We have a problem” is written to the file RESULTS.

Overlays  Overlays Overlays Overla ys are suppor teddonly in the controlle sectio ne describe describes s how LINK86 programs pro grams with separ separate atesupported files called calle overlays. overlay s. store Eachcontroller. overlay overlay r. fileThis is a section separate separat program mod module ule that creates is loaded into memory when when it is needed by the program. program. By loading only only those program program module modules s that are needed at a particular time, the amount of memory used by the program is kept to a minimum; however, you must link your application with the runtime library using the NOSHARED option. As an example, many application programs are menu-driven, with the user selecting the functions to perform. perfor m. Becaus Because e the program’s modu modules les are separate separate and invoked sequentially sequentially,, they need not reside in memory simultaneo simultaneously. usly. Using over overlays, lays, each each function on the menu can be a separate separate subp subprogra rogram m that is stored store d on disk, and loaded only only when required. required. When one func function tion is comple completed, ted, contro controll returns to the menu portion portion of the the program. program. You then select select the the next function. function. Figure 9-2 shows shows the concept concept of using using lar large ge program program ove overlays. rlays. Assume tthat hat a menu menu-drive -driven n applic application ation

program consists of three separate program separate user-selec user-selectable table functions. functions. If each function requ requires ires 30K of memory, and the menu portion requires 10K, then the total memory required for the program is 100K (without overlays). overl ays). Howeve However, r, if the three functions are designed designed as overlays (separat (separate e overlays overlays), ), the program requires only 40K, because all three functions share the same locations in memory. Note: The POSTLINK Utility must not be used on overlay files or the root module of an overlay file.

9-12

4690 Store System: Programming Guide

 

 

Function 3

30K

Function 1 Function 2

Function 2

Function 3

30K 30K

100K

40K Function 1

30K

Menu

10K

10 K

Menu

Fi Figu gure re 99-2. 2. Usin Using g Ov Over erla lays ys iin n a Larg Large e Prog Progra ram  m 

You can also also create create nested nested over overlays lays in the the form of a tr tree ee structure. structure. Figure 9-3 sh shows ows a tree tree struct structure ure overlay. The top of the the highest highest overlay overlay determines determines the the total am amount ount of memory memory re required quired.. In Figure Figure 9-3, the highest highest overlay overla y is SUB4. This overlay overlay requires requires substantially substantially less memory memory than would would be required if all the functions and subfunctions were to reside in memory simultaneously.

Sub4 Sub1

Sub2

Function 1

Sub3

Function 2

Function 3

Menu

Fi Figu gure re 99-3. 3. Tree Tree Str Struc uctu ture re of Over Overla lays  ys 

Overlay Command Line Syntax

You specify overlays in the LINK86 command line by enclosing each overlay specification in parentheses. You can specify an overlay in one of the following formats, where ROOT.OBJ is the object file that calls the overlays:

 

9-13

Chapter 9. Using the Linker Utility and the POSTLINK Utility

 

 

A:>LINK86 ROOT (OVERLAY1) A:>LINK86 ROOT (OVERLAY1,PART2,PART3) A:>LINK86 ROOT (OVERLAY1=PART1,PART2,PART3)  The first form produces the files ROOT.286 and OVERLAY1.OVR from ROOT.OBJ and OVERLAY1.OBJ. second form produces the files ROOT.286 and OVERLAY1.OVR from ROOT.OBJ,  The OVERLAY1.OBJ, PART2.OBJ, and PART3.OBJ.  The third form produces the files ROOT.286 and OVERLAY1.OVR from ROOT.OBJ, PART1.OBJ, PART2.OBJ, and PART3.OBJ. On the command line, a left parenthesis indicates the start of a new overlay specification and the end of the previous previous overlay specificati specification. on. You can use spaces to improv improve e readability, readability, and commas can separate separate parts of a single overlay. overlay. However, However, do not use commas to sepa separate rate the over overlay lay speci specification fications s from the root module or from each other. In the following example, the command line is not valid:

A:>LINK86 ROOT(OVERLAY1),MOREROOT The correct command line is:

A:>LINK86 ROOT,MOREROOT(OVERLAY1) To nest overlays, you must specify them in the command line with nested parentheses. In the following example, example, the command line creates creates the overlay system system shown in Figure 9-3:

A:>LINK86 MENU(FUNC1(SUB1)(SUB2))(FUNC2)(FUNC MENU(FUNC1(SUB1)(SUB2))(FUNC2)(FUNC3(SUB3)(SUB4)) 3(SUB3)(SUB4)) When linking files to be overlayed along with files not to be overlayed, the files to be overlayed are specified specif ied last. When you create create the file file ROOT.286 from from the files ROOT.OBJ, ROOT.OBJ, PARTA.OBJ, PARTA.OBJ, and and PARTB.OBJ, to link OVER1.OBJ and OVER2.OBJ as overlays, enter the following command line:

A:>LINK86 ROOT,PARTA,PARTB(OVER1, OVER2)

9-14

4690 Store System: Programming Guide

 

 

The POSTLINK Utility The POSTLINK Utility is a postprocessor program that converts a LINK86 load module into a module that can be loaded faster faster and use memory memory more efficie efficiently ntly in a multitasking multitasking enviro environment. nment. Using POSTLINK POSTLINK is mandatory for all load modules that have been linked with the CODESHARED option. When POSTLINK POSTLINK is invoked, invoked, a temporary file called called FILENAME.PST FILENAME.PST is created. created. When POSTLINK POSTLINK has completed converting the LINK86 load module into a new load module, the temporary file is erased. Notes: 1. The POSTLINK POSTLINK Utility must not be used on overlay overlay files or the root root module of an overla overlay y file. | |

2. A Postlinked load module that contains large unreferenced object modules can cause unpredictable results when loaded on a 4683 point-of-sale terminal.

Invoking the POSTLINK Utility You invoke the POSTLINK Utility with the following command line format:

POSTLINK  filespec filespec   is is a file specification of a load module consisting of an optional path specification and a filename with an extension. The output file has the same filespec as the input file.

A:>POSTLINK C:\LOADMODS\TEST.286

Use of ERRORLEVEL Test When running running the POSTLINK POSTLINK Utility from a batch file, file, the POSTLINK operation operation can be teste tested d for error errors. s. If POSTLINK POSTLIN K is successful, successful, an ERRORLEVEL value value of zero is retur returned. ned. To test for an error, error, use the batch file statement IF ERRORLEVEL 1... The following is an example within a batch file:

POSTLINK TEST.286 IF ERROR ERRORLEV LEVEL EL 1 ECHO ECHO We have have a probl problem em >> RESU RESULTS LTS In the above example, if the POSTLINK is unsuccessful the message “We have a problem” is written to the file RESULTS.

 

9-15

Chapter 9. Using the Linker Utility and the POSTLINK Utility

 

 

9-16

4690 Store System: Programming Guide

 

 

Chapte Cha pterr 10. 10. Using Using the the Prin Printt Spool Spooler er Util Utility ity Obtaining Job Status after a TCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10-1 Issuing a Command to the Print Spooler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10-2 Using Special Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10-3 Error Return Codes for the Print Spooler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10-5 The IBM 4690 Operating System has a Print Spooler Facility that allows you to send your files to one of eight queues queues for printing printing on one of eight printers. printers. This spoo spooling ling facility ca can n be shared by conc concurren urrently tly executing applications. System configura configuration tion allows a maximum maximum of eight printer printers s to be defined. Printers Printers are assigned assigned number numbers s (PRN1: through through PRN8:) at configurat configuration ion time. An application application program program uses this numbe numberr to gain access to a particular particular printer. printer. An application application can gain access access to the printer printer assigne assigned d to the console the appli application cation is running on by using the printer name PRN:. One of the printers printers (PRN1: through through PRN8:) can also also be defined as the sys system tem printer printer.. Any applic application ation can access the system printer using PRN0:. Note: By using the application service ADXSERVE, applications can determine the printer assigned to the console it is running on. Your application application must must open the printer in UNLOCKED UNLOCKED mode. This mode allows allows multiple applicatio applications ns to use the printer. printer. The printer printer must must be closed before printin printing g can be be scheduled. scheduled. You can can use e either ither CLOSE CLOSE or TCLOSE. CLOSE releases releases the application application fro from m all control of the file; TCLO TCLOSE SE allows limited limited control. If your application application uses TCLOSE, TCLOSE, the application application can receive receive job or printer printer status info informatio rmation. n. The TCLOSE is performed performed when the applicati application on complete completes s sending data data to the print spooler spooler.. The file is then scheduled schedu led for print. The print print spooler spooler al allows lows only only rea reading ding of a job’s status. If the a applicat pplication ion dec decides ides some action needs to be taken, it can issue special commands to perform the action on a print job or queue. See “Using “Using Special Special Commands Commands”” on page page 10-3 for for more more information information o on n these specia speciall comman commands. ds. The job status is obtained obtained by the application application performing performing a read after after a TCLOSE. The spoole spoolerr return returns s job and queue sta tus asofdetailed in the next next section. Specia are issued by perfo performing rming a WRITE FORM with status a string characters representing the Special desiredl commands command. are

Obtaining Job Status after a TCLOSE To obtain a job’s status, your application must perform a read with a buffer capable of holding at least 16 characters. chara cters. The spooler spooler places places the job’s job’s status status in the b buffer. uffer. The first seven characters in the buffer correspond to specific events. If any of these seven characters is occupied by a space, that particular event did not occur since the last read was was performed performed.. An even eventt that has has occ occurred urred since the last last read is marked marked by a an n aste asterisk. risk. The

characters indicate the following events:    Ch Char arac acter ter 0 Job completed. completed. The job has been entirely entirely despooled despooled to the printer printer and remov removed ed from the syste system. m.    Ch Char arac acter ter 1 Job cancele canceled. d. The job job was removed removed from from the system before it cou could ld be printe printed. d. The us user er either either canceled that particular job or an authorized user purged an entire print queue.

© Copyright

10-1

IBM Corp. 1994, 1996

 

 

 Ch Char arac acte terr 2 Printer held. held. A hold command has has been issued issued,, and no jobs are currently currently being despooled despooled fro from m that particular partic ular queue. queue. When an activate activate command is issued, issued, the job curr currently ently at the top of the queue will start over.    Ch Char arac acte terr 3 Printer error. error. The printer printer has has dete detected cted an error in printing. printing. This do does es not include error errors s such as out-of-paper, powered-OFF, and so on.    Ch Char arac acte terr 4 Out-of-Paper.. The prin Out-of-Paper printer ter has run out out of paper an and d is currently currently waitin waiting. g.    Ch Char arac acte terr 5 Printer timeout. timeout. The printer printer has taken taken too long to give give the “go ahead” ahead” signal. signal.    Ch Char arac acte terr 6 Printer powered-OFF powered-OFF.. The printer printer lost lost power. power. This ev event ent is seriou serious s because because it in involves volves a loss of data data.. The last nine characters are used as follows:    Ch Char arac acte terr 7 Indicates the printer Indicates printer the job was queued queued for. for. This v value alue is a number number 1 through through 8. 8. If the job job is being being held (not the queue), this character is an asterisk.  Characters 8 through 10 Indicate Indicat e the job’s current current position for printing. printing. ‘000’ indic indicates ates the job is currently currently being despoole despooled d to the printer.  Characters 11 through 13 Indicate the job’s current job ID.  Characters 14 and 15 Are carriage return and line feed characters, which indicate the end of the record. The only error error that is returned returned from a read is an implementation implementation error. error. (This type of err error or is defined in “Error “Err or Return Return Codes for for the Print Print Spoo Spooler” ler” on page page 10-5.) This error error is returne returned d if a read iis s attempt attempted ed and the job has not been closed using TCLOSE.

Issuing a Command to the Print Spooler Following a TCLOSE, an application can issue a special command that will affect a job or a queue. Special commands are issued by writing all necessary data to perform the action. The format for these special commands is the following (number in parentheses is the number of characters for that variable): command (2), (2), jobid   jobid (3),source  (3),source (1),destination  (1),destination (1),node  (1),node (8), (8),

10-2

4690 Store System: Programming Guide

 

 

where: command   = = PJ = TJ = CJ = HJ = AJ = HQ = AQ = LQ = TQ = RQ = CQ =

Mov Move e prior priority ity job to to top p of queue. queue. Tr Tran ansfe sferr jo job b to ano anoth ther er q que ueue ue.. Ca Canc ncel el the the job job.. Ho Hold ld the the jjob ob.. Ac Acti tiva vate te the the jjob ob.. Ho Hold ld the the q que ueue ue.. Act Activat ivate e the the queue. queue. Loa Load d the que queue ue follow following ing an an IPL IPL.. Tr Tran ansfe sferr a queu queue. e. Resume a queu queue e after previous previous transfer. transfer. Ca Canc ncel el a queu queue. e.

 jobid   = =

The The thre threee-ch char arac acte terr vari variab able le indi indica cate tes s the the job job to be affe affect cted ed (com (comma mand nds s e end ndin ing g w wit ith ha J J). ). Default job is the job corresponding to this OPEN.

source   = =

The The o one ne-c -cha hara ract cter er vari variab able le ind indic icat atin ing g th the e queu queue e to be aff affec ecte ted d ((co comm mman ands ds e end ndin ing g wi with th a Q). Valid Valid values values ar are e 1 to 8. Default Default qu queue eue is the the on one e cor corres respon pondin ding g to thi this s OPEN. OPEN.

destination   = =

The Th e que queue ue rece re ceiv ive e job jobs s (co (comm mman ands ds TJ and and T TQ) Q).. Va Valilid d val value ues sa are re 1 to to 8 8.. Th This is variable hastono default.

node   = =

Eigh Eightt-ch char arac acte terr va varria iabl ble e us used ed for for co comm mman ands ds TJ an and d TQ TQ.. If the the de des stina tinati tion on print rinter er is across the network, this variable supplies the node name.

All parameters parameters are optional optional depending depending on the command an and d whether or not a default default exists. A delimiting comma must replace replace each parameter parameter not entered. entered. For examp example, le, if an applicatio application n wanted to termin terminate ate one of its own jobs, the following command would terminate job 001 corresponding to the I/O session number used:

CJ,001,,,, The following command transfers all current and future files for PRN1: to PRN3:.

TQ,,1,3,, The following command results in job 073 being transferred to the PRN5: printer at node DD (if such a printer exists).

TJ,073,,5,ADXLXDDN This command cancels all jobs currently queued (and not being held) for PRN4:.

CQ,,4,,,

Using Special Commands The following nine special commands are available to applications that have performed a TCLOSE:

 PJ (Move priority job to top of queue) An application application can perform perform this operation operation on a job that is currently currently queued (b (but ut not being held). held). This command moves the job to the position immediately following the current job in whatever queue it is residing. resid ing. If the job is currently currently printing printing or will be the the next to prin print, t, the opera operation tion comp completes letes successfully succe ssfully.. Possible Possible errors retu returned rned from this operation operation includ include e Job Does Not Exist and Queue Full.

 

10-3

Chapter Chapt er 10. Using the Print Spooler Spooler Utility Utility

 

 

PJ,001,1,,, source  job ID

 TJ (Transfer job to another queue) An application can perform this operation on any job that has been scheduled to print, regardless of whether itit is currently currently queued queued or being he held. ld. The command command moves the job job from wher wherever ever it is to the destination destina tion printer printer specified specified and queues it for that printer. printer. Therefore Therefore a job could be moved moved from one queue to another another or activated activated with this command. command. The destination destination prin printer ter might be across across the networ network k as long as a proper node node and printer are are specified. specified. Networ Network k moves are done by wri writing ting the job’s file across acros s the network. Non-network Non-network moves moves are done by simply moving moving the job’s record record from one que queue ue to another. another. Network Network moves, therefore, therefore, take mor more e time to complete than a non-networ non-network k move. TJ,001,1,1,ADXLXCCN node destination source  job ID

 CJ (Cancel a job) This operation may be carried out on any job scheduled to print, regardless of whether it is currently queued or being being held. The job entry will be deleted deleted from the appr appropriat opriate e queue and the job’s file will will be erase erased. d. No recov recovery ery is is pos possib sible. le. CJ,001,1,,, source  job ID

 HJ (Hold a job) Any job which which is currently currently queued queued may be placed placed on hold. If an attempt is made made to place an al already ready held job on hold, a successful successful return return code is received. received. Jobs placed placed on hold will be held indefi indefinitely. nitely. However, Howeve r, a limit of 32 held jobs jobs exists exists.. Any attempt attempt to hold more tha than n this will rec receive eive a queue fu fullll error. HJ,001,1,,, source  job ID

 AJ (Activate a job) This command command can be used used on any held job. job. It will be activ activated ated in the que queue ue from which which it was held. If an alternate queue is desired, then the move command should be used. AJ,001,1,,, source  job ID

 HQ (Hold the queue) To hold all jobs jobs scheduled scheduled to print print,, issue the HQ command. command. This command command places places the queue on h hold old indefinitely.

 AQ (Activate a held queue) This command allows a held print queue to resume printing the jobs. AQ,,1,,, source

 LQ (Load a queue)

10-4

4690 Store System: Programming Guide

 

 

This command command is used only in the special special instance instance where an IPL has occurred. occurred. If the spooler dete detects cts unfinished unfinis hed jobs in a queue after an IPL, IPL, it enters recov recovery ery mode. In this mode, no affec affected ted queues ar are e restarted restar ted until a load queue command command is given given.. However, However, a queue is automati automatically cally restarted restarted afte afterr an IPL if it is sent a new job to queue. LQ,,1,,, source

Note: Only an authorized user with an access of Group 2 - User 1 or higher can perform the following commands (transfer, resume, and cancel queue).

 TQ (Transfer a queue) When a printer needs to be taken offline, it is possible to transfer all of its jobs to an alternate printer. This alternate alternate printer printer must be within the sys system tem or within the network. network. Transf Transfers ers within the sys system tem are checked for situations where, for example, PRN2: is redirected to PRN1: and PRN1: is redirected to PRN2:. Transfers Transfers acro across ss the network are are not checked, checked, and it is the user’s responsibil responsibility ity to prevent a loop. loo p. All tr trans ansfer fers s rem remain ain active active.. TQ,,1,1,ADXLXCCN node destination source

 RQ (Resume a queue) After a printer has been transferred, you can place it back online using this command. To ensure that the WRITE FORM statement goes to the correct print spooler driver, open the device SPRN1: on the controller controller that that the application application is running. running. Otherwise, Otherwise, if your PRN1: is tran transferr sferred ed to another controller your WRITE FORM might receive an implement error (80894009). RQ,,1,,, source

 CQ (Cancel all the jobs in a queue) Use this command command if you need need to cancel cancel all of the jobs scheduled scheduled to pr print int on a particular particular pr printer. inter. All  jobs currently queued for the specif specified ied printer are removed from the t he queue and their corresponding files deleted. deleted. Jobs that that have been held held from this queue queue will not be affected. affected. CQ,,1,,, source

Error Return Codes for the Print Spooler If a write of a special command is attempted before a TCLOSE has been performed, no error is returned. The command is treated like print data and is spooled with all other data. If a proper special command is written to the spooler following a TCLOSE, the following error return codes are possible:

 JOB HELD (80890006)

For a PJ command, command, this means means the job is not in a queue queue and needs needs to be activated activated first first.. For an HJ command, it means that because of a system failure, the held job has no printer associated with it and to be activated, a transfer command needs to be used.    NOJ NOJOB OB (80 (80890 890002 002)) The job ID specified is not currently in use in the system (the job was finished or canceled).    LOOP LOOP (80890 (80890003 003))

 

10-5

Chapter Chapt er 10. Using the Print Spooler Spooler Utility Utility

 

 

The requested redirection would result in a loop because of previous transfers.    QUEUEFUL QUEUEFULL L (80890004) (80890004) The requested action could not be completed because of a full queue.    AUTHORIZ AUTHORIZE E (80890005) (80890005) The requested action is not possible because the requestor is not operating under a group-user that allows such actions.    IMPLEMEN IMPLEMENT T (80894009) (80894009) A command is either missing a required parameter, contains a parameter that is not valid, or was issued by an unauthorized user. In addition, any errors that might result from trying to open a printer can also be returned (when performing a network move or a network redirection.) When an error error occurs, occurs, the print spooler spooler handles each each of the printer errors errors in the same way. way. If any other action is desired, you must initiate it. When the spooler spooler detects detects an error, it sets up a timer lasting lasting 30 seconds. seconds. Upon comple completion tion of the timer, the spooler spooler resume resumes s where it left off and continues continues trying to send data data to the printer. For the timeou timeoutt error,, the print drivers error drivers handle the time. Theref Therefore, ore, the spooler spooler does not start start a timer; it continues try trying ing to send data. The type of reaction reaction to these errors errors should depend depend on how serious serious a situation is con consider sidered ed to be. While timeout and paper out do not cause the loss of data and might not be a serious error, a printer error can cause the loss of data, which can be serious. If an application detects these errors, a reasonable response would be to print a message for you indicating indica ting something something is wrong. If the error involves involves certain certain data loss, it would ev even en be reason reasonable able to issue a command to hold the queue. queue. A hold causes the the current job to be restarted restarted from the beginning beginning whe when n the queue is activated thus ensuring it is printed in its entirety. However, if the printer is connected through serial interface, many (possibly all, depending on the interface and communication communication scheme) scheme) of the errors are detectable detectable only as timeout errors. errors. Theref Therefore, ore, there would be no way to distinguish between the errors. Note: If the same application is to perform both reads and writes of a special command after TCLOSE, the reads and writes must be performed under different I/O session numbers.

10-6

4690 Store System: Programming Guide

 

 

Chapte Cha pterr 11. Using Using the the Disk Disk Surfac Surface e Analys Analysis is Utili Utility ty Introduction to the Disk Surface Analysis Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  11-1 IPL Command Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  11-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example of a Command File Disk Surface Analysis Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Descriptions for ADXCSW0L . . . . . . . . . . . . . . . . . . . . . . . . . Command Formats for ADXCSW0L . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Disk Surface Analysis Utility to Recover Data . . . . . . . . . . . . . . . . Using the Time Frame Indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Case Examples of Disk Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Non-LAN (MCF Network), Defect in .286 File . . . . . . . . . . . . . . . . . . . . . LAN (MCF Network), Defect in .286 File on Master Controller . . . . . . . . . . . LAN (MCF Network), Defect in .286 File on Alternate Master Controller . . . . . Non-LAN (MCF Network), Defect in Unallocated Space . . . . . . . . . . . . . . . LAN (MCF Network), Defect in Unallocated Space on Master Controller . . . . . LAN (MCF Network), Defect in Unallocated Space on Alternate Master Controller Non-LAN (MCF Network), Defect in Item Record File . . . . . . . . . . . . . . . . . LAN (MCF Network), Defect in Item Record File on Master Controller LAN (MCF Network), Defect in Item Record File on Alternate Master . . Non-LAN (MCF Network), Defect Near End of TLOG . . . . . . . . . . . LAN (MCF Network), Defect Near End of TLOG on File Server . . . . . LAN (MCF Network), Defect Near End of TLOG on Alternate File Server

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 11-3  11-3  11-4  11-4  11-7  11-8  11-8  11-9  11-9  11-10  11-11  11-11  11-12  11-12

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

 11-13  11-13 . . . . . . . . . . . . . .  11-14 . . . . . . . . . . . . . .  11-15 . . . . . . . . . . . . . .  11-15

Introduction to the Disk Surface Analysis Utility The Disk Surface Analysis Utility is designed to minimize the disruption to the store while recovering from disk surface surface failures. failures. Previously, Previously, the proce procedure dure used for recovering recovering from fixed fixed disk surface failur failure e involved manually manuall y formatting formatting or replacing replacing the fixed disk. The 4690 Oper Operating ating Syst System em and other data wou would ld have to be reloaded on the new fixed disk. Using the Disk Surface Analysis Utility allows you to recover from surface failures by replacing only the data affected affected by the surface surface failure. failure. You d do o not need to rep replace lace or format format the fixed disk. If hos hostt communications are available, an operator can perform the disk surface analysis remotely at the host site. The IPL Command Processor provides the capability to execute a sequence of commands during the store controller controller IPL. IPL. The IPL Command Processo Processorr is necessar necessary y to start the Disk Surfa Surface ce Analysis Analysis Utility from the host.

IPL Command Processor The IPL Command Process Processor or executes executes commands commands at three separate separate times in the IPL sequen sequence. ce. The

commands command s are located in the command command file ADXILI0F.DAT, ADXILI0F.DAT, in the subdirecto subdirectory ry ADX_SDT ADX_SDT1. 1. You must create the command command file. Each comma command nd must have a time frame indicator indicator to spec specify ify when the proc processor essor should invoke invtimes oke the command. comman d. This is necessary necessary because because certa certain in commands ca can n be performe performed d only at specified during the IPL sequence.

© Copyright

11-1

IBM Corp. 1994, 1996

 

 

Table Tab le 11 11-1. -1. Using Using Time Time Fra Frame me Ind Indica icator tors  s  Time Frame Indicator

  Description

1

Commands tth hat tth he IP IPL Co Command Pr Processor p prrocesses e ea arly in in th the IP IPL se sequence o oc ccur b be efore th the creation of the operat creation operator or console facil facility ity (OCF) error logging logging proces process. s. Comm Commands ands execute executed d at this point can gain exclusiv exclusive e access to the disk. LAN (MCF Netw Network) ork) and error log logging ging (ADXE (ADXERROR) RROR) services are not available.

2

Commands that the IPL Command Processor pr processes in the middle of th the IPL sequence occur after the installation installation of the LAN drivers and before the install installation ation of Data Distribution. Distribution. Primi Primitive tive LAN services are available, but Data Distribution is not active to prevent operations on image files. File updates are not d distributed. istributed. Image versions of distributed files can be updated, renamed, and erased.. The op erased operatin erating g system does not not resolve resolve discr discrepanci epancies es auto automatica matically. lly. Prime versio versions ns of distributed files can be updated, renamed, and erased, although these changes are not performed on the corresponding image files. Disk repair procedures require changes to the image file, but the changes change s can cause damage damage if not used carefully. carefully. The user is respo responsible nsible for the res results ults of all file updates update s made during time time frame 2. Only files files that are defective and ha have ve been repair repaired ed by the Disk Surface Surface Analysis Uti Utility lity shoul should d be modified modified during time fra frame me 2. Error logg logging ing servic services es (ADXERROR) (ADXERR OR) are not availabl available e during time time frame 2.

3

Commands tth hat tth he IIP PL Co Command Pr Processor p prrocesses lla ate iin n th the IP IPL s se equence o oc ccur af after m mo ost drivers and services have been initi drivers initialized alized.. Howeve However, r, ADXSERVE, ADXST ADXSTART, ART, and ADXERRO ADXERROR R are not available. At each of the three time frames, the IPL Command Processor executes the commands for that phase in the order that that they appear in the comm command and file. The only contr control ol structur structure e provide provided d by the IPL Command Command Processor Processor is the Exit On Error Error optio option n (-x). If a command th that at has been pre prefaced faced by the Exit on Error option ends in an error, the IPL Command Processor executes no other commands comma nds for the remainde remainderr of the IPL sequence. sequence. An error is a nonnon-zero zero retu return rn code. Each command command appears appears on the scree screen n as it is being exe executed. cuted. Output on the d display isplay fo forr each command is redirected command redirected to a temporary RAM dis disk k work file. This allo allows ws the comman command d to have exclusive exclus ive acces access s to the disk. The work file file is copied to the ou output tput file (AD (ADXNS XNSxx F.DAT) F.DAT) in subdir sub direct ectory ory ADX ADX_SD _SDT1. T1. The xx  represents   represents the node node ID. If the outp output ut file al already ready ex exists, ists, the w work ork file is appended appended to the existing outp output ut file. Each command command name and ret return urn code is saved and logged when the OCF logging function becomes active. After the last command in the command file has been processed, the local output file is appended to ADXNSxx F.DAT F.DAT in subdirectory ADX_SDT1 ADX_SDT 1 on the Acting Master Con Controlle troller. r. The local ou output tput file is delet deleted ed when the Master sto store re controller receives a copy of the output file.

The IPL Command Processor assumes that each command in the command file is the name of a .286 file and executes executes it directly. directly. Therefore, Therefore, you cannot cannot specify shell shell commands, commands, such as ERASE, directly directly in the command comman d file. To execute execute shell commands commands from the command command file, you must specify specify command. command.286 286 with the command command specified specified as an argument. The -c option must must be present betw between een “comma “command” nd” and the argument. For example:

-3 command -c erase junk.dat The above command command erases erases the file JUNK.DAT. JUNK.DAT. The return return code for an internal internal command is not logged logged because the shell actually because actually executes executes it. The retur return n code that is logged represen represents ts the return co code de from the

execution execu tion of command.28 command.286. 6. The follo following wing is a list list of shell shell commands: commands: ASSIGN DEFINE ERASE DVRLINK DVRLOAD

DVRUNIT DVRUNLK MKDIR RMDIR SECURITY

For more information on these commands, refer to the 4690 Store System: User’s Guide .

11-2

4690 Store System: Programming Guide

 

 

To allow Data Distribution to update the command file in place on the disk, the attributes must be a compound, compou nd, Distribute Distribute Per Update. Update. Each comm command and in the command command file may be prefaced prefaced by a no node de identifier identifi er which allows allows each store controlle controllerr on a LAN (MCF Network) to be customized. customized. Each command command must be on a separate line and ended by ASCII carriage return and line feed characters. There are three three options that that may precede the command. command. Each optio option n should begin with with the switch charac cha racter ter (-). (-). The opti options ons a are: re: 1. The The E Exit xit On Erro Errorr opt option ion:: -x 2. A time time fram frame e iindic ndicato ator: r: -1, -2, or -3. The default default ind indica icator tor is --3. 3. 3. A node node indica indicator tor:: -nXX. -nXX. XX is the two-cha two-charac racter ter nod node e ID. ID. The default default is the local local nod node e IID. D. Note: Each command command must be entered entered on on one e line. The commands commands must no nott be split betwe between en lines.

Example of a Command File In the example that follows, follows, the first four four commands are are executed on controlle controllerr DD only. USERAP1 an and d USERAP2 are executed on all store controllers.

-nDD -1 chkdsk c: -nDD -1 adxcsw0l c: -f    

-nD -nDD renam c:\ adx_sp _spgm\ gm\adx adxrt1 rt1sl. sl.286 286 c:\adx c:\ adx_sd _sdt1\ t1\adx adxrt1 rt1sl. sl.bad bad -nDD -nDDD -2 -2 rename copy copy e c:\adx c:\a c:\adx dx_s _sdt dt1\ 1\ad adxx xxxx xxx1 x1.2 .286 86 c:\a c: \adx dx_s _spg pgm\ m\ad adxr xrt1 t1sl sl.2 .286 86 -3 c:\adx c:\adx_up _upgm\ gm\use userap rap11 -3 c:\adx c:\adx_up _upgm\ gm\use userap rap22

Note: If a command fails to terminate, you can abruptly end the command and the IPL Command Processor by pressing the F1 key F1 key while while the the comma command nd is disp display layed. ed. The IIPL PL comple completes tes.. How Howeve ever, r, wh when en you press the F1 key, IPL Command Process Processor or commands commands are pro processe cessed d during th the e IPL. The F1 key, no other IPL message recorded in the System Log indicates that you ended the command by pressing the F1 key. F1 key.

Disk Surface Analysis Utility The Disk Surface Surface Analysis Analysis Utility performs performs a surface surface analysis on a fixed disk. disk. The utility can als also o relocate files away from from areas containing containing surface surface defects defects on the fixed disk. The defect defective ive surface surface areas are marked in the file allocation allocation table table to prevent futu future re access to thes these e areas. If the defective defective area is allocated allocat ed to a file, some data data is lost. To repla replace ce the damaged damaged file, you must must copy the da data ta from anoth another er source. For each defective surface area, ADXCSW0L reports the file name or subdirectory name that is allocated in the defective defective disk space. Unallocated Unallocated areas areas with surface defects defects are also reported reported.. You can use the following following formats formats to invoke the Disk Surface Surface Analysis Analysis Utility. These form formats ats are explained explain ed in “Command “Command Formats Formats for ADXCSW0L” ADXCSW0L” on pa page ge 11-4.    ADX ADXCSW CSW0L 0L drive: drive:    ADXCSW0L ADXCSW0L drive:\filena drive:\filename.filety me.filetype pe  ADXCSW0L drive: -parameters

ADXCSW0L drive:\filename.filetype parameters Subdirectories Subdirectori es are reported reported as being defective, but are not fixed. Informa Information tion appear appears s that includes the defective cluster number, the subdirectory name, and a brief message indicating that the correction has not been performed. After invoking invoking a Disk Surface Surface Analysis Utility Utility command, command, two sections of information information appear. appear. The first section displays displays the defective defective cluster cluster infor information. mation. The information information can be a sector nu number mber spec specified ified by a user or reported reported by the utility. utility. The surface surface analysis analysis information information includes includes the following following::  

11-3

Chapter Chapt er 11. Using the Disk Surf Surface ace Analysis Analysis Utili Utility ty

 

 

 Defective cluster number  The status of the disk space   – Alloc located   – Un Unal allo loca cate ted d  Cylinder head sector address  Relative sector number  Error code (returned during the read-verify of the sector) Note: When the sector parameter (-R) is specified, the information appears regardless of the error code. See “Parameter Descriptions for ADXCSW0L” on page 11-4 for more information on the sector parameter. The second second part of the report lists lists the file names that are rel relocated ocated.. The followi following ng informa information tion is displayed:

   

New cluster number that contains the recovered data The defective cluster number that was replaced The name of the file The offset and size of the data area that was defective

You can invoke the Disk Surface Analysis Utility without the -F parameter to report the current defects and changes that have been made.

Parameter Descriptions for ADXCSW0L Descriptions of the parameters provided with the ADXCSW0L routine are listed below. -R

Allows you to specify specify a defective defective sector on a fixed disk. disk. It is referre referred d to as the sector para parameter. meter. This parameter must be followed by a decimal or hexadecimal (prefixed by 0X) number, which represents repre sents a relative relative sector number. number. The first sector sector on a fixed disk is the relative relative sector nu number mber 0. ADXCSW0L ADXCSW 0L assumes that that the disk sector that that is specified by the -R par parameter ameter is defective. defective. The clusterr correspondin cluste corresponding g to the specified sec sector tor is marked de defective fective in the file allocation allocation table. table. The data is copied to a new area on the disk when the -F parameter is specified. know if the sector is is defective, defective, invoke the the utility without without the -F par parameter ameter.. All Note: If you do not know information informa tion about about the sec sector tor is printed. printed. The data remains remains in place. place.

-F

Allows you to make repairs. repairs. If you do not specify this parameter parameter,, the information information is listed, but not corrected. corre cted. Unalloc Unallocated ated areas with surface surface defects are marked marked defective defective in the file allocation allocation table. Each cluster that is allocated to a file that contains defective sectors is remapped to another cluster. The former former cluster cluster is marked defectiv defective e in the file alloc allocation ation table. table. The data is rread ead into the new new cluster, cluste r, and the sectors sectors that cannot be read are are replaced replaced with fill data. The defaul defaultt fill character character is 0x2E. Note: The file allocation allocation table and the root root directo directory ry cannot be remapped. remapped. Errors Errors within these areas can be reported, but cannot be corrected.

-C

Allows you to specify specify the fill character character to replace replace the unreadable unreadable secto sectors rs in a file. The -C parame parameter ter can override the default fill character.

Command Formats for ADXCSW0L ADXCSW0L drive : performs performs a surface analysis analysis of of the entire disk disk drive drive.. All surfa surface ce defect defects s that are not flagged flagge d in the FAT are reported, reported, and the information information on the repaired repaired files is displayed. displayed. If the -F parameter parameter was specified, the default character X '2E' is used when the data is recovered from the defective area of the fixed disk.

11-4

4690 Store System: Programming Guide

 

 

Note: If the -F parameter is not specified, a message is displayed on the screen that indicates defects are reported but not corrected. Ex Exam ampl ple e 1: 1: The following following command command scans the the entire C: drive. drive. Surfac Surface e defects a are re listed bu butt not corrected. corre cted. The ou output tput re report port is listed below the the comma command. nd.

C>ADXCSW0L SurfaceC:defects are reported but not fixed. Attempting to recover C:      

**************************** **** Surface Defects **** ****************************

           

CClluster Number: Status: St C ylinder: Cy Head: He Sector: Se Relative Sector Number: E rror Co Er Code:

     

*************************** ****** Files Repaired **** ***************************

 

CClluster Number: Repl Replac aces es Clus Cluste terr Numb Number er:: File Name: Fi Lost Data Offset: 3500 35

   

0032 Allocated 4 1 8 16c 86210004

0033 0032 0032 C:\TEST1.DAT Lost Data Size: 0200

ADXCSW0L drive:\filename.filetype  performs   performs a surface analysis on the disk space occupied by the specified specifi ed file file.. If an error is located, located, the the def defect ect is repor reported. ted. The fill fill cha character racter default defaults s to X'2E'. Note: The correction is made if the -F parameter is specified. Ex Exam ampl ple e 2: 2: The following following command command recovers recovers the file TEST2.DA TEST2.DAT T on the D: drive. drive. Surface Surface defects ar are e reported repor ted but not corrected corrected.. The output output report is lilisted sted below below the command command..

C>ADXCSW0L D:\TEST2.DAT Surface defects are reported but not fixed. Attempting to recover D:\TEST2.DAT      

**************************** **** Surface Defects **** ****************************

 

Cluster Number: Cl

0946

   

SSttatus: Cylinder: Cy

Allocated 071

  

HHe Seeacdt:or: Se Relative Sector Number: E rror Co Er Code:

0063 25BD 86210004

 

 

11-5

Chapter Chapt er 11. Using the Disk Surf Surface ace Analysis Analysis Utili Utility ty

 

 

         

*************************** * *** Files Repaired **** ** *************************** CClluster Number: Repl Replac aces es Clus Cluste terr Numb Number er:: File Na Fi N ame: Lost Data Offset: 3 500 35

0033 0946 0946 C:\TEST2.DAT Lost Data Size 0200

ADXCSW0L drive: -parameters  allows   allows any any combination combination o off the para parameters meters.. Howeve However, r, a sect sector or numbe numberr cannot be specified when a file name is specified. Ex Exam ampl ple e 3: 3: In this example, the command uses the sector parameter, the fill character parameter, and the -F -F parameter. parameter. The specified specified sector parameter parameter is assume assumed d to be be defective. defective. All of the data data on the defective defect ive sector sector is relocated. relocated. The specified specified fill characte characterr is used used in the the reallocated reallocated disk space. space. All changes chang es are written to the disk disk because the -F parameter parameter is issued. issued. The output report report is listed afte afterr the command.

C>ADXCSW0L D: -R0x25D1 -C0x3D -F Attempting to recover D: With specified sector number 25D1.                        

Information on specified bad sector: Cluster Nu N umber: 094B Status: St Allocated Cylinder: Cy 071 Head: He 04 Sector: Se 09 Relative Sector Number: 25D1 Error Co Er Code: 86210004 *************************** ****** Files Repaired **** *************************** Cluster Number: Cl 0950 Replaces Bad Customer: 094B File Na Fi Name: TEST3.DAT Lost Data Offset: Lost Data Sizes 1800 18 200

ADXCSW0L drive:\filespec -parameters  performs   performs a surface analysis on a specified file name to be specified specif ied along with the parameter parameters. s. However, However, only the fill character character and the fix par parameter ameters s are allowed with the file name. name. The sector sector parameter parameter -R is not not allow allowed. ed. A message message app appears ears if the -R is incl included uded in the command. Ex Exam ampl ple e 4: 4: The follow following ing comman command d recove recovers rs the ffile ile TE TEST4 ST4.DAT .DAT on on the D: dr drive ive.. The -F an and d -C parameters param eters allo allow w the surface defect defect areas to be corr corrected ected and filled filled with the fill character character 0x4A. The

output report is listed below the command.

ADXCSW0L D:\TEST4.DAT -COx4A -F Attempting to recover D:\TEST4.DAT

11-6

4690 Store System: Programming Guide

 

 

             

*************************** **** Surface Defects **** ***************************

 

CClluster Number: Status: Cylinder: Cy Head: He Sector: Se Rela Relati tive ve Sect Sector or Numb Number er:: Error Co Code:

     

*************************** * *** Files Repaired **** ** ***************************

 

CClluster Number: Repl Replac aces es Clu Clust ster er Num Numbe ber: r: File Name: Fi Lost Data Offset: 2600 26

   

0947 Allocated 071 03 09 25C0 25C0 86210004

0046 0947 0947 C:\TEST4.DAT Lost Data Sizes 0200

Using the Disk Surface Analysis Utility to Recover Data Use the Disk Surface Analysis Utility to locate surface defects and to mark them defective in the FAT. Data may be moved if necessary necessary.. This process process prevents prevents future access access to the defect defective ive areas on the fixe fixed d disk. If the defectiv defective e area is within within a file, file, some data data is lost. Replace Replace the damaged damaged file by copyin copying g the fil file e from another source. The store controlle controllerr might dump, or a power line disturban disturbance ce might occu occurr during an IPL. The command command file should be organized so that problems are not caused by running the same command multiple times. For more information information on command command files, see “Example “Example of a Command Fil File” e” on page 11-3. To ensure that the command file executes only one time, place an ERASE command at the end of the command file. Perfor Perform m the erase erase at time frame frame 3 to distribute distribute the request. request. If you use RCP to re-IPL, and you configure it to start at each IPL as a background application, the IPL Command Processor command file ADXILI0F.DAT should contain a time frame 3 command to erase the RCP selection selection file ADXCSHCF.DAT. ADXCSHCF.DAT. The ERASE command command prevents prevents a store contr controller oller IPL loop loop.. If a surface defect prevents the IPL of a store controller, or if host communications cannot be established, the Disk Surface Surface Analysis Analysis Utility can be invoked invoked from the supplemental supplemental dis diskettes. kettes. You can use the disk rebuild function to obtain specific replacement files from another store controller on the LAN (MCF Network). Networ k). In a non-LAN environmen environment, t, you must obtain the replacemen replacementt files from a diskette or tap tape. e.

 

11-7

Chapter Chapt er 11. Using the Disk Surf Surface ace Analysis Analysis Utili Utility ty

 

 

The following steps explain how to use the Disk Surface Analysis Utility for disk recovery. Note: You can omit steps 1 through 3—which contain the initial disk analysis command, re-IPL, and report sequence—if you know a particular file is damaged (for example, an error message has been logged on a file). 1. Transfer Transfer the command file containing containing the ADXCSW0L ADXCSW0L command command from the host. The co command mmand requests that the Disk Surface Analysis Utility be started on the store controller’s fixed disk. 2. IPL the store control controller ler manually manually or or by using using the the RCP rre-IPL e-IPL command. command. Refer tto o the IBM 4690 Store  System: Communications Programming Reference  for   for more information. 3. The store control controller ler generates generates the utility’s utility’s output output report, report, and the host retriev retrieves es it. The repo report rt indicates indicates fixed disk areas that are defective. 4. Send a new command file to the store controller controller containing containing the following commands: commands:  Disk Surface Analysis Utility command using the -F parameter.  ERASE or RENAME RENAME command command of files containing containing su surface rface defects. defects. You can us use e the RENAME command to save a copy of the file that contains unreadable data replaced by fill characters. command for each file file with surf surface ace defects defects from any st store ore contr controller oller on the L LAN. AN. If the  COPY command store controller is not on a LAN, the file can be transmitted from the host. 5. IPL the store controller controller and and the repairs are are performed. performed. 6. The store controller generates a second output report at the store controller, and the host retrieves it to verify the changes. 7. Send a default default (empty) (empty) command file file to the store. store. Note: To ensure that a command file can be transmitted to the store after a surface defect appears, you can send a default default command file containing containing zer zeros os or blanks equ equaling aling the maximum maximum number of commands commands that you need. need. Use the HCP LOA LOAD D FILE command command or the RCMS SEND SEND command to overwri overwrite te the existing file with the new command file.

Using the Time Frame Indicators As part of the disk recovery procedure, you must execute some commands within a specified time frame. The time time frame frame default default is -3. -3. For ex exampl ample: e: CHKDSK

-1

ADXCSW0L RENAME

-1 -2

COPY

-2

COMMA CO MMAND ND -c ERASE ERASE -2 RENAME and and COPY are executed executed within within time frame --2, 2, so the operation operation is not di distribu stributed. ted. If a RENAME, COPY, or ERASE in the command file is to be distributed, the command should be preceded by -3. You should should use time frame -1 only for executing executing CHKDSK CHKDSK and the Disk Surface Surface Analysis Analysis Utility. Use time frame -2 only for renaming, erasing, or copying to files that have been repaired by the Disk Surface Analysis Utility.

Case Examples of Disk Recovery This section section describes describes some example scenarios scenarios and disk reco recovery very procedures procedures.. In an actual situation, situation, multiple files can be affected, a situation which would require you to develop a recovery procedure. However, in these examples, only one file is affected by a surface defect.

11-8

4690 Store System: Programming Guide

 

 

Non-LAN (MCF Network), Defect in .286 File Symptom: A user in a non-LAN environment cannot execute the Format Dump Data Utility (ADXCSL0L.286). The following messages were logged:  A W754 B4/S004/E021 with RC=80210004 or RC=8021000D W754 B4/S004/E01 B4/S004/E018 8 with the fil file e name name:: ADXCSL0L.286 ADXCSL0L.286  A W754 Action: 1. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-1 adxcsw0l c: 2. Execute Execute the following RCP command command to re-IPL the st store ore controller: controller:

adxcs20l N 13 3. Retrieve Retrieve ADX_SDT1:ADX ADX_SDT1:ADXNSCCF.DA NSCCF.DAT T (assumes (assumes store store controller controller no node de is CC) from from the sto store. re. Verify that the only file with a surface defect is ADXCSL0L.286. 4. Transmit Transmit a new copy of ADXCSL0L ADXCSL0L.286 .286 to subdirector subdirectory y ADX_SMNT. 5. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-x -1 adxcsw0l c: -f command -c erase ADX_SPGM:ADXCSL0L.286 rename ADX_SMNT:ADXCSL0L.286 ADX_SPGM:ADXCSL0L.286 6. Execute Execute the following RCP command command to re-IPL the st store ore controller: controller:

adxcs20l N 13 7. Retrieve Retrieve ADX_SDT1:ADX ADX_SDT1:ADXNSCCF.DA NSCCF.DAT T (assumes (assumes store store controller controller no node de is CC) from from the sto store. re. Verify that recovery was successful. 8. Transmit Transmit a copy of ADX_SDT1:ADXIl ADX_SDT1:ADXIlL0F.DAT L0F.DAT,, which contains no commands commands to the store.   9. Del Delete ete ADX_SDT ADX_SDT1:AD 1:ADXNS XNSCCF. CCF.DAT. DAT. 10. If a different version version of ADXCSL0L.286 was in the ADX_SMNT subdirectory prior to this recovery procedure, re-transmit that version to the store.

LAN (MCF Network), Defect in .286 File on Master Controller Symptom: A user in a two-controller LAN store environment cannot execute the Format Dump Data Utility (ADXCSL0L.2 (ADXCSL0L.286) 86) on the master store store contr controller. oller. The master is nod node e CC and the alternat alternate e master is node DD. The following return codes are logged:

 A W754 B4/S004/E021 with RC=80210004 or RC=8021000D  A W754 B4/S004/E018 with file name: ADXCSL0L.286 Action: 1. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-1 -nCC adxcsw0l c:  

11-9

Chapter Chapt er 11. Using the Disk Surf Surface ace Analysis Analysis Utili Utility ty

 

 

2. Execute the following following RCP command on the master stor store e controller controller to re-IPL:

adxcs20l N 13 3. Retrieve Retrieve ADX_SDT1:ADXN ADX_SDT1:ADXNSCCF.DAT SCCF.DAT from the store. store. Verify that that the on only ly file wit with h a surface surface defec defectt is ADXCSL0L.286. 4. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-ncc -x -1 adxcsw0l c: -f -ncc -ncc -2 copy copy adxl adxlxd xddn dn:: ::ad adx_ x_sp spgm gm:a :adx dxcs csL0 L0L. L.28 2866

gadx gadx_s _spp m:ad m:adxc xcsL sL0L 0L.2 .286 86

5. Execute the following following RCP command on the master stor store e controller controller to re-IPL.

adxcs20l N 13 6. Retrieve Retrieve ADX_SDT1:ADX ADX_SDT1:ADXNSCCF.DA NSCCF.DAT T from the store. store. Verify that re recovery covery was su successf ccessful. ul. 7. Transmit Transmit a copy of ADX_SDT1:ADXIL ADX_SDT1:ADXILI0F.DAT I0F.DAT that contains contains no commands to the store.   8. Dele Delete te ADX_SDT ADX_SDT1:A 1:ADXNS DXNSCFF CFF.DAT .DAT..

LAN (MCF Network), Defect in .286 File on Alternate Master Controller Symptom: A user in a two-controller LAN environment cannot execute the Format Dump Data Utility (ADXCSL0L.28 (ADXCS L0L.286) 6) on the alternate alternate master. The master is node node CC and the alternate mas master ter is node DD. The following return codes are logged:

 A W754 B4/S004/E021 with RC=80210004 or RC=8021000D  A W754 B4/S004/E018 with file name: ADXCSL0L.286 Action: 1. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-1 -ndd adxcsw0l c: 2. Execute the following following RCP command command to re-IPL the alternate alternate master. master.

dd::adxcs20l N 13 3. Retrieve Retrieve ADX_SDT1:ADXN ADX_SDT1:ADXNSDDF.DAT SDDF.DAT from the store. store. Verify that that the on only ly file wit with h a surface surface defec defectt is ADXCSL0L.286. 4. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-ndd -x -1 adxcsw0l c: -f -ndd -ndd -2 copy copy adxl adxlxc xccn cn:: ::ad adx_ x_sp spgm gm:a :adx dxcs csL0 L0L. L.28 2866

gadx gadx_s _spp m:ad m:adxc xcsL sL0L 0L.2 .286 86

5. Execute the following following RCP command command to re-IPL the alternate alternate master. master.

dd::adxcs20l N 13 6. Retrieve Retrieve ADX_SDT1:ADX ADX_SDT1:ADXNSDDF.DA NSDDF.DAT T from the store. store. Verify that re recovery covery was su successf ccessful. ul. 7. Transmit Transmit a copy of ADX_SDT1:ADXIL ADX_SDT1:ADXILI0F.DAT I0F.DAT that contains contains no commands to the store.   8. Dele Delete te ADX_DST ADX_DST1:A 1:ADXNS DXNSDDF DDF.DAT .DAT..

11-10

4690 Store System: Programming Guide

 

 

Non-LAN (MCF Network), Defect in Unallocated Space Symptom: A user in a non-LAN non-LAN environmen environmentt cannot transmit transmit a file from from the host to the st store. ore. The problem could be caused by an unallocate problem unallocated d area of the disk that contains contains a surface surface defect. Assume that the store controller node is CC. The following return codes are logged:

 W754 B4/S004/E021 with RC=80210004 or RC=8021000D  W754 B4/S004/E018 with the name of the file being transmitted Action: 1. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-1 adxcsw0l c: -f 2. Execute Execute the following RCP command command to re-IPL the st store ore controller: controller:

adxcs20l N 13 3. Retrie Retrieve ve ADX_SDT1 ADX_SDT1:ADX :ADXNSCF NSCFF.DA F.DAT T from the store. store. Ver Verify ify that that recov recovery ery wa was s succ success essful. ful. The error error is associated with an allocated cluster of the transmitted file. 4. Transmit Transmit a copy of ADX_SDT1:ADXIL ADX_SDT1:ADXILI0F.DAT I0F.DAT that contains contains no commands to the store.   5. Del Delete ete ADX_SDT ADX_SDT1:AD 1:ADXNS XNSCCF. CCF.DAT. DAT. 6. Retransmit Retransmit the o original riginal file file to the store. store.

LAN (MCF Network), Defect in Unallocated Space on Master Controller Symptom: A user in a two-controller LAN environment was unable to transmit a file from the host to the store. The symptom symptom may may be caused caused b by y an allocated allocated area of of the disk disk that contain contains s a su surface rface d defect. efect. The master is node CC and the alternate master is node DD. The following return codes are received:

 A W754 B4/S004/E021 with RC=80210004 or RC=8021000D  A W754 B4/S004/E018 with the name of the file being transmitted Action: 1. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-1 -ncc adxcsw0l c: -f 2. Execute Execute the following RCP command command on the master to rere-IPL IPL it:

adxcs20l N 13 3. Retrie Retrieve ve ADX_SD ADX_SDT1:A T1:ADXNS DXNSCCF CCF.DAT .DAT from from the store store.. Ver Verify ify that that the re recov covery ery wa was s succ success essful. ful. The

error is associated with an allocated cluster of the transmitted file. 4. Transmit Transmit a copy of ADX_SDT1:ADXIL ADX_SDT1:ADXILI0F.DAT I0F.DAT that contains contains no commands to the store.   5. Del Delete ete ADX_SDT ADX_SDT1:AD 1:ADXNS XNSCCF. CCF.DAT. DAT. 6. Retransmit Retransmit the o original riginal file file to the store. store.

 

11-11

Chapter Chapt er 11. Using the Disk Surf Surface ace Analysis Analysis Utilit Utility y

 

 

LAN (MCF Network), Defect in Unallocated Space on Alternate Master Controller two-controllerr LAN store environ environment ment cannot cannot transmi transmitt a file from the hos hostt to the store. A Symptom: A two-controlle Distribution Exception Distribution Exception Log entry entry was logged for the file bein being g transmit transmitted ted at node DD. The master is no node de CC and the alternate master is node DD. Message W754 B4/S004/E021 with RC=80210004 or RC=8021000D was logged at node DD. Action: 1. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-1 -ndd adxcsw0l c: -f 2. Execute the following following RCP command command to re-IPL the alternate alternate master: master:

dd::adxcs20l N 13 3. Retriev Retrieve e ADX_ ADX_SDT SDT1:AD 1:ADXNS XNSDDF. DDF.DAT DAT from from the store store.. Ver Verify ify that that the rec recove overy ry was s succ uccess essful. ful. The file that was transmitted from the host is reconciled during the IPL of the alternate master. 4. Transmit Transmit a copy of ADX_SDT1:ADXIL ADX_SDT1:ADXILI0F.DAT I0F.DAT that contains contains no commands to the store.   5. Dele Delete te ADX_SDT ADX_SDT1:A 1:ADXNS DXNSDDF DDF.DAT .DAT..

Non-LAN (MCF Network), Defect in Item Record File non-LAN environm environment. ent. The item record record file on th the e D: drive con contains tains a defe defect. ct. Symptom: The user is in a non-LAN The following errors were logged:

 W754 B4/S004/E021 with RC=80210004 or RC=8021000D  W754 B4/S004/E018 with file name EALITEMR.DAT Action: 1. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-1 adxcsw0l d: 2. Execute the following following RCP command command to re-IPL the store store controller: controller:

adxcs20l N 13 3. Retrieve Retrieve ADX_SDT1:ADXN ADX_SDT1:ADXNSCCF.DAT SCCF.DAT (assumes (assumes store store contr controller oller node node is CC) ffrom rom the st store. ore. Verify that the only file with a surface defect is EALITEMR.DAT. 4. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-1 adxcsw0l d: -f -c0

Note: A fill character of binary 0 is recommended for use when recovering a keyed file. 5. Execute the following following RCP command command to re-IPL the store store controller: controller:

adxcs20l N 13 6. Retrieve Retrieve ADX_SDT1:ADXN ADX_SDT1:ADXNSCCF.DAT SCCF.DAT (assumes (assumes store store contr controller oller node node is CC) ffrom rom the st store. ore. Verify that recovery was successful. 7. Transmit Transmit a copy of ADX_SDT1:ADXIL ADX_SDT1:ADXILI0F.DAT I0F.DAT that contains contains no commands to the store.

11-12

4690 Store System: Programming Guide

 

 

8. Delete Delete ADX_SDT ADX_SDT1:AD 1:ADXNS XNSCCF. CCF.DAT. DAT. 9. Use existing existing procedur procedures es to reload reload the ite item m recor record d file. Until this is done, a attempts ttempts tto o acces access s items tha thatt were present in the damaged section of the item record file fails.

LAN (MCF Network), Defect in Item Record File on Master Controller Symptom: In a two-controller LAN environment, the master is node CC and the alternate master is node DD. The ite item m record record file is on the D: D: drive drive,, which does not not contain contain eno enough ugh fr free ee spac space e on the D: drive for a second copy of it. The following return codes were logged against the item record file on the master:

 W754 B4/S004/E021 with RC=80210004 or RC=8021000D  W754 B4/S004/E018 with file name: EALITEMR.DAT Action: 1. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-ncc -1 adxcsw0l d: 2. Execute Execute the following RCP command command on the master to rere-IPL IPL it:

adxcs20l N 13 3. Retrieve Retrieve ADX_SDT1:AD ADX_SDT1:ADXNSCCF.D XNSCCF.DAT AT from the store. store. Verify that the only file file with a surface surface defe defect ct is EALITEMR.DAT. 4. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT.

-1 -ncc -x adxcsw0l d: -f -c0 -2 -ncc command -c erase d:adx_idt1\ealitemr.dat -2 -ncc -ncc copy copy adxl adxlxd xddn dn:: ::d: d:\a \adx dx_i _idt dt1\ 1\ea eali lite temr mr.d .dat at

&d:\ &d:\ad adxx us.id us.idt1 t1\e \eal alit item emr. r.da datt

5. Execute Execute the following RCP command command on the master to rere-IPL IPL it:

adxcs20l N 13 6. Retrieve Retrieve ADX_SDT1:AD ADX_SDT1:ADXNSCCF.D XNSCCF.DAT AT from the store. store. Verify that re recover covery y was s succes uccessful. sful. 7. Transmit Transmit a copy of ADX_SDT1:ADXIL ADX_SDT1:ADXILI0F.DAT I0F.DAT that contains contains no commands to the store.   8. Del Delete ete ADX_SDT ADX_SDT1:AD 1:ADXNS XNSCCF. CCF.DAT. DAT.

LAN (MCF Network), Defect in Item Record File on Alternate Master Symptom: On a two-controller LAN store environment, W754 errors are periodically logged against the item record record file on the alternate alternate master. master. The master master is node CC and the the alterna alternate te master is n node ode DD. The item record file is on the D: drive, and there is not sufficient free space on the D: drive for a second copy of it.

These return codes were logged:

 W754 B4/S004/E021 with RC=80210004 or RC=8021000D  W754 B4/S004/E018 with file name: EALITEMR.DAT Action: 1. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT  

11-13

Chapter Chapt er 11. Using the Disk Surf Surface ace Analysis Analysis Utilit Utility y

 

 

-ndd -1 adxcsw0l d: 2. Execute the following following RCP command command to re-IPL the alternate alternate master. master.

dd::adxcs20l N 13 3. Retrieve Retrieve ADX_SDT1:ADXN ADX_SDT1:ADXNSDDF.DAT SDDF.DAT from the store. store. Verify that that the on only ly file wit with h a surface surface defec defectt is EALITEMR.DAT. 4. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT.

-1 -ndd -x adxcsw0l d: -f -c0 -2 -ndd command -c erase d:adx_idt1\ealitemr.dat -2 -ndd -ndd copy copy adxl adxlxc xccn cn:: ::d: d:\a \adx dx_i _idt dt1\ 1\ea eali lite temr mr.d .dat at

&d:\ &d:\ad adxx us.id us.idt1 t1\e \eal alit item emr. r.da datt

5. Execute the following following RCP command command to re-IPL the alternate alternate master: master:

dd::adxcs20l N 13 6. Retrieve Retrieve ADx_SDT1:ADX ADx_SDT1:ADXNSDDF.D NSDDF.DAT AT from the store. store. Verify that the recovery recovery wa was s succ successful essful.. 7. Transmit Transmit a copy of ADX_SDT1:ADXIL ADX_SDT1:ADXILI0F.DAT I0F.DAT that contains contains no commands to the store.   8. Dele Delete te ADX_SDT ADX_SDT1:A 1:ADXNS DXNSDDF DDF.DAT .DAT..

Non-LAN (MCF Network), Defect Near End of TLOG example is a variation variation of a previous previous exa example. mple. In a non-LAN non-LAN store env environme ironment, nt, Symptom: This example unallocated unallo cated space space is causing errors. errors. The difference difference is that this prob problem lem occur occurs s as the terminals atte attempt mpt to write to the end of the transaction log. The following errors were logged as the terminals attempt to write to the transaction log:

 W754 B4/S004/E021 with RC=80210004 or RC=8021000D  W754 B4/S004/E018 with file name: EALTRANS.DAT Action: 1. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-1 adxcsw0l c: -f 2. Execute the following following RCP command command to re-IPL the store store controller: controller:

adxcs20l N 13 3. Retrieve Retrieve ADX_SDT1:ADX ADX_SDT1:ADXNSCCF.DA NSCCF.DAT T from the store. store. Verify that re recovery covery was su successf ccessful. ul. 4. Transmit Transmit a copy of ADX_SDT1:ADXIL ADX_SDT1:ADXILI0F.DAT I0F.DAT that contains contains no commands to the store.   5. Dele Delete te ADX_SDT ADX_SDT1:A 1:ADXNS DXNSCCF CCF.DAT .DAT..

11-14

4690 Store System: Programming Guide

 

 

LAN (MCF Network), Defect Near End of TLOG on File Server Symptom: A store in a two-controller LAN environment cannot write data to the end of the transaction log because becaus e of a defect in unallocated unallocated space. The file server/mas server/master ter is CC and the alterna alternate te file server/alternate master is DD. The following errors are logged as the terminals attempt to write to the transaction log:

 W754 B4/S004/E021 with RC=80210004 or RC=8021000D  W754 B4/S004/E018 with file name: EALTRANS.DAT Action: 1. Create the following following command command file at the host site and transmit transmit it to the store as ADX_SDT1:ADXILI0F.DAT

-1 -ncc adxcsw0l c: -f 2. Execute Execute the following RCP command command to re-IPL the fil file e server server::

adxcs20l N 13 3. Retrieve Retrieve ADX_SDT1:AD ADX_SDT1:ADXNSCCF.D XNSCCF.DAT AT from the store. store. Verify that re recover covery y was s succes uccessful. sful. 4. Transmit Transmit a copy of ADX_SDT1:ADXIL ADX_SDT1:ADXILI0F.DAT I0F.DAT that contains contains no commands to the store.   5. Del Delete ete ADX_SDT ADX_SDT1:AD 1:ADXNS XNSCCF. CCF.DAT. DAT.

LAN (MCF Network), Defect Near End of TLOG on Alternate File Server Symptom: In a two-controller LAN environment, the file server node is CC and the alternate file server is DD. The Distri Distribution bution Exception Exception Log for the file se server rver contains contains an entry for the transact transaction ion log. The following errors were logged by the alternate file server:

 W754 B4/S004/E021 with RC=80210004 or RC=8021000D  W754 B4/S004/E018 with file name: EALTRANS.DAT Action: 1. Create the following following command command file at the host site and transmit transmit it to the store as ADX_DST1:ADXILI0F.DAT

-1 -ndd adxcsw0l c: -f 2. Execute Execute the following RCP command command to re-IPL the al alternate ternate file server: server:

dd::adxcs20l N 13 3. Retrieve Retrieve ADX_SDT1:AD ADX_SDT1:ADXNSDDF.D XNSDDF.DAT AT from the store. store. Verify that the recovery recovery was succes successful. sful. Reconciliation should update the alternate file server with a current copy of the transaction log. 4. Transmit Transmit a copy of ADX_SDT1:ADXIL ADX_SDT1:ADXILI0F.DAT I0F.DAT that contains contains no commands to the store.

  5. Del Delete ete ADX_SDT ADX_SDT1:AD 1:ADXNS XNSDDF. DDF.DAT. DAT.

 

11-15

Chapter Chapt er 11. Using the Disk Surf Surface ace Analysis Analysis Utilit Utility y

 

 

11-16

4690 Store System: Programming Guide

 

 

Chapte Cha pterr 12. Using Using the Loop Loop Statu Status s Appl Applica icatio tion n Utility Utility The Loop Status Application Utility provides the current status for all configured loop adapters on a 4690 Operating System. The application application initially initially displays displays status for the first first primary or backup backup loop adap adapter ter found. If no primary or backup loop adapter is found, status for the first loop adapter appears in the controller running the Loop Status Application. The application application views each each controller controller as having two loop loop adapters. adapters. If a loop adapter is not phys physically ically present, or is present but not configured, the application reports the adapter’s configuration as “Not Used.” The following information is displayed for each loop adapter:

     

The number of configured loop adapters on the system The controller ID and loop adapter number The terminal number that was last used to select this loop adapter The loop adapter configuration; for example, primary, backup, or not used For primary loops, whether Auto-Resume is configured The loop adapter status; for example, controlling loop, receiving backup, backup allowed, backup prevented, providing backup, or inactive  The date, time, and terminal number for the last beacon received  The last three system messages for this loop adapter Use one of the following formats to invoke the Loop Status Application Utility:   Format: ADXLAS0L

The default interval is 30 seconds.   Format: ADXLAS0L -Rnnn  -Rnnn 

where: nnn   = =

the number number of second seconds s between between automati automatic c refresh refreshes. es. Spe Specif cifying ying a zer zero-s o-seco econds nds int interv erval al disa disable bles s automatic automati c refresh. refresh. The def default ault int interval erval iis s 30 seconds seconds..

© Copyright

12-1

IBM Corp. 1994, 1996

 

 

Format: ADXLAS0L -p  -p 

where: p   = = The numb number er of se secon conds ds be betwee tween n ref refres reshes hes of of the repor report. t. The defau default lt int interv erval al is 30 s seco econds nds.. You can select loop adapters for status display by performing the following steps: 1. 2. 3. 4.

Pr Pres ess s the the PgDn  key to view the next adapter. PgDn key Pr Pres ess s the the PgUp PgUp key  key to view the previous adapter. Enter the controller ID and loop adapter number of the desired adapter. Enter the terminal terminal number number of an active active terminal. terminal.

Loop adapter adapter status is checked checked at regular regular intervals intervals and the status screen screen is automatically automatically upd updated. ated. You can also request the current status at any time by pressing the Refresh key ( F9). F9). HELP information is available at any time by pressing the Help key ( F1). F1). The following is an example of a LOOP STATUS screen:

 

  L O O P

 Co  C ontroller/Loop: CC/1

S T A T U S

Loop 3 of 4

Configured:

 Se  S elect Terminal: 016

Status:

Primary, Auto Resume Controlling Loop

 Last  La st Beac Beacon: on: 09/09 09/09 12:06 12:06 Termin Terminal al 028  ******  *** ****** ****** ****** *** System System Messag Messages es for for this this Store Store Loop Loop Adapte Adapterr ****** ********* ****** ****** ***** 09/09 10:26 CC

2 W772 OPEN LOOP - BEACONING

  09/09 10 10:26 CC CC 2 W7 W761 B4/S008/E040 LO LOOP IS IS OP OPERATIONAL   B5/S008/E039 09/0 09/099 12: 12:06 06 CC 2 W76 W7600 OPE OPENN LOO LOOPP - TER TERMI MINNAL 028 028 IS IS BEA BEACO CONI NING NG   B4/S008/E036  ****  ** **** **** **** **** **** **** **** **** **** **** **** **** **** ** End End of of Mes Messa sage gess (New (Newes est) t) **** ****** **** **** **** **** **** **** ****  To  To sel selec ectt a loop loop::

F1 HELP HELP

 

F2

Pres Presss Page Page Down Down for for next next loop loop -OR-OREnte Enterr Cont Contro roll ller er/L /Loo oopp numb number er -OR-OREnter Select Terminal

F3 QUIT QUIT

F4

F5

F6

F7

F8 F8

F9 F9 Refr Refres eshh

F10 F10

 

12-2

4690 Store System: Programming Guide

 

 

Chapte Cha pterr 13. 13. Using Using the Staged Staged IPL Utility Utility Requirements   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Capabilities   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TCC Network Considerations . Application Applica tions s Only   . . . . . . . . Incompatible Software Levels . Application Applica tion Interfa Interface ce   . . . . . . . . Apply Software Maintenance . RCP Co Comma mmand nd   . . . . . . . . . Error Recovery . . . . . . . . . . Recommen Reco mmended ded Use   . . . . . . . Test Test Mo Mode de   . . . . . . . . . . . Wait Wa it Ti Time me   . . . . . . . . . . . Timeout Time out Value Value   . . . . . . . . Where to Run this Staged IPL IP IPL L Orde Orderr   . . . . . . . . . . . Load Loa d Ter Termina minals ls   . . . . . . . . User Applications that Idea Ideall Syste System m  . . . . Loading Terminal Storage Enable Terminal IPL . Disable Terminal IPL . Messages   . . . . . . . . . ASM History File . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Utility

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

IPL the Controller

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13-1 13-2  13-2 13-2  13-2 13-3  13-3 13-3  13-4 13-5 13-5 13-5 13-5  13-5 13-6 13-6  13-6 13-7  13-7  13-8  13-8 13-8  13-10

Requirements  Requirements This utility is useful only if you enable the Multiple Controller Feature and configure the controllers to allow backup.. By only IPLing one controlle backup controllerr at a time, the terminals automatical automatically ly switch to an active co controlle ntroller. r. On most systems, the order can be chosen so that the terminals end up on their primary controller. Automatic resume may be necessary in some topographies, especially those that have two TCC adapters on different different controll controllers ers that that back each ot other her up up.. See “Recommen “Recommended ded Us Use” e” on p page age 13-5 for for more information.

© Copyright

13-1

IBM Corp. 1994, 1996

 

 

Capabilities This section describes the capabilities of the Staged IPL Utility.

TCC Network Considerations The main benefit of the Staged IPL Utility is that at least one controller is available at all times to run the terminals, termin als, provided provided that store controller controller backup is allowed. allowed. During utility utility execution execution,, the terminals can switch controllers up to four times; each switch can cause an interruption of checkout lasting 6 to 10 seconds.

 Applicati Applic ations ons Only Only The Staged IPL utility can cause a dump IPL code loop if used for activating either the 4690 Operating System or LAN (MCF Network) because there is a brief time when both controllers are up and running different differ ent software software levels of code. For this reason, reason, the Staged IPL utility utility does not permit permit activation of eith either er 4690 Operating System or LAN with the staged IPL.

Incompatible Software Levels The same exposure exposure of incompatible incompatible software levels levels exists for applications. applications. You must test each application application maintenance package on a test system using the Staged IPL Utility with a long wait time to assess the compatibility compat ibility of the software software levels levels.. If there are changes changes in the file formats formats or message formats, formats, you must consider what effect these would have during the brief time that both controllers are up and running different software levels of code. If your test reveals that an incompatibility problem could result from running the LAN (MCF Network) at different software levels on each controller, you can minimize this exposure by taking the following precautions:

 Make the master store store contr controller oller and file server server the last node to IPL. Thus, the files tha thatt are open by the terminals terminals continue continue to use the older older level fi files les until the te terminals rminals are are ready to lload. oad. This arrangement prevents an incompatibility problem when terminal code has a corequisite change to controller code or data files.

 IPL the terminals immediately after they come on line with a controller that has activated the new maintenance, but only maintenance, only if an IPL of the terminals terminals is necessar necessary y to load new ter terminal minal cod code. e. Use the TL parameter on the ADXCST0L command, not the disable terminal IPL function of the ADXSERVE command.. If the terminals command terminals must be loaded, loaded, the TL parameter parameter is recommend recommended ed under a any ny circumstance circum stances. s. If terminal code code has a corequisite corequisite change to controller controller co code de or data files, avoid avoid the disable terminal IPL function of the ADXSERVE command so that old terminal code does not try to interface interfa ce with new controller controller code. code. If there is no corequisite corequisite chan change ge with contr controller oller code or da data ta files, the disable terminal terminal IPL function function is recommended recommended while cashiers cashiers are si signed gned on. (See “Loading “Loading Terminall Storage” Termina Storage” on page 13-7.)

 Minimize the wait time between controller IPLs so that the controllers do not have much time to communicate with each oth communicate other. er. This prevents prevents an incompatibility incompatibility problem problem when co controlle ntrollerr code has a corequisite corequ isite change change to code or data files on another another controller. controller. Howeve However, r, this option is unde undesirab sirable le because becaus e of the time required required for all of the backgrou background nd applications applications and runtimes runtimes to load. It may be necessary necess ary to set the wait time to zero seconds seconds if the software software levels are found found to be incompatib incompatible. le. If you do so, any terminal request to the controller will take more time than usual because the request must compete with the loading of background applications and runtimes.

13-2

4690 Store System: Programming Guide

 

 

Note: These steps are unnecessary for most maintenance; they are only precautions you should follow when when the software software might be incompatib incompatible. le. Even then, then, it may not be nece necessary ssary to follow follow all these suggestion suggestions. s. Use those that pro provide vide the most safety safety with the least inconvenien inconvenience. ce.

 Application Applicati on Interface Interface This section describes the application interfaces that you can use with the Staged IPL Utility.

Apply Software Maintenance Before running the Apply Software Maintenance (ASM) Utility, run ADXCST0L with the NI RCP parameter to build the activation activation file, ADX_SPGM:ADXC ADX_SPGM:ADXCSTAF.DA STAF.DAT. T. This file instructs instructs the IPL code to activate activate maintenance mainten ance upon the next next IPL, but this proced procedure ure does not IPL the controller controllers. s. You can then IPL the controllers manually or use this utility to IPL each controller individually. A dump or a power outage after you select NI and before the Staged IPL Utility runs can cause ASM to run prematurely prematurely during during the IPL. That should should not cause any problem problem except for a longer longer than norma normall IPL, which would would cause terminals terminals to be offline for a longer than than normal per period. iod. You can minimize minimize this window by running the Staged IPL Utility immediately after running ADXCST0L with the NI parameter. The activation file created by running ADXCST0L with the “NI” parameter will always be erased by the Staged IPL Utility Utility or by the IPL IPL portion of of Apply Softw Software are Maintenance Maintenance.. If the Staged IP IPL L Utility does does not complete successfully and must be restarted, you must also restart ADXCST0L.

 R CP Comm RCP Comman and d The Staged IPL Utility is an RCP command named ADXCS50L, which is placed in the RCP command file, usually immediately following the ADXCST0L command.   Format: ADXCS50L i w t n n n...

where: i 

= The RCP status file reset indicator: Y N

= Reset Reset RCP status status file before before the comman command d ex execu ecutes tes.. = Do Do n not ot rese resett RCP RCP stat status us fi file le..

Normally, y, this indic indicator ator is N because because it usua usually lly runs after after ADXCST ADXCST0L. 0L. Also, you would would not Note: Normall want to erase resulting messages from ADXCST0L. w 

= Wait time. This indicato indicatorr is the number number o off seconds seconds to to wait after the re remote mote n node ode comes comes up. up. The

node is considered up by this utility after the IBM logo is first displayed on the controller, and the background backgr ound appl application ications s have begun to load and start. start. The wait time should should usually be the esti estimated mated amount of time it takes takes to load an and d start the bac backgroun kground d applications. applications. The value mu must st be between between 0 and 2147483 2147483 (about (about 24 days). days). The value mu must st not have a decimal decimal poin point, t, comma, or min minus us sign. t 

= Timeout Timeout value. value. This indicator indicator is the number number of minutes minutes to wait fo forr the remote node to come up. If the node does not come up within the number of minutes specified, this utility ends with an error message and attempts to cancel maintenance on the controllers that have already successfully

 

13-3

Chapter Chap ter 13. Using the Staged Staged IPL Utili Utility ty

 

 

activated maintenanc activated maintenance. e. The value value mu must st be between 10 an and d 3579 35791 1 (about (about 24 days). The v value alue mu must st not have a decimal point, comma, or minus sign. n 

= Node ID. The no node de IDs a are re sets sets of two two-char -character acter design designations ations for for the controllers controllers to be IPL IPLed. ed. The controllers contro llers are IPLed IPLed in the order of the node IDs specified specified with this command. command. If the controller controller on which this utility utility runs runs is on the list, it must must be last. Otherwi Otherwise, se, the IPL end ends s this utility and and the subsequent nodes are not be IPLed.

Examples:: Examples

ADXCS50L N 300 120 DD CC This example does not not reset reset the RCP status status file. file. It requests requests that c control ontroller ler DD be IPL IPLed ed first. first. After controller DD comes up, wait 300 seconds (5 minutes) for the background applications to finish loading and then IPL control controller ler CC. If DD does not come come up within 120 minutes, minutes, do no nott IPL CC.

DD::ADXCS50L N 0 180 CC DD This example example does not reset reset the RCP status file. It request requests s that this utility be run on cont controller roller DD so that you you can can IPL controller controller CC firs first. t. After CC comes comes up, up, immediately immediately IPL co controlle ntrollerr DD. If CC does n not ot come up within 180 minutes, do not IPL DD.

 Errorr Re Erro Reco cove very ry If any error is detected detected while IPLing IPLing the controllers, controllers, this uti utility lity does not IPL the remaining remaining controllers controllers.. If a controller has already IPLed before the error is detected, this utility attempts to cancel the maintenance from all controllers controllers that have successfully successfully activated activated maintenance. maintenance. To cancel mainte maintenance, nance, the activation activation must have been been in test mode, mode, and the controller controller mu must st have come come back up. If the error w was as a timeout waiting for a controller to IPL, the maintenance of that controller cannot be canceled, leaving the controllers at different software levels. Some examples of errors that can stop the IPL sequence after controllers have already started IPLing are:

 A timeout waiting waiting for the controlle controllerr to complete complete the IPL. The timeout timeout value is specified specified as a parameter. An error while while activating activating maintenance maintenance during the IPL IPL.. The return return code of the activati activation on proces process s is  kept in a temporary temporary file, ADX_SDT1 ADX_SDT1:ADXCS5 :ADXCS5TF.DAT. TF.DAT. This error error is rare and would be accompanie accompanied d by a W638 message message in the System System Event Log Log.. If a W638 is logged, logged, the activ activation ation of main maintenanc tenance e has failed and remains remains in the the same state as before before the attempt attempt to activ activate ate mainten maintenance. ance. The new maintenance might be in the ADX?SMNT? subdirectory, depending on when the error occurred.

 The request to IPL could not be communicated to a remote controller for a reason other than not being active on the LAN (MCF Network).

 One of the controllers that has come up with the new software has dumped. All progress progress and error error messages messages are logged in the RCP status status file on the acting maste masterr controller. controller. If messages cannot be written to the acting master, which happens if it is not the last controller to IPL,

messages are written to the local controller. messages controller. Before this utility utility terminates, terminates, the messages are trans transferre ferred d to the acting master. master. If this transfer transfer fails, the messages messages must be gathered gathered from both the acting acting master and the local controller.

13-4

4690 Store System: Programming Guide

 

 

Recomm Rec ommend ended ed Use This section provides some recommendations for using the Staged IPL Utility.

Test Te st Mo Mode de:: Activati Activation on of maintenance maintenance should should be in test mode. mode. This mode al allows lows automatic automatic cancelation of maintenance cancelation maintenance if anything anything goes wrong. wrong. If disk space is a concern, concern, the mainten maintenance ance can be accepted accept ed after the RCP status file file has been check checked ed to verify the successful successful comp completion letion of the IPLs. An acceptance accept ance of maintenance maintenance in test mode does does not require an IPL of the controller controllers. s. If the RCP status file indicates that the controllers are now at different software levels, you must run an appropriate ADXCST0L command to direct the controllers to start running the same level of software.

Wait Wa it Ti Time me:: Before using this utility in a live store, you should apply the maintenance to a test system using this utility utility with a very long wait time. Observe Observe how well the system runs runs with the control controllers lers at different software levels. If the new software is highly highly compatible compatible with the old softwa software, re, the wait time should should be about 300 seconds. seconds. This gives the applicatio applications ns time to load and open all of the necessary necessary file files. s. Some syste systems ms might take longer to load applicatio applications, ns, depending depending on the number and co complexity mplexity of the applicatio applications ns to be loaded. If the wait time expires before all of the applications are loaded, any terminal request to the controller will take longer than usual because the request must compete with the loading of background applications and runtimes. If testing reveals an incompatibility problem with running the old and new software on another controller, the wait time should be zero.

Timeout Tim eout Val Value: ue: Set the timeout value long enough so that it expires only when a controller has taken too long to come come up. If the timeout does does expir expire, e, this utility utility attempts to c cancel ancel the ma maintenan intenance ce that has already alread y been successfully successfully applied applied to other con controller trollers. s. Make sure that that you allow time for exce exception ption log processing, for an IPL to activate configuration changes, and for other contingencies; 120 minutes should be adequate adequate for most systems. systems. Set the timeout value value short enough enough so that all control controllers lers are bac back k up and operating at the same software level in time for the busiest part of the day. Examples:  Assume that you have a four-controller LAN requiring 100 minutes per controller to activate maintenance mainten ance through through an IPL, reconcile the exception exception log, and load the background background applications. applications. Assume that the timeout value chosen is 120 minutes and that the third controller does not come up within that time. The total ela elapsed psed time for for the first two controll controllers ers to IPL is 200 minutes, minutes, plus plus 120 minute minutes s for the third controller controller to timeout, timeout, and 200 minutes minutes to cancel mainte maintenance nance on the first first two controlle controllers. rs. This time totals 520 minutes. minutes. Calculate Calculate the worst case situation situation for your your system, and choose choose the timeou timeoutt value accordingly.

Where to Run this S Staged taged IPL U Utility tility:: You You ca can n run run this this util utilit ity y on an any y co cont ntrrolle ollerr by pu putt ttin ing g the the controller ID controller ID in front front of of the command. command. The controll controller er running running ADXCS50 ADXCS50L L must be IPL IPLed ed last. last. Otherw Otherwise, ise, this utility will end when the controller running it is IPLed.

Examples: Examples:

DD::ADXCS50L N 0 120 CC DD This command causes the Staged IPL Utility, ADXCS50L, to run on the controller DD.

AA::ADXCS50L N 0 120 CC DD

 

13-5

Chapter Chap ter 13. Using the Staged Staged IPL Utili Utility ty

 

 

This command command causes causes the Staged Staged IPL Utility, ADXCS50L, ADXCS50L, to run run on the acting acting master master.. If DD is not the acting master store controller, the utility ends with the message:

CONTROLLER DD MUST BE LAST IN THE LIST OF CONTROLLERS TO IPL

IPL IPL Or Orde der: r: You should should IPL the primary controller controller before before the backup backup contro controller. ller. When the back backup up controller is IPLed, the primary controller primary controller controller will resume. resume. Otherwise, Otherwise, you must prov provide ide some means for th the e resume operation, for example, configure automatic resume, resume manually, or IPL the backup controller. Example:: Example If CC is the primary store controller and DD is the backup store controller, the command should be:

DD::ADXCS50L N 0 120 CC DD If CC is running one TCC Network and DD is running another, and they are backing each other up, you should activate automatic resume. You should should IPL the acting acting master last. last. Because Because the RCP statu status s file is opened opened on the acting ma master, ster, messages to be written while the acting master is down must be saved in the local RCP status file and written to the the acting master master RCP status status file after itit comes back up. up. This sho should uld not be a prob problem lem unles unless s there are errors trying to open files and or moving the messages. If there are two controllers and they back up each other, no sequence will result in both controllers returning to their primary node (backup or primary) unless the resume is automatic or manual.

Load Loa d Term Termina inals: ls: If you apply maintenance that must be loaded in the terminal to make it active, you must load terminal terminal storage storage in all terminals terminals.. You should should use the TL parameter parameter of AD ADXCST0L XCST0L to accomplish accomp lish this. The terminals terminals do not reload until until the TCC Networks switch switch to a controller controller that has been IPLed to apply the new new maintenan maintenance. ce. Also, you should should disable disable loading of terminal terminal storag storage e whenever a cashierr is signed cashie signed on. See “Loading “Loading Terminal Terminal Storage Storage”” on pag page e 13-7 for more in informatio formation n about d disablin isabling g loading of terminal storage. Other methods exist to load the terminals, but they all require a separate action that must be invoked after the controllers controllers have have come back up. You can invok invoke e one of the following after after checkin checking g the RCP status file for errors:

 Use the ADXCS20L N 11 RCP command.  Select the Load Terminal Storage option from the STORE CONTROL FUNCTIONS menu accessed using the the SysReq  key.  SysReq key.

 Power off half half of the terminals terminals at a time so that there there are always always some terminals terminals o online. nline. This only works if memory retention is disabled.

User Applic Applications ations that IIPL PL the Control Controller: ler: If yo you u ha have ve an ap appl plic icat atio ion n that that runs runs when whenev ever er the there is an IPL or that detects an IPL, ensure that the actions taken by that application do not cause the

controller to IPL or otherwise controller otherwise interfere interfere with the IPLing of the controller controllers. s. Do not manuall manually y or otherwis otherwise e IPL any controller controller while while this utility is running. running. Allow this utility utility to perform all IPLs until until it has finished.

13-6

4690 Store System: Programming Guide

 

 

Id Idea eall Sy Syste stem: m: The following summarizes the requirements presented in this chapter:  Run ADXCST0L first with the NI RCP parameter.  Put the controller on which this utility is running last on the list. The following list summarizes the recommendations presented in this chapter:

     

IPL the controller acting as primary before the controller configured to support backup. If the terminals need to be loaded, use the TL parameter of ADXCST0L. Use a wait time of 300 seconds. Use a timeout value of 120 minutes. IPL the acting master last. ADXCST0L should activate the software in test mode.

An example of an ideal system is:

CC is DD is CC is DD is Allow

the acting master and file server. the alternate master and alternate file server. the backup store controller. the primary store controller. backup is active.

Automatic resume can be active or inactive in this example.

The command file should be:

AA::ADXCST0L Y 1G TL NI AA::ADXCS50L N 300 120 DD CC Note: If CC is not the acting master, this utility ends with the message:

CONTROLLER CC MUST BE LAST IN THE LIST OF CONTROLLERS TO IPL

Loading Terminal Storage Terminals must be loaded to make terminal application Terminals application changes changes active. Howeve However, r, loading termi terminals nals while operators operat ors are runnin running g customer checkout checkout would defeat much of the usefuln usefulness ess of this utility. There Therefore, fore, the following two exit steps are recommended to significantly reduce terminal downtime. ADXSERVE (function 54) ADXSERVE 54) disables the the loading of terminals. terminals. If this ADXSERVE ca callll was made in the user exit for operator signon, and enabled (function 53) again in the user exit for operator signoff, the load all terminals termina ls request request would only load terminals terminals that were were signed off. When the rema remaining ining terminals terminals sign off, each then reloads. reloads. All terminals terminals will eventually eventually load, but not while the operator operator is running running custo customer mer checkout. checko ut. To use this recommendat recommendation, ion, the old terminal terminal code must be compatible compatible with the new controller controller code.

 

13-7

Chapter Chap ter 13. Using the Staged Staged IPL Utili Utility ty

 

 

Enable Terminal IPL This function function enables enables terminals to reload. reload. If terminals were were to be reloaded earlier earlier but could no nott because you had disabled IPL, making this call causes the terminals to reload. Note: This function does not prevent a terminal from dumping or reloading as a result of a request to load a specific terminal. For the enable terminal terminal IPL parameters, parameters, see “Using the Enable IPL Function” Function” on page 15-28. 15-28.

Disable Terminal IPL This function prevents the automatic reload that can occur when a terminal comes online, and it allows the terminal termin al application application to use effectively effectively the terminal terminal RAM disk support support for temporarily temporarily loggin logging g data. In most cases, when the controller comes back online, the terminal application transfers the logged data to the controller. For the disable terminal IPL parameters, see “Using the Disable Terminal IPL Function” on page 15-29.

Messages  Messages The following table explains the messages which can appear when you use this utility. Table Tab le 1313-1 1 (Pag (Page e 1 of 3). Stage Staged d IPL Uti Utilit lity y Mes Messag sages  es  Message

Description

Request is only valid on a LAN (MCF Network) system.

The Multiple Controller Feature is not active.

ADXCST0L has not completed successfully.

The Apply Software Maintenance activation file, ADX_SPGM:ADXC ADX_SPG M:ADXCSTAF.D STAF.DAT, AT, does n not ot exist. Either A ASM SM was not rrun un beforehand, or ASM had an error that was logged in the RCP status file.

Request is not allowed while activating OS or LAN (MCF Network).

The Apply Software Maintenance activation file, ADX_SPGM:ADXCSTAF.DAT, indicates that either the Operating System or the Multiple Controller Feature was chosen to apply maintenance using the staged IPL. IPL. This situation situation is no nott allowe allowed d because th there ere will be a bri brief ef time when the controlle controllers rs are up and runn running ing at differ different ent softwa software re level levels. s. In many cases, this would cause a communication problem between the controllers. control lers. Results Results woul would d be u unpredi npredictable ctable..

The wait time must be numeric characters.

The wait time cannot contain periods, commas, minus signs, letters, or any characters other than 0 through 9.

The wait time must not exceed 2147483 seconds.

The largest number allowed is 2147483.

The timeout value must be numeric characters.

The timeout value cannot contain periods, commas, minus signs, letters, or any characters other than 0 through 9.

The timeout value must not exceed 35791 minutes.

The largest number allowed is 35791.

Node names must have a length of two characters.

The node node name lists lists must b be e of the form ““CC CC DD”. There sh should ould not b be e commas separating the parameters.

13-8

4690 Store System: Programming Guide

 

 

Table Tab le 13-1 13-1 (Page (Page 2 of 3). Stage Staged d IPL Utilit Utility y Mes Messag sages  es  Message

Description

Controller xx  must   must be last in the list of controllers to IPL.

The controller controller that that is runnin running g this utili utility ty must be last in th the e list. To run on another controller, add the node ID to the front of the command, as in the following example:

DD::ADXCS50L N 0 120 CC DD Controller xx  is   is not active on the LAN (MCF Network).

The controller indicated is not able to receive commands using the Multiple Controller Feature.

Status of controller xx  could   could not be verified.

An ADXSERVE command issued to the remote node to test the ability of the controller to communicate failed.

Controller xx   coul could d not not be IP IPLe Led. d.

An at atte temp mptt tto o IIPL PL th the e rrem emot ote e n nod ode e fai faile led. d. Eith Either er the the req reque uest st retu return rned ed a negative return code, or the controller remained up after acknowledging the request. reque st. If no failing failing return cod code e was return returned ed from the req request, uest, the user-specified timeout value was used to prevent a long wait for the controller to go down.

Controller xx   ha has IPLed.

The remote controller has successfully received the command to IPL. If an error is detected, detected, this this utility wi willll not try to IPL the rem remainin aining g control controllers. lers. Use this message to determine which controllers were IPLed before the failure

Controller xx  became   became inactive after IPL.

occurred. The remote controller IPLed, then came up to at least the point when background backgr ound appl applicatio ications ns are started started.. After the speci specified fied wait time time,, a query of the node returned an error indicating that the controller is not active on the LAN (MCF Network).

Controller xx  is   is no nott c con onfi figu gure red. d.

The re rem mot ote e c con ontr trol olller has has n not ot been been defi define ned d b by y c con onfi figu gura rati tion on..

Controller xx  did   did not come up within nn  minutes.   minutes.

The remote controller has not come up within the number of minutes you specified as the timeout parameter.

None of the remaining controllers will be IPLed.

Because of an error reported previously, the IPL sequence was ended before all controllers were IPLed.

None of the controllers have been IPLed.

Because of an error reported previously, the IPL sequence was ended before any controllers were IPLed.

Return Code is 8xxx  8xxx 4xxx .

Refer to the 4690 Store System: Messages Guide  for   for further information on

ADXSERVE Return Code is -1xxx  -1xxx .

interpreting the error. Se See e ““AD ADXS XSER ERVE VE (Req (Reque uest stin ing g a an n A App ppli lica cati tion on Se Serv rvic ice) e)”” on on p pag age e 15 15-1 -17 7 to to interpret the error.

Create of temporary work file on node xx  failed.   failed.

The temporary file, ADX_SDT1:ADXCS5TF.DAT, could not be created on the remote remote node. This uti utility lity crea creates tes the file so tha thatt the IPL portion o off ASM can put the the return co code de in it. Use this fi file le to veri verify fy that ASM ra ran n prope properly rly during the IPL.

xx   is is not a valid node ID.

The node ID is not two uppercase letters.

Insu Insuffi ffici cien entt nu numb mber er o off pa para rame meter ters. s.

You You mus mustt supp supply ly at at le leas astt fo four ur p par aram amete eters rs ffor or tthi his s fu func ncti tion on tto o wo work rk.. See See th the e section about the format of the command.

Controller xx  cannot   cannot be listed more than once.

The node ID was the same as another node ID previously listed in the parameter param eter list list.. If it is not listed twi twice, ce, it is the same as an another other log logical ical dri drive ve that points to the same controller.

Activation of maintenance on controller %c%c failed.

The IPL portion portion of ASM that moves moves files fa failed. iled. A W638 mess message age shoul should d be in the System Event Event Log. Maint Maintenance enance wi willll be cancel canceled ed automa automaticall tically y if possible.

See the W638 message in the System Event Log.

The IPL portion portion of ASM that moves moves files fa failed. iled. A W638 mess message age shoul should d be in the System Event Event Log. Maint Maintenance enance wi willll be cancel canceled ed automa automaticall tically y if possible.

 

13-9

Chapter Chap ter 13. Using the Staged Staged IPL Utili Utility ty

 

 

Table Tab le 1313-1 1 (Pag (Page e 3 of 3). Stage Staged d IPL Uti Utilit lity y Mes Messag sages  es  Message

Description

Cancel failed because activation was not test mode.

At least one controlle controllerr was IPLed to acti activate vate mai maintenan ntenance. ce. When a prob problem lem prevented the remaining controllers from activating maintenance, the cancel attempt failed because the activation was not test mode.

The controllers are now at different maintenance levels.

Some of the controllers were successfully IPLed to activate maintenance, but a problem occurred that prohibits the remaining controllers from activating activat ing maintenan maintenance. ce. It was not possible possible to cance cancell mainte maintenance nance..

The reset parameter must be a Y or N.

The first parameter must be a Y or N.

Attempting to cancel maintenance on controller xx .

At least one controller was IPLed to activate maintenance, but a problem prevented preven ted the remaining remaining controll controllers ers from activat activating ing mainte maintenance. nance. The utility now attempts to change the activation file command from test to cancel and IPL the controllers that have already activated maintenance in test mode.

Attempt to cancel maintenance on controller xx  failed.   failed.

At least one controller was IPLed to activate maintenance, but when a problem prevented the remaining controllers from activating maintenance, the cancel attempt failed.

The timeout value must be at least

The timeout value must be at least long enough to allow time for the

10 minutes. The failing parameter is xx .

controller to IPL and activate maintenance. The e errror me message p prreviously rre eported p po oints to to th the in indicated p pa arameter.

Remove diskette from drive A: on node xx .

A diskette is in the A: drive of one of the controllers, and is preventing the successful success ful activation activation of mainte maintenance nance.. Remov Remove e the diskette, and res restart tart both ADXCST0L and ADXCS50L.

ASM History File If a failure occurs after a controller has already successfully applied maintenance and the activation was test mode, the utility attempts to cancel the maintenance from the controllers that have already activated maintenance. mainten ance. This action logs logs an entry in the ASM history history file, becaus because e this is an Apply Softwar Software e Maintenance Mainten ance action. action. If the cancel action action is initiated from this this utility, a B is recorded in the act action ion field. This B value is a new indicator for the action field and is not documented in this manual.

13-10

4690 Store System: Programming Guide

 

 

| | | | |

Chapte Cha pterr 14. Using Using the Multi Multiple ple File File Archi Archiver ver Util Utility ity Compressing, Combining, and Archiving Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  14-2 Mapping the Combine File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  14-3

Splitting Files Out of a Combine File . . . . . Splitting a Given List of Files from a Combine | Log Log Fi File les s  . . . . . . . . . . . . . . . . . . . . . | Re Retur turn n Co Code des s  . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

File

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 14-4  14-4 14-5 14-5

© Copyright

14-1

IBM Corp. 1994, 1996

 

 

|

ADXNSXZL is a multiple file archiver ADXNSXZL archiver with builtbuilt-in in compression compression and decompress decompression. ion. It provides provides a simple and convenient convenient means means of copying larg large e files onto a diskette as efficiently efficiently as po possible. ssible. It is not compatible with the 46x0 Compress/Decompress utility and is intended only for command line use.

|

This utility is built into the installation and migration tools used by 4690 OS and is also used by the Apply

| |

Software Softwar e Maintenance Maintenanc e procedures procedur es to minimize the number diskette diskettes s that maintenance maintenanc e requires requires. . Othera uses might include archiving include archivi ng a subdirectory subdirecto ry before replacing replacingofsome files for testing testin g purposes purposes. . To receive helpful reminder of the command line options, you may start the application as follows to receive minimal documentation.

| |

| | |

  Format:

|

  ADXNSXZL

| | | | |

| |

Compressing, Combining, and Archiving Files To create a combine file, you must specify a name for the combine file and which file (or files) you wish to be included. included. Additional Additional files files may be added added la later. ter.   Format: ADXNSXZL C TEST.DAT ADXCSLCF.DAT

This example creates a file called TEST.DAT which contains a compressed version of the 4690 dump file ADXCSLCF.DAT.

|

Efficiency of compression varies greatly depending upon the contents and the size of the file to be compre com presse ssed. d. Large Large dump dump files files compre compress ss very very well. well. In contra contrast, st, th there ere is negl negligib igible le compre compressi ssion on on sm small all text files. It is possible that that the resulting combine combine file is actually actually larger th than an the origina originall uncompressed uncompressed files. However However,, in general, ADXNSXZL ADXNSXZL recognizes recognizes if a file is unlikely unlikely to benefit from compression compression,, and in this case, simply simply adds the file to the combine combine file without atte attempting mpting to compress compress it. In particu particular, lar, ADXNSXZL ADXNSXZ L never tries tries to compress files files that are smaller than than 2K bytes in size. This provides provides some

|

optimization of speed versus compression.

|

Alternatively, if you wanted to compress all the files in ADX_UPGM: you could use the following command:

| | | | |

| |

| |

  Format: ADXNSXZL C MYFILES.DAT ADX_UPGM:**

The resulting combine file, MYFILES.DAT, contains all the files in ADX_UPGM and the original files are left untouched.

|

When called with the C parameter to create a combine file, ADXNSXZL first checks for the existence of the combine combine file. If it already already exists, exists, an err error or is rep reported. orted.

|

If you wish to add files to an already existing combine file, you must use the A parameter.

|

|

  Format: ADXNSXZL A MYFILES.DAT C:\TEST.LOG

|

14-2

4690 Store System: Programming Guide

 

 

This example adds a compressed version of the file C:\TEST.LOG to the existing combine file | MYFILES MYFILES.DAT. .DAT. If the combine combine file is missing, missing, an error error is repor reported ted and no action action is taken taken.. |

| | |

Wildcards may also be used with the A parameter to add files to an existing combine file.   Format: ADXNSXZL A MYFILES.DAT ADX_UDT1:*.DAT

This example adds all files with an extension of DAT in the subdirectory ADX_UDT1 to the existing | combine file MYFILES.DAT without affecting the original files in ADX_UDT1. |

| | | | |

Mapping the Combine File To determine which files are contained within a given combine file, it is necessary to map the combine file, using the M parameter.   Format: ADXNSXZL M TEST.DAT

This example lists the contents of the combine file TEST.DAT and reports the original sizes, time stamps, | and other other information. information. The following following is an example of the output: output: |

| |

  Format:   ADXNSSLG.DAT

468663

1

4-05-1995 15 15:23 [[6 61%]

This example shows that the combine file only contains one compressed file, ADXNSSLG.DAT, that had an original size of 468663 bytes, a distribution attribute of 1 (local file), and a time stamp of 3:23 PM on | | the 5th of April 1995. It also lists to what extent the file was was compres compressed sed as 61% (the comp compresse ressed d version | of ADXNSSLG.DAT was 61% of the original size). |

The fin final al symb symbols ols ( ) rrefle eflect ct w whet hether her the compre compresse ssed d vers version ion of tthe he file is s split plit acr across oss severa severall combine files. files. If the size opt option ion for add and and compress compress is not used used,, this will always always show thre three e solid | blocks, indicating that the compressed version of the file is contained completely within this combine file. |

|

| |

Through the use of the size option, at times a compressed file will not fit completely within a single combine file, then other symbols are shown in this space, as follows:

|

compressed file is contained completely within this combining file

|

only the beginning of the compressed file is included

|

only a middle portion of the compressed file is included

|

only the end of the compressed file is included

If the complete file is not included within the combine file, you will need to look in other combine files to | find the remaining portions of the compressed file before you will be able to split out the original files. |

 

14-3

Chapter Chapt er 14. Using the Multiple Multiple File Archiver Archiver Utility Utility

 

 

|

Splitting Files Out of a Combine File

|

To restore files to their original format from a combine file, you must use the split parameter.

|

  Format: ADXNSXZL S TEST.DAT ADX_UPGM:

|

|

This restores all the files compressed in TEST.DAT to the subdirectory ADX_UPGM:.

|

Alternatively, you can request individual files to be split out of the combine file by adding the filename as an optional parameter.

| |

  Format: ADXNSXZL S TEST.DAT ADX_UPGM: AMCTESTF.DAT

|

|

This restores just the file AMCTESTF.DAT from the combine file TEST.DAT into the subdirectory

|

ADX_UPGM:.

|

The subdirector subdirectory y is not an optional parameter. parameter. If you wish to restor restore e files into the curre current nt subdirectory subdirectory,, then use the following format:

| |

  Format: ADXNSXZL S TEST.DAT .\ 

|

|

This relies relies upon the fact that ‘.’ is the current current directo directory. ry. Also, the subdirecto subdirectory ry must have a colon (‘: (‘:’) ’) or a back slash slash (‘\’) at the end end of its name. The following following is an example example of an error: error:

|

 

|

Incorrect Incor rect Format: Format: ADXN AD XNSXZ SXZL LS T TES EST.D T.DAT AT C: C:\AD \ADX_ X_UPG UPGM M

|

(miss (missing ing trail trailin ing g b bac ack k slas slash) h)

|

This reports reports errors errors for each each of the files it attempts attempts to split out out of the combine combine file. Because Because it tries to create the target file by adding the filename to the directory name as given, it results in an attempt to create files such as C:\ADX_UGPMAMCTESTF.DAT, which is a filename that is not valid.

|

To correct the last invocation, a back slash should be appended as follows:

|

 

| |

|

Correc Cor rectt Format Format:: ADXN AD XNSXZ SXZL LST TES EST.D T.DAT AT C C:\A :\ADX DX_UP _UPGM\ GM\

(n (not otice ice trai trailin ling g back back sla slash sh))

| | |

Splitting a Given List of Files from a Combine File As well as splitting all files or a specific file out of a combine file, it is possible to split a chosen list of files. This relies upon the L (list) parameter supported by ADXNSXZL:

14-4

4690 Store System: Programming Guide

 

 

|

  Format: ADXNSXZL L TEST.DAT ADX_UPGM: FILES.LST

|

|

This restores all the files listed in FILES.LST from the combine file TEST.DAT into the subdirectory

| |

ADX_UPGM:. ADX_UPG M:. FILES.L FILES.LST ST should be a list of filenam filenames, es, with one file per line, followed followed by a carriage carriage return line feed. feed. This can can be create created d with a text editor editor..

|

Log L Files s   og File

If ADXNSXZL is being used as part of another process, perhaps being called from a BATCH file, then it messages generate generated d logged to a file rather tha than n displaye displayed d to the screen. This | may be useful to have any messages | can be accomplished by using the optional log file parameter on the split and list commands.

|

|

  Format: ADXNSXZL S TEST.DAT .\ (C:\ADXNSXZL.LOG

|

This splits all the files contained in the TEST.DAT combine file into the current directory and reports all | messages to ADXNSXZL.LOG in the root directory of the C: drive. |

|

Retu rn Code Codes s  R eturn

ADXNSXZL displays messages and progress indicators for most of the common functions provided. | However, for functions involving split combine files, it often relies upon return codes to report progress and | errors.

|

These return return codes are are not visible when calling calling ADXNSXZL ADXNSXZL directly directly from the command lin line. e. They can be | detected through the use of IF ERRORLEVEL when ADXNSXZL is invoked from a BATCH file. |

|

The return codes are:

|

0  1  2 3 4 5 6 7 8 9

| | | | | | | | |

Good Incorr Incorrect ect parameters parameters File is not valid or is corrupted. Combine file is corrupted. Filename/directory is not valid. Unable to allocate storage. File already exists. Combine file is not valid. Out of disk space. Temp file is not valid.

10 | 11 | 99 |

 

List file is not valid. Log file is not valid. New combine file is required.

14-5

Chapter Chapt er 14. Using the Multiple Multiple File Archiver Archiver Utility Utility

 

 

14-6

4690 Store System: Programming Guide

 

 

Partt 3: Applic Par Applicati ations ons (Desig (Designin ning g and and Using Using))

© Copyright

IBM Corp. 1994, 1996

 

 

4690 Store System: Programming Guide

 

 

Chapte Cha pterr 15. Design Designing ing Appli Applicat cation ions s with with IBM 4680 4680 BASIC BASIC Types of Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Interactive Interac tive Applications Applications   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Background Backg round Applica Applications tions   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applica App lication tion Siz Size e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory Mem ory Models Models   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Code Co de Si Size ze   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Da ta Si Size ze   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fi File le Si Size ze   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Application Applica tion Priori Priorities ties   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Access Priorities in Terminal Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting a Background Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ADXSTART   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ADXPSTAR   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Authorization Authorization   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ADXAUTH   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FUNC Parameter for Operator Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OPID$ Parameter—Operator ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OPPW$ Parameter—Operator Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OPID2$ OPID 2$ Paramet Parameter er   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Password Passwo rd Encryption Encryption   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Communicating between Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pipe Routing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Application Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Store Controller and Terminal Application Services . . . . . . . . . . . . . . . . . . . . . . . . . . ADXSERVE (Requesting an Application Service) . . . . . . . . . . . . . . . . . . . . . . . . . . ADXERROR (Application Event Logging) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chaining Chainin g Applications Applications   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chaining to Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chaining to Directly Executable Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RAM Disk Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations for Installing RAM Disks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing RAM Disk Files from Controller Applications . . . . . . . . . . . . . . . . . . . . . . . . Accessing Controller RAM Disk Files from Terminal Applications . . . . . . . . . . . . . . . . . . Accessing Terminal RAM Disk Files from Terminal Applications . . . . . . . . . . . . . . . . . . . ADXCOPYF (Copying RAM Disk Files) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Store Controller Application Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ADXFILES (Canceling the Shared Use of a File) . . . . . . . . . . . . . . . . . . . . . . . . . . ADXCSEOL (Store Closed Query Application) . . . . . . . . . . . . . . . . . . . . . . . . . . . . ADXEXIT (Set the ERRORLEVEL VALUE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ADXSERCL (Closing an Application Service) . . . . . . . . . . . . . . . . . . . . . . . . . . . . Terminal Application Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 15-2 15-2 15-2 15-3 15-3 15-3 15-4 15-5 15-5  15-5  15-6 15-6 15-7 15-8 15-8  15-9  15-10  15-10 15-10 15-11  15-11  15-12  15-17  15-17  15-17  15-29 15-30  15-30  15-31  15-31  15-31  15-31  15-32  15-32  15-32  15-33  15-34  15-37  15-38  15-39  15-39

ADXDIR (Listing Terminal RAM Disk Files) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  15-39 Extended Memory Management for the IBM Point of Sale Terminal . . . . . . . . . . . . . . .  15-41 The IBM 4690 Operating Operating Syste System m is a protectedprotected-mode mode operating operating syste system. m. This means that that an applicati application on can only access access code and data areas areas that are par partt of that applicatio application. n. Also, because because of file secur security ity capabilities, the application can only access files that it has created or been designated to access. Memory requirem requirements ents vary depending depending on your your application’s application’s objectives objectives and des design. ign. You can make an application a single module or split it into several load modules and chain from one to the other.

© Copyright

15-1

IBM Corp. 1994, 1996

 

 

Refer to the IBM 4680 BASIC: Language Reference  for   for the character set, variable types, commands, and syntax rules. rules. You can use use a text editor to write write your IBM 4680 4680 BASIC applicatio applications. ns. The IBM 4690 Operating Operating System System limits acces access s to files and operating operating system func functions. tions. Each file and function is assigned security attributes that limit its use according to the authorization level of the user. The system maintains a system file, ADXCSOUF.DAT, defines these authorization levels. levels . For more information information on authorization the system system authorization author ization file and file file that protection, protectio n, see “Syste “System m Authorization Author ization”” on page 15-8 and “Protecting “Protecting Files” on page page 2-23. For additional information on how to use the functions of your system, refer to the IBM 4690 Store  System: User’s Guide .

Types of Applications The store controller controller operating operating system supports supports two types of applications: applications: interactive interactive and background background.. An interactive  application   application uses the store controller keyboard and display or auxiliary console to directly commun com munica icate te with with the o oper perator ator.. A background  application   application communicates directly with the operator through throug h the BACKGROUN BACKGROUND D APPLICATION APPLICATION CONTROL screen. screen. This screen screen is a backgrou background nd applica application tion control screen used for communication between the operator and background applications. Using a window, window, you can run several several interac interactive tive applications applications at the same time. time. Each appli application cation runs runs until it either finishes finishes or operator input is required. required. When input is requir required, ed, the application application waits for further input input before continuing.

 Interactive Interact ive Appli Applicati cations ons Interactive appl Interactive application ications s fall into two categories: categories: prima primary ry and secondary. secondary. The primary application  is   is the main application that runs in your store’s normal operating environment. Secondary applications  are  are applications applic ations that are are selected from from the SECONDARY APPLICATION APPLICATION men menu. u. This menu is reac reached hed by choosing the second option on the SYSTEM MAIN MENU. Each interactive application is assigned a window . Windows enable each a applica pplication tion to e execute xecute as if it had actual actual control control o off the sc screen reen and and keyboard keyboard.. The IBM 4690 Store System: User’s Guide  explains   explains windows.

 Background Appli Background Applicati cations ons Background applications Background applications are non-interactive non-interactive store contro controller ller applications. applications. Some backgro background und applications applications start or stop running when the system is IPLed or when the acting master store controller or acting file serverr is changed serve changed on a LAN (MCF Network) Network) sy system. stem. The operator operator or the h host ost must star startt other applications that do not start automatically. There are two k kinds inds of backgrou background nd a applica pplications: tions: permanent permanent and and te temporar mporary. y. You d define efine permanent 

background application background applications s when designing designing your store’s store’s configuration configuration.. You define the name of the background application, the parameters passed to it, the text, and whether it begins at IPL by using the configuration screens. Temporary  background   background applications are started from the host site or from your application using the ADXSTART interface ADXSTART interface (see (see “ADXSTART “ADXSTART”” on page page 15-6). 15-6). HCP, if begun begun from from the h host ost site, site, runs as a temporary tempor ary background background application. application. The operator operator can remove tempor temporary ary applications applications if they are not active by pressing the Clear Clear key  key while viewing the BACKGROUND APPLICATION CONTROL screen.

15-2

4690 Store System: Programming Guide

 

 

You can determine the status of your background applications by displaying the BACKGROUND APPLICATION APPLICA TION CONTROL screen screen and spec specifying ifying the applicatio application n name. This screen screen gives you the sta status tus of the executing background application, the parameters passed to it, and any message sent by the background backgr ound ap applicati plication on to th the e oper operator. ator. Refer to the IBM 4690 Store System: User’s Guide  for   for information on BACKGROUND APPLICATION CONTROL. Your applications update the BACKGROUND APPLICATION CONTROL status screen by writing messages messag es to it periodically. periodically. Use a function called called Display Display Background Background Application Application Status to write write these status messag messages. es. This function function is desc described ribed iin n “Using “Using Application Application Servic Services” es” on page 15-17 15-17..

Applic A ation on Size Size   pplicati The IBM 4690 Operating System has several size restrictions on memory and disk space that your programs progr ams must meet. The restrictions restrictions are are different for the ter terminal minal and the store store controll controller. er. When planning planning your app applicatio lications, ns, you should kn know ow how much disk space space is available available to you. The IBM 4690 Operating System keeps track of the amount of space already used and the amount available on your disk. disk. You can determine determine th this is informa information tion by using using the CHKDSK or D DIR IR commands. commands. The CHKDSK command has options through which you can get a report of how much total disk space you have, how much of it contains files, how much space is still available, and how much space, if any, is considered defective. The DIR command gives you a listing of the files on your disk, how much space they occupy, and how much space space remains available available.. For more informati information on on these commands commands,, refer to the IBM 4690 Store  System: User’s Guide .

 Memory Memo ry Mo Mode dels ls IBM BASIC supports supports three different different memory memory models: large (for (for store controllers controllers)) and big and medium (for terminals). termina ls). With large or big memory memory models, models, your application application can have have more than 64 KB of code and more than 64 KB of heap  data  data (see (see “D “Data ata Size” Size” on on page 1515-4). 4). Big me memor mory y mode models ls all allow ow up to one one 64 KB segment of static    data, data, while large models allow multiple 64 KBwithin segments of KB static data. Medium memory models require that allmemory stack , static, and heap data reside one 64 segment. Use the compiler directive %ENVIRON to specify whether your application is to execute in the store controller contro ller or in the terminal. terminal. For more details details on memory models, models, refer to the memor memory y allocatio allocation n chapter in the IBM 4680 BASIC: Language Reference .

 C ode Si Code Siz ze Each IBM 4680 BASIC program program module module that you compile compile produces produces an object module module (OBJ file). An object module contains a code segment and a data segment.

Each code code segment ca can n have a maximum maximum of 64 KB. When you compile compile a pro program gram modu module, le, the comp compiler iler lists the number number of bytes required required for the code segment. segment. When you link you yourr progra program m modules toge together ther to form a load module, the link editor lists the code size (which is the total number of bytes for all of the code segments of the modules). The maximum code code size supported supported by the link editor editor is one million bytes. bytes. If your code size exceeds exceeds the amount of memory you have available, you may consider chaining from one load module to another to decrease decre ase the memory required required by each each load load modu module. le. See “Chaining “Chaining Applications” Applications” on pag page e 15-30 for more information on chaining.  

15-3

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

Each code code segment require requires s a code segment segment name. You can use a ma maximum ximum of 200 code code segmen segmentt names in a load load module for the the termina terminal. l. The IBM 4680 BASIC BASIC compiler compiler uses up to fiv five e of these code segmentt names segmen names for each load module. module. Each object object module uses one co code de se segment gment name. Theref Therefore, ore, you can have up to 195 object modules per load module plus five code segment names used by the compilerr for a terminal app compile application lication.. There is no limit to the number number of object module modules s in a load module for an application in the store controller.

 D ata Si Data Size ze The total data area area for a load module is composed composed of three elements: elements: static data data,, heap data, and stack data. The terminal terminal medium medium memory mod model el default data data size is almost almost 64 KB. If you want to cha change nge the valu value e of the terminal terminal data size, size, use the DATA[MAX[]] DATA[MAX[]] option option on the LINK86 LINK86 command. command. The maximu maximum m data area size is almost almost 64 KB. To define the the maximum data data area size, size, use the DATA[MAX[FFF DATA[MAX[FFF]] ]] option. The terminal big memory model and store controller default data area size is the sum of the initial 8 KB heap plus the load load module static data data plus the stack. The data are area a size change changes s dynamica dynamically lly with the size of the heap. The static data  area   area is used to hold hold your integer integer and real real variable variable data for your your code mo modules. dules. It also contains contai ns a pointer for each each string variable variable and a pointer fo forr each array definition definition.. In addition, addition, it contains these same types of data for the shared runtime library, common variables, and overlay variables. When you compile a program module, the compiler lists the number of bytes of static data required. When you link your program modules together to form a load module, the link editor lists the static data size, which which is the total number number of bytes bytes of static data data for all of the pro program gram modu modules. les. The maximum maximum static data area area for a medium model model termin terminal al load module module is 64 KB minus the stack stack and minus minus the heap heap.. The maximum static static data area area for a big memory memory model terminal terminal load module module is 64 KB. The maximum maximum static data area for a store controller load module is one million bytes. For medium memory models (terminals only), there is one data area whose size can be no larger than 64 KB minus minus 16 bytes. bytes. (This is the d default.) efault.) This area area contains contains th the e stack (2K), tthe he static static data, and the heap data. Big memory meup mory models allowlarge up up etoand 64 big KB of static static da ta. Large allow multiple 64 KB of static data— da ta— to 1 MB. Both larg memo memory ry data. models allow allowmemory up to 64models KB of stack stac k space.  area is where variable variable length items items are kept. These items items include all stri string ng variab variables, les, array The heap data  area elements, elemen ts, application application file and device buffers, buffers, and other runtime subroutine subroutine library library data. In the terminal, the size of the heap is determined by the number of bytes remaining in the data area after the stack and the static data are are allocated. allocated. In the store controller controller,, and in the terminal big memory memory model, the size of the heap is determine determined d dynamically. dynamically. The program program requ requests ests heap s space pace as nee needed. ded. You can determine determine the amount amount of available heap heap space from the application application.. The FRE function function indicates indicates the total number of bytes available everywhere in the heap, and the MFRE function indicates the largest

number of contiguous bytes available anywhere in the heap. The stack data  area   area is used to pass pass parameters parameters fr from om one function function or subprogra subprogram m to another another.. It is also used by the runtime runtime subroutine subroutine library library procedures procedures to pass int internal ernal data. data. The stack als also o contains the caller’s return address.

| |

The size of the stack is determined determined when when the application application load module module is loaded. The loader must must be able to obtain the minimum stack size request, which is 128 bytes for the terminal medium memory model, 1024 bytes for the terminal big memory model, and 2560 bytes for the store controller, or the application

15-4

4690 Store System: Programming Guide

 

 

load does not not succee succeed. d. The loader loader obtains as as much memory memory as possible possible for the sta stack, ck, up to the maximum size requested. The runtime stack in the BASIC terminal medium memory model occupies the first 2 Kb of the data | segmen segment. t. This stack stack size size is fixed fixed and canno cannott be cha changed. nged. |

| | | | |

The maximum stack stack size for big and large large memory mode modell applications applications is 64 Kb. Check the LINK86 LINK86 output messages messag es for the default default maximum maximum stack size size defined. defined. You may change change this with th the e LINK86 STACK[MAX[]] STACK[MA X[]] option. In order to leave more more space for dynamic dynamic data (the heap), heap), the stack should should be no larger than is necessa necessary ry for the the applic application ation to run run correctly. correctly. Refer to C Chapter hapter 9 for mor more e inform information ation on STACK and other link options.

Fil  F ile Si Siz ze Depending on your needs, you can decide to keep the current default size of system files or change the size. size. Changi Changing ng file s size ize can can help you you manage manage your your storage storage more more effici efficientl ently. y. The IBM 4690 Store System:  User’s Guide   tells tells you how to change file size when performing controller configuration. You do not have to change change system file size sizes. s. When the system system is IPLed, the opera operating ting system system checks the size of your store store controller controller dump file. If the store controller controller system system dump file size is not larg large e enough, file size is automa automatically tically increase increased. d. The terminal terminal dump file size is not automa automatically tically ad adjusted. justed.

Applicati on Priorities Priorities  Application The IBM 4690 Operating System runs all controller foreground applications and all terminal applications at priority prior ity 5. Background Background controller controller applications applications can run at any priority priority between 1 (high priority) priority) and 9 (low priority). prior ity). For most systems, systems, background background applications applications should be run at priority 5, which is the same priori priority ty as any foreground foreground applications applications.. Applications Applications are scheduled scheduled to run as follows: follows:

 If several applications are running at the same priority, then the 4690 Operating System uses the time-slice method . The time-slice time-slice method method maintains maintains a queue of applicati application on reque requests sts and allows allows each application to process for a certain time period and interrupts execution, so the next application may process.

 The 4690 Operating System allows the application with the highest priority to execute until one of the following conditions is met:

 – The application appli cation has completed execution.  – The application appli cation must wait for access to a resource such as a file.  – Another application appli cation with wit h a higher priority is executed.

File Access Priorities in Terminal Applications You can specify priorities for file access in a terminal application using the reserve word, PRIORITY. PRIORITY is a reserved reserved word tha thatt is valid only in terminal terminal applications. applications. You can spec specify ify it with the OPEN

or CREATE statements. When you specify PRIORITY, the operations of that file are performed before requests from other terminal files. other For example, examp le, terminal if you create a file using PRIORITY, PRIORITY, reading reading from and writing writing to that file takes prio priority rity over pending file requests without PRIORITY. Note: All terminal file requests have a higher priority than store controller file requests.

 

15-5

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

Starting a Background Application | |

This section section describes describes functions that can start start backgrou background nd applications. applications. These func functions tions are contai contained ned in the runtime library ADXACRCL.L86.

 ADXSTART ADXSTART This function starts a background application using the 4690 Operating System. This function is declared as follows:

     

FUNCTION ADXSTART (NAME$,PARM$,MESS$) EXTERNAL INTEGER* INTEG ER*22 ADXSTA ADXSTART RT STRING STRING NAME$, NAME$,PAR PARM$, M$,MES MESS$ S$ END FUNC FUNCTI TION ON

where: NAME$ =  Name of background application to be started (without R::) (maximum length = 21 bytes) PARM$ =  Parameters Parameters for the backgroun background d applicati application on (maximum (maximum length = 46 bytes) MESS$ =  Initial message to be displayed on the background status screen (maximum length = 46 bytes) The function is invoked as:

 

return.smal return.small=ADXS l=ADXSTART TART (pname$,ip (pname$,iparm$, arm$,imess$ imess$))

This function function returns returns a zero if a command command was was issued issued to start start the application application.. Table 15-1 sh shows ows retu return rn codes and their descriptions. Table Tab le 15-1 15-1.. ADX ADXSTA START RT Return Return Codes  Codes  Return Code

Description

0

Function completed successfully.

-1000

Function code (for example, first parameter) is not valid.

-1001

Buffer address or length not valid.

-1170

Application name missing or not valid.

-1171

All background application list entries in use.

-1172

Maximum number of ba background applications al already active.

-1175

Invalid parameter.

-1176

Internal error (unable to open driver).

15-6

4690 Store System: Programming Guide

 

 

ADXPSTAR This function function starts a background background application application at a specified specified priority. priority. To better under understand stand ADXPSTAR ADXPSTAR and its priority, you should become acquainted with how the 4690 Operating System schedules applications. Every applicatio application n has a priority ran ranging ging from 1 (highest) (highest) to 9 (lowest) (lowest) with 5 being the default default.. If several applications are running at the same priority, the operating system uses a time-slice method to service them. Each application application is allowed allowed to run for a certain period period and stop, so that the nex nextt application application may run. The 4690 Oper Operating ating System System allows the appli application cation with the highest highest prior priority ity to execute un until til one of the following conditions occur:

 The application is complete.  An application with a higher priority becomes scheduled to run and is executed.  The application is forced to wait for an external event to end. For example, if a system is running three applications, one at priority 2 and two at priority 5, then the application applica tion at priority priority 2 executes until until it has completed or is forced forced to wait. If an applicati application on at priority 1 is submitted, submitte d, then the application application at priority priority 2 is preempted. preempted. The priority priority 5 applicati applications ons would begin begin execution on a time-slice basis after the higher priority applications had completed execution or entered wait states. Use the ADXPSTAR ADXPSTAR function carefully. carefully. As the 4690 Operating Operating Syste System m allows the highes highestt priority application to execute until it ends or is preempted, it is possible that a high-priority application could cause your system system to neglect all lower priority priority applicati applications. ons. This occur occurs s if the high-p high-priorit riority y applicatio application n takes a long time to either complete or experiences few wait states. The ADXPSTAR ADXPSTAR function allows allows you only to set the priority priority of the background background applic applications ations.. All previo previous us applications and any applications initiated by the host, whether background or previous applications, run at the default priority 5. The function is declared as follows:

     

FUNCTION ADXPSTAR (NAME$,PARM$,MESS$,PRIORITY) EXTERNAL INTEGER*2 INTEGER*2 ADXPSTAR,P ADXPSTAR,PRIORIT RIORITYY STRING STRING NAME$, NAME$,PAR PARM$, M$,MES MESS$ S$ END FUNC FUNCTI TION ON

where: NAME$  PARM$  MESS$ 

= Name of background application to be started (maximum length = 21 bytes) = Parameters for the background application (maximum length = 46 bytes) = Initial message to be displayed on the background status screen (maximum length = 46   bytes) PRIORITY   = = Priority of the background application (value from 1 to 9; default=5) The function is invoked as:

 

return.smal return.small=ADX l=ADXPSTAR PSTAR (pname$,ipa (pname$,iparm$,im rm$,imess$,i ess$,iprior prior))

This functio function n returns returns a zer zero o if a command command was issued to start start tthe he ap applicati plication. on. Table 15-2 on page page 15-8 shows return codes and their descriptions.

 

15-7

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

Table Tab le 15-2 15-2.. ADXSTAR ADXSTAR Retu Return rn Cod Codes  es  Return Code

Description

0

Function completed successfully.

-1001

Buffer address or length not valid.

-1170

Application name missing or not valid.

-1171

All background application list entries in use.

-1172

Maximum number of ba background applications al already active.

-1175

Invalid parameter.

-1176

Internal error (unable to open driver).

-1177

Priority given is out of range.

System Sys tem Author Authoriza izatio tion n To ensure system and data security, the IBM 4690 Operating System requires that each operator using the system system be authorize authorized. d. This au authoriza thorization tion is gr granted anted through through a system authorization file  named   named ADXCSOU ADX CSOUF.DA F.DAT. T. It contain contains s operator authorization records . Each Each operato operatorr using using the sys system tem mu must st have have a record in this file. file. This recor record d contains the operator operator ide identifier ntifier (ID), (ID), passwo password, rd, group ID, and use userr ID and specifies which system request keys and menu options the operator ID can use. When an operator signs onto the store controller console, the system verifies the operator ID and password passw ord enter entered ed with the ID and password password in the system authorizatio authorization n file. If both are valid, the operator operator is allowed to use those system functions specified for the ID by the operator authorization record. The system system authorization authorization file is placed placed on your system during during installation. installation. The ADXCSOU ADXCSOUF.DAT F.DAT file resides in subdirectory ADX_IDT1 and has the same file protection as your other application files. The operating operating system system does not provide provide operator operator authorization authorization for termi terminal nal signon signon.. The IBM 4680 or 4690 applications applic ations provide provide this function. function. If you write your own app applicatio lication, n, it must provide this fun function ction if it is needed.

 ADXAUTH ADXAUTH For your operators to sign on and use the system, you must create and maintain authorization records for each one. To add, change, or delete an operator operator author authorization ization record, record, your appli application cation prog program ram must use the function ADXAUTH. ADXAUTH. The application application program program using this function should should be an interactive appl application ication.. You can also use this function in a background application, but only with functions that do not require screens scree ns to be used (functions (functions 3, 8, 9, and 10). This funct function ion can be used only in the stor store e controll controller er and is only in ADXACRCL.L86. The user ID and group group ID for each operator operator can be set with ADXAUTH. ADXAUTH. Operators Operators needi needing ng access to files

in command mode should be assigned according to: Files in Subdirectories

User ID

Group ID

ADX_Ixxx  ADX_I xxx 

1

2

ADX_Uxxx  ADX_U xxx 

1

3

xxx  can   can be any subdirectory name beginning with ADX_I or ADX_U. Software development functions should be performed in the ADX_Uxxx  ADX_Uxxx  subdirectories.   subdirectories.

15-8

4690 Store System: Programming Guide

 

 

The following example shows how to declare the ADXAUTH function:

     

FUNCTION ADXAUTH FUNCTION ADXAUTH (FUNC, (FUNC, OPID$,OPPW OPID$,OPPW$,OPI $,OPID2$) D2$) EXTERNAL EXTERNAL STRING ST OPID$,OPPW$,OPID2$ INTEGER*2 IN ADXAUTH,FUNC END FUNCTION EN

where: FUNC  OPID$  OPPW$  OPID2$ 

= The action to be taken. = The operator ID on which an action is to be taken. = The password for the ID. = The current current operator operator ID or the template template ID depe depending nding on th the e reques requested ted functi function. on. For FUNC parameter parameter 10, OPID2$ OPID2$ indic indicates ates two IDs separate separated d by a colon. The first is th the e template, and the second is the OPID whose authorization must not be exceeded.

The following example shows how to invoke the ADXAUTH function:

 

AUTH.RET=AD AUTH.RET=ADXAUTH XAUTH (func.code (func.code,opera ,operator,pa tor,password ssword,oper ,operid2) id2)

AUTH.RET is a 2-byte integer variable that receives the return code from the function. Note: The operating operating system system does not restrict restrict access to your primary primary and sec secondar ondary y applicati applications. ons. If security is required security required for these applications applications,, you must provid provide e it in the application. application. The curre current nt operato operatorr ID is the only parameter passed to these applications and can be used as part of an application authorization function if required.

FUNC Paramet Parameter er for Operato Operatorr Auth Authorizati orization: on: Th The e FUNC FUNC pa para rame mete terr tell tells s yo you u wh what at ac acti tion on can can be taken. taken. The ffunction unctions s you you can choose are: 1 2 3 8 9

= = = = =

Change an operator authorization record. Add an operator authorization record. Delete an operator authorization record. Change password only. Make operator operator ID have the the same authorizati authorization on as the oper operator ator ID spec specified ified by OPID OPID2$. 2$. If OPID2$ does not exist, a new ID is created.

10 = This function is the same 9 except OPID2$ contains a template ID and a second ID whose authorization must as notFUNC be exceeded. If you choose the ADD or CHANGE functions, the system displays several screens from which you select the system functions functions the operator operator can use. use. The current current operator operator (OPID2$ (OPID2$)) can select for another another ID (OPID$) only those functions for which the current operator ID is authorized. Note: You must have at least one ID on your system that is authorized for all system functions. The current operator ID making a change to a record cannot be the same as the operator ID being changed.

If you try to change an authorization record that does not exist, you receive error code 1010, and your requestt is handled reques handled as an add functio function. n. The system system creates creates a recor record d havin having g default default authorizat authorization. ion. The initial default default authorization authorization for the add function makes makes no system functions available. available. The operator operator would be allowed only to sign on and select primary and secondary applications. If you try to add a record for an operator ID that already exists, you receive error code -1010, and your request is handled as a change function. If you try to delete an authorization record that does not exist, you receive error code -1010.

 

15-9

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

The make function function allows allows you to use an an operator operator ID as a template for for other IDs. IDs. You can cre create ate or change other IDs without change without having to select eac each h system funct function ion from the screens. screens. The new or chang changed ed IDs have the same same authorizatio authorization n as the template template ID. However, However, for FUNC 10 10,, the new ID does not ha have ve greater authorization than the ID whose authorization must not be exceeded. If the template ID you specify for the make function does not exist, error code -1011 is returned and defaultt authorization defaul authorization is used as the template. template. A new ID having default default authoriza authorization tion is create created. d. Table 15-3 shows the FUNC para parameter meter return return codes and their descriptions descriptions.. Table Tab le 1515-3. 3. FUNC FUNC Par Parame ameter ter for Operat Operator or Authori Authorizati zation on Return Return Cod Codes  es  Return Code

Description

0

Function completed successfully.

-1000

Unknown function code.

-1001

File not found.

-1002

Error reading or writing the disk.

-1003

OPID$ not specified.

-1004 -1005

No password specified. No OPID2$ (only when two OPIDs required).

-1010

One of these conditions exists:

 Add function was handled as change because ID already existed.  Change function was handled as an add because ID was not found.  Delete requested for ID that was not found. -1011

Functio tion handled as re req queste ted d usi sin ng default authorization because OPID PID2$ was not fou found.

-1020

Memory could not be allocated to process authorization.

This is pa parramet ameter er in indi dica cate tes s the the op oper erat ator or ID to ad add d, cha hang nge, e, or OPID$ OPI D$ Par Parame ameter— ter—Ope Operato ratorr ID: Th delete. The OPID$ parameter delete. parameter should should be a string containing containing up to nine ASCII alphanumer alphanumeric ic characters. characters. There should should be no leading blanks. blanks. Leading Leading blanks and zer zeros os are considered considered par partt of the operator ID. Trailing blanks are ignored.

OPPW$ Parame Parameter—Op ter—Operator erator Passwor Password: d: Th This is pa para rame mete terr is the the pa pass sswo worrd for for func functi tion ons s 1, 2, 8, 9, and 10. The OPPW$ OPPW$ parameter parameter should should be a string co containing ntaining up up to eight ASCII al alphanum phanumeric eric characters. chara cters. This paramete parameterr should should not c contain ontain leading blanks. blanks. Leading Leading blank blanks s and zeros zeros a are re con considere sidered d part of of the passwor password. d. Trailing Trailing blanks blanks are ignored. ignored.

OPID2$ OPI D2$ Par Parame ameter: ter: For FUNC parameters 1 and 2, the OPID2$ parameter should be a previously defined operator ID. For FUNC parameter defined parameter 9, this parameter parameter indicates indicates the operator operator ID to be used to set the authorization authorization for the the ID specified by OPID$. OPID$. The OPID2$ parameter parameter should should be a string cont containing aining up

to nine ASCII alphanumeric alphanumeric chara characters cters without without any leading blank blanks. s. Leadin Leading g zeros are consid considered ered part of the operator operator ID. Trailing Trailing blanks blanks are are ignored. ignored. For F FUNC UNC parameter parameter 10, OP OPID2$ ID2$ contains contains two IDs separated separ ated by a colon. colon. The first first is the template ID, ID, and the seco second nd ID is the ID whose a authori uthorization zation must must not be exceeded exceeded (this can be the currently currently sig signed ned on ID). Both IDs should should be strings cont containing aining up to nine alphanumeric characters. For example:

"1234" + ":" + "4567" For other FUNC parameters, this parameter is ignored.

15-10

4690 Store System: Programming Guide

 

 

Passw Pas sword ord Enc Encryp ryptio tion n The IBM 4690 Operating Operating System uses one-way one-way encrypted encrypted passwords. passwords. The system encr encrypts ypts passw passwords ords before storing storing them in the system system authoriz authorization ation file. When an operator operator sign signs s on, the password password entered is encrypted and the encryption code is compared to the encrypted password code in the operator’s authorization record. authorization record. If the two two code codes s match, the operator operator is allowed allowed to s sign ign on. If your applica application tion fil files es contain password passwords, s, your applications applications should should encrypt encrypt the passwords. passwords. You can use the follo following wing subprogram to encrypt an eight-character ASCII password:

     

SUB ADXCRYPT (RETCODE, PWIN$, PWOUT$) EXTERNAL SSTTRING PWIN$,PWOUT$ INTEGER*2 RETCODE IN END SUB EN

where: RETCODE  = Contains the return code from the call. PWIN$  = Contains the password to be encrypted. PWOUT$  = Receives the encrypted value. The PWIN$ parameter should be a string containing up to eight ASCII alphanumeric characters with no leading blanks. blanks. Leading Leading zero zeros s are considered considered part part of tthe he password. password. If this parame parameter ter is missing missing,, erro errorr code -1100 is returned. The PWOUT$ parameter returns an eight-character string containing ASCII characters that represent decimal digits. You can use this subprogr subprogram am in both the store controller controller and the terminal. terminal. It is in ADXACRCL.L8 ADXACRCL.L86, 6, ADXUCLTL.L86, and ADXUCRTL.L86.

Communicating between Applications Your applications applications can can communicate communicate with each other other in two ways. They can writ write e informati information on to and read information from a file, or they can use pipes . Pipes are are file-like file-like structu structures res in memory used fo forr communicating communi cating betw between een applications applications.. Exchan Exchanging ging data using using pipes is much faster faster than with disk files. files. Use pipes to communicate data that can be recreated by the application writing the data; if there is a power line disturban disturbance ce the store con controller troller is IPLed, IPLed, and the contents contents of the pipe are lost. Use disk files for data that cannot be recreated. Pipes are used in the following types of application communication:

 Between applications at the store controller  Between applications from one terminal to another terminal or the store controller  Between applications from one node to another node on a multiple store controller system

A pipe is an area area of memory that that is like a sequential sequential file. Your app applicatio lication n create creates s a pipe by using th the e CREATE command command and specifyin specifying g a pipe name. A pipe name ha has s the same cha character racteristics istics as a fil file e name. The iden identifier tifier pi: pi: must precede precede the the pipe nam name e and no extension extension (xxx  (xxx ) is allowed. More than one program program can write write to a pipe, but only one reads data data from it. Because Because pipes are used thi this s way, two pipes must be used to communicate both ways between applications.

 

15-11

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

Pipes have have security restrict restrictions ions simila similarr to those used for files. files. The application application creating creating the pipe owns it, and the system system saves the user and group group ID of the creator creator.. The system creates creates and ope opens ns the pipe in read-write mode unless your application specifies otherwise. A pipe is temporary. temporary. When the last last applicat application ion that has access access to a pipe c closes loses tha thatt pipe, the pipe is deleted. delete d. If a program usin using g a pipe is terminated by the operating operating system system (not a norma normall application application termination), the termination), the operating operating system system automatic automatically ally closes closes the pipe. Refer to the IBM 4680 BASIC: Language  Reference  for   for more detailed information on pipes. A pipe may be created created with a zero-len zero-length gth buffer size size for use as a simple semaphore. semaphore. A READ operati operation on of a semaphore semaphore pipe obtains the semaphor semaphore e and a WRITE releases releases it. If another pr process ocess has obt obtained ained the pipe previously previously,, the READing proc process ess waits unti untill a WRITE to that pipe has been performed. performed. Write operations, on the other hand, never wait; even if the pipe was released previously, the call returns without an error. error. To create a semaphore semaphore pipe in a BASIC application application,, omit the BUFFSIZE parameter parameter and sp specify ecify BUFF as 0 in the CREATE statement.

Pipe Routing Services Pipe Routing Services is a facility of the IBM 4690 Operating System that enables applications to exchange data with applications in other store controllers or terminals by using pipes. To exchange data with other store controllers or terminals, you must use the pipes created through Pipe Routing Services. Identify these Identify these pipes pipes using using pipe pipe IDs. A pipe ID is a lette letterr between between A and Z. Make each each ID in a s store tore controller contr oller or or terminal terminal unique. unique. Each store store controll controller er or terminal terminal can have have up to 26 IDs IDs (A to Z). If you h have ave several applications running in a store controller at once, each must use a different pipe ID. One of three runtime libraries (one for the controller and two for the terminal) contain these functions, depending on whether you are requesting services for the store controller or the terminal. The large memory model controller library is ADXACRCL.L86. The medium memory model terminal library is ADXUCRTL.L86. The big memory model terminal library is ADXUCLTL.L86.

| | |

The system system has separate separate functions for the the terminals and and the store controllers controllers.. The functio function n names are as follows:

 

PRS xyyy

where: x  = x  = yyy  = =

T for functions used in the terminal C for functions used in the store controller CRT for the create pipe function WRT for the write function

= INT for the initialization function To prepare for receiving data through a Controller Pipe Routing Services pipe, call this function:

FUNCTION PRSxCRT (IONUM,SIZE%,PIPEID) EXTERNAL INTEGER INTE GER*2 *2 PRSxCR PRSxCRTT INTEGER*22 IONUM, INTEGER* IONUM,SIZ SIZE% E% STRING PIPEID END FUNC FUNCTI TION ON

       

15-12

4690 Store System: Programming Guide

 

 

where: IONUM 

An I/O session session number used used for normal normal opens and and creates. creates. Use the same nu number mber for wa waits its and reads that follow.

SIZE 

The number number of bytes to allocate allocate for the the pipe size. size. Maximum Maximum pipe size for p pipes ipes cre created ated by terminal applications terminal applications is 240 bytes. bytes. If you inadver inadvertently tently defin define e a size larger than the ma maximum ximum allowed, allowe d, the pipe size size is limited but no error error mes message sage appears. appears. The maxim maximum um pipe size fo forr pipes created by a controller application is 65,536 bytes.

PIPEID 

A character character between between A and Z. (Lower (Lowercase case is forced forced to uppercase uppercase be before fore it is use used d by this function.)

Table 15-4 show shows s the two-byte integers integers the PRSxCRT PRSxCRT functio function n returns returns.. Table Tab le 15-4. Functio Function n PRSxCR PRSxCRT T Two Two-Byt -Byte e Inte Integer gers  s  Integer

Description

0

Good completion

-1000

Invalid pipe ID

-1001

Pipe already exists

Note: Your calling program should have an ON ERROR routine to handle normal pipe creation runtime errors. Before reading data from a Pipe Routing Services pipe, your application should use the WAIT statement to obtain notification that there is data in the pipe. Note: If a terminal application issues a WAIT for a Pipe Routing Services pipe, you should be aware that the terminal terminal sends a message message to the controll controller er by way of the TCC TCC Network Network.. This mess message age tells th the e controller contro ller that the terminal terminal is waiting for data data to become available available in the pipe. If the WAIT ends because because the timeout interval specified on the WAIT is exhausted, the terminal sends another message to the controller contro ller by way of the TCC Network. Network. This message message tells the controller controller that the ter terminal minal is no longer waiting for data data in that pipe. Repeat Repeatedly edly issuing issuing WAITs for Pipe Routing Routing Services Services pipes with sho short rt timeout intervals in the terminal results in a large number of TCC Network messages being sent to the controller. This additional volume of TCC Network messages can have an adverse impact on the controller’s response respo nse time to terminal terminal requests requests.. Therefore, Therefore, short short timeout intervals intervals on the WAIT shou should ld be used only if absolutely absolu tely necessary. necessary. In no case should the tim timeout eout interval interval be less than 100 millis milliseconds econds,, as this much time is required to send the WAIT message to the controller and to receive a response back from the controller. contro ller. When the WAIT statement statement finishes finishes for the pipe, the applicatio application n should use the READ FOR FORM# M# statement stateme nt to read the data data from the pipe. pipe. The READ FOR FORM# M# statement statement should sp specify ecify the nu number mber of bytes to read according according to the type of message message written written to the Pipe Routing Serv Services ices pipe pipe.. You can use fixed-length or variable-length message types. For fixed-length message types, the number of bytes read from the pipe must be the same as the number of bytes written written to the pipe. Fixed-length Fixed-length messages messages require require that the application application wr writing iting to the pipe and the

application reading from the pipe always use the same number of bytes in their messages. For variable-length message types, the number of bytes read from the pipe must be less than or equal to the number of bytes written to the pipe. A variable-length variable-length message message consists consists of two parts. The first part is fixed-le fixed-length ngth and indicates indicates whether ther there e is a second part and the size size of the second part. The applic application ation writing writing the variab variable-len le-length gth messag message e writes both both parts of the message message together as one message. message. The application application reading reading the variable-len variable-length gth message messag e reads the first part part of the message by reading reading a fixed-le fixed-length ngth messa message. ge. From the first part part of the message the application determines the number of bytes to read for the second part.  

15-13

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

| |

The following conditions can result in errors being returned to a terminal application for a READ FORM# stat stateme ement nt.. Re Refer fer to the the IBM  IBM 4690 Store System: Messages Guide  for   for error information.

 If a READ FORM# specifies more bytes for a message than are actually in the Pipe Routing Services pipe, the system purges all of the data in the Pipe Routing Services pipe. the program issues a WAIT and is notified that data is in the Pipe Routing Services pipe, it is  Ifpossib possible le for the data to become unavailabl unavailable e before the pro program gram can issue issue the READ FORM#. This can occur if the program that wrote the data into the Pipe Routing Services pipe is ended before the READ FORM# is issued.

 If a program program attempts to read read a message message of more than 120 120 bytes, an er error ror is retu returned. rned. Pipe Routing Routing Services pipe messages can contain a maximum of 120 bytes. Sending data to other terminals or store controller Sending controllers s is a two-part two-part proces process. s. First, your app applicatio lication n must initialize initiali ze the writing service. service. Use the function function shown here to per perform form this initia initialization lization..

   

FUNCTION PRSxINT EXTERNAL INTEGER INTE GER*4 *4 PRSxIN PRSxINTT END FUNC FUNCTI TION ON

 

INTE INTEGE GER* R*44 PRSN PRSNUM UM

 

PRSNUM=PRSxINT

This function function returns returns a four-byte integer. integer. Your appl application ication must must save this integer integer for use when writin writing. g. You should call the initialization function only one time for each load of the application. If your controller application calls the PRSCINT function, and if your controller application uses the CHAIN statement to transfer control to another controller application, your application should call the PRSCCLS function before chaining:

   

FUNCTION PRSCCLS EXTERNAL INTEGER INTE GER*1 *1 PRSCCL PRSCCLSS END FUNC FUNCTI TION ON

 

CALL PRSC CALL PRSCCL CLSS

PRSCCLS releases the resource obtained by the PRSCINT function and makes it available to other programs. progr ams. If you omit this this call call to PR PRSCCLS, SCCLS, eventua eventually lly this this re resource source could be de depleted. pleted. PRSCCLS does not return a return code. After initializatio initialization, n, you can write to another another store con controller troller or terminal. terminal. Do this using the foll following owing function:

   

FUNCTION PRSxWRT (PRSNUM,DEST,BUFFER) EXTERNAL INTEGER INTE GER*4 *4 PRSxWR PRSxWRTT INTE INTEGE GER* R*44 PRSN PRSNUM UM

   

STRING DEST, BUFFER END FUNC FUNCTI TION ON

15-14

4690 Store System: Programming Guide

 

 

where: PRSNUM 

= Contains the value returned by the initialization function.

BUFFER 

|

= Contains the the data to be sent. sent. The maximum maximum length of data that that controller controller app applicatio lications ns may write to controller controller pipes pipes or terminal terminal pipes pipes is 120 bytes. bytes. The maxim maximum um length of da data ta that a

| |

terminall application termina application may write write to a terminal pipe pipe is also 120 b bytes. ytes. The maximu maximum m length of data that a terminal application may write to a controller pipe is 512 bytes.

|

DEST 

= Contains the the destination destination address. address. This is four charac characters ters of the form form aaaw . The aaa  indicates   indicates the termin terminal al or store controll controller er to which to send. send. For terminals, terminals, aaa  is   is the terminall number in ASCII. For store termina store controllers, controllers, itit consis consists ts of 0 0xy  xy  where x    where x  and   and y  are  are characters charac ters bet between ween C and Z. Thus, for for the store store controller, controller, aaa  can   can range from 0CC to 0ZZ. There are also two special values of aaa  for   for stor store e co cont ntro rolle llers rs:: 0AA 0AA an and d 0B 0BB. B. Us Use e 0AA 0AA when the destinatio destination n is the master store store controller controller.. Use 0BB when th the e destina destination tion is the controller contro ller to which the terminal terminal is attached. attached. You can think of these destinatio destinations ns as logical destinations. destina tions. The destination destination is associated associated with the machine machine performing performing the functi function on rather than the physical physical machine machine that is assigned the address. address. Where nec necessar essary, y, the operati operating ng system switches a destination to another machine when a configuration change occurs that affects the destinatio destinations. ns. For example, example, the system switches switches desti destinations nations wh when en one store controller takes over another controller another store cont controller roller’s ’s TCC Network. Pipe Routing Ser Services vices perform perform the translations of 0AA and 0BB so that your application does not have to actually know the real store controller addresses. The w  part   part of the destination address indicates which pipe to write to in the specified store controller contro ller or or ter terminal. minal. It is a pipe ID. It shou should ld be one of the pi pipe pe IDs used by by an applic application ation in the destination terminal or controller to create a Pipe Routing Services pipe. Note: If a terminal application is writing to a pipe created by another terminal, both terminals termina ls must be located located on the same same controller. controller. A terminal ap applicati plication on canno cannott write a message across the LAN to a terminal located on a different controller.

| | |

Table 15-5 show shows s the 4-byte integers integers that are returned returned by the PRSx PRSxWRT WRT functi function. on. Table Tab le 15-5. Function Function PRS PRSxWR xWRT T Four-B Four-Byte yte Int Intege egers  rs 

|

Integer 0

Description Good completion.

-1

Destination pipe is full or does not have enough space available to hold the data being written.

-1010

Invalid destination specified.

-1011

Destination not found.

-1012

Error on write to destination.

-1013

Data length greater than the maximum allowed length.

Additionally, you may choose Additionally, choose to use the conditional conditional pipe wri write. te. This write is identical identical in every wa way y to the | normal PRSxWRT PRSxWRT pipe write write with one additional additional function function.. If the destination destination pipe is full or does not have | enough room left to contain the entire message being written, the write will not wait for room to become available. availab le. Instead, Instead, the applicat application ion is given given control control immediat immediately ely with a -1 rreturn eturn c code. ode. At this point, point, the the |

application can make a decision to either discard the data being written or to retry the write at a later time. The intended use for the conditional pipe write is for situations where it is undesirable for an application to wait for extended extended periods periods of time. To use the condit conditional ional pipe write, write, use the followin following g function:

 

15-15

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

| | | | |

       

FUNCTION PRSxWRC (PRSNUM,DEST,BUFFER) EXTERNAL INTEGER INTE GER*4 *4 PRSxWR PRSxWRCC INTE INTEGE GER* R*44 PRSN PRSNUM UM STRING DEST, BUFFER END FUNC FUNCTI TION ON

where: |

PRSNUM  BUFFER 

| | |

DEST 

= Contains the value returned by the initialization function. = Contains Contains the data to be sen sent. t. The maximu maximum m length of data that that controller controller appl application ications s may write to controlle controllerr pipes or terminal terminal pipes pipes is 120 bytes. bytes. The maximum maximum length of data that that a terminall application termina application may write write to a terminal terminal pipe is also 120 120 bytes. The maxim maximum um length of data that a terminal application may write to a controller pipe is 512 bytes. = Contains Contains the destin destination ation address. address. This is four charact characters ers of the for form m aaaw . The aaa  indicates   indicates the the termina terminall or store co controlle ntrollerr to which to send. send. For terminals, terminals, aaa  is   is the terminal number in ASCII. For store terminal store cont controller rollers, s, it cons consists ists of 0xy  0xy  where x    where x  and   and y  are  are characters chara cters between between C and and Z. Thus, for the store store controller, controller, aaa  can   can range from 0CC to 0ZZ. There are also two special values of aaa  for   for sto store re c con ontr troll oller ers: s: 0AA 0AA an and d 0BB. 0BB. Us Use e 0AA 0AA when the destinatio destination n is the master s store tore controller controller.. Use 0BB whe when n the destination destination is the controller contro ller to which the terminal terminal is attached. attached. You can think of thes these e destinations destinations as logical logical destinations. destin ations. The destin destination ation is associated associated with the machine machine perfo performing rming the function function rathe ratherr than the physical physical machine machine that is assigned the address address.. Where ne necessar cessary, y, the operatin operating g system switches a destination to another machine when a configuration change occurs that affects the destinatio destinations. ns. For example, example, the system switches switches destinations destinations when when one store controller contro ller takes over another another store controller controller’s ’s TCC Network. Pipe Routing Ser Services vices perform perform the translations of 0AA and 0BB so that your application does not have to actually know the real store controller IDs.

| | | | | | | | | | | | |

The w  part   part of the destination address indicates which pipe to write to in the specified store controller contro ller or terminal. terminal. It is a pipe ID. It sho should uld be one of of the pipe IDs IDs used used by an ap applicati plication on in the destination terminal or controller to create a Pipe Routing Services pipe.

| | |

Note: If a terminal application is writing to a pipe created by another terminal, both terminals must be located terminals located on the same same contro controller. ller. A termina terminall application application cannot cannot write a message across the LAN to a terminal located on a different controller.

| | |

Table Tab le 15-6. PRSCW PRSCWRC RC Functi Function on Four-By Four-Byte te Inte Integer gers  s  Integer

Description

0

Good completion.

-1

The destination pipe is full or does not have enough space available to hold the data being written.

-1010

Invalid destination specified.

-1011

Destination not found.

|

-1012

Error on write to destination.

-1013

Data length greater than the maximum allowed length.

15-16

4690 Store System: Programming Guide

 

 

Using Application Services Application Services is a group of operating system services that are available to store controller and terminall applications termina applications for performing performing various various tasks. tasks. Some of these ser services vices can be used used by both store controller and terminal applications.

Store Controller and Terminal Application Services This section section lists routines routines that are available available to applications applications at the store store controll controller er and the termin terminal. al. The function code and parameters for each function are listed, along with an explanation of the function. Both sto store re cont contro rollller er and and term termina inall ADXSERVE ADXSER VE (Re (Requestin questing g an Ap Applica plication tion Se Service): rvice): Both applications use a routine called ADXSERVE to request Application Services. |

ADXSERVE is located in the following libraries: ADXACRCL.L86 for store controller applications ADXUCLTL.L86 for big memory model terminal applications ADXUCRTL.L86 for medium memory model terminal applications

| | |

The routine must be declared as follows:

SUB ADXSERVE (RET,FUNC,PARM1,PARM2) EXTERNAL INTEGE INTE GER* R*44 RET RET INTEGER*2 INTEGER *2 FUNC,P FUNC,PARM ARM11 S TRING ST PARM2 END SUB EN

       

Invoke the routine using this request:

 

CALL ADXSERVE(R ADXSERVE(RET,FU ET,FUNC,PAR NC,PARM1,PAR M1,PARM2) M2)

where: RET 

= Is the return return code. It is zero if the operation operation was was succe successful, ssful, or ne negative gative if the o operatio peration n

FUNC  PARM1 PARM2 

failed. Return code values are listed below. = Specifies which ADXSERVE service is to be called. = Varies accordin according g to the function. function. See the follo following wing function function desc description riptions. s. = Varies according to the function that is called.

Note: If your controller application calls ADXSERVE, it should also call ADXSERCL (see “ADXSERCL (Closing an Application Service)” on page 15-39) prior to chaining to another application in order to free system resources.

 

15-17

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

Table Tab le 15-7 15-7.. ADXSERVE ADXSERVE Ret Return urn Codes  Codes  Return Code

Description

-1000

Invalid function code.

-1001

Buffer or length invalid. (Returned when FUNC=25, 26, or 27)

-1002

Invalid terminal number supplied.

-1003

System unable to obtain a flag.

-1015

Cannot s se end p po ower-OFF me message to to rre emote co controller b be ecause o off no non-LAN s sy ystem. (Returned when FUNC=5)

-1016

Machine to be powered-OFF is not 4690 family or control roller/ter terminal environment. (Returned when FUNC=5)

-1017

Invalid date/time specified in ADXSERVE call. (Returned when FUNC=5)

-1018

Invalid contr tro oller ID specified in AD ADXS XSE ERVE call or not activ tive controller. (Returned when FUNC=5)

-1019

Request is issued o on n LAN sy system co controller tth hat is is n no ot th the m ma aster s sttore c co ontroller.

-1020

ABIOS driver open failed. (Returned when FUNC=5)

-1021

ABIOS IOS drive verr call fa faiiled eith the er beca cau use of a system tem problem or invalid time. (Returned when FUNC=5)

-1022

User logical name not defined/unknown request.

-1023

Programmable P Po ower re request is is p pe ending. Either P Prrogrammable P Po ower ha has be been d diisabled o orr an an application appli cation has set the 'No-IPL' 'No-IPL' flag in a MOD1 or MOD2. MOD2. (Return (Returned ed when FUNC= FUNC=5)* 5)*

-1080

Command bl blocked by by s sy ystem co control fu function fr from th the sc screen a an nd ke keyboard. (Returned w wh hen FUNC=2 or 3)

-1081

Terminal failed to respond.

-1100

Requestor not an interactive application. (Returned when FUNC=25 or 27)

-1101

Requestor not a background application.

-1212

Programmable power command issued for non-469x  family   family or controller/terminal.

Note: You receive an incorrect FUNC message if a store controller-only function is called in the terminal application. * When programmable power is subsequently enabled, the pending power-OFF command will be issued if the power-ON time has not passed, or if the power-ON time is 999.

Dump System Dump System Stor Storage age:: The Dump System Storage function causes all of the storage in the machine at which the request request is made to be dumped to a disk file. Both the application application and ope operating rating sy system stem stora storage ge are dumped.

The Dump System Storage function uses the following parameters:

FUNC   = 1 PARM1 = Unused; the value is ignored. PARM2  = Unused; the value is ignored. Enable Termin Terminal al Storage Storage Retention: Retention: This function function ena enables bles storage storage rretentio etention n on termi terminals. nals. If this function is called in a non multiple-controller LAN (MCF Network), all the terminals on that TCC Network are enabled. enabled. If this function function is called called in a terminal, terminal, only that ter terminal’s minal’s storag storage e rete retention ntion is enabled. enabled. If this function is called only from the acting master store controller in a multiple-controller LAN (MCF Network), all terminals on that network are enabled.

15-18

4690 Store System: Programming Guide

 

 

If the function is called called in the terminal, the effect effect is temporary. temporary. The condi condition tion establ established ished in the controller controller overrides overr ides the temporary temporary terminal condition. condition. Whene Whenever ver the terminal terminals s receive updat updates es from the controlle controller, r, terminal online updates occur when terminal-to-controller communications are interrupted or when system functions are used that require sending new status to a terminal. The Enable Terminal Storage Retention function uses the following parameters: FUNC   = 2 PARM1 = Unused; the value is ignored. PARM2  = Unused; the value is ignored. Disable Terminal Terminal St Storage orage Retention: Retention: This function function dis disables ables storage storage rretentio etention n on termi terminals. nals. If this function is called in a non multiple-controller LAN (MCF Network), all the terminals on that TCC Network are disabled. disabled. If this function function is called called in a terminal, terminal, only that terminal’s terminal’s storag storage e rete retention ntion is disabled. disabled. If this function is called from only the acting master store controller in a multiple-controller LAN (MCF Network), all terminals on that network are disabled.

If the function is called called in the terminal, the effect effect is temporary. temporary. See “Enab “Enable le Terminal Terminal Storage Retention” Retention” on page page 15-1 15-18. 8. The Disable Terminal Storage Retention function uses the following parameters: FUNC   = 3 PARM1 = Unused; the value is ignored. PARM2  = Unused; the value is ignored. Get Applicat Application ion Status Status Inform Information: ation: This function gathers status information and places it in the string variable variab le you you specify specify wi with th PARM2. PARM2. The informati information on returns returns in ASCI ASCIII data format. Use th the e MID$ stateme statement nt to extract selected selected fields fields from PARM2. MID$ references references the offset offset in the PARM2 string from from the left which ensures that your program works properly if PARM2 size is extended.

The Get Application Status Information function uses the following parameters: FUNC   = 4 PARM1 = Unused; the value is ignored. PARM2  = Specify a string variable. Table 15-8 show shows s the data for the store controller controller ap applicati plication on status. Table 15-8 (Page 1 of 2). Store Store Controller Controller Applic Application ation Status 

| | |

Offset

Length

Description

0

4

Store number

4

1

 Date format: 1 = m/d/y 2 = d/m/y

3 = m.d.y 4 = d.m.y

| | |

5

1

Time format: 1 = h:m:s 2 = h.m.s

| | |

6

1

Monetary format: 1 = period convention (1,234,970.06) 2 = comma convention (1.234.970,06) 3 = French convention (1 234 970 06)

| | |

 

15-19

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

Table 15-8 (Page 2 of 2). Store Store Controller Controller Appli Application cation Status 

|

Offset

Length

Description

7

1

Display type

|

0 = unknown display (for example CMOS information is invalid)

| |

1 = monochrome display 2 = color display

|

8

3

Number of terminals configured (001 through 999)

11

4

Store controller ID 00CC through 00ZZ for this store controller

15

2

Reserved

17

2

Controller ID for the master is 00 if not found; otherwise CC through ZZ.

19

3

Printer lines per page 001 through 999

22

1

Number of digits after decimal point 0 or 2

23

1

This controller on an active LAN System = 1; else = 0.

24

2

Acting ID is a 2-byte ASCII field:

     

Controller is on LAN = 1 Master = 16 Alternate master = 8 File server = 4 Alternate file server = 2 Or a combination of these (add the values) (for example, alternate master and alternate file server = 11;  Master and file server = 21  Controller is not on LAN = 00

|

26

1

Printer associated with console (1 through 8)

27

1

Assigned console (0 through 8)

28

1

LAN Type: 0 = LAN not installed 1 = Token Ring 2 = Ethernet

| | | |

29

51

Reserved

Table 15-9 sho shows ws the data for the the terminal terminal applica application tion status. status. Table 15-9 15-9 (Pag (Page e 1 of 3). Ter Terminal minal Appli Application cation Status  Offset

Length

Description

0

4

Store number

4

1

Date format: 1 = m/d/y

2 = d/m/y 3 = m/d/y 4 = d/m/y 5

1

Time format: 1 = h:m:s 2 = h:m:s

6

1

Monetary format: 1 = period convention (1,234,970.06) 2 = comma convention (1.234.970,06)

15-20

4690 Store System: Programming Guide

 

 

Table 15-9 15-9 (Pag (Page e 2 of 3). Term Terminal inal Applic Application ation Status  Offset

Length

Description

7

3

Terminal number (001 through 999)

10

1

Terminal online/offline 0 = offline 1 = online

11

1

Storage Retention 0 = disabled 1 = enabled

12

24

Default Application Name

 device name - 8 character character m maximu aximum m (:)  file file nam name e - 8 chara character cter maxi maximum mum (.)  file extension - 3 character maximum 36

1

Number of digits after decimal point 0 or 2

37

1

Terminal powered ON/OFF 0 = on

39

1

1 = off - Always on for Mod1; may be on or off for Mod2. Backup (loop) 1 = Loop in backup 0 = Not in backup

40

1

System Display 1 2 3 4 5

41

= = = = =

Display Display Display Display Display

named named named named named

ANDISPLAY is the system display ANDISPLAY2 is the system display VDISPLAY is the system display VDISPLAY2 is the system display ANDISPLAY3 is the system display

0 = Mod1 1 = Mod2

42

3

Partner terminal address

45 47

2 1

Current store controller ID Video Display Adapter 0 = 4683 Video display feature A 1 = VGA

48

1

Application Environment 0 = Running in a terminal 1 = Running in a controller/terminal

49

2

Hard Totals NVRAM Size 01 = 1 KB Hard Totals (4683)

16 = 16 KB Hard Totals (4693/4694)

|

51

|

1

Terminal Type

|

 

1 (4 (469 693) 3)

| | |

     

2 (4 (469 694) 4) 3 (4 (468 683) 3) 4 (4 (468 684) 4)

52

|

1

Supporting Operating System 1 (4690 OS) 2 (4690 Terminal Services for DOS)

| |

 

15-21

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

Table 15-9 15-9 (Pag (Page e 3 of 3). Ter Terminal minal Appli Application cation Status 

|

Offset

Length

Description

53

27

Reserved

Progra Pro gramma mmable ble Power Power:: Programmable power allows terminal or controller applications to issue program calls to enable or disable the programmable power feature, and to issue program calls to power OFF a terminal or controller.

When the application calls the power-OFF function, it will specify the day and time that the power is to be turned back on. on. The time must be specified specified in the the inter internationa nationall format. format. A 0000 o orr 2400 will be accept accepted ed as midnight. midnight. The day of month month is also specified specified and must must meet either of of the followin following g criteria: criteria:

 If the day and time are prior to the current day and time, the day must be valid for the next calendar month.  If the day and time are after the current day and time, the day must fall within the current month. Note: Using 999 for the time will indicate that a power down is to be done without enabling a power-ON time. The maximum time that a controller or terminal be programmed to wait before powering-ON is one month plus or minus a few minutes due to clockcan variances.

| |

Power OFF a Rem Power Remote ote Contr Controlle oller: r: This function is used to power OFF a remote LAN (MCF Network) controller. contr oller. This functio function n can be invoked on a controller from any supported supported family (personal (personal comp computer, uter, 4684, or 469x). 469x). The controller controller on which this this function is invoked invoked must be the master master controll controller er in a LAN system.. The remote controlle system controllerr being powered-OFF powered-OFF must must be in the 469x family to have the programmab programmable le power feature. feature. The day, hours, hours, and minutes minutes in the PARM2 PARM2 string ar are e the power power-ON -ON time. This function uses the following parameters: FUNC   = 5 PARM1   = 1 PARM1 PARM2   = DDHHMMCC  DD = is the day of month (01 - 31) HH = The hours (00 - 24) MM = The minutes (00 - 59) CC = The controller ID (CC through ZZ)

|

Power OF Power OFF F a Remote Remote Termin Terminal: al: This function function is u used sed to po power wer OFF a rremote emote ter terminal. minal. The term terminal inal can be store loop attached attached or token token ring attached. attached. This function function can be invoked invoked on a controller from from any supported suppo rted family (personal (personal computer, computer, 4684, or 469x). 469x). The controller controller on which this functio function n is invoked must be the master controller if on a LAN (MCF Network) system, or from the stand-alone controller running runni ng either the store store loop or token ring for terminals terminals.. The remote terminal terminal being po poweredwered-OFF OFF must be in the 469x family to have the program programmable mable power feature. feature. The day, hours, hours, and minutes in the PARM PARM2 2

string are the power-ON time.

15-22

4690 Store System: Programming Guide

 

 

This function uses the following parameters: FUNC   = 5 PARM1  = 2 PARM1  PARM2   = DDH DDHHMM HMMTT TTT T DD = The The day day o off mon month th (0 (01 1 - 31) 31) HH = The The ho hour urs s (00 (00 - 2 24) 4) MM = The The minut minutes es (0 (00 0 - 59) 59) TTT = The term termina inall num number ber (001 (001 - 999) 999) Disable Controller Controller Pr Programm ogrammable able Power: Power: This function is used to disable programmable power on the local controller controller.. This function function must be invoke invoked d on the controller controller on which prog programmab rammable le power is to be disabled. disable d. The controller controller on which which this function function is invoked invoked must be in the the 469 469x  x  family   family to have the programmable power feature. This function uses the following variables: FUNC   = 5 PARM1   = 3 PARM1 PARM2  = Unused; the value is ignored. Enable Contro Controller ller P Progra rogrammable mmable Power: This function is used to enable programmable power on the local controller controller.. This function function must be invoke invoked d on the controller controller on which prog programmab rammable le power is to be enabled. enable d. The controller controller on which which this function function is invo invoked ked must be in the 4 469x 69x family to have have the programmable power feature. This function uses the following parameters: FUNC   = 5 PARM1   = 4 PARM1 PARM2  = Unused; the value is ignored. Power OFF a Local Local Machine Machine (Controller (Controller or Te Terminal) rminal):: This function is used to power OFF a local machine. The machine machine. machine may be a controller or terminal, terminal, prov provided ided that the controller controller or ter terminal minal is in the 469x family. family. This function function should should be invoked invoked on the machine machine th that at is to be powe powered-O red-OFF. FF. The day, day, hour hours, s, and minutes in the PARM2 string are the power-ON time. This function uses the following parameters: FUNC   = 5 PARM1   = 5 PARM1 PARM2   = DDHH DDHHMM MM  DD = The The da day y of mont month h (0 (01 1-3 31) 1)  HH = The The h hou ours rs (0 (00 0-2 24) 4)  MM = The minutes minutes (00 (00 - 59) 59)

Display Application Application S Status tatus Message Message:: Interactive applications use this function to display status on the SYSTEM WINDOW WINDOW CONTROL Screen. Screen. Applications Applications started started in Command Mode cannot cannot use this func function. tion.

This function function displays displays the specified specified text on the WINDOW CONTROL CONTROL screen screen.. It puts the messag message e in the description field of the window for the application using this function. The message message is available available any time you you swap to the WINDOW WINDOW CONTROL CONTROL screen. screen. It is displa displayed yed until the application applica tion ends. This message message function provides provides one one place where you you can look to see the status of all active applications.

 

15-23

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

This function uses the following parameters: FUNC   = 25 PARM1 = Unused; the value is ignored. PARM2  = Specify a string containing containing the message. message. This sho should uld not be modified modified.. Display Backgro Background und Applic Application ation Status Status Message: Message: The following function gives status for background applications applic ations only. only. Applications Applications started started in Command Mod Mode e cannot use this function. function.

This function function displays displays the specified text text on the BACKGROUND APPL APPLICATION ICATION CONTROL CONTROL screen. screen. It puts the message message in the message field of the requestin requesting g background background application. application. The message message is available any time you swap swap to the BACKGROUND BACKGROUND APPLICATION APPLICATION CONTROL CONTROL screen. screen. It is displayed displayed until the application applic ation ends. ends. This message message function function provide provides s one place where you you can look to see the status of all active background applications. This function uses the following parameters: FUNC   = 26 PARM1 = Unused; the value is ignored. PARM2  = Specify a string containing the message; this should not be modified. Stop Applica Application tion with Message: Message: Interactive applications use this function to display status on the SYSTEM WINDOW WINDOW CONTROL screen. screen. Applications Applications started started in Command Mode cannot cannot use this func function. tion. The primary purpose of this function is to handle initialization problems preventing the application from operating. opera ting. It should not not be used once once the application application has displaye displayed d its first scr screen. een.

After this function function stops the applicatio application, n, it displays the message message text that you have have specifi specified. ed. It displays this text on the message line of the system screen used to start the requesting application. This function uses the following parameters: FUNC   = 27 PARM1 = Unused; the value is ignored. PARM2  = Use to pass a string containing the message; this should not be modified. The message is displayed only if this function is requested by the current owner of the physical screen. Get Disk Free Free Space Space:: This function returns the amount of free space on the specified remote or local drive.

This function uses the following parameters: FUNC   = 28 PARM1 = Unused; the value is ignored. PARM2  = Specify a node name (if non-local) and the drive or a logical name for the node or drive. Get Configure Configured d Controllers Controllers o on n the Network: Network: This function returns the IDs of all the store controllers on

the netw network ork.. Each Each ID is is two byt bytes es lo long. ng. Sto Store re c cont ontrol roller ler IDs IDs rang range e fro from m CC tthro hrough ugh ZZ. A store store controller ID of 00 indicates the end of the list. This function uses the following parameters: FUNC   = 29 PARM1 = Unused; the value is ignored. PARM2  = Specify a string variable.

15-24

4690 Store System: Programming Guide

 

 

Get the Contro Controller ller ID fo forr a Specified Specified Terminal: Terminal: This function returns the store controller ID for a terminal you specify.

The data returned is a negative return code, a numeric value for the store controller ID representing the ASCII values CC through ZZ or X '0' if the terminal was not defined. Note: This function returns a controller ID CC through ZZ only if the function was issued at the master store controller or if the terminal is local to the controller issuing the function. This function uses the following parameters: RET  = FUNC   = PARM1 = PARM2   =

Always modified. 30 Number of the termina terminall for which which the ID is rrequest equested. ed. Unused.

Convert ASCII Char Convert Character acters s to EBCDIC Cha Characte racters: rs: This function converts ASCII characters in a string to EBCDIC characters.

This function uses the following parameters: FUNC   = 31 PARM1 = Unused; the value is ignored. PARM2  = Specify a string of ASCII characters to be converted to EBCDIC; this string is modified to EBCDIC characters. Convert EBCDIC Cha Convert Characte racters rs to ASCII Cha Characte racters: rs: This function converts EBCDIC characters in a string to ASCII characters.

This function uses the following parameters: FUNC   = 32 PARM1 = Unused; the value is ignored. PARM2  = Specify a string of EBCDIC characters to be converted to ASCII; this string is modified to ASCII characters. Terminal Termin al Dump Preser Preservation: vation: This function prevents terminal dumps from being written to the terminal dump file until until the dump currently currently in the the file can be co copied pied to a diskette. diskette. This function function is enab enabled led by creating a user logical name ADXTDUMP.

The terminal terminal dump preservation preservation function function automatical automatically ly sets a flag whenever whenever a terminal dump oc occurs. curs. The preservation flag is reset after the dump is successfully copied to a diskette using the Create Problem Analysis Analys is Diskette funct function. ion. The preservation preservation flag is also reset when the Create Create Problem Analys Analysis is Diskette encounters an incomplete terminal dump and the user chooses to bypass copying the terminal dump to a diskette. diskett e. While the flag is set, terminal terminal dump req requests uests will be rejected rejected so that the dump currently currently in the terminal dump file will not be overwritten.

This function uses the following parameters: FUNC   = 33 PARM1 = Specify one of the following: 0 To tu turn rn off off the tterm erminal inal dump dump pres preserv ervatio ation n fla flag g 1 To tu turn rn on the the termin terminal al dump dump prese preserva rvation tion flag 2 To que query ry whether whether the terminal terminal d dump ump preserva preservation tion fflag lag is ON or OFF PARM2  = Unused; the value is ignored.

 

15-25

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

Get Loop Loop Mess Message age:: This function gets the three most recent system messages for the store loop or token-ring tokenring adapter adapter specified specified in PARM2. PARM2 is a string consisting consisting of node node (for example example,, CD), TCC Network (1 or 2), and three TCC Network messages.

The node and the TCC Network must be the first three characters of the string when the ADXSERVE function functio n is called. When the ADXSERVE ADXSERVE function function returns, returns, the three most recent recent messages messages will follow the node and TCC TCC Network in the the string. string. If no messages messages exist for the the specified specified node and T TCC CC Networ Network, k, blanks will be returned returned for the messages messages.. The oldest oldest m message essage will be be put in the buffer first. Each message is 133 characters long. This function uses the following parameters: FUNC   = 34 PARM1 = Unused; the value is ignored. PARM2  = Specify a string containing node and TCC Network. Get Lo Get Loop op Stat Status us:: This function returns the configuration and current status of the two loop adapters. Data is returned in RET in the form WWXXYYZZ  (hex)   (hex) where:

ZZ  = The 1st adapter configuration YY  XX  = = The The 1st 2ndadapter adapterstatus configuration WW  =   = The 2nd adapter status The configuration is defined as: 00 01  01  02  02  04 80

= = = = =

Not used Pr Prim imar ary y Seco Second ndar ary y 2400 bps loop Auto-resume of Primary Loop Control

The status is defined as: Stan andb dby y 03  03  = St Controllin lling g 04  04  = Contro 05  05  = Prev Preven ented ted This function uses the following parameters: FUNC   = 35 PARM1 = Unused; the value is ignored. PARM2  = Unused; the value is ignored. Get All Active Active Controlle Controllers rs on the the Network: Network: This function returns the IDs of all the active store controllers contr ollers on the network network.. Each ID is two b bytes ytes long. long. A store controller controller ID of 00 in indicates dicates the end of the

list. This function uses the following parameters: FUNC   = 36 PARM1 = Unused; the value is ignored. PARM2  = Specify a string variable. Get Controller Controller ID and and Loop ID for a Specified Specified Te Termina rminal: l: The data returned in RET is two bytes for the Loop ID followed by the two bytes bytes for tthe he cont controller roller ID. A X'01' is returned if the terminal number cannot be found.

15-26

4690 Store System: Programming Guide

 

 

Note: The RET is valid only if this function is issued at the master store controller. This function uses the following parameters: FUNC   = 37 PARM1 = Terminal number. PARM2  = Unused; a string variable. Get the Contro Controller ller Mach Machine ine Model Model and Type: Type: This function retrieves the machine model and type and places the 3-byte 3-byte hexadecimal hexadecimal values values to the left in the RET parameter. parameter. The 3-byte 3-byte hexadec hexadecimal imal values will be returned returned in PARM2 PARM2 if PARM2 is specified. specified. Use the MID$ statement statement to ex extract tract the individu individual al bytes from PARM2. PARM2. The MID$ statement statement referenc references, es, from the left, left, the offset in the the PARM2 stri string. ng.

This function uses the following parameters: RET 

= INTEGER* INTEGER*4 4 with the 3 most-signific most-significant ant bytes containi containing ng the machine machine model and ty type. pe. The least-signifi leastsignificant cant byte is a always lways zer zero. o. Identical Identical to the contents contents of PARM2. FUNC   = 38 PARM1 = Unused, the value is ignored. PARM2  = 3 hexadecimal hexadecimal values left-justifie left-justified d machine mode modell and type. For example, example, for a 4693-54 4693-541, 1, the values returned are:   X'F8 '   X'3E'   X'00'.

|

Check the the Master Master or File Server Server Except Exception ion Log: This function returns whether or not there are any entries in the exception log.

|

This function uses the following parameters:

|

RET 

|

| | | |

= One of the following values: 0 = No entries in the exception log 1 = Entries exist in the exception log 8xxxxxxx = Error code indicating why the status of the exception log cannot be obtained. FUNC   = 39

| |

PARM1 Specify one of the following values: 1 = Check the Master exception log | 2 = Check the File Server exception log Unus used ed | PARM2   = Un

Set Terminal Terminal Sle Sleep ep Mode Inactive Inactive Timeou Timeout: t: This function allows an application running in a store controller contro ller to set the Terminal Terminal Sleep Mode Inactive Inactive Timeout. Timeout. When you enable enable Termin Terminal al Storage Retention, you set this value to determine how many minutes a terminal will remain idle before being powered-down.

function is supported supported only on the store controlle controller. r. In order for the slee sleep p mode inactive tim timeout eout Note: This function to take effect, you must must invoke this function function befor before e enabling the Ter Terminal minal Storage Storage Retention. Retention. You may also specify the terminal sleep mode inactive timeout by selecting the Enable Terminal Storage Retention option on the TERMINAL TERMINAL FUNCTIONS FUNCTIONS screen. screen. The default default for the terminal sleep sleep mode inactive inactive timeout is 30 minutes. This function uses the following parameters: FUNC   = 41 PARM1 = Te Term rmina inall Sl Slee eep p Mo Mode de Time Timeou outt va valu lue. e. Va Valid lid va valu lues es are are 0 thro throug ugh h 255. 255. Yo You u can can us use ea0 value to disable the terminal sleep mode.

 

15-27

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

PARM2  = Unused; a string variable. Enable/Dis Enable /Disable able IPL: Termin Terminals als are able able to run offline from from the contr controller. oller. The prim primary ary reason reason to run offline is if there is a problem with the controller.

In many cases, cases, maintenance maintenance is applied to the controller controller to cor correct rect the problem. problem. One of the modules tha thatt may be applied applied to the controller controller as maintenance maintenance is the terminal operating operating system system (ADXRT (ADXRT1SL.28 1SL.286). 6). The controller contr oller and terminal terminal interact to ensure the terminal terminal is running the latest termi terminal nal operating operating system. The latest is the terminal terminal operating operating system system file currently currently being used on the con controller troller.. The contro controller ller is IPLed to apply maintenance maintenance.. If the terminal is not run running ning the same leve levell of the operating sy system stem that exist exists s in ADX_SPGM on the controller, the terminal is IPLed to load the latest terminal operating system. When the terminals run offline, the application can write the transaction data to the terminal RAM disk. This allows allows the terminals to run offline offline while a contr controller oller problem problem is being addressed. addressed. The termin terminals als eventually communicate with the controller and transfer all saved transactions in terminal RAM disk to normall transact norma transaction ion files in the controller. controller. If the terminal is IPLed prior prior to the complet completion ion of the saved transaction movement to the controller, the saved transactions are lost. Enable/Disable IPL allows an application program that is processing in a terminal to temporarily prevent automa automatic reloading reload of the terminal. terminal. requests Automat Automatic ic terminal reload reload can occur occuFunction r when the termin terminal al is offline and returns tic online or ing when an operator the Load Terminal Storage with an “*” specified as the terminal terminal number. Automatic Automatic terminal reloads reloads can also also occur when ADXCS20L ADXCS20L is invok invoked ed with the Load All Terminals function code. Application programs should use the Disable IPL function when the terminal application recognizes that it is offline and begins begins to save data on the RAM disk. When the termi terminal nal applic application ation reco recognizes gnizes it is onlin online e with the controller, controller, the saved saved data can be transferre transferred d to the controller. controller. After all data has be been en transfe transferred rred to the controller, the terminal application can use the Enable IPL function to allow any possible IPL. The requests to enable and disable the IPL of the terminal for the Mod1 and the Mod2 are handled independently indepe ndently.. If a Disable Terminal Terminal IPL was outstan outstanding ding on both terminals terminals and one term terminal’s inal’s app application lication issued an “Enable “Enable Terminal Terminal IPL” request, request, an IPL is not possible possible for the Mod1 and the Mod2 pair pair.. Both terminals must have the IPL enabled before an IPL can occur.

|

Load Spe Load Specif cific ic Ter Termin minal: al: This function allows an application running in a store controller to load a specific terminal.

|

This function uses the following parameters:

|

FUNC   = 42 PARM1 = Terminal Number PARM2  = Unused; a string variable

|

| |

Using the Enable IPL Functio Function: n: This function function en enables ables the the terminals terminals to IPL. If terminals terminals were IPLed

earlier, but could not because the user had disabled the IPL, requesting this function would cause the terminals to IPL. To enable terminal IPL, use the following parameters: FUNC   = 53 PARM1 = Unused; the value is ignored. PARM2  = Unused; the value is ignored. This function function is also used to enable enable programmable programmable powe power. r. It allows the terminal terminal to accept power-OFF power-OFF commands. If a previous power-OF commands. power-OFF F command had been been issued while programm programmable able power ha had d been

15-28

4690 Store System: Programming Guide

 

 

disabled, and the power-ON time had not yet passed, this function would cause the terminal to power down. Using the the Disa Disable ble Ter Terminal minal IPL IPL Function: Function: This function prevents the automatic reload which may occur when a terminal terminal comes online. online. This function function allows the ter terminal minal application application to effec effectively tively use the ter terminal minal

RAM disk support support for temporarily temporarily logging logging data. In most cases, whe when n the control controller ler retur returns ns online, the terminal application transfers the saved transaction files to the controller. To disable terminal IPL, use the following parameters: FUNC   = 54 PARM1 = Unused; the value is ignored. PARM2  = Unused; the value is ignored. This function function is also used to disable disable progra programmable mmable power. power. It allows the terminal terminal application application to block or delay a power down command.

ADXERROR ADXERR OR ((Appli Application cation Event Loggin Logging): g): Yo Your ur appl applic icat atio ion n can can use use a rout routin ine e call called ed ADXERROR to make entries in the system ADXERROR system log and optiona optionally lly display sy system stem messa messages. ges. The routin routine e should be declared as follows:

       

FUNCTION ADXERROR (TERM,MSGGRP,MSGNUM,SEVERITY,EVENT,UNIQUE) (TERM,MSGGRP,MSGNUM,SEVERITY,EVENT,UNIQUE) EXTERNAL INTEGER*2 INTEGER *2 TERM,MSGNU TERM,MSGNUM,ADXE M,ADXERROR RROR INTEGER*1 INTEGER *1 SEVERITY,M SEVERITY,MSGGRP, SGGRP,EVENT EVENT STRING UNIQUE END FUNC FUNCTI TION ON

Invoke the routine using this request:

 

i%=ADXERROR(....)

The function always returns zero and uses the following parameters: TERM 

The parameter parameter is the terminal terminal nu number. mber. This information information comes comes from the G GET ET APPLICA APPLICATION TION STATUS INFORMATION INFORMATION application application service service request request in the termina terminal. l. If the application application calling this routine resides in the store controller, the TERM parameter should be zero.

MSGGRP 

The (message group) parameter is a one-byte integer that contains the ASCII equivalent of the message message group character. character. The messag message e group is unique unique for each product product and should be in the range of J to S.

MSGNUM 

The message message number, number, if any. The message message number number should be zero zero if no message message is to be displayed. display ed. The system takes takes this number and and converts converts it to three printab printable le decimal digits, digits, which it appends appends to the message message gro group up to form the me message ssage ide identifier ntifier.. The message message identifier identifi er is used to scan the Application Application Message Message file. Your appl application ication must must provide this file for the system message display.

SEVERITY  A number ranging ranging from from 1 to 5 that is used to indicate indicate the importanc importance e of each mess message. age. The system uses uses the field as a message message level level indicator. indicator. The most imp important ortant messages messages h have ave a 1 in this field. field. The operator operator can request request a message message level level from 1 to 5, and only m message essages s whose severity number is less than or equal to the current message level appears. EVENT 

A one-byte integer integer whose whose value is completely completely determined determined by the applic application. ation. It can be used to indicate why the request is being made. For store controller application events 64 to 79, decimal, and terminal application events 64 to 81, decimal, the system uses the log data to generate Network Problem Determination Alert (NPDA) (NPDA) messages. messages. For a desc description ription of NP NPDA DA suppor support, t, refer to the IBM 4690 Store  System: Communications Programming Reference .

 

15-29

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

UNIQUE 

A string of up to 10 bytes bytes of data. data. This data is in included cluded in the the log entry made made as a resu result lt of this reques request. t. If the data iis s longer longer th than an 10 bytes, the s system ystem uses tthe he fir first st 10 bytes. If it iis s shorter, the system pads the entry with blanks. Note: The system automatically includes the application name in the log entry.

Applicatio Applica tion n Message Message Logging: Logging: The system references a message display file that your application can provide provi de for messages. messages. This file is called ADXCSOZF.D ADXCSOZF.DAT AT and must be in subdirectory subdirectory ADX_IPGM:. ADX_IPGM:.

This message file contains fixed length records, so entries must follow this format:

 

cXXX_sssssssss

where: c  XXX   _ sssssssss 

= 1-character message group passed through parameter MSGGRP to application services. = 3-digit message number passed through parameter MSGNUM to application services. = Blank space. = Message Message text explain explaining ing tthe he me message. ssage. This text must ffill ill 10 106 6 characte characterr sp spaces. aces. If the  message text is not that long, pad it with blanks.

Note: The 106-character message is displayed as two lines of 53 characters, so be careful of word breaks in your message text. The system uses the first four characters (cXXX  ( cXXX ) of the the message message to scan scan the messag message e file fo forr a mat match. ch. If it finds one, the system displays the message identifier and accompanying text on the SYSTEM MESSAGE DISPLAY screen.

Chaini C ng Applic Applicat ation ions s   haining Chaining  means   means to transfer control from a currently executing application program directly to another application applic ation program. program. Before the CHAIN CHAIN statement is issued, issued, any Displa Display y Manager file files s must be closed using the CLSDIS CLSDIS command. Failure Failure to do this results in a loss of system resources resources needed needed to open files files.. Chaining Chainin g can be performed performed in one of two ways: chaining chaining to a directly executable executable module module or chaining chaining to an overlay. overl ay. Directly Directly executabl executable e modules modules have have a file e extensio xtension n of 286. Overlays Overlays have have a file ex extensio tension n of OVR. Refer to the IBM 4680 BASIC: Language Reference  for   for more information on chaining.

Chaining to Overlays Chaining to overlays is supported only in the store controller. You can share share data with an overlay overlay by using common variables variables.. You cannot cannot pass paramet parameters ers to an

overlay with the CHAIN statement. overlay statement. Applications Applications using using overlays overlays are made up of a root section and ov overlay erlay sections. The root section section should define define all the public functions functions and subprogr subprograms ams that over overlays lays need to use. This allows the overlays to share a single definition of the function or subprogram instead of each overlay having its own copy copy of the function or subprogr subprogram. am. You can chain from from the root to an overlay and and from one overlay overlay to another another.. You cannot cannot chain chain from an overlay overlay to the roo root. t. When you chain chain to an overlay, execution execution begins begins at the first executable executable state statement ment in the program. program. If you use overlays, you must link edit your application with its own copy of the runtime subroutine library, because a shared copy of the runtime library does not support overlays.

15-30

4690 Store System: Programming Guide

 

 

Chaining to Directly Executable Modules Chaining to directly executable modules is supported in both the store controller and the terminal. You can share share data by passing parameters parameters to the modules modules in the CHAIN statement. statement. When a direc directly tly executable module is chained to, execution begins at the first executable statement in the program. Directly executable modules can use a shared copy of the runtime subroutine library.

RAM Disk Files The 4690 Operating System also supports another type of in-memory file called RAM disks . A RAM disk is a section of memory set set aside for use as a high-s high-speed peed disk sto storage rage devi device. ce. RAM disks impr improve ove performance by reducing the amount of time it takes to load frequently-used programs and by redirecting existing existin g applicat application ion access to files files in memory rather rather than to a hardware disk. disk. RAM disk files can be used used for both the store controller and the point-of-sale terminal. The IBM 4690 Operating System allows you to optionally install up to four virtual disks in the controller’s RAM memory and and up to two virtual virtual disks in th the e termina terminal’s l’s RAM memor memory. y. Virtual disks disks can be automatically installed at IPL if your system is configured for RAM disk memory. The controller’s controller’s optional optional disk disks s are named disk devices devices T:, U:, V:, and W:. Termin Terminal al applications applications can access only only disk T:. Controller Controller applications applications can can access access all disks. disks. The terminal’s terminal’s optional optional disks are named named disk devices devices X: and Y:. Terminal Terminal applications applications can acce access ss these disks, but controller applications cannot.

Considerations for Installing RAM Disks RAM disk installation installation is specified specified during during the configur configuration ation process. process. You can speci specify fy the RAM disk size in increments of 32K bytes and the number of directory entries in increments of 16. Note: Terminal RAM disk is created using the RAM disk information found in the Mod1 terminal device group record record only. Mod2 terminal terminal device group records records are erased when when creating termi terminal nal RAM disks. Some characteris characteristics tics of RAM disks are fixed fixed and cannot be redefined redefined by the user user.. These cha character racteristics istics include: Sector size Cluster size Track size

512 bytes 512 bytes 8 sectors

The maximum disk size is dependent on the terminal memory size, space available, and number of files. Disk memory memory is allocated in increments increments of 32 KB. Directory Directory space is allocated allocated in incr increments ements of 16 files.

FAT space is calculated based on the number of sectors.

Accessing RAM Disk Files from Controller Applications In controller applications, all operating system file commands can be executed for RAM disk files, and your IBM 4680 BASIC applications can OPEN, CLOSE, TCLOSE, READ#, or WRITE# to RAM disk files. Data on the RAM disks is lost during during a power outage. outage. Therefore, Therefore, you shou should ld set checkp checkpoints oints duri during ng processing proce ssing for copying copying the data from the RAM disk disk to the hardware disk. disk. The distri distribution bution character characteristics istics of RAM disks are similar similar to those those of d diskette iskettes: s: files are are not not distributed. distributed. However, However, op options tions of ADXC ADXCOPYF OPYF allow preservation of distribution attributes so that distribution occurs when the files are copied to the fixed  

15-31

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

disk. For information information on how how to copy files fr from om the RAM disk, refer refer to the section section on “AD “ADXCOPYF XCOPYF (Copying (Copy ing RAM Disk Files)” Files)” on page 15-32. 15-32.

Accessing Controller RAM Disk Files from Terminal Applications Your terminal application can use all IBM 4680 BASIC statements, which are used for the controller’s fixed disks or diskette diskettes, s, to access access RAM disk T: RAM disk disk U:, V:, and W: cannot cannot be acces accessed. sed. In additio addition, n, use ADXCOPYF to copy files in the controller, regardless of which disk contains them.

Accessing Terminal RAM Disk Files from Terminal Applications | | | |

Your terminal application can access the controller RAM disk with the same IBM 4680 BASIC statements that it uses to access access hard disks and diskettes diskettes on the con controller troller.. Termin Terminal al applications applications cann cannot ot use BASIC statements stateme nts to access controlle controllerr RAM disks U:, V:, and W:. Your application application can call call ADXCOPYF to copy files between the controller and terminal, regardless of which disk contains the files.

ADXCOPYF ADXCO PYF (Copyin (Copying g RA RAM M Di Disk sk Fi Files): les): Th The e subp subpro rogr gram am is desi design gned ed spec specif ific ical ally ly for for RA RAM M di disk sk files, but can can be used on any any files when the the target file is o on n the same con controller troller a as s the sourc source e file. This subprogram is not supported for copying files across the LAN (MCF Network). | | | | |

Warning: If ADXCOPYF fails, the target file is deleted, because partial data might have been written. Therefore, if ADXCOPYF fails while copying to a file which already exists, that file is erased. When you specify a filename for this routine you must specify the exact filename that you want to copy. You must also also specify specify the exact exact source source an and d target filename filenames. s. Do not not use  use global (or wildcard) filename characters. chara cters. The ADXCOPYF ADXCOPYF subroutine subroutine is in the system runtime runtime library library:: ADXACRCL. ADXACRCL.L86 L86 for store controller applications, ADXUCRTL.L86 for terminal medium memory model applications, and ADXUCLTL.L86 for terminal big memory model applications. ADXCOPYF issued from a terminal will always attempt to transmit to all terminals requesting a file at the same time. Your 4680 BASIC application should include a declaration similar to the following:

SUB ADXCOPYF (RETC,INFILE,OUTFILE,OPT0,OPT1) EXTERNAL   INTEG INTEGER ER*4 *4 RETC RETC   STRING INFILE,OUTFILE   INTEGE INTEGER*2 R*2 OPT0,O OPT0,OPT1 PT1 END SUB The function is invoked as follows:

CALL ADXCOPYF (retc,infile,outfile,opt0,opt1)

Where: retc 

= A 4-byte integer return code.

infile 

= A string containing the file name to be copied from (source file). Note: For the terminal ADXCOPYF, the total length of a controller input file name must be less than 25 25 char characters acters.. You can can use a logi logical cal name name to avoid this rrestric estriction. tion. See “U “Using sing L Logical ogical Names” on page page 2-11 for for more information. information.

outfile 

= A string containing the filename to be copied to (target file).

opt0 

= A 2-byte integer indicating whether or not copy operation should be performed:

15-32

4690 Store System: Programming Guide

 

 

0  1 opt1

= File is copied whether or not the output file already exists. = Error message (-2008) is returned if the file already exists and the file is not copied.

= A 2-byte integer used to indicate distribution on a LAN (MCF Network) system (only for 4680   Versi Version on 2): 2):  0  1  2

= Keep the distribution on the output file the same as on the input file. = If the output file exists, keep the same distribution. = Make the output file local.

Table 15-10 show shows s the ADXCOPYF defined return return codes and their desc description riptions: s: Table 15-10. ADXCOP ADXCOPYF YF Return Codes  Return Code

Description

0

Successful copy

Error codes for open on input file -2001

An incorrect file name on the input file

-2002

File in use on the input file

-2003 -2004

Input file not found Ownership differences

-2005

Incorrect device for input file

Error codes for open on output file -2006

Invalid file name on the output file

-2007

File in use on the output file

-2008

File already exists and user-specified not to delete

-2009

Incorrect device for output file

Error codes for reading the input file -2011

Error reading the input file

Error codes for writing to the output file -2016

Hardware error writing to the output file

-2017

Insufficient space for the output file

-2018

Unable to allocate Read/Write buffer for copy

Error code for closing the input file -2021

Error closing the input file

Error code for closing the output file -2026

Error closing the output file

Error code for renaming the temporary file -2031

Rename error

Store Controller Application Services This section section contains contains routines that that are available available only to applications applications on the store co controlle ntroller. r. These | routines are in runtime library ADXACRCL.L86.

|

 

15-33

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

ADXFILES ADXFI LES (Ca (Canceli nceling ng the S Shared hared U Use se of a File): AD ADXF XFIL ILES ES canc cancel el the the shar shared ed us use e of a file file such as the transaction transaction log. log. Without Without the use of ADXFILES, a shared shared file cannot be rena renamed med or deleted because it is in use by more than one user. Some of the conditions that can cause file sharing problems are incomplete transactions, terminal hardware hardw are failures, failures, incomplete controller controller functions, functions, and software failures. failures. ADXFILES ADXFILES provides the following functions to manage the canceling of shared file usage:

 Restricting a file for exclusive use  Unrestricting a file that was restricted  Determining despool status Your 4680 BASIC application should include a declaration similar to the following:

     

SUB ADXFILES (RET,FUNC,PARM1,PARM2) EXTERNAL INTEGE INTE GER* R*44 RET RET INTEGER*2 FUNC, PARM1 STRING PARM2 END SUB EN

ADXFILES ADXFILE S Rest Restric rict: t: ADXFILE ADXFILES S restrict restrict forces the exclusive exclusive use use of a single file. file. This function function is intended to be used only for store closing procedures and should not be used as a general purpose function.

ADXFILES restrict function causes all applications currently using that file to lose their access to that file until they have have closed and reopened reopened the file. file. When an application application atte attempts mpts to use a file that has been restricted, restr icted, the file request request is rejected rejected and a new return cod code e is returned. returned. In the control controller ler the return return code is 80F306F0 80F306F0 and the associate associated d ERR code in BASIC BASIC is *I. In the terminal, terminal, the first first terminal a access ccess to a restricted file receives a 80F306F0 and subsequent accesses (by the same or other terminals) receive a 80004007 80004 007 (bad file number). number). Both of these return return codes in the term terminal inal have an asso associated ciated ERR cod code e of *I. When an application application has a file open and receives receives eith either er of these return return codes for a file reque request, st, it should close and reopen that file.    Purpose: To restrict restrict the use of a file by all other applications. applications. The restr restrict ict applies to app applicatio lications ns on all controllers contro llers and all terminals. terminals. To restrict restrict the use of a mirrored or compound compound file you restrict restrict the prime prime version versio n of the file on the file server server or or master re respecti spectively. vely. You cann cannot ot use restrict restrict for a distribute-on distrib ute-on-clos -close e type file. file. After a file is rrestric estricted: ted:  – It cannot be opened by any application.  – An application applicat ion that is using a file fi le that is restricted by another application must close and reopen a file to use the file again.    Restrictions:  – Only one ADXFILES to restrict a file fil e can be active acti ve at a tim time. e.

 – To restrict a file fil e on a file fil e server or a master the controller application executing the restrict must be connected to the active file server or master.  – To restrict a mirrored file or compound file an application must restrict the prime version of the ffile. ile.  – A distribute-on-close distribut e-on-close type file cannot be restricted.

 Location of usage:  – Any application applicati on on any controller.  – It cannot be used by a terminal appl application. ication.    Call Calling ing seq sequen uence: ce:

CALL ADXFILES (ret,func,parm1,parm2) 15-34

4690 Store System: Programming Guide

 

 

where: RET 

= 4-byte integer that indicates the status of the restrict function hi lo  xx xx yy yy 

= Indicates how the file was being used when the restrict was executed: xxxx = Number of other controller applications that were using this file when it was restricted. yyyy = Number of controllers where terminal applications were using this file when it was restricted. 0000 = No other application has the file open.

80 F3 06 F4  80 F3 06 F5  80 F3 06 F6  8x xx xx xx  -1201 -1202  -1203 

= = = = = = =

Application attempted to restrict a file while another restrict is active. Application attempted to restrict a distribute-on-close file. Application attempted to restrict the file on the wrong node. Any other operating system error return code. Invalid function code used for the FUNC values defined for ADXFILES. PARM1 is not defined. PARM2 is not defined.

-1204  -1205 

= PARM2 is not a valid file name. = Force Close support is not installed.

FUNC  = 1 (This is the rrestric estrictt functi function on cod code e for ADXFILES. ADXFILES.)) PARM1 = Unused; the value is ignored. PARM2  = String containin containing g the file name of the file file to be restricted. restricted. The name may b be e a logical name or a fully-qual fully-qualified ified file name. name. To reference reference a mirrored mirrored or c compound ompound fi file le use the generic node names for the file server and the master:  – for file fi le server use ADXLXACN: ADXLXACN:::  – for master use ADXLXAAN:: ADXLXA AN:: Note: When an application attempts to use a file that has been restricted, you receive either an 80F306F0 80F306 F0 or an 80004007 80004007 (in BASIC, ERR code = *I). The error error recover recovery y should not be done in the ON ERROR code. code. The ON ERROR co code de should iindicate ndicate that that an error h has as occur occurred red and the fi file le should be closed closed and and reopened reopened.. The indicatio indication n should should be made to the code code tha thatt uses the fil file. e. The reopen should provide a delay and retry mechanism because the file remains restricted until it is unrestricted by the application. For example, example, you can can declare a global global variable variable in the pr program. ogram. If the ERR code is *I an and d ERRN is either 80F306F0 or 80004007, set a special value to the global variable in the ON ERROR routine to indicate indica te that the file has been restricted restricted by another another application. application. Then RESUME to the stat statement ement following followi ng the failing statement. statement. The progr program am can then check check for the special val value ue in the global variable varia ble set in the ON ERROR ERROR routine routine.. If the value is set, set, perfor perform m the error recove recovery. ry.

ADXFILES ADXFILE S Unrest Unrestrict rict:: ADXFILE ADXFILES S unrestrict unrestrict stops the effect effect of the ADXFILES ADXFILES res restrict. trict. The unre unrestrict strict is requested for the same file name that was used for the restrict even if the file was renamed while it was restricted. restr icted. After the unrestric unrestrictt is executed that file nam name e may be used by all applications applications again. again.

   Purpose: To unrestrict unrestrict the use of a file that had been previously previously restrict restricted. ed. To unrestrict unrestrict the use of a Mirror Mirrored ed or Compound file, unrestrict the prime version of the file on the File Server or Master respectively. After a file is unrestricted:  – The file fi le name can be used to open files according to the normal guidelines.  – An application appli cation that lost access to a file due to restrict must issue a CLOSE ffollowed ollowed by an OPEN after the unrestrict is issued to gain access to the file again.  

15-35

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

 Prerequisites: The application executing the unrestrict ADXFILES must have executed the restrict ADXFILES.    Restrictions: If an application is unrestricting a file on a file server or a master, the controller executing the application must be connected to the active file server or master.

 Location of usage:  – Any application applicati on on any controller.  – It cannot be used by a terminal appl application. ication.    Call Calling ing seq sequen uence: ce:

CALL ADXFILES (RET,FUNC,PARM1,PARM2) RET 

= 4-byte integer that identifies the unrestrict status. hi lo  00 00 00 00  = Unrestrict is successful. 80 F3 06 F2  = Application attempted to do an unrestrict without doing a restrict. 80 F3 06 F3  = Application attempted to unrestrict a file that it did not have restricted. 8x xx xx xx  -1201 -1202  -1203  -1204  -1205 

= = = = = =

Any other OS error return code. Invalid function code. PARM1 is not defined. PARM2 is not defined. PARM2 is not a valid file name. Force Close support is not installed.

When an unsuccessful unrestrict is executed because of a LAN failure (80 60 xx xx ), ), the application applica tion shoul should d wait 30 seconds and and retry the unrestrict. unrestrict. This shou should ld be repeate repeated d for a total of 7 executions of unrestrict. FUNC  = 2 (This is the unrestrict function code for ADXFILES.) PARM1 = Unused; the value is ignored. PARM2  = String containing containing the the file name of the fi file le to be restr restricted. icted. The name can b be e a logical name name or a fully qualified qualified file name. To reference reference a mirrored mirrored or compoun compound d file use the generic generic node names for the file server and the master store controller:  – For file server use ADXLXACN::  – For master use ADXLXAAN:: ADXLXAAN: : ADXFILES ADXFILE S Des Despoo pool: l: ADXFILES despool determines how many total bytes of data remain in all the spool files and how many controlle controllers rs have spool spool files. By using this function function the applications applications can de determine termine tha thatt the store personnel should be notified that a store closing must be delayed and can give the store personnel an idea of the length of the delay.

   Purpose: This function function determines determines the status of the operating operating system system despooli despooling ng of files. This functi function on determines how many bytes of data are yet to be despooled and how many controllers have data in their spool spool files to be despooled. despooled. The values values determined determined by this function function are probab probably ly differen differentt than the sizes of the spool files because the size of the spool files are not set to zero until all the data has been despooled from them.

15-36

4690 Store System: Programming Guide

 

 

 Prerequisites: None currently identified.    Restrictions: This function can only determine despool status for controllers that are currently in session with this controller on the LAN.

 Location of Usage:  – Any application appli cation on any controller.  – It cannot be used by a terminal application.    Cal Calling ling sequen sequence: ce:

CALL ADXFILES (RET,FUNC,PARM1,PARM2) RET 

= 4-byte integer that specifies the despool status. hi

lo 

0w xx yy yy  = where: w

= Status of LAN communications. 0 = Means all controllers are communicating with this controller. 8 = Means one or more controllers are not communicating with this   controller.

xx

= Number of communicating controllers with data to despool.

yyyy = Total number of bytes (in 1000s ) of data to be despooled by yyyy =   controllers controllers communicating communicating.. 00 00 00 00  = The system supports LAN and there is no despooling to do or the system does not support LAN. 8x xx xx xx 

= Any operating system error return code.

-1201

= Invalid function code.

-1202  -1205 

= PARM1 is not defined. = System supports LAN but Force Close support is not installed.

FUNC  = 3 (T (Thi his s is the the desp despoo ooll func functi tion on code code for for AD ADXF XFIL ILES ES.) .) PARM1 = Unused Unused;; the value value is ignore ignored. d. PARM2  = Unused Unused;; the value value is ignore ignored. d.

ADXCSEOL ADXCSE OL (S (Store tore Cl Closed osed Q Query uery A Applic pplication): ation): AD ADXC XCSE SEOL OL is a 4690 4690 Op Oper erat atin ing g Sy Syst stem em application that determines if the store has been closed to allow end of day processing to begin.

For example, you may want to start the end of day processing in every store in your IBM 4690 Store System network. network. Before starting starting this processi processing ng you must be sure that eac each h store is closed. closed. Closed  means you are no longer longer processing processing transacti transactions. ons. To determi determine ne if all the stores are clo closed, sed, invok invoke e *

ADXCSEOL each theerNetView  DMteINITIATECL IN ITIATECLIST co mmand. code ode rreturne eturned d. toIn this NetView DM in from thestore 4690using 4690 controll controller may indicate indica the store isIST still command. processing proc essing The sales salesc trans transactions actions. case the NetView DM plan which starts the end of day processing bypasses the store. The ADXCSEOL ADXCSEOL application application is written written in IBM 4680 BA BASIC SIC and allo allows ws for a user exit. exit. The user exit exit determines determ ines the status of the s store. tore. If a zero zero (0) is returned returned to to the main main program, program, the the stor store e is clo closed. sed. If the

 

15-37

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

store is open, open, the return code code is a negative one (-1). (-1). The retur return n value is defined as INT INTEGER*4. EGER*4. ADXCSEOL returns the code to the operating system. A user exit is required because determination of the store being closed differs for each sales application product. produ ct. The name name of the user user exit exit must be ADX ADXCSEUR. CSEUR. You must must link your user exit w with ith the base application applic ation to form ADXCSEOL. ADXCSEOL. The default user user exit returns returns a store closed closed status of -1 which is open. The purpose of this user exit routine is to enable you to write code in 4680 BASIC to accomplish any processing proce ssing that you want. want. For example, example, printing printing reports or saving saving critical critical data files. The subroutine should terminate with a recognizable return code that is returned to the host. A user exit subroutine subroutine is available available for the IBM General General Sales Application Application.. It queries the store store status fiel field d in the terminal terminal status file and return return a code of zero (clos (closed) ed) or negat negative ive one (open (open). ). For other sa sales les applications, a user exit is not available.

ADXEXIT ADXEX IT (Set the ERROR ERRORLEVEL LEVEL VALUE VALUE): ): ADXE DXEXIT can be used in a BASIC applica ication ion to set the ERRORLEVEL ERRORLEVEL value value that can be tested tested in a BAT file file.. This value value provid provides es a way for a BAT program to test the results of a BASIC program that it has invoked. Calling ADXEXIT terminates the calling program and sets a 2-byte integer that is used to set the ERRORLEVEL ERRORLE VEL value for for a BAT file. To call ADXE ADXEXIT XIT in a BASIC pro program, gram, you mu must st first def define ine it as follows:

   

SUB ADXEXIT (PARM1) EXTERNAL INTEGE INTE GER* R*22 PARM PARM11 END SUB EN

To call ADXEXIT, your code should be similar to the following:

ERRORLEVEL = 20 CALL ADXEXIT (ERRORLEVEL) The allowed values for the 2-byte integer are 0 to 32,767. In addition, the BASIC program calling ADXEXIT must be linked with the ADXACRCL.L86 file containing ADXEXIT.

15-38

4690 Store System: Programming Guide

 

 

To test the value of errorlevel in a BAT file, test in descending order as in the following example:

IF IF IF IF

ERRORLEVEL 500 GOTO T500 ERROR ERR ORLE LEVE VELL 20 GOTO GOTO T20 T20 ERROR ERR ORLE LEVE VELL 19 GOTO GOTO T19 T19 ER ERRORLEVEL 1 GOTO T1 T1 (this statement would be executed if ERRORLEVEL is 0) :T500 (this statement would be executed if ERRORLEVEL is 500 or more) :T20 (this statement would be executed if ERRORLEVEL is 20 to 499) :T19 (this statement would be executed if ERRORLEVEL is 19) :T1 (this statement would be executed if ERRORLEVEL is 1 to 18) This section section lists functions functions available available only to applications applications running running at the store controller controller.. Use the ADXSERVE request call for these functions.

ADXSERCL ADXSER CL (C (Closing losing an App Applicati lication on Ser Service): vice): Th This is subp subpro rogr gram am is used used by cont contro rollller er applications applica tions to close ADXSERVE. ADXSERVE. The ADXSERCL ADXSERCL subprogram subprogram is to be used only before before chaining fro from m an application application that invoked invoked ADXSERVE. ADXSERVE. If ADXSERVE was not invoked, invoked, ADXSERCL ADXSERCL does not affect affect the operating system. ADXSERCL allows applications ADXSERCL applications that chain to deallocate deallocate system resou resources. rces. These reso resources urces are allo allocated cated the first time the the application application uses ADXSERVE ADXSERVE.. It is not necessary necessary to close close ADXSER ADXSERVE VE each time it is used. If an ADXSERCL is used after after each execution execution of ADXSERVE, ADXSERVE, system performanc performance e is impaired. Warning: If you have invoked ADXSERVE and you are not chaining applications, ADXSERCL must not be used. The ADXSERCL ADXSERCL routine for store store controller controller applications applications is written written in IBM 4680 BASIC. The applic application ation should include the following declaration statement:

SUB ADXSERCL EXTERNAL END SUB The subprogram is invoked as follows:

 

Calll ADXS Cal ADXSER ERCL CL

Terminal Application Services This section lists routines that are available only to applications at the terminal.

ADXDIR ADXDI R (List (Listing ing Te Terminal rminal RAM Di Disk sk Fil Files): es): Term Termin inal al appl applic icati ation ons s use use the the AD ADXD XDIR IR subprogram to list subprogram list the files in RAM disks disks X: and Y: and the amount amount of free space space on the dis disks. ks. This subprogram displays the same type of information about terminal RAM disks that the DIR command | display displays s about controller controller disks. The ADXDIR subprogram subprogram is in the system runtime subroutine subroutine library library | |

ADXUCRTL.L86 for medium memory model terminal applications and ADXUCLTL.L86 for big memory model terminal applications.

 

15-39

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

The 4680 BASIC terminal application must contain a routine similar to the following:

SUB ADXDIR (RETC,DISKID,OUTINFO,FILEINDX) EXTERNAL INTEGER*4 RETC STRING DISKID,OUTINFO INTEGER*2 OPTION END SUB The SUBPROGRAM is called as follows: CALL ADXDIR (retcode,disk,direntry,opt) where: retcode  = 4-byte integer return code. disk 

= String containing the disk ID (X: or Y:) and optionally continuing with a file name with or without global file name characters (*).

direntry  = String that contains information for one directory entry on return to the caller. opt 

= Option indicating indicating whether whether the first or next dire directory ctory entr entry y is desired. An integer va value lue of 0 indicates first and 1 indicates next.

The ADXDIR subprogram is typically called within a loop in the application, such that each repetition of the loop passes passes the information information for a director directory y entry. entry. The opt  parameter   parameter should indicate the first entry on the first repetition repetition of the loop, and it should should indicate indicate the next entry on the following following repetition. repetition. When the application is executing such a loop, the ADXDIR subprogram passes information for each file on the RAM disk in the direntry  the direntry  string   string as the loop loop progresses. progresses. As the loop is executed executed and and file inform information ation is pas passed sed in the direntry  string,   string, the application can display it, collect it, or send it to an application in the controller, for example. exampl e. When informati information on for all existin existing g files has has been pa passed, ssed, the the retcode  indicates   indicates this condition and the application can terminate the loop. Ta Tabl ble e 15 15-1 -11. 1. S Suc ucce cessf ssful ul ADXD ADXDIR IR Retu Return rn Code Codes s th that at do no nott impl imply y erro errorr cond condit itio ions. ns. Return Code

Description

0

Indicates successful passing of file information

1

Indicates no more files on the disk

Ta Tabl ble e 15 15-1 -12. 2. ADXDIR ADXDIR Erro Errorr Re Retu turn rn Co Code des s th that at impl imply y er erro rorr cond condit itio ions ns.. Return Code

Description

3001

Indicates the disk ID is not X: or Y:

3002

Indicates the requested X: or Y: disk is not configured.

The direntry  string   string is formatted as follows on return from ADXDIR: If the return code is 0: file name blank   blank file extension blank   blank file size blank   blank date   date blank   blank time   time

15-40

 –8 characters –1 charac –1 character ter  –3 characters –1 charac –1 character ter  –7 characters –1 charac –1 character ter –8 cha charac racter ters s –1 charac –1 character ter –6 cha charac racter ters s

4690 Store System: Programming Guide

 

 

blank  blank  number of files blank   blank number of free bytes blank   blank

–1 – 1 charac character ter  –3 characters –1 charac –1 character ter  –7 characters –1 charac –1 character ter

If the return code is 1, the direntry  string   string contains the number of files and the number of free bytes in the positions indicated above, but all other positions contain blanks.

Extended Extende d Memory Ma Manageme nagement nt for the IBM Po Point int of Sale Te Terminal rminal:: Ext Extend ended ed memory memory management is an alterna management alternative tive to terminal terminal RAM disk. It is typically used used when the termin terminal al does not have enough memory for the RAM disk, but the application needs more memory for data than its 64K data segment. segmen t. Extended Extended memory management management is a library library of subroutines subroutines that is linked with the ter terminal minal application. applica tion. There are two two sets of libr libraries aries available available tha thatt contain contain these these subrouti subroutines: nes: ADXMEM0 ADXMEM0L.L86 L.L86 and ADXMEM1L.L86 are used when linking an application that was compiled using the 4680 CBASIC medium memory model compiler; ADXMEL0L.L86 and ADXMEL1L.L86 are used when linking an application that was compiled using the 4680/90 CBASIC big memory model. ADXMEM0L.L86 and ADXMEL0L.L86 libraries contain subroutines that allow the application to allocate, free, read, read, write, and search search the memory. memory. ADXMEM1L.L86 ADXMEM1L.L86 and ADXMEL1L.L8 ADXMEL1L.L86 6 libraries libraries contain subroutines subro utines that allow allow the application application to insert and dele delete te keyed records records in memor memory. y. Applic Applications ations in the Mod1 and Mod2 terminals can share a section of memory while using any of these routines. The subroutines are linked by adding the appropriate library to your link input file. Notes:   memory model model user: If you use onl only y extended extended memory ma manageme nagement nt routine routines s 1. If you you are are a medium  memory contained contai ned in the ADXMEM0L.L86 ADXMEM0L.L86 library, library, you do not need to link with the ADXMEM1L.L8 ADXMEM1L.L86 6 library. library. If you use any routines contained in the ADXMEM1L.L86 library, you must also link with the ADXMEM0L.L86 ADXMEM0 L.L86 library. library. Also, the ADXMEM1L ADXMEM1L.L86 .L86 library library must precede the ADXMEM0L.L86 ADXMEM0L.L86 libra library ry in the link order to avoid link errors. 2. If you you are are a big  memory   memory model model user: If you use only only extended extended memory ma managemen nagementt routines routines contained in the ADXMEL0L.L86 contained ADXMEL0L.L86 libra library, ry, you do not need to link with the ADXMEL1L.L ADXMEL1L.L86 86 library library.. If you use any routines contained in the ADXMEL1L.L86 library, you must also link with the ADXMEL0L.L86 ADXMEL0 L.L86 library. library. Also, the ADXMEL1L.L86 ADXMEL1L.L86 libra library ry must precede the ADXMEL0L.L86 ADXMEL0L.L86 library library in the link order to avoid link errors. The following table describes each subroutine and defines its library name.   Subroutine

  Description

Medium Memory Model Library Name

Big Memory Model Library Name

GETMEM

Allocate a memory file

ADXMEM0L.L86

ADXMEL0L.L86

OPENMEM

Gain access to a shared memory file

ADXMEM0L.L86

ADXMEL0L.L86

MEMSYN

Gain mutually exclusive access to shared memory

ADXMEM0L.L86

ADXMEL0L.L86

MEMUNSYN

Release mu mutually e ex xclusive access to shared memory

ADXMEM0L.L86

ADXMEL0L.L86

FREEMEM

Free a memory file

ADXMEM0L.L86

ADXMEL0L.L86

AVAILMEM

Query available free memory

ADXMEM0L.L86

ADXMEL0L.L86

MEMWRITE

Write data to a memory file

ADXMEM0L.L86

ADXMEL0L.L86

 

15-41

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

  Subroutine

  Description

Medium Memory Model Library Name

Big Memory Model Library Name

MEMREAD

Read data from a memory file

ADXMEM0L.L86

ADXMEL0L.L86

MEMSRCHB

Binary search for matching field

ADXMEM0L.L86

ADXMEL0L.L86

MEMSRCHS

Sequential search for matching field

ADXMEM0L.L86

ADXMEL0L.L86

MEMWRKEY

Insert ke keyed rre ecords iin nto a memory file sequenced in ascending order by key

ADXMEM1L.L86

ADXMEL1L.L86

MEMDLKEY

Delete keyed records from a memory file sequenced in ascending order by key

ADXMEM1L.L86

ADXMEL1L.L86

MEMCLEAR

Clear a memory file

ADXMEM1L.L86

ADXMEL1L.L86

Using Extended Extended Memory Memory Ma Managem nagement: ent: A section of memory that is managed by these subroutines is

|

called less an in-memory file .n RAM An in-me in-memor y file is no nott the same same a as sintended a RAM disk isktermi ffile. ile. nals In-memo In-memory ry files files h have aveof much overhead than overhead tha diskmory files. In-memory In-memo ry files are inte nded d for terminals that have 1 MB memory.. Normally memory Normally these ter terminals minals do not not contain enough enough memo memory ry for RAM disk disk use. The subroutines can be divided into five different categories, according to their functions. 1. The first category contains subroutines subroutines that are used to access or to release access to memory. GETMEM is used used to allocate allocate a section of memory memory of a size sp specified ecified by by the applic application. ation. GETMEM has an option option to allocate allocate a section of memory memory that can can be shared by by other app applicatio lications. ns. If another application needs to access an in-memory file that was allocated in this way, it issues an OPENMEM call. It can then access access the in-memory in-memory file file just as if it had allocated allocated it by iss issuing uing GETME GETMEM. M. FREEMEM is used to release release acce access ss to an in-memory in-memory file. In the case of shared inin-memory memory file files, s, the memory is released when the last application issues the FREEMEM against the in-memory file. 2. The second second category category contains contains subrou subroutines tines whi which ch read and write write the memor memory. y. These s subrou ubroutines tines function functio n the same whether or not not the in-memory in-memory file is shared. The simplest simplest subroutin subroutines es are MEMREAD and MEMWRITE.

|

MEMSRCHS is a routine that is used for a sequential search of an in-memory file for a particular key. MEMSRCHB is used used for a binary binary sear search. ch. MEMSRCHB MEMSRCHB should be used used for doing doing search searches es only if the in-memory file is sequenced by a key in ascending order; otherwise MEMSRCHS should be used. The MEMWRKEY MEMWRKEY subroutine subroutine is used to build a key sequenced sequenced memory memory file. A binary search search is faster than a sequential search, but a binary search does not work if the data is not sorted. Using the MEMSRCHS and MEMSRCHB subroutines, the caller passes a search argument, search argument argume nt length, and the offset offset into the in-memory in-memory file records records of the key. The searc search h argument argument is

compared compar ed with the key. key. If they match, match, the search complete completes s successfully. successfully. 3. The third category of subroutines subroutines is used by applications to synchronize access to shared in-memory files. If an application application temporarily temporarily needs exclusiv exclusive e access to a shared shared memory file, it shoul should d call MEMSYN before before beginning beginning the access. After it is finishe finished d with the access it should should call MEMUNSYN MEMUNSYN.. Following Followin g is an explanation explanation of how MEMSYN and MEMUNSYN MEMUNSYN are used. There are are two applicati applications: ons: application A and applicat application application ion B. They share an inin-memory memory file. The in in-memor -memory y file contai contains ns a counte counterr that is incremented at the end of every transaction, so that it contains the total number of transactions that have occurred occurred on the Mod1 and Mod2 Mod2 pair. At the end of each transa transaction, ction, the appl application ication must must read in the counter using MEMREAD, increment it, and write it back using MEMWRITE.

15-42

4690 Store System: Programming Guide

 

 

If the applications applications are are not using MEMSYN MEMSYN and MEMUNSYN, MEMUNSYN, the following following happens: happens: applica application tion A finishes finishe s a transa transaction. ction. It reads reads in the counter counter using MEMREAD MEMREAD.. Application Application A is preempted preempted by application applic ation B, which is also finish finish a transact transaction ion and read in the counter. counter. Applic Application ation B increments increments the counterr and writes it back using MEMWRIT counte MEMWRITE. E. Application Application A runs again. It increments increments its co copy py of the counterr and write it back. At that point, the counter counte counter is less than it should be because because the application applications s are not guaranteed guaranteed exclusive exclusive access. access. Howeve However, r, if each of the applications applications had called called MEMSYN before calling MEMREAD; and called MEMUNSYN after calling MEMWRITE, this problem would not have happened. If an application calls MEMSYN and then another application calls MEMSYN using the same in-memory file number, execution of the second application is suspended until the first application calls MEMUNSYN. Note: When a shared in-memory file is created, the GETMEM subroutine performs a MEMSYN. Until the application that performed the GETMEM calls MEMUNSYN, the execution of any application performing a MEMSYN is suspended. 4. The fourth fourth ca category tegory is the subrou subroutine tine AVA AVAILMEM. ILMEM. AVAILMEM is called called to fi find nd out h how ow much free memory is in the system. Each of the calls (excluding (excluding AVA AVAILMEM) ILMEM) provides provides an in-memory in-memory file num number. ber. When the GETME GETMEM M or the OPENMEM is performed, the subroutines associate that in-memory file number with a section of memory until the FREEMEM is done. One application application may not have more more than one in-memo in-memory ry file with the same in-memory in-memory file number. number. If two applications use the same in-memory file number for non-shared in-memory files, the in-memory file number refers to a different section of memory for each application. If an application allocates a shared in-memory file, the other application accesses that shared in-memory file by issuing an OPENMEM with the same in-memory file number as was used by the application that called GETMEM. 5. The fifth fifth category category contains contains the subroutines, subroutines, MEMWRKEY MEMWRKEY and MEMDLKEY. MEMDLKEY. MEMWRKEY MEMWRKEY and MEMDLKEY MEMDLKE Y are used to insert insert and delete delete keyed records records in in an in-memory in-memory file. MEMWRKE MEMWRKEY Y and MEMDLKEY MEMDLKE Y do not work if the in-memor in-memory y file is not sorted sorted in ascending ascending ord order er by key. Creati Creating ng a file using MEMWRKEY automatically sorts the in-memory file in ascending order by key. Using MEMWRKEY, MEMWRKEY, the in-memory in-memory file file is searched searched for a record. record. If a record wi with th the same ke key y is found, MEMWRKEY MEMWRKEY overlays overlays the the old record. record. If the record record that was foun found d does not hav have e the same key, then the MEMWRKEY creates space for the new record by moving up each record with a greater key. An argument argument is passed passed to MEMWRKEY MEMWRKEY that indicates indicates the leng length th of the key, and th the e size of the data including the key. Using MEMDLKEY, MEMDLKEY, the in-memory in-memory file file is searched searched for a rec record. ord. If the recor record d is found the ke keyed yed record recor d is deleted and all records records with a great greater er key are shifted shifted down by one recor record. d. If MEMDLKEY does not find the specified record, an error message indicating the record was not found is returned to the application.

MEMCLEAR MEMCLEA R can be used to delete delete all records records from from the in-mem in-memory ory file. The entir entire e memory space space is filled with X'0xFF' and the internal record counter is reset to zero. Note: When using MEMWRKEY and MEMDLKEY, the key must start with the first byte of the record. If MEMWRKEY, MEMDLKEY, or MEMCLEAR are being used on a shared in-memory file, the application should call MEMSYN before calling MEMWRKEY, MEMDLKEY, or MEMCLEAR followed by calling MEMUNSYN. Defining Extended Defining Extended Memory Mana Management gement Subrout Subroutines: ines: The following section contains an explanation of the subroutines that are supported by extended memory management.

Note: The following explains the parentheses within the parameter list:

 

15-43

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

 I   passes passes input data to the memory manager subroutine.   passes output data from the memory manager subroutine.  O  passes   passes input data to and output data from the memory manager subroutine in the same  I/O  passes parameter. Warning: Before reading data from a memory file, a string of data must be allocated in IBM 4680 BASIC. The memory manager does not allocate or increase the size of the receiving string. The subroutines by entry point are: GETMEM

Allocates a memory file    Call Par Paramet ameters ers:: (O) (O) (I) (I) (I) (I)

INTEGER*4 INTEGER *4 INTEGER*4 INTEGER *4 INTEGER INT EGER*2 *2 INTEGER*4 INTEGER *4 INTEGER INT EGER*2 *2 INTEGER INT EGER*2 *2

return return value value re recei ceive ve area area record record count count or system system er error ror receive receive area memory memory file number number count of memory memory records records to alloca allocate te memory memory reco record rd s size ize shared shared memo memory ry flag flag

0 = not shared 1 = shared    Retu Return rn Value: Value:  – Zero if file is successfully created  – Negative return code on error Notes: 1. GETMEM performs performs a MEMSYN when creati creating ng a shared shared in-memory in-memory file. MEMUNSYN should be called after GETMEM to allow the next function which issues a MEMSYN to obtain exclusive exclusive access access to the the in-memory in-memory file. If MEMUNSYN is not not called after after GETMEM, the next function to issue a MEMSYN is suspended until a MEMUNSYN is issued. 2. The memory memory file number is set by the 4680 BASIC BASIC program. program. The si size ze of the the in-me in-memory mory file that is allocated is obtained by multiplying the record count by the record size. Shared in-memor in-memory y files are limited limited in size to 64 64 Kb minus 12 bytes. bytes. A recor record d count is returned return ed to the caller to indicate indicate the number of rec records ords that were were allocated allocated.. Non-shared Non-shared files can be as large as the available memory in the terminal.  Gains access to a shared memory file OPENMEM Gains OPENMEM    Cal Calll Parame Parameter ters: s: INTEGER* GER*4 4 return return value value rrece eceive ive ar area ea (O) INTE (O) INTEGER* INTEGER*4 4 record record count or system system error error receive receive area

(I) (I)

INTEGER*2 INTEGER* 2 memory memory file num number ber INTEGER* INTE GER*2 2 memory memory file file re recor cord d size size

   Ret Return urn Valu Value: e:  – Zero if file is successfully created  – Negative return code on error Note: The record size specified on the OPENMEM should be the same as the record size specified specifi ed o on n the GETMEM. However, However, no automat automatic ic ch checking ecking is d done one for for th this. is. A re record cord count that is returned to the caller indicates the size of the in-memory file.

15-44

4690 Store System: Programming Guide

 

 

MEMSYN Gains mutually exclusive access to shared memory    Call Par Paramet ameters ers:: INTEGE GER* R*4 4 retu return rn valu value e (O)  INTE (O)  (O) INT INTEGER EGER*4 *4 system system err error or receive receive area area (I) INT INTEGER EGER*2 *2 memory memory file number number    Retu Return rn Value: Value:  – Zero if file is successfully created  – Negative return code on error Note: An error results if this call is issued using a file number for a non-shared in-memory file. MEMUNSYN Releases MEMUNSYN  Releases mutually exclusive access to shared memory    Call Par Paramet ameters ers:: (O)  INTE (O)  INTEGE GER* R*4 4 retu return rn valu value e (O) INT INTEGER EGER*4 *4 system system err error or receive receive area area INTEGER EGER*2 *2 memory memory file number number (I) INT    Retu Return rn Value: Value:  – Zero if file is successfully created  – Negative return code on error Note: An error results if this call is issued using a file number for a non-shared in-memory file. FREEMEM Frees FREEMEM  Frees a memory file    Call Par Paramet ameters ers:: (O) INT INTEGER EGER*4 *4 return return value value receivin receiving g area INTEGER*4 *4 system error code receiving receiving area area (O) INTEGER INTEGER EGER*2 *2 memory memory file number number (I) INT    Retu Return rn Value: Value:  – Zero if successful  – Negative return code on error AVAILMEM Queries AVAILMEM  Queries available free memory    Call Par Paramet ameters ers:: (O) INT INTEGER EGER*4 *4 return return value value receivin receiving g area INTEGER*4 *4 system error code receiving receiving area area (O) INTEGER    Retu Return rn Value: Value:  – Amount of free memory mem ory available in bytes

 Writes data to a memory file MEMWRITE Writes MEMWRITE    Call Par Paramet ameters ers:: INTEGER EGER*4 *4 return return value value receivin receiving g area (O) INT INTEGER*4 *4 system error code receiving receiving area area (O) INTEGER (I) (I) (I) (I) (I)

INTEGER*2 INTEGER *2 STRING INTEGER INT EGER*4 *4 INTEGER INT EGER*2 *2 INTEGER*2 INTEGER *2

memory memory file number number data tto o be be wr written target target memo memory ry record record num number ber offset offset into ta targe rgett record record length of data (0 defa defaults ults to recor record d size size))

   Retu Return rn Value: Value:

 

15-45

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

 – Zero if successful  – Negative on error MEMREAD Reads MEMREAD  Reads data from a memory file    Cal Calll Parame Parameter ters: s: (O) (O) (I) (O) (I) (I) (I)

INTEGER*4 INTEGER* 4 INTEGER*4 INTEGER* 4 INTEGER* INTE GER*2 2 STRI ST RING NG INTEGER* INTE GER*4 4 INTEGER* INTE GER*2 2 INTEGER*2 INTEGER* 2

return return value value rec receiv eiving ing area area system error code receiving receiving area area memory memory file num number ber rec ecei eiv vin ing g str strin ing g ffor or the the dat data a tar target get memory memory recor record d number number off offset set into into targ target et record record length of data (0 def defaults aults to recor record d size)

   Ret Return urn Valu Value: e:  – Zero if successful  – Negative on error Note: Before calling MEMREAD, allocate a string that is large enough to receive the data. MEMSRCHB Conducts MEMSRCHB  Conducts binary search for matching field    Cal Calll Parame Parameter ters: s: (O) (O) (I) (I/O)   (I/O) (I) (I) (I)

INTEGER*4 INTEGER *4 INTEGER*4 INTEGER *4 INTEGER INTE GER*2 *2 STRING ST INTEGER INTE GER*2 *2 INTEGER*2 INTEGER *2 INTEGER INTE GER*2 *2

ret return urn value value receivin receiving g area system error code receiving receiving area memory memory file num number ber search argument length length of search search ar argum gument ent offset into into target target recor record d of field, offset offset of 0 is valid length length of ret return urn data data

(I)

If 0, no data is returned. returned. If greater greater than 0, data is returne returned d to the searc search h argume argument. nt. INTEGER*4 INTEGER *4 offset of return return d data ata field iin n recor record, d, offset o off 0 is valid

   Ret Return urn Valu Value: e:  – if successful  – Zero Negative on error Note: The file must must be sorted in ascendin ascending g order to use use the binar binary y search search.. If the file is partially filled with records, it should be initialized with records of hexadecimal X'FF’' to ensure ascending ascend ing order. order. If data is to be returned, returned, allocate the argument argument string string large enoug enough h to receive the data. MEMSRCHS Performs MEMSRCHS  Performs sequential search for matching field    Cal Calll Parame Parameter ters: s:

15-46

(O) (O) (I) (I/O)   (I/O) (I) (I) (I)

INTEGER*4 INTEGER *4 INTEGER*4 INTEGER *4 INTEGER INTE GER*2 *2 STRING ST INTEGER INTE GER*2 *2 INTEGER*2 INTEGER *2 INTEGER INTE GER*2 *2

ret return urn value value receivin receiving g area system error code receiving receiving area memory memory file num number ber search argument length length of search search ar argum gument ent offset into into target target recor record d of field, offset offset of 0 is valid length length of ret return urn data data

(I)

If 0, no data is returned. returned. If greater greater than 0, data is returne returned d to the searc search h argume argument. nt. INTEGER*4 offset of return INTEGER*4 return d data ata field iin n recor record, d, offset o off 0 is valid

4690 Store System: Programming Guide

 

 

 Retu Return rn Value: Value:  – Zero if successful  – Negative on error Note: If data is to be returned, allocate the argument string large enough to receive the data. MEMWRKEY Inserts MEMWRKEY  Inserts data to a memory file in ascending order by key    Call Par Paramet ameters ers:: (O) (O) (I) (I) (I) (I)

INTEGER*4 INTEGER* 4 INTEGER*4 INTEGER* 4 INTEGER* INTE GER*2 2 STRING INTEG INT EGER* ER*2 2 INTEGER*2 INTEGER* 2

ret return urn value value receiv receiving ing area area system error code receiving receiving area memory memory file num number ber data tto ob be e wr written le leng ngth th of of key key length of data (0 def defaults aults to recor record d size)

   Retu Return rn Value: Value:  – Zero if successful  – Negative on error Notes: 1. When using using MEMWRKEY, the key must must start with the first byte of the record. record. 2. If MEMWRKEY is being used on a shared in-memory in-memory file, the applicati application on should call MEMSYN before calling MEMWRKEY followed by calling MEMUNSYN. MEMDLKEY Deletes MEMDLKEY  Deletes data from a memory file sequenced in ascending order by key    Call Par Paramet ameters ers:: (O) (O) (I) (I) (I)

INTEGER*4 INTEGER* 4 INTEGER*4 INTEGER* 4 INTEGER* INTE GER*2 2 STRI RIN NG INTEG INT EGER* ER*2 2

ret return urn value value receiv receiving ing area area system error code receiving receiving area memory memory file num number ber key of of re record to to b be e de deleted ted le leng ngth th of of key key

   Retu Return rn Value: Value:  – Zero if successful  – Negative on error Notes: 1. When using using MEMDLKEY, the key must must start with the first byte of the record. record. 2. If MEMDLKEY is being used used on a shared in-me in-memory mory file, the app applicatio lication n should call MEMSYN before calling MEMDLKEY followed by calling MEMUNSYN. MEMCLEAR Clears MEMCLEAR  Clears a memory file

   Call Par Paramet ameters ers:: (O) (O) (I)

INTEGER*4 INTEGER* 4 ret return urn value value receiv receiving ing area area INTEGER*4 INTEGER* 4 system error code receiving receiving area INTEGER* INTE GER*2 2 memory memory file num number ber

Note: If MEMCLEAR is being used on a shared in-memory file, the application should call MEMSYN before calling MEMCLEAR followed by calling MEMUNSYN. Example Subroutine Example Subroutine Declarations Declarations using using IBM 4680 BASIC: BASIC: The following examples explain how to format an IBM 4680 BASIC declaration.

 

15-47

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

SUB GETMEM (RETCODE,SYSRET,FILEID,KOUNT,RECSIZE,SHFLAG) (RETCODE,SYSRET,FILEID,KOUNT,RECSIZE,SHFLAG) EXTERNAL INTEGER*4 RETCODE, SYSRET, KOUNT INTEGER*2 FILEID, RECSIZE, SHFLAG END SUB SUB OPENMEM (RETCODE,SYSRET,FILEID,RECSIZE) EXTERNAL INTEGER*4 RETCODE, SYSRET INTEGER*2 FILEID, RECSIZE END SUB SUB MEMSYN (RETCODE,SYSRET,FILEID) EXTERNAL INTEGER*4 RETCODE, SYSRET   INTE INTEGE GER* R*22 FILE FILEID ID END SUB SUB MEMUNSYN (RETCODE,SYSRET,FILEID) EXTERNAL INTEGER*4 RETCODE, SYSRET   INTE INTEGE GER* R*22 FILE FILEID ID END SUB SUB   END

FREEMEM (RETCODE,SYSRET,FILEID) EXTERNAL INTEGER*4 RETCODE, SYSRET INTE INTEGE GER* R*22 FILE FILEID ID SUB

SUB AVAILMEM (KOUNT,SYSRET) EXTERNAL INTEGER*4 KOUNT, SYSRET END SUB SUB MEMWRITE (RETCODE,SYSRET,FILEID,INDATA$,\   RECNUM,OFFSE RECNUM ,OFFSET,LENG T,LENGTH) TH) EXTERNAL EXTERNAL INTEGER*4 RETCODE, SYSRET, RECNUM INTEGER*2 FILEID, OFFSET, LENGTH   ST STRING INDATA$ END SUB SUB MEMREAD (RETCODE,SYSRET,FILEID,INDATA$,\   RECNUM,OFFS RECNUM ,OFFSET,LEN ET,LENGTH) GTH) EXTERNAL EXTERNAL INTEGER*4 RETCODE, SYSRET, RECNUM INTEGER*2 FILEID, OFFSET, LENGTH   STRING INDATA$ END SUB SUB MEMSRCHB (RETCODE,SYSRET,FILEID,INDATA$,\   SLENGTH,TO SLENGTH,TOFFSET FFSET,RLEN ,RLENGTH,RO GTH,ROFFSET FFSET)) EXTERNAL EXTERNAL

INTEGER*4 RETCODE, SYSRET INTEGER*2 FILEID, SLENGTH, TOFFSET, RLENGTH, ROFFSET   ST STRING INDATA$ END SUB SUB   MEMSRCHS INTEGER*4 INTEGER*2   ST STRING END SUB

(RETCODE,SYSRET,FILEID,INDATA$,\ SLENGTH,TO SLENGTH,TOFFSET FFSET,RLEN ,RLENGTH,RO GTH,ROFFSET FFSET)) EXTERNAL EXTERNAL RETCODE, SYSRET FILEID, SLENGTH, TOFFSET, RLENGTH, ROFFSET INDATA$

SUB MEMWRKEY (RETCODE, SYSRET, FILEID, INDATA$,\ 15-48

4690 Store System: Programming Guide

 

 

KLENGTH, LENGTH) EXTERNAL INTEGER*4 RETCODE, SYSRET INTEGER*2 FILEID, KLENGTH, LENGTH   STRING INDATA$ END SUB SUB MEMDLKEY (RETCODE, SYSRET, FILEID, KEY$,\   KKLEN LENGTH GTH)) EXTERN EXTERNAL AL INTEGER*4 RETCODE, SYSRET INTEGER*2 FILEID, KLENGTH   STRING KEY$ END SUB SUB MEMCLEAR (RETCODE, SYSRET, FILEID) EXTERNAL INTEGER*4 RETCODE, SYSRET   INTE INTEGE GER* R*22 FILE FILEID ID END SUB Table 15-13. Functi Function on Return Codes 

|

Return Code

Description

-1009

Attempted to allocate more than 64 files

-1011

Out of memory; cannot continue

-1013

Attempted to allocate the same file ID twice

-1014

File not found, or attempted to use MEMSYN or MEMUNSYN on a non-shared file

-1015

Record position outside of the file

-1016

Search record not found

-1017

Data length not va vallid (greater th tha an 512 bytes) tes),, negative length, th, or empty stri rin ng passed as parameter to subroutine

-1019

Receiving string not large enough

-1020

Requested shared memory greater than 65,524 bytes in length

-1021

Null string parameter detected

 

15-49

Chapter Chapt er 15. Designing Designing Applicati Applications ons with IBM 4680 BASIC BASIC

 

 

15-50

4690 Store System: Programming Guide

 

 

Chapte Cha pterr 16. Design Designing ing Applic Applicati ations ons with with Other Other Language Languages s 4690 Operating System Interfaces for C and COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . .  16-2 . . . Using the C Language Interface Using the COBOL Language Interfaces Disk File Management . . . . . . . . . Fil File e Acce Access ss   . . . . . . . . . . . . . . . . Access Acc ess Modes Modes   . . . . . . . . . . . . File Poin Pointer ters s  . . . . . . . . . . . . . Pipe Pip e Manage Managemen mentt   . . . . . . . . . . . . Creating and Deleting Pipes . . . . Pipe Pipe Acce Access ss   . . . . . . . . . . . . . . File and Pipe Services . . . . . . . . . Create Point-of-Sale Keyed File . . Open Keyed File . . . . . . . . . . . Close Keyed File . . . . . . . . . . . Read Keyed Record . . . . . . . . .

|

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Write Keyed Record . . . . . . . . . . Delete Keyed Record . . . . . . . . . Create Point-of-Sale Non-Keyed File Create Non-Point-of-Sale File or Pipe Open File or Pipe . . . . . . . . . . . Close File or Pipe . . . . . . . . . . . Read Record from File or Pipe . . . . Write a Record to a File (nonkeyed) or Lock and Unlock Record . . . . . . . Delete File or Pipe . . . . . . . . . . . Rename a File . . . . . . . . . . . . . Seek (Change or Get File Pointer) . . Change File Attributes . . . . . . . . . Canceling the Shared Use of a File .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 16-3  16-3  16-4 16-4 16-4 16-5 16-5  16-5 16-5  16-7  16-7  16-11  16-11  16-12

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 16-13  16-14  16-14  16-16  16-17  16-18  16-19  16-20  16-21  16-22  16-22  16-23  16-24  16-24

Pipe Routing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Create a Pipe Routing Services Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Read from a Pipe Routing Services Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Initialize Pipe Routing Service Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Write to a Pipe Routing Services Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conditional Write to a Pipe Routing Services Pipe . . . . . . . . . . . . . . . . . . . . . . . . . Communications Communic ations Servic Services es   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specialized Specia lized Servic Services es   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operator Operat or Authorization Authorization   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

 16-28  16-28  16-28  16-29  16-30  16-30 16-32 16-32 16-32

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Pipe

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Password Encryption Password Encryption   . . . . . . . . . . . . . . . Common Application Services (ADX_CSERVE) Application Services for C-language and COBOL Starting a Background Application . . . . . . . . Logging an Error . . . . . . . . . . . . . . . . . . Miscellaneous Services Miscellaneous Services   . . . . . . . . . . . . . . Ending a Program . . . . . . . . . . . . . . . Exiting a Program . . . . . . . . . . . . . . . Getting Additional Storage . . . . . . . . . . Freeing Fre eing Stor Storage age   . . . . . . . . . . . . . . . . Suspended Processing for Indicated Duration Waiting for Event Completion . . . . . . . . .

© Copyright

16-34  16-35  16-35  16-40  16-42

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16-43  16-43  16-44  16-44 16-45  16-46  16-46

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16-1

IBM Corp. 1994, 1996

 

 

Converting HEX to ASCII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  16-48 Guidelines and Restrictions for Assembly Language Applications . . . . . . . . . . . . . . . . . . . .  16-48 This chapter contains coding guidelines and restrictions that you should consider when you are writing a program progr am in a language language other than than IBM 4680 BASI BASIC C to run under the the IBM 4690 Ope Operating rating System. System. It contains specific information about programming applications in C language and COBOL. The interfaces interfaces described described in this chapter chapter provide provide access access to many parts of the 4690 Operating Operating Syste System. m. This chapter explains how to use these interfaces.

4690 Operating System Interfaces for C and COBOL The 4690 Operating System interfaces described in this chapter provide access to various 4690 features for applications written in C language or COBOL.

|

The functions described in this chapter can be used only with IBM 4690 store controller applications. However, with the IBM C Programming Interface for 4690 terminals, C applications can be written for a 4690 Terminal. Terminal. See the CAPITPGP.DOC CAPITPGP.DOC included included with with the IBM C Programming Programming Interface Interface for 4690 4690

|

Terminals product for more information.

| |

These functions are written in C language and can be used by applications written in C language and COBOL. The functions functions were compiled compiled usin using gam memory emory model that generat generates es 3232-bit bit ad addresse dresses. s. The memory model model permits permits multiple code code and data data segments. segments. To use these these function functions, s, link with ADXAPACL.L86 ADXAPAC L.L86 located located on the optional optional diskette. Use the search search option to link only the re required quired co code de with ** the application application and not the entire entire library library.. These functions functions wer were e written in MetaWare MetaWare High C. . Any application that is not written in High C also must link with ADXAPABL.L86. |

The parameters parameters are assumed assumed to be passed passed with the first param parameter eter being pu pushed shed last on the stack stack.. The first parameter parameter for most most functions is a four-byte four-byte retur return n code. A negative return return code indicates indicates an error error code. Any nonsystem nonsystem error error codes that may be returned returned by these functions functions ar are e listed with the functi function on descriptions descr iptions.. System error codes are rreturn eturned ed as four-b four-byte yte hexadec hexadecimal imal values. values. Refer to the IBM 4690  Store System: Messages Guide  for   for a complete list list of system error error code codes. s. The conv conversion ersion fu function nction ca can n be used to convert the four-byte hexadecimal bytes to eight printable ASCII characters. The bit numbering scheme numbers the bits right to left with the least significant bit (lsb) being bit zero and the most significant significant bit (msb), (msb), being bit 15. The followi following ng is an example of numbe numbering ring for a two-by two-byte te word. BIT NUMBERING

msb Bits

15

14

13

12

11

10

9

8

7

lsb 6

5

4

3

2

1

0

16-2

4690 Store System: Programming Guide

 

 

Using the C Language Interface Applications written Applications written in C language can be written written in Metaware High High C or an equivalent C language. language. The functions functio ns in this chapter were were tested with Metaware Metaware High C code. The test code was com compiled piled using th the e big memor memory y model. The big memory memo model allows allows multip code and data data segments segmen ts of up toin64K byte bytes s each and creates cre ates 32-bit 32-b it address addresses. es.ryAn application applicat ion multiple using le thes these e functions function s must be compiled the same manner. The assumed sizes of the basic data types used are: char = 1 byte char = int = 2 bytes long = long  = 4 bytes

Using the COBOL Language Interfaces Applications written in COBOL can be written in COBOL/2 * or an equiva equivalen lentt COBO COBOL L languag language. e. The functions functio ns described described here were were tested with COBOL/2 COBOL/2 code. The test code was compiled compiled usin using g the huge memory model and the following compiler directives:        

   

 /NOIBMCOMP  /LITLINK  /VSC2  /OS(FLEXOS)**

An application application using these these functions must must be compiled in the same man manner. ner. The HUGE memor memory y model produces 32-bit addresses and far and far calls . It allows allows lite literal ral na names mes if the c compiler ompiler direc directive tive /LITLINK   /LITLINK  is   is used. The directive /NOIBMCOMP  directive  /NOIBMCOMP  causes   causes the compiler compiler to s store tore data in one one byte binary binary fields. fields. The direc directive tive  /LITLINK   causes causes the compiler to create external references to the literal names of the functions in this chapte cha pter. r. The direct directive ive /VSC2   /VSC2  allows   allows the the use of the the BY VALUE iin n the CALL statemen statement. t. If the app application lication is written in COBOL/2, the directive /OS(FLEXOS) directive /OS(FLEXOS) is  is needed for compatibility with the LINK86 command. If the directive directive OS(FLEXOS) OS(FLEXOS) is not recognized, recognized, a later level level of COBOL/2 is requir required. ed. COBOL/2 re referenc ferences es FAR_DATA FAR_DAT A in the OBJ files and and OS(FLEXOS) OS(FLEXOS) removes removes it. If CBLINK.BAT CBLINK.BAT is used to link ffiles, iles, the message “FAR_DATA FOUND” will be generated 286 file not execute properly. To avoid this problem, NOT edit the file MF_LNK.INP that is and usedthe by resulting CBLINK.BAT andwill remove “,class[FAR_D “,clas s[FAR_DATA,DAT ATA,DATA]” A]” from the data statement. statement. Or you can use LINK8 LINK86 6 with an INP file that does not contain FAR_DATA. For applications applications using using these functions, functions, the usag usage e type, COMP-5, COMP-5, is assumed for nume numeric ric variables. variables. This usage indicates that the value which can be stored for a numeric variable is not limited to the number of decimal digits digits specified specified in the picture clause. clause. The value can be the lar largest gest binar binary y number that can be stored in the indicated space.

The convention for byte length of COBOL numeric variables is: PIC PIC 9(2 9(2)) = 1 byt byte e PI PIC C 9(4 9(4)) = 2 by byte tes s PI PIC C 9(8 9(8)) = 4 by byte tes s In this chapter, some of the descriptions about how to call each function contain a variable that is listed as USAGE IS IS POINTER. POINTER. The address address of this pointer is coded coded BY VALUE in the CALL s statemen tatement. t. These variables variab les are specified specified in this manner manner to allow variati variation on in applications applications and prog programming ramming sty styles. les. The following is an example of how the variables may be defined in a program:

 

16-3

Chapter Chapt er 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

 

01 KFBUFF. 03 KF-KEY PIC 9(8) USAGE IS COMP-5. 03 KF-DAT PIC X(46) USAGE IS DISPLAY. 77 BUFFADR USAGE IS POINTER. PROCEDURE PROCED URE DIVISI DIVISION. ON. SET BUFFADR TO ADDRESS OF KFBUFF. CALL ... ... USING BY VALUE BUFFADR.

Disk File Management Disk media on the 4690 Operating System contain the following: File names

Every file file created o on n a disk must have have a name to identify identify the file. The 4690 Op Operatin erating g System forces all file names to uppercase on the media.

File record size When a file is created, created, the record record s size ize must be spe specified. cified. A record size size of zero is equivalent equiva lent to a record record size of one byte. byte. If a record size size of zero o orr one is spec specified, ified, the IBM 4690 Operating System will not perform record boundary checks when a READ or WRITE is requested.

File  File Ac Acce cess ss Access to files is initiated Access initiated using a CREATE CREATE or an OPEN OPEN operation. operation. Use a CREATE to o open pen a new file. Use an OPEN to gain gain acces access s to an existing existing file. For both operation operations, s, a file name will b be e specifie specified d and a four-byte fourbyte file number number will be returned. returned. The file number is the then n used for all subse subsequent quent oper operations ations on that file. When the the file is closed the file number is deleted. deleted. If the file file is reopene reopened, d, a ne new w numbe numberr is as assigned signed.. The DELETE statement statement removes removes a file from the disk directory directory.. Files to be deleted ar are e indicated indicated by the file name. A file c cannot annot be be deleted deleted when it is read-on read-only ly or iiff it is curren currently tly open open.. A file can can be automatic automatically ally deleted delete d by setting one one of two flag bits when when the file is created. created. One flag bit de determine termines s whether a fi file le is to be treated as temporar temporary y or permanent. permanent. If a file is marked as temporary, temporary, it will be deleted after after the last open is is closed. closed. If a file is marked marked as a permanent permanent file, file, the fil file e will rremain emain after after the last CLO CLOSE. SE. The other other flag bit that may be selected when the file is created determines what action will be taken if a file with the same name name exists. exists. If this fflag lag bit is is set, the the exis existing ting file file will be deleted before the new file is created created.. If this bit is not set, an error will be returned.

Acce Ac cess ss Mo Modes des:: Access modes modes determine determine if a file may be be shared shared.. If the file is sha shared, red, the foll following owing modes are selected when the file is opened:

 Exclusive access by calling process  Allow reads by other processes  Allow reads and writes by other processes

Exclusive Exclus ive access access to a file in one process prevents prevents any other other process fr from om sharing th the e file. Exclusive Exclusive access to a file is denied if another access another process process has has the file open open.. If a process process tries to ope open n a file with WRITE privilege and the file has been opened in ALLOW-READS mode, then the OPEN is denied and an error is returned. ALLOW/READ/WRITE ALLOW/READ/WR ITE mode has two options: options: shared or uniq unique ue file pointer. pointer. The shar shared ed file pointer mod mode e is only available to processes with the same family ID, and all processes in the family must specify this mode. For pr processe ocesses s outside outside the family, the the file appear appears s in exclusiv exclusive e mode. There are no restr restrictions ictions when the unique file pointer option is selected.

16-4

4690 Store System: Programming Guide

 

 

Fi File le Po Poin inte ters: rs: The IBM 4690 Operating System supports both sequential and random access to disk files by using the file pointer. pointer. Sequen Sequential tial file acces access s is supported supported by a file pointer which is incr incremented emented with each read read or write to maintain the position position within the file file.. Random file access access is suppo supported rted by an offset specified specified with each read read or write call. The offset can be specified specified by the file pointer, pointer, the beginning beginning of the file, or the end of the file. The file pointer pointer is initialized initialized to zero when a file is created or op opened. ened. Subseq Subsequent uent READs and WRITEs WRITEs move the file pointer pointer to the byte byte positio position n of the next seq sequential uential lo location. cation. For examp example, le, if a new file is created and 12 bytes are written, the file pointer would be pointing at the 13th byte (essentially the EOF marker). Separate processes sharing access to the same file can share the same file pointer or can have separate ones. File pointer pointer sharing sharing is limited limited to pr processe ocesses s with tthe he same family iidentific dentification ation ((FID) FID) nu number. mber. When the pointer is shared, reads or writes by any process update the file pointer. The seek function can be used to determine the file pointer’s location or to position the file pointer.

 Pipe Manage Pipe Managemen mentt Two or more processes communicate by using a type of filehes known as pipe for which supported through a special devicecan known as  pi :. as pi  :. Creati Creating ng a pipe establis establishes a buf buffer fera used theisde deposit posit and and withdrawal withdra wal of messages. messages. Pipe files ha have ve two ends, ends, one to write int into o and the other tto o read from from.. Messages Messag es are deposited deposited and withdrawn withdrawn from the pipe on a first-in-fir first-in-first-out st-out (FI (FIFO) FO) basis. The pipe length is the only limit to the number of messages you can store in a pipe at one time. :) or a In all calls that require a pipe name, the pipe name must be preceded with the device name ( pi :) logical name may be defined that includes the pi : reference. Use e the CREATE ATE fun function to make a pipe ipe. All pipe ipes are handled in Creatin Crea ting g and D Dele eletin ting g Pip Pipes: es: Us the same manner manner as sequential sequential files. files. The CREATE CREATE parameters parameters are us used ed as follow follows: s:

 Set the flags to reques requestt READ, WRITE, or D DELETE ELETE privilege privileges s and to requ request est the acce access ss mode. The privileges have the same meaning for pipes as they do for disk files.  The pipe name must include the device name, ( pi :) :) plus up to eight eight (8) alphanumeric alphanumeric charac characters. ters. Pipe names are case case sen sensitive. sitive. The default default is lowercase. lowercase. record size parameter parameter controls controls the message message blocks. For example, example, if a record size of four is  The record specified, specif ied, all pipe I/O is conducted conducted in four-b four-byte yte blocks blocks.. Record siz size e of zero or one must be speci specified fied if the application uses the WAIT function with the pipe.  Set the size to the the pipe buffer buffer length. The size is independ independent ent of the mess message age leng length th but must be a multiple of the record size. Use a DELETE to remove remove a pipe. pipe. A pipe that is marked marked as temporary temporary when when it is creat created ed will be automatically dele automatically deleted ted on the last CLOSE. If a pipe marked as temporary temporary is used to comm communicate unicate between between

two processes, the pipe is deleted automatically from the system when the processes terminate because files are automatically closed when a process ends. access privileges privileges are affected affected by existing access access mode modes. s. The followi following ng rules Pi Pipe pe Ac Acces cess: s: Pipe access govern the privileges available:

 A process’ open access is never restricted by an open connection previously made by the same process. WRITE ends of a pipe are conside considered red sepa separate rate with resp respect ect to open restr restrictions ictions.. For  The READ and WRITE example, an OPEN with exclusive READ does not restrict a process from opening a pipe as shared WRITE.  Any exclusive OPEN prevents other access requests to the same end.

 

16-5

Chapter Chapt er 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

 A shared OPEN prevents other exclusive access requests but allows other shared requests to the same end. pointer request request restri restricts cts pipe acces access s to processes processes with the same FID. All proces processes ses  A shared file pointer sharing sharin g the pipe must select the shared shared file pointer pointer mode. A process that that request requests s a different mode is denied access. access. For processes processes outs outside ide the family, the re request quest funct functions ions as an exclus exclusive ive reques request. t. A pipe is used differen differently tly if an end is opened opened in exclu exclusive sive or sh shared ared mod mode. e. If one end of a pipe is o opened pened in exclusive exclusive mode and then then closed, closed, a READ or WRIT WRITE E attempt to the oth other er end res results ults in an EOF er error. ror. It does not matter how the other end was opened. If one end of a pipe is opened in shared mode and then closed, the IBM 4690 Operating System uses the pipe as if it were still open on the other other end. Therefore, Therefore, any process process accessing accessing the pipe wa waits its until the operation opera tion is complete. complete. A pipe opened in shared shared file pointer pointer mode is shared only only by those processes processes with the same same FID. Notice the distinction distinction between shared mode and and shared shared file pointer mode. If one e end nd of a pipe is opened in shared file pointer mode, and then the pipe is closed by all of the processes accessing that end, any processes accessing the other end will receive an EOF error. Interprocess Interproces s Communicati Communications: ons: The READ and WRITE functions operate the same way for pipes as for files and the the READ and WRITE WRITE flags and pa paramete rameters rs are used used in the same way. way. Any numbe numberr of

processes can participate in the exchange. The amount amount of data written written to and read from from the pipe is independe independent nt of the pipe siz size. e. The following following procedures are observed when the amount exceeds the size:

 On WRITEs when the pipe is full, the process waits for another process to read data from the other end. When the reading reading process process removes removes enough to allow the data data to be written, the oper operation ation completes.  On READs when the pipe is empty, the process waits for another process to write data to the other end. The operation operation completes completes when enough enough data has been written written to satisfy the READ request. request. A READ request issued when there is no data in the pipe will cause the process to wait until there is enough enoug h data available available in the pipe to satisfy the read request. request. To avoid a possible possible hang, use the WAIT operation opera tion to wait for a specified specified time. Then the application application can select select whethe whetherr or not to wait again if the time limit expires before data is available to read. Synchronization Synchronizat ion and Exclusion: Exclusion: A pipe may be created with a zero-length buffer size for use as a simple semaphore. semaphore. For se semaphor maphore e pipes, pipes, a READ operation operation obta obtains ins the pipe an and d a WRI WRITE TE releases releases it. it. If another process has obtained the pipe previously, the calling process waits until a WRITE to that pipe has been performed. performed. WRITE operations operations,, on the other hand, nev never er wait; if the pipe was released released previ previously, ously, the call returns without an error. Nondestru Nondes tructi ctive ve Read: Read: The information stored in a pipe can be previewed using the READ operation by setting the specific specific flag bit to request request a nondest nondestructiv ructive e read. This allows allows a pipe to be used as a common

data area among among multiple applicatio applications. ns. It also allows an application application to pre pre-read -read a leng length th field or messag message e type field within within a message message and then read read the comp complete lete message message at a later time. time. To read re records cords o off varying lengths, specify record length of one when the pipe is created so that the operating system will not perform record checking; otherwise, an invalid record size error will be returned. Warning: Nondes Nondestructi tructive ve reads can can be dangerous dangerous if there there are multip multiple le reade readers rs of a pipe. It is the responsibility of the application to handle synchronization of pipe usage when there are multiple processes involved. Pipe Routin Pipe Routing g Servic Services: es: PRS for communicati communications ons between between a store controlle controllerr and a termin terminal. al. The WAIT operation opera tion available available is the same as for regular regular pipes. Pipe Routing Services Services (PRS) (PRS) enables applic applications ations to exchange excha nge data with application applications s in other store controller controllers s or terminals terminals by using pipes. These pipes pipes are

16-6

4690 Store System: Programming Guide

 

 

identified by a pipe ID, which identified which is a letter between between A and Z. Each store store contro controller ller or ter terminal minal can ha have ve up to 26 IDs (A (A through through Z). Each ID ID in a s store tore controll controller er or a termina terminall must b be e uniqu unique. e. For ex example, ample, iiff several several applications are running in a store controller at once, each must use a different pipe ID. On the 4690 store controller controller,, pipes are treated treated like seque sequential ntial files. A PRS pipe must first be cre created. ated. Then the application application should should wait for data to be available available before re requesti questing ng a READ. For PRS pipes in the store controlle controller, r, the READ buffer buffer may be large large but in the terminal terminal the limi limitt is 240 bytes bytes.. The maximu maximum m size for all PRS messages is 120 bytes. To write to a PRS pipe, the PRS driver driver must be initialized. initialized. This initia initializatio lization n must be request requested ed only once for each each load of of an applicatio application. n. After the the driver driver is initializ initialized, ed, a write write can be per performed formed.. All PRS pipes are are temporary. tempor ary. A pipe will be deleted when th the e last last process process tthat hat has has acc access ess to it has ended. The PRS PRS functions described for C language and COBOL can only be used in store controller applications.

File and Pipe Services This section section contains contains examples of C and COBOL interfaces interfaces for keyed, keyed, nonnon-keyed, keyed, and di direct rect files. It also contains examples for pipes.

Create Crea te Poi Point-o nt-of-Sa f-Sale le Keye Keyed d File File:: Crea Creati tin ng a point oint-o -off-sa sale le keye keyed d file file sets sets up the the file file as a keye keyed d file and write the keyed keyed file control control block as the first record. record. See “Keye “Keyed d File Control Record” Record” on page pag e 6-2 6-21 1 for a descr descripti iption on of the the key keyed ed file file contro controll block. block. The file file is op opene ened d if no er error ror o occu ccurre rred. d. The file must be closed if no access is needed. |

 C Int Interf erface ace::

|

void ADX_CCREATE_KFILE(long *fnum, unsigned int flags, char *filename, long filesize, unsigned int *buffadr, long buffsize);

|

 COBOL Interf COBOL Interface  ace 

77 FNUM 77 FLAGS

PIC S9(8) PIC 9(4)

USAGE IS COMP-5. USAGE IS COMP-5.

7*7 FILENnAM=Elength PoIfCFXI(LnE)-NAME incUlSuAdGiEngIS terminating NULL or blank. 77 FILESIZE PIC 9(8) USAGE IS 77 BUFFADR USAGE IS 77 BUFFSIZE PIC 9(8) USAGE IS

DISPLAY. COMP-5. POINTER. COMP-5.

CALL “ADX_CCREATE_KFILE” USING FNUM, BY VALUE FLAGS, BY REFERENCE FILENAME, BY VALUE FILESIZE, BY VALUE BUFFADR, BY VALUE BUFFSIZE.

Parameters: flags   bit 0:

1 = Delete file

bit 1:

0 = No delete Reserved (must be 0)

bit 2:

1 = Write 0 = No write

 

16-7

Chapter Chapt er 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

bit 3:

1 = Read 0 = No read

bit 4:

1 = Shared 0 = Exclusive

bit 5:

1 = Allow low shared comma mmands if shared 0 = Allow shared READ or WRITE commands if shared

bit bit 6 6–7 –7::

Rese Reserrved ved (mu (mus st be be z zer ero) o)

bit 8:

1 = Temporary—delete on last close 0 = Permanent

bit 9 9::

Reserved (m (must be be ze zero)

bit bit 1 10: 0:

1 = De Dele lete te file file if it alre alread ady y exi exist sts s 0 = Return error if file exists

bit 11 to 15: Reserved (must be zero) filename 

filesize 

Address of a NULL or blank terminated name string, or a previously defined logical name. If the file is not in the current current di director rectory, y, the strin string g must inclu include de the path sp specifica ecification. tion. The maximum length is 128 bytes including the NULL or blank. The size must be derived from the following algorithm and rounded up to the nearest 512-byte 512-by te multiple. multiple. The maxi maximum mum size for for a keyed keyed file rec record ord is 508. 508. T = Total number of records L = Logical keyed record size NL = 508 508/L /L (integ (integer er divi divisio sion) n) If (T divide divided d by NL h has as a rema remainde inder) r) size = 512 = 512 + (512 × ( 1 + T/ NL )) Else (no remainder)  512 + (512 × ( size = = 512

T/ NL ))

The total number of records should be at least 20% greater than the maximum number of records expected to account for the way the records must be distributed in the file and to allow for future growth. buffadr 

The address of the buffer containing keyed file information (BUF14 or BUF18 (see bit 11 of pflags)).

buffsize 

The size size of buffer buffer (B (BUF14 UF14 size size = 14. 14. BUF18 size = 18.) 18.) BUF14—Informa BUF14— Information tion buffer buffer for creating creating a keyed file file less than 32MB. 32MB. Size = 14 bytes. bytes.

Figure 16-1 on page page 16-9 illustrates illustrates how how the bytes are a allocate llocated d if th the e buffsize  is   is 14.

16-8

4690 Store System: Programming Guide

 

 

BUF14 Byte 0

pflags

2

numblocks

4

randivsr

6

keyrecl

8

keylen

10

cthresh

12

Reserved

Figure Figur e 16-1. 14-Byte 14-Byte Buffsiz Buffsize  e 

BUF18 – Information buffer for creating a keyed file greater than or equal to 32 megaby meg abytes tes.. Siz Size e = 18 bytes. bytes. Figure Figure 1616-2 2 illus illustra trates tes how the bytes bytes are alloca allocated ted if the buffsize  is   is 18. BUF18 Byte 0

pflags

2

numblocks

6

randivsr

10

keyrecl

12

keylen

14

cthresh

16

Reserved

Figure Figur e 16-2. 18-Byte 18-Byte Buffsiz Buffsize  e 

pflags   bit 0:

1 = Keyed file create

bit 1 to 3:

0 = Reserved (must be zero)

 

16-9

Chapter Chapt er 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

bit 4:

1 = File is mirrored (see note 1) 0 = File is not mirrored

bit 5:

1 = File is compound (see note 1) 0 = File is not compound

bit 6:

0 = Reserved (must be zero)

bit 7:

1 = File is local only (see note 1) 0 = File is not local

bit 8:

1 = Distributed at close (see note 2) 0 = No Distribution at close

bit 9:

1 = Distribution per update (see note 2) 0 = No Distribution per update

bit 10:

Reserved (must be zero)

bit 11 11:

1 = Th This in information s sttructure is is fo for files g grreater than or equal equal to 32 meg megaby abytes tes.. (Se (See e fform ormat at BUF1 BUF18.) 8.) 0 = This information structure is for files less than 32

bit 12:

bits 13 to 15:

megaby meg abytes. tes. (Se (See e format format BUF1 BUF14.) 4.) 1 = The data blocks will not be cleared to NULLs. (If this option is used, the user application must clear all data blocks to NULLs before adding records to the file.) 0 = All data blocks will be cleared to NULLs 0 Reserved Notes: 1. Bits 4, 5, and 7 are mu mutually tually ex exclusive clusive ((only only one of the three types can be chosen). 2. Bits 8 and 9 are mut mutually ually exclusive exclusive ((only only one of the two types can be chosen).

numblocks 

Number of of 512-byte 512-byte phys physical ical re records cords iin n the file. Must be = ffilesize ilesize ((as as calculated previously) / 512.

randivsr 

File randomizing divisor. This must must be greater greater than zero an and d less tha than n numblo numblocks. cks. This val value ue determines how the keyed records are dispersed in the file.

keyrecl 

Logicall keyed record Logica record size. Must be in ran range ge 1 to 508.

keylen 

Length of record key found in logical keyed records.

cthresh 

Chaining Chainin g thresh threshold old v valu alue. e. Mus Mustt be in rang range e 1 to 25 255. 5. The valu value e is th the e number of sectors that are checked to find a keyed record before a warning warnin g is sent that that a file is b becomin ecoming g ineffic inefficient. ient. The app applicatio lication n is not notified that the limit has been exceeded, and data is still returned to the application.

fnum 

Return co Return code. de. It contain contains s the fi file le num number ber ifif no err error or oc occur curred red.. The fi file le is automatically automat ically op opened. ened. The call calling ing process process must must close th the e file if no access is is needed. If an error occurr occurred ed the err error or code will be rreturne eturned d and a file will not  be created. not be

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors.

16-10

4690 Store System: Programming Guide

 

 

Open Op en Ke Keye yed dF Fil ile: e: Th This is oper operat atio ion n open opens s a keye keyed d file file.. |

 C Int Interf erface ace::

void ADX_COPEN_KFILE(long *fnum, unsigned int flags, char *filename, unsigned int *parmbuff, long | pbuffsize);

|

 COBOL Interf COBOL Interface  ace 

77 77 77 * 77 77

FNUM PIC S9(8) FLAGS PIC 9(4) FILENAME PIC X(n) n=leng n=length th of FILE-N FILE-NAME AME incl includi uding ng PARMBUFF PBUFSIZE PIC 9(8)

USAGE IS COMP-5. USAGE IS COMP-5. USAGE IS DISPLAY. term termina inatin tingg NULL NULL or blank. blank. USAGE IS POINTER. USAGE IS COMP-5.

CALL “ADX_COPEN_KFILE” USING FNUM, BY VALUE FLAGS, BY REFERENCE FILENAME, BY VALUE PARMBUFF, BY VALUE PBUFSIZE. Parameters: flags   bit 0:

1 = Delete file 0 = No delete

bit 1:

1 = Execute 0 = No execute

bit 2:

1 = Write 0 = No write

bit 3:

1 = Read 0 = No read

bit 4:

1 = Shared 0 = Exclusive

bit 5:

1 = Allow shared reads if shared 0 = Allow shared read or write if shared

bits 6 to 15:

Reserved (must be zero)

filename 

Address of NULL or blank terminated Address terminated name string string or a previou previously sly define defined d logical name name.. If the file is not in the curren currentt directory, directory, the str string ing must incl include ude the path s specific pecification. ation. The maximum length is 128 bytes, including the NULL or blank.

parmbuff 

User address address where the keyed keyed record size size and key length will be returned. returned. The recor record d

size is in the first two bytes of the buffer and the key length is in the second two bytes of the buffer. buffer. The b buffer uffer must be at lea least st four bytes in siz size. e. If pbu pbufsize fsize = 0, n no o values values wil willl be returned. pbufsize 

Size of parmbuff, parmbuff, in bytes. bytes. If pbufsize pbufsize = 0, no values will will be return returned ed in parmb parmbuff. uff.

fnum 

Return code. It will contain the file number if no error occurr occurred. ed. If an error occur occurred, red, the file will be closed and an error code is returned.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors. This is op oper erat atio ion n clos closes es a ke keye yed d file file an and d free frees s all all asso associ ciat ated ed bu buff ffer er sp spac ace. e. A pa parrtial tial Clos Close eK Keye eyed dF Fil ile: e: Th CLOSE flushes the associated I/O buffer but leaves the file open.

 

16-11

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

|

 C Interf Interface ace::

|

void ADX_CCLOSE_KFILE(long *ret, unsigned int option, unsigned int flags, long fnum)  COBOL Int COBOL Interf erface  ace 

77 77 77 77

RET OPTION FLAGS FNUM

PIC PIC PIC PIC

S9(8) 9(4) 9(4) S9(8)

USAGE USAGE USAGE USAGE

IS IS IS IS

COMP-5. COMP-5. COMP-5. COMP-5.

CALL “ADX_CCLOSE_KFILE” USING RET, BY VALUE OPTION, BY VALUE FLAGS, BY VALUE FNUM. Parameters: option 

0 = close file 1 = zero and close file (only valid for keyed files)

flags 

0 = full close 1 = partial close (flush only)

fnum 

File number of file to be closed, as returned from an OPEN or CREATE.

ret 

Return code. code. An error error code is return returned ed if an error error oc occurre curred. d.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors. This is oper operat atio ion n re read ads s data data from from the the indi indica cate ted d reco record rd in the the spec specif ifie ied d keye keyed d fi file le.. Read Re ad K Keye eyed d Re Reco cord: rd: Th |

 C Interf Interface ace::

|

void ADX_CREAD_KREC(long *nbytes, unsigned int option, long fnum, char *buffadr, long buffsize,   long keylen) long keylen);;

|

Example:  COBOL Int COBOL Interf erface  ace 

77 77 77 77 77 77

NBYTES OPTION FNUM BUFFADR BUFFSIZE KEYLEN

PIC S9(8) PIC 9(4) PIC S9(8) PIC 9(8) PIC 9(8)

USAGE USAGE USAGE USAGE USAGE USAGE

IS IS IS IS IS IS

COMP-5. COMP-5. COMP-5. POINTER. COMP-5. COMP-5.

CALL “ADX_CREAD_KREC” USING NBYTES, BY VALUE OPTION, BY VALUE FNUM, BY VALUE BUFFADR, BY VALUE BUFFSIZE, BY VALUE KEYLEN. Parameters: option 

0 1= = Read Read no andlock lock The record record is locked locked before it is read. read. The application application program program must must wait for the re record cord to become available.

fnum 

16-12

File number number of file from which which to read data. data. The file mus mustt be activated activated by a CREATE or OPEN before requesting a READ.

4690 Store System: Programming Guide

 

 

buffadr 

Address of buffer in which Address which to put data that that is read. The key for tthe he recor record d to read mus mustt begin at offset zero in this buffer.

buffsize 

Number of of bytes to read. read. The size mus mustt equal the record record leng length th specif specified ied when the fil file e was created.

keylen 

Length of the the key string string passed in the the read buff buffer. er. This valu value e must equal equal the key lengt length h specified when the keyed file was created.

nbytes 

Return code. It will contain the number number o off bytes bytes rea read d if n no o err error or oc occurre curred. d. An er error ror code is returned if an error occurred.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors.

Writ Wr ite e Ke Keye yed d Re Recor cord: d: Th This is op oper erat atio ion n writ writes es a keye keyed d re reco corrd in the the spe peci cifi fied ed file file.. |

 C Int Interf erface ace::

void ADX_CWRITE_KREC(long *nbytes, unsigned int option, unsigned int flags, long fnum, char *bufaddr, | long buffsize); |

 COBOL Interf COBOL Interface  ace 

77 77 77 77 77 77

NBYTES OPTION FLAGS FNUM BUFFADR BUFFSIZE

PIC PIC PIC PIC

S9(8) 9(4) 9(4) S9(8)

PIC 9(8)

USAGE USAGE USAGE USAGE USAGE USAGE

IS IS IS IS IS IS

COMP-5. COMP-5. COMP-5. COMP-5. POINTER. COMP-5.

CALL “ADX_CWRITE_KREC” USING NBYTES, BY VALUE OPTION, BY VALUE FLAGS, BY VALUE FNUM, BY VALUE BUFFADR, BY VALUE BUFFSIZE. Parameters: option   bit 0:

0 = Unlock = no 1 = Unlock = yes The record is unlocked after being written.

bit 1:

0 = Do not hold the write 1 = Hold the write The hold flag prevents the data from being physically written to a disk file until

the next write with hold option is issued by this process. bits 2 to 15: Must be zero flags  

Not us Not used ed

fnum 

File number where data is to be written, as returned from a CREATE or an OPEN.

buffadr 

Address of buffer containing Address containing data to write. write. The buffer mus mustt contain the desi desired red record’s record’s key at offset 0.

buffsize 

Number of bytes to write.

nbytes 

Return code. It contains contains the nu number mber o off bytes bytes wri written tten if no er error ror occurr occurred. ed. Notice that a zero (0) return value is a special case for the WRITE with HOLD and is considered a correct corre ct value. An error code code is returned returned if an error error occu occurred. rred.

 

16-13

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors.

Dele De lete te Ke Keye yed d Rec Recor ord: d: Th This is oper operat atio ion n dele delete tes s a spec specif ifie ied d reco record rd from from a keye keyed d file file.. |

 C Interf Interface ace::

|

void ADX_CDELETE_KREC(long *ret, long fnum, char *buffadr, long buffsize);  COBOL Int COBOL Interf erface  ace 

77 77 77 77

FNUM BUFFADR BUFFSIZE RET

PIC S9(8) PIC 9(8) PIC S9(8)

USAGE USAGE USAGE USAGE

IS IS IS IS

COMP-5. POINTER. COMP-5. COMP-5.

CALL “ADX_CDELETE_KREC” USING RET, BY VALUE FNUM, BY VALUE BUFFADR, BY VALUE BUFFSIZE. Parameters: fnum  buffadr  buffsize  ret 

File number of filecontaining containingthe record as returned by an OPEN or CREATE. Address of buffer key to of delete, the record to be deleted. Length of key string pointed to by buffadr . Return code. code. It contains contains an err error or code ifif an error error occu occurred. rred.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors.

Create Point-o Point-of-Sale f-Sale Non-Ke Non-Keyed yed File: Th This is oper operat atio ion n will will crea create te a poin pointt-of of-s -sal ale e nonk nonkey eyed ed file file.. A point-of-sale file is different from any other file because it may be distributed to other controllers as a mirrored mirro red or a compound compound file. file. After the the file is created, created, it will will be ope opened ned if no no error error occu occurred. rred. The file must be closed if no access is needed. |

 C Interf Interface ace::

| |

void ADX_CCREATE_POSFILE(long *fnum, unsigned int flags, char *filename, long filesize, unsigned int recsize, unsigned int ftype, unsigned int fdistrib);

16-14

4690 Store System: Programming Guide

 

 

COBOL COBO L Interf Interface  ace 

77 FLAGS PIC 9(4) USAGE IS COMP-5. 77 FILENAME PIC X(n) USAGE IS DISPLAY. * n = leng length th of of FILE FILE-N -NAM AMEE incl includ udin ingg term termin inat atin ingg 77 77 77 77 77

NULL FILESor IZEblank. RECSIZE FTYPE FDISTRIB FNUM

PIC PIC PIC PIC PIC

9(8) 9(4) 9(4) 9(4) S9(8)

USAGE USAGE USAGE USAGE USAGE

IS IS IS IS IS

COMP-5. COMP-5. COMP-5. COMP-5. COMP-5.

CALL “ADX_CCREATE_POSFILE” USING FNUM, BY VALUE FLAGS, BY REFERENCE FILENAME, BY VALUE FILESIZE, BY VALUE RECSIZE, BY VALUE FTYPE, BY VALUE FDISTRIB. Parameters: flags   bit 0:

1 = Delete file

bit 1:

0 = No delete Reserved (must be zero)

bit 2:

1 = Write 0 = No write

bit 3:

1 = Read 0 = No read

bit 4:

1 = Shared 0 = Exclusive

bit 5:

1 = Allow shared READ commands if shared 0 = Allow shared READ or WRITE commands if shared

bit 6:

1 = Shared file pointer 0 = Unique file pointer

bit 7:

Reserved (must be zero)

bit 8:

1 = Temporary—delete on last close 0 = Permanent

bit 9:

Reserved (must be zero)

bit 10:

1 = Delete file if it already exists 0 = Return error if file exists

bitt 11 to 15 bi 15::

Res Reserve erved d (m (mus ustt be zero) ero)

filename 

Address of NULL or blank terminated Address terminated name string string or a previou previously sly define defined d logical name name.. If the file is not in the curren currentt directory, directory, the str string ing must incl include ude the path s specific pecification. ation. The maximum length is 128 bytes, including the NULL or blank.

filesize  recsize 

File size in bytes The READ, WRITE, and LOCK operations use this value to ensure that the requested action falls falls on record record boundaries. boundaries. Use a record record size of zero zero or one if you do n not ot want boundary checks performed.

 

16-15

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

ftype 

File distribution type 0 = Local only 1 = Mirrored 2 = Compound file

fdistrib 

File distribution method 0 = Distribute at close 1 = Distribution per update

fnum 

Return code. It contains contains the file file nu number mber if no error occur occurred. red. The ffile ile is automat automatically ically opened;; therefor opened therefore, e, the callin calling g proces process s must clos close e the file if no access access is neede needed. d. If an error occurs, the file is closed and the error code is returned.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors.

Create Non-Poi Non-Point-of-Sa nt-of-Sale le F File ile or Pi Pipe: pe: Th This is oper operat atio ion n will will crea create te a nonnon-po poin intt-of of-s -sal ale e fi file le or a pipe. The file is op opened ened if no error error occur occurred red and it should should be clos closed ed if no acces access s is needed needed.. |

 C Interf Interface ace::

|

void ADX_CCREATE_FILE(long *fnum, unsigned int flags,char *filename, long filesize, unsigned int recsize);

|

Example:  COBOL Int COBOL Interf erface  ace 

77 FLAGS PIC 9(4) 77 FILENAME PIC X(n) * n = len lengt gthh of of FIL FILEE-NA NAME ME incl includ udin ingg terminating NULL or blank. 77 RECSIZE PIC 9(4) 77 FILESIZE PIC 9(8) 77 FNUM PIC S9(8) CALL “ADX_CCREATE_FILE” USING FNUM, BY VALUE FLAGS, BY REFERENCE FILENAME, BY VALUE FILESIZE, BY VALUE RECSIZE. Parameters: flags   bit 0:

1 = Delete file

USAGE IS COMP-5. USAGE IS DISPLAY. USAGE IS COMP-5. USAGE IS COMP-5. USAGE IS COMP-5.

0 = No delete

16-16

bit 1:

Reserved (must be zero)

bit 2:

1 = Write 0 = No write

bit 3:

1 = Read 0 = No read

bit 4:

1 = Shared 0 = Exclusive

bit 5:

1 = Allow shared READ commands if shared 0 = Allow shared READ or WRITE commands if shared

4690 Store System: Programming Guide

 

 

bit 6:

1 = Shared file pointer (disk files only) 0 = Unique file pointer

bit 7:

Reserved (must be zero)

bit 8:

1 = Temporary—delete on last close 0 = Permanent

bit 9:

Reserved (must be zero)

bit 10:

1 = Delete file if it already exists 0 = Return error if file exists

bit bit 11 11 a and nd 12: 12:

Reser Reserve ved d ((mu must st be ze zero ro))

bit 13:

1 = Force case to media default (pipes only) 0 = Do not force case on name

bit bit 14 14 a and nd 15: 15:

Reser Reserve ved d ((mu must st be ze zero ro))

Address of NULL or blank terminated Address terminated name string string or a previou previously sly define defined d logical name name.. If the file is not in the curren currentt directory, directory, the str string ing must incl include ude the path s specific pecification. ation. The maximum length length is 128 bytes, bytes, inclu including ding the NULL NULL or blank. The name for a pi pipe pe must

filename

include pi:  either   either in this string or in the logical name definition prefix. recsize

The READ, WRITE, and LOCK operations use this value to make sure that the requested action falls falls on record record boundaries. boundaries. Use a record record size of zero zero or one for fi files les if no boundary checks are desired, or for pipes if the WAIT function will be used.

filesize

File size in bytes

fnum

Return code. It contains contains the fi file le nu number mber if no error occurr occurred. ed. The file is is automatica automatically lly opened and and the callin calling g proces process s must close the the file if no acces access s is needed needed.. If an error occurred, the file is closed and the error code is returned.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors.

Open Op en F Fil ile eo orr Pi Pipe pe:: Th This is oper operat atio ion n will will open open a poin pointt-of of-s -sal ale e nonk nonkey eyed ed fi file le,, nonnon-po poin intt-of of-s -sal ale e file file,, or a pipe. Use Ope Open n Keyed Keyed File o option ption to open a keyed file. The file pointer is initialized initialized to to zero when the file is opened. |

 C Int Interf erface ace::

|

void ADX_COPEN_FILE(long *fnum, unsigned int flags, char *filename);  COBOL Interf COBOL Interface  ace 

77 FNUM

PIC S9(8)

USAGE IS COMP-5.

77 FLAGS PIC 9(4) USAGE IS COMP-5. 77 FILENAME PIC X(n) USAGE IS DISPLAY. * n = leng length th of of FILEFILE-NAM NAMEE inclu includin dingg termi terminat nating ing NULL NULL or blank blank CALL “ADX_COPEN_FILE” USING FNUM, BY VALUE FLAGS, BY REFERENCE FILENAME.

 

16-17

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

Parameters: flags   bit 0:

1 = Delete file 0 = No delete

bit 1:

1 = Execute 0 = No execute

bit 2:

1 = Write 0 = No write

bit 3:

1 = Read 0 = No read

bit 4:

1 = Shared 0 = Exclusive

bit 5:

1 = Allow shared reads if shared 0 = Allow shared R/W if shared

bit 6:

1 = Shared file pointer (disk files only) 0 = Unique file pointer

bit its s 7 to 12:

Reserved ((mu mus st be be z ze ero)

bit 13:

1 = Force case to media default (pipes only) 0 = Do not affect name case

bit 14 and and 1 15: 5:

Re Rese serv rved ed (mus (mustt be be z zer ero) o)

filename 

Address of NULL or blank terminated name string, or a previously defined logical name. If the file is not in the current current di director rectory, y, the strin string g must inclu include de the path sp specifica ecification. tion. The maximum length length is 128 bytes, bytes, inclu including ding the NULL or or blank. The name for a p pipe ipe must include pi:  either   either in this string or in the logical name definition prefix.

fnum 

Return code. It contains contains the the file number if no error occur occurred. red. If an error occurr occurred, ed, the file is closed and the error code is returned.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors. ion closes a fil ile e or a pipe ipe and frees all associated buffer fer space. A Clos Close e Fi File le o orr Pi Pipe pe:: This operation partial CLOSE flushes the associated I/O buffer but leaves the file open. |

 C Interf Interface ace::

|

void ADX_CCLOSE_FILE(long *ret, unsigned int flags, long fnum);

 COBOL Int COBOL Interf erface  ace 

77 RET 77 FLAGS 77 FNUM

PIC S9(8) PIC 9(4) PIC S9(8)

USAGE IS COMP-5. USAGE IS COMP-5. USAGE IS COMP-5.

CALL “ADX_CCLOSE_FILE” USING RET, BY VALUE FLAGS, BY VALUE FNUM.

16-18

4690 Store System: Programming Guide

 

 

Parameters: flags 

0 = Full close 1 = Partial close

fnum 

File number of file to be closed, as returned from an OPEN or CREATE.

ret 

Return code. It contains contains an error error code code if an err error or occu occurred. rred.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors.

Read Rea d Rec Record ord ffrom rom F File ile o orr Pip Pipe: e: Th This is op oper erat atio ion n re read ads s da data ta from from the the in indi dica cate ted d reco recorrd in a specified non-ke specified non-keyed yed file or a pipe file. The file pointer pointer is updated on every every READ to be the byte position immediately following the last data byte that was read. |

 C Int Interf erface ace::

void ADX_CREAD_REC(long *nbytes, unsigned int flags, long fnum, char *buffadr, long buffsize, long | boffset); |

Example:  COBOL Interf COBOL Interface  ace 

77 77 77 77 77 77

NBYTES FLAGS FNUM BUFFADR BUFFSIZE BOFFSET

PIC S9(8) PIC 9(4) PIC S9(8) PIC 9(8) PIC S9(8)

USAGE USAGE USAGE USAGE USAGE USAGE

IS IS IS IS IS IS

CALL “ADX_CREAD_REC” USING NBYTES, BY VALUE FLAGS, BY VALUE FNUM, BY VALUE BUFFADR, BY VALUE BUFFSIZE, BY VALUE BOFFSET. Parameters: flags   bit 0:

1 = Read from device 0 = Read from internal buffers

bit 1:

Reserved (must be zero)

bit 2:

1 = Nondestructive read 0 = Normal read

COMP-5. COMP-5. COMP-5. POINTER. COMP-5. COMP-5.

bits 3 to 7:

Reserved (must be zero)

bits bits 8 and and 9:

Inte Interp rpre reta tati tion on of offs offset et fi fiel eld d 00 = Relative to beginning of file 01 = Relative to file pointer (disk file only) 10 = Relative to end of file (disk file only)

bits bi ts 10 to 15

Res Reserve erved d ((mu must st be zero) ero)

fnum 

File number from which to read data, as returned from OPEN or CREATE.

buffadr 

Address of buffer in which to put data that is read.

buffsize 

Number of bytes to READ.

 

16-19

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

boffset 

Byte offset to begin reading, relative to the position indicated by flag bits 8 and 9. Negative Negativ e offsets are are allowed. allowed. Offset used used for disk files files only; set = 0 for pi pipes. pes.

nbytes 

Return code. It will contain contain the number of bytes bytes read read iiff no error occur occurred. red. Where nbytes  is positive and not equal to buffsize , an end-of-f end-of-file ile was encoun encountered. tered. An err error or code code is returned if an error returned error occurred. occurred. For pipe pipes, s, if the buffer is empty, empty, this op operatio eration n waits for enough data to be written in the buffer to satisfy the read request.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors.

Write a Recor Record d to a F File ile (no (nonkeyed nkeyed)) or Pip Pipe: e: Th This is oper operat atio ion n writ writes es data data into into the the indi indica cate ted d record of a specifie record specified d nonkeyed nonkeyed fil file e or a pipe. See “W “Write rite Keyed Keyed Record” Record” for ke keyed yed file files. s. The file pointer is updated on every WRITE to be the byte position immediately following the last data byte that was written. |

 C Interf Interface ace::

|

void ADX_CWRITE_REC(long *nbytes, unsigned int option, unsigned int flags, long fnum, char *buffadr, long buffsize, long boffset);

|

Example:  COBOL Int COBOL Interf erface  ace 

77 77 77 77 77 77 77

NBYTES OPTION FLAGS FNUM BUFFADR BUFFSIZE BOFFSET

PIC PIC PIC PIC

S9(8) 9(4) 9(4) S9(8)

PIC 9(8) PIC S9(8)

USAGE USAGE USAGE USAGE USAGE USAGE USAGE

IS IS IS IS IS IS IS

COMP-5. COMP-5. COMP-5. COMP-5. POINTER. COMP-5. COMP-5.

CALL “ADX_CWRITE_REC” USING NBYTES, BY VALUE OPTION, BY VALUE FLAGS, BY VALUE FNUM, BY VALUE BUFFADR, BY VALUE BUFFSIZE, BY VALUE BOFFSET. Parameters: option 

0 = Do not hold the write. 1 = Hold the write (not valid for pipes). The Hold flag prevents the data from being physically written to a disk file until the next write with hold option option is issued issued by this process. process. Each rec record ord must be less less than or eq equal ual to 512 bytes in length when using the HOLD option.

flags  

bit bit 0: 0:

1 = Fl Flus ush h buf buffe fers rs afte afterr w wri rite te (dis (disk k fil file eo onl nly) y).. 0 = Do not flush buffers. This forces forces the data to the the media. If this is a zero length length req request, uest, the media media is updated with any pending writes.

bits 1 to 7: Reserved (must be zero). bits 8 and 9: Determine how the offset field is interpreted: 00 = Relative to beginning of file 01 = Relative to file pointer (disk file only) 10 = Relative to end of file (disk file only) bits 10 to 15: Reserved (must be zero)

16-20

4690 Store System: Programming Guide

 

 

fnum 

File number where data is to be written, as returned from an OPEN or CREATE.

buffadr 

Address of buffer containing data to write.

buffsize 

Number of bytes to write.

boffset 

Offset into file file to start writing, writing, dep depending ending on bi bits ts 8 and 9 of flags. Offset is us used ed for disk fil files es only; set = 0 for pipes.

nbytes 

Return code. It will contain the number number of bytes bytes tra transferr nsferred ed if no er error ror occurr occurred. ed. Note that that a zero (0) return value is a special case for the WRITE with HOLD and is considered a correct valu value. e. Wh Wher ere e nbytes  is   is positive and not equal to buffsize , an end-of-media (disk or diskette full) condition condition exists. exists. For pipes pipes,, if the buffer is full this operat operation ion will wait until enou enough gh is read from the other other end to allow allow the WRITE to complete. complete. An error code code is returned returned if an err error or occurred.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors.

Lock Loc k an and dU Unlo nlock ck R Reco ecord: rd: Ac Acce cess ss to re reco cord rds s in a nonk nonkey eyed ed fi file le are are cont contro rolllled ed by sele select ctiv ivel ely y locking and unlocking locking unlocking the record. record. LOCK the reco record rd before reading reading it, then UNLOCK UNLOCK the record afte afterr writing to it. The area area to lock lock or unlock is determined determined from the the offse offsett and ho how w it is used. used. This op operatio eration n is only valid for disk files. |

 C Int Interf erface ace::

|

void ADX_CLOCK_REC(long *ret, unsigned int flags, long fnum, long boffset, long nbytes);  COBOL Interf COBOL Interface  ace 

77 77 77 77 77

FLAGS FNUM BOFFSET NBYTES RET

PIC PIC PIC PIC PIC

9(4) S9(8) S9(8) S9(8) S9(8)

USAGE USAGE USAGE USAGE USAGE

IS IS IS IS IS

COMP-5. COMP-5. COMP-5. COMP-5. COMP-5.

CALL “ADX_CLOCK_REC” USING RET, BY VALUE FLAGS, BY VALUE FNUM, BY VALUE BOFFSET, BY VALUE NBYTES. Parameters: flags   bits 0 and 1:

Lock Mode 00 = Unlock—release the indicated area 01 = Exclusive lock—prevents other processes from locking, reading

from, or writing to the locked area 10 = Exclusive write lock—allows other processes to read the area but not to write to it or lock it 11 = Shared write lock—allows other processes to read the area and establish shared write lock but not to write to the area bits 2 and bits and 3: bit 4:

Res Reserve erved d ((mu must st be zero) ero) 1 = Return error on lock conflict 0 = Wait on lock conflict

bits 5 to 7:

Reserved (must be zero)

 

16-21

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

bits bits 8 and and 9:

Inte Interp rpre reta tati tion on of offs offset et fi fiel eld d 00 = Relative to beginning of file 01 = Relative to the pointer 10 = Relative to the end of file

bits bits 10 to 15: 15:

Re Rese serv rved ed (m (mus ustt be be zer zero) o)

fnum 

File number of file containing record to lock or unlock, as returned by a CREATE or OPEN.

boffset 

Offset of of region region to loc lock k in fil file. e. See bits 8 and 9 in flags flags..

nbytes 

Length of region to lock, in bytes

ret 

Return code. code. An error error code is return returned ed if an if error error occurre occurred. d.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors.

Dele De lete te Fi File le o orr Pi Pipe pe:: Th This is oper operat atio ion n will will dele delete te the the desi design gnat ated ed fi file le or pipe pipe.. |

 C Interf Interface ace::

|

void ADX_CDELETE_FILE(long *ret, unsigned int flags, char *filename);  COBOL Int COBOL Interf erface  ace 

77 77 * 77

FLAGS PIC 9(4) USAGE IS FILENAME PIC X(n) USAGE IS n = leng length th of of FILEFILE-NAM NAMEE inclu includin dingg termi terminat nating ing RET PIC S9(8) USAGE IS

COMP-5. DISPLAY. NULL NULL or blank. blank. COMP-5.

CALL “ADX_CDELETE_FILE” USING RET, BY VALUE FLAGS, BY REFERENCE FILENAME. Parameters: flags 

1 = Force case to media default (pipes only). 0 = Do not affect name case.

filename 

Address of NULL or bla Address blank nk termina terminated ted name string string or a prev previously iously de defined fined logical logical name. If the file is not in the curren currentt directory, directory, the string string must inclu include de the path spe specificat cification. ion. The maximum length length is 128 bytes bytes includ including ing the NULL or blank. blank. The name for a pipe pipe must include pi:   either either in this string or in the logical name definition prefix.

ret 

Return code. code. An error error code is return returned ed if an if error error occurre occurred. d.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors.

Rena Re name me a Fi File le:: The rename operation changes the the name of an existi istin ng disk fil file. If the file is currently open by another currently another process, process, the file is not renamed renamed and an error code code is returned. returned. If the new file name specifies specifies another another directory, directory, the file is moved to that location. location. This featur feature e is limited to directo directories ries on the same drive. drive. Attributes, Attributes, ownership, ownership, protection protection and date date stamps are not cha changed. nged. |

 C Interf Interface ace::

|

void ADX_CRENAME_FILE(long *ret, char *filename, char *newname);  COBOL Int COBOL Interf erface  ace 

16-22

4690 Store System: Programming Guide

 

 

77 * 77 * 77

FILENAME PIC X(n) USAGE IS DISPLAY. n = lengt lengthh of FILE FILE-NA -NAME ME incl includi uding ng termi terminat nating ing NULL NULL or blan blank. k. NEWNAME PIC X(m) USAGE IS DISPLAY. m = leng length th of of NEW-N NEW-NAME AME includ including ing termin terminati ating ng NULL NULL or blan blank. k. RET PIC S9(8) USAGE IS COMP-5.

CALL “ADX_CRENAME_FILE” USING RET, BY REFERENCE FILENAME, BY REFERENCE NEWNAME. Parameters: filename 

Address of NULL or blank terminated string containing the current name of the file (Max length = 128 including NULL)

newname 

Address of NULL or blank terminated string containing the new name for the file (Max length = 128 including NULL)

ret 

Return code. It will contain contain an er error ror code code if an error error occu occurred. rred.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors. This is oper operat atio ion n ei eith ther er retu return rns s or chan change ges s the the fi file le poin pointe terr Seek See k (Cha (Change nge o orr Get Fi File le Po Point inter): er): Th position for the specified position specified file. To get the current current pointer position, position, selec selectt the Relative to file pointe pointerr option in flag bits 8 and 9 and and specify a an n offset of 0. Any other combinat combination ion of values values for flag bits 8 and and 9 and the offset cause cause a change in the file pointer pointer position. position. For all calls, calls, a positive retur return n value indica indicates tes the curr current ent file pointer position. The offset value value can be positive or negative. negative. An error is ret returned urned,, however, if the new poin pointer ter position position is less than 0. If the file consists consists of multibyte multibyte records, records, the off offset set must fall on a re record cord bou boundary. ndary. |

 C Int Interf erface ace::

|

void ADX_CSEEK_PTR(long *pposit, unsigned int flags, long fnum, long boffset);  COBOL Interf COBOL Interface  ace 

77 77 77 77

PPOSIT FLAGS FNUM BOFFSET

PIC PIC PIC PIC

S9(8) 9(4) S9(8) S9(8)

USAGE USAGE USAGE USAGE

IS IS IS IS

CALL “ADX_CSEEK_PTR” USING PPOSIT, BY VALUE FLAGS, BY VALUE FNUM, BY VALUE BOFFSET.

COMP-5. COMP-5. COMP-5. COMP-5.

Parameters: flags   bits 0 to 7:

Reserved (must be zero)

bits bits 8 and and 9:

Det Deter ermi mine ne how how the the off offse sett fiel field d is in inter terpr pret eted ed 00 01 = = Relative Relative to to beginning file pointerof file 10 = Relative to end of file

bits bits 10 to 15: 15:

Re Rese serv rved ed (m (mus ustt be be z zer ero) o)

fnum

File number as returned from an OPEN or a CREATE.

boffset

Number of bytes relative to reference selected in flag bits 8 and 9.

 

16-23

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

Return code. code. It contains the the current current position position of the file pointer pointer after th the e call or an err error or code if an error occurred.

pposit

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors.

Change Cha nge Fil File eA Attri ttribut butes: es: Th This is op oper erat atio ion n will will ch chan ange ge disk disk file file attr attrib ibut utes es to en enab able le a fi file le to be distributed. To use this opera distributed. operation, tion, the file must be open on the sto store re controller controller with owne ownership rship of the file. The master controll controller er owns compound compound files and the master master file serve serverr owns mirrored mirrored files. After the attributes have been changed at least one record in the file must be written so that the operating system will mark the file for distributi distribution. on. If the file has never been been distributed distributed or if there is curre currently ntly no copy on the other store controllers, the receiving store controllers must be IPLed for the file to be distributed. |

 C Interf Interface ace::

|

void ADX_CCHANGE_ATTRIB(long *ret, long fnum, unsigned int ftype, unsigned int fdistrib, long recsize);  COBOL Int COBOL Interf erface  ace 

77 FNUM

PIC S9(8)

USAGE IS COMP-5.

7777 77 77

PPIICC PIC PIC

UUSSAAGGEE USAGE USAGE

FFDTIYSPTERIB RECSIZE RET

99((44)) 9(8) S9(8)

IISS IS IS

CCOOMMPP--55.. COMP-5. COMP-5.

CALL “ADX_CCHANGE_ATTRIB” USING RET, BY VALUE FNUM, BY VALUE FTYPE, BY VALUE FDISTRIB, BY VALUE RECSIZE. Parameters: fnum 

File number returned by a create or an open.

ftype 

0 = Local only file 1 = Mirrored file 2 = Compound file

fdistrib 

0 = Distribute at close 1 = Distribute Per Update

recsize 

Size of record, as specified when the file was created

ret 

Return code. code. An error error code is return returned ed if an error error oc occurre curred. d.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors.

|

Cancel Can celing ing tthe he Sha Shared red Us Use e of a Fil File: e: ADX_CFI CFILES cancels the the shared use of a fil ile e such as the the

|

transaction log. Without transaction Without the use of ADX_CFILES, ADX_CFILES, a shared file cannot cannot be renamed or deleted deleted becau because se it is in use by more than one user.

| | | | | | |

Some of the conditions that can cause file sharing problems are incomplete transactions, terminal hardware hardw are failures, failures, incomplete controller controller functions, functions, and software failures. failures. ADX_CFILES ADX_CFILES provides the following functions to manage the canceling of shared file usage:

   Restricting a file for exclusive use    Unrestricting a file that was restricted    Determining despool status

16-24

4690 Store System: Programming Guide

 

 

| | |

ADX_CFILES ADX_CFI LES Rest Restric rict: t: ADX_CF ADX_CFILES ILES restrict restrict forces forces the excl exclusive usive use o off a single file. This func function tion is intended to be used only for store closing procedures and should not be used as a general purpose function.

|

ADX_CFILES restrict function causes all applications currently using that file to lose their access to that file until they have have closed and reopened reopened the file. When an application application attem attempts pts to use a file that has been restricted, restr icted, the file request request is rejected rejected and a new return code code is returned. returned. In the control controller ler the retur return n code is 80F306F0. 80F306F0. In the terminal, terminal, the first terminal terminal access to a restri restricted cted file rece receives ives a 80F306 80F306F0 F0 and subsequent subseq uent accesses accesses (by the sam same e or other terminals) terminals) receive receive a 80004007 80004007 (bad file numbe number). r). When an application has a file open and receives either of these return codes for a file request, it should close and reopen that file.

|

   Purpose:

| | | | | |

| | | |

To restrict restrict the use of a file by all other applications. applications. The restrict restrict applies to application applications s on all controllers contro llers and all terminals. terminals. To restrict restrict the use of a mirrored or compound compound file you re restrict strict the prime prime version versi on of the file on the file server or master master respectively respectively.. You cannot use restrict restrict for a distribute-o distri bute-on-clos n-close e type file. After a file is restricted: restricted:

|

 – It cannot be opened by any application. applicati on.

| |

 – An application appli cation that is using a file that is i s restricted by another application must m ust close and reopen a file to use the file again.

| | | | | | | | |

   Restrictions:  – Only one ADX_CFILES to restrict a file can be active at a time.  – To restrict a file on a file server or a master tthe he controller application executing executi ng the restrict must be connected to the active file server or master.  – To restrict a mirrored file or compound file an applicati application on must restrict tthe he prime version of the fifile. le.  – A distribute-on-close dist ribute-on-close type file cannot be restricted.

   Location of usage:  – Any application appli cation on any controller.  – It cannot be used by a terminal application.

|

 C Int Interf erface ace::

|

void ADX_CFILES(long *ret, unsigned int func, char *filename);  COBOL Interf COBOL Interface  ace 

This function is currently not supported for COBOL. Parameters:

ret 

= 4-byte integer that indicates the status of the restrict function hi lo  xx xx yy yy 

= Indicates how the file was being used when the restrict was executed: xxxx = Number of other controller applications that were using this file when it was restricted. yyyy = Number of controllers where terminal applications were using this file when it was restricted. 0000 = No other application has the file open.

80 F3 06 F4  = Application attempted to restrict a file while another restrict is active. 80 F3 06 F5  = Application attempted to restrict a distribute-on-close file. 80 F3 06 F6  = Application attempted to restrict the file on the wrong node.  

16-25

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

8x xx xx xx  -1201 -1203 

= Any other operating system error return code. = Invalid function code used for the FUNC values defined for ADX_CFILES. = FILENAME is not defined.

-1204  -1205 

= FILENAME not a valid name. = Force Closeissupport is notfileinstalled.

func 

= 1 (This is the rrestric estrictt funct function ion cod code e for ADX_CFIL ADX_CFILES.) ES.)

filename 

= String containing containing the the file name of the fil file e to be restr restricted. icted. The name ma may y be a logical name or a fully-qualif fully-qualified ied file name. name. To reference reference a mirrored mirrored or co compound mpound fil file e use the generic node names for the file server and the master:

 for file server use ADXLXACN::  for master use ADXLXAAN:: Note: When an application attempts to use a file that has been restricted, you receive either an 80F306F0 80F306 F0 or an 80004007. The error recovery recovery should should provide a delay and retry mechanism mechanism because because the file remains restricted until it is unrestricted by the application. ADX_CFILES ADX_CF ILES Unrest Unrestric rict: t: ADX_CFI ADX_CFILES LES unr unrestric estrictt stops the effect of tthe he ADX_C ADX_CFILES FILES restrict. restrict. The unrestrict is requested for the same file name that was used for the restrict even if the file was renamed while it was restricted. restricted. After the unrestric unrestrictt is executed that file nam name e may be used by all applications applications again.

   Purpose: To unrestrict unrestrict the use of a file that had been previously previously res restricted tricted.. To unrest unrestrict rict the use of a Mirror Mirrored ed or Compound file, unrestrict the prime version of the file on the File Server or Master respectively. After a file is unrestricted:  – The file fil e name can be used to open files fil es according to tthe he normal guidelines.  – An application applicat ion that lost access to a file due to restrict must issue a CLOSE fol followed lowed by an OPEN after the unrestrict is issued to gain access to the file again.    Prerequisites: The application executing the unrestrict ADX_CFILES must have executed the restrict ADX_CFILES.    Restrictions: If an application is unrestricting a file on a file server or a master, the controller executing the application must be connected to the active file server or master.

 Location of usage:  – Any application applicati on on any controller.  – It cannot be used by a terminal appl application. ication.

| |

 C Interf Interface ace::

 void ADX_CFILES(long *ret, unsigned int func, char *filename);  COBOL Int COBOL Interf erface  ace 

This function is currently not supported for COBOL. Parameters: ret 

= 4-byte integer that identifies the unrestrict status. hi lo  00 00 00 00  = Unrestrict is successful.

16-26

4690 Store System: Programming Guide

 

 

80 F3 06 F2  80 F3 06 F3  8x xx xx xx  -1201

= = = =

Application attempted to do an unrestrict without doing a restrict. Application attempted to unrestrict a file that it did not have restricted. Any other OS error return code. Invalid function code.

-1203  -1204  -1205 

= = FILENAME FILENAME is is not not defined. a valid file name. = Force Close support is not installed.

When an unsuccessful unrestrict is executed because of a LAN failure (80 60 xx xx ), ), the application applic ation should should wait 30 seconds and and retry the unrestrict. unrestrict. This shoul should d be repeated for a total of 7 executions of unrestrict. func 

= 2 (This is the unrestrict function code for ADX_CFILES.)

filename 

= String containin containing g the file name of the file file to be restricted. restricted. The name ca can n be a logical name or a fully fully qualifie qualified d file name. To reference reference a mirrored mirrored or co compound mpound fil file e use the generic node names for the file server and the master store controller:

 For file server use ADXLXACN::  For master use ADXLXAAN:: ADX_CFILES ADX_CFI LES Despoo Despool: l: ADX_CFILES despool determines how many total bytes of data remain in all the spool files and and how many controllers controllers have have spool files. By using this function function the applic applications ations can determine that the store personnel should be notified that a store closing must be delayed and can give the store personnel an idea of the length of the delay.

   Purpose: This function function determines determines the status of the operating operating sys system tem despooling despooling of files. This function function determines how many bytes of data are yet to be despooled and how many controllers have data in their spool spool files to be despooled. despooled. The values de determine termined d by this function are are probabl probably y differen differentt than the sizes of the spool files because the size of the spool files are not set to zero until all the data has been despooled from them.    Prerequisites: None currently identified.    Restrictions: This function can only determine despool status for controllers that are currently in session with this controller on the LAN.

 Location of Usage:  – Any application appli cation on any controller.  – It cannot be used by a terminal application.

|

 C Int Interf erface ace::

|

void ADX_CFILES(long *ret, unsigned int func, char *filename);

|

 COBOL Interf COBOL Interface  ace 

|

This function is currently not supported for COBOL.

|

Parameters:

|

RET 

= 4-byte integer that specifies the despool status.

|

hi

lo 

|

0w xx yy yy  = where:  

16-27

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

w

|

= Status of LAN communications. 0 = All controllers are communicating with this controller. 8 = One or more controllers are not communicating with this   controller.

| | |

= Number of communicating controllers with data to despool.

|

xx

|

yyyy = Total number of bytes (in 1000s ) of data to be despooled by yyyy =   controllers controllers communicating communicating..

|

|

00 00 00 00  = The system supports LAN and there is no despooling to do, or the system does not support LAN.

|

8x xx xx xx 

= Indicates any operating system error return code:

|

-1201

= Function code is not valid.

|

-1205 

= System supports LAN but Force Close support is not installed.

|

|

FUNC 

= 3 This is the despool despool function function code for ADX_CFILES ADX_CFILES..

|

FILENAME 

= Unused Unused;; the value value is igno ignored red..

Pipe Routing Services Pipe pe Ro Rout utin ing g Se Serv rvic ices es pipe pipes s are are crea create ted d for for excl exclus usiv ive, e, Create a Pi Pipe pe Ro Routing uting Servic Services es Pi Pipe: pe: Pi READ mode only. |

 C Interf Interface ace::

|

void ADX_CPRS_CREATE(long *pnum, long psize, char *pipeid);  COBOL Int COBOL Interf erface  ace 

77 PNUM 77 PSIZE 77 PIPEID

PIC S9(8) PIC 9(8) PIC X

USAGE IS COMP-5. USAGE IS COMP-5. USAGE IS DISPLAY.

CALL “ADX_CPRS_CREATE” USING PNUM, BY VALUE PSIZE, BY REFERENCE PIPEID. Parameters: psize  pipeid  pnum 

Pipe size, size, in bytes. The maximum maximum size for store store controller controller pipe is 65,536 65,536 byte bytes. s. One alphabetic character (A to Z) to identify the pipe. Return code. code. It will be the pipe identifier identifier or or an error code code if the cre create ate was uns unsuccess uccessful. ful.

The unique unique error codes are ““-1000 -1000 Invalid pipe id” id” and and “-1001 “-1001 Pipe alread already y exists.” exists.” R Refer efer to IBM 4690  Store System: Messages Guide  for   for system errors.

Read from a Pipe Routing Services Pipe |

 C Interf Interface ace::

|

void ADX_CPRS_READ(long *nbytes, long pnum, char *buffadr long buffsize);  COBOL Int COBOL Interf erface  ace 

16-28

4690 Store System: Programming Guide

 

 

77 77 77 77

NBYTES PNUM BUFFADR BUFFSIZE

PIC S9(8) PIC S9(8) PIC 9(8)

USAGE USAGE USAGE USAGE

IS IS IS IS

COMP-5. COMP-5. POINTER. COMP-5.

CALL “ADX_CPRS_READ” USING NBYTES, BY VALUE PNUM, BY VALUE BUFFADR, BY VALUE BUFFSIZE. Parameters: pnum  buffadr  buffsize  nbytes 

Pipe identifier returned from pipe routing services CREATE. Buffer to receive data Number of bytes to read Return code. code. It will contain contain the number of of bytes rea read d or an erro errorr code if an err error or occurred.

Refer to the IBM the IBM 4690 Store System: Messages Guide  for   for system errors. The e Pi Pipe pe Rout Routin ing g Se Serv rvic ices es Driv Driver er mu must st be init initia ialilize zed d Initialize Initi alize Pipe R Routing outing Service Driver: Th before app lication n can write to a pipe routing services services pip pipe. e. It should be initialized initialized only once once for each load of an an applicatio application. |

 C Int Interf erface ace::

|

void ADX_CPRS_INIT(long *prsnum);  COBOL Interf COBOL Interface  ace 

77 PRSNUM

PIC S9(8)

USAGE IS COMP-5.

CALL “ADX_CPRS_INIT” USING PRSNUM. Parameters: prsnum 

Return code. code. It will contain contain the PRS identifier identifier or an error error code if an e error rror oc occurre curred. d.

 IBM 4690 Store System: Messages Guide  for   for system errors. Refer to the the IBM

 

16-29

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

Write to a Pipe Routing Services Pipe |

 C Interf Interface ace::

|

void ADX_CPRS_WRITE(long *ret, long prsnum, char *buffadr, long buffsize, char *dest);  COBOL Int COBOL Interf erface  ace 

77 77 77 77 77

RET PRSNUM BUFFADR BUFFSIZE DEST

PIC S9(8) PIC S9(8) PIC 9(8) PIC X(4)

USAGE USAGE USAGE USAGE USAGE

IS IS IS IS IS

COMP-5. COMP-5. POINTER. COMP-5. DISPLAY.

CALL “ADX_CPRS_WRITE” USING RET, BY VALUE PRSNUM, BY VALUE BUFFADR, BY VALUE BUFFSIZE, BY REFERENCE DEST. Parameters: prsnum  buffadr 

PRS identifier returned from ADX_CPRS_INIT Buffer containing data to write

buffsize 

Number of bytes to write

dest 

Destination Destina tion address address (whe (where re to send data). data). It contains contains four char characters acters in th the e form aaaw . The aaaw  indicates   indicates which te terminal rminal or or store c control ontroller ler to send send the dat data a to. The w  part   part of the destination address is the pipeID for a pipe routing services pipe created by an application applica tion execu executing ting in the specified specified store controller controller or terminal. terminal. For termin terminals, als, aaa  is  is the terminal terminal number number in ASCII. For store store con controller trollers, s, it is 0xy  where   where 0  is   is an ASCII zero, x  and y  are   are ASCII character characters s between C and Z Z.. There are are two specia speciall values for 0xy  for  for store controllers: 0AA 0AA and  and 0BB . Use 0AA 0AA when  when the destination is the master store controller and use 0BB  when   when the destination is the store controller where the calling application applica tion is execu executing ting (in the local store store controll controller). er). Pipe routi routing ng services services transla translates tes these special destination addresses so that the application does not need to define the actual address address assigned assigned to the the physic physical al machine. machine. If the operating operating syste system m switche switches s destinations when a configuration changes, PRS will translate the change and no change is required for the application because of the switch.

ret 

Return code. code. Table 16-1 shows the retu return rn codes for the Pipe Routing Services Services function. function.

Table Tab le 1616-1. 1. Pipe Pipe Rou Routin ting g Service Services s Ret Return urn Codes  Codes  Return Code

Description

0

Good completion.

-1010

Invalid destination specified.

-1011

Destination not found.

-1012

Error on write to destination.

-1013

Data greater than 120-byte maximum.

Conditional Write to a Pipe Routing Services Pipe |

 C Interf Interface ace::

|

void ADX_CPRS_CWRITE(long *ret, long prsnum, char *buffadr, long buffsize, char *dest);

16-30

4690 Store System: Programming Guide

 

 

COBOL COBO L Interf Interface  ace 

77 RET 77 PRSNUM 77 BUFFADR

PIC S9(8) PIC S9(8)

USAGE IS COMP-5. USAGE IS COMP-5. USAGE IS POINTER.

7777 BDUEFSFTSIZE

PPIICC 9X((84))

UUSSAAGGEE IISS CDOIMSPP-L5A.Y.

CALL “ADX_CPRS_CWRITE” USING RET, BY VALUE PRSNUM, BY VALUE BUFFADR, BY VALUE BUFFSIZE, BY REFERENCE DEST. Parameters: prsnum 

PRS identifier returned from ADX_CPRS_INIT

buffadr 

Buffer containing data to write

buffsize 

Number of bytes to write

dest 

Destination address Destination address (where (where to send data). It contains fou fourr characters characters in the form aaaw . The aaaw  indicates   indicates the termin terminal al or store controll controller er to which send send the data. The w  part   part of the destination address is the pipe ID for a pipe routing services pipe created by an application executing execu ting in the specified specified sto store re controller controller or te terminal. rminal. For terminals, terminals, aaa  is   is the terminal number in ASCII. ASCII. For store store controllers, controllers, it is 0xy  where   where 0  is   is an ASCII zero, x  and   and y  are   are ASCII characters chara cters between between C and and Z. There a are re two special special values values for 0xy  for   for store controllers: 0AA and 0BB . Use 0AA 0AA when  when the destination is the master store controller and use 0BB  when   when the destination is the store controller where the calling application is executing (in the local store controller) contr oller).. Pipe routing routing services tra translates nslates thes these e special destination destination addr addresses esses so that the application applic ation does not need need to define the actual ad address dress ass assigned igned to the phys physical ical machin machine. e. If the operating system switches destinations when a configuration changes, PRS translates the change and no change is required for the application because of the switch.

ret 

Return code. Table 16-2 contains contains return return codes codes for the the Cond Conditional itional Write to Pipe Routing Services Pipe function.

Tabl Table e 16-2 16-2.. Retur Return n Code Codes s for Cond Condit itio iona nall Wr Writ ite e to a Pipe Pipe Ro Routi uting ng Servi Service ces s Pipe  Pipe  Return Code

Description

0

Good completion occurred.

-1

Destination pipe is full or does not ha have enough space available in the pipe to hold the data written.

|

-1010

The specified destination specified is not valid.

|

-1011

Destination is not found.

|

-1012

Error on write to destination.

|

-1013

Data greater than 120-byte maximum

|

Usage: This write is is similar to ADX_CPRS_ ADX_CPRS_WRITE WRITE with the the following e exceptio xception: n: If the destination destination pipe is full or does not have enough room left to contain the entire message written, the write does not wait for

|

room to become available. available. Instead, Instead, the a applicat pplication ion is given given control control immediat immediately ely with a -1 return return c code. ode. At this point the application must make a decision to either discard the data being written or retry the write at a later time. The intended use for the conditional pipe write is for situations where it is undesirable for an application to wait for an extended period of time.

 

16-31

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

Communica Commu nications tions Servi Services ces The following application interfaces are described in the IBM the IBM 4690 Store Store Syste System: m: Communi Communicati cations  ons  Programming Reference : ADX_COPEN_LINK ADX_COPEN_SESS   ADX_COPEN_SESS ADX_CCLOSE_LS ADX_CREAD_HOST ADX_CWRITE_HOST ADX_CGET_STAT ADX_CSEND_REQ

Open communications link Open se sess ssio ion n Close communications link or session Read data from link or session Write data to link or session Obtain status from link or session Requests to the driver

 Specializ Specia lized ed Ser Servic vices es The Specialized Services function provide a variety of functions for controller applications written in C langua language ge and CO COBOL. BOL. For backg backgrou round nd inform informatio ation, n, see Ch Chapte apterr 15 for a de descr scripti iption on of these these servic services es for BASIC applications.

Operatorr Author Operato Authorizatio ization: n: This authorization function can be used to create and maintain authorization records that enable operators to sign on and use the system. This authorization function is only valid for store controller applications written in C language and COBOL. If the authorization authorization function function requested requested is change change or add, the user will be prompted prompted for input. When the add or change is complete, the screen will be cleared and the cursor will be enabled and returned to the home position. |

 C Interf Interface ace::

|

void ADX_CAUTH(long *ret, int func, char *opid, char *password, char *opid2);  COBOL Int COBOL Interf erface  ace 

7777 77 77 77

FRUENTC OPID PASSWORD OPID2

PPIICC PIC PIC PIC

9S(94()8) X(9) X(8) X(19)

UUSSAAGGEE USAGE USAGE USAGE

IISS IS IS IS

CCOOMMPP--55.. DISPLAY. DISPLAY. DISPLAY.

CALL “ADX_CAUTH” USING RET, BY VALUE FUNC, BY REFERENCE OPID, BY REFERENCE PASSWORD, BY REFERENCE OPID2.

Parameters: func 

Action to be taken: 1 = 2 = 3 =

CHANG CHANGE Ea an n ope opera rato torr a auth uthor oriza izati tion on re reco cord rd ADD an oper operato atorr auth author oriz izat ation ion re reco cord rd DELET DELETE E an an ope opera rator tor auth author oriz izat ation ion re reco cord rd

8 = 9 =

CHAN HANGE PASSWOR SWORD D only MAKE ope operat rator or ID have have the same same autho authoriz rizatio ation na as s the the op opera erator tor ID s spec pecifie ified d by by opid2 opid2.. If opid2 does not exist, a new ID is created with limited (default) authorization. 10 = MAKE WIT WITH H CHECK CHECK—same —same as as 9 except except opid2 opid2 has template ID and author authority ity ID. Authorization for new ID may not be higher than authority ID even if the template authorization is higher.

16-32

4690 Store System: Programming Guide

 

 

opid 

Operator ID on which action Operator action is to be taken. taken. This ID should should be an ASCII string string of up to nine chara characters. cters. If the ID is less than nin nine e char characters acters it must be term terminated inated with a blank blank or a NULL. This parameter parameter should should h have ave no leading blanks. blanks. Leadin Leading g blan blanks ks and and zer zeros os ar are e cou counted nted as part of the ID.

password  Password Password for for ID. The passwor password d is an an ASCII ASCII string string of up to eight c charact haracters. ers. If the string is less than eight eight characters characters it must be terminated terminated with a blank or NULL. This parameter parameter shou should ld have no leading leading blan blanks. ks. Leading Leading zeros ar are e counted as as part of the pas password sword.. opid2 

Current operator ID for functions 1, 2, 3, and 8 or template ID for functions 9 and 10, depending depen ding on action action requested. requested. This ID may be up to ni nine ne ASCII char characters acters and and it must be terminated termin ated with a blank blank or NULL if it is less than than nine cha characte racters. rs. However However,, if the action to be taken is MAKE WITH CHECK, opid2 must have the template ID of up to nine characters, then a colon, and then the current operator ID of up to nine characters terminated with a blank or NULL if either ID is less than nine nine characte characters. rs. There sh should ould be no leading or imb imbedded edded blan blanks. ks. Leading blanks and zeros are counted as part of the ID.

ret 

Return code Return code.. It will will contain contain a neg negati ative ve in integ teger er if a an n error error oc occur curred red.. Ref Refer er to T Tabl able e 1616-3 3 on page 16-34 for a list list of er error ror co codes. des.

every system system should should be author authorized ized for all s system ystem func functions. tions. The defau default lt Note: At least one ID on every authorization all authorization allows ows the operator operator to sign on and select select only primary or se secondar condary y applicati applications. ons. The current operator ID making a change to a record cannot be the same as the operator ID being changed.

 If the action to be taken is ADD or CHANGE, the system displays several screens to select the system functions that can be used. The current functions current operat operator or (opid2 (opid2)) can select only those those functio functions ns for which the current operator ID is authorized.  If the action to be taken is a CHANGE for an ID that does not exist, the ID is added using default authorization and error code -1010 is returned.  If the action to be taken is an ADD for an ID that already exists, the action is handled as a CHANGE and error code -1010 is returned.  If the action to be taken is MAKE or MAKE WITH CHECK, an ID can be added using a template in opid2 without without having to select select each syste system m function from the various various scre screens. ens. The author authorization ization allowed will will be the same as the the template. template. For a MAKE WITH WITH CHECK, the authoriza authorization tion will onl only y include includ e functions for which which both the template template ID and the curren currentt operator ID hav have e authoriz authorization. ation. If opid2 is missing, or for MAKE WITH CHECK if either part is missing, error code -1011 is returned and the default authorization is used as the template. Table 16-3 o on n page 16-34 shows tthe he retu return rn cod codes es re returned turned by this function. function.

 

16-33

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

Table Tab le 16-3 16-3.. Fun Functio ction n Return Return Cod Codes  es  Error Code

Description

0

Function completed successfully.

-1000 -1001

Unknown function code. File not found.

-1002

Error reading or writing the disk.

-1003

OPID missing or not valid.

-1004

Password missing or not valid.

-1005

OPID2 missing or not valid.

-1010

One of these conditions exists:

 Add function was handled as change because ID already exists.  Change function was handled as an add because ID was not found.  Delete requested for ID that was not found. -1011

Functio tion handled as re req queste ted d usi sin ng default authorization because OPID PID2 not fou found.

-1020

Could not allocate memory for ID search.

For any system errors that are returned, refer to the IBM the  IBM 4690 Store System: Messages Guide .

Passwo Pas sword rd Enc Encrypt ryption ion:: This function function encrypts encrypts an eight-cha eight-character racter A ASCII SCII pass password. word. The IBM 4690 Operating System uses Operating uses one-way encrypte encrypted d passwords passwords for authorization authorization to sign sign on to the system. The encryption method can also be used by an application to establish authorization for use of applications, data files, or other things that need access controlled by the application. |

 C Interf Interface ace::

|

void ADX_CCRYPT(long *ret, char *pwin, char *pwout);  COBOL Int COBOL Interf erface  ace 

7777 PRWEITN 77 PWOUT

PPIICC XS(98()8) PIC X(8)

UUSSAAGGEE IISS DCIOSMPPL-A5Y.. USAGE IS DISPLAY.

CALL “ADX_CCRYPT” USING RET, PWIN, PWOUT. Parameters: pwin 

Password Passwo rd to be encrypted. encrypted. Must be terminated terminated with a NULL NULL or blank if le less ss than

eight characters. pwout 

Encrypted value returned.

ret 

Return code code = 0 indicates encryption encryption completed. completed. If PWIN is blank or has a leading leading blank, erro errorr code -1100 is returned.

The password password to be encrypted encrypted should be an ASCII ASCII string of up to eight alphanumeric alphanumeric characte characters. rs. This parameter can have no leading blanks. parameter blanks. Trailing Trailing blanks blanks are ignored. ignored. Leading Leading zero zeros s are counted as part part of the password. password. The encrypted encrypted value returned returned in PWOUT is an eight-character eight-character strin string g of ASCII characters that represents decimal digits.

16-34

4690 Store System: Programming Guide

 

 

Common Commo n Appl Applicatio ication n Serv Services ices ((ADX_CS ADX_CSERVE): ERVE): Th This is func functi tion on can can be ca call lled ed from from a stor store e controller application to request one of the application services. The parameters here are slightly different from those described for ADXSERVE. |

 C Int Interf erface ace::

|

void ADX_CSERVE(long *ret, int funcnum, char *databuff, int dbuffsize);  COBOL Interf COBOL Interface  ace 

77 77 77 77

RET FUNCNUM DATABUFF DBUFFSIZE

PIC S9(8) PIC 9(4) PIC 9(4)

USAGE USAGE USAGE USAGE

IS IS IS IS

COMP-5. COMP-5. POINTER. COMP-5.

CALL “ADX_CSERVE” USING RET, BY VALUE FUNC-NUM, BY VALUE DATA-BUFF, BY VALUE DBUFF-SIZE. Parameters: funcnum  databuff  dbuffsize  ret 

Function number for the service requested. Buffer for data sent to service requested or for data received from service requested. Size (bytes) of data-buff or data for requested service if data-buff is not used. Return code code values vary vary with the service service requested. requested. An error cod code e is returned if an err error or occurred.

Speciall error Specia error codes codes a are re rretur eturned ned.. See Tab Table le 1515-7 7 on page page 15-18 15-18 for for a list list of the ret return urn cod codes. es. For any system errors that are returned, refer to the IBM the  IBM 4690 Store System: Messages Guide . The e foll follow owin ing g is a li lis st of the the Ap Appl plic icat atio ion n Application Appli cation Service Services s for C C-langua -language ge and COBOL: Th Services available Services available when ADX_CSERVE ADX_CSERVE is called. called. The function function number and the re required quired dat data, a, if any, are listed for each service. Dump Sys Dump System tem Sto Storag rage: e: The Dump System Storage function causes all of the storage in the controller to be dumped to a disk disk file named named ADXCSLCF ADXCSLCF.DAT .DAT in the root root directory. directory. Both the app applicatio lication n and the operating system storage are dumped.

This function uses the following parameters: FUNC-NUM   = 1 DATA-BUFF   = Un Unus used ed

DBUFF SIZE  

Unus Unused ed

Enable Termin Terminal al Storage Storage Retention: Retention: This function enables storage retention in all of the terminals on the TCC Network of the store controller requesting the enable.

The Enable Terminal Storage Retention function uses the following parameters: FUNC-NUM   = 2 DATA-BUFF   = Un Unus used ed DBUFF-SIZE   = Unus Unused ed Disable Terminal Terminal St Storage orage Retention: Retention: This function disables storage retention in all of the terminals on the TCC Network of the store controller requesting the disable.

The Disable Terminal Storage Retention function uses the following parameters:

 

16-35

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

FUNC-NUM   = 3 DATA-BUFF   = Un Unus used ed DBUFF-SIZE   = Un Unus used ed Get Ap Applicati plication on Status Stat us Info Informat Get Application Status Information returns controller contr oller applicatio application n status. status . rmation: See ion: “Get Applica AThe pplication tion Status Status Information” Inform ation” o on n page function 15-19 fo for r the format forthe matstore of the data returned.

This function uses the following parameters: FUNC-NUM   = 4 DATA-BUFF  = Address of buffer to receive status information DBUFF-SIZE  = 80 bytes Programma Progra mmable ble Power Power:: The programmable power function allows terminal or controller applications to issue program calls to enable or disable the programmable power feature, and to issue program calls to power OFF a terminal or controller.

This function uses the following parameters: FUNC-NUM   5 DATA-BUFF  Eight-byte buffer containing:  Two-byte integer set to 5 (for function 5) Two-byte te integer integer specifying specifying subfunction. subfunction. Valid values are 1, 2, 3, 4, or 5. 5. These values  Two-by correspond to PARM5 values on ADXSERVE. Four-byte byte pointe pointerr to a character string. string. The character character stri string ng pointed to by this poin pointer ter  Fourcan have these valid formats:   –  DDHHMM  DDHHMM where: where: DD  = The day of the month (01-31). HH  = The hours of the day (00-24). MM  = The minutes of the hour (00-59).   –  DDHHMMTTT  DDHHMMTTT where: where: DD  HH  MM  TTT 

= = = =

The The The The

day of the month (01-31). hours of the day (00-24). minutes of the hour (00-59). terminal number (001-999).

  –  DDHHMMCC  DDHHMMCC where: where: DD  = The day of the month (01-31). HH  = The hours of the day (00-24).

MM  = The minutes of the hour (00-59). CC  = The controller ID (CC through ZZ). DBUFF-SIZE  = Size of the DATA-BUFF (eight bytes). Display Application Application Status Status Messag Message: e: The Display Application Status Message function displays the specified message on the WINDOW CONTROL screen in the description field of the window for the application that called this function.

This function uses the following parameters: FUNC-NUM   = 25 DATA-BUFF  = Address of buffer containing message to display DBUFF-SIZE  = Size (bytes) of message, (maximum = 79 bytes.)

16-36

4690 Store System: Programming Guide

 

 

Display Backgrou Background nd Applic Application ation Status Status Message: Message: The Display Background Application Status Message function displays the specified message on the BACKGROUND APPLICATION CONTROL screen scree n in the message field of the requesting requesting backgrou background nd applica application. tion. The messa message ge is displaye displayed d until the message is changed or the application ends.

This function uses the following parameters: FUNC-NUM   = 26 DATA-BUFF  = Address of buffer containing message to display DBUFF-SIZE  = Size (bytes) of message, (maximum = 46 bytes). Stop Application Application with Message: Message: The Stop Application with Message function displays the specified message messag e on the WINDOW CONTROL CONTROL screen used used to start the application. application. The messa message ge appear appears s after the application application is stopped. stopped. This function function provides provides a way to indicate problems problems that are preventing preventing an application from running properly.

This function uses the following parameters: FUNC-NUM   = 27 DATA-BUFF  = Address of buffer containing message to display DBUFF-SIZE  = Size (bytes) (bytes) of message. message. Maximum = 79 bytes. Get Disk Free Free Space Space:: The Get Disk Free Space function returns the free space on the specified remote or local local disk disk driv drive. e. Example Example:: local local = C:\, C:\, non-l non-loca ocall = AD ADXLN XLNX Xnn N::C:\ N::C:\ (where nn  =   = store controller ID). Count of characters should be exact, not general size of DATA-BUFF.

This function uses the following parameters: FUNC-NUM   = 28 DATA-BUFF  = Address of buffer containing the node name (if non-local) and the drive, or a logical name for the node &/or the drive DBUFF-SIZE  = Number Number of characte characters rs in name. name. Maximum = 127 bytes. bytes. Get Configured Configured Control Controllers lers on tthe he Network: Network: The Get Configured Controllers on the Network function returns return s the IDs IDs for all all of the the store contro controllers llers on on the network. network. Each ID is two b bytes ytes lo long. ng. Store c controll ontroller er IDs range from from CC through ZZ. If there are less than than 20 controllers, controllers, 00 (ASCII zer zeros, os, not numeri numeric) c) indicates the end of the list.

This function uses the following parameters: FUNC-NUM   = 29 DATA-BUFF  = Address of buffer to receive the list of store controllers. DBUFF-SIZE  = 40 bytes

Get The Control Controller ler ID fo forr a Specified Specified Terminal: Terminal: The Get The Controller ID for a Specified Terminal function functio n returns the store store controller controller ID for the specified specified terminal. terminal. The ID is returne returned d in the RET parameter as ASCII value CC through ZZ or X '0' if the terminal terminal was not not define defined. d. These values values a are re returned returned on only ly if the store controller requesting the ID is the master store controller or if the terminal is local to the store controller.

 

16-37

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

This function uses the following parameters: FUNC-NUM   = 30 DATA-BUFF   = Un Unus used ed DBUFF-SIZE  = Terminal number for which the ID is requested Convert ASCII Char Convert Character acters s to EBCDIC Cha Characte racters: rs: This function converts ASCII characters to EBCDIC characters. chara cters. The characters characters are changed changed byte by byte, therefor therefore e the original chara characters cters are no longer present when the function completes the conversion.

This function uses the following parameters: FUNC-NUM   = 31 DATA-BUFF  = Address of buffer containing ASCII characters to convert DBUFF-SIZE  = Number of characters to convert Convert EBCDIC Cha Convert Characte racters rs To ASCII Cha Characte racters: rs: This function converts EBCDIC characters to ASCII characters. chara cters. The characters characters are changed changed byte by byte, therefor therefore e the original chara characters cters are no longer present when the function completes the conversion.

The function uses the following parameters: FUNC-NUM   = 32 DATA-BUFF  = Address of buffer containing EBCDIC characters to convert DBUFF-SIZE  = Number of characters to convert Set/Reset/Query Set/Reset/Qu ery Terminal Terminal Dump Preservat Preservation ion Flag: This function lets you set, reset, and query the terminal termin al dump preservation preservation flag. Setting the preservati preservation on flag prevents a terminal terminal dump from being written to the terminal terminal dump file. Resetti Resetting ng the prese preservatio rvation n flag allows a dump to be written to the file. The query request returns the status of the preservation flag.

A return code code of 1 indicates indicates that the preserv preservation ation flag is ON. ON. A return code code of 0 indica indicates tes that the preservation flag is OFF. If the user logical name ADXTDUMP has not been created to enable the Terminal Dump Preservation Function, you will receive a return code of -1022 if you try to access this function. This function uses the following parameters: FUNC-NUM   = 33 DATA-BUFF   = Un Unus used ed DBUFF-SIZE  = Specify one of the following: 0 To tu turn rn off off the tterm ermina inall dump preser preservat vation ion fl flag ag

1 To Tu Turn rn on the termi terminal nal dump dump p pres reserv ervatio ation n flag 2 To que query ry wh whether ether the terminal terminal d dump ump preserv preservation ation fflag lag is ON or OFF Get Loop Loop Mess Message age:: This function gets the three most recent system messages for the store loop or token-ring tokenring adapter adapter specified in DATA-BUFF. DATA-BUFF. DATA-BUFF DATA-BUFF is a string consisting consisting of node (for example, CD), TCC Network (1 or 2), and three TCC Network messages.

The node and the TCC Network must be the first three characters of the string when the ADX_CSERVE function functio n is called. When the ADX_CSERVE ADX_CSERVE function function retur returns, ns, the three most recent recent messa messages ges will follow the node and TCC Network Network in the string. string. If no messages exist exist for the specified specified node and TCC Netwo Network, rk, blanks will be returned returned for the messages messages.. The oldest oldest m message essage will be be put in the buffer first. Each message messag e is 133 characters characters long. The function uses the following parameters:

16-38

4690 Store System: Programming Guide

 

 

FUNC   = 34 DATA-BUFF  = Address of the buffer DBUFF-SIZE  = 402 bytes Ge Get t Loo Loop p Stat Status us: This in function returns the configuration and current status of the two loop adapters. Data is returned in: RET the form WWXXYYZZ    (hex) where:  (hex)

ZZ  YY  XX  WW 

= = = =

First adapter configuration First adapter status Second adapter configuration Second adapter status

The configuration is defined as: 00 01  01  02  02  04 80

= = = = =

Not used Pr Prim imar ary y Se Seco cond ndar ary y 2400 bps loop Auto resume of primary loop control

The status is defined as: 03  03  04  04  05  05 

= St Stan andb dby y = Contro Controllin lling g = Pr Prev even ented ted

The function uses the following parameters: FUNC-NUM   = 35 DATA-BUFF  = Unused; the value is ignored. DBUFF-SIZE  = Unused; the value is ignored. Get All Active Active Controlle Controllers rs on the Network: Network: This function returns the IDs of all active store controllers on the network. network. Each ID ID is ttwo wo byt bytes es long. long. A stor store e controller controller ID of 00 ind indicates icates the en end d of tthe he list. list.

The function uses the following parameters: FUNC-NUM   = 36 DATA-BUFF  = Address of buffer to receive IDs DBUFF-SIZE  = 40 bytes Get Controller Controller ID and and Loop for a Specified Specified Terminal Terminal:: The data returned in RET is two bytes for the loop ID followed followed by the two bytes bytes for the the store control controller ler ID. A X'01' is returned if the terminal number

cannot be found. Note: The RET is valid only if this function is issued at the master store controller. The function uses the following parameters: FUNC-NUM   = 37 DATA-BUFF  = Address of buffer containing terminal number DBUFF-SIZE  = 2 bytes

 

16-39

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

Get the Controller Controller Machine Machine Mode Modell and Type: Type: This function returns the store controller model number and type. type. The fun function ction u uses ses the followin following g parameters parameters::

FUNC-NUM   = 38 DATA-BUFF  = Eight-byte integer containing:  2-byte integer set to 38 (for function 38) integer specify specifying ing subfunction subfunction 1. The val valid id value iis s 1.  2-byte integer  4-byte pointer pointer to a 44-byte byte buffer. buffer. The buffer pointed pointed to by th this is pointe pointerr should ha have ve a length leng th of four four by bytes tes.. It con contain tains s the ma machi chine ne model model and and type. type. For exam example ple,, for a 4693-541, the values returned are X'F8' X '3E' X '00' X '00'. DBUFF-SIZE  Size of the DATA-BUFF (8 bytes).

|

Check the the Master Master or File Server Except Exception ion Log: This function returns whether or not there are any entries in the exception log.

|

This function uses the following parameters:

|

RET 

|

| | | | | | | |

= One of the following values: 0 = No entries in the exception log 1 = Entries exist in the exception log 8xxxxxxx = Error code indicating why the status of the exception log can not be obtained. FUNC   = 39 PARM1 Specify one of the following values: 1 = Check the Master exception log 2 = Check the File Server exception log PARM2   = Un Unus used ed

Set Terminal Terminal Sl Sleep eep Mode Inactiv Inactive e Timeout: Timeout: This function allows an application running in a store controller contr oller to set the Terminal Terminal Sleep Mode Inactive Inactive Timeout. Timeout. When you enable enable Termina Terminall Storage Retention, you set this value to determine how many minutes a terminal will remain idle before being powered-down.

function is supported supported only on the store controller controller.. In order for the sle sleep ep mode inacti inactive ve timeout Note: This function to take effect, you must must invoke this fun function ction befor before e enabling the Terminal Terminal Stor Storage age Retenti Retention. on. You may also specify the terminal sleep mode inactive timeout by selecting the Enable Terminal Storage Retention option on the TERMINAL TERMINAL FUNCTIONS FUNCTIONS screen. screen. The default default for the terminal sleep sleep mode inactive inactive timeout is 30 minutes. This function uses the following parameters: FUNC-NUM   = 41 DATA-BUFF  = 2-byte buffer containing a two-byte integer specifying the terminal sleep mode

 inactive  inacti ve time timeou out. t. Va Valid lid va valu lues es are are 0 throu through gh 255. 255. Yo You u can can us use e a 0 va valu lue e to dis disab able le  the terminal sleep mode. DBUFF-SIZE  = Size of the DATA-BUFF (2 bytes).

Starting Startin ga B Backgrou ackground nd Appli Application: cation: Th This is op oper erat atio ion n ca can n be ca call lled ed from from an ap appl plic icat atio ion n writ writte ten n in C and COBOL to start start a background background applicatio application n on the 4690 Operating Operating S System. ystem. The abili ability ty to set a priority level for the background priority background application application is included. included. This function function is valid only for store controll controller er applications. applic ations. See “ADX “ADXSTART” START” on on page 15-6 fo forr a descr description iption of starting starting as backgroun background d applic application ation fro from m a CBASIC application. |

 C Interf Interface ace::

|

void ADX_CSTARTP(long *pid, char *bacappl, char *parms, int parmlen, char *initmsg, int imsglen, int cpriority);

|

16-40

4690 Store System: Programming Guide

 

 

COBOL COBO L Interf Interface  ace 

77 BACAPPL 77 PARMS 77 PARMLEN

PIC X(22) PIC X(46) PIC 9(4)

USAGE IS DISPLAY. USAGE IS DISPLAY. USAGE IS COMP-5.

7777 77 77

PPIICC PIC PIC

UUSSAAGGEE USAGE USAGE

IINMISTGMLSEGN CPRIORITY PID

X9((446)) 9(4) S9(8)

IISS IS IS

DCIOSMPPL-A5Y.. COMP-5. COMP-5.

CALL “ADX_CSTARTP” USING PID, BACAPPL, PARMS, BY VALUE PARMLEN, BY REFERENCE INITMSG, BY VALUE IMSGLEN, BY VALUE CPRIORITY.

 

16-41

Chapter Chap ter 16. Designing Designing Applicatio Applications ns with Other Languages Languages

 

 

Parameters: bacappl  Background Background applicatio application n name. The name must must be terminated terminated with a NULL o orr a blank. Maximum length = 22 characters including the ending blank or NULL. parms 

Parame Parameter ter listastothe be first passed to backgroun backand ground d applicati application. Note the in system automatica automatically lly passes BACKGRND parameter appends theon. parameters PARMS.

parmlen  Length of parameter parameter list. list. Maximum length = 46 characte characters. rs. initmsg 

The initial message to be displayed on the BACKGROUND APPLICATION CONTROL screen when the application is started.

imsglen  Length of of the initial initial message. message. Maximum length length = 46 charac characters. ters. cpriority  Value for setting setting priority. priority. May be from 1 to 9. This value value iis s added added to 1 195 95 to give th the e pri priority ority 196 to 204. The recommen recommended ded value value is is 5 to yield priori priority ty 200 200.. A lower value will aff affect ect ot other her applications that may be running with a different priority. pid 

Return code. code. It will be the process process ID or an er error ror if an error error occu occurred. rred.

Table 16-4 sho shows ws unique unique error codes codes that you you may recei receive: ve: Table 16-4. Error Codes  Error Code

Description

-1170

Application name missing or not valid.

-1171

All background application list entries are in use.

-1172

Maximum number of ba background applications al already active.

-1175

Invalid parameter.

-1176

Internal error.

-1177

Specified priority out of range.

For any system errors that are returned, refer to the IBM the  IBM 4690 Store System: Messages Guide . This is func functi tion on ca can n be ca call lled ed from from a stor tore cont contro roll ller er app ppli lica cati tion on writ writte ten n in C or Logg Lo ggin ing g an Erro Error: r: Th COBOL to log an error in the applicatio application n error log. See “ADXERROR “ADXERROR (Application (Application Even Eventt Logging)” Logging)” on page 15-29 for for a description description of logging logging an error error from a BASIC applicatio application. n. The func function tion will llook ook for a file file of error message messages s to display along along with the unique unique data. data. These messages messages sh should ould be in file ADXCSOZF.DAT ADXCSOZ F.DAT in the form specified. specified. The application application name is auto automatical matically ly include included d in the log entry. There is no return code for this function.