In addition to the more standard CGI-like interface that Mod_Rexx supplies, an object interface is also available. The object interface is composed of three classes and their accompanying methods.

The file Apache.cls contains the class definitions for the object interface to Apache. To use it, just include a ::Requires directive in your Object Rexx program.

When using any of the classes to interface to Apache, you should only use the methods to accesss or set values. Using other external Rexx functions to access the Apache internal structures may cause subsequent problems in your program.

The classes and methods for the object interface are documented below.

Table of Contents

Request_rec Class

The request record class (request_rec) supplies an interface to the Apache internal request record. There are methods for retrieving values from the internal request record and (in some cases) setting the value in the internal request record (which can then be used in a subsequent phase of the request processing). The methods supplied with the class enforce certian rules about how values are retrieved and set in the internal request record in order that the Apache server is always aware of any changes to the request record.

To instantiate a request_rec class use the arg(1) value passed to the Object Rexx program. The following is an example of how to create a request_rec object.

rxptr = arg(1)
request = .request_rec~new(rxptr)

The methods for the request_rec class are documented below.

Requect_rec Method Table of Contents

Method: allowed

This method can return a copy of bit vector that the handler or set a new value.

Example

This is a example of how to retrieve a copy of the allowed bits.

allowed = request~allowed

This is a example of how to set the allowed bits.

allowed = request~allowed(new_allowed)

Method Parameters

new_allowed

The new value to be assigned to the allowed bits in the request record. You should only supply this parameter when you want to assign a new value to the allowed bits.

Method: args

This method returns the args (the raw query string).

Example

This is a example of how to retrieve the args field.

argspath = request~args

Method Parameters

None.

Method: auth_type

Retrieves auth_type field in the request record.

Example

authorization_type = request~auth_type

Method Parameters

None

Method: connection

Retrieves the value to be used to create a connection object. See the documentation on the connection_rec class below.

Example

cxptr = request~connection

Method Parameters

None

Method: content_encoding

This method can return or set the content_encoding field.

Example

This is a example of how to retrieve the content_encoding.

content_encoding = request~content_encoding

This is a example of how to set the content_encoding field.

content_encoding = request~content_encoding(new_content_encoding)

Method Parameters

new_content_encoding

The new value to be assigned to the content_encoding field. You should only supply this parameter when you want to assign a new value to the content_encoding field.

Method: content_languages

This method can return or add a new entry to the content_languages array.

Example

This is a example of how to retrieve the list of content_languages. The list is a comma seperated.

content_languages = request~content_languages

This is a example of how to add an entry the content_languages array.

content_languages = request~content_languages(new_entry)

Method Parameters

new_entry

The new entry to be assigned to the content_languages array. You should only supply this parameter when you want to assign a new value to the content_languages array.

Method: content_type

This method can return or set the content_type field.

Example

This is a example of how to retrieve the content_type.

content_type = request~content_type

This is a example of how to set the content_type field.

content_type = request~content_type(new_content_type)

Method Parameters

new_content_type

The new value to be assigned to the content_type field. You should only supply this parameter when you want to assign a new value to the content_type field.

Method: err_header_out

This method can return a copy of the outgoing HTTP error header.

Example

This is a example of how to retrieve a copy of the err_header_out field.

err_header_out = request~err_header_out

This is a example of how to set the headers_out field.

err_header_out = request~err_header_out(new_err_header_out)

Method Parameters

new_err_header_out

The new value to be assigned to the err_header_out field in the request record. You should only supply this parameter when you want to assign a new value to the err_header_out field.

Method: filename

This method can return or set the filename field.

Example

This is a example of how to retrieve the filename field.

filename = request~filename

This is a example of how to set the filename field.

filename = request~filename(new_filename)

Method Parameters

new_filename

The new value to be assigned to the filename field. You should only supply this parameter when you want to assign a new value to the filename field.

Method: finfo_stmode

This method returns the file status bits of the filename field as a hexadecimal string. You can use the Rexx builtin function x2b() to turn it into a bit string for easier examination.

Example

This is a example of how to retrieve the file status bits.

status = request~finfo_stmode
/* status = '81ed' */
status = request~finfo_stmode~x2b
/* status = '1000000111101101' */

Method Parameters

None.

Method: handler

This method can return or set the handler field.

Example

This is a example of how to retrieve the handler name.

handler = request~handler

This is a example of how to set the handler name field.

handler = request~handler(new_handler)

Method Parameters

new_handler

The new value to be assigned to the handler name field. You should only supply this parameter when you want to assign a new value to the handler field.

Method: header_only

Returns .true if the request should only return header information. Otherwise it returns .false.

Example

if request~header_only = .true then do
   /* perform some processing */
   end
else do
   /* perform other procesing */
   end

Method Parameters

None

Method: headers_in

This method can return a copy of the incoming HTTP headers.

Example

This is a example of how to retrieve a copy of the headers_in field.

headers_in = request~headers_in

This is a example of how to set the headers_in field.

headers_in = request~headers_in(new_headers_in)

Method Parameters

new_headers_in

The new value to be assigned to the headers_in field in the request record. You should only supply this parameter when you want to assign a new value to the headers_in field.

Method: headers_out

This method can return a copy of the outgoing HTTP headers.

Example

This is a example of how to retrieve a copy of the headers_out field.

headers_out = request~headers_out

This is a example of how to set the headers_out field.

headers_out = request~headers_out(new_headers_out)

Method Parameters

new_headers_out

The new value to be assigned to the headers_out field in the request record. You should only supply this parameter when you want to assign a new value to the headers_out field.

Method: ismain

Returns .true if this is the main request object (the first object in a possible chain of request objects). Otherwise it returns .false.

Note: Because of a limitation in the Mod_Rexx package, this method will always return .true.

Example

if request~main = .true then do
   /* perform some processing */
   end
else do
   /* perform other procesing */
   end

Method Parameters

None

Method: main

Retrieves the value to be used to create a request object. In some cases the Apache server can chain requests together. If the current request is a chained request then this method will return a valid pointer to the first request record.

Example

rxptr = request~main

Method Parameters

None

Method: method

This method can return a copy of the HTTP method name or set its value.

Example

This is a example of how to retrieve a copy of the method name.

if request~method = 'POST' then do
   /* perform some processing */
   end
else do
   /* perform other procesing */
   end

This is a example of how to set the method name.

new_method = request~method('GET')

Method Parameters

new_method

The new value to be assigned to the method in the request record. You should only supply this parameter when you want to assign a new value to the method.

Method: method_number

This method can return a copy of the HTTP method_number or set its value.

Example

This is a example of how to retrieve a copy of the method_number.

method_number = request~method_number

This is a example of how to set the method_number.

method_number = request~method_number(new_method_number)

Method Parameters

new_method_number

The new value to be assigned to the method_number in the request record. You should only supply this parameter when you want to assign a new value to the method_number.

Method: next

Retrieves the value to be used to create a request object. In some cases the Apache server can chain requests together. If the current request is a chained request then this method will return a valid pointer to the next request record.

Example

rxptr = request~next

Method Parameters

None

Method: no_cache

This method can return or the no_cache setting.

Example

This is a example of how to retrieve the no_cache setting.

no_cache = request~no_cache

Method Parameters

None.

Method: notes

This method can return a copy of the notes table.

Example

This is a example of how to retrieve a value in the notes table.

value = request~notes(key)

This is a example of how to set a value in the notes table.

value = request~notes(key, new_value)

Method Parameters

key

The key lookup.

new_value

The new value to be assigned to the entry with the lookup key. If the key does not exist in the table, it will be added.

Method: path_info

This method can return or set the path_info field.

Example

This is a example of how to retrieve the path_info field.

path_info = request~path_info

This is a example of how to set the path_info field.

path_info = request~path_info(new_path_info)

Method Parameters

new_path_info

The new value to be assigned to the path_info field. You should only supply this parameter when you want to assign a new value to the path_info field.

Method: prev

Retrieves the value to be used to create a request object. In some cases the Apache server can chain requests together. If the current request is a chained request then this method will return a valid pointer to the previous request record.

Example

rxptr = request~prev

Method Parameters

None

Method: protocol

Returns a copy of the request protocol name.

Example

protocol = request~protocol
if protocol = 'HTTP v1.0' then do
   /* perform some processing */
   end
else do
   /* perform other procesing */
   end

Method Parameters

None

Method: proxyreq

Returns .true if the request is a proxy request. Otherwise it returns .false.

Example

if request~proxyreq = .true then do
   /* perform some processing */
   end
else do
   /* perform other procesing */
   end

Method Parameters

None

Method: server

Retrieves the value to be used to create a server object. See the documentation on the server_rec class below.

Example

sxptr = request~server

Method Parameters

None

Method: status

This method can return a copy of the status or set its value.

Example

This is a example of how to retrieve a copy of the status.

status = request~status

This is a example of how to set the status.

status = request~status(new_status)

Method Parameters

new_status

The new value to be assigned to the status in the request record. You should only supply this parameter when you want to assign a new value to the status.

Method: status_line

This method can return a copy of the status line or set its value.

Example

This is a example of how to retrieve a copy of the status line.

status_line = request~status_line

This is a example of how to set the status line.

status_line = request~status_line(new_status_line)

Method Parameters

new_line

The new value to be assigned to the status line in the request record. You should only supply this parameter when you want to assign a new value to the status_line.

Method: subprocess_env

This method can return a copy of the subprocess environment.

Example

This is a example of how to retrieve a copy of the subprocess environment.

subprocess_env = request~subprocess_env

This is a example of how to set the subprocess environment field.

subprocess_env = request~subprocess_env(new_subprocess_env)

Method Parameters

new_subprocess_env

The new value to be assigned to the subprocess_env field in the request record. You should only supply this parameter when you want to assign a new value to the subprocess_env field.

Method: the_request

Returns a copy of the HTTP request.

Example

http_request = request~the_request

Method Parameters

None

Method: uri

This method returns the path part of the URI.

Example

This is a example of how to retrieve the uri field.

uripath = request~uri

Method Parameters

None.

Method: user

Retrieves user field in the request record.

Example

username = request~user

Method Parameters

None

Connection_rec Class

The connection record class (connection_rec) supplies an interface to the Apache internal connection record. There are methods for retrieving values from the internal connection record. The methods supplied with the class enforce certian rules about how values are retrieved and set in the internal connection record in order that the Apache server is always aware of any changes to the connection record.

To instantiate a connection_rec class use the value returned from the request_rec method connection. The following is an example of how to create a connection_rec object.

/* establish the request record object */
rxptr = arg(1)
request = .request_rec~new(rxptr)

/* now establish the connection record object */
connx = .connection_rec~new(request)

The methods for the connection_rec class are documented below.

Connection_rec Method Table of Contents

Method: aborted

Retrieves aborted field in the connection record.

Example

abort = connx~aborted
/* abort is now set to either .true or .false */

Method Parameters

None

Server_rec Class

The server record class (connection_rec) supplies an interface to the Apache internal server record. There are methods for retrieving values from the internal server record. The methods supplied with the class enforce certian rules about how values are retrieved and set in the internal server record in order that the Apache server is always aware of any changes to the server record.

To instantiate a server_rec class use the value returned from the request_rec method server. The following is an example of how to create a server_rec object.

/* establish the request record object */
rxptr = arg(1)
request = .request_rec~new(rxptr)

/* now establish the server record object */
srvr = .server_rec~new(request)

The methods for the server_rec class are documented below.

Server_rec Method Table of Contents

Method: admin

Retrieves admin field in the server record.

Example

admin_email_addr = srvr~admin

Method Parameters

None

Method: hostname

Retrieves hostname field in the server record.

Example

srvr_host_name = srvr~hostname

Method Parameters

None

Method: is_virtual

Retrieves is_virtual field in the server record.

Example

virtual_srvr = srvr~is_virtual
/* if virtual_srvr is set to .true then the request was to a virtual server */
/* if virtual_srvr is set to .false then the request was to the main server */

Method Parameters

None

Method: port

Retrieves port field in the server record.

Example

port_num = srvr~port

Method Parameters

None

Copyright (C) W. David Ashley 2004. All Rights Reserved.