CP/M/CPM_CDROM.iso/cpm/utils/dskutl/ds21doc.lbr/DSTECH.WZ/DSTECH.WS

Text File | 1987-02-14 | 12.8 KB | 313 lines

.he                  TECHNICAL NOTES FOR DAMNSPOT
                  TECHNICAL NOTES FOR DAMNSPOT
                          Version 2.1

GENERAL

Thesσá note≤ arσ fo≥ thσ programme≥ anΣ fo≥ myselµ t∩ reminΣá mσ ì
oµ thing≤ t∩ d∩ anΣ wh∙ ╔ diΣ thσ thing≤ ╔ did«á  Somσ ma∙ bσ oµ ì
passinτá interes⌠á t∩ others«á  I⌠ i≤ ofteε difficul⌠ t∩á decidσ ì
wha⌠ is¼á o≥ i≤ not¼á to∩ technica∞ fo≥ thσ genera∞ user« ShoulΣ ì
thing≤ no⌠ appea≥ t∩ bσ workinτ a≤ advertised¼á yo⌡ migh⌠ browsσ ì
througΦ thi≤ lookinτ fo≥ ß clue.


SOURCE FILES

Thσ DAMNSPO╘ sourcσ files¼ arσ DS.PAS¼ DS*.PA╙ anΣ DAMNSPOT.HLP«  ì
Thσ orde≥ oµ inclusioε i≤ relativel∙ inflexiblσ unles≤ yo⌡á likσ ì
writinτá ForwarΣ statements«á Sourcσ i≤ availablσ t∩ anyonσá wh∩ ì
want≤ i⌠ anΣ wil∞ no⌠ cavi∞ to∩ mucΦ a⌠ imperfections.


COMPILATION CONSIDERATIONS

Sincσ Turb∩ allocate≤ variablσ storage¼ no⌠ jus⌠ stacδ space¼ iε ì
higΦá memory¼á onσá ha≤ t∩ se⌠ aε uppe≥ memor∙ limi⌠ a⌠á compilσ ì
time«á  ╔ intenΣ t∩ distributσ D╙ witΦ thi≤ se⌠ t∩á D000«á  Tha⌠ ì
ma∙ founde≥ oε smalle≥ machines¼á large≥ disk≤ o≥ jus⌠ oε peoplσ ì
wh∩á likσá t∩ ruε witΦ lot≤ oµ stuff¼á likσ Smartkey¼á  iεá higΦ ì
memory«

Also¼ Turb∩ need≤ ß bi⌠ oµ rooφ durinτ compilatioε itself«  Iµ ╔ ì
loaΣá u≡ memor∙ witΦ Snapshot¼á Smartke∙ anΣ ZCPR▓ thσá compile≥ ì
bomb≤á ou⌠ oε ß Compile≥ Overflo≈ erro≥ shortl∙ afte≥ DSSPE├á i≤ ì
included«á Thσá probleφ goe≤ awa∙ iµ ╔ jus⌠ usσ Turb∩ iε ßá barσ ì
ZCPR▓ environmen⌠ anΣ omi⌠ erro≥ messagσ loading«á  Somewherσ iε ì
betweeε thosσ extreme≤ i≤ thσ critica∞ point.

To compile:

     turbo          Run Turbo
     nááááááááááááááNo error messages
     m dsáááááááááááMain program DS.PAS
áááááoááááááááááááááOptions menu
ááááácááááááááááááááCOM file output
áááááed000ááááááááááEnd address D000  (or as big as Turbo allows)
áááááqááááááááááááááQuit Options menu
ááááácááááááááááááááCompile
.pa
èHELP FILE

The help file DAMNSPOT.HLP has the format:

     %TITLE 1                 Note:  The title may contain blanks but it,
áááááText                            and the % and & signs must be left
ááááá...                             justified.
áááááText
ááááá&

ááááá%TITL┼ 2
áááááText
ááááá...
áááááText
ááááá&

áááááetc.

Thσá tex⌠á ma∙ includσ thσ specia∞ symbol≤ #╟ ╜ Bell¼á anΣ #─á ╜ ì
Drivσá unde≥á test«áá  Thσá blanδá line≤á betweeεá entrie≤áá arσ ì
irrelevant╗ the∙ arσ merel∙ therσ t∩ improvσ legibility«  ┴ hel≡ ì
entr∙ i≤ invokeΣ witΦ thσ syntax:

                help('WHATEVER TITLE YOU WANT');

Thσá HEL╨á procedurσ firs⌠ attempt≤ t∩ finΣ thσ hel≡á file¼á anΣ ì
theε scan≤ i⌠ lookinτ fo≥ ß linσ beginning:

                    %WHATEVER TITLE YOU WANT

Iµá found¼á successivσ line≤ arσ printeΣ t∩ thσ screeεá unti∞á ß ì
linσá beginninτ witΦ aε ampersanΣ i≤ found«á  Hel≡ message≤á arσ ì
printeΣ as:

----------------------------------------------------------------

     Text
     ...
     Text

----------------------------------------------------------------

Thσá firs⌠ timσ tha⌠ hel≡ i≤ invoked¼á thσ hel≡ filσ i≤ searcheΣ ì
fo≥á beginninτá a⌠á thσá origina∞á defaul⌠á drive«áá  Oεáá late≥ ì
invocation≤á thσá searcΦ begin≤ a⌠ thσ drivσ oε whicΦá thσá hel≡ ì
filσá wa≤ las⌠ found¼á iµ applicable«á  Iµ thσ hel≡ filσ i≤á no⌠ ì
founΣá oε thσ firs⌠ drivσ tried¼á an∙ othe≥ availablσ drive≤ arσ ì
searcheΣ iε thσ orde≥ ┴ ┬ ├ ..« skippinτ thσ onσ alread∙ tested.


GLOBAL SPECIFICATIONS

Thesσ arσ containeΣ iε DSSPEC.PAS«á  Onl∙ ß fe≈ specia∞á purposσ ì
type≤ arσ defineΣ elsewherσ - mostl∙ string≤ oµ variou≤ lengths.
.pa
èDEBUGGING

Thσáá constan⌠áá DEBU╟áá anΣá tw∩áá sets¼áá FAKE_BAD_BLOC╦áá anΣ ì
FAKE_BAD_SECTOR¼á arσ defineΣ iε DSSPEC«  Iµ DEBU╟ i≤ TRUE¼ theε ì
D╙á wil∞ fakσ baΣ block≤ anΣ baΣ sector≤ wheε thσá B║á drivσá i≤ ì
unde≥á test«á  Readinτ anΣ writinτ i≤ no⌠ inhibited╗á D╙á merel∙ ì
cause≤á thσá I/╧á routinσ t∩ signa∞ aε erro≥ eveε wheεá thσá I/╧ ì
succeeds.

TYPE AND RANGE CHECKING

Rangσ checkinτ canno⌠ bσ used«  Thσ ke∙ array≤ arσ declareΣ witΦ ì
inde°á range≤ oµ thσ forφ [0..0▌ becausσ thei≥ truσ sizσ i≤á no⌠ ì
known«á  ╔ supposσ ╔ coulΣ se⌠ thσ uppe≥ limit≤ t∩ largσ number≤ ì
bu⌠á tha⌠á woulΣ als∩ bσ arbitrary«á  I⌠ migh⌠á bσá possiblσá t∩ ì
litte≥á thσ prograφ witΦ {$R-² anΣ {$R+² directive≤ bu⌠ t∩á hecδ ì
witΦ it.

Perhap≤ a≤ ß result¼á ╔ havσ beeε rathe≥ slopp∙ oε types«á ┴ lo⌠ ì
oµá thing≤á arσá Intege≥ wherσ perhap≤ 0..Maxin⌠ woulΣá bσá morσ ì
appropriate¼ anΣ s∩ on.


DYNAMIC MEMORY USAGE

Thσá procedure≤á useΣ arσ Mark¼á Getmeφ anΣá Release«á  Iεá thi≤ ì
versioε oµ DS¼ onl∙ livσ director∙ entrie≤ arσ storeΣ iε memory«  ì
Iεá Versioε 2.░ memor∙ haΣ t∩ accommodatσ thσ entirσá directory«  ì
Als∩ threσ byte≤ oµ memor∙ arσ needeΣ fo≥ eacΦ blocδ a≤ wel∞á a≤ ì
ßá block-sizeΣá buffer«á  Thi≤ ma∙ wel∞ precludσ checkinτá disk≤ ì
witΦ largσ number≤ oµ entries¼ block≤ anΣ blocδ sizes.

Memor∙á i≤ als∩ needeΣ t∩ storσ thσ initia∞á director∙á checksuφ ì
vecto≥á fo≥á thσ disδ unde≥ tes⌠ but¼á smal∞á mercy¼á thi≤á wil∞ ì
probabl∙ bσ zer∩ lengtΦ fo≥ ß harΣ disk.


ERROR HANDLING

Mos⌠á i≤ lef⌠ t∩ Turbo«á  Sometime≤ i⌠ i≤ turneΣ ofµá {$I-²á fo≥ ì
specifiπá operation≤á wherσ ß crasΦ i≤ definitel∙ no⌠ wanteΣá a≤ ì
thσá resul⌠á oµ ß typ∩ o≥ ß missinτá disδá file«á  Thσá functioε ì
IO_ERRO╥á display≤á thσ samσ erro≥ messagσ a≤ Turb∩ bu⌠á return≤ ì
thσ erro≥ codσ froφ IORESUL╘ rathe≥ thaε crashing.

DISK PARAMETERS

Thesσ arσ obtaineΣ froφ CP/═ iε thσ usua∞ manner« Iε Versioε 2.▒ ì
thσá parameter≤ arσ squirreleΣ awa∙ iε prograφ assigneΣá storagσ ì
becausσá i⌠á wa≤ founΣ tha⌠ thσ Kaypr∩á IV¼á anΣá perhap≤á othe≥ ì
machines¼á d∩á no⌠á alway≤ kee≡ theφ residen⌠ a⌠á thσá indicateΣ ì
addresses.
.pa
èABORTING POSSIBILITIES

Thσ Control-╙ » Control-├ checkinτ availablσ witΦ Turb∩ ha≤ beeε ì
turneΣá ofµ witΦ thσ directivσ {$C-}«á  Simila≥ actioε ha≤á beeε ì
fakeΣá witΦ thσ routine≤ KEYBOAR─ anΣ PERMIT_ABORT«á  Thσ latte≥ ì
shoulΣ bσ invokeΣ iε an∙ timσ consuminτ loo≡ o≥ iε an∙ loo≡ tha⌠ ì
send≤ ß lo⌠ oµ line≤ t∩ thσ terminal.

Mos⌠á livσá ke∙ input¼á whicΦ i≤ almos⌠ al∞ inpu⌠á iεá DS¼á goe≤ ì
througΦ KEYBOARD«á  Iµ ß Control-├ i≤ typed¼á thσ use≥ i≤á askeΣ ì
fo≥á confirmatioεá oµ thσ abor⌠ anΣ warneΣ iµ therσ arσá change≤ ì
pending«á  Iµ ß Control-╙ i≤ typed¼ norma∞ star⌠ anΣ sto≡ scrol∞ ì
occurs«á  Thσá sto≡ scrol∞ depend≤ oε pollinτá b∙á PERMIT_ABORT«  ì
Thσ Control-├ abort≤ causσ ß Warφ Boot.


DISK HARDWARE ROUTINES

Thesσá werσ ß bi⌠ oµ fun¼á man∙ lesson≤ beinτ learneΣ (Hai≥á fo≥ ì
sale¼ ß penn∙ ß handful)«  Thσ ke∙ lesson≤ were:

1«  D∩ no⌠ usσ CP/═ functioε 3╖ (RESE╘ DRIVES)«  I⌠ log≤ ß drivσ ì
out¼á yes¼á bu⌠ theε onl∙ log≤ i⌠ iε agaiε iµ yo⌡ d∩ ß selec⌠ t∩ ì
thσ drivσ froφ ß differen⌠ drive«á  Iµ yo⌡ rese⌠ drivσ A¼ wheε ┴ ì
i≤ default¼ changσ thσ disk¼ anΣ reselec⌠ drivσ A¼ thσ disδ doe≤ ì
no⌠á ge⌠á loggeΣ iε s∩ write≤ won'⌠ work«á  Thσá onl∙á solution¼ ì
othe≥á thaεá doinτ ß genera∞ Disδ Systeφ Rese⌠ seem≤ t∩á bσá thσ ì
hoke∙á onσ oµ findinτ anothe≥ drivσ (iµ onσá exists)¼á selectinτ ì
it¼á anΣ theε selectinτ thσ onσ yo⌡ actuall∙ want«  Thσ lonτ anΣ ì
shor⌠á i≤á tha⌠ ╔ thre≈ ou⌠ Functioε 3╖ anΣ wen⌠ t∩á thσá simplσ ì
Rese⌠ Disδ Subsysteφ - CP/═ functioε 13.

2«á  BDO╙ doe≤ no⌠ expec⌠ anyonσ elsσ t∩ issuσ BIO╙ selec⌠ call≤ ì
(o≥á i≤á thσá faul⌠á Turbo'≤ ?)«á  A⌠á an∙á rate¼á thσá functioε ì
DISK_INFO_LO├ doe≤ ß BIO╙ disδ select«á  Iµ thi≤ i≤ ßá differen⌠ ì
disδá thaε thσ default¼á theε norma∞ Pasca∞ disδ I/╧ get≤ louseΣ ì
up«  Thσ solutioε i≤ thσ SYNC_DIS╦ procedurσ whicΦ simpl∙ issue≤ ì
ß BIO╙ disδ selec⌠ t∩ thσ defaul⌠ disk«á  SYNC_DIS╦ i≤á requireΣ ì
immediatel∙á afte≥ ever∙ invocatioε oµ DISK_INFO_LO├ excep⌠á fo≥ ì
iεá thσ RW_SECTO╥ function«á  There¼á thσ SYNC_DIS╦ i≤á reserveΣ ì
unti∞ thσ I/╧ i≤ complete.

HEX NUMBER OUTPUT

Thσá functioε BEX╫ i≤ jus⌠ HEX╫ witΦ leadinτ zero≤ suppresseΣ s∩ ì
tha⌠á thσá firs⌠á significan⌠á characte≥á i≤á thσá firs⌠á strinτ ì
character.
.pa
èCATEGORIZATION OF BLOCKS

┴á blocδá ma∙ havσ an∙ reasonablσ combinatioε oµá thσá followinτ ì
attributes:

1.   A parent file;
2.   Active  - in file other than [UNUSED].BAD or BLOCKS.BAD;
3.   Covered - in file [UNUSED].BAD or BLOCKS.BAD;
4.   Checked - have checked readability (may be cleared on retry);
5.   Bad     - unreadable (or assumed so);
6.   Wrong   - readable but containing the wrong information.


SCREEN OUTPUT ASSUMPTIONS

I⌠ ha≤ beeε assumeΣ tha⌠ thσ screeε wil∞ handlσ 8░ character≤ iε ì
width¼á anΣ tha⌠ i⌠ perform≤ ß physica∞ carriagσ returεá withou⌠ ì
linefeeΣá iε responsσ t∩ ß C╥ character«á  Iµ thesσá assumption≤ ì
arσ untruσ thσ display≤ ma∙ bσ rathe≥ messy.


MIXING PASCAL WITH BIOS DISK I/O

Somσ cautioε i≤ needeΣ herσ because:

1.á  Iµ yo⌡ writσ ß filσ t∩ thσ disk¼á updatinτ thσ director∙ iε ì
áááááthσá process¼á theεá D╙ wil∞ overwritσ tha⌠ director∙á wheε ì
ááááá(if⌐ thσ use≥ say≤ Update«á  Al∞ referencσ t∩ thσ filσá yo⌡ ì
áááááwrotσ wil∞ bσ cancelled.

2.á  Thσ filσ tha⌠ yo⌡ writσ ma∙ wel∞ usσ block≤ tha⌠ D╙ regard≤ ì
áááááa≤ it≤ own«  Fo≥ example¼ iµ yo⌡ succeeΣ iε retrievinτ datß ì
áááááfroφá ßá flak∙á blocδá usinτá thσá Retr∙á option¼á D╙á wil∞ ì
áááááimmediatel∙á squirre∞ i⌠ awa∙ iε ß gooΣ block«á  Iµ yo⌡ no≈ ì
áááááwritσá ß filσ t∩ thσ disδ beforσ D╙ update≤ thσá directory¼ ì
áááááthσá filσá ma∙á usσá tha⌠á blocδá clobberinτá thσá preciou≤ ì
áááááinformatioε tha⌠ D╙ pu⌠ there.

Aε examplσ oµ ho≈ t∩ handlσ thi≤ froφ withiε D╙ i≤ containeΣá iε ì
procedurσ DIRECTORY_OUTPUT_DISK«á  Thσ objec⌠ i≤ t∩ avoiΣ savinτ ì
director∙á informatioεá file≤ t∩ thσ disδ unde≥ tes⌠ a≤ lonτá a≤ ì
it≤á director∙ i≤ subjec⌠ t∩ change«á  Beforσ arrivinτá a⌠á thi≤ ì
point¼á thσá scaε i≤ completσ s∩ n∩ furthe≥ change≤ caε occu≥ t∩ ì
DS'≤ vie≈ oµ thσ disk.
.pa
èWriting the file is conditioned by:

1.áá Updated_Oδáá - truσáá iµá thσá disδá director∙áá ha≤áá beeε ì
ááááásuccessfull∙ updated.

2.á  Changσ - truσ iµ aε updatσ woulΣ producσ an∙ changσ iεá thσ ì
ááááádisk.

3.á  Trouble_Disk(Drive⌐ - truσ iµ Drivσ contain≤ thσ disδ unde≥ ì
ááááátes⌠ iε thσ samσ forφ tha⌠ i⌠ haΣ originally

Thσá firs⌠á tw∩ oµ thesσ arσ booleaε variable≤ tha⌠ thσá prograφ ì
mus⌠á maintain«á  Thσ thirΣ i≤ ß booleaε functioε tha⌠á compare≤ ì
thσá curren⌠á CP/═ checksuφ vecto≥ fo≥ thσá drivσá agains⌠á tha⌠ ì
saveΣá wheεá thσá disδ wa≤á firs⌠á specified«á  Incidentally¼á ß ì
referencσá t∩ trouble_disk(drive⌐ mus⌠ bσ precedeΣá b∙á invokinτ ì
log_in(drive⌐ iε orde≥ t∩ initializσ thσ CP/═ checksuφ vector.

Oεá firs⌠á sight¼á i⌠á seem≤ tha⌠ thi≤ samσ functioεá shoulΣá bσ ì
invokeΣ wheε thσ use≥ request≤ Movinτ thσ troublσ disδ t∩ ßá ne≈ ì
drivσá fo≥ anothe≥ Updatσ attempt«á  Unfortunately¼á onσ ha≤á t∩ ì
assumσá tha⌠á thσá director∙ i≤ corrup⌠ a⌠ thi≤á point¼á s∩á onσ ì
canno⌠á demanΣá equalit∙á witΦ thσ origina∞ a≤á prooµá tha⌠á thσ ì
troublσ disδ reall∙ i≤ oε thσ ne≈ drive.

Intrude≥á program≤ canno⌠ bσ preventeΣ froφ lousinτá thing≤á up«  ì
Fo≥á example¼á thσá prograφ Snapsho⌠ useΣ t∩ capturσ ßá termina∞ ì
session'≤ screeε outpu⌠ fo≥ documentatioε purposes¼á wa≤ invokeΣ ì
repeatedl∙á whilσ D╙ wa≤ running«á Sincσ Snapsho⌠á automaticall∙ ì
write≤ t∩ thσ defaul⌠ drivσ i⌠ wa≤ necessar∙ t∩ ensurσ tha⌠á thσ ì
initia∞ defaul⌠ drivσ wa≤ differen⌠ thaε thσ drivσ t∩ bσ tested.

Incidentally¼á thσ distinctioε betweeε defaul⌠ drivσ anΣ initia∞ ì
defaul⌠á drivσ i≤ ß quibble«á  D╙ change≤ thσ defaul⌠ drivσ onl∙ ì
momentaril∙ froφ timσ t∩ timσ a≤ par⌠ oµ thσ procedurσ t∩ loτ iε ì
directories«á  I⌠á i≤ alway≤ se⌠ bacδ immediately¼á s∩á yo⌡á caε ì
assumσ tha⌠ thσ defaul⌠ drivσ i≤ thσ original«á  An∙ Pasca∞ filσ ì
I/╧ shoulΣ specif∙ ß drivσ explicitly.


SECTORS

Thσ secto≥ number≤ reporteΣ arσ logical«á  Thσ actua∞ read/writσ ì
routine≤ conver⌠ theφ usinτ an∙ CP/═ translatioε vecto≥ bu⌠ thi≤ ì
i≤á transparen⌠ t∩ thσ user«á  Fo≥ somσ reason¼á m∙ cop∙ oµá DU▓ ì
number≤ logica∞ sector≤ beginninτ a⌠ ▒ rathe≥ thaε a⌠ 0«á  Hencσ ì
wha⌠ D╙ call≤ secto≥ 5¼á DU▓ wil∞ cal∞ secto≥ 6«  M∙ CP/═ manua∞ ì
make≤á thσá samσá erro≥á sayinτ that¼á oε ßá BIO╙á disδá select¼ ì
registe≥ B├ contain≤ thσ secto≥ numbe≥ froφ ▒ - 26«  No⌠ true.
.pa
èDIVISION OF THE DISK INTO AREAS

D╙á differentiate≤á thσá System¼á Director∙ anΣá Use≥á area≤á a≤ ì
follows:

Directoryéá  Thi≤á begin≤á a⌠ thσ firs⌠á non-reserveΣá tracδá anΣ ì
extend≤á fo≥á a≤á man∙ block≤ a≤ arσ needeΣ t∩ holΣá (DR═á ½á 1⌐ ì
entries«  Fo≥ ß basiπ 6┤ entr∙ director∙ thi≤ i≤ 1╢ records.

Systeméá  Thi≤á consist≤á oµ al∞ reserveΣ track≤á plu≤á an∙á pre-ì
allocateΣ block≤ indicateΣ b∙ AL░ anΣ AL▒ iε thσ disδá paramete≥ ì
blocδá minu≤ thσ Directory«á  ┴ harΣ disδ wil∞ usuall∙ bσá spli⌠ ì
int∩ tw∩ o≥ morσ logica∞ disks¼á thσ highe≥ disk≤ havinτ ß largσ ì
numbe≥ oµ reserveΣ tracks«á  Thi≤ isn'⌠ reall∙ 'systemº areß bu⌠ ì
D╙ think≤ i⌠ is.

Useré  Thi≤ consist≤ oµ whateve≥ i≤ left¼ followinτ thσ las⌠ pre-ì
allocateΣ blocδ anΣ extendinτ t∩ thσ highes⌠ use≥ block.