HIPOT - program za dokumentacijo

Slabost dokumentacije AROPS za računalniške sisteme IBM je nefunkcionalnost, ker je

• nepopolna
• nesistematično urejena in
• napisana »post festum«.

Program HIPOT je prvenstveno narejen za dokumentacijo ozko povezano s samim programiranjem. To dokumentacijo mora napisati programer in opisuje logiko delovanja programa.

Osnovna ideja je, da se takoj po kodiranja nekega programskega modula v računalniškem jeziku (asembler, PL/I, RPG, COBOL itd.) napiše tudi ustrezna tekstualna (opisna) dokumentacija za ta modul.

Sistem programiranja in testiranja v SDK določa, da se takoj po končanem formalnem testiranju izvrši tudi katalogiziranje izvorne (source) oblike v ustrezno SSL (Source Statement Library). Ta sistem se sedaj dopolni tako, da se poleg izvorne kode modula katalogizira tudi njegova dokumentacija ter tako v ustrezni SSL dobimo dva modula:

• A.BOOKNAME – programska koda
• T.BOOKNAME – dokumentacija za A.BOOKNAME programski modul

Oba BOOKNAME imata isto ime toda različni podknjižnici. Tak način dela omogoča poleg urejene dokumentacije za vsak modul tudi enostavno distribucijo projekta, programa, modula skupaj z ustrezno dokumentacijo.

S programom HIPOT pa lahko natisnemo dokumentacijo tudi na papir.

Končni cilj tako avtomatiziranega načina izdelave dokumentacije s pomočjo SSL je

• vsak modul je dokumentiran
• enostavna distribucija
• dokumentacija se piše vzporedno z organiziranjem in programiranjem
• ON-LINE ažuriranje
• enotno in enostavno tiskanje s posebnim programom
• tiskanje na zahtevo in po potrebi

Način pisanja dokumentacije

Dokumentacija se piše v običajne kodirne liste za programsko kodo. Vse to se luknja v 80 kolonske kartice v kolone od 1 do 72. Kolone od 73 do 80 so rezervirana za IBM program MAINT, ki vzdržuje vse knjižnice. S HIPOT programom lahko te kartice neposredno izpišemo, če pa je dokumentacija katalogizirana v SSL, potem dobimo izpis s pomočjo delovnega magnetnega traku in ustrezne UPSI (User Program Switch Indicator) kartice.

Kontrolne kartice

Za lepšo in urejeno dokumentacijo je predvideno več kontrolnih kartic, ki so sestavni del vsakega modula. Te kontrolne kartice imajo podobno funkcijo kot TITLE, SPACE itd. v asembler jeziku.

Na razpolago so

• TITLE
• EJECT
• SPACE
• PUNCH
• END
• GENERALIJE

Oblika vseh kontrolnih kartic je naslednja:

• v koloni 1 in 2 sta znaka »*$« (brez apostrofov !), ki sta fiksna in identifikacijska oznaka kontrolne kartice. Zvezdica »*« v 1. koloni v asembler jeziku pomeni komentar.
• v kolonah 3, 4 in 5 je zapisana funkcijska oznaka za posamezno kartico.

*$TIT ukaz pomeni »TITLE« (naslov) in ima lastnosti

• besedilo do 67 znakov kot naslov takoj za *$TIT oznako
• izpis se začne na novi strani
• izpiše se tekoča stran dokumentacije
• po izpisanem naslovu 2 prazni vrstici za presledek
• pri vsaki novi *$TIT kartici se spremeni predhodne besedilo, razen če je ta nova *$TIT kartica brez besedila

*$EJE (EJECT) ukaz obsega

• skok na novo stran
• izpiše se besedilo s prejšnje *$TIT kartice
• izpiše se tekoča stran dokumentacije
• po izpisanem naslovi 2 prazni vrstici za presledek

*$SP# (SPACE – presledek) ukaz obsega

• presledek praznih vrstic navedenih kot parameter #
• lahko uporabimo od 1 do 9 praznih vrstic
• če uporabimo *#SP0 (ničla) potem se predhodna vrstica izpiše dvakrat, to je ena čez drugo, dobimo poudarjen izpis (BOLD ali krepko)

*$PUN (PUNCH) ukaz obsega

• poljubno besedilo (identifikacija) do 5 znakov takoj za *$PUN oznako
• začetek luknjanja in tiskanja vsega, kar sledi *$PUN ukazu
• izpis se začne na novi strani
• izpiše se tekoča stran dokumentacije
• po izpisanem naslovu 2 prazni vrstici za presledek
• doda se oznaka PUN pred vsako izpisano vrstico
• poljubna identifikacija do 5 znakov se samodejno doda vsaki kartici pred luknjanjem od 73 do 77 kolonami
• samodejno se doda vsaki kartici pred luknjanjem od 78 do 80 kolonami zaporedna številka

*$END ukaz obsega

• v primeru predhodnega *$PUN ukaza
• prekine se npr. luknjanje kartic
• briše poljubno izbrano 5 mestno identifikacijo
• dodatno luknja še 3 prazne kartice za morebitno lažje ločevanje več kompletov luknjanih kartic
• povrne se morebitno staro besedilo od predhodnega *$TIT ukaza

*$GEN (Generalije) ukaz obsega

• besedilo do 67 znakov takoj za *$GEN oznako
• ko izpisovanje dokumentacije doseže zadnjo vrstico na strani in pred skokom na novo stran, se izpiše besedilo v zadnji vrstici (kot »noga« ali footer«).
• besedilo je splošen podatek za celotno dokumentacijo določenega projekta, programa ali modula. Npr.: avtor, datum pisanja dokumentacije, verzija, …
• lahko se uporabi več *$GEN ukazov in novo besedilo prekrije staro
• priporoča se uporaba le enega *$GEN ukaza saj tako dobimo skupno identifikacijo za celoten projekt

Tiskanje dokumentacije

Vsako katalogiziranje (arhiviranje, shranjevanje) v IBM sistemske knjižnice SSL se izvede s pomočjo MAINT programa, ki med ostalim izvirno (source) vsebino stisne (ZIP) na poseben način. Pisanje posebnega uporabnikovega programa za izpis stisnjenih podatkov v SSL bi bilo nesmotrno, zato je bila uporabljena rešitev s pomočjo servisnega programa SSERV (Source Statement Library Service).

Tiskanje že shranjene dokumentacije v SSL je šlo takole v dveh korakih:

1.    korak: »luknjanje« T.DOKUMENTACIJA na delovni magnetni trak

Ustrezni JOB kontrolni ukazi pa so bili naslednji:

// JOB IZPIS DOKUMENTACIJE                1.
// ASSGN SYSPCH,X'280'                    2.
// EXEC SSERV                             3.
   PUNCH T.DOKUMT1,T.DOKUMENT2            4.
   PUNCH T.DOKUMENTX                      4.
/*                                        5.

2.    korak: izpis z uporabo HIPOT programa

Ustrezni JOB kontrolni ukazi pa so se nadaljevali takoj po 1. koraku:

// UPSI                                   6.
// ASSGN SYS004,SYSPCH                    7.
// EXEC HIPOT                             8.
/*                                        9.
/&                                        9.

Obrazložitev posameznega JCL ukaza – kartice:

1. prvi ukaz celotnega posla izpisa dokumentacije
2. rezultat programa SSERV naj bo na enoti 280 (delovni magnetni trak)
3. servisni program SSERV
4. ustrezni ukazi za program SSERV
5. ukaz, ki zaključi program SSERV
6. ustrezna uporaba UPSI kartice 
7. tračna enota za program HIPOT ista kot v 2. točki
8. program HIPOT, ki izpiše dokumentacijo na tiskalnik
9. ukaza, ki zaključujeta celoten JOB

Uporaba UPSI kartice ima naslednje pomene:

UPSI ukaz ni prisoten
na tiskalniku se izpiše dokumentacija v običajni obliki in način s pomočjo SSERV programa na delovni magnetni trak, ki je nato vhod za HIPOT program

// UPSI 1
poleg običajnega izpisa kot brez UPSI kartice se izpiše ob desni strani vsake vrstice še zaporedna številka vsake kartice v SSL knjižnici. Običajna uporaba takšnega izpisa je, da imamo podatek za popravljanje (UPDATE) s pomočjo MAINT programa.

// UPSI 01
omogoča izpis dokumentacije brez uporabe delovnega traku, saj so podatki – kartice z dokumentacijo nahajajo takoj za // EXEC HIPOT ukazom. Ta način se uporablja za urejanje dokumentacije pred katalogiziranjem v ustrezno SSL


Posebnosti

V primeru, da želimo kot sestavni del dokumentacije katalogizirati v SSL s programom MAINT tudi določene kartice, ki so sestavni del IBM JCL ukazov, ki lahko prekinejo ali povzročijo nezaželene rezultate, moramo upoštevati naslednje:

• // JOB IME ukaz zamenjamo s // JJJ IME
• /* ukaz zamenjamo s /Z
• /& ukaz zamenjamo s /A

Razumljivo je, da opisane zamenjave niso potrebne, če se ukazi ne začenjajo v 1. koloni!

Program HIPOT pri svojem izvajanju samodejno zamenja te tri izjeme in jih izpiše pravilno kot »// JOB IME«, »/*« in »/&«.


Junij 1976