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 page vii.

Third Edition (July 1996)

This edition applies to Version 1 Release 2 of the licensed program IBM 4690 Operating System, program number 5696-538, and to
all subsequent releases and modifications until otherwise indicated in new editions. Changes are made periodically to the
information herein.
Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the
address given below.
A form for readers comments is provided at the back of this publication. If the form has been removed, address your 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 . . . . . . . . . . . . . . . .
Terminal Models . . . . . . . . . . . . . . . . . . .
Where to Find More Information . . . . . . . . . .
Store System Related Publications Software
Store System Related Publications Hardware
General Publications . . . . . . . . . . . . . . .
Summary of Changes . . . . . . . . . . . . . . . .

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

vii
vii
viii
viii
viii
ix
ix
ix
x
xii
xiii

Part 1: The IBM 4690 Operating System Environment

Chapter 1. The IBM 4690 Operating System Environment
. . . . . . . . . . . . . . . . . . . . . . . .
System Capabilities
Concurrent Operations . . . . . . . . . . . . . . . . . . . . . . .
Operator Interface . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the Signon Screen . . . . . . . . . . . . . . . . . . .
Communications . . . . . . . . . . . . . . . . . . . . . . . . . .
Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
Problem Determination Aids
Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additional Products . . . . . . . . . . . . . . . . . . . . . . . . .
Store Controller Backup . . . . . . . . . . . . . . . . . . . . . .

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

Chapter 2. Managing Files . . . . . . . . . . . . . . . . . . . . . . . . .

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. Programming Terminal I/O Devices

2x20 Displays . . . . . . . . . . . . . . . . . . . . .
Shopper Display . . . . . . . . . . . . . . . . . . .
Video Display . . . . . . . . . . . . . . . . . . . . .
Cash Drawer Driver . . . . . . . . . . . . . . . . .
Coin Dispenser Driver . . . . . . . . . . . . . . . .
I/O Processor . . . . . . . . . . . . . . . . . . . . .
Magnetic Stripe Reader Driver . . . . . . . . . . .
Printer Driver Model 2 . . . . . . . . . . . . . . . .
Printer Driver Model 3 or 4 . . . . . . . . . . . . .

Copyright IBM Corp. 1994, 1996

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

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

1-1
1-1
1-1
1-2
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
3-48
3-60
3-67

iii

Magnetic Ink Character Recognition Support for Printers Model 3 and 4

Fiscal Printer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scale Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Serial I/O Communications Driver . . . . . . . . . . . . . . . . . . . . . .
Tone Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Totals Retention Driver
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 4. Using Error Recovery Procedures and Facilities
Error Recovery Options . . . . . . . . . . . . . . . . . . . . . . .
Error Functions and Statements . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
Logging System Errors
Audible Alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Distribution Exception Log . . . . . . . . . . . . . . . . . . . . . .
Power Line Disturbance Recovery . . . . . . . . . . . . . . . . .
Storage Retention . . . . . . . . . . . . . . . . . . . . . . . . . .
Terminal Power ON/OFF . . . . . . . . . . . . . . . . . . . . . .
Disk and File Error Recovery . . . . . . . . . . . . . . . . . . . .
Error Recovery for I/O Devices . . . . . . . . . . . . . . . . . . .

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

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

Chapter 5. User Application Considerations with a LAN (MCF Network)

Using TCLOSE to Close Application Data Files . . . . . . . . . . . . . . . . .
Application Read Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Spool Files on a LAN (MCF Network) System . . . . . . . . . . . . . . . . . .
. . . . . . . . .
Effects of Activating the Alternate File Server on Despooling
Record Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Application Program Interface (OS/2) . . . . . . . . . . . . . . . . .
Using the Application Program Interface (DOS) . . . . . . . . . . . . . . . . .

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

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
5-1
5-1
5-1
5-2
5-3
5-4
5-4
5-6

Part 2: Utilities
Chapter 6. Using the Keyed File Utility
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 . . . . . .
Hashing Algorithms . . . . . . . . . . . . .
Internal Processes of Keyed Files . . . .

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

Chapter 7. Using the Input Sequence Table Build Utility

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 Library Utility
Using LIB86 Command-Line Options . . . .
Creating a Library File . . . . . . . . . . . . .
Appending an Existing Library . . . . . . . .
Replacing Library Modules . . . . . . . . . .
Deleting Library Modules . . . . . . . . . . .
Selecting Modules . . . . . . . . . . . . . . .
Displaying Library Information
. . . . . . . .
Accessing Files in Other Directories . . . . .

iv

4690 Store System: Programming Guide

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

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

6-1
6-2
6-2
6-4
6-10
6-10
6-12
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 the Linker Utility and the POSTLINK Utility

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 . . . . . . . . . . . . . . . . . . . . . .
Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The POSTLINK Utility . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 10. Using the Print Spooler Utility
Obtaining Job Status after a TCLOSE . . . .
Issuing a Command to the Print Spooler . .
Using Special Commands . . . . . . . . . . .
Error Return Codes for the Print Spooler . .

|
|
|
|
|
|

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

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

Chapter 12. Using the Loop Status Application Utility

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

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

Chapter 11. Using the Disk Surface Analysis 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 Recover Data
Using the Time Frame Indicators . . . . . . . . . . . . .
Case Examples of Disk Recovery . . . . . . . . . . . .

Chapter 13. Using the Staged IPL Utility

Requirements . . . . . . . . . . . . . . . . .
Capabilities . . . . . . . . . . . . . . . . . .
Application Interface . . . . . . . . . . . . .
Loading Terminal Storage . . . . . . . . . .
Messages . . . . . . . . . . . . . . . . . . .
ASM History File . . . . . . . . . . . . . . .

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

9-1
9-2
9-3
9-4
9-4
9-11
9-12
9-12
9-12
9-15
10-1
10-1
10-2
10-3
10-5
11-1
11-1
11-1
11-3
11-4
11-4
11-7
11-8
11-8

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

12-1

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

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

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

Chapter 14. Using the Multiple File Archiver Utility

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 Files . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Codes . . . . . . . . . . . . . . . . . . . . . . . .

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

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

Part 3: Applications (Designing and Using)

Chapter 15. Designing Applications with IBM 4680 BASIC
Types of Applications . . . . . . . . . . . . . . . . . . . . . . .
Application Size . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Priorities . . . . . . . . . . . . . . . . . . . . . . . .
Starting a Background Application . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
System Authorization

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

15-1
15-2
15-3
15-5
15-6
15-8

Contents

Communicating between Applications

Using Application Services . . . . .
Chaining Applications . . . . . . . .
RAM Disk Files . . . . . . . . . . . .

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

Chapter 16. Designing Applications with Other Languages .

4690 Operating System Interfaces for C and COBOL . . . . . . .
Guidelines and Restrictions for Assembly Language Applications
Chapter 17. Using IBM DOS Applications . . .
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 . . . . . . . . . . . . . . . . .
Emulator Messages . . . . . . . . . . . . . . . . .

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

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

15-11
15-17
15-30
15-31
16-1
16-2
16-48
17-1
17-1
17-2
17-3
17-3
17-3
17-4
17-6
17-6

Appendixes
Appendix A. IBM 4690 Operating System Disk Directory
Protecting the IBM 4690-Provided Subdirectories . . . . . .
Naming Conventions for 4690 Operating System Files . . .
Dictionary of 4690 Operating System Files . . . . . . . . . .
Appendix B. Error Messages
LIB86 Error Messages . . . . .
POSTLINK Error Messages . .
LINK86 Error Messages . . . .

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

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

Appendix C. Character Sets and Check Printing Application

Example of a Normal Width Character Set . . . . . . . . . . . . .
Example of a Double Width Character Set . . . . . . . . . . . . .
Example Application for Printing Checks on the Model 2 Printer
Glossary
Index

vi

A-1
A-1
A-2
A-3
B-1
B-1
B-4
B-8

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

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

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

X-1

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

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

4690 Store System: Programming Guide

X-23

Notices
References in this publication to IBM products, programs, or services do not imply that IBM intends to
make these available in all countries in which IBM operates. Any reference to an IBM product, program,
or service in this publication is not intended to state or imply that only IBMs product, program, or service
may be used. Any functionally equivalent product, program, or service that does not infringe any of IBMs
intellectual property rights may be used instead of the IBM product, program, or service. Evaluation and
verification of operation in conjunction with other products, programs, or services, except those expressly
designated by IBM, are the users responsibility.
IBM may have patents or pending patent applications covering subject matter in this document. The
furnishing of this document does not give you any license to these patents. You can send license
inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue
THORNWOOD, NY 10594 USA.

Trademarks
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:
AS/400
Display Manager
NetView
Personal System/2
System/370
XT

C/2
IBM
Operating System/2
PS/2
Systems Application Architecture

COBOL/2
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 1The IBM 4690 Operating System Environment
Chapter 1 contains an overview of the 4690 Operating System environment and describes the
system capabilities, terminal models, and problem determination aids.
Chapter 2 describes how you can manage your files. It provides information on naming files and
subdirectories, and performing file functions.
Chapter 3 contains information on programming terminal input/output (I/O) devices.
Chapter 4 provides information on error recovery procedures and facilities. This information
includes error recovery options, logging system errors, and storage retention.
Chapter 5 describes options you should consider when using an application with a local area
network (LAN).
Part 2Utilities
Chapter 6 describes the Keyed File Utility (KFU) and provides instructions for using the utility.
Chapter 7 describes the input sequence tables and provides example worksheets for you to use
when designing the input sequence tables.
Chapter 8 describes the Library Utility (LIB86). The chapter contains information on using
command-line options, creating a library file, and displaying library information.
Chapter 9 describes the Linker and Postlink utilities. This information includes using link path
variables, input file options, and command syntax.
Chapter 10 describes the Print Spooler Utility, which allows you to send files to one of eight
queues for printing on one of eight printers.
Chapter 11 provides information on the Disk Surface Analysis Utility, including parameter
descriptions and time-frame indicators.
Chapter 12 describes the Loop Status Application Utility, including formats to use to invoke the
utility.
Chapter 13 describes the Staged IPL Utility. The chapter contains the requirements, capabilities,
and application interface for using the utility.
Part 3Applications (Designing and Using)
Chapter 15 contains information for designing applications with IBM 4680 BASIC.
Chapter 16 contains information for designing applications with other 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, Postlink, and Linker utilities.
Appendix C describes character sets and the check printing application.
The glossary defines new, unique, and unfamiliar terms and abbreviations used in this book.
The index provides a quick reference to the contents of the book.

Terminal Models
|
|

|
|

|
|

The 4683/4693-xx1/4694 terminals are called Mod1 terminals. Although all are called Mod1 terminals,
each terminal model supports some features that other models do not support.
The 4683/4693-xx2 terminals are called Mod2 terminals. These terminals attach to a Mod1 terminal and
depend upon that Mod1 terminal for control and communication with the store controller. Table 0-1
shows the different Mod1 and Mod2 terminals.
Table 0-1. Mod1 and Mod2 Terminals by Machine Type
4683 Terminals

4693 Terminals

4694 Terminals

Mod1

Mod2

Mod1

Mod2

Mod1

Mod2

|
|
|
|
|
|

4683-P11
4683-P21
4683-P41
4683-001
4683-A01
4683-421

4683-xx2
4683-xx2
4683-xx2
4683-xx2
4683-xx2
4683-xx2

4693-7x1
4693-5x1
4693-4x1
4693-3x1

4693-xx2
4693-xx2
4693-xx2
Not supported

4694-144

Not supported

Note: A 4683-xx2 terminal cannot attach to a 4693 Mod1 terminal. A 4693-xx2 terminal cannot attach to
a 4683 Mod1 terminal.
The controller/terminal (for example, a 4684 or 4693-5x1 controller/terminal) combines the function of the
store controller and point-of-sale terminal in a single product. The terminal portion of a controller/terminal
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, SGC30-3780
IBM 4690 Store System: Planning, Installation, and Configuration Guide, GC30-3600
IBM 4690 Store System: Users 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 Users Guide, SC30-3404
IBM 4690 Store System: 4690 Terminal Services for DOS Users 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: Users Guide, SC30-3461
IBM 4680 General Sales Application Terminal Offline Feature: Users 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
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: Users Guide, SC30-3512
IBM 4680 Supermarket Application Electronic Funds Transfer Feature: Users Guide, SC30-3513
IBM 4680-4690 Supermarket Application Electronic Funds Transfer Feature Enhancement: Users Guide,
SC30-3718
IBM 4680-90 Supermarket Application: Master 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: Users Guide, SC30-3485
IBM 4680 Store Management Application Price Management Feature: Users 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, 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

4690 Store System: Programming Guide

IBM
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, 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
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 Users 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: Operators Guide, SA27-3884
IBM 4687 Point-of-Sale Scanner Model 2: Maintenance Manual, SY27-0324
IBM 4696 Point-of-Sale Scanner Scale: Physical Planning, Installation, and Operation Guide, GA27-3965
IBM 4696 Point-of-Sale Scanner Scale: Maintenance Manual, SY27-0333
IBM 4696 Point-of-Sale Scanner Scale: Specification Sheet, G221-3361
IBM 4697 Point-of-Sale Scanner Model 001: Maintenance Manual, SY27-0338
IBM 4697 Point-of-Sale Scanner Model 001: Physical Planning, Installation, and Operations Guide,
SY27-3990
IBM Personal Computer
IBM Personal System/2
IBM Personal System/2
IBM Personal System/2
IBM Personal System/2
IBM Personal System/2
SK2T-0319

and IBM Personal System/2

Model 50 Quick Reference and Reference Diskette, S68X-2247
Model 60 Quick Reference and Reference Diskette, S68X-2213
Model 70 Quick Reference and Reference Diskette, S68X-2308
Model 80 Quick Reference and Reference Diskette, S68X-2284
Store Loop Adapter/A Supplements for the Hardware Maintenance Library,

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 Publications
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 provided with the product)
IBM 4680 Store System Regression Tester (Softcopy provided with the product)
IBM 4680 X.25 Application Programming Interface, GG24-3952
NetView Distribution Manager: General Information, GH19-6587
Systems Network Architecture: General Overview, GC30-3073
IBM Local Area Network Administrators Guide, GA27-6367
DSX Preparing and Tracking Transmission Plans, SH19-6399
IBM Dictionary of Computing (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, Inc.,
ISBN 0-07-046320-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

Fiscal Printers

Multiple File Archiver Utility

Notices

xiii

xiv

4690 Store System: Programming Guide

Part 1: The IBM 4690 Operating System Environment

Copyright IBM Corp. 1994, 1996

4690 Store System: Programming Guide

Chapter 1. The IBM 4690 Operating System Environment

System Capabilities
. . . .
Concurrent Operations . . .
Operator Interface . . . . .
Changing the Signon Screen
Communications . . . . . .
Files . . . . . . . . . . . . .
Problem Determination Aids
Utilities . . . . . . . . . . . .
Additional Products . . . . .
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 is an overview of the IBM 4690 Operating System environment. It provides the capabilities of
the system and refers you to other chapters for more detailed information.

System Capabilities
The IBM 4690 Operating System is a multitasking and multiuser environment that runs in the store
controller, the point-of-sale terminals, and the controller/terminals. The operating system can handle store
controller communications with point-of-sale terminals, other controllers, the controller/terminal, and the
host processor. The following sections briefly describe the systems capabilities.

Concurrent Operations
The following functions of the 4690 Operating System allow concurrent operations:
The operating system allows you to run your batch and interactive programs at the same time. One
program does not have to finish before another program can start.
The operating system allows several operators to use the system at the same time. Your operators
can be authorized to run one program at a time or several at a time. Operators are authorized
through the system authorization file. See Chapter 15 for information on how to authorize users 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 of an application running on a window. Windows are possible through a window
control facility. Refer to the IBM 4690 Store System: Users Guide 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 multiple serial devices to your store controller. The Multiple Console facility handles
the management of these devices as additional system consoles.

Copyright IBM Corp. 1994, 1996

1-1

Operator Interface
For some system functions (for example, configuration) you communicate with the system through a
menu-driven interface at the store controller console. For other functions (for example, copying files) you
enter commands directly into the system. You can attach auxiliary consoles to the store controller. For
information on how to use system functions and auxiliary consoles, refer to the IBM 4690 Store System:
Users 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\ADXLOGOD.DAT. If this file exists during system startup, the first 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 reside in the ADX_IPGM subdirectory. This file can be applied using Apply
Software Maintenance (ASM). See the IBM 4690 Store System: Users Guide for information on the ASM
utility program. When using ASM, the Advanced Data Communications Systems (ADCS) Host Command
Processor (HCP) six-character name should be ?LOGOD. You maintain the contents and distribution
attributes of this file.
The alternate logo can be a maximum of 10 rows with 79 columns in each row. Each row should be
terminated with a carriage return and a line feed. The 4690 system editor DR EDIX automatically
terminates lines with these characters.

Communications
The following list contains communications-related information:
The communication interfaces that support Systems Network Architecture (SNA) protocols are logical
unit (LU) 0 and LU 6.2 as node types 2.0 and 2.1. The line connections supported on the non-SNA
interface are asynchronous (ASYNC) and Binary Synchronous Communication (BSC). The line
connections supported on the SNA interface are BSC, Synchronous Data Link Control (SDLC), token
ring, Ethernet, local link, and X.25. The IBM 4690 Store System: Communications Programming
Reference 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). The TP accesses the LU 6.2 communications functions by calling APPC
functions. These functions are known as calls (verbs) from a set of library routines that are linked to
the TP. CPI Communication is the LU 6.2 communications interface used by the 4690 Operating
System. The IBM 4690 Store System: Communications Programming Reference explains LU 6.2
communications.
Application-to-application communications are processed through in-memory files called pipes. For
information on how pipes work with your applications, see 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 other using the Multiple Controller Feature (MCF). A store 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. For more information, refer to the IBM 4690 Store System: Users Guide.

1-2

4690 Store System: Programming Guide

Files
This list briefly describes file security, file types, and file structures:
The operating system provides protection for your files by limiting access to only authorized users. To
control file access, you assign each user to one of three categories. See Protecting Files on
page 2-23 for a description of these categories and their uses.
You can specify and manage the way disk files are shared with other users. See Sharing Files on
page 2-21 for information on allowing file access.
You can create and manage keyed files and other files. A utility allows you to change keyed files into
direct files or direct files into keyed files. See Keyed on page 2-4 for information about keyed files
and how to change these files into direct files, or direct files into keyed files. Creating Files on
page 2-19 explains how files are created on the 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 or on your system. One of the aids allows you to collect data about a problem, then
print, display, or file the data. You can also create a diskette for documenting and analyzing a
problem. Refer to the IBM 4690 Store System: Messages Guide for information on collecting problem
analysis data.
A system error log provides a record of system errors that occurred. You can use this data to help
identify and resolve problems. For information on the system error log, see Chapter 4.

Utilities
The 4690 Operating System provides the following utilities:
A utility is available to help you develop the input sequence table. The input sequence table lets you
edit operator input from various input devices. Chapter 7 describes the input sequence table utility.
The Apply Software Maintenance (ASM) Utility allows you to update system or user programs through
a menu-driven interface. Refer to the IBM 4690 Store System: Users Guide for information about this
utility. The Staged IPL Utility lets you apply maintenance using ASM when one controller is up and
able to run TCC Networks. See Chapter 13 for information on the Staged IPL Utility.
Special write operations protect your data in the event of a power line disturbance. For information on
recovering from power line disturbances, 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: Users Guide for a complete description of this utility.
A text editing facility lets you create and edit files. Refer to the IBM 4690 Store System: Users Guide
for information on the text editing facility.

Chapter 1. The IBM 4690 Operating System Environment

1-3

Additional Products
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 is available by RPQ P85154.
The IBM 4690 Operating System includes a Display Manager program that allows you to create,
modify, or manage information displayed on the store controller screen. Refer to the IBM 4680 Store
System: Display Manager Users Guide for information about this program.

Store Controller Backup

You specify the store controller backup during configuration. This backup automatically backs up your
primary controller when activated. The function provides continuous control for your terminal operations.
When you configure and prepare a store controller for backup, it can assume control of the TCC Network
when the store controller for that TCC Network is not operational. For information on configuring and
preparing store controller backup, refer to the IBM 4690 Store System: Users Guide.
The IBM 4690 Operating System also provides data backup. A multiple-controller system provides Data
Backup, the capability for file redundancy. This capability allows store controllers to communicate with
each other across the local area network (LAN). With this feature you can specify when your files are to
be automatically updated and distributed. For more information on data backup with a LAN, refer to the
IBM 4690 Store System: Users 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 1. Define the File . . . . . . . . . . . . . . . . . . . . . . . . .
Step 2. Create the File . . . . . . . . . . . . . . . . . . . . . . . . .
Step 3. Access the File from the User 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 . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Space Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File Access Rights . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting Files
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ending Access to Files . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sharing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Copying Files
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Renaming Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Protecting Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Protecting Subdirectories . . . . . . . . . . . . . . . . . . . . . . . . . .
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 Files
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

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

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 shows you how to handle files. It gives you information about file types and describes 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. You create all files using variations of the CREATE statement and accompanying
parameters.

Random
Random files have fixed record lengths. The system uses the last two bytes in each record for the
carriage return and line feed characters (CR/LF). The system pads the data space between the last field
of the record and the CR/LF.
Random files offer random access, which allows direct access to any record in a file. This ability makes
random and direct files an ideal type for files that can be referenced by a relative record number. If you
need a name or a specific number (such as a telephone number) to reference a record, use Keyed File
Services. You ensure that the number of bytes occupied by the field delimiters and CR/LF do not exceed
the specified record length. Figure 2-1 shows a random file composed of three records. The data is 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

Figure 2-1. Example of a Random File

IBM 4680 BASIC locates each record of a randomly accessed file by taking the record number,
subtracting 1, and then multiplying that result by the record length. The result is a byte displacement
value for the record measured from the beginning of the file. Records can span sectors. You must
specify the record to be accessed in each READ#, PRINT#, or WRITE# statement executed. The
following BASIC program creates the random file diagrammed in Figure 2-1.
CREATE

WRITE
WRITE
WRITE
CLOSE
END

2-2

"FILE.1" RECL 40 AS 2
A$ = "FIELD ONE"
B$ = "FIELD TWO"
C$ = "FIELD THREE"
D$ = "Field 1"
E$ = "Field 2"
F$ = ""
G% = 111
H% = 222
I = 3.3
J% = 444
K = 5.5
#2,1; A$, B$, C$
#2,2; D$, E$, F$
#2,3; G%, H%, I, J%, K
2

4690 Store System: Programming Guide

The following program reads the first three fields from record 3 in FILE.1.
IF END #20 THEN 200
OPEN "FILE.1" RECL 40 AS 20
READ #20,3; FIELD1%, FIELD2%, FIELD3
PRINT FIELD1%, FIELD2%, FIELD3
200 END
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 files are like random files except that direct files contain no delimiting characters (quotes, commas,
and CR/LF). Direct files contain no data formatting information. Because of this, you must specify a
special format string when you want to access the data in a direct file. See Performing File Functions on
page 2-18 to learn more about accessing a direct file.
The following program creates a direct file named DIRECT.DAT that consists of one 15-byte record. The
variable D represents the format string used in the WRITE FORM# statement.
STRING A,
INTEGER*2
REAL C

D
B

CREATE

"DIRECT.DAT" DIRECT
A = "ABC"
B = 32767
C = 27.35
D = "C3, I2, R"
WRITE FORM D; #3,1; A,B,C

RECL 15

AS 3

LOCKED

CLOSE 3
END
Figure 2-2 shows the direct file created by the preceding program. The data in the figure is in
hexadecimal.

RECORD 1

414243FF7F42000000000000003527

ABC

32767

27.35

Record length = 15 bytes

Figure 2-2. Example of a Direct File

Chapter 2. Managing 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 file consists of blocks that contain keyed records. A block is a 512-byte sector. Each block uses
the first four bytes for chain pointers and the next 508 bytes for records. A block can contain multiple
records, but records are not split across blocks. Each record contains its key and data, with the key
always being first. A record can be a maximum of 508 bytes. The key can be as many bytes of the
record as you need.
You should use keyed files for files accessed by a name or a number. Examples of such numbers are a
Universal Product Code (UPC), a label, a telephone number, or a check authorization number. These
types of names and numbers do not have any contiguous nature and are random in their occurrence. 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 do not have indexes. The more unique each key is with respect to all of the other keys used
in a keyed file, the better the hashing technique works.
To access a keyed file sequentially, use the keyed file as a direct file. You can obtain information about
the keyed file from the first block, which is used only for control information. The format of this first block
is:
Relative Byte
Offset (in Decimal)

Number of Bytes
(in Decimal)

Keyed File
Information

42

Number of blocks in keyed file

46

Keyed record size

48

Randomizing divisor

54

Key length

56

Chaining threshold

You can create keyed files directly with an IBM 4680 BASIC program, or you can use the Keyed File
Utility program provided with the IBM 4690 Operating System. The utility provides an efficient two-pass
method of converting a direct file into a keyed file. See Keyed Files on page 2-28 for an explanation of
this utility.
Like direct files, keyed files use no delimiting characters. You use a format string to map the data to and
from the record. Figure 2-3 shows a keyed file record with a 19-byte length. The data in the figure is in
hexadecimal.

RECORD 1

4B455931414243FF7F42000000000000003527

key1

ABC 32767

Record length = 19 bytes

Figure 2-3. Example of a Keyed File

2-4

4690 Store System: Programming Guide

27.35

The following program creates the 19-byte keyed file shown in the Figure 2-3 on page 2-4. The keyed
file consists of one 19-byte record.
STRING A,
INTEGER B
REAL C

D,

KEY

CREATE POSFILE "KEYFILE.DAT" KEYED 4 , , , 200 \

RECL 19 AS 4 LOCKED
KEY = "key1"
A = "ABC"
B = 32767
C = 27.35
D = "C4, C3, I2, R"
WRITE FORM D; #4; KEY,A,B,C
CLOSE 4
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 t