|
DataMuseum.dkPresents historical artifacts from the history of: RC4000/8000/9000 |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about RC4000/8000/9000 Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - download
Length: 22272 (0x5700) Types: TextFile Names: »alrc13«
└─⟦a41ae585a⟧ Bits:30001842 SW-save af projekt 1000, Alarm-system └─⟦72244f0ef⟧ └─⟦this⟧ »alrc13«
>fo Standard for indhold af vedligeholdelsesmanualer >a1 INTRODUKTION Samtidig med et stadigt stigende behov for do_kumen_tation er det ønskeligt, at denne do_kumen_tation har en ensartet ud_formning, og at indholdet er ensartet opbygget og struk_tureret. Den layout_mæssige udformning af (klasse 2) manualer er beskrevet i ref. 2. Denne manual tager derimod sigte på at løse pro_blem_er_ne omkring indhold og struk_turering af vedlige_holdelses_manualer. >a2 Formål Formålet med denne beskrivelse er dels at lette det - ofte trivielle - arbejde med at udforme vedlige_holdelses_manualer og dels at sikre at alt relevant er med. Herved kan vedlige_holdelses_manualen danne grund_lag for udarbej_delse af andre manu_aler. Dette opnås ved en "standard-indholds_fortegn_else", som er vejledende i den forstand, at alle manualer ikke nødvendig_vis skal indeholde alle punkter. Den skal nærmest opfattes som en huske_seddel. >a2 Hvad er et modul ? Ifølge ref. 3 er defini_tionen på et modul: >in2 "Et >ul modul er en logisk sammen_hængende enhed i et system. Et modul kan bestå af een eller flere processer, proce_durer, funktioner samt sammen_sætninger af disse eller delmængder af disse. Et modul er karakte_ristisk ved at det i systemet indgår som en enhed med hensyn til beskriv_else, registre_ring, program_mering osv." >in-2 >ne5 Et modul kan således fx være: - et program - en programdel - en procedure Sproget, programmet er skrevet i, samt maskinen, det skal køre på, er under_ordnet - alt software fra assemb_ler-program_mer i mikro_proces_sorer til ALGOL-progra_mmer i RC8000 kan beskrives i denne struktur. >a3 Systemer med flere moduler Er et givet system sammensat af flere moduler (fx corutiner i et corutine_system) skal der findes en vedlige_holdelses_manual for hvert modul. Herudover skal der skrives en vedlige_holdelses_manual for total_systemet. Alle vedlige_holdelses_manualer skal struktu_reres på samme måde, dvs. ifølge standarden beskrevet i dette skrift. En total system_vedlige_holdelses_manual bør indeholde en beskri_velse af systemets forskel_lige moduler samt en beskriv_else af, hvordan de kommuni_kerer. >ul Globale datastruk_turer, filer og lignende beskrives her. Endvidere bør semaforer, pools, message_formater og message_typer, der er >ul fælles for flere moduler, beskrives her. Eventuelt kan disse ting beskrives i særskilte skrifter, der kan refereres til. System_vedlige_holdelses_manualen bør i sin reference_liste have referencer til >ul samtlige andre skrifter, manualer og vedlige_holdelses_manualer i systemet. Subsidiært en reference til et særskilt skrift_register (se fx ref. 4). >a2 Typer af manualer Der eksisterer mange forskel_lige typer af manualer ud over vedlige_holdelses_manualer (reference manualer, user's guide osv.). Disse typer er beskrevet i ref. 6. Det er imidler_tidig karakteris_tisk for vedlige_holdelses_manualer, at de indeholder >ul al relevant infor_mation om et givet modul/sy_stem. Det er meningen at en vedlige_holdelses_manual skal kunne bruges som grundlag for at skrive de øvrige manualer. >a1 ARBEJDS_FORM Nærværende skrift lægger - ud over en struktur for indholdet - også op til en bestemt >ul arbejds_form omkring udarbejdel_sen af vedlige_holdelses_manualen. Det er nemlig tanken at sådanne manualer bør udarbejdes >ul side_løbende med specifikation og implementering. Dels fordi arbejdet hermed bliver mere overkom_meligt, dels fordi det meste af den informa_tion, der skal være i manualen, er til_gænge_ligt på et eller andet tidspunkt i implemen_terings_fasen. >a2 Ringbind Det er tanken, at når specifikationen starter, laves et ringbind for hvert modul. Dette forsynes med et sæt faneblade (10 stk.) samt en fane_blads_forside (brug fx standard blanket nr. 2: fanebladsforside). For store modu_ler/sy_stemer kan det anbefales at indsætte en "kapi_tel-over_sigt" (d.v.s en oversigt over kapit_lets under_afsnit) først i hvert fane_blads_afsnit. Hver gang man fremstiller et stykke papir vedrørende modulet sættes det ind i mappen det relevante sted. Dette kræver natur_lig_vis den disciplin, at man faktisk >ul frem_stiller dokumen_tation. Dette må imidlertid kraftigt anbefales. >a2 Side_nummere_ring Benyttes den ovenfor skitserede arbejds_form til frem_stilling af vedlige_holde_lses dokumen_tation_en, er det umuligt at holde siderne fort_løbende nummere_rede. Ikke desto mindre bør alle sider altid være nummere_rede, og det anbefales derfor at nummerere siderne >ul indenfor hvert afsnit og underafsnit. Består afsnit 3.2 således af fx 3 sider nummereres de: 3.2-1, 3.2-2 og 3.2-3 Kommer der en ny side til indsæt_telse mellem siderne 3.2-1 og 3.2-2 får den nummeret 3.2-1A. Endvidere bør samtlige sider dateres og den ansvar_lige for_fatters ini_tialer an_føres. Rettelse af siderne kan ske ved over_stregning af for_ældet tekst og anførel_se af nyt indhold. Alle rettelser mar_keres med korrektions_linier samt dato og ini_tialer. >a2 Distri_bution I større projekter, hvor flere personer arbejder sammen om udarbej_delsen af systemets forskel_lige moduler, er det vigtigt at alle hele tiden holdes opdateret med den til enhver tid gældende dokumen_tation. Det er derfor vigtigt at have faste procedurer omkring opdaterin_ger og distribu_tion af disse. Dette indbe_fatter bl.a. udnævnel_se af en >ul master-ansvarlig person. Benyttes DOKS-sy_stemet til skrift_registre_ring (se ref. 4) kan dettes opdaterings_blade anvendes. Der bør endvidere frem_stilles en distri_butions_liste, der indsættes forrest i masteren. Udgives vedligehol_delses_manualen kan standard blanket nr. 1 (table of contents) anven_des som indholds_fortegnel_se. >a1 INDHOLDET AF MODUL_BESKRIVEL_SEN I dette kapitel uddybes afsnit_soverskrif_terne fra standard_forsid_en. Kapitlet er inddelt i af_snit, der følger modul_beskrivel_sens opdeling i afsnit. Fx er der i denne manuals under-afsnit 3.2.1 speci_fice_ret, hvorledes modul_beskrivel_sens afsnit 2.1 udformes. >a2 Introduk_tion Formålet med modulet beskrives, dvs. - modulets rolle i dets omgivel_ser, og - modulets funktion En eventuel læsevej_ledning (om hvad der er beskrevet hvor) bringes også her. >a3 Revisions_historie Her noteres de ændringer, der løbende er foretaget i modul_beskrivel_sen, i store træk. Dette indebærer angivelse af dato for rettelse, >ul hvem der har foretaget rettelsen, >ul hvor i beskrivel_sen det er sket, >ul hvad rettelsen gik ud på og eventuelt >ul hvorfor rettelsen er foretaget. Standard blanket nr. 3, Revision Record, kan eventuelt anvendes. >a3 Termer, notation og forkortel_ser Her beskrives de konven_tioner og notations_former, der er anvendt i koden i forbindel_se med label_navne, variabel_navne osv. Disse konven_tioner bør naturlig_vis fastlægges >ul før program_meringen begynder og for >ul alle moduler i systemet, hvis dette indeholder flere moduler. Endvidere gives en liste over anvendte "non-stan_dard" forkortel_ser. Standard RC-terminologi, for_kortelser og skrive_måder er beskrevet i ref. 5. Et eksempel på en liste over for_kortelser er givet i bilag B.1. >a2 Data Strukturer Her beskrives de globale data_strukturer, der benyttes i modulet, fx: - records - pointere - variable - konstanter - typer - process de_scriptors - coroutine de_scriptors - activity de_scriptors Der kan eventuelt henvises til be_skrivelser, der findes andre steder (REAL-TIME PASCAL-environ_ments, ALGOL-copy eller andre externals). Hvor det skønnes at kunne lette for_ståelsen suppleres med >ul figurer over de benyttede data_strukturer og deres indbyrdes relationer (se bilag B.2). De >ul operationer, der kan udføres på de for_skellige strukturer skal også beskrives, hvis det skønnes nødvendigt for for_ståelsen. Det kan fx dreje sig om procedurer til ind_sættel_se af elementer i kæder etc. Endelig skal >ul initi_alise_ringer og initia_liserings_metoder beskrives, såfremt de ikke på simpel måde fremgår af kodens initiali_serings_afsnit. Det er ikke meningen, at program_tekstens erklæ_ringsdel skal gentages her - det er de struk_turer/variable, der ikke er umiddelbart for_ståelige. I de tilfælde, hvor data_strukturer anvendes af flere moduler, be_skrives de i detaljer netop eet sted, og der refereres til beskri_velsen fra de øvrige moduler. Beskrivel_sen placeres i vedligeholdel_ses_dokumen_tationen for det totale system; hvis en sådan ikke findes, placeres beskri_velsen sammen med det modul, der genererer (føder) data_strukturen. >a3 Semaforer og Pools Her beskrives de semaforer, semafor-pointere, refe_rencer og pools, modulet benytter. Det gælder såvel interne som eksterne semaforer. Semafor-arrays skal også beskrives her. For hver sema_for/pool skal beskrives: >in 22 >ti-22 navn:@@@@@@@@@@@@@@@@@det navn, modulet kender semaforen under. >ti-22 beskrivelse:@@@@@@@@@@en beskrivelse af hvad semaforen/poolen bruges til. >ti-22 signa_lerende moduler:@opremsning af de modu_ler/pro_gramdele, der signalerer til semaforen. Dette gælder også hvis det sker ved retur_nering. For pools nævnes de modu_ler/program_dele, der releaser buffere til poolen. >ti-22 ventende modu_ler:@@@@@oprems_ning af de modu_ler/program_dele, der venter på semaforen. Dette gælder også hvis det blot drejer sig om afføling af semaforen. For pools nævnes de modu_ler/program_dele, der allokerer buffere fra poolen. >ti-22 til_knyt_tede buf_fere:@@oprems_ning af de buffere, der er tilknyttet semaforen. Eventuelt opremses de referen_cer, der benyttes til bufferne. >ti-22 start til_stand:@@@@@@@beskriv_else af hvorledes semaforen skal initia_lise_res. For pools nævnes antallet af buffere, den fødes med. >in-22 En figur med alle benyttede semaforer - interne såvel som eksterne - bør gives her. >a3 Buffere og Messages Her beskrives formatet for de buffere og/eller messages, der bruges i kommuni_katio_nen med andre moduler eller internt i modulet. Såfremt de formater, der anvendes er beskrevet andre steder (fx i environ_ment, system_parame_tre eller i et specielt skrift om alle messages i det givne system) henvises til denne beskriv_else. Det anbefales, at man benytter ens formularer de steder, det kan lade sig gøre. Disse formularer er imidlertid ofte system_afhængige og må derfor opfindes til lejlig_heden. Fx skal det for messages i RC8000 beskrives: - hvilken proces den sendes til - eventuel operation_sko_de - meddelel_sens navn - meddelel_sens funktion - format for message - format for answer - eventuelle bemærk_ninger, fx til meddelel_sens brug eller til dens format. >a3 Tabeller og Arrays Benyttes tabel_ler/arrays skal de beskrives i dette afsnit. Det gælder også de >ul records, der eventuelt måtte indgå i tabel_lerne. Der kan eventuelt suppleres med >ul figurer over tabellerne og deres indbyrdes referen_cer. Som eksempel se bilag B.2. De >ul operatio_ner, der kan udføres på tabellerne skal også beskrives (fx procedurer til indsæt_telse, opdatering osv.). Tabel_lernes >ul initia_lisering (og eventuelt initia_liserings_proce_durer) beskrives også. >a3 Filer Her beskrives de filer, modulet benytter på run-time. Det gælder såvel eksterne filer som interne filer ("arbejds_filer"). >ul Strukturen skal beskrives og om nødvendigt illustre_res med figurer (se fx bilag B.3). Er filen opdelt i records skal >ul formatet for disse beskrives. Endelig skal de >ul operatio_ner, der udføres på filen og dens records beskrives. Også filens medium skal beskrives her (disc, floppy, magnet_bånd, etc.). Tekstfiler (dvs. printer_output) beskrives under pkt. 4.2. >a2 Program Struktur I dette afsnit beskrives strukturen af program_met. Dette gøres dels på det modulære niveau, dels på pro_gram-tekst niveau. Det modulære niveau beskrives ved hjælp af >ul diagram_mer, der angiver funk_tionel_le moduler, semaforer, buffer flow, pools osv. Ved tegning af disse diagrammer benyttes standard_symboler som vist i bilag B.4. På program_tekst niveau skal strukturen beskrives ved hjælp af >ul pseudo-kode (se bilag B.5). Formålet med afsnittet er at bibringe læseren et til_stræk_keligt kendskab til selve programteksten til at kunne finde rundt i dens enkelte dele. >a3 Kodnings_princip_per Her skal kodens >ul virkemåde beskrives for så vidt den ikke fremgår af program_teksten. Det vil fx sige specielle >ul teknikker, der ikke er alminde_ligt brugt, skal omtales her. >ex Tilstands_maskiner Fungerer programmet som en tilstands_maskine skal der her beskrives: - tilstande - handlinger - mulige input - transitionsd_iagram. >ex Algorit_mer Benyttes en særlig algoritme (fx til sortering) beskrives dens virkemåde her. >a3 Modes Hvis modulet kan optræde i forskel_lige "modes", eller kan sættes i et særligt mode, hvor det opfører sig anderledes end sædvan_ligt, kan dette beskrives her. Det kan fx dreje sig om kald-para_metre, der har ind_flydelse på hele modulets virkemåde, eller det kan dreje sig om input, der på run-time ændrer modulets virkemåde. >a3 Under_moduler Del_processer, store procedurer og program_dele, som kun er >ul nævnt i afsnit 3 beskrives her. Nedbryd_ningen fortsættes så langt som det skønnes nødvendigt for at kunne læse program_teksten uden besvær. Også tværgående funktio_ner, som berører flere af program_mets under_moduler, kan beskrives her. Er modulet beskrevet andre steder - fx hvis det er external - skal der henvises til dette. >a2 Ekstern kommuni_kation Her beskrives hvilke andre moduler, dette modul kommuni_kerer med. Der bør gives en figur visende modulet samt dets snitflader til omverde_nen. >ex Pseudo_processer Kommuni_kerer et RC8000-pro_gram via pseudo_processer beskrives disse her. >a3 Input Her beskrives behand_lingen af de typer input, modulet kan modtage. For >ul buf_fere/mes_sages nævnes de funktions_koder, der kan behandles. Selve formatet beskrives under pkt. 2.2. Er der tale om >ul operatør_input kan formatet beskrives, og der kan eventuelt gives eksempler. De forskel_lige >ul filer, modulet læser fra skal nævnes. Selve formatet beskrives under pkt. 2.3. >a3 Output Her beskrives de typer af output modulet kan producere. For >ul buf_fere/mes_sages nævnes de funktions_koder, der afsendes. Selve formatet beskrives under pkt. 2.2. For >ul operatør_output beskrives formatet og der kan eventuelt gives eksempler. For >ul printer_output gives formatet. Det oplyses om der eventuelt skal benyttes fortrykte prin_terformu_larer. Der kan eventuelt vedlægges eksempler på de udskrif_ter, modulet kan producere. De forskel_lige filer modulet genererer skal nævnes. Selve formatet beskrives under pkt. 2.3. >a2 System Generering I dette afsnit skal beskrives hvorledes man kommer fra sou_rce-teks_ten til et program, der er klar til at blive kørt. >ul Installa_tions- og system_paramet_re samt eventuelle >ul options skal nævnes, og det skal beskrives hvilken betydning de har, samt hvilken ind_virk_ning, de har på hinanden. Endelig beskrives arbejds_gangen for at >ul oversætte modulet. Benyttes et >ul job til at gøre det, skal dette listes. Benyttes >ul hjælpe_programmer skal disse beskrives (evt. med hen_visning). Kræves bestemte >ul baser på RC8000 skal dette også beskrives. Relevante udskrifter fra compileren kan vedlægges. >a3 Compi_le-ti_me Hardware Her beskrives de hardware forudsæt_ninger, der er nødvendige for at >ul over_sætte/generere modulet. Det gælder fx: - maskine (fx RC8000) - lager_størrelse - specielle devicer (fx punch) Der kan eventuelt tegnes et diagram over konfigura_tionen. >a3 Compi_le-ti_me Software Her beskrives de software forudsæt_ninger, der er nødvendige for at >ul over_sætte/genere_re modulet. >ne 7 Det gælder fx: - process størrelse - specielle hjælpe_program_mer - filer med system_paramet_re - filer til indkopi_ering (AL_GOL-co_py) - filer til linkning, etc. >a3 Instal_lation Her beskrives hvorledes modulet instal_leres, såfremt dette gøres på en speciel måde. Der skal således beskrives den >ul arbejds_gang, der skal følges for at det oversatte modul kan bringes til at køre i de rette omgivelser (eller den rette maskine). Det kan fx dreje sig om instruk_tion i at loade bestemte filer ned fra et bestemt magnet_bånd. >a2 Kørsel I dette kapitel skal beskrives hvordan modulet køres. Afsnittet er ikke relevant, hvis modulet er en procedure. Hvis modulet er et program, skal der angives >ul syntaks for kaldet. En eventuel >ul jobfil til at køre programmet skal listes. Er en særlig >ul kørsels_vejledning relevant, placeres den her. Såfremt modulet i bestemte situa_tioner kan >ul genstarte sig selv, beskrives dette. >a3 Run-time Hardware Her beskrives de hardware forudsæt_ninger, der er nødvendige for at >ul køre modulet. >ne 10 Det gælder fx: - maskine (fx RC3502) - lager_størrelse - specielle devicer (fx bånd_station eller farve_skærm) - specielle materialer (fx fortrykte printer formu_larer) Hvis det er relevant tegnes et diagram over konfigura_tionen. >a3 Run-time Software Her beskrives de software forudsætnin_ger, der er nødvendige for at køre modulet. Det gælder fx: - externals, der bruges på run-time - filer, modulet kræver adgang til - hjælpe_programmer - særligt basis_programmel (fx "RC8000 basis_system nyere end release 1.4 (SW8001/1)" eller "SW8100/1 (MIPS/TS)"). >a3 Fejl_udskrif_ter Her skal alle modulets fejl_udskrif_ter listes. For hver fejl_udskrift gives en >ul forklaring og en metode til at >ul udbedre den. Endelig skal modulets >ul fejl_reaktioner beskrives (fx frigivelse af res_sourcer, hvilke procedurer kaldes osv.). >a3 Test_faciliteter Her beskrives de test_faciliteter, der er indbygget i modulet. Kan modulet producere >ul test_output, skal det beskrives, hvorledes dette slås til og fra, samt hvorledes det fortolkes. Findes der specielle programmer til at fortolke en fil med test_output, skal dette beskrives (der kan evt. henvises, hvis det er beskrevet andet_steds). Det er >ul ikke meningen at de test_udskrifter, der let kan aflæses fra program-teksten, skal listes her. Der kan eventuelt vedlægges et >ul eksempel på testoutput fra modulet. Findes der specielle hjælpe_værktøjer, der kan bruges til at afteste modulet, skal disse nævnes, og der skal eventuelt refereres til dem. >a3 Test_rapport En test_rapport indeholder to dele: - strategi for udførelse af test - dokumen_tation for vel udført test >ul Test_strategien skal liste samtlige tests, der er nød_vendige, for - med rimelig sikkerhed - at kunne erklære modulet fejlfrit. Der skal for hver test gives testinput (testdata) samt modulets korrekte reaktion. Der kan fx benyttes specielle >ul for_mularer, som dog må special_fremstilles. Et eksempel er vist i bilag B.6. >ul Dokumen_tationen skal vise at testen er korrekt gennem_ført. Den kan fx bestå af en listning af en kørsel med modulet. Eller en listning af test_output, modulet har produ_ceret. >a2 Bilag A: Referencer Beskriv_else af de referen_cer, der er henvist til i modul_beskriv_elsen. Referen_celisten skal udformes i overens_stemmelse med ref. 2. >ap >a1 REFERENCER >ti-4 >ul 1.@@"Stan_dard for modul_beskrivelse (for_slag)". Torkil Bogh, marts 1980, 18 sider. >sp0 RCSL Nr. 52-AA965. Denne manual definerer standard for beskriv_else af moduler i forbindel_se med vedlige_holdel_ses_dokumen_tation for software_produkter. Den har dannet grundlag for udarbej_delsen af nærværende skrift. >ti-4 >ul 2.@@"Stan_dard for opbygning, skrivning og trykning af >ul RC klasse 2 manualer". Jens Falkenberg Andersen, Lis Clement, Henny Leth, oktober 1978, 28 sider. >sp0 RCSL Nr. 43-GL7390. Denne manual definerer standarder for RC klasse 2 manualer. Den henvender sig til for_fattere, skrive_personale og trykkere. Der bringes detal_jerede beskriv_elser af arbejds_fordeling og ansvar. >ti-4 >ul 3.@@"Stan_dard for program_tekster skrevet i PAS_CAL-lig_nende sprog". Erik Dybdal, oktober 1980, 15 sider. >sp0 RCSL Nr. 52-AA1001. >sp0 Dette skrift beskriver hvorledes en program_tekst bør opbygges for at den på en naturlig måde kan indgå i dokumen_tationen for et soft_ware_system. >ti-4 >ul 4.@@"Dokument_systemet DOKS" Stephen Biering-Sørensen, september 1980, 14 sider. >sp0 RCSL Nr. 52-AA997. >sp0 Denne manual beskriver et system til nummere_ring og registre_ring af alt skriftligt materiale i et projekt. >ne10 >ti-4 >ul 5.@@"RC Terminology List". Rune Einersen, Bodil Larsen, Klaus Hansen, september 1980, 48 sider. >sp0 RCSL Nr. 31-D609. Denne liste definerer alle termer, for_kortel_ser og skrive_måder, som bruges i for_bindel_se med RC-pro_dukter og som ikke er standard EDB-ter_mer. >ti-4 >ul 6.@@"Titler og indhold af produkt-dokumentation" Lis Clement, juni 1981, 15 sider. >sp0 RCSL Nr. 42-i1759. Dette skrift beskriver titler, indhold og struktur af RCs produkt-dokumenta_tion, hvorved menes den rent tek_niske infor_mation, der er nød_vendig for at kunne forstå, anvende og vedlige_holde et produkt. >a1 ILLU_STRA_TIVE EKSEMPLER I dette bilag gives en række uddybende eksempler. Det drejer sig om: 1. Eksempel på liste over for_kortel_ser 2. Illustra_tion af datastruk_tur 3. Illustra_tion af filstruk_tur 4. Standard_symbo_ler 5. Pseudokode 6. Test_formu_larer >a1 STANDARD BLANKETTER >rc $ >pn $p 11 I dette bilag findes standard blanket_ter, der kan bruges ved udform_ningen af vedlige_holdelses_manualen. De er ikke nummere_rede, da det er tanken, de skal kunne kopieres direkte. Det drejer sig om: 1. Table of contents 2. Fane_blads_forside 3. Revision Record ▶EOF◀