Natural SQL Gateway Server

This section covers the following topics:

• Natural SQL Gateway Server Concept

• Configuring the Natural SQL Gateway Server

• Operating the Natural SQL Gateway Server

• Monitor Client NATMOPI

• HTML Monitor Client

Natural SQL Gateway Server Concept

This section describes the concept and the structure of the server for the Natural SQL Gateway.

This server is necessary if the Natural SQL Gateway runs within a TP environment. For additional information, see Product Structure in the section Introduction to Natural SQL Gateway.

A Natural SQL Gateway server is a multi-user, multi-tasking application. The server is responsible for maintaining the persistent connection to the JDBC server for each client, because a client running in a TP environment cannot cope with persistent JDBC connections. The client opens a so called SQL session at the Natural SQL Gateway server. This is done implicitly with the SQL CONNECT statement. This session represents the client from the JDBC server point of view and keeps the persistent connection. The client is loosely coupled to this session just by maintaining a session identifier. The session remains until the client disconnects with the SQL DISCONNECT statement.

The Natural SQL Gateway server can host SQL sessions for multiple users and execute their requests concurrently.

To enable the administrator to monitor the status of the Natural SQL Gateway server, a monitor task is provided which is initialized automatically at server startup. Using the monitor commands, the administrator is able to control the server activities, cancel particular user sessions, terminate the entire server, etc. For further information, see Monitoring the Natural SQL Gateway Server in the section Operating the SQL Gateway Server.

Configuring the Natural SQL Gateway Server

This document describes how to configure a Natural SQL Gateway server.

The following topics are covered:

• Configuration Requirements

• Natural SQL Gateway Server Configuration File

• Natural SQL Gateway Server Configuration Parameters

• Natural SQL Gateway Server Configuration File Example

• Natural SQL Gateway Server Data Sets

Configuration Requirements

A Natural SQL Gateway server requires the following IBM Language Environment (LE) parameter configuration for z/OS:

ENVAR(TZ=CET-1DST) CET

To set the z/OS LE parameters, you have the following options:

• Use the PARM parameter specified in the EXEC card of the Natural SQL Gateway server startup job. The length of the options is limited by the maximum length of the PARM parameter.

• Assemble an LE/370 runtime option module CEEUOPT and link it to the Natural SQL Gateway server load module.

• As of z/OS Version 1.8, you can define the DD card for CEEOPTS to specify your LE options in a data set.

Natural SQL Gateway Server Configuration File

A configuration file is allocated to the name <serverid>C (for example, NSBS1C) or STGCONFG alternatively.

The configuration file contains the server configuration parameters in the form of a keyword=value syntax. In addition, it may contain comments whose beginning is marked with a hash symbol (#).

See also the Natural SQL Gateway Server Configuration File Example shown below.

Natural SQL Gateway Server Configuration Parameters

The following Natural SQL Gateway server configuration parameters are available:

• FRONTEND_NAME
• HANDLE_ABEND
• HOST_NAME
• HTPMON_ADMIN_PSW
• HTPMON_PORT
• PORT_NUMBER
• SESSION_TIMEOUT
• TRACE_FILTER
• TRACE_LEVEL

FRONTEND_NAME

This configuration parameter specifies the name of the CXX server front-end to be used to communicate with the JDBC server. The front-end resides on the CXX load library.

Example:

FRONTEND_NAME=CXXNSERV

HANDLE_ABEND

It is recommended that you leave this parameter on its default value in order to limit the impact of an abend to a single user. If you set the value of this parameter to NO, any abend in the server processing terminates the complete server processing. That is, it affects all users running on that server.

Example:

HANDLE_ABEND=NO

or

HANDLE_ABEND=NO

HOST_NAME

This optional configuration parameter is necessary only if the server host supports multiple TCP/IP stacks.

Example:

HOST_NAME=node1

or

HOST_NAME=157.189.160.55

HTPMON_ADMIN_PSW

This configuration parameter defines the password required for some monitor activities (for example, Terminate Server) performed by the HTML Monitor Client.

Example:

HTPMON_ADMIN_PSW=GHAU129B

HTPMON_PORT

A Natural SQL Gateway server can be configured to host an HTTP monitor task which serves the HTML Monitor Client running in a web browser. It is not required to run this monitor task on each server. A single task allows you to monitor all servers running at one node.

This configuration parameter defines the TCP/IP port number under which the server monitor task can be connected from a web browser.

Example:

HTPMON_PORT=3141

PORT_NUMBER

This configuration parameter defines the TCP/IP port number under which the server can be connected.

Example:

PORT_NUMBER=3140

SESSION_TIMEOUT

Cancel inactive sessions when the SESSION_TIMEOUT parameter is met. Check for sessions inactive longer then n minutes once a day at HH:MM (24 hours) or every n minutes.

The server will not start if an invalid SESSION_TIMEOUT parameter is given.

Examples:

SESSION_TIMEOUT=19:30,480

Every day at 19:30 cancel sessions more than 480 minutes inactive.

SESSION_TIMEOUT=360,480

Every 360 minutes cancel sessions more than 480 minutes inactive.

TRACE_FILTER

This optional configuration parameter enables you to restrict the trace by a logical filter in order to reduce the volume of the server trace output, for example:

TRACE_FILTER="Client=(XYZ P*)"

Each request of the user ID XYZ and each request of the user IDs starting with a P are traced.

See Trace Filter in the section Operating the Natural Gateway Server.

TRACE_LEVEL

Example:

TRACE_LEVEL=0x00000011

or alternatively

TRACE_LEVEL=31+27

The setting in the example switches on the TSW bits 31 and 27; see Trace Level in the section Operating the Natural Gateway Server.

Natural SQL Gateway Server Configuration File Example

For z/OS:

# This is a comment
FRONTEND_NAME=CXXNSERV       # and another comment
PORT_NUMBER=4811
TRACE_LEVEL=31+27

Natural SQL Gateway Server Data Sets

The Natural SQL Gateway server requires the following data sets:

Alternatively, you can qualify each data set name by the server ID.

Operating the Natural SQL Gateway Server

The following topics are covered below:

• Starting the Natural SQL Gateway Server

• Monitoring the Natural SQL Gateway Server

• Runtime Trace Facility

Starting the Natural SQL Gateway Server

Under z/OS:

The Natural SQL Gateway server can be started as a "started task":

//NSBSRV  PROC                                      
//SRV      EXEC PGM=NATRNSV,REGION=4000K,TIME=1440, 
// PARM=('POSIX(ON)/NSBSRV1')                        
//STEPLIB  DD DISP=SHR,DSN=NSBvrs.LOAD   
//CMPRINT  DD SYSOUT=X                             
//STGCONFG DD DISP=SHR,DSN=NSBvrs.CONFIG(SRV1)    
//STGTRACE DD SYSOUT=X                             
//STGSTDO  DD SYSOUT=X                             
//STGSTDE  DD SYSOUT=X

- where NSB is the product code and vrs is the version number of the Natural SQL Gateway server.

The name of the started task must be defined under RACF and the z/OS UNIX System Services.

Monitoring the Natural SQL Gateway Server

To enable the administrator to monitor the status of the Natural SQL Gateway server, a monitor task is provided which is initialized automatically at server startup. Using the monitor commands described below, the administrator is able to perform functions such as control the server activities, cancel particular user sessions, terminate the entire server, etc.

The following topics are covered below:

• Monitor Communication
• Monitor Commands

Monitor Communication

To communicate with the monitor

• Use the monitor client NATMOPI.

  See Monitor Client NATMOPI.

  Or:
  Use the HTML Monitor Client that supports a standard web browser.

  See HTML Monitor Client.

  Or:
  Under z/OS, you can alternatively use the operator command MODIFY to execute the monitor commands described below in the section Monitor Commands.

  The output of the executed monitor command will be written to the system log.

  Example:

  F jobname,APPL=ping

  sends the command ping to the Natural SQL Gateway server running under the job jobname.

Monitor Commands

The Natural SQL Gateway server supports the following monitor commands:

I'm still up

set TRACE_LEVEL 0x00000012

Runtime Trace Facility

For debugging purposes, the server code has a built-in trace facility which can be switched on, if desired.

The following topics are covered below:

• Trace Medium
• Trace Configuration
• Trace Level
• Trace Filter

Trace Medium

Under z/OS, the Natural SQL Gateway server writes its runtime trace to the logical system file STGTRACE.

Trace Configuration

The trace is configured by a trace level which defines the details of the trace. Once a trace is switched on, it can be restricted to particular clients or client requests by specifying a trace filter, see also Natural SQL Gateway server configuration parameter TRACE_FILTER.

Every session is provided with a 32-bit trace status word (TSW) which defines the trace level for this session. The value of the TSW is set in the Natural SQL Gateway server configuration parameter TRACE_LEVEL. A value of zero (0) means that the trace is switched off.

Trace Level

Each bit of the TSW is responsible for certain trace information. Starting with the rightmost bit:

Trace Filter

It is possible to restrict the trace by a logical filter in order to reduce the volume of the server trace output.

• The filter can be set with the configuration parameter TRACE_FILTER.

• The filter may consist of multiple keyword=filtervalue assignments separated by spaces.

• To activate the filter definition, the trace bit 14 in the trace status word (see Trace Level) must be set.

The filter keyword is:

The following rules apply:

• If a keyword is defined multiple times, the values are cumulated.

• The value must be enclosed in braces and can be a list of filter values separated by spaces.

• The values are not case sensitive.

• Asterisk notation is possible.

Example:

TRACE_FILTER="Client=(XYZ P*)"

Each request of the user ID XYZ and each request of the user IDs starting with a P are traced.

Monitor Client NATMOPI

This section covers the following topics:

• Introduction

• Command Interface Syntax

• Command Options Available

• Monitor Commands

• Directory Commands

• Command Examples

Introduction

The Monitor Client NATMOPI is a character-based command interface for monitoring the various types of servers that are provided in a mainframe Natural environment. Each of these servers has its own set of monitor commands which is described in the corresponding server documentation. In addition, a set of directory commands is available which can be used independent of the server type. One NATMOPI can be used to monitor different server types.

Command Interface Syntax

Basically the syntax of the command interface consists of a list of options where each option can/must have a value. For example:

-s <server-id> -c help

where -s and -c are options and <server-id> and help are the option values.

It is possible to specify multiple options, but each option can have only one value assigned.

The command options available are listed below.

Command Options Available

Words enclosed in <> are user supplied values.

Monitor Commands

These are commands that are sent to a server for execution. The monitor commands available depend on the type of server, however, each server is able to support at least the commands ping, terminate, and help.

For further commands, refer to Operating the Natural SQL Gateway Server where the corresponding server commands are described.

Directory Commands

Directory commands are not executed by a server, but directly by the monitor client NATMOPI.

You can use the directory commands to browse through the existing server entries and to remove stuck entries.

The following directory commands are available. Words enclosed in <> are user supplied values and words enclosed in straight brackets [] are optional.

Command Examples

Example: Ping a Server in Different Environments

Server in z/OS (started task or batch mode):

• Execute NATMOPI in batch job:

  NATMOPI,PARM=('-sServerName -cPING')

  Sample job:

  //SAGMOPI  JOB  SAG,CLASS=K,MSGCLASS=X                       
  //NATEX EXEC PGM=NATMOPI,REGION=3000K,                       
  // PARM=('-Sname -CPING')                                  
  //* PARM=('-H')                                              
  //STEPLIB  DD DISP=SHR,DSN=NATURAL.XXXvr.LE.LOAD         
  //         DD DISP=SHR,DSN=CEE.SCEERUN                       
  //SYSOUT   DD   SYSOUT=X
  //SYSPRINT DD   SYSOUT=X                                     
  //*                                                          
  

  Where XXX is the Natural SQL Gateway product code (NSB) and vr is the two-digit version number.

• Execute NATMOPI in TSO (Command):

  NATMOPI -sServerName -cPING

  The NSB load library must be included in the steplib of TSO.

Further Command Examples:

natmopi -dls

natmopi -dcl TST -ls TST

natmopi -sSRV1 -cping -sSRV2 -sSRV3 -cterminate

natmopi -cterminate -sSRV1 -cping -sSRV2 -sSRV3

natmopi -sSRV1 -cterminate -a

HTML Monitor Client

This section covers the following topics:

• Introduction

• Prerequisites for HTML Monitor Client

• Server List

• Server Monitor

Introduction

The HTML Monitor Client is a monitor interface that supports any web browser as a user interface for monitoring the various types of servers that are provided in a mainframe Natural environment. Each of these servers has its own set of monitor details which are described in the corresponding server documentation. The HTML Monitor Client enables you to list all existing servers and to select a server for monitoring.

Prerequisites for HTML Monitor Client

To run the HTML Monitor Client, any server must host an HTTP Monitor Server. The HTTP Monitor Server is a subtask that can run in any Natural SQL Gateway server address space and is configured with the configuration parameter HTPMON_PORT and HTPMON_ADMIN_PSW. An HTTP Monitor Server is accessible through a TCP/IP port number and can monitor all servers running on the current node (for SMARTS: running within the current SMARTS). Although it is not necessary, you can run multiple HTTP Monitor Servers on one node. But each one needs an exclusive port number.

Server List

Open your web browser and connect the HTTP Monitor Server using the following url: http://nodename:port, where nodename is the name of the host on which the Natural SQL Gateway server hosting the monitor is running. And port is the port number the administrator has assigned as the monitor port in the configuration file.

Example:

The server list consists of green and red entries. The red ones represent potentially dead server entries which can be deleted from the server directory by choosing the attached Remove button. The Remove button appears only for the red entries. "Potentially dead" means, that the HTTP Monitor Server "pinged" the server while assembling the server list, but the server did not answer within a 10 seconds timeout. Thus, even if you find a server entry marked red, it still might be active but could not respond to the ping. Choosing the Remove button does not terminate such a server but removes its reference in the monitor directory. Hence, it cannot be reached by the monitor anymore.

Choosing the Select button opens a window for monitoring the selected server.

Server Monitor

Example:

With the buttons, you can perform the labeled monitor commands.

The selection box allows you to modify the server configuration parameters. If you select a parameter for modification, it has a predefined value. This predefined value does not reflect the setting of the server. It is just a sample value.

If you choose the ListSess button, a list of all Natural sessions appears in the window, for example:

You can cancel sessions by selecting the session ID in the SessionId column and choosing the CancelSession button.