The MAS ODBC Client provides one basic connectivity option: MAS ODBC Direct. This option and its features are described in the sections below.
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".
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.
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.
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.
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:
NEONTHREADSAFE = YES
Modifying the registry can enable the driver to run in thread-safe mode when called by all applications, regardless of whether they are designed to be single- threaded or multi-threaded. Setting the NEONTHREADSAFE variable via the registry key to enable thread-safe mode is a machine-wide setting, available only via Microsoft Windows platforms
NEONTHREADSAFE = YES
Using an environment variable to enable thread-safe mode will only affect applications that inherit the environment settings when started.
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:
NEONTRACE=LOCKTHREAD INFO LOG c:\neonlog.txt
NEONTRACE=LOCKTHREAD INFO LOG=C:\neonlog
For UNIX systems:
NEONTRACE=INFO BUFFERTRACE LOG=/home/ai38aas/shadow/bin/neonlog.txt
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.
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:
The system displays the ODBC Data Source Administrator dialog box.
Figure 2. ODBC Data Source Administrator dialog box
This displays the Create New Data Source box as shown in Figure 3.
The system will display a configuration dialog box, as shown in Figure 4.
ODBC:
Table 21. Data source DBMS type
Data source | Enter in DBMS type field |
---|---|
DB2 | DB2 |
VSAM | VSAM |
VSAMCICS | VSAMCICS |
ADABAS | ADABAS |
IMSDB | IMSDB |
IMS/TM | DB2 (see note) |
CICS/TS | DB2 (see note) |
Natural | DB2 (see note) |
IDMS Database | DB2 (see note) |
TCP/IP:
Host Name (required): The TCP/IP address or host name for the connection. This field can contain a hostname string or a TCP/IP address in dot-notation format.
Port Number (required): The port number on which the MAS Mainframe Agent is listening. You can find this number by examining Shadow Server. It is often set to 1200.
Userid: Your mainframe userid. If you don't enter a userid, you are prompted for one at connection time.
Password: Your mainframe password. This is automatically encrypted (both on the screen and in the ODBC.INI file). If you don't enter a password, you are prompted for one at connection time.
LU 6.2:
APPC Type: The APPC type from the drop-down list provided.
Side Info (required): An entry in the Side Info table, which contains the partner LU name, conversation mode, and transaction program name for each side info name value. These values are used to establish an LU 6.2 connection with the host.
Userid: Your mainframe userid. If you don't enter a userid, you are prompted for one at connection time.
Password: Your mainframe password. This is automatically encrypted (both on the screen and in the ODBC.INI file). If you don't enter a password, you are prompted for one at connection time.
WebSphere MQ:
Figure 8. WebSphere MQ connection type
Queue Manager (required): There must be a Queue Manager on both the client and host. Figure 8 shows the client side. If the client, such as Windows 3.1 or Windows for Workgroups, can't support the Queue Manager, you must click Optional to define the WebSphere MQ Client and the MQSERVER (see b).
Output Queue (required): The location where the request is stored until it is sent. There must be an Output Queue. If the Queue Manager is placed on the server, then the Output Queue must be defined on the server.
Userid: Your mainframe userid. If you don't enter a userid, you are prompted for one at connection time.
Password: Your mainframe password. This is automatically encrypted (both on the screen and in the ODBC.INI file). If you don't enter a password, you are prompted for one at connection time.
WebSphere MQ Client: Allows the client to accept MQI calls from an application and communicate with a Queue Manager on a server system.
MQSERVER: The server where the Queue Manager is placed.
You can use this dialog box to set keyword values.
This section discusses syntax for CICS/TX and IMS/TM CALL statements.
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 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
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:
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.)
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:
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
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.
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:
ln -s shadow/lib/libscodbcts.so shadow/lib/libodbc.so ln -s shadow/lib/libscodbcts.so shadow/lib/libodbcinst.so
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
The following is the search order for the odbc.ini file: