Come usare script HTML definiti esternamente

2. Leggere in memoria lo script html definito esternamente

Si utilizzi la procedura

getHtml per caricare in memoria l' html definito esternamente in un membro di file sorgente (questa operazione equivale alla "open" di un file display).
getHtmlifs per caricare in memoria l' html definito esternamente in un stream file dell'IFS.
getHtmlifsMult per caricare in memoria in un colpo solo più script HTML definiti esternamente in file IFS.

Esempi per delimitatori di default, sia sezioni che variabili:

section start delimiter: /$
variable start delimiter: /%
variable end delimiter: %/

1) getHtml

C                   eval      HtmlSrcLib = 'CGIDEV2'
C                   eval      HtmlSrcFil = 'DEMOHTML'
C                   eval      HtmlSrcMbr = 'EXERCISE'
C                   callp     gethtml(HtmlSrcFil:HtmlSrcLib:HtmlSrcMbr)

C                   callp     gethtml('DEMOHTML':'CGIDEV2':'EXERCISE')

2) getHtmlifs

C                   callp     gethtmlifs('/CgidevExtHtml/talk2ifs.html')

Si noti come il directory da specificare come parametro della procedura gethtmlifs è ha il suo vero nome, non l'alias specificato in una eventuale direttiva pass per l'HTTP. Si raccomanda di tenere gli scripts html in directory IFS non utilizzati per pagine statiche ed immagini accessi dal serventi HTTP.

3) getHtmlifsMult
Questa procedura consente di caricare in memoria più file HTML definiti esternamente nell'IFS. Le sezioni ed i record dei vari file vengono caricati in memoria dinamica come se risiedessero in un unico file. Se una sezione compare più di una volta, viene utilizzata la prima di esse.
Questa funzione consente di mantenere in file separati spezzoni di HTML di uso frequente, come per esempio testate, barre di navigazione, chiusure di pagina, ecc.. In molte situazioni, il poter spezzare gli script HTML in moduli può ridurre notevolmente sia il tempo di sviluppo che quello di manutenzione.

 * Indicators for GetHtmlIfsMult subprocedure
D IfsMultIndicators...
D                 ds
D  NoErrors                       n
D  NameTooLong                    n
D  NotAccessible                  n
D  NoFilesUsable                  n
D  DupSections                    n
D  FileIsEmpty                    n
   ... etc. ...
 * Read externally defined output html files
C                   eval      IfsMultIndicators = gethtmlifsmult(
C                             '/CgiDevExtHtml/StdTop.Html -
C                             /CgidevExtHtml/StdRunTime.Html -
C                             /CgidevExtHtml/StdMsg.Html -
C                             /CgidevExtHtml/StdPssr.Html -
C                             /CgidevExtHtml/Talk2Stuff.Html -
C                             /CgidevExtHtml/StdEnd.Html')

Vedi l'esempio nel CGI TEMPLATE5.

Nota 1. Le procedure getHtmlifs e getHtmlifsMult possono anche caricare membri sorgente HTML visti come parte del directory /QSYS.LIB/....
Vedi l'esempio seguente:

 * Read externally defined output html files
C                   eval      IfsMultIndicators = gethtmlifsmult(
C                             '/CgiDevExtHtml/StdTop.Html +
C                             /QSYS.LIB/MYLIB.LIB/HTMLSRC.FILE/X.MBR')

Nota 2. Quando si usano le procedure getHtmlifs e getHtmlifsMult occorre assicurarsi che i file IFS contenenti gli script HTML siano accessibili in lettura al profilo utente QTMHHTP1 (profilo interno che l'HTTP server assegna ai CGI per la loro esecuzione). Entrambi gli esempi seguenti sono validi (il fatto che negli esempi il file sia posseduto da QPGMR è del tutto irrilevante):

	Data	--Object Authorities--
User	Authority	Exist	Mgt	Alter	Ref
*PUBLIC	*RX
QPGMR	*RWX	X	X	X	X

oppure

	Data	--Object Authorities--
User	Authority	Exist	Mgt	Alter	Ref
*PUBLIC	*EXCLUDE
QPGMR	*RWX	X	X	X	X
QTMHHTP1	*RX

Esempi di codifica relativi all'utilizzo di delimitatori specificati dall'utente (vedi anche questa pagina).

Primo esempio:

delimitatore inizio nome sezione: "<!-- Sec_"
delimitatore fine nome sezione (facoltativo): " -->"
delimitatore inizio variabile: "<var400>"
delimitatore fine variabile (facoltativo): "</var400>"

C                   eval      HtmlSrcLib = 'CGIDEV2'
C                   eval      HtmlSrcFil = 'HTMLSRC'
C                   eval      HtmlSrcMbr = 'TALK2'
C                   callp     gethtml(HtmlSrcFil:HtmlSrcLib:HtmlSrcMbr:
C                             '<!-- Sec_':
C                             ' -->':
C                             '<var400>':
C                             '</var400>')

Secondo esempio:

delimitatore inizio nome sezione: "<as400>"

C                   callp     gethtmlifs('/CgidevExtHtml/talk2ifs.html':
C                             '<as400>')

 * Indicators for GetHtmlIfsMult subprocedure
D IfsMultIndicators...
D                 ds
D  NoErrors                       n
D  NameTooLong                    n
D  NotAccessible                  n
D  NoFilesUsable                  n
D  DupSections                    n
D  FileIsEmpty                    n
   ... etc. ...
 * Read externally defined output html files
C                   eval      IfsMultIndicators = gethtmlifsmult(
C                             '/CgiDevExtHtml/StdTop.Html -
C                             /CgidevExtHtml/StdRunTime.Html -
C                             /CgidevExtHtml/StdMsg.Html -
C                             /CgidevExtHtml/StdPssr.Html -
C                             /CgidevExtHtml/Talk2Stuff.Html -
C                             /CgidevExtHtml/StdEnd.Html':
C                             '<as400>')

3. Valorizzare le variabili dell'HTML esterno

Per questa operazione si utilizza la procedura updHtmlVar.
Questa procedura assegna un valore a tutte le ripetizioni di una data variabile (nome) html.
Nota. Il valore da assegnare deve essere espresso in caratteri (campi numerici devono essere convertiti o editati in stringhe di caratteri, vedi gli esempi numero 4 e 5).

Input
nome della variabile html valore da assegnare a tale variabile azione (facoltativa) '1' = sostituisci questa variabile se esiste già, altrimenti aggiungila (azione di default) '0' = azzera tutte le variabili e assegna questa come prima variabile istruzioni di ritaglio (facoltative) %trim - togli blank sia a sinistra che a destra (azione di default) %triml - togli i blank solo a sinistra %trimr - togli i blank solo a destra %trim0 - non togliere nulla

Esempi:

Azzera tutte le variabili; alla variabile di nome custname assegna il valore contenuto nel campo (carattere) di nome CusNam:

 * Constant for updHTMLvar subprocedure
D initHTMLVars    c                   '0'
 *            ... etc. ...
C                   callp     updHTMLvar('custname':CusNam:InitHTMLVars)

Alla variabile html di nome custaddr assegna il valore contenuto nel campo di nome CusAdr:
C callp updHTMLvar('custaddr':CusAdr)
Alla variabile html di nome custaddr assegna il valore contenuto nel campo di nome CusAdr senza spuntare i blank nè a sinistra nè a destra
C callp updHTMLvar('custaddr':CusAdr:'1':'%trim0')
Alla variabile html di nome ordertotal assegna il valore contenuto nel campo di nome TotThisOrd utilizzando un "edit code":
C callp updHTMLvar('ordertotal': C %editc(TotThisOrd:'J'))
Codici di editazione
Alla variabile html di nome ordertotal assegna il valore contenuto nel campo numerico (9 2) di nome TotThisOrd utilizzando un "edit word":
C callp updHTMLvar('ordertotal': C %editw(TotThisOrd:' , , 0. '))
Vedi questo esempio dinamico.

4. Emettere sezioni di HTML e spedire il buffer

Per queste operazioni si utilizza la procedura wrtsection.
In una chiamata si possono emettere una o più sezioni.
Importante.
Una volta che tutte le sezioni desiderate sono state emesse, non si dimentichi di spedire al client il buffer di output. Questo si fa emettendo una sezione fittizia di nome *fini.

Esempio:

 * Emetti una sola sezione
C                   callp     wrtsection('start')
 * Emetti due sezioni
C                   callp     wrtsection('part1 part2')
 * Spedisci il buffer html al client
C                   callp     wrtsection('*fini')

Nota 4. Il nome della sezione non risente del maiuscolo/minuscolo. La lunghezza massima è di 50 caratteri. Non si accettano nè lettere accentate nè caratteri speciali.

Nota 5. La procedura wrtSection può avere due parametri facoltativi:

Indicatore NoNewLine.
Lo si imposta ad *on per segnalare che la wrtsection NON deve inserire il carattere di a-capo x'15' alla fine di ogni riga dell'HTML. Ciò è indispensabile quando al browser vengono inviati dei dati binari.
Valore NoDataString.
Segnala che cosa va fatto quando viene trovata una variabile di output a cui non è stato assegnato valore alcumo tramite UpdHtmlVar.
In sua assenza, alle variabili di output non valorizzate viene assegnato il valore "**Missing Data**".

Esempi:

D NoDataString    c                   '<b>*** no substitution! ***</b>'
 * Write a section without newline characters
C                   callp     wrtsection('mysection':*on)
 * Write a section with non-default warning for
 * missing substitution variables
C                   callp     wrtsection('mysection':*off:
C                             NoDataString)

5. Procedure particolari di output

La procedura wrtNoSection
invia dati al browser senza usare variabili di sostituzione nè sezioni.
È ideale quando si debba inviare in output un grosso blocco di dati, per esempio quando si tratti di emettere immagini o comunque dati non testuali. L'esempio seguente illustra come leggere un file IFS esterno (una pagina HTML, una immagine, ...) e come inserirla nel buffer di output di un programma CGI:

D IfsInpBuff      s          10000a   varying
D InpBuffLen      s             10i 0
D IfsObj          s            255a
D FileHandle      s             10i 0
D ReturnInt       s             10i 0
D BytesIn         s             10i 0
* ... ... ...
* Read an IFS object into "IfsInpBuff"
C                   eval      IfsObj = '/mypath/mysubpath/myobj.xxx'
*   1-Open the IFS file
C                   eval      FileHandle = open(%trim(IfsObj)
C                               : O_RDONLY + O_TEXTDATA)
*   2-Read the IFS file
C                   eval      BytesIn = read(FileHandle
C                               : %addr(IfsInpBuff)
C                               : %size(IfsInpBuff))
*   3-Close the IFS file
C                   eval      ReturnInt = close(FileHandle)
C                   eval      IfsInpBuff = %trim(IfsInpBuff)
* Insert the string read into the CGI output buffer
C     ' '           checkr    IfsInpBuff    InpBuffLen
C                   callp     WrtNoSection(%addr(IfsInpBuff):
C                             InpBuffLen)

La procedura clrHtmlBuffer
pulisce tutto quanto è stato posto nel buffer di output HTML, purchè non sia già stato spedito al client o scritto in uno stream file.
Questo è utile quando la logica del programma impone di fornire in output qualcosa di diverso da quanto è già stato posto nel buffer.

C                   callp     clrHtmlBuffer

La procedura getHtmlBytesBuffered

Restituisce la lunghezza (numero di byte) del buffer HTML di output

La lunghezza aumenta ogni volta che si scrive dell'output con la procedura WrtSection o con la procedura WrtNoSection

La lunghezza viene ripristinata a 0 quando si esegue WrtSection('*fini') oppure WrtHtmlToStmf

Se si lascia che la lunghezza del buffer HTML di output superi i 16 Mb, il programma CGI fallisce.
Questa procedura può essere utile per decidere di troncare una pagina HTML di output quando le sue dimensioni superino un limite ragionevole.

D buffsize        s             10i 0
C                   eval      buffsize = getHtmlBytesBuffered

La procedura getHtmlBufferP

Restituisce il puntatore al buffer HTML di output ed il numero di byte utilizzati in questo buffer.

Utile per effettuare del debugging o per prelevare dal buffer quanto ivi scritto.

 D OutBuffer       s          32767    based(OutbufferP)
 D OutBufferInfo   ds
 D  OutBufferP                     *
 D  OutBufferLen                 10u 0
 C                   eval      OutBufferInfo=callp(GetHtmlBufferP)

La procedura crtTagOpt

Restituisce una tag HTML <option value="...">...</option>
da utilizzarsi nell'ambito di una <select ...> .

Naturalmente esistono altri modi per creare le <option> all'interno di una selection list.

/$strselect
<table>
<tr><td>Please select desired date:</td></tr>
<tr><td><select name="date">
/$option
/%optionvalue%/
/$endselect
</select>
        </td></tr>
</table>

     D dates           s             15    dim(3)
     D i               s             10i 0
     D optionValue     s            200    varying
      /free

           wrtsection('strselect');
           for i=1 to 3;
              optionValue=CrtTagOpt(%char(i):dates(i));
              updhtmlvar('optionvalue':optionValue);
              wrtsection('option');
           endfor;
           wrtsection('endselect');

Abbiamo un programma che dimostra l'utilizzo della procedura CrtTagOpt: