Oakland CPM Archive/oakcpm.iso/cpmug/cpmug024.ark/TAPELIB.DOC

Text File | 1984-04-29 | 11.8 KB | 296 lines

            --  TAPELIB --

                BY  SAM J. SINGER
                    [phone]

I.  INTRODUCTION

    TAPELIB IS A GENERAL CASSETTE TAPE LIBRARY MANAGER FOR
CP/M. IT INCORPORATES MOST OF THE FEATURES OF THE CP/M PIP UTILITY.
ANY CP/M FILE OR GROUP OF FILES MAY BE COPIED FROM TAPE TO DISK
OR FROM DISK TO TAPE.
    IN ADDITION TO THE USUAL PIP COPY OPERATIONS, TAPELIB
PERMITS VERIFICATION OF TAPE FILES AGAINST DISK FILES AND DIRECT
EXECUTION OF BINARY PROGRAMS FROM TAPE.  TAPE FILES ARE NAMED AND
SPACE IS PROVIDED IN THE TAPE COPY FOR EXTENSIVE COMMENTS.
    FILES MAY BE DISPLAYED ON THE CONSOLE DURING COPY OPERATIONS
FOR VISUAL VERIFICATION .  THE PROGRAM CONTAINS EXTENSIVE ERROR
CHECKS, AND CONSOLE MESSAGES ARE UNABBREVIATED AND QUITE SPECIFIC.
EVERY EFFORT HAS BEEN MADE TO MAKE THE PROGRAM GENERAL AND EASY TO
USE. THE PROGRAM HAS BEEN OPTIMIZED TO PROVIDE THE FASTEST POSSIBLE
DATA TRANSFER RATES YET STILL MAINTAIN GOOD RELIABILITY.

II.  HARDWARE REQUIREMENTS

    TAPELIB REQUIRES AN 8080 OR Z-80 BASED COMPUTER SYSTEM
RUNNING THE CP/M OPERATING SYSTEM, AT LEAST ONE FLOPPY DISK DRIVE,
A CASSETTE RECORDER AND TARBELL CASSETTE INTERFACE AND A CONSOLE
DEVICE.  THE DISPLAY DURING COPY OPERATIONS REQUIRES THE TERMINAL
TO OPERATE AT A MINIMUM OF 4800 BAUD IF THIS FEATURE IS TO BE USED.

III.  PROGRAM OPERATION

    TAPELIB OPERATES AS A TRANSIENT FILE UNDER CP/M, AND
REQUIRES SLIGHTLY MORE THAN 4K OF MEMORY FOR CODE. THE REMAINDER
OF THE AVAILABLE MEMORY WILL BE USED FOR FILE BUFFERS.
    DURING DISK TO TAPE COPIES THE PROGRAM WILL FIRST ATTEMPT
TO READ THE ENTIRE FILE INTO MEMORY AND WRITE IT ON TAPE AS A
SINGLE RECORD. IF THERE IS INSUFFICIENT ROOM FOR THE ENTIRE FILE,
OR IF THE FILE CONTAINS MORE THAN ABOUT 14000 BYTES THE PROGRAM
WILL WRITE THE FILE ON TAPE IN 1K BLOCKS. A BLOCKED TAPE WILL ALSO
BE PRODUCED IF THE BLOCK OPTION IS USED. THIS OPTION IS USEFUL IF
TAPES ARE TO BE TRANSFERED FROM ONE SYSTEM TO ANOTHER OF A DIFFERENT
SIZE. A MESSAGE WILL BE DISPLAYED BEFORE A BLOCKED TAPE IS WRITTEN.
BLOCKED TAPES REQUIRE ABOUT 25 PER CENT MORE TIME TO WRITE.
    EACH TAPE FILE IS HEADED BY A 128 BYTE RECORD CONTAINING
THE FILE NAME. MOST OF THE REMAINDER OF THE 128 BYTES IS AVAILABLE
FOR COMMENTS. THE COMMENTS ARE DELETED DURING TAPE TO DISK COPIES.
    FILES ARE DISPLAYED ON THE TERMINAL DURING ALL COPY
OPERATIONS UNLESS THE NODISPLAY OPTION IS USED. CHARACTERS ARE
DISPLAYED IN ASCII IN 64 CHARACTER LINES WITH NONDISPLAYABLE
CHARACTERS CONVERTED TO PERIODS.
    DURING TAPE TO DISK COPY OPERATIONS A SEARCH IS MADE FOR
THE FILE NAME OR GROUP OF NAMES AND ONLY THE REQUESTED FILES
ARE COPIED. HOWEVER, THE HEADER RECORD CONTAINING THE FILE NAME
WILL BE DISPLAYED FOR EACH FILE ON THE TAPE. THIS PERMITS SCANNING
THE TAPE TO DETERMINE ITS CONTENTS, SINCE TAPES HAVE NO DIRECTORIES.
WHEN REQUESTED FILES ARE FOUND, THE ENTIRE CONTENTS WILL BE DISPLAYED.

IV.  TAPELIB COMMANDS

    TAPELIB MAY BE RUN BY ONE OF TWO METHODS. TYPE:

        TAPELIB
        TAPELIB <COMMAND STRING>

ALL COMMANDS ARE TERMINATED BY A CARRIAGE RETURN. IF THE FIRST METHOD IS
USED THE PROGRAM RESPONDS WITH A TITLE AND AN * PROMPT. THE COMMAND STRING
MAY THEN BE ENTERED. THE SECOND FORM EXECUTES THE COMMAND STRING
IMMEDIATELY.
    IF THE FIRST FORM OF THE CALL IS USED THE PROGRAM WILL RETURN TO
THE INPUT SECTION AFTER COMPLETION OF THE COMMAND. THE PROMPT WILL BE
DISPLAYED AND ANOTHER COMMAND EXECUTED WITHOUT RELOADING THE PROGRAM.
THE OTHER FORM WILL RETURN TO CP/M AFTER COMPLETION OF THE COMMAND.
ANY COMMAND MAY BE TERMINATED BY TYPING CONTROL C. THE FIRST CONTROL C
RETURNS TO THE INPUT SECTION OF THE PROGRAM. A SECOND CONTROL C RETURNS
BACK TO CP/M.
    THE COMMAND STRING HAS THE FOLLOWING FORM:

        DESTINATION:=SOURCE  <OPTIONS> <COMMENT>

    THE SOURCE AND DESTINATION MAY BE EITHER A FILE NAME AND TYPE, A
DEVICE NAME OR SPECIAL FUNCTION. DEVICE NAMES AND FUNCTIONS MUST BE FOLLOWED
BY A COLON. THE FOLLOWING TABLE GIVES ACCEPTABLE NAMES AND THEIR
INTERPRETATION.

        DEVICE/FUNCTION TABLE

    TAPE:        THE CASSETTE TAPE
    DISK:        THE CURRENTLY LOGGED DISK
    A:        DISK A
    B:        DISK B
    RUN:        LOAD TAPE TO MEMORY AND EXECUTE
    SYNC:        WRITE SYNC STREAM ON TAPE

    ANY CP/M LEGAL FILE NAME INCLUDING AMBIGUOUS FILE NAMES MAY BE
USED WITH TAPELIB. THE FOLLOWING ARE EXAMPLES OF ACCEPTABLE NAMES

        XXXX.YYY    FILENAME.TYP
        *.COM        TAPELIB.???
        *.*        A:MYPROG.COM
        B:NEWNAME.ASM    B:????????.ASM

NOTE THAT THE DISK NAME MAY BE SPECIFIED AS PART OF A FILE NAME.

    THE OPTIONS AVAILABLE AND THEIR FUNCTIONS ARE LISTED IN THE
OPTION TABLE WHICH FOLLOWS.

            OPTION TABLE

    NODISPLAY        TURN OFF DISPLAY FEATURE (FOR SLOW TERMINALS)
    BLOCK            BLOCK FILES ON TAPE IF FILE WILL NOT FIT
                    IN 16K CP/M SYSTEM
    VERIFY            COMPARE TAPE FILE WITH DISK FILE OF SAME NAME
    RENAME            RENAME FILE ON DISK AFTER COPY FROM TAPE

    COMMAND STRINGS CAN BE CONSTRUCTED FROM VARIOUS COMBINATIONS OF
THE NAMES AND OPTIONS LISTED ABOVE. IN GENERAL MORE THAN ONE OPTION CAN
BE INCLUDED IN ANY COMMAND STRING. IF COMMENTS OR OPTIONS ARE INCLUDED
IN A CASE WHERE THEY ARE NOT MEANINGFUL, THEY WILL BE IGNORED.

V.  EXAMPLES OF COMMANDS

            DISK TO TAPE

    TAPE:=FILENAME.TYP    'OPTIONAL COMMENTS'
    TAPE:=B:*.COM      RECORDED DEC 26 1977
    TAPE:=A:MYPROG.ASM    NODISPLAY

            TAPE TO DISK

    DISK:=*.COM
    A:=GAME.BAS   RENAME NEWGAME.BAS
    B:=TESTPROG.ASM     VERIFY

            OTHER COMMANDS

    TAPE:=SYNC:        (WRITE 6 MIN OF SYNC CODE)
    RUN:=ANYPROG.COM    (LOAD FROM TAPE AND EXECUTE)


    THE FORMAT OF COMMAND STRINGS IS FREE EXCEPT FOR THE SOURCE
AND DESTINATION. THE EQUAL SIGN AND COLONS ARE REQUIRED AND NO SPACES
ARE PERMITTED IN THE SOURCE OR DESTINATION. THE OPTIONS AND COMMENTS
MAY BE TYPED ANYWHERE ON THE INPUT LINE. INTERVENING SPACES WILL BE
SKIPPED OVER.
    TO RENAME A FILE DURING A TAPE TO DISK COPY ENTER THE WORD
RENAME FOLLOWED BY THE NEW FILE NAME AND TYPE ANYWHERE ON THE INPUT
LINE FOLLOWING THE SOURCE. THIS FEATURE IS USEFUL IF A FILE WITH THE
SAME NAME ALREADY EXISTS ON THE DISK.
    TO VERIFY A FILE OR GROUP OF FILES EXECUTE A TAPE TO DISK COPY
OPERATION WITH THE WORD VERIFY ANYWHERE FOLLOWING THE SOURCE. THE COPY
OPERATION WILL NOT ACTUALLY TAKE PLACE. INSTEAD THE FILE WILL BE READ
FROM TAPE AND COMPARED BYTE BY BYTE WITH THE FILE OF THE SAME NAME ON
THE DISK SPECIFIED. IF THE FILES ARE NOT THE SAME THE PROGRAM DISPLAYS

    VERIFY ERROR

IF THE FILES ARE THE SAME THE PROGRAM WILL DISPLAY:

    VERIFIED SUCCESSFULLY

    TO RUN A PROGRAM FROM TAPE TYPE RUN: AS THE DESTINATION. THE
PROGRAM CHECKS THE FILE TYPE BEFORE EXECUTION BEGINS AND WILL DISPLAY
AN ERROR MESSAGE IF THE FILE IS NOT TYPE 'COM'. COM FILES ARE MOVED TO
STARTING LOCATION 100H BEFORE BEING EXECUTED.

VII.  PROMPTS AND ERROR MESSAGES

    TAPELIB ASSUMES THAT ONLY AN INEXPENSIVE NON CONTROLED CASSETTE
TAPE RECORDER IS BEING USED. THE PROGRAM HALTS AT THE PROPER TIMES AND
DISPLAYS INSTRUCTIONS FOR STARTING AND STOPPING THE TAPE. FOR EXAMPLE
TO COPY DISK TO TAPE THE PROGRAM WILL PAUSE AND DISPLAY:

    START CASSETTE TAPE <<RECORD>> - TYPE CARRIAGE RETURN

FOR TAPE TO DISK OPREATIONS THE MESSAGE WILL BE:

    START CASSETTE TAPE - TYPE CARRIAGE RETURN

THE TAPE SHOULD BE STARTED IN THE PROPER MODE BEFOR TYPING THE CARRIAGE
RETURN.
    TAPELIB IS EXTENSIVELY TRAPPED FOR ERRORS. IF AN ERROR OCCURS
THE PROGRAM WILL DISPLAY AN ERROR MESSAGE AND PAUSE TO ALLOW THE ERROR
TO BE CORRECTED IF POSSIBLE. THE FOLLOWING TABLE CONTAINS ERROR MESSAGES,
THEIR PROBABLE CAUSE AND POSSIBLE CORRECTION.

            ERROR TABLE

1.  ERROR IN FILE NAME        INCORRECT FILE NAME - REENTER NAME

2.  NO SUCH DESTINATION        INCORRECT DESTINATION, MUST BE TAPE:
                DISK:, A:, B:, OR RUN: - REENTER

3.  NO FILE BY THAT NAME    INCORRECT NAME OR DRIVE - REENTER
    ON DRIVE A

4.  CHECKSUM ERROR        CHECK SUM ON TAPE DOES NOT AGREE WITH
                COMPUTED SUM. - VARIETY OF CAUSES
                CHECK TERMINAL SPEED 4800 BAUD OR GREATER
                REWIND TAPE TO BEGINNING OF FILE AND
                TYPE CARRIAGE RETURN

5.  VERIFY ERROR        A BYTE IN THE TAPE FILE DOES NOT MATCH
                THE DISK COPY - CHECK FOR INCORRECT TAPE
                OR DISK

6.  ERROR - FILE TYPE NOT <COM>    ONLY COM TYPE FILES CAN BE EXECUTED - LOAD
    - CANNOT BE RUN        FILE TO DISK AND RENAME

7.  DISK READ ERROR         CP/M SYSTEM ERROR IN DISK READ

8.  DISK WRITE ERROR - DISK    DISK FILLED - CHANGE DISKS
    OR DIRECTORY FULL

VII.  TAPE FORMAT

    THE FORMAT FOR EACH RECORD ON THE TAPE IS AS FOLLOWS:


    1.  START BYTES        03CH  (100)
    2.  SYNC  BYTE        06EH
    3.  DECODE BYTE        0FFH   (CONTROLS DISPLAY)
    4.  TYPE  BYTE        0,1 OR 2
    5.  LENGTH BYTE        NO OF 256 BYTE RECORDS
    6.  NAME        CP/M FILE NAME  (11 BYTES)
    7.  COMMENT        110 BYTES AVAILABLE BLANK IF NOT USED
    8.  DATA        MULTIPLES OF 256 BYTE RECORDS
    9.  CHECKSUM        ONE BYTE TARBELL CHECKSUM

    IF A FILE IS UNBLOCKED IT WILL CONTAIN ONLY ONE CONTINUOUS
RECORD IN THE FORMAT GIVEN ABOVE. IF A FILE IS BLOCKED ONLY THE
FIRST RECORD OF THE FILE CONTAINS THE NAME AND COMMENT, THE REMAINING
FIELDS HOWEVER ARE THE SAME.
    EACH FILE IS PRECEEDED BY A BLOCK OF 1500 START BYTES
FOLLOWED BY 100 HALT BYTES (76H). THE START BYTE BLOCK PROVIDES TIME
FOR DISK OPERATIONS TO COMPLETE AND THE HALT BYTES SERVE TO INDENTIFY
THE BEGINNING OF A FILE. THE NUMBER OF BYTES IN A TAPE RECORD IS
ALWAYS A MULTIPLE OF 256 NOT COUNTING THE START,SYNC,TYPE,LENGTH
AND DECODE BYTES. IF DATA DOES NOT EXACTLY FILL A RECORD, THE
REMAINDER OF THE RECORD IS FILLED WITH 1AH BYTES (THE CP/M END OF FILE
CODE).
    THE BLOCKS OF A BLOCKED RECORD ARE SEPARATED BY APPROX 1 SECOND
BLOCKS OF START BYTES. TWO OF THE BLOCKS ARE APPROX 3 SECONDS LONG TO
ALLOW FOR THE EXTRA TIME REQUIRED IF THE FILE HAS MORE THAN ONE EXTENT.

VIII.  COMMENTS

    SEVERAL POINTS SHOULD BE KEPT IN MIND WHEN USING TAPELIB
TAPE IS NOT NEARLY AS RELIABLE AS DISK FOR DATA STORAGE. ALWAYS
VERIFY TAPE COPIES OF DISK FILES BEFORE DESTROYING THE ORIGINALS.
USE REASONABLE QUALITY TAPE AND KEEP CASSETTE RECORDER HEADS CLEAN.
    BECAUSE THERE IS NO DIRECTORY ON TAPES, BLOCK COPY OPERATIONS
FROM TAPE TO DISK DO NOT WORK AS RELIABLY AS DISK TO DISK COPIES.
THE PROGRAM HAS NO WAY OF TELLING WHEN ALL THE FILES ON A TAPE HAVE
BEEN FOUND. IT IS UP TO THE USER TO STOP THE TAPE AT THE PROPER
TIME WITHOUT PROMPTING FROM THE PROGRAM.
    TAPE RECORDS ARE LABLED AND THEREFORE TAPE POSITIONING IS
NOT AT ALL CRITICAL. AS LONG AS THE TAPE STARTS BEFORE THE RECORD
REQUESTED THE PROGRAM WILL FIND THE FILE. THE PROGRAM MAY EVEN BE
STARTED WHILE READING LEADER.  HOWEVER IF TAPES ARE NOT ERASED
BEFORE USE, OLD FILES AT THE END OF THE TAPE MAY BE FOUND AND READ
DURING BLOCK COPY OPERATIONS. THE COPY-ALL OPERATION:

    DISK:=*.*

IS THE WORST OFFENDER IN THIS RESPECT. IT IS RECOMMENDED THAT TAPES
BE COMPLETELY ERASED BEFORE BEING USED AS BACK UP FOR ALL THE
FILES ON A DISK.
    CASSETTE RECORDERS ARE NOT CONTROLABLE DEVICES. IN GENERAL
THE PROGRAM HAS TO ACCEPT DATA AT THE FIXED SPEED COMING TO IT
FROM THE TAPE, 187 BYTES PER SECOND FOR TARBELL STANDARD. SUFFICIENT
SPACE MUST BE LEFT ON THE TAPE BETWEEN RECORDS TO ALLOW COPY TIME TO
DISK IF BLOCK COPIES ARE TO BE PERFORMED. ALTHOUGH LARGE GAPS ARE LEFT
ON THE TAPE BETWEEN FILES THE TIME MAY NOT BE SUFFICIENT IN ALL CASES.
IF THE TAPE DENSITY IS NOT TARBELL STANDARD OR DISK ERRORS OCCUR
REQUIRING MULTIPLE READS FOR ERROR CORRECTION ERRORS MAY OCCUR.
THE TYPE OF ERRORS WILL BE MISSED FILES DURING BLOCK COPIES OR MISSED
BLOCKS WHILE COPYING BLOCKED TAPES. SIMPLE INSPECTION WILL DETECT MISSING
FILES. SCAN THE TAPE AND COUNT THE RECORDS. MISSING BLOCKS ARE MORE
DIFFICULT BUT CAN USUALLY BE DETECTED BY REVERIFICATION OF THE TAPE.

IX.  TIMING DATA AND SPACE CONSIDERATIONS

    DATA TRANSFER RATES (APPROX)
        UNBLOCKED RECORDS        187 BYTES/SEC
        BLOCKED RECORDS            140 BYTES/SEC
    TIME BETWEEN FILES            8 SECONDS
    TIME BETWEEN BLOCKS            0.85 SECONDS

    LOAD TIME FROM TAPE FOR 10K BYTES
        UNBLOCKED RECORD        72 SECONDS
        BLOCKED RECORDS            83 SECONDS

    ONE SIDE OF A C-60 TAPE WILL USUALLY STORE THE CONTENTS OF ONE
FLOPPY DISK.