Configuring RXS Router

There are two main stages to routing configuration when using RXS Router. The first happens through the Apache configuration file - httpd.conf - which is typically in an IFS path like /www/rxs/conf/httpd.conf or /www/myrxs/conf/httpd.conf. The second stage happens within RXS Router and the RXS Router environments on your system.

Apache Configuration

RXS Router determines which environment to load based on the value of the RXSRTR_ENVIRONMENT variable, which is set by Apache. The first step is to add the following directive to your httpd.conf file:

ScriptAliasMatch ^/(([^/.]+/)*[^/.]+)$ /qsys.lib/RXS.lib/rxsrtr.pgm
  <Directory /qsys.lib/RXS.lib/>
     Options +ExecCGI
     Allow From all
  </Directory>

This directive tells Apache to call RXSRTR for every URL on which it is listening. This will allow Apache to transfer control to RXS Router, which will then run the associated programs before returning any output to Apache.

RXS Router checks the RXSRTR_ENVIRONMENT variable to determine which configuration should be loaded for a given request. This environment variable value is set by Apache. For each path which has a corresponding RXS Router environment, a Location element must be added to httpd.conf:

<Location /myrxs/>
  SetEnv RXSRTR_ENVIRONMENT 'MYRXS'
</Location>

The value of ‘/myrxs/’ should be substituted by your desired URL path, and the value of ‘MYRXS’ should correspond to the RXS Router environment that should be loaded.

RXS Router Configuration

The configuration of your RXS Router environment depends on which type of routing you are using - static or dynamic. Configuration records are stored in control files, which are accessible with the WRKRXSRTRE command.

Routing

Static (environment variable) routing

If the routingid flag has a value which begins with ENVVAR:, RXSRTR will check the specified environment variable on each request to determine the RRID. For instance, if the routingid flag is specified as follows:

-routingid envvar:http_soapaction

then whenever RXSRTR is called by the HTTP server, it will retrieve the value of the HTTP_SOAPACTION environment variable and will use that value as the RRID.

This processing will be performed for every request handled by RXSRTR, irrespective of the actual URL used.

If the specified environment variable is a path name, you may specify a qualifier of a colon followed by a slash, immediately following the environment variable name, e.g.:

-routingid envvar:http_soapaction:/

and RXSRTR will use only the last path segment of the environment variable as the RRID. For instance, if the value of the HTTP_SOAPACTION variable is

https://www.mycompany.com/webservices/local/values/focus/getasset

then the RRID used would be ‘GETASSET’.

Dynamic routing

If the routingid flag has a value which does not begin with ENVVAR:, RXSRTR will use ‘dynamic’ routing, whereby the actual URL used by the client will be parsed to determine the RRID.

RXSRTR uses the following steps to determine the RRID from the URL (as soon as the RRID has been determined, further steps are bypassed):

  1. The value of the QUERY_STRING environment variable is retrieved as {querystring}
  2. The SCRIPT_NAME environment variable is retrieved as {scriptname} and parsed into its constituent ‘segments’. For instance, a SCRIPT_NAME value of /rxsrtr/petstore/item’ is parsed into 3 separate segments – ‘rxsrtr’, ‘petstore’ and ‘item’. All values are converted to upper-case for comparison purposes during parsing.
  3. If one of the {scriptname} segments has a value of routingid and the next segment is not blank, that next segment is used as the RRID.
  4. If {querystring} is blank, the first {scriptname} segment (retrieved in step 2) is used as the RRID.
  5. If one of the variables in {querystring} is routingid, its value is used as the RRID.
  6. Otherwise the first {scriptname} segment is used as the RRID.

This means that all of the following example URI’s will result in an RRID of ‘MICKEY’ (assuming that the value of the routingid flag has the default value of ‘RXSRTR’)

  1. http://192.168.0.1/rxsrtr/mickey/foo/bar
  2. http://192.168.0.1/mickey/foo/bar
  3. http://192.168.0.1/foo/bar?fname=john&rxsrtr=mickey&lname=smith
  4. http://192.168.0.1/mickey/foo/bar?fname=john&lname=smith

In case 1, RXSRTR is specified as a path segment and the subsequent path segment is not blank, so it is used as the RRID. In case 2, RXSRTR is not specified as any of the path segments, and the QUERY_STRING variable is blank, so the first path segment is used as the RRID. In case 3, RXSRTR is not specified as any of the path segments. However, the QUERY_STRING variable does contain a variable called RXSRTR, so that variable’s value is used as the RRID. In case 4, RXSRTR is not specified as any of the path segments, and the none of the QUERY_STRING variables is called ‘RXSRTR’, so the first path segment is used as the RRID.

RXSRTRCTL Entries

Configuration entries for RXS Router are managed using WRKRXSRTRE. For a given RXS Router control file, there will be two or more individual entries, which are used to determine what programs are called by RXS Router.

Each control file must contain a *CONFIG entry. This entry is loaded first by RXS Router, and is used to determine which record in the environment is loaded for the final routing stage. More information about the options used by *CONFIG can be found on the RXS Router page.

The default value for the routing ID is RXSRTR, which instructs RXS Router to use dynamic routing to determine which control file record to load, based on the URL. For static routing, RXS Router will refer to the value of the specified environment variable to determine the correct control file record, and the routing ID flag must be specified using the ENVVAR: prefix.

Subsequent entries within your RXS Router control file contain configuration information for calling a specific program. RXS Router determines which of these records to invoke using the criteria outlined in the Routing section. There are many flags that can be specified for a given routing ID, but the only required one is -pgm, which tells RXS Router which program should be called.

The -pgm flag can either contain the name of a program or a special value (*0-*9). If a name is specified, RXS Router will search through the library list of the job for a match, or look in the library specified in the -lib tag. If a special value is used, RXS Router will refer to the URL path to determine which program should be called.

With Name

The following configuration will run the program DEMOSVC in the library MYRXS:

-pgm DEMOSVC -lib MYRXS

With Special Value

The following configuration will dynamically determine the program to be called, based on the URL, within the library list of the job decription (*JOBD) specified by the -liblst flag:

-pgm *1 -liblst MYRXS/RTRJOB

The special value of *0 corresponds to the routing ID, while *1-*9 represent URL path segments. If the service was called using the following URL:

https:/api.myservice.com/myrxs/demosvc/

the routing ID will be MYRXS, and RXS Router will call the program DEMOSVC.