Updated November 2025
xcall CGIUTL, CGIOP_MRGOUT, file, status {varsub1, varsub2 ..., varsubN}
Opcode 3, CGIOP_MRGOUT, copies a disk file (typically a web page template) to stdout, thus completing the CGI operation. (The web server launches the CGI application, passes it input via stdin, then waits for the output to come back via stdout.) To simplify the process of generating a custom web page, you may specify up to 256 variable substitutions, allowing you to use use a common template which is thereby customized.
Parameters
file (String) [in]
DevPPN or native file specification for input file. In the case of ambiguity, AMOS-style will be assumed; you can force it to assume native-style by prepending a "./" to the name (e.g. "./NativeFile.html")/ There is no particular limit to the size of the input file, but each line must be less than 32K (prior to any variable substitutions).
varsubN (String) [in]
One or more variable substitution definitions of the form <name>=<value> (e.g. $CLIENTID=12345). The maximum number of substitution pairs is limited only by the A-Shell limit on the number of XCALL parameters. You can overcome the limit by combining multiple substitution pairs in a single varsub parameter by separating them with a plus sign (+), for example "$CLIENTID=12345+$NAME=Bits R US".
You can combine multiple substitution definitions in one parameter by separating them with a plus sign; for example, $CLIENTID=12345+$NAME=Bits 4 Us. To include the literal character '=' or '+' in a substitution, precede it with a backslash, e.g. $FORMULA=1\+1\=2.
The variable substitution names are case sensitive, but do not have to be terminated or delimited in any special way. To avoid inadvertent matches, you might want to prefix and/or suffix them with some special character, like $.
status (Signed Num) [out]
Will be set to 0 to indicate that a page was successfully generated, although it may still fail to meet the necessary syntactic requirements for a valid webpage. –1 indicates that file could not be opened.
Comments
This operation can be difficult to debug, since if the resulting page is not valid, the web server will not display any of it and it will not be available for inspection. A first debugging step would be to attempt to launch the file in the browser directly, which should work (displaying the variable names instead of the replacement values) provided that variables are not used for critical elements of the HTML page structure. A second debugging step would be to add TRACE=XCALL, or otherwise arrange for the command SET TRACE XCALL ON to be executed before the program runs. This will not only log the subroutine parameters (for all subroutines) to the ashlog.log file, but will also create a file cgiutl.log containing a copy of the merged file that was output to stdout.
A common mistake in creating a template web page is to forget to include the "content-type" header line, which it not required in static web pages but is required in pages generated through CGI. As a minimum, the template and/or resulting page should contain the following elements (note the mandatory blank line following the "content-type" header:
content-type: text/html
<HTML>
<HEAD>
<TITLE>This is the page title</TITLE>
</HEAD>
<BODY>
bla bla bla
bla bla bla
</BODY>
</HTML>
See Also
| • | See this post on the A-Shell Forum if you are trying to use a template file containing an embedded PHP block. |
