Download Administration Guide - Supra

SQL ACCESS FOR SUPRA
SERVER PDM®
Administration Guide
P25-9501-04
SQL Access for SUPRA Server PDM®
Administration Guide
Publication Number P25-9501-04
© 2006, 2007, 2009, 2011 Cincom Systems, Inc.
All Rights Reserved
This document contains unpublished, confidential, and proprietary information of Cincom. No
disclosure or use of any portion of the contents of these materials may be made without the
express written consent of Cincom.
See http://www.cincom.com/legal/terms.html for a list of Cincom trademarks and other
trademarks that may appear in Cincom product documentation.
All other trademarks are trademarks or registered trademarks of their respective companies.
Cincom Systems, Inc.
55 Merchant Street
Cincinnati, Ohio 45246-3732
USA
PHONE: (513) 612-2300
FAX: (513) 612-2000
WORLD WIDE WEB: http://www.cincom.com
Attention:
Some Cincom products, programs, or services referred to in this publication may not be
available in all countries in which Cincom does business. Additionally, some Cincom products,
programs, or services may not be available for all operating systems or all product releases.
Contact your Cincom representative to be certain the items are available to you.
Release information for this manual
SQL Access for SUPRA Server PDM Administration Guide, P25-9501-04, is dated
September 1, 2011. This document supports Release 2.0 of SQL Access for
SUPRA Server PDM.
Cincom Technical Support for SQL Access for SUPRA Server PDM
All customers
Web:
http://supportweb.cincom.com
U.S.A customers
Phone:
1-800-727-3525
Fax:
(513) 612-2000
Attn: SQL Access for SUPRA Server PDM
Support
Mail:
Cincom Systems, Inc.
Attn: SQL Access for SUPRA Server PDM
Support
55 Merchant Street
Cincinnati, OH 45246-3732
USA
All:
Visit the support links at
http://www.cincom.com to find contact
information for your nearest Customer
Service Center.
Outside of U.S.A.
Using this manual
$ORDB refers to the directory identified by the ORDB environment variable.
This will be set to the installation directory.
This document may use both UNIX ($ORDB/..) and Windows (%ORDB%\..)
notations. Please adjust the environment variable and slashes accordingly
for your platform.
Contents
1. Overview of SQL Access for SUPRA Server PDM ............................... 11 Overview .................................................................................................. 11 2. Starting/stopping SQL Access for SUPRA Server PDM......................... 14 Starting SQL Access for SUPRA Server PDM components .......................................... 14 Starting the MVS CID Adapter Server ............................................................ 14 Starting the MVS CICS CID Adapter Server ...................................................... 14 Starting the OpenVMS CID Adapter Server...................................................... 15 Starting the UNIX CID Adapter Server ........................................................... 16 Testing the CID Adapter Server connection .................................................... 17 Starting the SQL Access Server on Windows ................................................... 18 Starting the SQL Access Server on UNIX ........................................................ 18 Shutting down SQL Access components .............................................................. 19 Shutting down the SQL Access Server on UNIX................................................. 19 Shutting down a CID Adapter Server ............................................................ 20 Controlling the start and shut down of the CID Adapter Client .................................. 22 Starting the CID Adapter Client .................................................................. 22 Controlling the CID Adapter Client .............................................................. 23 Startfdb utility ...................................................................................... 24 Stopfdb utility ...................................................................................... 25 3. Managing a CID Foreign Database................................................. 27 Overview .................................................................................................. 27 Registering a CID Foreign Database .................................................................. 29 Creating foreign tables ................................................................................. 30 Attributes and their domains ..................................................................... 32 Foreign table query specification ................................................................ 33 Definition of domain information ................................................................ 35 Data type mapping ................................................................................. 36 Data modeling considerations ......................................................................... 38 Using a script to register a CID Foreign Database .................................................. 40 REGISTER CID DATABASE statement ............................................................. 40 Altering the registration of a CID Foreign Database ............................................... 42 Altering a foreign table ................................................................................ 43 Adding an attribute ................................................................................ 45 Adding a new query specification ............................................................... 46 Changing an attribute definition ................................................................. 47 Administration Guide, P25-9501-04
Contents
4
Changing the query specification ................................................................ 48 Dropping an attribute.............................................................................. 50 Dropping a query specification ................................................................... 51 Renaming an attribute............................................................................. 52 Deleting/Dropping CID Foreign Database entities.................................................. 53 Dropping the registration of a CID Foreign Database ......................................... 54 Dropping foreign tables ........................................................................... 55 Joining foreign tables................................................................................... 56 Creating a view .......................................................................................... 57 Security and Authorization ............................................................................ 60 Access privileges ........................................................................................ 61 Authorizing access to a foreign table ................................................................ 62 Users.................................................................................................. 62 Granting authorization/privileges to users ..................................................... 63 Revoking authorization/privileges .................................................................... 66 User overview ............................................................................................ 68 Adding users .............................................................................................. 69 add_user method ................................................................................... 69 Groups and members .............................................................................. 70 User definition file ................................................................................. 71 Deleting users ............................................................................................ 73 Dropping a user ..................................................................................... 73 Dropping a member ................................................................................ 73 Renaming the DBA and PUBLIC users ................................................................. 74 Renaming the DBA .................................................................................. 74 Renaming the PUBLIC user ........................................................................ 74 Authorization classes in the SQL Access Server .................................................... 75 db_user class ........................................................................................ 75 db_authorizations class............................................................................ 76 Calling authorization methods ................................................................... 77 Authorization methods ............................................................................ 78 Transaction recovery ................................................................................... 83 PDM Locking considerations ........................................................................... 84 Statistics considerations ............................................................................... 85 4. Tailoring the CID Adapter Server ................................................. 88 Overview .................................................................................................. 88 Accessing VSAM Files .................................................................................... 90 Tailoring the MVS CID Adapter Server ................................................................ 91 Defining the MVS CID Adapter Server JCL ...................................................... 92 Defining the MVS CID Adapter Server CSV1SHUT JCL ......................................... 95 Defining the MVS CID Adapter Server CSV1PING JCL .......................................... 96 Defining the MVS CID Adapter Server CSV1PORT JCL ......................................... 97 Defining the MVS and CICS initialization parameters ......................................... 98 CID Adapter Server init file parameters (MVS and CICS) ..................................... 99 Coding the optional user logon exit (MVS) .................................................... 111 Administration Guide, P25-9501-04
Contents
5
Creating an additional MVS CID Adapter Server .............................................. 113 Tailoring the MVS CICS CID Adapter Server ........................................................ 114 Defining the MVS CICS initialization file parameters ........................................ 114 Updating the SUPRA PDM or VSAM CICS environment and JCL for the Adapter Server . 115 Defining the CICS CID Adapter Server CSV1PING and CSV1PORTJCL ..................... 117 Creating an additional CICS CID Adapter Server .............................................. 117 Tailoring the OpenVMS CID Adapter Server ........................................................ 118 Authorizing OpenVMS Privileges................................................................. 118 Running the S1_ADAPTER_SETUP.COM command file ....................................... 119 Defining CID Adapter Server logical names.................................................... 123 Defining and enabling a TCP/IP service through UCX (OpenVMS) ......................... 126 Defining the CID Adapter Server/CID Adapter Coordinator startup procedure (OpenVMS)127 Defining the initialization parameters (OpenVMS) ........................................... 130 Server init file parameters (OpenVMS) ......................................................... 131 Coding the optional user logon exit (OpenVMS) .............................................. 140 Tailoring the UNIX CID Adapter Server .............................................................. 142 Defining SUPRA PDM environment variables and logical names ............................ 142 Defining CID Adapter Server environment variables ......................................... 143 Running the s1_adapter_setup script .......................................................... 143 Defining TCP/IP to UNIX .......................................................................... 147 Defining the CID Adapter Server startup procedure (UNIX)................................. 148 Defining the initialization parameters (UNIX) ................................................ 149 Server init file parameters (UNIX) .............................................................. 150 Coding the optional user logon exit (UNIX) ................................................... 158 5. Tailoring the CID Adapter Client ................................................. 160 Overview ................................................................................................. 160 Tailoring the Windows CID Adapter Client component ........................................... 161 Defining parameter values ....................................................................... 162 Defining parameter values for a specific PDM database .................................... 162 Summary of CID Adapter Client component parameters .................................... 163 Tailoring the UNIX CID Adapter Client component ................................................ 170 Defining parameter values for the installation ............................................... 171 Defining parameter values for a specific database .......................................... 171 Summary of CID Adapter Client component parameters .................................... 173 CID Adapter NO-TRACE executable binaries ....................................................... 183 Windows CID Adapter Client component ...................................................... 183 UNIX CID Adapter Client component ........................................................... 184 MVS CID Adapter Server component ............................................................ 184 UNIX CID Adapter Server component ........................................................... 184 OpenVMS CID Adapter Server component ..................................................... 185 Administration Guide, P25-9501-04
Contents
6
6. Cincom ORDB Visual Administration Tool ...................................... 187 Overview ................................................................................................. 187 System requirements ............................................................................. 187 Starting the Visual Administration Tool............................................................. 188 Connecting to a database host ....................................................................... 189 Disconnecting from a database ...................................................................... 192 Starting and stopping SQL Access Servers .......................................................... 193 Viewing SQL Access Servers........................................................................... 194 View all SQL Access Servers ..................................................................... 194 View running SQL Access Server ................................................................ 195 View status for a SQL Access Server ............................................................ 196 Viewing Client Settings ................................................................................ 197 View Server Settings ................................................................................... 200 Database Security ...................................................................................... 202 DBA Logon ............................................................................................... 204 ORDBINIT Management ................................................................................ 205 SUPRA INI file Management ........................................................................... 208 Displaying SQL Access Server transactions ......................................................... 211 Killing SQL Access Server transactions .............................................................. 212 Displaying transaction lock information ............................................................ 213 Displaying SQL Access Server lock information .................................................... 214 Displaying SQL Access Server volumes .............................................................. 215 To display volumes: ............................................................................... 215 Displaying and starting CID Foreign Databases .................................................... 217 Starting CID Foreign Databases.................................................................. 217 Viewing CID Foreign Databases .................................................................. 217 SQL Access Server location file ...................................................................... 218 Maintaining a SQL Access Server ..................................................................... 219 Adding a volume ................................................................................... 220 Checking SQL Access Server consistency ...................................................... 222 Copying a SQL Access Server .................................................................... 224 Creating a SQL Access Server .................................................................... 229 Deleting a SQL Access Server .................................................................... 233 Loading a SQL Access Server ..................................................................... 234 Moving a SQL Access Server ...................................................................... 238 Renaming a SQL Access Server .................................................................. 241 Unloading a SQL Access Server .................................................................. 243 7. Utilities ............................................................................... 247 Overview ................................................................................................. 247 Foreign Table Generator .............................................................................. 248 Executing the Foreign Table Generator ....................................................... 249 createdb ................................................................................................. 251 Syntax ............................................................................................... 251 Return values ...................................................................................... 251 Administration Guide, P25-9501-04
Contents
7
Options .............................................................................................. 252 Choosing a locale and character set ........................................................... 257 SQL Access Server location file.................................................................. 259 User definition file ................................................................................ 261 addvoldb ................................................................................................. 263 Syntax ............................................................................................... 263 Options .............................................................................................. 264 loaddb .................................................................................................... 266 Loading the schema file .......................................................................... 266 Syntax ............................................................................................... 267 Return values ...................................................................................... 267 Options .............................................................................................. 268 Input file format ................................................................................... 270 Object references ................................................................................. 275 Using a CLASS method to populate a class .................................................... 279 unloaddb ................................................................................................. 281 Syntax ............................................................................................... 282 Return values ...................................................................................... 282 Options .............................................................................................. 282 copydb ................................................................................................... 285 Syntax ............................................................................................... 285 Return values ...................................................................................... 286 Options .............................................................................................. 286 Example ............................................................................................. 288 deletedb ................................................................................................. 290 Syntax ............................................................................................... 290 Return values ...................................................................................... 290 Options .............................................................................................. 291 renamedb ................................................................................................ 292 Syntax ............................................................................................... 292 Return values ...................................................................................... 292 Options .............................................................................................. 293 Displaying the SQL Access release version ......................................................... 295 Syntax ............................................................................................... 295 Example ............................................................................................. 295 checkdb .................................................................................................. 296 Syntax ............................................................................................... 296 Return values ...................................................................................... 296 Options .............................................................................................. 297 Example output .................................................................................... 298 Password maintenance ................................................................................ 299 Syntax ............................................................................................... 299 Return values ...................................................................................... 299 Options .............................................................................................. 299 Processing when no options are specified ..................................................... 301 Administration Guide, P25-9501-04
Contents
8
8. Controlling SQL Access for SUPRA Server PDM processes .................. 302 Programs to start or shut down the SQL Access Server .......................................... 302 The SQL Access Master program ................................................................ 305 The SQL Access Server program ................................................................. 306 The commdb utility ............................................................................... 307 Checking the status of the SQL Access Master and connected SQL Access Servers .......... 315 Syntax ............................................................................................... 315 Options .............................................................................................. 315 Killing a transaction.................................................................................... 316 Syntax ............................................................................................... 316 Return values ...................................................................................... 316 Options .............................................................................................. 317 Examples ............................................................................................ 318 9. SQL Access for SUPRA Server PDM system parameters ..................... 320 Summary of SQL Access system parameters ....................................................... 322 Displaying parameter values currently in effect .................................................. 325 Syntax for parameters ................................................................................. 326 Standalone parameters ................................................................................ 327 SQL Access Server parameters ....................................................................... 328 Parameters related to error messages ......................................................... 328 Parameters related to memory space .......................................................... 330 Parameters related to disk storage ............................................................. 331 Parameters related to recovery/logging....................................................... 333 Parameters related to concurrency/locking .................................................. 339 Parameter related to threads ................................................................... 343 Parameters related to communication services .............................................. 343 Parameters related to SQL Access Client requests on the SQL Access Server ........... 345 Parameter related to the query cache......................................................... 345 Parameters related to SQL Access Server file based objects ............................... 346 SQL Access Client parameters ........................................................................ 347 Parameters related to connecting to SQL Access Server .................................... 347 Parameters related to workspace memory .................................................... 348 Parameters related to query services .......................................................... 349 Parameters related to quitting/disconnecting from applications ......................... 353 Utility parameter ....................................................................................... 354 Foreign Database parameter ......................................................................... 355 Data validation parameters ........................................................................... 356 Administration Guide, P25-9501-04
Contents
9
A. Advanced Topics .................................................................... 357 Sample foreign tables for the MVS Burrys PDM database ........................................ 357 Sample foreign tables for the OpenVMS and UNIX Burrys PDM database ...................... 364 Extending the CID Adapter Schema ................................................................. 371 File................................................................................................... 374 Field ................................................................................................. 376 Foreign_key ........................................................................................ 386 Access_method .................................................................................... 388 File Example ....................................................................................... 391 View ................................................................................................. 393 Access ............................................................................................... 394 View example ...................................................................................... 400 COPY2XML COBOL copybook tool .................................................................... 404 Example ............................................................................................. 408 Modifying the ASCII/EBCDIC translation tables .................................................... 412 EBCDIC to ASCII default translation table ..................................................... 413 ASCII to EBCDIC default translation table ..................................................... 414 B. S1_ADAPTER_SETUP ............................................................... 415 OpenVMS ................................................................................................. 415 UNIX ...................................................................................................... 418 Index ...................................................................................... 421 Administration Guide, P25-9501-04
Contents
10
1. Overview of SQL Access for
SUPRA Server PDM
Overview
SQL Access for SUPRA Server PDM (SQL Access) enables dynamic access to your
PDM and/or CICS VSAM data in real time using ODBC, JDBC, or OLE DB
interfaces. There is no need to extract the data and transform it into a
relational database and write custom code. SQL Access allows you to easily
access your PDM and/or CICS VSAM data using ODBC, JDBC, or OLE DB client
applications.
The SUPRA Server PDM supports a virtually infinite number of data models
because of the flexibility of its data structures (record codes, linkpaths, etc.).
SQL Access provides the flexibility and power to allow relational SQL access to
these PDM data models. SQL Access makes use of the linkpaths, indices, and
control keys, where applicable, to develop optimal access strategies.
SQL Access can access KSDS, ESDS and RRDS VSAM files using a primary key or
an alternate index when appropriate. These CICS VSAM files may be joined to
each other or to CICS SUPRA Server PDM files. Update commands are available
for KSDS and ESDS files, and delete commands are available for KSDS files.
Additional components are also available for XML and XMLDB interfaces, as well
as providing a distributed multidatabase environment for other ODBC-compliant
databases. Contact your local Cincom representative for details about these
additional components.
In SQL Access the metadata for the fields in a PDM or CICS VSAM file are
mapped into an entity called a foreign table and stored in the SQL Access
Server. The foreign table definitions are made available to the client
application. SQL Access will optimize based on the information retrieved from
the PDM directory (linkpaths, indices and control keys) or based on available
CICS VSAM primary key and alternate indices.
It is important to note that the PDM and VSAM data is not copied into the SQL
Access Server; the SQL Access Client application has direct access to live PDM
and VSAM data.
Administration Guide, P25-9501-04
Chapter: 1. Overview of SQL Access for SUPRA Server PDM
Section: Overview
11
The following diagram shows the communication flow of SQL Access:
TCP/IP
- Client application
- SQL Access for SUPRA Server
PDM Client
- SQL Access for SUPRA
Server PDM Server
- PDM Adapter Client
- SUPRA Server PDM Database
- PDM Adapter Server
1. The client application sends an SQL request. The SQL Access Client sends
the request to the SQL Access Server.
2. The SQL Access Master, SQL Access Server and the Cincom Integrated
Data (CID) Adapter Client reside on the SQL Access Server machine. The
SQL Access Master manages connections to the SQL Access Server and
starts SQL Access Servers and CID Adapter Clients as necessary. The SQL
Access Server performs transaction management and sends the SQL
request to the CID Adapter Client.
3. The CID Adapter Client translates the SQL request using the maps (foreign
tables) stored in the SQL Access Server and sends it to the CID Adapter
Server.
4.
PDM The CID Adapter Server performs query optimization and joining and
sends the individual PDM commands to the SUPRA Server PDM Database.
VSAM The CID Adapter Server performs query optimization and joining and
sends the VSAM file requests to the VSAM Access Module. This in turn
sends the individual CICS VSAM requests to CICS for each VSAM file.
5. The SUPRA Server PDM Database or CICS VSAM executes each command
and sends the results back to the CID Adapter Server.
6. The results are buffered and sent back to the CID Adapter Client, which
passes them back to the SQL Access Server. The SQL Access Server sends
the results to the SQL Access Client, which passes them to the client
application.
Administration Guide, P25-9501-04
Chapter: 1. Overview of SQL Access for SUPRA Server PDM
Section: Overview
12
Before you can use ODBC, JDBC, or OLE DB to access your PDM and/or CICS
VSAM files, you must define the PDM database and the PDM files and/or the
VSAM files to the SQL Access Server. If one does not exist, you will create a SQL
Access Server. Then you define the PDM database or CICS VSAM to the SQL
Access Server by registering it. This is a simple process. For PDM you define
the PDM / dbmod name, PDM host name, and port for TCP/IP communications,
and give this definition or registration a name. For VSAM you define the CICS
VSAM system. For more details, see "Registering a CID Foreign Database" on
page 29.
Next you define each PDM and or VSAM file that you wish to make available to
the client application. This definition is called a foreign table. In the foreign
table you will define the field names and data types for each field in one file or
record code. This may sound daunting, but the Visual SQL tool makes this a
very easy task. For PDM, it will read the PDM Directory and display the names
and data types found there for the file. For VSAM, it will read the CID Adapter
Extensions XML file and display the names and data types found there for each
VSAM file. You may modify them or save the definition as it is. For more
information about adding a Foreign Table, refer to the SQL Access for SUPRA
Server PDM SQL Reference Guide, P25-9503.
Administration Guide, P25-9501-04
Chapter: 1. Overview of SQL Access for SUPRA Server PDM
Section: Overview
13
2. Starting/stopping SQL Access for
SUPRA Server PDM
Starting SQL Access for SUPRA Server PDM components
There are two components of SQL Access for SUPRA Server PDM (SQL Access)
that need to start: the CID Adapter Server on MVS/OpenVMS/UNIX and the SQL
Access Server on either Windows or UNIX.
Cincom recommends that you start these components in the order listed.
In addition, the SQL Access Server has three components that run as separate
processes on the SQL Access Server Machine: the SQL Access Master, the SQL
Access Server and the CID Adapter Client.
Starting the MVS CID Adapter Server
The CID Adapter Server can be started either as a batch job or as a started task
using the JCL described in "Tailoring the MVS CID Adapter Server" on page 91.
The CID Adapter Server is ready for connections as soon as the following
message is written to MSGPRINT:
CSHP522I CID Adapter Release n.n.nnx waiting for connections
The CID Adapter Server is fully reentrant and refreshable. It runs RMODE (24),
AMODE (31). If desired, it can be placed in the Linkpack area for shared
operation.
Starting the MVS CICS CID Adapter Server
The MVS CICS CID Adapter Server is started either from the sequential terminal
input DAKD\ or from any terminal with transaction DAKD. The Adapter Server is
ready for connections as soon as the following message is written to the VDAK
transit data destination:
CSHP522I CID Adapter Release n.n.nnx waiting for connections
The MVS CICS CID Adapter Server runs as CICS conversational task(s).
Administration Guide, P25-9501-04
Chapter: 2. Starting/stopping SQL Access for SUPRA Server PDM
Section: Starting SQL Access for SUPRA Server PDM components
14
Starting the OpenVMS CID Adapter Server
Prior to starting an OpenVMS CID Adapter Server it is necessary to set up an
adapter for a specific dbmod. This is done by executing the
S1_ADAPTER_SETUP.COM command file, located in the COMS directory of the
OpenVMS CID Adapter Server install. This will create all of the files necessary
to start and stop the CID Adapter Server. The file names and services for an
adapter are preceded by the CID Adapter Server name, which is typically the
dbmod name.
Prior to starting an OpenVMS CID Adapter Server it is necessary to define logical
names that will be used by all CID Adapter Servers. This is done by executing
the command file LOGICALS.COM in the COMS directory of the install directory.
It is recommended that one of the following lines be added to your
SYSTARTUP_VMS.COM file:
$ @ <install-disk>:[<install-directory>.COMS]LOGICALS GROUP
$ @ <install-disk>:[<install-directory>.COMS]LOGICALS
LNM$GROUP_nnnnnn
$ @ <install-disk>:[<install-directory>.COMS]LOGICALS SYSTEM
One of these commands may also be executed at the command line prior to
starting a CID Adapter Server.
An OpenVMS CID Adapter Server is started by executing the following command
located in the directory from which the S1_ADAPTER_SETUP command file was
executed:
@<adapter-name>_RUN
The OpenVMS CID Adapter Server is ready for connections as soon as the
following message is written to the log file, <adapter-name>_LOG.DAT:
4930 08:56:14 CSHP500I Tue Aug 22 08:56:14 2006
Coordinator for VMS Release n.n.nnx started
CID Adapter
See the "Tailoring the OpenVMS CID Adapter Server" on page 118 for more
information.
Administration Guide, P25-9501-04
Chapter: 2. Starting/stopping SQL Access for SUPRA Server PDM
Section: Starting SQL Access for SUPRA Server PDM components
15
Starting the UNIX CID Adapter Server
Prior to starting a UNIX CID Adapter Server it is necessary to set up a CID
Adapter Server for a specific dbmod. This is done by executing the
s1_adapter_setup script, located in the CIDAdapterServer_nnnn directory of the
UNIX CID Adapter Server install. This will create all of the files necessary to
start and stop the CID Adapter Server. The file names and services for a CID
Adapter Server are preceded by the CID Adapter Server name, which is
typically the dbmod name.
Prior to starting a UNIX CID Adapter Server it is necessary to start the UNIX
SUPRA Server PDM. This is usually done during or after logging in to the UNIX
machine by running scripts to create the necessary environment variables and
logical names.
A UNIX CID Adapter Server may be started by executing the following command
located in the PDM System directory, /supra1/<pdm-system-name>:
<adapter-name>_run
The UNIX CID Adapter Server is ready for connections as soon as the following
message is written to the log file, <adapter_name>.log:
19725 09:02:09 CSHP500I Tue Aug 22 09:02:09 2006
Coordinator for UNIX Release n.n.nnx started
CID Adapter
See "Tailoring the UNIX CID Adapter Server" on page 142 for more information.
Administration Guide, P25-9501-04
Chapter: 2. Starting/stopping SQL Access for SUPRA Server PDM
Section: Starting SQL Access for SUPRA Server PDM components
16
Testing the CID Adapter Server connection
After starting a CID Adapter Server, the csv1ping utility can be used to verify
that the CID Adapter Server is listening on the expected port. The csv1ping
utility can be run either on the SQL Access Server machine or on the CID
Adapter Server machine.
Use the following platform-specific commands to run the utility on the SQL
Access Server machine:
WINDOWS
UNIX
csv1ping –p <port-number> -d <database-name> -h <host-name>
csv1ping –p <port-number> -d <SQL-Access-Server-name> -h <hostname>
Use the following platform-specific methods or commands to run the utility on
the CID Adapter Server machine:
MVS
OPENVMS
UNIX
You can verify that the MVS CID Adapter Server is listening on the expected
port by using the CSV1PING JCL supplied with the installation. For more
information about this job, see "Defining the MVS CID Adapter Server
CSV1SHUT JCL" on page 95.
@V1HUB_COMS:CSV1PING –P <port-number> -D <SQL-Access-Servername>
csv1ping –p <port-number> -d <SQL-Access-Server-name>
In all cases, the utility will display normal messages to the standard output file
and errors to the standard error file. The utility will return 0 for success and -1
for failure.
Administration Guide, P25-9501-04
Chapter: 2. Starting/stopping SQL Access for SUPRA Server PDM
Section: Starting SQL Access for SUPRA Server PDM components
17
Starting the SQL Access Server on Windows
The SQL Access Master process is installed as a service, so it is started
automatically when Windows is started. The Master service then automatically
starts all the SQL Access Servers. The mastersrv command can be used to stop
and restart the SQL Access Master between Windows boots.
The Visual Administration Tool can be used to start, stop, and restart the SQL
Access Server between Windows boots. The CID Adapter Server on the PDM host
does not need to be stopped if you stop and restart the SQL Access Server on
Windows.
See "8. Controlling SQL Access for SUPRA Server PDM processes" on page 302 for
details about SQL Access Master and SQL Access Server processes.
Starting the SQL Access Server on UNIX
The SQL Access Server is started on UNIX using the start_server utility script
($ORDB/utilities/start_server). This script determines if the SQL Access Master
process is running. If it does not detect a SQL Access Master process running, it
starts the SQL Access Master before starting the SQL Access Server. Execute
this utility using the following syntax:
start_server <SQL-Access-Server-name>
This utility returns a value of zero (0) for successful execution or a non-zero
value for unsuccessful execution.
Administration Guide, P25-9501-04
Chapter: 2. Starting/stopping SQL Access for SUPRA Server PDM
Section: Starting SQL Access for SUPRA Server PDM components
18
Shutting down SQL Access components
When shutting down the CID Adapter Server, the SQL Access Server needs to
be shut down, as well. Cincom recommends that you shut them down in this
order:
1. SQL Access Server on Windows
2. CID Adapter Server on MVS/OpenVMS/UNIX
This is reverse of the order in which they should have been started.
Shutting down the SQL Access Server on Windows
The Visual Administration Tool or the commdb utility can be used to stop the
SQL Access Server. All SQL Access Server processes may be stopped using the
commdb utility (%ORDB%\commdb.exe). Execute this utility using the following
syntax:
commdb –A
See "8. Controlling SQL Access for SUPRA Server PDM processes" on page 302 for
details about shutting down the SQL Access Server processes.
Shutting down the SQL Access Server on UNIX
The Visual Administration Tool, the stop_server utility, or the commdb utility
can be used to stop the SQL Access Server on UNIX.
To stop a particular SQL Access Server using the stop_server utility script
($ORDB/utilities/stop_server), use the following syntax:
stop_server SQL-Access-Server-name
This utility returns a value of zero (0) for successful execution or a non-zero
value for unsuccessful execution.
The stop_server utility does not stop the SQL Access Master process. The SQL
Access Master process and all SQL Access Server processes may be stopped
using the commdb utility ($ORDB/utilities/commdb). Execute this utility using
the following syntax:
commdb –A
See "The commdb utility" on page 307 for more information.
Administration Guide, P25-9501-04
Chapter: 2. Starting/stopping SQL Access for SUPRA Server PDM
Section: Shutting down SQL Access components
19
Shutting down a CID Adapter Server
A CID Adapter Server can be shut down by executing the csv1shut utility on the
SQL Access Server machine using the following platform-specific commands:
WINDOWS
csv1shut –p <port-number> -d <SQL-Access-Server-name> -h <nostname>
UNIX
csv1shut –p <port-number> -d <SQL-Access-Server-name> -h <nostname>
When run on the SQL Access Server machine, the csv1shut utility requests the
shutdown user id and password from the user, obtains the port number, host
name, and SQL Access Server name from the command line arguments, and
connects to the CID Adapter Server requesting a shut down. The CID Adapter
Server validates the user id and password values against the SHUTDOWN_USER
and SHUTDOWN_PASSWORD defined in the CID Adapter Server INIT file. If the
values are valid and there are no active or cached connections, the CID Adapter
Server will shut down; otherwise, the shut down request will be denied. See
"Stopfdb utility" on page 25 for information about shutting down the CID
Adapter Client connections.
The csv1shut utility may also be run on the CID Adapter Server machine. This is
described in the following sections for each CID Adapter Server platform.
Shutting down the MVS CID Adapter Server
You can shut down the MVS CID Adapter Server by using the CSV1SHUT JCL
supplied with the installation. For more information about this job, see
"Defining the MVS CID Adapter Server CSV1SHUT JCL" on page 95. This job will
only successfully shut down the CID Adapter Server if all CID Adapter Clients
have been shut down. See "Stopfdb utility" on page 25 for information about
shutting down the CID Adapter Client connections.
If you have the CICSSHUT pltd program implemented, all active conversational
CICS CID Adapter Server tasks will be purged via this pltd and allow CICS to
continue with its normal shut down.
You can also run the CSV1SHUT batch job to shut down the MVS CICS CID
Adapter Server. This will put the MVS CICS CID Adapter Server into the shut
down state and will not allow any new connections. Transaction DAKD can be
run from any terminal to allow the MVS CICS CID Adapter Server to return the
system to the active state. It is not recommended that you use this job against
the MVS CICS Adapter Server.
Administration Guide, P25-9501-04
Chapter: 2. Starting/stopping SQL Access for SUPRA Server PDM
Section: Shutting down SQL Access components
20
Shutting down the MVS CICS CID Adapter Server
The MVS CICS CID Adapter Server is shutdown when CICS is shut down. Because
the server is running as a conservational task, there may be some delay
experienced during CICS shutdown. Processing and tasks may need to be
aborted via CICS to allow shut down processing to continue.
Shutting down the OpenVMS CID Adapter Server
On OpenVMS, you can shut down a CID Adapter Server with the <adaptername>_STOP.COM command file created by the S1_ADAPTER_SETUP.COM
command file in the directory from which it was executed. The csv1shut utility
is executed in this command file. Use the following syntax at the command
prompt:
@<adapter-name>_STOP
This form of the command will cause the CID Adapter Server to check for active
or cached connections before shutting down. To force the CID Adapter Server
to shut down, use the following syntax:
@<adapter-name>_STOP -F
Shutting down the UNIX CID Adapter Server
On UNIX, a CID Adapter Server may be shut down using the <adaptername>_stop script created by the s1_adapter_setup script in the PDM System
directory. The csv1shut utility is executed from this script file. Use the
following syntax at the command prompt:
<adapter-name>_stop
This form of the command will cause the CID Adapter Server to check for active
or cached connections before shutting down. To force the CID Adapter Server
to shut down, use the following syntax:
<adapter-name>_stop -f
Administration Guide, P25-9501-04
Chapter: 2. Starting/stopping SQL Access for SUPRA Server PDM
Section: Shutting down SQL Access components
21
Controlling the start and shut down of the CID Adapter Client
Starting the CID Adapter Client
Once you have registered your CID Foreign Database, the CID Adapter Client
component can be started in two different ways:
♦
It can be automatically started by the SQL Access Master process. When a
user requests data from the CID Foreign Database, a CID Adapter Client
process is started by the SQL Access Master process. The CID Adapter
Client then communicates the request to the CID Adapter Server on
MVS/OpenVMS/UNIX.
♦
You can use the startfdb utility to start the minimum number of CID
Adapter Clients prior to use by a SQL Access Client. Once the SQL Access
Client connection requests exceed the minimum number, CID Adapter
Client processes are started automatically, up to the maximum. The
minimum and maximum number of CID Adapter Clients are defined when
registering the Foreign Database. See "Registering a CID Foreign Database"
on page 29 for more information.
Administration Guide, P25-9501-04
Chapter: 2. Starting/stopping SQL Access for SUPRA Server PDM
Section: Controlling the start and shut down of the CID Adapter Client
22
Controlling the CID Adapter Client
The SQL Access Server can control the CID Adapter Client using the following
utilities:
♦
startfdb
♦
stopfdb
Each CID Adapter Client can be recycled during a SQL Access Server session.
The SQL Access Server keeps the defined minimum number of CID Adapter
Clients in its adapter cache. The SQL Access Client can get faster response to
its requests by reducing CID Adapter Client startup time. After the SQL Access
Client commits or aborts, the CID Adapter Client goes back to the cache to be
made available for the next SQL Access Client.
The minimum and maximum number of CID Adapter Clients for each CID
Foreign Database Is defined when registering that CID Foreign Database.
Setting the minimum number of CID Adapter Clients has two purposes:
♦
To start a specified number of CID Adapter Clients using the startfdb utility
before SQL Access Clients send PDM access requests to the CID Adapter
Server
♦
To preserve a minimum number of CID Adapter Clients that are not to be
killed when the SQL Access Server shuts down those that have been idle
beyond a certain time
Administration Guide, P25-9501-04
Chapter: 2. Starting/stopping SQL Access for SUPRA Server PDM
Section: Controlling the start and shut down of the CID Adapter Client
23
Startfdb utility
The startfdb utility provides the means to start up the minimum number of CID
Adapter Clients specified for the CID Foreign Database. Note that in addition to
the command line execution, the startfdb utility can be executed from the
Visual Administration Tool.
Syntax
This command line invokes the startfdb utility:
startfdb [options] SQL-Access-Server-name
where:
-
options can be the following:
-a All registered CID Foreign Databases for a specific SQL Access
Server. This option allows you to prestart the minimum number of
CID Adapter Clients for each registered CID Foreign Database. For
example, if there are five registered CID Foreign Databases, and
each has the value “2” for minimum number of CID Adapter
Clients, then 10 CID Adapter Clients will be started. Please note
that the default minimum number of CID Adapter Clients is “0”.
-l
Specific registered CID Foreign Database. This option allows the
DBA to specify a single CID Foreign Database for which the
minimum number of CID Adapter Clients is to be prestarted. The
CID Foreign Database name must have been previously registered
using a REGISTER PDM DATABASE (or REGISTER FOREIGN DATABASE)
statement.
-q Quiet. Startfdb will not show its start or end banners. The success
or failure of the startfdb command will be displayed.
-
SQL-Access-Server-name specifies the name of your SQL Access Server.
It cannot be a path such as C:\usr\smith\test_db but must be a
simple name such as test_db.
Example
In the following example the SQL Access Server name is ‘myserv’ and the
registered CID Foreign Database name is ‘fdb0’. This example shows how to
prestart CID Adapter Clients only for the specific CID Foreign Database
registered as ‘fdb0’.
C:\> startfdb -l fdb0 myserv
Administration Guide, P25-9501-04
Chapter: 2. Starting/stopping SQL Access for SUPRA Server PDM
Section: Controlling the start and shut down of the CID Adapter Client
24
Stopfdb utility
The stopfdb utility kills all CID Adapter Clients in the adapter cache without
considering the minimum number of CID Adapter Clients except those currently
active (bound to SQL Access Clients). It is used to clean the adapter cache so
that the CID Adapter Server does not maintain connections with idle adapters.
After this utility has run, the SQL Access Server will have to start up new CID
Adapter Clients on demand when a SQL Access Client requests CID Foreign
Database access.
Note that in addition to the command line execution, the stopfdb utility can be
executed from the Visual Administration Tool.
Syntax
This command line invokes the stopfdb utility:
stopfdb [options] server-name
where:
-
options includes the following:
-a All registered CID Foreign Databases for a specific SQL Access
Server. This option kills all idle CID Adapter Clients in the adapter
cache without considering the minimum number of CID Adapter
Clients.
-l
Specific registered CID Foreign Database. This option allows the
DBA to kill idle adapters only for a specific CID Foreign Database.
-q Quiet. If used, stopfdb will not show its start or end banners. The
success or failure of the stopfdb command will be displayed.
-pw SQL Access Server Password. Use this option to specify the
password if the SQL Access Server has a password. For example, to
specify the password tmp of the myserv SQL Access Server, enter
the following command:
stopfdb –pw tmp –l fdb0 myserv
A prompt requesting the SQL Access Server password is displayed if
a stopfdb is attempted for a password protected SQL Access Server
and the –pw option is not specified. The password entered in
response to this prompt is hidden while it is being typed.
-
server-name specifies the name of your SQL Access Server. It cannot
be a path such as C:\usr\smith\test_db but must be a simple name such
as myserv.
Administration Guide, P25-9501-04
Chapter: 2. Starting/stopping SQL Access for SUPRA Server PDM
Section: Controlling the start and shut down of the CID Adapter Client
25
Example
In the following example, the SQL Access Server name is ‘myserv’ and the
registered CID Foreign Database name is ‘fdb0’. This example shows how to
shut down idle CID Adapter Clients only for the specific CID Foreign Database
registered as ‘fdb0’.
C:\> stopfdb -l fdb0 myserv
Administration Guide, P25-9501-04
Chapter: 2. Starting/stopping SQL Access for SUPRA Server PDM
Section: Controlling the start and shut down of the CID Adapter Client
26
3. Managing a CID Foreign
Database
Overview
Each SUPRA PDM database is defined in the PDM Directory. The files and data
fields in the database are defined there as well as domain information and the
access methods available to access data in a variety of ways. It is REQUIRED
that the data fields and domain information be defined in the Cincom
Integrated Data (CID) Adapter Extensions XML file if they are not defined in the
CID Adapter Server prior to using SQL Access for SUPRA Server PDM (SQL
Access). For VSAM files all data fields and domain information must be defined
in the CID Adapter Extensions XML file prior to accessing the data using SQL
Access.
PDM
For PDM files, the CID Adapter Server component of SQL Access reads the PDM
Directory and builds a schema consisting of the information required by the CID
Adapter Client and Server components. Additionally, the schema can be
extended to include additional information that may not be defined in the PDM
Directory. This includes the definition of fields and their domains, foreign keys,
CID Adapter Views, and additional access methods. These extensions are
specified in the CID Adapter Extensions XML file, which is read by the CID
Adapter Server.
VSAM
For VSAM files, all the fields and their domains must be defined in the CID
Adapter Extensions XML file. If this information is contained in a COBOL
copybook, you may use the COPY2XML tool to place these definitions into the
CID Adapter Extensions XML file. Refer to “COPY2XML COBOL Copybook Tool”
for more details. The basic access methods and foreign keys are automatically
generated in the internal schema and do not need to be entered into the CID
Adapter Extensions XML file.
See "Extending the CID Adapter Schema" on page 371 for more information.
In prior releases, the CID Adapter Server’s schema was extended with the
foreign key file. The Adapter Extensions XML file replaces the foreign key file.
The foreign key file will continue to function as documented in earlier releases.
Both files may be used to extend the same CID Adapter Server schema in this
release.
The information in the schema is used by the CID Adapter Client and Server
components to access PDM and/or VSAM data and transform it into the SQL
Access data model.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Overview
27
A Foreign Database is a description of the PDM database or the CICS VSAM
system and the parameters used to communicate with it. The CID Foreign
Database is defined in the SQL Access Server by registering the Foreign
Database. The CID Foreign Database consists of foreign tables. A foreign table
is used to map PDM and/or VSAM fields and provide a direct link to the data in
one PDM and/or VSAM file.
A foreign table consists of two parts:
♦
Attribute list. The attribute list contains the attribute names and domains
that SQL Access Client tools will use in queries.
♦
Query specification. The query specification identifies the PDM and/or
VSAM fields that will correspond to each attribute in the attribute list and
identifies the name of the PDM and/or CICS VSAM file.
SQL Access uses the term "attribute" instead of "field" or "column" and the term
"domain" instead of "data type".
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Overview
28
Registering a CID Foreign Database
In order to access a PDM database or CICS VSAM system, it must be registered
in the SQL Access Server. An alias name for the PDM database CICS VSAM
system and information required for accessing the PDM database CICS VSAM
system are supplied when it is registered.
Cincom recommends that you use Visual SQL (refer to the SQL Access for SUPRA
Server PDM SQL Reference Guide, P25-9503) to register the CID or CICS VSAM
system Foreign Database. It provides a dialog box, which you can easily fill in
to complete the registration.
If, however, you would like to create a script file or otherwise register the
Foreign Database manually using SQL, you can use the REGISTER PDM DATABASE
statement, described in "Using a script to register a CID Foreign Database" on
page 40.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Registering a CID Foreign Database
29
Creating foreign tables
A foreign table is essentially a map of a file in the PDM or CICS VSAM Foreign
Database that is stored in the SQL Access Server. Only one foreign table can be
created for each PDM or CICS VSAM Foreign Database file to be accessed.
The foreign table consists of:
♦
One attribute and associated domain for each field in the PDM or CICS
VSAM file
♦
A query specification, which indicates the exact field name and file name
in the PDM or CICS VSAM Foreign Database
We recommend that you use either Visual SQL (refer to the SQL Access for
SUPRA Server PDM SQL Reference Guide, P25-9503) or the Foreign Table
Generator Utility (see "Foreign Table Generator" on page 248) to create foreign
tables. Visual SQL is best suited when you have just a few foreign tables to
create. The Foreign Table Generator Utility is more efficient when you have a
large number of foreign tables to create.
Both of these tools will suggest a name for the foreign table and attribute
names corresponding to each of the fields in the PDM or CICS VSAM file. You
may change the suggested foreign table name and the suggested attribute
names in each tool. The discussion below will help you understand the syntax
of the foreign table and the naming rules and conventions.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Creating foreign tables
30
Syntax
CREATE FOREIGN TABLE foreign_table_name ON [FOREIGN DATABASE]
foreign_database_name
[ { UNDER | AS SUBCLASS OF } super_foreign_table_name [ {,
super_foreign_table_name }… ] ]
[ ( foreign_table_attr_definition [ {,
foreign_table_attr_definition }… ] ) ]
[ AS foreign_table_query_specification ] [ ; ]
where:
-
foreign_table_name must be unique. It cannot be created using a name
that already exists in the SQL Access Server as another foreign table,
view/virtual class, class/table, or registered PDM or CICS VSAM Foreign
Database. The name cannot contain spaces, and it cannot be a SQL
Access reserved word. For a list of reserved keywords, refer to the SQL
Access for SUPRA Server PDM SQL Reference Guide, P25-9503.
Alphanumeric characters, underscores (_), the number sign (#), and the
percentage sign (%) are allowed in the foreign table name. The name
identifier must begin with a letter, and the maximum number of
characters for a name is 255.
-
foreign_table_attr_definition has the following syntax and is further
explained in "Attributes and their domains" on page 32:
attribute_name
-
data_type
[ DEFAULT value ]
foreign_table_query_specification has the following syntax and is
further explained in "Foreign table query specification" on page 33:
select_statement
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Creating foreign tables
31
Attributes and their domains
The attributes you define in a foreign table are enclosed in parentheses and
must be given a name and a domain. The attribute_name you assign should
follow the same character-use conventions that were described for foreign_
table_name.
The data_type given as the domain of an attribute can be any valid built-in
data type that is supported by SQL Access. See "Data type mapping" on page 36.
If the data type of the corresponding field in the PDM or CICS VSAM Foreign
Database is not one of the supported types, SQL Access may provide a default
conversion.
Foreign table attribute domains can be different from the default field data
type returned from the PDM or CICS VSAM Foreign Database. Coercions are
allowed for numeric types and the type TIMESTAMP. For additional information
on supported data types, refer to the SQL Access for SUPRA Server PDM SQL
Reference Guide, P25-9503.
Attributes can be optionally designated to have a DEFAULT value. If you
specify the DEFAULT syntax, you must also designate an initial value.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Creating foreign tables
32
Foreign table query specification
The foreign_table_query_specification is actually a SELECT command that
names the PDM or CICS VSAM field that corresponds to each attribute and the
FROM clause names the dataset_name[_rc]. For PDM, if external field names
are defined in the PDM Directory, they can be used in the SELECT command.
Otherwise, the names in the SELECT command either are the same as, or based
on, the 8-character PDM physical field names. For VSAM files, you will always
use the field name defined in the CID Adapter Extensions XML file. See the
examples that follow.
If external field names contain any characters other than alphanumeric
characters (A–Z, 0–9), underscores (_), percentage sign (%), or number sign (#),
they must be enclosed in double quotes (" ") in the SELECT command of the
foreign table. For example, the name MAXIMUM-VALUE would be interpreted
as MAXIMUM minus VALUE unless it is placed in double quotes “MAXIMUMVALUE”.
The elements of the SELECT command can also be an expression using the
external field name, PDM physical field name or VSAM field name. For
example, instead of just including the external field name price, the expression
price + 25 could be included in the SELECT list.
The query specification need not be specified when the foreign table is only
being used to define a superclass of one or more other foreign tables in the SQL
Access Server.
Each word of a multiple-word variable name must be connected by an
underscore.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Creating foreign tables
33
Examples:
This example creates a foreign table named ‘customer’ for PDM primary file
CUST. The foreign_database_name is ‘burrys’. The attribute names can be any
name. In the example below the first two are the same as the external field
names except that the dash(-) is replaced with the underscore (_). The third
attribute is different than the external field name, the next three are different
than the PDM field name and the last one is again the same as the external
field name. Either the exact external field name or PDM name must be used in
the SELECT command. The names that include a dash(-) must be enclosed in
quotes.
create foreign table customer on burrys
(
customer_no char(20),
customer_name char(20),
address char(30),
city char(20),
state char(2),
zip char(10),
original_loc char(20) )
as
select "CUSTOMER-NO", "CUSTOMER-NAME”, “CUST-ADDRESS”,
CUSTCITY, CUSTSTAT, CUSTZIPC, “ORIGINAL-LOC” from CUST;
The next example creates a foreign table named ‘order_detail_line’ for PDM
related file DETL record code LN. The foreign_database_name is burrys. The
foreign table includes fields from both the base portion and one record code.
A separate foreign table must be created for each record code you want to
access. Each foreign table for a record code will always contain the base
portion fields in addition to the fields for that record code.
The first three fields in the SELECT command below are from the base portion.
The remaining fields are from the LN record code. Note that the from clause
has the record code appended to the PDM file name. This is required to
enforce the coded record processing.
create foreign table order_detail_line on burrys
(
record_code char(2),
order_no char(4),
customer_no char(20),
product_code char(20),
quantity numeric(5),
cost numeric(9,2) )
as
select DETLCODE, "ORDER-NO”, “CUSTOMER-NO”, DETLPROD, QUANTITY,
COST from DETL_LN;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Creating foreign tables
34
Definition of domain information
SQL is a strongly data-typed language. Therefore, the CID Adapter Server must
contain domain information for those data fields that are to be made
accessible by SQL Access. This domain information can be obtained from the
PDM Directory, and it may also be defined, modified, and extended by using
the CID Adapter Extensions XML file. For VSAM files all the domain information
is defined in the CID Adapter Extensions XML file.
If you are an RDM user, the minimum set of PDM Directory domain fields is
probably already specified.
The following information for a field is utilized by SQL Access:
♦
Data format
♦
Field length
♦
Number of decimal places
♦
Signed option
♦
Linkpath type
♦
Nulls allowed option
♦
Null value
♦
Default value
Examine data formats carefully, especially for CHAR and BIT data. CHAR data is
translated to/from EBCDIC to/from ASCII. BIT data is not translated. In many
cases, the parent of sub-defined data fields should not be translated.
PDM does not support the BIT data type. The BIT data type is supported in the
CID Adapter Server by defining Type attributes in the CID Adapter Extensions
XML file.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Creating foreign tables
35
Data type mapping
To ensure no data loss, the following SQL Access specifications should be used
for each PDM type. CID Adapter Client and Server will automatically convert
data to and from the SQL Access specification. The following table shows the
PDM data types and the equivalent SQL Access domains:
SQL Access
specification
PDM specification
Type
Sign
Length
Binary
Signed
1
Binary
Signed
Binary
Signed
Binary
Decimals
Range
Domain
0
-128–127
SMALLINT
2
0
-32,768–32,767
SMALLINT
4
0
-2,147,483,648–
2,147,483,647
INTEGER
Signed
8
0
1.8 x 1019
NUMERIC(19,0)
Binary
Unsigned
1
0
0–255
SMALLINT
Binary
Unsigned
2
0
0–65,536
INTEGER
0–4,294,967,296
NUMERIC(10,0)
Binary
Unsigned
4
0
Binary
Unsigned
8
0
Float
Signed
4
FLOAT†
Float
Signed
8
DOUBLE††
Float
Signed
16
Not supported
Packed
decimal
Signed
1<len<16
p = 1–31
s = 0–31
Validate number of
digits left and right of
the decimal
NUMERIC(p,s)
Packed
decimal
Unsigned
1<len<16
p = 1–31
s = 0–31
Validate number of
digits left and right of
the decimal
NUMERIC(p,s)
Zoned decimal
Signed
1<len<18
p = 1–18
s = 0–18
Validate number of
digits left and right of
the decimal
NUMERIC(p,s)
Zoned decimal
Unsigned
†
††
NUMERIC(20,0)
1<len<18
s = 0–18
p = 1–18
Conversion from IBM to IEEE format may result in 1 bit of precision loss
Conversion from IBM to IEEE format may result in 4 bits of precision loss
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Creating foreign tables
NUMERIC(p,s)
36
SQL Access
specification
PDM specification
Type
Sign
Length
Decimals
Range
Domain
Character
n
0
n = 1–32,767 Converted
to/from EBCDIC
CHAR(n)†††
Bit
n
characters
0
n = 1–32,767
Bit data is not translated
BIT(n)††††
bits
Numeric
Unsigned
1<len<18
s = 0–18
0–
999,999,999,999,999,999
NUMERIC(p,s)
Numeric
overpunch
Signed
1<len<18
s = 0–18
-999,999,999,999,999,99
9–
999,999,999,999,999,999
NUMERIC(p,s)
Leading
separate
numeric
Unsigned
1<len<18
s = 0–18
0–
999,999,999,999,999,999
NUMERIC(p,s)
Leading
Signed
1<len<18
s = 0–17
-99,999,999,999,999,999 NUMERIC(p,s)
separate
–99,999,999,999,999,999
numeric
†††
CHAR data is translated automatically from/to EBCDIC (SAA code page 1057) to/from
Latin-1.
††††
BIT data is not translated.
PDM does not support any specific time or date format. There is no date or
time definition in the PDM metadata. If date or time information must be
supported by the SQL Access Server, you must write methods to translate your
date or time data to the SQL Access format.
PDM does not support the BIT data type. The BIT data type is supported by
SQL Access by defining Type attributes for Field elements in the Adapter
Extensions XML file.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Creating foreign tables
37
Data modeling considerations
The following considerations apply to modeling the SUPRA Server PDM data in
SQL Access:
♦
The RDM functions and facilities are not supported.
♦
For data defined as Type=”BIT”, all data will be returned as-is; for
Type=CHARACTER, the CID Adapter Server will provide automatic ASCII–
EBCDIC conversion using a table to drive translation. This table can be
replaced with a table customized to the user’s preference. All other data
types will be translated as necessary. See "Modifying the ASCII/EBCDIC
translation tables" on page 412 for more information on this table.
♦
Since the PDM supports only single phase commit, the DBA will need to be
aware of the issues single phase commit entails and the impact of these
issues before using SQL Access to update PDM data in a distributed
environment. For more information, see "Transaction recovery" on page 83
.
♦
SQL Access supports coded record processing. Nevertheless, record codes
cannot be modified via an update through SQL Access.
♦
When inserting into or updating a related file, the default action is to place
the record at the end of the chain. To place the record in a different
position, you will have to include the linkpath in the foreign table
definition.
♦
The CID Adapter Server will build the entire schema in memory upon
initialization, which precludes the use of Active Schema Maintenance. If
Active Schema Maintenance is performed while the CID Adapter Server is
active, the CID Adapter Server will have to be recycled.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Data modeling considerations
38
The following considerations apply to modeling the SUPRA Server PDM or CICS
VSAM data in SQL Access:
♦
When a SQL Access Client accesses a PDM or VSAM file through a foreign
table, all of the attribute definitions for that file are sent from the CID
Adapter Server to the CID Adapter Client and cached there in shared
memory. It is possible that a CID Adapter Client could have a large number
of attribute definitions cached, depending on the number of files accessed.
It may be necessary to recycle the CID Adapter Client when the CID
Adapter Server is recycled due to changes in the PDM Directory or the CID
Adapter Extensions XML file.
♦
PDM and VSAM alternate indices are optional but may improve
performance. The SQL Access optimizers will use all available information
provided in the WHERE clause to determine the best access path to the
PDM or VSAM data. The attributes specified in the WHERE clause may have
a dramatic affect on performance. For example, if the WHERE clause
contains attributes that map to a primary file control key or an index, a
direct access will be used to access the PDM or VSAM data. If the WHERE
clause contains attributes that do not map to any access methods defined
for the file (control key, index, linkpath, or foreign key), or there is no
WHERE clause, a scan of the entire PDM file will be used to access the PDM
data. If the WHERE clause contains VSAM attributes that do not map to any
access methods defined for the file (primary key, foreign key, or alternate
index), or there is no WHERE clause, a scan of the entire VSAM file will be
used to access the VSAM data.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Data modeling considerations
39
Using a script to register a CID Foreign Database
If you do not wish to use Visual SQL to register a Cincom Integrated Data (CID)
Foreign Database, you may use a script to allow a permanent record of the
parameters used to register the CID Foreign Database.
REGISTER CID DATABASE statement
Use the REGISTER CID DATABASE statement to register the Foreign Database
manually. This statement can only be performed by users who have been
granted the ALL privilege on the system classes ldb_catalog and ldb_properties.
By default, only the DBA (user dba) is granted this privilege.
This statement has the following syntax:
REGISTER CID DATABASE cid_alias_name
NAME
database_name
HOST
cid_adapter_client_host
[ MAX_ACTIVE unsignedInt ]
[ MIN_ACTIVE unsignedInt ]
CID_HOST
cid_adapter_server_host
CID_PORT
cid_adapter_server_port
where:
-
cid_alias_name is the name that you assign to the CID database that is
being registered. This name must be unique within the SQL Access
Server.
-
database_name is the DBM name in the CSIPARM file of the MVS
SUPRA Server PDM database or the DBMOD name for OpenVMS and UNIX
PDM platforms. This must be entered in UPPER CASE. This name is used
by the SQL Access Server to connect to the CID Foreign Database.
-
VSAM
-
cid_adapter_client_host is the name of the machine on which the CID
Adapter Client will be running. Typically this will be the same machine
on which the SQL Access Server is running.
-
MAX_ACTIVE unsignedInt sets the maximum number of active CID
Adapter Client processes allowed for the specified CID Foreign
Database. If a value is not specified for the MAX_ACTIVE setting, a
default value of 5 is used.
-
MIN_ACTIVE unsignedInt sets the minimum number of active CID
Adapter Client processes allowed for the specified CID Foreign
Database. If a value is not specified for the MIN_ACTIVE setting, a
default value of 0 is used.
PDM
database_name is ‘CICS’.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Using a script to register a CID Foreign Database
40
-
cid_adapter_server_host is the name of the machine on which the CID
Adapter Server is running.
-
cid_adapter_server_port is the TCP/IP port number on which the CID
Adapter Server is listening.
The parameters that are specified in the REGISTER CID DATABASE statement
must be entered as strings (enclosed in single quotes), and each string must be
less than 20 characters in length. All strings that you enter are case-sensitive.
Example
REGISTER CID DATABASE burrys
NAME 'EE72CPDM'
HOST ‘XP1234’
CID_HOST 'mvs'
CID_PORT '5530';
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Using a script to register a CID Foreign Database
41
Altering the registration of a CID Foreign Database
When one or more properties of a registered CID Foreign Database require
changing, the current registration can be altered with the new values.
For example, if the name of the CID Foreign Database changes at the host
machine, you can simply modify the NAME field of the current registration
rather than dropping and reregistering the CID Foreign Database.
We recommend that you use Visual SQL (refer to the SQL Access for SUPRA
Server PDM SQL Reference Guide, P25-9503) to edit the registration of a CID
Foreign Database. It will provide you with a dialog box that will display the
existing parameter values and allow you to change one or more of them.
Nevertheless, if you would like to create a script file or otherwise alter the
registration of a Foreign Database manually, you can use the REGISTER
FOREIGN DATABASE command.
Syntax
REGISTER FOREIGN DATABASE fdb_name ALTER
[ NAME
db_name_at_host ]
[ HOST
host_name ]
[ MAX_ACTIVE unsignedInt ]
[ MIN_ACTIVE unsignedInt ]
[CID_HOST
cid_adapter_server_host]
[CID_PORT
cid_adapter_server_port] [ ; ]
The registration of a CID Foreign Database cannot be altered if foreign tables of
that CID Foreign Database have already been accessed during the current SQL
Access session.
The ALTER keyword must be specified with the REGISTER FOREIGN DATABASE
command when you want to change a field of a current CID Foreign Database
registration. All fields are optional, but at least one new field must be
specified with this form of the statement. Fields not altered from the current
registration can be omitted.
Example
The following REGISTER FOREIGN DATABASE … ALTER statement changes two
fields in the current registration for the CID Foreign Database name rdb. Only
the fields that need to be altered are specified with the command:
register foreign database rdb alter
host
'edsel'
cid_port ‘1999’;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Altering the registration of a CID Foreign Database
42
Altering a foreign table
When changes are made to PDM or VSAM files in the CID Foreign Database,
foreign tables may require changing as well. Since a foreign table is a direct
representation of a CID Foreign Database entity, you may need to alter the
attribute list and/or query specification in the corresponding foreign table
definition when the CID Foreign Database is modified.
In most cases, the DBA is the creator and hence the owner of the foreign tables
in the SQL Access Server. Before you can alter the definition of an entity in the
SQL Access Server, you must be the owner or have ALTER authorization granted
to you by the owner (or DBA).
Syntax
ALTER [ FOREIGN TABLE ] foreign_table_name
{ ADD add_list
| CHANGE change_list
| DROP drop_list
| RENAME rename_list } [ ; ]
The name of the foreign table that you want to modify is denoted by the
parameter foreign_table_name. The keyword FOREIGN TABLE can optionally
be specified when you alter foreign table. You can modify the foreign table
definition with the ADD, CHANGE, DROP and RENAME clauses of the ALTER
statement. The various forms of these clauses follow:
add_list:
[ ATTRIBUTE ] foreign_table_attr_definition [ {,
foreign_table_attr_definition }… ]
QUERY query_specification
SUPERCLASS super_foreign_table_name [ {, super_foreign_table_name
}… ]
change_list:
attribute_name DEFAULT value_specification [ {, attribute_name
DEFAULT value_specification }… ]
QUERY [ integer ] query_specification
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Altering a foreign table
43
drop_list:
[ ATTRIBUTE ] attribute_name [ {, attribute_name }… ]
QUERY [ integer [ {, integer }… ] ]
SUPERCLASS super_foreign_table_name [ {, super_foreign_table_name
}… ]
rename_list:
[ ATTRIBUTE] attribute_name [ {, attribute_name }… ]
Each ALTER statement that you enter is restricted to one type of modification.
For example, you cannot drop an attribute and then change the query
specification within the same ALTER statement. See the corresponding section
below for details for each ALTER option.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Altering a foreign table
44
Adding an attribute
One or more new attributes can be added to the definition of a foreign table
with the ALTER … ADD ATTRIBUTE statement. New attribute definitions are
appended to the end of the current attribute definition list. Any time a new
attribute is added, the corresponding query specification(s) may also need to
be altered to include the new attribute as a SELECT field.
Syntax
ALTER [ FOREIGN TABLE ] foreign_table_name
ADD [ ATTRIBUTE ] foreign_table_attr_definition [ {,
foreign_table_attr_definition }… ] [ ; ]
where:
-
foreign_table_name is the name of the foreign table where you want
to define a new attribute.
To add an attribute, supply the ATTRIBUTE optional keyword before the
attribute definition. Adding a new attribute may cause the definition of the
foreign table to become inconsistent with the query specification. Queries and
updates on that entity fail when the entity definition is inconsistent with the
query specification. To prevent these failures, you must issue a separate
ALTER command with the appropriate CHANGE QUERY clause.
Example
This example modifies the foreign table called shipment to reflect a change in
the CID Foreign Database. Assume that the file DETL_LN in the PDM database
was given a new field called payment_plan. To access this data, the
corresponding foreign table order_detail_line must be modified with the
addition of a new attribute. The query specification also needs to be changed
to retrieve the additional attribute from the CID Foreign Database and to keep
the definition of the foreign table consistent:
alter foreign table order_detail_line
add attribute payment_plan char(15);
alter foreign table order_detail_line
change query select DETLCODE, "ORDER-NO”, “CUSTOMER-NO”,
DETLPROD, QUANTITY, COST, “PAYMENT-PLAN” from DETL_LN;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Altering a foreign table
45
Adding a new query specification
A new query can be added to a foreign table if a query specification is not
currently defined.
Syntax
ALTER [ FOREIGN TABLE ] foreign_table_name
ADD QUERY query_specification [ ; ]
where:
-
foreign_table_name is the name of the foreign table where the new
query specification is added.
-
query_specification syntax is the same under the ALTER statement as
was previously described of the foreign table where you want to define
a new attribute for the CREATE statement in "Creating foreign tables"
on page 30. Only one query can be added with each ALTER … ADD
QUERY statement.
Example
In this example, suppose that you previously have dropped the query
specification or created the foreign table without the query specification. It
can now be added to the foreign table as follows:
alter foreign table order_detail_line
add query select DETLCODE, "ORDER-NO”, “CUSTOMER-NO”, DETLPROD,
QUANTITY, COST, “PAYMENT-PLAN” from DETL_LN;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Altering a foreign table
46
Changing an attribute definition
Only the default value in an attribute definition can be changed with the
CHANGE clause. In order to change the domain of an attribute, you must drop
the attribute and add it with the new domain. The RENAME clause is used to
change the name of an attribute. The initial value associated with an attribute
can be changed with the ALTER statement. To change the default value you
need to reference the attribute name and designate the new value in the
CHANGE clause.
Syntax
ALTER [ FOREIGN TABLE ] foreign_table_name
CHANGE attribute_name DEFAULT value_specification
attribute_name DEFAULT value_specification }… ]
[ {,
[ ; ]
where:
-
attribute_name indicates the name of the attribute for which you want
to supply a new DEFAULT value. No specified limit exists to the
number of attributes you can change in the same ALTER statement.
Example
alter foreign table customer
change attribute original_loc default ‘Cincinnati’;
The default value will apply to every new instance inserted into the foreign
table unless a different value for the attribute is given when the instance is
inserted.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Altering a foreign table
47
Changing the query specification
Changes to the attribute definition list of the foreign table may require a
corresponding change to the query specification in that entity. Whenever an
attribute is added or dropped in a foreign table, the query specification(s) must
also be modified to keep the definition consistent.
Any of the query specification(s) defined in a foreign table can be altered with
the CHANGE QUERY clause. Query specifications are assigned integer values
that correspond to the position they occupy in the query specification list.
Because a foreign table can only have one query specification, it is always
identified with the integer 1.
Syntax
ALTER [ FOREIGN TABLE ] foreign_table_name
CHANGE QUERY [ integer ] query_specification [ ; ]
where:
-
integer is optional in the ALTER…CHANGE QUERY command. Since a
foreign table can contain at most one query specification, you can give
a new query specification after the CHANGE QUERY keywords, or you
can supply a value of 1 for integer.
-
query_specification can be any single SELECT statement that follows
the syntax requirements described for creating a foreign table (see
"Creating foreign tables" on page 30). The select list in the new query
must match the attribute definition list in both length and type. This
requires compatible data types and a one-to-one correspondence
between the SELECT fields and the attributes defined in the foreign
table.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Altering a foreign table
48
Example
The following example changes the query specification in the foreign table
shipment. The new query specifies NA instead of selecting the field CUSTSTAT
from the CID Foreign Database file customer. The data for the attribute state
will display as NULL.
alter foreign table customer
change query select "CUSTOMER-NO", "CUSTOMER-NAME”, “CUST-ADDRESS”,
CUSTCITY, NA, CUSTZIPC, “ORIGINAL-LOC” from CUST;
Queries changed with the ALTER … CHANGE QUERY statement are checked for
consistency against the current attribute definition list of the entity you are
altering.
If you want to remove a field in a query specification of a foreign table, the
corresponding attribute must already be dropped from the foreign table
definition.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Altering a foreign table
49
Dropping an attribute
An attribute can be dropped from the attribute definition list of a foreign table
if you no longer need to access the data associated with that attribute. In
addition, if you need to change the domain of an existing attribute, you must
first drop the attribute and then add it back with the ALTER … ADD ATTRIBUTE
statement. (Note that when you add the attribute, it will be appended to the
end of the attribute list.)
Fields that have been dropped from a file in a CID Foreign Database should also
be dropped from the attribute definition list and query specification list of the
appropriate foreign table. If the query specification selects an attribute that
does not exist in the CID Foreign Database, an error is returned.
Syntax
ALTER [ FOREIGN TABLE ] foreign_table_name
DROP [ ATTRIBUTE ] foreign_table_attr_name
[ {, foreign_table_attr_name }… ] [ ; ]
where:
-
foreign_table_name is the name of the foreign table from which you
want to drop an attribute.
-
foreign_table_attr_name is the name of one or more attributes from
the attribute definition list that you want to drop.
Dropping an attribute causes the definition of the foreign table to become
inconsistent with the query specification. Queries and updates on that foreign
table will fail when the definition is inconsistent with the query specification.
To prevent these failures, you must issue a separate ALTER statement with the
appropriate CHANGE QUERY clause.
Example
This example modifies the foreign table called order_detail_line by removing
the attribute payment_plan (which was added in a previous example). The
query specification is also changed in a separate ALTER statement to maintain
consistency between the attribute definition list and the fields selected by the
query:
alter foreign table order_detail_line
drop payment_plan;
alter foreign table order_detail_line
change query select DETLCODE, "ORDER-NO”, “CUSTOMER-NO”,
DETLPROD, QUANTITY, COST from DETL_LN;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Altering a foreign table
50
Dropping a query specification
Since a foreign table can have at most one query specification, dropping the
only query means that no data can be selected from the corresponding CID
Foreign Database entity. In this case, the foreign table can be specified as a
superclass to another foreign table in the SQL Access Server, so that its
attribute definition list can be inherited by that other foreign table.
Syntax
ALTER [ FOREIGN TABLE ] foreign_table_name
DROP QUERY [ integer] [ ; ]
where:
-
foreign_table_name is the name of the foreign table from which the
query specification is dropped.
-
integer is an optional specification and represents the position of the
query in the foreign table definition. A default value of 1 is implied
when integer is omitted.
Example
The query specification is dropped from foreign table shipment in the this
example. This removes the query that selects information from the file ship in
the CID Foreign Database.
alter foreign table shipment
drop query;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Altering a foreign table
51
Renaming an attribute
Attributes can be renamed in the definition of a foreign table. When you
change the name of an attribute in a foreign table, you do not have to modify
the query specification for that entity.
Syntax
ALTER [ FOREIGN TABLE ] foreign_table_name
RENAME [ ATTRIBUTE ] old_attr_name AS new_attr_name
[ ; ]
where:
-
foreign_table_name is the name of the foreign table that contains the
attribute to be renamed.
-
old_attr_name must be the name of an existing attribute in the foreign
table that you are altering. Designating the keyword ATTRIBUTE with
this command is optional.
Example
The following ALTER command renames the attribute price to cost in the
foreign table inventory:
alter foreign table order_detail_line
rename attribute cost as price;
The query specification in order_detail_line does not need to be changed to
reflect the new attribute name.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Altering a foreign table
52
Deleting/Dropping CID Foreign Database entities
Cincom recommends that you use Visual SQL to delete CID Foreign Database
entities. Refer to the SQL Access for SUPRA Server PDM SQL Reference Guide,
P25-9503, for details on Visual SQL. A CID Foreign Database cannot be removed
until all foreign tables have been removed from that CID Foreign Database.
If you are using a script, a CID Foreign Database registration and a foreign table
definition can be removed with the DROP statement.
If the foreign table you are dropping is included in the query specification of a
virtual class/view, that portion of the query specification should also be
removed. When a query specification references an entity that no longer
exists, a runtime error occurs.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Deleting/Dropping CID Foreign Database entities
53
Dropping the registration of a CID Foreign Database
The DROP FOREIGN DATABASE statement is used in a script to remove the
registration of a CID Foreign Database. When you no longer need access to a
CID Foreign Database for your application, you can drop its registration from
the SQL Access Server. This statement can only be performed by users with the
delete privilege for the system class ldb_catalog. By default, only the DBA
(user dba) has this privilege.
Syntax
DROP FOREIGN DATABASE fdb_name [ ; ]
The fdb_name is the name that was assigned to the CID Foreign Database when
it was registered in the SQL Access Server. Only one CID Foreign Database can
be dropped with the same statement.
When the registration of a CID Foreign Database is removed, any foreign tables
that reference the CID Foreign Database must have already been dropped;
otherwise an error is returned and the DROP FOREIGN DATABASE statement
fails.
The registration for a CID Foreign Database cannot be dropped if foreign tables
on that CID Foreign Database have already been accessed during the current
session. This includes both (1) queries or updates on the associated foreign
tables, and (2) queries or updates on virtual classes/views that access those
foreign tables.
In the next example, foreign tables inventory, shipment, and employee need to
be dropped before the registration of CID Foreign Database rdb can be
successfully dropped. For a detailed description of dropping foreign tables, see
"Dropping foreign tables", which follows.
Example
drop inventory, shipment, employee;
drop foreign database rdb;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Deleting/Dropping CID Foreign Database entities
54
Dropping foreign tables
If access to the CID Foreign Database file/table is no longer needed, the
foreign table definition can be removed with the DROP statement.
Foreign tables can be part of an inheritance hierarchy; therefore, specific
subclasses can also be removed as part of the same DROP statement. The
following shows the valid syntax for dropping a foreign table definition.
Syntax
DROP [ FOREIGN TABLE ] foreign_table_clause [ {,
foreign_table_clause }… ] [ ; ]
foreign_table_clause:
foreign_table_name
all_except_foreign_table_clause
all_except_foreign_table_clause:
ALL foreign_table_name [ EXCEPT except_foreign_table_clause ]
except_foreign_table_clause:
foreign_table_name
all_except_foreign_table_clause
where:
-
foreign_table_name is the name that was specified for the foreign
table when the entity was first created. When the ALL keyword is
given before the foreign_table_name, every subclass of that foreign
table is also dropped. If specific subclasses exist in the hierarchy that
you do not want to remove, you can include the EXCEPT clause in the
DROP ALL syntax.
When you drop a foreign table make sure that any query specifications
referencing the dropped foreign table are also removed from any view/virtual
class.
Examples
Both of the following statements will drop the foreign table named inventory:
drop foreign table inventory;
drop inventory;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Deleting/Dropping CID Foreign Database entities
55
Joining foreign tables
Joining multiple foreign tables allows you to select and combine data from
these foreign tables. You specify which foreign tables you wish to view in the
FROM clause. You use the WHERE clause to indicate how you want the data
joined for display in each instance. For example:
select * from inventory, shipment
where inv_product_no = ship_product_no
This will display attributes from both inventory and shipment foreign tables
when there is a match on the product number in each foreign table. This is
known as an inner join. If product number 1234 exists in the inventory foreign
table but does not exist in the shipment foreign table then product number
1234 will not be displayed.
If you wish to display product number 1234 even if there is no matching record
in the shipment foreign table, this is called an outer join. In order to
accomplish an outer join, you will need to create a CID Adapter View and
select from the foreign table created from the CID Adapter View. For more
information on CID Adapter Views, see "View" on page 393.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Joining foreign tables
56
Creating a view
A view (also called a virtual class) is essentially a different “view” of one or
more foreign tables. Since you can only define one foreign table for a PDM or
VSAM file, it is important to include all the PDM or VSAM fields into that foreign
table. This may be cumbersome to work with if there are a large number of
fields, so a view allows you to select only the fields you want to see. A view
can also be used to join two or more foreign tables and select only the fields
from these tables that you wish to see. You can create multiple views for a
foreign table.
A view is available to the SQL Access Client application. It appears no different
than a foreign table and has the same capabilities of a foreign table.
The format of a view is very similar to a foreign table. A view consists of:
♦
One attribute and associated domain for each attribute selected from the
foreign table
♦
A query specification, which indicates the attribute name and foreign table
name
We recommend that you use Visual SQL (refer to the SQL Access for SUPRA
Server PDM SQL Reference Guide, P25-9503) to create the view in a script
window. You can also use SQL/X to create a view.
Syntax
CREATE VIEW view_name
( view_attr_definition [ {, view_attr_definition }… ] )
AS view_query_specification
[ ; ]
where:
-
view_name is the unique name for the view. The view cannot be
created using a name that already exists in the SQL Access Server as
another foreign table, view/virtual class, class/table, or registered CID
Foreign Database. The name cannot contain spaces, and it cannot be a
SQL Access reserved word. Alphanumeric characters, underscores (_),
the number sign (#), and the percentage sign (%) are allowed in the
view name. The name identifier must begin with a letter, and the
maximum number of characters for a name is 255.
For a list of reserved keywords, refer to the SQL Access for SUPRA
Server PDM SQL Reference Guide, P25-9503.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Creating a view
57
-
view_attr_definition has the following syntax:
attribute_name
data_type
[ DEFAULT value ]
The attributes you define in a view are enclosed in parentheses and
must be given a name and a domain. The attribute_name you assign
should follow the same character-use conventions that were described
for view_name.
The data_type given as the domain of an attribute can be any valid
built-in data type that is supported by SQL Access.
View attribute domains are rarely different from the foreign table
attribute data type. However coercions may be allowed for numeric
types and the types DATE and TIMESTAMP. For additional information
on supported data types, refer to the SQL Access for SUPRA Server PDM
SQL Reference Guide, P25-9503.
If the attribute names and data types you will use in the view exactly
match the foreign table names and data types, it is not necessary to
specify them in the view definition.
Attributes can be optionally designated to have a DEFAULT value. If
you specify the DEFAULT syntax, you must also designate an initial
value.
-
view_query_specification is actually a SELECT command that names
the foreign table attribute that corresponds to each attribute in the
view.
The elements of the SELECT command can also be an expression using
the foreign table attribute name. For example, instead of just
including the attribute name price, the expression price + 25 could be
included in the SELECT list.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Creating a view
58
Example 1
This example creates a view named ‘address_label’ for foreign table address.
The attribute names in the view can be the same as the matching attribute
names in the foreign table, but the names can also be different. In the
example below, the physical file named ADDR and the address foreign table on
it contain 42 attributes/fields. Rather than sort through those attributes each
time you want to display the address label information for a customer, you can
create a view as follows:
create view address_label
(
line1 char(30),
line2 char(30),
liine3 char(30),
attn_name char(30),
customer_no char(20)
)
as
select addradl1, addradl2, addradl3, addratln, addrcust from
address;
This view can be used to select the label information for a customer based on
the customer number:
select line1, line2, line3, attn_name from address_label where
customer_no = ‘OH12345678’
Example 2
This example creates a view named ‘customer_address’, which joins foreign
tables address and customer. The view will show the address for a customer
and also includes customer name and sales region for the customer.
create view customer_address
(
customer_name char(30),
customer_no char(20),
customer_region char(10),
line1 char(30),
line2 char(30),
line3 char(30),
attn_name char(30)
)
as
select custname, custctrl, custregn, addradl1, addradl2,
addradl3, addratln from customer, address where addrcust =
custctrl;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Creating a view
59
Security and Authorization
The DBA and/or users authorized by the DBA control access to the SQL Access
Server, CID Foreign Database and foreign table information. A SQL Access
Server is created with a PUBLIC group and a DBA user. All users are members
of the PUBLIC group. The DBA must define all other users. This chapter
discusses various mechanisms available to define users and groups, as well as to
restrict and assign user access to a SQL Access Server. These include:
♦
Defining users at creation time
♦
Adding users
♦
Adding users with authorization methods
♦
Removing users
♦
Adding and removing groups and assigning or removing users to/from
groups
♦
Granting and revoking privileges
♦
Restricting class access with virtual methods
♦
Locking activity
Privileges to read, insert, update, and delete instances as well as to modify the
SQL Access Server and grant privileges to other users, are maintained on a
foreign table basis. Partial foreign table access can be achieved using virtual
classes.
Users and groups cannot be added, deleted, or changed if the SQL Access
Server is started in read-only mode (-r option).
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Security and Authorization
60
Access privileges
The basic unit of authorization is the foreign table. Each user is represented
by an instance of the db_user class. This db_user instance maintains the user’s
privileges for each foreign table for which he/she has access. Authorization for
the foreign table is accomplished using the GRANT statement.
Only the DBA or the owner can grant privileges for any given foreign table.
Authorization for a foreign table can be granted to either a single user or a list
of users, which are referred to as a group.
When authorization is granted for a group, all members of the group receive
the same authorization privileges. Every new user is a member of the PUBLIC
group.
SQL Access Server provides the following access privileges:
♦
SELECT
♦
INSERT
♦
UPDATE
♦
DELETE
♦
ALTER
♦
INDEX
♦
EXECUTE
♦
ALL PRIVILEGES
♦
GRANT OPTION
A user must have grant authorization (the owner of a foreign table
automatically has grant authorization) for an operation before he/she can
authorize other users for that operation on that foreign table.
DROP authorization is handled by setting ALTER privileges.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Access privileges
61
Authorizing access to a foreign table
Authorization for user access to a foreign table is primarily the responsibility of
the DBA. However, when you create a foreign table, you become its owner,
which entitles you to grant specific authorizations on that foreign table.
Access to the foreign table can be restricted according to the user and by the
type of statement that the user can issue against the foreign table.
Users
Each user is identified by a unique user name. The DBA can set up the names
of authorized users by invoking the appropriate methods on the built-in
authorization objects. User names can also be set up using the createdb utility
program that is supplied to your DBA. (See "createdb" on page 251 for details.)
Any user can have an associated list of members who also receive access
privileges. When authorization is granted to a user, it automatically applies to
all members associated with the user. Consequently, a user and the list of
related members (other users) are commonly referred to as a group. A user
without any members is referred to as a user.
SQL Access Server has two types of built-in users. The first type of built-in user
is referred to as PUBLIC, meaning that all other users are automatically
designated as members. If authorization on a foreign table is given to PUBLIC,
then all users are granted access to the particular foreign table. Granting
authorization to user PUBLIC is a convenient way to make foreign tables
broadly visible.
The second type of built-in user is DBA, which is reserved for the DBA. The DBA
is automatically a member of all users or groups. Hence, authorization for the
DBA user or a member of the DBA group does not need to be explicitly granted.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Authorizing access to a foreign table
62
Granting authorization/privileges to users
The basic unit of authorization in the SQL Access Server is the foreign table.
When you create a foreign table or a virtual class in the SQL Access Server,
your user name is assigned as the owner of the foreign table. Before another
user can access this foreign table, you must first grant the specific privilege(s)
to relevant users or groups.
Authorization for a foreign table or a virtual class can be granted to a single
user or a list of users, either of which can have members (compose a group).
When authorization is granted for a GROUP, all members in the group receive
the same privileges. It is not necessary to explicitly grant authorization to
every member in the group. When PUBLIC is given as a user name, all users of
the SQL Access Server have access to the foreign table or virtual class.
Authorization for a foreign table or virtual class is accomplished with the
GRANT statement.
Syntax
GRANT operation [ {, operation }… ] ON foreign_table_name
[ {, foreign_table_name }… ]
TO user [ {, user }… ] [ WITH GRANT OPTION ] [ ; ]
Each parameter that you supply in the syntax can be a single value or a list of
values. The value you specify for operation determines what actions on a
foreign table or virtual class that other users can perform. (The owner of the
foreign table or virtual class always has full access privileges. It is not
necessary to grant privileges to the foreign table or virtual class owner.) The
valid keywords and the type of authorization they allow are listed in the table
on the next page.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Authorizing access to a foreign table
63
Operation
Privilege authorized
SELECT
Permits the user to read the foreign table definition and
query the foreign table instances. This is the most
common type of authorization.
INSERT
Authorizes the creation of new instances of the foreign
table.
UPDATE
Allows the modification of existing instances of the
foreign table.
DELETE
Authorizes the removal of instances of the foreign table.
ALTER
Permits modification of the foreign table definition,
renaming a foreign table, or removal of the foreign table
from the SQL Access Server.
INDEX
Allows the user to assign indexes on foreign table
attributes for enhanced performance on query processing.
EXECUTE
Permits the user to invoke methods on the foreign table
or instances of the foreign table.
ALL PRIVILEGES
Specifies full authorization on the foreign table. All the
preceding authorization types will be in effect.
You can specify the authorization names and types for one or more foreign
tables or virtual classes by listing each relevant name. You must either be the
owner of every foreign table on which you grant authorization, or be given a
GRANT OPTION (see "Including the WITH GRANT OPTION specification" on
page 65) before you can authorize other users for a foreign table.
The user value determines which users or groups have been given authorization
for the foreign table. You can specify a user’s login name or the systemdefined user name PUBLIC. When PUBLIC is specified, every user of the SQL
Access Server can access the foreign table. The DBA (DBA) or any member of
the DBA group is automatically granted all authorization privileges for every
operation on every foreign table.
To perform SELECT, UPDATE, DELETE, and INSERT operations on a virtual class,
the owner of the virtual class must have SELECT and any corresponding
authorization on every foreign table in the query specification of the virtual
class. In addition, the virtual class must be updateable.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Authorizing access to a foreign table
64
Example 1
This GRANT statement allows user Davis (and any members associated with this
user) to issue queries on foreign table location:
grant select on location to Davis;
Example 2
This GRANT statement allows the users or groups of Davis and Brown to read,
add, modify, and delete the instances in two foreign tables, hotel and motel:
grant select, insert, update, delete on hotel, motel to Brown,
Davis;
Including the WITH GRANT OPTION specification
The same authorization privileges that you grant to a user can be passed on to
another user when you specify the WITH GRANT OPTION in your GRANT
statement. For example, if you grant SELECT authorization to a user or group,
you can also authorize that user or any member of the group to grant the same
privilege to another user or group of the SQL Access Server.
Example
This GRANT statement authorizes user Brown to read data from foreign tables
resort and hotel, and permits Brown to authorize the same SELECT privilege to
other users, although Brown is not the owner:
grant select on hotel, resort to Brown with grant option;
Now user Brown can issue a GRANT statement to other users of the SQL Access
Server (such as Jones in the following example). Brown can only grant the
same privilege that he is authorized to use, but he can grant it on either
foreign table resort or foreign table hotel:
grant select on resort to Jones;
User Brown can also pass authorization privileges to user Jones if he specifies
the WITH GRANT OPTION. Any time a GRANT authorization is passed to another
user, that user can further pass on privileges that he/she was given.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Authorizing access to a foreign table
65
Revoking authorization/privileges
Privileges that you grant to a user can be revoked at any time. If you had
originally authorized several privileges to a user, you have the option of
removing one, more than one, or all of the authorization types. You can also
selectively revoke users or foreign tables from your original GRANT statement.
When you revoke a privilege from a user to whom you had given authorization
(WITH GRANT OPTION), the privileges you revoke will also affect those users
who were granted authorization from the user(s) you authorized. In other
words, if you remove the authorization for user Brown to UPDATE a foreign
table, any user that Brown authorized to modify instances of that foreign table
is also denied the UPDATE privilege. In addition, you can also remove
authorization on any users that Brown authorized to update that foreign table
or modify instances of that foreign table. Removing authorization on a foreign
table is done using the REVOKE statement.
Syntax
REVOKE operation [ {, operation }… ] ON foreign_table_name
[ {, foreign_table_name }… ]
FROM user [ {, user }… ] [ ; ]
Each parameter you supply in the syntax can be a single value or a list of
values. If you want to remove every authorization type, use the ALL
PRIVILEGES specification rather than a listing of each type that you had
previously specified in the GRANT statement.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Revoking authorization/privileges
66
Examples
One of the previous examples granted four authorization types on two foreign
tables to two users:
grant select, insert, update, delete on hotel, motel to Brown,
Davis;
Suppose that you now want user Davis to have only read privileges on both
foreign tables, leaving Brown as the only user authorized to add, edit, or
delete data from these foreign tables. The following REVOKE statement
changes your original authorization for these foreign tables:
revoke insert, update, delete on hotel, motel from Davis;
The original authorization for Brown remains intact, but user Davis can now
only query the foreign table hotel and the foreign table motel. If Davis had
been given authorization to grant privileges to other users, those other users
could now only query the foreign tables to which Davis had granted them
access as well.
If you decide to remove all authorization privileges for user Davis, you can
issue the following statement. Davis is then denied any type of access to
foreign table hotel and foreign table motel:
revoke all privileges on hotel, motel from Davis;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Revoking authorization/privileges
67
User overview
The DBA user and the PUBLIC group are built into the SQL Access Server. DBA
is a member of all groups and has access to every object in the SQL Access
Server. The DBA must define all other users. All users, including DBA, are
members of the PUBLIC group.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: User overview
68
Adding users
When a user is added to the SQL Access Server, the system creates an instance
of the class db_user. Instances of the db_user class have the following
properties:
Property
Data type or class
Description
id
integer
Object number ID for the user
password
db_password
The user’s SQL Access Server password
authorization db_authorization
Privileges granted to the user
name
string
A string representing the user
groups
set (db_user)
Groups to which the user belongs
members
set (db_user)
Users that belong to this group (where
the db_user is a group)
add_user method
The add_user() method adds a user during the life of a SQL Access Server. This
is a db_user class method. It takes two arguments: name and password, both
of which are passed to the method as strings. The system requires the name
argument, and it must be unique. If no password is required for the specified
user, then the system uses the empty string ('') as the second parameter. The
system automatically adds the new user to the PUBLIC group. The following
example adds the user ‘alvaro’ having the password ‘wizard’ to the db_user
class for the currently active SQL Access Server:
CALL add_user('alvaro','wizard') ON CLASS db_user;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Adding users
69
Groups and members
As with users, you can add groups by using the add_user method call or when
you are creating the SQL Access Server by using the user definition file. To
make common access privileges easier to maintain, the DBA can set up groups.
To do this, the DBA must do the following:
1. Add a user with a descriptive group name.
2. Add each associated user as a member to the new user (group) using the
add_member() method.
All users in the SQL Access Server are members of the PUBLIC group.
Any user can become a group by adding members to it. Use interpreter
variables to hold the return identities for inclusion in the add_member()
method. The following example adds the group ‘admin’ having the password
‘password’ and the user ‘smith’ having the password '’’' to the db_user class for
the currently active SQL Access Server. It then adds user ‘smith’ to the group
‘admin’ using the interpreter variable ':admin':
CALL add_user('admin','password') ON CLASS db_user to :admin;
CALL add_user('smith','') ON CLASS db_user;
CALL add_member('smith') ON :admin;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Adding users
70
User definition file
Often, the DBA knows the names of the initial users of the SQL Access Server
before its creation. In such cases, the createdb utility accesses the file
containing the user information so that corresponding user objects are created
automatically in the SQL Access Server. It is not necessary to use this file to
define users in the SQL Access Server, but the format of the file is somewhat
more straightforward and easier to read than the corresponding SQL Access
Server statements that define users. The user definition file consists of one or
more lines of USER statements.
Syntax
USER user_name [ groups_clause | members_clause ]
groups_clause:
[ GROUPS user_name [ { user_name } … ]
members_clause:
[ MEMBERS group_name [ { group_name… } ] ]
For each USER statement in your file, the user_name is the name of the
authorized user. You can use alphanumeric characters in the name, but it must
not contain embedded blanks.
The GROUPS clause is optional and allows the specification of one or more
groups of which the user is a member. The group_name specification is no
different from the user_name; the name supplied as group_name is used as a
convention to identify a user that has one or more members. You must define
each group_name that is specified in the MEMBERS clause in another USER
statement elsewhere in the file.
Comments are allowed in the user definition file; each comment line must
begin with a hyphen (-). The system ignores blank lines in the file. Do not
continue a USER statement onto the next line. Instead, you can define several
statements for the same user (see the following example, Example user
definition file 2).
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Adding users
71
Examples
This example shows that user smith is a member of two groups and the other
users (brown and jones) are each a member of one group. All users are
indirectly members of group company:
--- Example user definition file
-USER company
USER engineering
GROUPS
USER marketing
GROUPS
USER administration
GROUPS
USER smith
GROUPS
USER brown
GROUPS
USER jones
GROUPS
1
company
company
company
administration marketing
engineering
marketing
This example demonstrates the cumulative effect of USER statements that
define the same user name. In this case, user brown is added as a member of
three groups. Because each USER statement must fit onto a single line, using
multiple USER statements can make the file more readable if a user is a
member of many groups:
--- Example user definition file
-USER engineering
USER marketing
USER administration
USER brown
GROUPS
USER brown
GROUPS
USER brown
GROUPS
2
engineering
administration
marketing
The next example illustrates another way of defining groups. In this case, the
members of the groups are defined with the MEMBERS keyword, rather than the
group names being spread out among the individual users:
--- Example user definition file 3
-USER brown
USER smith
USER jones
USER engineering
MEMBERS brown
USER marketing
MEMBERS smith jones
USER administration
MEMBERS smith
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Adding users
72
Deleting users
You can delete users and group members by using the drop_user () and
drop_member() methods.
Dropping a user
The DBA owns the db_user class. Only the DBA user of the DBA group can call
the drop_user() method of the db_user class. The drop_user method takes the
user name as its only argument. After a user is dropped, the system transfers
the ownership of any foreign tables previously owned. The following example
drops user james from the currently active SQL Access Server:
CALL drop_user('james') ON CLASS db_user;
The system predefines PUBLIC and DBA users as system users. Attempts to
drop either the PUBLIC or DBA user will result in an error.
Dropping a member
The drop_member() db_user instance method removes a member from the
group. You must be logged into the SQL Access Server as DBA, a member of the
DBA group, or as the group from which the member is to be removed. The
following example removes james from the users group:
CALL find_user('users') ON CLASS db_user TO :users;
CALL drop_member('james') ON :users;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Deleting users
73
Renaming the DBA and PUBLIC users
After a SQL Access Server is created, the DBA should revoke privileges on the
db_user class from the PUBLIC user. The following SQL/X command prevents
PUBLIC users from querying the db_user class to determine user names:
revoke all on db_user from public;
Renaming the DBA
The following SQL/X command changes the name of the DBA to newprivname.
Only the DBA can execute this command:
rename privileged user newprivname;
Renaming the PUBLIC user
The following SQL/X command changes the name of the PUBLIC user to
newdefname. Only the DBA can execute this command:
rename default user newdefname;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Renaming the DBA and PUBLIC users
74
Authorization classes in the SQL Access Server
Some system-defined classes are created in association with the users who are
initially authorized to access the system. Two of these classes can be accessed
by the DBA or a member of the DBA group, and other authorized users of the
SQL Access Server:
♦
db_user class
♦
db_authorizations class
The class db_user contains the login names, passwords (if any), and other
information about the SQL Access Server’s users. The db_authorizations class
contains a set of all the users in the SQL Access Server and the privileges they
have been granted.
db_user class
Several attributes are defined in the db_user class that contain information
about a particular user of the SQL Access Server. These attributes can be
updated or displayed by calling one or more of the authorization methods that
are built into the system.
db_user attributes
Attribute type
Definition
id
integer
Contains the object number ID for the user.
where:
0 = privileged user
1 = default user
NULL = all other users
password
db_password
References the user’s password from the
db_password class, which cannot be seen by
users of the SQL Access Server.
authorization
db_authorization
References the privileges granted to a user (as
contained in the db_authorizations class).
name
string
Contains the login ID of the user.
groups
set (db_user)
Contains the set of groups to which the user
belongs.
direct_groups
set (db_user)
Contains the set of users that compose the
group.
triggers
sequence (object)
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Authorization classes in the SQL Access Server
75
Four class methods are defined for the db_user class. These include the class
methods:
♦
login
♦
add_user
♦
drop_user
♦
find_user
Four methods that operate on the instances of the class db_user include:
♦
add_member
♦
drop_member
♦
set_password
♦
print_authorizations methods
See "Authorization methods" on page 78 for more information.
db_authorizations class
One attribute is defined for the db_authorizations class. The attribute name is
users, and its domain is defined as a set of users (instances) from the db_user
class described previously. One class method, print_authorizations, can be
called to operate on this class.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Authorization classes in the SQL Access Server
76
Calling authorization methods
Updates to the db_user class and descriptions from both the db_user class and
the db_authorizations class are managed by calling predefined methods. Some
of these methods can only be called by the DBA or a member of the DBA group.
The general syntax for calling an authorization method is shown next.
Syntax
CALL method_definition ON CLASS auth_class [ TO variable ]
[ ; ]
CALL method_definition ON variable [ ; ]
The first form of the CALL statement shows that you can call a method on one
of the authorization classes and optionally store the return value of the CALL
statement to a variable. This variable can then be referenced in subsequent
CALL statements, as shown in the second form of this syntax.
Here, method_definition is one of the predefined authorization methods (see
Authorization methods, which follows). Depending on the method that you
call, specific strings (enclosed in quotes) are used as input values for the
method’s arguments. The arguments vary with the method that you call (see
Authorization methods, which follows).
The auth_class is supplied as either db_user or db_authorizations, according to
the method that you call. If you store the CALL statement to a variable, the
variable name must be a single word whose character composition is limited to
alphanumeric characters and special characters including the number sign (#),
the percentage sign (%), and the underscore symbol (_).
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Authorization classes in the SQL Access Server
77
Authorization methods
Several class methods operate on the system authorization classes. In addition,
methods operate on the attributes of the db_user class. The operations and
individual examples are described next.
The login() method
After the SQL Access Server has been accessed, use this method to change the
user who is currently logged into the SQL Access Server. It can also be used to
log in as the DBA by entering dba as the user name. If the dba user has a
password, this needs to be entered as well. If the user originally logs into the
SQL Access Server as dba or as a member of the DBA group, then the DBA can
change the user without requiring that the password be given. In this case,
enter the password argument to the login() method as an empty string ( ‘ ’ ).
The login() method is a class method for the db_user class and accepts strings
for the user’s name and password as arguments:
method_definition:
auth_class:
login (name, password)
db_user
The following example changes the login identity of the current user to that of
user ‘jones’, allowing the current user the same authorization privileges that
are granted to ‘jones’. User ‘jones’ does not have a specific password, so an
empty string is provided for that argument:
call login ('jones', '') on class db_user;
The add_user() method
Use the add_user() method to add a new user to the SQL Access Server. Only
the DBA or a member of the DBA group can call this method. This is a class
method that accepts string arguments for the new user’s name and password.
The system displays an error message and will not add the user if the name
already exists in the SQL Access Server:
method_definition:
auth_class:
add_user (name, password)
db_user
The next example adds a user named ‘brown’ to the SQL Access Server. User
‘brown’ does not have an individual password to the SQL Access Server, as
indicated by the empty string for the password argument:
call add_user ('brown', '') on class db_user;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Authorization classes in the SQL Access Server
78
The drop_user() method
Only the DBA or a member of the DBA group can call this method. This class
method removes a current user from the SQL Access Server. If the user is the
owner of classes in the SQL Access Server, the system transfers ownership of
those classes to the DBA. The DBA may then reassign ownership to another
user in the SQL Access Server. The name argument is the only argument
included with the drop_user() method:
method_definition:
auth_class:
drop_user (name) db_user
In this example, user ‘jones’ is removed from the SQL Access Server:
call drop_user ('jones') on class db_user;
The find_user() method
This method finds a user in the SQL Access Server with the name given as the
argument to this method. This is a class method and is used most often with a
variable so the user can be referenced in other method calls:
method_definition:
auth_class:
find_user (name) db_user
The next example finds user ‘smith’ and stores this information to a variable
called ‘smith’ for easy reference in future method calls:
call find_user ('smith') on class db_user to smith;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Authorization classes in the SQL Access Server
79
The add_member() method
This method adds a member to an existing user in the SQL Access Server.
Recall that a user with one or more members is commonly called a group. The
system applies the add_member() method directly to an instance of the
db_user() class rather than to the db_user() class as a whole (it is not a class
method). This method can only be called if you are logged in as the user who
is receiving the new member. An exception is the DBA or a member of the DBA
group who always has the authority to add a new member:
method_definition:
auth_class:
add_member (member)
db_user
In the following example, user ‘smith’ is added as a member to user
‘administration’ (which is a group). The first CALL statement that adds a
member illustrates how the member argument can be given as a variable. The
second CALL statement shows the addition of another member to the
‘administration’ group by supplying a string (‘brown’) as the member
argument:
call add_user ('administration', '') on class db_user to admin;
call add_user ('smith', '') on class db_user to smith;
call add_member ('smith') on admin;
call add_member ('brown') on admin;
The drop_member() method
This method drops a member from the member list of an existing user (group)
in the SQL Access Server. The drop_member() method is applied directly to an
instance of the db_user class rather than to the db_user class as a whole (it is
not a class method). Only call this method if you are logged in as the user who
is dropping the member. An exception is the DBA or a member of the DBA
group who always has the authority to drop a member:
method_definition:
auth_class:
drop_member (member)
db_user
The next two CALL statements each use the find_user() method to identify the
group and the member to be dropped from the group. The ‘administration’
group and member ‘jones’, who is being dropped from the group, are stored as
variables for reference in the CALL drop_member() statement. To illustrate
that strings are valid member arguments as well, the user ‘brown’ is also
dropped from the ‘administration’ group:
call find_user ('administration') on class db_user to admin;
call find_user ('jones') on class db_user to jones;
call drop_member (jones) on admin;
call drop_member ('brown') on admin;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Authorization classes in the SQL Access Server
80
The set_password() method
This method changes the password for a user. Normal users can only change
their own password when logged in as that user, but the DBA or a member of
the DBA group can set any user’s password with this method. The
set_password() method applies directly to an instance of the db_user class:
method_definition:
auth_class:
set_password (password)
db_user
In the next example, the user ‘smith’ is first located using the find_user
method and stored to a variable named smith. A new string is then entered as
the password argument to the set_password() method:
call find_user ('smith') on class db_user to smith;
call set_password ('dfs582b') on smith;
The print_authorizations() method
You can obtain a description of any user in the SQL Access Server by calling this
method. The description includes a listing of the groups of which the user is a
member. Any user in the SQL Access Server can call the print_authorizations()
method. No arguments are passed to this method, which is an instance method
for class db_user. Consequently, you must use either the find_user() or
add_user() methods to make a variable associated with the user. The method
print_authorizations() is then called on that variable:
method_definition:
auth_class:
print_authorizations( )
db_user
The following example obtains a description of user ‘jones’. The find_user()
method is called first and stored in the variable jones. In the second call
statement, variable jones is referenced with the print_authorizations()
method:
call find_user ('jones') on class db_user to jones;
call print_authorizations () on jones;
The print_authorizations() class method of db_authorizations
You can obtain a full description of all users in the SQL Access Server (and the
authorizations they have been granted) from this method. No arguments are
passed to the print_authorizations() method, which is a class method for class
db_authorizations():
method_definition:
auth_class:
print_authorizations( )
db_authorizations
Use only one form of the print_authorizations() method on class
db_authorizations(), as shown in the following example:
call print_authorizations () on class db_authorizations;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Authorization classes in the SQL Access Server
81
The print_authorizations() method must be called from the Command Line
SQL/X processor. It cannot be called from Visual SQL.
The change_owner method of db_authorizations
Use this method to change the ownership information of a class. Only the DBA
user or a member of the DBA group executes this method. The first argument
to the method is the name of a class. The second argument is the name of a
user. Both the class and the user must already exist in the SQL Access Server:
method_definition:
auth_class:
change_owner (class_name, name)
db_authorizations
In the following example, the ownership of the class ‘person’ is changed such
that it belongs to the user ‘smith.’
call change_owner ('person', 'smith') on class db_authorizations;
The get_owner() method of db_authorizations
Use this method to access the user instance designated as the owner of a
particular class. The only argument to the method is the name of the class:
method_definition:
auth_class:
get_owner (class_name)
db_authorizations
In the following example, you can gain access to the object owner for
class ‘person’ by using the get_owner() method. Then,
print_authorizations() is used to get a short description of owner:
call get_owner ('person') on class db_authorizations to owner;
call print_authorizations () on owner;
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Authorization classes in the SQL Access Server
82
Transaction recovery
SQL Access transaction recovery provides transaction processing through the
use of the COMMIT and ROLLBACK statements. These SQL Access statements
are transmitted to the CID Adapter Server and executed as COMIT and RESET
PDM functions. SUPRA Server PDM is responsible for SQL Access Server integrity,
while SQL Access and ODBC, JDBC, and OLE DB client applications control
transaction boundaries and logical units of work (LRU).
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Transaction recovery
83
PDM Locking considerations
The CID Adapter Server supports read-only and update mode. Consider the
following:
♦
When the read-only CID Adapter Client parameter is set to TRUE, all
records are read with the PDM locking parameter RLSE.
♦
When the read-only parameter is set to FALSE in the CID Adapter Client,
either specifically or by default, the RLSE PDM locking parameter is used
for all selects.
OPENVMS UNIX
♦
Searched updates and searched deletes use a locking parameter of END.
MVS
♦
The CID Adapter Server parameter SEARCHUPD_LOCK allows you to specify
the locking parameter you wish to use for searched updates and deletes.
The default for SEARCHPUD_LOCK is READ. The READ locking parameter
allows other tasks to read the records but not update them, eliminating
the need to re-read the records when the update is done. The READ locks
are upgraded to WRITE locks when the update or delete is executed.
MVS
♦
MVS also has a CID Adapter Server parameter DATBASUPD_LOCK, which
allows you to specify the locking parameter for updates. The default is
LOCK.
All PDM locks are released when a COMMIT or ROLLBACK statement is executed.
These SQL Access statements are transmitted to the CID Adapter Server and
executed as COMIT and RESET PDM functions.
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: PDM Locking considerations
84
Statistics considerations
The CID Adapter Server supports four different options for displaying statistics.
The STATS= parameter in the INIT file of the CID Adapter Server is used to
define the level of statistics displayed.
If STATS=FUNCTION is specified, an abbreviated statistics block is printed at
the end of the function. Note that only non-zero lines are printed. It has the
following format:
CSHP870I RECORDS READ BY THE CURRENT xxxxx FUNCTION
CSHP879I
Strategy
CSHP880I
Direct
nnnnnnnn
nnnnnnnn
CSHP881I
Index
nnnnnnnn
nnnnnnnn
CSHP882I
Linkpath
nnnnnnnn
nnnnnnnn
Scan
nnnnnnnn
nnnnnnnn
CSHP883I
Records Read Qualified
CSHP884I
Path Records
nnnnnnnn
CSHP885I
Set
nnnnnnnn
CSHP886I
TOTAL
Records
nnnnnnnn
nnnnnnnn
In message CSHP870I, the xxxxx will be replaced by "SELECT", "SEARCHED
UPDATE", or "SEARCHED DELETE"
If STATS=FUNCTION or STATS=LUW is specified, an abbreviated statistics block
is printed at the end of the logical unit of work. Note that only non-zero lines
are printed. It has the following format:
CSHP871I RECORDS READ BY THE CURRENT LOGICAL UNIT OF WORK
CSHP879I
Strategy
Records Read Qualified
CSHP880I
Direct
nnnnnnnn
nnnnnnnn
CSHP881I
Index
nnnnnnnn
nnnnnnnn
CSHP882I
Linkpath
nnnnnnnn
nnnnnnnn
CSHP883I
Scan
nnnnnnnn
nnnnnnnn
CSHP884I
Path Records
nnnnnnnn
CSHP885I
Set
nnnnnnnn
CSHP886I
TOTAL
Records
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Statistics considerations
nnnnnnnn
nnnnnnnn
85
If STATS=FUNCTION or STATS=LUW or STATS=SYSTEM is specified, a full
statistics block is printed at the end of the run. It has the following format:
CSHP872I P D M
D R I V E R
S T A T I S T I C S
CSHP873I SELECT FUNCTIONS EXECUTED nnnnnnnn
CSHP874I RECORDS READ BY THE SELECT FUNCTION
CSHP879I
Strategy
Records Read Qualified
CSHP880I
Direct
nnnnnnnn
nnnnnnnn
CSHP881I
Index
nnnnnnnn
nnnnnnnn
CSHP882I
Linkpath
nnnnnnnn
nnnnnnnn
CSHP883I
Scan
nnnnnnnn
nnnnnnnn
CSHP884I
Path Records
nnnnnnnn
CSHP885I
Set
nnnnnnnn
CSHP886I
TOTAL
Records
nnnnnnnn
nnnnnnnn
CSHP875I SEARCHED UPDATE FUNCTIONS EXECUTED nnnnnnnn
CSHP876I RECORDS READ BY THE SEARCHED UPDATE FUNCTION
CSHP879I
Strategy
Records Read Qualified
CSHP880I
Direct
nnnnnnnn
nnnnnnnn
CSHP881I
Index
nnnnnnnn
nnnnnnnn
CSHP882I
Linkpath
nnnnnnnn
nnnnnnnn
CSHP883I
Scan
nnnnnnnn
nnnnnnnn
CSHP884I
Path Records
nnnnnnnn
CSHP885I
Set
nnnnnnnn
CSHP886I
TOTAL
Records
nnnnnnnn
nnnnnnnn
CSHP877I SEARCHED DELETE FUNCTIONS EXECUTED nnnnnnnn
CSHP878I RECORDS READ BY THE SEARCHED DELETE FUNCTION
CSHP879I
Strategy
Records Read Qualified
CSHP880I
Direct
nnnnnnnn
nnnnnnnn
CSHP881I
Index
nnnnnnnn
nnnnnnnn
CSHP882I
Linkpath
nnnnnnnn
nnnnnnnn
CSHP883I
Scan
nnnnnnnn
nnnnnnnn
CSHP884I
Path Records
nnnnnnnn
CSHP885I
Set
nnnnnnnn
CSHP886I
TOTAL
CSHP887I OO
Records
nnnnnnnn
nnnnnnnn
FETCH FUNCTIONS EXECUTED nnnnnnnn
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Statistics considerations
86
CSHP888I OO UPDATE FUNCTIONS EXECUTED nnnnnnnn
CSHP889I OO INSERT FUNCTIONS EXECUTED nnnnnnnn
CSHP890I OO DELETE FUNCTIONS EXECUTED nnnnnnnn
Administration Guide, P25-9501-04
Chapter: 3. Managing a CID Foreign Database
Section: Statistics considerations
87
4. Tailoring the CID Adapter Server
Overview
The Cincom Integrated Data (CID) Adapter Server component runs on the same
platform as the SUPRA Server PDM or CICS VSAM files. Each PDM database or
CICS VSAM system you intend to access using the CID Adapter Server requires a
unique network port, and each port can be used by only one CID Adapter
Server. This implies that each CID Adapter Server must have its own
initialization file, CID Adapter Extensions XML file, bound schema file, and
startup scripts. Each PDM database or CICS VSAM system to be accessed must
have a dedicated copy of the CID Adapter Server running and listening to a
unique TCP/IP port. For CICS, the CID Adapter Coordinator and Server are each
defined as a transaction that is started by CICS.
At startup time, the CID Adapter Server reads the CID Adapter Server
initialization parameter file and sets up its running environment. For PDM, the
CID Adapter Server is a multi-process DATBAS application. For CICS VSAM, the
CID Adapter Server uses the VSAM Access Module to access the requested VSAM
files. The first process that is started, or parent process, is called the CID
Adapter Coordinator. This process is responsible for loading the schema and
managing connections to the PDM database or to CICS VSAM.
After reading the CID Adapter Server initialization file, the CID Adapter
Coordinator loads the schema into memory. This is done in one of two ways:
PDM
♦
Schema information is requested directly from the PDM Directory.
VSAM PDM
♦
Schema information is loaded from the CID Adapter schema file that was
saved from the last CID Adapter Server initialization. If there is no saved
CID Adapter schema for VSAM, all the internal schema information will
come from the CID Adapter Extensions XML file, which is described below
The CID Adapter Server input parameter, BIND_SCHEMA, controls which of
these two options is used. See the BIND_SCHEMA parameter for your CID
Adapter Server platform below for more information.
The schema is then extended using the CID Adapter Extensions XML file. See
"Extending the CID Adapter Schema" on page 371 for more information.
After loading and extending the schema, the CID Adapter Server determines
the port on which it should listen for connect requests from CID Adapter
Clients. This is determined by the TCPPORT CID Adapter initialization
parameter or the PORT parameter in the Sockets Initialization file in CICS . The
CID Adapter Server or CICS simply begins listening for connections.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Overview
88
When a connection request is received, a process or CICS task is created for the
connection. Each CID Adapter Server platform accomplishes this task
differently; however, this process is dedicated to executing requests on behalf
of the CID Adapter Client requesting the connection.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Overview
89
Accessing VSAM Files
The MVS CICS CID Adapter Server is used to access KSDS, RRDS and ESDS VSAM
files. These files must be defined in the CID Adapter Extensions XML File before
accessing them using ODBC or JDBC SQL tools. The VSAM files may be added to
a schema built from a PDM database or, when there is no PDM database, the
VSAM files will comprise the entire schema. All files defined in the schema,
whether they are PDM or VSAM files, may be used in SQL queries and may be
joined. COMMIT and ROLLBACK transactional statements will execute the
appropriate functions in both databases.
The specific VSAM files and alternate indices to be added to the CID Adapter
Server’s schema are specified in the VSAM_FILE_LIST parameter(s) of the INIT
file for the CID Adapter Server. This is a comma-separated list of VSAM file DD
names that will be added to the CID Adapter Server’s schema. Refer to
"Defining the MVS and CICS initialization parameters" on page 98 for more
information on the VSAM_FILE_LIST parameter. At startup the CID Adapter
Server will request the file information for each file in the VSAM_FILE_LIST and
add the following information to the CID Adapter Server’s schema for each file:
♦
A File element for the file having the name and type specified by CICS. The
name will be the 1 to 8 character DD name of the file. The type will be
either KSDS, RRDS or ESDS.
♦
A Field element for the base field comprising the entire VSAM record
named file-name_BASE with the length set to the VSAM record length and
type of CHARACTER.
♦
For KSDS files, a Subfield element of the base field for the primary KSDS
key named file-name_KEY and type of CHARACTER.
♦
A Subfield element of the base field for each alternate index key named
alternate-index_name_KEY and type of CHARACTER.
♦
For KSDS files, an Access_method element for the primary KSDS key named
file-name.
♦
An Access Method element for each alternate index. The name will be the
1 to 8 character DD name of the alternate index file.
A CID Adapter Extensions XML file must be created that defines subfield and
data type information to the internal schema for each VSAM file. All fields
defined in the XML file must be subfields of the base field, file-name_BASE.
Each subfield may itself contain subfields, but there can be only one base field.
Additional Access Method elements may be added to define access methods on
subfields of a key. This allows the join optimizer to utilize the index when
subfields of the key are referenced in the query. See "Extending the CID
Adapter Schema" on page 371 for more information on the CID Adapter
Extensions XML file.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Accessing VSAM Files
90
Tailoring the MVS CID Adapter Server
After installing the MVS CID Adapter Server component, you must perform the
following tasks to tailor it for your site. Some of these tasks are required and
are a step in the installation. Cincom recommends, however, that you review
each task here to ensure that everything was set up correctly during
installation.
♦
♦
♦
♦
Defining the CID Adapter Server JCL
Defining the initialization file parameters
(Optional) Examining and updating the ASCII/EBCDIC translation tables
(Optional) Coding the user logon exit
These tasks are discussed in the sections that follow.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
91
Defining the MVS CID Adapter Server JCL
To tailor the CID Adapter Server component, you must first define your CID
Adapter Server JCL. The following JCL is required for the CID Adapter Server:
♦
The execute parm specifies the driver message language:
-
If the parm is omitted, US English is used.
//TEST EXEC PGM=V1DRIVER,PARM=
// Execute card for the server
-
If the parm is specified, a particular member, containing messages for
a specific language, is selected in the MSG PDS. The format of the
PARM is:
'=LANG=xxxxxxxx'
where xxxxxxxx is the member name
♦
The steplib concatenation must include the CID Adapter component, the
user sinon exit (if defined), the user translate tables (if defined), any PDM
command exits, the CSTEDCMT module, and the IBM C/C++ run-time
library.
//STEPLIB
♦
The initialization parameter file can be a DSORG=PS or DSORG=PO file.
RECFM=FB. LRECL is between 80 and 128. The contents of this file are set
by the user.
//INIT
♦
The XMLFILE is an optional file and contains schema extension information
defined by the user. The CID Adapter ExtensionsXML file can be a
DSORG=PS or DSORG=PO file. RECFM=FB. LRECL=80.
// XMLFILE
♦
The message prototype file is a DSORG=PO file. RECFM=FB. LRECL=256.
The contents of this file are set during product installation.
//MSG
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
92
♦
The CSIPARM file with the parameters specified for the PDM installation.
//CSIPARM
♦
The bound schema file is a DSORG=PS file. RECFM=VBS, LRECL=3200. The
contents of this file are set when the schema is bound during driver
initialization.
//SCHEMA
♦
The IBM TCP/IP configuration file (usually prefix.TCPIP.DATA).
//SYSTCPD
♦
The message output file can either be a SYSOUT file or a sequential file
with DSORG=PS,RECFM=FBA,LRECL=133.
//MSGPRINT
♦
The run-time library catastrophic error message output file can either be a
SYSOUT file or a sequential file with DSORG=PS,RECFM=FBA,LRECL=133.
//SYSTERM
♦
This is optional, but recommended.
//SYSUDUMP
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
93
Example:
//*
See member SERVER
Job card here
//*
//LIBSRCH
JCLLIB ORDER=XXXX.YYYYYYYY.JCLLIB
//*
//*******************************************************************
//*
//* LIBSRCH IS REQUIRED TO EXPAND THE INCLUDE GROUP IN INCS1 BELOW
//*
//*******************************************************************
//INCS1
INCLUDE MEMBER=SPARMS
//*
//*
CHANGE THE STEPLIB FOR SUPRA PDM LIBRARY
//*
CHANGE THE STEPLIB FOR C/C++ RUNTIME LIBRARY
//*
CHANGE THE XMLFILE OR REMOVE IF NOT REQUIRED
//*
CHANGE THE CSIPARM FOR YOUR SUPRA CSIPARM
//*
CHANGE THE SYSTCPD FOR YOUR TCP/IP LIBRARY
//*
//SERVER
EXEC PGM=V1DRIVER
//STEPLIB
DD DISP=SHR,DSN=&HLQ..LINKLIB
//
DD DISP=SHR,DSN=<SUPRALIB>
//
DD DISP=SHR,DSN=<CRUNTIME>
//INIT
DD DISP=SHR,DSN=&HLQ..MACLIB(INIT)
//XMLFILE
DD DISP=SHR,&HLQ..MACLIB(XML)
//MSG
DD DISP=SHR,DSN=&HLQ..MSG
//CSIPARM
DD DISP=SHR,DSN=<CSIPARM>
//SCHEMA
DD DISP=SHR,DSN=&HLQ..SCHEMA
//SYSTCPD
DD DISP=SHR,DSN=TCPIP.V2R21.TCPIP.DATA
//SYSPRINT DD SYSOUT=*
//MSGPRINT DD SYSOUT=*
//SYSTERM
DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
/*
//
&HLQ is defined in the SPARMS member, which is included in the beginning of the
job.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
94
Defining the MVS CID Adapter Server CSV1SHUT JCL
The CSV1SHUT member contains the JCL for shutting down the MVS CID Adapter
Server. The DD statements in the CSV1SHUT member are a subset of the DD
statements in the SERVER JCL above. The &PORT, &DBM and &HOST parms for
the EXEC statement are defined in the SPARMS member.
//LIBSRCH
JCLLIB ORDER=XXXX.YYYYYY.JCLLIB
//*
//*******************************************************************
//*
//* LIBSRCH IS REQUIRED TO EXPAND THE INCLUDE GROUP IN INCS1 BELOW
//*
//*******************************************************************
//*
//INCS1
INCLUDE MEMBER=SPARMS
//*
//*
CHANGE THE STEPLIB FOR SUPRA PDM LIBRARY
//*
CHANGE THE STEPLIB FOR IBM C/C++ RUNTIME LIBRARY
//*
CHANGE THE SYSTCPD FOR YOUR TCP/IP LIBRARY
//*
//*
//TEST
EXEC PGM=CSV1SHUT,PARM='-P &PORT -D &DBM -H &HOST'
//STEPLIB
DD DISP=SHR,DSN=&HLQ..LINKLIB
//
DD DISP=SHR,DSN=<SUPRALIB>
//
DD DISP=SHR,DSN=<CRUNTIME>
//INIT
DD DISP=SHR,DSN=&HLQ..MACLIB(INIT)
//SYSTCPD
DD DISP=SHR,DSN= TCPIP.V2R21.TCPIP.DATA
//SYSPRINT DD SYSOUT=*
//MSGPRINT DD SYSOUT=*
//SYSTERM
DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
95
Defining the MVS CID Adapter Server CSV1PING JCL
The CSV1PING member contains the JCL for testing the connection to the MVS
CID Adapter Server. The DD statements in the CSV1PING member are a subset
of the DD statements in the SERVER JCL above. The &PORT and &DBM parms
for the EXEC statement are defined in the SPARMS member.
//LIBSRCH
JCLLIB ORDER=XXXX.YYYYYYYY.JCLLIB
//*
//*******************************************************************
//*
//* LIBSRCH IS REQUIRED TO EXPAND THE INCLUDE GROUP IN INCS1 BELOW
//*
//*******************************************************************
//*
//INCS1
INCLUDE MEMBER=SPARMS
//*
//*
CHANGE THE STEPLIB PDM LIBRARY
//*
CHANGE THE STEPLIB FOR IBM C/C++ RUNTIME LIBRARY
//*
CHANGE THE SYSTCPD FOR YOUR TCP/IP LIBRARY
//*
//*
//TEST
EXEC PGM=CSV1PING,PARM='-P &PORT -D &DBM'
//STEPLIB
DD DISP=SHR,DSN=&HLQ..LINKLIB
//
DD DISP=SHR,DSN=<SUPRALIB>
//
DD DISP=SHR,DSN=<CRUNTIME>
//INIT
DD DISP=SHR,DSN=&HLQ..MACLIB(INIT)
//SYSTCPD
DD DISP=SHR,DSN=XXXX.TCPIP.V2R21.TCPIP.DATA
//SYSPRINT DD SYSOUT=*
//MSGPRINT DD SYSOUT=*
//SYSTERM
DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
96
Defining the MVS CID Adapter Server CSV1PORT JCL
The CSV1PORT member contains the JCL for verifying that no other application
is currently using the MVS CID Adapter Server port. The DD statements in the
CSV1PORT member are a subset of the DD statements in the SERVER JCL above.
The &PORT parm for the EXEC statement is defined in the SPARMS member.
//LIBSRCH
JCLLIB ORDER=XXXX.SUPRAC.JCLLIB
//*
//*******************************************************************
//*
//* LIBSRCH IS REQUIRED TO EXPAND THE INCLUDE GROUP IN INCS1 BELOW
//*
//*******************************************************************
//*
//INCS1
INCLUDE MEMBER=SPARMS
//*
//*
CHANGE THE STEPLIB FOR SUPRA PDM LIBRARY
//*
CHANGE THE STEPLIB FOR IBM C/C++ RUNTIME LIBRARY
//*
CHANGE THE SYSTCPD FOR YOUR TCP/IP LIBRARY
//*
//*
//TEST
EXEC PGM=CSV1PORT,PARM='-P &PORT'
//STEPLIB
DD DISP=SHR,DSN=&HLQ..LINKLIB
//
DD DISP=SHR,DSN=<SUPRALIB>
//
DD DISP=SHR,DSN=<CRUNTIME>
//INIT
DD DISP=SHR,DSN=&HLQ..MACLIB(INIT)
//SYSTCPD
DD DISP=SHR,DSN=XXXX.TCPIP.V2R21.TCPIP.DATA
//SYSPRINT DD SYSOUT=*
//MSGPRINT DD SYSOUT=*
//SYSTERM
DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
97
Defining the MVS and CICS initialization parameters
The MVS CID Adapter Server init file defines your initialization parameters (see
"CID Adapter Server init file parameters (MVS and CICS)" on page 99) and is
pointed to by the //INIT DD statement. When you code the init file, use the
following general coding rules:
♦
Whichever is shorter:
-
A maximum line length of 127 characters
-
The file LRECL
♦
Lines can be blank.
♦
All comment lines must begin with a pound sign (#).
♦
Parameters can begin anywhere on a line but must start and end on one
line.
♦
There can be no space between a parameter keyword and its subsequent
equals sign (=). However, there can be spaces after the equals sign.
♦
Keywords are case-insensitive; they can be lowercase, uppercase, or a
combination of both.
♦
Numbers can be specified as:
Representation
Numeric base
0xnnnn
Hexadecimal
0nnnn
Octal
nnnn
Decimal
♦
Enclose a text string in single quotes (‘text string’) or double quotes (“text
string”) if it contains white space characters (space, tab, newline, return,
form feed). If a text string contains a single quote, enclose the string in
double quotes. If a string contains a double quote, enclose the string in
single quotes.
♦
Boolean=false can be specified by the following character options:
N/n/F/f/0.
Boolean=true can be specified by the following character options:
Y/y/T/t/1.
Characters following one of these option characters are ignored (“not” and
“N1” would be treated as Boolean=false).
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
98
CID Adapter Server init file parameters (MVS and CICS)
The CID Adapter Server init file parameters on MVS are as follows:
ALLOW_CORE_DUMP=TRUE or FALSE
Description
(Optional) Specifies whether a core dump will be allowed. This is a Cincom
Technical Support parameter.
Default
FALSE
Options
TRUE
Allows a core dump to occur
FALSE
Does not allow a core dump to occur
Consideration By default, the CID Adapter Server component does not allow core dumps to be
written when there is an internal problem (segmentation violation). If the CID
Adapter Server component crashes, Cincom Technical Support may request that
this parameter be set so that a core dump can be written for problem analysis.
BIND_SCHEMA=YES or NO
Description
(Optional) Specifies whether bound schema support is enabled.
Default
YES
Options
YES
Enable bound schema support. YES can also be specified by
Y/y/T/t/1.
NO
Disable bound schema support. NO can also be specified by
N/n/F/f/0.
Considerations
♦
When the BIND_SCHEMA parameter is set to YES, the CID Adapter Server
will first look for a bound schema from a prior execution. If it exists, it will
verify that the PDM Directory has not changed since the bound schema file
was written, and, if not, will proceed to load the bound schema into
memory. If the bound schema does not exist or the PDM Directory has
changed since the bound schema file was written, the schema information
will be loaded directly from the PDM Directory, and, when complete, a
bound schema file will be written.
♦
The bound schema file contains the foreign key information from the
Adapter Extensions XML file and schema information from the PDM
Directory but does not contain the CID Adapter Views or Field and type
information. When a change is made to the foreign key information in the
CID Adapter Extensions XML file, it is not automatically detected by the CID
Adapter Server. If the BIND_SCHEMA parameter is set to YES, it is necessary
to delete the bound schema file in order to force the schema to be loaded
directly from the PDM Directory. This will cause the foreign key information
to be refreshed.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
99
♦
All other definitions in the CID Adapter Extensions XML file (CID Adapter
Views, field and type information) will always be processed at start-up
regardless of the BIND_SCHEMA parameter.
♦
When the BIND_SCHEMA parameter is set to NO, the CID Adapter Server will
always load the schema information directly from the PDM Directory and
will not write a bound schema file.
BYPASS_OPT_CTRL_LINKPATH=YES or NO
Description
(Optional) Specifies whether to bypass the optimizer direct lookup and
linkpath processing.
Default
NO
Options
YES
Bypass; do not allow direct and linkpath access. YES can also
be specified by Y/y/T/t/1.
NO
Do not bypass; allow direct and linkpath access. NO can also
be specified by N/n/F/f/0.
Consideration Bypassing is usually used only for debugging specific optimizer problems.
Bypassing can have a severe impact on CID Adapter Server performance.
BYPASS_OPT_INDEX=YES or NO
Description
(Optional) Specifies whether to bypass the optimizer index processing.
Default
NO
Options
YES
Bypass; do not allow index access. YES can also be specified by
Y/y/T/t/1.
NO
Do not bypass; allow index access. NO can also be specified by
N/n/F/f/0.
Consideration Bypassing is usually used only for debugging specific optimizer problems.
Bypassing can have a severe impact on CID Adapter Server performance.
BYPASS_QUAL=YES or NO
Description
(Optional) Specifies whether to bypass qualification on the CID Adapter Server.
Default
NO
Options
YES
Bypass; do not perform qualification on the CID Adapter Server.
YES can also be specified by Y/y/T/t/1.
NO
Do not bypass; perform qualification on the CID Adapter Server.
NO can also be specified by N/n/F/f/0.
Consideration Bypassing is usually used only for debugging specific optimizer problems.
Bypassing can have a severe impact on CID Adapter Server performance.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
100
CICS_SERVER_TRANSACTION=xxxx (CICS only)
Description
(Required CICS only) Specifies the CICS transaction that is used to start the
MVS CICS CID Adapter Server.
Default
NONE
Consideration This must be the save value as the transaction defined in your CSD file for
program CSXRAKSP program and the EZACICD TYPE=LISTENER macro expansion
for the CICS Sockets support CSTRAN= parameter.
DATBASUPD_LOCK=xxxx
Description
(Optional) Specifies the locking parameter value to be used for DATBAS
updates.
Default
LOCK
Consideration No validation is done on this parameter. Normally, this parameter is allowed
to default.
DISPLAY_OPTIONS=YES or NO
Description
(Optional) Specifies whether to display all initialization options and their
values.
Default
NO
Options
YES
Display all initialization options and their values. YES can also
be specified by Y/y/T/t/1.
NO
Do not display the initialization options. NO can also be
specified by N/n/F/f/0.
LOGON_EXIT=xxxxxxxx
Description
(Optional) Specifies the name of a user-written logon exit load module that is
called whenever the CID Adapter Client connects to the CID Adapter Server .
Format
1–8 characters.
Consideration If this parameter is not specified, a logon exit will not be called.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
101
MAX_DATAAREA=nnnnnnnnnn
Description
(Optional) Specifies the size of the data area for retrieving one SELECT or
DATBAS record.
Default
8192
Format
1–2,147,483,647
Consideration This value must be large enough to hold an entire SELECT record, including all
OIDs for all sets specified in the record. The maximum value actually used is
displayed at shutdown to help set this parameter.
MAX_DATALIST=nnnnnnnnnn
Description
(Optional) Specifies the size of the largest datalist that will be generated by
the CID Adapter Server.
Default
4096
Format
1–2,147,483,647
Consideration This value must be large enough to hold an entire datalist. Typically, the
maximum size is 18 * number-of-elements in the user-specified select or
update-list. The maximum value actually used is displayed at shutdown to help
set this parameter.
MAX_DATBAS_PDU=nnnnnnnnnn
Description
(Optional) Specifies the size of the response buffer to be used for db_set or
other object-oriented database functions.
Default
8192
Format
1–2,147,483,647
Consideration This value must be large enough to hold an entire FETCH data area, including
any sets. The maximum value actually used is displayed at shutdown to help
set this parameter.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
102
MAX_RCV_PDU=nnnnnnnnnn
Description
(Optional) Specifies the maximum message size received by the CID Adapter
Server from the CID Adapter Client.
Default
4096
Format
1–2,147,483,647
Consideration This value must be large enough to hold an entire SELECT, including all data
fields and qualifiers, or the entire INSERT data record, including all data fields
and data. The maximum value actually used is displayed at shutdown to help
set this parameter.
MAX_RECORDS_LIMIT=nnnnnnnnn
Description
(Optional) Specifies the maximum number of reads that are allowed to be used
to retrieve data during a query.
Default
0
Options
0–2,147,483,647
Considerations
♦
If the number specified is zero, then the number of reads allowed are
unlimited.
♦
The CID Adapter Client component can set only a lower limit than the
global limit in effect in the CID Adapter Server component.
The limit in effect is computed according to the following table:
Client
Server
Description
0
0
Unlimited reads.
0
n
Limit is the CID Adapter Server global
limit of n.
m
0
Limit is the CID Adapter Client limit of
m.
m
n
Limit is minimum of m, n.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
103
OPT_EXPLAIN=YES or NO
Description
(Optional) Specifies whether to enable the explanation feature of the
optimizer.
Default
NO
Options
YES
Enable the explanation facility. YES can also be specified by
Y/y/T/t/1.
NO
Do not enable the explanation facility. NO can also be
specified by N/n/F/f/0.
Consideration Typically, this parameter is only turned on in a test system. When debugging
new queries, this feature can help you understand query performance.
PDM_THREADS=nnnnn
Description
(Optional) Specifies the maximum number of concurrent threads connected to
the PDM.
Default
1
Format
1–99,997
Considerations
♦
The CID Adapter Server adds one thread to the specified number for its own
use.
♦
This value must be less than or equal to the value for
SERVER_CONNECTIONS.
PDM_USER_DATA=xxxxxxxx
Description
(Optional) Specifies the value to be passed to the PDM SINON in the
USER=(user data) parameter.
Format
1–8 characters in the format required by the PDM.
Consideration If this parameter is not specified, the USER= parameter is not passed to the
PDM SINON.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
104
SEARCHUPD_LOCK=xxxx
Description
(Optional) Specifies the locking parameter value to be used on the DATBAS
functions used for searched updates.
Default
READ
Consideration No validation is done on this parameter. Normally, this parameter is allowed
to default.
SELECTUPD_LOCK=xxxx
Description
(Optional) Specifies the locking parameter value to be used on the DATBAS
functions used for select statements when the connection is not read-only.
Default
RLSE
Consideration No validation is done on this parameter. Normally, this parameter is allowed
to default.
SERVER_CONNECTIONS=nnnnn
Description
(Optional) Specifies the maximum number of concurrent CID Adapter Client
connections to the CID Adapter Server.
Default
1
Format
1–99,997
Considerations
♦
The CID Adapter Server adds two connections to the specified number for
its own use.
♦
This value must be greater than or equal to the value for PDM_THREADS.
♦
Server connections are equivalent to PDM tasks.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
105
SHARED_MEM=nnnnnnnn
Description
(Optional) Specifies the size of shared memory requested for the schema
tables and error messages.
Default
1,048,576 (1MB)
Format
8–16,777,208 and evenly divisible by 8.
Consideration If this value is too small, the CID Adapter Server will not start. If the value is
too large, extra memory is wasted. This memory is allocated above the 16 MB
line. The value actually used is displayed at shutdown to help set this
parameter.
SHUTDOWN_PASSWORD=xxxxxxxx
Description
(Required) Specifies the password that validates CID Adapter Server shutdown
commands from the CID Adapter Client. (This parameter is not applicable to
the CICS MVS CID Adapter Server.)
Default
dba
Format
1–8 printable characters.
SHUTDOWN_USER=xxxxxxxx
Description
(Required) Specifies the user name that validates CID Adapter Server shutdown
commands from the CID Adapter Client.
Default
dba
Format
1–8 printable characters.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
106
STATS=option
Description
(Optional) Enables statistics accumulation.
Default
NO
Options
YES
Enable the statistics facility. YES can also be specified by
Y/y/T/t/1.
NO
Do not enable the statistics facility. NO can also be specified
by N/n/F/f/0.
SYSTEM
Accumulates and displays system level statistics.
LUW
Accumulates and displays system level statistics and logical
unit of work (LUW) level statistics.
FUNCTION
Accumulates and displays system level statistics, LUW level
statistics, and function level statistics.
Consideration The statistics facility can help you understand system performance. See
"Statistics considerations" on page 85 for examples.
TCP_HOSTNAME_LOOKUP=YES or NO
Description
(Optional) Specifies whether there will be a host name lookup for the IP
address whenever a TCP/IP connection is established. (This parameter is not
applicable to the CICS MVS CID Adapter Server.)
Default
NO
Options
YES
Enable the lookup. YES can also be specified by Y/y/T/t/1.
NO
Do not enable the lookup. NO can also be specified by
N/n/F/f/0.
Considerations
♦
The lookup will use either a TCP/IP host file or the TCP/IP resolver.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
107
TCP_HOSTFILE=‘xxx.xxx...’
Description
(Optional) Specifies the MVS name for the file equivalent to /etc/hosts. (This
parameter is not applicable to the CICS MVS CID Adapter Server.)
Default
None
Format
Any valid sequence of characters (enclosed in single quotes) that create a valid
MVS dataname.
Considerations
♦
This specification is necessary only if TCP_HOSTNAME_LOOKUP=YES, and
standard names are not used.
TCP_LISTEN_PORT=nnnnn
Description
(Optional) Specifies the port number to be used for the listener. (This
parameter is not applicable to the CICS MVS CID Adapter Server.)
Default
5010
Format
1–65,535
Considerations
♦
This value is ignored if TCPIP_SUPPORT=NO.
♦
This value must match the corresponding value in the REGISTER FOREIGN
DATABASE statement or the CID Adapter Client parameter db_pdmdatabase-name.
♦
To verify that no other application is currently using a port use the
CSV1PORT JCL supplied with the installation. For more information about
this job, see "Defining the MVS CID Adapter Server CSV1PORT JCL" on
page 97.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
108
TCP_PREFIX=xxxx.xxxx...
Description
(Optional) Specifies a high-level qualifier added to the TCP/IP file names for
TCP/IP access. (This parameter is not applicable to the CICS MVS CID Adapter
Server.)
Default
TCPIP
Format
Any valid sequence of characters that creates a valid MVS dataname.
Example
The default protocol file name is TCPIP.ETC.PROTO. The TCPIP prefix could be
replaced with any valid value specified for this parameter.
TR_TOASCII=xxxxxxxx
Description
(Optional) Specifies the name of the load module that contains a user-defined
EBCDIC-to-ASCII translation table (to replace the standard translation table) .
Default
If this parameter is not provided or has no value, the standard translation table
is used.
Format
1–8 characters.
Consideration The standard translation table for EBCDIC to ASCII is provided in "EBCDIC to
ASCII default translation table" on page 413.
TR_TOEBCDIC=xxxxxxxx
Description
(Optional) Specifies the name of the load module that contains a user-defined
ASCII-to-EBCDIC translation table (to replace the standard translation table) .
Default
If this parameter is not provided or has no value, the standard translation table
is used.
Format
1–8 characters.
Consideration The standard translation table for ASCII to EBCDIC is provided in "ASCII to
EBCDIC default translation table" on page 414.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
109
TRACE_OPTIONS=nnn,nnn-nnn…
Description
(Optional) If specified, this parameter turns on debug tracing and specifies one
or more tracing options to be used within the CID Adapter Client component.
This is a Cincom Technical Support parameter.
Default
The parameter is not present (no tracing).
Options
8–239
Format
One or more numbers or number ranges, separated by commas (e.g., 1, 10–14,
17).
Consideration Tracing is usually turned on at the recommendation of Cincom Support.
Support provides the specified numbers corresponding to specific tracing
actions. When enabled, some trace options generate significant output and
can degrade performance. All trace output is written to MSGPRINT DD.
VSAM_FILE_LIST=file-name, file-name,… (CICS only)
Description
(Optional) If specified, this parameter defines the 1 to 8 character DD names
of the KSDS, RRDS, ESDS and alternate index VSAM files that will be made
available in the CID Adapter Server for SQL queries.
Default
The parameter is not present (no VSAM files will be added to the schema).
Format
Comma-separated list of 1 to 8 character VSAM DD file names.
Considerations
♦
Any number of VSAM_FILE_LIST parameters may be included to provide lists
longer than will fit on one line of the input file.
♦
The VSAM files specified in the VSAM_FILE_LIST parameter must be defined
to and managed by CICS.
♦
Alternate index files must be listed after the base file to which they refer
and before a new base file. A good practice is to start all new base files on
a new VSAM_FILE_LIST parameter.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
110
Coding the optional user logon exit (MVS)
A user exit can be coded to perform user validation during user connection.
The intent is to permit security checking before allowing a user access to the
PDM. The exit is called at two points:
♦
Whenever a user connects to the driver
♦
During shutdown to do any necessary user exit cleanup
An assembler version of the user exit is contained in the MACLIB library
installed from the release tape.
The logon exit is loaded during CID Adapter Server initialization. It is called by
all of the CID Adapter Server processes for connection. Since CID Adapter
Server processes run asynchronously to each other, the user exit must either be
fully reentrant or use ENQ/DEQ logic to single-thread access. Note that the
user-defined context full word must be accessed though ENQ/DEQ or other SMP
programming techniques (the CS instruction).
When called, the exit uses the following register conventions:
R1
Points to a standard IBM parameter list.
R13
Points to a standard 72-byte save area.
R14
Contains the return address.
R15
Contains the exit entry point address.
On return, all registers must be the same as at entry, except R15, which
contains a return code. If the return code is zero, the connection will
continue. If the return code is not zero, the connection will be rejected by the
CID Adapter Server. The error message returned in the reason parameter will
be printed in the CID Adapter Server message log.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
111
The parameters on the connect and shutdown exit calls are:
♦
Address of 9-character database name (null terminated).
♦
Address of 9-character user name (null terminated).
♦
Address of 9-character password from logon (null terminated).
♦
Address of 17-character name of host that issues logon (null terminated).
♦
Address of a full word (initially zero) that can be used to store any userdefined context. This value will then be accessible on all future calls.
♦
Address of a127-character area that can be used to return an error message
to the CID Adapter Server. The message must be null terminated.
♦
Address of a full word that contains 1 for a shutdown request and 0 for a
connection request.
The termination call is made once, near the end of shutdown processing. When
this call is made, all connections have been broken and all CID Adapter Server
processes are detached. SMP processing is not required for this call. The
parameters on the termination exit call are:
♦
Zero.
♦
Zero.
♦
Zero.
♦
Zero.
♦
Address of a full word (initially zero) that can be used to store any userdefined context.
♦
Address of a 127-character area that can be used to return an error
message to the CID Adapter Server. The message must be null terminated.
♦
Address of a full word that contains the binary integer 2 for system
termination.
When the logon exit is called, the thread has been signed on to the PDM. Any
PDM database function (except SINON and SINOF) can be executed. If the user
exit uses DATBAS functions, it must be linked with the DATBAS interface
included with the CID Adapter Server. Note that this DATBAS interface should
only be used for the CID Adapter Server exit, and does not replace the DATBAS
module used for other application programming.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
112
Creating an additional MVS CID Adapter Server
Once you have tailored the MVS CID Adapter Server, you may wish to create an
additional MVS CID Adapter Server for a test or production PDM.
You will need the following information:
1. A new port number for TCP/IP communication
2. The DSN of the CSIPARM file for this MVS SUPRA PDM
3. The DSN of the MVS SUPRA PDM library that contains the CSTEDCMT file for
this MVS SUPRA PDM
Follow these steps to create the JCL for an additional MVS Adapter Server:
1. Create a copy of the INIT member of the JCL library and give it another
name. Put the new Port number in this new member in the
TCP_LISTEN_PORT parameter. Review the other parameters, especially the
PDM_THREADS and SERVER_CONNECTIONS.
2. Create a new SCHEMA file. Allocate a new file with the same format and
size as the one you are using now.
3. Create a copy of the SERVER member that you are currently using to bring
up the MVS CID Adapter Server.
a. Change the Jobname so that it is unique
b. Modify the INIT DD to point to the new member that you created
c. Modify the CSIPARM DD to point to the CSIPARM file for this MVS
SUPRA PDM to which you wish to connect
d. Modify the SCHEMA DD to point to the new SCHEMA file that you
created
e. Modify the STEPLIB to point to the appropriate SUPRA PDM library
that contains the CSTEDCMT file for this PDM
f.
If you are using the HLQ parameter, you may need to change this
parameter in the SPARMS member.
You will also need to register a new Foreign Database to communicate with this
additional MVS CID Adapter Server. For more information on registering a
Foreign Database, see "Registering a CID Foreign Database" on page 29.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CID Adapter Server
113
Tailoring the MVS CICS CID Adapter Server
After installing the MVS CICS CID Adapter Server component, you must perform
the following tasks to tailor it for your site. Cincom recommends that you
review each task here to ensure that everything was set up correctly during
installation.
♦
Defining the MVS CICS initialization file parameters
♦
Updating the SUPRA PDM CICS environment or the CICS VSAM environment
and JCL for the Adapter Server
♦
(Optional) Examining and updating the ASCII/EBCDIC translation tables
♦
(Optional) Coding the user logon exit
These tasks are discussed in the sections that follow.
Defining the MVS CICS initialization file parameters
The MVS CICS CID Adapter Server initialization file defines your initialization
parameters and is pointed to by the //CSIDAKI DD statement. In the next
section we describe how to create and load this VSAM file from the
&HLQ.MACLIB(INIT) sequential file.
Please review the section "Defining the MVS and CICS initialization parameters"
on page 98 and make any changes to the &HLQ.MACLIB(INIT) sequential file
prior to loading it into the VSAM file.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CICS CID Adapter Server
114
Updating the SUPRA PDM or VSAM CICS environment and JCL
for the Adapter Server
1. If your CICS is not setup for CICS SOCKET support, you will need to add it.
See IBM documentation in the Communications Server IP CICS Sockets
Guide, SC31-8807-xx for information on installing and using CICS SOCKETS.
2. The TCP/IP port number identified during the Adapter Server install and
the DAKS transaction must be supplied in the EZACICD TYPE=LISTENER
macro used with the above CICS SOCKET support. See member DEFTCPIP in
the &HLQ.MACLIB for sample JCL.
3. If your CICS does not have the Language Environment (LE) installed, you
will need to install it. See IBM documentation in CICS Transaction Server
for z/OS Installation Guide GC34-6426-xx for information on installing LE in
CICS.
4. Review member RDODAK in the &HLQ.MACLIB that was created during the
Adapter Server install. This member contains RDO updates to your CICS
CSD file. Make any changes for your system and update your current CICS
CSD file. Be sure to add the DAK001 group to a list that will be installed
when your CICS is started. The transactions DAKD and DAKS can be
changed if they conflict with existing transactions at your site.
5. Add to your CICS DFHRPL concatenation list the &HQL. LINKLIB that was
created during the Adapter Server install step.
//
DD DISP=SHR,DSN=&HLQ..LINKLIB
6. Add a DD for the VDAK transient data queue final route location. This DD
will display the output from the CICS CID Adapter Server. If you use the
DEFINE TDQUEUE supplied in the RDODAK member, it should look like this:
//VDAK
DD SYSOUT=*,DCB=(DSORG=PS,RECFM=V,BLKSIZE=136)
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CICS CID Adapter Server
115
7. Several VSAM datasets must be created, loaded from sequential datasets,
and added to your CICS JCL. Sample member ALLODAKF in the
&HLQ..MACLIB can be used as a guide in creating your datasets. Two of
these data sets are required and two are optional.
Required:
-
&HLQ.VSAM.MSG—Loaded from &HLQ.MSG as DDNAME CSIDAKM. This
ESDS file contains the Adapter Server messages.
Add to the CICS JCL:
//CSIDAKM
-
DD DSN=&HLQ..VSAM.MSG,DISP=SHR
&HLQ.VSAM.INIT—Loaded from &HLQ.MACLIB(INIT) as DDNAME CSIDAKI.
This ESDS file contains the initialization parameters.
Add to the CICS JCL:
//CSIDAKI
DD DSN=&HLQ..VSAM.INIT,DISP=SHR
Optional:
-
&HLQ.VSAM.SCHEMA—If the INIT file option BIND_SCHEMA=YES is
specified, the schema is created in memory and written to this ESDS
file on the initial execution of the CICS MVS CID Adapter Server. In
subsequent executions, the schema is loaded into memory from this
file. DDNAME CSIDAKS.
Add to the CICS JCL:
//CSIDAKS
PDM
VSAM
DD DSN=&HLQ..VSAM.SCHEMA,DISP=SHR
&HLQ.VSAM.XML—This is the schema extension RRDS file.
If it is available, it will be used to define or redefine the schema
information retrieved from the SUPRA PDM directory. It can also be
used to add schema information that is not available in the SUPRA PDM
directory.
This file is used to define the internal schema information for each
VSAM file.
Review the ALLOCDAK member of the &HLQ.MACLIB for details. DDNAME
XMLFILE.
//XMLFILE
DD DSN=&HLQ..VSAM.XML,DISP=SHR
8. Add the CICS_SERVER_TRANSACTION=DAKS to the &HLQ.VSAM.INIT file.
This must be the same value as the transaction defined in your CSD file for
program CSXRAKSP program and the EZACICD TYPE=LISTENER macro
expansion created above.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CICS CID Adapter Server
116
9. The DAKD transaction can then be started from one of the following:
-
A CICS sequential terminal—If you use SIT option TCT=5$ then this will
be the CARDIN DD in your CICS JCL. DAKD\ in this DD will cause
transaction DAKD to be started.
-
A CICS connected terminal
The DAKS transaction will be enabled by the DAKD transaction to allow
TCP/IP connections to start processing work from the client.
Defining the CICS CID Adapter Server CSV1PING and
CSV1PORTJCL
In order to test the connection to the CICS CID Adapter Server from MVS, use
the same batch JCL that is used for MVS. Refer to “Defining the MVS CID
Adapter Server CSV1PING JCL” for the necessary information.
In order to test the port that you will use for the CICS CID Adapter Server from
MVS you will use the same batch JCL that is used for MVS. Refer to “Defining
the MVS CID Adapter Server CSV1PORT JCL” for the necessary information.
Creating an additional CICS CID Adapter Server
Once you have tailored the CICS CID Adapter Server, you may wish to create an
additional CICS CID Adapter Server for a test or production system. Consider
the following:
♦
You will nee a new port number for TCP/IP communication.
♦
You will repeat the steps in the section "Updating the SUPRA PDM or VSAM
CICS environment and JCL for the Adapter Server" on page 115, being sure
to use different file names for CSIDAKS and CSIDAKI. CSIDAKM will be the
same for all CICS CID Adapter Servers. The XMLFILE may have a different
file or the same file for each CICS CID Adapter Server.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the MVS CICS CID Adapter Server
117
Tailoring the OpenVMS CID Adapter Server
After installing an OpenVMS CID Adapter Server, you must perform certain sitespecific tasks to set up a CID Adapter Server for a PDM database. During the
installation process (documented in the SQL Access for SUPRA Server PDM
Installation Guide, P25-9500) you chose an installation directory for the
OpenVMS CID Adapter Server. This directory is referred to here as the adapterinstall-directory.
Tailoring a CID Adapter Server on OpenVMS includes the following required and
optional tasks for each database:
♦
Authorizing OpenVMS Privileges
♦
Defining PDM Adapter logical names
♦
Defining and enabling a TCP/IP service
♦
Defining the CID Adapter Server/CID Adapter Coordinator startup command
procedures
♦
Defining your initialization file parameters
♦
(Optional) Defining the CID Adapter Extensions XML file
♦
(Optional) Coding the user logon exit
The S1_ADAPTER_SETUP.COM command file, documented in "Running the
S1_ADAPTER_SETUP.COM command file" on page 119, performs all of the above
tasks by requesting information from the user interactively. These tasks are
discussed individually in the sections that follow.
Because the files created by the adapter setup command file use the logical
names defined in [<adapter-install-directory>.COMS]LOGICALS.COM, it is not
necessary to run the adapter setup command file when upgrading to a new CID
Adapter Server service level. It is only necessary run the correct LOGICALS.COM
command file for the service level you want by changing the adapter-installdirectory name in the command file that runs LOGICALS.COM.
Authorizing OpenVMS Privileges
The following OpenVMS process privileges must be authorized in order to run
the S1_ADAPTER_SETUP.COM , as well as the run and stop command files
generated by S1_ADAPTER_SETUP.com for each CID Adapter Server:
SYSPRV, SYSLCK, SYSNAM, SYSGBL, GRPNAM, NETMBX, TMPMBX, OPER
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
118
Running the S1_ADAPTER_SETUP.COM command file
The adapter setup command file, S1_ADAPTER_SETUP.COM, interactively
guides the user through the process of setting up CID Adapter Servers for one or
more databases. Each CID Adapter Server is associated with exactly one PDM
database. Each CID Adapter Server is given a name—the DBMOD name plus an
optional extension. A TPCIP port number is assigned to the CID Adapter Server
and all of the files associated with the CID Adapter Server are created. Each
file and service associated with the CID Adapter Server is preceded by the
adapter name, allowing multiple CID Adapter Servers to reside in the same
directory, as well as allowing easy identification of the CID Adapter Server files
associated with a particular database.
After the adapter setup command file creates the files for a particular
database, these files can be safely customized with additional parameters or
DCL as necessary. The adapter setup command file may be run multiple times
for the same CID Adapter Server in order to modify the parameters. The files
created the first time it is run will be edited on subsequent runs. This preserves
any modifications made outside the command file.
The adapter setup command file requires that the [<adapter-installdirectory>.COMS]LOGICALS.COM command file be run in order to set up certain
logical names required by the command file. Once this is done, the command
file may be run using the following command:
@V1DRV_COMS:S1_ADAPTER_SETUP
The adapter setup command file uses menus and prompts to request
information from the user. Default values for prompts are displayed at the end
of a prompt enclosed within square brackets ( [default-value] ). Default values
are selected by pressing ENTER without typing a value.
The adapter setup command file can be canceled at any time by pressing
CTRL-C or CTRL-Y. The command file may then be re-run to continue setting up
CID Adapter Servers. Some errors cause the command file to exit. Once the
problem reported by the command file is corrected, it may be re-run to
continue setting up CID Adapter Servers.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
119
The files created by the adapter setup command file will reside in the current
default directory, referred to after setup as the adapter-home-directory, and
will be owned by the current user. The files created by the adapter setup
command file are listed here:
File name
Description
<adapter-name>_INIT.DAT
CID Adapter Server initialization
parameter file.
<adapter-name>_RUN.COM
A command file to run the adapter.
<adapter-name>_STOP.COM
A command file to stop the
adapter.
<adapter-name>_COORD_START.COM
A command file to start the CID
Adapter Coordinator process. This
is run by the <adapter-name>
_RUN.COM file as either a batch or
detached process.
<adapter-name>_SERVER_START.COM
A command file to start the CID
Adapter Server process. This file is
run by the TCPIP service in
response to a connect request.
There will be one CID Adapter
Server process in the system for
each connection.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
120
The adapter setup command file requests the information listed here:
Item
Description
DBMOD name
Choose a PDM DBMOD name from the menu. This
will be used as the adapter name.
Extension
An optional four character extension used to
uniquely identify an adapter if there is more than
one DBMOD with the same name in the system.
TCPIP port number
If TCPIP or UCX are available on the system, the
port number is automatically assigned. It can be
overridden, but the port number will be checked
for availability before proceeding. If neither
TCPIP or UCX are on the system, an available port
number must be supplied. In either case, the port
number is then used in the SQL Access REGISTER
FOREIGN DATABASE statement.
TCPIP limit
For TCPIP and UCX, this is the limit parameter
that limits the maximum number of CID Adapter
Server processes started. This should be at least
one greater than the MAX_ACTIVE parameter of
the SQL Access REGISTER FOREIGN DATABASE
statement.
MAX_RECORDS_LIMIT
This CID Adapter Server initialization parameter
controls the number of records that are allowed
to be read by a single query. The default value of
0 allows unlimited reading.
At the end of a CID Adapter Server setup session, the command file will ask if
you want to start the CID Adapter Server that has been created. If you are
installing SQL Access for SUPRA Server PDM (SQL Access), it is recommended
that you start the CID Adapter Server that you create so that the remaining
installation steps on the SQL Access Server machine can be completed.
The CID Adapter Servers created by the CID Adapter Server setup command file
can be started by entering the following command at the command prompt or
by adding the command to the SYSTARTUP_VMS.COM file:
@device:[adapter-home-directory]adapter-name_RUN
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
121
To stop an adapter, use the following command:
@device:[adapter-home-directory]adapter-name_STOP
After creating a CID Adapter Server for a database, it is possible to customize it
by adding parameters to the initialization parameter file, extending the
schema by adding a foreign key file, or customizing the command files. All of
the customizations made to a CID Adapter Server will be preserved if the CID
Adapter Server setup command file is run again, after the initial setup. This
may be desirable in order to change any of the values requested by the
command file, but is not necessary when upgrading to a new CID Adapter
Server service level.
The files created or used by a running CID Adapter Server are listed in the
following table:
File name
Description
adapter-name_SCHEMA.DAT
CID Adapter Server bound schema
file. This file is written
automatically by the CID Adapter
Coordinator, and, if present on
subsequent CID Adapter Server
runs, is read by the CID Adapter
Coordinator to build the internal
database schema instead of making
requests to PDM.
adapter-name_LOG.DAT
CID Adapter Server log file. This
file will contain logged output from
the CID Adapter Coordinator as
well as all of the CID Adapter
Server processes.
These files will be written to or read from the adapter-home-directory.
The output from a CID Adapter Server setup session that created a CID Adapter
Server for the sample BURRYS database is shown in Appendix B.
The following sections provide details of the tailoring steps provided by the
S1_ADAPTER_SETUP.COM command file for those who want to customize the
CID Adapter Servers created by the S1_ADAPTER_SETUP.COM command file.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
122
Defining CID Adapter Server logical names
The following logical names are used by the CID Adapter Server and the CID
Adapter Coordinator processes:
Logical name
Description
CSI_MESSAGE_FILE
The name of a message file. Since the section
associated with the message file is shared by all
CID Adapter Server systems, the logical name
should be defined in the system table.
CSI_INIT_FILE
Identifies the name of a file containing the
initialization parameters.
CSI_SERVER_SCHEMA
The name of a bound schema file (contains the
information about the database being accessed).
If the file does not exist, the CID Adapter
Coordinator process will generate it. The file will
be automatically updated if the database is
modified.
CSI_XML_SCHEMA
(Optional) The name of a CID Adapter Extensions
XML file
CSI_TRACE_FILE
The name of a CID Adapter Server trace file
(optional, default SUP1DRVR.ERR). This file
should be defined in the CID Adapter Coordinator
and CID Adapter Server processes.
CSI_TRACE_OPEN
When defined, this logical name causes the CID
Adapter Server to leave the trace log file open
permanently for performance reasons. It is only
closed when the CID Adapter Server terminates.
This prohibits different CID Adapter Servers from
using the trace log file and prevents the
examination of the trace log file while the CID
Adapter Server is running. The absence of this
logical causes the default behavior; the log file is
opened prior to writing each message and closed
after writing each message.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
123
The logical names associated with the release directory structure can be
defined by executing the LOGICALS.COM command procedure, found in
device:[<adapter-install-directory>.V1DRV_nnnnnn.COMS] where nnnnn is the
driver release number. The following logical names are defined:
Logical name
Description
CSISERVER
Specifies the path to the CSISERVER executable in
the EXE directory.
CSISERVER_DEB
Specifies the path to the CSISERVER_DEB executable
in the EXE directory.
CSIHUBSHR
Specifies the path to the CSIHUBSHR executable in
the EXE directory.
CSIHUBSHR_DEB
Specifies the path to the CSIHUBSHR_DEB executable
in the EXE directory.
V1DRV_BASE
Specifies the path to the CID Adapter Server install
directory.
V1DRV_BURRYS
Specifies the path to the BURRYS directory in the
install directory.
V1DRV_COMS
Specifies the path to the COMS directory in the CID
Adapter Server install directory. The COMS directory
contains CID Adapter Server command files.
V1DRV_EXE
Specifies the path to the EXE directory in the CID
Adapter Server install directory. The EXE directory
contains the entire executable file for the CID
Adapter Server.
V1DRV_HELP
Specifies the path to the HELP directory in the CID
Adapter Server install directory. The HELP directory
contains release notes, readme and SUP1DRVR.MSG
files.
V1DRV_LOGS
Specifies the path to the LOGS directory in the CID
Adapter Server install directory. The LOGS directory
contains output logs from the PDM Adapter.
V1DRV_PATCHES
Specifies the path to the PATCHES directory in the
CID Adapter Server install directory.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
124
The PDM Adapter service level is specified in the following file:
device:[adapter-installdirectory.V1DRVnnnnnn.COMS]V1DRV_SERVICE_LEVEL.COM
It defines the global symbol V1DRV_SERVICE_LEVEL, a string used by all of the
provided command files to identify the service level (for example, 2400).
Cincom suggests you include the following lines in your system startup
command procedure SYSTARTUP_VMS.COM:
$ @ device:[adapter-installdirectory.V1DRVnnnnnn.COMS]LOGICALS.COM SYSTEM
$ Define/SYSTEM CSI_MESSAGE_FILE V1DRV_HELP:SUP1DRVR.MSG
where nnnnn is the driver release number
For additional information about defining logical names for PDM, refer to the
SUPRA Server PDM System Administration Guide (OpenVMS), P25-0130.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
125
Defining and enabling a TCP/IP service through UCX (OpenVMS)
Before starting the system, you must define and enable a TCP/IP service
through TCP/IP, UCX or any other TCP/IP service installed on your machine for
each database the CID Adapter Server will access. Defining the TCP/IP service
is done only once by executing the following command procedure. An example
can be found in V1DRV_COMS:
Example: CSI_SUP1TCP_SETUP.COM
$UCX SET SERVICE <adapter-name> n
/limit=10 /FILE=V1DRV_COMS:<adapter-name>SERVER_START.COM - o
/PORT=5010 /user=dba /PROCESS_NAME=<adapter-name>
p
$UCX ENABLE SERVICE <adapter-name>
q
n The value specified (adapter-name) must be unique for each database. This
command is executed by the S1_ADAPTER_SETUP.COM command file.
o Cincom does not recommend using a directory path in place of a system
logical. The command procedure (<adapter-name>_SERVER_START.COM)
must contain a SERVER command using the same port number specified
here. The user must be defined in the OpenVMS system user authorization
file. The <adapter-name>_SERVER_START>COM file is created by the
S1_ADAPTER_SETUP.COM command file.
p The PROCESS_NAME is the process name given to the CID Adapter Server
when UCX starts it using the <adapter-name>_SERVER_START.COM
command procedure. The process name must be a valid OpenVMS process
name.
q This line enables the TCP/IP service. The name specified (adapter-name)
must be the same as in (1) above. This command is executed in the
<adapter-name>_RUN.COM command file.
For further information on UCX service parameters, refer to the Compact
TCP/IP Services for OpenVMS Reference Guide.
After defining and enabling the TCP/IP service for the first time using the
above command procedure, it is only necessary to enable the service during
the CID Adapter Server startup. This can be done by executing the following
command:
$ UCX ENABLE SERVICE service-name
where service-name is the SERVICE_name set up in the UCX SET SERIVICE
command in CSI_SUP1TCP_SETUP.COM. This command is included in the
<adapter-name>_RUN.COM command file created by S1_ADAPTER_SETUP.COM.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
126
Defining the CID Adapter Server/CID Adapter Coordinator
startup procedure (OpenVMS)
To define the Cincom Integrated Data (CID) Adapter Server/CID Adapter
Coordinator startup procedure, you must define the location of the bound
schema file, the Adapter Extensions XML file, the CID Adapter Server
initialization file, and the message file. Since the message file is shared by all
systems, it is recommended that the logical name be defined in a system table.
The $V1DRVR_COMS: directory contains the following example command files:
♦
Server Example: CSI_SUP1DRVR_START.COM – This file is generated by
S1_ADAPTER_SETUP.COM as <adapter-name>_SERVER_START.COM.
$DEFINE CSI_SERVER_SCHEMA V1DRV_BURRYS:CSI_SERVER_SCHEMA.BURRYS n
$DEFINE CSI_FOREIGN_KEY V1DRV_BURRYS:BURRYS_FOREIGN_KEY.DAT
o
$SERVER := $V1DRV_EXE:CSISERVER_nnnnnn.EXE
p
$SERVER SERVER 6000
q
n Define the name of a bound schema file
o Define the name of a CID Adapter Extensions XML file (optional)
p Define a symbol for the CID Adapter Server image
q Execute CID Adapter Server with SERVER function and a TCP port it
uses
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
127
♦
Coordinator Example: CSI_SUP1COORD_START.COM - This file is
generated by S1_ADAPTER_SETUP.COM as <adaptername>_COORD_START.COM.
$DEFINE CSI_INIT_FILE
n
V1DRV_BURRYS:SUP1DRVR_INIT.DAT
$DEFINE CSI_SERVER_SCHEMA V1DRV_BURRYS:CSI_SERVER_SCHEMA.BURRYS o
$SERVER := $V1DRV_EXE:CSISERVER_nnnnnn.EXE
p
$SERVER COORDINATOR 6000
q
n Define initialization parameters file for the system
o Define the name of a bound schema file
p Define a symbol for the CID Adapter Server image
q Execute CID Adapter Server with a COORDINATOR function and a TCP
port it uses
Cincom recommends you submit the above DCL script file to a batch queue in
order to activate a CID Adapter Coordinator process.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
128
Defining the TCP/IP service through MultiNet Server
Although not officially supported or certified, the following is included to aid in
the configuration of a MultiNet Server TCP/IP service.
The Network Administrator needs to ensure that the port being used for the
service is available and not in use by any other service.
The following is an example of MultiNet configuration:
Welcome to OpenVMS (TM) VAX Operating System, Version V7.1
Username: SYSTEM
Password:
MultiNet Server Configuration Utility V4.0(40)
[Reading in configuration from MULTINET:SERVICES.MASTER_SERVER]
SERVER-CONFIG>
SHO/FULL SUP1DRVR
Service "SUP1DRVR":
TCP socket (AF_INET,SOCK_STREAM), Port 6000
Socket Options =
SO_KEEPALIVE
Flags =
UCX_SERVER
INIT() = TCP_Init
LISTEN() = TCP_Listen
CONNECTED() = TCP_Connected
SERVICE() = Run_Program
Program =
"DKA100:[SUPRAHUB1140.V1DRV_114011N.COMS]CSI_SUP1DRVR_START.COM"
Max Servers = 10
Log File for Accepts & Rejects = OPCOM
Serving Process = SUP1DRVR
Username = "MNT"
SERVER-CONFIG>
EX
[Configuration not modified, so no update needed]
The sup1drvr service will not be available until the machine is rebooted. Once
established, this service can be used by the CSI_SUP1COORD_START.COM and
CSI_SUP1DRVR_START.COM command files defined above for UCX.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
129
Defining the initialization parameters (OpenVMS)
After defining your CID Adapter Server/CID Adapter Coordinator startup
procedure, you must now define your initialization parameters. The CID
Adapter Server initialization file is pointed to by the logical name
CSI_INIT_FILE. When you code the initialization file, use the following general
coding rules:
♦
Whichever is shorter:
-
A maximum line length of 127 characters
-
The file LRECL
♦
Lines can be blank.
♦
All comment lines must begin with a pound sign (#).
♦
Parameters can begin anywhere on a line but must start and end on one
line.
♦
There can be no space between a parameter keyword and its subsequent
equals sign (=). However, there can be spaces after the equals sign.
♦
Keywords are case-insensitive; they can be lowercase, uppercase, or a
combination of both.
♦
Numbers can be specified as:
Representation
Numeric base
0xnnnn
Hexadecimal
0nnnn
Octal
Nnnn
Decimal
♦
Enclose a text string in single quotes (‘text string’) or double quotes (“text
string”) if it contains white space characters (space, tab, newline, return,
form feed). If a text string contains a single quote, enclose the string in
double quotes. If a string contains a double quote, enclose the string in
single quotes.
♦
Boolean=false can be specified by the following character options:
N/n/F/f/0.
Boolean=true can be specified by the following character options:
Y/y/T/t/1.
Characters following one of these option characters are ignored (“not” and
“N1” would be treated as Boolean=false).
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
130
Server init file parameters (OpenVMS)
The CID Adapter Server init file parameters on OpenVMS are:
ALLOW_CORE_DUMP=True or False
Description
(Optional) Specifies whether a core dump will be allowed. This is a Cincom
Technical Support parameter.
Default
False
Options
True
Allows a core dump to occur
False
Does not allow a core dump to occur
Consideration By default, the CID Adapter Server component does not allow core dumps to be
written when there is an internal problem (segmentation violation). If the CID
Adapter Server component crashes, Cincom Technical Support may request that
this parameter be set so that a core dump can be written for problem analysis.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
131
BIND_SCHEMA=YES or NO
Description
(Optional) Specifies whether bound schema support is enabled.
Default
YES
Options
YES
Enable bound schema support. YES can also be specified by
Y/y/T/t/1.
NO
Disable bound schema support. NO can also be specified by
N/n/F/f/0.
Considerations
♦
When the BIND_SCHEMA parameter is set to YES, the CID Adapter Server
will first look for a bound schema from a prior execution. If it exists, it will
verify that the PDM Directory has not changed since the bound schema file
was written, and, if not, will proceed to load the bound schema into
memory. If the bound schema does not exist or the PDM Directory has
changed since the bound schema file was written, the schema information
will be loaded directly from the PDM Directory, and, when complete, a
bound schema file will be written.
♦
The bound schema file contains the foreign key information from the
Adapter Extensions XML file but does not contain the CID Adapter View or
Field and Type information. When a change is made to the foreign key
information in the CID Adapter Extensions XML file, it is not automatically
detected by the CID Adapter Server. If the BIND_SCHEMA parameter is set
to YES, it is necessary to delete the bound schema file in order to force the
schema to be loaded directly from the CID Directory. This will cause the
foreign key information to be refreshed.
♦
When the BIND_SCHEMA parameter is set to NO, the CID Adapter Server will
always load the schema information directly from the PDM Directory and
will not write a bound schema file.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
132
BYPASS_OPT_CTRL_LINKPATH=YES or NO
Description
(Optional) Specifies whether to bypass the optimizer direct lookup and
linkpath processing.
Default
NO
Options
YES
Bypass; do not allow direct and linkpath access. YES can also
be specified by Y/y/T/t/1.
NO
Do not bypass; allow direct and linkpath access. NO can also
be specified by N/n/F/f/0.
Consideration Bypassing is usually used only for debugging specific optimizer problems.
Bypassing can severely impact CID Adapter Server performance.
BYPASS_OPT_INDEX=YES or NO
Description
(Optional) Specifies whether to bypass the optimizer index processing.
Default
NO
Options
YES
Bypass; do not allow index access. YES can also be specified by
Y/y/T/t/1.
NO
Do not bypass; allow index access. NO can also be specified by
N/n/F/f/0.
Consideration Bypassing is usually used only for debugging specific optimizer problems.
Bypassing can severely impact CID Adapter Server performance.
BYPASS_QUAL=YES or NO
Description
(Optional) Specifies whether to bypass qualification on the CID Adapter Server.
Default
NO
Options
YES
Bypass; do not perform qualification on the CID Adapter Server.
YES can also be specified by Y/y/T/t/1.
NO
Do not bypass; perform qualification on the CID Adapter Server.
NO can also be specified by N/n/F/f/0.
Consideration Bypassing is usually used only for debugging specific optimizer problems.
Bypassing can severely impact CID Adapter Server performance.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
133
DBMOD=database-name
Description
Required. Specifies the name of the database accessed by the system.
Format
6-character database name.
DISPLAY_OPTIONS=YES or NO
Description
(Optional) Specifies whether to display all initialization options and their
values.
Default
NO
Options
YES
Display all initialization options and their values. YES can also
be specified by Y/y/T/t/1.
NO
Do not display the initialization options. NO can also be
specified by N/n/F/f/0.
LOGON_EXIT=xxxxxxxx
Description
(Optional) Specifies the name of a user-written logon exit load module that is
called whenever the CID Adapter Client connects to the CID Adapter Server.
Format
1–8 characters.
Consideration If this parameter is not specified, a logon exit will not be called.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
134
MAX_RECORDS_LIMIT=nnnnnnnnn
Description
(Optional) Specifies the maximum number of reads that are allowed to be used
to retrieve data during a query.
Default
0
Options
0–2,147,483,647
Considerations
♦
If the number specified is zero, then the number of reads allowed are
unlimited.
♦
The CID Adapter Client component can set only a lower limit than the
global limit in effect in the CID Adapter Server component.
The limit in effect is computed according to the following table:
Client
Server
Description
0
0
Unlimited reads.
0
n
Limit is the CID Adapter Server global
limit of n.
m
0
Limit is the CID Adapter Client limit of
m.
m
n
Limit is minimum of m, n.
MULTI=YES or NO
Description
(Optional) Specifies whether multiple system wide databases are being used.
Default
NO
Options
YES
The system serves multiple system wide databases.
NO
The system does not serve multiple system wide databases.
OPERATOR=OPERnn
Description
(Optional) Specifies an OpenVMS operator allowed to shut down the system.
Default
CENTRAL
Options
OPER1–OPER12
CENTRAL
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
135
OPT_EXPLAIN=YES or NO
Description
(Optional) Specifies whether to enable the explanation feature of the
optimizer.
Default
NO
Options
YES
Enable the explanation facility. YES can also be specified by
Y/y/T/t/1.
NO
Do not enable the explanation facility. NO can also be
specified by N/n/F/f/0.
Consideration Typically, this parameter is only turned on in a test system. When debugging
new queries, this feature can help you understand query performance.
PERFORMANCE_STATS=YES or NO
Description
(Optional) Specifies whether OpenVMS-specific performance statistics are to
be collected by the CID Adapter Server.
Default
NO
Options
YES
The CID Adapter Server will collect OpenVMS-specific statistics.
NO
The CID Adapter Server will not collect OpenVMS-specific
statistics.
PREFIX=nnn
Description
(Optional) Specifies the prefix associated with the database.
Format
1–3 character prefix name.
Consideration If DBMOD prefixing is used, this parameter must be included in the init file.
SHUTDOWN_PASSWORD=xxxxxxxx
Description
(Required) Specifies the password that validates CID Adapter Server shutdown
commands from the CID Adapter Client.
Default
dba
Format
1–8 printable characters.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
136
SHUTDOWN_USER=xxxxxxxx
Description
(Required) Specifies the user name that validates CID Adapter Server shutdown
commands from the CID Adapter Client.
Default
dba
Format
1–8 printable characters.
STATS=option
Description
(Optional) Enables statistics accumulation.
Default
NO
Options
YES
Enable the statistics facility. YES can also be specified by
Y/y/T/t/1.
NO
Do not enable the statistics facility. NO can also be specified
by N/n/F/f/0.
SYSTEM
Accumulates and displays system level statistics.
LUW
Accumulates and displays system level statistics and logical
unit of work (LUW) level statistics.
FUNCTION
Accumulates and displays system level statistics, LUW level
statistics, and function level statistics.
Consideration The statistics facility can help you understand system performance. See
"Statistics considerations" on page 85 for examples.
SYSTEM
Description
(Optional) Indicates that the application is run as a system-wide process,
generally used in conjunction with system-wide databases.
Default
N
Options
YES
Server process is treated as a system-wide application. YES can
also be specified by Y/y/T/t/1.
NO
Server process is treated as a group-wide application. NO can
also be specified by N/n/F/f/0.
Consideration The SYSTEM=Y option should be used with system-wide and multi-system wide
PDM databases. The SYSTEM=N option should be used with group-wide
databases.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
137
TCP_HOSTNAME_LOOKUP=YES or NO
Description
(Optional) Specifies whether there will be a host name lookup for the IP
address whenever a TCP/IP connection is established.
Default
NO
Options
YES
Enable the lookup. YES can also be specified by Y/y/T/t/1.
NO
Do not enable the lookup. NO can also be specified by
N/n/F/f/0.
Consideration The lookup will use either a TCP/IP host file or the TCP/IP resolver.
TCPPORT=nnnn
Description
(Optional) Specifies the TCP port used by the CID Adapter Server for
communication with the CID Adapter Client.
Format
4-digit TCP port number.
Considerations
♦
This value must be initialized but can also be set using the command line
option -p followed by the 4-digit port number. Command line options will
override initialization file values. If both values are missing, the CID
Adapter Server attempts to determine the value using the fall back service,
HUBDRIVER. Absence of a value results in an error message.
♦
The csv1port utility can be used to verify that no other application is
currently using a port. Execute the following command to run csv1port:
@V1HUB_COMS:CSV1PORT <port-number>
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
138
TRACE_OPTIONS=nnn,nnn-nnn…
Description
(Optional) If specified, this parameter turns on debug tracing and specifies one
or more tracing options to be used within the CID Adapter Client component.
This is a Cincom Technical Support parameter.
Default
The parameter is not present (no tracing).
Options
8–239
Format
One or more numbers or number ranges, separated by commas
(1, 10–14, 17).
Consideration Tracing is usually turned on at the recommendation of Cincom Technical
Support. Support provides the specified numbers corresponding to specific
tracing actions. When enabled, some trace options generate significant output
and can degrade performance. All trace output is written to a file pointed to
by the logical name CSI_TRACE_FILE. If the name is not defined, output is
written to the SUP1DRVR.ERR file.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
139
Coding the optional user logon exit (OpenVMS)
A user exit can be coded to perform user validation during user connection.
The intent is to permit security checking before allowing a user access to the
PDM. The exit is called at three points:
♦
Whenever a user connects to the driver
♦
Whenever a shutdown request is made using reply/pend=nn
♦
During shutdown to do any necessary user exit cleanup
The logon exit is loaded during CID Adapter Server initialization. It is called by
all of the CID Adapter Server processes for connection. The parameters on the
connect and shutdown exit calls are:
♦
Address of 9-character database name (null terminated).
♦
Address of 9-character user name (null terminated).
♦
Address of 9-character password from logon (null terminated).
♦
Address of 17-character name of host that issues logon (null terminated).
♦
Address of a full word (initially zero) that can be used to store any
user-defined context. This value will then be accessible on all future calls.
♦
Address of 127-character area that can be used to return an error message
to the CID Adapter Server. The message must have a null byte at the end.
♦
Address of full word that contains 0 for a shutdown request and 1 for a
connection request.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
140
The termination call is made once, near the end of shutdown processing. When
this call is made, all connections have been broken and all CID Adapter Server
processes are detached. The parameters on the termination exit call are:
♦
Zero.
♦
Zero.
♦
Zero.
♦
Zero.
♦
Address of a full word (initially zero) that can be used to store any userdefined context.
♦
Address of a 127-character area that can be used to return an error
message to the CID Adapter Server. The message must have a null byte at
the end.
♦
Address of a full word that contains the binary integer 2 for system
termination.
When the logon exit is called, the thread is signed on to the PDM. Any PDM
database function (except SINON and SINOF) can be executed.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the OpenVMS CID Adapter Server
141
Tailoring the UNIX CID Adapter Server
After installing a UNIX CID Adapter Server, you must perform certain sitespecific tasks to set up a CID Adapter Server for a PDM database. During the
installation process (documented in the SQL Access for SUPRA Server PDM
Installation Guide, P25-9500) you chose an installation directory for the UNIX
CID Adapter Server. After installation, this directory should contain the
directory, CIDAdapterServer_nnnn, where nnnn is the service level.
Tailoring the CID Adapter Servers for PDM databases on UNIX includes the
following required and optional tasks for each database:
♦
Defining SUPRA PDM environment variables and logical names
♦
Defining the CID Adapter Server startup procedure
♦
Defining TCP/IP to UNIX
♦
Defining your initialization file parameters
♦
(Optional) Defining the CID Adapter Extensions XML file
♦
(Optional) Coding the user logon exit
The s1_adapter_setup script, documented in "Defining CID Adapter Server
environment variables" on page 143, performs all but the first of the above
tasks by requesting information from the user interactively. These tasks are
discussed individually in later sections of this chapter.
Because the files created by the adapter setup script use the environment
variable CSI_ADAPTER_SERVICE_LEVEL, it is not necessary to run the adapter
setup script when upgrading to a new CID Adapter Server service level. It is
only necessary to change the value of CSI_ADAPTER_SERVICE_LEVEL prior to
running the adapter-name_run or adapter-name_stop scripts. You may,
however, choose not to set the CSI_ADAPTER_SERVICE_LEVEL environment
variable. In this case, the scripts will use the value of the service level at the
time of the setup. Upgrades to new service levels will require that scripts be
modified with the new service level value, either by running the adapter setup
script again, or editing the run and stop scripts for each CID Adapter Server.
Defining SUPRA PDM environment variables and logical names
The UNIX environment variable CSIRESOURCES and the logical names for the
PDM system for which you intend to set up or start CID Adapter Servers must be
defined prior to running the s1_adapter_setup, adapter-name_run, or adaptername_stop scripts. This is usually accomplished by running the pdm_startup
script generated by the s1_install script provided on the UNIX SUPRA Server
PDM installation media. The user running the s1_adapter_setup script and
starting a CID Adapter Server must have access privileges to these group and
system-wide logical names. For additional information, refer to the SUPRA
Server PDM System Administration Guide (UNIX), P25-0130.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
142
Defining CID Adapter Server environment variables
The UNIX environment variable SHLIB_PATH must be defined prior to running
the s1_adapter_setup script:
Environment
variable
SHLIB_PATH
Command
SHLIB_PATH= \
${SHLIB_PATH}:/adapter-install-directory/lib;
export SHLIB_PATH
Running the s1_adapter_setup script
The adapter setup script, s1_adapter_setup, interactively guides the user
through the process of setting up CID Adapter Servers for one or more
databases. Each CID Adapter Server is associated with exactly one PDM
database. Each CID Adapter Server is given a name, the DBMOD name plus an
optional extension. A TCP/IP port number is assigned to the CID Adapter Server
and all of the files associated with the CID Adapter Server are created. Each
file and service associated with the CID Adapter Server is preceded by the
adapter name, allowing multiple CID Adapter Servers to reside in the same
directory, as well as allowing easy identification of the CID Adapter Server files
associated with a particular database.
After the adapter setup script creates the files for a particular database, these
files can safely be customized with additional parameters or shell instructions
as necessary. The adapter setup script may be run multiple times for the same
CID Adapter Server in order to modify the parameters. The files created the
first time it is run will be edited on subsequent runs. This preserves any
modifications made outside the script.
The adapter setup script may be run using the following command:
adapter-install-directory/CIDAdapterServer_nnnn/s1_adapter_setup
Where nnnn is the service level of the CID Adapter Server. The script will
attempt to create the following link to the CIDAdapterServer_nnnn directory:
/supra1/adapters/nnnn
This provides a known path to the installed service level. If /supra1 is not
present on the system, the script will attempt to create it. If this fails, the
script will exit, requesting that you create this directory before proceeding.
The adapter setup script uses menus and prompts to request information from
the user. Default values for prompts are displayed at the end of a prompt
enclosed within square brackets ( [default-value] ). Default values are selected
by pressing ENTER without having typed any input value.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
143
The adapter setup script can be canceled at any time by pressing CTRL-C. The
script may then be re-run to continue setting up CID Adapter Servers. Some
errors cause the script to exit. Once the problem reported by the script is
corrected it may be re-run to continue setting up CID Adapter Servers.
The files created by the adapter setup script will reside in the PDM system
directory, /supra1/<pdm-system-name>, of the currently active PDM System,
determined by the value of the CSI_PDMID logical name, and will be owned by
the current user. If this directory does not exist, the script attempts to create
it. If this fails, the script will exit, requesting that you create this directory
before proceeding.
The files created by the s1_adapter_setup script are listed in the following
table:
File name
Description
<adapter-name>.init
CID Adapter Server initialization parameter file
<adapter-name>_run
A script to run the CID Adapter Server
<adapter-name>_stop
A script to stop the CID Adapter Server
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
144
The CID Adapter Server setup script requests the information listed in the
following table:
Item
Description
DBMOD name
Choose a PDM DBMOD name from the menu. This
will be used as the CID Adapter Server name.
Extension
An optional 4 character extension used to uniquely
identify a CID Adapter Server if there is more than
one DBMOD with the same name in the system.
TCP/IP port number
The port number is assigned by searching the
/etc/services file for a service with the default
port number, increasing the default port number
by one until an unused port is found. The port
number can then be overridden if desired. The
port number will again be verified to be unused
and a new service with the name adapter-name
will be added to the /etc/services file. If this fails,
a message is displayed providing the line that
should be added to the /etc/services file. A
duplicate entry is also added to the file
/supra1/adapters/services, which is also checked
in the same manner as described for the
/etc/services file. The port number is then used in
the SQL Access REGISTER FOREIGN DATABASE
statement.
MAX_RECORDS_LIMIT
This CID Adapter Server initialization parameter
controls the number of records that are allowed to
be read by a single query. The default value of 0
allows unlimited reading.
At the end of an adapter setup session, the script will ask if you want to start
the adapter that has been created. If you are installing SQL Access, Cincom
recommends that you start the CID Adapter Server that you created so that the
remaining installation steps on the SQL Access Server machine can be
completed.
The CID Adapter Server can be started by entering the following command at
the command prompt or by adding the command to script that is run at system
startup time:
/supra1/pdm-system-name/adapter-name_run
To stop an adapter use the following command:
/supra1/pdm-system-name/adapter-name_stop
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
145
After creating a CID Adapter Server for a database, it is possible to customize it
by adding parameters to the initialization parameter file, extending the
schema by adding a CID Adapter Extensions XML file, or customizing the scripts.
All of the customizations made to a CID Adapter Server will be preserved if the
s1_adapter_setup script is run again, after the initial setup. This may be
desirable in order to change any of the values requested by the script, but is
not necessary when upgrading to a new CID Adapter Server service level.
The files created or used by a running CID Adapter Server are listed here:
File name
Description
<adapter-name>.bsc
CID Adapter Server bound schema file. This file is
written automatically by the CID Adapter
Coordinator and, if present on subsequent CID
Adapter Server runs, is read by the CID Adapter
Coordinator to build the internal database schema
instead of making requests to PDM.
<adapter-name>.log
CID Adapter Server log file. This file will contain
logged output from the CID Adapter Coordinator
as well as all of the CID Adapter Server processes.
These files will be written to or read from the PDM system directory.
The output from an s1_adapter_setup session that created a CID Adapter Server
for the sample BURRYS database is shown in Appendix B.
The following sections provide details of the tailoring steps provided by the
s1_adapter_setup script for those who want to customize the CID Adapter
Servers created by the s1_adapter_setup script.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
146
Defining TCP/IP to UNIX
Before starting the CID Adapter Server, add a line to the /etc/services file for
the CID Adapter Server as follows:
adapter-name port-number/tcp
The s1_adapter_setup script will attempt to create this service in
/etc/services. If this is not possible due to insufficient privileges, the script
will create the service in /supra1/adapters/services. This simply documents
the use of the port number so that future adapters created by
s1_adapter_setup will not use a port number that is already in use.
The adapter name can be anything, but it is recommended that it include the
dbmod name in order to identify it later. The CID Adapter Server does not use
the service name. The port number must be provided either using the –p option
on the command line or by using the TCPPORT initialization parameter. The
port number along with the machine name of the CID Adapter Server machine
are also required for the SQL Access REGISTER FOREIGN DATABASE statement in
order to identify which PDM database to access.
The fallback service, HUBDRIVER, is used only when the TCPPORT initialization
parameter is not defined and the –p command line argument specifying the
port number is not present when starting the CID Adapter Server. Using the
HUBDRIVER service, the CID Adapter Server is limited to accessing a single
database.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
147
Defining the CID Adapter Server startup procedure (UNIX)
To define the CID Adapter Server startup procedure, you must define the
location of the CID Adapter Server initialization file and the message file. You
may optionally define the Adapter Extensions XML file location if applicable for
your installation. Define the following UNIX environment variables:
UNIX environment
variable
Description
CSI_INIT_FILE
The path and file name of the initialization file.
CSI_MESSAGE_FILE
The path to the file containing error message
templates. Typically, this will be a file called
sup1drvr.msg in a subdirectory of the install
directory called admin/msg/En_US.
CSI_XML_SCHEMA
Optional. The path and file name of the CID
Adapter Extensions XML file.
CSI_TRACE_FILE
The path and file name that contain all trace
output.
CSI_SERVER_SCHEMA
The name of a bound schema file (contains the
information about the database being accessed).
If the file does not exist, the CID Adapter
Coordinator process will generate it. The file will
automatically be updated if the database is
modified. If the environment variable
CSI_SERVER_SCHEMA is not set, the CID Adapter
Server looks for bound schema information in a
CSI_SERVER_SCHEMA file, which is located in the
current working directory for the process.
TRACE_OPTIONS
A string containing the tracing options.
If the required terms are undefined in the environment, the CID Adapter Server
looks for the required information in files with the same name as the
corresponding environment variable name (a file called CSI_INIT_FILE in the
startup directory).
After all of the required definitions are in place, the CID Adapter Server may be
invoked in the background as follows:
csiserver [-p tcpport] [trace options]
&
The CID Adapter Server executable must appear in your path or the path must
be explicitly defined in the invocation.
The adapter-name_run script created by s1_adapter_setup will execute this
command.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
148
Defining the initialization parameters (UNIX)
After defining your CID Adapter Server startup procedure, you must now define
your initialization parameters. The CID Adapter Server init file is pointed to by
the environment variable CSI_INIT_FILE. The <adapter-name>.init file will be
created by the s1_adapter_setup script for each adapter. When you code the
init file, use the following general coding rules:
♦
Lines can be blank.
♦
All comment lines must begin with a pound sign (#).
♦
Parameters can begin anywhere on a line but must start and end on one
line.
♦
There can be no space between a parameter keyword and its subsequent
equals sign (=). However, there can be spaces after the equals sign.
♦
Keywords are case-insensitive; they can be lowercase, uppercase, or a
combination of both.
♦
Numbers can be specified as:
Representation
Numeric base
0xnnnn
Hexadecimal
0nnnn
Octal
Nnnn
Decimal
♦
Enclose a text string in single quotes (‘text string’) or double quotes (“text
string”) if it contains whitespace characters (space, tab, newline, return,
form feed). If a text string contains a single quote, enclose the string in
double quotes. If a string contains a double quote, enclose the string in
single quotes.
♦
Boolean=false can be specified by the following character options:
N/n/F/f/0.
Boolean=true can be specified by the following character options:
Y/y/T/t/1.
Characters following one of these option characters are ignored (“not” and
“N1” would be treated as Boolean=false).
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
149
Server init file parameters (UNIX)
The CID Adapter Server init file parameters on UNIX are listed here.
ALLOW_CORE_DUMP=TRUE or FALSE
Description
(Optional) Specifies whether a core dump will be allowed. This is a Cincom
Technical Support parameter.
Default
False
Options
True
Allows a core dump to occur.
False
Does not allow a core dump to occur.
Consideration By default, the CID Adapter Server component does not allow core dumps to be
written when there is an internal problem (segmentation violation). If the CID
Adapter Server component crashes, Cincom Technical Support may request that
this parameter be set so that a core dump can be written for problem analysis.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
150
BIND_SCHEMA=YES or NO
Description
(Optional) Specifies whether bound schema support is enabled.
Default
YES
Options
YES
Enable bound schema support. YES can also be specified by
Y/y/T/t/1.
NO
Disable bound schema support. NO can also be specified by
N/n/F/f/0.
Considerations
♦
When the BIND_SCHEMA parameter is set to YES, the CID Adapter Server
will first look for a bound schema from a prior execution. If it exists, it will
verify that the PDM Directory has not changed since the bound schema file
was written, and, if not, will proceed to load the bound schema into
memory. If the bound schema does not exist or the PDM Directory has
changed since the bound schema file was written, the schema information
will be loaded directly from the PDM Directory, and, when complete, a
bound schema file will be written.
♦
The bound schema file contains the foreign key information from the
Adapter Extensions XML file but does not contain the CID Adapter View or
Field and Type information. When a change is made to the foreign key
information in the CID Adapter Extensions XML file, it is not automatically
detected by the CID Adapter Server. If the BIND_SCHEMA parameter is set
to YES, it is necessary to delete the bound schema file in order to force the
schema to be loaded directly from the PDM Directory. This will cause the
foreign key information to be refreshed.
♦
When the BIND_SCHEMA parameter is set to NO, the CID Adapter Server will
always load the schema information directly from the PDM Directory and
will not write a bound schema file.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
151
BYPASS_OPT_CTRL_LINKPATH=YES or NO
Description
(Optional) Specifies whether to bypass the optimizer direct lookup and
linkpath processing.
Default
NO
Options
YES
Bypass; do not allow direct and linkpath access. YES can also
be specified by Y/y/T/t/1.
NO
Do not bypass; allow direct and linkpath access. NO can also
be specified by N/n/F/f/0.
Consideration Bypassing is usually used only for debugging specific optimizer problems.
Bypassing can severely impact CID Adapter Server performance.
BYPASS_OPT_INDEX=YES or NO
Description
(Optional) Specifies whether to bypass the optimizer index processing.
Default
NO
Options
YES
Bypass; do not allow index access. YES can also be specified by
Y/y/T/t/1.
NO
Do not bypass; allow index access. NO can also be specified by
N/n/F/f/0.
Consideration Bypassing is usually used only for debugging specific optimizer problems.
Bypassing can severely impact CID Adapter Server performance.
BYPASS_QUAL=YES or NO
Description
(Optional) Specifies whether to bypass qualification on the CID Adapter Server.
Default
NO
Options
YES
Bypass; do not perform qualification on the CID Adapter Server.
YES can also be specified by Y/y/T/t/1.
NO
Do not bypass; perform qualification on the CID Adapter Server.
NO can also be specified by N/n/F/f/0.
Consideration Bypassing is usually used only for debugging specific optimizer problems.
Bypassing can severely impact CID Adapter Server performance.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
152
DBMOD=database-name
Description
Required. Specifies the name of the database accessed by the system.
Format
6-character database name.
DISPLAY_OPTIONS=YES or NO
Description
(Optional) Specifies whether to display all initialization options and their
values.
Default
NO
Options
YES
Display all initialization options and their values. YES can also
be specified by Y/y/T/t/1.
NO
Do not display the initialization options. NO can also be
specified by N/n/F/f/0.
LOGON_EXIT=xxxxxxxx
Description
(Optional) Specifies the name of a user-written logon exit load module that is
called whenever the CID Adapter Client connects to the CID Adapter Server.
Format
1–8 characters.
Consideration If this parameter is not specified, a logon exit will not be called.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
153
MAX_RECORDS_LIMIT=nnnnnnnnn
Description
(Optional) Specifies the maximum number of reads that are allowed to be used
to retrieve data during a query.
Default
0
Options
0–2,147,483,647
Considerations
♦
If the number specified is zero, then the number of reads allowed are
unlimited.
♦
The CID Adapter Client component can set only a lower limit than the
global limit in effect in the CID Adapter Server component.
The limit in effect is computed according to the following table:
Client
Server
Description
0
0
Unlimited reads.
0
n
Limit is the CID Adapter Server global limit of n.
M
0
Limit is the CID Adapter Client limit of m.
M
n
Limit is minimum of m, n.
MULTI=YES or NO
Description
(Optional) Specifies whether multiple system wide databases are being used.
Default
NO
Options
YES
The system serves multiple system wide databases.
NO
The system does not serve multiple system wide databases.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
154
OPT_EXPLAIN=YES or NO
Description
(Optional) Specifies whether to enable the explanation feature of the
optimizer.
Default
NO
Options
YES
Enable the explanation facility. YES can also be specified by
Y/y/T/t/1.
NO
Do not enable the explanation facility. NO can also be
specified by N/n/F/f/0.
Consideration Typically, this parameter is only turned on in a test system. When debugging
new queries, this feature can help you understand query performance.
PREFIX=nnn
Description
(Optional) Specifies the prefix associated with the database.
Format
1–3 character prefix name.
Consideration If DBMOD prefixing is used, this parameter must be included in the init file.
SHUTDOWN_PASSWORD=xxxxxxxx
Description
(Required) Specifies the password that validates CID Adapter Server shutdown
commands from the CID Adapter Client.
Default
dba
Format
1–8 printable characters.
SHUTDOWN_USER=xxxxxxxx
Description
(Required) Specifies the user name that validates CID Adapter Server shutdown
commands from the CID Adapter Client.
Default
dba
Format
1–8 printable characters.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
155
STATS=option
Description
(Optional) Enables statistics accumulation.
Default
NO
Options
YES
Enable the statistics facility. YES can also be specified by
Y/y/T/t/1.
NO
Do not enable the statistics facility. NO can also be specified
by N/n/F/f/0.
SYSTEM
Accumulates and displays system level statistics.
LUW
Accumulates and displays system level statistics and logical
unit of work (LUW) level statistics.
FUNCTION
Accumulates and displays system level statistics, LUW level
statistics, and function level statistics.
Consideration The statistics facility can help you understand system performance. See
"Statistics considerations" on page 85 for examples.
TCP_HOSTNAME_LOOKUP=YES or NO
Description
(Optional) Specifies whether there will be a host name lookup for the IP
address whenever a TCP/IP connection is established.
Default
YES
Options
YES
Enable the lookup. YES can also be specified by Y/y/T/t/1.
NO
Do not enable the lookup. NO can also be specified by
N/n/F/f/0.
Considerations
♦
The lookup will use either a TCP/IP host file or the TCP/IP resolver.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
156
TCPPORT=nnnn
Description
(Optional) Specifies the TCP port used by the CID Adapter Server for
communication with the CID Adapter Client.
Format
4-digit TCP port number.
Considerations
♦
This value must be initialized but can also be set using a command line
option -p followed by the 4-digit port number. Command line options
override initialization file values. If both values are missing, the CID
Adapter Server will attempt to determine the value using the values
entered for the HUBDRIVER service listed in the /etc/services file.
Absence of a value results in an error message.
♦
The csv1port utility can be used to verify that no other application is
currently using a port. Execute the following command to run csv1port:
csv1port <port-number>
TRACE_OPTIONS=nnn,nnn-nnn…
Description
(Optional) If specified, this parameter turns on debug tracing and specifies one
or more tracing options to be used within the CID Adapter Client component.
This is a Cincom Technical Support parameter.
Default
The parameter is not present (no tracing).
Options
8–239
Format
One or more numbers or number ranges, separated by commas
(1, 10–14, 17).
Consideration Tracing is usually turned on at the recommendation of Cincom Technical
Support. Support provides the specified numbers corresponding to specific
tracing actions. When enabled, some trace options generate significant output
and can degrade performance. All trace output is written to a file pointed to
by the environment variable CSI_TRACE_FILE. If the name is not defined,
output is written to a default log file. Tracing can also be configured via
command line argument. Any command line data not preceded by a legal
option character is assumed to be trace control data.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
157
Coding the optional user logon exit (UNIX)
A user exit can be coded to perform user validation during user connection.
The intent is to permit security checking before allowing a user access to the
PDM. The exit is called at two points:
♦
Whenever a user connects to the driver
♦
During shutdown to do any necessary user exit cleanup
The logon exit is loaded during CID Adapter Server initialization. It is called by
all of the CID Adapter Server processes for connection. The parameters on the
connect and shutdown exit calls are:
♦
Address of 9-character database name (null terminated).
♦
Address of 9-character user name (null terminated).
♦
Address of 9-character password from logon (null terminated).
♦
Address of 17-character name of host that issues logon (null terminated).
♦
Address of a full word (initially zero) that can be used to store any userdefined context. This value will then be accessible on all future calls.
♦
Address of a 127-character area that can be used to return an error
message to the CID Adapter Server. The message must have a null byte at
the end.
♦
Address of a full word that contains 0 for a shutdown request and 1 for a
connection request.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
158
The termination call is made once, near the end of shutdown processing. When
this call is made, all connections have been broken and all CID Adapter Server
processes are detached. The parameters on the termination exit call are:
♦
Zero.
♦
Zero.
♦
Zero.
♦
Zero.
♦
Address of a full word (initially zero) that can be used to store any userdefined context.
♦
Address of a 127-character area that can be used to return an error
message to the CID Adapter Server. The message must have a null byte at
the end.
♦
Address of a full word that contains the binary integer 2 for system
termination.
When the logon exit is called, the thread is signed on to the PDM. Any PDM
database function (except SINON and SINOF) can be executed.
Administration Guide, P25-9501-04
Chapter: 4. Tailoring the CID Adapter Server
Section: Tailoring the UNIX CID Adapter Server
159
5. Tailoring the CID Adapter Client
Overview
The Cincom Integrated Data (CID) Adapter Client component is installed into
the SQL Access for SUPRA Server PDM (SQL Access) environment. It is started
automatically by the SQL Access Master process when the first connect request
is made for a PDM database or CICS VSAM system. Each PDM database or CICS
VSAM system connection will be serviced by a separate CID Adapter Client
process.
%ORDB% refers to the directory identified by the ORDB environment variable.
This will be set to the installation directory.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Overview
160
Tailoring the Windows CID Adapter Client component
After you have installed the CID Adapter Server components, you must perform
certain site-specific tailoring tasks on the CID Adapter Client components.
The initialization parameters for the CID Adapter Client component are in the
sup1drvr.ini file. This file is stored in the %ORDB%\admin directory. You can
use this file to define default parameter values for this installation. You can
also use this file to define parameter values for a specific database.
Before making any modifications to the parameter values, be sure to make a
copy of the sup1drvr.ini file. Any changes should be made only after careful
consideration.
You can set overriding parameter values for all parameters in the following
places:
♦
The batch script supra1.bat in the %ORDB% directory
♦
The environment inherited from the SQL Access Master process when it
starts
Settings in the batch script override those in the SQL Access Master process
environment; settings in the SQL Access Master process environment override
those in the sup1drvr.ini file.
The CID Adapter Client component looks for parameter values in all of the
following locations in the following order:
1. %ORDB%\admin\sup1drvr.ini
2. Environment inherited from the SQL Access Master process
3. %ORDB%\supra1.bat
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the Windows CID Adapter Client component
161
Defining parameter values
To set a parameter value in the sup1drvr.ini file, use the following format:
parameter-name=value
Example
schema_segment_size=160000
To set a parameter value in the environment inherited from the SQL Access
Master process or in the supra1.bat shell script, use the following format:
ORDB_V1_PARAMETER-NAME=value
Example
ORDB_V1_SCHEMA_SEGMENT_SIZE=160000
Defining parameter values for a specific PDM database
You can set parameters for a specific PDM database in all three locations: ini
file, environment, and batch script. These parameter values override the
parameter values for the installation.
To do this, concatenate the literal ‘db_’ with the name of the database
followed by the name of the parameter and assign a value to the concatenated
variable name. The concatenated name must be in the following format:
db_pdm-database-name_parameter-name
The following examples use payroll as the PDM database name:
♦
To set a database specific parameter value in the sup1drvr.ini file, use the
following format:
db_pdm-database-name_parameter-name=value
Example
db_payroll_schema_segment_size=160000
♦
To set a database specific parameter value in the environment inherited by
the SQL Access Master process or in the supra1.bat shell script, use the
following format:
ORDB_V1_DB_PDM-DATABASE-NAME_PARAMETER-NAME=value
Example
ORDB_V1_DB_PAYROLL_SCHEMA_SEGMENT_ SIZE=160000
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the Windows CID Adapter Client component
162
Summary of CID Adapter Client component parameters
The following parameters define the system values for the CID Adapter Client
component. The specified order of the parameters is irrelevant. The following
table shows where you can specify each parameter. Keep in mind that the
shell script overrides the environment, which overrides the sup1drvr.ini file.
Parameter
db_pdm-database-name
sup1drvr.ini
Environment
database-type.bat
X
X
X
dbname
X
display_options
X
X
X
driver_directory
X
X
init_file
X
X
Lang
X
X
X
load_path
X
X
X
max_rcv_pdu
X
X
X
max_records_limit
X
X
X
oid_cache_max
X
X
X
read_only
X
X
X
schema_segment_address
X
X
X
schema_segment_size
X
X
X
X
X
trace
When setting a parameter value as an environment variable, you must set the
value before the SQL Access Master process is started in order for it to take
effect. A value can be set in the batch script at any time.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the Windows CID Adapter Client component
163
db_pdm-database-name=
Syntax
db_pdm-database-name=[dbmod=DBMOD,] node,tcpip,tcp-port-no
Description
(Optional) Specifies the network information required to connect the CID
Adapter Client component to a CID Adapter Server component. This information
may be alternatively specified when registering the CID Foreign Database
instead of specifying it here. This parameter overrides the information entered
when registering the CID Foreign Database.
Options
pdm-database-name
The name specified in the DBM parameter in CSIPARM of the
MVS SUPRA Server PDM database or the DBMOD name for
OpenVMS and UNIX platforms. This parameter must be unique
for a SQL Access Server. Therefore, if the dbmod is qualified
by a prefix in SUPRA PDM, you can add the prefix before the
DBMOD name separated by an underscore (_) in order to make
it unique (for example, 001_MRPDBO). The name is case
sensitive, which usually implies that it is specified in all
uppercase characters.
Alternately, if the optional dbmod clause is being used to
specify the value of the DBM or DBMOD parameter, an alias may
be specified in the pdm-database-name.
dbmod
An OPTIONAL identifier that may be used to specify the value
of the DBM parameter in CSIPARM of the MVS SUPRA Server PDM
database or the DBMOD name for OpenVMS and UNIX platforms.
The name is case sensitive, which usually implies that it is
specified in all uppercase characters. If this identifier is used,
then an alias may be specified in the pdm-database-name. This
identifier is used together with alias names to allow the CID
Adapter Client component to concurrently connect to several
PDM databases that have identical DBM or DBMOD names.
node
The host name where the PDM is running.
tcp-port-no
The TCP/IP port number that the CID Adapter Server
component listener process is listening on for connections from
any CID Adapter Client component.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the Windows CID Adapter Client component
164
Considerations
Example
♦
This database connection parameter must be set for each database to
which the CID Adapter Client component is to connect.
♦
The same value specified for TCP_LISTEN_PORT in the CID Adapter Server
component parameter information must be specified for tcp-port-no. The
port numbers must be identical for the connection to be successful.
db_payroll=fred,tcpip,5010
db_CENTPDM=ER84AP3,tcpip,5020
db_001_MRPDBO=BB12ZX3,tcpip,6001
dbname=pdm-database-name
Description
(Optional) Specifies the name of the PDM database to the CID Adapter Client
component for use with database-specific parameters.
Format
The name used in the CID Foreign Database registration statement.
Considerations
Example
♦
This parameter allows the PDM database name to be part of databasespecific parameter settings. Database-specific formats only work if the CID
Adapter Client is supplied with the name of the database via this
parameter.
♦
This parameter can only be set in the supra1.bat script in %ORDB%. When
this script is invoked to start the CID Adapter Client component, the pdmdatabase-name is specified on the command line that invoked the script,
with the name in %1.
♦
Setting this parameter in the supra1.bat script allows database specific
parameter settings to take effect for parameters that need to be read
before the sup1drvr.ini file is opened (display_option, driver_directory,
init_file, and trace).
At the top of the supra1.bat script, insert the following line:
set ORDB_V1_DBNAME=%1
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the Windows CID Adapter Client component
165
display_options=TRUE or FALSE
Description
(Optional) Specifies whether the CID Adapter Client component parameters
and their current valid values (as ascertained from the shell script
environment, and init file) will be listed in the sup1drvr.err file.
Default
false
Options
true Parameters and values will be listed.
false Parameters and values will not be listed.
Consideration A listing of valid parameter values can be useful since a parameter value
assigned in the sup1drvr.ini file can be overridden by the environment and the
shell script.
driver_directory=path-name
Description
(Optional) Specifies the directory to which the CID Adapter Client component
will switch when it begins execution. This is the directory where the
sup1drvr.err file will be created for error reporting.
Default
Directory where the SQL Access Master process started.
Consideration This parameter must be set as an environment variable or in the shell script.
init_file=path-name
Description
(Optional) Specifies a directory containing an alternate sup1drvr.ini file (other
than the one in %ORDB%\admin).
Default
%ORDB%\admin
Options
User-defined path name
Consideration This parameter must be set as an environment variable, in the shell script, or
in the registry.
lang=directory-name
Description
(Optional) Specifies the source directory for the sup1drvr.msg file containing
error and warning messages issued by the CID Adapter Client component.
Default
En_US
Consideration The default En_US directory is in %ORDB%\admin\msg\.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the Windows CID Adapter Client component
166
load_path=path-name
Description
(Optional) Specifies the dynamic library load path. This is a Cincom Technical
Support parameter.
Default
%ORDB%\lib
Format
User-defined path
Considerations
♦
This parameter is usually set at the request of Cincom Technical Support.
In such a case, the value can be set to a colon-separated list of directory
paths where the CID Adapter Client component searches for network
communications modules. This allows testing of TCP/IP related issues in a
separate directory.
♦
In the absence of a Support request, there is usually no need to set this
parameter as long as the directory containing the CID Adapter Client shared
objects is included in the PATH environment variable.
max_rcv_pdu=nnnnn
Description
(Optional) Specifies the maximum size of the protocol unit that the CID
Adapter Client component can receive from the CID Adapter Server component.
Default
8192 (bytes)
Options
≥ 1024 (bytes)
Consideration This parameter may be used to tune the CID Adapter Client/Server
communications. Making the max_rcv_pdu parameter larger will allow more
PDM data records to be sent from the CID Adapter Server to the CID Adapter
Client in a single TCP/IP message, which may improve performance.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the Windows CID Adapter Client component
167
max_records_limit=nnnnn
Description
(Optional) Specifies the maximum number of reads that are allowed to be used
to retrieve data during a query.
Format
Decimal number between 0 - 2,147,483,647 (zero represents unlimited reads).
Default
0
Options
0–2,147,483,647
Considerations
♦
If the number specified is zero, the number of reads allowed is unlimited.
♦
The CID Adapter Client component can only set a lower limit than the
global limit in effect in the CID Adapter Server component.
See the definition of the MAX_RECORDS_LIMIT parameter for your CID Adapter
Server platform.
oid_cache_max=nnnnn
Description
(Optional) Specifies the maximum size of the CID Foreign Database object
identifier cache.
Default
65,536 (bytes)
Format
User-defined value greater than 65,536 bytes.
Consideration If an application uses very large transactions, you may have to increase this
value.
read_only=TRUE or FALSE
Description
(Optional) Specifies whether to restrict the CID Adapter Client component to
read-only operation if this parameter is set to true.
Default
False
Options
True
Read-only operation (inserts, updates, and deletes are
disabled).
False
Inserts, updates, and deletes are enabled.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the Windows CID Adapter Client component
168
schema_segment_address=address-value
Description
(Optional) Specifies an address for the schema segment to be attached to the
CID Adapter Client component virtual address space.
Default
0x02000000
Format
User-defined address in hexadecimal.
Consideration The schema segment is attached at the above default virtual memory address.
schema_segment_size=nnnnnn
Description
(Optional) Specifies the size of the shared memory segment for the shared
schema segment.
Default
150,000
Format
User-defined value (no maximum limit).
Consideration None
trace=nnn,nnn-nnn…
Description
(Optional) If specified, this parameter turns on debug tracing and specifies one
or more tracing options to be used within the CID Adapter Client component.
This is a Cincom Technical Support parameter.
Default
The parameter is not present (no tracing).
Options
8–239
Format
One or more numbers or number ranges, separated by commas
(1, 10–14, 17).
Considerations
♦
Tracing is usually turned on at the recommendation of Cincom Support.
Support provides the specified numbers corresponding to specific tracing
actions. When enabled, some trace options generate significant output and
can degrade performance. All trace output is written to the sup1drvr.err
file.
♦
This parameter can only be set as an environment variable or in the shell
script.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the Windows CID Adapter Client component
169
Tailoring the UNIX CID Adapter Client component
After you have installed the SQL Access Cincom Integrated Data (CID) Adapter
components, you must tailor the CID Adapter Client component to your site.
You do this by defining parameter values, which can be set in three locations:
♦
File sup1drvr.init in the $ORDB/admin directory.
Be sure to make a copy of the sup1drvr.init file before making any
modifications to the parameter values. Any changes should be made only
after careful consideration.
♦
Environment inherited from the SQL Access Master process when it
starts.
Parameter values stored in environment variables must be set before the
SQL Access Master process starts. If you later change an environment
variable parameter, you will need to cycle the SQL Access Master process
for it to take effect.
♦
Shell script pdm-database-name.sh in the $ORDB/admin/ldb directory.
Replace pdm-database-name with the name specified in the DBM
parameter in the CSIPARM file of the MVS SUPRA Server PDM database. It is
the name of the DBMOD when accessing an OpenVMS or UNIX SUPRA Server
PDM database.
A parameter value can be set in the shell script at any time. If you change
a shell script parameter, however, you will need to cycle the CID Adapter
Client.
The CID Adapter Client component looks for parameter values in these
locations in the order listed above. Parameter values are overwritten if found
in multiple locations (e.g., a parameter defined in the SQL Access Master
process environment will be overwritten if that same parameter is also defined
in the shell script).
You can define default parameter values for the installation as well as for a
specific database, if it requires different values. This is described in the
following two sections.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the UNIX CID Adapter Client component
170
Defining parameter values for the installation
To set a parameter value in the sup1drvr.init file, use the following format:
Syntax
parameter-name=value
Example
schema_segment_size=160000
To set a parameter value in the environment inherited from the SQL Access
Master process or in the pdm-database-name.sh shell script, use the following
format:
Syntax
ORDB_V1_PARAMETER-NAME=value
export ORDB_V1_PARAMETER-NAME
Example
ORDB_V1_SCHEMA_SEGMENT_SIZE=160000
export ORDB_V1_SCHEMA_SEGMENT_SIZE
Defining parameter values for a specific database
You can also set parameters for a specific database. These parameter values
override the parameter values for the installation.
These parameters take the same name as the installation parameter they will
override but prepend it with the literal ‘db_’ and the name of the database, as
shown here:
db_pdm-database-name_parameter-name
where:
pdm-database-name is the name of the database for which this parameter
applies
parameter-name is the name of the installation parameter being overridden
See the following two sections for specific examples.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the UNIX CID Adapter Client component
171
Defining a parameter in the sup1drvr.init file
To set a database specific parameter value in the sup1drvr.init file, use the
following format:
db_pdm-database-name_parameter-name=value
For example, to override the "schema_segment_size" parameter for the
"payroll" database, you would use the following:
db_payroll_schema_segment_size=160000
Defining a parameter in the environment or pdm-databasename.sh
To set a database specific parameter value in the environment inherited by the
SQL Access Master process or in the pdm-database-name.sh shell script, use the
following format:
ORDB_V1_DB_PDM-DATABASE-NAME_PARAMETER-NAME=value
export ORDB_V1_DB_PDM-DATABASE-NAME_PARAMETER-NAME
For example, to override the "schema_segment_size" parameter for the
"payroll" database, you would use the following:
ORDB_V1_DB_PAYROLL_SCHEMA_SEGMENT_SIZE=160000
export ORDB_V1_DB_PAYROLL_SCHEMA_SEGMENT_SIZE
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the UNIX CID Adapter Client component
172
Summary of CID Adapter Client component parameters
The following table shows the parameters for the CID Adapter Client
component and where you can define each. The order in which the parameters
are defined is irrelevant.
Keep in mind that the shell script overrides the environment, which overrides
the sup1drvr.init file.
Parameters
Sup1drvr.init
Environment
pdm-database-name.sh
allow_core_dump
X
X
X
db_pdm-database-name
X
X
X
dbname
display_options
X
X
X
X
driver_directory
X
X
init_file
X
X
interproc_key
X
X
X
lang
X
X
X
load_path
X
X
X
max_rcv_pdu
X
X
X
max_records_limit
X
X
X
oid_cache_max
X
X
X
read_only
X
X
X
schema_segment_address
X
X
X
schema_segment_size
X
X
X
schema_table_size
X
X
X
table_segment_address
X
X
X
X
X
trace
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the UNIX CID Adapter Client component
173
allow_core_dump=True or False
Description
Optional. Specifies whether a core dump will be allowed. This is a Cincom
Technical Support parameter.
Default
False
Options
True
Allows a core dump to occur.
False
Does not allow a core dump to occur.
Consideration By default, the CID Adapter Client component does not allow core dumps to be
written when there is an internal problem (segmentation violation). If the CID
Adapter Client component crashes, Cincom Technical Support may request that
this parameter be set so that a core dump can be written for problem analysis.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the UNIX CID Adapter Client component
174
db_pdm-database-name=[dbmod=DBMOD,]node, tcpip,tcp-port-no
Description
Required. Specifies the network information required to connect the CID
Adapter Client component to a CID Adapter Server component.
Format
pdm-database-name
The name specified in the DBM parameter in CSIPARM of the
MVS SUPRA Server PDM database or the DBMOD name for
OpenVMS and UNIX platforms. The name is case-sensitive and
this usually implies that the name be specified completely in
uppercase characters. Alternately, if the optional dbmod
clause is being used to specify the value of the DBM or DBMOD
parameter, then an alias may be specified in the pdmdatabase-name.
DBMOD
An optional identifier that may be used to specify the value of
the DBM parameter in CSIPARM of the MVS SUPRA Server PDM
database or the DBMOD name for OpenVMS and UNIX platforms.
The name is case sensitive and this usually implies that the
name be specified completely in uppercase characters. If this
identifier is used, then an alias may be specified in the pdmdatabase-name. This identifier is used together with alias
names to allow the CID Adapter Client component to
concurrently connect to several PDM databases that have
identical DBM or DBMOD names.
node
The host name where the PDM is running.
tcp-port-no
The TCP/IP port number that the CID Adapter CID Adapter
Server component listener process is listening on for
connections from any CID Adapter Client component.
Considerations
Example
♦
This database connection parameter must be set for each database to
which the CID Adapter Client component is to connect.
♦
The same value specified for TCP_LISTEN_PORT in the CID Adapter Server
component parameter information must be specified for tcp-port-no. The
port numbers must be identical for the connection to be successful.
db_payroll=fred,tcpip,5010
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the UNIX CID Adapter Client component
175
dbname=pdm-database-name
Description
Optional. Specifies the name of the PDM database to the CID Adapter Client
component for use with database-specific parameters.
Format
The name used in the local database registration statement.
Considerations
Example
♦
This parameter allows the PDM database name to be part of databasespecific parameter settings. Database-specific formats only work if the CID
Adapter Client is supplied with the name of the database via this
parameter.
♦
This parameter can only be set in the pdm-database-name.sh script in
$ORDB/admin/ldb/. Setting this parameter in the shell script allows
database-specific parameter settings to take effect for parameters that
need to be read before the sup1drvr.init file is opened (display_options,
driver_directory, init_file, and trace).
The dbname parameter setting for the payroll database parameter would be
dbname=payroll. The database-specific setting for the display_options
parameter for the payroll database would be db_payroll_display_options=true.
display_options=True or False
Description
Optional. Specifies whether the CID Adapter Client component parameters and
their current valid values (as ascertained from the shell script, environment,
and init file) will be listed in the sup1drvr.err file.
Default
False
Options
True
Parameters and values will be listed
False
Parameters and values will not be listed
Consideration A listing of valid parameter values can be useful since a parameter value
assigned in the init file can be overridden by the environment and the shell
script.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the UNIX CID Adapter Client component
176
driver_directory=path-name
Description
Optional. Specifies the directory to which the CID Adapter Client component
switches when it begins execution. This is the directory where the sup1drvr.err
file will be created for error reporting.
Default
Directory where the SQL Access Master process started
Options
/dev/null
No output files are generated
User-defined path name
Consideration This parameter must be set as an environment variable or in the shell script.
init_file=path-name
Description
Optional. Specifies a directory containing an alternate sup1drvr.init file (other
than the one in $ORDB/admin).
Format
User-defined path name
Default
$ORDB/admin
Consideration This parameter must be set as an environment variable or in the shell script.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the UNIX CID Adapter Client component
177
interproc_key= nnnnnnnnnn
Description
Optional. Specifies the UNIX inter-process communication key used to
facilitate sharing of resources between multiple instances of the CID Adapter
Client component.
Format
A multiple of 256 up to 4,294,967,296 (the least significant byte is reserved for
the individual identity of each resource)
Default
1,296,649,029
Considerations
♦
This parameter must be set as an environment variable or in the shell
script. If you set the value as an environment variable, you must set the
value before the SQL Access Master process is started to have it take
effect. A value can be set in the shell script at any time.
♦
The resources created by an instance of the CID Adapter Client component
cannot be shared between different CID Adapter Clients started by
different SQL Access Master process. If you are starting a second SQL
Access Master process that will execute the CID Adapter Client component,
the interproc_key value must be unique. If you receive the following 445E
message, it is an indication that the interproc_key must be changed:
Get shared-memory segment failed. key: 0xsh-mem-key
size: nnnnn errno: nnn.
For example, if you have two different SQL Access systems accessing two
different PDM systems on the same machine, they will need different
interproc_key values.
lang= directory-name
Description
Optional. Specifies the source directory for the sup1drvr.msg file containing
error and warning messages issued by the CID Adapter Client component.
Default
En_US
Consideration The default En_US directory is in $ORDB/admin/msg/.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the UNIX CID Adapter Client component
178
load_path= path-name
Description
Optional. Specifies the dynamic library load path. This is a Cincom Technical
Support parameter.
Format
User-defined path name
Default
$ORDB/lib
Considerations
♦
This parameter is usually set at the request of Cincom Technical Support.
In such a case, the value can be set to a colon-separated list of directory
paths where the CID Adapter Client component searches for network
communications modules. This allows testing of TCP/IP-related issues in a
separate directory.
♦
In the absence of a Support request, there is usually no need to set this
parameter as long as the directory containing the CID Adapter Client shared
objects is included in the PATH environment variable.
max_rcv_pdu= nnnnn
Description
Optional. Specifies the maximum size of the protocol unit (TCP/IP
message)that the CID Adapter Client component can receive from the CID
Adapter Server component.
Format
Must be greater than 1024 (bytes)
Default
8192 (bytes)
Consideration This parameter may only be used to tune the CID Adapter Client/Server
communications. Making the max_rcv_pdu parameter larger will allow more
PDM data records to be sent from the CID Adapter Server to the CID Adapter
Client in a single TCP/IP message, which may improve performance.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the UNIX CID Adapter Client component
179
max_records_limit= nnnnn
Description
Optional. Specifies the maximum number of reads that are allowed to be used
to retrieve data during a query.
Format
Decimal number between 0 - 2,147,483,647 (zero represents unlimited reads)
Default
0
Considerations
♦
If 0 (zero) is specified, the number of reads allowed is unlimited.
♦
The CID Adapter Client component can only set a lower limit than the
global limit in effect in the CID Adapter Server component.
See the definition of the MAX_RECORDS_LIMIT parameter for your CID Adapter
Server platform (UNIX, MVS, or OpenVMS).
oid_cache_max= nnnnn
Description
Optional. Specifies the maximum size of the local database object identifier
cache.
Format
Value greater than 65,536 bytes
Default
65,536 (bytes)
Consideration If an application uses very large transactions, you may have to increase this
value.
read_only= True or False
Description
Optional. Specifies whether to restrict the CID Adapter Client component to
read-only operation if this parameter is set to true.
Default
False
Options
True
Read-only operation (inserts, updates, and deletes are
disabled).
False
Inserts, updates, and deletes are enabled.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the UNIX CID Adapter Client component
180
schema_segment_address= address-value
Description
Optional. Specifies an address for the schema segment to be attached to the
CID Adapter Client component virtual address space.
Format
Hexadecimal address
Default
0x0efff000
Consideration The schema segment is attached at the above default virtual memory address.
schema_segment_size= nnnnnn
Description
Optional. Specifies the size of the shared memory segment for the shared
schema segment.
Format
User-defined integer value (no maximum limit)
Default
153,600
Consideration This value must be less than the value of SHMMAX.
schema_table_size= nn
Description
Optional. Specifies the number of schema table entries used to look up shared
schema segments. Set this parameter to the maximum number of different PDM
databases that are being connected to the CID Adapter Client component.
Format
Integer value
Default
10
Consideration The schema table is used by the CID Adapter Client component to look up a
shared schema segment. There is one shared schema segment for each PDM
database accessed by the CID Adapter Client component. There is one schema
table entry for each shared schema segment.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the UNIX CID Adapter Client component
181
table_segment_address= address-value
Description
Optional. Specifies an address for the table schema segment to be attached to
the CID Adapter Client component virtual address space.
Default
0x0eff0000
Options
Hexadecimal address
Consideration The schema segment lookup table segment is attached at the above default
virtual memory address.
trace= nnn,nnn-nnn…
Description
Optional. If specified, this parameter turns on debug tracing and specifies one
or more tracing options to be used within the CID Adapter Client component.
This is a Cincom Technical Support parameter.
Format
One or more numbers or number ranges, separated by commas
(1, 10–14, 17).
Default
No tracing
Options
8–239
Considerations
♦
Tracing is usually turned on at the recommendation of Cincom Support.
Support provides the specified numbers corresponding to specific tracing
actions. When enabled, some trace options generate significant output and
can degrade performance. All trace output is written to the sup1drvr.err
file.
♦
This parameter can only be set as an environment variable or in the shell
script.
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: Tailoring the UNIX CID Adapter Client component
182
CID Adapter NO-TRACE executable binaries
Both CID Adapter Client and Server components are installed with no-trace
binaries by default. These binaries are smaller and run faster than their
traceable counterparts. The traceable binary images may be used for problem
solving.
The following instructions indicate how to switch between the non-traceable
and traceable binary images for each platform.
Windows CID Adapter Client component
The traceable binaries will be installed in the %ORDB% directory along with the
non-traceable binaries. To switch from trace to no-trace, it is simply a matter
of defining a different driver type in the CID Foreign Database register
statement or updating the ldb_catalog class using the database administrator
user and password.
The TYPE for non-traceable binaries is 'supra1' and for traceable binaries is
'supra1tr'.
To register the CID Foreign Database and specify the type for non-traceable or
traceable binaries:
register CID Foreign Database burrys
name 'BURRYS'
type 'supra1' or 'supra1tr'
host 'mterry';
If the CID Foreign Database has already been registered, logon to the SQL
Access Server as the dba and execute the following SQL to select the traceable
binary:
update ldb_catalog set database_type = 'supra1tr' ;
To switch to the non-traceable binary, execute the following SQL:
update ldb_catalog set database_type = 'supra1' ;
The statement may require a where clause if there is more than one CID
Foreign Database registered. For example,
update ldb_catalog set database_type = 'supra1'
where database_name = 'BURRYS'
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: CID Adapter NO-TRACE executable binaries
183
UNIX CID Adapter Client component
The traceable binaries will be installed in the $ORDB directory along with the
non-traceable binaries. To switch from trace to no-trace, it is simply a matter
of defining a different driver type in the CID Foreign Database register
statement or updating the ldb_catalog class using the database administrator
user and password.
The TYPE for non-traceable binaries is supra_v1 and for traceable binaries is
supra_v1_trc.
To register the CID Foreign Database and specify the type for non-traceable or
traceable binaries:
register CID Foreign Database burrys
name 'BURRYS'
type 'supra_v1' or 'supra_v1_trc'
host 'mterry';
If the CID Foreign Database has already been registered, logon to the SQL
Access Server as the dba and execute the following SQL to select the traceable
binary:
update ldb_catalog set database_type = 'supra_v1_trc' ;
To switch to the non-traceable binary, execute the following SQL:
update ldb_catalog set database_type = 'supra_v1' ;
The statement may require a where clause if there is more than one CID
Foreign Database registered. For example,
update ldb_catalog set database_type = 'supra_v1'
where database_name = 'BURRYS'
MVS CID Adapter Server component
To execute to the traceable code on MVS, place the DBUGLINK library before
the LINKLIB library in the job used to start the MVS CID Adapter Server.
UNIX CID Adapter Server component
The <adapter-name>_run script generated by the s1_adapter_setup script runs
the non-traceable binary, csiserver, by default. To run the traceable binary,
csiserver.dbg, use the following command:
<adapter-name>_run -d
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: CID Adapter NO-TRACE executable binaries
184
OpenVMS CID Adapter Server component
The <adapter-name>_RUN.COM, <adapter-name>_COORD_START.COM and
<adapter-name>_SERVER_START.COM command files generated by the
S1_ADAPTER_SETUP.COM command file use the values of the logical names
CSISERVER and CSIHUBSHR to start the CID Adapter Server and Coordinator
processes. By default, the V1HUB_COMS:LOGICALS.COM command file sets
these logical names to point to the installed non-traceable images:
♦
V1HUB_EXE:CSISERVER_nnnn.EXE
♦
V1HUB_EXE:CSIHUBSHR_nnnn.EXE
These logical names can be changed to point to the traceable images:
♦
V1HUB_EXE:CSISERVER_TRC_nnnn.EXE
♦
V1HUB_EXE:CSIHUBSHR_TRC_nnnn.EXE
It is imperative that both of these logical names be pointing to either the
traceable or non-traceable images. The logical names must also be persistent
and visible to the user running the <adapter-name>_RUN.COM command file, as
well as the user identified in the <adapter-name> TPCIP service, as this will be
the user that runs the <adapter-name>_SERVER_START.COM in response to a
connect.
It is possible to execute the traceable binary images by copying them to the
installed binary images as follows:
♦
Copy V1HUB_EXE:CSIHUBSHR_TRC_nnnn.EXE to
V1HUB_EXE:CSUHUBSHR_ nnnn.EXE
♦
Copy V1HUB_EXE:CSISERVER_TRC_nnnn.EXE to
V1HUB_EXE:CSISERVER_ nnnn.EXE
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: CID Adapter NO-TRACE executable binaries
185
This method does not require any changes to the CSISERVER or CSIHUBSHR
logical names. To resume executing the non-traceable binary images, you can
copy them to installed binary images as follows:
♦
Copy V1HUB_EXE:CSIHUBSHR_PRV_nnnn.EXE to
V1HUB_EXE:CSIHUBSHR_nnnn.EXE
♦
Copy V1HUB_EXE:CSISERVER_PRV_nnnn.EXE to
V1HUB_EXE:CSISERVER_nnnn.EXE
Administration Guide, P25-9501-04
Chapter: 5. Tailoring the CID Adapter Client
Section: CID Adapter NO-TRACE executable binaries
186
6. Cincom ORDB Visual
Administration Tool
Overview
The Cincom ORDB Visual Administration tool is a graphical application that can
be used to:
♦
Start and Stop SQL Access for SUPRA Server PDM (SQL Access) Servers
♦
View and/or kill transactions on a SQL Access Server
♦
Display transaction and SQL Access Server lock information
♦
Load and unload SQL Access Servers
♦
Create a new SQL Access Server
♦
Maintain a SQL Access Server
The Visual Administration Tool presents a hierarchy view of host machines, SQL
Access Servers, and SQL Access Server transactions. The hierarchy is displayed
in the left pane of the tool in a tree view. When you select a node in the tree,
specific data and operations for the selected node are displayed in the right
pane.
You can also right-click on a node in the tree and access specific
operations that are available for the node.
The Tool requires a connection to the SQL Access Master process of each SQL
Access machine you want to administer. You can connect to as many SQL
Access Master processes as you want with the Visual Administration Tool. The
Visual Administration Tool refers to a SQL Access Master process as a "Database
Host". A database host is simply the TCP/IP address or machine name, and the
TCP/IP port number of the SQL Access Master process.
System requirements
The Visual Administration tool requires version 1.4.0 or higher of the Java
runtime.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Overview
187
Starting the Visual Administration Tool
Start the Visual Administration Tool using one of the following methods:
These examples assume that the java executable can be found in your path.
WINDOWS
♦
Select Start ⇒ SQL Access ⇒ Server ⇒ Admin Tool from the Windows
Taskbar
WINDOWS
♦
Enter the following command at a command prompt:
java –cp %ORDB%\ordbjava.jar;
%ORDB%\distributable\javahelp\jhall.jar
ordbjava.admin.AdminTool
UNIX
♦
Execute the AdminTool file in $ORDB. You will need a terminal emulator
like Xterm to view the tool.
UNIX
♦
Start the tool manually with:
java –cp ${ORDB}/ordbjava.jar:
${ORDB}/distributable/javahelp/jhall.jar
ordbjava.admin.AdminTool &
When you start the Visual Administration Tool, you will see a screen similar to
the following:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Starting the Visual Administration Tool
188
Connecting to a database host
The Visual Administration Tool requires a connection to the SQL Access Master
process of each host machine you want to administer. You can connect to as
many SQL Access Master processes as you want with the Visual Administration
Tool.
When you start the administration tool, you will see a screen similar to the
following:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Connecting to a database host
189
To initiate a database host connection:
1. Right-click Hosts in the left pane of the window.
2. Then, select Connect To Host from the pop-up menu. A dialog box
displays prompting you to enter the information for the SQL Access Master
process you want to connect to:
where:
-
Host Name can be a network name or a TCP/IP address.
-
Port number can be left as “<Default Port>” if you want to use the
port defined as the master_port_id in the ordbinit.txt file.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Connecting to a database host
190
3. Click OK to attempt a connection with the SQL Access Master process.
After successfully connecting to a database host, the left pane shows all the
SQL Access Servers that the database host knows about. The list will contain:
♦
Running SQL Access Servers
♦
Servers on stand-by (defined in ordbserv.txt)
♦
Servers that are in the ordblist.txt file (that are not running or on stand-by)
The following shows the SQL Access Servers being managed by the SQL Access
Master process running on a machine named cg25717, and listening on port
1978:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Connecting to a database host
191
Disconnecting from a database
To disconnect a database host, perform the following steps:
1. Right-click Hosts in the left pane.
2. Then, select Disconnect from the pop-up menu. A dialog box displays
prompting you to confirm that you want to disconnect:
3. Click Yes to confirm that you want to remove the host.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Disconnecting from a database
192
Starting and stopping SQL Access Servers
You can start or stop a SQL Access Server by selecting the appropriate action
from the pop-up menu:
If the SQL Access Server is password protected, the database security
password will be required in order to stop the SQL Access Server.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Starting and stopping SQL Access Servers
193
Viewing SQL Access Servers
You can display all SQL Access Servers at once or only the SQL Access Servers
that are running. In addition, you can view the status for an individual SQL
Access Server.
View all SQL Access Servers
To display all SQL Access Servers, right-click on the connected host in the left
pane, and select Show All Servers from the pop-up menu:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Viewing SQL Access Servers
194
View running SQL Access Server
To display only the running SQL Access Servers, right-click on the connected
host in the left pane, and select Show Running Servers from the pop-up menu:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Viewing SQL Access Servers
195
View status for a SQL Access Server
To display details for an individual SQL Access Server, click on the SQL Access
Server in the left pane. The right pane displays the information for the SQL
Access Server you selected:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Viewing SQL Access Servers
196
Viewing Client Settings
Using the Visual Administration tool, users can display the values assigned to
system parameters, which determine the overall performance and behavior of
the SQL Access system.
SQL Access system parameters have default values (assigned in the system
code) that you can redefine by setting the parameter values in:
♦
An ordbinit.txt file for an installation
♦
A desired SQL Access Server
♦
A particular user
The SQL Access Server looks for ordbinit.txt files in the following locations in
the order shown:
♦
%ORDB%\admin directory
♦
Home directory of the SQL Access Server
The SQL Access Client looks for ordbinit.txt files in the following locations in
the order shown:
♦
%ORDB%\admin directory
♦
Working directory of the process that is starting up
The ordbinit.txt file in the %ORDB%\admin directory defines default
parameter values for an installation. That is, it defines the values for all
databases. Settings found in an ordbinit.txt file override any values that
may have been previously assigned to system parameters. For detailed
information on system parameters, see "9. SQL Access for SUPRA Server
PDM system parameters" on page 320.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Viewing Client Settings
197
To view values assigned to parameters:
Right-click on the database host (in the left pane). Then, select View Client
Settings from the pop-up menu:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Viewing Client Settings
198
When View Client Settings opens, the default view shows all:
In addition, tabs are available so you can choose to view only parameters
pertaining to the following specific categories:
♦
SQL Access Client connection
♦
SQL Access Client disconnect
♦
SQL Access Client query settings
♦
SQL Access Client workspace
♦
java method
♦
miscellaneous
♦
utility
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Viewing Client Settings
199
View Server Settings
To view the values assigned to a SQL Access Server:
1. Right-click on the database (in the left pane).
2. Then, select Server Settings from the pop-up menu:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: View Server Settings
200
The default view displays the show all tab:
In addition, tabs are available so you can view specific categories:
♦
java method
♦
server error handling
♦
server recovery
♦
miscellaneous
♦
server fbo
♦
server request limits
♦
server communication
♦
server locking
♦
server threads
♦
server disk space
♦
server memory
♦
utility
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: View Server Settings
201
Database Security
The Security feature for the database allows you to:
♦
Add a password
♦
Remove a password
♦
Change a password
To access Database Security:
1. Right-click the database name in the left pane.
2. Select Security from the pop-up menu.
3. Then, select the appropriate task from the Security submenu. Depending
on your selection, one of the following screens will appear:
-
When "Add Password" is selected, the following screen displays:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Database Security
202
-
When "Remove Password" is selected, the following screen displays:
-
When "Change Password" is selected, the following screen displays:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Database Security
203
DBA Logon
When prompted to provide the dba logon information, you will see the
following screen:
where:
-
DBA Name specifies your DBA name.
-
Password specifies the password if your DBA name has one.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: DBA Logon
204
ORDBINIT Management
The Visual Administration Tool also allows you to manage the ordbinit file. To
view the values assigned:
1. Select Other Tools from the top toolbar.
2. Then, select ORDBINIT Management. The following screen appears:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: ORDBINIT Management
205
3. Click Browse and navigate to the location of your ordbinit.txt file. For
example:
C:\CincomTIGER2.2\ORDB\Admin\ordbinit.txt
When ordbinit management opens, the default view displays the show all tab:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: ORDBINIT Management
206
In addition, tabs are available so you can view specific categories:
♦
SQL Access Client connection
♦
SQL Access Client disconnect
♦
SQL Access Client query settings
♦
SQL Access Client workspace
♦
java method
♦
miscellaneous
♦
utility
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: ORDBINIT Management
207
SUPRA INI file Management
The Visual Administration Tool also allows you to manage the SUPRA ini file
(sup1drvr.ini). To view the values assigned:
1. Select Other Tools from the top toolbar.
2. Then, select SUPRA INI Management. The following screen appears:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: SUPRA INI file Management
208
3. Click Browse and navigate to the location of your sup1drvr.ini file. For
example:
C:\n\v2_3\ORDB\Admin\sup1drvr.ini
When SUPRA INI File management opens, the default view shows all:
To change any of these values:
1. Select the item in the Name column. The current value is displayed on the
right side of the window.
2. Change the value as needed and press ENTER.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: SUPRA INI file Management
209
3. Click Save.
The db_<pdm_name> (db_EE72CPDM in the example above) is required and
specifies the MVS/OpenVMS/UNIX host name, network protocol and port
number. If the db_<pdm_name> parameter is not included in the display, you
can add it by clicking Add PDM DB, which will display the following:
-
PDM Database Name is the DBM name in the CSIPARM file for MVS and
the dbmod name for OpenVMS and UNIX. This name is used by the SQL
Access Server to connect to the CID Foreign Database. This parameter
must be unique within the SUPRA ini file. Therefore, for OpenVMS and
UNIX, the dbmod prefix can be placed before the dbmod name
separated by an underscore (_) (for example, 001_MRPDBO).
-
Node Name is the name of the machine on which the relational CID
Adapter Server is running.
-
Port Number is the TCP/IP port number on which the relational CID
Adapter Server is listening.
-
Dbmod Name OPENVMS UNIX (Optional) is the name of the dbmod. It is
used when the prefix+dbmod name is not enough qualification to make
the PDM Database Name parameter unique. In this case the PDM
Database Name parameter will be an alias and can be any unique
name.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: SUPRA INI file Management
210
Displaying SQL Access Server transactions
You can display the transaction information about a SQL Access Server for all
transactions at once or for an individual transaction. You will be required to
provide the dba logon information the first time you attempt to display the
transaction information for a SQL Access Server.
♦
All transactions at once. To display information for all transactions at one
time, click Transaction in the left pane. The details for all the transactions
appear in the right pane.
♦
An individual transaction. To display information for an individual
transaction, expand the tree view for "transaction" in the left pane. Then,
click the individual transaction node that you wish to view. The details for
that specific transaction appear in the right pane.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Displaying SQL Access Server transactions
211
Killing SQL Access Server transactions
To kill transactions, right-click on the Transactions in the left pane, and select
Kill from the pop-up menu. A confirmation box will ask you to confirm your
desire to kill the transaction.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Killing SQL Access Server transactions
212
Displaying transaction lock information
The lock information can be helpful in determining locking conflicts between
transactions. The data shown includes:
♦
Transaction isolation level and lock request timeout setting
♦
Locks being held by the transaction
♦
Locks this transaction is waiting to obtain
♦
Transactions blocking this transaction
♦
Transactions being blocked by this transaction
You can display lock information about all transactions or a specific
transaction. You will be required to provide the dba logon information the first
time you attempt to display the transaction lock information for a SQL Access
Server.
♦
All locks at once. To display information for all locks at one time, click
Transactions in the left pane. The details for all the transactions appear in
the right pane.
♦
An individual lock. To display information for an individual lock, expand
the tree view for "Transactions" in the left pane. Then, click the individual
transaction node that you wish to view. The details for that specific
transaction appear in the right pane.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Displaying transaction lock information
213
Displaying SQL Access Server lock information
You can display lock information for the entire SQL Access Server. You will be
required to provide the dba logon information the first time you attempt to
display the lock information for a SQL Access Server.
To display SQL Access Server lock information, right-click on the SQL Access
Server in the left pane, and select Show All Locks.
The right pane displays the information for the SQL Access Server you selected:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Displaying SQL Access Server lock information
214
Displaying SQL Access Server volumes
The addvoldb utility adds new volumes to a SQL Access Server (see "Adding a
volume" on page 220). Before new volumes are added, the DBA is advised to
plan a configuration that provides some performance benefits. Performance is
improved when these general rules are followed:
♦
Fewer volumes with large amounts of disk space are preferred over many
volumes with small amounts of disk space.
♦
I/O contention is reduced when data, index, and temporary information are
stored in completely different volumes on different disk drives.
The addvoldb utility operates only on databases that are on the same machine
as the Visual Administration Tool.
To display volumes:
You can view volume information for all volumes at once or for an individual
volume. You will be required to provide the dba logon information the first
time you attempt to display the volume information for a SQL Access Server.
♦
All volumes at once. To display information for all volumes at one time,
click Volumes in the left pane. The details for all the volumes appear in
the right pane:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Displaying SQL Access Server volumes
215
♦
An individual volume. To display information for an individual volume,
expand the tree view for Volumes in the left pane. Then, click the
individual volume node that you wish to view. The details for that specific
volume appear in the right pane:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Displaying SQL Access Server volumes
216
Displaying and starting CID Foreign Databases
The Visual Administration Tool allows users to start foreign database servers
and display information about them. You will be required to provide the dba
logon information when you try to start the CID Foreign Database or the first
time you attempt to display the detail for the CID Foreign Database. The
sections below detail both starting and viewing CID Foreign Databases.
Starting CID Foreign Databases
You can start all CID Foreign Databases or an individual CID Foreign Database.
First, you need to be connected to the host and SQL Access Server that the CID
Foreign Database(s) reside on.
♦
To start all CID Foreign Databases, right-click Foreign Databases in the
left pane, and select Start All from the popup menu.
♦
To start an individual CID Foreign Database, right-click on the name of
the CID Foreign Database in the left pane, and select Start from the popup
menu.
Viewing CID Foreign Databases
You can view details on all CID Foreign Databases or an individual CID Foreign
Database. First, you need to be connected to the host and SQL Access Server
that the CID Foreign Database(s) reside on.
♦
To display information for all CID Foreign Databases, click Foreign
Databases in the left pane. The right pane displays the information for all
CID Foreign Databases.
♦
To display information for an individual CID Foreign Database, click on
the name of the CID Foreign Database in the left pane. The right pane
displays the information for that CID Foreign Database.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Displaying and starting CID Foreign Databases
217
SQL Access Server location file
Several utilities maintain a file named ordblist.txt that contains information
about the location of SQL Access Servers.
In order to connect to a SQL Access Server, each SQL Access Client application
must specify the SQL Access Server name. The user is not required to supply
any other information such as the full path name of the SQL Access Server or
the host name of the SQL Access Server. Instead, this information is kept in a
common file named ordblist.txt that can be accessed by many users. This file is
created and maintained automatically by several utilities, including create,
copy, rename, and delete. The file consists of a sequence of lines in the
following format:
db_name db_path_name server_host logfile_path_name
The SQL Access Server location file is located through the environment variable
ORDB_DATABASES. If this environment variable is set, it must be the name of a
directory containing the ordblist.txt file. If this environment variable is not set,
the current working directory is searched for the ordblist.txt file. In a
traditional environment, the DBA maintains a directory hierarchy containing
databases with the SQL Access Server location file at its root. The DBA then
ensures that all SQL Access Server users have their environment variables set
up properly to access the location file.
Because the utilities must be able to make modifications to the SQL Access
Server location file, the user must have write access to that file. If the
ORDB_DATABASES environment variable points to a directory for which the user
does not have write access, the user is not permitted to create a SQL Access
Server. In this case, either the DBA needs to grant the user write access to the
directory, or the user must create a private copy of the SQL Access Server
location file in a directory for which the user has access and set the
environment variable to this directory.
The copy, rename, and delete utilities can also update the SQL Access Server
location file.
ALWAYS use these utilities to operate on SQL Access Server files. NEVER use the
operating system file system commands directly. Using these utilities ensures
that the SQL Access Server location file is maintained consistently.
When working with SQL Access Clients and Servers, all databases must:
♦ Have unique names
♦ Be listed in one central SQL Access Server location file
All users working in client/server mode use the single, central SQL Access
Server location file. (When a SQL Access Server is started, the location of a SQL
Access Server is determined by the ORDB_DATABASES environment variable.)
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: SQL Access Server location file
218
Maintaining a SQL Access Server
Using the Visual Administration Tool, users can maintain databases with the
following utilities:
♦
Add volume to a SQL Access Server using the addvoldb utility.
♦
Check a SQL Access Server using the checkdb utility.
♦
Copy a SQL Access Server using the copydb utility.
♦
Create a SQL Access Server using the createdb utility.
♦
Delete a SQL Access Server using the deletedb utility.
♦
Load a SQL Access Server using the loaddb utility.
♦
Move a SQL Access Server using the movedb utility.
♦
Rename a SQL Access Server using the renamedb utility.
♦
Start CID Foreign Databases using the startfdb utility.
♦
Stop CID Foreign Databases using the stopfdb utility.
♦
Unload a SQL Access Server using the unloaddb utility.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
219
Adding a volume
The addvoldb utility operates only on databases that are on the same machine
as the Visual Administration Tool.
To add volume to a SQL Access Server:
1. Right-click Volumes in the left pane, and select Add Volume from the
popup menu. The following screen appears:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
220
The following screen appears:
where:
-
Page Number specifies the number of pages to allocate for the new
volume. This is a REQUIRED field.
-
Volume Path specifies directory path for the volume.
-
Storage Purpose specifies the purpose for the volume storage.
-
Quiet (if checked) disables the display of the starting and ending
information banners.
2. Click Add Volume to begin.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
221
Checking SQL Access Server consistency
This is a diagnostic utility used to verify SQL Access Server consistency. It
checks the internal physical consistency of the data and log volumes to verify
their indices and other data structures. Since the time required checking a SQL
Access Server rises with the size of the SQL Access Server, this may not be
practical with very large databases.
The checkdb utility operates only on databases that are on the same machine
as the Visual Administration Tool.
To check a SQL Access Server:
1. Right-click the SQL Access Server in the left pane.
2. Then, select Check from the popup menu. A dialog box displays allowing
the user to select what options to check:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
222
where (if checked):
-
DBA Name specifies your DBA name.
-
DBA Password specifies the password if your DBA name has one.
-
Check Volume Path enables volume path check.
-
Check Volume Header enables volume header check.
-
Check Page Header enables page header check.
-
Check Heap Page enables heap page check.
-
Check B-Tree enables b-tree check.
-
Check Class enables class check.
-
Check B-Tree and Heap enables b-tree and heap check.
-
Quiet disables starting and ending information banners.
By default, all options are checked. Users should uncheck the options that
they want to exclude.
3. Click Check to begin checking the SQL Access Server.
The result is shown in an informational dialog. Although the utility finds and
reports problems, no action is taken to correct the problems.
All non-fixed problems listed in the error log need to be analyzed by Cincom
Technical Support, who will then advise you on your best choices of action to
put your SQL Access Server back into a consistent state.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
223
Copying a SQL Access Server
Using the Visual Administration Tool, users can copy or move databases from
one location to another. The system copies every volume and control file of the
SQL Access Server into the new destination and creates a new log to support
the new SQL Access Server. You must give the new SQL Access Server a name
different from the name of SQL Access Server that you are copying.
Because a SQL Access Server is made up of several interdependent volumes,
you should not use the operating system file commands to copy or move the
SQL Access Server files. Rather, using the copydb utility ensures that all of the
associated files are properly copied. The copydb utility must be run offline; in
other words, it should not be run when someone else is using the SQL Access
Server.
The SQL Access Server location file is modified to add the entry for the new
SQL Access Server and optionally delete the entry for the source SQL Access
Server. For more information, see "SQL Access Server location file" on
page 218.
Recovery information from the source SQL Access Server is not included in the
destination SQL Access Server. This information includes information from
backups and active/archive logs.
Cincom recommends making a backup of the destination SQL Access Server
after the copy is done.
To copy a SQL Access Server:
1. In the left pane, right-click on the SQL Access Server host to copy.
2. Then, select Copy from the pop-up menu. The following screen appears:
where Destination Name specifies the name of the SQL Access Server copy
that is made. This is a REQUIRED field.
Clicking Show Options expands the Copy Database screen allowing users to
specify additional options. For more information, see the following section
about additional options.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
224
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
225
3. Click Copy to begin.
The copydb utility operates only on databases that are on the same
machine as the Visual Administration Tool.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
226
Additional options for copying a SQL Access Server
The following screen is displayed when you click Show Options when copying a
SQL Access Server:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
227
The table below lists the available options and default values:
Option
Default value
Description
Database Path
Current directory
Specifies the SQL Access Server
directory path
Log Path
Same as directory
specified for Database
Path
Specifies the log file directory path
Specifies the file that names volumes
and directory locations
File Name
Vol. Extension
Path
Same as original volumes,
or corresponding entry
specified in the File Name
Specifies the directory path for
volume extensions
Database
Password
Database password of the selected
SQL Access Server
Re-Enter
Password
Database password of the selected
SQL Access Server
Replace
Existing
Unchecked
When checked, confirms that you
want a new SQL Access Server to
replace an existing SQL Access Server
with the same name
Quiet
Unchecked
When unchecked, disables the display
of the starting and ending information
banners
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
228
Creating a SQL Access Server
After successfully connecting to a SQL Access Server host, you can create a new
SQL Access Server.
To create a new SQL Access Server:
1. Right-click on the CID Foreign Database host in the left pane.
2. Then, select Create from the pop-up menu:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
229
The following screen appears:
where:
-
Database Name specifies the name of your SQL Access Server. This is a
REQUIRED field.
-
Number of Pages specifies the allocated number of pages (default is
1000).
-
Database Path specifies the path of your SQL Access Server directory.
Clicking More Options expands the Create Database screen
allowing users to specify additional options. For details, see the
following section about additional options.
3. Click Create to begin.
The createdb utility operates only on databases that are on the same
machine as the Visual Administration Tool.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
230
Additional options for creating a SQL Access Server
The following screen is displayed if you click More Options when creating a SQL
Access Server:
The table below lists the available options and default values:
Option
Default Value
Description
Log Path
Same as directory specified
for Database Path
Log file directory path
Log Page Number
Value of system parameter
log_size
Indicates the size of the log file in
number of pages
Page Size
4096
Specifies the page size in bytes
Output File
stdout
Name of the output file for
initialization messages
Temp Volume
Path
Same as directory specified
for Database Path
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
Directory path for the permanent
temporary file
231
Option
Default Value
Description
Temp Page Size
The larger of 100 and onetenth of the number of SQL
Access Server pages
Number of pages to allocate for the
permanent temporary file
Backup Volume
Path
Same as directory specified
for Database Path
Directory path for backup files
Char Algorithm
BINARY
The CHAR collation algorithm
NChar Algorithm
BINARY
The NCHAR collation algorithm
Char Locale
BINARY
The CHAR collation local
NChar Locale
BINARY
The NCHAR collation local
Code Sets
Database
Password
Specify a password to protect the
SQL Access Server
Confirm Password
Confirm the password specified to
protect the SQL Access Server
Replace Existing
Unchecked
When unchecked, the new SQL
Access Server will not replace an
existing SQL Access Server with the
same name
Make backup
Checked
When checked, an initial backup of
the SQL Access Server is performed
after a successfully creating the SQL
Access Server
Verbose
Unchecked
When unchecked, verbose output is
disabled
Quiet
Unchecked
When unchecked, disables the
display of the starting and ending
information banners
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
232
Deleting a SQL Access Server
The Visual Administration Tool provides functionality to delete databases.
To delete a SQL Access Server:
1. In the left pane, right-click on the SQL Access Server name you want to
delete.
2. Then, select Delete from the popup menu:
3. A dialog box displays prompting you confirm that you want to delete the
SQL Access Server:
4. Click Yes to confirm that you want to delete.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
233
Loading a SQL Access Server
The loaddb utility provides a quick and easy way to populate a SQL Access
Server with large amounts of data.
The input file format for loaddb follows a simple tabular format. This format
makes it an effective means for importing large amounts of data from
traditional relational databases. To run loaddb, Cincom ORDB can be running in
either standalone or client/server mode.
To load a SQL Access Server:
1. In the left pane, right-click the SQL Access Server and select Load from the
popup menu:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
234
The following screen appears:
where Schema File specifies the name of the schema file (.sch) created by
the unloaddb utility. The schema file is used to populate schema
information into the newly created SQL Access Server prior to loading the
input file. This is a REQUIRED field.
Clicking Show Options expands the Load Database screen allowing users to
specify additional options. For more information, see the following section
about additional options.
2. Click Load to begin.
The loaddb utility operates only on databases that are on the same machine as
the Visual Administration Tool.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
235
Additional options for loading a SQL Access Server
The following screen is displayed when you click Show Options when loading a
SQL Access Server:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
236
The table below lists the available options, default values, and brief
descriptions:
Option
User Name
Default value
Public
Description
Specifies the name of the user under which SQL Access
Server access is performed.
Specifies the password associated with the current
user name.
User Password
Estimated Size
5000
Specifies the number of objects to be defined.
Periodic Commit
Count
0
When set to a value other than zero, loaddb
automatically commits the transaction after that
number of instances has been inserted.
Syntax only
Disabled
If checked, performs syntax and data type checking on
the input file without creating instances in the SQL
Access Server.
Load only
Disabled
If checked, skips syntax and data type checking on the
input file and proceed directly to loading the SQL
Access Server.
Quiet
Disabled
If checked, disables the display of the starting and
ending information banners.
Verbose
Disabled
If checked, displays status messages as the SQL Access
Server is being populated.
Verbose Commit
Disabled
If checked, prints the running total of committed
instances.
No Statistics
Disabled
If checked, updates the internal statistics for every
class into which instances are inserted.
No Logging
Disabled
If checked, no logging is performed during the load.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
237
Moving a SQL Access Server
Using the Visual Administration Tool, users can copy or move databases from
one location to another. The system copies every volume and control file of the
SQL Access Server into the new destination and creates a new log to support
the new SQL Access Server. You must give the new SQL Access Server a name
different from the name of the SQL Access Server that you are copying.
Because a SQL Access Server is made up of several interdependent volumes,
you should not use the operating system file commands to copy or move the
SQL Access Server files. Rather, using the copydb utility ensures that all of the
associated files are properly copied. The copydb utility must be run offline; in
other words, it should not be run when someone else is using the SQL Access
Server.
The SQL Access Server location file is modified to add the entry for the new
SQL Access Server and optionally delete the entry for the source SQL Access
Server. For more information, see "SQL Access Server location file" on
page 218.
Recovery information from the source SQL Access Server is not included in the
destination SQL Access Server. This information includes information from
backups and active/archive logs.
Cincom recommends making a backup of the destination SQL Access Server
after the copy is done.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
238
To move a SQL Access Server:
1. In the left pane, right-click the SQL Access Server host and select Move
from the popup menu:
The following screen appears:
where:
-
Source Database lists the name of the SQL Access Server host you want
to move.
Destination Name specifies the name of the SQL Access Server move
that is made.
Clicking Show Options expands the Move Database screen allowing users to
specify additional options. For more information, see the following section
about additional options.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
239
2. Click Move to begin.
The movedb utility operates only on databases that are on the same machine
as the Visual Administration Tool.
Additional options for moving a SQL Access Server
The following screen is displayed when you click Show Options when moving a
SQL Access Server:
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
240
Option
Default value
Description
Database Path
Current directory
Specifies the SQL Access Server
directory path
Log Path
Same as directory specified
for Database Path
Specifies the log file directory path
Specifies the file that names volumes
and directory locations
File Name
Vol. Extension Path
Same as original volumes, or
corresponding entry specified
in the File Name
Specifies the directory path for
volume extensions
Database Password
Database password of the selected
SQL Access Server
Re-Enter Password
Database password of the selected
SQL Access Server
Replace Existing
Unchecked
When checked, confirms that you
want a new SQL Access Server to
replace an existing SQL Access Server
with the same name
Quiet
Unchecked
When unchecked, disables the
display of the starting and ending
information banners
Renaming a SQL Access Server
The renamedb utility changes the current name of an existing SQL Access
Server. The information volumes, log volumes, and control files are renamed to
coincide with the new name. Unlike copydb, renamedb does not require any
additional disk storage, because the SQL Access Server is renamed in place.
The renamedb utility is different from copydb in that it does not allow you to
change the location of the volumes to another disk partition (for example, to
another disk drive or another file system).
The renamedb utility must be run offline (it should not be run when someone is
using the SQL Access Server). Otherwise, renamedb fails.
If a SQL Access Server with the new name already exists, the rename operation
is aborted and an error message displayed. If renamedb is successful, the SQL
Access Server location file is automatically updated to reflect the new name.
The names of the files that comprise the SQL Access Server are also renamed to
correspond to the new name.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
241
To rename a SQL Access Server:
1. In the left pane, right-click on the SQL Access Server to rename. Then,
select Rename from the pop-up menu. The following screen appears:
where:
-
New Name specifies the new name of the SQL Access Server you are
renaming. This is a REQUIRED field.
-
Database Path specifies the pathname for the renamed SQL Access
Server files.
-
Input File is the file that controls the renaming of information volumes
for several disk locations.
-
Quiet, if checked, disables the display of the starting and ending
information banners.
2. Click Rename to begin.
The renamedb utility operates only on databases that are on the same machine
as the Visual Administration Tool.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
242
Unloading a SQL Access Server
The unloaddb utility is used with the loaddb utility to compress a SQL Access
Server or to migrate an existing SQL Access Server to a new release of Cincom
ORDB. In other words, the unloaddb and loaddb utilities reload a SQL Access
Server from one version to another. The unloaddb utility runs only in
standalone mode. For complete information on the loaddb utility, see "Loading
a SQL Access Server" on page 234.
The unloaddb utility produces three files:
♦
Schema file, which contains the schema definition of the SQL Access
Server. It is created with the name of the SQL Access Server prefixed to
.sch. (for example, a schema file for a SQL Access Server named "test",
would be testdb.sch).
♦
Object file, which contains the objects (instances) that are contained in
the SQL Access Server. It is created with the name of the SQL Access Server
prefixed to .obs (for example, an object file for a SQL Access Server named
"test", would be shown as testdb.obs).
♦
Index file, which contains indexes defined in the SQL Access Server. The
index file name is formed from the name of the SQL Access Server prefixed
to .idx (for example, an index file for a SQL Access Server named "test",
would be shown as testdb.idx).
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
243
To unload a SQL Access Server:
1. In the left pane, right-click the SQL Access Server and select Unload from
the popup menu. The following screen appears:
Clicking Show Options expands the Unload Database screen allowing users
to specify additional options. For more information, see the following
section about additional options.
2. Click Unload to begin.
The unloaddb utility operates only on databases that are on the same machine
as the Visual Administration Tool.
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
244
Additional options for unloading a SQL Access Server
The following screen is displayed when you click Show Options when unloading
a SQL Access Server:
Option
Default value
Description
Class Names File
None
Name of file containing specific classes to unload
(all classes are unloaded if not specified)
Estimated Instances
Computed
Aids the internal hashing function of the object
table manager
Cached Page Size
4096
Specifies cached page size
Cached Pages
100
Sets the number of object-table pages to cache
in memory
Output Directory
Current working
directory
Specifies the directory where the schema and
object output files are produced
Output Prefix
Database name
Determines the prefix for the schema and object
output files
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
245
Option
Default value
Description
Hash File Name
utility tmpnam( )
Supplies the pathname of the temporary file that
is used for the object table
User Name
'dba'
Current user name
Password
None
Password for current user
Include References
Disabled
If checked, includes references when used with
the Class Names File option
Verbose
Disabled
If checked, enables verbose output
Schema Only
Disabled
If checked, produces the schema output file
only; the object file is not created
Debug
Disabled
If checked, no logging is performed during the
load
Objects Only
Disabled
NOTE: This option should only be used when
directed by Cincom Technical Support
Quiet
Disabled
If checked, no start/stop messages displayed
Administration Guide, P25-9501-04
Chapter: 6. Cincom ORDB Visual Administration Tool
Section: Maintaining a SQL Access Server
246
7. Utilities
Overview
This chapter describes the programs and utilities used to maintain SQL Access
for SUPRA Server PDM (SQL Access) Servers. For Windows, all of the utilities
described below are found in the SQL Access install directory. For UNIX, all of
the utilities may be found in the utilities directory under the install directory.
The Install directory location is stored in the environment variable ORDB. To
execute the utilities, the PATH environment variable should contain %ORDB% on
Windows and $ORDB:$ORDB/utilities on UNIX.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: Overview
247
Foreign Table Generator
The foreign table generator is a command line utility that can be used to
automatically create SQL Access foreign tables. The utility creates foreign
table statements for each PDM or VSAM file and writes these statements to a
file (standard output if no output file is specified). The foreign table is given
the same name as the PDM or VSAM file, however, this can be modified prior to
storing the definition in the SQL Access Server.
If external field names are defined in the PDM Directory, they will be used as
the attribute names in the foreign table instead of the 8-character PDM
physical field names. The utility will replace dashes in the external field names
with underscores. This helps to ensure compatibility with SQL Access Client
applications.
Super-elements (fields that have sub-defined fields) are suppressed; only the
sub-elements will be included in the foreign table. If the super-element is
desired rather than the individual sub-elements, the output file may be
modified prior to storing the definition in the CID Foreign Database on the SQL
Access Server.
A separate foreign table is generated for each record code in a record-coded
related file. The query clause is suppressed in the foreign table statement for
the base portion of coded files. The base portion of the file exists only so that
attributes in the base portion can be shared between several coded overlays of
the same file through inheritance.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: Foreign Table Generator
248
Executing the Foreign Table Generator
The Foreign Table Generator is a command line executable that will generate
the statements to create the foreign table for each PDM or VSAM file defined in
the CID Adapter Server. It will generate statements for all the PDM or VSAM
files, or you can input a list of files. The name of the executable is
foreign_tables.exe on Windows and foreign_tables on UNIX. The input
parameters are defined below.
The CID Foreign Database must be registered prior to executing this utility.
The Foreign Table Generator utility has the following parameters:
Parameters
Description
-f fdb_name
(Required) Specifies the CID Foreign Database name
to be used in the ON FOREIGN DATABASE clause of
the CREATE FOREIGN TABLE statement. The Foreign
Database must be registered prior to executing
supra_tables. See "Registering a CID Foreign
Database" on page 29.
-i
(Optional) Specifies the path name of an input file
that contains the names of PDM or VSAM files for
which CREATE FOREIGN TABLE statements should be
generated. The list must contain one file name per
line.
-o output_filename
(Optional) Specifies the path name of an output file
to write the foreign table statements into instead of
writing the statements to standard output.
-p password
(Optional) Specifies the password that was specified
in the REGISTER FOREIGN DATABASE statement, if
any.
-u username
(Required) Specifies the username that was specified
in the REGISTER FOREIGN DATABASE statement, if
any.
SQL_ Access_server_name
(Required) This parameter is the name of the SQL
Access Server being used to store the foreign table
definitions.
Messages from the utility are written to the same file that receives the CREATE
FOREIGN TABLE statements and to stderr.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: Foreign Table Generator
249
The command to execute the Foreign Table generator for this example is as
follows:
foreign_tables –f burrys –o burrys.sql burrysrvr
This command will generate CREATE FOREIGN TABLE statements for all of the
files in the CID internal schema and write them to a file named burrys.sql in
the Windows directory where the command is executed. The registered CID
Foreign Database is named burrys and the SQL Access Server that will serve as
repository for the foreign table definitions is named burrysrvr.
The Foreign Database must be registered in the SQL Access Server prior to
running this utility.
The statements generated by the example above can then be loaded by
executing the generated file burrys.sql in Visual SQL or executing the following
statement from the Windows command prompt:
sqlx -u dba -i burrys.sql burrysrvr
The excerpt below shows the foreign table statements for the E$BR file.
(NOTE: The ‘$’ character is not valid and an underscore is substituted.) The
PDM directory contains external field names for all the fields, so the attribute
names in the foreign table are the corresponding external field names (with the
dash ‘-‘ replaced by an underscore because ‘-‘ is an invalid character in some
external tools). The attributes are in the same order as they exist in the PDM
file.
create foreign table E_BR on burrys
(BRANCH_NO char(4),
BRANCH_NAME char(20),
BRANCH_ADDR char(20),
BRANCH_CITY char(13),
BRANCH_STATE char(2),
BRANCH_ZIPCODE numeric(5),
BRANCH_REGION char(3),
BRANCH_DEL_ROUTE char(2),
BRANCH_SLS_QUOTA numeric(9,2),
BRANCH_STF_QUOTA numeric(5))
as
select "BRANCH-NO", "BRANCH-NAME", "BRANCH-ADDR", "BRANCH-CITY",
"BRANCH-STATE", "BRANCH-ZIPCODE", "BRANCH-REGION", "BRANCH-DELROUTE", "BRANCH-SLS-QUOTA", "BRANCH-STF-QUOTA" from "E$BR";
commit work;
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: Foreign Table Generator
250
createdb
The createdb utility creates SQL Access Servers and can define the initial users
to be authorized in the SQL Access Server. Normally, only the DBA uses the
createdb utility.
The location of logs and the SQL Access Server are also specified by createdb.
If SQL Access Server and log locations are not specified, the values in the SQL
Access Server location files (ordbinit.txt) are used. For more information on
the SQL Access Server location file, see "SQL Access Server location file" on
page 218. See "log_path" on page 336 for more information on specifying
default log locations.
Syntax
This command line syntax invokes the createdb utility:
createdb [options] SQL-Access-Server-name
where:
-
options includes those options described in the following table.
-
SQL-Access-Server-name specifies the name of your SQL Access Server.
It cannot be a path such as /usr/smith/test_db but must be a simple
name such as test_db. It must conform to the operating system filenaming requirements, it must not contain embedded blanks, and it
cannot consist of more than 17 characters.
Return values
Return values for createdb are as follows:
♦
Zero (0). On a successful execution.
♦
Nonzero. On an unsuccessful execution.
After creating a SQL Access Server, it is recommended that you run the backup
utility to insure recovery in the event of a hard disk crash.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: createdb
251
Options
-p integer
Pages. Select an appropriate number of pages for the intended SQL Access
Server application. The default value of 1000 creates a small SQL Access
Server information volume that is primarily useful for demonstration purposes.
The minimum value for this parameter is dependent on the page size. The
following table provides the minimum pages for each page size.
Page Size
Minimum Pages
1024
1600
2048
800
4096
400
8192
200
16384
100
For any substantial application, a SQL Access Server of ten thousand (10,000) or
more pages is recommended. The maximum number of pages is dependent
upon the maximum size of a volume allowed by your operating system and your
SQL Access Server page size (see the -ps option below). To add more than one
volume, use the addvoldb command. See "addvoldb" on page 263 for more
information.
-f dirname
SQL Access Server directory path. A SQL Access Server is normally created in
a directory created for that purpose. This standard makes it easier to maintain
multiple SQL Access Servers without concern for name conflicts among the
various files that make up the SQL Access Server. This option allows you to
specify the exact path name of a directory in which to create the new SQL
Access Server. If you do not specify -f, the current working directory is used.
-l dirname
Log file directory path. Log files are maintained as part of the SQL Access
Server. Cincom recommends maintaining log files in a directory or disk device
separate from the other SQL Access Server files. The -l option allows you to
specify the name of this directory. If you skip this option, the log files are
created in the same directory as the SQL Access Server (either the current
working directory or as specified with the -f option).
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: createdb
252
-lp number
Log pages. This option lets you customize the size of the log files for each
individual SQL Access Server (it overrides the value specified for the log_size
system parameter). The size of the log required varies according to the
amount of update activity, the duration of time of concurrent transactions,
etc. If you expect very few changes to occur, set the number of pages low. If
you expect a large number of changes, set this value high. If you do not
specify this option, the size of the log defaults to the value specified for
log_size. The minimum value for this parameter is dependent on the SQL
Access Server page size. The following table provides the minimum log pages
for each page size.
Page Size
Minimum Log Pages
1024
1600
2048
800
4096
400
8192
200
16384
100
The maximum is determined by your system capabilities. To avoid
performance degradation, do not specify a value that is less than 20% of the
estimated total SQL Access Server size. It is recommended that you specify a
value that is at least as large as the SQL Access Server size. If your application
requires mass object updates, specify a value that is at least twice as large as
the number of objects to be simultaneously updated. For more information on
how to calculate archive and active log sizes, see "Parameters related to
recovery/logging" on page 333.
-ps number
Page size. You can configure the page size to one of the following five values
(in bytes): 1024, 2048, 4096, 8192, or 16384. The default value is 16384. For
example, to set the page size of the mydb SQL Access Server to 2048, enter the
following command:
createdb -ps 2048 mydb
Note that createdb rounds a value falling between one of the allowable values
to the next larger number. Thus, the following command creates a SQL Access
Server with a page size of 8192.
createdb -ps 4097 mydb
A change in page size affects the num_data_buffers, num_log_buffers, and
sr_buffer system parameters.
-r
Overwrite flag. The createdb utility does not allow a SQL Access Server to be
created if there is an existing SQL Access Server with the same name. If you
want to overwrite an existing SQL Access Server, you must specify your intent
with the -r option. If this option is not specified, the existing SQL Access
Server is not overwritten.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: createdb
253
-o filename
Initialization output file. You can redirect the output of the createdb utility
to a file instead of displaying the output on the console. This option can be
useful if you want to save the createdb messages for later reference on how a
particular SQL Access Server was created.
-mv filename More volumes. You can specify a file that lists additional volumes for the SQL
Access Server that is created. This option can be used to spread a SQL Access
Server across multiple physical disk drives, which may be desirable for a large
SQL Access Server. The following sample file input allocates additional
volumes in the dbx directories on the D, E, and F drives:
# additional volumes for the dbx SQL Access Server
PATH
D:\DBX
NPAGES 5000
PATH
E:\DBX
NPAGES 5000
PATH
F:\DBX
NPAGES 5000
Comment lines in the file are preceded with the # character, as shown above
in the first line of input.
It is also possible to designate the volume purpose as part of the input. If no
purpose if specified, the volume is considered generic and eligible to hold any
kind of data. For the above sample, if the volume on drive F were to be used
for temporary data, the input line would be expanded to:
PATH
F:\DBX
PURPOSE TEMP
NPAGES 5000
See the –pu option of the addvoldb utility later in this chapter for details
regarding the four possible settings for PURPOSE.
-u filename
User definition file. You can specify the names of SQL Access Server users to
add during SQL Access Server creation. See "User definition file" on page 261
for details regarding file format.
-i filename
SQLX input file. You can specify the name of an SQLX input file to execute via
the sqlx program in standalone mode as the last step of SQL Access Server
creation. See “Using the SQL/X Processor” in the SQL Access for SUPRA Server
PDM SQL Reference Guide, P25-9503 for details regarding the sqlx program.
The sqlx program is run from createdb via the public user. If your input file
includes commands that require dba user authorization, add a line at the
beginning of the input file such as:
call login('dba', '') on class db_user;
... to sign on as the dba user. One possible use of this option is to define the
SQL Access Server schema when the SQL Access Server is created.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: createdb
254
-v
Verbose output. To maximize the amount of information about the createdb
utility operation, enable verbose output with the -v option. The -v option
takes no arguments. Both information about users defined in the SQL Access
Server and a full line-by-line listing of the SQL Access input file (if one was
specified) are included in the verbose output. The verbose option can be used
in conjunction with the -o option so that a history of the SQL Access Server
creation can be saved in a file.
-t
Temporary Volume directory path. When the SQL Access Server is created, a
permanent volume used for temporary data is allocated. This volume is used
for query results, sorting, etc. This option allows you to specify the exact path
name of an existing directory in which to place the permanent temporary
volume. If you do not specify the –t option, the temporary data volume will be
created in the same directory as the SQL Access Server (specified by the –f
option or in the current working directory).
-tp
Temporary Volume page count. The number of pages to allocate for the
permanent data area used for temporary query processing results. If this
option is not used, the number of pages will be the largest of 100 and onetenth of the number of pages allocated for the SQL Access Server. The
minimum number of temporary volume pages is dependent on the SQL Access
Server page size. The following table provides the minimum pages for each
page size:
Page Size
Minimum Pages
1024
800
2048
400
4096
200
8192
100
16384
50
-ca char-algorithm
CHAR collation algorithm. The collation algorithm for CHAR, CHAR VARYING
and/or STRING type. The possible values include BINARY or ICU. If -ca is not
specified, the default BINARY is used.
-na nchar-algorithm
NCHAR collation algorithm. The collation algorithm for NCHAR and/or NCHAR
VARYING type. The possible values include BINARY or ICU. If -na is not
specified, the default BINARY is used.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: createdb
255
-cl char-locale CHAR collation locale. Select the locale you want to use for collating CHAR
data type. You may select any locale available on the system or BINARY if you
do not want lexigraphical collation. The collation locale affects the order in
which data is returned from the SQL Access Server. Data selected via indices,
the ORDER BY clause, or a WHERE clause containing a string comparison will be
returned in the lexigraphical order specified by the locale. See "Choosing a
locale" on page 258.
Once a SQL Access Server is created, the collation locales may not be changed.
To change the SQL Access Server collation locales, the data must be unloaded
from the original SQL Access Server and reloaded into a new SQL Access Server
with the desired collation locales.
-nl nchar-locale
NCHAR collation locale. Select the locale you want to use for collating NCHAR
data type. You may select any locale available on the system or BINARY if you
do not want lexigraphical collation. The collation locale affects the order in
which data is returned from the SQL Access Server. Data selected via indices,
the ORDER BY clause, or a WHERE clause containing a string comparison will be
returned in the lexigraphical order specified by the locale. See "Choosing a
locale" on page 258.
Once a SQL Access Server is created, the collation locales may not be changed.
To change the SQL Access Server collation locales, the data must be unloaded
from the original SQL Access Server and reloaded into a new SQL Access Server
with the desired collation locales.
-lc charsetlist Comma-separated list of character sets. A comma-separated list of character
sets to be supported by the SQL Access Server for all locales specified. If an
algorithm or locale is specified that does not support a particular character set,
that character set may not be specified here even though the character set
might be valid for some other algorithm. Otherwise, a particular SQL Access
Client or Server would be in the position of attempting to support twocharacter sets simultaneously, which is expressly forbidden by SQL Access.
ORDB_CHARSET is an implicit member of the charsetlist and is the default
charsetlist if the -lc option is omitted. See "Choosing a locale" on page 258.
-b
SQL Access Server backup directory path. A backup SQL Access Server is
normally created in a directory created for that purpose. This standard makes
it easier to maintain multiple SQL Access Servers without concern for name
conflicts among the various files that make up the SQL Access Server. This
option allows you to specify the exact path name of a directory in which to
create the backup SQL Access Server. If you do not specify -b, the current
working directory is used.
-nb
No Backup. This option directs createdb to skip the initial backup performed
after SQL Access Server creation. By default, an initial backup of the SQL
Access Server is performed after a successful createdb.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: createdb
256
-q
Quiet. If used, createdb will not show its start nor end banners. The success
or failure of the createdb command will be displayed.
-pp
Prompt for remove password. Use this option to designate a SQL Access
Server password by entering the password at a prompt as hidden text. For
example, if this option is specified when creating the tempdb SQL Access
Server as follows:
createdb -pp tempdb
The following prompt is displayed:
Enter password for SQL Access Server tempdb:
The password entered at the prompt will be assigned to the SQL Access Server.
-pw
SQL Access Server Password. Use this option to assign a password to the SQL
Access Server. For example, to specify the password tmp when creating the
tempdb SQL Access Server, enter the following command:
createdb –pw tmp tempdb
Choosing a locale and character set
The supported locale - character set combinations are listed in the following
table:
Locale:
Valid Character Sets:
Collation Language:
De_DE
ISO-8859-1
German
En_US
ISO-8859-1
English – United States
Es_ES
ISO-8859-1
Spanish
Fr_FR
ISO-8859-1
French
Ja_JP
EUC
S_JIS
UTF-8
Japanese
BINARY
ASCII
ISO-8859-1
EUC
S_JIS
UTF-8
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: createdb
257
Choosing a locale
Locale is any valid SQL Access locale name defined in the file
%ORDB%\admin\locale.txt or BINARY. The locale.txt file is a user maintainable
text file containing one line for each SQL Access locale name. Each SQL Access
locale name is associated with a system locale name.
Example of a Windows locale.txt file
-- SQL Access locale name translate file for Windows
--- SQL Access locale name System locale name
En_US
American_America.1252
GERMAN
German_Germany.1252
SWISS
German_Switzerland.1252
-- end of file
The SQL Access locale names can be any meaningful string except “BINARY”.
Each SQL Access locale name must be associated with a valid system locale
name. Additionally, SQL Access locale names must be equal on all platforms in
the system. For example, a SQL Access Server is created with the
CHAR/VARCHAR collate locale set to GERMAN as in the example above. The SQL
Access Server and all SQL Access Client machines must have a locale.txt file
that contains the SQL Access locale name “GERMAN”. The system locale name
associated with the GERMAN SQL Access locale name may be different on each
platform.
A locale.txt file containing some SQL Access locale names is supplied for each
platform supported by SQL Access. Additional SQL Access locale names may be
added by the user as necessary. Comment lines starting with "--" and "blank
lines" are ignored.
The system locale you choose for collation must be defined to your operating
system. The locale is composed of the following fields:
language_country.code-page
where:
-
language_country may or may not be abbreviated on your machine.
-
code-page may be called a character set or an encoding on your
machine.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: createdb
258
The list of Microsoft locales may be obtained under “References” from
http://www.microsoft.com/globaldev:
To obtain:
Look under:
Locales
Locales and language groups
Code pages
Codepages – Windows
and
Codepages – OEM
Character sets
Character sets – ISO 8859
A list of language and country strings may also be obtained from Microsoft
Visual studio help (MSDN). Under "index" look for "country/region strings" and
then following the links to “language strings” and “country/region strings”.
SQL Access Server location file
The createdb utility and other utilities maintain a file named ordblist.txt that
contains information about the locations of all known SQL Access Servers.
In order to connect to a SQL Access Server, each SQL Access Client application
must specify the SQL Access Server name. The user is not required to supply
any other information such as the full path name of the SQL Access Server or
the host name of the SQL Access Server. Instead, this information is kept in a
common file that can be accessed by many users. This file is created and
maintained automatically by several utilities, including createdb, copydb,
renamedb, and deletedb. The file consists of a sequence of lines in the
following format:
db_name db_path_name server_host logfile_path_name
The SQL Access Server location file is located through the environment variable
ORDB_DATABASES. If this environment variable is set, it must be the name of a
directory containing the ordblist.txt file. If this environment variable is not
set, the current working directory is searched for the ordblist.txt file. In a
traditional environment, the DBA maintains a directory hierarchy containing
SQL Access Servers with the SQL Access Server location file at its root. The
DBA then ensures that all SQL Access Server users have their environment
variables set up properly to access the location file.
Because the utilities must be able to make modifications to the SQL Access
Server location file, the user must have write access to that file. If the
ORDB_DATABASES environment variable points to a directory for which the user
does not have write access, the user is not permitted to create a SQL Access
Server. In this case, either the DBA needs to grant the user write access to the
directory, or the user must create a private copy of the SQL Access Server
location file in a directory for which the user has access and set the
environment variable to this directory.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: createdb
259
The copydb, renamedb, and deletedb utilities can also update the SQL Access
Server location file. Always use these utilities to operate on SQL Access Server
files. Never use the operating system file system commands directly. Using
these utilities ensures that the SQL Access Server location file is maintained
consistently.
When working with SQL Access Clients and Servers, all SQL Access Servers must:
♦
Have unique names
♦
Be listed in one central SQL Access Server location file
All users working in client/server mode use the single, central SQL Access
Server location file. (When a SQL Access Server is started, the location of a
SQL Access Server is determined by the ORDB_DATABASES environment
variable.)
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: createdb
260
User definition file
The user definition file consists of one or more lines of USER statements. This
file name can be given with the -u option to automatically define authorized
users when the SQL Access Server is being created.
Syntax
USER user_name [ groups_clause | members_clause ]
groups_clause:
[ GROUPS user_name [ { user_name }… ] ]
members_clause:
[ MEMBERS group_name [ { group_name...
} ] ]
For each USER statement in your file, the user name is the name of the
authorized user. The name can be composed of alphanumeric characters and
must not contain embedded blanks.
The GROUPS clause is optional and allows the specification of one or more
groups of which the user is a member. The group name specification is no
different from the user name; the name supplied as group name is used as a
convention to identify a user that has one or more members. Each group name
that is specified in the MEMBERS clause must be defined in another user
statement elsewhere in the file.
Comments are allowed in the user definition file. Each comment line must
begin with a hyphen (-). Blank lines in the file are ignored. A USER statement
cannot be continued onto the next line. Instead, you can define several
statements for the same user (see Example 2 below).
Example 1
This example shows that user smith is a member of two groups, and the other
users (brown and jones) are each a member of one group. All users are
indirectly members of group company.
--- Example user definition file 1
-USER
USER
USER
USER
company
engineering
marketing
administration
USER smith
USER brown
USER jones
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: createdb
GROUPS company
GROUPS company
GROUPS company
GROUPS administration marketing
GROUPS engineering
GROUPS marketing
261
Example 2
This example demonstrates the cumulative effect of USER statements that
define the same user name. In this case, user brown is added as a member of
three groups. Because each USER statement must fit onto a single line, using
multiple USER statements can make the file more readable if a user is a
member of many groups.
--- Example user definition file 2
-USER engineering
USER marketing
USER administration
USER brown
USER brown
USER brown
GROUPS engineering
GROUPS administration
GROUPS marketing
Example 3
Another way of defining groups is illustrated in this example. In this case, the
members of the groups are defined with the MEMBERS keyword rather than the
group names being spread out among the individual users.
--- Example user definition file 3
-USER brown
USER smith
USER jones
USER engineering
USER marketing
USER administration
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: createdb
MEMBERS brown
MEMBERS smith jones
MEMBERS smith
262
addvoldb
The addvoldb utility adds new volumes to a SQL Access Server. Before new
volumes are added, the DBA is advised to plan a configuration that provides
some performance benefits. Performance is improved when these general
rules are followed:
♦
Fewer volumes with large amounts of disk space are preferred over many
volumes with small amounts of disk space.
♦
I/O contention is reduced when data, index, and temporary information are
stored in completely different volumes on different disk drives.
Syntax
This command-line syntax invokes the addvoldb utility:
addvoldb [options] SQL-Access-Server-name number-of-pages
where:
-
options includes those options described below.
-
SQL-Access-Server-name is the name of the SQL Access Server you wish
to expand. This name cannot be a path name, such as
C:\usr\smith\testdb, but instead must be a simple name such as testdb.
-
number-of-pages specifies the number of pages to allocate for the new
volume.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: addvoldb
263
Options
-f dirname
Volume extension directory path. This option designates the exact path name
of the directory where the new volume of the SQL Access Server is created.
When this argument is omitted, the value of the system parameter is used as
the default. The DBA normally decides the value of this option when storage
planning of the SQL Access Server is done.
-pu
Volume purpose. The storage purpose for the new volume can be stated with
this option. The possible values include:
♦
data. Holds user information of classes, instances, and multimedia data.
♦
index. Holds index information (used to speed up query processing and to
verify integrity constraints).
♦
temp. Holds temporary data that is used during query processing and
sorting routines.
♦
generic. Holds any kind of data, including data that is allowed with a data,
index, or temp purpose. This is the default if none is specified.
A volume purpose should be specified to improve I/O performance. Better
performance is achieved when user data is separated from index and temporary
data, which are then stored in different volumes and disk drives. This allows
the disk drives to work simultaneously, retrieving both the table and index at
the same time. This enhances performance when several users access the SQL
Access Server at the same time.
-sa
Standalone mode. This option invokes the addvoldb utility from the
standalone mode of execution. If the -sa option is specified, then -cs cannot
also be specified. If a mode option is not given, the value of the ORDB_MODE
environment variable is used as the default.
-cs
Client/server mode. This option invokes the addvoldb utility using the
client/server mode of execution. If the -cs option is specified, then -sa cannot
also be specified. If a mode option is not given, the value of the ORDB_MODE
environment variable is used as the default.
If neither the -sa option nor the -cs option is specified and the environment
variable ORDB_MODE is not defined, client/server mode is assumed.
-q
Quiet. If used, addvoldb will not show its start or end banners. The success or
failure of the addvoldb command will be displayed.
-pw
SQL Access Server Password. Use this option to specify the password if the
SQL Access Server has a password. For example, to specify the password tmp
of the tempdb SQL Access Server, enter the following command:
addvoldb –pw tmp tempdb 100
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: addvoldb
264
A prompt requesting the SQL Access Server password is displayed if an addvoldb
is attempted for a password protected SQL Access Server and the –pw option is
not specified. The password entered in response to this prompt is hidden while
it is being typed.
-ud
DBA user. Use this option to specify the dba user name. This option is useful
if access to the db_user class to obtain the dba user name is not permitted. If
the dba user is not accessible and the –np option is not specified, a prompt for
the dba user is displayed.
-pd
DBA password. Use this option to specify the dba user password. This option
is used when the –ud option is specified and the dba user has a password. A
prompt for the dba user password is displayed if the dba user is not accessible
and the –ud and –np options are not specified.
-np
No prompt for DBA user/password. With this option, the dba user and
password will not be requested if the dba user name cannot be obtained and
the –ud and –pd options are not specified.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: addvoldb
265
loaddb
The loaddb utility provides a quick and easy way to populate a SQL Access
Server with large amounts of data. The loaddb utility creates instances
directly in the SQL Access Server without incurring the overhead of loading the
new instances into the workspace.
The input file format for loaddb follows a simple tabular format. This format
makes it an effective means for importing large amounts of data from
traditional relational SQL Access Servers. To run loaddb, SQL Access Server can
be running in either standalone or client/server mode.
Loading the schema file
Before running the loaddb utility, you must load the schema file created by the
unloaddb utility into your newly created SQL Access Server. To do this, you
must run the sqlx command with the -i option as follows:
sqlx -i olddb.sch mydb -u dba
When the sqlx interpreter is used to load the schema file, always execute it
under the “dba” user by specifying -u dba in the command line. The generated
schema creation script contains calls to privileged methods (authorized for use
exclusively by the DBA).
Users migrating from a prior release: Before loading the schema
(DBNAME.schema) from a prior release, the DBNAME.schema file needs lines
inserted at the beginning of the schema file. This will allow multiple
transactions to be open at one time:
call login('dba', '') on class db_user;
update db_track_event set active = 'Off';
commit work;
In lieu of adding these lines to the schema file, another option is to add a
“commit work” before any “call login” commands in the file.
The ddltojava utility generates custom Java classes from a SQL Access Server
schema. The utility processes the schema (.sch) file produced by the unloaddb
utility and generates Java classes for use in your applications.
Even if you still have your schema file, Cincom recommends that you run the
unloaddb utility to generate a new schema file. This ensures that all system
classes are included in the schema used by the ddltojava utility.
For more information on the ddltojava utility, refer to the SQL Access for
SUPRA Server PDM SQL Reference Guide, P25-9503.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
266
Syntax
This command-line syntax invokes the loaddb utility:
loaddb [ options ] SQL-Access-Server-name input-file
where:
-
options includes those options described in the following table.
-
SQL-Access-Server-name is the name of an existing SQL Access Server
created with createdb. The name of the SQL Access Server cannot be
entered as a path (such as D:\usr\smith\test_db) but must be given as a
simple name (such as test_db).
-
input-file is a path name to the loader input file, which was generated
by the unloaddb utility or typed by the user. For the format of the
input file, see "Input file format" on page 270.
Return values
Return values for loaddb are as follows:
♦
Zero (0). On a successful execution.
♦
Nonzero. On an unsuccessful execution.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
267
Options
-sa
Standalone mode. This option specifies standalone mode and is the default
mode for loaddb. If this option is specified, client/server mode (-cs) cannot
also be specified.
-cs
Client/server mode. This option specifies client/server mode. If this option is
not specified, loaddb defaults to the mode set by the ORDB_MODE environment
variable. If this option is specified, standalone mode (-sa) cannot also be
specified.
-s
Syntax check only. Activating this flag causes the loaddb utility to perform
syntax and data type checking on the input file without creating instances in
the SQL Access Server. By default, a syntax check is always performed on the
input file before the SQL Access Server is modified.
-v
Verbose output. Activating this flag causes the loaddb utility to display status
messages as the SQL Access Server is being populated. Output statistics such as
current class being loaded, loading phase, syntax checking, and number of
instances for a specific class are displayed. Because loading large input files is
often a time-consuming process, enabling the verbose flag allows you to track
the progress with these statistics.
-e integer
Estimated number of objects. This option should be specified when the
number of objects to be defined is greater than the default number (2048).
The value of this option determines the overall performance of the load
operation. When the number is set too low, the load process may take a
substantially longer time to complete.
-l
Load only, no initial syntax check. Activating this option causes loaddb to
skip syntax and data type checking on the input file and proceed directly to
loading the SQL Access Server. Using this option saves time when the -s option
has already been used to check the input file. Errors may still be caught by
syntax and data type checking during the load phase.
-u string
Name of current user. This option specifies the name of the user under which
SQL Access Server access is performed. If no user name is supplied, the default
value of public is assumed.
-p string
Password. The password option specifies the password associated with the
current user name. This parameter is not required if the user does not have a
password for SQL Access Server access. If the current user has a password but
does not give the -p option, the user is prompted for the password at the
terminal. Note that the -p option is normally used to run the loaddb utility in
batch mode where interactive prompting for passwords is not desired.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
268
-c integer
Periodic commit count. When all of the instances from the input file have
been loaded into the SQL Access Server, loaddb automatically commits the
transaction. In some cases this commit may result in the generation of
numerous log archive files while loaddb executes. To prevent the generation
of log archives when large amounts of data are being loaded, you must set the
media_failures_are_supported system parameter in the ordbinit.txt file to
zero, and use the periodic commit option of loaddb. When the periodic
commit option is set to a value other than zero, loaddb regularly commits the
transaction after that number of instances has been inserted.
For example, if the -c option is set to 50, then a commit takes place after 50
instances have been inserted. Note that this value makes it impossible for
loaddb to remove insertions if an error is detected late in the load process.
Therefore, use this feature only after due consideration.
Cincom recommends that you do not use the -c option to loaddb on a SQL
Access Server that is already populated.
-vc
Verbose output on periodic commits. Activating this option causes loaddb to
display status messages as the SQL Access Server is being populated. The
output from this option is simpler than the statistics displayed under the -v
option. Instead, only a running total of the committed instances are shown.
The frequency of this display is determined by the setting on the -c option.
-nl
No logging option. This option directs the loader to run without logging. This
will speed up the load job, but errors will not be recoverable. Disabled by
default.
-nc
No unique constraints checking option. This option directs the loader to run
without checking for unique constraints violations. Disabled by default.
-q
Quiet mode. When enabled, the loader will not display starting and stopping
messages. Disabled by default.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
269
Input file format
The input file used with the loaddb utility is an ASCII text file that is formatted
as a sequence of command lines, data lines, and comments. The command
lines are used to define the format of subsequent data lines, and the data lines
describe the attribute values of the objects to be inserted into the SQL Access
Server. Comments are used to annotate the loaddb file.
Comments
SQL Access style comments, beginning with two hyphens (--), can be used as in
the following example:
-- This is a comment!
-- And this is another.
Command lines
Command lines must always begin with the percent (%) character. The
command name is then specified immediately after the %. There are two
commands that can be specified in the input file, the % class command, and
the %id command.
♦
%class command line. The %class command always precedes the data lines
used to populate the specified class. The format of the data lines is
determined by the order in which the attributes are listed in the %class
command line. The data lines must have a corresponding value (or NULL)
for every attribute in the preceding command line, but a value is not
required for every attribute that is defined in the class. If an attribute is
omitted from the command and data lines, the attribute value for that
instance is the default value (if one was defined) or NULL.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
270
Syntax
%class class_name ( attr_name [ { attr_name }… ] ) [
constructor_spec ]
where:
-
class_name is the name of an existing class in the SQL Access Server
that you want to populate.
-
attr_name is specified for each attribute in the class for which you
supply data.
-
constructor_spec is an optional specification that allows you to name a
previously defined class method to create and initialize the instances
of the class referenced in this command. This constructor specification
must be used to insert multimedia instances into a class. For more
information on the constructor_class option, see "Using a CLASS method
to populate a class" on page 279.
Example
The following %class command tells the loader that subsequent data lines
are used to create instances of the person class. Each data line that
follows the %class command line should contain two values: the first value
is associated with the name attribute, and the second value corresponds to
the age attribute. Note that it is not necessary to specify the type of the
attribute. This information is obtained by consulting the schema that is
stored in the SQL Access Server:
%class person (name age)
♦
%id command line. The %id command line creates an alternate class
identifier or alias for easier reference later in the input file. It precedes
data lines that use object references to populate a class.
Syntax
%id class_name class_id
where:
-
class_name is the name of an existing class in the SQL Access Server
that you want to populate.
-
class_id is given as an integer used in object references contained in
data lines of the input file.
See “Example 2” on page 276 for an example of using the %id.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
271
Data lines
The values given in the input file must match the corresponding attributes in
the class. If a value in a subsequent data line conflicts with the type of the
associated attribute, the load operation is not performed on that attribute, an
error message is displayed, and the loaddb operation halts.
For example, assume that the person class is defined with the name attribute
as a string, and the age attribute as an integer. The next listing shows the
previous command line with the appropriately structured data lines:
%class person (name age)
‘smith’
31
‘newman’
33
‘jones’
31
‘underwood’
47
Successive values on a data line must be separated by at least one space
character. A long data line can be continued onto the next line with a plus sign
(+). This continuation character is placed at the end of a line of text when the
next line is to be interpreted as a continuation of the previous line. The plus
sign must occur immediately after the close-quotation mark, with no space.
White space may appear between the plus sign and the open quotation mark on
the next line.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
272
The next table gives an example for each of the fundamental data types that
can be loaded from the input file:
Data type
Example value
SMALLINT
2048
INTEGER
123456789
†
123.456
FLOAT
†
DOUBLE
1.45693e+20
STRING
‘this is a string’
CHAR(n)
‘this is a char(19)’
TIME
‘10:20:00’
DATE
‘07/14/1776’
TIMESTAMP
‘1:03 pm 10/15/1992’
SET
{123}
MULTISET
{11223}
LIST (SEQUENCE)
{ ‘one’ ‘two’ ‘three’ }
BIT STRING
B’0100110010100011’
X’4ca3’
NCHAR(n)
N’Härder’
†
FLOAT and DOUBLE values can be expressed in simple form or in scientific
notation.
Single quote characters delimit STRING values. If the string is surrounded by
single quotes, it is not allowed to have escape sequences (that are translated
into a character) within the string. New-line characters within a string are
allowed. When you precede a string with any of the keywords DATE, TIME, or
TIMESTAMP, the string is interpreted as the keyword type when it is put into
the SQL Access Server.
Strings of an arbitrary size can be created using string continuation syntax. A
string to be continued must be terminated with a single quote and plus sign (+).
The string continuation must begin on the next line and must be enclosed in
single quotes, as follows:
‘This is an example’+
‘of a string created with continuation syntax.’
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
273
TIME values are entered as strings and are not required to have a value in the
seconds' field. In other words, the constant ‘10:20’ is interpreted as twenty
minutes after ten with zero seconds. Unless time values are followed by the
optional AM or PM, time values are based on a 24-hour clock, where the value
‘13:30’ is the same as ‘1:30 PM’.
TIMESTAMP values are entered as strings containing date and time information.
The order of the date and time are interchangeable.
A SET, MULTISET, and LIST (or SEQUENCE) must be enclosed in braces ({}). The
elements inside the braces can optionally be separated by commas (,).
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
274
Object references
The loaddb utility uses a special syntax for specifying references between
objects. The syntax for an object reference follows.
Syntax
@class_ref | instance_no
class_ref
- class_name
- class_id
class_name
- identifier
class_id
- integer
instance_no
- integer
An object reference consists of a class identifier and an instance number that is
unique to that class. The class can be referenced using the class name, or it
can be given as the class identifier, which is an integer value. Both the
class_name and the class_id must be immediately preceded by the @ symbol.
A vertical bar (|) separates the class_ref and the instance_no. Spaces are not
allowed on either side of the vertical bar. The instance number is stated as an
integer.
Example 1
The following object reference is for instance number 28 of the class person:
@person|28
Instance numbers are assigned when you include an instance number prefix on
a data line. This prefix must be given as a nonnegative integer that is unique
to that class and followed immediately by a colon.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
275
Example 2
Some instance prefixes are included in the following data lines:
%class person (name age)
1: ‘steve’
32
2: ‘joe’
33
3: ‘mary’
45
‘sarah’
23
Three of the four instances defined for class person were assigned instance
numbers. The instances prefixed by an instance number can later be
referenced elsewhere in the input file by using the appropriate object
reference. For example, the class automobile can now reuse the three
instances numbered in class person:
%class automobile (make owner)
‘Ford’
@person|1
‘Mazda’
@person|3
‘Jeep’
@person|2
‘Lexus’
@person|56
The attribute owner in class automobile points to a particular instance of class
person. Assuming instances 1–3 were created for class person, three
automobile instances are created to reference the previously defined person
instances.
Note that the last data line for class automobile references person instance
number 56, which has not yet been defined. You are allowed to reference
instances that have not previously been defined in the input file. If instance
number 56 is defined in a later data line, the loader knows that a reference has
already been made for this instance. The loaddb utility ensures that the object
identifier that was stored in a previous object is the same as the object
identifier that is associated with the new object.
If a forward reference to an instance is made, but the instance is never defined
in the input file, the loader automatically creates the instance using the
default attribute values that were defined for that class.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
276
Example 3
This example shows a complete loader input file:
%class person (name)
1: ‘sid’
2: ‘nancy’
%class automobile (owner)
@person|1
@person|2
@person|3
After this input file has been loaded, three instances of class person have been
created. Instances 1 and 2 contain the information that was specified in the
corresponding data lines. Instance 3 is built to satisfy the reference to
@person|3, and contains the default value for the name attribute. If a
default value for name has not been defined, instance 3 contains NULL.
As previously mentioned, instance numbers for a particular class must be
unique within the input file. When an instance number has been assigned, it
cannot be reused in another data line for that class. The next example shows
an illegal sequence of data lines that use the instance number 1 twice:
%class person (name)
1: ‘sid’
2: ‘nancy’
1: ‘john’
Instances of different classes, however, can use the same instance number. A
separate instance table is maintained for each class in the input data file.
Because the syntax of an object reference requires that you specify the class of
the instance that is being referenced, the correct instance can always be
identified even if several instances from different classes use the same
instance number. This requirement is illustrated in the following example.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
277
Example 4
This example defines two instances of different classes each using the instance
number 1:
%class person (name)
1: ‘sid’
%class automobile (make)
1: ‘rambler’
%class car_and_driver (owner auto)
@person|1 @automobile|1
An additional syntax option for object references uses the %id command line.
Instead of writing an object reference that includes the class name, the object
reference can be written more concisely by using a class identifier. To write
an object reference in this manner, a class identifier number must have been
previously assigned using the %id command line. Using class identifiers in
object references can significantly reduce the size of the data file, especially
when the classes have long names.
Example 5
Class identifiers are established and used as object references in the next
example:
%id person 1
%id automobile 2
%class car_and_driver (owner auto)
@1|100 @2|340
An instance of class car_and_driver references two other instances in the input
file: instance 100 of class person and instance 340 of class automobile. In this
form of the object reference syntax, the class identification number (rather
than the class name) is placed between the symbols @ and |.
A class can be assigned any integer as an identifier, but the same identifier
number cannot be shared by more than one class. It is recommended that your
identifier numbers begin at 1 and increment by a value of one. Although larger
numbers are valid, they cause unnecessary extra work during parsing of the
data file.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
278
Using a CLASS method to populate a class
The %constructor clause is an optional specification to the %class command
that allows you to name a previously-defined class method to create the
instances of a class. This clause is required for the construction of instances in
multimedia classes, but it populates any other user-defined class as well.
Syntax
%class class_name ( attr_name [ { attr_name }… ] ) [
constructor_spec ]
constructor_spec
- %constructor method_name ( [ arg_name [ { arg_name }… ] ])
method_name
- identifier
arg_name
- identifier
The method_name you designate must be a CLASS method that is defined or
inherited by the class that is being populated with the %class command. The
load process aborts if a method with the specified name is not found. The
class method must be written such that a new instance is created or returned
when the method is called. The loaddb utility calls the specified method each
time a new data line is encountered for the class. An example of a simple
constructor method follows:
%class employee (name age) %constructor new_employee ()
‘fred’ 20
‘lisa’ 30
In this example, the method new_employee is called twice because two data
lines follow the command. There are no arguments for the new_employee
method; existing instances are returned and updated with the values found on
the data lines. Note that the constructor method is not responsible for
assigning the attribute values from the data lines. Rather, the method only
creates or initializes the instances. The values on each data line are assigned
by the loaddb utility after the method has returned the instance.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
279
When you define a constructor method that takes arguments, each argument
must be specified in the %constructor clause. The values associated with each
argument are placed on the data lines following the values for the attributes.
The method in the next constructor example has one argument called major:
%class student (name age) %constructor new_student (major)
‘fred’ 20 ‘nursing’
‘lisa’ 30 ‘architecture’
The data lines in this example each contain three values. The first two
correspond to the attributes name and age, and the last value represents the
input argument that is passed to the method new_student. As in the previous
example, the method in this example is called once for each data line. The
argument that is passed to the method is examined to perform the complex
initialization of the new instance.
For example, suppose that the student class contains numerous attributes that
are related to a student’s chosen major. Rather than duplicating the
initialization of these attributes on each data line, the initialization can be
encapsulated in the constructor method.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: loaddb
280
unloaddb
The unloaddb utility is used with the loaddb utility to compress a SQL Access
Server or to migrate an existing SQL Access Server to a new release of SQL
Access. In other words, the unloaddb and loaddb utilities reload a SQL Access
Server from one version to another. The unloaddb utility runs only in
standalone mode. For complete information on the loaddb utility, see "loaddb"
on page 266.
The following commands illustrate unload and load processes (as entered from
a system prompt) used to compress a SQL Access Server.
desoto% unloaddb testdb
desoto% createdb testdb -r
desoto% sqlx testdb -sa -u dba -i testdb.sch
desoto% loaddb -u dba testdb testdb.obs
desoto% sqlx testdb -sa -u dba -i testdb.idx
The unloaddb utility produces three files:
♦
Schema file. Contains the schema definition of the SQL Access Server. It
is created with the name of the SQL Access Server prefixed to .sch, shown
as testdb.sch in the previous example.
♦
Object file. Contains the objects (instances) that are contained in the SQL
Access Server. It is created with the name of the SQL Access Server
prefixed to .obs, shown as testdb.obs in the previous example.
♦
Index file. Contains indexes defined in the SQL Access Server. The index
file name is formed from the name of the SQL Access Server prefixed to
.idx, shown as testdb.idx in the previous example.
Large objects (LOs) are unloaded into the same directory as the schema,
object, and index files. When loaddb is later called to load the object file,
these objects are found in the same directory as the object file and will be
correctly loaded into the SQL Access Server.
When the sqlx interpreter loads the schema file, it should always be executed
under the “dba” user by specifying -u dba in the command line.
The schema creation script that is generated contains calls to privileged
methods that are authorized for use only by the DBA.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: unloaddb
281
Syntax
This command-line syntax invokes the unloaddb utility:
unloaddb [options] SQL-Access-Server-name
where:
-
options includes those options described below
SQL-Access-Server-name is the name of an existing SQL Access Server
that you wish to unload.
Return values
Return values for unloaddb are as follows:
♦
Zero (0). On a successful execution.
♦
Nonzero. On an unsuccessful execution.
The unloaddb utility does not unload the privileged or default user in the
schema file or the objects file. However, if either the privileged (DBA) and or
default user (PUBLIC) have been renamed, unloaddb validates the values of the
privileged and default user. If either one has been renamed, you would find
the following command at the end of the schema file generated by unloaddb:
rename privileged user to 'newprivname';
Options
-e integer
Estimated number of instances. Aids the internal hashing function of the
object table manager. The default is to query the statistics, determining the
number of instances in the SQL Access Server. If the statistics have not been
refreshed recently or if querying the statistics is not desired, the -e option
should be specified. If the number you specify with this option is too small,
many hash collisions occur, resulting in decreased performance of the unload
process.
-n integer
Object-table pages. Determines the number of object-table pages to cache in
memory. The object table is used to map internal object identifiers to
instance numbers in the object output file. The table is maintained in a
temporary file with some number of pages being cached. Each page is 4096
bytes; setting this value is a trade off between memory and speed. A larger
cache usually causes faster execution. The default is 100 pages.
-od dirname
Directory for output files. Used when the output files for schema and object
need to be created in a specific directory. When this option is not used, the
output files are created in the current working directory.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: unloaddb
282
-so
Schema only output file. By default, both the schema and object output files
are generated from the unloaddb utility. When you only want the schema file
to be created, specify the -so option. If this option is specified, the objects
only output file (-oo) cannot also be specified.
-oo
Objects only output file. By default, both the schema and object output files
are generated from the unloaddb utility. When you only want the object file to
be created, specify the -oo option. If this option is specified, schema only
output file (-so) cannot also be specified.
-p string
Output file prefix. A specific string can be entered with the -p option to be
used as the prefix to the schema and object output files. This string precedes
“schema” and _objects in the names of the output files that are generated.
When this option is not specified, the name of the SQL Access Server being
unloaded is used as the default prefix.
-f pathname
Hash filename. The object table built by unloaddb uses a temporary file that
may consume a considerable amount of disk space. By default, the system
routine tmpnam is called to choose a pathname for the temporary file. When
specified, the -f option determines the pathname for the object table file. The
file is deleted when unloaddb completes execution.
-v
Verbose output. This option enables verbose output during processing of the
unloaddb utility. Activating this flag displays messages indicating which class is
being processed and the amount of instances processed for that class.
-i
Class names. Points to a file containing the names of classes to include in the
unload job. Each class name should appear on a separate line in the file. All
classes will be unloaded if this parameter is not specified.
-ir
Include references option. When you use the –i option to explicitly unload
selected classes, references to classes not included in the unload will be set to
NULL. If you specify the –ir option, instances referenced by the selected
classes will also be unloaded. The schema definition for all classes will also be
generated when this option is selected.
-u string
Name of current user. This option specifies the name of the user under which
SQL Access Server access is performed. If no user name is supplied, the default
value of dba is assumed.
-pw string
Password. The password option specifies the password associated with the
current user name. This parameter is not required if the user does not have a
password for SQL Access Server access. If the current user has a password but
does not give the -pw option, the user is prompted for the password at the
terminal. Note that the -pw option is normally used to run the unloaddb utility
in batch mode where interactive prompting for passwords is not desired.
-q
Quiet mode. When enabled, the loader will not display starting and stopping
messages.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: unloaddb
283
-s
Cached page size. This option specifies the cached page size. The default
value is 4096.
-d
Debug flag. This option is for debugging and should only be used when
directed by Cincom Technical Support.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: unloaddb
284
copydb
The copydb utility copies or moves SQL Access Servers from one location to
another. The system copies every volume and control file of the SQL Access
Server into the new destination and creates a new log to support the new SQL
Access Server. You must give the new SQL Access Server a name different from
the name of SQL Access Server that you are copying.
Because a SQL Access Server is made up of several interdependent volumes,
you should not use the operating system file commands to copy or move the
SQL Access Server files. Rather, using the copydb utility ensures that all of the
associated files are properly copied. The copydb utility must be run offline; in
other words, it should not be run when someone else is using the SQL Access
Server.
The SQL Access Server location file is modified to add the entry for the new
SQL Access Server and optionally delete the entry for the source SQL Access
Server. For more information, see "SQL Access Server location file" on
page 218.
Recovery information from the source SQL Access Server is not included in the
destination SQL Access Server. This information includes information from
backups and active/archive logs. Cincom recommends making a backup of the
destination SQL Access Server (using backupdb) after the copy is done.
Syntax
This command-line syntax invokes the copydb utility:
copydb [options] src-SQL-Access-Server-name dest-SQL-AccessServer-name
where:
-
options includes those options described below.
src-SQL-Access-Server-name is the name of an existing SQL Access
Server (such as test_db).
dest-SQL-Access-Server-name is the name of the SQL Access Server
copy that is made.
The src-SQL-Access-Server-name and the dest-SQL-Access-Server-name
cannot be a path such as D:\usr\smith\test_db, but must be simple
names such as test_db. To designate a directory location for the new
SQL Access Server copy, use the -f option (as shown in the " Example"
on page 288).
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: copydb
285
Return values
Return values for copydb are as follows:
♦
Zero (0). On a successful execution.
♦
Nonzero. On an unsuccessful execution.
Options
-f dirname
SQL Access Server directory path. The system normally creates a SQL Access
Server in a dedicated directory. This standard makes it easier to maintain
multiple SQL Access Servers without concern for name conflicts among the
various files that make up each SQL Access Server.
The -f option allows you to specify the exact path name of a directory in which
to create the destination SQL Access Server. If you do not specify the -f option
or the -tf option (volume copy path file), the system uses the current working
directory as the target SQL Access Server directory path. Otherwise, the SQL
Access Server directory path is found in the volume copy path file. Similar to
the SQL Access Server host name, the system maintains the SQL Access Server
directory path in the SQL Access Server location file. This path allows a SQL
Access Client application started in another directory to correctly determine
the full path name of the SQL Access Server files when given only the SQL
Access Server name.
When the SQL Access Server directory path is specified with the -f option, the
-tf option should not be specified.
-l dirname
Log file directory path. The system maintains log files as part of the SQL
Access Server. Cincom recommends that you maintain log files in a directory
and disk device that is separate from the other SQL Access Server volumes.
This option allows you to specify the name of this directory. If you do not
provide this option, the system creates the log files in the same directory as
the new SQL Access Server.
-e dirname
Volume extensions directory path. This option specifies the exact path name
into which volume extensions for the destination SQL Access Server are to be
copied. When this option is not specified, the system describes the location of
each specific volume in the file supplied with the -tf option. If the -e and -tf
options are both omitted, the system creates volume extensions in the same
location as the source SQL Access Server volumes.
When a path is given with the -e option, the -tf option should not be specified.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: copydb
286
-tf filename
Volume copy path file. When you need a more sophisticated copy of the SQL
Access Server volumes, the system can supply a file containing the names and
placement of individual volumes into different directories.
All volumes of the source SQL Access Server must be contained in this file.
The syntax that identifies each volume is as follows:
volid source_fullvolname dest_fullvolname
where:
-
volid is an integer that identifies the volume number
-
source_fullvolname parameter is the source path name for the volume
-
dest_fullvolname is the destination path name for the new volume
You must supply all parameters for each volume. This file can be easily
constructed by copying the SQL Access Server volume information control file
to the file specified with the -tf option. The first two arguments (volid and
source_fullvolname) are already in the volume copy path file, which must then
be edited to include the dest_fullvolname parameter.
When a copy path file is specified with the -tf option, the -e and -f options
should not be given.
-r
Overwrite flag. The copydb utility does not allow a new SQL Access Server
(the destination SQL Access Server) to be created if there is an existing SQL
Access Server with the same name. If you want to overwrite an existing SQL
Access Server, you must specify your intent with the -r option.
-m
Move flag. The copydb utility normally leaves the source SQL Access Server in
place after the copy. To delete the source SQL Access Server after the copy,
use the move flag. This flag’s function is identical to using the deletedb utility
after the SQL Access Server has been copied.
-q
Quiet. The starting and ending information banners will not be displayed if
this option is used. This is enabled by default.
-ps
Source SQL Access Server password. If the –m (move) option is specified and
the source SQL Access Server is protected, this option specifies the source SQL
Access Server password.
A prompt requesting the source SQL Access Server password is displayed if a
copydb -m is attempted for a password protected source SQL Access Server and
the -pm option is not specified. The password entered in response to this
prompt is hidden while it is being typed.
-pr
Destination SQL Access Server password. If the –r (replace) option is
specified and the destination SQL Access Server is protected, this option
specifies the destination SQL Access Server password.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: copydb
287
A prompt requesting the destination SQL Access Server password is displayed if
a copydb -r is attempted for a password protected destination SQL Access
Server and the -pr option is not specified. The password entered in response to
this prompt is hidden while it is being typed.
-pd
Destination SQL Access Server password. The password to assign to the
destination SQL Access Server. If this SQL Access Server already exists, use the
–pr option instead.
Example
Given the situation below:
♦
Source directory = D:\usr\db
♦
Name of source SQL Access Server = costs_db
♦
Destination directory = D:\usr\db\dbsavedir
♦
Name of destination SQL Access Server = dbcosts_db
... use the copydb utility as shown to copy costs_db to dbcosts_db in the
directory D:\usr\db\dbsavedir. The -m option causes costs_db to be deleted
after the copy:
copydb -m -f D:\usr\db\dbsavedir costs_db dbcosts_db
For example, the SQL Access Server testdb comprises the following volumes:
testdb.ord
located in
D:\usr\database
testdb.v1
located in
D:\usr\paul\ext
testdb.v2
located in
D:\usr\jon\ext
testdb.v3
located in
D:\usr\mary\ext
testdb.v5
located in
D:\usr\database
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: copydb
288
The next three scenarios show different ways to use the copydb utility, where
the testdb SQL Access Server is copied to a new SQL Access Server called
demodb:
♦
Scenario 1. Copy demodb from the testdb SQL Access Server, keeping the
new demodb volumes in the same location as the source volumes of testdb:
% copydb testdb demodb
♦
Scenario 2. Copy demodb from the testdb SQL Access Server, but place all
new volumes for demodb in the directory /usr/database/demodb:
% copydb -f D:\usr\database\demodb -e D:\usr\database\demodb
testdb demodb
♦
Scenario 3. Copy demodb from the testdb SQL Access Server, but place all
new volumes in different locations with different default names. The log
files should be placed on a disk drive that is different from the SQL Access
Server information volumes.
The following table shows the names of the volumes and directories where the
new volumes are placed:
Old volume name
New volume name
New directory path name
Testdb.ord
demodb
D:\jon\db/data
Testdb.v1
demodb.v1
D:\jon\db/data
Testdb.v2
demodb.v2
E:\jon\db/index
Testdb.v3
demodb.v3
E:\jon\db/index
Testdb.v4
demodb.v4
D:\jon\db\extension
Testdb.v5
demodb.v5
D:\jon\db\extension
The system uses information volume testdb.orv as the basis for the volume
copy path file that is given with the -tf option. In this example the name of the
file is “copypath”, so you copy testdb.orv to copypath. The volume
identification numbers and source paths/volume names are already in the file,
but you must add the destinations and new volume names to this file (as shown
next in the edited version of copypath):
0 /usr/database/testdb.ord D:\jon\db\data\demodb
1 /usr/paul/ext/testdb.v1 D:\jon\db\data\demodb_jondata1
2 /usr/paul/ext/testdb.v2 E:\jon\db\index\demodb_jonindex1
3 /usr/jon/ext/testdb.v3 E:\jon\db\index\demodb_jonindex2
4 /usr/jon/ext/testdb.v4 D:\jon\db\extension\demodb_jongen1
5 /usr/database/testdb.v5 D:\jon\db\extension\demodb_jonext5
Then refer to this file with the -tf option in the next copydb command:
% copydb -l F:\jon\db\logs -tf copypath testdb demodb
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: copydb
289
deletedb
The deletedb utility deletes a SQL Access Server. Because a SQL Access Server
is made up of several interdependent files, you should not use the operating
system file deletion commands to remove a SQL Access Server. You can use
the deletedb utility to ensure that all of the associated files (data, log, backup)
are properly removed. The SQL Access Server location file is also modified to
remove the entry for the specified SQL Access Server.
The deletedb utility must be run offline (when no one is using the SQL Access
Server); otherwise, deletedb fails.
Cincom strongly recommends that you copy the SQL Access Server to tape (or
some location other than the log and backup directories) before running
deletedb.
Syntax
This command-line syntax invokes the deletedb utility:
deletedb [options] SQL-Access-Server-name
where:
-
options includes those options described below.
-
SQL-Access-Server-name is the name of the SQL Access Server. It
cannot be a path such as D:\usr\smith\test_db but must be a simple
name such as test_db.
Return values
Return values for deletedb are as follows:
♦
Zero (0). On a successful execution.
♦
Nonzero. On an unsuccessful execution.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: deletedb
290
Options
-o
Output Redirection. This specifies the filename where the output will be
written. The default is to display messages on the console.
-q
Quiet. The starting and ending information banners will not be displayed if
this option is used. Default is enabled
-pw
SQL Access Server Password. Use this option to specify the password if the
SQL Access Server that is being deleted has a password. For example, to
specify the password tmp of the tempdb SQL Access Server that is being
deleted, enter the following command:
deletedb –pw tmp tempdb
A prompt requesting the SQL Access Server password is displayed if a deletedb
is attempted for a password protected SQL Access Server and the –pw option is
not specified. The password entered in response to this prompt is hidden while
it is being typed.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: deletedb
291
renamedb
The renamedb utility changes the current name of an existing SQL Access
Server. The information volumes, log volumes, and control files are renamed
to coincide with the new name. Unlike copydb, renamedb does not require any
additional disk storage, because the SQL Access Server is renamed in place.
The renamedb utility is different from copydb in that it does not allow you to
change the location of the volumes to another disk partition (for example, to
another disk drive or another file system).
The renamedb utility must be run offline (it should not be run when someone is
using the SQL Access Server); otherwise, renamedb fails.
Syntax
This command-line syntax invokes the renamedb utility:
renamedb [options] src-SQL-Access-Server-name dest-SQL-AccessServer-name
where:
-
-
options includes those options described below.
src-SQL-Access-Server-name is the name of the source SQL Access
Server. It cannot be a path such as D:\usr\smith\test_db, but must be a
simple name such as test_db.
dest-SQL-Access-Server-name is the name of the destination SQL Access
Server. It must conform to the operating system file name conventions,
must not contain spaces, and must be 17 characters or less.
If a SQL Access Server with the new name already exists, the rename operation
is aborted and an error message displayed. If renamedb is successful, the SQL
Access Server location file is automatically updated to reflect the new name.
The names of the files that compose the SQL Access Server are also renamed to
correspond to the new name.
Return values
Return values for renamedb are as follows:
♦
♦
Zero (0). On a successful execution.
Nonzero. On an unsuccessful execution.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: renamedb
292
Options
-tf filename
Volume rename path file. When a more sophisticated renaming scheme for
the SQL Access Server volumes is needed, a file can be supplied containing the
names and placement of individual volumes into different directories. All
volumes of the source SQL Access Server must be contained in this file.
The syntax that identifies each volume is as follows:
volid src_fullvolname dest_fullvolname
where:
-
volid is an integer that identifies the volume number
-
src_fullvolname is the source path name for the volume
-
dest_fullvolname is the destination path name for the new volume
All parameters must be supplied for each volume. The dest_fullvolname must
be in the same disk partition (or same file system) as the src_fullvolname; if
these paths are different, the rename procedure fails. This file can be easily
constructed by copying the SQL Access Server volume information control file
(database.orv) to the file that is specified with the -tf option. The first two
arguments (volid and src_fullvolname) are already in the rename path file,
which must then be edited to include the dest_fullvolname parameter. For a
similar example of this file configuration, see "copydb" on page 285.
When a rename path file is specified with the -tf option, the -e option should
not be specified.
-f pathname
SQL Access Server Files Pathname. Use this option to specify the pathname
for the renamed SQL Access Server files. If this option is not specified, then
the existing SQL Access Server file locations will be used.
-q
Quiet. The starting and ending information banners will not be displayed if
this option is used. Enabled by default.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: renamedb
293
-pw
SQL Access Server Password. Use this option to specify the password if the
SQL Access Server that is being renamed has a password. For example, to
specify the password tmp of the tempdb SQL Access Server that is being
renamed to permdb, enter the following command:
renamedb –pw tmp tempdb permdb
A prompt requesting the SQL Access Server password is displayed if a renamedb
is attempted for a password protected SQL Access Server and the –pw option is
not specified. The password entered in response to this prompt is hidden while
it is being typed.
-ud
DBA user. Use this option to specify the dba user name. This option is useful
if access to the db_user class to obtain the dba user name is not permitted. If
the dba user is not accessible and the –np option is not specified, a prompt for
the dba user is displayed.
-pd
DBA password. Use this option to specify the dba user password. This option
is used when the –ud option is specified and the dba user has a password. A
prompt for the dba user password is displayed if the dba user is not accessible
and the –ud and –np options are not specified.
-np
No prompt for DBA user/password. With this option, the dba user and
password will not be requested if the dba user name cannot be obtained and
the –ud and –pd options are not specified.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: renamedb
294
Displaying the SQL Access release version
The whichdb utility displays the SQL Access release that you are running.
Syntax
This command line syntax invokes the unirel utility:
whichdb
Example
To display your current SQL Access release enter the following command:
C:> whichdb
The system responds in the following format:
Cincom ORDB Release 2.1
Build 2146 2003-09-09 14:30:37 at Cincom
Copyright (C) 1991-2003 NTT DATA CORPORATION
All Rights Reserved
Copyright 1997-2003 CINCOM SYSTEMS, INC.
All Rights Reserved
Licensed to 999-999-998
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: Displaying the SQL Access release version
295
checkdb
The checkdb diagnostic utility is used to verify a SQL Access Server. It checks
the internal physical consistency of the data and log volumes to verify their
indices and other data structures. To run checkdb, you must be logged in as
DBA.
The DBA should periodically run checkdb as part of routine maintenance, if
possible. Since the time required running checkdb rises with the size of the
SQL Access Server, this may not be practical with very large SQL Access
Servers.
The checkdb utility problems are found and reported, but no action is taken to
correct the problems.
Syntax
This command line syntax invokes the checkdb utility:
checkdb [options] SQL-Access-Server-name
where:
-
options includes those options described below.
-
SQL-Access-Server-name is the SQL Access Server to be verified. It
cannot be a path such as D:\usr\smith\test_db but must be a simple
name such as test_db.
Return values
Return values for checkdb are as follows:
♦
Zero (0). On a successful execution.
♦
Nonzero. On an unsuccessful execution. The error log will contain the
inconsistencies.
All non-fixed problems listed in the error log need to be analyzed by
Cincom Technical Support, who will then advise you on your best choices of
action to put your SQL Access Server back into a consistent state.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: checkdb
296
Options
-sa
Standalone mode. This option specifies standalone mode. If this option is not
specified, the utility defaults to the mode set by the ORDB_MODE environment
variable. If this option is specified, client/server mode (-cs) cannot also be
specified.
-cs
Client/server mode. This option specifies client/server mode. If this option is
not specified, the utility defaults to the mode set by the ORDB_MODE
environment variable. If this option is specified, standalone mode (-sa) cannot
also be specified.
If any of the following options (-vp, -vh, -ph, -hp, -bt, -cl, -bh) are used, then
only the specified checks will be performed. If none of these options are used,
then all checks will be performed. Cincom recommends that you do not specify
these options without direction from Cincom Technical Support.
-vp
Volume Path Check. This option will check that the location of the SQL Access
Server volume match the location information found in the SQL Access Server
information files.
-vh
Volume Header Check. The header information in each SQL Access Server
volume will be verified. This information includes total pages and free pages,
and total sectors and allocated sectors.
-ph
Page Header Check. The header information in each SQL Access Server page
of each SQL Access Server file will be verified. This information includes total
pages and free pages, and total sectors and allocated sectors on a file-by-file
basis.
-hp
Heap Page Check. All heap files are validated by checking that all pages
identified by the heap file manager do indeed belong to the heap file being
checked.
-bt
B-Tree check. All btree files in the SQL Access Server will be validated to
make sure the tree is constructed correctly.
-cl
Class Check. Validates the mapping between object identifiers and the heap
files used for object storage.
-bh
Heap Page Check and B-Tree Check. Validate the consistency between the
heap files and the b-tree files.
-q
Quiet. The starting and ending information banners will not be displayed if
this option is used. Enabled by default.
-ud
DBA user. Use this option to specify the dba user name. This option is useful
if access to the db_user class to obtain the dba user name is not permitted. If
the dba user is not accessible and the –np option is not specified, a prompt for
the dba user is displayed.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: checkdb
297
-pd
DBA password. Use this option to specify the dba user password. This option
is used when the –ud option is specified and the dba user has a password. A
prompt for the dba user password is displayed if the dba user is not accessible
and the –ud and –np options are not specified.
-np
No prompt for DBA user/password. With this option, the dba user and
password will not be requested if the dba user name cannot be obtained and
the –ud and –pd options are not specified.
Example output
The following example shows sample output to the screen after checkdb gives a
nonzero return value. The error messages are also added to the error log. If
no errors are found, then only the first two lines will appear and the error log
is unchanged.
Cincom ORDB Release 2.1
Build 2146 2003-09-09 14:30:37 at Cincom
Copyright (C) 1991-2003 NTT DATA CORPORATION
All Rights Reserved
Copyright 1997-2003 CINCOM SYSTEMS, INC.
All Rights Reserved
Licensed to 999-999-998
error messages
Some inconsistencies were detected in your database.
Please consult error_log_file database_name.err for additional information.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: checkdb
298
Password maintenance
The changedb utility is used for password maintenance. Use this utility to add
a password to an unprotected SQL Access Server, change the SQL Access Server
password, or unprotect a SQL Access Server by removing the password.
Syntax
This command line syntax invokes the changedb utility:
changedb [options] SQL-Access-Server-name
where:
-
options includes those options described in the following table.
-
SQL-Access-Server-name is the target SQL Access Server. It cannot be a
path such as D:\usr\smith\tempdb but must be a simple name such as
tempdb.
Return values
Return values for changedb are as follows:
♦
Zero (0). On a successful execution.
♦
Nonzero. On an unsuccessful execution.
Options
-sa
Standalone mode. This option specifies standalone mode. If this option is not
specified, the utility defaults to the mode set by the ORDB_MODE environment
variable. If this option is specified, client/server mode (-cs) cannot also be
specified.
-cs
Client/server mode. This option specifies client/server mode. If this option is
not specified, the utility defaults to the mode set by the ORDB_MODE
environment variable. If this option is specified, standalone mode (-sa) cannot
also be specified.
-pn
New password. Add a password to an unprotected SQL Access Server. In this
example, the password tmp is assigned to the tempdb SQL Access Server:
changedb tempdb –pn tmp
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: Password maintenance
299
-pc
Current password. Specify the current password when changing the password.
This is used in conjunction with the –pn option, as in the following example
where the password for tempdb is changed from tmp to tpw:
changedb tempdb –pc tmp –pn tpw
-pr
Remove password. Specify the current password to unsecure the SQL Access
Server. In this example, the password tmp will be removed from the tempdb
SQL Access Server:
changedb tempdb –pr tmp
-pp
Prompt for remove password. Use this option to remove the SQL Access
Server password by entering the password at a prompt as hidden text. If the
password is to be removed from tempdb, the following command:
changedb tempdb –pp
will result in this prompt:
Enter password for database tempdb:
and the password will be removed from the SQL Access Server if it was entered
correctly at the prompt.
-ud
DBA user. Use this option to specify the dba user name. This option is useful
if access to the db_user class to obtain the dba user name is not permitted. If
the dba user is not accessible and the –np option is not specified, a prompt for
the dba user is displayed.
-pd
DBA password. Use this option to specify the dba user password. This option
is used when the –ud option is specified and the dba user has a password. A
prompt for the dba user password is displayed if the dba user is not accessible
and the –ud and –np options are not specified.
-np
No prompt for DBA user/password. With this option, the dba user and
password will not be requested if the dba user name cannot be obtained and
the –ud and –pd options are not specified.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: Password maintenance
300
Processing when no options are specified
If changedb is executed with only the SQL Access Server name, the subsequent
processing depends on whether the SQL Access Server has a password. If the
SQL Access Server is unprotected, changedb will request a new password, and
if the SQL Access Server already has a password, changedb will prompt for this
password as part of a change operation. For example, if tempdb has no
password and the following command is executed:
changedb tempdb
the following two prompts are displayed
Enter new password for database tempdb:
Confirm new password for database tempdb:
and the same password must be entered at both prompts. If tempdb already
has a password, however, then changedb will assume a password change is
desired and three prompts are displayed to complete the password change:
Enter current password for database tempdb:
Enter new password for database tempdb:
Confirm new password for database tempdb:
The second and third prompts are only displayed if the current password is
entered correctly at the first prompt. The same password must be entered for
both the second and third prompts to change the password.
Administration Guide, P25-9501-04
Chapter: 7. Utilities
Section: Password maintenance
301
8. Controlling SQL Access for
SUPRA Server PDM processes
This chapter describes the programs and utilities used to start and shut down
SQL Access for SUPRA Server PDM (SQL Access) processes.
Programs to start or shut down the SQL Access Server
This section describes a variety of initialization, termination, and monitoring
programs for the SQL Access Server. Only the DBA uses these programs. The
ordbinit.txt file contains network information (the service name and the TCP
port ID) that is used by the programs described in the subsections that follow.
At installation the SQL Access Master and SQL Access Server processes are set
up to run as a service, which means they will start automatically when the
system boots. If you wish to shut down the SQL Access Server without
rebooting, it can be stopped and restarted using the Visual Administration tool.
If you wish to do this from a DOS prompt, use the commdb command to stop
the SQL Access Server and execute the server program to restart the SQL
Access Server (see "The commdb utility" on page 307 and "The SQL Access
Server program" on page 306 for more information).
The SQL Access Master service can be stopped and started between system
boots by using the mastersrv command.
Running SQL Access Master as a service (Windows)
Services are processes that automatically start as the system boots and then
remain running as background processes no matter who is currently logged in.
Master can run as a Windows Service.
Administrator privileges are required to run SQL Access Master as a Windows
service. Attempting to run mastersrv without administrator privilege results in
an error.
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Programs to start or shut down the SQL Access Server
302
In order to run SQL Access Master as a Windows service:
♦
Define ORDB in the system environment variables pointing to the ORDB
executable directory.
♦
Add the ORDB directory to the system path.
♦
The ORDB_DATABASES environment variable should point to the directory
that contains the ordblist.txt.
♦
Run the command mastersrv –install from the command prompt.
This installs SQL Access Master as a service.
♦
From the Control Panel → Services applet, set SQL Access Master Server to
start automatically.
♦
Reboot and verify using the COMMDB -P utility.
♦
The command mastersrv –remove will uninstall SQL Access Master as
service.
♦
The command mastersrv –stop will stop the SQL Access Master as a
service.
♦
The command mastersrv –start will start the SQL Access Master as a
service after it has been stopped.
You may run SQL Access Master as a user console job by issuing a “master”
command from the command prompt.
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Programs to start or shut down the SQL Access Server
303
The Server as service (Windows)
To run local SQL Access Servers as a service do the following:
♦
Create ordbserv.txt file in %ORDB%\admin folder
♦
Add the SQL Access Server names to the ordbserv.txt file or **all** to run all
SQL Access Servers in the ordblist.txt file as a service
♦
Make sure ORDB_DATABASES environment variable is pointing to the
directory that contains the ordblist.txt
♦
The options described in the section "The SQL Access Server program" on
page 306 can be specified for an individual SQL Access Server in this form:
<server_name> <option>
Verify by using the commdb –p command. The SQL Access Servers on stand-by
are the ones that will run as service. Servers on stand-by will automatically
start as a service when a SQL Access Client attempts to connect to it. The SQL
Access Server will then remain running. Restarting your machine is not
necessary to re-initialize the server list. Instead, issue a commdb -r command
to re-initialize the SQL Access Master.
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Programs to start or shut down the SQL Access Server
304
The SQL Access Master program
The SQL Access Master is a network listener program that acts as a referee for
new SQL Access Client requests.
Syntax
To start the SQL Access Master program, type the following at your system
prompt:
start/min master
WINDOWS
master&
UNIX
At startup time, SQL Access Servers register themselves with the SQL Access
Master so new requests from remote SQL Access Clients can be passed to the
correct SQL Access Server. You should start the SQL Access Master when the
host machine is rebooted. Each machine on the network that will host one or
more SQL Access Servers requires a SQL Access Master to be running on that
machine.
Return values
Return values for SQL Access Master are as follows:
♦
Zero (0). On a successful execution.
♦
Nonzero. On an unsuccessful execution.
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Programs to start or shut down the SQL Access Server
305
The SQL Access Server program
The SQL Access Server is a single process, multi-thread program that provides
storage for SQL Access Foreign Database and Foreign Table definitions that are
used by SQL Access Client applications. One machine can host one or more
SQL Access Servers. The SQL Access Server handles all SQL Access Client
connections either from the same machine or individual machines on the
network running SQL Access Client applications. The SQL Access Server can
store any number of Foreign Database definitions that may be hosted by the
same CID Adapter Server host machine or different ones. See "Registering a CID
Foreign Database" on page 29 for more information on defining Foreign
databases. The following syntax should be used to start a SQL Access Server:
start server [options] SQL-Access-Server-name
WINDOWS
start_server [options] SQL-Access-Server-name
UNIX
Options
Command-line options for the SQL Access Server program are shown in the
following table:
Option
Description
-q
Disables the display of the starting and ending information
banners.
-p port-id
Override the OS assignment of a TCP/IP port.
-r
Brings up the SQL Access Server with a read-only schema.
-s
Allows modification of most system classes.
When this parameter is specified, all system classes can be
altered with the exception of db_root, db_authorization,
db_user, db_password, db_locale-base, db_locale_binary,
db_track_event, and db_event.
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Programs to start or shut down the SQL Access Server
306
The commdb utility
The commdb utility prints status information about the SQL Access Master and
Server programs to standard output. It also provides a way for the user to shut
down a specified SQL Access Server or to shut down the SQL Access Master
program and all currently running SQL Access Servers. A shutdown process can
be initiated immediately or delayed by a specified number of minutes. When a
shutdown request is delayed, the user can halt the shutdown before the
shutdown time expires.
The commdb utility can be invoked in two ways:
♦
As an interactive program
♦
As a command-line driven program
The commdb utility requires a SQL Access Master program to be running on the
host with which it is attempting to communicate.
The commdb utility now ships with 500 permissions (instead of 555), so only the
identified SQL Access user can execute it.
Using commdb from the command line
The command-line version of commdb supports the same features as the
interactive version of commdb, with an added difference: you can use
command-line arguments to invoke commdb. Options entered from the
command line are case-sensitive.
Syntax
commdb [ -h [ host_name ] ] -P
commdb [ -h [ host_name ] ] -R
commdb [ -h [ host_name ] ] –V { server_name }
commdb [ -h [ host_name ] ] [ -T { minutes } ] -A
commdb [ -h [ host_name ] ] [ -T { minutes } ] -S
{ server_name }
commdb [ -h [ host_name ] ] -H
commdb [-I server_name]
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Programs to start or shut down the SQL Access Server
307
Options
The following table describes the supported set of arguments for the commandline version of commdb:
Option
Description
-h [ host_name ]
Identifies the host name; if none is specified, the
default is the current host.
-S SQL_Access_Server_name
Identifies the SQL Access Server name for
shutdown. If a shutdown time is not given (-T
minutes), zero minutes is used.
-V SQL_Access_Server_name
Identifies the SQL Access Server name to start
up.
-R
Reinitializes the SQL Access Master process.
-H
Halts the shutdown process.
-A
Shuts down the SQL Access Master and all SQL
Access Servers. If a shutdown time is not given
(-T minutes), zero minutes is used.
-P
Prints the SQL Access Master and SQL Access
Server status to stdout.
-I server_name
Causes immediate shutdown of the named SQL
Access Server. commdb cannot halt an
immediate shutdown request.
-q
Quiet. Disables the display of starting and
ending information banners.
-pw
SQL Access Server password.
The password must be supplied for any protected SQL Access Server before it
can be shut down. If the SQL Access Server is password protected and the
password is not supplied via the –pw option, a prompt requesting the SQL
Access Server password is displayed. The password entered in response to this
prompt is hidden while it is being typed.
If the –A option is used to shut down more than one SQL Access Server that is
password protected, the passwords for all of the protected SQL Access Servers
must be supplied. The passwords are separated by commas. For example, xdb
(password x), ydb (password y), and zdb (password z) are all running. All three
can be shut down via the –A option as follows:
commdb –A –pw x,y,z
Commdb will verify the passwords before doing the shutdown, so all the
passwords must be correctly specified or none of the SQL Access Servers will be
shut down. If the –pw option is not specified with the –A option and one or
more of the SQL Access Servers is protected, the password(s) will be requested
via a prompt. For the above example, three prompts will be displayed:
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Programs to start or shut down the SQL Access Server
308
Enter password for database xdb:
Enter password for database ydb:
Enter password for database zdb:
and the passwords entered in response to the prompts are hidden while being
typed. The passwords must be correctly specified at all the prompts or none of
the SQL Access Servers will be shut down.
Example
As an example, suppose you want to print the status of the SQL Access Master
and connected SQL Access Servers on host jaguar. In this case, the commdb
invocation and the resulting output looks like this:
commdb -h jaguar -p
The master running on host jaguar
was started at Mon Dec 06 14:07:53 1999
has serviced 16 requests. 1 server(s) running,
0 server(s) standing by.
Server foo, fd = 5, running.
To use the command-line version of commdb to shut down the SQL Access
Server foo on host bar in 5 minutes, enter the commdb invocation as follows:
commdb -h bar -S foo -T 5
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Programs to start or shut down the SQL Access Server
309
Using commdb from a menu
Call the commdb with no arguments or with only the -h (host_name) argument
to invoke the interactive version of commdb.
Syntax
commdb [ -h [ host_name ] ]
When invoked in this manner, commdb prints a list of options:
Options:
P
S
A
H
I
R
V
J
:
–
–
–
Q - quit
print
shutdown one server
shutdown master and all servers
halt shutdown
immediate server shutdown
reinitialize master
start a server
shutdown Java Method Broker
The colon (:) prompts for the commdb menu selection. Note that you can
enter the option characters from this menu as either upper or lowercase
letters. With the exception of option Q (to quit interactive commdb), the
system redisplays the option menu after the option processes.
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Programs to start or shut down the SQL Access Server
310
Options
The following table describes the interactive commdb options:
Option
Description
Q
Quits the commdb program.
P
Prints the state of the SQL Access Master program and the
names of connected SQL Access Servers.
S
Shuts down the SQL Access Server. The commdb program
prompts for the name of the SQL Access Server and the number
of minutes to wait before shutdown. If a shutdown time is not
entered, the default value of zero minutes is used and the
shutdown is immediate.
A
Brings down all SQL Access Servers and the SQL Access Master
program. The commdb program prompts for the number of
minutes to wait before shutdown. If a shutdown time is not
entered, the default value of zero minutes is used and the
shutdown is immediate.
H
Terminates a previous shutdown request.
I
Causes immediate shutdown of a specified SQL Access Server.
The commdb utility cannot halt an immediate shutdown
request.
R
Reinitializes the SQL Access Master process.
V
Starts the specified SQL Access Server.
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Programs to start or shut down the SQL Access Server
311
The following screen shows the selection of the -P option from the commdb
menu, which causes the status of the SQL Access Master program and its
connected SQL Access Servers to print at the terminal:
Options:
Q - quit
P - print
S - shutdown one server
A - shutdown master and all servers
H - halt shutdown
I - immediate server shutdown
R – reinitialize master
V – start a server
J – shutdown Java Method Broker
:P
The master running on host jaguar
was started at Wed Sep 09 14:03:20 2003
has serviced 16 requests. 1 server(s) running,
0 server(s) standing by.
Server foo, fd = 5, running.
When the S option is selected from the commdb menu, the system prompts you
for the name of the SQL Access Server to shut down and the number of minutes
before shutdown occurs:
Options:
Q - quit
P - print
S - shutdown one server
A - shutdown master and all servers
H - halt shutdown
I - immediate server shutdown
R – reinitialize master
V – start a server
J – shutdown Java Method Broker
:S
Name of server to shutdown : foo
How many minutes until shutdown? : 10
Server foo notified of shutdown
To bring down all SQL Access Servers and the SQL Access Master program, type
in the A option from the commdb menu. A prompt appears, asking you to enter
the minutes to wait before shutdown takes place. The value you enter must be
an integer or zero, as shown in the next screen:
Options:
Q - quit
P - print
S - shutdown one server
A - shutdown master and all servers
H - halt shutdown
I - immediate server shutdown
R – reinitialize master
V – start a server
J – shutdown Java Method Broker
:A
How many minutes until shutdown? : 3
Master will shut down in 3 minutes
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Programs to start or shut down the SQL Access Server
312
You can halt a SQL Access Server shutdown (S) or SQL Access Master/all SQL
Access Servers shutdown (A) if the time given until shutdown has not expired.
In the previous example, the shutdown of the SQL Access Master and all SQL
Access Servers is aborted by entering the H option within the 3-minute
shutdown period:
Options:
P
S
A
H
I
R
V
J
:H
Halted the shutdown
Options:
P
S
A
H
I
:
–
–
–
Q - quit
print
shutdown one server
shutdown master and all servers
halt shutdown
immediate server shutdown
reinitialize master
start a server
shutdown Java Method Broker
process
-
Q - quit
print
shutdown one server
shutdown master and all servers
halt shutdown
immediate server shutdown
Upon successful completion of commdb with either the -A or -S option, the
following error message displays (by default to the SQL Access Server error
file):
ERROR***ERROR CODE= -673. Your connection to the
database server has been closed since the server is
going down immediately.
This error message confirms successful completion.
To cause the immediate shutdown of a SQL Access Server, select I from the
commdb menu. After you enter option I, the system prompts you for the
name of the SQL Access Server to shut down:
Options:
Q - quit
P - print
S - shutdown one server
A - shutdown master and all servers
H - halt shutdown
I - immediate server shutdown
R – reinitialize master
V – start a server
J – shutdown Java Method Broker
:I
Name of server to shut down : foo
Server foo notified of shutdown
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Programs to start or shut down the SQL Access Server
313
If the SQL Access Master program shuts down while the commdb program is still
running, the next option selected from the interactive menu exits the program
as if the Q (quit) option were selected:
Options:
Q - quit
P - print
S - shutdown one server
A - shutdown master and all servers
H - halt shutdown
I - immediate server shutdown
R – reinitialize master
V – start a server
J – shutdown Java Method Broker
:A
How many minutes until shutdown? : 0
Master will shutdown in 0 minutes
Options:
Q - quit
P - print
S - shutdown one server
A - shutdown master and all servers
H - halt shutdown
I - immediate server shutdown
R – reinitialize master
V – start a server
J – shutdown Java Method Broker
:P
(desoto) 60%
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Programs to start or shut down the SQL Access Server
314
Checking the status of the SQL Access Master and connected SQL
Access Servers
The statusdb utility prints the status of the SQL Access Master and Server
programs.
Syntax
The following command-line syntax prints the status of the SQL Access Master
Server(s) to stdout:
statusdb [option]
Options
The following command-line option is available for the statusdb utility:
Option
-h [ host_name ]
Description
Identifies the host name; if none is
specified, the default is the current
host.
For example, suppose you want to print the status of the SQL Access Master
and connected SQL Access Servers on host jaguar. In this case, the statusdb
invocation and the resulting output looks like this:
statusdb -h jaguar
The master running on host jaguar
was started at Fri Sep 07 14:07:53 2003
has serviced 16 requests. 1 server(s) running,
0 server(s) standing by.
Server foo, fd = 5, running.
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Checking the status of the SQL Access Master and connected SQL Access Servers
315
Killing a transaction
The killtran utility aborts active transactions from outside their normal
execution environment. This utility can only be used by the DBA of the SQL
Access Server. The killtran utility can only be used in client/server mode. The
transaction is only removed from the SQL Access Server; the SQL Access Client
process is not removed. The next time the SQL Access Client tries to contact
the SQL Access Server, however, the SQL Access Client is notified that its
transaction has been aborted. Some reasons the DBA will kill an active
transaction are:
♦
The user has left the office without committing/aborting a transaction that
has acquired important resources and is preventing other users from
continuing their SQL Access Server session. The DBA can find out what
resources a SQL Access Client has by running the lockdb utility.
♦
A SQL Access Client process of a transaction is no longer active, but the
SQL Access Server system has not been able to detect its failure.
♦
The Cincom ORDB Visual Administration Tool can also be used to view
transactions, query lock information about transactions, and kill
transactions.
Syntax
killtran [options] SQL-Access-Server-name
where:
-
options includes options described in the following table.
-
SQL-Access-Server-name is the name of the SQL Access Server.
Return values
♦
Zero (0). On a successful execution.
♦
Nonzero. On an unsuccessful execution.
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Killing a transaction
316
Options
The following table shows the command-line options for the killtran utility:
Option
Description
-t tranIndex
Kill transaction associated with transaction index.
-u user
Kill all transactions associated with user.
-h clientHost
Kill all transactions associated with SQL Access Client host.
-pg progname
Kill all transactions associated with SQL Access Client
program name.
-p dbaPassword
Password of the DBA user. System will prompt if not
specified.
-d
Display information about active transactions. This is the
default if no options are specified.
-v
Prompt for verification to kill transactions. The default is
TRUE.
-q
Disables the display of starting and ending information
banners.
Only one of -t, -u, -h, or -pg is allowed. If no options are given, the -d option
is assumed and the utility displays the current information about all active
transactions.
The killtran utility screen consists of the information:
Column name
Description
Tran index
Transaction index
User name
Name of user
Host name
Name of host for user
PID
Process ID
CONN
Number of connections the user has
Program name
Name of program for user
Clients before Release 1.2 will have an empty CONN column.
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Killing a transaction
317
Examples
1. Find out the active transactions of SQL Access Server testdb:
Tran index
User name
Host name
PID
CONN
Program name
-------------------------------------------------------------------1
user1
host1
8559
1
usqlx_cs
2
user1
host1
8566
1
usqlx_cs
3
user2
host1
8567
1
usqlx_cs
--------------------------------------------------------------------
2. Kill all transactions of user1 and verify that the transactions have been
removed. Kill transactions of user1:
Tran index
User name
Host name
PID
CONN
Program name
-------------------------------------------------------------------1
user1
host1
8559
1
usqlx_cs
2
user1
host1
8566
1
usqlx_cs
-------------------------------------------------------------------Do you wish to proceed? (Y/N)
Press y to continue. The system responds:
Killing transaction associated with transaction index 1
Killing transaction associated with transaction index 2
Verify that the above two transactions have been removed by displaying
the currently active transactions:
C:\> killtran testdb
The system responds:
Tran index
User name
Host name
PID
CONN
Program name
-------------------------------------------------------------------3
user2
host1
8567
1
usqlx_cs
--------------------------------------------------------------------
Now user 'user1' finds that his transactions have been killed:
sqlx> select * from foo;
sqlx> ;x
The system responds:
ERROR: Your transaction has been aborted by the system due to server failure.
3. Restart two SQL Access Client transactions on different host machines and
display the active transactions:
C:\> killtran testdb
The system responds:
Tran index
User name
Host name
PID
CONN
Program name
-------------------------------------------------------------------3
user2
host1
8567
1
usqlx_cs
4
user1
host2
23118
1
usqlx_cs
5
user1
host3
16438
1
usqlx_cs
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Killing a transaction
318
--------------------------------------------------------------------
4. Kill all transactions associated with host3 using the -h option:
C:\> killtran testdb -h host3
The system responds:
Ready to kill the following transactions:
Tran index
User name
Host name
PID
CONN
Program name
-------------------------------------------------------------------5
user1
host3
16438
1
usqlx_cs
-------------------------------------------------------------------Do you wish to proceed? (Y/N)
Press y to kill the transaction. The system responds:
Killing transaction associated with transaction index 5
5. Now kill all transactions associated with program usqlx_cs having the -pg
option:
Ready to kill the following transactions:
Tran index
User name
Host name
PID
CONN
Program name
-------------------------------------------------------------------3
user2
host1
8567
1
usqlx_cs
4
user1
host2
23118
1
usqlx_cs
-------------------------------------------------------------------Do you wish to proceed? (Y/N)
Press y to continue. The system responds:
Killing transaction associated with transaction index 3
Killing transaction associated with transaction index 4
6. Display the active transactions with the killtran utility:
killtran testdb
No transactions are displayed.
Administration Guide, P25-9501-04
Chapter: 8. Controlling SQL Access for SUPRA Server PDM processes
Section: Killing a transaction
319
9. SQL Access for SUPRA Server
PDM system parameters
The values assigned to system parameters determine the overall performance
and behavior of the SQL Access for SUPRA Server PDM (SQL Access) system. The
parameter values are located and applied only at startup time of the individual
component (SQL Access Client, SQL Access Master, SQL Access Server).
SQL Access system parameters have default values (assigned in the system
code) that you can redefine by setting the parameter values in an ordbinit.txt
file for an installation, a desired SQL Access Server, or a particular user. The
SQL Access Server looks for ordbinit.txt files in the following locations in the
order shown:
WINDOWS
♦
%ORDB%\admin directory
UNIX
♦
$ORDB/admin directory
♦
Home directory of the SQL Access Server
On the SQL Access Client, the software looks for the ordbinit.txt file in the
following locations in the order shown:
WINDOWS
♦
%ORDB%\admin directory
UNIX
♦
$ORDB/admin directory
♦
Working directory of the process that is starting up
The ordbinit.txt file in the admin directory defines default parameter values
for an installation; that is, it defines the values for all SQL Access Servers.
Settings found in an ordbinit.txt file override any values that may have been
previously assigned to system parameters.
Values do not have to be specified for all parameters. For example, the user’s
ordbinit.txt file can redefine only a few parameters; unspecified parameters do
not need to be included in the ordbinit.txt file.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: Killing a transaction
320
After all ordbinit.txt files have been read, the process environment is searched
for environment variables of the form ORDB_parameter_name, where
parameter_name is the uppercase parameter name defined below. If such an
environment variable exists, that value of the environment variable overrides
the value previously assigned to the parameter.
For example, if the ORDB_SR_BUFFERS environment variable is set, the value of
ORDB_SR_BUFFERS replaces any value of the sr_buffers parameter in the
ordbinit.txt file.
For a list of ordbinit.txt file parameters, see "Summary of SQL Access system
parameters" below. Descriptions of the parameters appear in the sections
following the summary table.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: Killing a transaction
321
Summary of SQL Access system parameters
The following table contains a summary of SQL Access standalone, SQL Access
Client, SQL Access Master, and SQL Access Server parameters that compose the
ordbinit.txt file, including their associated defaults and the range of values you
can provide for each one. These parameters are described in detail after the
table.
If you enter a value outside the range of values, the default is used.
Parameter
Default value
Accepted range of values
active_requests
50
lower limit: 1
no maximum limit
auto_increment_modify
0
0 or 1
auto_volext_factor
1.0
≥ 0.0
backup_buffer_size
1 (multiplier)
≥1
backup_max_volume_size
-1 (no limit)
≥ 32K
charcode_check
0
0 or 1
lang=En_US:
Charset
lang=En_US:
ISO-88591
lang=Ja_JP,
HP-UX & NT:
S-JIS
lang=Ja_JP,
Solaris:
EUC
lang=Ja_JP:
checkpoint_interval
100
≥ 10
class_representation_cache
50
commit_on_shutdown
connection_timeout
0
3 (seconds)
≥ 10
0 or 1
lower limit: 1
no maximum limit
deadlock_detection_interval
30 (seconds)
default_adapter_dir
none
event_handler
none
execute_queries_streaming
1
fbo_root
flush_data_buffer_factor
null
.80 (80%)
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: Summary of SQL Access system parameters
ISO-88591
ASCII
UTF-8
S-JIS
EUC
UTF-8
≥ 0 (seconds)
See "default_adapter_dir" on
page 355.
See "event_handler" on
page 328.
See
"execute_queries_streaming"
on page 349.
See "fbo_root" on page 346.
.30 - 1.0 (30 - 100%)
322
Parameter
Default value
hot_fault_objects
hot_load_workspace
ignore_timezone
initial_workspace_table_siz
e
isolation_level
0
4096 (4K)
Accepted range of values
See "hot_fault_objects" on
page 348.
See "hot_load_workspace" on
page 348.
0 or 1
≥ 1 (K)
keep_schema_locks
TRAN_REP_CLASS
_COMMIT_INSTANCE
1 or YES
See "isolation_level" on
page 341.
0 or 1
Lang
Ja_JP
Ja_JP, En_US
lock_escalation
1000 (locks)
lock_timeout_in_secs
20
lockf_enable
log_path
log_reserve_space
log_size
1 or YES
SQL_Access_Server_location
0
SQL_Access_Server_size
≥ 5 (locks)
0 (do not wait)
>0
0 or NO, 1 or YES
user_defined_location
0 or 1
master_port_id
1978
≥ 100 (pages)
See "master_port_id" on
page 344.
max_block_count
0 (no limit)
≥ 0 (blocks)
max_block_size
128K
max_char_string_size
8,388,602
16 ≤ K ≤ 8192
16384 to 1,073,741,823
max_clients
500
Lower limit: 1
no maximum limit
max_lock_structures
1000
10 to 1000
max_quick_size
256 (bytes)
≥ 32 (bytes) ≤ 1K
max_ping_wait
5
maxlength_error_log
3000*80 characters
≥1
lower limit: 100*80
characters
no upper limit
maxtmp_pages
-1 (infinite/no limit)
media_failures_are_support
ed
multiple_connection_shared
_objects
1 (YES or ON)
1 (True)
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: Summary of SQL Access system parameters
-1 or ≥ 0
0 (NO or OFF)
1 (YES or ON)
0 (False) or 1 (True)
323
Parameter
Default value
Accepted range of values
network_pagesize
network_service_name
num_data_buffers
32K
sqlx
3000 (buffers)
1K - 1024K
user_defined_port_name
num_log_buffers
50 (buffers)
object_mode_character
optimization_level
query_cache_max_entries
query_cache_server_statisti
cs
query_cache_statistics
query_cache_threshold
query_max_rows
query_oidset_threshold
query_stream_window
query_timeout
request_threads_to_start
0
1
100
0 (no)
≥ 3 (buffers)
0 or 1
0 or 1
>= 0
0 (no) or 1 (yes)
select_star_includes_identity
server_inserts
socket_recv_timeout
sr_buffers
0
1 (true)
0
16 (buffers, 4K each)
standalone
unfill_factor
0
.10 (10%)
unfill_index_factor
.20 (20%)
Unload_max_column
70
use_index_concurrency
volext_path
Voltmp_path
warn_outofspace_factor
1
SQL_Access_Server_location
SQL_Access_Server_location
.15 (15%)
0 (no)
1
0 (infinite)
9
2
0 (infinite)
0
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: Summary of SQL Access system parameters
≥ 5 (buffers)
0 (no) or 1 (yes)
>= 0
0-2147483648
0 to 100
0 – 65536
0-2147483648
See "request_threads_to_start"
on page 343.
0 or 1
0 (false) or 1 (true)
0-2147483648
16 ≤ (buffers, 4K each) ≥ 500
0 or 1
0 (no space reserved)
>.00 - .30 (>0 – 30%)
0 (no space reserved)
>.00 - .35 (>0 – 35%)
Lower limit 1
No upper limit.
0 or 1
user_defined_location
user_defined_location
0 (no warning issued)
>.00 - 1.0 (>0 - 100%)
324
Displaying parameter values currently in effect
The print_param class method on system class db_root can be called to display
the parameters currently being used by the SQL Access Client or SQL Access
Server.
♦ Syntax to display SQL Access Client parameters:
call print_params(‘client’) on class db_root
♦
Syntax to display SQL Access Server parameters:
call print_params(‘server’) on class db_root
SQL Access Servers created before Socrates XML Release 1.2 do not have this
new function in the schema. Since you cannot modify db_root, the function
can be added with one of the following:
n create class foo
or:
o
method class print_params() function print_params_method;
alter class bar add
method class print_params() function print_params_method;
Then:
or:
p
call
call
call
call
print_params(‘server’) on class foo;
print_params(‘client) on class foo;
print_params(‘server’) on class bar;
print_params(‘client’) on class bar;
The create or alter may be committed or rolled back as desired.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: Displaying parameter values currently in effect
325
Syntax for parameters
The following syntax rules apply to parameters:
♦ Parameter names in the ordbinit.txt file are not case-sensitive. For
example, log_path and LOG_PATH are the same parameter.
♦ When you set the value of a parameter, you can include white space
(blanks or tabs) on either side of the equal sign:
lock_escalation = 100
or
lock_escalation=100
Regardless, both the parameter name and the value must be on the same
line.
♦
If the value assigned to a parameter is a string, quotes are only needed if
the string contains white space.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: Syntax for parameters
326
Standalone parameters
The parameters for the standalone version of SQL Access Server are the same
as those for the client/server version of the product (described in the following
sections), with the exception of the communication and concurrency control
parameters. The system ignores the communication and concurrency control
parameters in the standalone version because this version does not support
multiple concurrent users.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: Standalone parameters
327
SQL Access Server parameters
This section describes a variety of parameters that configure and tune a SQL
Access Server installation. The DBA should define the values of these
parameters.
Parameters related to error messages
This section contains information on configuring error messages that are logged
by SQL Access.
event_handler
This parameter acts as an interface to the event notification facility. It allows
selective delivery and categorization of messages to a process outside of SQL
Access. If event_handler does not exist in the ordbinit.txt file, no event
filtering takes place. The parameter should be the full path name of a userprovided executable event handler. By default, no event handler is installed.
%ORDB%\demo\evnthand.exe (Windows) or $ORDB/demo/evnthand (UNIX)
supplies an example event handler executable program. This program outputs
the messages it receives from the SQL Access Server to a file named
event_handler.log. Upon successful completion of the SQL Access Server, a
status code of 0 is returned. If an error occurs, the SQL Access Server returns a
status code of 1 and the event handler prints an error message in the
event_handler.log file. %ORDB%\demo\evnthand.c (Windows) or
$ORDB/demo/evnthand.c (UNIX) supplies the C source file for the example
event handler. Use this file as a framework to customize event notification for
your needs.
An external configuration file identifies selective error/event codes of interest.
A default configuration file is supplied in %ORDB%\admin\event.cfg (Windows)
or $ORDB/admin/event.cfg (UNIX) and is given here for reference. If event
notification is turned on, then the system reads this file to get the list of
events (error Ids) to select for notification. The default list contains a list of
the critical events. Each line in the event.cfg file uses the following format:
error_name<tab>error_info
where:
-
error_name is the error number constant defined in
%ORDB%\include\dber.h
-
error_info is a free format string containing user data
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
328
This example has a severity and error group field:
ER_OUT_OF_VIRTUAL MEMORY
Fatal
ER_IO_FORMAT_FAIL
Severe
Memory unavailable
Disk I/O
ER_IO_FORMAT_OUT_OF_SPACE
Severe
Disk unavailable
ER_IO_DISMOUNT_FAIL
Warning
Disk space
ER_IO_READ
Warning
Disk I/O
ER_IO_WRITE
Warning
Disk I/O
ER_IO_WRITE_OUT_OF_SPACE
Severe
Disk space
ER_DK_ALMOST_OUT_OF_SPACE
Warning
Disk space
ER_DK_DATA_ALMOST_OUT_OF_SPACE
Warning
Disk space
ER_DK_INDEX_ALMOST_OUT_OF_SPACE
Warning
Disk space
ER_DK_GENERIC_ALMOST_OUT_OF_SPACE
Warning
Disk space
ER_DK_TEMP_ALMOST_OUT_OF_SPACE
Warning
Disk space
ER_DK_LAST_ALMOST_OUT_OF_SPACE
Severe
Disk space
ER_DK_DATA_LAST_ALMOST_OUT_OF_SPACE
Severe
Disk space
ER_DK_INDEX_LAST_ALMOST_OUT_OF_SPACE
Severe
Disk space
ER_DK_GENERIC_LAST_ALMOST_OUT_OF_SPACE
Severe
Disk space
ER_DK_TEMP_LAST_ALMOST_OUT_OF_SPACE
Severe
Disk space
ER_FL_NOT_ENOUGH_PAGES_IN_DATABASE
Severe
Disk space
ER_FL_NOT_ENOUGH_PAGES_IN_VOLUME
Severe
Disk space
ER_LOG_WRITE_OUT_OF_SPACE
Severe
Disk space
ER_LOG_MOUNT_FAIL
Severe
Disk unavailable
ER_THREAD_STACK
Severe
Memory unavailable
The event.cfg file can reside in your current directory or in admin. The SQL
Access software first searches for the file in the current directory and then in
the admin directory. The generic name used in the event.cfg file should
correspond with the definition of the error in %ORDB%\include\dber.h
(Windows) or $ORDB/include/dber.h (UNIX). The event handler reads the
event.cfg at startup.
maxlength_error_log
This parameter specifies the maximum number of characters that will be
written to the error log. When this limit is reached, the errors will wrap
around and start being logged over the oldest error messages. The default is
80*3000 (3000 error messages).
If ORDB_MAXLENGTH_ERROR_LOG_OPEN_APPEND is set, then the
max_length_error_log parameter is ignored.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
329
Parameters related to memory space
These parameters affect management of memory space in the SQL Access
Server.
class_representation_cache
The SQL Access Server maintains a cache of information used to speed up the
determination of how instances of classes are laid out in memory. This
parameter is used to indicate the number of entries that can be held in this
cache. The default is 50 entries and the minimum value is 10.
num_data_buffers
A page buffer replacement algorithm swaps pages in and out of memory. This
parameter specifies the number of data buffers cached in main memory. (The
size of each buffer is specified by the -ps option of createdb). The more
buffers you define, the more likely that data will be found in memory. The
minimum value of this parameter is 5 buffers. The maximum value depends
directly on the amount of memory available in the machine on which your SQL
Access Server or standalone application runs. A value smaller than 50 buffers is
too low for any real sized SQL Access Server. The default value of 3000
buffers, in a SQL Access Server with pagesize of 4K (see the -ps parameter in
"createdb" on page 251), requires 120 MB of memory. If you specify a value
less than the minimum, the default value is used.
7
The higher this value, the more likely it is that a requested page is cached in
the page buffer pool. This decreases I/0. If the memory required for the
buffer pool exceeds physical memory capacity, the operating system paging
can increase.
sr_buffers
This parameter indicates the number of SQL Access Server buffers allocated for
sorting purposes. The parameter allocates a set of sort buffers to each SQL
Access Client on the SQL Access Server when needed. The size of each buffer
is the same size as a SQL Access Server page as specified by the -ps option of
createdb (see the -ps parameter in "createdb" on page 251). The minimum
value for this parameter is 16, which is also the default. If a number less than
the minimum is given, the default value is used. When a sort is complete, the
sort buffers are freed.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
330
Parameters related to disk storage
You can use the parameters in this section to define SQL Access Server
volumes, as well as affect the storage space of some file structures.
voltmp_path
SQL Access automatically creates and removes temporary volumes that are
used during the normal processing of large queries and sorts. The voltmp_path
parameter is a string that identifies the location (directory) where temporary
volumes are created. The default value of this parameter is the location where
the first SQL Access Server volume was located. If no value or NULL is given,
the default is used.
volext_path
Volume extensions are created only for general purposes. The volext_path
parameter is a string that specifies the single location (directory) where
permanent volume extensions for a SQL Access Server are to be created. If you
do not specify a location or if you specify NULL, the value of volext_path
defaults to the location of the first SQL Access Server volume. SQL Access can
automatically extend a SQL Access Server when the value of auto_volext_factor
is greater than 0. The system always creates automatic volume extensions
with generic purposes.
maxtmp_pages
This parameter specifies the maximum number of pages that can be allocated
for temporary volumes. The default value is -1, indicating an infinite number
of pages. The space available on the location specified by voltmp_path
imposes the limit. If a value of 0 is given, the system does not create a
temporary volume. In this case, the DBA can use the addvoldb utility to create
permanent volumes for temporary purposes. If a negative value other than -1
is given, the system uses the default (for more information, see "voltmp_path"
on page 331).
auto_volext_factor
The auto_volext_factor parameter determines the minimum number of pages
that are used when an automatic volume extension is added to the SQL Access
Server system. The minimum number of pages is determined by multiplying
auto_volext_factor by the number of pages of the first SQL Access Server
volume created with the createdb utility.
The default value of the auto_volext_factor parameter is 1. If you specify 0 for
the value of this parameter, the system does not automatically create volume
extensions. If you specify a negative value, the system uses the default value.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
331
unfill_factor
This parameter defines the percentage of space reserved in each heap page for
future updates. Situations may arise when the size of an updated instance
increases such that not enough space exists to store the instance on its original
page. In these situations, the system relocates the instance to another page.
Instance relocations are undesirable for performance reasons.
The default is set to 0.10 (10%), the maximum value is 0.30 (30%), and the
minimum is 0.0 (0%). Use a higher value if a large number of changes are
expected. Use a lower value if very few updates to the instances of the SQL
Access Server classes. If you specify a negative value or a number greater than
0.30, the system uses the default value.
unfill_index_factor
The system uses this parameter when an index is created. It determines the
amount of space to be reserved on each page of the new index. The amount of
reserved space indicated by unfill_index_factor affects the performance on a
B+tree index, because index pages split when they fill. This reserved space
minimizes the splitting of index pages when new records are added to the
indexed class.
The default value for this parameter is 0.20 (20%), and the maximum value is
0.35 (35%). When you expect to add a large number of records to a class after
the index is created, you should use the maximum value. If unfill_index_factor
is set to 0 (0%), the system reserves no space for future additions, indicating
that you do not expect to insert any more instances of the class being indexed
(after the index is created).
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
332
warn_outofspace_factor
The system records the value of this parameter on a permanent SQL Access
Server volume when it is created. It issues warnings when the SQL Access
Server disk is running out of space.
An automatic warning message is issued the first time a SQL Access Server
volume falls below a specific number of free pages during the allocation of
pages. The threshold value is calculated by multiplying the total number of
free SQL Access Server volume pages by the value of this parameter. A new
warning threshold is calculated by multiplying warn_outofspace_factor by the
number of available pages. A final warning message is given when the disk falls
below 10 free pages, and no new additional warnings are given. Similarly, outof-space warning messages are given during SQL Access Server restart and
shutdown when the SQL Access Server volume falls below the first calculated
threshold value.
The default value is 0.15 (15%). If you specify 0, the out-of-space warning
messages are not issued. If you specify a negative value or a number greater
than 1, the default value is used.
Parameters related to recovery/logging
SQL Access uses a log and a SQL Access Server backup to recover committed
and uncommitted transactions in case of system and media crashes, as well as
user-initiated rollbacks. A log consists of a set of sequential files that are
created by SQL Access. There are two types of logs:
♦
Active log. Log file with the most recent changes.
♦
Archive logs. The rest of the log files.
The term "log" refers to the entire set of active and archive logs. The system
records changes to the SQL Access Server in the active and archive logs.
When the active log becomes full, its pages are archived in an archive log to
support media crashes and the effects of changes that have not been recorded
in the SQL Access Server volumes. SQL Access determines when archive logs
are no longer needed for normal processing. The system retains archive logs to
support media crashes until the files are removed by the DBA.
The backup is a snapshot of all committed changes at the time the backup is
completed. Thus, it is a live snapshot of the SQL Access Server. That is, users
can be logged into the SQL Access Server and transactions can update the SQL
Access Server during the backup. The system saves all updates committed
during the backup. The SQL Access recovery system uses the parameters
discussed in the following sections.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
333
backup_max_volume_size
This parameter places an upper limit on the size (in bytes) of the backup
volumes created by the backupdb utility. It allows backup to disk while
creating volumes of a specified size for archive purposes. For instance, you
may want to archive to tape but would like to save time by backing up to disk
at night. You can then transfer the backup volumes to a slower tape drive in
the morning, with each tape holding exactly one backup volume.
The default for this parameter is -1, which gives no upper limit. It should be
set only when needed. When this parameter is not set, backup volumes will be
as large as the destination media will allow. The lowest limit that can be
specified is 32 KB; the upper limit is 2 GB.
The backup_max_volume_size parameter must be greater than the block buffer
size for the device multiplied by the backup_buffer_size parameter.
backup_buffer_size
This parameter speeds up the backup by providing a way to increase the block
buffering between the backupdb utility and the backup device. The value
specifies multiples of the default block size for the device. For example, a
value of 10 gives a 10x increase in the block size of the data buffered to the
device. This parameter is particularly helpful when backing up to streaming
tape devices. Since each device has its own buffer size, the default value is
both operating system and device dependent. For example, on Solaris, the
default buffer for backups to most disk drives is 8192 bytes. On Windows
systems, the backup buffer is always 4096 bytes.
The parameter default is 1, and the upper bound is the maximum allowed
integer value for the system. The recommended value is 4–10. This parameter
applies only when the backups are being created. Upon restore, the block
buffering used to create the backup is automatically used to do the restore.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
334
checkpoint_interval
The value of this parameter specifies the number of log pages to fill before a
checkpoint is performed. The purpose of a checkpoint is to limit the number of
log pages that must be scanned and the amount of work that must be redone
during the restart recovery process.
Each time a checkpoint occurs, SQL Access flushes committed and/or
uncommitted changed data pages that have occurred since a previous
checkpoint. Pages that remain uncommitted for a long time are flushed, to
avoid delays during a recovery. That is, a checkpoint flushes a changed and
frequently used data page without waiting for replacement of the buffer
containing the page. In addition, the checkpoint process records (in the log)
the state of each transaction in the system.
If the value of this parameter is very large, recovery of your SQL Access Server
and bringing it online after a system failure may take a long time. A very small
parameter value reduces the time necessary for system recovery in case of
system failures. However, a small parameter value has a negative impact on
performance because the frequency of checkpoints increases. You should
choose a value based on your system’s performance. If you are more
concerned with efficient runtime performance than recovery time, set
checkpoint_interval to a higher value. If you are more concerned with fast
recovery time, choose a smaller value.
Cincom recommends a value of 50–100. The system default value is 100 pages.
The minimum value for this parameter is 10. If a number less than the
minimum is given, the default value is used. In addition, if the value of this
parameter is smaller that the value of num_log_buffers parameter, the system
uses the value of num_log_buffers instead.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
335
flush_data_buffer_factor
The recovery system of SQL Access allows the execution of commits and
rollbacks without forcing dirty data pages to the SQL Access Server. You can
force out dirty pages asynchronously to the SQL Access Server later. This
approach benefits not only the commit and rollback operations but also
multiple updates to the same pages by future transactions because I/O is
reduced. If all data buffers are filled with only dirty pages, the SQL Access
page buffer replacement algorithm executes two I/Os. One I/O writes out the
dirty page currently placed in the replacement buffer. The other I/O reads in
the desired page.
The system avoids this undesirable situation by forcing dirty data pages out
when the value of this parameter is reached and either SQL Access is idle or a
checkpoint operation is in progress. The value of this parameter indicates the
desirable saturation factor of dirty pages in the data buffer. When this factor
is reached, dirty data pages are forced written to disk. The minimum value for
this parameter is .30 (30%). However, Cincom recommends a value between
0.70 and 0.90 (70–90%). The default value is 0.80. If you specify a value less
than 0.30 or greater than 1, the system uses the default value.
log_path
This parameter is a string that specifies the location (directory) of the log files
and default locations for SQL Access Server backups. The default value of this
parameter is the location of the SQL Access Server. If you specify a NULL value
or no value, the system uses the default value.
Cincom strongly recommends that you place the SQL Access Server files, log
files, and SQL Access Server backup files in physically different disk/media
devices. Otherwise, if the disk where a volume of the SQL Access Server is
located fails, the log and SQL Access Server backups may have been damaged,
and it may be impossible to recover the SQL Access Server.
The log_path is also the default destination for backups unless a different
backup directory was specified at the original run of createdb.
log_reserve_space
When you create a SQL Access Server, SQL Access verifies that enough space
exists for the log without reserving the space. It is possible for the space to be
used by another application. SQL Access will not be able to find the required
space if it was claimed by another application. Setting the value of this
parameter to 1 forces SQL Access to reserve the active log space at the time
the SQL Access Server is created to avoid an out-of-disk-space condition in the
future.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
336
log_size
This parameter indicates the number of log file pages (active log and archive
logs). The system determines the page size for the log files by the value
entered for the -ps option of the createdb utility. The size of the log should be
large enough to handle all dynamic changes of concurrent transactions without
reaching saturation. Cincom recommends a value that is at least as large as
the number of SQL Access Server pages. The minimum value for this parameter
is 200. The default value is the number of pages for the SQL Access Server as
specified by the -p option of the createdb utility. If you specify a number less
than the minimum, the system uses the default value.
To alleviate performance problems, the active log acts as a circular file,
wrapping around when it becomes saturated. However, before a portion of the
log file is reused, you must archive it in an archive log. An archive log process
may be done in one or several steps (for example, when the system is idle,
some archiving may take place).
To estimate the active log size, first determine the peak transaction load using
the following formula:
Peak Transaction Load = (largest-amount-of-data-changes /
longest-transaction time) * number-of-current-transactions
You can estimate the transaction that changes the largest amount of data in
the longest transaction time by using the estimatedb_data and
estimatedb_index utilities. For INSERTs and DELETEs, use the value obtained
with these utilities. For UPDATEs, multiply that value by 2.
Next, determine the frequency of finished transactions during the longest
transaction time, as follows:
Frequency of Finished Transactions = (Transactions To Finish /
Longest Transaction Time)
Your desired log size is then calculated as follows:
Log Size = peak-transaction-load / frequency-of-finishedtransactions
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
337
media_failures_are_supported
This parameter specifies whether you wish to support media failures.
When this parameter is set to 0, SQL Access automatically removes archive log
files that do not contain active changes. The default value of this parameter is
1, indicating that media failures are supported. SQL Access will not remove
archive log files.
When you activate media_failures_are_supported for a SQL Access Server for
which it was not formerly set, a backup of the SQL Access Server must be made
to ensure that log records of removed archives are not needed.
num_log_buffers
This parameter specifies the number of log buffers cached in memory for
logging purposes. The size of each buffer is in SQL Access Server pagesize
(which is determined when the SQL Access Server is created using the -ps
option of createdb). A large value reduces log I/O when transactions are long
and numerous. It also reduces synchronization of log writes against the disk.
Cincom recommends a value between 50–100 buffers. The default value is 50
buffers (which, in a SQL Access Server with a page size of 4K, requires 400K).
The minimum value for num_log_buffers is three buffers. The maximum value
depends directly on the amount of memory available in the machine where you
run SQL Access. If you specify a value smaller than the minimum, the system
uses the default value.
8
The num_log_buffers parameter is one of the most important parameters to
improve the performance of SQL Access under SQL Access Server modifications
and numerous concurrent transactions. Keep in mind that increasing this
parameter increases machine memory usage and may induce swapping in your
machine.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
338
Parameters related to concurrency/locking
The SQL Access concurrency control system uses these parameters.
keep_schema_locks
When set to 1 (the default), read locks on schema information will be held
across transaction boundaries. This can increase performance since schema
locks will not be dropped and re-acquired repeatedly in the same SQL Access
Client application. If you set this parameter to 0, schema locks will be
released at the end of a transaction. You should only set this to 0 if your
application does a lot of schema modifications to existing classes (is ALTER
class commands, etc.).
lock_escalation
SQL Access synchronizes concurrent access to shared data using a
multigranularity locking mechanism. SQL Access may lock the SQL Access
Server as a whole, specific classes, or instances, depending on the operation
being executed. Under this scheme, all classes and instances are implicitly
locked with the lock on the SQL Access Server. If a class is locked, all its
instances are implicitly locked with the lock on the class. The value of this
parameter automatically determines the locks needed to access any type of
SQL Access Server data.
This parameter specifies the maximum number of locks acquired on individual
instances of a class before the locks on instances are escalated to a class lock.
The minimum value for this parameter is 5. The default value is 1000. If a
value less than the minimum is given, the system uses the default value. In
general, larger values for this parameter achieve greater concurrency;
however, the overhead of lock management will also increase.
It is important to specify a value for this parameter to avoid an excessively
large lock table, which can affect concurrency control performance.
lock_timeout_in_secs
This parameter indicates the minimum amount of time to wait for a lock. If a
lock is not granted within the amount of time specified, the lock is denied and
execution of the operation is canceled. SQL Access returns an error indicating
cancellation of the operation due to a lock timeout. The system cancels only
the current operation and not the entire transaction. Time-outs must be
carefully handled by users and applications. The default value of this
parameter is to wait 20 seconds for the lock to be granted. A value of zero
indicates not to wait for a lock. If a negative value is given, the system uses
the default value.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
339
lockf_enable
This parameter locks the SQL Access Server to prevent several applications
from opening the SQL Access Server at one time. If you disable this parameter,
concurrent application access to the same SQL Access Server could occur,
resulting in SQL Access Server corruption.
The user should not modify this parameter unless severe NFS network problems
are occurring.
UNIX uses a distributed locking mechanism based on rpc.lockd. A system
function, called lockf( ), provides the interface to this mechanism.
The lockf( ) function has proven troublesome in certain versions of SunOS.
If you experience problems with SQL Access Server access (such as when using
createdb), the lockf_enable parameter in the ordbinit.txt file turns the locking
enable feature to NO (0) or YES (1). If set to YES or 1, (lockf_enable=YES or
lockf_enable=1), lockf( ) is enabled. If set to NO or 0, it is disabled.
If a client mounts a file system using NFS that is physically on a remote server
and that client does not have an entry in that server’s /etc/hosts file (as might
happen if the site is not running NIS), and that client subsequently issues a
lockf( ) call (locking a file system on that NFS-mounted file system), the
server’s lockd and statd become confused and are unable to connect to their
counterparts on the client. Essentially, the user experiences a “hang.”
Whatever operation was in progress at the time blocks in an uninterruptible
state inside the system call, and it is impossible to kill the process. In
addition, as the statd and lockd on the server continue to spend time trying to
contact the client, other clients with apparently unrelated processes hang.
The following messages display on the NFS server console:
rpc.lockd: cannot do cnvt
rpc.statd: cannot talk to statd at <client>
The workaround is to ensure that any client that mounts a file system from a
Server via NFS is also present in the host's files of that server. This should
happen automatically if you are running NIS.
If you disable this parameter, concurrent application access to the same SQL
Access Server could result in data corruption or collision problems. Disable
locking only if you are experiencing access problems. Exercise caution in
simultaneous SQL Access Server operations (from two different windows and/or
two different users across the network).
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
340
deadlock_detection_interval
It is possible to get into a deadlock situation where two or more transactions
are waiting for each other to finish. When a deadlock occurs, SQL Access
resolves it by rolling back one of the transactions in the deadlock. The
transaction that is rolled back is likely the most recent transaction.
The deadlock detection program is run every deadlock_detection_interval (the
value of this parameter) when there are at least two suspended transactions
and one of those transactions has not been suspended during the last deadlock
detection run.
If the interval value is very small, a lot of time is expended looking for
deadlocks even if deadlocks are rare. If the interval is very long, less cost is
incurred for deadlock detection; however, a real deadlock may go undetected
for a long time. The system default value for deadlock detection is 30 seconds.
If either zero or a negative value is given, the system uses the default.
isolation_level
This parameter indicates the isolation level of the transaction. Isolation levels
allow transactions to run with less restrictive levels of consistency. The
isolation level of a transaction is a measure of the degree of interference that
the transaction can tolerate from other concurrent transactions. The higher
the isolation levels the less interference and the lower the concurrency. The
default value of this parameter is TRAN_REP_CLASS_COMMIT_INSTANCE.
The following table indicates the possible values for this parameter. The
values are grouped according to isolation levels, and you can specify any value
in a group for the same isolation level (some of the names have aliases).
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
341
For example, you can specify TRAN_REP_CLASS_REP_INSTANCE,
TRAN_REP_READ, or TRAN_SERIALIZABLE and get the same isolation level (for
complete descriptions of these isolation levels and concurrency control, refer
to the SQL Access for SUPRA Server PDM SQL Reference Guide, P25-9503):
Isolation level
parameter values
Description
Isolation level
parameter number
REPEATABLE READ
CLASS
with
REPEATABLE READ
INSTANCES
(or SERIALIZABLE)
TRAN_REP_CLASS_REP_INSTANCE
TRAN_REP_READ
TRAN_SERIALIZABLE
5
REPEATABLE READ
CLASS
with
READ COMMITTED
INSTANCES
(or CURSOR STABILITY)
TRAN_REP_CLASS_COMMIT_INSTANCE
TRAN_READ_COMMITTED
TRAN_CURSOR_STABILITY
4
REPEATABLE READ
CLASS
with
READ UNCOMMITTED
INSTANCES
TRAN_READ_UNCOMMITTED
TRAN_REP_CLASS_UNCOMMIT_INSTANCE
3
READ COMMITTED CLASS
with
READ COMMITTED
INSTANCES
TRAN_COMMIT_CLASS_COMMIT_INSTANCE
2
READ COMMITTED CLASS
with
READ UNCOMMITTED
INSTANCES
TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE
1
use_index_concurrency
By default, locks on index keys can be used to increase concurrency during
query executions. This parameter can be set to 0 to disable this behavior.
max_lock_structures
Sets the maximum number of structures kept for reuse by the locking module.
An increase in this parameter can improve performance by reducing the
number of times that memory is allocated and freed but at the expense of
increasing memory consumption by the SQL Access Server. The valid range of
values is 10 to 1000.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
342
Parameter related to threads
request_threads_to_start
This parameter specifies the number of request threads that the SQL Access
Server will create and initiate at startup. The default value is 0, indicating
that the minimum number (determined by the SQL Access Server) of request
threads are created/started at startup.
A value of –1 indicates the maximum number of request threads should be
created/started at startup. This is beneficial if the SQL Access Server is
required to obtain all the thread resources it will use upfront.
If the value is lower than a system determined minimum, the minimum number
of request threads will be started.
The SQL Access Server will start up a number system threads in addition to the
request threads. Additional request threads will be created/started as
required; for example, as more SQL Access Clients connect and the number of
requests handled concurrently increases.
Parameters related to communication services
The SQL Access communication subsystem uses these parameters. When a SQL
Access Client starts an application, the system requests a connection to a
particular SQL Access Server. The SQL Access communication subsystem
connects the application to the SQL Access Server process/machine that
administers (maintains) the requested SQL Access Server through the service
name.
The values of these parameters are usually specified during the installation
procedure and are not normally altered. Thus, you should only define these
parameters in the ordbinit.txt file of the installation (found in
%ORDB%\admin\ordbinit.txt (Windows) or $ORDB/admin/ordbinit.txt (UNIX)).
The /etc/hosts and /etc/services files must be present on each UNIX client and
UNIX server computer that runs SQL Access or on the NIS server if your network
uses Network Information Server (NIS). On NIS systems, the /etc/hosts and
/etc/services files are maintained on the NIS server. The files that reside on
your local computer are not used and may be obsolete.
network_service_name
This parameter is similar to the master_port_id parameter, except that it
indicates a symbolic address instead of a numeric address. This parameter is a
string (must be enclosed in double quotes) that indicates the port name of the
SQL Access communication service that has been assigned in the UNIX network
software table (/etc/services).
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
343
The default value of this parameter is sqlx. This default value is initially
assigned to the network_service_name parameter in your ordbinit.txt file, but
it can be changed to suit your site’s requirements. However, whether you use
the system-supplied value or provide a new value of your own, you must still
update the UNIX network software table (usually located in /etc/services) to
reflect this value. The value of the network_service_name parameter is only
used if the value of the master_port_id parameter is unknown.
master_port_id
This parameter is similar to the network_service_name parameter, except that
it indicates a numeric address instead of a symbolic address.
The default value of this parameter is 1978. This value is initially assigned to
the master_port_id parameter in your ordbinit.txt file, but it can be changed
to suit your site’s requirements. However, whether you use the systemsupplied value or provide a new value, you must still update the UNIX network
software table (usually located in /etc/services) to reflect this value.
The port number indicates to the SQL Access Client how to find the SQL Access
Server on the specified host. It does not matter what service name you
choose, as long as it agrees with the name specified in your /etc/services file.
Only if the value of the master_port_id parameter is unknown, the
network_service_name parameter is used.
network_pagesize
The network_pagesize parameter specifies the size in bytes that SQL Access
used as the communication block between the SQL Access Client and the SQL
Access Server. This value must be a power of two and greater than or equal
to 1K (1024 bytes). The default value is 32K.
max_ping_wait
Set this parameter to the maximum number of seconds the SQL Access Server
blocks before determining that the SQL Access Client is unreachable. A value
less than or equal to 0 turns off this test. The default value is 5. Windows SQL
Access Servers ignore values greater than 0 and may block for the full timeout
period (about 1 minute).
socket_recv_timeout
Sets a time limit in seconds for the socket receive function. When 0 (the
default), no time limit is set on a socket receive.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
344
Parameters related to SQL Access Client requests on the SQL
Access Server
Use these parameters to manage SQL Access Server resources more efficiently.
active_requests
This parameter sets the number of simultaneously active requests for which the
SQL Access Server is tuned. The default value is 50.
max_clients
This parameter identifies the maximum number of concurrent SQL Access
Client connections that the SQL Access Server can accept. If the max_clients
limit has been reached and a new SQL Access Client connects to the SQL Access
Server, the system refuses the new connection. The default value is 500.
Parameter related to the query cache
query_cache_server_statistics
This parameter tells the SQL Access Server to print query cache statistics when
the SQL Access Server is terminated. The default value is 0, meaning no
statistics will be printed. When the parameter is set to 1, statistics will be
printed to standard out when the SQL Access Server terminates.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
345
Parameters related to SQL Access Server file based objects
The following parameter is used to identify valid directory/file locations for
SQL Access Server file based objects.
fbo_root
The SQL Access Server FBO storage mechanism gives users the ability to read
and write files in the SQL Access Server's host file system. To protect the host
system from accidental damage, it is necessary to place limits on which files
and directories can contain Server FBOs. This is accomplished using the
fbo_root system parameter.
The fbo_root parameter can be set to a colon- or semicolon-delimited list of
SFBO files or directories that may contain SFBO files. Each element of the list
must be the full pathname of a file or a directory. If it is a file, it is explicitly
allowed as an SFBO file. If it is a directory, then files that are in or descended
from that directory are allowed as SFBO files.
The first pathname in the list has special significance. It is the “starting point”
for all FBOs created with a relative pathname. If this value is a file rather than
a directory, relative paths will effectively be disabled for this installation.
The first element of any pathname in the list may be the name of an
environment variable preceded by a dollar sign ($). The environment variable
will be evaluated at run time on the SQL Access Server.
Windows Server example.
fbo_root=c:\FBODir;d:\images\mypic.jpg;$IMAGES\fbos;
value of $IMAGES at runtime is ‘\\serverhost\c\images’
The value of fbo_root is checked on every access to an SFBO, not only at create
time. Therefore, changing the value of fbo_root could cause previously
created SFBOs to not be accessible any longer. In particular, SFBOs having a
relative path will not be accessible if the first pathname in fbo_root is
modified.
The default value of fbo_root is NULL, effectively disabling the use of SFBOs for
this installation.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Server parameters
346
SQL Access Client parameters
This section describes a variety of parameters that can be selected to configure
and tune a SQL Access Client. These parameters are usually defined by a user
or application of SQL Access.
Parameters related to connecting to SQL Access Server
connection_timeout
When a SQL Access Server’s host is overloaded, the system can forcefully
refuse or “time out” an incoming new SQL Access Client connection. This may
happen when a SQL Access Server (or SQL Access Master) receives a large
number of incoming connections in a very short period and its queue of backlog
connections overflows. If a SQL Access Client connection is refused, the SQL
Access Client can continue to retry its connection during the number of seconds
specified by the value of connection_timeout. The default value is 3 seconds.
The lowest value is 1 second. No maximum value exists.
multiple_connection_shared_objects
This parameter is for applications that do not use multiple SQL Access Server
connections. When this parameter is set to 0, the system is prevented from
creating a shared cache. The shared cache only benefits multiple connection
applications.
standalone
When this parameter is set to 1, the default connection mode for an
application that does not explicitly set the connection mode will be
standalone. The default is 0. Setting this to 1 does not mean that the SQL
Access Server will always be in standalone mode, it only defines the default
when no specific mode (standalone or client/server) is specified.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Client parameters
347
Parameters related to workspace memory
The system uses these parameters to manage memory space in the SQL Access
Client workspace.
hot_load_workspace
If this parameter is true, then threads will attempt to preload their workspace
during startup.
hot_fault_objects
If this parameter is true, then threads will attempt to hot fault objects during
object fetching.
max_quick_size
The workspace uses a storage management algorithm called quick fit, which
maintains free blocks of the same size on individual lists. Free blocks are
maintained on these special lists as long as they are below the number of bytes
specified by max_quick_size. Allocations larger than this size are handled in a
different manner with somewhat more overhead.
You can increase this parameter if you determine that an application makes
frequent use of objects that are larger than the current setting of
max_quick_size. The default value is 256 bytes. A value greater than or equal
to 32 bytes and less than 1K is accepted. If a number outside this range is
given, the system uses the default.
max_block_size
The quick fit algorithm allocates large blocks of storage and manages small
allocations inside these blocks. If all of the available storage inside a block is
allocated, the quick fit algorithm allocates an additional block of storage. The
max_block_size parameter specifies the size of these blocks. This has the side
effect of also defining the maximum size of any single allocation within the
workspace.
The minimum value for this parameter is 16K. The default value is 128K. If a
number less than 16K is given, the system uses the default.
max_block_count
This parameter is closely related to max_block_size. This sets the number of
large workspace blocks that may be allocated before the system begins to issue
warning messages. If the application requires huge amounts of storage, it may
run out of virtual address space, which causes program termination.
Workspace warning messages allow the application to know in advance that
large amounts of memory are being consumed.
The minimum and default value for this parameter is 0, which indicates no
limit on the number of blocks allocated. If a negative value is given, use the
system default.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Client parameters
348
initial_workspace_table_size
You can set this parameter to an estimate of the total number of objects that
are referenced during a session. The system maintains an internal table of
object identifiers that grows as objects are brought into the workspace.
Because extending this table incurs some overhead, creating a table of the
maximum required size once at the beginning of the session can be beneficial.
The minimum value for this parameter is 1K. The default value is 4096 (4K)
objects. If a number less than the minimum is given, use the system default.
Parameters related to query services
execute_queries_streaming
When 1 (the default), streaming queries will be used. When 0, streaming
queries will be disabled.
query_max_rows
Sets a limit for the maximum number of rows that can be returned to a query.
When 0 (the default), all rows will be returned.
server_inserts
This parameter tells the SQL Access Client whether to execute inserts on the
SQL Access Server or the SQL Access Client. The default value is 1 meaning that
most inserts will be executed on the SQL Access Server. This makes the best
use of the query cache and normally provides the best performance.
When this parameter is set to 0 the SQL Access Client will perform most inserts
on the SQL Access Client using the SQL Access Client workspace. Inserts are
flushed to the SQL Access Server in groups of 100. The query cache is not used
to perform these inserts.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Client parameters
349
query_stream_window
The query_stream_window parameter is an integer that controls how many
instances in a result set will be available for reverse (fetch previous) cursor
operations. A value of 0 implies that no streaming queries will be supported.
A large value for this parameter will increase the storage needed by the SQL
Access Server, but it will allow applications to perform “get previous cursor”
over a broader range of results. The default value is 2.
This parameter can be also modified for a particular application with the
db_query_stream_window api function:
SQLX_query_stream_window( )
DB_ERROR SQLX_query_stream_window(
SQLHDBC sqlhdbc,
DB_INT32 nPages);
Arguments
Return value
Description
sqlhdbc⎯(IN) Connection handle
nPages⎯(IN) Number of pages maintained on the SQL Access
Server for query results
Error status
This function changes the number of pages the SQL Access
Server reserves for query results. The SQL Access Server
sends the results to the SQL Access Client as soon as it has
enough results to fill a network buffer. The SQL Access
Server can reclaim space that was used for results that have
already been transmitted to the SQL Access Client. This can
cause a problem if the SQL Access Client needs to perform a
large number of reverse cursor reads.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Client parameters
350
object_mode_character
The object_mode_character is used to tell SQL Access how to format oids
(identities) and collections in result sets. If set to 1, oids and collections will
be returned in char(254) format. Unlike object pointers, character
representation of an oid can be passed across connection handles. The default
is 0. When 0 the data will be returned as in previous releases
(DB_COLLECTIONS and DB_OBJECTS).
This behavior can be also modified for a particular application using any of the
following:
♦
SET OBJECT MODE CHARACTER sqlx statement (refer to the SQL Access for
SUPRA Server PDM SQL Reference Guide, P25-9503)
♦
SET OBJECT MODE OBJECT sqlx statement (refer to the SQL Access for
SUPRA Server PDM SQL Reference Guide, P25-9503)
♦
SQLX_set_object_mode_char api function (shown here)
SQLX_set_object_mode_char()
DB_BOOL SQLX_set_object_mode_char(
SQLHDBC con,
DB_BOOL* display_as_char);
Arguments
con—(IN) Connect handle
display_as_char—(IN) DB_TRUE is string display is
desired
Return value
The previous setting
Description
This function sets OIDs to be displayed as character
strings if display_as_char is DB_TRUE, or not if
display_as_char is DB_FALSE.
optimization_level
Setting this parameter to 0 will turn off SQL Access’s query optimizer.
query_cache_max_entries
This parameter controls the number of query cache entries available for each
connection to a SQL Access Server. The default number of query cache entries
is 100. Setting this parameter to 0 turns off query caching.
query_cache_threshold
This parameter controls the number of times a query will be compiled before is
cached. The default is 1, meaning that a query will be compiled twice before it
is cached. The setting effectively eliminates adhoc queries that are executed
only once from using query cache entries.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Client parameters
351
query_oidset_threshold
This parameter is used to control when the SQL Access Server should abandon
an index scan in favor of a sequential scan. The parameter specifies the
percentage of qualified index hits that should be reached before switching to a
sequential scan. The default of 9 was found to result in the smallest amount of
I/O over a variety of indices and queries.
query_timeout
Sets the default query timeout in seconds. When 0 (the default), no time limit
is set on queries.
select_star_includes_identity
If this is 1, then a “select *…” sqlx statement will include the identity attribute
as the first attribute in the result set. The default for this parameter is 0.
This behavior can be also modified for a particular application using any of the
following:
♦
♦
♦
SET SELECT IDENTITY ON sqlx statement (refer to the SQL Access for SUPRA
Server PDM SQL Reference Guide, P25-9503)
SET SELECT IDENTITY OFF sqlx statement (refer to the SQL Access for
SUPRA Server PDM SQL Reference Guide, P25-9503)
SQLX_set_select_identity api function (shown below)
SQLX_set_select_identity()
DB_BOOL SQLX_set_select_identity(
SQLHDBC con,
DB_BOOL* select_identity);
Arguments
con—(IN) Connect handle
select_identity—(IN) DB_TRUE if adding identity attribute
is desired
Return value
There is no return value
Description
This function will add the identity attribute to the result
set as the first column if select_identity is DB_TRUE, or
not if select_identity is DB_FALSE.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Client parameters
352
Parameters related to quitting/disconnecting from applications
commit_on_shutdown
SQL Access consults the value of the commit_on_shutdown parameter to
commit or roll back work when an application/user exits from SQL Access.
Accepted values for this parameter are YES (or 1) and NO (or 0). If YES (or 1) is
given, then the active work is committed. Otherwise, it is rolled back.
The default value of this parameter is NO or 0 (roll back work when exiting).
Cincom recommends finishing an application or SQL Access tool with either a
commit or rollback statement before exiting. This parameter is not consulted
when you exit a SQL Access interactive tool; instead, the system asks you
whether to commit the transaction.
query_cache_statistics
This parameter tells the SQL Access Client to print query cache statistics when
the SQL Access Client application disconnects from the SQL Access Server. The
default setting is 0, meaning that query cache statistics will not be printed.
Setting this parameter to 1 will cause query cache statistics to be printed to
standard out.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: SQL Access Client parameters
353
Utility parameter
This section describes the parameter that can be selected to configure SQL
Access utility operation.
unload_max_column
This parameter controls the line width for strings written to the unloaddb
object file. If the length of a string exceeds the value of this parameter, the
string continues on the next line. The default value for this parameter is 70.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: Utility parameter
354
Foreign Database parameter
This section describes the parameter that can be used to configure SQL Access
CID Foreign Database operation.
default_adapter_dir
When a CID Foreign Database is registered without a directory parameter, this
parameter controls where a CID Foreign Database host will look for adapters.
The default is %ORDB% on Windows and $ORDB/utilities on UNIX.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: Foreign Database parameter
355
Data validation parameters
This section describes parameters that can be used to configure SQL Access
data validation.
charcode_check
If this parameter is set to 0 (the default), the system will check inserted and
updated string data against the valid range based on the current character set
being used. Invalid characters will generate an error condition. The valid
ranges are as follows:
1. EUC Encoding
ASCII character
Full-width character
First byte
Second byte
Half-width Katakana
First byte (ss2)
Second byte
JIS X 0212
First byte (ss3)
Second byte
Third byte
2. Shift JIS Encoding
ASCII character
Full-width character
First byte
Second byte
Half-width Katakana
0x00 – 0x7f
0xa1 – 0xfe
0xa1 – 0xfe
0x8e
0xa1 – 0xdf
0x8f
0xa1 – 0xfe
0xa1 – 0xfe
0x00 – 0x7f
0x81 – 0x9f , 0xe0 – 0xef
0x40 – 0x7e , 0x80 – 0xfc
0xa1 – 0xdf
ignore_timezone
When changed to 1, this parameter causes the system to ignore the TZ (time
zone) environment variable when storing/retrieving time values. Use this
parameter with caution and then only for new SQL Access Servers for which the
SQL Access Server and all SQL Access Clients will use this parameter
consistently.
Administration Guide, P25-9501-04
Chapter: 9. SQL Access for SUPRA Server PDM system parameters
Section: Data validation parameters
356
A. Advanced Topics
Sample foreign tables for the MVS Burrys PDM database
The sample Burrys database is delivered with SUPRA Server PDM. The following
foreign table definitions were created for the files in the Burrys database.
For details on the Burrys SQL Access for SUPRA Server PDM (SQL Access) Server,
refer to the SUPRA Server PDM DBA Utilities User’s Guide (z/OS and VSE),
P26-6260.
First register the Burrys CID Foreign Database:
REGISTER CID FOREIGN DATABASE burrysdb
NAME 'CENTCPDM'
HOST 'earth'
CID_HOST ‘mvs’
CID_PORT ‘9999’;
After registering the CID Foreign Database, you then can create the foreign
tables. Each foreign table maps one PDM file or one PDM record code.
branch foreign table mapping to the E$BR file:
create foreign table branch on burrysdb
(branch_number
char(4),
branch_name
char(20),
branch_reg_no
char(3),
branch_address
char(20),
branch_city
char(13),
branch_state_code
char(2),
branch_zipcode
numeric(5,0),
branch_delivery_route
char(2),
branch_staff_quota
numeric(5,0),
branch_sales_quota
numeric(9,2))
as
select "BRANCH-NO", "BRANCH-NAME", "BRANCH-REGION",
"BRANCH-ADDR", "BRANCH-CITY", "BRANCH-STATE", "BRANCH-ZIPCODE",
"BRANCH-DEL-ROUTE", "BRANCH-STF-QUOTA",
"BRANCH-SLS-QUOTA" from "E$BR";
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the MVS Burrys PDM database
357
customer foreign table mapping to the E$CU file:
create foreign table customer on burrysdb
(customer_number
char(6),
customer_name
char(20),
customer_branch_no
char(4),
customer_address
char(20),
customer_city
char(13),
customer_state_code
char(2),
customer_zipcode
numeric(5,0),
customer_class
char(2),
customer_credit_limit
numeric(9,2),
customer_credit_rating
char(2))
as
select "CUSTOMER-NO", "CUSTOMER-NAME",
"CUSTOMER-BRANCH", "CUSTOMER-ADDR",
"CUSTOMER-CITY", "CUSTOMER-STATE",
"CUSTOMER-ZIPCODE", "CUSTOMER-CLASS",
"CUSTOMER-CR-LIM", "CUSTOMER-CR-CODE" from "E$CU";
invoice_line_item foreign table mapping to the E$IL file:
create foreign table invoice_line_item on burrysdb
(invline_invoice_no
char(4),
invline_product_no
char(9),
invline_price
numeric(9,2),
invline_quantity
numeric(5,0))
as
select "E$ILE$IN", "E$ILE$PG", "E$ILPRCE", "E$ILQNTY"
from "E$IL";
invoice foreign table mapping to the E$IN file:
create foreign table invoice on burrysdb
(invoice_number
char(4),
invoice_date
numeric(5,0),
invoice_sales_person
char(4),
invoice_total
numeric(9,2),
invoice_branch_no
char(4),
invoice_customer_no
char(6))
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the MVS Burrys PDM database
358
as
select "E$INCTRL", "E$INDATE", "E$INSLMN", "E$INTOTL",
"E$INBRAN", "E$INCUST" from "E$IN";
manifest_branch foreign table mapping to the E$MB file:
create foreign table manifest_branch on burrysdb
(manb_branch_no
char(4),
manb_manifest_no
char(5))
as
select "E$MBBRAN", "E$MBE$MF" from "E$MB";
manifest foreign table mapping to the E$MF file:
create foreign table manifest on burrysdb
(manifest_number
char(5),
manifest_date
numeric(5,0),
manifest_total
numeric(9,2),
manifest_branch_no
char(4))
as
select "E$MFCTRL", "E$MFDATE", "E$MFTOTL", "E$MFBRAN"
from "E$MF";
manifest_line_item foreign table mapping to the E$ML file:
create foreign table manifest_line_item on burrysdb
( manline_manifest_no
char(5),
manline_product_no
char(9),
manline_quantity
numeric(5,0),
manline_value
numeric(9,2))
as
select "E$MLE$MF", "E$MLE$PD", "E$MLQNTY", "E$MLVLUE"
from "E$ML";
product foreign table mapping to the E$PD file:
create foreign table product on burrysdb
(product_number
char(9),
product_description
char(30),
product_price
numeric(9,2),
product_whse_quantity
numeric(5,0),
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the MVS Burrys PDM database
359
product_group_no
char(2))
as
select "E$PDCTRL", "E$PDDESC", "E$PDPRCE", "E$PDWQTY",
"E$PDPGRP" from "E$PD";
product_group foreign table mapping to the E$PG file:
create foreign table product_group on burrysdb
(group_code
char(2),
group_description
char(30))
as
select "E$PGCTRL", "E$PGDESC" from "E$PG";
purchase_order_header foreign table mapping to the E$PL(HD) file:
create foreign table purchase_order_header on burrysdb
(po_item_rc
char(2),
po_no
char(6),
po_header_date
numeric(5,0),
po_supplier_no
char(6))
as
select "E$PLCODE", "E$PLE$PO", “E$PLDATE", "E$PLE$SU"
from "E$PL_HD";
purchase_order_line_item foreign table mapping to the E$PL(LN) file:
create foreign table purchase_order_line_item on burrysdb
(po_item_rc
po_no
char(2),
char(6),
po_item_cost
numeric(9,2),
po_item_quantity
numeric(5,0),
po_item_product_no
char(9))
as
select "E$PLCODE", "E$PLE$PO", "E$PLCOST", "E$PLQNTY",
"E$PLE$PD" from "E$PL_LN";
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the MVS Burrys PDM database
360
purchase_order_received_product foreign table mapping to the E$PL(PD)
file:
create foreign table purchase_order_received_product on burrysdb
(po_item_rc
char(2),
po_no
char(6),
po_received_date
numeric(5,0),
po_received_quantity
numeric(5,0),
po_received_delivery
numeric(3,0),
po_received_product_no
char(9))
as
select "E$PLCODE", "E$PLE$PO", "E$PLDELD", "E$PLDELQ",
"E$PLDELN", "E$PLDELP" from "E$PL_PD";
purchase_order foreign table mapping to the E$PO file:
create foreign table purchase_order on burrysdb
(pord_number
char(6),
pord_date
numeric(5,0),
pord_total
numeric(9,2))
as
select "E$POCTRL", "E$PODATE", "E$POTOTL"
from "E$PO";
region foreign table mapping to the E$RG file:
create foreign table region on burrysdb
region_number
char(3),
region_name
char(20))
as
select "E$RGCTRL", "E$RGNAME" from "E$RG";
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the MVS Burrys PDM database
361
stock foreign table mapping to the E$SK file:
create foreign table b_stock on burrysdb
( stock_product_no
char(9),
stock_branch_no
char(4),
stock_quantity
numeric(5,0),
stock_location
char(5),
stock_ytd
numeric(9,2))
as
select "E$SKE$PD", "E$SKE$BR", "E$SKQNTY", "E$SKBINL",
"E$SKSYTD" from "E$SK";
product_structure foreign table mapping to the E$ST file:
create foreign table product_structure on burrysdb
(product_assm_product_no
char(9),
product_comp_product_no
char(9),
component_quantity
numeric(5,0))
as
select "E$STASSM", "E$STCOMP", "E$STQNTY" from "E$ST";
supplier foreign table mapping to the E$SU file:
create foreign table supplier on burrysdb
(supplier_number
char(6),
supplier_name
char(20),
supplier_addr
char(20),
supplier_city
char(13),
supplier_state
char(2),
supplier_zip
numeric(5,0))
as
select "E$SUCTRL", "E$SUNAME", "E$SUADDR", "E$SUCITY",
"E$SUSTAT", "E$SUZIPC" from "E$SU";
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the MVS Burrys PDM database
362
vendor_stock foreign table mapping to the E$VS file:
create foreign table vendor_stock on burrysdb
( vs_key
char(15),
vs_supplier_no
char(6),
vs_product_no
char(9),
vs_number
char(20),
vs_cost
numeric(9,2))
as
select "E$VSCTRL", "E$VSE$SU", "E$VSE$PD", "E$VSNUMB",
"E$VSVCST" from "E$VS";
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the MVS Burrys PDM database
363
Sample foreign tables for the OpenVMS and UNIX Burrys PDM
database
The sample Burrys database is delivered with SUPRA Server PDM. The following
foreign table definitions were created for the files in the Burrys database.
First register the Burrys CID Foreign Database:
REGISTER CID FOREIGN DATABASE burrysdb
NAME 'DBMOD'
HOST 'earth'
CID_HOST ‘pdm’
CID_PORT ‘9999’;
After registering the CID Foreign Database, you then can create the foreign
tables. Each foreign table maps one PDM file or one PDM record code.
branch foreign table mapping to the BRAN file:
create foreign table branch on burrysdb
(branch_number
char(4),
branch_name
char(20),
branch_reg_no
char(3),
branch_address
char(20),
branch_city
char(13),
branch_state_code
char(2),
branch_zipcode
numeric(5,0),
branch_delivery_route
char(2),
branch_staff_quota
numeric(5,0),
branch_sales_quota
numeric(9,2))
as
select "BRANCH-NO", "BRANCH-NAME", "BRANCH-REGION",
"BRANCH-ADDR", "BRANCH-CITY", "BRANCH-STATE", "BRANCH-ZIPCODE",
"BRANCH-DEL-ROUTE", "BRANCH-STF-QUOTA",
"BRANCH-SLS-QUOTA" from BRAN;
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the OpenVMS and UNIX Burrys PDM database
364
customer foreign table mapping to the CUST file:
create foreign table customer on burrysdb
(customer_number
char(6),
customer_name
char(20),
customer_branch_no
char(4),
customer_address
char(20),
customer_city
char(13),
customer_state_code
char(2),
customer_zipcode
numeric(5,0),
customer_class
char(2),
customer_credit_limit
numeric(9,2),
customer_credit_rating
char(2))
as
select "CUSTOMER-NO", "CUSTOMER-NAME",
"CUSTOMER-BRANCH", "CUSTOMER-ADDR",
"CUSTOMER-CITY", "CUSTOMER-STATE",
"CUSTOMER-ZIPCODE", "CUSTOMER-CLASS",
"CUSTOMER-CR-LIM", "CUSTOMER-CR-CODE" from CUST;
invoice_line_item foreign table mapping to the INVL file:
create foreign table invoice_line_item on burrysdb
(invline_invoice_no
char(4),
invline_product_no
char(9),
invline_price
numeric(9,2),
invline_quantity
numeric(5,0))
as
select INVLINVC, INVLPROD, INVLPRCE, INVLQNTY
from INVL;
invoice foreign table mapping to the INVC file:
create foreign table invoice on burrysdb
(invoice_number
char(4),
invoice_date
numeric(5,0),
invoice_sales_person
char(4),
invoice_total
numeric(9,2),
invoice_branch_no
char(4),
invoice_customer_no
char(6))
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the OpenVMS and UNIX Burrys PDM database
365
as
select INVCCTRL, INVCDATE, INVCSLMN, INVCTOTL,
INVCBRAN, INVCCUST from INVC;
manifest_branch foreign table mapping to the BRMA file:
create foreign table manifest_branch on burrysdb
(manb_branch_no
char(4),
manb_manifest_no
char(5))
as
select BRMABRAN, BRMAMANF from BRMA;
manifest foreign table mapping to the MANF file:
create foreign table manifest on burrysdb
(manifest_number
char(5),
manifest_date
numeric(5,0),
manifest_total
numeric(9,2),
manifest_branch_no
char(4))
as
select MANFCTRL, MANFDATE, MANFTOTL, MANFBRAN
from MANF;
manifest_line_item foreign table mapping to the MANL file:
create foreign table manifest_line_item on burrysdb
( manline_manifest_no
char(5),
manline_product_no
char(9),
manline_quantity
numeric(5,0),
manline_value
numeric(9,2))
as
select MANLMANF, MANLPROD, MANLQNTY, MANLVLUE
from MANL;
product foreign table mapping to the PROD file:
create foreign table product on burrysdb
(product_number
char(9),
product_description
char(30),
product_price
numeric(9,2),
product_whse_quantity
numeric(5,0),
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the OpenVMS and UNIX Burrys PDM database
366
product_group_no
char(2))
as
select PRODCTRL, PRODDESC, PRODPRCE, PRODWQTY,
PRODPGRP from PROD;
product_group foreign table mapping to the PGRP file:
create foreign table product_group on burrysdb
(group_code
char(2),
group_description
char(30))
as
select PGRPCTRL, PGRPDESC from PGRP;
purchase_order_header foreign table mapping to the POLN(HD) file:
create foreign table purchase_order_header on burrysdb
(po_item_rc
char(2),
po_no
char(6),
po_header_date
numeric(5,0),
po_supplier_no
char(6))
as
select POLNCODE, POLNPORD, POLNDATE, POLNSUPP
from POLN_HD;
purchase_order_line_item foreign table mapping to the POLN(LN) file:
create foreign table purchase_order_line_item on burrysdb
(po_item_rc
po_no
char(2),
char(6),
po_item_cost
numeric(9,2),
po_item_quantity
numeric(5,0),
po_item_product_no
char(9))
as
select POLNCODE, POLNPORD, POLNCOST, POLNQNTY,
POLNPROD from POLN_LN;
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the OpenVMS and UNIX Burrys PDM database
367
purchase_order_received_product foreign table mapping to the POLN(PD)
file:
create foreign table purchase_order_received_product on burrysdb
(po_item_rc
char(2),
po_no
char(6),
po_received_date
numeric(5,0),
po_received_quantity
numeric(5,0),
po_received_delivery
numeric(3,0),
po_received_product_no
char(9))
as
select POLNCODE, POLNPORD, POLNDELD, POLNDELQ, POLNDELN,
POLNDELP from POLN_PD;
purchase_order foreign table mapping to the PORD file:
create foreign table purchase_order on burrysdb
(pord_number
char(6),
pord_date
numeric(5,0),
pord_total
numeric(9,2))
as
select PORDCTRL, PORDDATE, PORDTOTL
from PORD;
region foreign table mapping to the REGN file:
create foreign table region on burrysdb
region_number
char(3),
region_name
char(20))
as
select REGNCTRL, REGNNAME from REGN;
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the OpenVMS and UNIX Burrys PDM database
368
stock foreign table mapping to the STCK file:
create foreign table b_stock on burrysdb
( stock_product_no
char(9),
stock_branch_no
char(4),
stock_quantity
numeric(5,0),
stock_location
char(5),
stock_ytd
numeric(9,2))
as
select STCKPROD, STCKBRAN, STCKQNTY, STCKBINL,
STCKSYTD from STCK;
product_structure foreign table mapping to the STRU file:
create foreign table product_structure on burrysdb
(product_assm_product_no
char(9),
product_comp_product_no
char(9),
component_quantity
numeric(5,0))
as
select STRUASSM, STRUCOMP, STRUQNTY from STRU;
supplier foreign table mapping to the SUPP file:
create foreign table supplier on burrysdb
(supplier_number
char(6),
supplier_name
char(20),
supplier_addr
char(20),
supplier_city
char(13),
supplier_state
char(2),
supplier_zip
numeric(5,0))
as
select SUPPCTRL, SUPPNAME, SUPPADDR, SUPPCITY,
SUPPSTAT, SUPPZIPC from SUPP;
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the OpenVMS and UNIX Burrys PDM database
369
vendor_stock foreign table mapping to the VSNO file:
create foreign table vendor_stock on burrysdb
( vs_key
char(15),
vs_supplier_no
char(6),
vs_product_no
char(9),
vs_number
char(20),
vs_cost
numeric(9,2))
as
select VSNOCTRL, VSNOSUPP, VSNOPROD, VSNONUMB, VSNOVCST from
VSNO;
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Sample foreign tables for the OpenVMS and UNIX Burrys PDM database
370
Extending the CID Adapter Schema
During startup, the CID Adapter Server builds an internal schema, which it uses
during the execution of queries. The internal schema is built by reading the
PDM directory and/or by requesting VSAM file information from CICS using the
VSAM_FILE_LIST input parameter.
For PDM files, the internal schema contains all of the files, data fields, access
methods, external field names, and domains defined in the PDM Directory. The
internal schema may be extended or modified using the CID Adapter Extensions
XML file. Extensions include subfields, access methods, foreign keys and CID
Adapter Views. Modifications include type overrides, date fields, external
names and file statistics information.
The IBM CICS CID Adapter Server may be used to access VSAM files defined to
CICS. This Adapter may be used to access PDM database files, VSAM files or
both.
For VSAM files the internal schema contains all of the files and access methods
defined in the VSAM_FILE_LIST input parameter(s). Each file element will
contain a single field representing the entire VSAM data record with subfields
defined for each access method key value. Messages CSHP954I, CSHP676I and
CSHP677I display the file, field and access methods automatically added to the
internal schema. The CID Adapter Extensions XML file is used to provide the
additional information required to define the fields and subfields of the
records. Optionally, additional access methods, foreign keys and Adapter Views
may be added.
Throughout the remainder of this section, references to file or files refer to
either PDM files or VSAM files.
After loading the schema information from the PDM Directory, the CID Adapter
Server will extend the schema with the field definitions in the CID Adapter
Extensions XML file. This occurs each time the CID Adapter Server initializes,
regardless of the value of the BIND_SCHEMA parameter. The CID Adapter Server
must be restarted in order to load any changes made to the CID Adapter
Extensions XML file.
In prior releases, the CID Adapter Server’s schema was extended with the
foreign key file. The CID Adapter Extensions XML file replaces the foreign key
file. The foreign key file will continue to function as documented in earlier
releases. Both files may be used to extend the same CID Adapter Server schema
in this release.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
371
The CID Adapter Extensions XML file must start with the following line:
<?xml version="1.0"?>
The CID Adapter Extensions XML file for a CID Adapter Server is located as
follows, depending on the platform:
Platform
Location
Alternate Location
MVS
// XMLFILE DD DSN=<xmlfilename>
CICS
// XMLFILE DD DSN=<xmlfilename>
OpenVMS
CSI_XML_SCHEMA logical name
CSI_XML_SCHEMA file in
the default directory
UNIX
CSI_XML_SCHEMA environment
variable
CSI_XML_SCHEMA file in
the current directory
All schema extensions must be enclosed in a single root element named
Adapter_extensions as follows:
<Adapter_extensions>
schema extensions as described below
</Adapter_extensions>
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
372
The following diagram shows the main elements of the CID Adapter Extenstions
XML file:
Adapter Extensions
0..n
0..n
File
View
1..
0..n
Field
1..n
Access_Method
0..n
0..n
Access
Foreign_Key
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
373
File
The internal schema contains memory structures for each file found in the PDM
directory and/or in the VSAM_FILE_LIST input parameter(s). The File element is
used to extend the metadata description of an internal record defined for a
file. You must define a separate File element for each record code in a PDM
file. The file elements in the internal schema are identified by:
PDM
VSAM
The 4 character PDM file name, along with the 2 character record code, if the
PDM file has record codes.
The VSAM file name provided in the VSAM_FILE_LIST input parameter(s).
A File element can contain Field elements that describe the layout of the
internal record. A File element may also contain Access_method elements to
define additional metadata that can aid the optimizer, and foreign key
elements describing the fields in one file that reference a unique key in
another file.
The File element has the following structure:
<File >
<Field/>
[<Field/> | <Subfield/>]
<Access_method/>
<Foreign_key/>
</File>
A File element has the following attributes:
Attribute Name
Required
Description
Name
Yes
(PDM) The 4 character name of the PDM
file. This must be defined in the PDM
Directory.
(VSAM) The 1 to 8 character DD name of
the VSAM file. The VSAM file name must be
specified in the VSAM_FILE_LIST
initialization parameter.
Record_code
No
(PDM) This is required only if the PDM file
contains record code(s). You must use a
separate FILE element for each record
code.
External_name
No
The external name of this file. May be up
to 32 characters. This name will be used to
reference this file in foreign tables.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
374
Record_count
No
Used by the optimizer. Specify this
attribute if you want to override the value
defined in the PDM directory.
Active_record_count
No
Used by the optimizer. Specify this
attribute if you want to override the value
calculated by the CID Adapter Server – 80%
of the Record_count.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
375
Field
The Field element is used to define new fields and subfields and/or modify
existing field information. All of the fields defined in the PDM directory will be
added to the internal schema automatically, including any domain information
found in the directory.
The typical COBOL shop will define one large data item to PDM and sub-define
that data area using COBOL copybooks. The names, sizes and types of these
sub-defined fields are known only to the COBOL applications that use the
copybooks. The naming conventions follow the rules of COBOL names. These
sub-defined fields must be added to the internal schema via the CID Adapter
Extensions XML file before they can be used in SQL queries.
For VSAM files, the CID Adapter Server will create the base field for each VSAM
file specified in the VSAM_FILE_LIST initialization parameter. The base field
defines the entire VSAM record and is named file-name_BASE. It must be used
as the base field for all fields in the file. Except for the fields automatically
created for the keys of access methods, all sub-definitions of the VSAM records
must be added to the internal schema via the CID Adapter Extensions XML file
before they can be used in SQL queries.
The Field element has the following structure:
<Field>
[<Field/> | <Subfield/>]
</Field>
A Field element has the following attributes:
Attribute
Name
Required
Description
Name
Yes
Either the 8 character name of the PDM Field or up
to 32 character field name.
External_na
me
No
Up to 32 character external name of the field. When
present, this name will be used in foreign table
definitions.
Type
No
One of the data types from the table in "Data Types"
on page 381.
Parent
No
The field name of the parent. This may not be used
in a hierarchy.
Displacement
No
Displacement into the parent field. Subfields
automatically start at displacement 0 in the parent
field.
Length
No
The physical length of the field, including decimals.
Decimals
No
The number of decimal places.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
376
Nulls
No
May be set to one of the following: ALLOWED,
NOT_ALLOWED, NOT_NULL. NOT_ALLOWED and
NOT_NULL are equivalent.
Null
No
The NULL value. This can be a string that will be
converted to the data type of the field or a hex
value in the form X’nnnnnnnn’.
Default
No
The Default Value. This can be a string that will be
converted to the data type of the field or a hex
value in the form X’nnnnnnnn’.
Date_type
No
One of the following date types: DATE, TIME,
TIMESTAMP
Date_format
No
The date format string as described in "Date_type
and Date_format" on page 382.
Subfields
There are three ways to define subfields: in a hierarchy, using the Parent
attribute or using the Subfield element. When a subfield is defined in a
hierarchy, the parent field is the immediate parent of the inner field. The
Parent attribute may not be used in this case.
The displacement of the subfield is calculated automatically beginning with
zero (0), unless it is overridden with a Displacement attribute. The automatic
displacement of the next subfield will be immediately following this subfield.
When the Parent attribute is used to define a subfield, the field containing the
Parent attribute may not be a subfield defined within a Field. The
displacement may be used to define the displacement into the parent field. If
the displacement is not specified it will be calculated automatically starting
with displacement zero (0).
The Subfield element looks just like the Field element in a hierarchy. It can be
used to clarify the fact that this is a subfield.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
377
The following XML syntax may be used to define a hierarchy of fields and
subfields:
<File
Name="file-name"
Record_code=”Record-code”
External_name=”external-file-name”>
<Field
Name="field-name"
External_name=”external-field-name”
Type="data-type"
Parent=”parent-field-name”
Decimals="decimal-places"
Nulls=”ALLOWED | NOT_ALLOWED| NOT_NULL”
Null=”null-value”
Default=”default-value”>
<Field
Name="subfield-name"
External_name=”external-field-name”
Type="data-type"
Displacement="displacement"
Length="physical-length"
Decimals="decimal-places"
Nulls=”ALLOWED | NOT_ALLOWED| NOT_NULL”
Null="null-value"
Default=”default-value”>
</Field>
</Field>
</File>
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
378
The following XML syntax may be used to define a hierarchy using the Field and
Subfield elements:
<File
Name="file-name"
Record_code=”Record-code”
External_name=”external-file-name”>
<Field
Name="field-name"
External_name=”external-field-name”
Type="data-type"
Parent=”parent-field-name”
Decimals="decimal-places"
Nulls=”ALLOWED | NOT_ALLOWED| NOT_NULL”
Null=”null-value”
Default=”default-value”>
<Subfield
Name="subfield-name"
External_name=”external-field-name”
Type="data-type"
Displacement="displacement"
Length="physical-length"
Decimals="decimal-places"
Nulls=”ALLOWED | NOT_ALLOWED| NOT_NULL”
Null="null-value"
Default=”default-value”/>
</Field>
</File>
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
379
The following XML syntax may be used to define a subfield using the Parent
attribute:
<File
Name="file-name"
Record_code=”Record-code”
External_name=”external-file-name”>
<Field
Name="field-name"
External_name=”external-field-name”
Type="data-type"
Decimals="decimal-places"
Nulls=”ALLOWED | NOT_ALLOWED| NOT_NULL”
Null=”null-value”
Default=”default-value”>
</Field>
<Field
Name="subfield-name"
External_name=”external-field-name”
Type="data-type"
Parent=”parent-field-name”
Displacement="displacement"
Length="physical-length"
Decimals="decimal-places"
Nulls=”ALLOWED | NOT_ALLOWED| NOT_NULL”
Null="null-value"
Default=”default-value”>
</Field>
</File>
The physical length of pre-defined fields in the internal schema may
not be modified using the Length attribute. The Length attribute is
required for new subfields. New subfields having no Type attribute
default to character.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
380
Data Types
The Type attribute of the Field element allows the type information in the
internal schema to be specified or changed.
For PDM fields, the type attributes may be used to supply type information
required by the CID Adapter Server when the type information is not provided
in the PDM Directory. Type attributes may also be used to override any type
information that exists in the PDM directory. The data type defaults to
character for new subfields with no Type attribute.
For VSAM fields and subfields, the data type will default to character if the
Type attribute is not specified.
It is occasionally desirable to have data returned to the SQL Access Client
application without the normal data conversion that occurs in the CID Adapter
Client and Server. This can be accomplished by overriding the PDM data type to
BIT.
Any data field may be overridden to type BIT. If a data field is defined as BIT,
it is transmitted to the SQL Access Server with no data translation regardless of
the platform or the original PDM data type. The data is displayed in hex unless
further modified with a SQL Access Server method. The size of BIT types is in
bytes in the CID Adapter Server. The size of BIT types is in bits in the SQL
Access Server. This means that an eight character CID Adapter BIT type must be
mapped as BIT(64) in the SQL Access Server foreign table.
The Type attribute may be set to any one of the following data-types:
TYPE
PDM/RDM
type
PDM/RDM
sign
PDM
PLATFORM
COBOL
PICTURE
CHARACTER
CHARACTER
All
X(n)
BIT
Any
All
Any
COBOL
USAGE
UNSIGNED_BINARY
BINARY
No
All
9(n)
COMP-4
SIGNED_BINARY
BINARY
Yes
All
S9(n)
COMP-4
UNSIGNED_PACKED
PACKED
DECIMAL
No
All
9(n)
COMP
COMP-3
SIGNED_PACKED
PACKED
DECIMAL
Yes
All
S9(n)
COMP
COMP-3
FLOAT
FLOATING
POINT
All
S9(n)
COMP-1
COMP-2
All
9(n)
DISPLAY
MVS
Treated as
unsigned
numeric
9(n)
DISPLAY
UNSIGNED_NUMERIC
UNSIGNED_NUMERIC
ZONED
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
No
COBOL
SIGN
381
PDM/RDM
type
TYPE
PDM/RDM
sign
PDM
PLATFORM
COBOL
PICTURE
COBOL
USAGE
UNSIGNED_NUMERIC
LEADING
SEPARATE
NUMERIC
No
VMS/UNIX
Treated as
unsigned
numeric
9(n)
DISPLAY
UNSIGNED_NUMERIC
NUMERIC
TRAILING
OVERPUNCH
No
VMS/UNIX
Treated as
unsigned
numeric
9(n)
DISPLAY
UNSIGNED_NUMERIC
ZONED
TRAILING
NUMERIC
No
VMS/UNIX
Treated as
unsigned
numeric
9(n)
DISPLAY
MVS
S9(n)
DISPLAY
LEADING_ZONED
COBOL
SIGN
LEADING
TRAILING_ZONED
ZONED
Yes
MVS
S9(n)
DISPLAY
TRAILING
TRAILING_ZONED
ZONED
TRAILING
NUMERIC
Yes
VMS/UNIX
S9(n)
DISPLAY
TRAILING
LEADING_SEPARATE
LEADING
SEPARATE
NUMERIC
Yes
All
S9(n)
DISPLAY
LEADING
SEPARATE
TRAILING_SEPARATE
All
S9(n)
DISPLAY
TRAILING
SEPARATE
LEADING_OVERPUNCH
VMS/UNIX
S9(n)
DISPLAY
LEADING
VMS/UNIX
S9(n)
DISPLAY
TRAILING
TRAILING_OVERPUNCH
NUMERIC
TRAILING
OVERPUNCH
Yes
Null and Default values
The null-value and default-value strings are converted to the data type of the
data item and stored in the schema in that format. They may also contain a
hex string composed of the letter x or X followed immediately by a single
quoted hex value, i.e. Default=“X’80000000’”. The hex string will be converted
to a hex value and stored directly into the schema without conversion. The hex
string must contain valid data for the data item’s type. The maximum length of
a null or default value is 32 characters.
Date_type and Date_format
The Date_type and Date_format attributes may be used in a Field or Subfield
element to allow any field containing date information to be defined as an SQL
date, time or timestamp. This allows comparison and arithmetic operations to
take place during query execution in the CID Adapter Server.
The format-string contains alphanumeric characters and escape sequences. The
following table lists the supported escape sequences:
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
382
Valid escape
sequences
Equals
%%
%
%a
Abbreviated day of the week (Mon, Tue, ...)
%A
Day of the week
%b
Abbreviated name of month (Jan, Feb, ...)
%B
Name of the month
%c
Full date and time formatted by locale
%C
2-digit century number [00-99] (the year divided by 100 and
truncated to an integer).
%d
2-digit day of the month (01-31)
%D
Date formatted as %m/%d/%y (2 digit year)
%e
Day of the month (1-31) single digits preceded by space
%H
2-digit hour (00 – 23) 24 hour clock
%I
2-digit hour (01-12) 12 hour clock
%j
3-digit day of the year
%m
2-digit month (01-12)
%M
2-digit minute (00-59)
%p
AM/PM from locale
%q
The quarter of the year (0-3)
%S
2-digit second (00-59)
%T
Time formatted by %H:%M:%S 24 hour clock
%U
Week of the year where Sunday is the first day of the week
%w
Day of the week (0-6) where Monday if the first day of the
week
%W
Week of the year where Monday is the first day of the week
%x
Date formatted according to locale
%X
Time formatted according to locale
%y
2-digit year (00-99)
%Y
4-digit year (0000-9999)
%1
Century as number of centuries since 1900 (0-9)
%t
Tab
%n
Newline
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
383
Dates stored in numeric data items in the PDM database or a VSAM file will be
converted to strings before applying the date format string. For example, if
dates were stored in the database in 4 byte binary data items such as
19920116, the format string “%Y%m%d” would be required to convert the
number to a date, and date back to a number. If the dates are stored in the
database in character data items with a format such as “January 16, 1992” the
format string “%B %d, %Y” would be used to interpret the date in the CID
Adapter Server.
The internal format of all dates, times and timestamps is a 4 byte binary
number that can be used to compare dates and can be used in arithmetic
expressions. The CID Adapter Server will convert date fields to this internal
format when records are read that contain dates. The internal format will be
converted to the database format on inserts and updates. This is the same
internal format used by the SQL Access SQL processor, thus requiring no
conversion beyond the initial and/or final conversion in the CID Adapter Server.
The following restrictions on dates, times and timestamps apply to CID Adapter
dates, as well as SQL dates:
♦
The range of values allowed in the representation of a time value is
constrained by the 24-hour clock.
♦
For dates, the values used are constrained by the Gregorian calendar.
♦
If values are entered for a date or time that does not exist, an error is
flagged.
♦
The year component of a DATE must fall between A.D. 0 and 9999.
♦
The year component of a TIMESTAMP value has a smaller range, specifically
00:00:00 January 1, 1970 through 03:14:07 January 19, 2038 GMT.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
384
In addition, the following rolling century algorithm is used to calculate the
century of two-digit years stored in the database (%y or %D):
Current Year
Range
2 Digit Year
Range
Century
0-24
0-49
Current century
0-24
50-99
Previous century
25-74
All
Current century
75-99
0-49
Previous century
75-99
50-99
Current century
This provides a sliding 50 year window where dates are valid. Forward dates up
to 25 years ahead of the current date are valid through the transition points
and for 25 years after the transition point.
Holding two digit year dates in a database for longer than 50 years
results in century creep.
Example
The CUSTOMER file is extended to include a field called DATE-OF-LAST-SALE
defined as follows:
10
CUST-DATE-OF-LAST-SALE
PIC 9(10)
COMP-3.
The database definition for this field would be:
<Field
Name="DATE-OF-LAST-SALE"
Type="UNSIGNED-PACKED"
Length="5"
Date_type=”date”
Date_format=”0%m%d%Y” />
Unsigned packed fields have a sign nibble even though they are
unsigned. In order to store 8 digits in the field, there must be 10 digits
with one digit being wasted. 10 digits can be stored in 5 packed
characters. The sign nibble is never considered as a character of the
field. It is necessary to consume the entire packed field with the
format. Any valid numeric character may be used as a filler for unused
nibbles.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
385
Foreign_key
Foreign keys are one or more fields in one file that, taken together within one
record, contain a unique key value in another file. The access method of the
referenced file may be a PDM control key, or a unique index. All referback
fields in PDM related files are automatically defined as foreign keys.
There are other frequently used instances of foreign keys in databases that are
not defined to the database and therefore do not exist in the internal schema.
Primary file control keys can be stored in any record in the database and used
to locate data in a one to one relationship. These foreign keys are not defined
in the PDM Directory and must be defined in the CID Adapter Extensions XML
file if they are to be used by the CID Adapter Server.
For VSAM files, all foreign keys must be defined in the CID Adapter Extensions
XML file. There are none that are automatically defined.
The File element may include Foreign_key elements. The Foreign_key element
has the following structure:
<Foreign_key >
<References >
</References>
</Foreign_key>
A Foreign_key element has the following attributes:
Attribute Name
Fields
Required
Yes
Description
A comma-separated list of field names
composing the foreign key in this file.
A References element has the following attributes:
Attribute Name
Required
Description
Name
Yes
The name of the file to which the foreign
key refers.
Fields
Yes
A comma-separated list of field names
composing the key in the referenced file.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
386
Example
The customer file, CUST, contains a field CUSTBRAN which contains the control
key of the related branch record in the BRAN file. The following XML will define
this foreign key:
<File
Name="CUST">
<Foreign_key
Fields=”CUSTBRAN”>
<References
Name="BRAN"
Fields=”BRANCTRL”>
</References>
</Foreign_key>
</File>
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
387
Access_method
All standard PDM Access methods, control keys, linkpaths, and indices defined
in the PDM Directory will automatically be added to the internal schema. All
VSAM access methods defined for the files in the VSAM_FILE_LIST (KSDS files
and all Alternate Index files) will automatically be added to the internal
schema. In addition, all of the above mentioned access methods that contain
fields with sub-definitions will have extra access methods automatically
defined using the lowest level subfields of each field in the key.
Under certain circumstances it may be necessary to add additional access
methods to the schema. Additional access methods may be defined in the
schema using the Access_method element in a File element. The
Access_method element also can be used to modify the statistics of an existing
access method. In the case of VSAM alternate key access methods, the Unique
attribute also may be modified. The value set automatically for the Unique
attribute in this case is No (nonunique).
The Access_method element has the following structure:
<Access_method >
</Access_method>
An Access_method element has the following attributes:
Attribute Name
Required
Description
Name
Yes
Up to 32 character name of the access
method in the format <access-methodname>[_extension].
Type
No
One of the following access method
types: INDEX, HASH, LINKPATH, or KSDS,
where INDEX includes PDM secondary keys
and VSAM alternate keys.
Unique_keys
No
The number of unique keys in the index.
Overrides the value obtained from the
PDM directory.
Num_rows
No
The total number of rows available
through this access method. Overrides
the value obtained from the PDM
Directory.
Num_nulls
No
The number of keys in the access method
that are NULL. Overrides the value
obtained from the PDM directory.
Fields
No
Comma-separated list of fields that
compose the key.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
388
Unique
No
YES if the access method contains only
unique keys, No if there are duplicate
keys in the access method. For VSAM
alternate keys, the default is NO and can
be overriden.
For performance reasons, it may be useful to add access methods to a
file when an access method key contains multiple levels of subdefinitions and it is necessary to use the sub-defined fields that are not
automatically defined as access methods in join queries. Any number of
access methods may be defined using different combinations of subdefinitions of the key. The name of each access method must be unique
and must begin with the name of the access method followed by an
underscore and an extension.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
389
For example, if the PDM control key CUSTCTRL were defined as 10 characters
and sub-defined as CUSTCUID=2 and CUSTNUMB=8, the following
Access_method should be added to the CUST file:
<File
Name=”CUST”>
<Access_method
Name=”CUSTCTRL_IDNUM”
Type=”HASH”
Unique=”TRUE”
Fields=”CUSTCUID, CUSTNUMB”/>
</File>
This Access_method will allow the join optimizer to use the control key to
access the file if a join query specifies the CUSCUID and CUSTNUMB fields.
Without this access method the join optimizer will not recognize that the two
fields compose the control key and will produce a scan of the file.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
390
File Example
A PDM database or CICS VSAM system contains file(s) that are defined with a
large data item named DATA. COBOL copybooks define the record layouts. The
PART file has the following copybook:
05
PART-DATA.
10
PART-NUMBER
PIC X(15).
10
PART-DESCRIPTION
PIC X(30).
10
PART-LIST-PRICE
PIC 9(6)V99
COMP-3.
10
PART-DEALER-PRICE
PIC 9(6)V99
COMP-3.
10
PART-WAREHOUSE-PRICE
PIC 9(6)V99
COMP-3.
10
PART-COST
PIC 9(6)V99
COMP-3.
10
PART-QTY-ON-HAND
PIC 9(8)
COMP-3.
10
PART-QTY-ON-ORDER
PIC 9(8)
COMP-3.
10
PART-AVG-MONTHLY-SALES
PIC 9(8)
COMP-2.
The XML definition for this copybook would be as follows:
<File
Name="PART">
<Field
Name="PARTDATA">
<Subfield
Name="PART-NUMBER"
Type="CHARACTER"
Length="15"
Nulls=”NOT_NULL” />
< Subfield
Name="DESCRIPTION"
Type="CHARACTER"
Length="30"
Nulls=”ALLOWED” />
< Subfield
Name="LIST-PRICE"
Type="UNSIGNED-PACKED"
Length="5"
Decimals="2"
Nulls=”NOT_NULL” />
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
391
< Subfield
Name="DEALER-PRICE"
Type="UNSIGNED-PACKED"
Length="5"
Decimals="2"
Nulls=”NOT_NULL” />
< Subfield
Name="WAREHOUSE-PRICE"
Type="UNSIGNED-PACKED"
Length="5"
Decimals="2"
Nulls=”NOT_NULL” />
< Subfield
Name="COST"
Type="UNSIGNED-PACKED"
Length="5"
Decimals="2"
Nulls=”NOT_NULL” />
< Subfield
Name="QTY-ON-HAND"
Type="UNSIGNED-PACKED"
Length="5"
Nulls=”NOT_NULL”
Default=”0” />
< Subfield
Name="QTY-ON-ORDER"
Type="UNSIGNED-PACKED"
Length="5"
Nulls=”NOT_NULL”
Default=”0” />
< Subfield
Name="AVG-MONTHLY-SALES"
Type="FLOAT"
Length="8"
Nulls=”NOT_NULL”
Default=”0” />
</Field>
</File>
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
392
Unsigned packed fields have a sign nibble even though they are
unsigned. In order to store 8 digits in the field, there must be 10
digits with one digit being wasted. 10 digits can be stored in 5
packed characters.
View
A CID Adapter View can be defined to provide complex navigation rules to
access multiple PDM and/or VSAM files in a single view. This allows simple SQL
select statements to be used to access complex data relationships in PDM and
VSAM.
This is accomplished by adding CID Adapter View definitions to the CID Adapter
Extensions XML file, which is read by the CID Adapter Server to extend the CID
Adapter schema.
Once the CID Adapter View has been added to the schema, you can create a
foreign table on that CID Adapter View. You then select from the foreign table
just as you would from a foreign table created for an individual PDM or VSAM
file. See "View example" on page 400 for a complete example.
The View element has the following structure:
<View >
<Access/>
</View>
The View element has the following attribute:
Attribute Name
Required
Description
Name
Yes
Up to 32 character name of the view. It
may include alphabetic characters,
numbers, and dashes (but not
underlines).
External_name
No
Up to 32 character external name of the
view. If present, this name will be used in
the foreign table definition.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
393
Access
An Access element defines one database or CICS VSAM access to the named
file. The first Access element in the View will always be accessed first. It must
not have a Using, From, Via, Once or Reverse attribute. Subsequent Access
elements are executed in the order specified and require either a Using or Via
attribute, or both. Any number of Access elements may be included in a View.
The Access element has the following structure:
<Access >
</Access >
An Access element has the following attributes. These are discussed in more
detail later in this section.
Attribute Name
Required
Description
Name
Yes
The file name to be accessed. May
include a comma separated list of record
codes enclosed in parentheses; for
example, (HD,IT).
Alias
No
Up to 32 character alias for this access.
From
No
An alias name or file name and a single
record code. Provides a starting point for
a linkpath Access
Using
No
A comma-separated list of field names or
string literals composing the key for this
Access.
Via
No
An access method name or
comma-separated list of field names
composing the key of an access method
enclosed in parentheses.
Once
No
Either TRUE or FALSE. If set to TRUE the
Access will return only one record.
Reverse
No
Either TRUE or FALSE. If set to TRUE the
records will be returned in reverse order.
The WHERE clause of the SQL query or the foreign table query is used to
optimize the first Access. If no key values are supplied, a scan is implied. The
WHERE clause is also used to qualify the records read for each Access. Records
are qualified after they are read. If a record does not qualify, the next record
is read. The WHERE clause is also used to qualify the view record after all
Accesses have been executed. View qualification will be done when the WHERE
clause contains a comparison between two attributes read from two different
Accesses.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
394
If an Access has no records (MRNF or END. is returned on the read), the fields
requested from that Access will be set to NULL. If no keys are required from
that Access, the next Access is executed. If keys are required from the NULL
record, all of the fields from the remaining Accesses will be set to NULL.
All Accesses in a view will be performed even if no data is being selected from
them. This can cause what appears to be duplicate records in the result set.
Duplicate records in the result set can be eliminated by using the UNIQUE
keyword in the select list.
Examples
<Access Name=”PO1=PORD” …/>
<Access Name=”POLN(HD)” …/>
<Access Name=”POLN(HD,LN)” …/>
Name
This attribute has the following syntax:
Name=”[alias-name=]file-name [(record-code[, record-code...])]”
Name identifies the dataset and record containing the field values to be
returned. One or more record codes may be specified with this attribute. When
more than one record code is specified an OR is implied. The dataset is read
until one of the record codes specified is found. The fields requested in the
select clause for that record code are returned with the remaining fields from
all other record codes set to NULL.
Alias-name
Alias allows you to assign an identifier to a file-name so as to distinguish
ambiguous Access elements; that is, multiple Access elements for the same
data-set.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
395
From
This attribute has the following syntax:
From=”alias-name | file-name [(record-code)]”
From applies only to PDM file access; it does not apply to VSAM file access.
From provides a starting point for a linkpath Access. It may be used to identify
a particular Access from which to extract the control key or refer, if the named
access method is a linkpath. Also see the discussion of the Via attribute, below,
for additional information.
The From attribute can only be used with a Via attribute that specifies a
linkpath. Either an alias name or data-set name may be specified.
If the specified Access is for a primary data-set, the control key of the record
read by that Access is used as the referback of this Access and the refer is set
to the linkpath name. If the specified Access is for a related dataset, the
referback and refer fields from the referenced Access are used for this Access.
If the specified Access contains multiple record codes, the From attribute must
contain one of the specified record codes.
Three uses are possible:
♦
To access an ordered chain when different coded records, such as
header(HD)/detail(LN), are stored on the same linkpath. The From
attribute refers to a related file Access. The current refer and referback
field of the referenced Access will be used to begin this Access. The Access
returns records until a record is read that contains a different record code
than the code of this Access.
Examples
<Access Name=”PORD”/>
<Access Name=”POLN(HD)” Via=”PORDLK01”/>
<Access Name=”POLN(LN)” Via=”PORDLK01” From=”POLN(HD)”/>
♦
To switch linkpaths from one primary dataset to another using the
referback field of the linkpath as the control key for the Access.
Examples
<Access Name=”SUPP”
<Access Name=”POLN(HD)” Via=”SUPPLK01”/>
<Access Name=”POLN(LN)” Via=”PORDLK01” From=”POLN(HD)”/>
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
396
♦
To specify the primary Access from which the linkpath specified in a Via
attribute is to be accessed when there is more than one Access attribute
for the same primary data-set. The control key of the primary Access
specified will be used with the LKxx refer to start the access.
Examples
<Access Name=”SUPP” Alias=”SUPPLIER”/>
<Access Name=”SUPP” Alias=”WAREHOUSE” Using
“SUPPLIER:SUPPWHSE”/>
<Access Name=”POLN(HD)” Via=”SUPPLK01” From=”WAREHOUSE”/>
<Access Name=”POLN(LN)” Via=”PORDLK01” From=”POLN(HD)”/>
These examples assume that the field SUPPWHSE contains the control key
of a warehouse record for a supplier that is also in the supplier data-set.
Using
This attribute has the following syntax:
Using=”[(][alias-name:]field-name | subfield | “string-literal”[,
[alias-name:]field-name…]][)]”
Using may be used by itself to specify the control key value of a PDM primary
file or may be used in conjunction with a Via attribute to specify the value of
the key for an indexed access method named in the Via attribute. The Using
attribute may not be used with a Via attribute that specifies a linkpath. See
the discussion of the Via attribute, below, for additional information.
The fields referenced must be available from Access elements previously
defined in the view. They may not refer to fields in the current or subsequent
Access elements.
Alias names may be used to specify a specific Access from which to extract the
key value. If no alias name is specified, the next prior Access containing the
field will be chosen.
String literals may be supplied in the Using attribute using double quoted
strings (e.g. “string-literal”).
Examples
<Access Name=”INVC”/>
<Access Name=”BRAN” Using=”INVCBRAN”/>
<Access Name=”CUST” Via=”CUSTSK01" Using=”INVCCUST”/>
These examples assume that there is an index on the customer file.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
397
In this PDM example, the INVC file is accessed first. Then the BRAN file is
accessed using the field INVCBRAN from the INVC file. Then the CUST file is
accessed via the index named CUSTSK01 using a field from the INVC file named
INVCCUST.
This example assumes that there is an index on the CUST file.
<Access Name=”invoice”/>
<Access Name=”branch” Using=”invoice_branch_no”/>
In this VSAM example, the invoice file is accessed first. Then the branch file is
accessed using the field invoice_branch_no from the invoice file.
Via
Via defines the access method to use to access this dataset. The named access
method can be either a secondary key name or a linkpath name for PDM or it
can be an alternate index name for a VSAM file. If the named access method is
a secondary key (for PDM) or an alternate index (for VSAM), the Access element
must contain a Using attribute (see above) to identify the key value. If the
named access method is a linkpath, the From attribute (see above) may be
used to identify a particular Access from which to extract the control key or
refer. If a From attribute is not used, the control key of the previously defined
primary dataset for the linkpath is assumed. When the Via attribute is used,
the Once, Reverse or From attributes may also be specified.
Examples
<Access Name=”INVC”/>
<Access Name=”INVL” Via=”INVCLK01”/>
<Access Name=”CUST Via=”CUSTSK01” Using=”INVCCUST”
In this PDM example, the INVC file is accessed first. Then the INVL
file is accessed using the INVCLK01 linkpath from the INVC file.
Then the CUST file is accessed via the index CUSTSK01 in the CUST
file using the INVCCUST field from the INVC file.
<Access Name=”INVOICE”/>
<Access Name=”INVLINE” Via=”INVLNPTH” Using=”INVOICE_NO”/>
In this VSAM example, the invoice file is accessed first. Then the invline
file is accessed using the alternate index access method named invline
using the invoice_no field from the invoice file.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
398
Once
This attribute has the following syntax:
Once=”TRUE | FALSE”
Once indicates whether or not only the first record is to be retrieved from the
data-set. This attribute can be used only if the Via attribute is also used. The
named access method can be either a linkpath or a secondary key.
Examples
<Access Name=”INVC”/>
<Access Name=”INVL” Via=”INVLLK01” Once=”TRUE”/>
<Access Name=”INVOICE”/>
<Access Name=”INVLINE” Via=”INVLNPTH” Using=”INVOICE_NO
Once=”TRUE”/>
In this VSAM example, the invoice file is accessed first. Then the invline
file is accessed ONCE using the alternate index access method named
invline using the invoice_no field from the invoice file.
Reverse
This attribute has the following syntax:
Reverse=”TRUE | FALSE”
Reverse is not applicable to VSAM files.
Reverse indicates whether or not the named access method will be read in
reverse order. This attribute can be used only if the Via attribute is also used.
Examples
<Access Name=”INVC”/>
<Access Name=”INVL” Via=”INVLLK01” Reverse=”TRUE”/>
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
399
View example
The following is an example of a CID Adapter View in the CID Adapter
Extensions XML file:
<View
Name=”INVOICE-CUSTOMER”>
<Access=”INVC”/>
<Access=”INVL” Via=”INVLLK01”/>
<Access=”CUST” Via=”CUSTSK01” Using=”INVCCUST”/>
</View>
With this view definition in the CID Adapter Extensions XML file, a foreign table
can be created that uses this CID Adapter View named INVOICE-CUSTOMER:
create foreign_table invoice_cust
(invoice_no
char(4),
invoice_slsprsn
char(4),
invoice_total
char(9),
invoice_branch
char(4).
invoice_date
numeric(5),
invoice_customer
char(6),
invline_invoice
char(4),
invline_product
char(9).
invline_qnty
numeric(5),
invline_price
numeric(9,2),
customer_no
char(6),
customer_name
char(20),
customer_addr
char(20),
customer_city
char(13),
customer_state
char(2),
customer_zipcode
numeric(5),
customer_class
char(2),
customer_cr_code
char(2),
customer_cr_limit
numeric(9,2),
customer_branch
char(4))
as
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
400
select invoice_no, invoice_slsprsn, invoice_total,
invoice_branch, invoice_date, invoice_customer,
invline_invoice, invline_product, invline_qnty, invline_price,
customer_no, customer_name, customer_addr, customer_city,
customer_state, customer_zipcode, customer_class,
customer_cr_code, customer_cr_limit, customer_branch from
“INVOICE-CUSTOMER”
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
401
The following is an example of a CID Adapter View in the CID Adapter
Extensions XML file for VSAM files:
<View
Name=”INVOICE-CUSTOMER”>
<Access=”INVOICE”/>
<Access Name=”INVLINE” Via=”INVLNPTH” Using=”INVOICE_NO”/>
<Access=”CUSTOMER” Via=”CUSTOMER” Using=”INVOICE_CUST_NO”/>
</View>
With this view definition in the CID Adapter Extensions XML file, a foreign table
can be created that uses this CID Adapter View name INVOICE-CUSTOMER:
create foreign_table invoice_cust
(invoice_no
char(4),
invoice_slsprsn
char(4),
invoice_total
char(9),
invoice_branch
char(4).
invoice_date
numeric(5),
invoice_customer
char(6),
invline_invoice
char(4),
invline_product
char(9).
invline_qnty
numeric(5),
invline_price
numeric(9,2),
customer_no
char(6),
customer_name
char(20),
customer_addr
char(20),
customer_city
char(13),
customer_state
char(2),
customer_zipcode
numeric(5),
customer_class
char(2),
customer_cr_code
char(2),
customer_cr_limit
numeric(9,2),
customer_branch
char(4))
as
select invoice_no, invoice_slsprsn, invoice_total,
invoice_branch, invoice_date, invoice_customer,
invline_invoice, invline_product, invline_qnty, invline_price,
customer_no, customer_name, customer_addr, customer_city,
customer_state, customer_zipcode, customer_class,
customer_cr_code, customer_cr_limit, customer_branch from
“INVOICE-CUSTOMER”
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
402
Cincom recommends that you include all the fields in all three files in this
foreign table, because you can only create one foreign table for the view. You
can then create SQL Access views that contain only the fields that you wish to
display. See "Creating a view" on page 57 for more information.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Extending the CID Adapter Schema
403
COPY2XML COBOL copybook tool
The Copy2XML tool is available only on Windows.
In order to assist you in creating the CID Adapter Extensions XML file, we have
provided a tool that will convert a COBOL copybook into XML-formatted output.
The Copy2XML tool will read a COBOL copybook and create a file that follows
the XML format described in the section "Extending the CID Adapter Schema" on
page 371. This output can be used to create a CID Adapter Extensions XML file
or merged into an existing CID Adapter Extensions XML file.
To execute:
1. If the copybook(s) do not currently exist on Windows, move the
copybook(s) to Windows in the ORDB directory using a utility such as FTP.
2. Open a command prompt window on the PC and change the directory to
your ORDB directory.
3. Execute the Copy2XML as follows for each copybook:
PDM
Copy2XML -c <copybook name> -d <database_type>
-x <XML output file name> -f <native file name>
-e <PDM element name> -r <record code> -l <list file name>
where:
<copybook name> is the input copybook filename.
<database_type> is PDM ; default is PDM.
<XML output file name> is the name where XML output for copybook is
placed. Default is output.xml.
<native file name> is the name of the PDM file that the copybook
describes.
<PDM element name> {PDM ONLY} is the name of the PDM element that
this copybook redefines.
<record code> {PDM ONLY} is the record code of the related file that
this copybook redefines.
<list file name> is the name of a file on the PC that processes multiple
copybooks in one execution. If this option is specified, the only other
valid option is -x <XML output file name>. See #6 for further details on
the list file.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: COPY2XML COBOL copybook tool
404
VSAM
Copy2XML -c <copybook name> -d <database_type>
-x <XML output file name> -f <native file name>
-o <ORDB Server name> -f <foreign database name>
-u <ORDB user name> -p <ORDB password> -l <list file name>
where:
<copybook name> is the input copybook filename.
<database_type> is PDM ; default is PDM.
<XML output file name> is the name where XML output for copybook is
placed. Default is output.xml.
<native file name> is the name of the file that the copybook describes.
For VSAM this is the name in the VSAM_FILE_LIST. Defaults to copybook
name.
<ORDB Server name> [VSAM ONLY] is the name of the ORDB Server that
will connect to the CID Adapter Server.
<foreign database name> {VSAM ONLY} is the name of the foreign file
that contains the native file that this copybook redefines.
<user name> {VSAM ONLY} is the name of the DBA user for the ORDB
Server.
<ORDB password> {VSAM ONLY} is the password for the DBA user for the
ORDB Server.
<list file name> is the name of a file on the PC that processes multiple
copybooks in one execution. If this option is specified, the only other
valid option is -x <XML output file name>. See #6 for further details on
the list file.
4. This utility will generate a file named <XML output file name> and a log file
in this same directory named Copy2XML.log.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: COPY2XML COBOL copybook tool
405
5. Review the generated file to ensure:
VSAM
♦
That the File element has a Name parameter that matches the VSAM
file name in the VSAM_FILE_LIST parameter.
VSAM
♦
That the high-level/base Field element has NAME=<file-name>_BASE.
PDM
♦
That the File element has a Name parameter that is the 4 character
PDM file name.
PDM
♦
If it is a coded file you must add Record_code=”<record-code>”. This is
not generated by the Copy2XML tool.
See "File" on page 374 for further information.
6. If you have more than one copybook you wish to add to the XMLFILE, you
may use the –l parameter on the command file. This allows you to create
an input file that lists all the copybooks and their parameters in this form.
This parameter (-l) may only be accompanied by one other parameter on
the command line: the –x parameter, which specifies the name of the XML
output file. The default name is output.xml if –x is not supplied. All the
copybooks in the list file will be translated into the same output file.
The parameters within the list file differ slightly for PDM copybooks versus
VSAM copybooks.
PDM
♦
List parameters for each copybook on a separate line in this order:
<copybook name> <database type> <native file name>
<PDM element name> <record code>
VSAM
♦
List parameters for each copybook on a separate line in this order:
< copybook name> <database type> <native file name>
<ORDB Server name> <foreign database name>
<ORDB user name> <ORDB password >
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: COPY2XML COBOL copybook tool
406
7. The resulting output file is then moved to the CID Adapter Server platform
using a utility such as FTP. It can then be used as the CID Adapter
Extensions XMLFILE or merged into an existing XMLFILE for the CID Adapter
Server.
If merging this file into an existing XMLFILE, remove the first two lines of
the <XML output file>:
<?xml version="1.0" encoding="UTF-16" standalone="no" ?>
<Adapter_Extensions>
and the last line of the <XML output file>:
</Adapter_Extensions>
These lines will already be present in the existing XMLFILE.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: COPY2XML COBOL copybook tool
407
Example
Copybook named branch.cob on Windows in the ORDB directory. This describes
a VSAM file in which BRANCH-NUMBER is the primary key and BRANCH-REGION
is an alternate index whose path name is BRANREG:
05
BRANCH-DATA.
10 BRANCH-NUMBER
PIC X(4).
10 BRANCH-NAME
PIC X(20).
10 BRANCH-REGION
PIC X(3).
10 BRANCH-ADDRESS
PIC X(20).
10 BRANCH-CITY
PIC X(13).
10 BRANCH-STATE-CODE
PIC X(2).
10 BRANCH-ZIPCODE
PIC 9(5).
10 BRANCH-DELIVERY-ROUTE
PIC X(2).
10 BRANCH-STAFF-QUOTA
PIC 9(5).
10 BRANCH-SALES-QUOTA
PIC 9(7)v99.
To execute:
C:\%ORDB%\Copy2XML
-c branch.cob –f BRANCH –d VSAM –o
burry_vsam –f vsam_cics –u dba –p test
Resulting XML file:
<?xml version="1.0" encoding="UTF-16" standalone="no" ?>
<Adapter_Extensions>
<File Name="BRANCH">
<Field Length="85" Name="BRANCH-BASE">
<Subfield Length="04" Name="BRANCH_KEY" Type="CHARACTER"
External Name = “BRANCH-NUMBER”/>
<Subfield Length="20" Name="BRANCH-NAME" Type="CHARACTER"/>
<Subfield Length="03" Name="BRANREG_KEY" Type="CHARACTER"
External Name=”BRANCH-REGION”/>
<Subfield Length="20" Name="BRANCH-ADDRESS" Type="CHARACTER"/>
<Subfield Length="13" Name="BRANCH-CITY" Type="CHARACTER"/>
<Subfield Length="02" Name="BRANCH-STATE-CODE"
Type="CHARACTER"/>
<Subfield Decimals="0" Length="05" Name="BRANCH-ZIPCODE"
Type="UNSIGNED_NUMERIC"/>
<Subfield Length="02" Name="BRANCH-DELIVERY-ROUTE"
Type="CHARACTER"/>
<Subfield Decimals="0" Length="05" Name="BRANCH-STAFF-QUOTA"
Type="UNSIGNED_NUMERIC"/>
<Subfield Decimals="2" Length="09" Name="BRANCH-SALES-QUOTA"
Type="UNSIGNED_NUMERIC"/>
</Field>
</File>
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: COPY2XML COBOL copybook tool
408
</Adapter_Extensions>
Copybook named poln.cob for a PDM record-coded file named POLN. The
record code is PD and the PDM element that the copybook subdefines/redefines
is POLNDATA:
03
POLN-DATA.
05 PO-NO
PIC X(6).
05 PO-RECEIVED-DATE
PIC 9(5).
05 PO-RECEIVED-QUANTITY
PIC 9(5).
05 PO-RECEIVED-DELIVERY
PIC 9(3).
05 PO-RECEIVED-PRODUCT-NO
PIC x(9).
To execute:
C:\%ORDB%\Copy2XML
-c poln.cob –f POLN –d PDM –p POLNDATA –r PD
Output:
<?xml version="1.0" encoding="UTF-16" standalone="no" ?>
<Adapter_Extensions>
<File Name="POLN" Record_Code=”PD” >
<Field Length="28" Name="POLNDATA">
<Subfield Length="06" Name="PO-NO" Type="CHARACTER"/>
<Subfield Decimals="0" Length="05" Name="PO-RECEIVED-DATE"
Type="UNSIGNED_NUMERIC"/>
<Subfield Decimals="0" Length="05" Name="PO-RECEIVED-QUANTITY"
Type=" UNSIGNED_NUMERIC "/>
<Subfield Decimals="0" Length="03" Name="PO-RECEIVED-DELIVERY"
Type=" UNSIGNED_NUMERIC "/>
<Subfield Length="09" Name="PO-RECEIVED-PRODUCT-NO"
Type="CHARACTER"/>
</Field>
</File>
</Adapter_Extensions>
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: COPY2XML COBOL copybook tool
409
If you wished to generate output for both of these copybooks using the list file
the command line would be:
C:\%ORDB%\Copy2XML
-l list.txt –x xmlout.xml
The content of input file list.txt:
branch.cob BRANCH VSAM burry_vsam vsam_cics dba test
poln.cob POLN PDM POLNDATA PD
Output:
<?xml version="1.0" encoding="UTF-16" standalone="no" ?>
<Adapter_Extensions>
<File Name="BRANCH">
<Field Length="85" Name="BRANCH_BASE">
<Subfield Length="04" Name="BRANCH_KEY" Type="CHARACTER"
External Name=”BRANCH-NUMBER”/>
<Subfield Length="20" Name="BRANCH-NAME" Type="CHARACTER"/>
<Subfield Length="03" Name="BRANREG_key" Type="CHARACTER"
External Name=”BRANCH-REGION”/>
<Subfield Length="20" Name="BRANCH-ADDRESS"
Type="CHARACTER"/>
<Subfield Length="13" Name="BRANCH-CITY" Type="CHARACTER"/>
<Subfield Length="02" Name="BRANCH-STATE-CODE"
Type="CHARACTER"/>
<Subfield Decimals="0" Length="05" Name="BRANCH-ZIPCODE"
Type="UNSIGNED_NUMERIC"/>
<Subfield Length="02" Name="BRANCH-DELIVERY-ROUTE"
Type="CHARACTER"/>
<Subfield Decimals="0" Length="05" Name="BRANCH-STAFF-QUOTA"
Type="UNSIGNED_NUMERIC"/>
<Subfield Decimals="2" Length="11" Name="BRANCH-SALES-QUOTA"
Type="UNSIGNED_NUMERIC"/>
</Field>
</File>
<File Name="POLN" Record_Code=”PD” >
<Field Length="28" Name="POLNDATA">
<Subfield Length="06" Name="PO-NO" Type="CHARACTER"/>
<Subfield Decimals="0" Length="05" Name="PO-RECEIVED-DATE"
Type="UNSIGNED_NUMERIC"/>
<Subfield Decimals="0" Length="05" Name="PO-RECEIVED-QUANTITY"
Type=" UNSIGNED_NUMERIC "/>
<Subfield Decimals="0" Length="03" Name="PO-RECEIVED-DELIVERY"
Type=" UNSIGNED_NUMERIC "/>
<Subfield Length="09" Name="PO-RECEIVED-PRODUCT-NO"
Type="CHARACTER"/>
</Field>
</File>
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: COPY2XML COBOL copybook tool
410
</Adapter_Extensions>
The resulting XML file is then moved to the CID Adapter Server platform using a
utility such as FTP.
The following table shows how the COBOL Picture clause is converted to the
SQL Access data type in the XML file:
SQL ACCESS TYPE
PLATFORM
COBOL
PICTURE
COBOL
USAGE
CHARACTER
All
X(n)
BIT
All
Any
UNSIGNED_BINARY
All
9(n)
SIGNED_BINARY
All
S9(n)
COMP-4
UNSIGNED_PACKED
All
9(n)
COMP
COMP-3
SIGNED_PACKED
All
S9(n)
COMP
COMP-3
FLOAT
All
S9(n)
COMP-1
COMP-2
UNSIGNED_NUMERIC
All
9(n)
DISPLAY
UNSIGNED_NUMERIC
MVS
Treated as unsigned numeric
9(n)
DISPLAY
UNSIGNED_NUMERIC
VMS/UNIX
Treated as unsigned numeric
9(n)
DISPLAY
UNSIGNED_NUMERIC
VMS/UNIX
Treated as unsigned numeric
9(n)
DISPLAY
UNSIGNED_NUMERIC
VMS/UNIX
Treated as unsigned numeric
9(n)
DISPLAY
COBOL SIGN
COMP-4
LEADING_ZONED
MVS
S9(n)
DISPLAY
LEADING
TRAILING_ZONED
MVS
S9(n)
DISPLAY
TRAILING
TRAILING_ZONED
VMS/UNIX
S9(n)
DISPLAY
TRAILING
LEADING_SEPARATE
All
S9(n)
DISPLAY
LEADING SEPARATE
TRAILING_SEPARATE
All
S9(n)
DISPLAY
TRAILING SEPARATE
LEADING_OVERPUNCH
VMS/UNIX
S9(n)
DISPLAY
LEADING
TRAILING_OVERPUNCH
VMS/UNIX
S9(n)
DISPLAY
TRAILING
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: COPY2XML COBOL copybook tool
411
Modifying the ASCII/EBCDIC translation tables
The CID Adapter Server uses two translation tables that translate characters
between EBCDIC (SAA code page 1047) and ASCII (ISO 8859-1 Latin-1). Listings
of these tables are provided below. If you desire, you can override one or both
of these tables. Assembler versions of these tables are contained in the
MACLIB library installed from the release tape.
Each override table is coded in a separate load module. The load module has
exactly 256 bytes of translation values. The translation tables can be
generated using any language desired as long as the entry point address of the
load module points to the first byte of data. The load modules must be placed
in the JOBLIB or STEPLIB library so they can be loaded during CID Adapter
Server initialization.
The TOASCII= and TOEBCDIC= initialization parameters are used to specify the
names of the modules to be loaded for translation.
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Modifying the ASCII/EBCDIC translation tables
412
EBCDIC to ASCII default translation table
unsigned char EbcdicToAscii[256] = {
0x00, 0x01, 0x02, 0x03, 0x9c, 0x09, 0x86, 0x7f,
/* 00 - 07 */
0x97, 0x8d, 0x8e, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
/* 08 - 0F */
0x10, 0x11, 0x12, 0x13, 0x9d, 0x0a, 0x08, 0x87,
/* 10 - 17 */
0x18, 0x19, 0x92, 0x8f, 0x1c, 0x1d, 0x1e, 0x1f,
/* 18 - 1F */
0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x17, 0x1b,
/* 20 - 27 */
0x88, 0x89, 0x8a, 0x8b, 0x8c, 0x05, 0x06, 0x07,
/* 28 - 2F */
0x90, 0x91, 0x16, 0x93, 0x94, 0x95, 0x96, 0x04,
/* 30 - 37 */
0x98, 0x99, 0x9a, 0x9b, 0x14, 0x15, 0x9e, 0x1a,
/* 38 - 3F */
0x20, 0xa0, 0xe2, 0xe4, 0xe0, 0xe1, 0xe3, 0xe5,
/* 40 - 47 */
0xe7, 0xf1, 0xa2, 0x2e, 0x3c, 0x28, 0x2b, 0x7c,
/* 48 - 4F */
0x26, 0xe9, 0xea, 0xeb, 0xe8, 0xed, 0xee, 0xef,
/* 50 - 57 */
0xec, 0xdf, 0x21, 0x24, 0x2a, 0x29, 0x3b, 0x5e,
/* 58 - 5F */
0x2d, 0x2f, 0xc2, 0xc4, 0xc0, 0xc1, 0xc3, 0xc5,
/* 60 - 67 */
0xc7, 0xd1, 0xa6, 0x2c, 0x25, 0x5f, 0x3e, 0x3f,
/* 68 - 6F */
0xf8, 0xc9, 0xca, 0xcb, 0xc8, 0xcd, 0xce, 0xcf,
/* 70 - 77 */
0xcc, 0x60, 0x3a, 0x23, 0x40, 0x27, 0x3d, 0x22,
/* 78 - 7F */
0xd8, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67,
/* 80 - 87 */
0x68, 0x69, 0xab, 0xbb, 0xf0, 0xfd, 0xfe, 0xb1,
/* 88 - 8F */
0xb0, 0x6a, 0x6b, 0x6c, 0x6d, 0x6e, 0x6f, 0x70,
/* 90 - 97 */
0x71, 0x72, 0xaa, 0xba, 0xe6, 0xb8, 0xc6, 0xa4,
/* 98 - 9F */
0xb5, 0x7e, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78,
/* A0 - A7 */
0x79, 0x7a, 0xa1, 0xbf, 0xd0, 0x5b, 0xde, 0xae,
/* A8 - AF */
0xac, 0xa3, 0xa5, 0xb7, 0xa9, 0xa7, 0xb6, 0xbc,
/* B0 - B7 */
0xbd, 0xbe, 0xdd, 0xa8, 0xaf, 0x5d, 0xb4, 0xd7,
/* B8 - BF */
0x7b, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47,
/* C0 - C7 */
0x48, 0x49, 0xad, 0xf4, 0xf6, 0xf2, 0xf3, 0xf5,
/* C8 - CF */
0x7d, 0x4a, 0x4b, 0x4c, 0x4d, 0x4e, 0x4f, 0x50,
/* D0 - D7 */
0x51, 0x52, 0xb9, 0xfb, 0xfc, 0xf9, 0xfa, 0xff,
/* D8 - DF */
0x5c, 0xf7, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58,
/* E0 - E7 */
0x59, 0x5a, 0xb2, 0xd4, 0xd6, 0xd2, 0xd3, 0xd5,
/* E8 - EF */
0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
/* F0 - F7 */
0x38, 0x39, 0xb3, 0xdb, 0xdc, 0xd9, 0xda, 0x9f
/* F8 - FF */
};
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Modifying the ASCII/EBCDIC translation tables
413
ASCII to EBCDIC default translation table
unsigned char AsciiToEbcdic[256] =
{
0x00, 0x01, 0x02, 0x03, 0x37, 0x2d, 0x2e, 0x2f,
/* 00 - 07 */
0x16, 0x05, 0x15, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
/* 08 - 0F */
0x10, 0x11, 0x12, 0x13, 0x3c, 0x3d, 0x32, 0x26,
/* 10 - 17 */
0x18, 0x19, 0x3f, 0x27, 0x1c, 0x1d, 0x1e, 0x1f,
/* 18 - 1F */
0x40, 0x5a, 0x7f, 0x7b, 0x5b, 0x6c, 0x50, 0x7d,
/* 20 - 27 */
0x4d, 0x5d, 0x5c, 0x4e, 0x6b, 0x60, 0x4b, 0x61,
/* 28 - 2F */
0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
/* 30 - 37 */
0xf8, 0xf9, 0x7a, 0x5e, 0x4c, 0x7e, 0x6e, 0x6f,
/* 38 - 3F */
0x7c, 0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc6, 0xc7,
/* 40 - 47 */
0xc8, 0xc9, 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6,
/* 48 - 4F */
0xd7, 0xd8, 0xd9, 0xe2, 0xe3, 0xe4, 0xe5, 0xe6,
/* 50 - 57 */
0xe7, 0xe8, 0xe9, 0xad, 0xe0, 0xbd, 0x5f, 0x6d,
/* 58 - 5F */
0x79, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87,
/* 60 - 67 */
0x88, 0x89, 0x91, 0x92, 0x93, 0x94, 0x95, 0x96,
/* 68 - 6F */
0x97, 0x98, 0x99, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6,
/* 70 - 77 */
0xa7, 0xa8, 0xa9, 0xc0, 0x4f, 0xd0, 0xa1, 0x07,
/* 78 - 7F */
0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x06, 0x17,
/* 80 - 87 */
0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x09, 0x0a, 0x1b,
/* 88 - 8F */
0x30, 0x31, 0x1a, 0x33, 0x34, 0x35, 0x36, 0x08,
/* 90 - 97 */
0x38, 0x39, 0x3a, 0x3b, 0x04, 0x14, 0x3e, 0xff,
/* 98 - 9F */
0x41, 0xaa, 0x4a, 0xb1, 0x9f, 0xb2, 0x6a, 0xb5,
/* A0 - A7 */
0xbb, 0xb4, 0x9a, 0x8a, 0xb0, 0xca, 0xaf, 0xbc,
/* A8 - AF */
0x90, 0x8f, 0xea, 0xfa, 0xbe, 0xa0, 0xb6, 0xb3,
/* B0 - B7 */
0x9d, 0xda, 0x9b, 0x8b, 0xb7, 0xb8, 0xb9, 0xab,
/* B8 - CF */
0x64, 0x65, 0x62, 0x66, 0x63, 0x67, 0x9e, 0x68,
/* C0 - C7 */
0x74, 0x71, 0x72, 0x73, 0x78, 0x75, 0x76, 0x77,
/* C8 - DF */
0xac, 0x69, 0xed, 0xee, 0xeb, 0xef, 0xec, 0xbf,
/* D0 - D7 */
0x80, 0xfd, 0xfe, 0xfb, 0xfc, 0xba, 0xae, 0x59,
/* D8 - DF */
0x44, 0x45, 0x42, 0x46, 0x43, 0x47, 0x9c, 0x48,
/* E0 - E7 */
0x54, 0x51, 0x52, 0x53, 0x58, 0x55, 0x56, 0x57,
/* E8 - EF */
0x8c, 0x49, 0xcd, 0xce, 0xcb, 0xcf, 0xcc, 0xe1,
/* F0 - F7 */
0x70, 0xdd, 0xde, 0xdb, 0xdc, 0x8d, 0x8e, 0xdf,
/* F8 - FF */
};
Administration Guide, P25-9501-04
Appendix: A. Advanced Topics
Section: Modifying the ASCII/EBCDIC translation tables
414
B. S1_ADAPTER_SETUP
OpenVMS
****************************************************************
CINCOM SUPRA CID Adapter Setup Script
****************************************************************
This script may be used to set up any number of
CID Adapter Servers for the V1HUB PDM System.
The current user V1HUBDEV will be the owner of the
files associated with all PDM Adapters created by this
s1_adapter_setup session.
The files associated with the PDM Adapters will be maintained
in the directory [V1HUBDEV].
->
Continue? (Y/N) [Y]:
The following is a list of the V1HUB SUPRA PDM databases.
Each CID Adapter Server is associated with exactly
one PDM database.
1. 001_TESTDB
GROUP_000212
2. BURRYS
GROUP_000212
3. SYSWID
SYSTEM_TABLE
->
Enter your menu selection
or press ENTER to exit CID Adapter Server setup: 2
The adapter name must be unique on this system.
In order make the adapter name unique, it can be
extended with 1 to 4 alpha numeric characters.
For example, you might add PROD to one adapter_name
and TEST to another.
->
Enter the adapter name extension or press ENTER for none:
Each CID Adapter Server must have a TCPIP
port number associated with it. The port number
must be available and unique on this machine.
The port number will be used in the SQL
Access REGISTER FOREIGN DATABASE statement to identify
which CID Adapter Server will service the database
requests for the CID Foreign Database.
->
Enter the TCPIP port number to be used
for this CID Adapter Server [5014]:
The TCPIP service BURRYS has a limit
Administration Guide, P25-9501-04
Appendix: B. S1_ADAPTER_SETUP
Section: OpenVMS
415
parameter that controls the maximum number of copies
that are allowed to run. One copy is required for
each client connection, therefore, the limit parameter
must correspond to the MAX_ACTIVE parameter specified
in the SQL Access REGISTER statement
for this CID Foreign Database.
->
Enter the TCPIP limit parameter to be used
for this CID Adapter Server [10]:
Each CID Adapter Server has a record limit
that specifies the maximum number of PDM reads that
are allowed to be used to retrieve data during a query.
The default of 0 indicates that there is no limit.
->
Enter the MAX_RECORDS_LIMIT to be used
for this CID Adapter Server [0]:
Copying or creating BURRYS initialization files
in [V1HUBDEV].
Creating BURRYS_INIT.DAT in [V1HUBDEV]
Creating BURRYS_COORD_START.COM in [V1HUBDEV]
->
Creating BURRYS_SERVER_START.COM in [V1HUBDEV]
The CID Adapter Coordinator can be either submitted to a
batch queue or run detached.
Which would you prefer? (1=batch, 2=detached) [1]:
Creating BURRYS_RUN.COM in [V1HUBDEV]
Creating BURRYS_STOP.COM in [V1HUBDEV]
->
Press ENTER to continue:
The MAX_RECORDS_LIMIT parameter of the BURRYS_INIT.DAT file
has been set to 0.
The TCPPORT parameter of the BURRYS_INIT.DAT file
has been set to 5014.
The DBMOD parameter of the BURRYS_INIT.DAT file
has been set to BURRYS.
->
Press ENTER to continue:
The TCPIP service BURRYS has been created or
modified with the following information:
port=5014
file=[V1HUBDEV]BURRYS_SERVER_START.COM
user=V1HUBDEV
limit=10
Administration Guide, P25-9501-04
Appendix: B. S1_ADAPTER_SETUP
Section: OpenVMS
416
process=BURRYS
->
Press ENTER to continue:
The BURRYS CID Adapter Server is now ready to run.
The adapter can be run by executing the following command:
@[V1HUBDEV]BURRYS_RUN
The adapter can be stopped by executing the following command:
@[V1HUBDEV]BURRYS_STOP
If you are in the process of installing SQL Access,
it is recommended that you start the BURRYS PDM Adapter
Server before continuing with Part 2 of the Windows installation.
This will allow you to define PDM foreign tables using VSQL.
->
Start the BURRYS CID Adapter Server now? (Y/N) [Y]:
Job BURRYS (queue SYS$BATCH, entry 44) started on SYS$BATCH
This completes the set up for BURRYS CID Adapter Server
in the V1HUB PDM System.
->
Press ENTER to set up a CID Adapter Server for another database
or enter Q to quit:
The following is a list of the V1HUB SUPRA PDM databases.
Each CID Adapter Server is associated with exactly
one PDM database.
1. 001_TESTDB
GROUP_000212
2. BURRYS
GROUP_000212
3. SYSWID
SYSTEM_TABLE
->
Enter your menu selection
or press ENTER to exit CID Adapter Server setup:
Exiting s1_adapter_setup
Administration Guide, P25-9501-04
Appendix: B. S1_ADAPTER_SETUP
Section: OpenVMS
417
UNIX
****************************************************************
CINCOM SUPRA PDM Adapter Setup Script
****************************************************************
This script may be used to set up any number of
CID Adapter Servers for the XSQL PDM System.
The CID Adapter Server service level 2400
has been installed in the standard PDM install directory
/supra1/adapters.
The current user xsql will be the owner of the
files associated with all PDM Adapters created by this
s1_adapter_setup session.
The files associated with the PDM Adapters will be maintained
in the directory /supra1/XSQL.
->
Continue? (Y/N) [Y]:
The following is a list of the XSQL SUPRA PDM databases
available to user xsql.
Each CID Adapter Server is associated with exactly
one PDM database.
Building database menu. Please wait...
1. BURRYS
->
group_523
Enter your menu selection
or press ENTER to exit CID Adapter Server setup: 1
The adapter name must be unique on this system.
In order to make the adapter name unique it can be
extended with 1 to 4 alpha numeric characters.
For example, you might add PROD to one adapter_name
and TEST to another.
->
Enter the adapter name extension or press ENTER for none:
Each CID Adapter Server must have a TCPIP
port number associated with it. The port number
must be available and unique on this machine.
The port number will be used in the SUPRA Relational
Access REGISTER FOREIGN DATABASE statement to identify
which CID Adapter Server will service the database
requests for the CID Foreign Database.
->
Enter the TCPIP port number to be used
for this CID Adapter Server [5010]:
Administration Guide, P25-9501-04
Appendix: B. S1_ADAPTER_SETUP
Section: UNIX
418
The /etc/services file is not writable and
cannot be updated. Please insert the following line
in /etc/services:
BURRYS 5010/tcp
The service BURRYS 5010/tcp
has been appended to the /supra1/adapters/services file.
Each CID Adapter Server has a record limit
that specifies the maximum number of PDM reads that
are allowed to be used to retrieve data during a query.
The default of 0 indicates that there is no limit.
->
Enter the MAX_RECORDS_LIMIT to be used
for this CID Adapter Server [0]:
Copying or creating BURRYS initialization files
in /supra1/XSQL.
Creating BURRYS.init in /supra1/XSQL
->
Press ENTER to continue:
The MAX_RECORDS_LIMIT parameter of the BURRYS.init file
has been set to 0.
The TCPPORT parameter of the BURRYS.init file
has been set to 5010.
The DBMOD parameter of the BURRYS.init file
has been set to BURRYS.
->
Press ENTER to continue:
The /supra1/XSQL/BURRYS_run script has been created.
The /supra1/XSQL/BURRYS_stop script has been created.
The BURRYS CID Adapter Server is now ready to run.
The CID Adapter Server can be run by executing the
following command:
/supra1/XSQL/BURRYS_run
The CID Adapter Server can be stopped by executing the
following command:
/supra1/XSQL/BURRYS_stop
If you are in the process of installing SQL Access,
it is recommended that you start the BURRYS CID Adapter
Server before continuing with Part 2 of the Windows installation.
This will allow you to define CID foreign tables using VSQL.
Administration Guide, P25-9501-04
Appendix: B. S1_ADAPTER_SETUP
Section: UNIX
419
->
Start the BURRYS CID Adapter Server now? (Y/N) [Y]:
Waiting for BURRYS_server to start.
BURRYS_server started - process number 9316.
By default, the BURRYS_run and BURRYS_stop scripts
are hard coded to use service level 2400. The scripts
can be made service level independent by setting the UNIX
environment variable, CSI_ADAPTER_SERVICE_LEVEL, to the
desired service level prior to executing these scripts.
This completes the set up for BURRYS CID Adapter Server
in the XSQL PDM System.
->
Press ENTER to set up a CID Adapter Server for another database
or enter Q to quit: q
Exiting s1_adapter_setup.
Administration Guide, P25-9501-04
Appendix: B. S1_ADAPTER_SETUP
Section: UNIX
420
Index
A accessing a prefixed database
142
Active Schema Maintenance 38
active_requests parameter
345
add_member method 80
add_user method 69, 78
addvoldb utility 263
allow_core_dump
UNIX CID Adapter Client
parameter 174
ALLOW_CORE_DUMP
MVS and CICS server
parameter 99
OpenVMS server parameter
131
UNIX CID Adapter Server
parameter 150
ALTER authorization 43
ALTER statement 43
ASCII translation (MVS) 412
attribute
DEFAULT value 58
dropping 50
renaming 52
authorization 61
for a foreign table 62
granting 63
revoking 66
auto_volext_factor parameter
331
B backup_buffer_size parameter
334
backup_max_volume_size
parameter 334
BIND_SCHEMA 99, 132, 151
MVS and CICS server
parameter 99
OpenVMS server parameter
132
UNIX CID Adapter Server
parameter 151
bound schema file 88
Administration Guide, P25-9501-04
Index
bring down master and servers
311
b-tree check 297
BYPASS_OPT_CTRL_LINKPATH
MVS and CICS server
parameter 100
OpenVMS server parameter
133
UNIX CID Adapter Server
parameter 152
BYPASS_OPT_INDEX
MVS and CICS server
parameter 100
OpenVMS server parameter
133
UNIX CID Adapter Server
parameter 152
BYPASS_QUAL
MVS and CICS server
parameter 100
OpenVMS server parameter
133
UNIX CID Adapter Server
parameter 152
C CHANGE clause 47
change_owner method 82
changedb utility 299
client/server mode 299
current password 300
DBA password 300
DBA user 300
new password 299
no specified options 301
prompt for remove password
300
remove password 300
return values 299
standalone mode 299
syntax 299
changing a SQL Access Server
password 299
charcode_check parameter
356
421
checkdb utility 296
b-tree check 297
class check 297
client/server mode 297
DBA password 298
DBA user 297
heap page check 297
heap page check and b-tree
check 297
page header check 297
quiet 297
return values 296
standalone mode 297
syntax 296
volume header check 297
volume path check 297
checking a SQL Access Server
296
checkpoint_interval_factor
parameter 335
CICS CID Adapter Server
starting on MVS 14
CID Adapter Client
start and shutdown 23
starting 22
tailoring 160
CID Adapter Client component
parameters
allow_core_dump 174
db_pdm_database-name 175
dbname 176
display_options 176
driver_directory 177
init_file 177
interproc_key 178
lang 178
load_path 179
max_rcv_pdu 179
max_records_limit 180
oid_cache_max 180
read_only 180
schema_segment_address
181
schema_segment_size 181
schema_table_size 181
table_segment_address 182
trace 182
CID Adapter Client component
parameters, summary
UNIX 173
Administration Guide, P25-9501-04
Index
CID Adapter Client
component, traceable
binaries 185
CID Adapter Coordinator 88
CID Adapter Server
shutting down 20
shutting down on MVS 20
shutting down on MVS CICS
21
shutting down on OpenVMS
21
shutting down on UNIX 21
starting on MVS 14
starting on OpenVMS 15
starting on UNIX 16
startup procedure
UNIX 148
tailoring 88
CID Adapter Server init file,
coding rules
UNIX 149
CID Adapter Server
initialization parameters
UNIX 149
CID Adapter View 393
CID foreign Database
altering registration 42
overview 28
registration, removing 53
CID foreign Database
parameters
default_adapter_dir 355
overview 355
class check 297
class_representation_cache
parameter 330
client component, tailoring
UNIX 170
client/server mode 297, 299
client/server requests SQL
Access Server parameters
345
coded record processing 38
coding rules
OpenVMS server init file 130
UNIX CID Adapter Server init
file 149
422
commdb utility 19, 307
bring down master and
servers 311
command-line arguments
308
halt shutdown 308
identify host name 308
print master and server
status 308, 311
quiet 308
quit commdb 311
reinitialize master 311
reinitialize SQL Access
Master 308
shutdown database server
311
shutdown master and servers
308
shutdown server 311
shutdown SQL Access Server
308
SQL Access Server password
308
start database server 311
startup database SQL Access
Server 308
terminate previous shutdown
request 311
COMMIT statement 83
communication services SQL
Access Server parameters
343
concurrency/locking SQL
Access Server parameters
339
connecting to a database host
189
connecting to server SQL
Access Client parameters
347
connection_timeout
parameter 347
controlling communication
between client and server
129
Administration Guide, P25-9501-04
Index
copydb utility 285
overwriting a SQL Access
Server 287
return values for 286
copying a SQL Access Server
in quiet mode 287
specifying
destination password 287
destination SQL Access
Server password 288
source password 287
copying SQL Access Servers
285
CSI_FOREIGN_KEY
OpenVMS 123
UNIX 148
CSI_INIT_FILE
OpenVMS 123
UNIX 148
CSI_MESSAGE_FILE
OpenVMS 123
UNIX 148
CSI_SERVER_SCHEMA
OpenVMS 123
UNIX 148
CSI_TRACE_FILE
OpenVMS 123
UNIX 148
CSI_TRACE_OPEN
OpenVMS 123
CSIHUBSHR 124
CSIHUBSHR_DEB 124
CSISERVER 124
CSISERVER_DEB 124
CSV1PING 96
csv1ping utility 17
CSV1PORT 97
csv1shut utility 20
current password 300
D data type mapping 36
data validation parameters
charcode_check 356
ignore_timezone 356
overview 356
423
database
bring down master and
servers 311
host
connecting 189
Visual Administration Tool
189
identify host name 308
print master and server
status 311
print SQL Access Master and
Server status 308
quit commdb 311
reinitialize master 311
shutdown database server
311
shutdown master and servers
308
shutdown server 311
start database server 311
terminate previous shutdown
request 311
database-specific parameters
176
DATBASUPD_LOCK 84
MVS and CICS server
parameter 101
date-time data types
properties of 384
range of supported values
384
db_authorizations class 76
db_pdm_database-name
UNIX CID Adapter Client
parameter 175
db_pdm-database-name 164,
175
db_user class 75
DBA password 300
DBA user 62, 300
DBA user, renaming 74
DBMOD
OpenVMS server parameter
134
UNIX CID Adapter Server
parameter 153
dbname 165, 176
UNIX CID Adapter Client
parameter 176
DBUGLINK library 184
deadlock_detection_interval
parameter 341
Administration Guide, P25-9501-04
Index
default parameter values,
defining 320
default_adapter_dir
parameter 355
defining
database parameter values
UNIX 171
environment variables 148
initialization parameters
OpenVMS 130
UNIX 149
installation parameter
values
UNIX 171
defining TCP/IP, for OpenVMS
server component 129
deletedb utility 290
output redirection 291
quiet 291
SQL Access Server password
291
deleting a SQL Access Server
after copying 287
deletedb utility 290
disable information banners
308
disk storage SQL Access Server
parameters 331
display_options 166
UNIX CID Adapter Client
parameter 176
DISPLAY_OPTIONS
MVS and CICS server
parameter 101
OpenVMS server parameter
134
UNIX CID Adapter Server
parameter 153
displaying
database transactions 211
ordbinit parameters 325
SQL Access release version
295
SQL Access Server lock
information 214
transaction lock information
213
displaying current parameter
values 176
domain
changing 50
information 35
424
driver_directory 166, 176,
177, 178, 179, 180, 181,
182
UNIX CID Adapter Client
parameter 177
DROP FOREIGN DATABASE
statement 54
drop_member method 73, 80
drop_user method 73, 79
E EBCDIC translation (MVS) 412
environment variables 148
ORDB 143
overriding values in the
ordbinit.txt file 321
error message SQL Access
Server parameters 328
event_handler parameter 328
execute_queries_streaming
parameter 349
exit, user logon
MVS 111
OpenVMS 140
UNIX 158
F fbo_root parameter 346
find_user method 79
flush_data_buffer_factor
parameter 336
foreign key file 88
foreign table
altering 43
creating 30
definition, removing 53
joining 56
Foreign Table Generator
Utility 30
foreign_table_query_specifica
tion 33
G get_owner method 82
GRANT statement 61, 63
group 60
adding 70
group member, deleting 73
Administration Guide, P25-9501-04
Index
H halt shutdown 308
heap page check 297
heap page check and b-tree
check 297
HOSTNAME LOOKUP
OpenVMS 138
UNIX 156
hot_fault_objects parameter
348
hot_load_workspace
parameter 348
I ignore_timezone parameter
356
init_file 166
UNIX CID Adapter Client
parameter 177
initial_workspace_table_size
parameter 349
initialization file 88
initialization parameters
defining for OpenVMS 130
defining for UNIX 149
interactive options 311
interproc_key, UNIX CID
Adapter Client parameter
178
isolation_level parameter 341
J java method broker
statusdb 315
K keep_schema_locks parameter
339
killing database transactions
Visual Administration tool
212
killing transactions 316
options 317
SQL Access Server 187
425
killtran utility
associated with
SQL Access Client host
317
SQL Access Client
program name 317
transaction index 317
user 317
disable banner informtion
317
display active transaction
information 317
options 317
overview 316
password of the DBA user
317
prompt to verify 317
L lang 166
UNIX CID Adapter Client
parameter 178
limitations
maximum number of rows
349
Server FBOs 346
time set on queries 352
load_path 167
UNIX CID Adapter Client
parameter 179
loaddb utility
cached page size 284
debug flag 284
load schema file 266
modify system class 306
options for 306
override TCP/IP port 306
quiet 306
quiet mode 283
read-only schema 306
lock_escalation parameter 339
lock_timeout_in_secs
parameter 339
lockf_enable parameter 340
locking 84
log file, specifying directory
path 286
log_path parameter 336
log_reserve_space parameter
336
log_size parameter 337
Administration Guide, P25-9501-04
Index
login method 78
logon exit
MVS 111
OpenVMS 140
UNIX 158
LOGON_EXIT
MVS and CICS server
parameter 101
OpenVMS server parameter
134
UNIX CID Adapter Server
parameter 153
M maintaining a SQL Access
Server password 299
maintaining SQL Access
Servers 247
master process, Visual
Administration Tool 189
master utility 305
as an NT service 302
master_port_id parameter 344
max_block_count parameter
348
max_block_size parameter 348
max_clients parameter 345
MAX_DATAAREA, MVS and CICS
server parameter 102
MAX_DATALIST, MVS and CICS
server parameter 102
MAX_DATBAS_PDU, MVS and
CICS server parameter 102
max_lock_structures
parameter 342
max_ping_wait parameter 344
max_quick_size parameter 348
max_rcv_pdu 167
UNIX CID Adapter Client
parameter 179
MAX_RCV_PDU, MVS and CICS
server parameter 103
max_records_limit 168
UNIX CID Adapter Client
parameter 180
426
MAX_RECORDS_LIMIT
MVS and CICS server
parameter 103
OpenVMS server parameter
135
UNIX CID Adapter Server
parameter 154
maximum number of rows,
limitations 349
maxlength_error_log
parameter 329
maxtmp_pages parameter 331
media_failures_are_supported
parameter 338
memory space SQL Access
Server parameters 330
method broker
printing status 315
statusdb 315
modify system class 306
moving SQL Access Servers 285
MULTI
OpenVMS server parameter
135
UNIX CID Adapter Server
parameter 154
MultiNet Server, defining
TCP/IP 129
multiple_connection_shared_o
bjects parameter 347
MVS and CICS server
parameter
ALLOW_CORE_DUMP 99
BIND_SCHEMA 99
BYPASS_OPT_CTRL_LINKPAT
H 100
BYPASS_OPT_INDEX 100
BYPASS_QUAL 100
DATBASUPD_LOCK 101
DISPLAY_OPTIONS 101
LOGON_EXIT 101
MAX_DATAAREA 102
MAX_DATALIST 102
MAX_DATBAS_PDU 102
MAX_RCV_PDU 103
MAX_RECORDS_LIMIT 103
OPT_EXPLAIN 104
PDM_THREADS 104
Administration Guide, P25-9501-04
Index
PDM_USER_DATA 104
SEARCHUPD_LOCK 105
SELECTUPD_LOCK 105
SERVER_CONNECTIONS 105
SHARED_MEM 106
SHUTDOWN_PASSWORD 106
SHUTDOWN_USER 106
STATS 107
TCP_HOSTFILE 108
TCP_HOSTNAME_LOOKUP
107
TCP_LISTEN_PORT 108
TCP_PREFIX 109
TR_TOASCII 109
TR_TOEBCDIC 109
TRACE_OPTIONS 110
VSAM_FILE_LIST 110
N network port 88
network_pagesize parameter
344
network_service_name
parameter 343
new password 299
no prompt for DBA
user/password 294, 298
no specified options 301
no trace binary 183, 184, 185
NT Service, running master
utility 302
num_data_buffers parameter
330
num_log_buffers parameter
338
number of rows, limitations
349
O object_mode_character
parameter 351
oid_cache_max 168
UNIX CID Adapter Client
parameter 180
OpenVMS server component,
no trace binary 185
OpenVMS server init file,
coding rules 130
427
OpenVMS server parameter
ALLOW_CORE_DUMP 131
BIND_SCHEMA 132
BYPASS_OPT_CTRL_LINKPAT
H 133
BYPASS_OPT_INDEX 133
BYPASS_QUAL 133
DBMOD 134
DISPLAY_OPTIONS 134
LOGON_EXIT 134
MAX_RECORDS_LIMIT 135
MULTI 135
OPERATOR 135
OPT_EXPLAIN 136
PERFORMANCE_STATS 136
PREFIX 136
SHUTDOWN_PASSWORD 136
SHUTDOWN_USER 137
STATS 137
SYSTEM 137
TCP_HOSTNAME_LOOKUP
138
TCPIP_SUPPORT 138
TCPPORT 138
TRACE 139
OPERATOR, OpenVMS server
parameter 135
OPT_EXPLAIN
MVS and CICS server
parameter 104
OpenVMS server parameter
136
UNIX CID Adapter Server
parameter 155
optimization_level parameter
351
ORDB environment variable,
setting
HP-UX 143
ORDB server, starting and
stopping 18
ordbinit
defined 320
displaying parameters 325
summary of system
parameters 322
syntax rules for parameters
326
ordbmb, statusdb 315
override TCP/IP port 306
overwriting a SQL Access
Server
Administration Guide, P25-9501-04
Index
copydb 287
P page header check 297
parameter values
defining
for UNIX 171
displaying current 176
parameter values, defining
320
parameters
active_requests 345
auto_volext_factor 331
backup_buffer_size 334
backup_max_volume_size
334
charcode_check 356
checkpoint_interval_factor
335
class_representation_cache
330
commit_on_shutdown 353
connection_timeout 347
database-specific 176
deadlock_detection_interval
341
default_adapter_dir 355
event_handler 328
execute_queries_streaming
349
fbo_root 346
flush_data_buffer_factor
336
hot_fault_objects 348
hot_load_workspace 348
ignore_timezone 356
initial_workspace_table_size
349
isolation_level 341
keep_schema_locks 339
lock_escalation 339
lock_timeout_in_secs 339
lockf_enable 340
log_path 336
log_reserve_space 336
log_size 337
master_port_id 344
max_block_count 348
max_block_size 348
max_clients 345
max_lock_structures 342
428
max_ping_wait 344
max_quick_size 348
maxlength_error_log 329
maxtmp_pages 331
media_failures_are_supporte
d 338
multiple_connection_shared
_objects 347
network_pagesize 344
network_service_name 343
num_data_buffers 330
num_log_buffers 338
object_mode_character 351
OpenVMS server
initialization 130
optimization_level 351
query_cache_max_entries
351
query_cache_server_statistic
s 345
query_cache_statistics 353
query_cache_threshold 351
query_max_rows 349
query_oidset_threshold 352
query_stream_window 350
query_timeout 352
request_threads_to_start
343
select_star_includes_identit
y 352
server_inserts 349
socket_recv_timeout 344
sr_buffers 330
standalone 347
syntax rules 326
unfill_factor 332
unfill_index_factor 332
UNIX CID Adapter Server
initialization 149
unload_max_column 354
use_index_concurrency 342
volext_path 331
voltmp_path 331
warn_outofspace_factor 333
parameters, system 320
PDM database
alias 29
registering 29
PDM Directory 27
PDM indices 39
PDM_THREADS, MVS and CICS
server parameter 104
Administration Guide, P25-9501-04
Index
PDM_USER_DATA, MVS and
CICS server parameter 104
PERFORMANCE_STATS,
OpenVMS server
parameter 136
PREFIX
OpenVMS server parameter
136
UNIX CID Adapter Server
parameter 155
prefixed database, setting up
access 142
print master and server status
311
print SQL Access Master and
Server status 308
print_authorizations method
81
printing status 315
privileges 61
granting 63
revoking 66
prompt for remove password
300
PUBLIC group 60
PUBLIC user 62
PUBLIC user, renaming 74
Q query cache server
parameters 345
query services SQL Access
Client parameters 349
query specification
adding 46
changing 48
dropping 51
query, time limitations 352
query_cache_max_entries
parameter 351
query_cache_server_statistics
parameter 345
query_cache_statistics
parameter 353
query_cache_threshold
parameter 351
query_max_rows parameter
349
query_oidset_threshold
parameter 352
429
query_stream_window
parameter 350
query_timeout parameter 352
quiet 297, 306
quit commdb 311
quitting/disconnecting from
applications parameter
353
quitting/disconnecting from
applications SQL Access
Client parameters 353
R RDM functions and facilities 38
read_only 168
UNIX CID Adapter Client
parameter 180
read-only schema 306
recovery/logging SQL Access
Server parameters 333
recycle
CID Adapter Client 39
CID Adapter Server 39
REGISTER CID DATABASE
statement 40
reinitialize master 311
reinitialize SQL Access Master
308
release version, displaying 295
remove password 300
RENAME clause 47
renamedb utility
DBA password 294
DBA user 294
no prompt for DBA
user/password 294
overview 292
quiet 293
SQL Access Server files
pathname 293
SQL Access Server password
294
volume rename path file 293
renaming a SQL Access Server
292
request_threads_to_start
parameter 343
reserved keywords 57
resource sharing in CID
Adapter Client component
178
Administration Guide, P25-9501-04
Index
RLSE 84
ROLLBACK statement 83
rules for parameters 326
S schema_segment 169
schema_segment_address
UNIX CID Adapter Client
parameter 181
schema_segment_size 169
UNIX CID Adapter Client
parameter 181
schema_table_size, UNIX CID
Adapter Client parameter
181
SEARCHUPD_LOCK 84
SEARCHUPD_LOCK, MVS and
CICS server parameter 105
select_star_includes_identity
parameter 352
SELECTUPD_LOCK, MVS and
CICS server parameter 105
server component
startup procedure
OpenVMS 127
tailoring
UNIX 142
server file based objects SQL
Access Server parameters
346
server init file, coding rules
OpenVMS 130
server initialization
parameters
OpenVMS 130
SERVER_CONNECTIONS, MVS
and CICS server parameter
105
server_inserts parameter 349
servers
interactive options 311
master as an NT service 302
master utility 305
shutdown 19
utilities to start/shutdown
SQL Access Master 305
set_password method 81
setting parameter values
UNIX 171
setting up prefixed database
access 142
430
shared resources 178
SHARED_MEM, MVS and CICS
server parameter 106
SHLIB_PATH environment
variable 143
show transactions, SQL Access
Servers 187
shutdown
database server 311
master and servers 308
server 311
SQL Access Server 308
SHUTDOWN_PASSWORD
MVS and CICS server
parameter 106
OpenVMS server parameter
136
UNIX CID Adapter Server
parameter 155
SHUTDOWN_USER
MVS and CICS server
parameter 106
OpenVMS server parameter
137
UNIX CID Adapter Server
parameter 155
SHUTRAK 95
single phase commit 38
socket_recv_timeout
parameter 344
SQL Access Client parameters
commit_on_shutdown 353
connecting to SQL Access
Server 347
connection_timeout 347
execute_queries_streaming
349
hot_fault_objects 348
hot_load_workspace 348
initial_workspace_table_size
349
max_block_count 348
max_block_size 348
max_quick_size 348
multiple_connection_shared
_objects 347
object_mode_character 351
optimization_level 351
overview 347
query services 349
query_cache_max_entries
351
Administration Guide, P25-9501-04
Index
query_cache_statistics 353
query_cache_threshold 351
query_max_rows 349
query_oidset_threshold 352
query_stream_window 350
query_timeout 352
quitting/disconnecting from
applications 353
select_star_includes_identit
y 352
server_inserts 349
standalone 347
workspace memory 348
SQL Access for SUPRA Server
PDM
CID foreign Database
parameters 355
data validation parameters
356
flow diagram 12
ordbinit.txt file 320
servers. See servers.
SQL Access Client
parameters. See SQL
Access Client parameters.
SQL Access Server
parameters. See SQL
Access Server
parameters. 328
standalone parameters 327
system parameters 320, 322
utility parameters 354
SQL Access Master
reinitialize SQL Access
Master 308
SQL Access Master, printing
status 315
SQL Access Server
b-tree check 297
changing password 299
checking 296
class check 297
client/server mode 297, 299
copying 285
copying in quiet mode 287
current password 300
DBA password 294, 298, 300
DBA user 294, 297, 300
deleting 290
deleting after copying 287
431
directory pathname to copy
a new database 286
displaying transaction lock
information 213
displaying transactions 211
halt shutdown 308
heap page check 297
heap page check and b-tree
check 297
killing transactions 212
lock information 214
maintaining 247
modify system class 306
moving 285
new password 299
no prompt for DBA
user/password 294
no specified options 301
output redirection 291
override TCP/IP port 306
page header check 297
password 308
placing volumes in different
directories 287
printing status 315
prompt for remove password
300
quiet 297
read-only schema 306
remove password 300
renaming 292
setting the log file directory
path 286
shutdown SQL Access Server
308
specifying destination
password while copying
287
specifying destination SQL
Access Server password
288
specifying source password
while copying 287
specifying the path name to
create the destination
database 286
SQL Access Server files
pathname 293
SQL Access Server password
291, 294, 308
SQL Access Server utility 306
standalone mode 297, 299
Administration Guide, P25-9501-04
Index
starting 193
starting and stopping 187
starting on UNIX 18
starting on Windows 18
startup SQL Access Server
308
stopping 193
volume extensions directory
path 286
volume header check 297
volume path check 297
volume rename path file 293
SQL Access Server FBOs,
limitations 346
SQL Access Server parameters
active_requests 345
auto_volext_factor 331
backup_buffer_size 334
backup_max_volume_size
334
checkpoint_interval_factor
335
class_representation_cache
330
client/server requests 345
communication services 343
concurrency and locking 339
deadlock_detection_interval
341
disk storage 331
error messages 328
event_handler 328
fbo_root 346
flush_data_buffer_factor
336
isolation_level 341
keep_schema_locks 339
lock_escalation 339
lock_timeout_in_secs 339
lockf_enable 340
log_path 336
log_reserve_space 336
log_size 337
master_port_id 344
max_clients 345
max_lock_structures 342
max_ping_wait 344
maxlength_error_log 329
maxtmp_pages 331
media_failures_are_supporte
d 338
memory space 330
432
network_pagesize 344
network_service_name 343
num_data_buffers 330
num_log_buffers 338
overview 328
query cache 345
query_cache_server_statistic
s 345
recovery/logging 333
request_threads_to_start
343
server file based objects 346
socket_recv_timeout 344
sr_buffers 330
unfill_factor 332
unfill_index_factor 332
use_index_concurrency 342
volext_path 331
voltmp_path 331
warn_outofspace_factor 333
SQL Access Server utility 306
sr_buffers parameter 330
standalone mode 297
standalone mode 299
standalone parameter 347
start database server 311
start_server utility 19
startfdb 24
startfdb utility 22
starting a SQL Access Server
193
starting SQL Access Server 187
startup procedure, for
OpenVMS server
component 127
startup procedure, for UNIX
CID Adapter Server 148
startup script 88
statistics 85
statistics, enabling
OpenVMS 137
UNIX 156
STATS
MVS and CICS server
parameter 107
OpenVMS server parameter
137
UNIX CID Adapter Server
parameter 156
STATS=FUNCTION 85
STATS=LUW 85
STATS=SYSTEM 86
Administration Guide, P25-9501-04
Index
statusdb utility
method broker 315
options 315
stop_server utility 19
stopfdb 25
stopping
a SQL Access Server 193
SQL Access Server 187
sup1drvr.err file, location 177
sup1drvr.ini file 161
supported data types 58
supra1.bat 161
syntax rules for parameters
326
system parameters 320
summary 322
SYSTEM, OpenVMS server
parameter 137
T table_segment_size, UNIX CID
Adapter Client parameter
182
tailoring
client components 170
tailoring server components
142
TCP/IP
port number specification
175
TCP/IP, defining service
through MultiNet 129
TCP_HOSTFILE, MVS and CICS
server parameter 108
TCP_HOSTNAME_LOOKUP
MVS and CICS server
parameter 107
OpenVMS server parameter
138
UNIX CID Adapter Server
parameter 156
TCP_LISTEN_PORT
CID Adapter Client
consideration 175
TCP_LISTEN_PORT, MVS and
CICS server parameter 108
TCP_PREFIX, MVS and CICS
server parameter 109
TCPIP_SUPPORT, OpenVMS
server parameter 138
433
TCPPORT
OpenVMS server parameter
138
UNIX CID Adapter Server
parameter 157
TCPPORT CID Adapter system
parameter 88
terminate previous shutdown
request 311
time set on queries,
limitations 352
TR_TOASCII, MVS and CICS
server parameter 109
TR_TOEBCDIC, MVS and CICS
server parameter 109
trace 169
UNIX CID Adapter Client
parameter 182
TRACE
OpenVMS server parameter
139
UNIX 148
UNIX CID Adapter Server
parameter 157
TRACE_OPTIONS, MVS and
CICS server parameter 110
traceable binaries 183, 184,
185
transactions, killing 316, 317
translation tables, ASCII
EBCDIC 414
U unfill_factor parameter 332
unfill_index_factor parameter
332
UNIX CID Adapter Client
component
parameters, summary 173
UNIX CID Adapter Client
parameter
allow_core_dump 174
db_pdm_database-name 175
dbname 176
display_options 176
driver_directory 177
init_file 177
interproc_key 178
lang 178
load_path 179
max_rcv_pdu 179
Administration Guide, P25-9501-04
Index
max_records_limit 180
oid_cache_max 180
read_only 180
schema_segment_address
181
schema_segment_size 181
schema_table_size 181
table_segment_size 182
trace 182
UNIX CID Adapter Server
component, no trace
binary 184
UNIX CID Adapter Server init
file, coding rules 149
UNIX CID Adapter Server
parameter
ALLOW_CORE_DUMP 150
BIND_SCHEMA 151
BYPASS_OPT_CTRL_LINKPAT
H 152
BYPASS_OPT_INDEX 152
BYPASS_QUAL 152
DBMOD 153
DISPLAY_OPTIONS 153
LOGON_EXIT 153
MAX_RECORDS_LIMIT 154
MULTI 154
OPT_EXPLAIN 155
PREFIX 155
SHUTDOWN_PASSWORD 155
SHUTDOWN_USER 155
STATS 156
TCP_HOSTNAME_LOOKUP
156
TCPPORT 157
TRACE 157
unload_max_column
parameter 354
unloaddb utility
class names 283
hash filename 283
include references options
283
name of current user 283
output file prefix 283
password for current user
283
verbose output 283
use_index_concurrency
parameter 342
434
user 62
adding 69
deleting 73
user definition file 71
user logon exit
MVS 111
OpenVMS 140
UNIX 158
utilities
commdb 19, 307, 308, 311
copydb 285
deletedb 290
killtran 316, 317
master 305
master as an NT service 302
renamedb 292
SQL Access Server 306
start_server 19
statusdb 315
stop_server 19
utility parameters
overview 354
unload_max_column 354
V V1DRV_BASE 124
V1DRV_BURRYS 124
V1DRV_COMS 124
V1DRV_EXE 124
V1DRV_HELP 124
V1DRV_LOGS 124
V1DRV_PATCHES 124
verifying a SQL Access Server
296
view, defined 57
virtual class 57
Visual Administration tool
connecting to a database
host 189
displaying database
transaction 211
displaying SQL Access Server
lock information 214
displaying transaction lock
information 213
general information 187
killing database transactions
212
overview 187
requirements 187
starting 188
Administration Guide, P25-9501-04
Index
starting SQL Access Server
193
stopping SQL Access Server
193
Visual SQL
to create foreign tables 30
to create views 57
to edit a registration of a
CID foreign Database 42
to register a CID foreign
Database 29
volext_path parameter 331
voltmp_path parameter 331
volume header check 297
volume path check 297
VSAM_FILE_LIST, MVS and CICS
server parameter 110
W warn_outofspace_factor
parameter 333
Windows service, running
master utility 302
WITH GRANT OPTION 65
workspace memory SQL Access
Client parameters 348
435