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 D, 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 27. 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 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:
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(*))')
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).
|
'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:
|
'MESSAGE LENGTH' | Optional. Specifies the length of the messages that are written to or read from the message queue. The default value is 32k. |
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 [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
The following is the search order for the odbc.ini file: