Configuring the ODBC driver

The MAS ODBC Client provides one basic connectivity option: MAS ODBC Direct. This option and its features are described in the sections below.

MAS ODBC direct

This is the recommended option. It allows Windows NT and 2000, OS/2, UNIX, and Linux client systems to access many types of data including DB2-OS/390, IMS/DB, IMS/TM, CICS/TS, ADABAS, VSAM, PDSs, flat files, and many more. There are drivers available for TCP/IP users and LU 6.2 users. The MAS Mainframe Agent will interact with any application that uses the ODBC API.

If you select ODBC for your client connectivity, you will need to know your DBMS type, which is the means by which you will be accessing data. Initially, the DB2 type is displayed in the ODBC Data Source Administrator, the tool you use to configure the ODBC driver data source. See "Using the ODBC data source administrator".

Controlling the ODBC driver

After you configure the MAS ODBC driver, you can control it using driver keywords. These keywords are automatically given default values that can be changed depending on the connector you are using. For further information, see Appendix C, MAS driver keywords.

Data sources

The data source you will be defining stores information about how to connect to the indicated data provider.

You will be configuring the data source on the ODBC Administrator, which was automatically installed. The ODBC Administrator lets you configure multiple data sources of any type or types on the same workstation according to your requirements.

Data sources for MAS are desktop. All connection information is stored locally in each user's ODBC.INI file. If you make any changes to the connection information, the new ODBC.INI file must be propagated to everyone's PC. If the data source moves to another computer, everything must be reconfigured.

Using support for multi-threaded applications

The MAS ODBC driver is enhanced to work with multi-threaded applications, which include many popular server products that use concurrent threads or thread-based connection pooling models to invoke ODBC operations. The MAS ODBC driver is fully thread-safe and does not require thread affinity.

By default, the driver does not run in the thread-safe mode; it must be enabled. The default is set to remove the performance penalty caused by the requirement to control access to shared resources by concurrent threads and because most applications do not take advantage of the multithreading programming model.

Running the driver in multi-threaded mode

To enable the driver to run in thread-safe mode when called by a multi-threaded application, you can set the NEONTHREADSAFE variable to YES or 1 in one of the following ways:

Enabling debug tracing in multi-threaded mode

When you use the NEONTRACE environment variable, its value controls the trace settings for that session. This means any values set by the NEONTRACE ODBC keyword are ignored. To enable debug tracing and thread-safe behavior, set all trace keywords with the NEONTRACE environment variable.

For example, to force thread-safeness and generate an INFO level trace file to C:\NEONLOG.TXT on Windows systems:

For UNIX systems:

Note:
For further information on tracing, see "Tracing".

Configuring the ODBC driver data source for Windows

You configure the data source on Windows systems using the MAS ODBC Data Source Administrator, a graphical user interface (GUI). The sections below describe how to do this.

Using the ODBC data source administrator

When MAS was installed, the icon for the MAS ODBC Data Source Administrator automatically placed on your PC's Control Panel. Using the Control Panel is the easiest way to access the driver, although you can access it using the path specified during the installation process.

To configure the MAS ODBC driver data source:

  1. Open the Start menu and select Settings/Control Panel (if you are using Windows NT 3.0 or higher) or Settings/Control Panel/Administrative Tools (if you are using Windows 95 or higher).
  2. Double-click the ODBC Data Sources icon (or item, if viewing by List or Details).

    The system displays the ODBC Data Source Administrator dialog box.

    Figure 2. ODBC Data Source Administrator dialog box



  3. Select the User DSN tab.
  4. Click Add.

    This displays the Create New Data Source box as shown in Figure 3.

    Figure 3. Create new data source dialog box

  5. Select the Neon Client Debug 32-bit (thread-safe) or Neon Client 32-bit (thread-safe) driver and click Finish.
    Note:
    Only thread-safe is advisable.

    The system will display a configuration dialog box, as shown in Figure 4.

    Figure 4. MAS debug configuration dialog box

  6. Enter the Data Source Name and Description.
  7. Select the data source type: ODBC. The dialog box options will change depending on the data source type.

    ODBC:

    Note:
    You can select DB2 as your DBMS type when you are accessing IMS/TM, CICS/TS, Natural, and IDMS Database. In these cases, all creates, modifications, retrieves, and deletes will be processed using CALL statements. See "Syntax for CICS/TS and IMS/TM CALL statements".
  8. Select the Connection Information (shown in Figure 4): TCP/IP, LU 6.2, or WebSphere MQ. Like the data source type, this portion of the dialog box changes depending on the option you select.

    TCP/IP:

    LU 6.2:

  9. Click Advanced. The system displays the Advanced Information dialog box, shown in Figure 10 (based on the data source type you selected, some of the fields shown in the figure may be missing.)

    Figure 10. Client Advanced Information

  10. If you selected ODBC as your data source type, enter or select the following information:
  11. Click More. The system will display the Optional Information dialog box, as shown in Figure 11.

    You can use this dialog box to set keyword values.

    Note:
    Some of these keyword values must be set to non-default values, depending on the interface you are using. These keywords and their values are covered in Appendix C, MAS driver keywords.

    Figure 11. Optional settings

  12. Click OK until you exit you from the ODBC Data Source Administrator to write the entered values into the ODBC.INI file, which will be used as your default the next time you connect to the data source.

Syntax for CICS/TS and IMS/TM CALL statements

This section discusses syntax for CICS/TX and IMS/TM CALL statements.

CICS/TS CALL Syntax

CICS/TS statements use the following syntax:

CALL <CICS Stored procedure> (<parameters>)
 

an example would be:

CALL CICSEX.NESPSEL ('logonid')
 

it will return one row with four columns and it will look like this:

CA_IN_LID        CA_OUT_NAME        CA_OUT_PHONE        CA_OUT_EMAIL
 
         SCHFS                    Henry Sobieski
 
8005056366               HSOBIESKI@NEONSYS.COM
 
IMS/TM CALLSyntax

IMS/TM statements use the following syntax:

CALL <IMS Stored procedure> (<parameters>)
 

an example would be:

call ims.imssp('','','','s','Sobieski', 'Henry','F','','','','','','','')
 

A record will be retrieved by specifying the first name, last name and middle initial in parm 5 (D05751), parm 6 (D05757), and parm 7 (D05752).

Note that the parm 4 (REVFLD) is populated with an 's'. The resultset will look like this:

          ADDFLD                         CHGFLD                    REMFLD
 
REVFLD          D05751                 D05757              D05752
 
D05754          D05755                 D05756              D15333  
 
D15334          D07786                           F00028
 
SOBIESKI        HENRY                  F          FAIRFAX           VA           
 
           IBM    TEST          SDBB000          0SDBB00001246581
 
ITINERARY RETRIEVED
 

Configuring the ODBC data source for UNIX

The ODBC drivers for UNIX are provided as UNIX shareable libraries but, unlike the Windows environment, the UNIX drivers do not require the presence of an ODBC driver manager. Instead, you need only edit the .INI file. However, if your application requires a third-party ODBC manager, MAS provides a procedure. The sections below describe:

ODBC driver file structure

The installation process creates a directory tree with the root directory named shadow. The installed files are untar'ed. The directory structure is as follows:

SHADOW - +--- SAMPLES (scodbcsm.c)
 |  scimbmsm.c
 |  scimccsm.c
 |  schorpsm.c,
 |  Readme files,
 |  makefile)
 |
 +--- INCLUDE (header files for UNIX)
 |
 +--- LIB (shareable library)
 |             libscodbc.so.1    (production version)
 |             libscodbcts.so.1  (debug version)
 |
 +--- BIN (Dynamic-to-static)
 |             dsa                 (dynamic-to-static)
 |             scodbcdm executable (sample program - See
             appendix.)
 

Editing the odbc.ini file

To configure data sources on the SunOS/Solaris platform, you specify a search path and use a text editor to modify the obdc.ini file:

  1. Specify the Search Path.

    Make sure the search path to the MAS run-time library is specified. For example, using csh under SunOS and Solaris, you would specify the directory name where the libraries are located by modifying the LD_LIBRARY_PATH environment variable:

    setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/shadow/lib
     
    
  2. Configure the .odbc.ini or odbc.ini file.

    All ODBC data connection information must be stored in a configuration file. MAS supports two naming conventions: .odbc.ini (used by many UNIX ODBC driver manager vendors) and odbc.ini. This configuration file must be stored in the directory pointed to by the $HOME environment variable. The driver searches for the .odbc.ini file first, then the odbc.ini.

    Note:
    The file name for the configuration file must be in lower case. For example, .odbc.ini is a valid file name, but .ODBC.INI is not.
Tip:
When the ODBC application runs as a daemon process or is spawned by a master process, the $HOME environment variable might not be set in the process context calling the driver. You can either set the variable programatically using putenv(3C) or by setting the environment variable in the context of the parent process.

Using a UNIX-based ODBC application linked with third-party ODBC driver manager

If an application requires the presence of a third-party driver manager and the run-time library dependency cannot be altered, then you must do the following to allow the application to use MAS drivers:

  1. Ensure that the MAS ODBC driver is setup correctly.
  2. Create two new symbolic links from the standard MAS driver library with the driver manager library's file names. These are usually named libodbc.so and libodbcinst.so. For example:
    ln -s shadow/lib/libscodbcts.so shadow/lib/libodbc.so
     ln -s shadow/lib/libscodbcts.so shadow/lib/libodbcinst.so
     
    
  3. Ensure these two new symbolic links can be searched ahead of the real ODBC driver manager libraries by modifying the LD_LIBRARY_PATH variable.

Sample odbc.ini file

The DSN keyword is used to identify a valid keyword section in the odbi.ini file.

[ODBC Data Sources]
 DB2.DEMO=Shadow Direct UNIX Debug Driver
 DB2.TEST=Shadow Direct UNIX Debug Driver
 VSAM.TEST=Shadow Direct UNIX Debug Driver
  
 [DB2.DEMO]
 Driver=<put the load path of the library here....>
 Description=<your description here...>
 APPL=ODBC
 MR=0
 HD=NO
 CPFX=SHADOW
 LINK=TCPIP
 UID=<user id>
 PWD=<password>
 HOST=<hostname or IP address>
 PORT=<server listening port>
 CD=NO
 PLAN=SDBC1010
 SUBSYS=DSN2
 # this is a comment line
 # this is a comment line
 NEONTRACE=INFO log=/tmp/neonlog.txt
 

Search order for UNIX odbc.ini file

The following is the search order for the odbc.ini file:

  1. /usr/local/lib/neon/odbc.ini
  2. $ODBC_INI
  3. $ODBC_INI (e.g., setenv ODBC_INI "/home/somebody/.my_odbc.ini")
  4. $HOME/.odbc.ini
  5. $HOME/.ODBC.INI
  6. $HOME/odbc.ini
  7. $HOME/ODBC.INI

The driver requires only the READ permission on this file.

Copyright IBM Corp. 1997, 2003