The run time interpreter nph-srep¶
Contents
The run time interpreter nph-srep is used to run Sculptor template files (.sch, .scj or .scx suffix) and Sculptor report programs with HTML output (.q suffix). The nph- prefix stands for non-parsed header. This is a standard cgi convention that tells the web server not to strip the HTML header from the outgoing text.
The nph-srep interpreter is placed in the web server’s cgi-bin directory, and can be specified as the program to be run in a URL (a link on a web page). The Sculptor HTML file and/or Sculptor report program to be run can be specified in the URL itself, or in hidden fields on the web page. When a Sculptor HTML file is specified, an associated Sculptor report program can be specified as well.
nph-srep processes a template HTML file and outputs a finished HTML page. It can run in one of two modes, either to create a static HTML page for later uploading to a web server, or as a cgi-bin program, that runs on a web server, to create a dynamic, up to date, HTML page in immediate response to an Internet request for that page. A special Sculptor tag in the template page or a web parameter is used to attach a Sculptor program to the page. Further special tags can call functions in the Sculptor program, reference values in Sculptor files and temporary fields, and enable conditional logic and loops to be placed in the page. The loop tags (repeat, while, for) are perfect for creating web page tables that are populated with data from a Sculptor database. The Sculptor tags conform to HTML rules, so the template HTML can be designed in a proprietary HTML editor such as DreamWeaver or FrontPage.
Sculptor report programs¶
A Sculptor report program run by nph-srep or associated with a Sculptor HTML file is, like any other report, compiled from a source file with a .r extension by the compiler scc into an executable program with a .q extension. All the commands, functions and declarations available in the standard Sculptor report language can be used. However, the output of the program must be standard HTML or other code that creates the required web page or web page section in a form that the client’s browser can interpret, using Sculptor’s print and put statements.
A report program run directly by nph-srep creates a web page.
A report program associated with a Sculptor HTML file directs its output to the web page created by that HTML file at the point where it is called by the <SCRUNREPORT> tag. The program may contain any number of reports, each defined in a !report section. The <SCRUNREPORT> tag includes the report_id of the report to be run. See Special tags for HTML files.
Sculptor template files¶
A Sculptor template file is an HTML web page (.sch), a JSON file (.scj) or a XML file (.scx), created using any tool. In addition to standard HTML/JSON/XML code, it can contain special tags that are recognised and processed by nph-srep. These tags allow an associated Sculptor report program to place output into the web page, thus creating Sculptor Dynamic Server pages, the Sculptor equivalent of Microsoft’s Active Server pages and Java Server pages. See Special tags for HTML files.
Outputting header information¶
The Sculptor system variable sys.HTMLHeader is used to specify whether or not nph-srep should output standard, cgi header information.
Special variables¶
The following variables are available to define the page or program to be run:
SCPROG defines a Sculptor report program (.q suffix)
SCHPAGE defines a Sculptor template file (.sch, .scj or .scx suffix)
Specifying the page and/or program in the URL¶
Two forms can be used in each case, depending on whether a variable is included. The forms have identical functionality.
Run a specified Sculptor report program. A Sculptor HTML file is not used.
href=“cgi-bin/nph-srep?newprice” |
|
or |
href=“cgi-bin/nph-srep?scprog=newprice” |
Output a specified Sculptor templae file. No associated Sculptor report program is defined in the URL, but one may be specified with an <SCPROG> tag in the template file file. See Special tags.
href=“cgi-bin/nph-srep?index.sch” |
|
or |
href=“cgi-bin/nph-srep?schpage=index” |
Output a specified Sculptor template file in conjunction with a specified Sculptor report program.
href=“cgi-bin/nph-srep?ordlist.sch&scprog=ordrep” |
|
or |
href=“cgi-bin/nph-srep?schpage=ordlist&scprog=ordrep” |
Note: nph-srep is prepared to be used with popular web server extension mappings. So that a .q (or template file extension as .sch) can be directly used on the URL as “http://domain/file.sch”. See the Sculptor tutorials guides to setup is.
Specifying the page and/or program in a tag¶
Each of the options listed above can also be specified using hidden fields in the page, as shown in the following example:
<FORM ACTION=“cgi-bin/nph-srep” METHOD=POST>
<INPUT TYPE=hidden NAME=SCPROG VALUE=prices>
<INPUT TYPE=hidden NAME=SCHPAGE VALUE=prlist>
…
</FORM>
Processing¶
Initialisation
nph-srep performs the following tasks when it starts, and before any user code is executed:
1 |
Reads all parameters and values passed by the browser. |
2 |
Reads all cookies that this web server has stored on the user’s machine. |
3 |
Reads the session information. |
When these tasks have been completed the user code is executed.
Startup code
The startup code of the report program, which has access to all the cookies, parameters and session information, should make any checks required.
If no .sch, .scj or .scx file is attached, the startup code must use the run report command to execute the report required to generate the web page.
If a .sch, .scj or .scx file is attached, nph-srep starts to output this file as soon as it reaches an end command in the startup code, executing any tags it finds. See Special tags for template files.
Arguments¶
The arguments of a call to nph-srep may be accessed within the program by means of the subscripted Sculptor system variable sys.Arg. They are as follows:
sys.Arg[1] |
“nph-srep” |
sys.Arg[2] |
the name of the .q or template file. If no extension is specified, .q is assumed. |
sys.Arg[3] |
if present, this argument is the printer parameter file. If none is specified, the default is nullp. As usual, a printer parameter file specified as an argument can be over-ridden in the run report command. |
sys.Arg[4] , … |
any other parameters that are not in a NAME=value pair. |
Setting up nph-srep in a web server¶
Even though the nph-srep program can be executed directly from the command line, from another Sculptor program using exec or execute() or from other programs. The intended way to execute nph-srep is through a web browser.
In that sense nph-srep has been prepared to work with apache, nginx and IIS. See the tutorials on the Sculptor website download page to learn how to configure the web servers with nph-srep.
The nph-srep environment variables provides more information.
RELATED TOPICS |