|
DataMuseum.dkPresents historical artifacts from the history of: RC3500 |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about RC3500 Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - download
Length: 22272 (0x5700) Types: TextFileVerbose 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»