Microsoft Service for DRDA - Platform Modernization Alliance

Transcription

Microsoft Service for DRDA
Whitepaper
March 2014
(c)2014 Microsoft Corporation. All rights reserved. This document is provided "as-is." Information and
views expressed in this document, including URL and other Internet Web site references, may change
without notice. You bear the risk of using it.
Some examples are for illustration only and are fictitious. No real association is intended or inferred.
This document does not provide you with any legal rights to any intellectual property in any Microsoft
product. You may copy and use this document for your internal, reference purposes.
Contents
Contents ................................................................................................................................................................ 2
Overview ............................................................................................................................................................... 5
Planning ................................................................................................................................................................. 6
Distributed Relational Database Architecture ...........................................................................................................6
Enterprise Single Sign-On ..........................................................................................................................................7
Microsoft SQL Server .................................................................................................................................................7
Architecture ........................................................................................................................................................... 9
Connectivity ...............................................................................................................................................................9
Compatibility ...........................................................................................................................................................11
Administration .........................................................................................................................................................12
Deployment ......................................................................................................................................................... 14
Installing and Configuring Service for DRDA ...........................................................................................................14
Configuring DRDA AR Client Connections ................................................................................................................15
Configuring SQL Server Connections .......................................................................................................................17
SQL Application .......................................................................................................................................................21
Security ....................................................................................................................................................................21
Configuring Database Alias Mappings ....................................................................................................................25
Configuring Package Bind Processing .....................................................................................................................27
Configuring SQL Syntax Transformations ................................................................................................................31
Configuring Data Type Mappings ............................................................................................................................32
Configuring Date Time Conversions ........................................................................................................................32
Configuring Service Encodings.................................................................................................................................36
Configuring Application Encodings ..........................................................................................................................38
Configuring Collation Mapping ...............................................................................................................................39
Configuring Trace Listeners .....................................................................................................................................41
Configuring Enterprise Single Sign-On .....................................................................................................................47
Configuring Microsoft Client Connections ...............................................................................................................48
Configuring DB2 for z/OS ........................................................................................................................................51
Operations ........................................................................................................................................................... 61
Managing DRDA Service..........................................................................................................................................61
Service for DRDA
Microsoft Corporation
Page 2
Connecting DRDA Clients to SQL Server Databases .................................................................................................62
Processing Package Binds .......................................................................................................................................63
Performance ............................................................................................................................................................65
Security and Protection ....................................................................................................................................... 70
Security ....................................................................................................................................................................70
Protection ................................................................................................................................................................72
Troubleshooting .................................................................................................................................................. 80
Trace Listeners .........................................................................................................................................................80
Event Logs ...............................................................................................................................................................80
Data Type Mapping .................................................................................................................................................84
Code Page Mappings ...............................................................................................................................................84
Troubleshooting Tools .............................................................................................................................................84
Solutions to Common Problems ..............................................................................................................................87
Development – Programmer’s Guide ................................................................................................................... 98
Understanding Static SQL for DB2 Custom Packages ..............................................................................................98
Creating Static SQL for DB2 Custom Packages ........................................................................................................98
Calling Static SQL for DB2 Custom Packages ...........................................................................................................99
Converting packages to stored procedures ...........................................................................................................100
Static SQL Package Statements .............................................................................................................................101
DRDA Service Package Bind Options .....................................................................................................................102
DRDA Service Static SQL Cursors ...........................................................................................................................103
Data Type Conversions ..........................................................................................................................................105
Date Time Formats and Conversions .....................................................................................................................109
BLOB and CLOB......................................................................................................................................................110
Error Code Mapping ..............................................................................................................................................110
Development - Programmer’s Reference ........................................................................................................... 112
Locale Encoding .....................................................................................................................................................112
Distributed Relational Database Architecture .......................................................................................................112
PowerShell Module ................................................................................................................................................113
Static SQL for DB2 Custom Packages XML Schema V90 ........................................................................................138
Static SQL for DB2 Custom Packages XML Schema V85 ........................................................................................156
Samples ............................................................................................................................................................. 173
Service for DRDA
Page 3
Custom Listeners ...................................................................................................................................................173
Enterprise Single Sign-On ......................................................................................................................................178
Service for DRDA
Page 4
Overview
The Microsoft Service for DRDA enables DRDA clients, such as IBM DB2 for z/OS, to execute static SQL
statements mapped to SQL Server stored procedures. The DRDA Service provides host-initiated data
integration essential to enterprises during a phased workload migration, or for daily operations in
support of remote batch or business intelligence solutions. The DRDA Service offers the following
features.













Deployed on Windows Server including virtualization with Hyper-V
Respond to DRDA client requests across a TCP/IP network connection
Access SQL Server on local computer or remotely using SqlClient provider
Authenticate in-bound client connections using Enterprise Single Sign-On
Encrypt data using Secure Sockets Layer and Transport Layer Security
Map SQL Server transactions using MSDTC to DB2 DRDA transactions using XA
Convert static SQL statements in DB2 packages to SQL Server stored procedures
Transform dynamic SQL statements in ANSI SQL to SQL Server T-SQL
Map DB2 DRDA data types to SQL Server data types
Encode SQL Server ANSI and UNICODE strings as DB2 EBCDIC
Map SQL Server error codes and text to DRDA reply messages with SQLSTATE and SQLCODE
Configure and administer service using PowerShell module cmdlet commands
Trace connections and commands using Event Tracing for Windows (ETW)
Figure 1. HIS 2013 integrates existing IBM host systems with Microsoft server applications.
The DRDA Service is a feature of Microsoft Host Integration Server 2013 (HIS 2013). Read the HIS 2013
Release Notes and Installation Guide for more information on software prerequisites and installation.
HIS 2013 Release Notes and Installation Guide are posted to the Microsoft Download Center
(http://www.microsoft.com/download/details.aspx?id=39951). HIS 2013 On-Line Documentation is
available on MSDN (http://msdn.microsoft.com/en-us/library/gg241192(v=bts.10).aspx) and TechNet
(http://technet.microsoft.com/en-us/library/gg241192(v=BTS.10).aspx)
Microsoft HIS 2013 is licensed as supplemental software to Microsoft BizTalk Server 2013 (BTS 2013).
HIS 2013 Evaluation Copy is available on the Microsoft Download Center
(http://www.microsoft.com/download/details.aspx?id=39950).HIS 2013 Enterprise Edition is available
on the Microsoft Volume License site. HIS 2013 Developer Edition is available on MSDN
(http://msdn.microsoft.com/subscriptions/downloads) and TechNet
(http://technet.microsoft.com/subscriptions/downloads). Visit the Microsoft Host Integration Server
website (http://www.microsoft.com/hiserver) for more information on HIS 2013 and BTS 2013.
Service for DRDA
Page 5
Planning
Enterprise IT organizations need to deliver new solutions, while increasing developer efficiency and
reducing costs. The DRDA Service offers technology and tools to enable IT professionals and enterprise
developers to deploy new solutions based on Microsoft SQL Server, while connecting existing workloads
based on IBM DB2.
Figure 2. Connecting IBM DB2 client programs via the DRDA Service to Microsoft SQL Server databases.
Distributed Relational Database Architecture
IBM DB2 clients and servers communicate using Distributed Relational Database Architecture (DRDA)
protocol and formats. The DRDA Service functions as a DRDA Application Server (AS) to enable DRDA
Application Requester (AR) clients to interact with Microsoft SQL Server databases. The DRDA Service
supports a limited set of DRDA code points as defined in the architecture references published by The
Open Group (http://www.opengroup.org).



DRDA, Version 5, Volume 1: Distributed Relational Database Architecture (DRDA)
DRDA, Version 5, Volume 2: Formatted Data Object Content Architecture (FD:OCA)
DRDA, Version 5, Volume 3: Distributed Data Management (DDM) Architecture
You can download DRDA V5 Vol. 3: Distributed Data Management Architecture, publication number
C114, from The Open Group bookstore (http://go.microsoft.com/fwlink/?LinkID=219127).
IBM DB2 DRDA Clients and Servers
Microsoft, IBM, and third-party vendors implement DRDA protocols and formats in various DRDA
Application Requester (AR) client technologies. The DRDA Service supports in-bound connections from
DRDA AR clients that conform to the DRDA Version 5 standard, including DRDA ARs in these IBM
products.


IBM DB2 for z/OS V9.1 and V10
IBM DB2 for i5/OS V6R1 and V7R1
Service for DRDA
Page 6

IBM DB2 for Windows, AIX, HP-UX, Solaris, Linux V9.7 and V10
Microsoft DRDA Client for DB2
Microsoft HIS 2013 includes a DRDA Application Requester client designed to connect to remote IBM
DB2 database server, supporting a subset of DRDA Version 5.0.
 Microsoft ODBC Driver for DB2
 Microsoft OLE DB Provider for DB2
 Microsoft ADO.NET Framework Data Provider for DB2
 Microsoft BizTalk Adapter for DB2
 Microsoft Entity Framework Provider for DB2
Enterprise Single Sign-On
Microsoft Enterprise Single Sign-On is a technology included with HIS 2013 and BTS 2013 to map
Windows credentials for foreign credentials (e.g. IBM RACF username) to enable single sign-on
solutions. Optionally, the DRDA Service can utilize Microsoft Enterprise Single Sign-On to map in-bound
host credentials (e.g. RACF user authorization identifier) to out-bound Windows Active Directory (AD)
credentials, allowing the DRDA Service to connect to SQL Server using Integrated Security.
Figure3. Enterprise Single Sign-One enabled the DRDA Service to map inbound DRDA credentials to
outbound SQL Server credentials.
Host-initiated ESSO requires elevated permissions in Active Directory (Kerberos constrained delegation,
and Use any authentication protocol). ESSO requires a Kerberos Service Principal Name for the SQL
Server computer to which the DRDA Service connects. For more information on ESSO, see
Understanding Enterprise Single Sign-On (http://msdn.microsoft.com/enUS/library/aa754070(v=BTS.10).aspx).
Microsoft SQL Server
Enterprise administrators and developers rely on Microsoft SQL Server to build mission critical data
platforms for line-of-business applications. SQL Server helps enterprises to unlock new insights through
data discovery across the organization while providing tools consistent data and large scale analytics and
Service for DRDA
Page 7
data warehousing. The DRDA Service can connect existing IBM host workloads to new solutions based
on Microsoft SQL Server to enable heterogeneous enterprise applications and business intelligence.
The DRDA Service relies on the Microsoft SQL Server network client and ADO.NET Framework Data
Provider for SQL Server for connectivity and data access to SQL Server databases. For more information
on Microsoft SQL Server, see http://www.microsoft.com/sql.
Windows Operating Systems
The DRDA Service requires one of the following Microsoft operating systems (32-bit x86 or 64-bit x64).








Microsoft Windows® 8.1
Microsoft Windows 8
Microsoft Windows 7 SP1
Microsoft Windows Server® 2012 R2
Microsoft Windows Server 2012
Microsoft Windows Server 2008 R2 SP1
Virtualization with Hyper-V®
Virtualization with Windows Azure™
Prerequisite Software
The DRDA Service requires the following software products as installation prerequisites.




Microsoft .NET Framework 4.0 (http://www.microsoft.com/enus/download/details.aspx?id=17851)
Microsoft PowerShell 3.0 (Windows Management Framework 3.0)
(http://www.microsoft.com/en-us/download/details.aspx?id=34595)
Microsoft Visual C++ 2010 Service Pack 1 Redistributable Package (x86)
Microsoft Visual C++ 2010 Service Pack 1 Redistributable Package (x64)
Note: When installing on a 64-bit (x64) operating system, you must install both x86 and x64 of Visual
Studio 2010 Service Pack 1 C++ Runtime packages.
Service for DRDA
Page 8
Architecture
The DRDA Service enables connectivity from a remote IBM DB2 client program and a local Microsoft SQL
Server database, by providing compatibility services based on the industry-standard DRDA (Distributed
Relational Database Architecture) that defines DB2 client-to-server communications in the form of a set
of protocol code points and formats. The DRDA Service operates within the DRDA as an Application
Server (AS). The IBM DB2 client programs (e.g. COBOL TOS and CICS for z/OS) are locally-attached to DB2
for z/OS and functions within the DRDA as Application Requester (AS) clients. The DRDA Service is a
Windows service program that hosts an instance of the Microsoft .NET Framework, connects to a local
or remote Microsoft SQL Server using the Microsoft ADO.NET Framework Data Provider for SQL Server
and underlying Microsoft SQL Server network client.
Figure 4. DRDA Service connects IBM DB2 for z/OS to Microsoft SQL Server.
Connectivity
DRDA Protocol and Formats
The DRDA Service converts DRDA code points and data formats into corresponding Microsoft ADO.NET
connections, transactions, commands, data types, and error objects. The primary function of the DRDA
Service is to functionally map static SQL for DB2 packages and statement execution to Microsoft SQL
Server stored procedure and CALL statements. The DRDA Service processes the DRDA protocol flows as
defined within the architecture based on the various DRDA managers.
Network transports and transactions
The DRDA Service supports in-bound authenticated DRDA client connections across a TCP/IP network.
The DRDA Service does not support SNA APPC over LU6.2 using HPR/IP (High Performance Routing over
Internet Protocol). To connect to SQL Server, the DRDA Service uses an underlying Microsoft ADO.NET
Provider for SQL Server and SQL network client, supporting in-memory, named pipes, and TCP/IP
network connections.
By default, the DRDA Service will listen on the default DRDA port 446 for in-bound connections,
accepting any DRDA client connection request. Optionally, the DRDA Service can listen on another preconfigured port number. Also, to improve security, the DRDA Service can be configured to accept inbound connection requests from a pre-defined list of remote network addresses.
Service for DRDA
Page 9
To enable reliable updates across the network, the DRDA Service supports DRDA DUW (Distributed Unit
of Work) two-phase commit transactions. The DRDA DUW transactions are mapped to SQL Server
transactions through the Microsoft ADO.NET Framework Data Provider for SQL Server and underlying
SQL network client.
Pooling and load balancing
The DRDA Service supports the SQL client connection pooling through configuring the SQL client pooling
options in the SQL Server connection string arguments in the DRDA Service app config. Also, the DRDA
Service offers an internal connection pool, mapping in-bound DRDA AR client connections and
authentication credentials to out-bound SQL Server database connections and credentials.
Figure 6. DRDA Service primary and partner server work together for load balancing.
The DRDA Service can operate in groups of two (2) servers, one per computer, to provide basic fault
tolerance. When a DRDA AR client connects to a SQL Server database (DSN1), the DRDA Service (SRV1)
returns a DRDA SRVLST (Server List) with a weighted list of Data Server instances (DSN1 on SRV1 and
DSN1 on SRV2). In case of failover of a primary DRDA Service (SRV1), the DRDA AR can use this
information to connect to the partner member (SRV2) of a pair of DRDA Service computers.
Authentication and encryption
To secure information, the DRDA Service supports common DRDA authentication and data encryption
technologies. For example, the DRDA Service can support basic authentication (plain text EBCDICencoded username with password) or secure authentication using 256-bit Advanced Encryption
Standard (AES). Also, the DRDA Service can support combined authentication and encryption using
Secure Sockets Layer (SSL) V3.0 or Transport Layer Security (TLS) V1.0.
To provide integrated authentication, the DRDA Service can combine in-bound credential validation and
mapping using Microsoft Enterprise Single Sign-On (ESSO), with out-bound SQL Server authentication
using Windows SSPI (Security Support Provider Interface). For example, the DRDA Service can work with
ESSO to map an IBM RACF (Resource Access Control Facility) username and password to a Microsoft
Windows Active Directory domain\username, with which to connect with integrated security to a
remote SQL Server database.
Service for DRDA
Page 10
Compatibility
Static and Dynamic SQL
Primarily, the DRDA Service enables DB2 client programs to execute remotely-defined static SQL for DB2
packages, by mapping the package statements to SQL Server stored procedures. For example, when a
DB2 administrator or programmer bind copies a DB2 package to SQL Server, the DRDA Service converts
the DRDA BNDSQLSTT (Bind SQL Statement) flows into SQL Server T-SQL CREATE PROCEDURE
statements. When the DB2 program executes the remote package statement, the DRDA Service
converts the DRDA OPNQRY (Open Query) or EXCSQLSTT (Execute SQL Statement) into a CALL
statement.
Secondarily, the DRDA Service supports limited dynamic SQL operations to allow DB2 client programs to
execute remote SQL Server T-SQL commands. For example, a DB2 administrator can utilize QMF (Query
Management Facility) for z/OS to query a remote SQL Server table.
SQL Syntax
The DRDA Service has a limited DB2 ANSI to SQL Server T-SQL command syntax transformer that it
utilizes for binding packages, executing static and dynamic SQL statements. Optionally, the DRDA Service
offers additional compatible DB2 functions in the form of SQL Server CLR-based functions.
The DRDA Service offers a replaceable package bind component for processing DRDA BNDSQLSTT (Bind
SQL Statement) to SQL Server T-SQL CREATE PROCEDURE statements. For example, an ISV (Independent
Software Vendor) or enterprise developer can implement a custom-defined package binding component
to support syntax, data type, encoding, or other required conversions.
Catalog and schema names
The DRDA Service offers basic mapping of high-level object identifiers, including catalog and schema
names. For example, the DRDA Service can map an in-bound DRDA RDBNAM (Relational Database
Name) to an out-bound SQL Server database name. Also, the DRDA Service can map an in-bound DRDA
COLLID (Collection Identifier) to an outbound SQL Server schema name.
Data type conversion
To support cross platform interoperability between SQL Server databases running on Windows
operating systems and DB2 servers running on z/OS and i5/OS, the DRDA Service offers a set of data
type mappings and conversions defined in XML files (DB2ToMSSql.xml and MSSQLToDB2.xml). For
example, the DRDA Service can maps and will convert in-bound DB2 DECIMAL to out-bound SQL Server
money.
String encodings
The DRDA Service supports converting from DB2 EBCDIC string encodings to SQL Server ANSI and
UNICODE encodings. Optionally, the DRDA Service supports modified replaceable Windows EBCDIC-toUNICODE NLS (National Language Support) conversion files. Also, the DRDA Service offers in-line
character replacement based on a pre-defined map using CCSID (Coded Character Set Identifier)
hexadecimal value pairs.
Datetime formatting
The DRDA Service offers in-line DB2 DATE/TIME/TIMESTAMP to SQL Server date/time/datetime2 format
and string literal value conversions. For example, the DRDA Service can convert an in-bound DB2
Service for DRDA
Page 11
formatted TIMESTAMP string literal value in the form YYYY-MM-DD-hh.mm.ss.tttttt to an out-bound SQL
Server datetime2(6) value in the form YYYY-MM-DD hh:mm:ss.tttttt.
Administration
An administrator can configure the DRDA Service by modifying the MsDrdaService.exe.config file, along
with ancillary XML files (data types and error mapping), prior to starting the DRDA Service. Optionally,
the DRDA Service offers immediate reading of the MsDrdaService.exe.config to enable dynamic
configuration updates.
Configuration
IT professionals can specify all required DRDA Service configuration settings by running the interactive
or unattended installation program. See topic titled “To install the product”. See also, topic titled “To
install the product unattended”.
Post-installation, IT professionals can customize the DRDA Service configuration by editing the
MsDrdaService.exe.config file and updating other XML files. The following is a listing of DRDA Service
components, configurable items, and configuration stores.
Component
Items
Configuration Store
DRDA Service
Service Credentials
Windows Registry
Security Policy Rights
MsDrdaService.exe.config
Connection Manager
MSDRDAErrorMappings.xml
Security Manager
SQL Access Manager
Database Manager
Data Conversion
Data Type Mappings
Date, Time, DateTime Formats
DB2ToMSSql.xml
MSSQLToDB2.xml
Code Page Conversion
Bind Listeners
Custom Code Pages
Windows Registry
Code Point Mappings
Default
Custom
Trace Listeners
Text Listener
Console Listener
ETW Listener
Custom
Service for DRDA
Page 12
Component
Items
Configuration Store
Event Log
Events
Application Log
Performance Monitor
Counters
Windows Registry
Table 1. Configurable DRDA Service components, items, and configuration stores.
PowerShell
Windows PowerShell® is a task-based command-line shell and scripting language designed especially for
system administration. Built on the .NET Framework, Windows PowerShell helps IT professionals and
power users control and automate the administration of the Windows operating system and
applications that run on Windows. The DRDA Service offers a PowerShell module,
Microsoft.HostIntegration.PowerShell, with a number of Cmdlet commands to add/get/remove/set
MsDrdaService.exe.config elements and attributes, as well as commands to start/stop listeners.
Tracing
The DRDA Service supports multiple trace options console listener tracing, text listener tracing, event log
listener, ETW (Event Trace for Windows) listener, ETW (Event Tracing for Windows) listener, and custom
tracing. The administrator uses the console tracing when running the DRDA Service in Windows console
mode, to output trace data to the screen. The administrator uses text tracing when running the DRDA
Service in Windows service mode or console mode, to output trace data to a text-readable file. The
DRDA Service automatically posts event log listener trace items to the Windows Event Log. The
administrator uses ETW tracing for high speed data collection. Optionally, the enterprise developer can
implement a custom trace listener to output all or selected trace data to another component.
Accounting and logging
The DRDA Service supports the standard DRDA accounting code points: Client Workstation Name; Client
User ID; Client Application Name; and Client Accounting. An enterprise developer can specify dynamic
values in their program with which to populate the DRDA client accounting properties. The DRDA Service
reads the values at runtime to populate the DRDA Service trace, allowing correlation of problems to
specific application and user context. Optionally, the enterprise developer can implement a DRDA
Service customer trace listener with which log DRDA AR client requests. For example, a customer trace
listener can log selected network and database access, based on a client account value, to a remote SQL
Server logging database.
Error mapping
The DRDA Service returns SQL Server errors in the form of either a DRDA code point Reply Message
(RM) or DRDA SQLCARD (SQL Communications Area Reply Data). By default, for common issues, the
DRDA Service uses a built-in table to map SQL error codes and error strings to DRDA reply messages and
errors. Also, the DRDA Service uses an external MsDrdaErrorMappings.xml file to map from SQL Server
error code and error text to SQLCODE, SQLSTATE, Reason Code, and Error Message.
Service for DRDA
Page 13
Deployment
The HIS 2013 setup and configuration wizard provide installation and basic configuration of the DRDA
Service. IT professionals will modify the MsDrdaService.exe.config application configuration file and
PowerShell module cmdlet commands to further configure and administer the DRDA Service.
Installing and Configuring Service for DRDA
To install the DRDA Service, use the HIS 2013 “server” setup program and configuration wizard. The HIS
2013 setup and configuration wizard support both interactive and command-line operations for install,
configure, and removal of the DRDA Service software as a feature of HIS 2013. See the HIS 2013 Release
Notes, Installation Guide, and on-line help for more information. HIS 2013 Release Notes and
Installation Guide are posted to the Microsoft Download Center
(http://www.microsoft.com/download/details.aspx?id=39951).HIS 2013 On-Line Documentation is
available on MSDN (http://msdn.microsoft.com/en-us/library/gg241192(v=bts.10).aspx) and TechNet
(http://technet.microsoft.com/en-us/library/gg241192(v=BTS.10).aspx)
Service Credentials
Using Windows Services Microsoft Management Console (MMC) snap-in, you can change the account
name and password in which context to run the DRDA Service (C:\Program Files\Microsoft Host
Integration Server 2013\system\MsDrdaService.exe). The configuration is stored in the Windows
registry.
1. On the Start menu, point to All Programs, point to Administrative Tools, and click Computer
Management.
2. In the Computer Management (local) settings pane, navigate to Services under Services and
Applications.
3. In the Service pane, double click Microsoft Service for DRDA.
4. In the Microsoft Service for DRDA Properties (local) dialog, click Log On.
5. In the Log On dialog, click This account. Type a computer_name\user_name or
domain_name\user_name. Optionally, click Browse to select a local or domain account.
Note: When ESSO to map foreign credentials to AD credentials, this log on service account must be a
member of the SSO Affiliate Administrators group.
6. Type a corresponding password in the Password and Confirm password edit boxes. Click OK to
continue.
Note: You must stop and re-start the service in order for the new credentials to utilize the newlyentered log service credentials.
Service Security Policy Rights
Using the Windows Policy Editor Microsoft Management Console (MMC) snap-in, you can change policy
objects associated with the MsDrdaService and credentials. The MsDrdaService requires the Log on as a
service policy rights.
Service for DRDA
Page 14
This security setting allows a security principal to log on as a service. Services can be configured to run
under the Local System, Local Service, or Network Service accounts, which have a built in right to log on
as a service. Any service that runs under a separate user account must be assigned the right.
Application Configuration File
The DRDA Service configuration is stored in the MsDrdaService.exe.config application configuration (app
config) file, and associated XML files (error message mapping and data type mapping). At runtime, the
DRDA Service will monitor the MsDrdaService.exe.config file for changes. When detected, the DRDA
Service will read and utilize the changed configuration information when processing new in-bound
connections.
Post-installation, IT professionals can customize the DRDA Service configuration by editing the
MsDrdaService.exe.config application configuration (app config) file using an XML editor and the
associated %SNAROOT%\System\Schemas\HostIntegrationDrdaServiceConfiguration.xsd file.
Configuring DRDA AR Client Connections
The DRDA Service handles communication with DRDA AR clients across TCP/IP network connections. The
DRDA Service supports optional encryption and failover features to improve security and reliability. You
can edit the MsDrdaService.exe.config file to instruct the DRDA Service on how to manage the DRDA AR
client connections. The connectionManager element of the MsDrdaService.exe.config file contains the
network, security and failover settings for managing in-bound DRDA client connections. The
connectionManager type is the Microsoft.HostIntegration.Drda.Server.TcpConnectionManager, which
supports in-bound DRDA AR client connections across a TCP/IP network connection.
Network
The DRDA Service listens and responds to in-bound TCP/IP network connections on a specified network
port.
TCP/IP Listener Port
The port attribute defines the TCP/IP Port number on which the DRDA Service must listen for in-bound
DRDA Application Requester client connection requests. This optional attribute accepts an integer
value. The default value is 446. If you specify a port different from the default DRDA port 446, then
DRDA clients must specify the non-default port number in requests to the computer or they will not
connect to the DRDA Service.
Transaction Log Synchronization IP Address
The resyncIpAddress attribute instructs the DRDA Service the TCP/IP address to send to the DRDA Client
in the DRDA Access Relational Database Reply Message (ACCRDBRM), following a successful data
connection to the target SQL Server database. The DRDA Client uses the resyncIpAddress value and the
configured port value to establish a transaction log synchronization connection. This optional attribute
accepts a string value. The default value is an empty string, which instructs the DRDA Service to return
the TCP/IP address used by the DRDA Client on the data connection.
Transaction Log Synchronization Port
The DRDA Service listens for in-bound DRDA Client transaction log synchronization connections on the
same TCP/IP Listener Port used for in-bound DRDA Client data connections. See TCP/IP Listener Port for
more information.
Service for DRDA
Page 15
Security
The DRDA Service supports Secure Sockets Layer 3.0 (SSL) and Transport Layer Security 1.0 (TLS) to
encrypt the authentication and data between DRDA AR client and DRDA Service.
Client IP Addresses Allowed
The clientIpAddressesAllowed attribute restricts the DRDA Service to accepting in-bound TCP/IP
network connections from a list of known DRDA AR client computers. This optional attribute accepts a
string value. The default value is an empty string, which allows the DRDA Service to respond to all inbound client connection requests. The list is comprised of a TCP/IP address or alias semi-colon
delimited. The TCP/IP address can be defined in either IPv4 or IPv6 format. For example, 123.34.45.57;
123.34.45.58 defines a valid client list in IPv4 network address format.
Secure Sockets Layer and Transport Layer Security
The useSSL attribute instructs the DRDA Service to use Secure Sockets Layer (SSL) Version 3.0 and
Transport Layer Security (TLS) Version 1.0 when responding to in-bound TCP/IP network connections.
This optional attribute accepts a Boolean value. The default value is false.
The sslCertificatePath attribute specifies the SSL or TLS certificate contained in an X.509 certificate file,
including file path, file name, and file extension. This optional attribute is required when useSSL=true,
and accepts a string value. The default value is an empty string. For example, “c:\testdir\testssl.cer” is a
fully-qualified file path and file name with file extension containing information for a X.509 certificate.
For more information on certificates, see http://technet.microsoft.com/en-us/library/cc754122.aspx.
Failover
The DRDA Service can operate within a group to provide fault tolerant failover. The group is defined by
specifying a local service role (primary or secondary), available failover partner servers, and a ping
interval for monitoring the health of servers within a group.
Primary Server
The isPrimary attribute instructs the DRDA Service whether to operate in a primary role within a group
of servers. This optional attribute accepts a Boolean value. The default value is true. The primary server
will respond to all DRDA AR client requests by processing EXCSAT (Exchange Server Attributes), ACCSEC
(Access Security) and ACCRDB (Access Relational Database), including returning a SRVLST (Server List) on
the ACCRDBRM (ACCRDB Reply Message). The Server List contains a weighted priority list of primary
(highest weighted value) and secondary servers (lowest weighted values), to inform the DRDA AR clients
to which DRDA Service computer to connect.
Partner Servers
The partnerServers attribute defines the list of secondary server computers. This optional attribute is
required when isPrimary=false, and accepts a string value. The default value is an empty string. The list
is comprised of a TCP/IP address or alias colon-separated by a TCP/IP port number. The TCP/IP address
can be defined in either IPv4 or IPv6 format. The list can contain multiple partner server computers
semi-colon delimited. For example, 123.34.45.57:446; 123.34.45.58:446 defines a valid partner server
list in IPv4 network address format.
Service for DRDA
Page 16
Ping Interval
The pingInterval attribute instructs the DRDA Service how frequently to monitor the health of partner
server computers, by executing an EXCSAT (Exchange Server Attribute) flow and checking for an
EXCSATRD (EXCSAT Reply Data). This optional attribute accepts an integer value. The default value is
10000 milliseconds (10 seconds).
Performance
The DRDA Service supports Windows Performance Monitor.
Performance Monitors Counters
The peformanceCountersOn attribute instructs the DRDA Service to collect information into
performance counters. This optional attribute accepts a Boolean value. The default value is false. See
the Performance topic in the Operations book for more information.
Configuring SQL Server Connections
The DRDA Service communicates to upstream local or remote SQL Server databases using the ADO.NET
Framework Provider for SQL Server. The underlying SQL Client access SQL Server via an in-memory
connection, or across a network using either Named Pipes or TCP/IP. The SQL Client supports optional
encryption and failover features to improve security and reliability. The DRDA Service supports optional
single sign-on and pooling features to improve security and performance. You can edit the
MsDrdaService.exe.config file to instruct the DRDA Service on how to manage the SQL client to SQL
Server connections.
Network
The DRDA Service connects to SQL Server through the Microsoft ADO.NET Framework Provider for SQL
Server and underlying SQL Client. The database element of the MsDrdaService.exe.config file contains
the network settings for managing out-bound SQL client connections. The database type is the
Microsoft.HostIntegration.Drda.RDB.SqlDatabase, which defines the network settings for out-bound SQL
client connections.
Connection String
The connectionString attribute defines the list of argument name and value pairs for use by the DRDA
Service in defining a Microsoft ADO.NET Framework Data Provider for SQL Server connection object.
This required attribute accepts a string value. The default value is Data Source=localhost;Integrated
Security=true;MultipleActiveResultSets=true.
Item
Description
Application Name
The Application Name property instructs the SQL Client the name
of the application to associate with the connection. This optional
property accepts a string value. The default value is an empty
string.
Service for DRDA
Page 17
Item
Description
Connect Timeout
The Connect Timeout property instructs the SQL Client the length
of time (in seconds) to wait for a connection to the server before
terminating the attempt and generating an error.
This optional property accepts an integer value. Valid values are
greater than or equal to 0 and less than or equal to
2147483647.The default value is 15 seconds.
Data Source
The Data Source property defines the name or network address of
the instance of SQL Server to which to connect using TCP/IP or
Named Pipes. This required property accepts a string value. The
default value is an empty string.
For TCP/IP, the formatted value starts with a “tcp:” prefix,
followed by a TCP/IP alias or address in IPv4 or IPv6 format,
followed by a backslash-separated SQL Server instance name or
comma-separated TCP/IP port number.

tcp:<host name>\<instance name>

tcp:<host name>,<TCP/IP port number>
For Named Pipes, the formatted value starts with an “np:” prefix,
followed by a host name and named pipe name.

np:\\<host name>\pipe\<pipe name>
Encrypt
The Encrypt property instructs the SQL Client to use Secure
Sockets Layer (SSL) to encrypt all data sent between SQL Client
and SQL Server. This optional property accepts a Boolean value of
true, false, yes, and no. The default value is false.
Failover Partner
The Failover Partner property informs the SQL Client of the name
of the SQL Server where database mirroring is configured. This
optional property accepts a string value. The default value is an
empty string.
Initial Catalog
The Initial Catalog property instructs the SQL Client to which
database to connect. This optional property accepts a string value
of up to 128 characters. The default value is an empty string.
Service for DRDA
Page 18
Item
Description
Integrated Security
The Integrated Security property instructs the SQL Client to
connect to SQL Server using Windows Authentication through the
Security Support Provider Interface (SSPI). This optional property
accepts a Boolean value of true, false, yes, and no. The default
value is false.
When this property value is true or yes, the DRDA Service will
connect to SQL Server using Windows Authentication.

Connection credentials are derived from the running
MsDrdaService.exe (service account or logged in user
when running from command line).

Connection credentials are derived from Enterprise Single
Sign-On service, when the separate Affiliate Application
argument is specified with a value. See topic on Affiliate
Application for more information.
When this property value is false or no, the DRDA Service will
connect to SQL Server using SQL Server Authentication.

Connection credentials are derived from the User ID and
Password arguments in the ConnectionString.

Connection credentials are derived from the DRDA
Application Requester Data Client, when User ID and
Password arguments are not present.
Note: You must specify false, when using Windows-initiated
Enterprise Single Sign-On and Mapped Authentication Domain
features.
Max Pool Size
The Max Pool Size property defines the maximum number of
connections the SQL Client should retain in the connection pool.
This optional property accepts an integer value. The default value
is 100.
MultipleActiveResultSets
The MultipleActiveResultSets property instructs SQL Server to
maintain multiple maintain multiple active result sets (MARS),
including open server cursor objects. This required property
accepts a Boolean value of true, false, yes, and no. The default
value is true.
Note: The DRDA Service requires MARS to support server cursors
created by static SQL CURSOR WITH HOLD statements.
Service for DRDA
Page 19
Item
Description
Network Library
The Network Library property instructs the SQL Client to connect
to SQL Server using shared memory or TCP/IP. This optional
property accepts a string value of dbmslpcn (Shared Memory),
dbnmpntw (Named Pipes), or dbmssocn (TCP/IP). The default
value is dbmslpcn.
Packet Size
The Packet Size property defines the size in bytes of the network
packets the SQL Client will use to communicate with an instance of
SQL Server. This optional property accepts an integer value, of
512 to 32676. The default value is 8192.
Password
The Password property defines the value for login password when
the SQL Client uses SQL Server Authentication. This optional
property accepts a string value of up to 128 characters. The
Pooling
The Pooling property instructs the SQL Client to add newly created
connections will be added to the pool when closed by the DRDA
Service. In a next attempt to open the same connection, with the
same connection string property values, that connection will be
drawn from the pool. This optional property accepts a Boolean
value of true, false, yes, and no. The default value is false.
TrustServerCertificate
The TrustServerCertificate instructs the SQL Client to encrypt the
channel when bypassing walking the certificate chain to validate
trust. This optional property accepts a Boolean value of true,
false, yes, and no. The default value is false.
User ID
The User ID property defines the value for login user ID when the
SQL Client uses SQL Server Authentication. This optional property
accepts a string value of up to 128 characters. The default value is
an empty string.
Workstation ID
The Workstation ID property defines the name of the workstation
when connecting to SQL Server. This optional property accepts a
string value of up to 128 characters. The default value is an empty
string.
Table 2. DRDA Service supports these SqlClient Connection String argument names and values.
For more information, see SqlClient provider SqlConnection.ConnectionString property
(http://msdn.microsoft.com/library/system.data.sqlclient.sqlconnection.connectionstring.aspx).
Client Application Name
The clientApplicationName attribute instructs the DRDA Service how to set the SQL Client Application
Name connection property. This optional attribute accepts a string value. The default value is
Service for DRDA
Page 20
externalName, which is the DRDA External Name (EXTNAM) representing the name of the job, task or
process of the DRDA AR client program. Optionally, specify a value of transactionIdentifier, which is
bytes 5-8 of the EXTNAM representing the name of the transaction identifier of the DRDA AR client
program when running in CICS for z/OS.
Stored Procedure CALL Timeout
The storedProcedureCallTimeout attribute instructs the DRDA Service the length of time (in seconds) to
wait for SQL Server to process a CALL statement to execute a stored procedure, before terminating the
attempt and generating an error. This optional attribute accepts an integer value. Valid values are
greater than or equal to 0 and less than or equal to 2147483647. A value of 0 indicates no limit (an
attempt to execute a command will wait indefinitely). The default value is 30 seconds.
Note: This timeout value is the cumulative time-out for all network reads during command execution or
processing of the results. A timeout can still occur after the first row is returned, and does not include
user processing time, only network read time.
SQL Application
The sqlApplicationManager element of the MsDrdaService.exe.config file contains the application
settings for managing out-bound SQL client connections. The sqlApplicationManager type is the
Microsoft.HostIntegration.Drda.Server.SqlApplicationManager, which processes the out-bound SQL
client connections.
Rollback Transaction on Error
The rollbackTransactionOnError attribute instructs the DRDA Service to execute a ROLLBACK following a
negative SQL Server database error. This optional attribute accepts a Boolean value. The default value is
true.
Note: Setting this value to false may provide compatibility with custom programs attached to DB2 for
z/OS. However, setting this value to false may break compatibility with standard open platform (e.g.
ODBC) DRDA application requester clients, such as IBM DB2 Connect JDBC Driver.
Security
The DRDA Service processes authentication of in-bound TCP/IP network connections. The DRDA Service
supports optional encryption and single sign-on features to improve security and performance. The
securityManager element of the MsDrdaService.exe.config file contains the security settings for
managing in-bound DRDA client connections. The securityManager type is the
Microsoft.HostIntegration.Drda.Server.SecurityManager, which processes authentication of in-bound
TCP/IP network connections.
ESSO Host-Initiated Affiliate Application
The hostInitiatedAffiliateApplication attribute defines the Affiliate Application name that the DRDA
Service should use with Microsoft Enterprise Single Sign-On to map the in-bound DRDA AR client
credentials to a Windows Active Directory domain user, when the SQL Client uses Windows
Authentication. This optional property accepts a string value. The default value is an empty string,
which instructs the DRDA Service to not use host-initiated ESSO.
Service for DRDA
Page 21
Note: When using host-initiated ESSO, you must specify Integrated Security=true in the SQL Server
connection string.
Affiliate applications are logical entities that represent a system or sub-system such as a host, back-end
system, or IBM DB2 database client. Contact your SSO administrator for the SSO Affiliate Application
name. For more information, see Understanding Enterprise Single Sign-On
(http://msdn.microsoft.com/en-US/library/aa754070(v=BTS.10).aspx).
ESSO Windows-Initiated Affiliate Application
The windowsInitiatedAffiliateApplication attribute defines the Affiliate Application name that the DRDA
Service should use with Microsoft Enterprise Single Sign-On to map the Windows Active Directory
domain user to an out-bound SQL Client credentials, when the SQL Client uses SQL Server
Authentication. This optional property accepts a string value. The default value is an empty string,
which instructs the DRDA Service to not use Windows-initiated ESSO.
Optionally, specify a value of isRdbName to instruct the DRDA Service to retrieve SQL Server database
connection information from Windows-initiated Affiliate Application mapping records. For example, the
mapping record can contain an Initial Catalog argument value pair, instructing the DRDA Service to
dynamically re-direct the connection to an alternate SQL Server database. By default, the DRDA Service
connects to the SQL Server database using the DRDA client-to-server connection information—RDBNAM
(Relational Database Name) field in the DRDA client-to-server ACCRDB (Access Relational Database)
protocol flow. To use this feature, the ESSO Administrator creates a Windows-initiated Affiliate
Application with the same name as the expected in-bound DRDA RDBNAM value, defining the Affiliate
Application to contain a third field (Username, Password, “ConnectionString”), and then including in the
user credential mapping the SQL Server connection string argument value pairs. In this example, the
original RDBNAM value might be “SQL1” with corresponding Affiliate Application named “SQL1”. The
user credential mapping for “USER1” might contain “MS$SAME” for Username and Password fields, and
then “Initial Catalog=”SQLALT1” for the ConnectionString field—instructing the DRDA Service to
dynamically re-route connection requests from USER1 for database SQL1 to alternate SQL Server
database named SQLALT1.
Note: When using Windows-initiated ESSO, you must specify Integrated Security=false in the SQL Server
connection string.
Affiliate applications are logical entities that represent a system or sub-system such as a host, back-end
system, or IBM DB2 database client. Contact your SSO administrator for the SSO Affiliate Application
name. For more information, see Understanding Enterprise Single Sign-On
(http://msdn.microsoft.com/en-US/library/aa754070(v=BTS.10).aspx).
Security Token Timeout
The DRDA Service will cache the security token obtained from Microsoft Enterprise Single Sign-On and
Mapped Authentication Domain features for a configured duration of time, with which to use when
connecting to SQL Server configured for Windows authentication using integrated Security Support
Provider Interface (SSPI).
The securityTokenTimeout attribute instructs the DRDA Service to retain a security token for a duration
of time, after which to obtain a new Windows Client Identifier (CID). This optional attribute accepts a
Service for DRDA
Page 22
duration value. The default value is PT8H (Period of Time is 8 hours). The duration value is specified in
the form PnYnMnDTnHnMnS.
Item
Description
P
Period of time for the duration (required)
nY
Number of years.
nM
Number of months.
nD
Number of days.
T
Start of a time section (required to specify a time duration consisting of hours, minutes, or
seconds).
nH
Number of hours.
nM
Number of minutes.
S
Number of seconds.
Table 3. Duration of time expressed in XML format.
Mapped Authentication
The mappedAuthenticationDomain attribute instructs the DRDA Service to which Microsoft Windows
Active Directory domain to map the in-bound DRDA client credentials (user name and password), when
Provider Interface (SSPI), but not when using Microsoft Enterprise Single Sign-On. This optional attribute
accepts a string value. The default value is an empty string.
Note: The Mapped Authentication Domain security authentication requires the following additional
configuration.
SQL Server Database Connection
The Integrated Security argument in the SQL Server connection string must be set to a value of true.
The hostInitiatedAffiliateApplication attribute within the database element of the
MsDrdaService.exe.config file must be set to a value of empty string. You cannot utilize host-initiated
ESSO concurrently with Mapped Authentication Domain security authentication.
Windows Security for the DRDA Service Account
The MsDrdaService.exe must run in the context of a domain user account (Domain\User).
The service account must be a member of the HIS Administrators and HIS Runtime Users Local Groups.
Local Security Policy
The service account requires these Local Security Policy settings to run as a service:

The service account requires Log on as a service.

The service account requires Act as part of the operating system.
Service for DRDA
Page 23

The service account requires Access Credential Manager as a trusted caller.

The service account requires Enable computer and user accounts to be trusted for delegation.
DB2 for z/OS Connection Database (CDB)
Table
Column
Value
Description
SYSIBM.IPNAMES
SECURITY_OUT
P
The value “P” denotes password with
authorization identifier.
SYSIBM.IPNAMES
USERNAMES
O
The value “O” denotes outbound identifier from
SYSIBM.USERNAMES table.
SYSIBM.USERNAMES
TYPE
O
The value “O” denotes outbound translation.
SYSIBM.USERNAMES
AUTHID
<string> The string value is the Windows Active Directory
domain user name.
SYSIBM.USERNAMES
PASSWORD
<string> The string value is the Windows Active Directory
domain password.
Table 4. DB2 for z/OS Connection Database settings required to support Mapped Authentication Domain
security authentication.
Authentication Lookup Timeout
The authenticationLookupTimeout attribute instructs the DRDA Service the duration of time to wait for
a security authentication lookup request before failing. This optional attribute accepts a duration value.
The default value is PT30S (Period of Time is 30 seconds). The duration value is specified in the form
PnYnMnDTnHnMnS.
Item
Description
P
nY
Number of years.
nM
Number of months.
nD
Number of days.
T
seconds).
nH
Number of hours.
nM
Number of minutes.
S
Number of seconds.
Service for DRDA
Page 24
Authentication Lookup Retries
The authenticationLookupRetries attribute instructs the DRDA Service the number of times to attempt
a security authentication lookup request before failing. This optional attribute accepts an integer value.
The default value is 3 retries.
SET Statements
Server and underlying SQL Client. The sqlSet element of the MsDrdaService.exe.config file contains the
SET statements the DRDA Service will issue for each SQL Server connection, in order to alter the current
session handling of specific information.
SET ARITHABORT
The arithAbort attribute instructs the DRDA Service to issue the SET ARITHABORT statement at
connection time, to request SQL Server to terminate a query when an overflow or divide-by-zero error
occurs during query execution. This optional attribute accepts a string value. The default is ON.
Configuring Database Alias Mappings
IBM DB2 and Microsoft SQL Server databases utilize different terminology for naming objects, as can be
seen in the following table defining the fully-qualified three-part object identifier for a table. The DRDA
Service can map DB2 catalog and schema names to SQL Server catalog and schema names.
Platform
Catalog
Schema
Table
DB2 for z/OS
LOCATION
COLLECTION (aka
OWNER)
TABLENAME
DB2 for i5/OS
RELATIONAL DATABASE NAME
(RDBNAM)
COLLECTION (aka
LIBRARY)
TABLENAME
DB2 for LUW
DATABASE
SCHEMA
TABLENAME
SQL Server
DATABASE
SCHEMA
TABLENAME
DRDA
RELATIONAL DATABASE NAME
(RDBNAM)
COLLECTION
TABLENAME
Table 6. Three-part table naming conventions.
The databaseAliases element instructs the DRDA Service to map in-bound catalog and schema names to
outbound catalog and schema names, for use when executing static SQL packages for DB2 commands
mapped to SQL Server stored procedures. The databaseAlias element contains a sourceLocation,
sourceCollection, targetDatabase, and targetSchema to define one or more optional object name
mappings.
Note: The databaseAliases element is not used when binding packages or executing dynamic SQL
statements.
Service for DRDA
Page 25
Source Location
The sourceLocation attribute defines an in-bound DRDA RDBNAM (Relational Database Name) that the
DRDA Service should use when mapping to an out-bound SQL Server database name. This optional
property accepts a string value. The default value is an empty string, which denotes any value.
Note: When connecting DB2 for z/OS to the DRDA Service, the sourceLocation value may be the
database alias (DBALIAS) value from the DB2 for z/OS Connection Database (CDB) table
SYSIBM.LOCATIONS.
Source Collection
The sourceCollection attribute defines an in-bound DRDA COLID (Collection Identifier) that the DRDA
Service should use when mapping to an out-bound SQL Server schema name. This optional attribute
accepts a string value. The default value is an empty string, which denotes any value.
Target Database
The targetDatabase attribute defines an out-bound SQL Server database name that the DRDA Service
should use when mapping from an in-bound DRDA RDBNAM value. This optional attribute accepts a
string value. The default value is an empty string, which denotes any value.
Target Schema
The targetSchema attribute defines an out-bound SQL Server schema name that the DRDA Service
should use when mapping from an in-bound DRDA COLID value. This optional attribute accepts a string
value. The default value is an empty string, which denotes any value.
Example: The DRDA Service can map a DB2 location name (e.g. CONTOSO) to a SQL Server database
name (e.g. ContosoRetailDW), and a DB2 collection name (e.g. PROD1) to a SQL Server database schema
name (e.g., dbo).
<databaseAliases>
<databaseAlias
sourceLocation="CONTOSO"
sourceCollection="PROD1"
targetDatabase="ContosoRetailDW"
targetSchema="dbo" />
<databaseAlias sourceLocation="NWIND"
sourceCollection="DSN8HC91"
targetDatabase="Northwind"
targetSchema="DSN8910" />
</databaseAliases>
Example. DRDA Service can map DB2 catalog and schema names to SQL Server names.
At runtime, the DB2 DRDA AR connects to the relational database using the DBALIAS value.
DrdaAs Information: 1 : [<timestamp>] Processing ACCRDB
DrdaAs Information: 1 : [<timestamp>] Processing ACCRDB
RDBNAME="ContosoRetailDW"
...
Service for DRDA
Page 26
DrdaAs Information: 0 : [<timestamp>] Transformed:
SELECT * FROM CONTOSO.DSN8HC91.FACTSALES FOR FETCH ONLY
SELECT * FROM ContosoRetailDW.DSN8910.FACTSALES FOR FETCH ONLY
Example. DRDA Service trace output of the DRDA ACCRDB connection and EXCSQLSTT command.
Configuring Package Bind Processing
Internal Package Binder
The DRDA Service will convert static SQL for DB2 packages into SQL Server stored procedures, by
processing DRDA Begin Bind (BGNBND) and Bind SQL Statement (BNDSQLSTT) commands into SQL
Server DROP PROCEDURE and CREATE PROCEDURE statements. A DRDA BGNBND flow will contain one
or more BNDSQLSTT flows, one per SQL statement stored within the package. The DRDA Service maps
one DRDA static SQL package section (with one statement) to one SQL Server stored procedure. The
DRDA Service maps or preserves the BGNBND package bind options in comments within the stored
procedures, and optional extended stored procedure properties. The DRDA Service uses an internal SQL
transformer to convert SQL command syntax, parameters, data types, cursors, and results sets.
Optionally, you can develop a custom package bind listener to process the packages interactively with
the DRDA Service or off-line.
Package Procedure
The createPackageProcedure attribute instructs the DRDA Service to process a single BGNBND flow into
a SQL Server stored procedure, transforming the original statements as defined by the DRDA
BNDSQLSTT flows into corresponding SQL Server syntax. This optional attribute accepts a Boolean value.
The default value is true.
Package XML
The createPackageXml attribute instructs the DRDA Service to process a single BGNBND flow into a
static SQL for DB2 package XML file, preserving the original bind options and statements as defined by
the DRDA BNDSQLSTT flows. This optional attribute accepts a Boolean value. The default value is false.
Note: The DRDA Service will process a DRDA PKGRPLOPT (Package Replacement Option) by transforming
this code point into a DROP PROCEDURE statement.
Package XML Format
The packageXmlFormat attribute instructs the DRDA Service to write the static SQL for DB2 XML file in
the either v90 or v85 format. This optional attribute accepts a string value of either v85 or v90. The
default value is v90.
Note: Microsoft HIS 2010 2013 (V9) supports both the old and new format, which includes an associated
XML schema for validating the XML document. Microsoft HIS 2009 and HIS 2010 (V8.5) support the old
format only.
Package XML Location
The packageXmlLocation attribute instructs the DRDA Service where to write the static SQL for DB2
package XML file. This optional attribute accepts a string value. The default value is c:\temp.
Service for DRDA
Page 27
Note: The DRDA Service does not validate the SQL command syntax when processing the DRDA
BGNBND to static SQL for DB2 XML file. The DRDA Service preserves the original bind options, SQL
statement syntax, data types, and other values.
Stored Procedure Name
DRDA defines a fully-qualified static SQL package using a PKGNAMCT (Package Name and Consistency
Token) that consists of these multiple parts.





RDBNAM (Relational Database Name)
DRDA RDBCOLID (RDB Collection Identifier)
DRDA PKGID (RDB Package Identifier)
DRDA PKGCNSTKN (RDB Package Consistency Token)
DRDA PKGSN (Package Section Number)
The DRDA Service converts the DRDA package name into a SQL Server stored procedure name, removing
the RDBNAM part, separating the RDBCOLID using a period, and then separating the remaining three
parts using a single underscore character.
DRDA BGNBND static SQL package naming convention:
RDBNAME.RDBCOLID.PKGID.PKGCNSTKN.PKGSN
DRDA Service mapped SQL Server stored procedure naming convention:
CollectionIdentifer.PackageIdentifier_PackageConsistencyToken_Pac
kageSectionNumber
Original package schema and name:
CONTOSO.DSN8HC91_PKGSAMP1_43484152544F4B31_1
Mapped package schema and name:
ContosoRetailDW.DSN8910_PKGSAMP1_43484152544F4B31_1
The storedProcedureNameSeparator attribute instructs the DRDA Service what separator character to
use when mapping a DRDA package name to a SQL Server stored procedure name. This optional
attribute accepts a string value. The default value is a single underscore character (_).
Package Bind Options
The createPackageProcedureWithExtendedProperties attribute instructs the DRDA Service to preserve
the BGNBND package bind options as extended properties on the SQL Server stored procedure. This
optional attribute accepts a Boolean value. The default value is false.
Package Procedure Schema
The DRDA Service will process DRDA EXCSQLSTT (Execute SQL Statement) and OPNQRY (Open Query)
commands by executing a SQL Server CALL statement against a corresponding SQL Server stored
procedure. The DRDA Service will locate the target SQL Server stored procedure in a schema name
derived from the value of the DRDA RDBCOLID (RDB Collection Identifier), within the DRDA PKGNAMCT
(Package Name and Consistency Token) or fully-qualified package name that is part of the DRDA
EXCSQLSTT and OPNQRY command flows.
Service for DRDA
Page 28
The packageProcedureSchemaList instructs the DRDA Service to locate the target SQL Server stored
procedure in alternative schemas. This optional attribute accepts a string value. The default value is an
empty string. The string is comprised of a comma-separated SQL Server schema names.
packageProcedureSchemaList="DBO,DSN8910"
The packageProcedureSchemaList attribute is similar to the IBM DB2 for z/OS CURRENT PACKAGESET
special register and SET CURRENT PACKAGESET statement. The DRDA Service will combine the naming
mapping conventions contained within both the databaseAliases element and the
packageProcedureSchemaList attribute.
Original package schema and name:
CONTOSO.DSN8HC91_MSDB2SDK_43484152544F4B31_1
Mapped package schema and name:
ContosoRetailDW.DSN8910_MSDB2SDK_43484152544F4B31_1
First, the DRDA Service will attempt to locate the metadata for the target SQL Server stored procedure
within the DRDA Service package procedure cache, using the literal package procedure name, and then
using the mapped name using the package procedure schema list values.
Second, the DRDA Service will attempt to locate the metadata for the target SQL Server stored
procedure within the SQL Server database catalog, using the literal package procedure name, and then
using the mapped name using the package procedure schema list values.
Package Procedure Cache
procedure. Prior to executing the CALL statement, the DRDA Service will fetch metadata for the SQL
Server stored procedure with which to verify the statement type (SELECT, INSERT, UPDATE, DELETE),
cursor type (WITH HOLD), parameter data types (e.g. CHAR FOR BIT), and other attributes (e.g. has
results). After fetching the metadata, the DRDA Service will cache this information, including the
mapped procedure name, for a configured interval in a package procedure cache.
Package Procedure Cache Flush
The packageProcedureCacheFlush attribute instructs the DRDA Service to flush the package procedure
cache after a specified interval of time. This optional attribute accepts a duration value. The default
value is P1D (Period of Time is 1 Day). The duration value is specified in the form PnYnMnDTnHnMnS.
Item
P
nY
nM
nD
T
nH
nM
Description
Number of years.
Number of months.
Number of days.
seconds).
Number of hours.
Number of minutes.
Service for DRDA
Page 29
Item Description
S
Number of seconds.
Package Procedure Last Invoke
The packageProcedureLastInvoke attribute instructs the DRDA Service to write the names of objects in
the package procedure cache to a text file, %DRDAROOT%\LastInvokePackageProcedures.txt, after a
specified interval of time. This optional attribute accepts a duration value. The default value is PT0S
(Period of Time is Zero Seconds), which disables the reading and writing of the
LastInvokePackageProcedures.txt file. At service startup, the DRDA Service will load this text file to prefetch schema for procedures listed in the file. The duration value is specified in the form
PnYnMnDTnHnMnS.
Item
P
nY
nM
nD
T
Description
Number of years.
Number of months.
Number of days.
seconds).
nH
Number of hours.
nM
Number of minutes.
S
Number of seconds.
Table x. Duration of time expressed in XML format.
Note: To improve performance of service startup, you can edit this file and remove unneeded stored
procedure names. To improve performance of runtime execution, you can edit this file to include
additional stored procedure names. To disable the reading and writing of the
LastInvokePackageProcedures.txt file, set the timespan to PT0S (Period of Time Zero Seconds).
Custom Package Binder
The DRDA Service supports custom package binders in the form of a .NET Framework custom listener.
See Programmer’s Guide and Reference for information on the custom package bind listener sample.
The packageBindListeners element contains one or more packageBindListener elements to instruct the
DRDA Service to send bind package with bind SQL statement output to optional custom bind listeners.
The packageBindListener element contains a set of attributes to define a custom bind listener. The type
is Microsoft.HostIntegration.Drda.Common.PackageBindListener, which defined a DRDA Service custom
bind listener.
Custom Bind Listener
The createPackageProcedureWithCustomSqlScripts attribute instructs the DRDA Service to process
DRDA BGNBND and BNDSQLSTT through an external custom package bind listener component. This
optional attribute accepts a Boolean value. The default value is false.
Note: The custom package bind listener component must be referenced in the
MsDrdaService.exe.config as follows.
<packageBindListeners>
Service for DRDA
Page 30
<packageBindListener
type="Microsoft.HostIntegration.Drda.Common.PackageBindListener,
Microsoft.HostIntegration.Drda.Common, Version=9.0.1000.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35, processorArchitecture=MSIL"
errorWhenNoCallback="true"
/>
</packageBindListeners>
Example x. Default values for packageBindListener in the DRDA Service application configuration file.
Error When No Callback
The errorWhenNoCallback attribute instructs the DRDA Service to return BGNBNDRM (Begin Bind Reply
Message) to the DRDA AR client, when the custom bind listener component does not return any
information on the callback interface. This optional attribute accepts a Boolean value. The default value
is true.
Configuring SQL Syntax Transformations
The DRDA Service will utilize a set of SQL command syntax transformers. The primary SQL transformer is
within the MsDrdaService.exe and is referred to as the SQL parser, providing core transformations for
most commonly required syntax. The secondary SQL transformer is within the SQL Server database .NET
CLR (Common Language Runtime), where the MsDrdaService setup program will install optional DB2 to
SQL Server mapped functions. The DRDA Service supports STRIP, TRANSLATE, HEX, and CHAR mapped
CLR functions.
SQL Transformer
The sqlTransforms attribute instructs the DRDA Service to utilize internal service or external CLR-based
SQL transforms. This optional attribute accepts a string value of Service or Clr. The default value is
Service.
Note: To enable SQL Server CLR Integration, execute the following stored procedure.
sp_configure 'show advanced options', 1;
GO
RECONFIGURE;
GO
sp_configure 'clr enabled', 1;
GO
RECONFIGURE;
GO
Example x. SQL Server stored procedure to enable CLR integration.
For more information on Enabling CLR Integration, see http://msdn.microsoft.com/enus/library/ms131048.aspx.
SQL Transformer Unicode Output
The SQL Transformer will output NCHAR and NVARCHAR for all string values. The
sqlTransformsUnicodeOutput attribute instructs the DRDA Service to encode output from the CLRbased SQL transformer in Unicode or ANSI. This optional attribute accepts a Boolean value. The default
value is false, which instructs the DRDA Service to output ANSI CHAR and VARCHAR strings.
Service for DRDA
Page 31
Configuring Data Type Mappings
The DRDA Service converts base data types from DB2 to SQL Server, and from SQL Server to DB2.
Optionally, you can edit these XML files to modify the base data type mappings.
C:\Program Files\Microsoft Host Integration Server 2013\system\
DB2ToMSSql.xml
C:\Program Files\Microsoft Host Integration Server 2013\system\
MSSQLToDB2.xml
Configuring Date Time Conversions
The DRDA Service will format string literal date time values from source and into target formats when
processing dynamic and static SQL statements, for specific date time and character data types. The
conversionFormats element contains dateMasks, timeMasks, and dateTimeMasks for converting to and
from DB2 and SQL Server datetime formats.
1. When reading data from DB2 and writing to SQL Server, the MsDrdaService will read string
literal values that match source DB2 formats specified in the app config, and then write string
literal values into the default SQL Server format.
2. When reading data from SQL Server and writing to DB2, the MsDrdaService will read string
literal values that match known input formats, and then write string literal values into the DB2
target format specified in the app config.
<conversionFormats>
<dateTimeMasks>
</dateTimeMasks>
<timeMasks>
</timeMasks>
<dateMasks>
</dateMasks>
</conversionFormats>
Example x. Example of the conversionFormats portion of the MsDrdaService.exe.config file.
Date
The DRDA Service will process string literal date values within DB2 and SQL Server DATE, CHAR (10), and
VARCHAR (10) data types, to convert from DB2 date format to SQL Server date format, and to convert
from SQL Server date format to DB2 date format. The dateMasks contains one or more dateMask
elements to define date mappings. The dateMask element contains a db2ToSql or sqlToDb2 to indicate
the direction, and a sourceFormat and a targetFormat to specify the mapping. The db2ToSql defines the
direction from DB2 to SQL Server. The sqlToDb2 defines the direction from SQL Server to DB2.
DB2 DATE to SQL Server date
When reading data from DB2 and writing to SQL Server, the MsDrdaService will read string literal DB2
date values that match input DB2 date source formats specified in the app config, and then write string
literal SQL Server date values into the default SQL Server date format.
<dateMask>
<db2ToSql sourceFormat="YmdHyphen"/>
</dateMask>
Service for DRDA
Page 32
Example x. DRDA Service will process strings to match the input DB2 date source format YYYY-MM-DD.
The sourceFormat attribute defines the format of the source string that the DRDA Service should
identify as an input string literal date value. This optional attribute accepts an enumerated value. The
default is YmdHyphen.
Format Name Format Mask Description
ISO
yyyy-mm-dd
ISO date format seperator
Usa
mm/dd/yyyy
USA date format seperator
Eur
dd.mm.yyyy
EUR date format seperator
Jis
yyyy-mm-dd
JIS date format seperator
DmyBlank
dd mm yy
Day Month Year with blank seperator
DmyComma
dd,mm,yy
Day Month Year with comma seperator
DmyHyphen
dd-mm-yy
Day Month Year with hyphen seperator
DmyPeriod
dd.mm.yy
Day Month Year with period seperator
DmySlash
dd/mm/yy
Day Month Year with slash seperator
JulBlank
yy ddd
Julian with blank seperator
JulComma
yy,ddd
Julian with comma seperator
JulHyphen
yy-ddd
Julian with hyphen seperator
JulPeriod
yy.ddd
Julian with period seperator
JulSlash
yy/ddd
Julian with slash seperator
MdyBlank
mm dd yy
Month Day Year with blank seperator
MdyComma
mm,dd,yy
Month Day Year with comma seperator
MdyHyphen
mm-dd-yy
Month Day Year with hyphen seperator
MdyPeriod
mm.dd.yy
Month Day Year with period seperator
MdySlash
mm/dd/yy
Month Day Year with slash seperator
YmdBlank
yy mm dd
Year Month Day with blank seperator
YmdComma
yy,mm,dd
Year Month Day with comma seperator
YmdHyphen
yy-mm-dd
Year Month Day with hyphen seperator
YmdPeriod
yy.mm.dd
Year Month Day with period seperator
YmdSlash
yy/mm/dd
Year Month Day with slash seperator
Table 8. Supported sourceFormat attribute values for use with db2ToSql dateMask conversion.
SQL Server date to DB2 DATE
When reading data from SQL Server and writing to DB2, the MsDrdaService will read string literal date
values that match known input SQL Server date formats, and then write string literal date values into the
DB2 date target format specified in the app config.
<dateMask>
<sqlToDb2 targetFormat="YmdHyphen"/>
</dateMask>
Example x. DRDA Service will process strings to match the DB2 date target format YYYY-MM-DD.
The targetFormat attribute defines the format of the target string that the DRDA Service should produce
as an output string literal date value. This optional attribute accepts an enumerated value. The default
is YmdHyphen.
Service for DRDA
Page 33
ISO
yyyy-mm-dd
ISO date format seperator
Usa
mm/dd/yyyy
USA date format seperator
Eur
dd.mm.yyyy
EUR date format seperator
Jis
yyyy-mm-dd
JIS date format seperator
DmyBlank
dd mm yy
Day Month Year with blank seperator
DmyComma
dd,mm,yy
Day Month Year with comma seperator
DmyHyphen
dd-mm-yy
Day Month Year with hyphen seperator
DmyPeriod
dd.mm.yy
Day Month Year with period seperator
DmySlash
dd/mm/yy
Day Month Year with slash seperator
JulBlank
yy ddd
Julian with blank seperator
JulComma
yy,ddd
Julian with comma seperator
JulHyphen
yy-ddd
Julian with hyphen seperator
JulPeriod
yy.ddd
Julian with period seperator
JulSlash
yy/ddd
Julian with slash seperator
MdyBlank
mm dd yy
Month Day Year with blank seperator
MdyComma
mm,dd,yy
Month Day Year with comma seperator
MdyHyphen
mm-dd-yy
Month Day Year with hyphen seperator
MdyPeriod
mm.dd.yy
Month Day Year with period seperator
MdySlash
mm/dd/yy
Month Day Year with slash seperator
YmdBlank
yy mm dd
Year Month Day with blank seperator
YmdComma
yy,mm,dd
Year Month Day with comma seperator
YmdHyphen
yy-mm-dd
Year Month Day with hyphen seperator
YmdPeriod
yy.mm.dd
Year Month Day with period seperator
YmdSlash
yy/mm/dd
Year Month Day with slash seperator
Table 9. Supported targetFormat attribute values for use with sqlToDb2 dateMask conversion.
Time
The DRDA Service will process string literal time values within DB2 and SQL Server TIME, CHAR (8), and
VARCHAR (8) data types, to convert from DB2 time format to SQL Server time format, and to convert
from SQL Server time format to DB2 time format. The timeMasks contains one or more timeMask
elements to define time mappings. The timeMask element contains a db2ToSql or sqlToDb2 to indicate
the direction, and a sourceFormat and a targetFormat to specify the mapping. The db2ToSql defines the
DB2 TIME to SQL Server time
time values that match input DB2 time source formats specified in the app config, and then write string
literal SQL Server time values into the default SQL Server time format.
<timeMask>
<db2ToSql sourceFormat="HmsColon"/>
</timeMask>
Example x. DRDA Service will process strings to match the input DB2 time source format HH:MM:SS.
Service for DRDA
Page 34
identify as an input string literal time value. This optional attribute accepts an enumerated value. The
default is HmsColon.
HmsBlank
hh mm ss
Hour Minute Second with blank separator
HmsColon
hh:mm:ss
Hour Minute Second with colon separator
HmsComma
hh,mm,ss
Hour Minute Second with comma separator
HmsPeriod
hh.mm.ss
Hour Minute Second with period separator
Table 10. Supported sourceFormat attribute values for use with db2ToSql timeMask conversion.
SQL Server time to DB2 TIME
When reading data from SQL Server and writing to DB2, the MsDrdaService will read string literal time
values that match known input SQL Server time formats, and then write string literal time values into
the DB2 time target format specified in the app config.
<timeMask>
<sqlToDb2 targetFormat="HmsColon"/>
</timeMask>
Example x. DRDA Service will process strings to match the DB2 time target format HH:MM:SS.
as an output string literal time value. This optional attribute accepts an enumerated value. The default
is HmsColon.
HmsBlank
hh mm ss
HmsColon
hh:mm:ss
HmsComma
hh,mm,ss
HmsPeriod
hh.mm.ss
Table 11. Supported targetFormat attribute values for use with sqlToDb2 timeMask conversion.
Timestamp
The DRDA Service will process string literal timestamp values within DB2 and SQL Server TIMESTAMP,
DATETIME2 (6), CHAR (26), and VARCHAR (26) data types, to convert from DB2 timestamp format to SQL
Server datetime2 (6) format, and to convert from SQL Server datetime2 (6) format to DB2 timestamp
format. The dateTimeMasks contains one or more dateTimeMask elements to define timestampdatetime mappings. The dateTimeMask element contains a db2ToSql or sqlToDb2 to indicate the
direction, and a sourceFormat and a targetFormat to specify the mapping. The db2ToSql defines the
DB2 TIMESTAMP to SQL Server datetime2
timestamp values that match input DB2 timestamp source formats specified in the app config, and then
write string literal SQL Server datetime2 (6) values into the default SQL Server datetime2 (6) format.
<dateTimeMask>
<db2ToSql sourceFormat="Db2TimestampFormat"/>
</dateTimeMask>
Service for DRDA
Page 35
Example x. DRDA Service will process strings to match the input DB2 timestamp source format YYYYMM-DD hh:mm:ss.nnnnnn.
identify as an input string literal timestamp value. This optional attribute accepts an enumerated value.
The default is Db2TimestampFormat.
Format Name
Format Mask
Db2TimestampFormat
YYYY-MM-DD-hh:mm:ss.tttttt
IsoTimestampFormat
YYYY-MM-DD.hh.mm.ss.tttttt
SqlServerTimestampFormat YYYY-MM-DD hh:mm:ss.tttttt
AnyTimeStampFormat
YYYY?MM?DD?hh?mm?ss?tttttt
Table 12. Supported sourceFormat attribute values for use with db2ToSql dateTimeMask conversion.
SQL Server datetime2 to DB2 TIMESTAMP
When reading data from SQL Server and writing to DB2, the MsDrdaService will read string literal
timestamp values that match known input SQL Server datetime2 (6) formats, and then write string
literal date values into the DB2 timestamp target format specified in the app config.
<dateTimeMask>
<sqlToDb2 targetFormat="Db2TimestampFormat"/>
</dateTimeMask>
Example x. DRDA Service will process strings to match the DB2 timestamp target format YYYY-MM-DD
hh:mm: ss.nnnnnn.
as an output string literal timestamp value. This optional attribute accepts an enumerated value. The
default is Db2TimestampFormat.
Format Name
Format Mask
Db2TimestampFormat
YYYY-MM-DD-hh:mm:ss.tttttt
IsoTimestampFormat
YYYY-MM-DD.hh.mm.ss.tttttt
SqlServerTimestampFormat YYYY-MM-DD hh:mm:ss.tttttt
Table 13. Supported targetFormat attribute values for use with sqlToDb2 dateTimeMask conversion.
Configuring Service Encodings
The DRDA Service maps code pages and supports custom code page conversions using an underlying HIS
Encoder component and the Windows National Language Support (NLS) system components.
Custom NLS Code Pages
Using Microsoft Windows Update, you can install additional Windows language packs that include
Windows NLS code page conversion libraries. Optionally, the HIS Encoder can load a custom NLS code
page based on codePage elements defined within the codePages portion of the
MsDrdaService.exe.config file.
Code Page Number
The number attribute instructs the HIS Encoder to load a custom NLS code page file. This optional
attribute accepts an integer. The default value is 0.
Service for DRDA
Page 36
Code Page Name
The name attribute names the custom NLS code page that the HIS Encoder should load based on the
defined custom NLS code page number. This optional attribute accepts a string. The default value is an
empty string.
Code Page Description
The description attribute describes the custom NLS code page that the HIS Encoder should load based
on the defined custom NLS code page number. This optional attribute accepts a string. The default
value is an empty string.
NLS Code Page Number
The nlsCodePage attribute defines which standard NLS code page number that the HIS Encoder should
replace with the custom code page number. This optional attribute accepts an integer. The default
value is 0.
For example, to replace the standard NLS code page for “EBCDIC - U.S./ Canada (Euro)” CCSID 1140 with
a custom NLS code page “EBCDIC US Custom” custom code page file 21140.nls and custom code page
number 21140, specify the following.
<codePage number="21140"
name="Custom21140"
description="Custom codepage based on 1140"
nlsCodePage="1140">
Example x. DRDA Service maps code pages and supports custom code page conversions using an
underlying HIS Encoder component and the Windows National Language Support (NLS) system
components.
Custom Code Point Mappings
The HIS Encoder can custom map code points within standard NLS and custom NLS code pages based on
ebcdicToUnicodeConversion elements defined within the codePages portion of the
EBCDIC to UNICODE
The “from” and “to” attributes within an ebcdicToUnicode element instruct the HIS Encoder to convert
from and to these code points. This optional attribute accepts a string value, in the form of a hex code
point value.
The reversible attribute instructs the HIS Encoder to convert in the reversible direction. This optional
attribute accepts a Boolean value. The default is false.
UNICODE to EBCDIC
The “from” and “to” attributes within a unicodeToEbcdic element instruct the HIS Encoder to convert
from and to these code points. This optional attribute accepts a string value, in the form of a hex code
point value.
The reversible attribute instructs the HIS Encoder to convert in the reversible direction. This optional
attribute accepts a Boolean value. The default is false.
Service for DRDA
Page 37
Conversion Behavior
The HIS Encoder is shared by a number of Microsoft Host Integration Server 2013 features, including the
DRDA Service and Transaction Integrator. The conversionBehavior element is for use by Transaction
Integrator only. The DRDA Service does not require this element.
Configuring Application Encodings
The DRDA Service converts base code pages and maps code points using an underlying HIS Encoder
component and the Windows National Language Support (NLS) system components. The
applicationEncodings element contains applicationEncoding elements for specifying default
application-level encoding schemes on a per-database basis.
Default Encodings
The DRDA Service will encode character strings in output parameter and result set values using the
encoding scheme and Coded Character Set Identifier (CCSID) specified by the DRDA Application
Requester client in the ACCRDB (Access Relational Database) request.
Application Encodings
Optionally, the DRDA Service can encode character strings based on overrides defined in one or more
applicationEncoding elements within the applicationEncodings portion of the MsDrdaService.exe.config
file.
Application Encoding Scheme
The scheme attribute instructs the DRDA Service to encode output parameter and result set values using
an override encoding scheme, and not the DRDA AR client-requested encoding scheme. This optional
attribute accepts a string value. The supported values are Ebcdic, Unicode, and Ansi. The default value is
Unicode.
Application Encoding CCSID
The ccsid attribute instructs the DRDA Service to encode output parameter and result set values using
an override CCSID (Coded Character Set Identifier), and not the DRDA AR client-requested CCSID. This
optional attribute accepts an integer. The default value is 1208.
Name
ANSI - Arabic
ANSI - Baltic
ANSI - Central Europe
ANSI - Cyrillic
ANSI - Greek
ANSI - Hebrew
ANSI - Latin I
ANSI - Turkish
EBCDIC - Arabic
EBCDIC - Cyrillic (Russian)
EBCDIC - Cyrillic (Serbian, Bulgarian)
EBCDIC - Denmark/ Norway
Service for DRDA
CCSID
1256
1257
1250
1251
1253
1255
1252
1254
420
880
1025
277
NLS File
c_1256.nls
c_1257.nls
c_1250.nls
c_1251.nls
c_1253.nls
c_1255.nls
c_1252.nls
c_1254.nls
c_20420.nls
c_20880.nls
c_21025.nls
c_20277.nls
Euro-enabled
No
No
No
No
No
No
No
No
No
No
No
No
Page 38
Name
CCSID
EBCDIC - Denmark/ Norway (Euro)
1142
EBCDIC - Finland/ Sweden
278
EBCDIC - Finland/ Sweden (Euro)
1143
EBCDIC - France
297
EBCDIC - France (Euro)
1147
EBCDIC - Germany
273
EBCDIC - Germany (Euro)
1141
EBCDIC - Greek
423
EBCDIC - Greek (Modern)
875
EBCDIC - Hebrew
424
EBCDIC - Icelandic
871
EBCDIC - Icelandic (Euro)
1149
EBCDIC - International
500
EBCDIC - International (Euro)
1148
EBCDIC - Italy
280
EBCDIC - Italy (Euro)
1144
EBCDIC - Latin America/Spain
284
EBCDIC - Latin America/Spain (Euro)
1145
EBCDIC - Multilingual/ ROECE (Latin-2) 870
EBCDIC - Thai
838
EBCDIC - Turkish (Latin-3)
905
1026
EBCDIC - U.S./ Canada
37
EBCDIC - U.S./ Canada (Euro)
1140
EBCDIC - United Kingdom
285
EBCDIC - United Kingdom (Euro)
1146
Table 14. Application Encoding CCSID values.
NLS File
c_1142.nls
c_20278.nls
c_1143.nls
c_20297.nls
c_1147.nls
c_20273.nls
c_1141.nls
c_20423.nls
c_875.nls
c_20424.nls
c_20871.nls
c_1149.nls
c_500.nls
c_1148.nls
c_20280.nls
c_1144.nls
c_20284.nls
c_1145.nls
c_870.nls
c_20838.nls
c_20905.nls
c_1026.nls
c_037.nls
c_1140.nls
c_20285.nls
c_1146.nls
Euro-enabled
Yes
No
Yes
No
Yes
No
Yes
No
No
No
No
Yes
No
Yes
No
Yes
No
Yes
No
No
No
No
No
Yes
No
Yes
Application Encoding Custom CCSID
The customCcsid attribute instructs the DRDA Service to encode output parameter and result set values
using an override custom CCSID (Coded Character Set Identifier), and not the DRDA AR client-requested
CCSID. This optional attribute accepts an integer. The default value is -1.
Application Encoding Database
The database attribute instructs the DRDA Service to encode output parameter and result set values
using an override encoding scheme, and not the DRDA AR client-requested encoding scheme, for a
specified target SQL Server database only. This optional attribute accepts a string value. The default
Configuring Collation Mapping
SQL Server may collate query results in a different order than what is expected by the DRDA client
program. For example, an IT professional may configure a SQL Server database to use an ANSI collation
and a DB2 for z/OS database to use EBCDIC collation.
Service for DRDA
Page 39
Automatic Collation
The DRDA Service can add a COLLATE clause to an ORDER BY clause, based on a default ORDER BY
collation name.
SELECT * FROM CONTOSO.DSN8910.DEPT ORDER BY DEPTNAME
SELECT * FROM [CONTOSO].[DSN8910].[DEPT] ORDER BY DEPTNAME COLLATE
SQL_EBCDIC037_CP1_CS_AS
Example x. DB2 SELECT ORDER BY syntax automatically transformed to SQL Server ORDER BY COLLATE.
The defaultCollationName element instructs the DRDA Service to add a SQL Server COLLATE
(collation_name) clause, when transforming a DB2 SELECT statement with ORDER BY clause into a SQL
Server SELECT statement with ORDER BY clause. This optional attribute accepts a string value. The
default value is SQL_Latin1_General_CP1_CI_AS.
Mapping Collation Names
The DRDA Service can transform a SELECT statement from DB2 ORDER BY COLLATION_KEY (collationname) syntax to SQL Server T-SQL ORDER BY COLLATE (collation_name) syntax, mapping from a DB2
collation-name value to a SQL Server collation_name value, to provide more compatible query results.
See collation syntax conversion below.
SELECT * FROM CONTOSO.DSN8910.DEPT ORDER BY COLLATION_KEY (DEPTNAME,
'UCA400R1_LEN_AN')
SELECT * FROM [CONTOSO].[DSN8910].[DEPT] ORDER BY DEPTNAME COLLATE
SQL_EBCDIC037_CP1_CS_AS
Example x. DB2 SELECT ORDER BY COLLATION_KEY syntax transformed to SQL Server ORDER BY COLLATE
syntax.
The collationNames element within the service element can contain one or more collationName
elements to instruct the DRDA Service to convert from a DB2 collation-name value to a SQL Server
collation_name value, when transforming a DB2 SELECT statement with ORDER BY COLLATION_KEY
(collation-name) clause into a SQL Server SELECT statement with ORDER BY COLLATE (collation_name)
clause.
<collationNames>
<collationName from="UCA400R1_LEN_AN" to="SQL_EBCDIC037_CP1_CS_AS"/>
</collationNames>
Example x. Collation Names element and attributes.
Collation Name
The collationName element must contain a from attribute and a to attribute to define a collation name
mapping.
Service for DRDA
Page 40
Mapping from Collation Name
The from attribute instructs the DRDA Service SQL Transformer to convert from the specified collationname string within a DB2 SELECT ORDER BY COLLATION_KEY clause. This required attribute accepts a
string value. There is no default value.
Mapping to Collation Name
The to attribute instructs the DRDA Service SQL Transformer to convert to the specified collation_name
string within a SQL Server SELECT ORDER BY COLLATE clause. This required attribute accepts a string
value. There is no default value.
For more information on SQL Server COLLATE, see http://msdn.microsoft.com/enus/library/ms184391.aspx.
Configuring Trace Listeners
The DRDA Service supports multiple concurrent trace listeners, including: text trace listener, console
trace listener, custom trace listener, and Event Trace for Windows (ETW) listener.
The drdaServiceTraceListeners element contains one or more drdaServiceTraceListener elements to
instruct the DRDA Service to send trace output to optional custom text trace listeners.
System Diagnostics
The DRDA Service supports a set of shared listeners to log information to text, console, and event log.
The system.diagnostics element of the hostIntegration.drdaAs.drdaService section of the
MsDrdaService.exe.config file defines and controls the various listeners.
<system.diagnostics>
<sources>
<source name="DrdaAs" switchName="sourceSwitch"
switchType="System.Diagnostics.SourceSwitch">
<listeners>

<remove name="Default" />
</listeners>
</source>
</sources>
<sharedListeners>
<add name="DrdaAsTextListener"
type="Microsoft.HostIntegration.Drda.Common.DrdaTraceListener,
initializeData="MsDrdaService.DSTF"
traceOutputOptions="None"
autoFlush="true"
traceLevel="0"
maxTraceEntries="1000000"
maxTraceFiles="10"
/>
<add name="DrdaAsConsoleListener"
Service for DRDA
Page 41
type="Microsoft.HostIntegration.Drda.Common.DrdaConsoleTraceListener,
traceOutputOptions="None"
traceLevel="3"
/>
<add name="EventLog"
type="System.Diagnostics.EventLogTraceListener, System, Version=2.0.0.0,
Culture=neutral, PublicKeyToken=b77a5c561934e089"
initializeData="DrdaService1" >
<filter type="System.Diagnostics.EventTypeFilter"
initializeData="Error,Warning,Information"/>
</add>
<add name="DrdaETWListener"
type="Microsoft.HostIntegration.Drda.Common.DrdaEventProviderTraceListener,
initializeData="{3B4388CE-50E0-404C-A62B-E9C87D4F3BC4}"
traceLevel="0"/>
</sharedListeners>
</system.diagnostics>
Example x. Example of source element in the system.diagnostics section of the MsDrdaService.exe.config
file.
Enabling Tracing
By default, the DRDA Service trace listeners are disabled. To enable the DRDA Service trace listeners,
uncomment one or more elements in the source element within the system.diagnostics portion of the
MsDrdaService.exe.config file. Also, to enable tracing, set a positive value (1-4) for the traceLevel
attribute for each of the target trace listeners within the sharedListeners element of the
system.diagnostics portion of the MsDrdaService.exe.config file.
<sources>
<source name="DrdaAs" switchName="sourceSwitch"
switchType="System.Diagnostics.SourceSwitch">
<listeners>


<add name="DrdaETWListener"/>
<add name="EventLog" />
<remove name="Default" />
</listeners>
</source>
</sources>
Example x. Example of sources element in the system.diagnostics section of the
Text Trace Listener
The DRDA Service text trace listener outputs trace data to a disk file in text format.
Trace Listener Name
The name attribute defines the name of the DRDA Service text trace listener. This required attribute is
accepts a string, with a value of DrdaAsTextListener.
Service for DRDA
Page 42
Trace Listener Type
The type attribute defines the type of the DRDA Service text trace listener. This required attribute is
accepts a string, with a value of Microsoft.HostIntegration.Drda.Common.DrdaTraceListener,
PublicKeyToken=31bf3856ad364e35, processorArchitecture=MSIL only.
Trace Listener Initialization
The initializeData attribute defines the type of disk file to create. This required attribute is accepts a
string, with a value of MsDrdaService.DSTF.
Trace File Folder
The traceFileFolder attribute instructs the DRDA Service where to write the text listener trace output
file. This optional attribute accepts a string value. The default value is C:\Program Files\Microsoft
Service for DRDA\traces.
Note: Each user account must have write access to the traces folder, in order to insert lines into the text
trace file. Each user account requires the Folder Access Control List settings associated with the HIS
Runtime Users Local Group. See section titled Security and Protection for more information.
Automatic Flush
The autoFlush attribute instructs the DRDA Service to flush data automatically to the trace listener. This
optional attribute accepts a Boolean value. The default is false.
Note: The DRDA Service can flush trace data automatically to the trace listeners, which ensures the
trace data is captured but will increase disk I/O and reduce overall system performance. To improve
performance, set autoFlush=false, to disable automatic trace flush.
Maximum Trace Entries
The maxTraceEntries attribute instructs the DRDA Service to trace up to a maximum number of entries,
and then to stop tracing. This optional attribute accepts an integer. The default value is 1000000.
Maximum Trace Files
The maxTraceFiles attribute instructs the DRDA Service to write the text listener trace output a
maximum number of individual trace files, and then overwrite existing trace files. This optional attribute
accepts an integer. The default value is 10.
Trace Output Options
The traceOutputOptions attribute is not used by the DRDA Service. This optional attribute accepts a
string value. The default value is none.
Trace Level
The traceLevel attribute instructs the DRDA Service to trace defined collections of information, from a
minimum to a maximum level of tracing. This optional attribute accepts an integer value. The default
value is 3.
Value
0
1
2
Description
Output no tracing messages.
Output error messages.
Output warning messages and error messages.
Service for DRDA
Page 43
Value Description
3
Output information messages, warning messages and error messages.
4
Output all messages.
Table 15. DRDA Service trace listener levels.
Console Trace Listener
The DRDA Service console trace listener outputs trace data to a command console window.
Trace Listener Name
accepts a string, with a value of DrdaAsConsoleListener.
Trace Listener Type
The type attribute defines the type of the DRDA Service text trace listener. This required attribute is
accepts a string, with a value of Microsoft.HostIntegration.Drda.Common.DrdaConsoleTraceListener,
PublicKeyToken=31bf3856ad364e35, processorArchitecture=MSIL only.
Trace Output Options
The traceOutputOptions attribute is not used by the DRDA Service. This optional attribute accepts a
string value. The default value is none.
Trace Level
value is 3, which disables tracing.
ETW Trace Listener
The DRDA Service ETW (Event Tracing for Windows) trace listener as an ETW provider outputs trace data
through an ETW session to a Windows operating system ETW controller. An administrator can register
the ETW provider using the ProviderId GUID “3B4388CE-50E0-404C-A62B-E9C87D4F3BC4”. An ETW
consumer can read ETW log files or listen to an ETW session for real time events.
Trace Listener Name
accepts a string, with a value of DrdaETWListener.
Trace Listener Type
The type attribute defines the type of the DRDA Service ETW trace listener. This required attribute is
accepts a string, with a value of Microsoft.HostIntegration.Drda.Common.
DrdaEventProviderTraceListener, Microsoft.HostIntegration.Drda.Common, Version=9.0.1000.0,
Culture=neutral, PublicKeyToken=31bf3856ad364e35, processorArchitecture=MSIL only.
Trace Listener Initialization
The initializeData attribute defines the ETW ProviderID GUID used to register the ETW provider to the
ETW controller. This required attribute is accepts a string, with a value of 3B4388CE-50E0-404C-A62BE9C87D4F3BC4.
Service for DRDA
Page 44
Trace Level
Start Event Trace Session
The Windows administrator must start a DRDA Service ETW event trace session using Performance
Monitor or the logman command line utility.
1. On the Start menu, point to All Programs, point to Microsoft Visual Studio 2010, point to Visual
Studio Tools, right click Visual Studio x64 Win64 Command Prompt (2010), and click Run as
administrator. The User Account Control dialog may appear. Click Yes to continue.
2. In the Visual Studio x64 Win64 Command Prompt (2010) window, locate the installation folder
in which you downloaded the installation program, logman start MsDrdaService -p {3B4388CE50E0-404C-A62B-E9C87D4F3BC4} -o c:\temp\MsDrdaServiceETW.etl -ets, and then click Enter.
C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC>logman
start MsDrdaService -p {3B4388CE-50E0-404C-A62B-E9C87D4F3BC4} -o
c:\temp\MsDrdaServiceETW.etl -ets
The command completed successfully.
Example x. Define ETW event trace session command line argument with example property
values.
Stop Event Trace Session
The Windows administrator can stop a DRDA Service ETW event trace session using Performance
in which you downloaded the installation program, logman stop MsDrdaService -ets, and then
click Enter.
stop MsDrdaService -ets
Example x. Define ETW event trace session command line argument with example property
values.
Event Log Listener
The DRDA Service event log listener outputs log data to the Windows event log.
Service for DRDA
Page 45
Event Log Listener Name
The name attribute defines the name of the DRDA Service event log listener. This required attribute is
accepts a string, with a value of EventLog.
Event Log Listener Type
The type attribute defines the type of the DRDA Service event log listener. This required attribute is
accepts a string, with a value of System.Diagnostics.EventLogTraceListener, System, Version=2.0.0.0,
Culture=neutral, PublicKeyToken=b77a5c561934e089.
Event Log Listener Initialization
The initializeData attribute defines the DRDA Service instance. This required attribute is accepts a
string, with a value of DrdaService1.
Event Log Listener Filter
The filter element instructs the DRDA Service to log data by filter type. This required element contains
two attributes: type; and initializData.
Event Log Filter Type
The type attribute of the filter element defines a filter type. This required attribute accepts a string
value, with a value of System.Diagnostics.EventTypeFilter.
Event Log Filter Level
The initializeData attribute instructs the DRDA Service to log defined collections of information. This
optional attribute accepts a string value. The default value is Error,Warning,Information, which includes
all event log levels.
Value
Description
Error
This value instructs the DRDA Service to log only the error level data.
Warning
This value instructs the DRDA Service to log only the warning level data.
Information This value instructs the DRDA Service to log only the information level data
Table 16. DRDA Service event log listener levels.
Custom Trace Listener
The DRDA Service supports custom trace listeners in the form of a .NET Framework custom listener. See
Programmer’s Guide and Reference for information on the custom trace listener sample. . The
drdaServiceTraceListeners element contains one or more drdaServiceTraceListener elements to instruct
the DRDA Service to send trace output to optional custom text trace listeners. The
drdaServiceTraceListener element contains a set of attributes to define a custom trace listener. The
type is Microsoft.HostIntegration.Drda.Common.BaseDrdaTraceListener, which defined a DRDA Service
custom trace listener.
The DRDA Service will process text trace output to a custom trace listener that is referenced in the
MsDrdaService.exe.config as follows.
<drdaServiceTraceListeners>
<drdaServiceTraceListener
type="Microsoft.HostIntegration.Drda.Common.BaseDrdaTraceListener,
Service for DRDA
Page 46
traceLevel="4"/>
</drdaServiceTraceListeners>
Example x. Default values for custom trace listener in the DRDA Service application configuration file.
Trace Level
Configuring Enterprise Single Sign-On
The DRDA Service can utilize Enterprise Single Sign-On (ESSO) to better secure the authentication and
configuration information.
Define an ESSO Host-Initiated Affiliate Application
You must define an ESSO Affiliate Application, in order to use host-initiated SSO for use by multiple
client programs and users.
1. On the Start menu, point to All Programs, point to Microsoft Enterprise Single Sign-On, and
click SSO Administration. When prompted by User Access Control, click Yes.
2. In the Enterprise Single Sign-On scope pane, of the ENTSSO MMC snap-in, click the Affiliate
Applications folder; click the Action menu, and then Create Application.
3. In the Enterprise Single Sign-On Application Wizard Welcome dialog, click Next.
4. In the General dialog, enter an Application name (e.g. “SYS1”), click Allow local accounts for
access accounts, click Use SSO Affiliate Admin Accounts for Application Admin accounts, and
then click Next.
5. In the Accounts dialog, under the Application Users list, click Add.
6. In the Select Users or Groups dialog, enter a user account (e.g. DOMAIN\username), click Check
Names, and then click OK. Verify the account is added to the Application Users list, and then
click Next.
7. In the Options dialog, verify the Affiliate Application is Enabled, that Allow Windows Initiated
SSO is selected, that Allow host initiated SSO is selected, and that Verify external credentials is
selected. Click Next to continue.
8. In the Fields dialog, verify the Number of fields is the default two (2). Optionally, select
Credentials are Windows credentials (to increase the security with host-initiated SSO). Click
Create to continue.
9. In the Completing the Application Wizard dialog, verify that you successfully created the
Application, and then click Finish.
Applications folder; click the newly-created Affiliate Application (e.g. “SYS1”), click the Action
menu, click New Mapping.
11. In the Create New Mapping dialog, enter a Windows user (e.g. DOMAIN\username that is
authorized to access SQL Server via the DRDA Service on behalf of the External user), enter an
Service for DRDA
Page 47
External user (e.g. “HISDEMO” account authorized to access “SYS1” DB2 server and SQL Server
via the DRDA Service), click Set credentials for new mapping, and then click OK.
12. In the Set Credentials dialog, enter a valid DB2 server password (e.g. “HISDEMO”) in the
Password and Confirm edit boxes, and then click OK.
Applications folder, verify the newly-created Affiliate Application (e.g. “SYS1”) is Enabled. Click
the Affiliate Application (e.g. “SYS1”), and verify in the results pane (list of Windows users on
right side of dialog) is enabled.
Set the Local Security Policy for ESSO Application Admin Account
You must define an ESSO Affiliate Application, in order to use host-initiated SSO for use by multiple
client programs and users.
1. On the Start menu, point to All Programs, point to Administrative Tools, and click Local Security
Policy. When prompted by User Access Control, and then click Yes.
2. In the Security settings pane, navigate to User Rights Assignment under Local Policies.
3. Click Access Credential Manager as a trusted caller, right-click to select Properties. In the
Access Credential Manager as a trusted caller dialog, click Add User or Group. In the Select
Users or Groups dialog, enter the Application Admin accounts user account
(DOMAIN\username), click Check Names, and then click OK. Verify the account is added to the
Application Users list, and then click OK.
4. Click Enable computer and user accounts to be trusted for delegation, right-click to select
Properties. In the Enable computer and user accounts to be trusted for delegation dialog, click
Add User or Group. In the Select Users or Groups dialog, enter the Application Admin accounts
user account (DOMAIN\username), click Check Names, and then click OK. Verify the account is
added to the Application Users list, and then click OK. .
5. Click Act as part of the operating system, right-click to select Properties. In the Act as part of
the operating system dialog, click Add User or Group. In the Select Users or Groups dialog,
enter the Application Admin accounts user account (DOMAIN\username), click Check Names,
and then click OK. Verify the account is added to the Application Users list, and then click OK.
Configuring Microsoft Client Connections
Connect Microsoft Client to DRDA Service
You can connect the Microsoft Client for DB2 to the DRDA Service directly, to test the DRDA Service
configuration.
1. On the Start menu, point to All Programs, point to Microsoft Host Integration Server 2010, and
click Data Access Tool. When prompted by User Access Control, click Yes.
2. In the Data Access Tool, click the Data Sources, click the File menu, and then click New Data
Source.
3. In the Welcome dialog of the Data Source Wizard, click Next.
4. In the Data Source dialog, select DB2/NT in the Data source platform list, select TCP/IP, and
click Next.
Service for DRDA
Page 48
5. In TCP/IP Network Connection dialog, enter an Address or alias (e.g. “127.0.0.1”), enter a Port
(e.g. “446”), and then click Next.
6. In the DB2 Database dialog, enter an Initial Catalog (e.g. “NWIND”), Package collection (e.g.
“dbo”, Default schema (e.g. “dbo”, Default qualifier (e.g. “dbo”, and then click Next.
7. In the Locale dialog, select the Host CCSID (e.g. “Unicode – UTF8 [1208]”) and PC code page
(e.g. “Unicode – UTF8 [1208]”), and then click Next.
8. In the Security dialog, select Interactive Sign-On from the Security method list, enter
“HISDEMO“ in the User name, Password, and Password confirmation fields, and then click Next
to continue.
9. In the Advanced Options dialog, optionally select Connection pooling, and then click Next.
10. In the All Properties dialog, optionally verify the properties in the list, and then click Next.
11. In the Validation dialog, click Connect, and then verify the Output of the test connection.
Successfully connected to data source 'DB2_IP_DRDA_AS_NWIND'.
Server class: DB2/NT
Server version: 09.07.0000
12. In the Validation dialog, optionally click Packages, and then verify the Output of the create
package process. When prompted by the Warning dialog, click Continue.
Note: The Packages operation will succeed, however the DRDA Service does not create the
corresponding SQL Server stored procedures for these Microsoft Client packages. See DRDA
Service operations topic describing use of IgnoreStandardPackages.txt file.
13. In the Validation dialog, optionally click Sample Query, and then verify the results in the Grid,
and then click Next.
Note: The Sample Query operation will fail unless you’ve defined a SQL Server view that is
compatible with the IBM DB2 SYSCAT.TABLES catalog view.
14. In the Saving Information dialog, enter a Data source name (e.g. “DB2_IP_DRDAAS_NWIND”),
click Universal data link and Initialization string file, and then click Next.
15. In the Completing the Data Source Wizard dialog, review what you have accomplished, and
then click Finish.
16. In the Data Access Tool, click the newly-created DB2 OLE DB UDL (e.g.
“DB2_IP_DRDA_AS_NWIND”), to view the Connection String (at bottom of Data Link Tool
dialog).
Provider=DB2OLEDB;User ID=HISDEMO;Password=HISDEMO;Initial Catalog=NWIND;Network
Transport Library=TCPIP;Host CCSID=1208;PC Code Page=1208;Network
Address=127.0.0.1;Network Port=446;Package Collection=dbo;Default Schema=dbo;Process
Binary as Character=False;Units of Work=RUW;Default Qualifier=dbo;DBMS
Platform=DB2/NT;Use Early Metadata=False;Defer Prepare=False;DateTime As
Char=False;Rowset Cache Size=0;Datetime As
Date=False;AutoCommit=False;Authentication=Server;Persist Security Info=True;Data
Source=DB2ADMIN;Cache Authentication=False;Connection Pooling=False;Derive
Parameters=False;
Service for DRDA
Page 49
Example x. Data Access Tool connection string.
Service for DRDA
Page 50
Configuring DB2 for z/OS
IBM DB2 for z/OS supports access to remote DRDA Application Servers using information stored in the
DB2 for z/OS Communications Database (CDB), which is a collection of catalog tables.
Table
SYSIBM.LOCATIONS
Description
Required catalog table for defining a remote
relational database, including address (TCP/IP
port), security, and naming convention (alias).
SYSIBM.IPNAMES
Required catalog table for defining address
(TCP/IP address or alias) and security
(authentication and encryption).
SYSIBM.IPLIST
Optional catalog table for defining address
(TCP/IP address or alias) when using failover.
SYSIBM.USERNAMES
Optional catalog table for defining authentication
mapping.
Table 17. DB2 for z/OS Communications Database tables.
You can update the CDB tables using dynamic SQL statements, either locally (e.g. DB2 Admin, QMF,
SPUFI) or remotely (e.g. Microsoft Data Provider for DB2 with SQL Server Management Studio).
Figure 7. DB2 for z/OS Communications Database tables.
SQL Server Management Studio
Using the Microsoft OLE DB Provider for DB2 with SQL Server Management Studio and a Distributed
Query Processor (DQP) Linked Server, you can configure the DB2 for z/OS Configuration Database (CDB)
to enable DRDA connectivity over a TCP/IP network connection to the DRDA Service.
1. On the Start menu, point to All Programs, point to Microsoft SQL Server 2008 R2 (SQL Server
2008, SQL Server 2012), click SQL Server Management Studio.
2. In the Connect to Server dialog, type a Server name (e.g. LOCALHOST), and then click Connect.
3. In the Microsoft SQL Server Management Studio, on the File menu, click New, and then click
Query with Current Connection.
Service for DRDA
Page 51
4. Copy and paste the examples below into the SQLQuery1.sql file within the Query Editor window,
and then modify the bold yellow highlighted text to match values for your DB2 instance, DRDA
Service, and SQL Server database.
SQL Server Linked Server Name
These system stored procedures define a SQL Server Linked Server Name for connecting to DB2 for
z/OS. Optionally, or if you do not have authority, you can ask your DB2 administrator to update the
DB2 connection database tables.
-- ----------------------------------- Microsoft Service for DRDA Example
-- ----------------------------------- Drop existing linked server by name
EXEC sp_dropserver
@server = 'DRDA_AS_Example',
@droplogins = 'droplogins';
-- Add linked server for use with Microsoft OLE DB Provider for DB2
(DB2OLEDB)
EXEC sp_addlinkedserver
@srvproduct = 'Microsoft OLE DB Provider for DB2',
@provider = 'DB2OLEDB',
@catalog = 'DSN1D037',
@provstr ='Provider=DB2OLEDB;Initial Catalog=DSN1D037;Network Transport
Library=TCPIP;Host CCSID=37;PC Code Page=1252;Network
Address=SYS1;Network Port=446;Package Collection=HISDEMO;Default
Schema=HISDEMO;Default Qualifier=HISDEMO;DBMS Platform=DB2/NT'
-- Add linked server login by specifying valid DB2 user identifer and
password
EXEC sp_addlinkedsrvlogin
@rmtsrvname = 'DRDA_AS_Example',
@rmtuser = 'HISDEMO',
@rmtpassword = 'HISDEMO';
-- List linked servers
EXEC sp_linkedservers;
-- Specify linked server option to support Remote Procedure Call (to
allow execution of DB2 stored procedures)
EXEC sp_serveroption
@optname = 'RPC OUT',
@optvalue = 'TRUE' ;
-- List linked servers options
EXEC sp_helpserver;
Example x. Defining SQL Server Linked Server using SQL Server Management Studio.
Updating SYSIBM.LOCATIONS table
These system stored procedures define SQL Server Pass-Thru queries for defining a LOCATION in the
DB2 for z/OS connection database.
Service for DRDA
Page 52
DB2 for z/OS
LOCATION
Description
Specify a value that matches the name of the target SQL Server database
name (e.g. NWIND).
If you cannot specify a LOCATION name value that matches the target SQL
Server database (e.g. LOCATION name is in use; SQL Server database name is
too long), then use the DBALIAS and the MsDrdaService.exe.config entries
(drdaDatabaseAliases) to instruct the DRDA Service how to interpret and map
the LOCATION and DBALIAS to a corresponding SQL Server database name.
LOCATION is known as the DRDA RDBNAME (Relational Database Name).
LOCATION is known as the SQL Server Database Name or Initial Catalog.
LINKNAME
This value is used to associate the record in the SYSIBM.LOCATIONS table to
the records in the SYSIBM.IPNAMES, SYSIBM.IPLIST, and SYSIBM.USERNAMES
tables. This value is limited to 8 characters when running DB2 for z/OS in
compatibility mode.
IBMREQD
Specify “N”.
PORT
Specify a value for the TCP/IP port for use by the DRDA Service running on the
SQL Server computer. For example, the default DRDA port number is 446.
TPN
Specify “”. The DRDA Service does not support an alternate TPN (Transaction
Program Name).
DBALIAS
Specify a value that matches the name of the target SQL Server database
name (e.g. NWIND), if you cannot specify this value in the LOCATION field.
When using the DBALIAS, you must utilize the MsDrdaService.exe.config
entries (drdaDatabaseAliases) to instruct the DRDA Service how to interpret
and map the LOCATION and DBALIAS to a corresponding SQL Server database
name.
TRUSTED
Specify “N”. The DRDA Service does not support a trusted connection.
SECURE
Specify “Y” when connecting to the DRDA Service using Secure Sockets Layer
4.0 or Transport Layer Security 1.0.
Table 18. DB2 for z/OS Connection Database SYSIBM.LOCATION table.
-- --------------------------------------------------- Distributed Relational Database Entries
-- ---------------------------------------------------SYSIBM.LOCATIONS
--LOCATION VARCHAR(128) NOT NULL
--LINKNAME VARCHAR(24) NOT NULL
--IBMREQD CHAR(1) NOT NULL WITH DEFAULT 'N'
--PORT VARCHAR(96) NOT NULL WITH DEFAULT '446'
--TPN VARCHAR(192) NOT NULL WITH DEFAULT X’07F6C4C2’
--DBALIAS VARCHAR(128) NOT NULL
--TRUSTED CHAR(1) NOT NULL WITH DEFAULT 'N'
--SECURE CHAR(1) NOT NULL WITH DEFAULT 'N'
EXECUTE ('
DELETE FROM SYSIBM.LOCATIONS WHERE LINKNAME = ''DRDA1''
') AT DRDA_AS_Example;
GO
EXECUTE ('
INSERT INTO SYSIBM.LOCATIONS VALUES (''CONTOSO'', ''DRDA1'',
''N'', ''446'', '''', '''', ''N'', ''N'')
Service for DRDA
Page 53
GO
Example x. SYSIBM.LOCATIONS entries in DB2 for one DRDA Service (“DRDA1”).
Updating SYSIBM.IPNAMES table
These system stored procedures update the SYSIBM.IPNAMES table on DB2 for z/OS.
DB2 for z/OS
LINKNAME
Description
This value is used to associate the record in the SYSIBM.IPNAMES table to the
records in the SYSIBM.LOCATIONS, SYSIBM.IPLIST, and SYSIBM.USERNAMES
tables.
SECURITY_OUT Specify “A” to send an authorization identifier.
Optionally, specify “D” to send an encrypted authorization identifier.
Optionally, specify “E” to send an encrypted authorization identifier and
encrypted data.
Optionally, specify “P” to send an encrypted authorization identifier,
encrypted password, and encrypted data.
Do not specify “R”. The DRDA Service does not support a RACF Pass Ticket.
USERNAMES
Specify “” to send the authorization identifier associated with the logged in
user, running task or program.
Optionally, specify “O” to translate outbound authorization identifier using
the SYSIBM.USERNAMES.
Do not specify “S”. The DRDA Service does not support a trusted connection.
IBMREQD
Specify “N”.
IPADDR
Specify a value for the TCP/IP address or alias for the computer on which the
DRDA Service is running.
Optionally, leave this field blank, when configuring fault tolerant failover,
which relies on IPADDR entries in the SYSIBM.IPLIST table.
Table 19. DB2 for z/OS Connection Database SYSIBM.IPNAMES table.
--SYSIBM.IPNAMES
--SECURITY_OUT CHAR(1) NOT NULL WITH DEFAULT 'A'
---A=Already Verified
---D=Data Encrypt
---E=Auth Encrypt
---P=Password with Authorization ID
---R=RACF PassTicket
--USERNAMES CHAR(1) NOT NULL WITH DEFAULT
--IPADDR VARCHAR(254) NOT NULL WITH DEFAULT
EXECUTE ('
DELETE FROM SYSIBM.IPNAMES WHERE LINKNAME = ''DRDA1''
GO
EXECUTE ('
INSERT INTO SYSIBM.IPNAMES VALUES (''DRDA1'', ''P'', ''O'',
''N'', ''123.34.45.56'')
GO
Example x. SYSIBM.IPNAMES entries in DB2 for one DRDA Service (“DRDA1”).
Service for DRDA
Page 54
Updating SYSIBM.IPLIST table
These system stored procedures update the SYSIBM.IPLIST table on DB2 for z/OS. The IPLIST table
allows you to specify multiple IP address for a given LOCATION, when using the DRDA Service with
the Server List (SRVLST) for fault tolerant failover.
DB2 for z/OS
LINKNAME
Description
tables.
IPADDR
Specify a value for each TCP/IP address or alias for a group of computers on
which the DRDA Services are running, providing fault tolerant failover.
IBMREQD
Specify “N”.
Table 20. DB2 for z/OS Connection Database SYSIBM.IPNAMES table.
--SYSIBM.IPLIST
--IPADDR VARCHAR(254) NOT NULL WITH DEFAULT
EXECUTE ('
DELETE FROM SYSIBM.IPLIST WHERE LINKNAME = ''DRDA1'';
GO
EXECUTE ('
INSERT INTO SYSIBM.IPLIST VALUES (''DRDA1'', ''123.34.45.56'',
''N'')
GO
EXECUTE ('
INSERT INTO SYSIBM.IPLIST VALUES (''DRDA1'', ''123.34.45.57'',
''N'')
GO
Example x. SYSIBM.IPLIST entries for connecting to two DRDA Services (“DRDA1” and “DRDA2”).
Updating SYSIBM.USERNAMES table
These system stored procedures update the SYSIBM.USERNAMES table on DB2 for z/OS.
DB2 for z/OS
TYPE
AUTHID
LINKNAME
NEWAUTHID
PASSWORD
IBMREQD
Service for DRDA
Description
Specify “O” to translate outbound authorization identifier.
Do not specify “I”. The DRDA Service does not support operating as a DRDA
Application Requester client.
Do not specify “S”. The DRDA Service does not support a trusted connection.
Specify the authorization identifier to be translated.
tables.
Specify the translated value for the authorization identifier.
Specify the password.
Specify “N”.
Page 55
Table 21. DB2 for z/OS Connection Database SYSIBM.USERNAMES table.
--SYSIBM.USERNAMES
--TYPE CHAR(1) NOT NULL
---I=Inbound transalation
---O=Outbound translation
---S=Outbound AUTHID trusted connection
--AUTHID VARCHAR(128) NOT NULL WITH DEFAULT
--NEWAUTHID VARCHAR(128) NOT NULL WITH DEFAULT
--PASSWORD VARCHAR(24) NOT NULL
EXECUTE ('
DELETE FROM SYSIBM.USERNAMES WHERE LINKNAME = ''DRDA1''
GO
EXECUTE ('
INSERT INTO SYSIBM.USERNAMES VALUES (''O'', ''DBUSRID'',
''DRDA1'', '''', ''DBUSRPWD'', ''N'')
GO
EXECUTE ('
SELECT * FROM SYSIBM.LOCATIONS
EXECUTE ('
SELECT * FROM SYSIBM.IPNAMES
EXECUTE ('
SELECT * FROM SYSIBM.USERNAMES
GO
Example x. SYSIBM.USERNAMES entries in DB2 for one DRDA Service (“DRDA1”).
DRDA Connections
DRDA ARs, including IBM DB2 for z/OS, offer various methods of defining the remote DRDA
connection—network address, port, and authentication. For example, IBM DB2 for z/OS relies on a CDB
(Connection Database) comprised of a set of SYSIBM.* tables (LOCATIONS, IPNAMES, USERNAMES).
Also, IBM DB2 for z/OS supports multiple methods of initiating a DRDA connection to a remote system.
A COBOL for TSO program locally-attached to DB2 for z/OS can connect to SQL Server via the DRDA
Service using either (a) an explicit connection based on a SQL CONNECT statement or (b) an implicit
connection based on a SQL 3-part object identifier (CATALOG.SCHEMA.TABLE).
Service for DRDA
Page 56
Figure 8. DRDA directed data access supports both implicit and explicit connections.
Connect statement
A common technique is to use a SQL CONNECT statement to create an explicit connection from a local
DRDA AR to a remote DRDA AS, using pre-configured authentication, in-line authentication credentials,
or mapped credentials.
CONNECT TO CONTOSO; SELECT * FROM DSN8910.DEPT
or
CONNECT TO :LOC USER :USERID USING :PASSWORD; SELECT * FROM
DSN8910.DEPT
Example x. SQL CONNECT statements.
Three-part object identifier
Another common technique is to use a 3-part object identifier within a SQL statement to create an
implicit connection from a local DRDA AR to a remote DRDA AS.
SELECT * FROM CONTOSO.DSN8910.DEPT
Example x. Using a 3-part object identifier in a SQL statement.
Service for DRDA
Page 57
Alias for three-part object identifier
Optionally, one can encapsulate the 3-part name within a 2-part local table alias. To define an alias for
use with DB2 for z/OS and a remote DRDA Service, one must follow these steps.

Define an alias in the local DB2 for z/OS database.
CREATE ALIAS DSN8910. FOR RDB1.COL1.TABLE1

Define a corresponding synonym or view in the remote SQL Server database.
CREATE SYNONYM [DSN8910].[ADEPT] FOR [DSN8910].[DEPT]
CREATE VIEW [DSN8910].[VDEPT] ("DEPTNO", "DEPTNAME", "MGRNO",
"ADMRDEPT") AS SELECT ALL DEPTNO , DEPTNAME, MGRNO , ADMRDEPT
FROM DSN8910.DEPT

Reference the local DB2 for z/OS alias in a SQL statement.
SELECT * FROM CONTOSO.DSN8910.ADEPT
SELECT * FROM CONTOSO.DSN8910.VDEPT
Example x. Defining and using a DB2 for z/OS alias over a 3-part object identifier in a SQL statement.
Verify DB2 for z/OS to DRDA Service connection using QMF
You can verify the DB2 for z/OS to DRDA Service connection by using QMF and a number of other hostresident DB2 client programs.
1. On the Start menu, point to All Programs, point to Microsoft Host Integration Server 2010, click
Tools, and then click 3270 Client.
2. In the Host Integration Server 3270 Client (3270 Client) window, click Session menu, and then
Session Configuration.
3. In the 3270 Settings dialog, select TN3270E Server Connection, type “SYS1” in the Server Name
edit box, and then click OK.
4. On the Session menu, click Connect. The 3270 Client will display the SSCP screen. At the cursor
(lower left corner), type TSO HISDEMO, and then press Enter.
5. On the TSO/E LOGON screen, at the cursor (Password field), enter HISDEMO, and then press
Enter.
6. On the Welcome screen, press Enter, to retrieve the rest of the screen data. Below the READY
prompt, type ISPF, and then press Enter.
7. On the ISPF Primary Option Menu screen, press Enter, to clear the IBM license text. At the
cursor (Option), type U, and then press Enter.
8. At the USER OPTIONS SELECTION MENU screen, at the cursor (SELECT OPTION), type B, and
then press Enter.
9. At the DB2I PRIMARY OPTION MENU screen, at the cursor (COMMAND), type Q, and then press
Enter.
10. At the QMF HOME PANEL screen, at the cursor (COMMAND), press F6.
Service for DRDA
Page 58
11. At the SQL QUERY screen, at the cursor (COMMAND), press Tab, and then press Tab again. At
the cursor (two lines below the SQL QUERY screen label), type SELECT * FROM
NWIND.DBO.CUSTOMERS, and then press F2.
12. On the REPORT screen, view the results from the query. Optionally, press F8 to scroll forward,
and then press F11 to scroll right. Press F6 to return to the SQL QUERY screen. Press F3 to return
to the QMF HOME PANEL screen.
DB2 for z/OS Bind Copy Static SQL Packages
You can bind copy static SQL packages from DB2 for z/OS to the DRDA AS, with which to define Static
SQL Package XML files for later creation of corresponding SQL Server stored procedures. You can run the
DB2 for z/OS Bind Copy command from the DB2 Bind Package Utility or DB2 Administration utility using
a 3270 terminal emulation program.
DB2 Bind Package Utility
Enter.
cursor (Option), type U, and then press Enter.
8. On the USER OPTIONS SELECTION MENU screen, at the cursor (SELECT OPTION), type B, and
then press Enter.
9. On the DB2I PRIMARY OPTION MENU screen, at the cursor (COMMAND), type D, and then
press Enter.
10. On the DB2I DEFAULTS PANEL 1 screen, at the cursor (COMMAND), press Tab twice to place
cursor on the DB2 NAME field, type DSN1, and then press Enter.
11. On the DB2I DEFAULTS PANEL 2 screen, at the cursor (COMMAND), press Enter.
12. On the DB2I PRIMARY OPTION MENU screen, at the cursor (COMMAND), type 5, and then
press Enter.
13. On the BIND/REBIND/FREE screen, at the cursor (COMMAND), type 4, and then press Enter.
14. On the BIND PACKAGE screen, in the LOCATION NAME field type “DRDA1”, and then press Tab.
In the COLLECTION-ID field, type “DBO”, and then press Tab. In the DBRD or “COPY” option
field, type COPY, and then press Tab. In the COLLECTION-ID field, type “DBO”, and then press
Tab. In the PACKAGE-ID field, type “PKGAREAS”, and then press Tab to locate the cursor on the
Service for DRDA
Page 59
ACTION ON PACKAGE field. In the ACTION ON PACKAGE field, type “ADD”, and then press
Enter.
DB2 Admin Bind Copy Package
Enter.
cursor (Option), type M, and then press Enter.
8. On the USER OPTIONS SELECTION MENU screen, at the cursor (SELECT OPTION), type B, and
then press Enter.
9. On the IBM Products Panel screen, at the cursor (Option), type 3, and then press Enter.
10. On the DB2 Admin – Active DB2 Systems screen, at the cursor (DB2 system name), type DSN1,
and then press ENTER.
11. On the DB2 Admin – DB2 Administration Menu screen, press Enter, to clear the IBM license
text. At the cursor (Option), type 1, and then press Enter.
12. On the DB2 Admin – DSN1 System Catalog screen, at the cursor (Option), type K, and then
press Enter.
13. On the DB2 Admin – DSN1 Packages screen, at the cursor (Option), press F8 repeatedly to scroll
forward through the list, until you see the source Collection and package Name. Optionally,
press F7 to scroll to the previous items in the list. On the line corresponding with the source
Collection and package Name, under column S, type BC, and then press Enter.
14. On the DB2 Admin – DSN1 Bind Copy Package screen, at the cursor (Command), press Tab to
position the cursor in the Location field, type the target Location name (e.g. “DRDA1”). Press
Tab to position the cursor in the Collection field, type the target schema name (e.g. “DBO”), and
then press ENTER.
Service for DRDA
Page 60
Operations
The following sections provide help for operating Microsoft Service for DRDA (DRDA Service).
Managing DRDA Service
Starting DRDA Service
You can start the DRDA Service to run as a service or console application.
Windows Service
Using a Command Window, you can start the DRDA Service to run as a service, under credentials
defined in the service configuration.
administrator. The User Account Control dialog will appear. Click Yes to continue.
2. From the command prompt, enter net start msdrdaservice and press Enter.
C:\Windows\system32>net start msdrdaservice
The Microsoft Service for DRDA service is starting.
The Microsoft Service for DRDA service was started successfully.
Console Application
Using a Command Window, you can run the DRDA Service to run as a console application, under the
credentials of the command window.
2. From the command prompt, enter cd C:\Windows\system32>cd C:\Program Files\Microsoft
Host Integration Server 2013\system and press Enter.
C:\Program Files\Microsoft Host Integration Server
2013\system>MsDrdaService.exe -c
C:\Program Files (x86)\Microsoft Visual Studio
10.0\VC>msdrdaservice -c
The Microsoft Service for DRDA Version 1.0 Beta is time-sensitive
software. The software will stop running on 30/06/2013
(day/month/year), which is 264 days and 7 hours from now.
Information:0:0:[Jun 21 2012 16:46:11.581] Microsoft Service for
DRDA (build: 9.0.1651.0 )
Information:0:0:[Jun 21 2012 16:46:11.597] TCP communication
manager listening on port 446
Note: The DRDA Service trace listener will output information to the console window.
Service for DRDA
Page 61
Stopping DRDA Service
You can stop the DRDA Service when it is running as a service or console application.
Windows Service
Using a Command Window, you can stop the DRDA Service when running as a service.
2. From the command prompt, enter net stop msdrdaservice and press Enter.
C:\Windows\system32>net stop msdrdaservice
The Microsoft Service for DRDA service is stopping.
The Microsoft Service for DRDA service was stopped successfully.
Console Application
Using a Command Window, you can stop the DRDA Service when it is running as a console application.
1. From the command prompt, type CTRL+C.
C:\Windows\system32>
Note: The DRDA Service stops running as a console application, and the command prompt appears.
Connecting DRDA Clients to SQL Server Databases
The DRDA Service processes DRDA client requests into connections to local and remote SQL Server
databases. This topic discusses the operation of the MsDrdaService database connection operations.
Client Connections
At service startup, the DRDA Service will write an informational entry to the internal DRDA Service trace
listeners, notifying the IT professional of the port on which the TCP Communication Manager is listening
for in-bound DRDA application requester client connections.
Information:0:0:[Apr 30 2012 17:00:34.547] TCP communication
Remote DRDA application requester clients connect to the local DRDA Service via a TCP/IP network
connection. The DRDA client sends DRDA EXCSAT (Exchange Server Attributes), ACCSEC (Access
Security), and ACCRDB (Access Relational Database) protocol flows and data formats, to which the DRDA
Service responds with DRDA protocol replies.
Authentication
remote SQL Server database.
Service for DRDA
Page 62
SQL Server Connections
The DRDA Service communicates to upstream local or remote SQL Server databases using the ADO.NET
Framework Provider for SQL Server. The underlying SQL Client access SQL Server via an in-memory
connection, or across a network using either Named Pipes or TCP/IP. The SQL Client supports optional
encryption and failover features to improve security and reliability. The DRDA Service supports optional
single sign-on and pooling features to improve security and performance. You can edit the
MsDrdaService.exe.config file to instruct the DRDA Service on how to manage the SQL client to SQL
Server connections.
Failover Connections
The DRDA Service can operate in groups of two (2) servers, one per computer, to provide basic fault
tolerance. When a DRDA AR client connects to a SQL Server database, the DRDA Service returns a DRDA
SRVLST (Server List) with a weighted list of Data Server instances. In case of failover of a primary DRDA
Service, the DRDA AR can use this information to connect to the alternate member of a pair of DRDA
Service computers. Combined with SQL Server clustering or mirroring, this technology can offer a
reasonable level of fault tolerant failover protection.
Figure 9. DRDA clients can re-connect to DRDA Service partner server in failover scenarios.
Processing Package Binds
Server DROP PROCEDURE and CREATE PROCEDURE statements. A DRDA BGNBND flow will contain one
or more BNDSQLSTT flows, one per SQL statement stored within the package. The DRDA Service maps
one DRDA static SQL package section (with one statement) to one SQL Server stored procedure. The
DRDA Service maps or preserves the BGNBND package bind options in comments within the stored
procedures, and optional extended stored procedure properties. The DRDA Service uses an internal SQL
transformer to convert SQL command syntax, parameters, data types, cursors, and results sets.
Service for DRDA
Page 63
Optionally, you can develop a custom package bind listener to process the packages interactively with
the DRDA Service or off-line.
Bind Package to XML File
The DRDA Service can process a single BGNBND flow into a static SQL for DB2 package XML file,
preserving the original bind options and statements as defined by the DRDA BNDSQLSTT flows.
Bind Package to Stored Procedure
The DRDA Service will process a single BGNBND flow into a SQL Server stored procedure, transforming
the original statements as defined by the DRDA BNDSQLSTT flows into corresponding SQL Server syntax.
Create Procedure Statement
The DRDA Service internal package bind listener and most custom listeners will include an IF EXISTS
clause with DROP PROCEDURE statement, depending on the value of the PKGRPLOPT (Package
Replacement Option) in the BGNBND (Begin Bind) DRDA protocol flow. The default value for PKGRPLOPT
is PKGRPLALW (Package Replacement Allowed). Optionally, the value PKGRPLNA (Package Replacement
Not Allowed) can be specified.
The DRDA Service internal package bind listener and most custom listeners will include comments just
prior to the CREATE PROCEDURE statement text, which inform the DRDA Service runtime how to
execute the stored procedures.
Query Resultset
This comment instructs the DRDA Service to use a SqlClient DataReader to return the results of the
SELECT statement.
/****** RETURN RESULTSET ******/
Query Output Parameters
This comment instructs the DRDA Service to prepare OUTPUT parameters when calling the procedure
with which to return the data from the query.
/****** HAS OUTPUT PARAMS ******/
Cursor with Hold
This comment instructs the DRDA Service to hold cursors open within a transaction.
/****** CURSOR WITH HOLD ******/
Bind Options
This comment preserves the runtime DRDA BNDOPT (Bind Options) for future use.
/****** BNDOPT:
<Options><BNDCHKEXS>BNDEXSOPT</BNDCHKEXS><BNDCRTCTL>BNDNERALW</BNDCRTCTL><BND
EXPOPT>EXPNON</BNDEXPOPT><DFTRDBCOL>DBO</DFTRDBCOL><DGRIOPRL>1</DGRIOPRL><PKG
ATHOPT>PKGATHKP</PKGATHOPT><PKGATHRUL>OWNER</PKGATHRUL><PKGISOLVL>ISOLVLCS</P
KGISOLVL><PKGOWNID>PLARSEN</PKGOWNID><PKGRPLOPT>PKGRPLALW</PKGRPLOPT><QRYBLKC
TL>LMTBLKPRC</QRYBLKCTL><RDBRLSOPT>RDBRLSCMM</RDBRLSOPT><STTDATFMT>ISODATFMT<
/STTDATFMT><STTDECDEL>DECDELPRD</STTDECDEL><STTSTRDEL>STRDELAP</STTSTRDEL><ST
TTIMFMT>ISOTIMFMT</STTTIMFMT></Options> ******/
Service for DRDA
Page 64
Ignore Bind and Execute Package Commands
DRDA Client programs will bind a set of standard packages that contain basic DECLARE CURSOR
statements, with which to define how to fetch and return results on SELECT and CALL statements
against IBM DB2 for z/OS. The DRDA Service does not need to convert these packages into SQL Server
stored procedures. You can save bind processing and storage space by instructing the DRDA Service to
ignore these packages, by reading a IgnoreStandardPackages.txt file containing a delimited list of
qualified package name values.
COLID PKGNAM
SYSIBM *
*
MSCS001
*
MSUR001
*
MSRS001
*
MSRR001
*
MSNC001
NULLID SYSSH*
Example x. Contents of stock IgnoreStandardPackages.txt file.
The first row of the file contains a tab-delimited set of two values that represent column headers. The
first column header is the COLID (Collection Identifier). The second column header is the PKGNAM
(Package Name). The remaining rows of the file contain a set of tab-delimited values for collection
identifier and package name.
An asterisk in place of a value denotes any value. The Microsoft DRDA Client offers a set of tools for
defining the standard set of packages in one or more user-defined collections. In this case, the wildcard
instructs the DRDA Service to ignore bind and execution commands referencing the Microsoft DRDA
Client standard packages, no matter in which collection the packages are defined.
An asterisk at the end of a string denotes a partial value. The IBM DB2 Connect DRDA Client offers a set
of tools for defining the standard set of packages in a NULLID collection with a starting package name
value of SYSSH. In this case, the wildcard instructs the DRDA Service to ignore bind and execution
commands referencing the full set of IBM DB2 Connect DRDA Client standard packages.
Performance
This topic contains information that will help you maximize performance when you are using the DRDA
Service.
Authentication and Encryption
Authentication
The DRDA Service utilizes Microsoft Enterprise Single Sign-On for authenticating in-bound DRDA
Application Requester (e.g. DB2 for z/OS RACF user identifier and password) user credentials to outbound SQL Client to SQL Server database connection (e.g. Integrated Security with Windows Active
Directory accounts) user credentials.
As an alternative to ESSO, you can configure the MsDrdaService to use mapped authentication. The
mappedAuthenticationDomain attribute of the MsDrdaService.exe.config instructs the DRDA Service to
which Microsoft Windows Active Directory domain to map the in-bound DRDA client credentials (user
name and password), when connecting to SQL Server configured for Windows authentication using
Service for DRDA
Page 65
integrated Security Support Provider Interface (SSPI), but not when using Microsoft Enterprise Single
Sign-On.
The DRDA Service will cache the security token obtained from Microsoft Enterprise Single Sign-On and
Mapped Authentication Domain features for a configured duration of time, with which to use when
Provider Interface (SSPI).
The securityTokenTimeout attribute instructs the DRDA Service to retain a security token for a duration
of time, after which to obtain a new Windows Client Identifier (CID). This optional attribute accepts a
duration value. The default value is PT8H (Period of Time is 8 hours).
To improve performance, you can adjust the ESSO Security Token Timeout value for a longer duration.
Encryption
The DRDA Service supports the Data Provider supports authentication and data encryption using Data
Encryption Standard (DES) technologies, Secure Sockets Layer (SSL) V3.0, and Transport Layer Security
(TLS) V1.0. Also, the DRDA Service supports data encryption only using Advanced Encryption Standard
(AES) encryption. These encryption mechanisms may impact performance.
Connection
SQL Server Connection
The DRDA Service connects to a SQL Server database using the ADO.NET Framework Data Provider for
SQL Server and underlying SQL network client. To improve performance when connecting to a local SQL
Server instance, specify the Network Library=dbmslpcn to instruct the SQL Client to connect to SQL
Server using shared memory rather than a TCP/IP network connection.
To reduce connection start-up time, use SQL Server connection pooling, by setting Pooling=true in the
connection string to instruct the SQL Client to add newly created connections to the pool when closed
by the DRDA Service. To adjust the impact to the local server, set the Max Pool Size in the connection
string to define the maximum number of connections the SQL Client should retain in the connection
pool. The default value is 100. To increase scalability, set the Max Pool Size to a higher value (e.g. 1000).
DRDA Service Connection
To further reduce connection start-up time, use the MsDrdaService internal connection pool, mapping
in-bound DRDA AR client connections and authentication credentials to out-bound SQL Server database
connections and credentials, by setting a connectionCacheSize attribute to define the number of SQL
Client to SQL Server computer connections the DRDA Service will cache in the SQL Client Connection
Pool. This optional attribute accepts an integer value. The default value is 1000.
The connectionCacheTimeout attribute instructs the DRDA Service to retain a pooled connection for a
duration of time, after which to obtain a new SQL client connection. This optional attribute accepts a
duration value. The default value is PT8H (period of time is 8 hours).
Platform compatibility
Package Procedure Cache
Service for DRDA
Page 66
procedure. Prior to executing the CALL statement, the DRDA Service will fetch metadata for the SQL
Server stored procedure with which to verify the statement type (SELECT, INSERT, UPDATE, DELETE),
cursor type (WITH HOLD), parameter data types (e.g. CHAR FOR BIT), and other attributes (e.g. has
results). After fetching the metadata, the DRDA Service will cache this information, including the
mapped procedure name, for a configured interval in a package procedure cache in order to improve
performance when next executing this package section. The packageProcedureCacheFlush attribute
instructs the DRDA Service to flush the package procedure cache after a specified interval of time. This
optional attribute accepts a duration value. The default value is P1D (Period of Time is 1 Day).
The packageProcedureLastInvoke attribute instructs the DRDA Service to write the names of objects in
the package procedure cache to a text file, %DRDAROOT%\LastInvokePackageProcedures.txt, after a
specified interval of time. This optional attribute accepts a duration value. The default value is P7D
(Period of Time is 7 Days). At service startup, the DRDA Service will load this text file to pre-fetch schema
for procedures listed in the file.
To improve performance of service startup, you can edit this file and remove unneeded stored
procedure names. To disable the reading and writing of the LastInvokePackageProcedures.txt file, set
the timespan to PT0S (Period of Time Zero Seconds).
To improve performance of runtime execution, you can edit this file to include additional stored
procedure names.
SQL Syntax
The DRDA Service has a limited DB2 ANSI to SQL Server T-SQL command syntax transformer that it
utilizes for binding packages, executing static and dynamic SQL statements. Optionally, the DRDA Service
offers additional compatible DB2 functions in the form of SQL Server CLR-based functions. To improve
performance of SQL syntax transformations, enable the DRDA Service CLR-based functions.
The DRDA Service transforms static SQL for DB2 packages into SQL Server stored procedures, when
processing DRDA begin bind and bind SQL statements commands, including embedded SQL DECLARE
CURSOR statements. To improve performance, the DRDA Service returns multiple rows per fetch when
possible, unless the package or cursor is defined for single row fetch to support concurrent updating.
When defining SELECT statements for optimal read performance, the developer should include a FOR
FETCH ONLY or FOR READ ONLY clause.
Isolation Level
The DRDA Service maps the IBM DB2 isolation level in the DRDA EXCSQLSTT (Execute SQL Statement) to
the SQL Server transaction level on the ADO.NET Provider for SQL Server transaction object. To improve
performance and reduce contention on database objects, the developer should utilize DB2 isolation
level Cursor Stability (CS) that maps to SQL Server isolation level Read Committed.
Date Time Formats and Conversions
The DRDA Service will format string literal date time values from source and into target formats when
processing dynamic and static SQL statements, for specific date time and character data types. The
conversionFormats element contains dateMasks, timeMasks, and dateTimeMasks for converting to and
from DB2 and SQL Server datetime formats, and instructs the DRDA Service when to perform these
Service for DRDA
Page 67
transformations. The parsing, encoding and decoding of strings to and from date time formatted values
will consume additional DRDA Service resources.
Code Page Conversions
The DRDA Service maps code pages and supports custom code page conversions using an underlying HIS
Encoder component and the Windows National Language Support (NLS) system components. Optionally,
the DRDA Service can convert individual code points to support custom code pages. The DRDA Service
will consume additional resources when supporting custom code page conversion.
Collation Mappings
SQL Server may collate query results in a different order than what is expected by the DRDA client
program. For example, an IT professional may configure a SQL Server database to use an ANSI collation
and a DB2 for z/OS database to use EBCDIC collation.
The DRDA Service can transform a SELECT statement from DB2 ORDER BY COLLATION_KEY (collationname) syntax to SQL Server T-SQL ORDER BY COLLATE (collation_name) syntax, mapping from a DB2
collation-name value to a SQL Server collation_name value, to provide more compatible query results.
The DRDA Service can add a COLLATE clause to an ORDER BY clause, based on a default ORDER BY
collation name. The DRDA Service parsing and replacing or adding of SQL syntax will consume additional
resources.
Tracing
The DRDA Service supports a set of shared listeners to log information to text, console, event log, and
custom component. The system.diagnostics element of the hostIntegration.drdaAs.drdaService section
of the MsDrdaService.exe.config file defines and controls the various listeners.
The DRDA Service can flush trace data automatically to the trace listeners, which ensures the trace data
is captured but will increase disk I/O and reduce overall system performance. To improve performance,
set autoFlush=false, to disable automatic trace flush.
Performance Monitor
To measure performance, the DRDA Service offers performance counters. The DRDA Service
performance counters capture information about open connections, open statements, packets and
bytes sent/received, average processing time, command executions, data fetches, and transaction
commits/rollbacks.
Configuration
To measure performance, the DRDA Service offers performance counters for use with Windows
Performance Monitor. The peformanceCountersOn attribute instructs the DRDA Service to collect
information into performance counters. This optional attribute accepts a Boolean value. The default
value is false. For more information, see section on Performance. Also, for more information on
Windows Performance Monitor, see Performance Counters
(http://go.microsoft.com/fwlink/?LinkID=119211).
Service for DRDA
Page 68
Counters
The DRDA Service outputs data to these Performance Monitor Counters.
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
Active Sessions
Active SQL Connections
Active Transactions
Bytes Received
Bytes Received/sec
Bytes Sent
Bytes Sent/sec
Transactions
Transactions Commits
Transactions Commits/sec
Transactions RollBacks
Transactions/sec
DRDA Service Instances
The DRDA Service offers Performance Monitor Counters on a per-service or per-connection “instance”
basis, where an “instance” can be a process or session.
Service for DRDA
Page 69
Security and Protection
The following sections provide help for securing and protecting deployments of Microsoft Service for
DRDA (DRDA Service).
Security
The DRDA Service provides cross-platform database access and interoperability through distributed unit
of work (DUW) transactions for on-line and batch processing. The DRDA Service connects IBM DB2 DRDA
Application Requester client programs to Microsoft SQL Server databases. The DRDA Service functions
as an application server supporting the Distributed Relational Database Architecture (DRDA) protocols
and formats that are compatible with IBM products functioning as DB2 application requester clients.
The DRDA Service responds to in-bound DB2 client application requests across Transmission Control
Protocol over Internet Protocol (TCP/IP) network connections that use optional security features
described in this topic. The DRDA Service initiates out-bound SQL managed client requests using Tabular
Data Stream (TDS) using in-memory or TCP/IP network connections.
The DRDA Service processes in-bound parameterized static SQL commands that the DRDA Service maps
to out-bound dynamic SQL CALL statements to execute corresponding SQL Server stored procedures.
Also, the DRDA Service processes in-bound dynamic SQL SELECT, INSERT, UPDATE, DELETE and CALL
statements as pass-through commands to SQL Server.
The DRDA Service can authenticate in-bound client requests by mapping user name, user name and
password, or Kerberos tickets to Windows credentials. The DRDA Service supports secure authentication
and secure data encryption options.
Windows Security
Service Account
The MsDrdaService.exe must run in the context of a user or service account.
1. The service account can be the Local System, Local Service, or Network Service account.
2. The service account can be a local user account.
3. The service can be a domain user account (Domain\User).
Local Group
The service account must be a member of the HIS Administrators and HIS Runtime Users Local Groups.
1. The service account must be a member of the HIS Administrators Local Group.
2. The service account must be a member of the HIS Runtime Users Local Group.
3. The end user accounts must be a member of the HIS Runtime Users Local Group. For example,
when mapping in-bound DRDA AR user name utilizing host-initiated Enterprise Single Sign-On,
the mapped Windows user account must be a member of the HIS Runtime Users Local Group.
Local Security Policy
The service account requires these Local Security Policy settings to run as a service.

The service account requires Log on as a service.
Service for DRDA
Page 70
The service account requires these Local Security Policy settings to utilize host-initiated Enterprise Single
Sign-On.

The service account requires Act as part of the operating system.

The service account requires Access Credential Manager as a trusted caller.

The service account requires Enable computer and user accounts to be trusted for delegation.
Folder Access Control List
The MsDrdaService account requires the Folder Access Control List settings associated with the HIS
Administrators Local Group and HIS Runtime Users Local Group.
The HIS Administrators Local Group has these Folder Access Control settings.
File Folder
Modify
Read &
execute
Allow
List folder
contents
Allow
Microsoft Host
Integration Server
2013
Microsoft Host
Allow
Allow
Integration Server
2013\system
Microsoft Host
Integration Server
2013\traces
Table 22. HIS Administrators Folder Access Control List.
Read
Write
Special
permissions
Allow
Allow
Each user account requires the Folder Access Control List settings associated with the HIS Runtime Users
Local Group. For example, each user must have write access to insert lines into a MsDrdaService.DSTF
text trace file.
The HIS Runtime Users Local Group has these Folder Access Control settings.
File Folder
Modify
Read &
execute
Allow
List folder
contents
Allow
Microsoft Host
Integration Server
2013
Microsoft Host
Allow
Allow
Integration Server
2013\system
Microsoft Host
Allow
Allow
Integration Server
2013\traces
Table 23. HIS Runtime Users Folder Access Control List.
Read
Write
Special
permissions
Allow
Allow
Allow
Allow
ESSO Security Groups
4. The service account must be a member of the SSO Affiliate Administrators Local Group.
5. The service account may be a member of the SSO Administrators Local Group.
Service for DRDA
Page 71
Constrained Delegation and Kerberos
ESSO requires elevated permissions in Active Directory (Kerberos constrained delegation, and Use any
authentication protocol). ESSO requires a Kerberos Service Principal Name for the SQL Server computer
to which the DRDA Service connects.
Protection
DRDA Service Authentication Methods
DRDA Service supports multiple authentication methods, using DRDA in combination with Kerberos and
Windows Active Directory using Enterprise Single-Sign-On.
Server Authentication
IT professionals can configure the DRDA Service to use DRDA client-provided authentication credentials
that are validated on the server.




User name and password.
User name only.
Unencrypted User name with encrypted password using 256-bit Advanced Encryption Standard
(AES) to secure the authentication credentials.
Encrypted user name and password using 256-bit Advanced Encryption Standard (AES) to secure
the authentication credentials.
Kerberos Authentication
IT professionals can configure the DRDA Service to authenticate in-bound user with a Kerberos ticket,
which the DRDA Service uses to connect to SQL Server using Kerberos authentication.
IT professionals can configure the DRDA Service to use DRDA client-provided authentication credentials
that are mapped on the server to Windows Active Directory credentials.




Host-initiated validation of user name and password mapped to Windows domain account using
SQL Server integrated security.
Host-initiated validation of user name only mapped to Windows domain account using SQL
Server integrated security.
Host-initiated validation of user name and password mapped to Windows domain account, and
then mapped to SQL Server user name and password authentication.
Host-initiated validation of user name only mapped to Windows domain account, and then
mapped to SQL Server user name and password authentication.
DRDA Service authenticates based on user name only
When receiving in-bound connections from DB2 for z/OS uses DRDA Service authentication, the DRDA
Service will authenticate based on user name only. The DRDA ACCSEC (Access Security) SECMEC
(Security Mechanism) is USRIDONL (User ID only). To support this authentication method using hostinitiated Enterprise Single Sign-On, you must set the Verify external credentials property to True in the
Affiliate Application.
Service for DRDA
Page 72
DRDA Service receives and sends unencrypted data
By default, the DRDA Service sends and receives unencrypted data. We recommend that you configure
the Data Provider to use data encryption by using Secure Sockets Layer (SSL) V3.0 or Transport Layer
Security (TLS) V1.0.
The following table describes supported encryption standards for DB2.
Encryption
Authentication Data
DB2 for z/OS
Kerberos
Yes
No
V8
SSL V3
Yes
Yes
V9
TLS V1
Yes
Yes
V9
AES
Yes
No
V8 (APAR PK56287)
Table 24. DRDA Service authentication and encryption options.
DB2 for i5/OS
V5R3
V5R4
V5R4
V5R4
DB2 for LUW
V8
V9.1
V9.1
V9.5 (Fix Pack 3)
DRDA Service accepts unencrypted credentials
By default, the DRDA Service accepts in-bound connections over a TCP/IP network using basic
authentication, where the user name and password are not encrypted and are submitted in plain text.
We recommend that you configure the DRDA AR clients and DRDA Service to use authentication
encryption by using Kerberos, Secure Sockets Layer (SSL) V3.0 or Transport Layer Security (TLS) V1.0, or
authentication encryption using Advanced Encryption Standard (AES).
Additionally, when using in-bound user name for authentication, we recommend that you configure the
DRDA Service to use Enterprise Single Sign-On, which integrates Windows Active Directory® accounts
with IBM host system and DB2 credentials. Administrators map host and DB2 credentials to AD
accounts, storing these in an encrypted SQL Server database. The DRDA Service retrieves these
mappings at runtime to securely authenticate users to remote DRDA application requester clients. For
more information about Enterprise Single Sign-On, see the Host Integration Server Security User's
Guide (http://go.microsoft.com/fwlink/?LinkID=180767).
DRDA Service supports weak encryption based on DES
Optionally, the DRDA Service supports authentication and data encryption using weak 56-bit Data
Encryption Standard (DES) technologies. We recommend that you configure the Data Provider to use
authentication and data encryption by using Secure Sockets Layer (SSL) V3.0 or Transport Layer Security
(TLS) V1.0. For encrypting authentication only, you can utilize the Advanced Encryption Standard (AES)
to support 256-bit encryption.
DRDA Authentication and Encryption options
The DRDA Service supports selected DRDA authentication and encryption options.
Technology
Code Point
MsDrdaService
Kerberos
KERSEC
Yes
Plug-in
PLGIN
No
DCE
DCESEC
No
Service for DRDA
Page 73
Technology
Code Point
MsDrdaService
User ID only
USRIDONL
Yes
User ID and password
USRIDPWD
Yes
Encrypted user ID and password
EUSRIDPWD
Yes
User ID and encrypted password
USRENCPWD
Yes
User ID and password substitute
USRSBSPWD
No
User ID, password, and new password
USRIDNWPWD
No
User ID and strong password substitute
USRSSBPWD
No
Encrypted user ID only
EUSRIDONL
Yes
Encrypted user ID and security-sensitive data
EUSRIDDTA
Yes
Encrypted user Id, password, and security-sensitive data
EUSRPWDDTA
Yes
Encrypted user ID, password, new password, and security-sensitive data
EUSRNPWDDTA
No
Table 25. DRDA Authentication and Encryption options
DRDA Service configuration files
The default location for the DRDA Service files is \Program Files\Microsoft Service for DRDA. There
subfolders (System, SysWOW64, traces, and Schemas) and files that contain information that should be
kept secured. The Host Integration Server Configuration program limits access to all the files in this
folder structure to members of the HIS Administrators Local Group and HIS Runtime Users Local Group.
See Security topic for more information on security groups associated with folder security.
The DRDA Service validates the contents of the \Program Files\Microsoft Host Integration Server
2013\system\MsDrdaService.exe.config file by element and attribute type, enumerated and other
defined values, using Microsoft.HostIntegration.ConfigurationSectionHandlers.dll configuration
reader/writer component and HostIntegrationDrdaServiceConfiguration.XSD. If the application
configuration file content is not valid, the DRDA Service will not start and log a Windows application
event message.
Event 1034: The Microsoft Service for DRDA failed to load the configuration file. Verify the format of the
Microsoft Service for DRDA XML MsDrdaService.exe.config application configuration file.
2013\system\MSDRDAErrorMappings.XML file by element and attribute type, enumerated and other
defined values, using the HostIntegrationDrdaSqlErrorMappings.XSD. If the error mapping file content is
not valid, the DRDA Service will not start and log a Windows application event message.
Service for DRDA
Page 74
Event 1056: The Microsoft Service for DRDA failed to load the error mapping file. Verify the contents of
the MSDRDAErrorMappings.XML file using the HostIntegrationDrdaSqlErrorMappings.XSD file, and then
re-start the DRDA Service.
2013\system\DrdaServiceEventMessages.XML file by element and attribute type, enumerated and other
defined values. If the event messages file content is not valid, the DRDA Service will not start and log a
Windows application event message.
Event 1057: The Microsoft Service for DRDA failed to load the event messages file. Verify the contents of
the DraServiceEventMessages.XML file and then re-start the DRDA Service.
2013\system\DB2ToMSSql.XML file by element and attribute type, enumerated and other defined
values. If the DB2 to SQL data type mapping file content is not valid the DRDA Service will not start and
log a Windows application event message.
Event 1058: The Microsoft Service for DRDA failed to load the DB2 to SQL data type mapping file. Verify
the contents of the DB2ToMSSql.XML file and then re-start the DRDA Service.
2013\system\MSSQLToDB2.XML file by element and attribute type, enumerated and other defined
values. If the event messages file content is not valid, the DRDA Service will not start and log a Windows
application event message.
Event 1059: The Microsoft Service for DRDA failed to load the SQL to DB2 data type mapping file. Verify
the contents of the MSSQLToDB2.XML file and then re-start the DRDA Service.
DRDA Service Package XML
Server DROP PROCEDURE and CREATE PROCEDURE statements. Optionally, based on the
createPackageXml attribute in the MsDrdaService.exe.config file, the DRDA Service to process a single
BGNBND flow into a static SQL for DB2 package XML file, preserving the original bind options and
statements as defined by the DRDA BNDSQLSTT flows.
The DRDA Service will write a package XML file by element and attribute type, enumerated and other
defined values, using a Microsoft.HostIntegration.ConfigurationSectionHandlers.dll app.config
reader/writer component and HostIntegrationStaticSql.XSD. The DRDA Service will not process a bind,
generate a package XML file, if it cannot validate the DRDA Begin Bind (BGNBND) and Bind SQL
Statement (BNDSQLSTT) protocol flow and formatted data.
The package XML file contains information that should be kept secured. The administrator should set
the additional optional packageXmlLocation attribute to instruct the DRDA Service to write the static
SQL for DB2 package XML file to a secure folder. For example, \Program Files\Microsoft Service for
DRDA\traces. The Host Integration Server Configuration program limits access to all the files in the
traces folder to members of the HIS Administrators Local Group and HIS Runtime Users Local Group. See
Security topic for more information on security groups associated with folder security.
Service for DRDA
Page 75
DRDA Service Custom Package Bind Listener
Optionally, the administrator can define in the MsDrdaService.exe.config one or more
packageBindListener elements within the packageBindListeners element to instruct the DRDA Service to
send bind package with bind SQL statement output to optional custom bind listeners, which are
developed using the Microsoft.HostIntegration.Drda.Common.PackageBindListener component.
The Administrator should set the createPackageProcedureWithCustomSqlScripts attribute to instruct
the DRDA Service to process DRDA BGNBND and BNDSQLSTT through an external custom package bind
listener component. The DRDA Service processes a single XML document per call to a custom bind
listener, containing one or multiple static SQL package sections. The custom bind listener should
transform the XML into SQL, returning on the callback to the DRDA Service a SQL script containing a set
of DROP PROCEDURE and CREATE PROCEDURE statements only. The DRDA Service validates the callback
to ensure it contains only a set of DROP PROCEDURE and CALL PROCEDURE statements. The
administrator should set the errorWhenNoCallback attribute to instruct the DRDA Service to return
BGNBNDRM (Begin Bind Reply Message) to the DRDA AR client, when the custom bind listener
component does not return any information on the callback interface.
The administrator should instruct the DRDA Service to load only custom bind listener assemblies from a
secure directory (\Program Files\ Microsoft Host Integration Server 2013\system) that are signed and
installed into the .NET Framework Global Assembly Cache (GAC). If the DRDA Service cannot load a
custom bind listener, the DRDA Service will not start and log a Windows application event message.
Event 1027: The Microsoft Service for DRDA cannot load the text trace listener. Verify the source
attribute values of the sources element of the system.diagnostics section of the
MsDrdaService.exe.config application configuration file.
DRDA Service Trace Listeners
You can troubleshoot problems with the DRDA Service by understanding looking at trace output, the
Windows event log entries, and understanding solutions to common problems. The DRDA Service
supports multiple concurrent trace listeners, including the default Text Encoder, default Console
Encoder, ETW (Event Tracing for Windows) listener, and optional Custom Encoder.
The trace output contains information that should be kept secured. The DRDA Service runs the trace
listeners in-process. By default, the trace listeners are disabled. The administrator can enable the trace
output, on a per-listener basis, by uncommenting elements within the listeners element of the sources
element within the system.diagnostics section of the MsDrdaService.exe.config file.
The administrator should set the traceLevel attribute to instruct the DRDA Service to trace defined
collections of information, to set a maximum level of tracing. Also, the administrator should set the
optional maxTraceEntries attribute to instruct the DRDA Service to trace up to a maximum number of
entries, and then to stop tracing.
When using the text trace listener, the administrator should set the optional maxTraceFiles attribute to
instruct the DRDA Service to write the text listener trace output a maximum number of individual trace
files, and then overwrite existing trace files. Also, the administrator should set the additional optional
traceFileFolder attribute to instruct the DRDA Service where to write the text listener trace output file.
The default value is \Program Files\Microsoft Service for DRDA\traces. The Host Integration Server
Service for DRDA
Page 76
Configuration program limits access to all the files in the traces folder to members of the HIS
Administrators Local Group and HIS Runtime Users Local Group. See Security topic for more information
on security groups associated with folder security.
The DRDA Service writes messages to the Windows application event log, to track issues with tracing.
The administrator should check the event log to track and correct issues with tracing.
Event ID
1024
Level
Error
Task Category
Extension
1027
Warning
Logging
1028
Warning
Logging
1030
Information
Logging
1031
Warning
Logging
1032
Information
Logging
1043
Warning
Trace/Log
1044
Error
Trace/Log
Text
The Microsoft Service for DRDA cannot load a custom
trace listener.
The Microsoft Service for DRDA cannot load the text
trace listener. Verify the source attribute values of the
sources element of the system.diagnostics section of the
The Microsoft Service for DRDA failed to write a trace log
file. Verify the attribute values in the sharedListeners
element of the system.diagnostics section of the
The Microsoft Service for DRDA created a trace listener
instance.
The Microsoft Service for DRDA did not find trace log file
in the configured directory. The Microsoft Service for
DRDA will create a new trace log file in the default
location. Verify the source traceFileFolder value of the
sharedListeners element of the system.diagnostics
section of the MsDrdaService.exe.config application
configuration file.
The Microsoft Service for DRDA trace file contains the
maximum allowed number of trace entries. Verify the
maxTraceEntries attribute value of the sharedListeners
The Microsoft Service for DRDA failed to create specified
trace directory {0}. Using the default trace directory.
The Microsoft Service for DRDA failed to created trace
file {0}. Exception message: {1}
Table 26. DRDA Service Event Log Messages.
DRDA Service Connections to SQL Server
Server and underlying SQL Client. The administrator can use the database element of the
MsDrdaService.exe.config file to define the network settings for managing out-bound SQL client
connections.
The DRDA Service can access local and remote SQL Server database servers using in-memory, named
pipes and TCP/IP connections. The default network library is shared memory (dbmslpcn). The
administrator can check the Network Library argument value of the connectionString attribute within
the database element in the MsDrdaService.exe.config file.
Service for DRDA
Page 77
The DRDA Service can connect to remote SQL Server database servers across a TCP/IP network
connection using Secure Sockets Layer (SSL) encryption. The default is no SSL encryption. The
administrator can instruct the DRDA Service to use SSL by specifying the Encrypt=true argument value
pair in the connectionString attribute within the database element in the MsDrdaService.exe.config file.
The DRDA Service can authenticate SQL Server connections using out-bound Windows Authentication
through the Security Support Provider Interface (SSPI). The default is no SSPI. The administrator can
instruct the DRDA Service to use Windows Authentication by specifying the Integrated Security=true
argument value pair in the connectionString attribute within the database element in the
The DRDA Service uses Transact-SQL distributed transactions when connecting to SQL Server databases,
which are protected by Microsoft Distributed Transaction Coordinator (MS DTC). The administrator can
log access (source, time, summary of data) to SQL Server using DRDA Service tracing, SQL Server profiler
tracing, and MSDTC logging.
DRDA Service Failover
The DRDA Service can operate within a group to provide basic failover, using DRDA client transaction
load balancing. The group is defined by specifying a local service role (primary or secondary), available
failover partner servers, and a ping interval for monitoring the health of servers within a group. At
connection time, the primary DRDA Service returns to the DRDA client a DRDA SRVLST (Server List) with
a weighted list of DRDA Service instances. In case of failover of a primary DRDA Service, the DRDA Client
can use this information to connect to the alternate member of a pair of DRDA Service computers.
The administrator can specify a pingInterval attribute to instruct the DRDA Service how frequently to
monitor the health of partner server computers, by executing an EXCSAT (Exchange Server Attribute)
flow and checking for an EXCSATRD (EXCSAT Reply Data). The default value is 10000 milliseconds (10
seconds). The administrator can include the partner server computer IP address or alias in the optional
clientIpAddressesAllowed attribute, which restricts the DRDA Service to accepting in-bound TCP/IP
network connections from a list of known DRDA Service partner computers. The administrator can
specify the useSSL attribute to instruct the DRDA Service to use Transport Layer Security (TLS) Version
1.0 when responding to in-bound TCP/IP network connections.
The administrator can log partner pings (source, time, summary of data) using DRDA Service tracing. The
administrator can track DRDA Service primary status, partner status, and DRDA Service List changes
using the Windows application event log.
Event 1017: The Microsoft Service for DRDA is operating in partner server role.
Event 1018: The Microsoft Service for DRDA changed the DRDA SRVLST (Server List) values.
As an alternative to or in conjunction with DRDA transaction load balancing, the DRDA Service
participates in SQL Server clustering and mirroring. The administrator can specify a Failover Partner
argument value pair in the connectionString attribute within the database element in the
Service for DRDA
Page 78
DRDA Client Connections to DRDA Service
DRDA Clients connect to the DRDA Service using the DRDA protocol and formats across a TCP/IP
network connection. The administrator can use the connectionManager element of the
MsDrdaService.exe.config file contains the network, security and failover settings for managing inbound DRDA client connections.
The administrator can include the partner server computer IP address or alias in the optional
clientIpAddressesAllowed attribute, which restricts the DRDA Service to accepting in-bound TCP/IP
network connections from a list of known DRDA Client computers. Also, the administrator can specify
the useSSL attribute to instruct the DRDA Service to use Transport Layer Security (TLS) Version 1.0 when
responding to in-bound DRDA Client TCP/IP network connections. The administrator can track DRDA
Client connection attempts from disallowed IP addresses using the Windows application event log.
Event 1036: The Microsoft Service for DRDA has detected a possible denial of service attack. The
Microsoft Service for DRDA rejected DRDA client requests from TCP/IP address not configured in the
clientIpAddressesAllowed attribute of the configuration file.
The DRDA Service uses Distributed Unit of Work (DUW) transactions between DRDA Client and DRDA
Service for two-phase commit protected transactions only. The DRDA Service processes DRDA Client
connections on separate threads to provide isolation. The DRDA Service validates the DRDA Client
commands to ensure they comply with DRDA protocol code points, instance variables, command syntax,
reply messages, and formatted data values. The DRDA Service parses the command text and parameter
values to map syntax to corresponding SQL Server Transact-SQL command with parameter syntax. The
administrator can track DRDA Client authentication attempts from unauthenticated users through the
Windows application event log.
Event 1012: The Microsoft Service for DRDA failed to retrieve access token from ESSO server.
remote SQL Server database. Alternatively, the DRDA Service supports Kerberos authentication.
The administrator can log access (source, time, summary of data) to SQL Server using DRDA Service
tracing. Also, the administrator should check the event log to track and correct issues with DRDA Client
connections.
Service for DRDA
Page 79
Troubleshooting
The following sections provide help for troubleshooting deployments of Microsoft Service for DRDA
(DRDA Service).
Trace Listeners
You can troubleshoot problems with the DRDA Service by understanding looking at trace output, the
Windows event log entries, and understanding solutions to common problems.
The DRDA Service supports multiple concurrent trace listeners, including the default Text Encoder,
default Console Encoder, ETW (Event Tracing for Windows) listener, and optional Custom Encoder. The
drdaServiceTraceListeners element contains one or more drdaServiceTraceListener elements to instruct
the DRDA Service to send trace output to optional custom text trace listeners.
Trace Format
The console, text and custom trace listener output is formatted into five (5) columns of data.
Type
Column 1 is the Type of data. The Type is a string value. The Type column is divided from the Session
Identifier column by a colon. The DRDA Service writes a Type value of Information only.
Session Identifier
Column 2 is the Session Identifier. The Session Identifier is an integer value. The Session Identifier
column is divided from the Type column by a colon. The Session Identifier can be used as a correlation
identifier, matching connection information to command execution information. The DRDA Service
writes a Session Identifier of 0 for non-client connections, including service startup information and
DRDA Service-to-DRDA Service communications.
Information:0:0:[Jan 16 2013 16:52:53.815] Microsoft Service for DRDA (build: 9.0.1870.0 )
Information:0:0:[Jan 16 2013 16:52:53.817] TCP communication manager listening on port 446
Trace Level
Column 3 is the Trace Level. The Trace Level is an integer value. The Trace Level column is divided from
the Session Identifier column by a colon. The DRDA Service writes a Trace Level value of 0 to 6,
corresponding to the traceLevel attribute value.
Datetime
Column 4 is a Datetime value. The Datetime value is enclosed in square brackets to separate this column
from the preceding Trace Level and following Trace Data columns.
Trace Data
Column 5 is the Trace Data value. The Trace Data is a string value.
Event Logs
The DRDA Service logs events to the Microsoft Windows application and service log named
“DrdaService”. IT professionals can view this log using the Microsoft Windows Event Viewer. The DRDA
Service logs events to the Event Viewer.
Service for DRDA
Page 80
Event Viewer
The Event Viewer is a Microsoft Management Console (MMC) snap-in that enables you to browse and
manage event logs. It is an indispensable tool for monitoring the health of systems and troubleshooting
issues when they arise.
Event Viewer enables you to perform the following tasks:




View events from multiple event logs
Save useful event filters as custom views that can be reused
Schedule a task to run in response to an event
Create and manage event subscriptions
The Event Viewer is a Microsoft Management Console (MMC) snap-in. You can start Event Viewer by
adding the snap-in to MMC or by double-clicking the snap-in file, Eventvwr.msc, which is located in the
%SYSTEMROOT%\system32 folder. In addition, Event Viewer can be started from the Windows interface
or the command line by using the following procedures.
To start Event Viewer by using the Windows interface
1.
2.
3.
4.
5.
Click the Start button.
Click Control Panel.
Click System and Maintenance.
Click Administrative Tools.
Double-click Event Viewer.
To start Event Viewer by using a command line
1. Open a command prompt. To open a command prompt, click Start, click All Programs, click
Accessories and then click Command Prompt.
2. Type eventvwr.
The eventvwr.exe command-line tool supports options that determine the computer the snap-in will
connect to and the event logs it will display. When connecting to a computer running a previous version
of Windows, the tool can be used to start the snap-in and connect to the remote computer, but the
additional command-line options are ignored.
To display additional help for the eventvwr command-line tool, type the following command at a
command prompt: eventvwr /?.
For the latest information about Event Viewer, see Event Viewer online
(http://go.microsoft.com/fwlink/?linkid=45698).
Configuring Log Entries
See Event Log Listener topic in the Configuring Trace Listeners portion of the Data Integration
(Configuration) Deployment book.
Log Entries
The following DRDA Service events are recorded in the Microsoft Windows application and service log
named “DrdaService”.
Service for DRDA
Page 81
Event ID
1011
Event Type
Error
Event Category
Connection
Event Message Text
The Microsoft Service for DRDA cannot connect to SQL Server.
Verify the connectionString value in the
1012
Error
Connection
The Microsoft Service for DRDA failed to retrieve access token
from ESSO server.
1013
Warning
Connection
The Microsoft Service for DRDA is connecting to a remote SQL
Server ({0}) database ({1}) when configured for SQL mirroring.
1014
Warning
Connection
The Microsoft Service for DRDA is connecting to a local SQL
Server ({0}) database ({1}) when configured for SQL mirroring.
1015
Information
Connection
The Microsoft Service for DRDA TCP communication manager is
listening on port {0}.
1016
Information
Connection
The Microsoft Service for DRDA is operating in primary server
role.
1017
Information
Connection
The Microsoft Service for DRDA is operating in partner server
role.
1018
Information
Connection
The Microsoft Service for DRDA changed the DRDA SRVLST
(Server List) values.
1019
Information
Connection
The Microsoft Service for DRDA flushed package procedure
cache. The Microsoft Service for DRDA flushed the package
procedure cache based on the packageProcedureCacheFlush
attribute value in the MsDrdaService.exe.config application
configuration file.
1020
Error
Connection
The Microsoft Service for DRDA cannot listen on port {0}. Verify
the Port attribute value in the MsDrdaService.exe.config
application configuration file.
1022
Warning
Environment
The Microsoft Service for DRDA could not load a custom NLS
code page file. Verify the codePage number in the codePages
element of the encoding section of the
1023
Warning
Environment
The Microsoft Service for DRDA could not load a default NLS
code page file. Verify the ccsid number in the
applicationEncodings element of the service section of the
1024
Error
Extension
The Microsoft Service for DRDA cannot load a custom trace
listener. Verify the attribute values in the
drdaServiceTraceListeners element of the
Service for DRDA
Page 82
Event ID
1025
Event Type
Error
Event Category
Extension
Event Message Text
The Microsoft Service for DRDA cannot load a custom bind
listener. Verify the attribute values in the packageBindListeners
element of the MsDrdaService.exe.config application
configuration file.
1026
1027
Error
Warning
Internal
Logging
An internal error occurred.
The Microsoft Service for DRDA cannot load the text trace
listener. Verify the source attribute values of the sources
1028
Warning
Logging
The Microsoft Service for DRDA failed to write a trace log file.
Verify the attribute values in the sharedListeners element of
the system.diagnostics section of the MsDrdaService.exe.config
1029
Error
Warning
The Microsoft Service for DRDA cannot create a performance
counter.
1030
Information
Logging
The Microsoft Service for DRDA created a trace listener
instance.
1031
Warning
Logging
The Microsoft Service for DRDA did not find trace log file in the
configured directory. The Microsoft Service for DRDA will
create a new trace log file in the default location. Verify the
source traceFileFolder value of the sharedListeners element of
the system.diagnostics section of the MsDrdaService.exe.config
1032
Information
Logging
The Microsoft Service for DRDA trace file contains the
maximum allowed number of trace entries. Verify the
maxTraceEntries attribute value of the sharedListeners
1033
Error
Management
The Microsoft Service for DRDA cannot find the configuration
file. Verify that the Microsoft Service for DRDA
MsDrdaService.exe.config application configuration file is in
the default system directory.
1034
Error
Management
The Microsoft Service for DRDA failed to load the configuration
file. Verify the format of the Microsoft Service for DRDA XML
1035
Information
Management
The Microsoft Service for DRDA has re-read a modified
Service for DRDA
Page 83
Event ID
1036
Event Type
Warning
Event Category
Security
Event Message Text
The Microsoft Service for DRDA has detected a possible denial
of service attack. The Microsoft Service for DRDA rejected
DRDA client requests from TCP/IP address not configured in
the clientIpAddressesAllowed attribute of the configuration
file.
1037
1038
1039
1040
1042
Warning
Error
Error
Information
Information
Startup/Shutdown
Startup/Shutdown
Startup/Shutdown
Startup/Shutdown
Startup/Shutdown
The Microsoft Service for DRDA has stopped.
The Microsoft Service for DRDA cannot start.
The Microsoft Service for DRDA cannot stop.
The Microsoft Service for DRDA (Build: 9.0.1789.0) started.
The Microsoft Service for DRDA processed the package
procedure last invoke list. The Microsoft Service for DRDA
processed the package procedures listed in the
packageProcedureLastInvoke attribute value of the
1043
Warning
Trace/Log
The Microsoft Service for DRDA failed to create specified trace
directory {0}. Using the default trace directory.
1044
Error
Trace/Log
The Microsoft Service for DRDA failed to created trace file {0}.
Exception message: {1}
1056
Error
Connection
The Microsoft Service for DRDA failed to load error mappings
Xml. Error message: {0}
1057
Error
Connection
The Microsoft Service for DRDA failed to load event mappings
Xml. Error message: {0}
1058
Error
Connection
The Microsoft Service for DRDA failed to load DB2 to SQL data
mappings Xml. Error message: {0}
1059
Error
Connection
The Microsoft Service for DRDA failed to load SQL to DB2 data
mappings Xml. Error message: {0}
Table 27. DRDA Service events logged to Windows event log.
Data Type Mapping
You can customize the default data conversions by modifying the data type mapping XML files.
Code Page Mappings
You can specify service-level and application-level code page mapping overrides. Also, you can specify
code point mapping overrides within a defined code page. For more information, see Deployment.
Troubleshooting Tools
SQL Server tracing using Profiler
SQL Server Profiler is a graphical user interface to SQL Trace for monitoring an instance of the Database
Engine or Analysis Services. You can capture and save data about each event to a file or table to analyze
later. For more information, see Introducing SQL Server Profiler
Service for DRDA
Page 84
DB2 provider tracing using HIS Trace Utility
The Provider Trace Utility captures and saves information from the Microsoft client for DB2 network
connections, OLE DB interfaces and data messages. For more information, see the Host Integration
Server 2013 Trace Utility Help (http://go.microsoft.com/fwlink/?LinkID=180447) and SNA Trace Utility
Network tracing using Network Monitor
The Network Monitor captures network traffic for display and analysis. It enables you to perform tasks
such as analyzing previously captured data in user-defined methods, extracting data from defined
protocol parsers. It includes a Distributed Data Management (DDM) parser for use with the Data
Provider. Contact Microsoft Customer Support Services for a copy of the DDM parser. For more
information, see Network Monitor (http://go.microsoft.com/fwlink/?LinkID=180448).
DB2 server tracing using IBM tools
For more information, see the IBM DB2 Administration Guide for the applicable DB2 platform and
version.
Windows Server events using Event Viewer
Enterprise Single Sign-On utilizes the Windows Application event log. The Event Viewer is a Microsoft
Management Console (MMC) snap-in that enables you to browse and manage event logs. For more
information, see Event Viewer (http://go.microsoft.com/fwlink/?LinkID=131274).
Event Tracing for Windows using Performance Monitor
The DRDA Service ETW (Event Tracing for Windows) trace listener operates as an ETW provider to
output trace data to a Windows ETW controller for access by ETW consumers. The Windows
Performance Monitor uses performance counters, event trace data, and configuration information,
which can be combined into Data Collector Sets. For more information, see Performance Monitor
(http://technet.microsoft.com/en-us/library/cc749249.aspx).
Start Event Trace Session
The Windows administrator must start a DRDA Service ETW event trace session using Performance
in which you downloaded the installation program, logman start MsDrdaService -p {3B4388CE50E0-404C-A62B-E9C87D4F3BC4} -o c:\temp\MsDrdaServiceETW.etl -ets, and then click Enter.
start MsDrdaService -p {3B4388CE-50E0-404C-A62B-E9C87D4F3BC4} -o
c:\temp\MsDrdaServiceETW.etl -ets
Service for DRDA
Page 85
Example x. Start ETW event trace session command line argument with example property
values.
Stop Event Trace Session
The Windows administrator can stop a DRDA Service ETW event trace session using Performance
in which you downloaded the installation program, logman stop MsDrdaService -ets, and then
click Enter.
stop MsDrdaService -ets
Example x. Stop ETW event trace session command line argument with example property values.
Format Event Trace Session Data
The Windows administrator can format DRDA Service ETW event trace session data using Service Trace
Viewer Tool (SvcTraceViewer.exe) (http://msdn.microsoft.com/en-us/library/ms732023.aspx) or the
tracerpt command line utility.
in which you downloaded the installation program, tracerpt c:\temp\MsDrdaServiceETW.etl,
and then click Enter.
C:\temp>tracerpt c:\temp\MsDrdaServiceETW.etl
Input
---------------File(s):
c:\temp\MsDrdaServiceETW.etl
100.00%
Output
---------------DumpFile: dumpfile.xml
Service for DRDA
Page 86
Summary: summary.txt
Example x. Format ETW event trace session data command line argument with example
property values.
Solutions to Common Problems
You may encounter these common problems when using the DRDA Service.
Cannot start DRDA Service as console application
If you cannot start the DRDA Service as a console application, check to see if the DRDA Service is already
running as a service.

On the Start menu, point to All Programs, point to Microsoft Visual Studio 2010, point to Visual

From the command prompt, enter net stop msdrdaservice and press Enter.
Problem with DRDA Service installation
Error 1937. An error occurred during the installation of assembly
‘Microsoft.HostIntegration.TI.EssoHelper.Interop,version=”1.0.0.0
”,culture=”neutral”,publicKeyToken=”31BF3856AD36E35”,processorArc
hitecture=”MSIL”’. The signature or catalog could not be verified
or is not valid.
Solution is to turn off strong name verification during testing. This error is caused by the current
“unsigned” binaries in the current build. Therefore, one needs to disable strong name signing
verification. See the instructions in the DRDA Service installation and configuration document, under the
section titled “Copy Installation Files and Disable Strong Name Signing Verification”.
In the Visual Studio Command Prompt (2010) window, enter sn -Vr *,* and press the Enter key. Verify
that the command succeeded by checking the command output.
Microsoft (R) .NET Framework Strong Name Utility
4.0.30319.1
Copyright (c) Microsoft Corporation.
Version
All rights reserved.
Verification entry added for assembly '*,*'
In the Visual Studio x64 Win64 Command Prompt (2010) window, enter sn -Vr *,* and press the Enter
key. Verify that the command succeeded by checking the command output.
4.0.30319.1
Service for DRDA
Version
Page 87
Custom Listeners
At service startup, the DRDA Service will write warning entries to the internal DrdaAsTextListener and
DrdaAsConsoleListener, notifying the IT professional that the DRDA Service could not load custom
listeners (bind, text, other).
Custom Bind Listener
The DRDA Service supports custom bind listeners, which may support one of two static SQL for DB2 XML
document formats: HIS 2010 (v8.5) or HIS 2013 (v9.0). On a callback from a custom bind listener, the
DRDA Service may log this error.
Error:2:2:[sep 13 2012 10:44:09.571]
SqlDatabase::CreateXMLForPackage::OnPackageBound(xmlstring ... out
sqlscripts) no sql scripts are passed back.
Error:2:2:[sep 13 2012 10:44:09.573]
SqlDatabase::CreateXMLForPackage::OnPackageBound(xmlstring, ..., out
sqlscripts) Null and empty scripts passed from custom binder
Error:2:4:[sep 13 2012 10:44:09.575]
SqlDatabase::CreateXMLForPackage::OnPackageBound(xmlstring, ..., out
sqlscripts) at
Microsoft.HostIntegration.Drda.RDB.SqlDatabase.CreateXMLForPackage
The solution is to configure the appropriate packageXmlFormat attribute value. The packageXmlFormat
attribute instructs the DRDA Service to write the static SQL for DB2 XML file in the either v90 or v85
format. This optional attribute accepts a string value of either v85 or v90. The default value is v90.
In this case, you should try specifying the value “v85”, and then re-request the bind or bind copy
command.
packageXmlFormat="v85"
Example x. Static SQL for DB2 package XML format attribute.
Note: Microsoft HIS 2013 (V9) supports both the old and new format, which includes an associated XML
schema for validating the XML document. Microsoft HIS 2009 and HIS 2010 (V8.5) support the old
format only.
Problem with Microsoft Client for DB2 test connection failure
Could not connect to data source 'DATASOURCE':
An internal network library error has occurred. A network level
syntax error has occurred.
Solution is to verify the DRDA Service configuration for Enterprise Single Sign-On.
First, check that you configured Enterprise Single Sign-On for Host-Initiated SSO and then re-started the
EntSSO service, by following steps 6 and 7 in the section titled “Configure HIS 2010 and ESSO V4.5”.
Service for DRDA
Page 88
Second, check that you mapped the host and Windows credentials correctly, by following steps 11-13 in
the section titled “To define an ESSO Affiliate Application for Windows-initiated SSO”. Additionally,
verify that you are using the correct host credentials from the Microsoft Client for DB2 when testing the
connection.
Problem with IBM QMF for z/OS failing with location name is not known error
IBM QMF for z/OS connection failure (e.g. SELECT * FROM HISDEMO1.DBO.CUSTOMERS) will return the
following error.
The location name is not known to the local DB2 subsystem.
Solution is to verify DB2 for z/OS configuration database and re-start DDF as needed.
First, verify that you updated the DB2 for z/OS catalog tables (SYSIBM.LOCATIONS, SYSIBM.IPNAMES,
and SYSIBM.USERNAMES) with your remote relational database.
Second, ask your DB2 for z/OS administrator t to stop and re-start the DB2 for z/OS Distributed Data
Facility (DDF), which is the DRDA protocol gateway, and then re-try the SQL query.
Problem with IBM QMF for z/OS failing with unavailable resource error
following error.
Unsuccessful execution caused by an unavailable resource. (Reason
code:
00D300F4; type of resource: 00001005; and resource name: NAME).
The DRDA AS log will have the following corresponding error.
Could not map use rid/password to a valid windows account.
Ahthentication failed.
Solution is to verify DB2 for z/OS configuration database and re-start DDF as needed.
First, verify that you updated the DB2 for z/OS catalog tables (SYSIBM.LOCATIONS, SYSIBM.IPNAMES,
and SYSIBM.USERNAMES) with your remote relational database.
Second, ask your DB2 for z/OS administrator t to stop and re-start the DB2 for z/OS Distributed Data
Facility (DDF), which is the DRDA protocol gateway, and then re-try the SQL query.
Problem with IBM QMF for z/OS failing with syntax error or access rule violation
IBM QMF for z/OS, SPUFI, DB2 Admin or other program fails to query a DB2 for z/OS alias (e.g.
DBO.REMAREAS) over a SQL Server table (e.g. DRDA1.DBO.AREAS), using the DRDA AS, returning the
following error.
DSNT408I SQLCODE =
-204, SQLSTATE = 42704, SYNTAX ERROR OR
ACCESS RULE VIOLATION FROM DB2 UDB for AIX, Linux, HP-UX, Sun,
and Windows TOKENS 'DBO.REMAREAS' IS AN UNDEFINED NAME.
The DRDA AS log will have the following corresponding error.
Service for DRDA
Page 89
DrdaAs Information: 7 : [9/19/2011 4:30:55 PM] Processing
PRPSQLSTT "SELECT * FROM DBO.REMAREAS"
DrdaAs Error: 7 : [9/19/2011 4:30:55 PM] Message: Invalid object
name 'DBO.REMAREAS'.
Solution is to verify that you created a corresponding SQL Server ALIAS or VIEW.
For example:
CREATE VIEW [dbo].[REMAREAS]
AS
SELECT dbo.AREAS.*
FROM dbo.AREAS
Problem with IBM QMF for z/OS failing with a communications error
following error.
A communications error was detected.
Message No: DSQ10427.
The IBM QMF for z/OS Messages and Codes Reference defines QMF message DSQ10427 as SQLCODE 30081. The IBM DB2 for z/OS Codes Reference defines SQLCODE -30081 as communications error.
Solution is to verify the Windows Firewall exception list includes the MsDrdaService.exe program on the
DRDA Service computer.
1. On the Start menu, point to Control Panel, click System and Security, click Windows Firewall,
click Allow a program or feature through Windows Firewall, click Change settings, click Allow
another program, click Browse, enter “%DRDAROOT%\MsDrdaService.exe”, and then click
Add, and then click OK.
2. Re-start the DRDA Service.
DRDA Client SELECT or CALL Statement Fails
DRDA Client programs will bind a set of standard packages that contain basic DECLARE CURSOR
statements, with which to define how to fetch and return results on SELECT and CALL statements. If the
statement fails, then check to see if the package or collection is listed in the IgnoreStandardPacakges.txt
file. If listed, remove the reference, rebind and re-execute the statement.
Access Relational Database Connection Failure
The DRDA Service will connect to a SQL Server database using the connections string in the
MsDrdaService.exe.config in response to a DRDA ACCRDB (Access Relational Database) request. In
certain circumstances, the SQL Server database connection attempt may fail with the following error.
A network-related or instance-specific error occurred while establishing a connection to SQL
Server. The server was not found or was not accessible. Verify that the instance name is correct
Service for DRDA
Page 90
and that SQL Server is configured to allow remote connections. (provider: Named Pipes
Provider, error: 40 - Could not open a connection to SQL Server).
The DRDA Service will return to the DRDA client the following IBM DB2 error.
SQLCODE -30041
SQLSTATE 57013
Error Text: EXECUTION FAILED DUE TO UNAVAILABLE RESOURCES THAT WILL AFFECT THE
SUCCESSFUL EXECUTION OF SUBSEQUENT COMMANDS AND SQL STATEMENTS.
In these cases, you should utilize the Microsoft SQL Server documentation and best practices to
determine the cause of the connection failure.
Problem with authentication failure when using host-initiated ESSO
When receiving in-bound connections from DB2 for z/OS uses DRDA Service authentication, the DRDA
Service will authenticate based on user name only. The DRDA ACCSEC (Access Security) SECMEC
(Security Mechanism) is USRIDONL (User ID only).
The DRDA Service may write the following error to the trace listener when processing the DRDA SECCHK
(Security Check).
Failed to authenticate the user: SSO LogonExternalUser failed using specified userid/passwd.
To support this authentication method using host-initiated Enterprise Single Sign-On, you must set the
Verify external credentials property to True in the Affiliate Application.
Problem with failure to process BNDSQLSTT when parameter names contain hyphens
According to MSDN, Microsoft SQL Server does not recognize variable names and stored procedure
parameters that are delimited. These types of identifiers must comply with the rules for regular
identifiers. For more information on SQL Server Delimited Identifiers, see
http://msdn.microsoft.com/en-us/library/ms176027.aspx.
However, PL/I and COBOL parameter names contain hyphens and other special characters.
Solution is for the DRDA Service to process the BGNBND BNDSQLSTT by removing special characters and
replacing with a single underscore. For example, the DRDA Service replaces the static SQL parameter
name “PARM-1” with SQL Server stored procedure parameter name “PARM_1”. The DRDA Service uses
the replaced value when processing the BGNBIND BNDSQLSTT into a SQL Server stored procedure or
into a static SQL for DB2 XML definition file.
See list of invalid characters in the SQL Server Transact-SQL reference, at
http://msdn.microsoft.com/en-us/library/aa224033(v=SQL.80).aspx.
Original Value
tilde (~)
hyphen (-)
exclamation point (!)
left brace ({)
percent (%)
Service for DRDA
Replaced Value
Page 91
Original Value
Replaced Value
right brace (})
caret (^)
apostrophe (')
ampersand (&)
period (.)
left parenthesis (()
backslash (\)
right parenthesis ())
accent grave (`)
Table 28. DRDA Service replaces invalid characters with single underscore.
Problem with processing BGNBND BNDSQLSTT when consistency token is unreadable
The solution is for the DRDA AS to process the BGNBND BNDSQLSTT using a hexadecimal representation
of the 8-byte Consistency Token.
Problem with connection timeout when connecting to SQL Server mirroring partner
For information timeout error when a mirrored database connection is created by the on .NET
Framework Provider for SQL Server, see Microsoft KB article http://support.microsoft.com/kb/2555235.
Problem loading custom bind listener at service startup
DRDA Service will return a warning if it cannot load a custom bind listener at service startup. The
warning does not prevent the DRDA Service from starting.
This problem may be caused when the DRDA Service cannot access the custom bind listener, or the
directory in which the custom bind listener is configured to write bind copy to XML or trace files. The
administrator should set the appropriate access control list rights to these directories.
All members of the HIS Runtime User group must have read and execute rights to program files system
directory in which the custom bind listener dynamic link library is installed. All members of the HIS
Runtime Users group must have write, read and execute rights to bind copy to directories in which the
custom bind listener will write bind copy to XML and trace files.
Problem when custom bind listener does not return on the callback interface.
The DRDA Service will not return a BGNBNDRM (Begin Bind Error Reply Message) to the DRDA
Application Requester client when a custom bind listener fails to return to the DRDA Service a CREATE
PROCEDURE DDL statement. The errorWhenNoCallback attribute instructs the DRDA Service to return
BGNBNDRM (Begin Bind Reply Message) to the DRDA AR client, when the custom bind listener
component does not return any information on the callback interface. This optional attribute accepts a
Boolean value. The default value is true.
<packageBindListener
type="Microsoft.HostIntegration.Drda.Common.PackageBindListener,
errorWhenNoCallback="true"/>
Service for DRDA
Page 92
Example x. Default values for packageBindListener in the DRDA Service application configuration file.
Problem with starting DRDA Service as a command line application
When starting the DRDA Service as a command line application, the program may fail with an error.
Only one usage of each socket address (protocol/network
address/port) is normally permitted
The solution is to stop the already running DRDA Service as a Windows service.
Using a Command Window, you can stop and start the DRDA Service.
Using a Command Window, you can run the DRDA Service as an application.
3. From the command prompt, enter cd C:\Windows\system32>cd C:\Program Files\Microsoft
Host Integration Server 2013\system and press Enter.
DrdaAs Information: 0 : [10/4/2011 4:51:48 PM] Microsoft Service
for DRDA (build: 9.0.1203.0 )
DrdaAs Information: 0 : [10/4/2011 4:51:48 PM] TCP communication
Note: The DRDA Service log writer will output information to the console window.
Service for DRDA
Page 93
To disable Strong Name Signing Verification
Test builds of the Microsoft Service for DRDA are unsigned; therefore, you must disable strong name
signing verification for both 32-bit and 64-bit files.
Studio Tools, right click Visual Studio Command Prompt (2010), and click Run as administrator.
The User Account Control dialog will appear. Click Yes to continue.
2. In the Visual Studio Command Prompt (2010) window, enter sn -Vr *,* and press the Enter key.
Verify that the command succeeded by checking the command output.
4.0.30319.1
Version
3. In the Visual Studio x64 Win64 Command Prompt (2010) window, enter sn -Vr *,* and press
the Enter key. Verify that the command succeeded by checking the command output.
4.0.30319.1
Version
Cannot load Custom Package Bind Listener
At service startup, if the DRDA Service cannot load a custom package bind listener, then the DRDA
Service will log the following warning.
Warning:0:2:[Apr 30 2012 16:04:12.996] SessionManager::Initialize
PackageBindingListener failed to load type: "
Microsoft.HostIntegration.Drda.Common.PackageBindListener,
Microsoft.HostIntegration.Drda.Common, Version=9.0.1000.0,
Culture=neutral, PublicKeyToken=31bf3856ad364e35,
processorArchitecture=MSIL "
At runtime, if the MsDrdaService cannot load a custom package bind listener, then the MsDrdaService
will not return an error.
Note: The DRDA Service will continue to run without additional warning. The DRDA Service supports
multiple concurrent custom package bind listeners. The IT professional or developer should correct the
problem, based on the initial warning after DRDA Service startup.
Query against SYSIBM.SYSDUMMY1 returns SQLCODE -204
To define a SYSIBM schema and SYSDUMMY1 table, edit the USE clause to reference the target SQL
Server database, and then execute the statement.
The DRDA Service internal bind will include this comment when executing the CREATE PROCEDURE
statement.
Service for DRDA
Page 94
USE [CONTOSO]
GO
/****** Object: Schema [SYSIBM] Script Date: 09/26/2012 13:21:38 ******/
IF NOT EXISTS (SELECT * FROM sys.schemas WHERE name = N'SYSIBM')
EXEC sys.sp_executesql N'CREATE SCHEMA [SYSIBM] AUTHORIZATION [dbo]'
GO
/****** Object: Table [SYSIBM].[SYSDUMMY1] Script Date: 09/26/2012 13:21:38
******/
SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER ON
GO
SET ANSI_PADDING ON
GO
IF NOT EXISTS (SELECT * FROM sys.objects WHERE object_id =
OBJECT_ID(N'[SYSIBM].[SYSDUMMY1]') AND type in (N'U'))
BEGIN
CREATE TABLE [SYSIBM].[SYSDUMMY1](
[IBMREQD] [char](1) NOT NULL
) ON [PRIMARY]
END
GO
SET ANSI_PADDING OFF
GO
INSERT [SYSIBM].[SYSDUMMY1] ([IBMREQD]) VALUES (N'Y')
Example x. DDL to create SYSIBM schema and SYSDUMMY1 table.
Query Returns an Empty Parameter Value
The CREATE PROCEDURE statement should include a comment, to denote the one or more OUTPUT
parameters will be used to return the data from the SELECT statement.
statement.
Query Returns an Empty Resultset
When executing DECLARE CURSOR FOR SELECT, the DRDA Service may return an empty resultset and
the following error.
THE CURSOR IS NOT IN A PREPARED STATE
SQLSTATE: 26501, SQLCODE: -514
The CREATE PROCEDURE statement should include a comment, to denote the stored procedure will
return a resultset.
/****** RETURN RESULTSET ******/
statement.
Service for DRDA
Page 95
Bind Copy fails with SQLCODE -904
When executing DRDA BGNBND (Begin Bind) to copy a package from DB2 for z/OS to SQL Server, using
the DB2 Admin Bind Copy Package panel, the DB2 system may return a SQLCODE -904.
This problem can be caused by incorrect security configuration, associated with your 3270 profile used
to log into the host session.
Execute Package fails with SQLCODE 805
When executing a static SQL package from DB2 for z/OS to SQL Server, using a DB2 for z/OS locally
attached program (TSO, CICS), the DB2 system may return a SQLCODE -805.
This problem can be caused by incorrect mapping of DB2 for z/OS to SQL Server fully qualified package
naming convention. Check that the bind copy produced a stored procedure in the SQL Server schema
matching the DB2 for z/OS literal or matched collection name. Also, check that the
MsDrdaService.exe.config databaseAliases includes any required DB2 location to SQL Server database
name mappings, or DB2 collection to SQL Server schema name mappings.
<databaseAliases>
<databaseAlias sourceLocation="CONTOSO"
targetDatabase="ContosoRetailDW"
<databaseAlias sourceLocation="NWIND"
targetDatabase="Northwind"
</databaseAliases>
Further, check the comma separated values for the packageProcedureSchemaList attribute within the
database element of the MsDrdaService.exe.config.
packageProcedureSchemaList="DBO,DSN8910"
Troubleshooting Static SQL for DB2 Custom Packages
This topic describes common errors and coding mistakes that can occur when you work with the static
SQL for DB2 packages feature in Microsoft ADO.NET Provider for DB2 (Data Provider).
Common Errors
The following table describes DB2 server errors that may occur along with the actions you must take to
correct them.
SQLCODE
SQLCODE -104 (invalid statement)
SQLCODE -204 (object not found)
SQLCODE -440 (incorrect
parameters)
SQLCODE -501 (cursor not opened)
SQLCODE -551 (insufficient
privileges)
Service for DRDA
Action


Validate and match data to database schema.
Verify that the command elements match the package
schema.
Verify that the qualified object names (four-part or alias).
Verify that the command elements match the package schema.
Verify that command includes CALL STATIC.
Verify that the privileges to CREATE, BIND and EXECUTE
packages are set.
Page 96
SQLCODE
SQLCODE -601 (object name not
unique)
Table 29. Common Errors.
Action
Verify the uniqueness of the naming convention.
Common Coding Mistakes
The following table describes common coding mistakes by feature area.
Area
XML document
Description
 Every input parameter requires a parameter element. Each output column
requires a column element.
 Cursor names should be unique within a package.
 Elements are not closed or do not match.
DB2 for AS/400 In HIS 2010, the isolation level supported is No Commit (NC), which must be
isolation level
specified in the XML document as “IsolationLevel="NoCommit.
Stored
 Package creation will fail when the package name, section number, or
Procedure and
package alias is not unique.
Alias overlap
 If package creation succeeds, but the alias name is the same as a stored
procedure name, then a runtime error may result (for example, SQLCODE 440 for invalid parameters). Alternately, the DB2 server may return an
unexpected result set.
No Alias Name
 If the metadata file does not contain an alias name, then the Microsoft
client executes the statement as a stored procedure.
 If a stored procedure with the same name exists, then the stored
procedure will be executed and the program may experience unexpected
results.
 If there is no stored procedure by the same name, then the database
server will return an error that the object name is undefined (SQLCODE 204).
Table 30. Common Mistakes.
Service for DRDA
Page 97
Development – Programmer’s Guide
The following sections provide help for developing applications for use with Microsoft Service for DRDA
(DRDA Service).
Understanding Static SQL for DB2 Custom Packages
DRDA supports two methods of defining SQL statements for execution against a remote IBM DB2 DRDA
Service. First, the DRDA AR can dynamically-define SQL statements at runtime, using the DRDA
commands EXCSQLIMM (Execute Immediate SQL Statement) or EXCSQLSTT (Execute SQL Statement).
Second, the DRDA AR can statically-define SQL statements at bind time, using the DRDA commands
BGNBND (Begin Binding a Package to an RDB) and BNDSQLSTT (Bind SQL Statement to an RDB Package).
All Microsoft HIS data providers for DB2 support executing CREATE CURSOR statements within the
standard set of Microsoft static SQL packages for DB2 used to return results on SELECT and CALL
statements. See Deployment book for information on defining the standard set of packages.
Only the Microsoft ADO.NET Framework Data Provider for DB2 supports executing statements within
custom-defined static SQL packages for DB2, which are created using the
Microsoft.HostIntegration.DataAccessLibrary DataAccessControl.CreateCustomPackage interface. The
developer can write a program to execute the CreateCustomPackage interface or can use the Visual
Studio 2012 Server Explorer to reference an XML file and create the package.
Using Visual Studio 2012 or another XML editor, the enterprise developer creates a Microsoft static SQL
for DB2 package XML file, which contains elements that specify the bind options, package(s),
statement(s), optional parameter(s) and result set(s). The DRDA AR client converts the static SQL for DB2
package XML file into a DRDA BGNBND with one or more BNDSQLSTT protocol flows.
Note: The Microsoft DRDA AR client cannot execute static SQL for DB2 packages that are not defined
using the Microsoft DAL DAC interface.
Creating Static SQL for DB2 Custom Packages
Create Custom Packages Menu
You can use the tools in the Data Connections tab of the Server Explorer in Visual Studio 2012 and Visual
Studio 2010 to create custom packages. The Microsoft ADO.NET Data Provider for DB2 supports the
standard Microsoft Visual Studio Data Designer Extensibility (DDEX) interfaces to customize the Server
Explorer. The Static SQL Packages folder within MsDb2Client Data Connections contains the Create
Custom Packages menu option. You can use this option to set a reference to an XML file to create
packages in the target DB2 database. The Set Custom Package Data menu option on the connection
folder loads the XML file into the schema cache. This operation populates the packages, sections,
statements, columns and result set properties in the Static SQL Packages folder.
Note: The Data Access Tool does not offer an option for creating custom static SQL packages. The
following sections of this document provide more information on these static SQL technologies.
Create Custom Packages Class
This section describes how to automate the creation of custom packages using the classes in the
Microsoft.HostIntegration.DataAccessLibrary namespace. For the online version of the reference
Service for DRDA
Page 98
documentation, see Microsoft.HostIntegration.DataAccessLibrary Namespace
Parameters
The following table describes the parameters and return value for the
DataAccessControl.CreateCustomPackages method.
Item
Description
connStr
The connection string to use.
packageData
The package data to use.
callback
The callback to use.
Return Value
true if creation was successful; otherwise, false.
Table 31. Data Access Control Create Custom Packages parameters
Description
The IConnectionString connStr takes a Universal Data Link (UDL) file. You can define a UDL file using the
Data Source Wizard by using the Data Access Tool. The following listing shows the syntax for a UDL.
[oledb]
; Everything after this line is an OLE DB initstring Provider=DB2OLEDB;Password=PASSWORD;Persist
Security Info=True;User ID=USERID;Initial Catalog=DSN1;Authentication=Server;Defer
Prepare=False;Derive Parameters=False;Rowset Cache Size=0;Network Transport Library=TCPIP;Host
CCSID=37;PC Code Page=1252;Network Address=SYS1;Network Port=446;Package
Collection=COLLID;Default Schema=COLLID;Default Qualifier=COLLID;DBMS Platform=DB2/MVS;Process
Binary as Character=False;Connection Pooling=False;Units of Work=RUW
Calling Static SQL for DB2 Custom Packages
Package Naming Convention
DRDA defines a fully-qualified static SQL package using a PKGNAM (RDB Package Name) that consists of
these multiple parts.


RDBCOLID (RDB Collection Identifier)

PKGID (RDB Package Identifier)
Example x. Fully-qualified package name with consistency token.
Note: If more than one package has the same value for PKGNAM, then the packages are distinguished
by the VRSNAM (Version Name) or PKGCNSTKN (package name consistency token).

PKGCNSTKN (RDB Package Consistency Token)

VRSNAM (Version Name)
Service for DRDA
Page 99
Executing Static SQL Statements
You can use ADO.NET Command and Parameter objects to execute static SQL statement using an EXEC
STATIC syntax referencing the fully-qualified package name.
EXEC STATIC RDBNAME.RDBCOLID.PKGID.PKGCNSTKN.PKGSN
Example x. Command syntax for executing static SQL statement, using fully-qualified package name.
Optionally, you can use ADO.NET Command and Parameter objects to execute static SQL statement
using a CALL syntax referencing the package alias name.
CALL RDBNAME.RDBCOLID.PKALIAS.PKGSN
Example x. Command syntax for executing static SQL statement, using package alias name.
Note: When binding the package, you must specify a value for Alias (V85) or packageSectionAlias (V90).
Static SQL Result Set
The Microsoft DRDA Client can use early metadata or late metadata to interpret the result set columns.
Use Early Metadata
You can use early metadata specified in the package XML to define the result set columns (data types,
encoding). First, specify one or more Column elements in the Result Set element. Second, set the
MsDb2Client connection property Use Early Metadata to true. Third, load the static SQL for DB2 package
XML file using the MsDb2Client property.
Use Late Metadata
You can use late metadata returned by the DRDA Service to define the result set columns (data types,
encoding), by setting the MsDb2Client connection property Use Early Metadata to false.
Converting packages to stored procedures
The DRDA Service converts static SQL for DB2 packages and embedded SQL statements into SQL Server
stored procedures, by processing DRDA BGNBND (Begin Bind) and BNDSQLSTT (Bind SQL Statement)
protocol flows and formatted data values. Optionally, the DRDA Service can processing binds as XML
files, for later conversion into stored procedures or troubleshooting purposes. Further, the DRDA Service
can invoke a custom bind listener component to process BGNBND and BNDSQLSTT flows. See the
Operations book for more information on processing package bind flows. See Programmer’s Guide and
Programmer’s Reference for information on custom bind listeners.
Service for DRDA
Page 100
Figure 10. DB2 for z/OS embedded SQL is converted to DB2 packages during the DB2 pre-compile phase,
and then converted to DRDA BGNBND and BNDSQLSTT flows during the DB2 bind copy phase, and then
converted to SQL Server stored procedures by the DRDA Service when processing the DRDA bind package
and statements flows.
Static SQL Package Statements
The IBM DB2 for z/OS product and documentation includes a set of installation verification test sample
programs, including a COBOL for z/OS
EXEC SQL CONNECT TO :TEMPLOC END-EXEC
EXEC SQL INSERT INTO VHDEPT
VALUES (:DEPT-NUMB, :DEPT-NAME, :DEPT-MGR,
:DEPT-ADMR, :DEPT-LOC)
END-EXEC.
Example x. IBM DB2 for z/OS sample COBOL program with embedded SQL CONNECT and INSERT
statements.
CONNECT TO :H
INSERT INTO VHDEPT VALUES (:H, :H, :H, :H, :H )
Example x. IBM DB2 for z/OS sample COBOL program embedded SQL statement extracted by DB2 precompiler and stored in a static SQL for DB2 package—one section per statement.
<Section Number="18" Alias="">
<Statement Number="18">INSERT INTO VHDEPT VALUES ( :H , :H , :H , :H , :H ) </Statement>
<Parameters>
<Parameter Name="DEPT-NUMB" Type="Char" Length="3" Precision="0" Scale="0"
CCSID="37" Nullable="False" />
<Parameter Name="DEPT-NAME" Type="Char" Length="36" Precision="0" Scale="0"
CCSID="37" Nullable="False" />
Service for DRDA
Page 101
<Parameter
CCSID="37"
<Parameter
CCSID="37"
<Parameter
CCSID="37"
</Parameters>
</Section>
Name="DEPT-MGR" Type="Char" Length="6" Precision="0" Scale="0"
Nullable="False" />
Name="DEPT-ADMR" Type="Char" Length="3" Precision="0" Scale="0"
Nullable="False" />
Name="DEPT-LOC" Type="Char" Length="16" Precision="0" Scale="0"
Nullable="False" />
Example x. IBM DB2 for z/OS sample COBOL program static SQL for DB2 package statements converted
by the DRDA Service into a static SQL for DB2 XML file section. DB2 for z/OS does not include the
CONNECT statement in the remote DRDA-defined package.
/****** BNDOPT:
<Options><BNDCHKEXS>BNDEXSOPT</BNDCHKEXS><BNDCRTCTL>BNDNERALW</BNDCRTCTL><BNDEXPOPT>EXPNON</BNDEXP
OPT><DFTRDBCOL>CXE001</DFTRDBCOL><DGRIOPRL>1</DGRIOPRL><PKGATHOPT>PKGATHKP</PKGATHOPT><PKGISOLVL>I
SOLVLCS</PKGISOLVL><PKGOWNID>CXE001</PKGOWNID><PKGRPLOPT>PKGRPLALW</PKGRPLOPT><QRYBLKCTL>FIXROWPRC
</QRYBLKCTL><RDBRLSOPT>RDBRLSCMM</RDBRLSOPT><STTDATFMT>USADATFMT</STTDATFMT><STTDECDEL>DECDELPRD</
STTDECDEL><STTSTRDEL>STRDELAP</STTSTRDEL><STTTIMFMT>USATIMFMT</STTTIMFMT></Options> ******/
CREATE PROCEDURE [DSN8910].[DSN8HC3_18BBB2BA1492DAC8_19] @DEPT_NUMB Char(3), @DEPT_NAME Char(36),
@DEPT_MGR Char(6), @DEPT_ADMR Char(3), @DEPT_LOC Char(16)
AS
Begin INSERT INTO VHDEPT VALUES ( @DEPT_NUMB , @DEPT_NAME , @DEPT_MGR , @DEPT_ADMR ,
@DEPT_LOC ) return @@ROWCOUNT
end
GO
Example x. IBM DB2 for z/OS sample COBOL program static SQL for DB2 package statements converted
by the DRDA Service into a SQL Server CREATE PROCEDURE statement.
DRDA Service Package Bind Options
The DRDA BGNBND (Begin Bind) flow includes a set of package bind options that can influence the
storage and execution of the runtime package. The DRDA Service maps a limited number of bind options
to SQL Server constructs. The DRDA Service preserves the bind options in the static SQL for DB2 package
XML file, as comments within the stored procedure, and optionally as extended properties on the stored
procedure.
Bind Package Creation Control
The DRDA Service supports the DRDA BGNBND BNDCRTCTL (Bind Package Creation Control), which
instructs the MsDrdaService to skip over bind errors. The BNDCRTCTL code point supports an
enumeration of values.




BNDCHKONL(Bind Check Only)
BNDNERALW (Bind No Errors Allowed)
BNDERRALW (Bind Errors Allowed)
BNDNERALW (Bind No Errors Allowed)
By default, the DRDA Service defaults to BNDNERALW (Bind No Errors Allowed). The DRDA Service
returns a BGNBNDRM (BGNBND Reply Message) with an error indicating the problem, when one of the
following instances occurs.

DRDA-to-XML conversion problem
Service for DRDA
Page 102



XML-to-DDL conversion problem
Custom bind listener does return DDL on the callback interface
DRDA Service cannot execute the DDL statement
To instruct the DRDA Service to ignore errors and continue processing a package, the DRDA AR client
should specify BNDCRTCTL option BNDERRALW (Bind Errors Allowed).
When using the DB2 Administrative tool with DB2 for z/OS, the DB2 administrator can specify the option
SQLERROR “C” (Continue). When using the DB2 bind copy tool with DB2 for z/OS, the DB2 programmer
can navigate to the DB2 BIND PACKAGE panel, specify CHANGE CURRENT DEFAULTS=YES, and then set
SQLERROR PROCESSING=C.
Bind Package Replace
The DRDA Service supports the DRDA BGNBND PKGRPLOPT (Package Replacement Option), which
instructs the MsDrdaService to drop and re-create the package stored procedure. The PKGRPLOPT code
point supports a Boolean value.
Currently, we add but do not replace packages, when processing BGNBND (Begin Bind) BNDSQLSTT
(Bind SQL Statement). This option instructs DB2 for z/OS to drop and create a new copy of the package.


PKGRPLALW (Package Replacement Allowed)
PKGRPLNA (Package Replacement Not Allowed)
By default, the DRDA Service defaults to PKGRPLALW (Package Replacement Allowed). The DRDA Service
executes a DROP PROCEDURE statement prior to executing a CREATE PROCEDURE statement.
Bind Options List
The following are a list of the package bind options defined in the static SQL for DB2 package XML file.
The format of these elements, types and values differ from version of Host Integration Server to
another. In HIS 2010 (V8.5), the technology supported a version 8.5 format of these bind options. In HIS
2013 (V9.0), the technology supports a version 9.0 format of these bind options, which is more verbose
and descriptive. The HIS 2013 technology includes an XSD schema file for use with the static SQL for DB2
package XML file.
DRDA Service Static SQL Cursors
The DRDA Service transforms static SQL for DB2 packages into SQL Server stored procedures, when
processing DRDA begin bind and bind SQL statements commands, including embedded SQL DECLARE
CURSOR statements. Depending on the cursor type, the DRDA Service defines the stored procedure to
include additional input parameters (“INVOKE_TYPE”) to define the action on the cursor (e.g. open,
fetch, close). The DRDA Service includes comments in the SQL Server stored procedure to denote the
bind options (e.g. fixed row protocol) and cursor type (e.g. global, for update, read only).
Declare and Open a Cursor
The DRDA Service opens a cursor by calling a SQL Server stored procedure with an invoke type
parameter argument “@__INVOKE_TYPE__ = 0”, in response to a DRDA AR OPNQRY (Open Query) to
support a consumer program’s DECLARE CURSOR and OPEN CURSOR commands, returning a single row
to the DRDA AR in a reply to the DRDA OPNQRY command called a QRYDTA (Query Answer Data Set).
Service for DRDA
Page 103
Fetch against a Cursor
The DRDA Service fetches against a cursor by calling a SQL Server stored procedure with an invoke type
parameter argument “@__INVOKE_TYPE__ = 1” and parameter argument @__FETCH_ROW_COUNT__ =
n”, in response to a DRDA AR CNTQRY (Continue Query) to support a consumer program’s FETCH
commands, returning a single row or multiple (n) rows to the DRDA AR in a reply to the DRDA CNTQRY
command called a QRYDTA (Query Answer Data Set).
To improve performance, the DRDA Service returns multiple rows per fetch when possible, unless the
package or cursor is defined for single row fetch to support concurrent updating. See description of SQL
clause syntax and bind options below.
Close a Cursor
The DRDA Service closes a cursor by calling a SQL Server stored procedure with an invoke type
parameter argument “@__INVOKE_TYPE__ = 2”, in response to a DRDA AR CLSQRY (Close Query) to
support a consumer program’s CLOSE CURSOR command, returning to the DRDA AR a reply to the DRDA
CLSQRY command called a ENDQRYRM (End of Query Reply Message).
If the DECLARE CURSOR statements includes a SQL clause WITH HOLD, then the DRDA Service defines
the stored procedure with a DECLARE CURSOR GLOBAL option. In this case, and SQL Server will retain
the cursor over close and commit requests for the duration of the DRDA AR to DRDA Service to SQL
Server connection.
SQL Clause Syntax
The DRDA Service will include a RETURN_RESULTSET comment in the stored procedure when the
DECLARE CURSOR SQL statement includes the SQL clause DECLARE CURSOR FOR SELECT.
The DRDA Service will include a CURSOR_WITH_HOLD comment in the stored procedure when the
DECLARE CURSOR SQL statement includes the SQL clause WITH HOLD. The DRDA Service defines the
stored procedure with a DECLARE CURSOR GLOBAL option, and SQL Server will retain the cursor over
close and commit requests for the duration of the DRDA AR to DRDA Service to SQL Server connection.
The DRDA Service will include a CURSOR_FOR_UPDATE comment in the stored procedure when the
DECLARE CURSOR SQL statement includes the SQL clause FOR UPDATE. The DRDA Service defines the
stored procedure without the parameter argument @__FETCH_ROW_COUNT__ = n”. The DRDA Service
will return a single row per fetch only.
Depending on bind option, the DRDA Service interprets the SQL clause syntax FOR READ ONLY and FOR
FETCH ONLY as denoting a non-updateable cursor, against which the DRDA Service can fetch multiple
rows per CNTQRY. The DRDA Service defines the stored procedure with the parameter argument
@__FETCH_ROW_COUNT__ = n”. The DRDA Service will return a single row or multiple rows per fetch
based on the bind option.
DECLARE C2 CURSOR WITH HOLD FOR SELECT SALESKEY FROM
CONTOSO.DSN8910.BULKTST1 FOR READ ONLY
CONTOSO.DSN8910.BULKTST1 FOR FETCH ONLY
Service for DRDA
Page 104
CONTOSO.DSN8910.BULKTST1
Examples of SELECT statements defined using LMTBLKPRC that include fetch row count parameter.
Package Bind Option
The DRDA Service interprets the DRDA BGNBND (Begin Bind) option QRYBLKCTL (Query Block Protocol
Control) as an override to the cursor type and SQL clause syntax, instructing the DRDA Service to return
either a single row per fetch or multiple rows per fetch on non-updateable cursors.
The default QRYBLKCTL is LMTBLKPRC(Limited Block Query Protocol), which instructs the DRDA Service
to return multiple rows per query block, as many as will fit on average into a 32K block less the byes
required for the DRDA DSS (Data Stream Structures) for defining the column data types.
Optionally, the DB2 programmer can bind a package with DB2 CURRENTDATA=YES bind option, which is
translated to DRDA BGNBND (Begin Bind) option QRYBLKCTL (Query Block Protocol Control) FIXROWPRC
(Fixed Row Query Protocol), to instruct the DRDA Service to return a single (fixed row) per CNTQRY
(Continue Query) in response to the program’s SQL FETCH statement.
No Cursor Required
If the bind option is the default LMTBLKPRC, the Data Server defines a stored procedure with a SELECT
statement but no DECLARE CURSOR, when the statement is unambiguously read-only. See description of
SQL clause syntax and bind options below.
DECLARE C1 CURSOR FOR SELECT SALESKEY FROM
CONTOSO.DSN8910.BULKTST1 FOR READ ONLY
CONTOSO.DSN8910.BULKTST1 FOR FETCH ONLY
CONTOSO.DSN8910.BULKTST1
Examples of SELECT statements that do not require SQL Server cursors.
Data Type Conversions
The DRDA Service provides compatibility across heterogeneous vendor products and technologies, by
providing these platform conversions.
DB2 to SQL Server Data Type Mappings
The DRDA Service maps DB2 to SQL Server data types based on a defined set of mappings stored in a
Db2ToSql.xml file in the %SNAROOT%\system directory. For example, the DRDA Service converts DB2
TIMESTAMP values and formats as defined in DRDA protocol flows and formatted data into SQL Server
DATETIME2(6) values and formats as defined in stored procedures and dynamic SQL statements through
the Microsoft ADO.NET Framework Data Provider for SQL Server interfaces.
Source DB2 Type
TIME
TIMESTAMP
DATE
Service for DRDA
Target SQL Server Type
TIME
DATETIME2
DATETIME
Page 105
Source DB2 Type
CHAR
CHAR () FOR BIT DATA
CHAR () FOR MIXED DATA
CHAR () FOR SBCS DATA
CHARACTER
CHARACTER () FOR BIT DATA
FIXEDBYTE
CHARACTER () FOR MIXED DATA
CHARACTER () FOR SBCS DATA
NATIONAL CHARACTER
VARCHAR
VARCHAR () FOR BIT DATA
VARBYTE
VARCHAR () FOR MIXED DATA
VARCHAR () FOR SBCS DATA
CHARACTER VARYING
CHARACTER VARYING () FOR BIT DATA
CHARACTER VARYING () FOR MIXED DATA
CHARACTER VARYING () FOR SBCS DATA
NATIONAL CHARACTER VARYING
LONG VARCHAR FOR BIT DATA
LONG VARCHAR
GRAPHIC
VARGRAPHIC
GRAPHIC VARYING
SMALLINT
INT
INTEGER
BIGINT
DECIMAL
NUMERIC
REAL
FLOAT
DOUBLE
DOUBLE PRECISION
BLOB
BINARY LARGE OBJECT
CLOB
CLOB () FOR MIXED DATA
CLOB () FOR SBCS DATA
CHAR LARGE OBJECT
CHAR LARGE OBJECT () FOR MIXED DATA
CHAR LARGE OBJECT () FOR SBCS DATA
CHARACTER LARGE OBJECT
CHARACTER LARGE OBJECT () FOR MIXED DATA
Service for DRDA
CHAR
BINARY
NCHAR
CHAR
CHAR
BINARY
BINARY
NCHAR
CHAR
NCHAR
VARCHAR
VARBINARY
VARBINARY
NVARCHAR
VARCHAR
VARCHAR
VARBINARY
NVARCHAR
VARCHAR
NVARCHAR
IMAGE
TEXT
NCHAR
NVARCHAR
NVARCHAR
SMALLINT
INT
INT
BIGINT
DECIMAL
DECIMAL
REAL
FLOAT
FLOAT
FLOAT
IMAGE
IMAGE
TEXT
NTEXT
TEXT
TEXT
NTEXT
TEXT
TEXT
NTEXT
Page 106
Source DB2 Type
CHARACTER LARGE OBJECT () FOR SBCS DATA
Table 32. DB2 to SQL Server Data Type Mappings
TEXT
Based on source data length, the DRDA Service will convert from these source DB2 to these target SQL
Server data types.


CHAR () FOR BIT greater than 8K is mapped to VARBINARY(MAX).
CHAR () greater than 8K is mapped to VARCHAR(MAX).
CHAR|VARCHAR () FOR BIT
Depending on the the source package definition and bind copy options, SQL commands with parameters
of type CHAR|VARCHAR () FOR BIT may be encoded in the DRDA BGNBND BNDSQLSTT as
CHAR|VARCHAR (CCSID=37, 277, 1208) and not as CHAR|VARCHAR (65535), or CHAR|VARCHAR ( ) FOR
BIT, or BINARY|VARBINARY. This parameter data type encoding issue may cause the bind copy to
CREATE PROCEDURE process to fail, if the target SQL Server columns are BINARY|VARBINARY. To resolve
this problem, the MsDrdaService will automatically capture the CREATE DRDA BNDSQLSTT to SQL Server
CREATE PROCEDURE error, obtain column metadata from the SQL Server catalog with which to correct
the stored procedure parameter data types, and then re-execute the CREATE PROCEDURE statement.
SQL Server to DB2 Data Type Mappings
The DRDA Service maps DB2 to SQL Server data types based on a defined set of mappings stored in a
MsSqlToDb2.xml file in the %SNAROOT%\system directory. For example, the DRDA Service converts SQL
Server MONEY values and formats as defined by the Microsoft ADO.NET Framework Data Provider for
SQL Server interfaces into DB2 DECIMAL values and formats as defined in DRDA protocol flows and
formatted data.
SMALLINT
INT
REAL
FLOAT
SMALLMONEY
MONEY
BIT
TINYINT
BIGINT
UNIQUEIDENTIFIER
VARBINARY
TIMESTAMP
BINARY
XML
IMAGE
VARIANT
TEXT
CHAR
VARCHAR
Service for DRDA
Source DB2 Type
SMALLINT
INTEGER
REAL
DOUBLE
DECIMAL(10,4)
DECIMAL(19,4)
SMALLINT
SMALLINT
BIGINT
CHAR(38)
VARBYTE
TIMESTAMP
FIXEDBYTE
LONG VARCHAR
LONG VARCHAR
VARCHAR(32672) FOR BIT DATA
LONG VARCHAR
CHAR
VARCHAR
Page 107
NCHAR
NVARCHAR
NTEXT
DECIMAL
NUMERIC
DATETIME
DATETIMEOFFSET
DATE
TIME
SMALLDATETIME
SYSNAME
Table 33. SQL Server to DB2 Data Type Mappings
Source DB2 Type
CHAR
VARCHAR
LONG VARCHAR
DECIMAL
DECIMAL
TIMESTAMP
TIMESTAMP
DATE
TIME
TIMESTAMP
VARGRAPHIC(128)
VARCHAR columns map to CHAR parameters
The DRDA Service will process DRDA BNDSQLSTT (Bind SQL Statement) commands into SQL Server
CREATE PROCEDURE statements, transforming the DB2 DRDA data types into corresponding SQL Server
T-SQL data types. The DRDA BNDSQLSTT will define CHAR parameter types for reading and writing to
DB2 and SQL Server VARCHAR column data types. See for example the DB2 for z/OS IVT (Installation
Verification Test) sample program static SQL package DSN8HC91.DSN8HC3 and corresponding SQL
Server and DB2 tables.
CREATE TABLE DEPT (
DEPTNO CHAR(3) NOT NULL,
DEPTNAME VARCHAR(36) NOT NULL,
MGRNO CHAR(6) WITH DEFAULT NULL,
ADMRDEPT CHAR(3) NOT NULL,
LOCATION CHAR(16) WITH DEFAULT NULL
)
AUDIT NONE
DATA CAPTURE NONE
CCSID EBCDIC;
Example of DB2 CREATE TABLE statement.
CREATE TABLE [DSN8910].[DEPT](
[DEPTNO] [char](3) NOT NULL,
[DEPTNAME] [varchar](36) NOT NULL,
[MGRNO] [char](6) NULL,
[ADMRDEPT] [char](3) NOT NULL,
[LOCATION] [char](16) NULL
) ON [PRIMARY]
Example of SQL Server CREATE TABLE statement.
Service for DRDA
Page 108
UPDATE VHDEPT SET DEPTNAME = :H, MGRNO = :H, ADMRDEPT = :H,
LOCATION = :H WHERE DEPTNO = :H
Example ofDB2 embedded static SQL statement.
CREATE PROCEDURE [DSN8910].[DSN8HC3_18BBB2BA1492DAC8_24]
@P0 char(36)
,@P1 char(6)
,@P2 char(3)
,@P3 char(16)
,@P4 char(36)
AS
UPDATE VHDEPT
SET DEPTNAME = @P0,
MGRNO = @P1,
ADMRDEPT = @P2,
LOCATION = @P3
WHERE DEPTNO = @P4;
RETURN @@ROWCOUNT;
Example of SQL Server CREATE PROCEDURE statement.
Date Time Formats and Conversions
The DRDA Service converts to and from DB2 and SQL Server date time formats based on a defined set of
format masks in the MsDrdaService.exe.config file—to support interoperability between DB2, SQL
Server, ISO and string literal datetime values. See the Operations book for more information on date
masks, time masks, and datetime masks.
The DRDA Service maps DB2 data types to and from SQL Server data types.
DB2 TIME and TIMESTAMP with Hour 24
IBM DB2 TIME and TIMESTAMP can contain an Hour 24 value that is out of range of Microsoft SQL
Server TIME, DATETIME, and DATETIME2 data types.
IBM DB2 supports a TIME value range from 00.00.00 to 24.00.00, and TIMESTAMP value range from
0001-01-01-00.00.00.000000 to 9999-12-31-24.00.00.000000.
SQL Server supports a TIME value range from 00:00:00.0000000 to 23:59:59.9999999, and DATETIME2
value range from 01-01-01 00:00:00 to 9999-12-31 23:59:59.9999999.
The DRDA Service will transform DB2 TIME and TIMESTAMP values with hour 24 into SQL Server TIME,
DATETIME, and DATETIME2 values with hour 00:00:00 of the next day. For example, the DRDA Service
will transform the DB2 TIME value ’24:00:00’ into the SQL Server TIME value ’00:00:00’). For example,
the DRDA Service will transform the DB2 DATETIME value '2011-12-31-24.00.00.000000' into the SQL
Server DATETIME/DATETIME2 value '2012-01-01-00.00.00.000000'.
Service for DRDA
Page 109
BLOB and CLOB
MsDrdaService support for DB2 BLOB and CLOB is limited. MsDrdaService supports DB2 BLOB data type
mapped to SQL Server VARBINARY(MAX), with an optional mapping to IMAGE. MsDrdaService supports
DB2 CLOB data type mapped to SQL Server VARCHAR(MAX), with optional mappings to TEXT and NTEXT.
Dynamic SQL BLOB and CLOB





BLOB to and from IMAGE
BLOB to and from VARBINARY(MAX)
CLOB to and from TEXT
CLOB to and from NTEXT
CLOB to and from VARCHAR(MAX)
Static SQL BLOB and CLOB work in limited ways with these data type mappings.


Input parameters
 BLOB to VARBINARY(MAX)
 CLOB to VARCHAR(MAX)
Output parameters
 BLOB to VARBINARY(MAX)
 CLOB to VARCHAR(MAX)
 CLOB to TEXT
 CLOB to NTEXT
Microsoft recommends that you utilize the default data type mappings.
ntext, text, and image data types will be removed in a future version of Microsoft SQL Server.
Avoid using these data types in new development work, and plan to modify applications that
currently use them. Use nvarchar(max), varchar(max), and varbinary(max) instead.
Fixed and variable-length data types for storing large non-Unicode and Unicode character and
binary data. Unicode data uses the UNICODE UCS-2 character set.
For more information on ntext, text, and image data types in the SQL Server Transact-SQL reference, see
http://msdn.microsoft.com/en-us/library/ms187993(v=sql.105).aspx.
Error Code Mapping
The DRDA Service converts SQL Server error codes and messages to instances of a DRDA reply message
or a DB2 SQLCA (Communications Area) based on a defined set of mappings stored in an
MsDrdaErrorMappings.xml file in the %SNAROOT%\system directory. The in-bound SQL Server error
code is mapped to the out-bound DB2 error code. The XML document contains a set standard format, as
documented in the associated HostIntegrationDrdaSqlErrorMappings.xsd schema file.
<SqlErrorMappings>
<sqlErrorMapping
msSqlMessageId="201"
msSqlMessageSeverityLevel="16"
msSqlMessageText="Procedure or function '{0}' expects parameter '{1}',
which was not supplied."
drdaSqlCode="-313"
drdaSqlState="07001"
Service for DRDA
Page 110
drdaReasonCode=""
drdaMessageText="THE NUMBER OF HOST VARIABLES SPECIFIED IS NOT EQUAL TO
THE NUMBER OF PARAMETER MARKERS."
drdaExplanationText="The server cannot execute a SQL statement that
contains an incorrect parameter list."
drdaActionText="Verify the number and type of parameters."/>
Example. SQL Server error message mapped to DB2 error message.
Item
sqlErrorMappings
Type
element
Description
The sqlErrorMappings element contains sqlErrorMapping
definition elements.
sqlErrorMapping
element
The sqlErrorMapping element contains the definition of a
SQL Server error message mapped to a DRDA reply message.
Table 34. Microsoft SQL Server error messages.
Item
msSqlMessageId
Type
integer
Description
The msSqlMessageId attribute represents the identifier (ID)
of the message and is a unique value across the server. This
required attribute accepts an integer value.
msSqlMessageSeverityLevel integer
The msSqlMessageSeverityLevel attribute represents the
severity level of the message, between 1 and 25. This
required attribute accepts an integer value.
msSqlMessageText
string(1024) The msSqlMessageText attribute represents the message
text. This required attribute accepts a string value.
Table 35. Microsoft SQL Server error messages.
Item
drdaSqlCode
Type
integer
drdaSqlState
integer
drdaReasonCode
hex binary
drdaMessageText
string
drdaExplanationText
string
drdaActionText
string
Description
The drdaSqlCode attribute denotes the IBM DB2 SQLCODE.
This required attribute accepts an integer value.
The drdaSqlState attribute denotes the IBM DB2 SQLSTATE.
This required attribute accepts an integer value.
The drdaReasonCode attribute denotes the IBM DB2 reason
code. This optional attribute accepts a hex binary value. The
default value is 0.
The drdaMessageText attribute denotes the IBM DB2
message text. This required attribute accepts a string value.
The drdaExplanationText attribute denotes the IBM DB2
explanation text. This optional attribute accepts a string
value.
The drdaActionText attribute denotes the IBM DB2 action
text. This optional attribute accepts a string value.
Table 36. IBM DB2 error messages.
Service for DRDA
Page 111
Development - Programmer’s Reference
Locale Encoding
The DRDA Service supports locale-specific string encodings.
EBCDIC
The DRDA Service supports the below-listed SBCS (Single Byte Character Set) EBCDIC CCSIDs converted
to and from UNICODE 1208.
Name
EBCDIC - Arabic
EBCDIC - Cyrillic (Russian)
EBCDIC - Cyrillic (Serbian, Bulgarian)
EBCDIC - Denmark/ Norway (Euro)
EBCDIC - Denmark/ Norway
EBCDIC - Finland/ Sweden (Euro)
EBCDIC - Finland/ Sweden
EBCDIC - France (Euro)
EBCDIC - France
EBCDIC - Germany (Euro)
EBCDIC - Germany
EBCDIC - Greek (Modern)
EBCDIC - Greek
EBCDIC - Hebrew
EBCDIC - Icelandic (Euro)
EBCDIC - Icelandic
EBCDIC - International (Euro)
EBCDIC - International
EBCDIC - Italy (Euro)
EBCDIC - Italy
EBCDIC - Latin America/Spain (Euro)
EBCDIC - Latin America/Spain
EBCDIC - Multilingual/ ROECE (Latin-2)
EBCDIC - Thai
EBCDIC - U.S./ Canada (Euro)
EBCDIC - U.S./ Canada
EBCDIC - United Kingdom (Euro)
EBCDIC - United Kingdom
Table 37. Supported EBCDIC CCSIDs.
CCSID
420
880
1025
277
277
278
278
297
297
273
273
875
423
424
871
871
500
500
280
280
284
284
870
838
905
1026
37
37
285
285
NLS Code Page
20420
20880
21025
1142
20277
1143
20278
1147
20297
1141
20273
875
20423
20424
1149
20871
1148
500
1144
20280
1145
20284
870
20838
20905
1026
1140
37
1146
20285
Distributed Relational Database Architecture
The DRDA Service supports DRDA Version 5.
Service for DRDA
Page 112
Figure 11. DRDA Managers.
DRDA Manager Levels
The DRDA Service supports the below-listed DRDA Manager Levels.
Manager
Min Max Description
AGENT
3
7
Agent Manager represents application requester
CMNAPPC
NA
NA
SNA APPC LU6.2 conversational communications manager
CMNSYNCPT 4
4
SNA APPC LU6.2 conversational sync point communications manager
CMNTCPIP
5
8
TCP/IP communications manager
RDB
3
8
Relational database
RSYNCMGR
5
5
Resynchronization manager
SECMGR
5
8
Security manager
SQLAM
3
8
SQL application manager
SYNCPTMGR 5
7
Sync point manager
XAMGR
NA
NA
XA manager
Table 38. Supported DRDA Manager Levels.
PowerShell Module
Windows PowerShell® is a task-based command-line shell and scripting language designed especially for
system administration. Built on the .NET Framework, Windows PowerShell helps IT professionals and
power users control and automate the administration of the Windows operating system and
applications that run on Windows. The DRDA Service offers PowerShell commands as part of a common
HIS 2013 PowerShell module, Microsoft.HostIntegration.PowerShell, including a number of Cmdlet
commands to add/get/remove/set MsDrdaService.exe.config elements and attributes, as well as
commands to start/stop listeners.
Service for DRDA
Page 113
PowerShell Cmdlets
A PowerShell cmdlet is a lightweight command that is used in the Windows PowerShell environment.
The Windows PowerShell runtime invokes these cmdlets within the context of automation scripts that
are provided at the command line. The Windows PowerShell runtime also invokes them
programmatically through Windows PowerShell APIs.
The public properties that define the parameters that are available to the user or to the application that
is running the cmdlet. Cmdlets can have required, named, positional, and switch parameters. A switch
parameter is a parameter that may, or may not, be specified when the command is run. If the parameter
is specified, the Windows PowerShell runtime resolves its value as true. If the parameter is not specified,
which is typically the default, the parameter value is resolved as false. The common parameters are
added to all cmdlets and can be accessed whenever the cmdlet is run.
DRDA Service PowerShell Module Cmdlets Commands
The DRDA Service configuration is stored in the MsDrdaService.exe.config application configuration (app
config) file, and associated XML files (error message mapping and data type mapping). At runtime, the
DRDA Service will monitor the MsDrdaService.exe.config file for changes. When detected, the DRDA
Service will read and utilize the changed configuration information when processing new in-bound
connections. The DRDA Service includes a
%SNAROOT%\System\Schemas\HostIntegrationDrdaServiceConfiguration.xsd file to validate the
IT professionals can customize the DRDA Service configuration by using the DRDA Service PowerShell
module Microsoft.HostIntegration.PowerShell. The cmdlets are grouped into configuration and
operation collections.
Prerequisite software
The DRDA Service PowerShell module requires the following software products as feature prerequisites.

Microsoft PowerShell 3.0 (Windows Management Framework 3.0)
o
http://www.microsoft.com/en-us/download/details.aspx?id=34595
Start PowerShell
Start PowerShell with Administrator permissions by running one of these commands.




From the Start screen, right-click the Windows PowerShell app tile, and in the app bar, click Run
as administrator.
In Server Manager or the Desktop on the taskbar, right-click the Windows PowerShell shortcut
and then click Run as Administrator.
On the Desktop, move the cursor to the upper right corner, click Search, type PowerShell, rightclick the Windows PowerShell app tile, and in the app bar, click Run as administrator.
At the Windows PowerShell command prompt, type:
Start-Process PowerShell -Verb RunAs
Start PowerShell ISE
Service for DRDA
Page 114
Start PowerShell ISE (Integrated Scripting Environment) with Administrator permission by running one of
these commands.




From the Start screen, type ISE, right-click Windows PowerShell ISE tile, and in the app bar, click
Run as administrator.
On the taskbar, right-click Windows PowerShell and then click Run ISE as administrator.
From the Server Manager Tools menu, select Windows PowerShell ISE.
At the Windows PowerShell command prompt, type:
Start-Process PowerShell_ISE -Verb RunAs
Set Module Path
The DRDA Service PowerShell module must be in the module path. When installing the DRDA Service
using the standalone MsDrdaService.MSI, you must manually set the module path using PowerShell or
PowerShell ISE.
1. At the Windows PowerShell or PowerShell ISE command prompt, type the following command,
$CurrentValue = [Environment]::GetEnvironmentVariable("PSModulePath", "Machine")
[Environment]::SetEnvironmentVariable("PSModulePath", $CurrentValue + ";C:\Program
Files\Microsoft Host Integration Server 2013\system\ Microsoft.HostIntegration.PowerShell\
Microsoft.HostIntegration.PowerShell", "Machine")
2. Type the following Get-Module command, and then click Enter.
Get-Module Microsoft.HostIntegration.PowerShell
3. Verify the following information.
ModuleType: Binary
Version: 9.0.1000.0
Name: Microsoft.HostIntegration.PowerShell
ExportedCommands: {Add-DrdaApplicationEncoding, Remove-DrdaApplicationEncoding, GetDrdaApplicationEncoding, Add-DrdaCollationName...}
Get Module Commands
1. At the Windows PowerShell or PowerShell ISE command prompt, type the following command,
Get-Command - Microsoft.HostIntegration.PowerShell
2. Verify the following information.
Add-HisCharacterConversion
Add-HisCodePage
Add-HisDrdaApplicationEncoding
Add-HisDrdaCollationName
Add-HisDrdaDatabaseAlias
AddAdd-HisDrdaDatetimeFormat
Service for DRDA
Page 115
Add-HisDrdaPackageBindListener
Add-HisCustomCodePage
Add-HisCustomConversion
Get-DrdaApplicationEncoding
Get-DrdaCollationName
Get-DrdaDatabaseAlias
Get-DrdaDatetimeFormat
Get-DrdaPackageBindListener
Get-DrdaPackageBindProcessing
Get-DrdaPackageProcedureCache
Get-DrdaService
Get-DrdaSqlServerConnection
Get-DrdaSqlTransform
Get-DrdaTraceListener
Get-HisCustomCodePage
Get-HisCustomConversion
Remove-DrdaApplicationEncoding
Remove-DrdaCollationName
Remove-DrdaDatabaseAlias
Remove-DrdaDatetimeFormat
Remove-DrdaPackageBindListener
Remove-HisCustomCodePage
Remove-HisCustomConversion
Set-DrdaConsoleTraceListener
Set-DrdaEtwTraceListener
Set-DrdaEventLogTraceListener
Set-DrdaPackageBindProcessing
Set-DrdaPackageProcedureCache
Set-DrdaService
Set-DrdaSqlServerConnection
Set-DrdaSqlTransform
Set-DrdaTextTraceListener
Start-DrdaTraceListener
Stop-DrdaTraceListener
DRDA Service Connectivity and Package Bind Processing
DRDA Service connectivity and package binding comprises: (1) DRDA Client-to-DRDA Service
connections, (2) DRDA Service-to-SQL Server connections, (3) DRDA Service-to-DRDA Service
connections, and (4) DRDA Service package bind processing (including SQL syntax transformations).
Set-DrdaService
This Set-DrdaService cmdlet configures the DRDA Service for in-bound DRDA Client connections.
Syntax
Set-DrdaService [-PartnerServers <string>] [-Port <uint32>] [-IsPrimary ] [-UseSsl ] [-PingInterval
<uint32>] [-EnablePerformanceCounters ] [-AllowClientIpAddresses <string>] [-SslCertificatePath
<string>] [<CommonParameters>]
Service for DRDA
Page 116
Parameters
The AllowClientIpAddresses parameter restricts the DRDA Service to accepting in-bound TCP/IP
network connections from a list of known DRDA AR client computers. This optional parameter accepts a
string value. The default value is an empty string, which allows the DRDA Service to respond to all inbound client connection requests. The list is comprised of a TCP/IP address or alias semi-colon
delimited. The TCP/IP address can be defined in either IPv4 or IPv6 format. For example, 123.34.45.57;
123.34.45.58 defines a valid client list in IPv4 network address format.
The EnablePeformanceCounters parameter instructs the DRDA Service to collect information into
performance counters. This optional parameter accepts a Boolean value. The default value is false.
The IsPrimary parameter instructs the DRDA Service whether to operate in a primary role within a group
of servers. This optional parameter accepts a Boolean value. The default value is true. The primary
server will respond to all DRDA AR client requests by processing EXCSAT (Exchange Server Attributes),
ACCSEC (Access Security) and ACCRDB (Access Relational Database), including returning a SRVLST
(Server List) on the ACCRDBRM (ACCRDB Reply Message). The Server List contains a weighted priority
list of primary (highest weighted value) and secondary servers (lowest weighted values), to inform the
DRDA AR clients to which DRDA Service computer to connect.
The PartnerServers parameter defines the list of secondary server computers. This optional parameter
is required when isPrimary=false, and accepts a string value. The default value is an empty string. The
list is comprised of a TCP/IP address or alias colon-separated by a TCP/IP port number. The TCP/IP
address can be defined in either IPv4 or IPv6 format. The list can contain multiple partner server
computers semi-colon delimited. For example, 123.34.45.57:446; 123.34.45.58:446 defines a valid
partner server list in IPv4 network address format.
The PingInterval parameter instructs the DRDA Service how frequently to monitor the health of partner
server computers, by executing an EXCSAT (Exchange Server Attribute) flow and checking for an
EXCSATRD (EXCSAT Reply Data). This optional parameter accepts an integer value. The default value is
10000 milliseconds (10 seconds).
The Port parameter defines the TCP/IP Port number on which the DRDA Service must listen for in-bound
DRDA Application Requester client connection requests. This optional parameter accepts an integer
value. The default value is 446.
The SslCertificatePath parameter specifies the SSL or TLS certificate Common Name (CN). This optional
parameter is required when useSSL=true, and accepts a string value. The default value is an empty
string.
The UseSSL parameter instructs the DRDA Service to use Secure Sockets Layer (SSL) Version 3.0 and
Transport Layer Security (TLS) Version 1.0 when responding to in-bound TCP/IP network connections.
This optional parameter accepts a Boolean value. The default value is false.
Get-DrdaService
This Get-DrdaService cmdlet gets the DRDA Service configuration settings for in-bound DRDA Client
connections.
Service for DRDA
Page 117
Syntax
Get-DrdaService [<CommonParameters>]
Parameters
None.
Outputs
This Get-DrdaService cmdlet returns an object with properties: AllowClientIpAddresses (string);
IsPrimary (Boolean); PartnerServers (string); EnablePerformanceCounters (Boolean); PingInterval
(integer); Port (integer); SslCertificatePath (string); and UseSsl (Boolean).
Set-DrdaSqlServerConnection
This Set-DrdaSqlServerConnection cmdlet configures the DRDA Service for out-bound SQL Server
connections.
Syntax
Set-DrdaSqlServerConnection [-MappedAuthenticationDomain <string>] [AuthenticationLookupTimeoutDuration <string>] [-AuthenticationLookupRetryCount <uint32>] [SecurityTokenTimeoutDuration <string>] [-RollbackTransactionOnError ] [-ClientApplicationName
<ClientApplicationName>] [-DefaultCollationName <string>] [-ConnectionString <string>] [StoredProcedureCallTimeout <uint32>] [-HostInitiatedAffiliateApplication <string>] [WindowsInitiatedAffiliateApplication <string>] [-EnableArithAbort ] [<CommonParameters>]
Parameters
The AuthenticationLookupRetryCount parameter instructs the DRDA Service the number of times to
attempt a security authentication lookup request before failing. This optional parameter accepts an
integer value. The default value is 3 retries.
The AuthenticationLookupTimeoutDuration parameter instructs the DRDA Service the duration of time
to wait for a security authentication lookup request before failing. This optional parameter accepts a
string value representing an XML duration value. The default value is PT30S (Period of Time is 30
seconds). The duration value is specified in the form PnYnMnDTnHnMnS. For more information and
description of values, see Data Integration (Deployment), DRDA Service, Configuring SQL Server
Connections.
The ClientApplicationName parameter instructs the DRDA Service how to set the SQL Client Application
Name connection property. This optional parameter accepts an enumerated string value. The default
value is empty. Specify externalName to instruct the DRDA Service to use bytes 1-8 of the DRDA
External Name (EXTNAM) representing the name of the job, task or process of the DRDA AR client
program. Specify transactionIdentifier to instruct the DRDA Service to use bytes 5-8 of the EXTNAM
Service for DRDA
Page 118
representing the name of the transaction identifier of the DRDA AR client program when running in CICS
for z/OS.
The ConnectionString parameter defines the list of argument name and value pairs for use by the DRDA
Service in defining a Microsoft ADO.NET Framework Data Provider for SQL Server connection object.
This required parameter accepts a string value. The default value is Data Source=;Integrated
Security=True;MultipleActiveResultSets=True. For more information, see Data Integration
(Deployment), DRDA Service, Configuring SQL Server Connections.
The DefaultCollationName parameter instructs the DRDA Service to add a SQL Server COLLATE
(collation_name) clause, when transforming a DB2 SELECT statement with ORDER BY clause into a SQL
Server SELECT statement with ORDER BY clause. This optional parameter accepts a string value. The
default value is SQL_Latin1_General_CP1_CI_AS. For more information and description of values, see
Data Integration (Deployment), DRDA Service, Configuring Collation Mapping.
The EnableArithAbort parameter instructs the DRDA Service to issue the SET ARITHABORT statement at
connection time, to request SQL Server to terminate a query when an overflow or divide-by-zero error
occurs during query execution. This optional parameter accepts a Boolean value. The default is false.
The HostInitiatedAffiliateApplication parameter defines the Affiliate Application name that the DRDA
Service should use with Microsoft Enterprise Single Sign-On to map the in-bound DRDA AR client
credentials to a Windows Active Directory domain user, when the SQL Client uses Windows
Authentication. This optional parameter accepts a string value. The default value is an empty string,
which instructs the DRDA Service to not use host-initiated ESSO. When using host-initiated ESSO, you
must specify Integrated Security=true in the SQL Server connection string.
The MappedAuthenticationDomain parameter instructs the DRDA Service to which Microsoft Windows
Active Directory domain to map the in-bound DRDA client credentials (user name and password), when
Provider Interface (SSPI), but not when using Microsoft Enterprise Single Sign-On. This optional
parameter accepts a string value. The default value is an empty string.
The RollbackTransactionOnError parameter instructs the DRDA Service to execute a ROLLBACK
following a negative SQL Server database error. This optional parameter accepts a Boolean value. The
default value is true.
The SecurityTokenTimeout parameter instructs the DRDA Service to retain a security token for a
duration of time, after which to obtain a new Windows Client Identifier (CID). This optional parameter
accepts a duration value. The default value is PT8H (Period of Time is 8 hours). The duration value is
specified in the form PnYnMnDTnHnMnS. For more information and description of values, see Data
Integration (Deployment), DRDA Service, Configuring SQL Server Connections.
The WindowsInitiatedAffiliateApplication parameter defines the Affiliate Application name that the
DRDA Service should use with Microsoft Enterprise Single Sign-On to map the Windows Active Directory
domain user to an out-bound SQL Client credentials, when the SQL Client uses SQL Server
Authentication. This optional parameter accepts a string value. The default value is an empty string,
which instructs the DRDA Service to not use Windows-initiated ESSO. When using Windows-initiated
ESSO, you must specify Integrated Security=false in the SQL Server connection string.
Service for DRDA
Page 119
The StoredProcedureCallTimeout parameter instructs the DRDA Service the length of time (in seconds)
to wait for SQL Server to process a CALL statement to execute a stored procedure, before terminating
the attempt and generating an error. This optional parameter accepts an integer value. Valid values are
greater than or equal to 0 and less than or equal to 2147483647. A value of 0 indicates no limit (an
attempt to execute a command will wait indefinitely). The default value is 30 seconds.
Get-DrdaSqlServerConnection
This Get-DrdaSqlServerConnection cmdlet gets the DRDA Service configuration settings for out-bound
SQL Server connections.
Syntax
Get-DrdaSqlServerConnection [<CommonParameters>]
Parameters
None.
Outputs
This Get-DrdaSqlServerConnection cmdlet returns an object with properties: ArithAbort (Boolean);
AuthenticationLookupTimeout (string); AuthenticationLookupRetryCount (integer);
ClientApplicationName (string); ConnectionString (string); DefaultCollationName (string);
HostInitiatedAffiliateApplication (string); MappedAuthenticationDomain (string);
RollbackTransactionOnError (Boolean); SecurityTokenTimeoutSeconds (string);
StoredProcedureCallTimeoutSeconds (integer); and WindowsInitiatedAffiliateApplication (string).
Set-DrdaPackageBindProcessing
This Set-DrdaPackageBindProcessing cmdlet configures the DRDA Service for processing DRDA static SQL
packages into SQL Server stored procedures.
Syntax
Set-DrdaPackageBindProcessing [-CreatePackageProcedureWithCustomSqlScripts ] [PackageProcedureSchemaList <string>] [-CreatePackageProcedure ] [-CreatePackageXml ] [PackageXmlFormat <PackageXmlFormat>] [-PackageXmlLocation <string>] [StoredProcedureNameSeparator <string>] [-CreatePackageProcedureWithExtendedProperties ]
[<CommonParameters>]
Parameters
The CreatePackageProcedure parameter instructs the DRDA Service to process a single BGNBND flow
into a SQL Server stored procedure, transforming the original statements as defined by the DRDA
BNDSQLSTT flows into corresponding SQL Server syntax. This optional parameter accepts a Boolean
value. The default value is true.
Service for DRDA
Page 120
The CreatePackageProcedureWithCustomSqlScripts parameter instructs the DRDA Service to process
DRDA BGNBND and BNDSQLSTT through an external custom package bind listener component. This
optional parameter accepts a Boolean value. The default value is false.
The CreatePackageProcedureWithExtendedProperties parameter instructs the DRDA Service to
preserve the BGNBND package bind options as extended properties on the SQL Server stored procedure.
This optional parameter accepts a Boolean value. The default value is false.
The CreatePackageXml parameter instructs the DRDA Service to process a single BGNBND flow into a
static SQL for DB2 package XML file, preserving the original bind options and statements as defined by
the DRDA BNDSQLSTT flows. This optional parameter accepts a Boolean value. The default value is
false.
The PackageProcedureSchemaList instructs the DRDA Service to locate the target SQL Server stored
procedure in alternative schemas. This optional parameter accepts a string value. The default value is an
empty string. The string is comprised of a comma-separated SQL Server schema names. The
packageProcedureSchemaList parameter is similar to the IBM DB2 for z/OS CURRENT PACKAGESET
special register and SET CURRENT PACKAGESET statement.
The PackageXmlFormat parameter instructs the DRDA Service to write the static SQL for DB2 XML file in
the either v90 or v85 format. This optional parameter accepts an enumerated string value of either v85
or v90. The default value is v90.
The PackageXmlLocation parameter instructs the DRDA Service where to write the static SQL for DB2
package XML file. This optional parameter accepts a string value. The default value is c:\temp.
The StoredProcedureNameSeparator parameter instructs the DRDA Service what separator character to
use when mapping a DRDA package name to a SQL Server stored procedure name. This optional
parameter accepts a string value. The default value is a single underscore character (_).
Get-DrdaPackageBindProcessing
This Get-DrdaPackageBindProcessing cmdlet gets the DRDA Service configuration settings for processing
DRDA static SQL packages into SQL Server stored procedures.
Syntax
Get-DrdaPackageBindProcessing [<CommonParameters>]
Parameters
None.
Outputs
This Get-DrdaPackageBindProcessing cmdlet returns an object with properties: CreatePackageProcedure
(Boolean); CreatePackageXml (Boolean); PackageXmlFormat (string); PackageXmlLocation (string);
StoredProcedureNameSeparator (string); CreatePackageProcedureWithExtendedProperties (Boolean);
CreatePackageProcedureWithCustomSqlScripts (Boolean); and PackageProcedureSchemaList (string).
Service for DRDA
Page 121
Set-DrdaPackageProcedureCache
This Set-DrdaPackageProcedureCache cmdlet configures the DRDA Service for caching metadata for the
SQL Server stored procedure with which to verify the statement type, cursor type, parameter data
types, and other attributes.
Syntax
Set-DrdaPackageProcedureCache -FlushTimeSpan <string> [<CommonParameters>]
Parameters
The FlushTimeSpan parameter instructs the DRDA Service to flush the package procedure cache after a
specified interval of time. This optional parameter accepts a string value representing an XML duration
value. The default value is P1D (Period of Time is 1 Day). The duration value is specified in the form
PnYnMnDTnHnMnS. For more information and description of values, see Data Integration
(Deployment), DRDA Service, Configuring Package Bind Processing.
Get-DrdaPackageProcedureCache
This Get-DrdaPackageProcedureCache cmdlet gets the DRDA Service configuration settings for caching
metadata for the SQL Server stored procedure with which to verify the statement type, cursor type,
parameter data types, and other attributes.
Syntax
Get-DrdaPackageProcedureCache [<CommonParameters>]
Parameters
None.
Outputs
This Get-DrdaPackageProcedureCache cmdlet returns an object with property: FlushTimeSpan (string).
Set-DrdaSqlTransform
This Set-DrdaSqlTransform cmdlet configures the DRDA Service for using internal or external CLR-based
SQL transforms to convert DB2 function syntax into SQL Server T-SQL function syntax.
Syntax
Set-DrdaSqlTransform [-EnableUnicodeOutput] [-Type <SqlTransforms>] [<CommonParameters>]
Parameters
Service for DRDA
Page 122
The EnableUnicodeOutput parameter instructs the DRDA Service to encode output from the CLR-based
SQL transformer in Unicode or ANSI. This optional parameter accepts a Boolean value. The default value
is false, which instructs the DRDA Service to output ANSI CHAR and VARCHAR strings.
The SqlTransforms parameter instructs the DRDA Service to utilize internal service or external CLRbased SQL transforms. This optional parameter accepts a SqlTransforms value of Service or Clr. The
default value is Service.
Get-DrdaSqlTransform
This Get-DrdaSqlTransform cmdlet gets the DRDA Service configuration settings for using internal or
external CLR-based SQL transforms to convert DB2 function syntax into SQL Server T-SQL function
syntax.
Syntax
Get-DrdaSqlTransforms [<CommonParameters>]
Parameters
None.
Outputs
This Get-DrdaSqlTransforms cmdlet returns an object with properties: Type (SqlTransforms); and
EnableUnicodeOutput (Boolean).
Database Alias Mapping
IBM DB2 and Microsoft SQL Server databases utilize different terminology for naming objects, as can be
seen in the following table defining the fully-qualified three-part object identifier for a table. The DRDA
Service can map DB2 catalog and schema names to SQL Server catalog and schema names. For more
information, see Configuring Database Alias Mappings.
Add-DrdaDatabaseAlias
This Add-DrdaDatabaseAlias cmdlet configures the DRDA Service for mapping in-bound catalog and
schema names to outbound catalog and schema names, for use when executing static SQL packages for
DB2 commands mapped to SQL Server stored procedures.
Syntax
Add-DrdaDatabaseAlias -SourceLocation <string> -SourceCollection <string> -TargetDatabase <string> TargetSchema <string> [<CommonParameters>]
Parameters
The SourceLocation parameter defines an in-bound DRDA RDBNAM (Relational Database Name) that
the DRDA Service should use when mapping to an out-bound SQL Server database name. This optional
parameter accepts a string value. The default value is an empty string, which denotes any value.
Service for DRDA
Page 123
The SourceCollection parameter defines an in-bound DRDA COLID (Collection Identifier) that the DRDA
Service should use when mapping to an out-bound SQL Server schema name. This optional parameter
accepts a string value. The default value is an empty string, which denotes any value.
The TargetDatabase parameter defines an out-bound SQL Server database name that the DRDA Service
should use when mapping from an in-bound DRDA RDBNAM value. This optional parameter accepts a
The TargetSchema parameter defines an out-bound SQL Server schema name that the DRDA Service
should use when mapping from an in-bound DRDA COLID value. This optional parameter accepts a
Get-DrdaDatabaseAlias
This Get-DrdaDatabaseAlias cmdlet gets the DRDA Service configuration settings for mapping in-bound
catalog and schema names to outbound catalog and schema names, for use when executing static SQL
packages for DB2 commands mapped to SQL Server stored procedures.
Syntax
Get-DrdaDatabaseAlias [<CommonParameters>]
Parameters
None.
Outputs
This Get-DrdaDatabaseAlias cmdlet returns an object with collection of properties: SourceLocation
(string); SourceCollection (string); TargetDatabase (string); and TargetSchema (string).
DRDA Service Date Time Conversions
DRDA Service will format string literal date time values from source and into target formats when
processing dynamic and static SQL statements, for specific date time and character data types.
Add-DrdaDatetimeFormat
This Add-DrdaDatetimeFormat cmdlet configures the DRDA Service for processing string literal date
values within DB2 and SQL Server DATE, CHAR (10), and VARCHAR (10) data types, to convert from DB2
date format to SQL Server date format, and to convert from SQL Server date format to DB2 date format.
The dateMasks contains one or more dateMask elements to define date mappings. The dateMask
element contains a db2ToSql or sqlToDb2 to indicate the direction, and a sourceFormat and a
targetFormat to specify the mapping. For more information and description of values, see Data
Integration (Deployment), DRDA Service, Configuring Date Time Conversions.
Syntax
Add-DrdaDatetimeFormat -Conversion <Conversion> -DateFormat <DateFormats>
Service for DRDA
Page 124
Add-DrdaDatetimeFormat -Conversion <Conversion> -TimeFormat <TimeFormats>
Add-DrdaDatetimeFormat -Conversion <Conversion> -DateTimeFormat <DateTimeFormats>
Parameters
The Conversion parameter defines the direction either DB2-to-SQL or SQL-to-DB2. This required
parameter accepts an enumerated Conversion value. Specify Db2toSql to instruct the DRDA Service to
read to convert the in-bound DateTime format. Specify SqlToDb2 to instruct the DRDA Service to write
to convert the out-bound DateTime format.
The DateFormat parameter defines the format type. This required parameter accepts an enumerated
DateFormat value.
The TimeFormat parameter defines the format type. This required parameter accepts an enumerated
TimeFormat value.
The DateTimeFormat parameter defines the format type. This required parameter accepts an
enumerated DateTimeFormat value.
For more information and description of values, see Data Integration (Deployment), DRDA Service,
Configuring Date Time Conversions.
Get-DrdaDatetimeFormat
This Get-DrdaDatetimeFormat cmdlet gets the DRDA Service configuration settings for processing string
literal date values within DB2 and SQL Server DATE, CHAR (10), and VARCHAR (10) data types, to convert
from DB2 date format to SQL Server date format, and to convert from SQL Server date format to DB2
date format.
Syntax
Get-DrdaDatetimeFormat -DateTime <DateTime> [<CommonParameters>]
Parameters
The DateTime parameter instructs the DRDA Service to return a configured format conversion. This
required parameter accepts an enumerated DateTime value. There is no default value. Specify Date to
instruct the DRDA Service to return the configured Date format conversion. Specify Time to instruct the
DRDA Service to return the configured Time format conversion. Specify DateTime to instruct the DRDA
Service to return the configured DateTime format conversion.
Outputs
This Get-DrdaDatetimeFormat cmdlet returns an object with collection of properties: Db2ToSql (string);
and SqlToDb2 (string).
Service for DRDA
Page 125
Remove-DrdaDatetimeFormat
This Remove-DrdaDatetimeFormat cmdlet removes one or more DRDA Service configuration settings for
processing string literal date values within DB2 and SQL Server DATE, CHAR (10), and VARCHAR (10) data
types, to convert from DB2 date format to SQL Server date format, and to convert from SQL Server date
format to DB2 date format.
Syntax
Remove-DrdaDatetimeFormat -DateTime <DateTime> -Conversion <Conversion> -Format <string>
Parameters
The DateTime parameter instructs the DRDA Service to remove a configured format conversion. This
required parameter accepts an enumerated DateTime value. There is no default value. Specify Date to
instruct the DRDA Service to remove the configured Date format conversion. Specify Time to instruct the
DRDA Service to remove the configured Time format conversion. Specify DateTime to instruct the DRDA
Service to remove the configured DateTime format conversion.
The Conversion parameter defines the direction either DB2-to-SQL or SQL-to-DB2. This required
parameter accepts an enumerated Conversion value. Specify Db2toSql to instruct the DRDA Service to
read to convert the in-bound DateTime format. Specify SqlToDb2 to instruct the DRDA Service to write
to convert the out-bound DateTime format.
The Format parameter defines the format type. This required parameter accepts an enumerated
DateFormat, TimeFormat, or DateTimeFormat value.
DRDA Service Encodings
DRDA Service maps code pages and supports custom code page conversions using an underlying HIS
Encoder component and the Windows National Language Support (NLS) system components. Using
Microsoft Windows Update, you can install additional Windows language packs that include Windows
NLS code page conversion libraries. Optionally, the HIS Encoder can load a custom NLS code page based
on codePage elements defined within the codePages portion of the MsDrdaService.exe.config file. The
HIS Encoder can custom map code points within standard NLS and custom NLS code pages based on
ebcdicToUnicodeConversion elements defined within the codePages portion of the
MsDrdaService.exe.config file. For more information and description of values, see Configuring Service
Encodings.
Add-HisCustomCodePage
This Add-HisCustomCodePage cmdlet configures the DRDA Service to instruct the HIS Encoder
component to load a custom Windows National Language Support (NLS) system code page conversion
file.
Syntax
Service for DRDA
Page 126
Add-HisCustomCodePage -CodePage <uint32> -Name <string> -NlsCodePage <uint32> [-Description
<string>] [<CommonParameters>]
Parameters
The CodePage parameter instructs the HIS Encoder to load a numbered custom NLS code page file. This
required parameter accepts an integer. The default value is 0.
The Name parameter names the custom NLS code page that the HIS Encoder should load based on the
defined custom NLS code page number. This required parameter accepts a string. The default value is
an empty string.
The NlsCodePage parameter defines which standard NLS code page number that the HIS Encoder should
replace with the custom code page number. This required parameter accepts an integer. The default
value is 0.
The Description parameter describes the custom NLS code page that the HIS Encoder should load based
on the defined custom NLS code page number. This optional parameter accepts a string. The default
Get-HisCustomCodePage
This Get-HisCustomCodePage cmdlet gets the DRDA Service configuration settings for instructing the HIS
Encoder component to load a custom Windows National Language Support (NLS) system code page
conversion file.
Syntax
Get-HisCustomCodePage [-CodePage <uint32>] [-Name <string>] [-NlsCodePage <uint32>]
Parameters
The CodePage parameter instructs the DRDA Service to get configuration settings using this numbered
custom NLS code page file. This optional parameter accepts an integer. The default value is 0.
The Name parameter instructs the DRDA Service to get configuration settings using this custom NLS
code page name. This optional parameter accepts a string. The default value is an empty string.
The NlsCodePage parameter instructs the DRDA Service to get configuration settings using this custom
code page number. This optional parameter accepts an integer. The default value is 0.
Outputs
This Get-HisCustomCodePage cmdlet returns an object with properties: Name (string); CodePage
(integer); NlsCodePage (integer); and Description (string).
Service for DRDA
Page 127
Remove-HisCustomCodePage
This Remove-HisCustomCodePage cmdlet removes the DRDA Service configuration settings for
instructing the HIS Encoder component to load a custom Windows National Language Support (NLS)
system code page conversion file.
Syntax
Remove-HisCustomCodePage [-Name] <string> [<CommonParameters>]
Parameters
The Name parameter instructs the DRDA Service to remove configuration settings using custom NLS
code page name. This required parameter accepts a string. The default value is an empty string.
Add-HisCustomConversion
This Add-HisCustomConversion cmdlet configures the DRDA Service to override code point mappings
within standard NLS and custom NLS code pages.
Syntax
Add-HisCustomConversion -CodePage <uint32> [-EbcdicToUnicode <string[]>] [-UnicodeToEbcdic
<string[]>] [<CommonParameters>]
Add-HisCustomConversion -Name <string> [-EbcdicToUnicode <string[]>] [-UnicodeToEbcdic <string[]>]
Parameters
The CodePage parameter instructs the DRDA Service to add configuration settings using this numbered
NLS code page file. This required parameter accepts an integer. The default value is 0.
The Name parameter instructs the DRDA Service to add configuration settings using this custom NLS
code page name file. This required parameter accepts a string. The default value is an empty string.
The EbcdicToUnicode parameter instructs the HIS Encoder to convert from the specified EBCDIC code
point. This optional parameter accepts a string value, in the form of “To=From” where the “To” is
EBCDIC hex code point value and the “From” is the Unicode hex code point value. The default value is an
empty string.
The UnicodeToEbcdic parameter instructs the HIS Encoder to convert from the specified Unicode code
point. This optional parameter accepts a string value, in the form of “To=From” where the “To” is
Unicode hex code point value and the “From” is the EBCDIC hex code point value. The default value is an
empty string.
Get-HisChracterConversion
This Get-HisCustomConversion cmdlet gets the DRDA Service configuration settings for overriding code
point mappings within standard NLS and custom NLS code pages.
Service for DRDA
Page 128
Syntax
Get-HisCustomConversion -Type <ConversionType> {EbcdicToUnicode | UnicodeToEbcdic} -CodePage
<uint32> [<CommonParameters>]
Get-HisCustomConversion -Type <ConversionType> {EbcdicToUnicode | UnicodeToEbcdic} -Name
<string> [<CommonParameters>]
Parameters
The Type parameter instructs the DRDA Service to get configuration settings using this numbered NLS
code page file or custom NLS code page name file. This required parameter accepts an enumerated
value of either EbcdicToUnicode or UnicodeToEbcdic.
Outputs
This Get-HisCustomConversion cmdlet returns an object with properties: From (hex); and To (hex).
Remove-HisCustomConversion
This Remove-HisCustomConversion cmdlet removes the DRDA Service configuration settings for
overriding code point mappings within standard NLS and custom NLS code pages.
Syntax
Remove-HisCustomConversion -CodePage <uint32> [-EbcdicToUnicode <string[]>] [-UnicodeToEbcdic
Remove-HisCustomConversion -Name <string> [-EbcdicToUnicode <string[]>] [-UnicodeToEbcdic
Parameters
The EbcdicToUnicode parameter instructs the HIS Encoder to convert from the specified EBCDIC code
point. This optional parameter accepts a string value. The default value is an empty string.
The UnicodeToEbcdic parameter instructs the HIS Encoder to convert from the specified Unicode code
point. This optional parameter accepts a string value. The default value is an empty string.
Service for DRDA
Page 129
DRDA Service Application Encodings
DRDA Service converts base code pages and maps code points using an underlying HIS Encoder
component and the Windows National Language Support (NLS) system components. The
applicationEncodings element contains applicationEncoding elements for specifying default applicationlevel encoding schemes on a per-database basis. For more information and description of values, see
Configuring Application Encodings.
Add-DrdaApplicationEncoding
This Add-DrdaApplicationEncoding cmdlet configures the DRDA Service for default application-level
encoding schemes on a per-database basis, for use by the HIS Encoder component and Windows
National Language Support (NLS) system components in mapping code points within code pages. For
more information and description of values, see Configuring Application Encodings for more
information.
Syntax
Add-DrdaApplicationEncoding -Ccsid <uint32> -Database <string> [-Scheme <string>]
Add-DrdaApplicationEncoding -Database <string> -CustomCcsid <uint32> [-Scheme <string>]
Parameters
The Ccsid parameter instructs the DRDA Service to encode output parameter and result set values using
an override CCSID (Coded Character Set Identifier), and not the DRDA AR client-requested CCSID. This
required parameter accepts an integer. The default value is 1208.
The CustomCcsid parameter instructs the DRDA Service to encode output parameter and result set
values using an override custom CCSID (Coded Character Set Identifier), and not the DRDA AR clientrequested CCSID. This required parameter accepts an integer. The default value is -1.
The Database parameter instructs the DRDA Service to encode output parameter and result set values
using an override encoding scheme, and not the DRDA AR client-requested encoding scheme, for a
specified target SQL Server database only. This required parameter accepts a string value. The default
The Scheme parameter instructs the DRDA Service to encode output parameter and result set values
using an override encoding scheme, and not the DRDA AR client-requested encoding scheme. This
optional parameter accepts a string value. The supported values are Ebcdic, Unicode, and Ansi. The
default value is Unicode.
Get-DrdaApplicationEncoding
This Get-DrdaApplicationEncoding cmdlet gets the DRDA Service configuration settings for default
application-level encoding schemes on a per-database basis, for use by the HIS Encoder component and
Windows National Language Support (NLS) system components in mapping code points within code
pages.
Service for DRDA
Page 130
Syntax
Get-DrdaApplicationEncoding [-Ccsid <uint32>] [-Database <string>] [-CustomCcsid <uint32>]
Parameters
The Ccsid parameter instructs the DRDA Service to get application encoding configuration using an
override CCSID (Coded Character Set Identifier). This optional parameter accepts an integer. The default
value is 1208.
The CustomCcsid parameter instructs the DRDA Service to get application encoding configuration using
a custom CCSID (Coded Character Set Identifier). This optional parameter accepts an integer. The
default value is -1.
The Database parameter instructs the DRDA Service to get application encoding configuration using a
specified target SQL Server database name. This optional parameter accepts a string value. The default
Outputs
This Get-DrdaApplicationEncoding cmdlet returns an object with properties: Scheme (string); Ccsid
(integer); Database (string); and CustomCcsid (integer).
Remove-DrdaApplicationEncoding
This Remove-DrdaApplicationEncoding cmdlet removes the DRDA Service configuration settings for
default application-level encoding schemes on a per-database basis, for use by the HIS Encoder
component and Windows National Language Support (NLS) system components in mapping code points
within code pages.
Syntax
Remove-DrdaApplicationEncoding -Ccsid <string[]> [-Database <string>] [<CommonParameters>]
Remove-DrdaApplicationEncoding -CustomCcsid <string[]> [-Database <string>]
Parameters
The Ccsid parameter instructs the DRDA Service to remove application encoding configuration using an
override CCSID (Coded Character Set Identifier). This optional parameter accepts an integer. The default
value is 1208.
The CustomCcsid parameter instructs the DRDA Service to remove application encoding configuration
using a custom CCSID (Coded Character Set Identifier). This optional parameter accepts an integer. The
default value is -1.
Service for DRDA
Page 131
The Database parameter instructs the DRDA Service to remove application encoding configuration using
a specified target SQL Server database name. This optional parameter accepts a string value. The
DRDA Service Collation Mapping
DRDA Service maps collation syntax to provide cross-platform compatibility of query results. For more
information and description of values, see Data Integration (Deployment), DRDA Service, Configuring
Collation Mapping.
Add-DrdaCollationName
This Add-DrdaCollationName cmdlet configures the DRDA Service for transforming a SELECT statement
from DB2 ORDER BY COLLATION_KEY (collation-name) syntax to SQL Server T-SQL ORDER BY COLLATE
(collation_name) syntax, mapping from a DB2 collation-name value to a SQL Server collation_name
value, to provide more compatible query results. For more information and description of values, see
Data Integration (Deployment), DRDA Service, Configuring Collation Mapping.
Syntax
Add-DrdaCollationName -To <string> -From <string> [<CommonParameters>]
Parameters
The To parameter instructs the DRDA Service SQL Transformer to convert to the specified
collation_name string within a SQL Server SELECT ORDER BY COLLATE clause. This required parameter
accepts a string value. There is no default value.
The From parameter instructs the DRDA Service SQL Transformer to convert from the specified
collation-name string within a DB2 SELECT ORDER BY COLLATION_KEY clause. This required parameter
Get-DrdaCollationName
This Get-DrdaCollationName cmdlet gets the DRDA Service configuration settings for transforming a
SELECT statement from DB2 ORDER BY COLLATION_KEY (collation-name) syntax to SQL Server T-SQL
ORDER BY COLLATE (collation_name) syntax, mapping from a DB2 collation-name value to a SQL Server
collation_name value, to provide more compatible query results.
Syntax
Get-DrdaCollationName [-To <string>] [-From <string>] [<CommonParameters>]
Parameters
The To parameter instructs the DRDA Service get collation name configuration using the specified
collation_name string. This required parameter accepts a string value. There is no default value.
Service for DRDA
Page 132
The From parameter instructs the DRDA Service get collation name configuration using the specified
collation-name string within a DB2 SELECT ORDER BY COLLATION_KEY clause. This required parameter
Outputs
This Get-DrdaCollationName cmdlet returns an object with properties: To (string); and From (string).
Remove-DrdaCollationName
This Remove-DrdaCollationName cmdlet removes the DRDA Service configuration settings to add a
COLLATE clause to an ORDER BY clause, based on a default ORDER BY collation name.
Syntax
Remove-DrdaCollationName -RemoveAll <bool> [-To <string>] [-From <string>] [<CommonParameters>]
Parameters
The To parameter instructs the DRDA Service remove collation name configuration using the specified
collation_name string. This required parameter accepts a string value. There is no default value.
The From parameter instructs the DRDA Service remove collation name configuration using the
specified collation-name string within a DB2 SELECT ORDER BY COLLATION_KEY clause. This required
parameter accepts a string value. There is no default value.
Configuring Trace Listeners
The DRDA Service supports multiple concurrent trace listeners, including: text trace listener, console
trace listener, custom trace listener, and Event Trace for Windows (ETW) trace listener. For more
information and description of values, see Data Integration (Deployment), DRDA Service, Configuring
Trace Listeners.
Set-DrdaConsoleTraceListener
The Set-DrdaConsoleTraceListener cmdlet configures the DRDA Service console trace listener to write
trace data to a command console window.
Syntax
Set-DrdaConsoleTraceListener -Level <uint32> [<CommonParameters>]
Parameters
The Level parameter instructs the DRDA Service to trace defined collections of information, from a
minimum to a maximum level of tracing. This required parameter accepts an integer value. The default
value is 0.
Value
0
Description
Service for DRDA
Page 133
Value
Description
1
2
3
4
Table 39. Trace Levels.
Set-DrdaEtwTraceListener
The Set-DrdaEtwTraceListener cmdlet configures the DRDA Service ETW (Event Tracing for Windows) as
an ETW provider to output trace data through an ETW session to a Windows operating system ETW
controller.
Syntax
Set-DrdaEtwTraceListener -Level <uint32> [<CommonParameters>]
Parameters
value is 0.
Value
Description
0
1
2
3
4
Table 40. Trace Levels.
Set-DrdaEventLogTraceListener
The Set-DrdaEventLogTraceListener cmdlet configures the DRDA Service event log listener outputs log
data to the Windows event log.
Syntax
Set-DrdaEventLogTraceListener -InitializeData <string> [<CommonParameters>]
Parameters
The InitializeData parameter instructs the DRDA Service to log defined collections of information. This
required parameter accepts a string value. The default value is “Error,Warning,Information”, which
includes all event log levels.
Value
Error
Warning
Description
This value instructs the DRDA Service to log only the error level data.
This value instructs the DRDA Service to log only the warning level data.
Service for DRDA
Page 134
Value
Description
Information This value instructs the DRDA Service to log only the information level data
Table 41. Event Log Levels.
Set-DrdaTextTraceListener
The Set-DrdaTextTraceListener cmdlet configures the DRDA Service text trace listener to write trace
data to a disk file in text format.
Syntax
Set-DrdaTextTraceListener -Level <uint32> [-InitializeData <string>] [-AutoFlush <bool>] [MaxTraceEntryCount <uint32>] [-MaxTraceFileCount <uint32>] [<CommonParameters>]
Parameters
value is 0.
Value
Description
0
1
2
3
4
Table x. Trace Levels.
The AutoFlush parameter instructs the DRDA Service to flush data automatically to the trace listener.
This required parameter accepts a Boolean value. The default is false.
Note: The DRDA Service can flush trace data automatically to the trace listeners, which ensures the
trace data is captured but will increase disk I/O and reduce overall system performance. To improve
performance, set AutoFlush=$False, to disable automatic trace flush.
The MaxTraceEntryCount parameter instructs the DRDA Service to trace up to a maximum number of
entries, and then to stop tracing. This required parameter accepts an integer. The default value is
1000000.
The MaxTraceFileCount parameter instructs the DRDA Service to write the text listener trace output a
maximum number of individual trace files, and then overwrite existing trace files. This required
parameter accepts an integer. The default value is 10.
Get-DrdaTraceListener
This Get-DrdaTextTraceListener cmdlet gets the DRDA Service configuration settings for text trace
listener to write trace data to a disk file in text format.
Syntax
Service for DRDA
Page 135
Get-DrdaTraceListener [-Listener] <TraceListenerType> [<CommonParameters>]
Parameters
The Listener parameter instructs the DRDA Service to get the configuration for the specified trace
listener type. This required parameter accepts a Listener value of Console, Text, Etw, or EventLog. There
is no default value.
Outputs
This Get-DrdaTraceListener cmdlet returns a collection of properties.
Start-DrdaTraceListener
This Start-DrdaTraceListener cmdlet instructs the DRDA Service to start the specified type of trace
listener.
Syntax
Start-DrdaTraceListener [-Listener] <TraceListenerType> [<CommonParameters>]
Parameters
The Listener parameter instructs the DRDA Service to start the specified trace listener type. This
required parameter accepts a Listener value of Console, Text, Etw, or EventLog. There is no default
value.
Stop-DrdaTraceListener
This Stop-DrdaTraceListener cmdlet instructs the DRDA Service to stop the specified type of trace
listener.
Syntax
Stop-DrdaTraceListener [-Listener] <TraceListenerType> [<CommonParameters>]
Parameters
The Listener parameter instructs the DRDA Service to stop the specified trace listener type. This
required parameter accepts a Listener value of Console, Text, Etw, or EventLog. There is no default
value.
DRDA Service Package Bind Listener
The DRDA Service supports custom package binders in the form of a .NET Framework custom listener.
Add-DrdaPackageBindListener
This Add-DrdaPackageBindListener cmdlet adds a DRDA Service configuration for sending bind package
with bind SQL statement output to an optional custom bind listener.
Service for DRDA
Page 136
Syntax
Add-DrdaPackageBindListener -TypeName <string> [-ThrowWhenNoCallback ] [<CommonParameters>]
Parameters
The TypeName parameter defines the type of the DRDA Service custom bind listener. This mandatory
parameter is accepts a string. There is no default value. The Type value for the custom package bind
listener sample is "CustomListeners.MyPackageBindListener, CustomListeners, Version=1.0.0.0,
Culture=neutral, PublicKeyToken=34013cf74da51d17, processorArchitecture=MSIL".
The ThrowWhenNoCallback parameter instructs the DRDA Service to return BGNBNDRM (Begin Bind
Reply Message) to the DRDA AR client, when the custom bind listener component does not return any
information on the callback interface. This optional parameter accepts a Boolean value. The default
value is true.
Get-DrdaPackageBindListener
This Get-DrdaPackageBindListener cmdlet gets the DRDA Service configuration settings for sending bind
package with bind SQL statement output to an optional custom bind listener.
Syntax
Get-DrdaPackageBindListener [-Type <string>] [<CommonParameters>]
Parameters
The Type parameter defines the type of the DRDA Service custom bind listener. This mandatory
Remove-DrdaPackageBindListener
This Remove-DrdaPackageBindListener cmdlet removes the DRDA Service configuration settings to add a
custom trace listener.
Syntax
Remove-DrdaPackageBindListener -TypeName <string> [<CommonParameters>]
Parameters
The Type parameter defines the type of the DRDA Service custom bind listener. This mandatory
Service for DRDA
Page 137
Static SQL for DB2 Custom Packages XML Schema V90
Microsoft HIS 2013 (V9) supports both the old and new format, which includes an associated XML
schema for validating the XML document. Microsoft HIS 2009 and HIS 2010 (V8.5) support the old
format only.
The Microsoft static SQL for DB2 custom package XML file contains multiple elements to inform the
DRDA Client and DRDA Service how to execute the DRDA commands BGNBND (Begin Binding a Package
to an RDB) and BNDSQLSTT (Bind SQL Statement to an RDB Package). This topic describes the XML
elements that you can define to describe the static SQL package bind options, package name, package
sections, statements, parameters, and result sets. The following XML listing is an example of the custom
package XML.
Package Schema V90 Example
The custom packages XML schema v90 sample contains multiple sections.
Options
<?xml version="1.0" encoding="utf-8"?>
<hostIntegration.staticSql xmlns="http://schemas.microsoft.com/his/StaticSql/2012">
<options bindAllowErrors="Yes" bindAuthorizationKeep="true" bindCheck="false"
bindReplace="true" bindReplaceVersion="" packageCcsidSbc="1208" packageCcsidDbc="1200"
packageCcsidMbc="1208" packageCharacterSubtype="Default" packageDecimalPrecision="15"
packageExecuteAuthorization="Requester" bindExplain="ExplainNone"
packageIsolationLevel="ReadCommitted" packageOwnerIdentifier="" statementDateFormat="Iso"
statementDecimalDelimiter="System" defaultRdbCollection=""
releaseDatabaseResources="Commit" parallelProcessDegree="1" keepPreparedStatement="None"
statementQueryProtocol="FixedRow" statementStringDelimiter="System"
statementTimeFormat="Iso"/>
<packages>
<package collectionIdentifier="DSN8910" consistencyToken="CHARTOK1"
packageIdentifier="MSDB2SDK" title="" versionName="">
Sections 1 and 2
<sections>
<section packageSectionAlias="MSDB2SDK1" packageSectionNumber="1">

<statement sqlStatement="DECLARE C1 CURSOR FOR SELECT DEPTNO, DEPTNAME, MGRNO
FROM CONTOSO.DSN8910.DEPT WHERE ADMRDEPT = 'A00'" sqlStatementAssumptions="true"
sqlStatementNumber="1"/>
<resultSet>
<columns>
<column name="DEPTNO" nullable="false">
<char ccsid="37" length="3"/>
</column>
<column name="DEPTNAME" nullable="false">
<varChar ccsid="37" length="36"/>
</column>
<column name="MGRNO" nullable="false">
Service for DRDA
Page 138
</column>
</columns>
</resultSet>
</section>
table DSN8810.DEPT. Assume that the data will be updated later with a searched update and
should be locked when the query executes. The query itself appears in the DECLARE CURSOR
statement.-->
<statement sqlStatement="DECLARE C2 CURSOR FOR SELECT DEPTNO, DEPTNAME, MGRNO
FROM CONTOSO.DSN8910.DEPT WHERE ADMRDEPT = 'A00' FOR READ ONLY WITH RS"
sqlStatementAssumptions="true" sqlStatementNumber="2"/>
<resultSet>
<columns>
</column>
</column>
</column>
</columns>
</resultSet>
</section>
Sections 3 and 4


<!-<statement sqlStatement="EXEC SQL DECLARE C2 CURSOR FOR STMT2;"
</section>-->

<statement sqlStatement="DECLARE C4 CURSOR WITH HOLD FOR SELECT * FROM
CONTOSO.DSN8910.EMP FOR UPDATE OF WORKDEPT, PHONENO, JOB, EDLEVEL, SALARY"
<resultSet>
<columns>
<column name="EMPNO" nullable="false">
</column>
<column name="FIRSTNAME" nullable="false">
</column>
<column name="MIDINIT" nullable="false">
Service for DRDA
Page 139
</column>
<column name="LASTNAME" nullable="false">
</column>
<column name="WORKDEPT" nullable="true">
</column>
<column name="PHONENO" nullable="true">
</column>
<column name="HIREDATE" nullable="true">
<date length="10"/>
</column>
<column name="JOB" nullable="true">
</column>
<column name="EDLEVEL" nullable="true">
<smallInt length="2"/>
</column>
<column name="SEX" nullable="true">
</column>
<column name="BIRTHDATE" nullable="true">
<date length="10"/>
</column>
<column name="SALARY" nullable="true">
<decimal precision="9" scale="2"/>
</column>
<column name="BONUS" nullable="true">
</column>
<column name="COMM" nullable="true">
</column>
</columns>
</resultSet>
</section>
Sections 5 and 6

<statement sqlStatement="DECLARE C5 CURSOR WITH HOLD WITH RETURN FOR SELECT
PROJNO, PROJNAME FROM CONTOSO.DSN8910.PROJ WHERE DEPTNO = 'A01'"
<resultSet>
<columns>
<column name="PROJNO" nullable="false">
</column>
<column name="PROJNAME" nullable="true">
Service for DRDA
Page 140
</column>
</columns>
</resultSet>
</section>
<statement sqlStatement="DECLARE C6 CURSOR FOR SELECT * FROM
CONTOSO.DSN8910.DEPT" sqlStatementAssumptions="true" sqlStatementNumber="6"/>
<resultSet>
<columns>
</column>
</column>
</column>
</columns>
</resultSet>
</section>
Sections 7 and 8
table DSN8910.DEPT. The query itself appears in the DECLARE CURSOR statement-->
<resultSet>
<columns>
</column>
</column>
</column>
</columns>
</resultSet>
</section>

<statement sqlStatement="SELECT MAX(SALARY) INTO :MAXSALRY FROM DSN8910.EMP
WHERE EMPNO = '000010'" sqlStatementAssumptions="true" sqlStatementNumber="10"/>
<parameters>
<parameter name="MAXSALARY" nullable="false">
</parameter>
</parameters>
</section>
Section 11

<statement sqlStatement="SELECT * INTO :EMPREC FROM DSN8910.EMP WHERE EMPNO =
'528671'" sqlStatementAssumptions="true" sqlStatementNumber="11"/>
Service for DRDA
Page 142
<parameters>
<parameter name="MAXSALARY" nullable="false">
</parameter>
</parameters>
</section>
</sections>
</package>
</packages>
</hostIntegration.staticSql>
Example x. Microsoft static SQL for DB2 custom package XML file format v90.
Options Element
The Options element contains a set of optional attributes that define the values for the BNDOPT (Bind
Options) when executing the DRDA command BGNBND (Begin Binding a Package to an RDB).
The bindAllowErrors attribute informs the DRDA Service whether errors are allowed during package
binding. This optional attribute accepts a string value.
A value of Yes instructs the DRDA Service to allow errors and continue binding the package.
A value of No instructs the DRDA Service that no errors are allowed.
A value of Validate instructs the DRDA Service to validate the bind request only.
The default value is No.
Package Authorization Option
The bindAuthorizationKeep attribute informs the DRDA Service whether to keep or revoke package
authorizations when the package is replaced. This optional attribute accepts a Boolean value. The
default value is true.
Bind Existence Checking
The bindCheck attribute informs the DRDA Service whether to return an error when checking for the
existence of database objects and authorities referenced in a package statement. This optional attribute
accepts a Boolean value. The default value is false.
Package Replacement Option
The bindReplace attribute instructs the DRDA Service whether the bind should replace the existing
package. This optional attribute accepts a Boolean value. There default value is true.
Replaced Package Version Name
The bindReplaceVersion attribute defines the package version name of the package that the DRDA
Service should replace. This optional attribute accepts a string value. There is no default value for this
element.
Service for DRDA
Page 143
Package Default SBCS CCSID for a Column
The packageCcsidSbc informs the DRDA Service which Code Character Set Identifier for Single-Byte
Characters to use when executing a SQL CREATE or ALTER table statement. This optional attribute
accepts an integer value. The default value is 1208.
Package Default DBCS CCSID for a Column
The packageCcsidDbc informs the DRDA Service which Code Character Set Identifier for Double-Byte
Package Default MBCS CCSID for a Column
The packageCcsidMbc informs the DRDA Service which Code Character Set Identifier for Mixed-Byte
Package Default Character Subtype
The packageCharacterSubtype attribute informs the DRDA Service which character subtype to use when
executing a SQL CREATE or ALTER table statement. This optional attribute accepts a string value. The
default value is Default.
Value
Description
Bit
CHAR FOR BIT DATA
Default System default
MBCS
Mixed-Byte Character Set
SBCS
Single-Byte Character Set
Table 42. Values for packageCharacterSubtype.
Decimal Precision
The packageDecimalPrecision attribute informs the DRDA Service the default decimal precision. This
optional attribute accepts an integer value of 15, 16, 31 or 63. There default value is 15.
Note: When connecting to IBM DB2 for i5/OS, you should not specify this attribute.
Package Authorization Rules
The packageExecuteAuthorization attribute informs the DRDA Service which authorization identifier to
use when executing dynamic SQL statements. This optional element attribute a string value. The default
value is Requester.
Value
Requester
Owner
InvokerRevertToRequester
InvokerRevertToOwner
Service for DRDA
Description
Instructs the DRDA Service to use the DRDA requester authorization
Instructs the DRDA Service to use the package owner authorization
Instructs the DRDA Service to use the authorization of the invoker of a
function or stored procedure, otherwise use the DRDA requester
authorization
Instructs the DRDA Service to use the authorization of the invoker of a
function or stored procedure, otherwise use the package owner
authorization
Page 144
Value
DefinerRevertToRequester
Description
Instructs the DRDA Service to use the authorization of the creator of a
function or stored procedure, otherwise use the DRDA requester
authorization
DefinerRevertToOwner
Instructs the DRDA Service to use the authorization of the creator of a
function or stored procedure, otherwise use the package owner
authorization
Table 43. Values for packageExecuteAuthorization.
Bind Explain Option
The bindExplain attribute informs the DRDA Service whether to produce explanatory information for
explainable database objects. This optional attribute accepts a string value.
A value of ExplainNone instructs the DRDA Service to not produce explanatory information.
A value of ExplainAll instructs the DRDA Service to explain all statements.
A value of ExplainStatic instructs the DRDA Service to explain static SQL statements only.
The default value is ExplainNone.
Note: When connecting to IBM DB2 for i5/OS and DB2 for LUW, you should specify a value of
ExplainNone only.
Package Isolation Level
The packageIsolationLevel attribute instructs the DRDA Service to bind the package with the requested
DRDA PKGISOLVL (Package Isolation Level). This required attribute accepts a string value. The default
value is ReadCommitted.
Value
ReadCommitted
Serializable
RepeatableRead
ReadUncommitted
Service for DRDA
Description
ANSI READ COMMITTED
DRDA ISOLVLCS (Isolation Level Cursor Stability)
IBM DB2 CURSOR STABILITY (CS)
IBM DB2 for i5/OS COMMIT(*CS)
Microsoft .NET Framework ReadCommitted
ANSI SERIALIZABLE
DRDA ISOLVLRR (Isolation Level Repeatable Read)
IBM DB2 REPEATABLE READ (RR)
IBM DB2 for i5/OS COMMIT(*RR)
Microsoft .NET Framework Serializable
ANSI REPEATABLE READ
DRDA ISOLVLALL (Isolation Level All)
IBM DB2 READ STABILITY (RS)
IBM DB2 for i5/OS COMMIT(*RS)
Microsoft .NET Framework RepeatableRead
ANSI READ UNCOMITTED
DRDA ISOLVLCHG (Isolation Level Change)
IBM DB2 UNCOMMITTED READ (UR)
IBM DB2 for i5/OS COMMIT(*UR)
Microsoft .NET Framework ReadUncommitted
Page 145
Value
NoCommit
Description
DRDA ISOLVLNC (Isolation Level No Commit)
IBM DB2 for i5/OS COMMIT(*NC)
Table 44. Values for packageIsolationLevel.
Package Owner Identifier
The packageOwnerIdentifier attribute instructs the DRDA Service which authorization identifier is the
owner of the package. This optional attribute accepts a string value. There is no default value for this
element.
Statement Date Format
The statementDateFormat element informs the DRDA Service which statement date format to use in
SQL statements. This optional element accepts a string value. There default value is Default.
Value
Format
Description
Iso
yyyy-mm-dd
ISO date format
Usa
mm/dd/yyyy USA date format
Eur
dd.mm.yyyy
EUR date format
Jis
yyyy-mm-dd
JIS date format
Default
NA
Default date format
Local
NA
Local date format
DmyBlank
dd mm yy
Day Month Year with blank separator
DmyComma dd,mm,yy
Day Month Year with comma separator
DmyHyphen dd-mm-yy
Day Month Year with hyphen separator
DmyPeriod
dd.mm.yy
Day Month Year with period separator
DmySlash
dd/mm/yy
Day Month Year with slash separator
JulBlank
yy ddd
Julian with blank separator
JulComma
yy,ddd
Julian with comma separator
JulHyphen
yy-ddd
Julian with hyphen separator
JulPeriod
yy.ddd
Julian with period separator
JulSlash
yy/ddd
Julian with slash separator
MdyBlank
mm dd yy
Month Day Year with blank separator
MdyComma mm,dd,yy
Month Day Year with comma separator
MdyHyphen mm-dd-yy
Month Day Year with hyphen separator
MdyPeriod
mm.dd.yy
Month Day Year with period separator
MdySlash
mm/dd/yy
Month Day Year with slash separator
YmdBlank
yy mm dd
Year Month Day with blank separator
YmdComma
yy,mm,dd
Year Month Day with comma separator
YmdHyphen yy-mm-dd
Year Month Day with hyphen separator
YmdPeriod
yy.mm.dd
Year Month Day with period separator
YmdSlash
yy/mm/dd
Year Month Day with slash separator
Table 45. Values for statementDateFormat.
Statement Decimal Delimiter
The statementDecimalDelimiter attribute informs the DRDA Service which statement decimal delimiter
to use in SQL statements. This optional attribute accepts a string value. There default value is System.
Service for DRDA
Page 146
Value
Description
Period
Indicates a period
Comma
Indicates a comma
Package Indicates package default, when rebinding package
System
Indicates the system default
Table 46. Values for statementDecimalDelimiter.
Default RDB Collection ID
The defaultRdbCollection attribute informs the DRDA Service what default collection identifier to use to
complete unqualified database object names. This optional attribute accepts a string value. There is no
default value. IBM DB2 for z/OS accepts a 128-byte string. IBM DB2 for i5/OS accepts a 10-byte string.
IBM DB2 for LUW accepts a 30-byte string.
Release Database Object Resources
The releaseDatabaseResources attribute informs the DRDA Service when to release database object
resources such as locks that are associated with the package execution. This optional attribute accepts a
string value. A value of Commit instructs the DRDA Service to release database object resources when
processing a transaction commit. A value of Deallocation instructs the DRDA Service to release database
object resources when deallocating the session. The default value is Commit.
Degree of IO Parallelism
The parallelProcessDegree attribute informs the DRDA Service to what degree to utilize I/O parallel
processing for bound statements. This optional attribute accepts an integer value of -1 to 32676. A
value of 1 instructs the DRDA Service that no IO parallel processing is required. A value of -1 instructs
the DRDA Service to apply whatever degree of IO parallel processing is appropriate. The default value is
1.
Keep Prepared Statement
The keepPreparedStatement attribute instructs the DRDA Service to keep prepared dynamic SQL
statements until released. This optional attribute accepts a string value. The default value is None.
Value
Description
None
Indicates statements are released during commit and rollback
Commit
Indicates statements are kept during commit, but released during rollback
Rollback Indicates statements are released during commit, but kept during rollback
All
Indicates statements are kept during commit and rollback
Table 47. Values for keepPreparedStatement.
Query Block Protocol Control
The statementQueryProtocol attribute instructs the DRDA Service what type of query block protocol to
use when returning results on a query. This optional attribute accepts a string value. The default value is
FixedRow.
Value
Description
FixedRow
Indicates fixed row query protocol
LimitedBlock
Indicates limited block query protocol
ForceFixedRow Indicates force fixed row query protocol
Table 48. Values for statementQueryProtocol.
Service for DRDA
Page 147
Statement String Delimiter
The statementStringDelimiter attribute informs the DRDA Service which statement string delimiter to
use in SQL statements. This optional attribute accepts a string value. There default value is System.
Value
Description
Apostrophe
Indicates an apostrophe
DoubleQuote Indicates a double quote
Package
Indicates package default, when rebinding package
System
Indicates the system default
Table 49. Values for statementDecimalDelimiter.
Statement Time Format
The statementTimeFormat attribute informs the DRDA Service which statement time format to use in
SQL statements. This optional attribute accepts a string value. There default value is Iso.
Value
Format
Description
Iso
hh.mm.ss
ISO time format
Usa
hh:mm:ss AM USA time format AM | PM
Eur
hh.mm.ss
EUR time format
Jis
hh:mm:ss
JIS time format
Default
NA
Default time format
Local
NA
Local time format
HmsBlank
hh mm ss
HmsColon
hh:mm:ss
HmsComma
hh,mm,ss
HmsPeriod
hh.mm.ss
Table 50. Values for statementTimeFormat.
Packages Element
The packages element contains one or more package elements that define the values when executing
the DRDA command BGNBND (Begin Binding a Package to an RDB).
Package Element
The package element contains a set of attributes and a sections element.
Collection Identifier
The collectionIdentifier attribute corresponds to the DRDA RDBCOLID (RDB Collection Identifier) and
instructs the DRDA Service into which collection to bind the package. This optional element accepts a
string value. There is no default value. IBM DB2 for z/OS accepts a 128-byte string. IBM DB2 for i5/OS
accepts a 10-byte string. IBM DB2 for LUW accepts a 30-byte string.
Note: DRDA defines a fully-qualified static SQL package using a PKGNAM (RDB Package Name) that
consists of these multiple parts.



Service for DRDA
Page 148
Package Identifier
The packageIdentifier attribute corresponds to the DRDA PKGID (RDB Package Identifier) and informs
the DRDA Service what is the package identifier. This required element accepts a string value. There is
no default value. IBM DB2 accepts a 128-byte string.
Consistency Token
The consistencyToken attribute corresponds to the DRDA PKGCNSTKN (RDB Package Consistency Token)
and informs the DRDA Service what is the package consistency token. This optional element accepts a
string value. There is no default value. IBM DB2 supports an 8-byte string.


Version Name
The versionName attribute corresponds to the DRDA VRSNAM (Version Name) and informs the DRDA
Service what is the package version name. This optional element accepts a string value. There default
value is null. IBM DB2 supports a 254-byte string.
Package Title
The Title attribute corresponds to the DRDA TITLE (Title) and instructs the DRDA Service to bind the
package with a descriptive comment. This optional element accepts a string value. There is no default
value. DRDA supports a 254-byte string.
Sections Element
The sections element contains one or more section elements that define the values when executing the
DRDA command BGNBND (Begin Binding a Package to an RDB).
Section Element
The section element contains a set of attributes, a required statement element, and an optional
resultSet element.
Section Number
The packageSectionNumber attribute corresponds to the DRDA PKGSN (RDB Package Section Number)
and instructs the DRDA Service to bind the section as this number. This optional attribute accepts an
integer value and must be unique within the Package element. There is no default value.
Section Alias
The packageSectionAlias attribute instructs the Microsoft DRDA Client to locate a package section based
on an alias name. This optional element accepts an 8-byte string value. There is no default value.
Note: See Programmer’s Reference for Microsoft.HostIntegration.MsDb2Client.MsDb2Connection
SetCustomPackageData.
Service for DRDA
Page 149
Statement Element
The Statement element contains a set of attributes, and an optional parameters element.
Statement Number
The sqlStatementNumber attribute corresponds to the DRDA SQLSTTNBR (SQL Statement Number) and
instructs the DRDA Service to bind the statement as this number, which is a reference to the statement
embedded within the source application. This optional attribute accepts an integer value and must be
unique within the Package element. There is no default value.
SQL Statement Assumptions
The sqlStatementAssumptions attribute corresponds to the DRDA BNDSTTASM (Bind SQL Statement
Assumptions) and instructs the DRDA Service to bind the statement with these assumptions. This
optional attribute accepts a Boolean value. A value of Yes indicates the source server successfully
classified the statement during the program precompile preparation process. A value of No indicates the
source server made assumptions for a statement that it could not classify. The default value is Yes.
SQL Statement Command Text
The sqlStatement attribute corresponds to the DRDA SQLSTT (SQL Statement) and instructs the DRDA
Service to bind the statement to the package with this SQL statement command text. This required
element accepts a string value. There is no default value. DB2 accepts a 2,097,152-byte string.
Parameters Element
The parameters element contains one or more parameter elements.
Parameter Element
The parameter element contains a set of attributes that correspond to the DRDA SQLSTTVRB (SQL
Statement Variable Descriptions), and type element.
Note: The parameter elements must be defined in the same order as the variables in the SQL statement.
Parameter Name
The name attribute instructs the DRDA Service what is the name of the parameter. This required
attribute accepts a string value. There is no default value. IBM DB2 supports a 128-byte string.
Parameter Nullability
The nullable attribute instructs the DRDA Service whether the parameter value is nullable. This required
attribute accepts a Boolean value. There default value is true.
Parameter Type
The type element instructs the DRDA Service what is the type of the parameter. This required attribute
Parameter Length
The length attribute instructs the DRDA Service what is the length of the parameter. This required
attribute accepts an integer value. There is no default value.
Parameter Precision
The precision attribute instructs the DRDA Service what is the precision of the parameter. This required
Service for DRDA
Page 150
Parameter Scale
The scale attribute instructs the DRDA Service what is the scale of the parameter. This required attribute
accepts an integer value. There is no default value.
Parameter Coded Character Set Identifier
The ccsid attribute instructs the DRDA Service what is the Coded Character Set Identifier of the
parameter. This required attribute accepts an integer value. There is no default value.
ResultSet Element
The optional resultSet element contains a columns element, which informs the DRDA Client what are
the expected order and data types of columns in the result set.
Note: The MsDb2Client provider uses this information to return a result set to the consumer program,
including the correct metadata for the column names and data types. Optionally, configure the
MsDb2Client connection string argument “Use Early Metadata=False” to instruct the MsDb2Client to
ignore the design-time metadata defined in the ResultSet portion of the static SQL for DB2 XML file, and
then use the late metadata returned by the DRDA Service.
Columns Element
The columns element contains one or more column elements.
Column Element
The column element contains a set of attributes.
Column Ordinal
The ordinal attribute identifies the place of the column within the result set. This required attribute
Column Name
The name attribute instructs the DRDA Service what is the name of the column. This required attribute
accepts a string value. There is no default value. IBM DB2 supports a 128-byte string.
Column Nullability
The nullable attribute instructs the DRDA Service whether the column value is nullable. This required
Column Type
The type element instructs the DRDA Service what is the type of the column. This required attribute
Column Length
The Length attribute instructs the DRDA Service what is the length of the column. This required
Column Precision
The Precision attribute instructs the DRDA Service what is the precision of the column. This required
Service for DRDA
Page 151
Column Scale
The Scale attribute instructs the DRDA Service what is the scale of the column. This required attribute
Column Coded Character Set Identifier
The CCSID attribute instructs the DRDA Service what is the Coded Character Set Identifier of the column.
This required attribute accepts an integer value. There is no default value.
Reference Tables
Data Types
The following table lists data types and lengths for use in defining parameter and columns in the static
SQL for DB2 XML file format V85.
Type
bigint
char
charForBit
date
Length
8
Description
A 64-bit signed integer.
A character string.
A binary string.
10
Date and time data ranging in value from January 1, 1753 to December
31, 9999 to an accuracy of 3.33 milliseconds.
decimal
A simple type representing values ranging from 1.0 x 10 -28 to
approximately 7.9 x 10 28 with 28-29 significant digits.
double
8
A floating point number within the range of -1.79E +308 through 1.79E
+308.
graphic
A double-byte character string.
int
4
A 32-bit signed integer, with values between -2147483648 and
2147483647.
numeric
An exact numeric value with a fixed precision and scale.
real
4
Signed, approximate, numeric value with a binary precision 24 (zero or
absolute value 10[–38] to 10[38]).
smallint
2
A 16-bit signed integer, with values between -32768 and 32767.
time
8.
timestamp
26
Data and time data in the format YYYY-MM-DD-hh.mm.ss.tttttt.
varChar
A variable-length character string.
varCharForBit
A variable-length binary string.
varGraphic
Table 51. Data type and length values.
Coded Character Set Identifiers
The following table lists data types and lengths for use in defining options, parameter and columns in
the static SQL for DB2 XML file format V85.
Type
SBCS
SBCS
SBCS
SBCS
Group
ANSI
ANSI
ANSI
ANSI
Service for DRDA
CCSID
1250
1251
1252
1253
NLS
1250
1251
1252
1253
Description
Central Europe
Cyrillic
Latin I
Greek
Page 152
Type
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
Group
ANSI
ANSI
ANSI
ANSI
ANSI/OEM
ANSI/OEM
ANSI/OEM
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
Service for DRDA
CCSID
1254
1255
1256
1257
874
932
1258
37
37
273
273
277
277
278
278
280
280
284
284
285
285
290
290
297
297
420
423
424
500
500
833
836
838
870
871
871
875
880
905
924
NLS
1254
1255
1256
1257
874
932
1258
1140
37
1141
20273
1142
20277
1143
20278
1144
20280
1145
20284
1146
20285
NA
290
1147
20297
20420
20423
20424
1148
500
NA
NA
20838
870
1149
20871
875
20880
20905
20924
Description
Turkish
Hebrew
Arabic
Baltic
Thai
Japanese Shift-JIS
Viet Nam
U.S./ Canada (Euro)
U.S./ Canada
Germany (Euro)
Germany
Denmark/ Norway (Euro)
Denmark/ Norway
Finland/ Sweden (Euro)
Finland/ Sweden
Italy (Euro)
Italy
Latin America/Spain (Euro)
Latin America/Spain
United Kingdom (Euro)
United Kingdom
Japan Katakana (Extended)
France (Euro)
France
Arabic
Greek
Hebrew
International (Euro)
International
Korean (Extended)
Simplified Chinese (Extended)
Thai
Multilingual/ ROECE (Latin-2)
Icelandic (Euro)
Icelandic
Greek (Modern)
Cyrillic (Russian)
Turkish (Latin-3)
Latin-1/Open System (Euro)
Page 153
Type
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
Group
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
ISO
ISO
ISO
ISO
ISO
ISO
ISO
ISO
ISO
ISO
ISO
OEM
OEM
OEM
OEM
OEM
OEM
OEM
OEM
OEM
OEM
OEM
OEM
OEM
OEM
OEM
Service for DRDA
CCSID
930
931
933
935
937
939
1025
1026
1027
1027
1047
5026
5035
28709
813
819
912
913
914
915
916
920
923
1089
6937
437
737
775
850
852
855
857
860
861
862
863
864
865
866
869
NLS
930
931
933
935
937
939
21025
1026
NA
NA
1047
NA
NA
NA
28597
28591
28592
28593
28594
28595
28598
28599
20865
28596
20269
437
737
775
850
852
855
857
860
861
862
863
864
865
866
869
Description
Japan Katakana/Kanji (Extend Katakana)
Japanese
Korea (Extended)
Traditional Chinese (Extended)
Japan English/Kanji (Extended)
Cyrillic (Serbian, Bulgarian)
Turkish (Latin-5)
Japan English (Extended)
Latin-1/Open System
8859-7 Greek
8859-1 Latin-1
8859-2 Central Europe
8859-3 Latin 3
8859-4 Baltic
8859-5 Cyrillic
8859-8 Hebrew (Visually Ordered)
8859-9 Hebrew (Logically Ordered)
8859-15 Latin 9 (Euro)
8859-6 Arabic
6937 Non-Spacing Accent
United States
Greek 437G
Baltic
Multilingual Latin I
Multilingual Latin II
Cyrillic
Turkish
Portuguese
Icelandic
Hebrew
Canadian French
Arabic
Nordic
Cyrillic II
Modern Greek
Page 154
Type
Group
CCSID
NLS
Description
MBCS EBCDIC
930
NA
Japan Katakana/Kanji (Extended)
MBCS EBCDIC
931
NA
Japanese
MBCS EBCDIC
933
NA
Korea (Extended)
MBCS EBCDIC
935
NA
MBCS EBCDIC
937
NA
MBCS EBCDIC
939
NA
MBCS EBCDIC
5026
NA
MBCS EBCDIC
5035
NA
DBCS
ANSI/OEM 936
936
Simplified Chinese GBK
DBCS
ANSI/OEM 949
949
Korean
DBCS
ANSI/OEM 950
950
Traditional Chinese Big5
DBCS
EBCDIC
300
NA
IBM EBCDIC - Japan
DBCS
EBCDIC
834
NA
IBM EBCDIC - Korea
DBCS
EBCDIC
835
NA
IBM EBCDIC - Traditional Chinese
DBCS
EBCDIC
837
NA
IBM EBCDIC - Simplified Chinese
DBCS
EBCDIC
4396
NA
IBM EBCDIC - Japan
Table 52. Coded Character Set Identifier values.
Note: The Microsoft ADO.NET Data Provider for DB2 supports a set of Coded Character Set Identifiers.
IBM DB2 database servers for z/OS and i5/OS typically use EBCDIC. For more information, see
Service for DRDA
Page 155
Static SQL for DB2 Custom Packages XML Schema V85
The Microsoft static SQL for DB2 custom package XML file contains multiple elements to inform the
DRDA AR client how to execute the DRDA commands BGNBND (Begin Binding a Package to an RDB) and
BNDSQLSTT (Bind SQL Statement to an RDB Package). This topic describes the XML elements that you
can define to describe the static SQL package bind options, package name, package sections,
statements, parameters, and result sets. The following XML listing is an example of the custom package
XML.
Package Schema V85 Example
The custom packages XML schema v85 sample contains multiple sections.
Options
<?xml version="1.0" encoding="utf-8"?>
<Packages>
<Options>
<BNDCHKEXS>BNDEXSOPT</BNDCHKEXS>
<BNDCRTCTL>BNDNERALW</BNDCRTCTL>
<BNDEXPOPT>EXPNON</BNDEXPOPT>
<DECPRC>31</DECPRC>
<DFTRDBCOL>COLLID</DFTRDBCOL>
<DGRIOPRL>1</DGRIOPRL>
<PKGATHOPT>PKGATHKP</PKGATHOPT>
<PKGATHRUL>OWNER</PKGATHRUL>
<PKGDFTCC>
<CCSIDDBC>0</CCSIDDBC>
<CCSIDMBC>0</CCSIDMBC>
<CCSIDSBC>0</CCSIDSBC>
</PKGDFTCC>
<PKGDFTCST>CSTSYSDFT</PKGDFTCST>
<PKGOWNID>PLARSEN</PKGOWNID>
<PKGRPLOPT>PKGRPLALW</PKGRPLOPT>
<PKGRPLVRS></PKGRPLVRS>
<PRPSTTKP>F0</PRPSTTKP>
<RDBRLSOPT>RDBRLSCMM</RDBRLSOPT>
<STTDATFMT>ISODATFMT</STTDATFMT>
<STTDECDEL>DECDELPRD</STTDECDEL>
<STTSTRDEL>STRDELAP</STTSTRDEL>
<STTTIMFMT>ISOTIMFMT</STTTIMFMT>
</Options>
<Package Collection="DBO" Id="MSDB2SDK" Token="CHARTOK1"
IsolationLevel="CursorStability">
Sections 1 and 2
<Section Number="1" Alias="MSDB2SDK1">

<Statement>DECLARE C1 CURSOR FOR SELECT DEPTNO, DEPTNAME, MGRNO FROM
CONTOSO.DSN8910.DEPT WHERE ADMRDEPT = 'A00'</Statement>
<ResultSet>
<Column Ordinal="1" Name="DEPTNO" Type="CHAR" Length="3"
CCSID="37" Nullable="FALSE"/>
<Column Ordinal="2" Name="DEPTNAME" Type="VARCHAR" Length="36"
Service for DRDA
Page 156
<Column Ordinal="3" Name="MGRNO" Type="CHAR" Length="6"
</ResultSet>
</Section>
the table DSN8810.DEPT. Assume that the data will be updated later with
a searched update and should be locked when the query executes. The
query itself appears in the DECLARE CURSOR statement.-->
<Statement>DECLARE C2 CURSOR FOR SELECT DEPTNO, DEPTNAME, MGRNO FROM
CONTOSO.DSN8910.DEPT WHERE ADMRDEPT = 'A00' FOR READ ONLY WITH
RS</Statement>
<ResultSet>
CCSID="37" Nullable="False"/>
CCSID="37" Nullable="True"/>
</ResultSet>
</Section>
Sections 3 and 4




<Statement>DECLARE C4 CURSOR WITH HOLD FOR SELECT * FROM
CONTOSO.DSN8910.EMP FOR UPDATE OF WORKDEPT, PHONENO, JOB, EDLEVEL,
SALARY</Statement>
<ResultSet>
<Column Ordinal="1" Name="EMPNO" Type="CHAR" Length="6"
<Column Ordinal="2" Name="FIRSTNAME" Type="VARCHAR" Length="12"
<Column Ordinal="3" Name="MIDINIT" Type="CHAR" Length="1"
<Column Ordinal="4" Name="LASTNAME" Type="VARCHAR" Length="15"
<Column Ordinal="5" Name="WORKDEPT" Type="CHAR" Length="3"
<Column Ordinal="6" Name="PHONENO" Type="CHAR" Length="4"
<Column Ordinal="7" Name="HIREDATE" Type="DATE" Nullable="True"/>
<Column Ordinal="8" Name="JOB" Type="CHAR" Length="8" CCSID="37"
Nullable="True"/>
<Column Ordinal="9" Name="EDLEVEL" Type="SMALLINT"
Nullable="True"/>
<Column Ordinal="10" Name="SEX" Type="CHAR" Length="1" CCSID="37"
Nullable="True"/>
Service for DRDA
Page 157
<Column Ordinal="11" Name="BIRTHDATE" Type="DATE"
Nullable="True"/>
<Column Ordinal="12" Name="SALARY" Type="DECIMAL" Precision="9"
Scale="2" Nullable="True"/>
<Column Ordinal="13" Name="BONUS" Type="DECIMAL" Precision="9"
<Column Ordinal="14" Name="COMM" Type="DECIMAL" Precision="9"
</ResultSet>
</Section>
Sections 5 and 6

<Statement>DECLARE C5 CURSOR WITH HOLD WITH RETURN FOR SELECT PROJNO,
PROJNAME FROM CONTOSO.DSN8910.PROJ WHERE DEPTNO = 'A01'</Statement>
<ResultSet>
<Column Ordinal="1" Name="PROJNO" Type="CHAR" Length="6"
<Column Ordinal="2" Name="PROJNAME" Type="VARCHAR" Length="24"
</ResultSet>
</Section>

<Statement>DECLARE C6 CURSOR FOR SELECT * FROM
CONTOSO.DSN8910.DEPT</Statement>
<ResultSet>
</ResultSet>
</Section>
Sections 7 and 8
the table DSN8910.DEPT.
The query itself appears in the DECLARE CURSOR statement.-->
CONTOSO.DSN8910.DEPT</Statement>
<ResultSet>
Service for DRDA
Page 158
</ResultSet>
</Section>
statement.-->
CONTOSO.DSN8910.DEPT FOR READ ONLY</Statement>
<ResultSet>
</ResultSet>
</Section>
Sections 9 and 10
statement. -->
CONTOSO.DSN8910.DEPT FOR UPDATE</Statement>
<ResultSet>
</ResultSet>
</Section>

<Statement>SELECT MAX(SALARY) INTO :MAXSALRY FROM DSN8910.EMP WHERE
EMPNO = '000010'</Statement>
<Parameters>
<Parameter Name="MAXSALRY" Type="DECIMAL" Precision="9"
Scale="2"/>
</Parameters>
</Section>
Sections 11 and 12

Service for DRDA
Page 159
<Statement>SELECT * INTO :EMPREC FROM DSN8910.EMP WHERE EMPNO =
'528671'</Statement>
<Parameters>
<Parameter Name="MAXSALRY" Type="DECIMAL" Precision="9"
Scale="2"/>
</Parameters>
</Section>
<Statement>SELECT 1 FROM DSN8910.EMP FETCH FIRST 1 ROW ONLY</Statement>
</Section>
</Package>
</Packages>
Example x. Microsoft static SQL for DB2 custom package XML file format v85.
Packages Root Element
The Packages root element contains a set of nested elements consisting of Options and Package. There
may be one Options element per document. There must be at least one Package element per
document, as described in the following table.
Options Element
The Options element contains a set of optional elements that instruct the DRDA Client what values to
specify for the BNDOPT (Bind Options) when executing the DRDA command BGNBND (Begin Binding a
Package to an RDB).
Bind Existence Checking
The BNDCHKEXS element informs the DRDA Service whether to return an error when checking for the
existence of database objects and authorities referenced in a package statement. This optional element
accepts a string value. BNDEXSOPT instructs the DRDA Service to not return an error. BNDEXSRQR
instructs the DRDA Service to check existence of database objects and authorities. The default value is
BNDEXSOPT.
The BNDCRTCTL element informs the DRDA Service whether errors are allowed during package binding.
This optional element accepts a string value. BNDNERALW instructs the DRDA Service that no errors are
allowed. BNDERRALW instructs the DRDA Service to allow errors and continue binding the package.
BNDCHKONL instructs the DRDA Service to validate the bind request only. The default value is
BDNERALW.
Bind Explain Option
The BNDEXPOPT element informs the DRDA Service whether to produce explanatory information for
explainable database objects. This optional element accepts a string value. EXPNON instructs the DRDA
Service to not produce explanatory information. EXPALL instructs the DRDA Service to explain all
statements. EXPYES instructs the DRDA Service to explain static SQL statements only. The default value
is EXPNON.
Note: When connecting to IBM DB2 for i5/OS and DB2 for LUW, you should specify a value of EXPNON
only.
Service for DRDA
Page 160
Decimal Precision
The DECPRC element informs the DRDA Service the default decimal precision. This optional element
accepts an integer value of 15, 16, 31 or 63. There is no default value.
Note: When connecting to IBM DB2 for i5/OS, you should not specify this element.
Default RDB Collection ID
The DFTRDBCOL element informs the DRDA Service what default collection identifier to use to complete
unqualified database object names. This optional element accepts a string value. There is no default
value for this element. IBM DB2 for z/OS accepts a 128-byte string. IBM DB2 for i5/OS accepts a 10-byte
string. IBM DB2 for LUW accepts a 30-byte string.
Degree of IO Parallelism
The DGRIOPRL element informs the DRDA Service to what degree I/O parallel processing is in effect for
bound statements. This optional element accepts an integer value of -1 to 32676. A value of 1 instructs
the DRDA Service that no IO parallel processing is required. A value of -1 instructs the DRDA Service to
apply whatever degree of IO parallel processing is appropriate. The default value is 1.
Package Authorization Option
The PKGATHOPT element informs the DRDA Service whether to keep or revoke package authorizations
when the package is replaced. This optional element accepts a string value. PKGATHKP instructs the
DRDA Service to keep authorizations. PKGATHRVK instructs the DRDA Service to revoke authorizations.
The default value is PKGATHKP.
Package Authorization Rules
The PKGATHRUL element informs the DRDA Service which authorization identifier to use when
executing dynamic SQL statements. This optional element accepts a string value. There default value is
REQUESTER.
Value
REQUESTER
OWNER
INVOKER_REVERT_TO_REQUESTER
INVOKER_REVERT_TO_OWNER
DEFINER_REVERT_TO_REQUESTER
DEFINER_REVERT_TO_OWNER
Service for DRDA
Description
Instructs the DRDA Service to use the DRDA requester
authorization
Instructs the DRDA Service to use the package owner
authorization
Instructs the DRDA Service to use the authorization of the
invoker of a function or stored procedure, otherwise use the
DRDA requester authorization
invoker of a function or stored procedure, otherwise use the
package owner authorization
creator of a function or stored procedure, otherwise use the
DRDA requester authorization
creator of a function or stored procedure, otherwise use the
package owner authorization
Page 161
Table 53. PKGATHRUL values.
Package Default CCSIDs for a Column
The PKGDFTCC element informs the DRDA Service which CCSID (Coded Character Set Identifier) to use
when executing a SQL CREATE or ALTER table statement. This optional element contains 3 elements:
CCSIDSBC (Code Character Set Identifier for Single-Byte Characters); CCSIDMBC (Code Character Set
Identifier for Mixed-Byte Characters); and CCSIDDBC (Code Character Set Identifier for Double-Byte
Characters). There is no default value for this element.
Package Default Character Subtype
The PKGDFTCST element informs the DRDA Service which character subtype to use when executing a
SQL CREATE or ALTER table statement. This optional element accepts a string value. CSTSYSDFT
indicates system default. CSTBCS indicates SBCS. CSTMBCS indicates MBCS. CSTBITS indicates CHAR FOR
BIT DATA. The default value is CSTSYSDFT.
Package Owner Identifier
The PKGOWNID element instructs the DRDA Service which authorization identifier is the owner of the
package. This optional element accepts a string value. There is no default value for this element.
Package Replacement Option
The PKGRPLOPT element instructs the DRDA Service whether the bind should replace the existing
package. This optional element accepts a string value. PKGRPLALW indicates replace package allowed.
PKGRPLNA indicates replace package not allowed. There default value is PKGRPLALW.
Replaced Package Version Name
The PKGRPLVRS element defines the package version name of the package that the DRDA Service
should replace. This optional element accepts a string value. There is no default value for this element.
Prepared Statement Keep
The PRPSTTKP element instructs the DRDA Service to keep prepared dynamic SQL statements until
released. This optional element accepts a string value. The default value is F0.
Value Description
F0
Indicates statements are released during commit and rollback
F1
Indicates statements are kept during commit, but released during rollback
F2
Indicates statements are released during commit, but kept during rollback
F3
Indicates statements are kept during commit and rollback
Table 54. PRPSTTKP values.
RDB Release Option
The RDBRLSOPT element informs the DRDA Service when to release objects. This optional element
accepts a string value. RDBRLSCMM indicates resources are released at commit. RDBRLSCNV indicates
resources are released at end of session. The default value is RDBRLSCMM.
Statement Date Format
The STTDATFMT element informs the DRDA Service which statement date format to use in SQL
statements. This optional element accepts a string value. There is no default value for this element.
Service for DRDA
Page 162
Value
Format
ISODATFMT
yyyy-mm-dd
USADATFMT
mm/dd/yyyy
EURDATFMT
dd.mm.yyyy
JISDATFMT
yyyy-mm-dd
DFTDATFMT
NA
LOCDATFMT
NA
DMYBLKDATFMT
dd mm yy
DMYCMADATFMT
dd,mm,yy
DMYHPNDATFMT
dd-mm-yy
DMYPRDDATFMT
dd.mm.yy
DMYSLHDATFMT
dd/mm/yy
JULBLKDATFMT
yy ddd
JULCMADATFMT
yy,ddd
JULHPNDATFMT
yy-ddd
JULPRDDATFMT
yy.ddd
JULSLHDATFMT
yy/ddd
MDYBLKDATFMT
mm dd yy
MDYCMADATFMT
mm,dd,yy
MDYHPNDATFMT
mm-dd-yy
MDYPRDDATFMT
mm.dd.yy
MDYSLHDATFMT
mm/dd/yy
YMDBLKDATFMT
yy mm dd
YMDCMADATFMT
yy,mm,dd
YMDHPNDATFMT
yy-mm-dd
YMDPRDDATFMT
yy.mm.dd
YMDSLHDATFMT
yy/mm/dd
Table 55. STTDATFMT values.
Description
ISO date format
USA date format
EUR date format
JIS date format
Default date format
Local date format
Day Month Year with blank separator
Day Month Year with comma separator
Day Month Year with hyphen separator
Day Month Year with period separator
Day Month Year with slash separator
Julian with blank separator
Julian with comma separator
Julian with hyphen separator
Julian with period separator
Julian with slash separator
Month Day Year with blank separator
Month Day Year with comma separator
Month Day Year with hyphen separator
Month Day Year with period separator
Month Day Year with slash separator
Year Month Day with blank separator
Year Month Day with comma separator
Year Month Day with hyphen separator
Year Month Day with period separator
Year Month Day with slash separator
Statement Decimal Delimiter
The STTDECDEL element informs the DRDA Service which statement decimal delimiter to use in SQL
statements. This optional element accepts a string value. DECDELPRD indicates a period. DECDELCMA
indicates a comma. DFTPKG indicates package default, when rebinding package. There is no default
value.
Statement String Delimiter
The STTSTRDEL element informs the DRDA Service which statement string delimiter to use in SQL
statements. This optional element accepts a string value. STRDELAP indicates an apostrophe. STRDELDQ
indicates a double quote. DFTPKG indicates package default, when rebinding package. There is no
default value.
Statement Time Format
The STTTIMFMT element informs the DRDA Service which statement time format to use in SQL
statements. This optional element accepts a string value. There is no default value for this element.
Value
ISOTIMFMT
Service for DRDA
Format
hh.mm.ss
Description
ISO time format
Page 163
Value
Format
USATIMFMT
hh:mm:ss AM
USATIMFMT
hh:mm:ss PM
EURTIMFMT
hh.mm.ss
JISTIMFMT
hh:mm:ss
DFTTIMFMT
NA
LOCTIMFMT
NA
HMSBLKTIMFMT
hh mm ss
HMSCLNTIMFMT
hh:mm:ss
HMSCMATIMFMT hh,mm,ss
HMSPRDTIMFMT
hh.mm.ss
Table 56. STTTIMFMT values.
Description
USA time format AM
USA time format PM
EUR time format
JIS time format
Default time format
Local time format
Package Element
The Package element contains a set of attributes, and one or more nested Section elements. There must
be at least one Section element per Package element.
Collection Identifier
The Collection attribute corresponds to the DRDA RDBCOLID (RDB Collection Identifier) and instructs the
DRDA Service into which collection to bind the package. This optional element accepts a string value.
There is no default value. IBM DB2 for z/OS accepts a 128-byte string. IBM DB2 for i5/OS accepts a 10byte string. IBM DB2 for LUW accepts a 30-byte string.
Note: DRDA defines a fully-qualified static SQL package using a PKGNAM (RDB Package Name) that
consists of these multiple parts.



Package Identifier
The Id attribute corresponds to the DRDA PKGID (RDB Package Identifier) and informs the DRDA Service
what is the package identifier. This required element accepts a string value. There is no default value.
IBM DB2 accepts a 128-byte string.
Consistency Token
The Token attribute corresponds to the DRDA PKGCNSTKN (RDB Package Consistency Token) and
informs the DRDA Service what is the package consistency token. This optional element accepts a string
value. There is no default value. IBM DB2 supports an 8-byte string.

Service for DRDA
Page 164

Version Name
The Version attribute corresponds to the DRDA VRSNAM (Version Name) and informs the DRDA Service
what is the package version name. This optional element accepts a string value. There default value is
null. IBM DB2 supports a 254-byte string.
Package Isolation Level
The IsolationLevel attribute instructs the DRDA Service to bind the package with the requested DRDA
PKGISOLVL (Package Isolation Level). This required element accepts a string value. The default value is
ISOLVLCS.
DDM
ISOLVLCS
Description
DRDA ISOLVLCS (Isolation Level Cursor Stability)
ANSI READ COMMITTED
IBM DB2 CURSOR STABILITY (CS)
IBM DB2 for i5/OS COMMIT(*CS)
Microsoft .NET Framework ReadCommitted
ISOLVLRR
DRDA ISOLVLRR (Isolation Level Repeatable Read)
ANSI SERIALIZABLE
IBM DB2 REPEATABLE READ (RR)
IBM DB2 for i5/OS COMMIT(*RR)
Microsoft .NET Framework Serializable
ISOLVLALL
DRDA ISOLVLALL (Isolation Level All)
ANSI REPEATABLE READ
IBM DB2 READ STABILITY (RS)
IBM DB2 for i5/OS COMMIT(*RS)
Microsoft .NET Framework RepeatableRead
ISOLVLCHG
DRDA ISOLVLCHG (Isolation Level Change)
ANSI READ UNCOMITTED
IBM DB2 UNCOMMITTED READ (UR)
IBM DB2 for i5/OS COMMIT(*UR)
Microsoft .NET Framework ReadUncommitted
ISOLVLNC
DRDA ISOLVLNC (Isolation Level No Commit)
IBM DB2 for i5/OS COMMIT(*NC)
Table 57. PKGISOLVL values.
Package Title
The Title attribute instructs the DRDA Service to bind the package with the requested DRDA TITLE (Title),
which is a descriptive comment. This optional element accepts a string value. There is no default value.
DRDA supports a 254-byte string.
Section Element
The Section element contains a set of attributes, and nested Statement, Parameters, and ResultSet
elements. There must be at least one Statement element per Section element.
Service for DRDA
Page 165
Section Number
The Number attribute instructs the DRDA Service to bind the statement to the package with the
requested DRDA PKGSN (RDB Package Section Number). This required element accepts an integer value
and must be unique within the Package element. There is no default value.
Section Alias
The Alias attribute instructs the Microsoft DRDA Client to locate a package section based on an alias
name. This optional element accepts an 8-byte string value. There is no default value.
Note: See Programmer’s Reference for Microsoft.HostIntegration.MsDb2Client.MsDb2Connection
SetCustomPackageData.
Statement Element
The Statement element contains an attribute and a value.
Statement Number
The Number attribute instructs the DRDA Service to bind the statement to the package with the
requested DRDA SQLSTTNBR (SQL Statement Number). This required element accepts an integer value
and must be unique within the Package element. There is no default value.
The Number attribute corresponds to the DRDA PKGSN (RDB Package Section Number) and instructs the
DRDA Service to bind the section as this number. This optional attribute accepts an integer value and
must be unique within the Package element. There is no default value.
SQL Statement Command Text
The Statement attribute corresponds to the DRDA SQLSTT (SQL Statement) and instructs the DRDA
Service to bind the statement to the package with this SQL statement command text. This required
element accepts a string value. There is no default value. DB2 accepts a 2,097,152-byte string.
Parameters Element
The Parameters element contains one or more Parameter elements.
Parameter Element
The Parameter element contains a set of attributes.
Note: The parameter elements must be defined in the same order as the variables in the SQL statement.
Parameter Name
The Name attribute instructs the DRDA Service what is the name of the parameter. This required
attribute accepts a string value. There is no default value. IBM DB2 supports a 128-byte string.
Parameter Type
The Type attribute instructs the DRDA Service what is the type of the parameter. This required attribute
Parameter Length
The Length attribute instructs the DRDA Service what is the length of the parameter. This required
Service for DRDA
Page 166
Parameter Precision
The Precision attribute instructs the DRDA Service what is the precision of the parameter. This required
Parameter Scale
The Scale attribute instructs the DRDA Service what is the scale of the parameter. This required
Parameter Coded Character Set Identifier
The CCSID attribute instructs the DRDA Service what is the Coded Character Set Identifier of the
parameter. This required attribute accepts an integer value. There is no default value.
Parameter Nullability
The Nullable attribute instructs the DRDA Service whether the parameter value is nullable. This required
ResultSet Element
The ResultSet element contains one or more Column elements which define the output column in the
result set.
Note: The MsDb2Client provider uses this information to return a result set to the consumer program,
including the correct metadata for the column names and data types. Optionally, configure the
MsDb2Client connection string argument “Use Early Metadata=False” to instruct the MsDb2Client to
ignore the design-time metadata defined in the ResultSet portion of the static SQL for DB2 XML file, and
then use the late metadata returned by the DRDA Service.
Column Element
The Column element contains a set of attributes.
Column Ordinal
The Ordinal attribute identifies the place of the column within the result set. This required attribute
Column Name
The Name attribute instructs the DRDA Service what is the name of the column. This required attribute
accepts a string value. There is no default value. IBM DB2 supports a 128-byte string.
Column Type
The Type attribute instructs the DRDA Service what is the type of the column. This required attribute
Column Length
The Length attribute instructs the DRDA Service what is the length of the column. This required
Column Precision
The Precision attribute instructs the DRDA Service what is the precision of the column. This required
Service for DRDA
Page 167
Column Scale
The Scale attribute instructs the DRDA Service what is the scale of the column. This required attribute
Column Coded Character Set Identifier
The CCSID attribute instructs the DRDA Service what is the Coded Character Set Identifier of the column.
This required attribute accepts an integer value. There is no default value.
Column Nullability
The Nullable attribute instructs the DRDA Service whether the column value is nullable. This required
Reference Tables
Data Types
The following table lists data types and lengths for use in defining parameter and columns in the static
SQL for DB2 XML file format V85.
Type
BigInt
Char
CharForBit
Date
Length
8
Description
A 64-bit signed integer.
A character string.
A binary string.
10
Decimal
A simple type representing values ranging from 1.0 x 10 -28 to
approximately 7.9 x 10 28 with 28-29 significant digits.
Double
8
A floating point number within the range of -1.79E +308 through 1.79E
+308.
Graphic
Int
4
A 32-bit signed integer, with values between -2147483648 and
2147483647.
Numeric
An exact numeric value with a fixed precision and scale.
Real
4
Signed, approximate, numeric value with a binary precision 24 (zero or
absolute value 10[–38] to 10[38]).
SmallInt
2
A 16-bit signed integer, with values between -32768 and 32767.
Time
8.
Timestamp
26
Data and time data in the format YYYY-MM-DD-hh.mm.ss.tttttt.
VarChar
A variable-length character string.
VarCharForBit
A variable-length binary string.
VarGraphic
Table 58. Data type and length values.
Coded Character Set Identifiers
The following table lists data types and lengths for use in defining options, parameter and columns in
the static SQL for DB2 XML file format V85.
Type
SBCS
Group
ANSI
Service for DRDA
CCSID
1250
NLS
1250
Description
Central Europe
Page 168
Type
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
Group
ANSI
ANSI
ANSI
ANSI
ANSI
ANSI
ANSI
ANSI/OEM
ANSI/OEM
ANSI/OEM
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
Service for DRDA
CCSID
1251
1252
1253
1254
1255
1256
1257
874
932
1258
37
37
273
273
277
277
278
278
280
280
284
284
285
285
290
290
297
297
420
423
424
500
500
833
836
838
870
871
871
875
NLS
1251
1252
1253
1254
1255
1256
1257
874
932
1258
1140
37
1141
20273
1142
20277
1143
20278
1144
20280
1145
20284
1146
20285
NA
290
1147
20297
20420
20423
20424
1148
500
NA
NA
20838
870
1149
20871
875
Description
Cyrillic
Latin I
Greek
Turkish
Hebrew
Arabic
Baltic
Thai
Japanese Shift-JIS
Viet Nam
U.S./ Canada (Euro)
U.S./ Canada
Germany (Euro)
Germany
Denmark/ Norway (Euro)
Denmark/ Norway
Finland/ Sweden (Euro)
Finland/ Sweden
Italy (Euro)
Italy
Latin America/Spain (Euro)
Latin America/Spain
United Kingdom (Euro)
United Kingdom
France (Euro)
France
Arabic
Greek
Hebrew
International (Euro)
International
Korean (Extended)
Thai
Multilingual/ ROECE (Latin-2)
Icelandic (Euro)
Icelandic
Greek (Modern)
Page 169
Type
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
SBCS
Group
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
EBCDIC
ISO
ISO
ISO
ISO
ISO
ISO
ISO
ISO
ISO
ISO
ISO
OEM
OEM
OEM
OEM
OEM
OEM
OEM
OEM
OEM
OEM
OEM
OEM
Service for DRDA
CCSID
880
905
924
930
931
933
935
937
939
1025
1026
1027
1027
1047
5026
5035
28709
813
819
912
913
914
915
916
920
923
1089
6937
437
737
775
850
852
855
857
860
861
862
863
864
NLS
20880
20905
20924
930
931
933
935
937
939
21025
1026
NA
NA
1047
NA
NA
NA
28597
28591
28592
28593
28594
28595
28598
28599
20865
28596
20269
437
737
775
850
852
855
857
860
861
862
863
864
Description
Cyrillic (Russian)
Turkish (Latin-3)
Latin-1/Open System (Euro)
Japanese
Korea (Extended)
Cyrillic (Serbian, Bulgarian)
Turkish (Latin-5)
Latin-1/Open System
8859-7 Greek
8859-1 Latin-1
8859-2 Central Europe
8859-3 Latin 3
8859-4 Baltic
8859-5 Cyrillic
8859-8 Hebrew (Visually Ordered)
8859-9 Hebrew (Logically Ordered)
8859-15 Latin 9 (Euro)
8859-6 Arabic
6937 Non-Spacing Accent
United States
Greek 437G
Baltic
Multilingual Latin I
Multilingual Latin II
Cyrillic
Turkish
Portuguese
Icelandic
Hebrew
Canadian French
Arabic
Page 170
Type
Group
CCSID
NLS
Description
SBCS
OEM
865
865
Nordic
SBCS
OEM
866
866
Cyrillic II
SBCS
OEM
869
869
Modern Greek
MBCS EBCDIC
930
NA
MBCS EBCDIC
931
NA
Japanese
MBCS EBCDIC
933
NA
Korea (Extended)
MBCS EBCDIC
935
NA
MBCS EBCDIC
937
NA
MBCS EBCDIC
939
NA
MBCS EBCDIC
5026
NA
MBCS EBCDIC
5035
NA
DBCS
ANSI/OEM 936
936
Simplified Chinese GBK
DBCS
ANSI/OEM 949
949
Korean
DBCS
ANSI/OEM 950
950
Traditional Chinese Big5
DBCS
EBCDIC
300
NA
IBM EBCDIC - Japan
DBCS
EBCDIC
834
NA
IBM EBCDIC - Korea
DBCS
EBCDIC
835
NA
IBM EBCDIC - Traditional Chinese
DBCS
EBCDIC
837
NA
IBM EBCDIC - Simplified Chinese
DBCS
EBCDIC
4396
NA
IBM EBCDIC - Japan
Table 59. Coded Character Set Identifier values.
Note: The Microsoft ADO.NET Data Provider for DB2 supports a set of Coded Character Set Identifiers.
IBM DB2 database servers for z/OS and i5/OS typically use EBCDIC. For more information, see SNA
Internationalization Programmer's Reference (http://go.microsoft.com/fwlink/?LinkID=181017).
Service for DRDA
Page 171
Service for DRDA
Page 172
Samples
Custom Listeners
A number of the DRDA Service listeners are replaceable with custom listeners for trace output and
package bind output.
Custom Trace Listener
The DRDA Service can trace runtime operations and output the information to the default
MsDrdaService.log file and to the standard DrdaAsTextListener. Optionally, you can replace the
DrdaAsTextListener with a custom trace listener.
The DRDA Service supports trace levels to select information to write to the log file and trace listeners.
For more information, see Tracing topic in the Troubleshooting book.
To use the trace listener sample, follow these steps.
1. Using Microsoft Visual Studio 2010, build the sample. You may need to change the reference to
the strong name key in the project properties, and the output directory path in the program
code.
using System;
using System.IO;
using Microsoft.HostIntegration.Drda.Common;
namespace CustomListeners
{
public class MyTraceListener : BaseDrdaTraceListener
{
StreamWriter sw = null;
public bool EnsureWriter()
{
if (sw == null)
{
try
{
System.IO.DirectoryInfo dirInfo = new
System.IO.DirectoryInfo(@"c:\temp");
if (!dirInfo.Exists)
{
dirInfo.Create();
}
string fileName = @"c:\temp\MsDrdaService" +
DateTime.Now.ToFileTime() + ".log";
sw = new StreamWriter(fileName);
sw.AutoFlush = true;
sw.WriteLine("MsDrdaService custom log.
Created on: " + DateTime.Now);
Service for DRDA
Page 173
return true;
}
catch (Exception ex)
{
System.Console.WriteLine("Failed to create
log file. Message:" + ex.Message);
return false;
}
}
else
return true;
}
#region override IDrdaTraceListener Members
public override void
TraceEvent(System.Diagnostics.TraceEventType type, int id, string
msg)
{
if (EnsureWriter())
{
sw.WriteLine(string.Format("[" + type + "][" + id
+ "]" + msg));
}
}
#endregion
}
}
Sample x. Sample code for a custom trace listener.
2. Using Microsoft Global Assembly Cache tool, install an assembly into the global assembly cache.
In the Visual Studio x64 Win64 Command Prompt (2010) window, navigate to the bin\Debug or
bin\Retail folder for your custom package bind listener component, type gacutil /i
“<path>\<component_name>.dll”, and then press Enter.
C:\Windows\system32>gacutil /i
<path>\CustomListeners\bin\Debug\CustomListeners.dll
Microsoft (R) .NET Global Assembly Cache Utility.
4.0.30319.1
Version
Assembly successfully added to the cache
Example x. Example command to add custom listener component to GAC.
3. Using Microsoft Global Assembly Cache tool, read the assembly information from the global
assembly cache. In the Visual Studio x64 Win64 Command Prompt (2010) window, navigate to
Service for DRDA
Page 174
the bin\Debug or bin\Retail folder for your custom package bind listener component, type
gacutil /l “<path>\<component_name>.dll”, and then press Enter.
C:\TechReady\DRDA_AS\CustomListeners\bin\Debug>gacutil -l
CustomListeners
4.0.30319.1
Version
The Global Assembly Cache contains the following assemblies:
CustomListeners, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=34013cf74da51d17, processorArchitecture=MSIL
Number of items = 2
Example x. Example command to read custom listener component info from GAC.
4. Using Microsoft Visual Studio 2010, edit the DRDA Service application configuration file. Update
the configuration for the custom trace listener.
<drdaServiceTraceListeners>
<drdaServiceTraceListener type="CustomListeners.MyTraceListener,
PublicKeyToken=34013cf74da51d17, processorArchitecture=MSIL" traceLevel="3"/>
</drdaServiceTraceListeners>
Example x. Sample values for custom trace listener in the MsDrdaService.exe.config.
Custom Package Bind Listener
To use the custom package bind listener sample, follow these steps.
1. Using Microsoft Visual Studio 2010, build the sample. You may need to change the reference to
the strong name key in the project properties, and the output directory path in the program
code.
using
using
using
using
using
System;
System.Collections.Generic;
System.Xml;
System.Text;
Microsoft.HostIntegration.Drda.Common;
namespace CustomListeners
{
public class MyPackageBindListener: IPackageBindListener
{
#region IPackageBindListener Members
/// <summary>
/// Notify after package is bound with string representation of the xml.
/// </summary>
/// <param name="packageXMLString">package XML String</param>
public void OnPackageBound(string packageXMLString, string rdbNam, string
collid)
Service for DRDA
Page 175
{
}
/// <summary>
/// Notify after package is bound with xml document.
/// </summary>
/// <param name="xmldoc"></param>
public void OnPackageBound(XmlDocument xmldoc, string rdbNam, string collid)
{
try
{
System.IO.DirectoryInfo dirInfo = new
System.IO.DirectoryInfo(@"c:\temp");
if (!dirInfo.Exists)
{
dirInfo.Create();
}
string fileName = @"c:\temp\PackageXMLFile" +
DateTime.Now.ToFileTime() + ".xml";
xmldoc.Save(fileName);
//callback.ReloadPackageProcedureTable(null);
}
catch (Exception ex)
{
System.Console.WriteLine("Failed to save xml file. Message:" +
ex.Message);
}
}
/// <summary>
/// Notify after package is bound with string representation of the xml.
/// </summary>
public void OnPackageBound(string packageXMLString, string rdbNam, string
collid, out List<string> sqlScripts)
{
sqlScripts = new List<string>();
}
/// <summary>
/// Notify after package is bound with xml document.
/// </summary>
public void OnPackageBound(XmlDocument xmldoc, string rdbNam, string collid,
out List<string> sqlScripts)
{
sqlScripts = new List<string>();
string[] sqlScript1 = {
"/****** Object: StoredProcedure
[dbo].[DBOAREAS_43484152544F4B31_1]
Script Date: 01/06/2012 13:36:23 ******/",
"SET ANSI_NULLS ON",
"GO",
"SET QUOTED_IDENTIFIER ON",
"GO",
Service for DRDA
Page 176
[dbo].[DBOAREAS_43484152544F4B31_1]
DBO.AREAS",
"CREATE PROCEDURE
AS DECLARE C1 CURSOR GLOBAL FOR SELECT * FROM
"GO",
};
string[] sqlScript2 = {
"CREATE PROCEDURE
[dbo].[DBOAREAS_43484152544F4B31_2] AS SELECT * FROM DBO.AREAS"
};
sqlScripts.AddRange(sqlScript1);
sqlScripts.AddRange(sqlScript2);
}
#endregion
}
}
Sample x. Sample code for a custom package bind listener.
2. Using Microsoft Global Assembly Cache tool, install an assembly into the global assembly cache.
In the Visual Studio x64 Win64 Command Prompt (2010) window, navigate to the bin\Debug or
bin\Retail folder for your custom package bind listener component, type gacutil /i
“<path>\<component_name>.dll”, and then press Enter.
C:\Windows\system32>gacutil /i
<path>\CustomListeners\bin\Debug\CustomListeners.dll
4.0.30319.1
Version
Assembly successfully added to the cache
Example x. Example command to add custom listener component to GAC.
5. Using Microsoft Global Assembly Cache tool, read the assembly information from the global
assembly cache. In the Visual Studio x64 Win64 Command Prompt (2010) window, navigate to
the bin\Debug or bin\Retail folder for your custom package bind listener component, type
gacutil /l “<path>\<component_name>.dll”, and then press Enter.
C:\TechReady\DRDA_AS\CustomListeners\bin\Debug>gacutil -l
CustomListeners
4.0.30319.1
Version
The Global Assembly Cache contains the following assemblies:
PublicKeyToken=34013cf74da51d17, processorArchitecture=MSIL
Service for DRDA
Page 177
Number of items = 2
Example x. Example command to read custom listener component info from GAC.
3. Using Microsoft Visual Studio 2010, edit the DRDA Service application configuration file. Replace
the default package bind listener with the custom package bind listener. The DRDA Service will
return a BGNBNDRM (Begin Bind Error Reply Message) to the DRDA AR, if it does not receive a
valid response to the callback interface, when the errorWhenNoCallback= value is “true”.
<packageBindListener type="CustomListeners.MyPackageBindListener,
PublicKeyToken=34013cf74da51d17, processorArchitecture=MSIL"
errorWhenNoCallback="true"/>
Example x. Example values for custom package bind listener in the DRDA Service application
configuration file.
To create and enable a host-initiated affiliate application using the command line
You can use the SSO Administration MMC Snap-In or the SSO Command Line Utility to create and enable
one or more applications, as specified by an XML file. In this task, you will create and enable a hostinitiated affiliate application using the command line.
1. Click Start, click Run, type cmd, and then click OK.
2. At the command prompt, go to the Enterprise Single Sign-On installation directory. The default
installation directory is <drive>:\Program Files\Common Files\Enterprise Single Sign-On.
3. Type ssomanage –createapps <application file name>, and then press Enter.
<sso>
<application name="HOST1">
<description>Host DRDA AR</description>
<contact>[email protected]</contact>
<appuserAccount>domain\AppUserAccount</appuserAccount>
<appAdminAccount>domain\AppAdminAccount</appAdminAccount>
<field ordinal="0" label="User ID" masked="no" />
<field ordinal="1" label="Password" masked="yes" />
<flags hostInitiatedSSO="yes" enableApp="yes" />
</application>
</sso>
Example x. x.
4. Verify the SSO Command Line Utility output.
Using SSO server on this computer
---------Created application 'HOST1' with the following values Application name: DRDAHOSTINIT
Application type: Individual
Description: An Affiliate Application for Host Initiated SSO
Service for DRDA
Page 178
Contact info: [email protected]
Application Users account: REDMOND\plarsen
Application Administrators account: REDMOND\plarsen
Ticket timeout (in minutes): 0
Application flags Application enabled: Yes
Allow local accounts: No
Admin account same: No
Allow Windows initiated SSO: No
Allow host initiated SSO: Yes
- verify external credentials: Yes
Allow direct password sync: No
Credentials are Windows credentials: No
Application Users cannot create mappings: Yes
Application fields User ID: (Not Masked)
Password: (Masked)
----------
Number of applications created = 1
Example x. x.
5. Type ssomanage –enableapp <application name>, and then press Enter.
The operation completed successfully.
Example x. x.
To create, set and enable user mappings using the command line
You can use the SSO Administration MMC Snap-In or the SSO Command Line Utility to create, set and
enable one or more mappings, as specified by an XML file. In this task, you will create, set and enable a
mapping using the command line.
1. Click Start, click Run, type cmd, and then click OK.
2. At the command prompt, go to the Enterprise Single Sign-On installation directory. The default
installation directory is <drive>:\Program Files\Common Files\Enterprise Single Sign-On.
3. Type ssomanage –createmappings <mappings file name>, and then press Enter.
<sso>
<mapping>
<windowsDomain>domain</windowsDomain>
<windowsUserId>WindowsUserName</windowsUserId>
<externalApplication>Application name1</externalApplication>
Service for DRDA
Page 179
<externalUserId>App1UserName</externalUserId>
</mapping>
<mapping>
<windowsDomain>domain</windowsDomain>
<windowsUserId>WindowsUserName</windowsUserId>
<externalApplication>Application name2</externalApplication>
<externalUserId>App2UserName</externalUserId>
</mapping>
</sso>
Example x. x.
Created mapping in application 'HOST1' for user DOMAIN\user to
HISDEMO.
Example x. x.
5. Type ssomanage -setcredentials <Windows account name> <application name>, and then
press Enter. Enter password and connection string values at the command prompt.
User Id : HISDEMO
Password : *******
Confirm 'Password' : *******
Example x. x.
7. Type ssomanage –enablemapping <domain>\<username> <application name>, and then press
Enter.
Example x. x.
Service for DRDA
Page 180

Microsoft Service for DRDA - Platform Modernization Alliance

Transcription

Similar documents

The NCCS State Charity Office Database System

* Report was persoll days i.e., should be done llEGA whert wal is

Mission College

Microsoft Windows Server Codename "Longhorn"

Deploying (Forward Engineering) Emovies to SQL Server 2005 The

EZStream - ClearOne

matthias kolowrat