Serving CGI Programs

Summary of Steps

1. Decide which environment you want to run your CGI program in, and select a filetype that matches the environment.
2. Write the CGI program.
3. Move the CGI program to the server root domain. If necessary, add an entry to a DIRMAP file to identify it.

Steps in Detail

1. Decide which environment you want to run your CGI program in, and select a filetype that matches the environment.

   A CGI program runs in a particular environment. VM:Webgateway supports the following environments:

   Environment	The CGI program runs ...
   SVMEXEC	as an EXEC on the VM:Webgateway SVM
   WORKEREXEC	as an EXEC on a VM:Webgateway worker machine
   SVMWEBSHARE	in Webshare compatibility mode on the VM:Webgateway SVM
   WORKERWEBSHARE	in Webshare compatibility mode on a VM:Webgateway worker machine

   ---

   Note: You cannot serve CGI programs that run in Webshare compatibility mode from a BFS directory.

   ---

   You must indicate the environment that you want VM:Webgateway to use for a CGI program. In addition, you must indicate whether you want VM:Webgateway to pass the HTTP Authorization header to your CGI program. A VM:Webgateway system administrator configures filetype definitions to map the characteristics of files (in this case, the CGI environment and whether the HTTP Authorization header should be passed) to filetypes.

   When serving files from a minidisk, SFS directory, or using CMS search order, use a configured filetype for the CMS filetype of the CGI program. When serving files from a BFS directory, use a configured filetype for the BFS extension of the CGI program.

   ---

   Note: If you want to use a filetype that is not configured, identify the file on a FILE directory control record and use the content_filetype parameter to indicate the file's characteristics.

   ---

   To view a list of filetypes that have been defined for CGI programs, enter the following command from a VM userid:

   query filetype * environment *

2. Write the CGI program.

   How you code the CGI program depends on the environment in which it will run:

   SVMEXEC

   Write the CGI program using REXX and the CGI program commands. Because SVMEXEC CGI programs run on the VM:Webgateway SVM, the VM:Webgateway SVM must have the authorization to obtain any data that your CGI program requests.

   Avoid including long-running tasks in your SVMEXEC CGI programs because VM:Webgateway can perform no other work while the CGI program executes on the VM:Webgateway SVM.

   WORKEREXEC

   Write the CGI program using REXX and the CGI program commands. When a CGI program runs on a VM:Webgateway worker machine, the CGI program has the privileges and authorities of the owner of the CGI program.

   If your CGI program contains long-running tasks, use the WORKEREXEC environment rather than SVMEXEC to avoid tying up the server resources.

   SVMWEBSHARE

   In most cases you do not have to make any changes to CGI programs that were written for Webshare. Because SVMWEBSHARE CGI programs run on the VM:Webgateway SVM, the VM:Webgateway SVM must have the authorization to obtain any data that your CGI program requests.

   If the CGI program expects the HTTP Authorization request header, use a filetype that indicates AUTHHEADERPASSED YES. If you are not authorized to use a filetype that indicates AUTHHEADERPASSED YES, change the CGI program to not require the HTTP Authorization request headers.

   Avoid including long-running tasks in your SVMWEBSHARE CGI programs because VM:Webgateway can perform no other work while the CGI program executes on the VM:Webgateway SVM.

   WORKERWEBSHARE

   In most cases you do not have to make any changes to CGI programs that were written for Webshare. When a CGI program runs on a VM:Webgateway worker machine, the CGI program has the privileges and authorities of the owner of the CGI program.

   If the CGI program expects the HTTP Authorization request header, use a filetype that indicates AUTHHEADERPASSED YES. If you are not authorized to use a filetype that indicates AUTHHEADERPASSED YES, change the CGI program to not require the HTTP Authorization request headers.

   If your CGI program contains long-running tasks, use the WORKERWEBSHARE environment rather than SVMWEBSHARE to avoid tying up the server resources.

   ---

   Note: http://www.slac.stanford.edu/~cottrell/rexx/share/ describes how to write CGI programs in REXX.
   VM:Webgateway complies with WWW Common Gateway Interface Version 1.1.

   ---

3. Move the CGI program to the server root domain. If necessary, add an entry to a DIRMAP file to identify it.

   Make sure VM:Webgateway has authorization to access the CGI program:

   If you serve data from a minidisk:

   VM:Webgateway requires read access to the minidisk from which you serve data.

   If you serve data from an SFS directory:

   VM:Webgateway requires SFS authorization to read the CGI program.

   If you serve data from a BFS directory:

   VM:Webgateway requires read and search permissions to the directory on which the CGI program resides and to all the parent directories. In addition, VM:Webgateway requires read and execute permissions to the CGI program.

   If you serve data using CMS search order:

   VM:Webgateway requires read access to each accessed minidisk you want to serve files from and SFS authorization to read each file you want to serve from an accessed SFS directory.