This page shows how to
We recommend you use
- command cgidev2/setcgilib
to setup the development and execution environments
in your source library and object (production) library
- command cgidev2/crtcgisrc
to create a sample source for a new CGI program.
You can compile an run such program.
If you do so, you'll find out that the variables are already defined
by copying in other source members:
/copy mysrclib/qrpglesrc,hspecs
/copy mysrclib/qrpglesrc,hspecsbnd
... etc. ...
/copy mysrclib/qrpglesrc,prototypeb
/copy mysrclib/qrpglesrc,usec
/copy mysrclib/qrpglesrc,variables(1, or 2, or 3)
... etc. ... |
|
|
2. Read skeleton html member into memory
Use subprocedure
- getHtml
to load into memory a single
externally defined html source member
- getHtmlifs
to load into memory a single
externally defined html IFS (stream) file
- getHtmlifsMult
to load into memory in one shot multiple
externally defined html IFS (stream) files
Examples for default section and variables delimiters
- section name start delimiter:
/$
- variable name start delimiter:
/%
- variable name 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') |
|
|
See the example in CGI
TEMPLATE4.
Note that the directory to be specified as a parameter of
the gethtmlifs procedure
is the real directory path, not
the alias mentioned in a HTTP pass directive.
The recommendation is -in any case- not to use for the
IFS html code directories accessed also by the
HTTP server.
3) getHtmlifsMult
This subprocedures allows to load into memory
multiple externally defined html files.
All the sections and records
in all the files are read into dynamic storage as though
they resided in a single file. If a section name appears
more than once, only the first occurrence is used.
This feature allows to maintain as separate
HTML files frequently used pieces of HTML code,
such as headers, footers, navigation bars, etc..
In several cases, breaking html code into separate
modules may greatly reduce both development
and maintenance times.
|
|
* 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')
|
|
See the example in CGI
TEMPLATE5.
Note 1.
Subprocedures getHtmlifs and getHtmlifsMult
can also load HTML source members as part of the
/QSYS.LIB/... directory.
See the following example:
|
|
* Read externally defined output html files
C eval IfsMultIndicators = gethtmlifsmult(
C '/CgiDevExtHtml/StdTop.Html +
C /QSYS.LIB/MYLIB.LIB/HTMLSRC.FILE/X.MBR')
|
|
Note 2.
When using getHtmlifs or getHtmlifsMult
subprocedure, make sure that the IFS files containing
the external HTML code
can be read from the HTTP server user profile QTMHHTP1
(the one adopted when running CGI).
This can be done in one of the following ways
(in the examples below, we assume that QPGMR owns the files,
but this is not relevant at all):
|
Data |
--Object Authorities-- |
|
User |
Authority |
Exist |
Mgt |
Alter |
Ref |
|
*PUBLIC |
*RX |
|
QPGMR |
*RWX |
X |
X |
X |
X
|
|
|
or
|
Data |
--Object Authorities-- |
|
User |
Authority |
Exist |
Mgt |
Alter |
Ref |
|
*PUBLIC |
*EXCLUDE |
|
QPGMR |
*RWX |
X |
X |
X |
X |
|
QTMHHTP1 |
*RX |
|
|
Examples for user-defined delimiters
(see also this page).
First example:
- section name start delimiter:
"<!-- Sec_"
- section name end delimiter (optional):
" -->"
- variable name start delimiter:
"<var400>"
- variable name end delimiter:
"</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>') |
|
|
Second example:
- section name start delimiter:
"<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. Assign values to html variables
This must be done using subprocedure
updHtmlVar.
This subprocedure assigns a value to
all the instances
of a given html variable name.
Note 3. The value to be assigned must be a character
string (numeric fields must be converted or edited to
character strings, see examples number 4 and 5).
Inputs
- variable name
- variable value
- action (optional)
- '1' = replace this variable if it exists, otherwise add it (default)
- '0' = clear arrays and write this one as the first
- trim instructions (optional)
- %trim - trim left and right (default)
- %triml - trim left only
- %trimr - trim right only
- %trim0 - don't trim
|
Examples:
- Clear all html variables and
assign to html variable
custname
the value contained in character field
CusNam:
C callp updHTMLvar('custname':CusNam:'0') |
|
|
- Assign to html variable
custaddr
the value contained in character field
CusAdr:
C callp updHTMLvar('custaddr':CusAdr) |
|
|
- Assign to html variable
custaddr
the value contained in character field
CusAdr without trimmimg it:
C callp updHTMLvar('custaddr':CusAdr:'1':'%trim0') |
|
|
- Assign to html variable
ordertotal
the value contained in numeric field (9 2)
TotThisOrd
using an edit code:
C callp updHTMLvar('ordertotal':
C %editc(TotThisOrd:'J')) |
|
|
About edit codes
- Assign to html variable
ordertotal
the value contained in numeric field (9 2)
TotThisOrd
using an edit word:
C callp updHTMLvar('ordertotal':
C %editw(TotThisOrd:' , , 0. ')) |
|
|
See this living
example.
For vary large output variables (max 16 Mb) you may use subprocedure
updHtmlVar2.
In this subprocedure, instead of passing the name or the value
of the substituting variable, you will pass a pointer to it and its length.
Inputs
- variable name
- pointer to the substituting string
- length of the substituting string
- action (optional)
- '1' = replace this variable if it exists, otherwise add it (default)
- '0' = clear arrays and write this one as the first
- trim instructions (optional)
- %trim - trim left and right (default)
- %triml - trim left only
- %trimr - trim right only
- %trim0 - don't trim
|
Example:
|
|
D varPointer s *
D varLength s 10i 0
C callp updHtmlVar2('longdata':
C varPointer:varLength) |
|
|
4. Write html sections and send the output buffer
This must be done using subprocedure
wrtsection.
One can write one or multiple sections in a single call.
Important.
Once all sections have been written,
do not forget to
send the output buffer to the client.
This must be done by writing a pseudo section named
*fini.
Example:
* Write a single section
C callp wrtsection('start')
* Write two sections
C callp wrtsection('part1 part2')
* Send the output html to the remote browser
C callp wrtsection('*fini') |
|
|
Note 4. Section names are not case sensitive.
A section name is a 50 char max alfanumeric string. Only english letters are supported.
Note 5. Subprocedure wrtSection supports two optional parameters:
- NoNewLine indicator.
Set it to *on to tell wrtsection
NOT to insert a newline character x'15' at the end of each HTML output line.
This may be useful when binary data are being sent to the browser.
- NoDataString value.
What to do when a substitution variable is encountered and no
value has been set up with UpdHtmlVar.
If not specified, output variables left without substitutions display
the default "**Missing Data**".
Examples:
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. Special output procedures
Subprocedure
wrtNoSection
writes data for the browser without using substitution variables
or sections.
This subprocedure can be used when a large block of data is to
written. This is more likely to happen when writing non-textual
data such as images.
The following example shows how to read an external IFS file
(an HTML page, an image, or what you need) and how to insert
it into the CGI output buffer:
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) |
|
|
Subprocedure
clrHtmlBuffer
clears any HTML output that has been buffered
but has neither been sent to the browser
nor written into a stream file.
This is useful when program logic dictates you need to output
something other than what has already been buffered.
Subprocedure
getHtmlBytesBuffered
Returns the number of bytes in the output HTML buffer.
This number is incremented each time output is written with
WrtSection or WrtNoSection.
It is reset to 0 when either WrtSection('*fini') or
WrtHtmlToStmf is run.
If this number is allowed to grow to more than 16 MB, the CGI
program will fail.
Could be useful to stop creating an output page when its size
exceeds a reasonable limit.
D buffsize s 10i 0
C eval buffsize = getHtmlBytesBuffered |
|
|
Subprocedure
getHtmlBufferP
Returns the pointer to the output HTML buffer and the number of bytes used in the output HTML buffer.
This is expecially useful for debugging.
D OutBuffer s 32767 based(OutbufferP)
D OutBufferInfo ds
D OutBufferP *
D OutBufferLen 10u 0
C eval OutBufferInfo=callp(GetHtmlBufferP) |
|
|
