ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/walnut-creek-CDROM/CPM/ZCPR33/S-Z/SLB36HLP.LBR/SYSLIB0.HZP/SYSLIB0.HLP

Text File | 2000-06-30 | 14KB | 356 lines

Introduction to SYSLIB 3
Comments on Software Engineering
Definitions of Terms
Parameter-Passing Conventions
Overview of SYSLIB 3 Routines
:Introduction to SYSLIB 3

     SYSLI┬ │ i≤ aε integrateΣ too∞ se⌠ whicΦ i≤ designeΣ t∩ ì
assis⌠á thσá assembl∙á languagσ programme≥á iεá writinτá hi≤ ì
application«á  I⌠ i≤ intendeΣ t∩ placσ hiφ a⌠ ß highe≥ leve∞ ì
oµ abstractioε tha⌠ allow≤ hiφ t∩ concentratσ oε thσ probleφ ì
a⌠ hanΣ withou⌠ havinτ t∩ concerε himselµ witΦ thσ low-leve∞ ì
implementatioεá detail≤ oµ thσ operatinτá systeφá interface¼ ì
input/output¼áá tex⌠á parsinτá anΣá evaluation¼áá math¼á anΣ ì
sorting.

     T∩ illustratσ thi≤ point¼ conside≥ aε assembl∙ languagσ ì
programme≥á wh∩á need≤á t∩ acces≤á ßá disδá directory«á  Thσ ì
applicatioεá hσá i≤ writinτ i≤ onσ whicΦ display≤á ßá sorteΣ ì
disδ director∙ t∩ thσ user.

     Withou⌠ SYSLI┬ │ o≥ ß librar∙ likσ it¼á thσá programme≥ ì
woulΣá havσ t∩ writσ ß relativel∙ sophisticateΣ bod∙ t∩ codσ ì
t∩ acces≤ thσ directory¼á loaΣ i⌠ int∩ memory¼á sor⌠ it¼ anΣ ì
displa∙ i⌠ t∩ thσ user.


     WitΦ SYSLI┬ 3¼á however¼á thσ programme≥ ha≤ ß hos⌠á oµ ì
tool≤á hσá caε cal∞ oε t∩ perforφ somσ oµ thσá morσá tediou≤ ì
functions«á  Onσ oµ thesσ tools¼ DIRF¼ load≤ thσ element≤ oµ ì
ßá disδá director∙á whicΦ matcΦ ß filσ speπá int∩á ßá memor∙ ì
buffe≥ fo≥ him.

     Bu⌠á morσ thaε jus⌠ providinτ ß se⌠ oµ tools¼á SYSLI┬ │ ì
wa≤áá designeΣá witΦá structureΣá programminτá anΣá softwarσ ì
engineerinτ iε mind«á  Thσ basiπ goa∞ iε softwarσ desigεá i≤ ì
tha⌠ thσ program≤ mee⌠ thσ stateΣ requirements«  Iε applyinτ ì
softwarσá engineering¼á wσ wan⌠ morσ thaε jus⌠ this«á  Amonτ ì
other things, we want the program to be:

          o Modifiable             o Efficient
          o Reliable               o Understandable

     SYSLI┬á │ offer≤ ß significan⌠ se⌠ oµ facilitie≤á whicΦ ì
caε hel≡ t∩ achievσ thesσ goals.

:Comments on Software Engineering

     Wσ arσ experiencinτ ß SOFTWAR┼ CRISI╙ today¼á thσ basi≤ ì
oµá whicΦá i≤á simpl∙á tha⌠ i⌠ i≤ morσá difficul⌠á t∩á builΣ ì
reliablσ softwarσ system≤ tha⌠ wσ thinδ i⌠ shoulΣá be«á  Al∞ ì
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


     Thσá bottoφ linσ iε thσ desigε oµ ß softwarσ systeφá i≤ ì
tha⌠á thσ softwarσ shoulΣ mee⌠ it≤ stateΣ requirements«á  T∩ ì
achievσá thi≤á end¼á thσ fielΣ oµ SOFTWAR┼á ENGINEERIN╟á ha≤ ì
arisen.  The goals of SOFTWARE ENGINEERING are:

     1«á Modifiabilit∙ - Softwarσ shoulΣ bσ eas∙ t∩á change¼ ì
anΣ softwarσ shoulΣ bσ designeΣ witΦ late≥ changσ iε mind.

     2«á  Efficienc∙á - Thσ softwarσ systeφ shoulΣá usσá it≤ ì
availablσ resource≤ iε aε optima∞ manner.

     3«  Reliabilit∙ - Thσ softwarσ shoulΣ perforφ accordinτ ì
t∩ specificatioε anΣ recove≥ safel∙ froφ failurσ durinτ use.

     4«  Understandabilit∙ - Softwarσ shoulΣ bσ eas∙ t∩ reaΣ ì
anΣ follow«  Understandabilit∙ i≤ thσ too∞ useΣ t∩ pas≤ froφ ì
ß particula≥ probleφ spacσ t∩ ß solution.


     SYSLI┬á │á attempt≤ t∩ hel≡ thσ programme≥ achievσá thσ ì
goal≤ oµ Softwarσ Engineerinτ b∙ applyinτ thσ principle≤á oµ ì
Softwarσ Engineering«  Thesσ principle≤ are:

     1«á  Abstractioεá anΣ Informatioε Hidinτá - Unnecessar∙ ì
detai∞á i≤á hiddeε froφ thσ user«á  Fo≥á example¼á thσá DIR╞ ì
routinσ load≤ thσ content≤ oµ ß disδ director∙ int∩ ß memor∙ ì
buffer«  Ho≈ thi≤ loaΣ i≤ donσ i≤ hiddeε froφ thσ programme≥ ì
-- al∞ hσ need≤ t∩ kno≈ i≤ tha⌠ thσ loaΣ wa≤ donσ anΣ hσ no≈ ì
ha≤ ß vecto≥ oµ director∙ entrie≤ t∩ worδ with.

     2«á  Modularit∙á - SYSLI┬ │ i≤ ver∙ modula≥ iεá design«  ì
EacΦá routinσá iεá thσá librar∙ perform≤ onσá anΣá onl∙á onσ ì
function¼á anΣ thσ documentatioε provide≤ completσ detai∞ a≤ ì
t∩á wha⌠ tha⌠ functioε is¼á wha⌠ it≤ inpu⌠á parameter≤á are¼ ì
wha⌠á it≤ outpu⌠ parameter≤ are¼á wha⌠ it≤ sidσ effect≤ are¼ ì
anΣ othe≥ data.


     3«á  Localizatioε anΣ Loosσ Couplinτ - SYSLI┬ │ module≤ ì
arσáá loosel∙áá coupleΣá -- eacΦá modulσá ma∙áá bσáá treateΣ ì
independentl∙ oµ thσ others«á  Additionally¼ thσ module≤ arσ ì
strongl∙á cohesivσá -- thσá component≤ oµá eacΦá modulσá arσ ì
intimatel∙á relateΣ t∩ eacΦ othe≥ bu⌠ no⌠ t∩á component≤á oµ ì
othe≥ modules.

     4«á  Uniformit∙á - Thσ callinτ convention≤ betweeεá thσ ì
variou≤ SYSLI┬ │ module≤ arσ consisten⌠ witΦ eacΦ other¼ anΣ ì
i⌠á i≤á frequentl∙ thσ casσ tha⌠ thσ outpu⌠ parameter≤á froφ ì
onσá modulσá ma∙á bσ directl∙ useΣ a≤á inpu⌠á parameter≤á t∩ ì
another.

     5«á  Completenes≤á - EacΦá modulσ o≥ grou≡á oµá relateΣ ì
module≤ arσ functionall∙ complete«á  N∩ additiona∞ function≤ ì
are required.

     6«á  Confirmabilit∙ - ┴ prograφ writteε usinτ SYSLI┬á │ ì
modules can be readily decomposed for incremental testing.
:Definitions of Terms

     Somσá term≤á arσá useΣá frequentl∙á iεá thσá SYSLI┬áá │ ì
documentation«  Thesσ term≤ arσ defineΣ below.

     1«á  Buffe≥á - ┴ contiguou≤ vecto≥ oµ byte≤ iεá memory«  ì
Thσá buffe≥á i≤ knowε b∙ it≤ startinτ addres≤ anΣá sizσá (iε ì
bytes)«  Example:

          buffer║   D╙   4░   ╗ 40-bytσ buffer

     2«á  Characte≥á - ┴á one-bytσ (8-bit⌐ value«á  ┴á valuσ ì
rangσá withiεá thσ ASCI╔ characte≥ se⌠ (ßá 7-bi⌠á value⌐á i≤ ì
implieΣ bu⌠ no⌠ required¼á s∩ ß characte≥ coulΣ havσ ß valuσ ì
oµ 81H.


     3«á  Director∙ - Aε inde° t∩ thσ file≤ oε thσ disk«  Aε ì
entr∙á iε ß director∙ contain≤ thσ namσ oµ ß file¼á thσ use≥ ì
numbe≥ i⌠ reside≤ in¼á ho≈ largσ thσ filσ is¼á anΣ wherσ thσ ì
filσ i≤ locateΣ oε thσ disk«á  Thσ informatioε loadeΣ b∙ thσ ì
SYSLI┬á director∙á routine≤ doe≤ no⌠ includσá filσá locatioε ì
information¼á bu⌠ doe≤ includσ everythinτ else«á  Iε anothe≥ ì
sense¼á thσ terφ director∙ i≤ useΣ t∩ refe≥ t∩ ßá particula≥ ì
disδ anΣ use≥ areß (sucΦ a≤ A┤ o≥ B31).

     4«á  FC┬ (Filσ Contro∞ Block⌐ - ┴ 36-bytσ buffe≥á whicΦ ì
correspond≤á t∩á thσ ful∞ definitioε oµ ß CP/═ Filσá Contro∞ ì
Block«á  SYSLI┬ │ FCB'≤ arσ ALWAY╙ 3╢ byte≤ long«á  Iεá man∙ ì
cases¼ wheε ß routinσ require≤ ß user-supplieΣ FCB¼ thσ use≥ ì
neeΣ onl∙ fil∞ iε thσ filσ namσ anΣ typσ field≤ (byte≤ 1-11⌐ ì
anΣá neeΣá no⌠ concerε himselµ witΦ thσ res⌠ oµ thσá fields«  ì
Thσ INITFC┬ routinσ store≤ zer∩ iε al∞ byte≤ excep⌠ byte≤ 1-ì
1▒ oµ thσ FCB.


     5«á  Filσ - An∙ CP/═ file¼á whicΦ ma∙ bσ eithe≥ tex⌠ o≥ ì
binary«á  SYSLI┬á │ make≤ n∩ distinctioε betweeεá thesσá tw∩ ì
type≤ oµ files.

     6«áá  Strinτáá - An∙áá sequencσá oµá ASCI╔áá character≤ ì
terminateΣ b∙ ß <NULL╛ character¼á whicΦ i≤ ß bytσ oµá valuσ ì
0«  Example≤ oµ string≤ are:

          DB   'This is a string',0
          DB   1,2,3,'This is also',0


:Parameter-Passing Conventions

     SYSLI┬á │ i≤ ver∙ consisten⌠ iεá it≤á parameter-passinτ ì
conventions«á  Iεá al∞ cases¼á parameter≤ arσ passeΣ t∩á anΣ ì
froφ thσ SYSLI┬ │ routine≤ iε registers«  Iµ morσ value≤ arσ ì
requireΣá thaε therσ arσ availablσ registers¼á thσá registe≥ ì
value≤á arσá pointer≤ t∩ specificatioε block≤ whicΦá contaiε ì
thσá desireΣá parameter≤á (seσ thσ FXn$xxxx°á anΣá thσá SOR╘ ì
routines).

     Iεá mos⌠á cases¼á thσá followinτ genera∞á rule≤á apply«  ì
Therσá wil∞á alway≤á bσ exception≤á t∩á thσá rule¼á bu⌠á thσ ì
followinτ statement≤ arσ true¼ by-and-large.


Uses of the HL Register Pair --

     1«á  H╠á i≤ useΣ a≤ ß buffe≥ pointer╗á fo≥ example¼á H╠ ì
contain≤ thσ addres≤ oµ thσ buffe≥ useΣ b∙ DIRF

     2«á  H╠ i≤ useΣ a≤ ß strinτ pointer╗á fo≥á example¼á H╠ ì
contain≤á thσ addres≤ oµ thσ firs⌠ bytσ oµ ß strinτ fo≥á thσ ì
EVA╠ routine

     3«á  H╠á i≤ useΣ t∩ contaiε thσ firs⌠ operanΣ fo≥á matΦ ì
routines╗ fo≥ example¼ DIVH─ divide≤ H╠ b∙ DE


Uses of the DE Register Pair --

     1«á  D┼á i≤ useΣ t∩ poin⌠ t∩ aε FCB╗á fo≥á example¼á D┼ ì
contain≤ thσ addres≤ oµ thσ FC┬ useΣ b∙ DIRF

     2«á  D┼á i≤ useΣ t∩ contaiε thσ seconΣ operanΣ fo≥ matΦ ì
routines╗ fo≥ example¼ SUBH─ subtract≤ D┼ froφ HL

     3«á  D┼á i≤ useΣ t∩ poin⌠ t∩ specia∞á block≤á (buffers⌐ ì
useΣá b∙ SYSLI┬ │ routines╗á fo≥ example¼á D┼ point≤ t∩á thσ ì
Sor⌠ Specificatioε Blocδ fo≥ thσ SOR╘ routine


Uses of the BC Register Pair --

     1«  B├ i≤ useΣ t∩ contaiε ß D╒ form¼ wherσ ┬ contain≤ ß ì
disδ numbe≥ (A=0⌐ anΣ ├ contain≤ ß use≥ number



Uses of the A Register --

     1«á  ┴ i≤ useΣ t∩ contaiε aε inpu⌠ flag╗ fo≥ example¼ ┴ ì
contain≤ thσ selectioε flaτ useΣ b∙ DIRF

     2«á  ┴ i≤ useΣ t∩ contaiε aε erro≥ returε code╗á iµ thσ ì
valuσ oµ thi≤ codσ i≤ 0¼á thσ Zer∩ Flaτ (Z⌐ i≤ als∩ set¼ anΣ ì
vice-versa╗á fo≥á example¼á ┴ contain≤ ß TP┴ overflo≈á erro≥ ì
flaτ returneΣ b∙ thσ DIR╞ routine

     3«á  ┴á i≤ useΣ t∩ contaiε ß characte≥ inpu⌠ o≥á outpu⌠ ì
froφá ßá SYSLI┬á │á routine╗á fo≥á example¼á CI╬á return≤á ß ì
character in A and COUT outputs a character in A

:Overview of SYSLIB 3 Routines

     SYSLI┬á │á contain≤á many¼á man∙á routines¼á anΣá thesσ ì
routine≤ arσ groupeΣ int∩ thσ followinτ functiona∞ areas:

     1«  Director∙ Manipulatioε Routines
          Thesσá routine≤ dea∞ witΦ director∙á access«á  Thσ ì
entrie≤á oµá ß disδ director∙ caε bσ loadeΣá int∩á ßá memor∙ ì
buffer¼á selecteΣ agains⌠ aε FCB¼ sorted¼ anΣ manipulateΣ b∙ ì
thesσ routines.

     2«  Numeriπ Strinτ Evaluatioε Routines
          Thesσá routine≤ conver⌠ characte≥ string≤ int∩ 16-ì
bi⌠ binar∙ values«  String≤ likσ thosσ belo≈ arσ processed:

               DB   '123',0   ; value is 123 decimal
               DB   '5AH',0   ; value is 5A hexadecimal
               DB   '110B',0  ; value is 110 binary
               DB   '77Q',0   ; value is 77 octal


     3«  Byte-OrienteΣ Filσ Input/Outpu⌠ Routines
          Thesσá routine≤á suppor⌠ inpu⌠ anΣ outpu⌠á t∩á anΣ ì
froφ file≤ oε thσ basi≤ oµ ß bytσ a⌠ ßá time«á  FX$GET¼á fo≥ ì
example¼ return≤ thσ nex⌠ bytσ froφ thσ curren⌠ filσ iε A.

     4«  CP/═ Filσ Input/Outpu⌠ Routines
          Thesσá routine≤á suppor⌠ inpu⌠ anΣ outpu⌠á t∩á anΣ ì
froφá file≤á oεá thσ basi≤ oµ ß 128-bytσ blocδá a⌠á ßá time«  ì
Facilitie≤á arσ als∩ provideΣ fo≥ deletinτá files¼á renaminτ ì
files¼ anΣ computinτ filσ sizes.

     5«  User/Disδ Manipulatioε Routines
          Thesσá routine≤ allo≈ thσ prograφ t∩ finΣ ou⌠ wha⌠ ì
disδ anΣ use≥ areß i⌠ i≤ iε anΣ t∩ movσ betweeε directories.


     6«  Filσ Namσ Strinτ Parser
          Thi≤á routinσ i≤ useΣ t∩ conver⌠ ß filσ namσá tex⌠ ì
strinτá int∩á aε acceptablσ forφ anΣ placσ i⌠ int∩á aεá FCB«  ì
Fo≥ example¼ thσ followinτ conversioε caε bσ done:

               DB   'MYFILE.TXT',0      ; string

               DB   0                   ; ... converted to
               DB   'MYFILE  '
               DB   'TXT'
               DS   24

     7«  Inpu⌠ Linσ Editors
          Thesσ routine≤ accep⌠ use≥ inpu⌠ witΦ editinτá anΣ ì
returεá ßá pointe≥á t∩ thσ firs⌠ bytσ oµ thσ use≥á inpu⌠á iε ì
strinτ forφ (terminateΣ b∙ ß binar∙ 0).


     8«  Strinτ Outpu⌠ Routines
          Thesσá routine≤ senΣ string≤ t∩á variou≤á devices«  ì
Routine≤á arσ provideΣ t∩ senΣ string≤ oµ character≤ t∩á thσ ì
consolσáá o≥á printe≥á witΦá o≥á withou⌠áá control-characte≥ ì
processing.

     9«  Numeriπ Outpu⌠ Routines
          Thesσá routine≤ conver⌠ binar∙ value≤ t∩ characte≥ ì
sequence≤ anΣ outpu⌠ theφ t∩ variou≤ devices«  Outpu⌠ t∩ thσ ì
consolσ anΣ printe≥ i≤ provided¼ anΣ thσ outpu⌠ i≤ eithe≥ iε ì
thσ forφ oµ decima∞ o≥ hexadecima∞ numbers.

     10«  Strinτ anΣ Valuσ Comparisoε Routines
          Thesσááá routine≤áá providσáá variou≤áá comparisoε ì
function≤ fo≥ botΦ string≤ anΣ numbers«á  Onσ strinτ ma∙á bσ ì
compareΣá agains⌠á anothe≥ strinτ o≥ ß substrinτ oµá anothe≥ ì
string.  Two 16-bit numbers can be compared.


     11«  Character-OrienteΣ Input/Outpu⌠ Routines
          Thesσá routine≤ providσ inpu⌠ anΣ outpu⌠á service≤ ì
oε ß character-for-characte≥ basi≤ t∩ ß variet∙ oµá devices«  ì
Outpu⌠á t∩ thσ consolσ anΣ thσ printe≥ i≤á provided«á  Also¼ ì
devicσá status¼á sucΦ a≤ consolσ inpu⌠ status¼á routine≤ arσ ì
available.

     12«  MatΦ Routines
          Thesσá routine≤ perforφ mathematica∞á calculation≤ ì
oεá 16-bi⌠ quantities«á  Add¼á subtract¼á multiply¼á divide¼ ì
rotate¼á shift¼ logica∞ AND¼ logica∞ OR¼ anΣ logica∞ XO╥ arσ ì
somσ oµ thσ function≤ provided.

     13«  CR├ Routines
          Thesσáá routine≤á suppor⌠á computatioεá oµá Cycliπ ì
Redundanc∙á Checδá value≤ fo≥ bytσá streams«á  ┴á numbe≥á oµ ì
differen⌠áá CR├á calculatioεá routine≤á arσá availablσáá fo≥ ì
differen⌠ CR├ polynomials.


     14«  Randoφ Numbe≥ Generato≥ Routines
          Thesσá routine≤á providσá ßá pseudo-randoφá numbe≥ ì
generator«á  Thσ seeΣ valuσ fo≥ thi≤ generato≥ ma∙ bσ feΣ t∩ ì
it¼á thereb∙á generatinτá thσ samσ sequencσ fo≥á eacΦá giveε ì
seed¼á o≥á i⌠á ma∙ bσ computeΣá somewha⌠á randomly«á  Randoφ ì
number≤ arσ 8-bi⌠ quantities.

     15«  Sor⌠ Routines
          Thesσ routine≤ providσ ß fast¼ general-purposσ in-ì
memor∙á sor⌠á capability«áá  Thσá sor⌠á algorithφá i≤áá ver∙ ì
efficien⌠á (ßá shel∞ sort)¼á anΣ ma∙ bσ performeΣá b∙á usinτ ì
elemen⌠á pointer≤á o≥á no⌠ usinτ pointer≤ (usσá oµá pointer≤ ì
cost≤ morσ memor∙ bu⌠ speed≤ u≡ thσ sor⌠ eveε further).


     16«  Capitalizatioε anΣ Characte≥ Test/Ski≡ Routines
          Thesσá routine≤ arσ usefu∞ fo≥á tex⌠á parsing«á  ┴ ì
variet∙ oµ evaluatioε routine≤ arσ provideΣ t∩ determinσ thσ ì
typσá oµá characte≥á beinτ deal⌠ witΦ (sucΦá a≤á alphabetic¼ ì
numeric¼ hexadecimal¼ space¼ punctuation¼ etc)«  BotΦ strinτ ì
anΣá individua∞á characte≥ capitalizatioεá capabilitie≤á arσ ì
provided also.

     17«  Memor∙ Allocatioε Routines
          Thesσ routine≤ providσ ß dynamiπ memor∙ allocatioε ì
mechanisφá tha⌠ constantl∙ check≤ fo≥ TP┴á overflow«á  Afte≥ ì
defininτ thσ bound≤ oµ ß memor∙ buffer¼á request≤ fo≥á spacσ ì
from this area may be issued on a byte-for-byte basis.