TPUrte - WASD RTE environment for DECTPU.

TPUrte is a TPU program, that accepts WASD RTE request, prepares CGI-like environment and runs the requested TPU script. When the request is serviced, it waits for the new request and runs the next TPU script, and so on, while httpd doesnt't abort the TPUrte process.

TPUrte gets CGI variables from httpd, places them into TPU string variables, finds the requested TPU script, executes it and closes the httpd transaction.

TPUrte is tested against DECTPU, EVE and LSEDIT.

1. Startup environment.

TPUrte requires SYS$INPUT to point to CGIPLUSIN: This should be done in the command file with the DCL command $ DEFINE SYS$INPUT CGIPLUSIN: So the startup file TPUrte.COM should look like

$ DEFINE/NOLOG SYS$INPUT CGIPLUSIN:
$ EDIT/TPU/NOINIT/NODISPLAY/NOJOURNAL/NOWORK/MODIFY/NOOUTPUT -
/NOSECTION/COMMAND=CGI-BIN:[000000]TPURTE.TPU $ DEASSIGN SYS$INPUT
$ EXIT

2. Scripting environment.

2.1. CGI variables.

All the request CGI variables are placed in the TPU area named WWW as string variables, indexed just like httpd names them - WWW_*. For example WWW{"WWW_QUERY_STRING TPU"} string variable represents the request query string.

2.2. Script output.

There are three ways the script can produce it's output.

2.3. Script input.

Normally TPUrte inputs PUT/POST data directly by using the READ_FILE(RTE_input) TPU procedure (RTE_input variable points to HTTP$INPUT:).

TPUrte can be instructed to prefetch PUT/POST data by setting WWW_RTE_FETCH CGI variable. Tis is done by WASD mapping rules:

set ... script=params=(RTE_FETCH="")

In such a case before starting the script TPUrte reads the PUT/POST body from HTTP$INPUT: and places it in the special buffer named RTE_fetch.

2.4. TPUrte special buffers.

There is a number of TPUrte special buffers available to user scripts.

The user script can create and use it's own buffers and other variables as needed. TPUrte will delete them after script is done.

2.5. RTE variables.

There is a number of special names for RTE to script interaction. See RTEset for detailed information.

2.6. Error reporting.

TPUrte has a built-in RTE_error_report procedure. To report an error the script should call it with the following parameters:

RTE_error_report(http_status,error_text,[module_name],[line_number]);

In addition TPUrte has an error handler, but any script should include it's own handler calling RTE_error_report.

4. TPUrte execution modes.

TPUrte can be used in source, compiled and mixed modes.

4.1. Source execution mode.

In source mode TPURTE.TPU is passed to TPU as a command file via /COMMAND qualifier. After accepting the request it loads the source TPU script, compiles and executes it. E.g.:

$ EDIT/TPU/NOINIT/NODISPLAY/NOJOURNAL/NOWORK/MODIFY/NOOUTPUT -
/NOSECTION/COMMAND=CGI-BIN:[000000]TPURTE.TPU

4.2. Mixed execution mode.

In mixed mode TPURTE.TPU is precompiled into TPURTE.TPU$SECTION and passed to TPU as a section file via /SECTION qualifier. The script is processed just as in source mode. E.g.:

$ EDIT/TPU/NOINIT/NODISPLAY/NOJOURNAL/NOWORK/MODIFY/NOOUTPUT -
/SECTION=CGI-BIN:[000000]TPURTE.TPU$SECTION/NOCOMMAND

4.3. Compiled execution mode.

In compiled mode TPURTE.TPU is precompiled with the scripts into TPURTE.TPU$SECTION and passed to TPU as a section file via /SECTION qualifier. After accepting the request it executes the precompiled script. E.g.:

$ EDIT/TPU/NOINIT/NODISPLAY/NOJOURNAL/NOWORK/MODIFY/NOOUTPUT -
/SECTION=CGI-BIN:[000000]TPURTE.TPU$SECTION/NOCOMMAND

5. Script code conventions.

After accepting the request and script <name> TPUrte acts as follows:

6. Compilation.

6.1. TPUrte is compiled using the TPU /OUTPUT qualifier. If this qualifier is present, TPUrte enters the compile mode, compiles itself and writes the compiled code into the file, pointed to bu the /OUTPUT= value (TPURTE.TPU$SECTION the default). The init stub file TPURTE$SECTION.TPU is compiled into the section too. E.g.:

$ EDIT/TPU/NOINIT/NODISPLAY/NOJOURNAL/NOWORK/MODIFY/NOSECTION -
/COMMAND=CGI-BIN:[000000]TPURTE.TPU/OUTPUT=TPURTE.TPU$SECTION

6.2. If input files are present on the command line, they are compiled and added into the section. So the scripts can be inserted for compiled mode. There may be different TPUrte section files with different precompiled script sets. E.g.:

$ EDIT/TPU/NOINIT/NODISPLAY/NOJOURNAL/NOWORK/MODIFY/NOSECTION -
/COMMAND=CGI-BIN:[000000]TPURTE.TPU/OUTPUT=TPURTE.TPU$SECTION CGI_SYMBOLS.TPU

7. Other environments.

TPUrte can execute scripts in extended environments - EVE or LSEDIT.

$ EDIT/TPU/NOINIT/NODISPLAY/NOJOURNAL/NOWORK/MODIFY/NOOUTPUT -
/SECTION/COMMAND=CGI-BIN:[000000]TPURTE.TPU

or

$ LSEDIT/NOINIT/NODISPLAY/NOJOURNAL/NOWORK/MODIFY/NOOUTPUT -
/SECTION/COMMAND=CGI-BIN:[000000]TPURTE.TPU
$ EDIT/TPU/NOINIT/NODISPLAY/NOJOURNAL/NOWORK/MODIFY/SECTION -
/COMMAND=CGI-BIN:[000000]TPURTE.TPU/OUTPUT=EVERTE.TPU$SECTION

or

$ LSEDIT/NOINIT/NODISPLAY/NOJOURNAL/NOWORK/MODIFY/SECTION -
/COMMAND=CGI-BIN:[000000]TPURTE.TPU/OUTPUT=LSERTE.TPU$SECTION

In both environments the script files can be added as input parameters.

8. CGI+ scripting.

In any execution mode TPUrte environment can be used for CGI+ scripting. CGI+ environment differs from RTE in that it has no WWW_SCRIPT_FILENAME CGI variable. There are two ways to execute the unnamed script.

9. Support DCL procedure.

The support DCL procedure TPURTE.COM starts TPUrte in required mode and prepares it's environment. It uses logicals and command line parameters to determine the needed action.

10. Mapping rules.

exec /tpurte/* (@CGI-BIN:[000000]TPURTE.COM)/cgi-bin/*
exec /tpulib/* (@CGI-BIN:[000000]TPURTE.COM)/* script=nofind

Evidently for compiled mode TPURTE.COM should start only precompiled with scripts TPUrte using /SECTION qualifier. Both exec rules can be present pointing to the same TPURTE.COM as the precompiled version can start non-compiled scripts in mixed mode.

11. Typical installation.

exec /tpulib/* (@CGI-BIN:[000000]TPURTE.COM)/* script=nofind
exec /tpurte/* (@CGI-BIN:[000000]TPURTE.COM)/cgi-bin/*

12. Typical use.