HTML definito esternamente

In un normale programma RPG-ILE che non usi il service program di Mel, occorre creare la stringa HTML di risposta e quindi spedirla utilizzando l'API Write to Stdout (QtmhWrStout). Costruire questa stringa all'interno del programma non è facile e costituisce un grave elemento di rigidità. Infatti ogni volta che occorra effettuare una variazione (del testo, dei link, delle immagini, e così via) bisogna modificare il programma.

Ben maggiore è la flessibilità di un programma tradizionale il quale utilizzi un display file.

Il service program di Mel consente di utilizzare una tecnica flessibile come le DDS, anzi ancora più semplice.
Queste tecnica viene denominata:

Ci sono due modi per definire dell'HTML esterno al programma:

utilizzare un membro di file sorgente
utilizzare uno stream file IFS

1. Utilizzare un membro di file sorgente

Ecco come si fa.

Crea un file fisico sorgente denominato HTMLSRC (il nome del tracciato record deve essere HTMLSRC) con lunghezza record 240 (non deve superare 240). Se vuoi, successivamente puoi ridenominare il file (il nome del tracciato record resterà HTMLSRC).
Nota 1. Quando usi il comando cgidev2/setcgilib, nella tua libreria "oggetti" ("di produzione") viene automaticamente creato questo file HTMLSRC.
Aggiungi un membro con nome di tua scelta (ti consigliamo di specificare HTML come tipo SEU).
Dividi il sorgente in sezioni.
- In un certo senso una sezione equivale ad un tracciato record nel corpo di un display file.
  Una sezione è un pezzo di html che il tuo programma CGI può decidere di emettere in una data situazione. Esempi di sezioni potrebbero essere:
  - l'avvio dell'html, con la definizione del titolo e del body
  - l'inizio di una table
  - la riga di una table
  - la fine di una table
  - la chiusura del body e dell'html
- Una sezione viene identificata da una riga contenente
  - /$nome_sezione a partire da colonna 1, dove nome_sezione è una parola lunga fino a 20 caratteri preceduta dal prefisso /$ (il prefisso /$ è quello standard, ma si possono utilizzare altri prefissi scelti dallo sviluppatore)
  - per esempio, la dicitura /$top ad iniziare da colonna 1 identifica la sezione di nome top
- La prima sezione emessa dal CGI deve iniziare come segue:
  
  /$section_name
  Content-type: text/html
  
  <html>
  Attenzione alla riga in bianco prima di quella contenente <html>. Se la si manca, il browser potrebbe non essere in grado di interpretare l'html e dare codice errore 500.
  - NOTA - Content-type è una così detta http header. Le HTTP header dicono al browser come si deve comportare. Tutte le HTTP header devono stare all'inizio dello script e devono terminare con due CRLF (Carriage Return Line Feed) consecutivi. Questo spiega perchè di fatto occorra fare seguire con una riga vuota l'ultima HTTP header.
    Per un elenco completo dell HTTP header, si veda questa pagina.

Gli script HTML delle sezioni possono contenere delle variabili. Un caso banale potrebbe essere quello di una riga di una table (riga di subfile) con celle <TD> (campi della riga di subfile) contenenti delle variabili, per esempio articolo e prezzo.

Nello script HTML le variabili si specificano con la sintassi seguente:
/%nome_variabile%/
dove nome_variabile è una parola lunga sino a 30 caratteri.
Il prefisso /% ed il suffisso %/ sono standard. Lo sviluppatore può però adottare altri prefissi/suffissi di sua scelta.
Non esiste alcuna necessità di dare ad una variabile lo stesso nome del campo di database da cui viene valorizzata, anche se ciò facendo si migliora la comprensibilità dello script.

Il CGI farà quanto segue:

Leggere in memoria il membro di html esterno utilizzando la procedura gethtml del service program di Mel
Valorizzare le /%variabili%/ (per esempio con i valori dei campi di un record di database) utilizzando la procedura updhtmlvar del service program di Mel
Emettere una o più sezioni di html utilizzando la procedura wrtsection del service program di Mel.

Delimitatori dei nomi delle Sezioni e delle Variabili

Delimitatori dei nomi delle Sezioni
Una sezione viene identificata dalla sequente sequenza che deve incominciare in colonna 1 di una riga a ciò riservata:
xxxsection_nameyyy
dove
- xxx è il delimitatore di partenza del nome della sezione (al massimo 10 caratteri) che va citato nel programma RPG quando si usa la procedura gethtml.
  Il valore di default per il delimitatore di partenza del nome della sezione è /$. Se la sezione è codificata in questo modo, il delimitatore di partenza del nome può essere omesso quando si chiama la procedura gethtml.
- section_name è il nome della sezione (obbligatorio) che va citato quando si chiama la procedura wrtsection. Il nome della sezione deve essere una stringa alfanumerica lunga al massimo 20 caratteri.
- yyy è il delimitatore di fine del nome della sezione (facoltativo, lunghezza massima 10 caratteri). Se utilizzato per definire i nomi delle sezioni, va specificato nel programma RPG quando si invoca la procedura gethtml.
Note sui delimitatori di nome di sezione
1. Il delimitatore di default per l'inizio del nome della sezione /$ può causare problemi quando l'HTML esterno si trova in uno stream file IFS. Ciò deriva dal fatto che il carattere $ può non essere interpretato correttamente dal service program CGISRVPGM2.
2. Noi suggeriamo di utilizzare la seguente rappresentazione:
  "<! -- Sec_" come delimitatore d'inizio del nome della sezione
  " -->" come delimitatore di fine del nome della sezione.
  Per esempio:
  <! -- Sec_top -->
  per la sezione di nome top.
  Questo approccio consente di definire il nome della sezione come un commento HTML ed è quindi trasparente agli strumenti per la scrittura automatica di HTML.
Delimitatori dei nomi delle Variabili
I delimitatori di default per i nomi delle variabili sono
/% e %/
Si possono utilizzare anche delimitatori definiti dall'utente (lunghezza massima 10 caratteri).
I delimitatori dei nomi di variabile specificati dall'utente vanno citati al momento del caricamento in memoria dell'html esterno, specificandoli nella chiamata alla procedura gethtml.

Valgono i limiti seguenti:

Descrizione	Massimo
Lunghezza record file origine	240 byte (228 byte per i dati origine)
Numero di record	32,764
Numero di variabili uniche (ogni variabile può comparire più volte nel testo)	16,221
Numero complessivo di variabili uniche o ripetute	32,767
Lunghezza del nome della variabile	30 caratteri
Lunghezza del valore della variabile	1,000 caratteri
Lunghezza delimitatori nome variabile	10 caratteri
Numero di sezioni	200
Lunghezza nome sezione	20 caratteri
Lunghezza delimitatori nome sezione	10 caratteri

2. Utilizzare uno stream file IFS

Invece di scrivere l'HTML esterno in un membro di un file fisico, lo si può memorizzare come stream file IFS. Questo approccio offre notevoli vantaggi:

il limite di 228 caratteri per riga scompare (gli altri limiti restano validi)
si possono generare gli script HTML con strumenti quali Front Page di Micfosoft, Websphere Studio di IBM, o altri.

Le prestazioni sono le stesse che si otterrebbero utilizzando file origine.

I directory IFS contenenti HTML esterno

non necessitano di alcuna direttiva HTML per essere accessi dai CGI
ma si raccomanda che siano diversi da quelli accessi dall'HTTP e contenenti pagine statiche ed immagini.

Esempi

Un HTML esterno che utilizza delimitatori standard
Un HTML esterno che utilizza delimitatori di sezione non-standard

"La stessa potenza e flessibilità di un Display File definito esternamente"