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 D, 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 D, 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 SHADOW_CICS('NNNN','CCCC','TTTT','PPPPPPPP',
1,2,3,4,5,6,'COLUMN or MAP')

where parameters are as shown in Table 28.

Table 28. Shadow interface for CICS/TS ODBC call parameters

Parameter Description
'NNNN'
Connection type as defined in the SD EXEC, "EXCI".
'CCCC'
Connection name as defined in the SD EXEC.
'TTTT'
Tran ID as defined in CICS. For EXCI, this is the tran ID that is associated with the DFHMIRS program.
'PPPPPPPP'
Program name as defined in CICS.
'1'
First parameter expected by program.
'2'
Second parameter expected by program.
'3'
Third parameter expected by program.
'4'
Fourth parameter expected by program.
'5'
Optional. Length of commarea. If not present, default is 32k.
'6'
Indicates if recursive execution of transaction is required. Possible values are as follows:

Y
for yes

N
for no.

Default value is N.

'COLUMN or MAP'
Column name or map name used for returned data. For the MAP keyword, the syntax is: 'MAP(NAME(PARTREXX) FIELDS(*))'

NAME: This entry should correspond to the name assigned to the map during extraction.

FIELDS: There are two ways to return data from all columns that are enabled in the map definition: Use an asterisk after FIELDS. Omit FIELDS altogether. To exclude some columns, enter the names of the enabled columns you do want returned in parentheses after FIELDS. For more information about the Data Mapping Facility, refer to the Shadow Server Planning & Administration Guide.

'NNNN'
Connection type as defined in the SD EXEC, "EXCI".

Example of EXCI demo transaction:

CALL SHADOW_CICS('EXCI','EXCS','EXCI','DFH$AXCS',
2,'FILEA ',   ' 1','',150,'','MAP(NAME(EXCIMAP)FIELDS(*))')
Note:
In the above statement FILEA is followed by three spaces (for a total of eight characters) and 1 is preceded by five spaces (for a total of six characters).

IMS/TM CALLSyntax

IMS/TM statements use the following syntax:

CALL SHADOW_IMS('IME','TRANSACTION PROGRAM NAME',
'IMS-PARTNER-LU NAME','SECURITY-TYPE','TP PARAMETERS',
'COLUMN or MAP','LOCAL LU NAME','MODE NAME',
'SYMDEST','USERID','PASSWORD','PROFILE',
'SEND-TYPE','MESSAGE-LENGTH')

The SHADOW_IMS parameters are described in Table 29.

Table 29. Shadow interface for CICS/TS ODBC call parameters

Parameter Definition
'IME'
A keyword describing the interface.
'TRANSACTION
PROGRAM NAME'
The name of the IMS transaction to be executed.
'IMS-PARTNER-
LUNAME'
The name of the IMS partner LU, as defined in SYS1.PARMLIB(APPCPMxx).
'SECURITY-TYPE'

Defines the type of security in use: NONE specifies to omit access security information on this allocation request.

SAME specifies to use the userid and security profile (if present) from the allocation request that initiated the local program. The password (if present) is not used; instead, the userid is indicated as being already verified. If the allocation request that initiated execution of the local program contained no access security information, then access security information is omitted on this allocation request.

PROGRAM specifies to use the access security information that the local program provides on the call. The local program provides the information by means of the userid, password, and profile parameters. These values are passed exactly as specified, without folding to uppercase.

'TP PARAMETERS'
Parameters for the transaction program.
'COLUMN or MAP'

Column name or map name used for returned data. For the MAP keyword, the syntax is: 'MAP(NAME(PARTREXX) FIELDS(*))' NAME: This entry should correspond to the name assigned to the map during extraction.

FIELDS: There are two ways to return data from all columns that are enabled in the map definition:

Use an asterisk after FIELDS.

Omit FIELDS altogether.

To exclude some columns, enter the names of the enabled columns you do want returned in parentheses after FIELDS.

For more information about the Data Mapping Facility, refer to the Shadow Server Planning & Administration Guide.

'LOCAL LU NAME'
Optional. Name of local LU where the caller's allocate request originates. The ability to specify a local LU name allows the caller to associate its outbound conversations with particular LUs. The caller's address space must have access to the named LU. Otherwise, a parameter_error return code is returned. This is the new local LU name, specified in SYS1.PARMLIB(APPCPMxx). This parameter is optional. The default is to use the APPC base LU, as defined in SYS1.PARMLIB(APPCPMxx).
Note:
It is recommended that a separate local LU be defined for each Shadow Server you have running using IMS/APPC. Application developers should be informed of which LU should be used with which copy of the Shadow Server. The APPC base LU will work in most cases; however, using a separate local LU tends to be more reliable.
'MODE NAME'

Optional. Specifies the mode name designating the network properties for the session to be allocated for the conversation. The network properties include, for example, the class of service to be used. The mode name value of SNASVCMG is reserved for use by APPC/MVS. If a mode name of SNASVCMG is specified on the allocate service, the request is rejected with a parameter_error return code.

If you specify a symbolic destination name in the SYMDEST name parameter, set mode name to blanks to obtain the mode name from the side information.

If the partner LU is the same or on the same system as the local LU name, mode name is ignored. If the partner LU is on a different system, and you do not specify a SYMDEST name, a blank mode name defaults to any mode in effect for the local and partner LUs or causes a parameter_error return code.

'SYMDEST'

Optional. Specifies a symbolic name representing the partner LU, the partner TP name, and the mode name for the session on which the conversation is to be carried. The symbolic destination name must match that of an entry in the side information data set. The appropriate entry in the side information is retrieved and used to initialize the characteristics for the conversation.

If you specify a SYMDEST name, the partner LU name, mode name, and TP name are obtained from the side information. If you also specify values for the partner LU name, mode name, or TP name parameters on the allocate service, these values override any obtained from the side information.

The SYMDEST name in this field can be from 1 to 8 characters long, with characters from character set 01134. If the SYMDEST name is shorter than 8 characters, it must be left-justified in the variable field and padded on the right with blanks. To not specify a SYMDEST name, set the SYMDEST name parameter value to 8 blanks and provide values for the partner LU name, mode name, and TP name parameters.

'USERID'

Optional. Specifies the userid. The partner LU uses this value and the password to verify the identity of the end user that initiated the allocation request. The partner LU may use this value for auditing and accounting purposes, and, together with the security profile (if present), to determine which partner programs the local program can access.

When the partner LU is on MVS with RACF protection, the userid must be 1 to 8 alphanumeric characters.

This parameter is significant only when the security type is set to PROGRAM. Otherwise, this parameter has no meaning and is ignored.

'PASSWORD'

Optional. Specifies the password. The partner LU uses this value and the userid to verify the identity of the end user that made the allocation request. When the partner LU is on MVS with RACF protection, the password must be 1-to-8 alphanumeric characters padded with blanks.

This parameter is significant only when the security type is set to PROGRAM. Otherwise, this parameter has no meaning and is ignored.

'PROFILE'

Optional. Specifies additional security information that may be used to determine what partner programs the local program may access and which resources the local program may access. When the partner LU is on MVS with RACF protection, APPC/MVS treats the profile name as an RACF group name for verifying access to partner programs. The profile name must be 1 to 8 alphanumeric characters.

This parameter is significant only when the security type is set to PROGRAM. Otherwise, this parameter has no meaning and is ignored.

'SEND-TYPE'
Optional. Specifies what, if any, information is to be sent to the partner program in addition to the data supplied. Also lets you combine operations (for example, send_and_confirm) and save extra calls to APPC. Default value is 1. Valid values for this parameter are as follows:

0
Buffer_data

Specifies that no additional information is to be sent to the partner program, and the data may be buffered until a sufficient quantity is accumulated.

1
Send_and_flush

Specifies that no additional information is to be sent to the partner program. However, the supplied data is sent immediately rather than buffered. This is functionally equivalent to a send_data call with the send_type parameter set to buffer_data, followed by a flush call.

2
Send_and_confirm

Specifies that the supplied data is to be sent to the partner program immediately, along with a request for confirmation. This is functionally equivalent to a send_data call with the send_type parameter set to buffer_data, followed by a confirm call.

3
Send_and_prepare_to_receive

Specifies that the supplied data is to be sent to the partner program immediately, along with send control of the conversation. This is functionally equivalent to a send_data call with the send_type parameter set to buffer_data followed by a prepare_to_receive call with the prepare_to_receive_type set to sync_level, and the locks parameter set to short.

4
Send_and_deallocate

Specifies that the supplied data is to be sent to the partner program immediately, along with a deallocation notification. This is functionally equivalent to a send_data call with the send_type parameter set to buffer_data, followed by a deallocate call with the deallocate_type set to sync_level.

'MESSAGE LENGTH'
Optional. Specifies the length of the messages that are written to or read from the message queue. The default value is 32k.

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
 
[VSAM.TEST]
Driver=/home/pbangalore/Sapphire/connectors/NEONAIX/shadow/lib/libscodbcts.so
Description=my test win NEON
APPL=ODBC
MR=0
HD=NO
CPFX=SHADOW
LINK=TCPIP
UID=DEMO01
PWD=DEMO01
HOST=mkt.neonsys.com
PORT=1200
CD=NO
PLAN=SDBC1010
SUBSYS=NONE
# this is a comment line
# this is a comment line
NEONTRACE=INFO log=/tmp/neonlog.txt
DBTY=VSAM
 
[CICS.TEST]
Driver=/home/pbangalore/Sapphire/connectors/NEONAIX/shadow/lib/libscodbc.so
Description=my test win NEON
APPL=ODBC
MR=0
HD=NO
CPFX=SHADOW
LINK=TCPIP
UID=DEMO01
PWD=DEMO01
HOST=mkt.neonsys.com
PORT=1200
CD=NO
PLAN=SDBC1010
SUBSYS=NONE
# this is a comment line
# this is a comment line
NEONTRACE=INFO log=/tmp/neonlog_cics.txt
DBTY=DB2
 
[NATL.TEST]
Driver=/home/pbangalore/Sapphire/connectors/NEONAIX/shadow/lib/libscodbc.so
Description=my test win NEON
APPL=ODBC
MR=0
HD=NO
CPFX=SHADOW
LINK=TCPIP
UID=DEMO01
PWD=DEMO01
HOST=mkt.neonsys.com
PORT=1227
CD=NO
PLAN=SDBC1010
SUBSYS=NONE
# this is a comment line
# this is a comment line
NEONTRACE=INFO log=/tmp/neonlog_natural.txt
DBTY=DB2
 
[DB2.TEST]
Driver=/public5/neon5/sgpbin/libscodbcts.so
Description=DB2 system
APPL=ODBC
MR=0
HD=NO
CPFX=SHADOW
LINK=TCPIP
UID=demo01
PWD=demo01
HOST=mkt.neonsys.com
PORT=1200
CD=NO
PLAN=SDBC1010
SUBSYS=DSN1
# this is a comment line
# this is a comment line
NEONTRACE=INFO log=/tmp/neonlogdb2.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