Type ASSEMBLE
Source Lines : 1,519
Fixes Applied : 3
Most Recent Version : Tuesday, December 12, 1978
Last Fix ID : [HRC012DS]
Module
DMSBWR (WRBUF)
Function
TO WRITE ONE OR MORE SUCCESSIVE ITEMS INTO A
SPECIFIED DISK FILE.
Attributes
NUCLEUS RESIDENT, REENTRANT, CALLED BY BALR OR SVC
Operation
WRBUF FIRST PERFORMS A SERIES OF TESTS TO ENSURE THAT
THE PARAMETER LIST IS LEGAL. IF IT IS NOT, WRBUF
SIGNALS THE ERROR AND RETURNS TO THE CALLING PROGRAM.
IF THE PARAMETER IS LEGAL, WRBUF CALLS THE ACTLKP
ROUTINE TO SEE IF THE FILE EXISTS AND IS ACTIVE; IF
YES, PROCESSING PROCEEDS AS DESCRIBED UNDER "FILE
ACTIVE". IF NOT, WRBUF CALLS THE FSTLKW FUNCTION
PROGRAM TO DETERMINE WHETHER THE SPECIFIED FILE
EXISTS. IF YES, PROCESSING PROCEEDS AS DESCRIBED
UNDER "FILE EXISTS, NOT ACTIVE". IF NOT, PROCESSING
PROCEEDS AS DESCRIBED UNDER "FILE DOES NOT EXIST".
FILE DOES NOT EXIST:
IF THE FILE DOES NOT EXIST, WRBUF CALLS ADTLKP TO
DETERMINE THE ACTIVE DISK TABLE PERTAINING TO THE
GIVEN MODE, AND CHECKS TO ENSURE THAT THE DISK IS
AVAILABLE AND IN READ-WRITE STATUS (ERROR RETURN IF
NOT). THEN ACTFREE IS CALLED TO OBTAIN AN AVAILABLE
SLOT IN THE ACTIVE FILE TABLE FOR THE FILE ABOUT TO
BE CREATED. THEN WRBUF INITIALIZES THE AFT ENTRY
WITH NECESSARY INFORMATION INCLUDING THE NAME, TYPE,
AND MODE OF THE FILE. WRBUF THEN CALLS THE QQTRK
ROUTINE TO OBTAIN AN AVAILABLE SIXTEENTH OF A TRACK
OF DISK SPACE FOR USE AS THE FIRST CHAIN LINK AND
STORES THE DISK ADDRESS RETURNED BY QQTRK IN THE FILE
STATUS TABLE. NEXT, WRBUF CALCULATES (FROM THE ITEM
NUMBER SUPPLIED IN THE PARAMETER LIST) THE DATA BLOCK
INTO WHICH THE ITEM(S) IS/ARE TO BE WRITTEN. THIS
CALCULATION ALSO YIELDS THE LOCATION WITHIN THE DATA
BLOCK AT WHICH THE ITEM(S) WILL RESIDE. (THE
CALCULATION IS ((N-1)*L)/800. N IS THE ITEM NUMBER, L
IS THE ITEM LENGTH, AND 800 IS THE LENGTH OF A DATA
BLOCK. THE QUOTIENT PRODUCED BY THIS CALCULATION IS
THE NUMBER OF THE AFFECTED DATA BLOCK AND THE
REMAINDER IS THE DISPLACEMENT INTO THE DATA BLOCK AT
WHICH THE ITEM(S) WILL RESIDE.) NEXT, WRBUF
CALCULATES THE NUMBER OF BYTES TO BE WRITTEN. THIS
IS EQUAL TO THE ITEM LENGTH MULTIPLIED BY THE NUMBER
OF ITEMS TO BE WRITTEN. BOTH VALUES ARE OBTAINED
FROM THE PARAMETER LIST. WRBUF THEN MARKS THE FILE
ACTIVE, OBTAINS BUFFER SPACE FOR THE DATA BLOCK, AND
DETERMINES IF THE ITEM TO BE WRITTEN IS OF FIXED OR
VARIABLE LENGTH. IF OF VARIABLE LENGTH, PROCESSING
PROCEEDS AS DESCRIBED UNDER "VARIABLE-LENGTH ITEM".
IF OF FIXED LENGTH, PROCESSING PROCEEDS AS DESCRIBED
BELOW.
FIXED-LENGTH ITEM: WRBUF DETERMINES THE CHAIN LINK
THAT SHOULD CONTAIN THE ADDRESS OF THE AFFECTED DATA
BLOCK. (ORDINARILY, AT THIS POINT, THIS WILL BE THE
FIRST CHAIN LINK AND IT WILL EXIST IN MAIN STORAGE.)
IF THIS CHAIN LINK DOES NOT EXIST (THAT IS, ITS
CORRESPONDING ENTRY IN THE FIRST CHAIN LINK IS NOT A
VALID DISK ADDRESS), WRBUF CALLS THE TRKLKP FUNCTION
PROGRAM TO OBTAIN A QUARTER OF A TRACK FOR THE NEW
CHAIN LINK, INSERTS THE DISK ADDRESS RETURNED BY
TRKLKP INTO THE CHAIN LINK DIRECTORY OF THE ACTIVE
FILE TABLE ENTRY, AND OBTAINS STORAGE FOR USE IN
CONSTRUCTING THE NEW CHAIN LINK. IF THE CHAIN LINK
EXISTS, WRBUF CALLS THE RDTK FUNCTION PROGRAM TO READ
IT INTO MAIN STORAGE. WRBUF THEN DETERMINES IF THE
AFFECTED DATA BLOCK EXISTS. (IT WILL IF THE
CORRESPONDING ENTRY IN THE CHAIN LINK THAT IS IN MAIN
STORAGE CONTAINS A VALID DISK ADDRESS.) IF IT DOES
NOT EXIST, WRBUF CALLS THE TRKLKP FUNCTION PROGRAM TO
OBTAIN A QUARTER OF A TRACK FOR THE NEW DATA BLOCK,
INSERTS THE DISK ADDRESS RETURNED BY TRKLKP INTO THE
APPROPRIATE ENTRY IN THE CHAIN LINK THAT IS IN MAIN
STORAGE, AND CLEARS THE DATA BLOCK BUFFER FOR USE IN
CONSTRUCTING THE DATA BLOCK. IF THE DATA BLOCK
EXISTS, WRBUF CALLS THE RDTK FUNCTION PROGRAM TO READ
IT INTO THE DATA BLOCK BUFFER. WRBUF THEN CALCULATES
THE NUMBER OF BYTES IN THE DATA BLOCK BUFFER THAT ARE
AVAILABLE FOR USE. (THE NUMBER OF BYTES AVAILABLE IS
EQUAL TO 800 MINUS THE PREVIOUSLY CALCULATED
DISPLACEMENT.) NEXT, WRBUF DETERMINES WHETHER THE
NUMBER OF BYTES TO BE WRITTEN IS GREATER THAN THE
NUMBER OF BYTES AVAILABLE IN THE DATA BLOCK BUFFER.
IF THE NUMBER OF BYTES TO BE WRITTEN IS NOT GREATER
THAN THE NUMBER AVAILABLE, WRBUF MOVES THE BYTES TO
BE WRITTEN FROM THE INPUT BUFFER TO THE BLOCK BUFFER
AND RETURNS TO THE CALLING PROGRAM. (IN THIS CASE,
THE DATA BLOCK IS NOT WRITTEN ONTO DISK BECAUSE IT IS
NOT FULL.) IF THE NUMBER OF BYTES TO BE WRITTEN
EXCEEDS THE NUMBER OF BYTES AVAILABLE, WRBUF MOVES
SUFFICIENT BYTES INTO THE DATA BLOCK BUFFER TO FILL
IT, AND WRITES THE COMPLETED DATA BLOCK ONTO DISK.
WRBUF THEN DETERMINES IF THE CHAIN LINK THAT SHOULD
CONTAIN THE ADDRESS OF THE DATA BLOCK THAT IS TO
RECEIVE THE OVERFLOW FROM THE PREVIOUS DATA BLOCK IS
IN MAIN STORAGE. IF IT IS NOT, WRBUF WRITES THE
CURRENT CHAIN LINK (THAT IS, THE ONE IN MAIN STORAGE)
ONTO DISK AND RETRIEVES THE CHAIN LINK CONTAINING THE
ADDRESS OF THE DATA BLOCK THAT IS TO RECEIVE THE
OVERFLOW. THIS CHAIN LINK MAY OR MAY NOT EXIST. IF
THE CHAIN LINK DOES NOT EXIST, WRBUF ALLOCATES DISK
SPACE FOR THE NEW CHAIN LINK IN THE PREVIOUSLY
DESCRIBED MANNER AND DETERMINES IF THE DATA BLOCK
THAT IS TO RECEIVE THE OVERFLOW EXISTS AS PREVIOUSLY
DESCRIBED. IF THE CHAIN LINK EXISTS, WRBUF READS IT
INTO MAIN STORAGE AND DETERMINES IF THE DATA BLOCK TO
RECEIVE THE OVERFLOW EXISTS. WHEN THE DATA BLOCK
THAT IS TO RECEIVE THE OVERFLOW IS IN MAIN STORAGE,
(THAT IS, IN THE DATA BLOCK BUFFER) WRBUF CALCULATES
THE NUMBER OF BYTES REMAINING TO BE WRITTEN. IF THIS
IS NOT GREATER THAN THE NUMBER OF BYTES AVAILABLE IN
THE DATA BLOCK BUFFER (ON OVERFLOW, ALL 800 BYTES OF
THE DATA BLOCK BUFFER ARE AVAILABLE), WRBUF MOVES THE
REMAINING BYTES FROM THE INPUT BUFFER TO THE DATA
BLOCK BUFFER AND RETURNS TO THE CALLER. IF THE
NUMBER OF BYTES REMAINING TO BE WRITTEN IS GREATER
THAN THE NUMBER OF BYTES AVAILABLE IN THE DATA BLOCK
BUFFER, WRBUF MOVES SUFFICIENT BYTES INTO THE DATA
BLOCK BUFFER TO FILL IT, WRITES THE DATA BLOCK ONTO
DISK, AND MOVES THE OVERFLOW INTO THE NEXT DATA BLOCK
AS DESCRIBED.
VARIABLE-LENGTH ITEM: WRBUF READS SUCCESSIVE DATA
BLOCKS (STARTING WITH THE FIRST) INTO THE DATA BLOCK
BUFFER UNTIL IT LOCATES THE ONE THAT CONTAINS THE
ITEM IMMEDIATELY PRECEDING THE ONE THAT CORRESPONDS
TO THE ITEM NUMBER SPECIFIED IN THE PARAMETER LIST.
IT THEN LOCATES THE END OF THAT ITEM. (THIS MAY
ENTAIL READING ADDITIONAL DATA BLOCKS, DEPENDING ON
THE LENGTH OF THE ITEM.) WHEN IT LOCATES THE END OF
THE ITEM, WRBUF MOVES THE LENGTH OF THE ITEM TO BE
WRITTEN FROM THE INPUT BUFFER TO THE LOCATION IN THE
DATA BLOCK BUFFER IMMEDIATELY AFTER THE END OF THE
PREVIOUS ITEM. IT THEN MOVES THE ITEM TO BE WRITTEN
FROM THE INPUT BUFFER TO THE DATA BLOCK BUFFER IN THE
SAME MANNER AS FOR FIXED-LENGTH ITEMS. (IF OVERFLOW
OCCURS, IT IS HANDLED IN THE SAME MANNER AS FOR
FIXED-LENGTH ITEMS.)
FILE EXISTS, NOT ACTIVE:
IF THE FILE EXISTS BUT IS NOT ACTIVE, WRBUF
CALCULATES THE DATA BLOCK INTO WHICH THE ITEM(S) IS
TO BE WRITTEN. THIS CALCULATION ALSO YIELDS THE
LOCATION WITHIN THE DATA BLOCK AT WHICH THE ITEM(S)
WILL RESIDE. ACTFREE IS CALLED TO OBTAIN AN
AVAILABLE SLOT IN THE ACTIVE FILE TABLE AND TO STORE
THE FST ENTRY THEREIN. NEXT, WRBUF MARKS THE FILE AS
ACTIVE, READS THE FIRST CHAIN LINK INTO MAIN STORAGE,
AND MOVES THE FIRST 80 BYTES OF THE FIRST CHAIN LINK
INTO THE CHAIN LINK DIRECTORY OF THE ACTIVE FILE
TABLE ENTRY. WRBUF THEN DETERMINES IF THE ITEM(S) TO
BE WRITTEN ARE OF FIXED OR VARIABLE LENGTH. FOR BOTH
OF THESE ITEM TYPES, WRBUF PROCEEDS AS DESCRIBED
UNDER THE CORRESPONDING HEADING IN "FILE DOES NOT
EXIST" IN THIS SECTION.
FILE ACTIVE:
IF THE FILE IS ACTIVE, WRBUF CALCULATES THE DATA
BLOCK INTO WHICH THE ITEM(S) IS/ARE TO BE WRITTEN.
THIS CALCULATION ALSO YIELDS THE DISPLACEMENT INTO
THE DATA BLOCK AT WHICH THE ITEM(S) WILL RESIDE.
NEXT, WRBUF DETERMINES THE NATURE OF THE ITEM(S) TO
BE WRITTEN. IF OF VARIABLE LENGTH, WRBUF PROCEEDS AS
DESCRIBED UNDER "VARIABLE-LENGTH ITEM". IF OF FIXED
LENGTH, IT PROCEEDS AS DESCRIBED BLOW.
FIXED-LENGTH ITEM: WRBUF DETERMINES WHETHER THE
AFFECTED DATA BLOCK IS IN MAIN STORAGE. IF IT IS,
WRBUF PROCEEDS AS DESCRIBED UNDER "FILE DOES NOT
EXIST", STARTING AT THE POINT WHERE THE NUMBER OF
BYTES AVAILABLE IN THE DATA BLOCK BUFFER IS
CALCULATED. IF THE AFFECTED DATA BLOCK IS NOT IN MAIN
STORAGE, WRBUF PROCEEDS IN ESSENTIALLY THE SAME
MANNER AS DESCRIBED UNDER "FILE DOES NOT EXIST",
STARTING AT THE POINT WHERE THE DATA BLOCK IS WRITTEN
ONTO DISK. (IN THIS CASE, AN OVERFLOW CONDITION IS
NOT BEING PROCESSED; HOWEVER, THE LOGIC USED TO
OBTAIN THE AFFECTED CHAIN LINK AND DATA BLOCK IS
ESSENTIALLY THE SAME. ALSO, BECAUSE THIS IS NOT AN
OVERFLOW CONDITION, WHEN THE AFFECTED DATA BLOCK IS
RESIDENT IN THE DATA BLOCK BUFFER, THE NUMBER OF
BYTES AVAILABLE IN THAT BUFFER IS EQUAL TO 800 MINUS
THE CALCULATED DISPLACEMENT.)
VARIABLE-LENGTH ITEM: IF THE VARIABLE-LENGTH ITEM TO
BE WRITTEN IMMEDIATELY FOLLOWS THE ONE THAT WAS JUST
PROCESSED, WRBUF MOVES THE ITEM LENGTH FROM THE INPUT
BUFFER INTO THE DATA BLOCK BUFFER IMMEDIATELY AFTER
THE END OF THE PREVIOUS ITEM. IT THEN MOVES THE ITEM
TO BE WRITTEN FROM THE INPUT BUFFER INTO THE DATA
BLOCK BUFFER IMMEDIATELY AFTER THE LENGTH. THIS IS
DONE IN THE USUAL MANNER. (IF OVERFLOW OCCURS, IT IS
HANDLED IN THE USUAL MANNER.) IF THE ITEM TO BE
WRITTEN DOES NOT IMMEDIATELY FOLLOW THE ONE THAT WAS
JUST PROCESSED, WRBUF PROCEEDS IN THE SAME MANNER AS
DESCRIBED UNDER THE VARIABLE-LENGTH ITEM PORTION OF
"FILE DOES NOT EXIST".
NOTES:
1. WRBUF CAN ONLY WRITE A CERTAIN NUMBER OF LOGICAL
RECORDS OR ITEMS, REGARDLESS OF HOW MUCH DISK
SPACE MAY BE AVAILABLE, BECAUSE THE "NUMBER OF
ITEMS" IS KEPT IN A HALFWORD IN THE 40-BYTE FST
ENTRY FOR THAT FILE, AND IS LIMITED BY THE SIZE OF
A NUMBER WHICH WILL FIT IN A (16-BIT) HALFWORD.
TO AVOID RUNNING INTO THIS LIMITATION BEFORE IT IS
TOO LATE TO CLOSE THE FILE SUCCESSFULLY, WRBUF
CHECKS THAT THE ITEM-NUMBER (WHEN A WRBUF CALL HAS
BEEN COMPLETED) WILL NOT EXCEED A GIVEN LIMIT. IF
IT DOES, AN ERROR CODE 6 IS RETURNED, AND NO MORE
DATA IS WRITTEN. THE FILE MAY, HOWEVER, AT THIS
POINT BE SUCCESSFULLY CLOSED (VIA FINIS), AND CAN
LATER BE READ BY RDBUF. AT PRESENT THIS LIMITING
NUMBER OF RECORDS HAPPENS TO BE 65533. (65533
WOULD HAVE BEEN THE ABSOLUTE LIMITING FACTOR.)
2. IN CALLS TO QQTRK FOR OBTAINING THE FIRST CHAIN
LINK FOR A NEW FILE, AND TO TRKLKP FOR OBTAINING
EITHER A NEW NTH CHAIN LINK OR A DATA BLOCK, ERROR
CODES ARE CHECKED FROM THESE FUNCTION PROGRAMS FOR
THE FULL DISK CONDITION. IF ANY OF THESE
SITUATIONS OCCUR, WRBUF CAREFULLY SETS OR RESETS
ANY FLAGS OR CONDITIONS AS NEEDED, AND PRESENTS
THE USER WITH THE NON-FATAL ERROR-CODE 13.
THE FILE WHICH WAS BEING WRBUF'ED (UNLESS
NULL) IS THEN AVAILABLE AND COMPLETE INSOFAR AS
THE DATA BEING WRITTEN COULD FIT IN THE SPACE
AVAILABLE. THE DIRECTORY IS NOT UPDATED UNLESS A
KX IS IN EFFECT, THUS ALLOWING ANY DESIRED ERROR
RECOVERY PROCEDURES TO BE INSTITUTED.
3. BECAUSE OF THE DESIGN OF THE FIRST CHAIN LINK IN
THE CMS FILE SYSTEM, THERE IS A LIMITATION OF
16060 800-BYTE DATA BLOCKS FOR ANY GIVEN FILE. IF
A FILE BEING WRBUF'ED REACHES THIS LIMIT, AN ERROR
19 IS RETURNED, AND NO MORE DATA IS WRITTEN. THE
FILE MAY BE CLOSED, AND CAN THEN BE SUCCESSFULLY
READ (OR ERASED), BUT IT CANNOT BE MADE ANY
LARGER. (A FILE OF THIS SIZE WOULD FILL MORE THAN
HALF OF A FULL-SIZE 2314 DISK).
4. THERE IS ALSO A LIMIT OF 3400 FILES THAT CAN BE
REPRESENTED FOR ANY GIVEN DISK, AS LIMITED BY THE
LAYOUT OF THE MFD BLOCK. IF A DISK ALREADY HAS
REACHED THIS MAXIMUM AND AN ATTEMPT TO WRBUF A NEW
FILE IS MADE, WRBUF RETURNS AN ERROR CODE 10, AND
THE NEW FILE IS NOT OPENED.
Calls to Other Routines
ACTFREE, ACTFRET, ACTLKP, ADTLKP, DISKDIE, FREE, FRET,
FSTLKW, KILLEXF, QQTRK, QQTRKX, RDTK, TRKLKP,
TRKLKPX, WRTK