.«:SM^-<q's^r~-si

^Mi

—ia

Ws

'8







ZCPR3: THE LIBRARIES

A Reference Manual
and
User's Guide
for
SYSLIB, Z3LIB, and VLIB

Written by
Richard Conn

Copyright 1986    Richard Conn

Echelon, Inc.
885 N. San Antonio Road
Los Altos, CA 94022 USA







Copyright 1986 Richard L. Conn.  All rights reserved.  No part of
this document may be reproduced in any manner or by any means
without prior written permission from the publisher.   Contact
Echelon, Inc., 885 N. San Antonio Road, Los Altos, CA 94022,
415/948-3820, for further details.







CONTENTS

ZCPR3: THE LIBRARIES

A Reference Manual
and
User's Guide
for
SYSLIB, Z3LIB, and VLIB

Written by
Richard Conn

Copyright 1986    Richard Conn







This Page Left Blank










TABLE      OF      CONTENTS

1. INTRODUCTION..........................................1-1

1.1. What Are the Libraries of ZCPR3?................. 1-1

1.2. What is Needed to Use the Libraries?............. 1-2

1.3. What Do the Libraries Buy You?................... 1-2

1.4. How Do You Assemble with the Libraries?.......... 1-3

1.5. How to Learn to Use the Libraries Effectively?...1-4

1.6. Comments on Software Engineering................. 1-4

1.7. Definitions of Terms............................. 1-6

1.8. Parameter-Passing Conventions .................... 1-7

1.9. Programs and Files............................... 1-8

SYSLIB

2. INTRODUCTION TO SYSLIB................................2-1

3. CHARACTER INPUT/OUTPUT ................................ 3-1

3.1. Character Input.................................. 3-3

3.2. Conditional Input................................ 3-3

3.3. Character Output.................................3-3

3.4. Newline Output...................................3-4

3.5. Console Status...................................3-4

4. STRING INPUT/OUTPUT ................................... 4-1

4.1. String Print..................................... 4-3

4.2. File Name Output................................. 4-3

4.3. Input Line Editors............................... 4-5

5. NUMERIC INPUT/OUTPUT..................................5-1

5.1. Numeric Output................................... 5-2

5.1.1. Hexadecimal Output of Register A.......... 5-3

5.1.2. Decimal Output of Register A.............. 5-3

5.1.3. Hexadecimal Output of Register Pair HL....5-5

5.1.4. Decimal Output of Register Pair HL........5-5

5.2. Numeric String Evaluation........................ 5-6

6. FILE MANIPULATION..................................... 6-1

6.1. File Input/Output................................6-2

6.1.1. Append to a File..........................6-2

6.1.2. Close a File..............................6-3

6.1.3. Delete a File.............................6-3

6.1.4. Test of Existence of a File...............6-4

6.1.5. Create a File.............................6-4

6.1.6. Open a File...............................6-4

6.1.7. Read and Write a Block....................6-5

6.1.8. Rename a File............................. 6-5

6.1.9. Compute File Size.........................6-5

6.1.10. Get Random Record Number.................6-6

6.1.11. Get File Size in Records.................6-6

6.1.12. Get File Attributes......................6-6

6.1.13. Random Read and Write a Block............6-7

6.1.14. Set and Clear File Attributes............6-7

6.2. Byte-Oriented File Input/Output.................. 6-8

6.2.1. Open File................................. 6-9

6.2.2. Close File............................... 6-10

6.2.3. Byte Input and Output....................6-10

6.2.4. Error Return Codes....................... 6-11

6.3. Byte-Oriented File I/O with Variable Buffers....6-11

6.3.1. Open File................................6-13

6.3.2. Close File...............................6-13

6.3.3. Byte Input and Output Routines........... 6-14

6.4. Byte-Oriented File I/O with UNGET...............6-14

6.4.1. Open Pile................................6-16

6.4.2. Close File...............................6-16

6.4.3. Byte Input, Onget, and Output............6-17

6.5. Library Files................................... 6-17

6.5.1. Library File Initialization..............6-18

6.5.2. Library File Directory Access............ 6-18

6.5.3. File Extraction..........................6-19

6.6. Miscellaneous...................................6-20

6.6.1. File Name String Parser (FNAME)..........6-20

6.6.2. FCB Initialization.......................6-21

6.6.3. Set DMA Address..........................6-21

7. DIKECTORY MANIPULATION. .............................. .7-1

7.1. Buffer Allocation................................7-4

7.2. Directory Alphabetization........................ 7-4

7.3. Directory Entry Selection........................7-5

7.4. Directory Load...................................7-5

7.5. Directory Pack................................... 7-6

7.6. Disk Parameter Information Extraction............7-7

7.7. File Size Computation............................7-7

7.8. Free Space Computation........................... 7-7

7.9. General-Purpose..................................7-8

8. USER AREAS AND DISKS..................................8-1

8.1. Save and Restore Disk/User Area..................8-3

8.2. Get and Set Current User Area.................... 8-3

8.3. Log Into a Disk/User............................. 8-3

8.4. Return the Current Disk/User..................... 8-4

9. BRANCHING.............................................9-1

9.1. Case with Register A.............................9-3

9.2. Case with Register Pair HL.......................9-5

9.3. Computed Goto with Register A.................... 9-6

9.4. Computed Goto with Register Pair HL.............. 9-8

9.5. Arithmetic IF with Register A................... 9-10

9.6. Arithmetic IF with Register Pair HL.............9-10

10. MATHEMATICAL FUNCTIONS...............................10-1

10.1. Arithmetic Operations..........................10-2

10.2. Complement Operations.......................... 10-3

10.3. Logical Operations............................. 10-4

10.4. Rotate and Shift Operations.................... 10-4

10.5. Random Number Generator........................10-5

10.6. CRC Calculation................................10-6

11. UTILITIES 1..........................................11-1

11.1. Memory Allocation..............................11-2

11.1.1. Allocate a Block of Memory.............11-3

11.1.2. Initialize Memory Allocation Buffer....11-3

11.2. Parsing Aids................................... 11-4

11.2.1. Character Skip.........................11-4

11.2.2. Character Test.........................11-5

11.2.3. UNIX-Style ARGC/ARGV String Parser.....11-5

11.3. Sort...........................................11-6

11.3.1. SSB Initializer........................11-7

11.3.2. SSB Sort...............................11-8

n



















11.4. String and Value Comparison.................... 11-8

11.4.1. Substring Search....................... 11-8

11.4.2. Value Comparision......................11-8

11.4.3. Vector Comparison...................... 11-9

11.4.4. Vector Search.......................... 11-9

12. UTILITIES 2..........................................12-1

12.1. BDOS and BIOS Access........................... 12-2

12.2. Capitalization.................................12-3

12.3. Command Line Tail Extraction................... 12-3

12.4. Convert ASCII to Hexadecimal...................12-4

12.5. End of Code.....................................12-4

12.6. Exchange Nybbles............................... 12-5

12.7. Memory Fill....................................12-5

12.8. Memory Move....................................12-5

12.9. Pause Execution................................ 12-6

12.10. Version Number of SYSLIB...................... 12-6

Z3LIB

13. INTRODUCTION TO Z3LIB................................13-1

14. ENVIRONMENT ACCESS 1.................................14-1

14.1. Command Line...................................14-3

14.2. CRT/Printer Data...............................14-5

14.3. DU/Max DU...................................... 14-7

14.4. External FCB...................................14-8

14.5. Environment....................................14-9

14.6. FCP Address....................................14-9

14.7. File Names....................................14-10

14.8. Initialize....................................14-11

14.9. Introduction to IOP Concepts.................. 14-11

14.10. IOP Address..................................14-12

14.11. IOP Recording................................14-14

15. ENVIRONMENT ACCESS 2.................................15-1

15.1. Messages.......................................15-2

15.2. Named Directories..............................15-2

15.3. Path...........................................15-5

15.4. Processor Speed................................15-5

15.5. Quiet Flag.....................................15-6

15.6. RCP Address....................................15-6

15.7. Shell Stack....................................15-7

15.8. Wheel Byte.....................................15-7

16. FLOW AND ZEX CONTROL.................................16-1

16.1. Flow Control...................................16-2

16.1.1. End IF.................................16-3

16.1.2. Raise IF...............................16-4

16.1.3. Test IF................................16-4

16.1.4. Toggle IF..............................16-4

16.2. ZEX Access and Control......................... 16-5

16.2.1. ZEX Data............................... 16-5

16.2.2. 2EX Status and Control................. 16-6

17. MESSAGES OF ZCPR3....................................17-1

17.1. Command Status Messages........................ 17-4

17.2. Error Flag and Error Command...................17-5

17.3. Inter-Transient Error Code..................... 17-7

17.4. Register Access................................ 17-8

in

18. UTILITIES............................................18-1

18.1. Log into ZCPR3 FCB DU..........................18-2

18.2. Locate ROOT Directory in Path.................. 18-2

18.3. Named Directory and Disk User Conversion.......18-3

18.4. Output Routines Based on the Quiet Flag........18-3

18.5. Parse Command Line............................. 18-4

18.6. Parse Token.................................... 18-5

18.7. Pause Execution................................18-5

18.8. Program Loader (Chain).........................18-6

18.9. Resolve Directory References................... 18-7

18.10. Search for File Along Path.................... 18-8

18.11. Shell Stack Manipulation......................18-8

18.12. Z3LIB Version Number.........................18-10

18.13. Initialize Z3LIB.............................18-10

VLIB

19. VLIB.................................................19-1

19.1. Clear Screen...................................19-3

19.2. Cursor Positioning............................. 19-3

19.3. Erase to End of Line........................... 19-4

19.4. Initialization.................................19-4

19.5. Print..........................................19-5

19.6. Standout Mode..................................19-6

19.7. Terminal Initialization and Deinitialization...19-7

USER'S GUIDE

20. INTRODUCTION......................................... 20-1

21. INPUT AND OUTPUT.....................................21-1

22. INPUT LINE EDITORS...................................22-1

22.1. What is an Input Line Editor?.................. 22-1

22.2. The BDOS-Based Input Line Editors.............. 22-1

22.3. The INLINE Input Line Editor...................22-2

23. NUMERIC STRING EVALUATION............................23-1

24. DISK INPUT/OUTPUT....................................24-1

24.1. Directory Manipulation.........................24-1

24.2. Block-Oriented File Input/Output............... 24-9

24.3. Byte-Oriented File Input/Output............... 24-10

24.4. File Control Block (FCB) Manipulation.........24-11

25. MATH.................................................25-1

26. CYCLIC REDUNDANCY CHECKS.............................26-1

27. SORT.................................................27-1

28. CODEND...............................................28-1

IV










APPENDICES

A. SAMPLE PROGRAMS.......................................A-l

A.I. Classic File Dump Program (STEST006).............A-2

A.2. Random File Access (STESTOOO)....................A-7

A.3. Byte-Oriented File Output (STEST001)............A-14

A.4. Directory Access (STEST002).....................A-18

A.5. Evaluation and Math (STEST003)..................A-23

A.6. Sort (STEST004).................................A-28

A.7. Random Number Generator < STEST005)..............A-34

A.8. Directory Access and File Size (STEST010).......A-37

A.9. File Append (STEST013)..........................A-40

B. FILE LISTINGS.........................................B-l

B.I. SYSLIB...........................................B-3

B.I.I. Character Input/Output....................B-3

B.1.2. String Input/Output.......................B-3

B.1.3. Numeric Input/Output......................B-4

B.1.4. File Manipulation.........................B-5

B.I.5. Directory Manipulation....................B-7

B.I.6. User Areas and Disks......................B-8

B.1.7. Branching.................................B-8

B.1.8. Mathematical Functions....................B-9

B.I.9. Utilities 1..............................B-10

B.I.10. Utilities 2.............................B-ll

B.I.11. Other Files.............................B-12

B.2. Z3LIB...........................................B-15

B.2.1. Environment Access 1.....................B-15

B.2.2. Environment Access 2.....................B-16

B.2.3. Flow and ZEX Control.....................B-17

B.2.4. Messages of ZCPR3........................B-17

B.2.5. Utilities................................B-18

B.2.6. Other Files..............................B-20

B.3. VLIB............................................B-21

B.3.1. VLIB.....................................B-21

B.3.2. Other Files..............................B-21

C. UPDATE NOTICES........................................C-l

COMPREHENSIVE INDEX....................................Index-1




v




This Page Left Blank