Difference between revisions of "M2Web Tutorials"

From VistApedia
Jump to: navigation, search
(Added glossary link to Configuration~)
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
[[M2Web Overview|Back to M2Web Overview]]
 
[[M2Web Overview|Back to M2Web Overview]]
  
(Below is edited/compiled from emails with Jim Self)
+
(Below is edited/compiled from emails with Jim Self, head of project M2Web)
 +
 
 +
 
 +
Q: Can I have a quick overview of how M2Web works?
 +
 
 +
A: OK.  Here is an overview.
 +
  Kevin T wrote:
 +
  1. User enters URL in a web browser pointed at a M2Web server
 +
  2. On the server, Apache web server launches a CGI program
 +
  3. This CGI program is just a simple bash script that sets up some
 +
    environmental variables and then launches GT.M with a command line
 +
    instruction to launch ^htCGI, like this
 +
            $gtm_dist/mumps -r ^htCGI
 +
  4. ^htCGI retrieves some environmental variables that Apache had set up
 +
    for communication re the URL.
 +
  5. ^htCGI then launches other M code.
 +
  6. All output to the "console" (i.e. standard WRITE commands from M)
 +
    get sent back to Apache as an IO stream.  The only requirement is that
 +
    Apache get back a line of text at the very beginning that states
 +
    something like: "Content-type text/html".  If the text happens to
 +
    contain HTML markup, then the display is pretty, otherwise it is just
 +
    text.
 +
 
 +
If I have this wrong, someone feel free to jump in and correct me.
 +
--> Jim Self responded to the Above:
 +
 
 +
That is a good start on the basics, but some parts of item 6) are not
 +
quite right.
 +
 
 +
CGI simplifies HTTP and the htCGI* routines in M2Web take care of the
 +
details of CGI so that [[application~|Application]] routines can focus exclusively on
 +
content for normal HTML responses and so that error conditions,
 +
persistent sessions, and non-HTML responses can be handled consistently
 +
and very simply.
 +
 
 +
The essence of HTTP is a brief stateless connection with a single cycle
 +
of request and response. Both request and response contain many
 +
name:value pairs called headers and can be of virtually unlimited size
 +
and complexity.  For bare minimum CGI only one header (Content-type) is
 +
required, others will be supplied by the general server (i.e. Apache).
 +
 
 +
The Content-type header specifies the mime-type of returned content so
 +
that virtually any type of content can be returned.
 +
 
 +
M2Web typically returns "Set-cookie" headers to maintain user login sessions
 +
 
 +
M2Web [[application~|Application]] handlers can return content without using the WRITE
 +
command.
 +
 
 +
The simplest way is to set content into the local variable htReturn.
 +
Here is an example of a complete response:
 +
 
 +
hello ;example M2Web CGI handler
 +
    Set htReturn="Hello World"
 +
    Quit
 +
 
 +
To produce the same response with WRITE:
 +
 
 +
hello2 ;another example M2Web CGI handler
 +
    Do startOut^htCGI ;--WARNING - This command must precede any WRITE
 +
commands--;
 +
    Write "Hello World",!
 +
    Quit
 +
 
 +
The very first part of all HTTP responses is a status code. The number
 +
200 indicates a normal response. CGI [[application~|Application]]s indicate error
 +
conditions by sending a "Status" header. This is handled in M2Web by
 +
setting the variable htCode to a standard error code number or
 +
*preferrably* by calling one of the error condition labels in ^htCGI,
 +
such as notFnd^htCGI(errorMessage) (Not Found) or
 +
badRqst^htCGI(errorMessage) (Bad Request) etc.
  
  
 
Q: How do we go from user request, via URL, to Apache serving web pages on the server, into GT.M Mumps code, and then back out to Apache and then to the user's web browser?
 
Q: How do we go from user request, via URL, to Apache serving web pages on the server, into GT.M Mumps code, and then back out to Apache and then to the user's web browser?
  
A: Web requests handled by M2Web start MUMPS execution with the
+
A: Every URL addressed to the server host get processed by a script file
routine ^htCGI ( http://vista.vmth.ucdavis.edu/rtn/htCGI ). This routine and helpers handle the basic HTTP/CGI request/response cycle.  
+
(m2web.cgi) that calls MUMPS (GT.M) to run the routine ^htCGI ( http://vista.vmth.ucdavis.edu/rtn/htCGI ). This is described in a setup document at http://vista.vmth.ucdavis.edu/home/index/48.html.  ^htCGI uses helpers to handle the basic HTTP/CGI request/response cycle.  
  
 
The HTTP headers are processed into local array
 
The HTTP headers are processed into local array
Line 16: Line 86:
 
concise reference to the context and character of each given request.  
 
concise reference to the context and character of each given request.  
  
When an application handler starts up, it will find the inputs in local
+
When an [[application~|Application]] handler starts up, it will find the inputs in local
array htInput. From example below:
+
array htInput. For example
 +
 
 +
http://vista.vmth.ucdavis.edu/echo?dbfile=19&index=Name&format=OptnNo;Name;MenuText
 +
 
 +
will lead to:  
  
 
   htInput("dbfile")=19
 
   htInput("dbfile")=19
Line 23: Line 97:
 
   htInput("format")="OptNo;Name;MenuText"
 
   htInput("format")="OptNo;Name;MenuText"
  
Change "query" to "echo" in the URL above to see the two arrays
+
One can try to change "query" to "echo" in the URL above to see the two arrays
  
http://vista.vmth.ucdavis.edu/echo?dbfile=19&index=Name&format=OptnNo;Name;MenuText
+
This display is provided by routine ^htEcho ( http://vista.vmth.ucdavis.edu/rtn/htEcho ), a simple [[application~|Application]]
 
 
This display is provided by routine ^htEcho ( http://vista.vmth.ucdavis.edu/rtn/htEcho ), a simple application
 
 
handler that illustrates a basic HTML and CGI response. It can be a
 
handler that illustrates a basic HTML and CGI response. It can be a
useful tool for basic diagnostics when developing a new application.
+
useful tool for basic diagnostics when developing a new [[application~|Application]].
  
 +
=================================
 +
=================================
  
 
Q: How does one specify the function that ^htCGI is to use for handling a request?  
 
Q: How does one specify the function that ^htCGI is to use for handling a request?  
  
A: every URL addressed to the server host get processed by a script file
+
A: When ^htCGI is called, information from the URL is passed in. So, for example, with the URLs:
(m2web.cgi) that calls MUMPS (GT.M) to run the routine ^htCGI. This is
 
described in a setup document at
 
http://vista.vmth.ucdavis.edu/home/index/48.html
 
So, for example, with the URLs:
 
  
 
  http://vista.vmth.ucdavis.edu/rtn/...
 
  http://vista.vmth.ucdavis.edu/rtn/...
Line 53: Line 123:
 
   'query'
 
   'query'
  
The corresponding handlers are the MUMPS routines ^htRtn, ^htGo,
+
And these values are loaded into htRsrc.  The corresponding handlers are the MUMPS routines ^htRtn, ^htGo, ^htEcho, and ^view2ht.
^htEcho, ^view2ht.
 
  
In the code for ^htCGI, the following line can be seen:
+
In ^htCGI, the following code can be seen:
  
Set htHandler=^htCGI("resource",htRsrc,htMethod),htAuth=$Get(^(htMethod,"ACCESS"))
+
set htHandler=^htCGI("resource",htRsrc,htMethod)
 +
set htAuth=$Get(^(htMethod,"ACCESS"))
  
 
And this is where the resource from the URL (e.g. 'rtn') is mapped to '^htRtn'.  If one were to add a new resource, the programmer would need to "register" itself with M2Web such that there is an entry in ^htCGI("resource",htRsrc,htMethod))?  And if everything is OK, then htHandler will point to the handler for the given request.  It will contain M code to launch the handler, like this:
 
And this is where the resource from the URL (e.g. 'rtn') is mapped to '^htRtn'.  If one were to add a new resource, the programmer would need to "register" itself with M2Web such that there is an entry in ^htCGI("resource",htRsrc,htMethod))?  And if everything is OK, then htHandler will point to the handler for the given request.  It will contain M code to launch the handler, like this:
Line 64: Line 134:
 
do @htHandler
 
do @htHandler
  
There is a configuration utility (/resedit) that you can use to review and enter/edit resource definitions. See http://vista.vmth.ucdavis.edu/resedit
+
There is a [[configuration~|Configuration]] utility (/resedit) that you can use to review and enter/edit resource definitions. See http://vista.vmth.ucdavis.edu/resedit
 
They can also be viewed and edited directly from /go.
 
They can also be viewed and edited directly from /go.
 +
 +
=================================
 +
=================================
  
 
Q:  Can any user access any resource?
 
Q:  Can any user access any resource?
  
A:  Basic access restrictions are controlled by the "ACCESS" attribute of a
+
A:  Basic access restrictions are controlled by the "ACCESS" [[attribute~|Attribute]] of a
 
given method for a given resource which is loaded into local variable
 
given method for a given resource which is loaded into local variable
 
htAuth. Login is required unless htAuth="" and htNoSec=0.  
 
htAuth. Login is required unless htAuth="" and htNoSec=0.  
  
 +
=================================
 +
=================================
  
 
Q: What other functions does M2Web provide?
 
Q: What other functions does M2Web provide?
Line 78: Line 153:
 
A: I have a different set of utilities in M2Web (see
 
A: I have a different set of utilities in M2Web (see
 
http://vista.vmth.ucdavis.edu/rtn/view*) for traversing and processing
 
http://vista.vmth.ucdavis.edu/rtn/view*) for traversing and processing
records defined by Fileman (or otherwise). These make use of ^iterator
+
[[record~|Record]]s defined by Fileman (or otherwise). These make use of ^iterator
 
and variable names derived from Fileman field labels to make extremely
 
and variable names derived from Fileman field labels to make extremely
 
concise yet readable processing specifications. Using these utilities
 
concise yet readable processing specifications. Using these utilities
makes applications routines, smaller, simpler, more readable, and often
+
makes [[application~|Application]]s routines, smaller, simpler, more readable, and often
 
more general also.
 
more general also.
  
Line 94: Line 169:
 
  * "filter" Optional parameters -- further refine the iteration.
 
  * "filter" Optional parameters -- further refine the iteration.
 
  * "format=OptnNo;Name;MenuText" is optional.  
 
  * "format=OptnNo;Name;MenuText" is optional.  
     It specifies 3 output fields per data record.  
+
     It specifies 3 output fields per data [[record~|Record]].  
 
     Default output is an HTML table but many other possibilities  
 
     Default output is an HTML table but many other possibilities  
 
       are readily available.
 
       are readily available.
 
...
 

Latest revision as of 23:55, 17 October 2012

Back to M2Web Overview

(Below is edited/compiled from emails with Jim Self, head of project M2Web)


Q: Can I have a quick overview of how M2Web works?

A: OK. Here is an overview.

 Kevin T wrote:
 1. User enters URL in a web browser pointed at a M2Web server
 2. On the server, Apache web server launches a CGI program
 3. This CGI program is just a simple bash script that sets up some
    environmental variables and then launches GT.M with a command line
    instruction to launch ^htCGI, like this
           $gtm_dist/mumps -r ^htCGI
 4. ^htCGI retrieves some environmental variables that Apache had set up
    for communication re the URL.
 5. ^htCGI then launches other M code.
 6. All output to the "console" (i.e. standard WRITE commands from M)
    get sent back to Apache as an IO stream.  The only requirement is that
    Apache get back a line of text at the very beginning that states
    something like: "Content-type text/html".  If the text happens to
    contain HTML markup, then the display is pretty, otherwise it is just
    text.

If I have this wrong, someone feel free to jump in and correct me. --> Jim Self responded to the Above:

That is a good start on the basics, but some parts of item 6) are not quite right.

CGI simplifies HTTP and the htCGI* routines in M2Web take care of the details of CGI so that Application routines can focus exclusively on content for normal HTML responses and so that error conditions, persistent sessions, and non-HTML responses can be handled consistently and very simply.

The essence of HTTP is a brief stateless connection with a single cycle of request and response. Both request and response contain many name:value pairs called headers and can be of virtually unlimited size and complexity. For bare minimum CGI only one header (Content-type) is required, others will be supplied by the general server (i.e. Apache).

The Content-type header specifies the mime-type of returned content so that virtually any type of content can be returned.

M2Web typically returns "Set-cookie" headers to maintain user login sessions

M2Web Application handlers can return content without using the WRITE command.

The simplest way is to set content into the local variable htReturn. Here is an example of a complete response:

hello ;example M2Web CGI handler

   Set htReturn="Hello World"
   Quit

To produce the same response with WRITE:

hello2 ;another example M2Web CGI handler

   Do startOut^htCGI ;--WARNING - This command must precede any WRITE

commands--;

   Write "Hello World",!
   Quit

The very first part of all HTTP responses is a status code. The number 200 indicates a normal response. CGI Applications indicate error conditions by sending a "Status" header. This is handled in M2Web by setting the variable htCode to a standard error code number or

  • preferrably* by calling one of the error condition labels in ^htCGI,

such as notFnd^htCGI(errorMessage) (Not Found) or badRqst^htCGI(errorMessage) (Bad Request) etc.


Q: How do we go from user request, via URL, to Apache serving web pages on the server, into GT.M Mumps code, and then back out to Apache and then to the user's web browser?

A: Every URL addressed to the server host get processed by a script file (m2web.cgi) that calls MUMPS (GT.M) to run the routine ^htCGI ( http://vista.vmth.ucdavis.edu/rtn/htCGI ). This is described in a setup document at http://vista.vmth.ucdavis.edu/home/index/48.html. ^htCGI uses helpers to handle the basic HTTP/CGI request/response cycle.

The HTTP headers are processed into local array htCGI(headerName)=value by routine ^htCGI1 ( http://vista.vmth.ucdavis.edu/rtn/htCGI1 ) and named inputs are processed into local array htInput(inputName)=value by routine ^htCGI2.

Additional ht* local variables are defined in ^htCGI1 that provide concise reference to the context and character of each given request.

When an Application handler starts up, it will find the inputs in local array htInput. For example

http://vista.vmth.ucdavis.edu/echo?dbfile=19&index=Name&format=OptnNo;Name;MenuText

will lead to:

 htInput("dbfile")=19
 htInput("index")="Name"
 htInput("format")="OptNo;Name;MenuText"

One can try to change "query" to "echo" in the URL above to see the two arrays

This display is provided by routine ^htEcho ( http://vista.vmth.ucdavis.edu/rtn/htEcho ), a simple Application handler that illustrates a basic HTML and CGI response. It can be a useful tool for basic diagnostics when developing a new Application.

=================================
=================================

Q: How does one specify the function that ^htCGI is to use for handling a request?

A: When ^htCGI is called, information from the URL is passed in. So, for example, with the URLs:

http://vista.vmth.ucdavis.edu/rtn/...
http://vista.vmth.ucdavis.edu/go
http://vista.vmth.ucdavis.edu/echo?...
http://vista.vmth.ucdavis.edu/query/?...

The key handlers/functions/"resources" (recall that URL stands for Universal Resource Locator) to use are:

 'rtn'
 'go'
 'echo'
 'query'

And these values are loaded into htRsrc. The corresponding handlers are the MUMPS routines ^htRtn, ^htGo, ^htEcho, and ^view2ht.

In ^htCGI, the following code can be seen:

set htHandler=^htCGI("resource",htRsrc,htMethod)
set htAuth=$Get(^(htMethod,"ACCESS"))

And this is where the resource from the URL (e.g. 'rtn') is mapped to '^htRtn'. If one were to add a new resource, the programmer would need to "register" itself with M2Web such that there is an entry in ^htCGI("resource",htRsrc,htMethod))? And if everything is OK, then htHandler will point to the handler for the given request. It will contain M code to launch the handler, like this:

do @htHandler

There is a Configuration utility (/resedit) that you can use to review and enter/edit resource definitions. See http://vista.vmth.ucdavis.edu/resedit They can also be viewed and edited directly from /go.

=================================
=================================

Q: Can any user access any resource?

A: Basic access restrictions are controlled by the "ACCESS" Attribute of a given method for a given resource which is loaded into local variable htAuth. Login is required unless htAuth="" and htNoSec=0.

=================================
=================================

Q: What other functions does M2Web provide?

A: I have a different set of utilities in M2Web (see http://vista.vmth.ucdavis.edu/rtn/view*) for traversing and processing Records defined by Fileman (or otherwise). These make use of ^iterator and variable names derived from Fileman field labels to make extremely concise yet readable processing specifications. Using these utilities makes Applications routines, smaller, simpler, more readable, and often more general also.

- example: http://vista.vmth.ucdavis.edu/query/?dbfile=19&index=Name&format=OptnNo;Name;MenuText

This

* index=Name specifies iteration over the "B" index of file 19 (OPTION). 
* "OptnNo" is the variable name for the (IEN) of this file
    so "index=OptnNo" would specifiy iteration over the IEN. 
* "find" Optional parameter -- further refine the iteration.
* "filter" Optional parameters -- further refine the iteration.
* "format=OptnNo;Name;MenuText" is optional. 
   It specifies 3 output fields per data Record. 
   Default output is an HTML table but many other possibilities 
     are readily available.