|
|
|
ASNA DataGate® 8.1 for Microsoft® SQL Server™ 2000/2005
Differences
between DataGate®, DataGate/400® .NET (DG/400) and DataGate for SQL Server® for
.NET
Porting
AVR for .NET Applications to Employ ASNA DataGate® for SQL Server® for .NET
AVR for .NET Programming Considerations
Installation Notes
Meet System Requirements
To run DataGate 8.1 for SQL Server and ASNA DataGate 8.1, you must have
certain hardware and software installed on your computer.
The system requirements include:
· Windows 2000 Professional SP4, Windows 2000 Server SP4, Windows Server 2003, Windows XP Professional SP2, or Windows Vista (Business Edition only)
· TCP/IP;
· You must be signed on with Administrative privileges in order to start the DataGate Service and to license both products;
· A CD-ROM disc drive.
· VGA or higher-resolution screen supported by Microsoft Windows.
· A minimum of 64 MB of RAM.
· A mouse or other suitable pointing device.
· At least 130 MB free disk space (includes a new installation of AVR, DataGate and DataGate for SQL Server).
SQL Server Express:
SQL Server Express is a version of SQL Server 2005, which requires the following minimal configuration:
1. TCP networking must be enabled via Surface configuration.
2. UDP port 1434 must be enabled in any firewall that may be running.
3. TCP port 1433 must be enabled in any firewall that may be running.
4. SQL Server Browser service must be enabled and started. It is installed disabled by Microsoft.
Recommendations:
· Run your mission critical Database running a backup Power Supply with NTFS (not FAT or FAT32) OR on an AS/400.
· Run your mission critical Applications with NTFS.
· Memory requirements should triple the minimum recommendation for the operating system.
·
Keep recent Data Backups.
Before installing ASNA DataGate 8.1 for SQL Server, consider the following:
· Read the following topic on Enabling SQL Server Instance(s) to ensure that the target instance(s) for Microsoft SQL Server 2005 will be properly detected and the installation process will complete successfully.
· Ensure that Microsoft for SQL Server has been installed, or install Microsoft for SQL Server. Refer to Microsoft SQL Server documentation for further information.
· Be sure the computer meets the system requirements for DataGate 8.1 for SQL Server. For more information, see System Requirements.
· Verify that the Microsoft SQL Server Service is started, and that the Auto-start service when OS starts is selected. See Starting, Pausing, and Stopping SQL Server below for more information.
· Review the Installation Instructions for installing DataGate 8.1 for SQL Server and be prepared to make the appropriate selections when running Setup.
· Read the Release Notes section in this document, or on the ASNA Developer Network site or DataGate for SQL Server for the latest on product issues, as well as known fixes, known bugs, etc.
Enabling SQL Server Instance(s)
Please complete the following steps prior to installing DataGate for SQL Server 8.1. These steps will ensure that the target instance(s) for Microsoft SQL Server will be properly detected and the installation process will complete successfully.
1. UDP port 1434 must be enabled for any firewall that may be running.
2. TCP port 1433 must be enabled for any firewall that may be running.
TCP/IP networking must be enabled for each target instance via the Service Configuration Manager.
3. Restart the SQL SERVER service for each target instance for the configuration changes to take effect.
4. Finally, SQL Server Browser service must be enabled and started. (It may have been installed as disabled by Windows)
The following includes the basic steps to install Microsoft
SQL Server. Please refer to the
Microsoft SQL Server documentation for further information.
To install Microsoft SQL Server 2000
1. Insert the Microsoft® SQL Server™ 2000 compact disc in your CD-ROM drive. If the compact disc does not automatically run, double-click Autorun.exe in the root directory of the compact disc.
2. Select SQL Server 2000 Components.
3. Select Install Database Server and setup prepares the SQL Server Installation Wizard. At the Welcome screen, click Next.
4. In the Computer Name dialog box, Local Computer is the default option and the local computer name appears in the edit box. Click Next.
For a remote installation, click Remote Computer. You can then type a computer name or click Browse to locate a remote computer.
If a cluster is detected, Virtual server is the default option.
5. In the Installation Selection dialog box, click Create a new instance of SQL Server, or install Client Tools, and then click Next.
6. Follow directions on the User Information, Software License Agreement and related screens.
7. In the Installation Definition dialog box, click Server and Client Tools, and then click Next.
8. In the Instance Name dialog box, if the Default check box is available, you can install either the default or a named instance. If the Default check box is not available, a default instance has already been installed, and you can install only a named instance.
· To install the default instance, select the Default check box, and click Next.
· To install a named instance, clear the Default check box, and type a new named instance in the Instance Name edit box. Click Next.
9. In the Setup Type dialog box, click Typical or Minimum, and then click Next.
If you want to select components and subcomponents, change character set, network libraries or other settings, click Custom, and then click Next.
10. In the Service Accounts dialog box, accept the default settings, enter your domain password, and then click Next.
11. In the Authentication Mode dialog box, accept the default setting, and click Next.
12. When you are finished specifying options, click Next in the Start Copying Files dialog box.
13. In the Choose Licensing Mode dialog box, make selections according to your license agreement, and click Continue to begin the installation.
Click Help for information about licensing or see your system administrator.
14. In
the Setup Complete dialog box, click Yes, I want to restart my
computer now, and then click Finish.
SQL Server Service Manager is used to start, stop, and pause
the Microsoft® SQL Server™ 2000 components on the server. These components run as services on Microsoft Windows® 2000 and above.
SQL Server Service implements the SQL Server database engine. There is one SQL Server service for each instance of SQL Server running on the computer.
SQL Server Service Manager is a taskbar application and
follows the standard behavior of taskbar applications. The task bar icon will display whether the
Server is running 
,
paused, or stopped 
.
Important!!!! There is a field within the SQL Server Service Manager that you need to select, or ensure that it is enabled. It is called “Auto-start service when OS starts”. Please ensure this option is selected, especially when installing AVR as well, as the system will reboot after installing AVR. If this option is not selected, the SQL Server Service will be stopped, so when the installation process continues and tries to install DataGate for SQL Server, you will receive an error, and DataGate for SQL Server will not be installed.
Note that this option is not selected by default. You must select this option prior to installing DataGate for SQL Server (if installing AVR at the same time).
To Open, Start, Pause or Stop the SQL Server Manager
1.
After
Microsoft SQL Server is installed, the SQL Service Manager icon for the local
machine will display in the right hand corner of your taskbar. To open SQL Server Service Manager, either
double-click on the 
, or right-click on the icon to display a list of menu
options. The following dialog will
display.
Enter or select the following to SQL Server Service Manager:
Server:
The name of the local computer will display. Clicking on the arrow to the right will display all of the SQL Servers that you have access to.
Services:
The SQL Server service will display. Clicking on the arrow to the right will display the other SQL services you have access to, such as SQL Server Agent, and Distributed Transaction Coordinator.
Refresh services…
Select this button to refresh the services.
Start/Continue
Selecting this button starts the SQL Server Service. After it is started, the option will be dimmed, and the icon will display with a green start icon next to it, indicating the service is started. Select this option when the service is either currently paused, or stopped.
Pause
Select this button to temporarily pause the SQL Server Service. To continue service, select the Start/Continue button.
Stop
Select this button to stop the SQL Server Service. To start the service again, select the Start/Continue button.
Auto-start service when OS starts:
Select this option to ensure that the SQL Server Service automatically restarts after your system has been restarted.
Note that this option is not selected by default. You must select this option prior to installing DataGate for SQL Server (if installing AVR at the same time).
2.
To
close SQL Server Service Manager, right-click the SQL Server Service
Manager icon on the taskbar, and then select the Exit menu option.
DataGate for SQL Server is also installed with the AVR 8.1 and Windows Deployment installations. However, to install DSS on a system that does not have AVR, you can install from the CD or from the Developer Network Downloads page.
When installing DataGate for SQL Server, you should be signed on with Administrative Privileges to start the DataGate Service. If you are not signed on with Administrative Privileges, a Warning will display – stating that you need to have Administrative privileges to start the DataGate Service. Therefore, you may want to check with your Network Administrator prior to installing to ensure you have Administrative privileges.
To Install from ASNA Developer Network (DevNet)
1. Go to http://devnet.asna.com.
2. Click on Sign In link on the top right corner and sign in to your DevNet account, or select Create an Account on the left to create a new account.
3. Once you are signed in, click on the Downloads link at the top.
4. Scroll down and select the 8.1 product and version you wish to download.
5. On the next screen, the list of products in the product suite selected will display for you to select from.
6. 6. Select the product to install. The Release Notes for that product will display. In the right hand corner "Downloads" window, you will see the list of products available based on your sign in. Select the icon of the product to install. The installation exe will display for you to Run now, or Save to your system and install later.
To Install DataGate for SQL Server from CD
1. Insert the ASNA .NET Product Suite CD into your CD drive.
2. Click on ASNA DataGate 8.1 for Microsoft SQL Server 2000/2005.
3. Click on the Install… button to begin the installation.
Note that you can also View the Readme file by selecting the Read me button.
4. After the installation has installed for a few minutes, the stored procedures will install. A dialog will then display for you to respond to if you would like to select a SQL database name to be used as the special QTEMP library. The default is set as disabled. See Enabling SQL Database(s) to be used a QTEMP Library for further information.
5. Selecting Done or Install to the dialog below will complete the installation. A dialog will display indicating that the installation or update is complete.
Note that after DSS is installed, or if you already have AVR installed on your system, you can access Stored Procedures at any time from Start - Programs - ASNA .NET Product Suite - DataGate for SQL Server 8.1 - ASNA DataGate for SQL Server 8.1 Stored Procedures.
Enabling SQL Database(s) to be used as QTEMP Library
The DataGate for SQL Server dialog (Stored Procedures) displays during the installation of DataGate for SQL Server and when selecting the Stored Procedures option. It allows you to select a SQL Server instance and connect to SQL Server. You can set security information, as well as specify a SQL database to be used as a QTEMP library.
Note that after DSS is installed, you can access this dialog at any time from Start - Programs - ASNA .NET Product Suite - DataGate for SQL Server 8.1 - ASNA DataGate for SQL Server 8.1 Stored Procedures.
To Enable SQL Server Instance(s)
1. Enter or select the following to the SQL Server instance dialog.
SQL Server Instance:
This option displays the list of currently running and available named SQL Server instances specified on your system for DataGate setup.
-
Click on the arrow to the right to change or select another SQL Server Instance (if available).
Use Trusted Connection:
This option allows you to use integrated Login security to connect with SQL Server.
-
If checked (default), DataGate will use integrated Login security to connect with SQL Server.
-
If unchecked, you will need to enter a valid Login Name and Password to connect.
Login Name: -
This box is disabled if Use Trusted Connection is checked.
-
If enabled, specify a Login Name used to connect to SQL Server.
Password:
-
This box is disabled if Use Trusted Connection is checked.
-
If enabled, specify the Password for the Login Name used to connect to SQL Server.
QTEMP library support:
This option allows you to enable, or specify a SQL database name to be used as the special QTEMP library. By default, this option will be disabled.
-
To enable this support, click on the Enable button to enable the ability for a SQL database name to be used as the special QTEMP library. When the Enable button is selected, the "SQL Database to be used as QTEMP library" option will be enabled, for you to specify a SQL Database to be used as a QTEMP library.
-
To disable this support (if previously enabled), click on the Disable button. The "SQL Database to be used as QTEMP library" option will be disabled and appear 'dimmed'.
SQL Database to be used as QTEMP library:
This option will only be available if the Enable button has been clicked.
-
Specify the name of a SQL database to be used as the special QTEMP library. The name of the database does not have to be QTEMP, but it will be accessed by DataGate in response to requests for QTEMP library requests.
-
If the database does not exist, it will be created with default attributes.
Install Button:
Selecting Install will save the entries to the dialog and continue with the installation.
Please note that the Install button will only be enabled when the Enable button is selected.
Done Button:
Selecting Done indicates you are finished with the dialog, and that you will not specify a SQL Database to be used as a QTEMP library. The DSS installation will continue.
However, please note that selecting Done while accessing the Stored Procedures dialog from Start - Programs - ASNA .NET Product Suite - DataGate for SQL Server 8.1 - ASNA DataGate for SQL Server 8.1 Stored Procedures will display a dialog stating "DataGate For SQL Server was cancelled or was unable to install properly will display". Select the OK button to close the dialog box.
Help Button:
Select Help to display the help topic for additional
information.
ASNA DataGate 8.1 for SQL Server must be properly
licensed prior to using it. The steps to
license DataGate for SQL Server is exactly the same as licensing AVR
or DataGate Client.
Refer to the Registration Assistant help file (Regasist.chm)
in C:\Program Files\Common Files\ASNA Shared for more information!
After you have completed the installation procedure, you can
start any of the products included with DataGate at any time.
1. Start DataGate Database Manager by selecting Start – Programs - ASNA .NET Product Suite – DataGate – DataGate Database Manager.
2.
For
help on using any of the products, select Contents from the Help menu to
display the On-line help file.
To Remove ASNA DataGate for SQL Server
1. Select Start – Settings - Control Panel.
2. Select Add/Remove Programs.
3. Select ASNA DataGate 8.1 for SQL Server.
4. Click the Add/Remove… icon.
5. Click Yes to begin removing DataGate. Click No to return to the previous screen.
To remove Stored Procedures, you will need to also
select the ASNA DataGate for SQL Server 8.1 Stored Procedures option
separately.
SQL Server Service Manager is used to start, stop, and pause
the Microsoft® SQL Server™ 2000 components on the server. These components run as services on Microsoft Windows® 2000 and above.
SQL Server Service implements the SQL Server database engine. There is one SQL Server service for each instance of SQL Server running on the computer.
SQL Server Service Manager is a taskbar application and
follows the standard behavior of taskbar applications. The task bar icon will display whether the
Server is running ,
paused, or stopped .
Important!!!! There is a field within the SQL Server Service Manager that you need to select, or ensure that it is enabled. It is called “Auto-start service when OS starts”. Please ensure this option is selected, especially when installing AVR as well, as the system will reboot after installing AVR. If this option is not selected, the SQL Server Service will be stopped, so when the installation process continues and tries to install DataGate for SQL Server, you will receive an error, and DataGate for SQL Server will not be installed.
Note that this option is not selected by default. You must select this option prior to installing DataGate for SQL Server (if installing AVR at the same time).
To Open, Start, Pause or Stop the SQL Server Manager
1.
After
Microsoft SQL Server is installed, the SQL Service Manager icon for the local
machine will display in the right hand corner of your taskbar. To open SQL Server Service Manager, either
double-click on the , or right-click on the icon to display a list of menu options. The SQL Server Service Manager dialog will display.
Enter or select the following to SQL Server Service Manager:
Server:
The name of the local computer will display. Clicking on the arrow to the right will display all of the SQL Servers that you have access to.
Services:
The SQL Server service will display. Clicking on the arrow to the right will display the other SQL services you have access to, such as SQL Server Agent, and Distributed Transaction Coordinator.
Refresh services…
Select this button to refresh the services.
Start/Continue
Selecting this button starts the SQL Server Service. After it is started, the option will be dimmed, and the icon will display with a green start icon next to it, indicating the service is started. Select this option when the service is either currently paused, or stopped.
Pause
Select this button to temporarily pause the SQL Server Service. To continue service, select the Start/Continue button.
Stop
Select this button to stop the SQL Server Service. To start the service again, select the Start/Continue button.
Auto-start service when OS starts:
Select this option to ensure that the SQL Server Service automatically restarts after your system has been restarted.
Note that this option is not selected by default. You must select this option prior to installing DataGate for SQL Server (if installing AVR at the same time).
2.
To
close SQL Server Service Manager, right-click the SQL Server Service
Manager icon on the taskbar, and then select the Exit menu option.
Back to Top
Release Notes
ASNA DataGate 8.1 for
SQL Server also supports SQL Server 2005 and SQL Server 2005 Express.
Licensing Changes
DataGate 8.1 for SQL Server employs a new
License Manager that eliminates the duplicate user counts that were encountered
in previous versions.
Installing Microsoft's XP Pro Service Pack 2, by default, enables the built-in Windows firewall settings which interfere with SQL Server connectivity. These settings, unless changed, won't let you connect to SQL Server 2000 (with either SQL Server's own Enterprise Manager or with ASNA's DataGate for SQL Server (DSS).
The Windows Firewall closes ports such as 445 that are used for file and printer sharing to prevent Internet computers from connecting to file and print shares on your computer or to other resources. When SQL Server is configured to listen for incoming client connections by using named pipes over a NetBIOS session, SQL Server communicates over TCP ports and these ports must be open. SQL Server clients that are trying to connect to SQL Server will be not be able to connect until SQL Server is set as an exception in Windows Firewall. To set SQL Server as an exception in Windows Firewall, use the steps that are listed here.
As part of the basic strategy to give SQL Server the semantics of
DB2/400, DataGate for SQL Server (DSS) was built to permit as much manipulation
as possible of the underlying objects directly, via native SQL commands. As a
consequence of such strategy, it was decided that there would be no artificial
structure imposed on the tables and views used to implement the concept of
physical and logical files. Files were then implemented as follows:
·
A
Physical file is implemented as a Table.
An Indexed Physical file requires an Index with the same name as the
Table.
·
A
Simple Logical file is implemented
as a View. An Indexed Simple Logical file requires an
Index with the same name as the View.
·
A
Join Logical file is implemented as
a View. An Indexed Join Logical file requires an
Index with the same name as the View.
This index marks which table is considered the ‘primary file’.
When a simple logical file is
created, it is possible to establish the underlying ‘Select’ in two ways:
·
Select
individual columns from the table.
·
Select
all columns via a ‘Select * from TableX’ by checking the ‘Clone base file
fields in new format’ check box.
In either case, the SCHEMABINDING option is not used; this permits the
table to be altered, thus new columns can be added to an existing table without
having to drop the views first. However,
SQL Server does not reflect the new columns in the corresponding views (those
with the ‘Select * ’ command) until such views are recreated.
This is a natural behavior of SQL Server views and DSS does not alter it. Notice also that DSS does not provide a way to add new fields to a file, so the procedure aforementioned has to be done using SQL Server’s Enterprise Manager.
Contents
Native SQL Server Field Interpretation
Calling
Programs/Procedures Considerations
|
Item |
DG/400 |
DSS for .NET |
DataGate |
|
Library & file name length |
10 characters |
31 characters |
31 |
|
Members per file |
0 ® *NoMax |
Exactly
1 |
0 ®
*NoMax |
|
File types |
Physical Simple logical Join logical Multiformat logical Print |
Physical SqlLogical Simple logical Join logical Print |
Physical Simple logical Join logical Multiformat logical Print |
|
Max record length |
32,000
bytes |
8,060
bytes (Not counting Text and Image fields which are not accessible yet by DSS
.NET). |
32,000 bytes |
|
Max number of records per member |
|
2,147,483,646 |
2,147,483,646* |
|
Library implemented as: |
Library |
Database |
Illusion |
|
Object text (description) |
49 characters |
49 characters |
49 characters |
|
Stored Procedures |
Any AS/400 language |
Programmed in SQL-Transact |
None |
|
Triggers |
Any AS/400 language |
Programmed in SQL-Transact |
None |
|
Field Reference File (FRF) |
A physical file can refer to any number of
FRF, which are any physical file in any library. However, DG/400 will report
only those coming from the file stated in the DDS REF keyword. |
Refers to the collection of ‘User Defined
Data Types’, which is one per Database (i.e.: Library). This collection is surfaced via the special
file ‘*FieldRef’
which is the ONLY file usable as a FRF. |
A physical file can refer to only ONE
FRF, which can be any physical file in any library. |
* NOTE:
For Max number of records per member, DataGate for Windows and
Desktop Servers Release 8.1, Version 8.155 and higher support member/file sizes
limit is 16 exabytes ( 2^4 * 2^60).
|
Item |
DG/400 |
DSS
.NET |
DataGate |
|
Indexed logical
files per physical file |
|
249 |
*NoMax |
|
Logical field
used as a key field must be based on a physical field with the same name |
No |
Yes.
Notice that this eliminates the possibility of using Renamed,
Concatenated and Substringed fields as keys. |
No |
|
Maximum number
of key fields per key |
|
16 |
250 |
|
Maximum length
of key in bytes |
2,000 |
900 |
250 |
Data Access Considerations
|
Item |
DG/400 |
DSS
.NET |
DataGate |
|
Arrival Access |
Relative Record
Number is used for Sequential and Random access. |
Only Consecutive access is supported, but
there is no guaranteed order of retrieval unless the file is indexed. The only random operation allowed is SetLL
and this is only when used with *Start and *End. No other kind of seeking
(SetGT,CHAIN) is allowed. |
Relative Record
Number is used for Sequential and Random access. |
|
Format Name |
Given by file
creator. |
Always
‘R’ followed by File Name. Note to AVR Users: The Format can be renamed
in the DclDiskFile, using the RNMFMT keyword by providing a new name, is not
necessary to provide the existing Name in the RNMFMT. This allows the
creation of single-source apps that can compile against DG/400 and DSS .NET. |
Given by File creator. |
|
Open Query File |
Implemented
with OpenQry. |
Select expression is used as the WHERE
clause of a SELECT. The key field list
is used as the ORDER BY clause. The select expression is passed directly to
the SQL analyzer with no interpretation. The expression must follow
valid SQL Server syntax. Pay special
attention to uses of logical operators. Use ‘and’ and ‘or’ not ‘&’
and ‘|’. |
A temporary
logical file is created using the select expression as a select/omit
expression and the key field list to define the new key. |
Record Locking
DG/400
DB2/400 determines the type and duration of
records locks depending on how the file was opened.
For read-only files, when a record is read, there is no lock requested on it, and if some other application has the record lock, the reading application does not block on the lock, that is, the record gets read in-spite of being locked by somebody else.
For files open for update, every time a record is read it is write-locked so that other updating applications can’t read it. The write lock is held until the record is updated or explicitly unlock by the application or when another record is read or positioned to.
DSS .NET
DSS for .NET (using server cursors) also
determines the locking characteristics bases on how the file is opened.
For read-only files DSS for .NET behaves like DG/400, that is, there are no locks neither placed nor considered on records being read.
The behavior of DSS for .NET when the file is opened for update is similar to DG/400 but with two significant differences: updating a record does not release the lock on the record and explicitly unlocking a record causes the ‘current record position’ to be lost. These differences bear the following considerations.
|
Item |
DG/400 |
DSS .NET |
|
|
Unlock
Record |
Cursor
position is unchanged. |
The
file has no ‘current’ position after the Unlock. |
|
|
Update
Record |
The
record just updated is released. |
The record just updated is kept locked. |
|
|
*NoLock
option on Read operations |
Supported but deprecated. |
Unsupported. The better way to achieve this is to open the file twice, once for input only and the other for update. Where the read appears with the *NoLock option, the file should be substituted with the one open for input only. By doing this, the application can take advantage of network blocking - yielding better performance. |
|
|
Range
operations |
When the end of the range is reached, the file has no ‘current’ position. |
When the end of the range is reached, the file has no ‘current’ position. |
|
|
Hit
EOF on a ReadE (P) |
Lose Record position. |
Lose Record position. |
|
|
Other
Operations like SetLL |
Unlock Record. |
Unlock Record. |
|
Loops involving SetLL/SetGT and
Read/ReadE/ReadPE should be recoded to use the Range operations.
The most demanding change is the one requiring segments of code involving CHAIN-UPDATE. Combinations have to be studied and possibly modified.
·
If
the CHAIN-UPDATE happens in a tight loop, then at the end of the loop an UNLOCK
should be issued to release the last record updated. Notice however that the
record position will be lost after the UNLOCK.
·
If
the CHAIN-UPDATE is sprinkled throughout the code, then each case has to be
closely studied.
Object Locking
Not
implemented on DSS .NET.
|
Item |
DG/400 |
DSS
.NET |
DataGate |
|
Field name
length |
10 characters |
31 characters |
31 |
|
Types supported |
Char ®
*CHAR Packed ®
*PACKED Zoned ® *ZONED Binary ® *BINARY Float ® *FLOAT Integer ® *INTEGER Date ® *DATE Time ® *TIME Timestamp ® *TIMESTAMP Hex ® *HEX DBCS ® *DBCS Unicode ® *DBCS Boolean ® *CHAR(1) |
Char ®
char Packed ®
decimal Zoned ® numeric Binary ® numeric Float(4) ® float Float(8) ® real Integer(2) ® smallint Integer(4) ® int Date ® *ASNA_DSS .NET_DATE datetime= Time ® *ASNA_DSS .NET_TIME datetime=1899/12/30 Timestamp ® datetime Hex ® binary DBCS ® nchar Unicode ® nchar Boolean ®
Bit |
Char ®
*CHAR Packed ®
*PACKED Zoned ® *ZONED Binary ® *BINARY Float ® *FLOAT Integer ® *INTEGER Date ® *DATE Time ® *TIME Timestamp ® *TIMESTAMP Hex ® *HEX DBCS ® *DBCS Unicode ® *DBCS Boolean ®
*CHAR(1) |
|
Allow Nulls |
Yes |
Yes |
No |
|
Variable Length
Fields |
Char Hex DBCS |
Char ®
varchar Hex ®
varbinary DBCS ® varnchar |
No |
|
Date value
range |
|
Datetime
(ASNA_DSS .NET_DATE): 1753-01-01 ®
9999-12-31 Smalldatetime: 1900-01-01 ® 2079-06-06 |
|
|
Decimal Number
Storage |
Packed (1 nibble per digit) Zoned (1 bye per digit) Binary: 1 – 4 digits = 2 bytes 5 – 9 digits = 4 bytes |
Decimal | Numeric: 1
– 9 digits = 4 + 1 bytes 10 – 19 digits = 8 + 1 bytes 20 – 29 digits = 12 + 1 bytes 30 – 38 digits = 16 + 1 bytes |
Packed (1 nibble per digit) Zoned (1 bye per digit) Binary: 1 – 4 digits = 2 bytes 5 – 9 digits = 4 bytes |
|
Date storage |
1 byte per
digit/character |
Datetime
8 bytes ASNA_DSS .NET_DATE 8 bytes SmallDatetime 4
bytes |
1 byte per
digit/character |
|
Fields per file |
|
1,024 |
32,000 |
|
Re-typing
logical fields |
Unrestricted |
Logical fields who’s type differs from that
of the corresponding physical field cannot be updated. |
Unrestricted |
|
Column Heading
Definitions |
Up to 3
31-characters |
The 3 headings
are concatenated into the MS Access CAPTION field. |
Up to 3
31-characters |
|
Text
Description |
Up to 49
characters |
Up to 49
characters |
Up to 49
characters |
|
Numerics |
Date/Time |
Char/Other |
|
Float ®
*Float (4) Real ®
*Float (8) Int ® *Integer (4) SmallInt ® *Integer (2) TinyInt ® *Integer (2) Decimal ® *Packed BigInt ® *Zoned(19,0) Money ® * Zoned(19,4) Numeric ® *Zoned SmallMoney ® * Zoned(9,4) |
DateTime ®
*Timestamp SmallDateTime ® *Timestamp |
Bit ®
*Boolean Char ®
*Char VarChar ® *Char (VarLen) NChar ® *Unicode NVarChar ® *Unicode (VarLen) Binary ® *Hex VarBinary ® *Hex (VarLen) UniqueIdentifier ® *Hex (16) |
The types Image, Text and NText are not supported. Fields of these types are hidden from the
file definition. You will be able to
display the file definition in Database Manager, but won’t be able to open the
file. To ensure future application compatibility, you should not use files
containing these field types. Instead you should create logical files
naming the individual fields that your application will manipulate. That
way, if in a future release the fields ‘appear’, your application will not
break.
|
Item |
DG/400 |
DSS
.NET |
DataGate |
|
|
Supports Use
Default for Joins by: |
DDS Keyword JOINDFLT?? When a record
is not found in the secondary file, logical fields whose base is that file
will be populated with the default values specified in the physical file
definition. |
|
|
|
Creating a Left Outer Join instead of an Inner Join.
|
Supports ‘Join
Duplicates By’ |
DDS Keyword
JDUP |
Not supported. Duplicate rows in the ‘secondary’ tables
may be returned in random order. |
Yes |
|
LEFT JOIN or LEFT OUTER JOIN
|
The result set of a left outer join includes all the rows from the left table specified in the LEFT OUTER clause, not just the ones in which the joined columns match. When a row in the left table has no matching rows in the right table, the associated result set row contains null values for all select list columns coming from the right table. | Yes | |
|
Item |
DG/400 |
DSS
.NET |
DataGate |
|
Maximum Number
of Parameters |
36 |
2100 |
N/A |
|
Parameter
Direction |
*Input,
*Output, *Both |
*Input, *Both |
N/A |
Q. Will DataGate for SQL Server require SQL Server
client licenses for end Users or will a server license be
enough?
A. Every user will have to be licensed. There are 2 ways of achieving this; one is to
buy individual Per-Seat licenses, the other is to buy a per-processor license.
The following link will take you to the MS prices as of Aug. 2001:
http://www.microsoft.com/sql/howtobuy/pricing/default.asp. This is another good link with common
licensing questions:
http://www.microsoft.com/catalog/display.asp?site=10145&subid=22&pg=4
Here is a breakpoint list of the 2 different
license models for Standard Edition:
SQL Server 2000 Standard Edition - purchase
processor license if:
1 processor machine: more than 24 users
2 processor machine: more than 53 users
4 processor machine: more than 112 users
8 processor machine: more than 229 users
Q. Will I have to get a DataGate for
SQL Server license or is a SQL Server licenses all I need?
A. You will have to obtain a DataGate license to
access data stored in SQL Server.
Q. Which version(s) of SQL Server will be supported
by DataGate for SQL Server?
A. DataGate supports all editions of SQL Server 2000 (
Q. Is the Library List supported?
A. Yes.
Q. I have an DataGate database with files in the
root library, how can I get them into SQL Server?
A. Use the CopyLibrary option of DataGate Database Manager, user ‘/’ for
the Source library and a named library for the target.
Q. After copying my libraries to SQL Server, are
there new files identical to the originals?
A. Almost, but not quite. The main difference you will see is that
fields defined as BINARY in the original files will appear as being ZONED. The impact of this change in your AVR
programs is only reflected when the field is part of a Data Structure, in which
case, the compiler will protest the discrepancy in the definition of the field,
i.e: the program defines as binary, but the file as defines as zoned.
Q. What is MSDE ?
A. Go to
http://www.microsoft.com/sql/techinfo/development/2000/MSDE2000.asp for a description of MSDE. The
Addendum 1 is attached in case the link moves.
Q. Given that DSS for .NET imposes the format name
(as an ‘R’ followed by the file name), do I have to modify all of my file
record formats on the AS/400 to match the file and how will this affect my AVR
programs when referring to the old format name?
A. If you compile against DataGate or DG400, you
will be able to run against DSS for .NET even if your format names are
different. However if you compile
against DSS for .NET and your code refers to a format name which doesn't match
the one in DSS .NET, then you can either change your references to it (lots of
work), or do a rename format in the DclDiskFile (little work).
RNMFMT has been enhanced to take a single parameter
to indicate to AVR that this is the new name by which you will be referring to
the ONLY format in this DclDiskFile. If
you don't rename the format, then AVR will use whatever the database provided
it with.
Q. How are the printer files going to work if we
cannot have multiple record formats?
A. Print files are supported just like in DataGate,
that is, they can still be multi-format.
It is only the data files that have to be single-format.
Porting AVR .NET Applications
to Employ ASNA DataGate® for SQL Server®
for .NET
Introduction
ASNA's DataGate for SQL Server Classic (DSS for .NET) provides AVR programmers’ access to Microsoft SQL Server 2000 through native RPG file IO using familiar RPG operation codes such as CHAIN and SETLL. DSS for .NET allows you write one set of applications that works concurrently with both the iSeries and SQL Server databases.
You will not need to learn SQL to get effective access to SQL Server. The skills you use today for iSeries file IO will work exactly the same way for SQL Server via DSS for .NET. The same AVR programs that connect to SQL Server will seamlessly connect to the iSeries and ASNA’s DataGate engine.
DSS for .NET makes a SQL Server instance appear as a database similar to DataGate or iSeries. The characteristic features of DB2/400 materialize on SQL Server when seen through the eyes of DSS for .NET. With DSS for .NET, you can use the Library list, Physical and Logical files, even DB2 field types, like packed and zoned.
Back to Porting Applications Top
Even though DSS for .NET tries to make SQL Server look like DB2/400, there are several features that cannot be implemented in a totally transparent fashion. The SQL Server 2000 database engine is of a different design and implementation than the iSeries and DataGate engines.
The intent of this document is to help you become aware of the items that will most likely affect your application and the process of using SQL Server as your database. Through it all, remember the goal you are seeking is to create applications that take advantage of the many features of SQL Server and to create applications that can run with either SQL Server or DB2/400 as the underlying database engine.
In the next sections we’ll deal with all of the issues that will need your attention, but the following items are probably the ones with the most impact for many of you.
No Multi-Format Logical Files:
DSS for .NET implements a physical file through the use of a native SQL Server table. A logical file is implemented through a native view. SQL Server Views are single formatted in nature, so there is no support for multi-format logical data files. You will have to eliminate any reference to multi-format logical files in your application.
Print files, although they are typically multi-formatted, are fully supported in DSS for .NET, however.
Single Member Files:
SQL Server doesn’t have the concept of members of a table/view. DSS for .NET makes it appear as though each file had one (and only one) member; the member name is exactly the same as the file name. For the member name, you can use the exact name or the special values *FIRST and *FILE. You should be careful when using the Copy Data and Copy Library tools of the DataGate Database Manager to copy a file from DataGate or iSeries, because they default to *SAME for the target member name; if the source member name was differently than the file name the copy will fail.
If your application depends on the existence of multiple members per file, you will want to re-architect it to provide an alternative method for handling the logic involving these files.
Logical Field Restrictions:
There are two restrictions on the usage of logical
fields when they change the name or the type of their corresponding base physical
field. When the field is retyped, most
typically because the field is a concatenation or substring of the physical,
then the field becomes read only. A
logical field, whose name has changed from its physical base field, can’t be
used as a key field in the logical file.
Unlocking Records:
This is probably the most demanding area of application adaptation between the differences of implementation between iSeries method of record locking and that of the SQL Server database engine. The problem arises in two areas: Using the *nolock keyword on the read operations and on the implementation of the UNLOCK command.
DSS for .NET uses SQL Server ‘Server Cursors’ to implement file access. When a file is opened for update, it is not possible to tell SQL Server to not lock the record on a read, so a read with *nolock has no effect for files opened for Update. There are two methods to resolve this problem:
1. Declare a second instance of the file marked as input only
and use it wherever the NoLock option would have been given on a read/chain.
2. Retain the *nolock and follow the read/chain with an UNLOCK
command. Be aware this method imposes
some restrictions as stated in the next paragraph.
The UNLOCK command leaves the cursor in a no-position state, meaning you can’t perform a subsequent read (next/previous) without repositioning the file with a SETLL, SETGT or CHAIN.
Back to Porting Applications Top
In a nutshell, the process of upgrading your application is composed of the following steps:
1. Get a decent size computer.
2. Move your data from the iSeries or DataGate Engine to SQL Server.
3. If necessary, modify your application to adapt to any new restrictions.
4. Optimize your application to take advantage of several AVR op-codes.
1. Computer Size
SQL Server is very demanding on computer resources. We recommend you get a computer with at least the capacity of the cheapest machine you can get from Dell, but with twice the amount of memory. The machine doesn’t have to be a Dell computer, but use the Dell machine as a reference to configure your box.
It is highly recommend that you use Windows XP Professional and above or Windows 2000 workstation for your development machine.
Back to Porting Applications Top
2. Move Your Data
The first step after installing DataGate for SQL Server on your machine is to create a Database Name that points to your SQL Server. You can use the Database Wizard or the Work with Database Names option of the Database menu of Database Manager.
Under typical SQL Server installations, there is only one instance of the server installed on the machine and that instance typically contains the following databases:
· Master
· Model
· Msdb
· Northwind
· Pubs
· Tempdb
Each one of these databases will be presented through DSS for .NET as individual libraries. Since all databases are shown under a common database name, the "Label' parameter of a database name pointing to DataGate 8.1 for SQL Server must be "SQL".
The following figure shows a Database Name
called
You can use *DOMAIN for your user name or you can supply one of the login names recognized by SQL Server with its corresponding password.
Test your Database Name by opening the database with Database Manager. You should see something like the following:
When you open a database for the first time, Database Manager prompts you for your viewing preferences for the database with a dialog like the following.
Notice in particular the checkbox Show system objects. It controls whether to or not to display a set of SQL Server objects called sysxxxx. For iSeries databases, this option shows or hides objects like QSYS.
Prepare Files and Copy Libraries:
The next step in moving your data is to prepare a
library (or libraries) on the source machine with all the files you wish to
copy to the target SQL Server.
After you have prepared the library, use the Copy Library option from the Tool menu to move the data.
You can use one of your existing libraries, but it
may require some clean up before it is ready. To check your data, use one of
the options below:
1.
You
can do a visual inspection of the files in the library to
verify/modify them to comply with the check list.
2.
Alternatively
issue the copy command and wait for it to tell you whether
there are any problems.
Visual Inspection Using a Checklist:
Use the following checklist to ensure
a DataGate or iSeries data file will be successfully copied to SQL Server:
The file must have:
-
only one member
-
the member name the same as the file name
-
only one format
-
maximum of 16 key fields
-
maximum key length of 900 bytes
-
maximum of 1024 fields
-
maximum record length of 8060 bytes
Logical
files have extra restrictions. Make sure
that the key fields are not substrings or concatenations of physical fields and
that the name of the logical field is the same as that of its base field.
Issue the Copy Command and Note if there are
any Problems
If you choose the second option, uncheck the Copy Data Records in the Copy Library dialog to speed up the process. Take note of any problem and after fixing it, delete the target library and issue the Copy Library command again, this time copying the data records. You can view the result of the copy in the Message Log window.
Copy Library:
Once you have modified your files to comply with the limitations stated above, you can use the Copy Library menu option.
All files stored under SQL Server must reside inside a ‘Library’ just like files on an iSeries. DataGate Engine has allowed files to be placed at the ‘root’ level of the database and under subfolders inside a library. If you have files in places other than first level libraries, you’ll have to adapt your application (or the library list) to point to the new locations.
When a physical file is copied to SQL Server, a table is created with the name of the physical file. For logical files, a view is created. In either case, if the file is keyed, an index is created on the table; for logical files the index is created on the primary base table.
When a view is encountered through DSS for .NET, it is reported as being
a new kind of logical file, called SQL
Logical. That is why when a logical file is copied, regardless of whether a
logical file is a Simple Logical or
a Join Logical, it will appear on the SQL
Server database as a SQL Logical
file.
Field Reference Files
Field Reference Files are used on the iSeries to collect definitions of named field types that are used in the creation of data files. SQL Server has a built-in data dictionary where user types can be defined. DSS for .NET surfaces this data dictionary through the special file *FieldRef. There is one *FieldRef file per library.
If you use a field reference file as part of your data file definitions, you should first import those fields into the data dictionary of the DSS for .NET library.
Follow these steps to populate the dictionary:
1. Open
the source database.
2. Drag
the field reference file to the Work Definition
Area.
3. Open the target database.
4. Create
the target library.
5. Drag
the field reference file to the target database taking care of specifying *FieldRef as the file name to be
created. DSS for .NET will notice the special name and add the fields to the
data dictionary.
After you
have populated the data
dictionary, you can view the type definitions by clicking on the *FieldRef file
in the target library.
If you don’t see the *FieldRef file in the library, ensure that the
option to Show System Objects is
checked ON in the options dialog.
Back to Porting Applications Top
3.
Adapt the Application
Enable DataGate for SQL Server Warnings:
To assist in finding areas in code that will potentially cause an error, a new IDE option has been added to ASNA Visual RPG to give warnings for invalid operations under DSS for .NET. This option is located within the “Compiler” Tab of the Project >Settings menu option.
Select the Enable DataGate for SQL Server Warnings option so that a check mark appears in the check box and select OK.
Depending upon your application, the following are some changes you will/may need to make to your DCLDISKFILE statements.
Arrival sequence processing must be changed to indexed processing. SQL Server doesn’t have the concept of a relative record number (RRN).
The simplest method for handling this would be to employ the use of a key field in the file. If the file is being processed only in consecutive fashion (i.e. you don’t use random op-codes like SETLL or CHAIN on the file) then you can choose any field to be the key and specify RANDOM(*NO) in the DCLDISKFILE. If you do process the file randomly, then you will need to add a field to the file to simulate the RRN sequence. The easiest way to achieve this is by adding an identity field called RecNum of type integer.
In DSS for .NET, the record format name is always “R” + Filename. If the record format name is anything else, and you’ve specified this record format name on I/O operations, a rename format will need to be specified on the DCLDISKFILE statement as follows. RNMFMT(OldFormatName) where OldFormatName is the name of the existing format. No changes will need to be made to the actual I/O statements.
If your application makes use of the Open Query File capability of DataGate or iSeries, you will have to take care of a couple of things.
-
The string passed in the QrySelect must comply with the syntax of SQL Server, for example you should use the word ‘and’ not the symbol ‘&’.
-
If you are changing the order of the file by providing a value in the QryKeyFlds parameter, then you must also specify RANDOM(*NO) in the DCLDISKFILE to state that you will be accessing this file only consecutively.
If an application is going to run against both DSS for .NET and DataGate 400, and your file currently contains binary fields, you will need to consider changing the field type.
The behavior of DSS for .NET when the file is opened for update is similar to DG/400, but with two significant differences:
1. Updating a record does not release the lock on the record.
2. Explicitly unlocking a record causes the ‘current record position’ to be lost.
These
differences bear the following considerations:
Loops involving SetLL-SetGT and Read-ReadE-ReadPE should be re-coded to use the Range operations.
The most demanding change is the one requiring segments of code involving CHAIN-UPDATE combinations to be studied and possibly modified.
·
If the CHAIN-UPDATE happens in a tight loop, then at the
end of the loop, an UNLOCK should be issued to release the last record
updated. Notice however that the record
position will be lost after the UNLOCK.
· If the CHAIN-UPDATE is sprinkled throughout the code, then each case has to be closely studied.
Back to Porting Applications Top
4. Optimize Your Applications with AVR Op-Codes
To optimize SQL Server
processing and to enhance client/server performance with all supported database
engines (iSeries/400, DataGate and SQL Server) with dynamic Network Blocking,
AVR has 3 op-codes; SetRange, ReadRange and DeleteRange, as
described below:
I/O op-codes provide better
performance in two ways:
1. When
working with large SQL Server files,
DSS for .NET is able to optimize the record set selection operation.
2. Network
Blocking becomes dynamic, in that records outside of the range are not
transmitted to the client.
Use the SETRANGE op-code in
place of SETLL and SETGT when you’re doing SETLL/READE and SETGT/READPE loops.
Use the READRANGE op-code in
place of the CHAIN op-code when you’re doing CHAIN/READE loops.
Use the DELETERANGE in place
of DELETE loops.
Strong consideration should be given to Visual RPG Error Indicators when
performing I/O operations as they could be turned on now for reasons not
present before. For instance, when the Chain opcode returned an error,
the cause was commonly assumed to be that the record was busy. With DSS
for .NET, error indicators can be turned on for various reasons such as the use
of the *NOLOCK option on I/O operations.
(See Locking Considerations in the DG400 vs. DSS for .NET
document).
New Error
Conditions under DSS for .NET:
The following situations will cause the error indicator to be set on.
1. Arrival Random Access.
When a file is opened for *Arrival
access, commands such as Chain, Setll, etc, will cause an error condition.
2. Use of the *NOLOCK option is not supported under DSS for .NET.
Any I/O operations that make use of the *NOLOCK option when working with files opened for update will cause an error condition.
Contents
Considerations for Adapting Existing Applications
to DSS for .NET
Strong consideration should be given to Visual RPG Error Indicators when
performing I/O operations as they could be turned on now for reasons not
present before. For instance, when the Chain opcode returned an error,
the cause was commonly assumed to be that the record was busy. With DSS
for .NET, error indicators can be turned on for various reasons such as the use
of the *NOLOCK option on I/O operations.
(See Locking considerations in the DG400 vs. DSS for .NET document).
The following situations will cause the error indicator to be set on.
1. Arrival Random Access.
When a
file is opened for
*Arrival access,
commands such as Chain, Setll, etc, will cause an error condition.
2. Use of the *NOLOCK option is not supported under DSS for .NET.
Any I/O operations that make use of the *NOLOCK option when working with files opened for update will
cause an error condition.
To assist in finding areas in code that will potentially cause an error, a new IDE option is added to give warnings for invalid operations for DSS for .NET. This option is located in the “Compiler” Tab of the Project >Settings menu option.
I/O op codes provide better
performance when working with large files.
·
SetRange
– Use the SetRange opcode in place of Setll when you’re doing Setll/Reade
loops.
·
ReadRange
– Use the ReadRange opcode in place of the Chain opcode when you’re doing Chain/Reade
loops.
·
DeleteRange
– Use the DeleteRange when performing delete loops.
In DataGate for SQL Server, the record format
name is always “R” + Filename. If
the record format name is anything else, and you’ve specified this
record format name on I/O operations, a rename format will need to be specified
on the DCLDISKFILE statement as follows. RNMFMT(OldFormatName) where
OldFormatName is the name of the existing format. No changes will need to
be made to the actual I/O statements.
The old syntax of RNMFMT(OldFormatName,NewFormatName) is not needed.
·
Arrival sequence processing must be changed to indexed
processing. The simplest method for handling this would be to employ the use of
a key field in the file.
·
If
you’re using multi-member files, you will need to provide an alternative
method for handling the logic involving these files.
·
If
your file’s record length is > 8060, you will need to consider
changes necessary in order to make the record length smaller.
·
Be
sure to include the
range operations to enhance speed.
·
If
you were using the *NOLOCK opcode for files opened for update, you will
need to declare an *Input instance of the file for *NOLOCK access.
·
If
an application is going to run against both DataGate for SQL Server and DataGate 400, and
your file currently contains binary fields, you will need to consider changing
the field type.
·
Object
Locking