risutil

(1)

for 32-Bit Applications

RIS Utilities Guide

August 1996

DNA111760

Version 5.4

(2)

Warranties and Liabilities

All warranties given by Intergraph Corporation about equipment or software are set forth in your purchase contract, and nothing stated in, or implied by, this document or its contents shall be considered or deemed a modification or amendment of such warranties.

The information and the software discussed in this document are subject to change without notice and should not be considered commitments by Intergraph Corporation. Intergraph Corporation assumes no responsibility for any error that may appear in this document.

The software discussed in this document is furnished under a license and may be used or copied only in accordance with the terms of this license.

No responsibility is assumed by Intergraph for the use or reliability of software on equipment that is not supplied by Intergraph or its affiliated companies.

Trademarks

InterAct, Intergraph, and RIS are registered trademarks of Intergraph Corporation. DIALOG, InterServe, and TD1 are trademarks of Intergraph Corporation. All other brands and product names are trademarks of their respective owners.

Copyright

Including software, file formats, and audiovisual displays; may be used pursuant to applicable software license agreement; contains confidential and proprietary information of Intergraph and/or third parties which is protected by copyright and trade secret law and may not be provided or otherwise made available without proper

authorization.

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of The Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c) (1) and (2) of Commercial Computer Software — Restricted Rights at 48 CFR 52.227-19, as applicable.

Unpublished — rights reserved under the copyright laws of the United States.

Intergraph Corporation

(3)

1. Before You Begin ... 1 - 3 1.1 Document Purpose ... 1 - 3 1.2 Audience ... 1 - 3 1.3 Document Prerequisites ... 1 - 3 1.4 Related Documentation ... 1 - 3 1.5 Additional Information ... 1 - 4 1.6 Document Conventions ... 1 - 4 1.7 Using On-line Help ... 1 - 6 1.7.1 Parts of the Help Window ... 1 - 6 2. Getting Started ... 2 - 3 2.1 Products Needed to Use the RIS Utilities ... 2 - 4 3. risbatch ... 3 - 3 4. risclnsr ... 4 - 3 5. risdcode ... 5 - 3 6. risdtype ... 6 - 3 7. risgui ... 7 - 3 7.1 Exiting the risgui Utility ... 7 - 4 7.2 Performing Queries in the risgui Utility ... 7 - 4 7.3 Options... ... 7 - 6 7.4 Utilities... ... 7 - 7 7.5 Restart ... 7 - 7 7.6 Set... ... 7 - 8 7.7 Show... ... 7 - 9 8. rislod ... 8 - 3 8.1 The Log File ... 8 - 8 8.2 The Bad File ... 8 - 9 8.3 Loading Index, View, and Privilege Definitions ... 8 - 10 8.4 Using rislod with the Interactive Interface ... 8 - 10 8.5 Using rislod with the Command Line Interface ... 8 - 17 8.6 BNF Representation of rislod Command Line Syntax ... 8 - 18

(6)

9. rismgr ... 9 - 3 9.1 RIS Schema Manager ... 9 - 5 9.2 Schema Definition ... 9 - 7 9.2.1 Displaying Schema Information ... 9 - 9 9.2.2 Creating Schemas ... 9 - 11 9.2.2.1 Creating Schemas (INFORMIX) ... 9 - 15 9.2.2.2 Creating Schemas (ORACLE) ... 9 - 17 9.2.2.3 Creating Schemas (DB2) ... 9 - 19 9.2.2.4 Creating Schemas (SYBASE) ... 9 - 22 9.2.2.5 Creating Schemas (Microsoft SQL Server) ... 9 - 24 9.2.3 Dropping Schemas ... 9 - 26 9.2.4 Granting/Revoking Access Privileges to Secure Schemas ... 9 - 28 9.2.5 Obtaining Dictionary Access ... 9 - 30 9.2.6 Modifying Schema Passwords ... 9 - 32 9.2.7 Modifying Node Information ... 9 - 33 9.2.8 Modify DB2 Password Form ... 9 - 35 9.3 Displaying Table, View, and Index Information ... 9 - 37 9.3.1 Displaying Table Information ... 9 - 39 9.3.2 Creating Tables ... 9 - 40 9.3.3 Dropping Tables ... 9 - 42 9.3.4 Appending Columns to Tables ... 9 - 43 9.3.5 Including Tables, Views, and Indexes ... 9 - 45 9.3.6 Excluding Tables, Views, and Indexes ... 9 - 47 9.4 Reviewing and Manipulating Schema Files ... 9 - 48 9.5 Locating RIS Client Processes ... 9 - 50 9.6 Setting Modes and Enabling Databases ... 9 - 52 10. risplbck ... 10 - 3 11. risrecrd ... 11 - 3 12. risunlod ... 12 - 3 12.1 Using risunlod with the Interactive Interface ... 12 - 7 12.2 Using risunlod With the Command Line Interface ... 12 - 13 12.3 BNF Representation of risunlod Command Line Syntax ... 12 - 16 Appendix A: Changes to This Version of RIS ... A - 3 A.1 RDBMS Versions ... A - 3 A.2 UNION and UNION ALL Supported ... A - 3 A.3 Objects of Different Owners Within a Schema ... A - 3 A.4 Object Aliases ... A - 4

(7)

A.6 Shared Dictionaries ... A - 6 A.7 Dictionary Objects ... A - 6 A.8 Dictionary Views ... A - 7 A.9 RIS_BLOB/RIS_TEXT ... A - 8 A.10 Interoperability ... A - 11 A.11 Upgrade Utility ... A - 12 A.12 Utilities ... A - 12 A.13 Parameters ... A - 13 A.14 Internationalization ... A - 13 Appendix B: File Formats for risunlod and rislod ... B - 3 B.1 Format for Representing Schema Definitions ... B - 5 B.2 Format for Representing Table Definitions ... B - 6 B.3 Format for Representing ‘‘Insert Into’’ Statements ... B - 6 B.4 Format for Representing Field Definitions ... B - 6 B.5 Format for Representing Table Data ... B - 8 B.6 Format for Representing Data File Specifications ... B - 9 B.7 Format for Representing Index, View, and Privilege Definitions ... B - 10 B.8 File Format for Data Files ... B - 10 B.9 Use of Spaces and New Line Characters ... B - 10 B.10 BNF Representation of File Formats ... B - 11 Glossary ... GL - 3 Index ... IN - 3

(8)

(9)

Before You Begin

(10)

(11)

__________________________________________________________________________________________________________________________________________________

1. Before You Begin

1.1 Document Purpose

The RIS Utilities Guide for 32-Bit Applications describes the RIS utilities.

1.2 Audience

This document was written for application users, application designers, and computer software specialists.

1.3 Document Prerequisites

This document assumes a basic understanding of your operating system, RDBMS software, and RIS.

1.4

1.5 Additional Information

For additional information about RIS, see the following files delivered with the RIS software. The default location for these files is the c:\Program Files\risdp directory.

README Provides product information and describes changes and additions to the product since the last release.

product.def Lists all dependencies and related parts for the product.

MANIFEST.TXT Lists all files delivered with the product.

1.6 Document Conventions

Filenames and directory paths appear in italic typeface. However, the italic typeface is also used for emphasis of new words or important phrases. For example:

c:\windows

Command names, menu names, tools, system prompts and messages, and keys may appear in boldface type. For example:

File menu

— OR — Press Enter

The word mouse refers to the 2-button or 3-button mouse.

The word select means to select a command by pressing the left mouse button over a menu command or by pressing the Alt key and the underlined character

simultaneously.

The word choose means to choose a button or icon by pressing the left mouse button over a Toolbar button, or application icon.

The word reset means to terminate a command initiated with the mouse. Reset by pressing the right mouse button.

The word identify means to define an area or place graphic elements in a graphics file. For PCs, identify with the left mouse button.

The phrase key in generally means to enter data into a field on a dialog box. To advance to the next field, use the Tab key.

(13)

System key-ins, keywords, and programming code segments, appear in monospaced type. For example:

main ( )

— OR —

commit

In actual usage, keywords can be in either upper or lowercase.

Words that appear in angle brackets, < >, are identifiers or names that you must supply, or dynamic information that can change for each error message. For example: ERROR: Error opening the file <filename>

Phrases in square brackets, [ ], are optional phrases.

Curly braces contain several options (used in conjunction with a logical OR symbol ( | ) or phrases that can be repeated (used in conjunction with [, ...]). A comma followed by a series of three periods in square brackets ([, ...]) indicates that the last phrase contained within curly braces ({}), or the last item, can be repeated numerous times (separated by commas).

For example: { <column> <data type> } [, ...] means that numerous column names and associated data types can be specified (separated by commas).

The logical or symbol ( | ) separates phrases or keywords within curly braces ({}) that can be used alone but not together.

For example: { user| database} means that either the userkeyword or the

databasekeyword can be specified, but not both. This symbol notes important information.

This symbol cautions about operations that can cause limited damage.

(14)

1.7 Using On-line Help

On-line Help is an on-line reference tool accessible at any time the application is in use. The on-line Help contains a description for each command and tool and step-by-step procedures for common tasks. For example, if you need to perform a certain task, search and display the topic. You can move or resize your application and Help windows so that they are next to each other. This lets you follow the procedures without having to search for the pages in the documentation.

(15)

1.7.1 Parts of the Help Window

To view the on-line Help, select Contents from the Help menu. To get more specific information, select one of the major topics or perform a search on a specific topic.

(16)

Use To

Contents Display a listing of the table of contents for the on-line Help file.

Search Locate information about a certain topic that you enter in the Search box.

Back Take you back to the previous Help topics you

have already viewed.

History Display a sequential list of every Help topic you have viewed during your current Windows session.

Find Display a dialog box used to retrieve partial or

full text strings in the help file. Use the Hints button for information on constructing your search query.

<< View the previous topic in a series of related topics. The button is dimmed when you reach the first topic in the series.

>> View the next topic in a series of related topics. The button is dimmed when you reach the last topic in the series.

If the graphics in the on-line Help appear distorted, check your graphics driver. If you are using an Intergraph TD1 machine, the S3 1024x768 256 color (Large Font) distorts the graphics slightly. Changing to the (Small Font) version corrects the display. If you are using other drivers, check with your PC manual for information about available graphics drivers.

(17)

Getting Started

(18)

(19)

__________________________________________________________________________________________________________________________________________________

2. Getting Started

The Intergraph Relational Interface System (RIS) is a generic interface to relational

database management systems (RDBMSs). RIS offers simultaneous connections to RDBMSs from many vendors on dissimilar hardware platforms using numerous protocols. RIS makes an entire network of databases available as if there were a single, local database.

During installation, the RIS utilities path is added to the system path environment variable. By default, the utilities are loaded in c:\Program Files\Common Files\Intergraph\ris05.nn\bin.

RIS Utilities:

1. RIS Batch – risbatch

Executes SQL statements in ASCII files. 2. RIS Clean Server – risclnsr

Cleans up some of the RIS dictionary tables. 3. RIS Decode – risdcode

Prints the error message for a RIS error code. 4. RIS Data Types – risdtype

Instructs RIS to interpret a column’s data type in a different manner. 5. RIS Interactive – risgui

Interactively query databases using RIS. 6. Configure RIS Version – risintop

Described in the RIS Installation Guide for 32-Bit Applications. 7. RIS Loader – rislod

Transfers data from specially formatted files into new or existing schemas. 8. RIS Playback – risplbck

Reads and executes files containing RIS commands generated by applications and captured with the risrecrd utility.

(20)

2 - 4 Getting Started

9. RIS Record – risrecrd

Records all SQL statements and timing data into specially formatted files. Useful for repeating long sequences when trying to uncover program problems.

10. RIS Unloader – risunlod

Extracts data from a schema and places it into specially formatted files. 11. Upgrade Utility – risupgrd

Converts a schema (dictionary and schema file) from RIS Version 4 to RIS Version 5.

2.1 Products Needed to Use the RIS Utilities

Refer to the RIS Installation Guide for 32-Bit Applications for information concerning products needed to use the RIS Utilities.

(21)

risbatch

(22)

(23)

__________________________________________________________________________________________________________________________________________________

3. risbatch

This utility is a simple, shell-callable program providing easy access to RIS and to underlying databases. The primary purpose of this utility is batch execution of SQL statements.

Any SQL statement can be specified in an input file, provided that you have the proper access.

All SQL statements must be terminated with a semicolon (;).

The RIS_PARAMETERS environment variable is used to specify the location of the

parms file.

Output is directed to stdout when the -o option is not used. To start the risbatch utility, do one of the following:

Type risbatchin a Command Prompt window.

(24)

3 - 4 risbatch

Usage

______

risbatch [-?] [-V] [-i <infile>] [-o <outfile>]

Flags

______

<none> If you do not specify any command-line arguments, or if you start the utility by selecting its icon from the Program Manager, the utility runs interactively and prompts for the necessary

information.

-? Display usage information and exit.

-V Display version information and exit.

-i <infile> Specify the input file containing the RIS SQL statements. The locate client command prompts for the client version.

-o <outfile> Specify the output file where output is stored.

Type helpat the risbatch prompt to get a list of available non-SQL commands.

Examples

_________

In this example, risbatch is invoked with the input file input.sql and the output file

output.sql:

risbatch -i input.sql -o output.sql

Files

_____

c:\Program Files\Common Files\Intergraph\ris05.nn\bin\risbatch c:\Program Files\Common Files\Intergraph\ris05.nn\parms

c:\Program Files\Common Files\Intergraph\ris05.nn\config\english\messages\ris.msg c:\Program Files\Common Files\Intergraph\ris05.nn\config\english\messages\net.msg c:\Program Files\Common Files\Intergraph\ris05.nn\config\english\messages\utl.msg Status Returns

______________

0 Normal termination.

(25)

risclnsr

(26)

(27)

__________________________________________________________________________________________________________________________________________________

4. risclnsr

This interactive utility deletes all nonessential records from the RIS dictionary tables. This utility is provided to clean up when the server process has not been able to do so. The server fails to clean up when it is killed or the machine is shutdown or rebooted.

Do not run this utility while the schemas to be cleaned are being accessed.

To start the risclnsr utility, do one of the following: Type risclnsrin a Command Prompt window.

Choose the RIS 05.nn icon from Program Manager; then choose the RIS Clean Server icon:

(28)

4 - 4 risclnsr

Choose the RIS 05.nn icon from the Program Manager; then choose the RIS Interactive icon. Choose the Utilities... button from the RIS Interactive form; then choose the RIS Clean Server... button from the Utilities form.

If you use another utility within RIS Interactive, you must choose the Restart button before RIS Interactive is aware of any RIS parameter changes, or creating or dropping of schemas.

Usage

______

risclnsr [-?] [-V] schema[.password] [user[.password]] [osuser[.password]]

The osuser[.password] option specifies the user and password for a secure schema. If the schema specified is a secure schema, risclnsr prompts for the osusername and osusername password (if one exists).

Flags

______

<none> If you do not specify any command-line arguments, or if you start the utility by selecting its icon from the Program Manager, the utility runs interactively and prompts for the necessary information.

Files

_____

c:\Program Files\Common Files\Intergraph\ris05.nn\bin\risclnsr

______________

(29)

risdcode

(30)

(31)

__________________________________________________________________________________________________________________________________________________

5. risdcode

This utility prints error messages for RIS error codes. To start the risdcode utility, do one of the following:

Type risdcodein a Command Prompt window.

(32)

5 - 4 risdcode

Choose the RIS 05.nn icon from the Program Manager; then choose the RIS Interactive icon. Choose the Utilities... button from the RIS Interactive form; then choose the RIS Decode... button from the Utilities form.

Usage

______

risdcode [-?] [-V] [<error code>]

Flags

______

<error code> Decimal, octal, or hexadecimal error code.

Examples

_________

To get the error message corresponding to an error code of 100, key in one of the following:

risdcode 100 (Using decimal.) risdcode Ox64 (Using hexadecimal.) risdcode 0144 (Using octal.) risdcode

(33)

Files

_____

c:\Program Files\Common Files\Intergraph\ris05.nn\bin\risdcode

______________

(34)

(35)

risdtype

(36)

(37)

__________________________________________________________________________________________________________________________________________________

6. risdtype

This interactive utility lets you instruct RIS to interpret the data type of a column differently and modify the size of a RIS_BLOB/RIS_TEXT data type.

The variety of data types in database systems permits multiple mappings of database data types to ANSI standard data types. When a schema is created, or a table is included in a schema, RIS chooses one interpretation of a data type. This utility lets you instruct RIS to interpret the data type of a column differently by prompting you for the schema name, username (for secure schemas), password (if one exists), table names, column names, and new data types.

The environment variable RIS_LANGUAGE specifies the language that RIS uses for parsing and error messages. The default is English. Consult the file c:\Program Files\Common

Files\Intergraph\ris05.nn\config\langs for other values.

To start the risdtype utility, do one of the following: Type risdtypein a Command Prompt window.

Choose the RIS 05.nn icon from Program Manager; then choose the RIS Data Types icon:

(38)

6 - 4 risdtype

Choose the RIS 05.nn icon from the Program Manager; then choose the RIS Interactive icon. Choose the Utilities... button from the RIS Interactive form; then choose the RIS Data Types... button from the Utilities form.

Example:

c:\risdtype

Enter schema (<CR> to exit):sch1

Enter a table or view name (or ? for a list of names): >blob_table

Pos Column Name type type-string len prec scale null —- —————— —- ———– —- —- ——

—-1 c1 15 ris_blob 0 null null YES

Do you wish to modify this column? <y(es), n(o), d(one with table)>>yes 0 UNSUPPORTED

1 CHARACTER 2 RIS_BLOB 6 RIS_TEXT

Choose a data type from those listed (enter the number) >>2 Current maximum ris_blob length is:0

Current maximum ris_blob length is:10000

Current status for nullable is YES, nulls are allowed Are null values allowed? <y(es), n(o)> >>yes

(39)

Pos Column Name type type-string len prec scale null —- —————— —- — ——– —- —- —— —- 1 c1 15 ris_blob 10000 null null YES

Is this correct? <y(es), n(o), q(uit)> >>yes

Usage

______

risdtype [-?] [-V]

Flags

______

Files

_____

c:\Program Files\Common Files\Intergraph\ris05.nn\bin\risdtype

______________

(40)

(41)

risgui

(42)

(43)

__________________________________________________________________________________________________________________________________________________

7. risgui

The risgui utility lets you interactively perform RIS queries. To start the risgui utility, do one of the following:

Type risguiin a Command Prompt window.

Choose the RIS 05.nn icon from Program Manager; then choose the RIS Interactive icon.

(44)

7 - 4 risgui

The RIS Interactive Utility form is displayed.

7.1 Exiting the risgui Utility

To exit the risgui utility, select the Cancel button.

7.2 Performing Queries in the risgui Utility

To perform a query in the risgui utility, follow these steps: 1. Select a default schema from the Default Schema field.

2. Key an SQL statement into the Query field. You must terminate the SQL statement with a semicolon character (;). The statement can wrap across several lines.

If you need to change the entry, select the Clear button to clear the Query field, then enter the statement again.

3. Select the Execute button. The results appear in the Results field.

If the query results do not completely fit in the Results field, the risgui utility can display a screenful at a time. For more information see the section Options.... Select the Continue button to display the next screenful, or the Abort button to stop the query.

(45)

To save the query results in a file, select the Save Results... button.

History File

When you execute a query, the risgui utility saves the SQL statement in the history file. To determine the name of the history file, the ris utility uses the file:

1. Specified by the RIS_HISTORY_FILE environment variable.

2. ris.his in the directory specified by the HOME environment variable, if the

RIS_HISTORY_FILE environment variable is not defined.

3. ris.his in the directory from which you started the risgui utility, if the HOME

environment variable is not defined.

When risgui saves a query in the history file, you can go back to the same query later and execute it again or edit the SQL statement to use it as the basis for a new query. Select the Previous or Next buttons to display the queries in the history file. Select the Search... button to perform a search in the history file.

1. Key a search term into the Search String field. 2. Select a search direction (Up or Down).

(46)

7 - 6 risgui

3. Select the Find Next button.

The risgui utility highlights the next match.

Saving and Loading Queries

To save the current query (shown in the Query field) to a file, select the Save... button. To load a previously-saved query, select the Open... button.

To save the results of the current query, select the Save Results... button.

7.3 Options...

The Options... button modifies the behavior of query results. 1. Select the Options... button.

2. To specify the behavior for query results that do not fit in the Results field, select one of the following:

— Fetch by screenful (Append) – fetch one screenful of results. When you select the Continue button, append the next screenful to the results.

— Fetch by screenful (Overwrite) – fetch one screenful of results. When you select the Continue button, discard the results and get the next screenful. — Fetch all rows – fetch all results without pausing.

3. Select the OK button to accept the settings or select the Cancel button to reject them.

(47)

7.4 Utilities...

The Utilities... button lets you start the other RIS utilities from within the risgui utility.

1. Select the Utilities... button.

In Windows 95, only RIS Manager... is available.

2. Select one of the following buttons to start a utility: — RIS Manager... – starts the rismgr utility. — RIS Loader... – starts the rislod utility. — RIS Unloader... – starts the risunlod utility. — RIS Record... – starts the risrecrd utility. — RIS Playback... – starts the risplbck utility. — RIS Clean Server... – starts the risclnsr utility. — RIS Data Types... – starts the risdtype utility. — RIS Decode... – starts the risdcode utility.

7.5 Restart

While you are running the RIS Interactive utility, you can run other RIS utilities; however, if you modify the RIS parameters with the other utilities, or create or drop a schema, the RIS Interactive utility is not aware of the changes.

Select the Restart button to restart risgui and make it aware of your changes. Your selection of modes, enabled databases, and default schema is not altered.

(48)

7 - 8 risgui

7.6 Set...

The Set... button sets RIS modes and enables the databases. 1. Select the Set... button.

2. Select the modes for the risgui utility: — ANSI Mode

— Verify Mode — Autocommit — Blank Strip Mode — Autorename

Refer to the RIS SQL User’s Guide for more information on the RIS modes. 3. Select the databases to enable:

— Informix — Ingres — Rdb — ORACLE — DB2 — SYBASE — MSSQL

(49)

7.7 Show...

The Show... button gives you additional information about RIS on your system. 1. Select the Show... button.

2. Select one of the following buttons:

Parameters... shows the settings in your parameters file.

(50)

7 - 10 risgui

(51)

rislod

(52)

(53)

__________________________________________________________________________________________________________________________________________________

8. rislod

You must understand the risunlod utility before using the rislod utility.

The rislod utility permits the transfer of schema information between external ASCII files and RIS schemas by loading schema information from external files into RIS schemas.

rislod:

Reads schema information from the main external file and data files (if any) and restores them in the form of RIS schemas.

Restores only user-requested schema information into RIS schemas.

Lets information about multiple schemas be stored in the same external main file. May create two files to report the loading status: the log file reports successful loading and the bad file reports unsuccessful loading.

The rislod and risunlod utilities are not designed for use as backup utilities. The following are some reasons for not using rislod and risunlod as backup utilities:

If a view was created in the database (not with RIS), RIS cannot unload the definition of the view.

If you drop a schema and then recreate the schema, and there were existing views, RIS cannot load the definition of the view because RIS lost the definition when you dropped the schema.

In certain cases data types are mapped slightly differently in ORACLE databases. ORACLE uses numeric data types, and RIS uses integer, smallint, real, and double. If you create a column of RIS data type real, it is mapped to a float(21) ORACLE data type. If you drop the schema, then recreate the schema, RIS maps the float(21) in ORACLE to a RIS double data type.

For these and further reasons, you should use the database’s utilities to back up data correctly.

The environment variable RIS_LANGUAGE specifies the language that RIS uses for parsing and error messages. The default is English. Consult the file c:\Program

(54)

8 - 4 rislod

The representation of information must comply with the format defined in the section File Formats for risunlod and rislod.

The following figure represents the functional mechanisms of rislod and shows the input requirements and output generated.

Data for ris_blob and ris_text columns cannot be loaded; however, you can have ris_blob and ris_text columns in a create tablestatement. To start the rislod utility, do one of the following:

Type rislodin a Command Prompt window.

Choose the RIS 05.nn icon from Program Manager; then choose the RIS Loader icon:

(55)

Choose the RIS 05.nn icon from the Program Manager; then choose the RIS Interactive icon. Choose the Utilities... button from the RIS Interactive form; then choose the RIS Loader... button from the Utilities form.

Usage

______

rislod [-?] [-V] [-n] [-p] [-e <db_list>]

[-m {w|a|e}] [-i <filename>] [-b <filename>] [-d <delimiter>] [-c <commit>] [-s <schemas>] [-f <filename>]

Flags

______

-n Set ANSI mode off. ANSI mode is on by default. Refer to the set modestatement in the RIS SQL User’s Guide for 32-Bit Applications for more information.

-p Preserve blanks. By default, rislod strips trailing blanks from character data. Refer to the set modestatement in the RIS SQL

User’s Guide for 32-Bit Applications for more information.

-e <db_list> Enable the database specified in the <db_list>. All databases are enabled by default. Refer to the set enable databasestatement in the RIS SQL User’s Guide for 32-Bit Applications for more information.

(56)

8 - 6 rislod

-m {w|a|e} Specify the file mode for output files. Thewoverwrites an existing file, theaappends to an existing file, and theereturns an error if an output file with the specified name exists.

-i <filename> Specify the main input ASCII file from which RIS schema information is loaded. The default main filename is ris.dmp.

-l <filename> Specify the log file into which RIS schema status information is recorded. The default log filename is ris.log.

-b <filename> Specify the bad file into which rejected RIS schema information is dumped. The default bad filename is ris.bad.

-d <delimiter> Specify the character for delimiting column values of character type while loading rows in a table. A single quotation mark (’) is the default delimiter character.

-c <commit> Specify the commit interval value that informs the loader to commit after inserting <commit> number of rows for a table. The default <commit> value is 25.

-s <schemas> Specify schema and schema-related information, such as tables, indexes, views, and grants. Alternatively, you can specify this information in a specification file.

-f <filename> Specify the name of the specification file for <schemas>. This option cannot be used with the-soption.

See the section Using rislod with the Command Line Interface for more detailed information.

Files

_____

c:\Program Files\Common Files\Intergraph\ris05.nn\bin\rislod c:\Program Files\Common Files\Intergraph\ris05.nn\parms

______________

1 Abnormal termination.

rislod loads user-requested RIS schema objects (items) from external ASCII files into

RIS schemas. rislod can: Load schema definitions Load table definitions Load table data

(57)

Load index definitions Load view definitions Load privilege definitions

Load multiples of above items in a single run

Load items of one schema into any other existing schema Load table definition only without table data

Load table data into existing table

Delete records from the table before loading table data from external file Load table data from separate data file

Commit table data insertion after specific interval

Overwrite or append the log and bad files or return error if files exist Enhanced features of rislod include the following:

Setting the ANSI mode on/off

The ANSI mode can be turned on or off, depending upon your requirements, before starting the loading execution.

Enabling specific databases

rislod lets you enable specific databases before starting the loading execution.

Loading of any other existing schema

rislod permits information about a particular schema to be loaded into another

existing schema using the rislod rename capability. You do not need to edit or correct the external main file to use this feature.

Returning error and/or delete table records before loading

You can specify that rislod report errors while loading data into a table, if the table already exists. You can also specify that rislod load data into existing tables or delete data from existing tables before loading.

Committing insertion at a specific interval

To improve execution performance, rislod commits table data insertions at specific intervals, rather than committing after each table insertion. By default, table data insertions are committed after 25 rows are inserted.

(58)

8 - 8 rislod

Not imposing the order of information stored in the main external file For an index, view, or privilege definition to be loaded successfully, all its references must exist. rislod does not impose a strict order on the information stored in the main file because it often postpones the loading of an index, view, or privilege until its references are loaded.

There are three ways to interact with rislod: using the Interactive Interface, the

Command Line Interface, or the Embedded Programming Function Interface.

1. Interactive Interface. When rislod is invoked without any command line

arguments, interactive prompts display. You are prompted for required inputs as the main external file is scanned.

See the section Using rislod with the Interactive Interface for more information about the meanings of these prompts and the corresponding actions taken by

rislod.

2. Command Line Interface. When rislod is invoked with arguments, the rislod

command line interface activates. This interface lets you specify, in a single command, the responses to various prompts that would have been generated if

rislod had been invoked interactively. Errors encountered during parsing are not

reported in the log or bad file, and rislod terminates abnormally. See the section Using rislod with the Command Line Interface for more information about the syntax for constructing a rislod command and the semantics of the command.

3. Embedded Programming Function Interface. The RIS_loader function provides

the functionality of rislod in an embedded program when you call the function and pass the appropriate structures. Refer to the RIS Programmer’s Guide for more information.

8.1 The Log File

When rislod begins execution, it creates a log file. The default log filename is ris.log. You can specify a different name for the log file. The log file can be opened in overwrite or append mode. If rislod cannot create a log file, execution terminates.

The log file contains a detailed summary of the execution with several sections:

Section . . . Contains . . .

Header File mode for the log and bad files Input main external filename Log filename

Bad filename

(59)

Schema Information Schema section, containing:

Schema name

Whether the schema loaded successfully or unsuccessfully

Renamed schema name (if selected)

Table section, containing:

Table name

Whether the table was created successfully or unsuccessfully

Number of rows loaded successfully Number of rows loaded unsuccessfully

Index section, containing:

Table name

Number of indexes loaded successfully for this table Number of indexes loaded unsuccessfully for this table

View section, containing:

View name

Whether the view loaded successfully or unsuccessfully

Grants Summary For each schema loaded:

Schema name and table or view name

Number of grants loaded successfully for this table or view

Number of grants loaded unsuccessfully for this table or view

Miscellaneous Date and time of the run Total elapsed time

8.2 The Bad File

As it executes, rislod creates a file called the bad file. The bad file contains all schema item definition statements that rislod attempted to load but could not. These

statements could be create schema, create table, insert, table field definition, create index, create view, or grantstatements. The default name for the bad file is ris.bad, but you can specify a different name for the file.

Statements that fail to load are dumped to the bad file with appropriate error codes and error messages. These error codes and messages are commented so the bad file can be used again, after it is edited or corrected, to load rejected schema information.

For example, if rislod cannot load a schema statement, then all the schema information pertaining to this schema is dumped to the bad file. Or, if the create table

statement fails, and data are to be loaded in this table, then all table data statements such as create table, insert, table field definition, and data statements are dumped to the bad file. The error messages are ignored by rislod.

(60)

8 - 10 rislod

Additionally, the status of each schema item being loaded is echoed to the screen in the interactive and command line interfaces.

The bad file can be opened in overwrite or append mode.

8.3 Loading Index, View, and Privilege Definitions

For an index to be loaded, the table it references must exist. Similarly, for a view to be successfully loaded, all the tables and views it references must exist. To successfully load a privilege definition (a grantstatement), the grantee, relation, and access privileges referenced in the statement must also exist. To take away the burden of organizing information into a proper order for loading, rislod postpones the loading of the index, view, or privilege definition until its references have been loaded.

When an index definition in a schema is fetched, rislod tries to load it. If rislod receives an error message from RIS stating that the table on which the index is created does not exist, the index definition is stored in a temporary file. After rislod has tried to load every statement in the schema once, it attempts to load the indexes from the temporary file again. The same thing happens to a view definition that could not be loaded the first time because its references did not exist. rislod continuously loads these views in the temporary file until all of them have been loaded or until no more views can be loaded successfully.

When rislod fetches a privilege definition in a schema, it is broken down into several

grantstatements, one for each grantee specified. rislod tries to load each of the new

grantstatements. If RIS notifies rislod that the statement could not be loaded, the grant statement is stored in a temporary file along with the information about the schema to which it belongs. After rislod tries to load every statement in the files at least once, rislod tries to load the grant statements in the temporary file again. rislod continuously loads these grant statements until either all of them have been loaded or no more grant statements can be loaded successfully. In this approach you may notice the breakdown of a grant statement and notice that some of the grant statements are loaded at the end of a rislod session.

8.4 Using rislod with the Interactive Interface

Invoking rislod without any command line arguments displays interactive prompts.

Accepting Default Values. Most prompts have default values indicated in square

brackets ([]). Press the ENTER key to select these default values.

Selecting Nondefault Values. To select a nondefault value choose the character in

parentheses corresponding to the option you want. Key in that character and press ENTER.

Specifying Other Information. Some prompts ask you to enter information, such as

(61)

The following list discusses the interactive prompts in detail. 1. Set mode ansi ON(y/n) :[y] >

The default is set ANSI mode on. See the RIS SQL User’s Guide for 32-Bit

Applications for more information.

Do one of the following:

Press ENTER to accept the default. Selectnto turn off ANSI mode. 2. Preserve blanks? (y/n) :[n] >

This prompt lets you set the blankstrip mode. By default rislod strips trailing blanks from character data.

Press ENTER to accept the default if you do not want to preserve trailing blanks.

Selectyif you want to preserve trailing blanks. 3. Set mode enable databases?

all(a) specific(s) :[a] >

This prompt lets you enable databases during the loading of a schema. Do one of the following:

Press ENTER to enable all RIS-supported databases. Selectsand rislod prompts you for a database type:

Enter DBMS type (ex. informix) :[return] >

Enter the RIS-supported database type, such as informix, ingres, or

oracle. This prompt repeats until you press ENTER without entering a database name.

4. File mode of all output files? overwrite(w) append(a) error out if exists(e) :[e] >

This prompt lets you set the file mode for log and bad files. The file mode affects the log and bad files only. The default ise, error outmode.

Press ENTER to accept the default; when you are prompted for the log and bad filenames, rislod prompts you to quit if the files you specify already exist.

(62)

8 - 12 rislod

Selectwto overwrite the existing log and bad files. Selectato append to the existing log and bad files. 5. Main file for loading :[ris.dmp] >

This prompt lets you specify the name of the main file for loading. The default name for the main file is ris.dmp.

Press ENTER to accept the default filename. Enter another filename for the main file. 6. Log file :[ris.log] >

This prompt lets you specify the name of the log file for loading. The default name for the log file is ris.log.

Press ENTER to accept the default filename. Enter another filename for the log file.

If you selectedefor error outmode at the promptFile mode of all output files?, and a file with the name you specify exists, the messageLog File already existsis displayed. You are prompted:

Quit risload? (y/n):[n] >

Press ENTER to accept the default. You are again prompted to enter a name for the log file; key in a new filename.

Selectyto quit rislod. 7. Bad file :[ris.bad] >

This prompt lets you specify the name of the bad file for loading. The default name for the bad file is ris.bad.

Press ENTER to accept the default filename. Enter another filename for the bad file.

(63)

If you selectedefor error outmode at the promptFile mode of all output files?, and a file with the name you specify exists, the messageBad File already existsis displayed. You are prompted:

Quit risload? (y/n):[n] >

Press ENTER to accept the default. You are again prompted to enter a name for the bad file; key in a new filename.

Selectyto quit rislod.

8. Enter delimitation used in the files for loading: [’] >

This prompt lets you specify the delimiter to use for enclosing character values of variable lengths to use in the main and data files.

You cannot use the space character as a delimiter.

The files generated by risunlod use single quotation marks (’) for delimitation. This feature of rislod lets you use files not prepared by

risunlod for loading as long as the other parts of the files comply

with the file format used by rislod. Do one of the following:

Press ENTER to accept the default. Enter another delimitation character. 9. Enter commit interval :[25] >

The commit interval lets you commit the insertion of rows in a table after the specified commit interval value. The default is 25 (commit after inserting 25 rows in a table).

Press ENTER to accept the default. Enter another commit interval. 10. Which schemas should be loaded?

all(a)

prompted - optionally transfer into existing schema(p) :[a] >

This prompt lets you choose between loading all the schemas or only selected schemas from the main file. The default isafor all schemas.

(64)

8 - 14 rislod

Press ENTER to load all the schemas from the main file.

Prompts let you choose how to load tables, indexes, views, and privilege definitions. These prompts appear once, after the prompt for the schema, if you choose to load all the schemas in the main file.

Selectpand rislod generates a list of schemas and prompts you before loading each schema. (After each schema is selected, you are prompted for how to load tables, indexes, views, and privilege definitions for that schema.)

Load schema <schname>(y/n) :[y] >

— Selectyto load the specified schema. If you selectpat the promptWhich schemas should be loaded?and you selectyat this prompt, you are prompted to optionally load into another existing schema:

To Transfer <schema>’s items into another existing schema... Enter an existing schema name :[<return>]

– Press ENTER if you do not want to use another existing schema;

rislod loads the schema into the schema name specified in the main

file.

– Enter the name of an existing schema. rislod then prompts for the username, user password, and schema password, if necessary, for the specified schema.

— Selectnif you do not want to load the specified schema.

rislod lets you rename schemas only if the prompted(p)selection was made at theWhich schemas should be loaded?prompt.

If the schema is a secure schema, you are prompted for the database username, the database username password, the operating system username, and the operating system username password. If the schema has a password, you are prompted for the schema password. Passwords are not echoed to the screen.

11. Which tables should be loaded? all(a) prompted(p) none(n) :[a] >

(65)

Press ENTER to accept the default and load all the tables in the schema. Selectpif you want to be prompted for each table.

Selectnif you do not want to load any tables.

If you selectaorpat the promptWhich tables should be loaded?the following prompt appears next:

Both definitions and data(b) definitions only(o):[b] >

This prompt lets you decide whether to load both the definitions and data of the tables in the schema or load only the definitions.

Press ENTER to accept the default and load both table definitions and data. Selectoto load table definitions only.

rislod loads either fixed or variable formatted table data.

If only the definitions exist for some or all of the tables in a schema, choosing to load both definitions and data does not cause any problem to rislod. These tables are created without data in them. Similarly, if both the definitions and data exist for some or all of the tables in a schema, choosing the second selection does not cause problems. These table data are

discarded and the string only definitions is placed in the log file.

Selectnif you do not want to load any tables.

If you selectbat the promptBoth definitions and data(b) definitions only(o)the following prompt appears:

Continue loading into a table even though that table exists (y/n):[n] >

When loading a table definition of a table that already exists, an error message is generated stating that a table/view with this name already exists. Whether or not the data is loaded into the existing table depends on the answer to this prompt.

— Press ENTER to accept the default and data are not loaded into an existing table.

(66)

8 - 16 rislod

Ifyis selected for the previous prompt, the following prompt is displayed:

Clear existing data from table before loading(y/n) :[n] >

– Press ENTER to accept the default and keep existing data.

– Selectyto delete all rows from this table before loading data from the

main file.

12. Which index definitions should be loaded? all(a) prompted(p) none(n): [a] >

Press ENTER to accept the default and load all index definitions.

Selectpand rislod generates a list of indexes and prompts for each index definition:

Load definition <definition>(y/n):[y] >

— Press ENTER to load the specified definition.

— Selectnif you do not want to load the index definition. Selectnand no index definitions are loaded.

13. Which views should be loaded? all(a) prompted(p) none(n):[a] >

Press ENTER to accept the default and load all views. Selectpand rislod prompts for each view:

Load view <view>(y/n):[y]:

— Press ENTER to load the specified view. — Selectnand the specified view is not loaded. Selectnand no views are loaded.

(67)

14. Which privilege definitions should be loaded? all(a) prompted(p) none(n):[a] >

Press ENTER to accept the default and load all privilege definitions. Selectpand rislod prompts for each table or view on which one or more privileges are defined:

Load access privilege on <relation>(y/n):[y]

— Press ENTER to load the specified privilege definition. — Selectnif you do not want to load the privilege definition. Selectnand no privilege definitions are loaded.

If you selectedpat the promptWhich table should be loaded?the following prompt is displayed.

Load table <table>(y/n):[y]

Press ENTER to accept the default and load the specified table. Selectnand the specified table is not loaded.

When all the necessary information has been specified, rislod processes the schema(s) selected.

8.5 Using rislod with the Command Line Interface

The command line can be used to specify which schemas in the main file should be loaded. It can also be used to specify which information in the schemas should be loaded. The syntax for constructing a rislod command is almost the same as the syntax for constructing a risunlod command, except for a few additions and changes.

Examples

rislod -i \dir1\dir2\mainfile -d\" -l load.log -b load.bad -f ..\dir3\specfile -n -mw -e rdb informix -c 15

(68)

8 - 18 rislod

-i Main filename. The default is ris.dmp.

-d Delimiter. The default is a single quotation mark (’). The delimiter in this example is a double quotation mark. The backslash before the delimiter causes the shell not to interpret the double quotation mark.

-l Log filename. The default is ris.log.

-b Bad filename. The default is ris.bad.The delimiter in this example is a

double quotation mark. The back slash before the delimiter causes the shell not to interpret the double quotation mark.

Additional options not used in the example are:

Option Specifies

-n ANSI mode off.

-e Enable databases listed after this option.

-m Set the file mode (w, a, or e) for the output files (such as log and bad files).

-c Commit interval.

rislod -s sch1.create_sch_passwd1.user_passwd1 all

-s sch2 .create_sch_passwd2 .user_passwd2 new table with data all -s sch3 clear table with data t1 t2 grant all

-s sch4 rename sch5 .sch5pass table t1 index t2 view v1 grant t2 v2 sch.t3 sch.v3

rislod lets you specify up to three passwords after a schema name (schema password,

osuser password, and user password). Passwords are necessary if they are not already stored in the main file. For schema sch2, data is loaded only into newly created tables. For schema sch3, data is loaded into tables t1 and t2 after deleting previously inserted rows even if it already exists before loading. For schema sch4 all the following items are loaded into existing schema sch5. No data is loaded into table t1, but index definitions on table t1 and privilege definitions on table t1 and view view1 are loaded. The specification file format is the same for both rislod and risunlod.

8.6 BNF Representation of rislod Command Line Syntax

Backus Naur form (BNF) is a method of describing the syntax of a language. It is used here to show the capabilities of the RIS command line interface.

(69)

<command_line> ::= rislod [-n] [-e <database_list>] [-m <file_mode>] [-i <input_file>] [-b <bad_file] [-l <log_file>] [-d <delimiter>] [-c <commit_interval>] { { -s <schema> [.<create_sch_passwd>] [<os_name>[<user_name>]] [.<os_passwd>] [.<user_passwd>] [rename <new_schema> [.<new_sch_passwd>] [user <user_name>[.<user_pwd>]]] [<info_tobe_load>] } [...] | -f <spec_file> } <database_list> ::= {<database> [...]} <file_mode> ::= w | a | e

w represents overwrite file mode a represents append file mode e represents return error <info_tobe_load> ::= all | { [ { table

| [{new | clear}] table with data } <table_tobe_load> ] [view <view_tobe_load>] [index <index_tobe_load>] [grant <grant_tobe_load>] }

<table_tobe_load> ::= all | {<table>[ ...]} <view_tobe_load> ::= all | {<view>[ ...]} <index_tobe_load> ::= all | {<table>[ ...]} <grant_tobe_load> ::= all | { { [<schema>.]<table>|[<schema>.]<view> } [ ...] }

(70)

8 - 20 rislod

The following is the BNF representation of the format for a specification file.

<spec_file_format> ::= {<schema> [.<create_sch_passwd>] [.<user_passwd>] <info_tobe_load>}[;<new_line>...]

(71)

rismgr

(72)

(73)

__________________________________________________________________________________________________________________________________________________

9. rismgr

This utility creates, changes, and drops RIS schemas. You can also use it to display information about existing schemas.

To start the rismgr utility, do one of the following: Type rismgrin a Command Prompt window.

Choose the RIS 05.nn icon from Program Manager; then choose the RIS Schema Manager icon:

(74)

9 - 4 rismgr

Choose the RIS 05.nn icon from the Program Manager; then choose the RIS Interactive icon. Choose the Utilities... button from the RIS Interactive form; then choose the RIS Manager... button from the Utilities form.

Usage

______

rismgr

Files

_____

c:\Program Files\Common Files\Intergraph\ris05.nn\bin\rismgr

c:\Program Files\Common Files\Intergraph\ris05.nn\config\english\forms\v5forms\* c:\Program Files\Common Files\Intergraph\ris05.nn\parms

______________

(75)

__________________________________________________________________________________________________________________________________________________

9.1 RIS Schema Manager

The RIS Schema Manager dialog box displays a three-column list showing all the schemas known to RIS, each schema type (standard or secure), and whether the schema’s associated dictionary is owned or shared. Buttons corresponding to the actions of the Schema Manager are also on the dialog box. When you choose a button, you initiate that particular action, and the associated subordinate dialog box is displayed. When you choose one of the schemas from the list on the RIS Schema Manager dialog box, information about that schema is displayed on the subordinate dialog box.

Operating Sequence

1. Activate the RIS Schema Manager.

(76)

9 - 6 rismgr

2. Choose the button from the RIS Schema Manager dialog box for the function you want to use. The RIS Schema Manager functions are described briefly in the following list. See the section listed for a complete description.

Button Name Function

Schema Definition Provides additional functions and dialog boxes for defining schemas. See the section Schema Definition. Data Definition Provides additional functions and dialog boxes that

manipulate tables, views, and indexes. See the section

Displaying Table, View, and Index Information.

Schema File Lets you review and manipulate schema files. See the section Reviewing and Manipulating Schema Files. Locate Client Lets you review and specify the location of a RIS client

process. See the section Locating RIS Client Processes.

Set Lets you set ANSI, autocommit, autorename, blankstrip,

and verify modes on or off and enable different

databases. See the section Setting Modes and Enabling

Databases.

3. Do one of the following:

Choose the Reset button to erase the subordinate dialog boxes.

The RIS Schema Manager rereads the RIS schemas file.

Choose the Close button to end the RIS Schema Manager session. Choose the Help button to obtain RIS Schema Manager help.

(77)

__________________________________________________________________________________________________________________________________________________

9.2 Schema Definition

The Schema Definition dialog box lets you initiate functions to display schema information, create and drop schemas, access secure schemas and dictionaries, and modify schema passwords, node information, and DB2 passwords.

Operating Sequence

1. Choose the Schema Definition button from the RIS Schema Manager dialog box.

The Schema Definition dialog box appears.

The dialog box has eight buttons, each letting you initiate a particular function. 2. Do one of the following:

Choose the button from the Schema Definition dialog box for the function you want to use. The Schema Definition functions are described briefly in the following list. See the section listed for a complete description.

Button Name Function

Schema Information Displays information about a specified schema. See the section Displaying Schema Information.

Create Schema Creates schemas. See the section Creating

Schemas.

Drop Schema Drops schemas. See the section Dropping

(78)

9 - 8 rismgr

Secure Schema Access Grants and revokes access to a secure schema. See the section Granting/Revoking Access

Privileges to Secure Schemas.

Dictionary Access Grants and revokes dictionary access to a schema. See the section Obtaining Dictionary

Access.

Modify Schema Password Modifies the schema password. See the section

Modifying Schema Passwords.

Modify Node Information Modifies node information. See the section

Modifying Node Information.

Modify DB2 Password Modifies the DB2 password. See the section

Modify DB2 Password Form.

Choose the Reset button to dismiss the subordinate dialog boxes. Choose the Close button to dismiss the Schema Definition dialog box. Choose the Help button to obtain RIS Schema Definition help.

(79)

__________________________________________________________________________________________________________________________________________________

9.2.1 Displaying Schema Information

The Schema Information dialog box displays information about a specified schema. You can key in a schema name or select a name from the Schema Name list on the RIS Schema Manager dialog box.

Operating Sequence

1. Choose the Schema Information button from the Schema Definition dialog box.

The Schema Information dialog box appears and displays information about the selected schema (if one has been selected from the RIS Schema Manager dialog box).

2. Do one of the following if the schema you want is not already the selected schema: In the Schema Name box, type a schema name.

Select a schema from the Schema Name list on the RIS Schema Manager dialog box.

The schema information is displayed.

The following information is displayed:

risutil

for 32-Bit Applications

RIS Utilities Guide

August 1996

DNA111760

Table of Contents

Table of Contents

Before You Begin

1.

Before You Begin

1.1

Document Purpose

1.2

Audience

1.3

Document Prerequisites

1.4

Related Documentation

1.5

Additional Information

1.6

Document Conventions

1.7

Using On-line Help

1.7.1

Parts of the Help Window

Getting Started

2.

Getting Started

2.1

Products Needed to Use the RIS Utilities

risbatch

3.

risbatch

risclnsr

4.

risclnsr

risdcode

5.

risdcode

risdtype

6.

risdtype

risgui

7.

risgui

7.1

Exiting the risgui Utility

7.2

Performing Queries in the risgui Utility

History File

Saving and Loading Queries

7.3

Options...

7.4

Utilities...

7.5

Restart

7.6

Set...

7.7

Show...

rislod

8.

rislod

8.1

The Log File

8.2

The Bad File

8.3

Loading Index, View, and Privilege Definitions

8.4

Using rislod with the Interactive Interface

8.5

Using rislod with the Command Line Interface

Examples

8.6

BNF Representation of rislod Command Line Syntax

rismgr

9.