Type ASSEMBLE
Source Lines : 645
Fixes Applied : 2
Most Recent Version : Tuesday, December 12, 1978
Last Fix ID : [R12074DS]

Function

       DMSREA IS AN INTERFACE MODULE FOR THE CMS CPEREP COMMAND.
       DMSREA READS A SPECIFIED LOGICAL RECORD FROM THE VM/370
       ERROR RECORDING CYLINDERS AND RETURNS IT TO THE CALLER.
       THE CALLER SPECIFIES WHICH LOGICAL RECORD HE WANTS BY
       PASSING A RECORD ADDRESS TO DMSREA.  THE RECORD ADDRESS
       FORMAT RESEMBLES THE STANDARD 5 BYTE CCHHR DISK ADDRESS
       FORMAT, BUT IS A LITTLE DIFFERENT.  THE FORMAT IS:
         CCB0R
       WHERE:
         CC - IS THE RELATIVE DASD CYLINDER ADDRESS (RELATIVE TO
              THE FIRST OF THE ERROR CYLINDERS, E.G., CC IS
              X'0000', X'0001', ...,X'0008').
         B  - IS THE NUMBER OF THE 4K BLOCK (OR PAGE) WITHIN THE
              SPECIFIED DASD CYLINDER.
         0  - A BYTE OF ZERO.
         R  - LOGICAL RECORD NUMBER OF A RECORD WITHIN THE
              SPECIFIED BLOCK.  THE BLOCK CONTAINS VARIABLE LENGTH
              RECORDS, EACH PRECEEDED BY THE STANDARD 4 BYTE RECORD
              DESCRIPTOR WORD WHICH CONTAINS THE RECORD LENGTH.
              SINCE RECORDS IN THE ERROR RECORDING CYLINDERS ARE
              NEVER LESS THAN 24 BYTES IN LENGTH, THERE CANNOT BE
              MORE THAN 255 RECORDS IN A BLOCK.  RECORDS WITHIN
              A BLOCK ARE NUMBERED 1 THRU M.
       THE CCB0R ADDRESS IS NOT ONLY RECEIVED FROM THE CALLER,
       BUT IS RETURNED TO HIM AFTERWARDS AS WELL, FOR REASONS
       THAT WILL SOON BE APPARENT.  SOMETIMES THE REQUESTED RECORD
       DOES NOT EXIST OR CANNOT BE READ (DUE TO AN I/O ERROR).
       IN THESE CASES, THE NEXT LOGICAL RECORD IS RETURNED TO THE
       CALLER INSTEAD.  AND IN THESE CASES THE CCB0R ADDRESS
       RETURNED TO THE CALLER IS A CORRECTED CCB0R ADDRESS THAT
       SHOWS WHAT RECORD WAS ACTUALLY GOTTEN.  SOME EXAMPLES
       WILL CLARIFY THIS.

       ASSUMPTIONS FOR EXAMPLES:
         * EACH CYLINDER CONTAINS 10 (=X'0A') OF THE 4K BLOCKS.
         * NO RECORDS WERE RECORDED IN THE 1ST (CC=X'0000') CYLINDER,
           I.E., ALL 10 BLOCKS THERE ARE FLAGGED AS EMPTY.
         * BLOCK 1 IN THE 2ND CYLINDER CONTAINS 7 RECORDS.
         * BLOCK 2 IN THE 2ND CYLINDER IS FLAGGED AS UNREADABLE OR
           EMPTY.
         * BLOCK 3 IN THE 2ND CYLINDER CONTAINS 5 RECORDS.
         * BLOCK 4 IN THE 2ND CYLINDER CONTAINS 3 RECORDS.
         * THE REMAINING BLOCKS OF THE 2ND CYLINDER ARE EMPTY.
       EXAMPLE 1:
         THE CALLER PASSES X'0001030005' AS THE CCB0R ADDRESS.
         THE REQUESTED RECORD 5 IN BLOCK 3 OF THE 2ND CYLINDER
         EXISTS, SO THE REQUESTED RECORD IS RETURNED.  AND THE
         ORIGINAL CCB0R VALUE IS RETURNED UNCHANGED.
       EXAMPLE 2:
         THE CALLER WANTS TO READ THE NEXT SEQUENTIAL RECORD AFTER
         THE ONE HE READ IN EXAMPLE 1.  SO HE ADDS 1 TO THE R
         VALUE OF THE CCB0R ADDRESS RETURNED IN EXAMPLE 1, GETTING
         X'0001030006', WHICH HE NOW PASSES TO DMSREA.  SINCE
         THERE IS NO RECORD 6 IN BLOCK 3, DMSREA RETURNS THE NEXT
         AVAILABLE RECORD WHICH IS RECORD 1 IN BLOCK 4.  AND THE
         RETURNED ADDRESS IS X'0001040001'.
       EXAMPLE 3:
         THE CALLER PASSES X'0001010008' AS THE CCB0R ADDRESS.
         THERE IS NO RECORD 8 IN BLOCK 1, SO DMSREA TRIES TO GET
         RECORD 1 FROM BLOCK 2, BUT BLOCK 2 IS FLAGGED AS
         UNREADABLE, SO IT ADVANCES TO BLOCK 3 AND RETURNS RECORD
         1 OF BLOCK 3.  THE RETURNED ADDRESS IS X'0001030001'.
       EXAMPLE 4:
         THE CALLER PASSES X'0000050005', ATTEMPTING TO READ
         NON-EXISTENT DATA FROM THE EMPTY 1ST CYLINDER.  DMSREA
         SCANS THRU BLOCKS 5 THRU 10 OF THE 1ST CYLINDER, FINDING
         NOTHING, AND THEN SWITCHES TO THE 2ND CYLINDER.  THERE
         IT FINDS AND RETURNS RECORD 1 OF BLOCK 1 AND RETURNS
         THE ADDRESS X'0001010001'.
       EXAMPLE 5:
         THE CALLER PASSES X'00000B0001', ATTEMPTING TO READ FROM
         THE 1ST CYLINDER, BUT BEYOND THE ALLOWED LIMIT OF
         10 (=X'0A') BLOCKS PER CYLINDER (AS ASSUMED FOR THIS
         EXAMPLE).  THIS IS NOT ALLOWED.  THE RESULTS ARE
         UNPREDICTABLE.  (NOTE: THE CALLER IS NOT EXPECTED TO
         KNOW HOW MANY BLOCKS ARE ALLOWED IN A CYLINDER ON A
         PARTICULAR DEVICE.  RATHER, IT IS EXPECTED THAT HE WILL
         ONLY USE ADDRESSES THAT HAVE BEEN RETURNED TO HIM FROM
         PRIOR CALLS TO DMSREA, WITH ONLY THE R FIELD CHANGED BY
         HIM.  AN EXCEPTION IS THAT HE IS PERMITTED TO MAKE UP
         AN ADDRESS HIMSELF TO GET STARTED AT THE FIRST BLOCK
         OF EITHER CYLINDER.)
       EXAMPLE 6:
         THE CALLER PASSES X'0001040004' REQUESTING A RECORD
         FOLLOWING THE FINAL RECORD OF BLOCK 4, 2ND CYLINDER.
         BLOCKS BEYOND BLOCK 4 ARE ALL EMPTY.  DMSREA LOOKS FOR,
         BUT FAILS TO FIND, A NEXT AVAILABLE RECORD IN THE
         REMAINING BLOCKS.  SO DSMREA RETURNS AN END-OF-FILE
         INDICATION RATHER THAN A NEXT AVAILABLE RECORD.
       EXAMPLE 7:
         FORGET THE ASSUMPTIONS OF THE EARLIER EXAMPLES.  ASSUME
         NOW THAT ALL CYLINDERS ARE EMPTY. THE CALLER PASSES
         X'0000010001' REQUESTING THE FIRST RECORD OF THE FIRST
         CYLINDER. DMSREA READS THRU ALL CYLS LOOKING FOR
         AN AVAILABLE RECORD AND FINALLY RETURNS AN END-OF-FILE
         INDICATION RATHER THAN A RECORD.

Operation

       1. SAVE REGISTERS AS NECESSARY.  SET R15 RETURN CODE TO 0.
       2. IF THIS IS NOT THE FIRST CALL TO DMSREA, GO TO 4.
       3. ISSUE DIAGNOSE X'2C' TO FIND THE START OF THE VM/370
          ERROR RECORDING CYLINDERS.  STORE RETURNED ADDRESS VALUE
          IN 'STARTCYL'.  'AVAILBLK' IS INITIALLY ZERO; NON-EXISTENT
          ZERO ADDRESS INSURES THAT IN CODE BELOW WE DO NOT GET
          FOOLED INTO THINKING 4K BUFFER CONTAINS A BLOCK.
          THROW 'FIRST TIME' SWITCH. STORE COUNT OF RECORD-
          ING CYLINDERS IN 'CYLCOUNT'.
       4. CHECK CC PORTION OF INPUTTED CCB0R FOR VALID RANGE.
          IF INVALID, GO TO 16.
       5. CONVERT CCB PORTION OF INPUTTED CCB0R ADDRESS TO A
          'VM/370 CONTROL PROGRAM INTERNAL FORMAT (CPIF)' ADDRESS.
       6. IF COMPUTED CPIF ADDRESS MATCHES VALUE IN 'AVAILBLK',
          THEN DESIRED BLOCK IS ALREADY IN BUFFER, SO GO TO 11.
       7. SET 'RECNO' TO ZERO INDICATING WE HAVE NOT YET COUNTED UP
          TO ANY PARTICULAR RECORD IN THE NEW BLOCK ABOUT TO BE
          READ IN.  SET 'AVAILBLK' TO ZERO (WE COULD ALMOST AS WELL
          SET IT TO THE NEW CPIF ADDRESS SINCE WE ARE ABOUT TO
          READ THAT BLOCK INTO THE BUFFER; BUT THE READ COULD FAIL
          AND ZERO BEST INDICATES UNDEFINED STATE OF THE BUFFER).
          ISSUE DIAGNOSE X'30' USING COMPUTED CPIF ADDRESS TO READ
          THE ADDRESSED BLOCK.  TEST CONDITION CODE SET BY DIAGNOSE:
             CC=0: BLOCK WAS READ SUCCESSFULLY; GO TO 10.
             CC=1: END OF CYLINDER, ADDRESSED BLOCK IS NON-EXISTENT;
                   GO TO 17.
             CC=3: SPECIFIED CYLINDER IS OUTSIDE THE ERROR RECORDING
                   AREA; GO TO 16.
             CC=2: I/O ERROR,BLOCK COULD NOT BE READ; FALL THRU TO 8.
       8. ISSUE MESSAGE DMSREA830E (I/O ERROR), SET CODE 60 FOR R15.
          (WE CANNOT GET THE ADDRESSED RECORD, SO WE WILL TRY FOR
          THE NEXT AVAILABLE RECORD INSTEAD.)
       9. PREPARE TO READ NEXT BLOCK AND USE FIRST RECORD IN IT:
          ADD ONE TO BLOCK NUMBER IN CPIF ADDRESS; SET R VALUE OF
          CCB0R TO RECORD 1; GO TO 7.

      10. STORE CPIF ADDRESS IN 'AVAILBLK'.
          IF THE BLOCK IS FLAGGED AS EMPTY, GO TO 9.
      11. (COMMENT: BLOCK SPECIFIED BY CPIF ADDRESS IS NOW IN THE
          BUFFER AND DOES CONTAIN SOME RECORDS.  'RECNO' AND
          'RECADDR' EITHER POINT TO SOME RECORD IN THE BUFFER OR
          'RECNO' IS ZERO.  R IN CCB0R SPECIFIES THE RECORD WE
          WANT TO FIND IN THE BUFFER.)
          IF 'RECNO' IS GREATER THAN R, SET 'RECNO' TO ZERO.
      12. IF 'RECNO' IS ZERO, SET IT TO ONE AND INITIALIZE
          'RECADDR' TO POINT TO FIRST RECORD IN BUFFER.
      13. (COMMENT: STEP THRU THE BUFFER INCREMENTING 'RECNO'
          AND 'RECADDR' UNTIL 'RECNO' MATCHES R OR UNTIL THERE
          ARE NO MORE RECORDS IN THE BUFFER.)
          IF 'RECNO' EQUALS R, GO TO 14.
          INCREMENT 'RECNO' BY ONE AND ADVANCE 'RECADDR' TO NEXT
          RECORD, IF ANY.
          IF 'RECADDR' IS BEYOND LAST RECORD IN BUFFER, GO TO 9.
          OTHERWISE, LOOP TO 13 FOR ANOTHER ITERATION.

      14. FROM THE CURRENT R AND CPIF ADDRESS, COMPUTE A CORRECTED
          CCB0R VALUE TO BE RETURNED TO THE CALLER.  PUT ADDRESS
          OF CORRECTED CCB0R DATA IN R1.  LOAD 'RECADDR' INTO R0.
      15. RESTORE REGISTERS (EXCEPT OUTPUT PARAMETER REGISTERS) AND
          RETURN TO THE CALLER.

      16. SET ERROR CODE IN R15 FOR INVALID CYLINDER.  GO TO 15.

      17. (COMMENT: END OF CYLINDER INDICATION WAS RECEIVED.)
          SET R0 TO ZERO (INDICATES EOF TO CALLER IN CASE THIS
          CYLINDER IS THE LAST CYLINDER).
          IF CC PORTION OF CPIF ADDRESS INDICATES WE WERE ALREADY
          ON THE FINAL CYLINDER, GO TO 15.
          OTHERWISE ADVANCE TO NEXT CYLINDER: ADD 1 TO CC OF CPIF
          ADDRESS; SET B OF CPIF ADDRESS TO BLOCK 1; SET R OF CCB0R
          ADDRESS TO RECORD 1;
          GO TO 7 (TO READ FIRST AVAILABLE RECORD IN NEXT CYLINDER).

Calls to Other Routines

       DIAGNOSE CALLS TO CP AS BELOW:
            DIAGNOSE CODE X'2C' = FIND RECORDING AREA ON SYSTEM DISK.
            DIAGNOSE CODE X'30' = READ PAGE SIZE RECORD FROM ERROR
            RECORDING CYLINDERS.
       DMSERR - CALLED VIA MACRO SVC TO WRITE ERROR MESSAGE TO
                THE CONSOLE.