Introduction to SYSLIB 4 Comments on Software Engineering Library Definitions and Terms Parameter-Passing Conventions Overview of SYSLIB 4 Routines ------------------------------------------------------------- Introduction to SYSLIB 4 SYSLIB 4 is an integrated tool set which is designed to assist you, the assembly language programmer, in writing programs. It is intended to place you at a higher level of abstraction and allow you to concentrate on the problem at hand without having to concern yourself with the low-level implementation details of the operating system interface, input/output, text parsing and evaluation, math, and sorting. To illustrate this point, consider an assembly language program which needs to access a disk directory, then display a sorted list of file names. Without SYSLIB 4 or similar library, you would have to write a relatively sophisticated body to code to access the directory, load it in memory, sort, and display it. SYSLIB 4, however, provides you with a "toolbox" of routines to call on to perform some of the more tedious functions. One of these tools, DIRF, loads the elements of a disk directory which match a file spec into a memory buffer for you. But, more than just providing a set of tools, SYSLIB 4 was designed with structured programming and software engineering in mind. The basic goal in software design is that the programs meet the stated requirements. In applying software engineering, we want more than just this. Among other things, we want the program to be: o Modifiable o Efficient o Reliable o Understandable SYSLIB 4 offers a significant set of facilities which can help to achieve these goals. Comments on Software Engineering We are experiencing a SOFTWARE CRISIS today, the basis of which is simply that it is more difficult to build reliable software systems that we think it should be. All too often, the symptoms of the SOFTWARE CRISIS are seen: o Cost - unpredictable and judged excessive o Efficiency - time and space utilitization are not efficient o Modifiability - software is difficult to change o Reliability - software often fails o Responsiveness - user needs are not met o Timeliness - software is not delivered on time o Transportability - software used on one system may not be used on another The bottom line in the design of a software system is that the software should meet its stated requirements. To achieve this end, the field of SOFTWARE ENGINEERING has arisen. The goals of SOFTWARE ENGINEERING are: 1. Modifiability - Software should be easy to change, and software should be designed with later change in mind. 2. Efficiency - The software system should use available resources in an optimal manner. 3. Reliability - The software should perform according to specification and recover safely from failure during use. 4. Understandability - Software should be easy to read and follow. Understandability is the tool used to pass from a particular problem space to a solution. SYSLIB 4 attempts to help you achieve the goals of Software Engineering by applying these principles: 1. Abstraction and Information Hiding - Unnecessary detail is hidden from you. For example, the DIRF routine loads the contents of a disk directory into a memory buffer. How this load is done is hidden -- all you need to know is that the load was done and you have a vector of directory entries. 2. Modularity - SYSLIB 4 is very modular in design. Each routine in the library performs one and only one function, and the documentation provides complete detail as to what that function is, what its input parameters are, what its output parameters are, what its side effects are, and other data. 3. Localization and Loose Coupling - SYSLIB 4 modules are loosely coupled -- each module may be treated independently of the others. Additionally, the modules are strongly cohesive -- the components of each module are intimately related to each other but not to components of other modules. 4. Uniformity - The calling conventions between the various SYSLIB 4 modules are consistent with each other, and it is frequently the case that the output parameters from one module may be directly used as input parameters to another. 5. Completeness - Each module or group of related modules are functionally complete. No additional functions are needed. 6. Confirmability - A program written using SYSLIB 4 modules can be readily decomposed for incremental testing. Definitions and Terms Some terms are used frequently in the SYSLIB 4 documentation. These terms are defined below. 1. Buffer - A contiguous vector of bytes in memory. The buffer is known by its starting address and size as: BUFFER: DEFS 40 ; 40-byte buffer 2. Character - A one-byte (8-bit) value. A value range within the ASCII character set (a 7-bit value) is implied but not required, so a character could have a value of 81H. 3. Directory - An index to files on a disk. A directory entry contains the name of a file, the User number it resides in, the file size, and where the file is located on the disk. The information loaded by SYSLIB directory routines does not include file location information, but does include every- thing else. In another sense, the term directory is used to refer to a particular disk and user area (such as A4 or B31). 4. FCB (File Control Block) - A 36-byte buffer satisfying the full definition of a CP/M File Control Block. SYSLIB 4 FCB's are ALWAYS 36 bytes long. In many cases, when routines need a user-supplied FCB, you need only fill in the file name and type fields (bytes 1-11) and need not concern yourself with the rest of the fields. The INITFCB routine stores zero in all bytes except bytes 1-11 of the FCB. 5. File - Any CP/M file, either text or binary. SYSLIB 4 makes no distinction between these two types of files. 6. String - Any sequence of ASCII characters terminated by a character, which is a byte of value 0. Examples of strings are: DEFB 'This is a string',0 DEFB 1,2,3,'This is also',0 Parameter-Passing Conventions SYSLIB 4 is very consistent in its parameter-passing conven- tions. In all cases, parameters are passed to and from SYSLIB 4 routines in registers. If more values are required than there are available registers, the register values are pointers to specification blocks which contain the desired parameters (see the FXn$xxxxx and the SORT routines). In nearly all cases, the following register usage rules apply: The HL Register Pair is used -- 1. as a buffer pointer; for example, HL contains the address of the buffer used by DIRF 2. as a string pointer; for example, HL points to the first byte of a string for the EVAL routine 3. to hold the first operand for math routines; for example, DIVHD divides HL by DE The DE Register Pair is used -- 1. to point to an FCB; for example, DE contains the address of the FCB used by DIRF 2. to contain the second operand for math routines; for example, SUBHD subtracts DE from HL 3. to point to special blocks (buffers) used by SYSLIB 4 routines; for example, DE points to the Sort Specification Block for the SORT routine The BC Register Pair is used to contain a DU form, where B hold a Disk Number (A=0) and C hold a User Number The A Register is used to -- 1. contain an Input Flag; for example, A contains the selection flag used by DIRF 2. contain an Error Return Code; if the value of this code is 0, the Zero Flag (Z) is also set, and vice-versa; for example, A contains a TPA overflow error flag returned by the DIRF routine 3. contain a character input or output from a a SYSLIB 4 routine; for example, CIN returns a character in A and COUT outputs a character in A Overview of SYSLIB 4 Routines SYSLIB 4 contains many routines grouped into the following functional areas: 1. Directory Manipulation Routines. These routines deal with directory access. The entries of a disk direc- tory can be loaded into a memory buffer, selected against an FCB, sorted, and manipulated. 2. Numeric String Evaluation Routines. These routines convert character strings into 16-bit binary values. Strings like those below are processed: DEFB '123',0 ; value is 123 decimal DEFB '5AH',0 ; value is 5A hexadecimal DEFB '110B',0 ; value is 110 binary DEFB '77Q',0 ; value is 77 octal 3. Byte-Oriented File Input/Output Routines. These routines support input and output to and from files on the basis of a byte at a time. FX$GET, for example, returns the next byte from the current file in A. 4. CP/M File Input/Output Routines. These routines support input and output to and from files on the basis of a 128-byte block at a time. Provisions for deleting files, renaming files, and computing file sizes also exist. 5. User/Disk Manipulation Routines. These routines allow the program to find out what disk and user area it is in and to move between directories. 6. File Name String Parser. This routine is used to convert a file name text string into an acceptable form and place it into an FCB. For example, the following con- version can be done: DEFB 'MYFILE.TXT',0 ; string DEFB 0 ; ..converted to DEFB 'MYFILE ' DEFB 'TXT' DEFS 24 7. Input Line Editors. These routines accept user input with editing and return a pointer to the first byte of user input in string form (terminated by a binary 0). 8. String Output Routines. These routines send strings to various devices. Routines are provided to send strings of characters to the console or printer with or without control-character processing. 9. Numeric Output Routines. These routines convert binary values to character sequences and output them to various devices. Output to the console and printer is provided, and the output is either in the form of decimal or hexadecimal numbers. 10. String and Value Comparison Routines. These routines provide various comparison functions for both strings and numbers. One string may be compared against another string or a substring of another string. Two 16-bit numbers can be compared. 11. Character-Oriented Input/Output Routines. These routines provide input and output services on a character-for-character basis to a variety of devices. Output to the console and the printer is provided. Also, device status, such as console input status, routines are available. 12. Math Routines. These routines perform mathematical calculations on 16-bit quantities. Add, subtract, multiply, divide, rotate, shift, logical AND, logical OR, and logical XOR are some of the functions provided. 13. CRC Routines. These routines support computation of Cyclic Redundancy Check values for byte streams. A number of different CRC calculation routines are available for different CRC polynomials. 14. Random Number Generator Routines. These routines implement a pseudo-random number generator which returns an 8-bit value when called. The seed value for this generator may be fed to it, thereby generating the same sequence for each given seed, or it may be selected randomly. 15. Sort Routines. These routines provide a fast, general- purpose in-memory sort capability. The sort algorithm is very efficient (a Shell Sort), and may be performed using element pointers or not using pointers (pointers cost more memory but speed up the sort even further). 16. Capitalization and Character Test/Skip Routines. These routines are useful for text parsing. A variety of evaluation routines are provided to determine the type of character being dealt with (such as alphabetic, numeric, hexadecimal, space, punctuation, etc). Both string and individual character capitalization capa- bilities are also provided. 17. Memory Allocation Routines. These routines provide a dynamic memory allocation mechanism that constantly checks for TPA overflow. After defining the bounds of a memory buffer, requests for space from this area may be issued on a byte-for-byte basis.