A Using NAV_UTIL Utility

Oracle Connect for IMS, VSAM, and Adabas Gateways includes the NAV_UTIL utility. It is a command-line console that enables executing a collection of commands including troubleshooting and metadata utilities.

This section explains how to run the NAV_UTIL utility and describes the available commands. It contains the following topics:

Running NAV_UTIL

This section contains information on the following topics:

Activating NAV_UTIL

Perform the following procedure to activate NAV_UTIL on z/OS platforms.

  1. Run the following command: NAVROOT.USERLIB(navcmD)

    Where NAVROOT is the high-level qualifier where Oracle Connect for IMS, VSAM, and Adabas Gateways is installed.

  2. At the prompt, enter:

    [<options>] <command_name> [<command_params>]

    Where:

    • <options>: One of the values listed in Table A-1.

      Table A-1 NAV_UTIL Options

      Option Description

      -p<password>

      The master password specified for the user profile with the name specified in the -u parameter (or the default NAV user profile if the -u option is not specified). If a master password has been set, use of NAV_UTIL requires this password.

      -u<name>

      The name of a user profile to be used other than the default (NAV).

      -b<binding_name>

      A binding setting other than the default (NAV) binding configuration.

      -command

      Runs the utility from a shell environment.

      -db

      Runs the utility on an Oracle Connect for IMS, VSAM, and Adabas Gateways virtual database.

    • <command_name>: The name of the command you want to execute.

    • <command_params>: Command-specific parameters. If you do not supply the command parameters, you are prompted for them.

Basic NAV_UTIL Syntax

The syntax used herein reflects the way in which the command line utility is also written. To this end, bear in mind the meaning of the following symbols:

  • Plain text: an absence of symbols signifies a keyword, which must be entered as it appears.

  • <>: parameters inside angular brackets need to be entered in context. For example <data_source> must be replaced with the appropriate data source on which you wish to conduct the transaction at hand.

  • []: parameters inside square brackets are optional. Note that you can have a combination of angular and square brackets, signifying an optional parameter that, if entered, must be in context, such as [<data_source>].

  • |: signifies 'or'. For example <bindings | datasource | remote_machine> signifies any one of the parameters inside the angular brackets.

ADD_ADMIN

The ADD_ADMIN command enables you to specify which users can manage the machine where this command is run, from within Oracle Connect for IMS, VSAM, and Adabas Gateways.

Perform the following procedure to run the ADD_ADMIN command on z/OS platforms.

  • At the prompt, enter:

    add_admin <admin_username> | *

    Where:

    • admin_username: The name of a valid user who can administer the current machine from within Oracle Studio for IMS, VSAM, and Adabas Gateways.

    • *: All users can administer the current machine from within Oracle Studio for IMS, VSAM, and Adabas Gateways.

      Note:

      The user specified can be changed from within Oracle Studio for IMS, VSAM, and Adabas Gateways.

CHECK

The CHECK command checks various facets of the client/server system. The following parameters can be checked:

check irpcd

This checks whether an Oracle Connect for IMS, VSAM, and Adabas Gateways daemon is running. Perform the following procedure to run the CHECK IRPCD command on z/OS platforms.

  • At the prompt, enter:

    CHECK IRPCD (daemon_location [, username, password])

check network [port]

This lists the machines that have an active daemon. You can list all machines or specific machines, based on a specified port number. Perform the following procedure to run the CHECK NETWORK command on z/OS platforms.

  • At the prompt, enter:

    CHECK NETWORK (<port>)

check irpcdstat

This checks the status of a daemon for all workspaces, including active server processes (both those connected to a client and those that are available), the name and location of the log file, and the IRPCD configurations. Use this option to identify server processes that need terminating. You can also check the status of a specific daemon workspace.

Perform the following procedure to run the CHECK IRPCDSTAT command on z/OS platforms.

  • At the prompt, enter:

    CHECK IRPCDSTAT(<daemon_location>, <workspace> [,<username>, <password>])

check tcpip

This checks the basic TCP/IP configuration on the machine (as far as Oracle Connect for IMS, VSAM, and Adabas Gateways can check it).

check server

This checks whether a client can access a specific workspace and checks the details of the workspace configuration. Perform the following procedure to run the CHECK SERVER command on z/OS platforms.

  • At the prompt, enter:

    CHECK SERVER(<daemon_location>, <workspace> [,<username>, <password>])

check license

This checks the license details. You can also check the license details for a specific remote machine.

check datasource

This tests the connection to a specific data source, defined in the default local binding configuration. Perform the following procedure to run the CHECK DATASOURCE command on z/OS platforms.

  • At the prompt, enter:

    CHECK DATASOURCE(<ds_name>[,<connect_info>])

DELETE

DELETE is used to remove the following objects from the repository:

  • Binding

  • User Profile

  • Daemon

There is a separate syntax for Deleting Data Source Objects. Perform the following procedure to run the DELETE command on z/OS platforms.

  • At the prompt, enter:

    [<options>] delete <obj_type> <obj_name>

    Where:

    • options: See Table A-1, "NAV_UTIL Options" for details.

    • obj_type: The type of object to be deleted. You can specify any of the following:

      binding: A particular set of binding information.

      daemon: Daemon general configuration settings.

      datasources: The data sources specified in a binding.

      env[ironment]: Environment properties for a particular binding.

      remote_machines: Remote machines defined in the binding.

      user: A user profile definition.

    • obj_name: The name of the specific object (of the type specified in the obj_type parameter) to be deleted. Use the following table to determine the obj_name to supply, dependent on the value of obj_type:

      binding, datasources, remote_machines, and environment: The name of the binding in which these objects are defined.

      daemon: The daemon name.

      user: The user name that identifies the user profile.

Deleting Data Source Objects

You can delete from the repository the information about the following for a given data source:

  • Tables that rely on ADD metadata

  • ADD metadata for a table generated by the LOCAL_COPY command

  • Stored procedures that rely on ADD metadata

  • ADD metadata for a stored procedure generated by the LOCAL_COPY command

  • Views

  • Synonyms

Perform the following procedure to delete data source objects on z/OS platforms.

  • At the prompt, enter:

    [<options>] delete <obj_type> <ds_name> <obj_name>

    Where:

    • options: See Table A-1, "NAV_UTIL Options" for details.

    • obj_type: The type of object to be deleted. You can specify any of the following:

      table: Deletes the information for the specified table.

      local_table: Deletes a local copy of a table.

      procedure: Deletes an Oracle Connect for IMS, VSAM, and Adabas Gateways procedure.

      local_procedure: Deletes a local copy of a stored procedure.

      view: Deletes an Oracle Connect for IMS, VSAM, and Adabas Gateways view.

      synonym: Deletes an Oracle Connect for IMS, VSAM, and Adabas Gateways synonym.

    • ds_name: The name of the data source, as specified in the binding configuration, for the data source object that is deleted.

    • obj_name: The name of the specific object (of the type specified in the obj_type parameter) to be deleted. Use the following table to determine the obj_name to supply, dependent on the value of obj_type:

      table: The name of the table to be deleted or * to delete all the tables for the specified ds_name.

      local_table: The name of a local copy of a table to be deleted or * to delete all the local copy tables for the specified ds_name.

      procedure: The name of an Oracle Connect for IMS, VSAM, and Adabas Gateways procedure for the specified ds_name.

      local_procedure: The name of a local copy of a procedure to be deleted or * to delete all the local copy procedures for the specified ds_name.

      view: The name of the view to be deleted or * to delete all the views for the specified ds_name.

      synonym: The name of the synonym to be deleted or * to delete all the synonyms for the specified ds_name.

EDIT

The EDIT command enables you to modify the contents of a repository. You can directly edit the following types of repository objects:

  • All configuration information for a particular machine, including all the other elements listed ahead.

  • User profile definitions

  • The list of available bindings

  • Information for a particular binding, which can include information about the following:

    • Data sources

    • Remote machines

    • Environment settings

  • Information about the available daemons

  • Information about the following for a particular data source:

    • Tables that rely on ADD metadata

    • ADD metadata for a table generated by the LOCAL_COPY command

    • Stored procedures that rely on ADD metadata

    • ADD metadata for a stored procedure generated by the LOCAL_COPY command

    • Views

    • Synonyms

The object is exported to an XML file that is automatically displayed in a text editor. When the text editor is closed, the XML file is saved back to the repository. However, you cannot delete a repository entry by deleting it from the text editor through this command. To delete a repository entry, use the DELETE command.

The text editor used is the native text editor for the operating system. You can change the editor in the miscellaneous environment settings, either using Oracle Studio for IMS, VSAM, and Adabas Gateways or running a command.

Perform the following procedure to run the EDIT command on z/OS platforms.

  • At the prompt, enter:

    navedit obj_type [<ds_name> [-native]] <obj_name>

    Where:

    • options: See Table A-1, "NAV_UTIL Options" for details.

    • obj_type: The type of object to be edited. You can specify the following types of objects:

      bindings: All available bindings and their environments.

      binding: A particular set of binding information.

      daemon: Daemon general configuration settings.

      daemons: Daemon general configuration settings of all daemons.

      datasources: The data sources specified in a binding.

      remote_machines: Remote machines defined in the binding.

      env[ironment]: Environment properties for a particular binding.

      table: Table definitions that rely on ADD metadata per data source.

      local_procedure: ADD metadata for a stored procedure generated by the LOCAL_COPY command.

      local_table: ADD metadata for a table generated by the LOCAL_COPY command.

      machine: All configuration information for a particular machine.

      procedure: Stored procedure definitions that rely on ADD metadata.

      synonym: Synonyms definitions per data source.

      user: A user profile definition.

      users: All user profile definitions.

    • ds_name: The name of data source for the object to be edited, as specified in the binding configuration, when the obj_type is any of: table, local_table, view, procedure, local_procedure, and synonym.

    • -native: Extracts metadata from the native data source. This option is relevant only for viewing the definition of a local table or procedure (when the obj_type value is local_table or local_procedure).

    • obj_name: The name of the specific object (of the type specified in the obj_type parameter) that is edited. Use the following table to ascertain the obj_name to supply, according on the value of obj_type, or use * for all of the objects of the specified type:

      binding: The name of the binding. If not provided, the default binding (NAV) is used.

      bindings: No value necessary.

      datasources: The name of the binding configuration.

      daemon: The daemon name.

      daemons: No value necessary.

      env[ironment]: The name of the binding configuration for this working environment.

      local_procedure: The name of a local copy of a procedure to be edited or * to edit all the local copy procedures for the specified ds_name.

      local_table: The name of a local copy of a table to be edited or * to edit all the local copy tables for the specified ds_name.

      machine: No value necessary.

      procedure: The name of the procedure to be edited or * to edit all the procedures for the specified ds_name.

      remote_machines: The name of the binding configuration.

      synonym: The name of the synonym to be edited or *to edit all the synonyms for the specified ds_name.

      table: The name of the table to be edited or * to edit all the tables for the specified ds_name.

      user: The user name that identifies the user profile.

      view: The name of the view to be edited or * to edit all the views for the specified ds_name.

Supplying a value for obj_name that does not exist in the repository, will also create a template, based on the default object (such as NAV for binding or IRPCD for daemon).

EXECUTE

This section contains information on the following topics:

EXECUTE Overview

Use the EXECUTE command to test data connections and SQL statements in the interactive NavSQL environment. Running the EXECUTE command gives you the NavSQL prompt.

An example of when to use the EXECUTE command is to check the available data types supported by the data source. For example, if a table in the data source requires a float, the SQL must specify a float rather than a string.

Perform the following procedure to run the EXECUTE command on z/OS platforms.

  • At the prompt, enter:

    execute [-P<password>] [-W<workspace>] <ds_name> [<filename>]

    Where:

    • password: The master password that was specified for the user profile. If the password is not supplied, you are prompted for it.

    • workspace: The name of the binding that is used as the basis for information. If the binding is not supplied, the default Oracle Connect for IMS, VSAM, and Adabas Gateways binding is used.

    • ds_name: The name of the data source, as specified in the binding configuration. If you don't supply this parameter, you are prompted for it.

    • filename: The name of a file, which contains SQL statements. The SQL statements in the file are run immediately. The file is a text file (with any extension). Multiple SQL statements in the file must be separated by semi-colons (;).

The EXECUTE command lets you perform the following tasks:

  • Run SQL statements.

  • Request Help and information about a data source.

  • Change the name of the default data source.

    Enter the command tdp with the new name that you want as the default data source. This name must have been defined in the binding configuration.

  • Exit the NavSQL environment.

    Enter quit or exit.

Each entered command can span a number of lines. End the command with a semi-colon (;).

Running SQL Statements

You can write and run SQL statements as follows:

On-the-fly

Compose an SQL statement and end it with a semi-colon. Press <Enter> to execute the statement.

If the SQL contains data from more than one data source, use a colon (:) to identify the data source (that is, datasource_name:Table_name).

From a File

Enter the full name of a dataset that contains SQL, surrounded by single quotes and prefixed by @. Press <Enter> to execute the SQL contained in the dataset. For example:

@'NAVROOT.TMP.SQL1'

will execute the SQL contained in the SQL1 dataset.

Perform the following procedure to run a dataset immediately.

  • At the prompt, enter:

    execute <data_source> <file>

    Where:

    • data_source is the name of the data source as defined in the binding and file is the name of the SQL file.

Perform the following procedure to run all the queries in the dataset without the overhead of displaying query information on the screen for each query.

  • At the prompt, enter:

    execute <data_source> -quiet <file>

In this case, only queries that fail cause information to be displayed to the screen during the run. A message is displayed after all the queries have been run, stating the number of queries that succeeded and the number that failed.

From within a Transaction

Enter the command begin-transaction (optionally with either read-only or write permission) to start a transaction where you can commit a number of SQL statements together. Use commit to update the data sources with any changes or rollback if you decide that you do not want to accept the changes.

EXECUTE Commands

Use the HELP command to list all the available EXECUTE commands, as shown in Figure A-1.

Figure A-1 Available EXECUTE commands

NavSQL Environment
Description of "Figure A-1 Available EXECUTE commands"

The following transaction-based commands are available for use with the EXECUTE command:

  • Begin-transaction

  • Commit

  • Rollback

The following command can be used to change the default data source:

  • tdp <ds_name> or tdp-default <ds_name>

The following commands can be used to extract information related to the data source:

  • describe [<ds-name>:]<table-name> [full] [index]: Provides table information. If full is specified, additional column information is provided. If index is specified, where available a visual representation of the record structure is displayed (this structure can be made available by running the NAV_UTIL EXPORT command).

    desc is a short form of the describe command.

  • describe @<proc_name>: To provide a description of a stored procedure and/or procedures that are included in an Oracle Connect for IMS, VSAM, and Adabas Gateways procedure (the type is Application Connection (Procedure) or Natural/CICS in the binding configuration).

    desc is a short form of the describe command.

  • list catalogs [<mask>]: Lists details about all the catalogs, or a subset of the catalogs when a mask is supplied.

    list cata or list catas are short forms of the list catalogs command.

  • list columns [<table-mask>] [<column-mask>]: Lists details about the columns of the data source. You can list details about specific columns of the data source and about columns in specific tables belonging to the data source. You must also specify if the data source management system is case sensitive.

  • list procedures [<mask>]: Lists details of all the Oracle Connect for IMS, VSAM, and Adabas Gateways procedures, or a subset of the procedures when a mask is supplied.

  • list procedure_col [<proc-mask>] [<column-mask>]: Lists details about the columns referenced by the Oracle Connect for IMS, VSAM, and Adabas Gateways procedures. You can list details about specific columns and about columns in specific procedures. You must also specify if the data source management system is case sensitive.

  • list special-col [<mask>]: Lists details about all the columns with special characteristics (for example key fields), for the data source or a specific table belonging to the data source when a mask is supplied.

  • list statistics [<mask>]: Lists statistics about all the tables, or a subset of the tables when a mask is supplied.

  • list synonyms: Lists details about all the synonyms.

  • list tables [<mask>]: Lists details about all the tables, identified by the type of table: views, synonyms and system tables. A subset of the tables is displayed when a mask is supplied.

    list tab or list tabs are short forms of the list tables command.

  • list tables @*: Provides a listing of all procedures included in an Oracle Connect for IMS, VSAM, and Adabas Gateways procedure (type is Application Connection (Procedure) in the binding configuration).

    list tab or list tabs are short forms of the list tables command.

  • show datatype [<dt-id>]: Lists details about all the data types available, or a specific data type when a number (the dt-id parameter) is supplied.

  • list views: Lists details about all the views.

  • native_describe [<ds-name>:]<table-name> [full] [index]: Runs the describe command of the data source. If full is specified, additional column information is provided.

  • query[_describe] <query>: Provides query information, including the number of fields in the query with the field descriptions and the number of parameters expected by the query.

EXPORT

The EXPORT command enables you to export the contents of a repository to an XML document. You can export the following types of objects from the repository to an XML file:

  • All configuration information for a particular machine

  • User profile definitions

  • The list of available bindings

  • Information for a particular binding, which can include information about the following:

    • Data sources

    • Remote Machine

    • Environment settings

  • Information about the available daemons

  • Information about the following for a particular data source:

    • Tables that rely on ADD metadata

    • ADD metadata for a table generated by the LOCAL_COPY command

    • Stored procedures that rely on ADD metadata

    • ADD metadata for a stored procedure generated by the LOCAL_COPY command

    • Views

    • Synonyms

In addition, you can use the EXPORT utility to export metadata from a data source where the metadata is readable by Oracle Connect for IMS, VSAM, and Adabas Gateways (such as Oracle metadata). The metadata is converted to XML, which is editable. When running EXPORT, use the -native option, as described below. After editing, import the metadata to a local repository for the data source.

Example A-1 EXPORT Syntax

Local> [<options>] export <obj_type>
[ds_name [-native]] <obj_name> <xml_file>

Where:

  • options: See Table A-1, "NAV_UTIL Options" for details

  • obj_type: The type of object to be exported. You can specify the following types of objects:

    • all: All configuration information for a data source.

    • bindings: All available bindings and their environments.

    • binding: A particular set of binding information.

    • daemon: Daemon general configuration settings.

    • daemons: Daemon general configuration settings of all daemons.

    • datasources: The data sources specified in a binding.

    • remote_machines: Remote machines defined in the binding.

    • env[ironment]: Environment properties for a particular binding.

    • table: Table definitions per data source.

    • local_procedure: ADD metadata for a data source stored procedure generated by the LOCAL_COPY command.

    • local_table: ADD metadata for a table generated by the LOCAL_COPY command.

    • machine: All configuration information for a particular machine.

    • procedure: Stored procedure definitions that rely on ADD metadata.

    • synonym: Synonyms definitions per data source.

    • user: A user profile definition.

    • users: All user profile definitions.

    • view: Oracle Connect for IMS, VSAM, and Adabas Gateways view on a data source.

  • ds_name: The name of data source for the object to be exported, as specified in the binding configuration, when the obj_type is any of: table, local_table, view, procedure, local_procedure, and synonym.

  • -native: Extracts metadata from the native data source where the metadata is readable by Oracle Connect for IMS, VSAM, and Adabas Gateways (such as Oracle metadata). The metadata is converted to XML which is editable. Use the -native option to view the native metadata. This option is relevant only for exporting a table or stored procedure (when the obj_type parameter is table or procedure).

    If the data source is an ADD data source, the metadata is extracted from the repository and from information specific to the driver for that data source, which is usually retrieved from the data source at runtime. For example, the ISN value in Adabas or RFA column in RMS.

  • obj_name: The name of the specific object (of the type specified in the obj_type parameter) that is exported. Use the following table to ascertain the obj_name to supply, dependent on the value of obj_type, or use * for all of the objects of the specified type

    • all: All configuration information for a data source.

    • bindings: All available bindings and their environments.

    • binding: A particular set of binding information.

    • daemon: Daemon general configuration settings.

    • daemons: Daemon general configuration settings of all daemons.

    • datasources: The data sources specified in a binding.

    • remote_machines: Remote machines defined in the binding.

    • env[ironment]: Environment properties for a particular binding.

    • table: Table definitions per data source.

    • local_procedure: ADD metadata for a data source stored procedure generated by the LOCAL_COPY command.

    • local_table: ADD metadata for a table generated by the LOCAL_COPYcommand.

    • machine: All configuration information for a particular machine.

    • procedure: Stored procedure definitions that rely on ADD metadata.

    • synonym: Synonyms definitions per data source.

    • user: A user profile definition.

    • users: All user profile definitions.

    • view: An Oracle Connect for IMS, VSAM, and Adabas Gateways view on a data source.

  • xml_file: The XML file to which the specified object is exported (output). If a file name is not specified, the output is displayed on the terminal.

Perform the following procedure to back up Oracle server definitions on z/OS.

  1. At the prompt, enter: export all <ds_name> * <xml_file1>

    where ds_name is the name of a data source in the binding with Oracle Connect for IMS, VSAM, and Adabas Gateways metadata defined for it.

  2. Repeat the previous step for every data source with Oracle Connect for IMS, VSAM, and Adabas Gateways metadata defined for it, changing the name of the output file for each data source.

    The collection of output files together constitute a complete backup of all the Oracle Connect for IMS, VSAM, and Adabas Gateways definitions on the machine.

GEN_ARRAY_TABLES

The GEN_ARRAY_TABLES command creates virtual tables for Adabas, CISAM, DBMS, DISAM, Enscribe, RMS, and VSAM arrays from existing metadata. The Adabas database can be accessed using ADD or Predict.

Virtual tables are created automatically by Oracle Connect for IMS, VSAM, and Adabas Gateways when the metadata is created for the data source.

Perform the following procedure to run the GEN_ARRAY_TABLES command on z/OS platforms.

  • At the prompt, enter:

    gen_array_tables <ds_name> <table>

    Where:

    • ds_name: The data source name, as specified in the binding configuration.

    • table: The name of the table in the repository that is defined with an array. Use wildcards if you want to generate virtual tables for more than one table.

IMPORT

The IMPORT command enables you to import the contents of a valid XML document (formatted correctly for Oracle Connect for IMS, VSAM, and Adabas Gateways) to the repository. You can import the following types of objects to the repository from an XML file:

  • User profile definitions

  • Binding information

  • Environment settings (per workspace)

  • Daemon configuration information

  • Table definitions that rely on ADD metadata (per data source)

  • View definitions (per data source)

  • Stored procedures that rely on ADD metadata

  • Synonym definitions (per data source)

  • Metadata generated by the LOCAL_COPY command

Perform the following procedure to run the IMPORT command on z/OS platforms.

  • At the prompt, enter:

    [<options>] import <name> <xml_file>

    Where:

    • options: See Table A-1, "NAV_UTIL Options" for details.

    • name: The name of the data source for the object to be imported, as specified in the binding configuration, when the object is any of: table, local_table, view, procedure, local_procedure, and synonym.

      The value of ds_name is used and not the value of the data source attribute in the XML file. The data source value is generated when using NAV_UTIL EXPORT. Thus, for example, if you export a table definition and then want to import the definition to another data source, you do not need to change the data source attribute value in the XML file before imported the file.

    • xml_file: The XML file to which the specified object is exported (output). If a file name is not specified, the output is displayed on the terminal.

When importing the following types of objects, you must specify SYS as the ds_name entry:

  • Binding information

  • Daemon configuration information

  • User profiles

  • Working environment configuration

IMS_MERGE

The IMS_MERGE command creates IMS ADDL and command files from COBOL ADDL files and IMS metadata. Perform the following procedure to run the IMS_MERGE command on z/OS platforms.

  • At the prompt, enter:

    ims_merge <COBOL_ADDL> <DBD_file> <PSB_file> <ouput_ADDL> <output_allocation_template> [cobol_segment_translation_file]

IRPCDCMD

The IRPCDCMD is a utility for the z/OS platform that is used to perform management tasks on the daemon. This utility can be used from the IRPCDCMD REXX.

To use this utility, execute the IRPCDCMD script, located in navroot.userlib.

When you get the prompt, you can invoke the required command.

For example:

> -l 183.22.12.10 status

Usage Format

irpcd [-l daemon_location] [-u username] [-p password] command [arguments]

The following commands are available:

  • APPLIST [app-name or app-mask]

  • RELOADINI

  • RESETLOG

  • SHUTDOWN [<ABORT|OPERATOR> ["why..."]]

  • STATUS [workspace-name]

  • REFRESH [workspace-name]

  • KILL [workspace-name]

  • TEST

  • ENABLE [workspace-name]

  • DISABLE [workspace-name]

LOCAL_COPY

The LOCAL_COPY command extracts the data definition of a table or stored procedure from the data source catalogs and saves it to the repository. This utility enables you to improve query performance by creating a copy (“snapshot”) of the data source metadata, which is used instead of the data source metadata. The copy must be on the same machine as the data.

Perform the following procedure to run the LOCAL_COPY command on z/OS platforms.

  • At the prompt, enter:

    local_copy <ds_name> <src_table>

    Where:

    • ds_name: The data source name, as specified in the binding configuration.

    • src_table: The source table name (wildcards are allowed).

PASSWORD

The PASSWORD command allows you to define a master password.

Perform the following procedure to run the PASSWORD command on z/OS platforms.

  • At the prompt, enter:

    password [-u<username>] <new_password>

    If you have an existing password, you are prompted to specify it before defining the new master password.

SVC

The SVC command starts a server on the port specified.

Perform the following procedure to run the SVC command on z/OS platforms.

  • At the prompt, enter:

    svc :<port-number>

TEST

The TEST command is for use only when instructed by Oracle Support.

UPDATE

The UPDATE command collects information about tables, indexes, and optionally column cardinalities, for use by the Oracle Connect for IMS, VSAM, and Adabas Gateways Query Optimizer. Each time the utility is run, the resulting statistics overwrite previous statistics.

The UPDATE command collects information about tables, indexes, and optionally column cardinalities, for use by the Oracle Connect for IMS, VSAM, and Adabas Gateways Query Optimizer. Each time the utility is run, the resulting statistics overwrite previous statistics.

This command can be used for all data sources (both those that require ADD metadata and relational data sources). For relational data sources, an entry is created in the Oracle Connect for IMS, VSAM, and Adabas Gateways repository for the data source. An example of when statistics would be used for a relational driver is with SQL/MP, to generate index statistics in addition to the column statistics generated by SQL/MP.

Caution:

Executing the UPDATE command with the reset option deletes all statistics on the specified table.

Perform the following procedure to run the UPDATE command on z/OS platforms.

  • At the prompt, enter:

    update[_statistics] <ds_name> <table_name> [EXACT | rows <row_num>] [+All | [column-options] [index-options]]

Removing Metadata Statistics

On z/OS platforms, remove metadata statistics as follows:

  1. Run the following command: NAVROOT.USERLIB(navcmD)

    Where NAVROOT is the high-level qualifier where Oracle Connect for IMS, VSAM, and Adabas Gateways is installed.

  2. At the prompt, enter:

    update[_statistics] <ds_name> <table_name> reset

    Where:

    • ds_name: The name of the data source, as specified in the binding configuration.

      Note:

      The data source must be local. For a remote data source, run the utility on the remote machine.

    • table_name: The name of the table. You can specify the wildcards * and % as part of the table name.

      Note:

      If you use a wildcard as part of the table name, only the default -All parameter is available (the column-options and index-options parameters are invalid).

    • EXACT: The exact statistical information is returned. Note that this option does not work with large tables.

    • rows row_num: The number of rows in the table. This value is used to shorten the time to produce the statistics, assuming that the value specified here is the correct value, or close to the correct value. It is recommended to specify a value for rows. The number of unique values per index is also returned.

      When the number of rows in the table is not provided, the number of rows used is determined as the maximum value between the value specified in the tuningdsmMaxBufferSize parameter of the environment settings and the value set in the nRows attribute (specified as part of the metadata for the data source).

    • +All: Information about the table, indexes, partial indexes and columns is included in the output. The default is that only information about the table and indexes is included in the output and not information for partial indexes and columns.

    • column-options: The following column options can be specified:

      +fcol_name1 +fcol_name2…: Returns information only about the specified table columns.

      +f*: Returns information about all the table columns.

    • index-options: The following index options can be specified:

      +i1 +i2 …: Returns information only about the specified indexes and partial indexes.

      +i*: Returns information about all the table indexes.

      If you want information about all the indexes and only some of the partial indexes, you can run the utility twice: once with the -All option and once with the +i1, +i2,... option for the required partial indexes.

Example A-2 Eliminating Statistics Samples

Local> update disam nation

Estimates the number of rows in the NATION table of the data source. The result is based on the number of nRows specified as part of the metadata for the data source and the amount of available memory as specified by the dsmMaxBufferSize parameter of the environment settings.

Local> update disam nation rows 100

Estimates the number of rows in the NATION table of the data source. The result is based on the number of rows specified (100). If the value specified here is the correct value, or close to the correct value, the time to calculate the statistics is shortened.

Local> update disam nation EXACT

Exact statistics for the NATION table of the data source are returned.

UPD_DS

To update the default binding configuration, use the UPD_DS command. This enables you to update the binding only with changes that involve specifying the connection information.

Perform the following procedure to run the UPD_DS command on z/OS platforms.

  • At the prompt, enter:

    [<options>] upd_ds <ds_name> <ds_type> <connect_string>

    Where:

    • options: See Table A-1, "NAV_UTIL Options" for details.

    • ds_name: The name of the data source to be added to the binding configuration.

    • ds_type: The name of the driver that is used when accessing the data source.

    • connect_string: The connect string to be used to access the data source.

UPD_SEC

To update the default user profile, use the UPD_SEC command. This enables you to update the user name and password for both a specific data source or machine in a user profile. Perform the following procedure to run the UPD_SEC command on z/OS platforms.

  • At the prompt, enter:

    [<options>] upd_sec <ds_name> | -machine <machine>[:<port>] [-u<username>] [-p<password>]

    Where:

    • options: See Table A-1, "NAV_UTIL Options" for details.

    • ds_name: The name of the data source, as specified in the binding configuration, to which the user profile is related.

    • machine[:port]: The name and, optionally, the port of the data source to which the user profile is related.

    • username: The user name to access the data source or machine.

    • password: The password to access the data source or machine.

VERSION

The VERSION command enables you to check which version of Oracle Connect for IMS, VSAM, and Adabas Gateways is running on the machine.To display the version of the Oracle Connect for IMS, VSAM, and Adabas Gateways installation, use the following command line:

  • At the prompt, enter:

    version [-history]

VERSION_HISTORY

The VERSION_HISTORY command returns a report of installations, upgrades and patches installed on the machine. Perform the following procedure to run the VERSION_HISTORY command on z/OS platforms.

  • At the prompt, enter:

    version_history

VIEW

The VIEW command enables you to view the contents of a repository. With this command you can see the definitions of the following types of repository objects:

  • All configuration information for a particular machine, including all the elements listed below.

  • User profile definitions

  • The list of available bindings

  • Information for a particular binding, which can include information about the following:

    • Data sources

    • Remote machines

    • Environment settings

  • Information about the available daemons

  • Information about the following for a particular data source:

    • Tables that rely on ADD metadata

    • ADD metadata for a table generated by the LOCAL_COPY command

    • Stored procedures that rely on ADD metadata

    • ADD metadata for a data source stored procedure generated by the LOCAL_COPY command.

    • Views

    • Synonyms

Perform the following procedure to run the VIEW command on z/OS platforms.

At the prompt, enter:

[<options>] view <obj_type> [<ds_name> [-native]] <obj_name>

Where:

  • options: See Table A-1, "NAV_UTIL Options" for details.

  • obj_type: The type of object whose definition is displayed. You can specify the following types of objects:

    • binding: A particular set of binding information.

    • bindings: All available bindings and their environments.

    • datasources: The data sources specified in a binding.

    • datasources: The data sources specified in a binding.

    • daemon: Daemon general configuration settings.

    • daemons: Daemon general configuration settings of all daemons.

    • env[ironment]: Environment properties for a particular binding.

    • local_procedure: ADD metadata for a stored procedure generated by the LOCAL_COPY command.

    • local_table: ADD metadata for a table generated by the LOCAL_COPY command.

    • machine: All configuration information for a particular machine.

    • procedure: Stored procedure definitions that rely on ADD metadata.

    • remote_machines: Remote machines defined in the binding.

    • synonym: Synonyms definitions per data source.

    • table: Table definitions per data source.

    • user: A user profile definition.

    • view: An Oracle Connect for IMS, VSAM, and Adabas Gateways view on a data source.

  • ds_name: The name of data source, as specified in the binding configuration, for the object whose definition is displayed, when the obj_type is any of: table, local_table, view, procedure, local_procedure, and synonym.

  • -native: Extracts metadata from the native data source. This option is relevant only for viewing the definition of a table or stored procedure (when the obj_type value is table or procedure). You usually define this feature in Oracle Studio for IMS, VSAM, and Adabas Gateways.

  • obj_name: The name of the specific object (of the type specified in the obj_type parameter) that is displayed. Use the following table to ascertain the obj_name to supply, dependent on the value of obj_type, or * for all of the objects of the specified type:

    • binding: The name of the binding. If not provided, the default binding (NAV) is used.

    • bindings: No value necessary.

    • datasources: The name of the binding configuration.

    • daemon: The daemon name.

    • daemons: No value necessary.

    • env[ironment]: The name of the binding configuration for this working environment.

    • local_procedure: The name of a local copy of a procedure to be viewed or * to view all the local copy procedures for the specified ds_name.

    • local_table: The name of a local copy of a table to be viewed or * to view all the local copy tables for the specified ds_name.

    • machine: No value necessary.

    • procedure: The name of the procedure to be viewed or * to view all the procedures for the specified ds_name.

    • remote_machines: The name of the binding configuration.

    • synonym: The name of the synonym to be viewed or * to view all the synonyms for the specified ds_name.

    • table: The name of the table to be viewed or * to view all the tables for the specified ds_name.

    • user: The user name that identifies the user profile.

    • view: The name of the view to be viewed or * to view all the views for the specified ds_name.

XML

The XML command sends an XML request directly to Oracle Connect for IMS, VSAM, and Adabas Gateways for processing, much like execute sends an SQL query directly to Oracle Connect for IMS, VSAM, and Adabas Gateways. XML is particularly suited to troubleshooting, by enabling system administrators and DBAs to check the Oracle Connect for IMS, VSAM, and Adabas Gateways XML dispatcher's handling of queries specified in XML documents.

Perform the following procedure to run the XML command on z/OS platforms.

  • At the prompt, enter:

    xml <fin>.xml <fout>.xml

    Where:

    • fin.xml: The file name with the input XML.

    • fout.xml: The file name of the output XML. If a file name is not specified, the output is displayed on the terminal.

XML Samples

Oracle Connect for IMS, VSAM, and Adabas Gateways processes XML requests (including queries) specified only in documents formatted in the syntax specific to Oracle Connect for IMS, VSAM, and Adabas Gateways. The general structure of this syntax is as follows:

Example A-3 XML Sample

header>
  <request-step1>…</request-step1>
  ...
  <request-stepn>…</request-stepn>
</header>

The following input file is formatted according to the requirements of the Oracle Connect for IMS, VSAM, and Adabas Gateways XML implementation and specifies the SQL query select * from navdemo:nation:

Example A-4 XML Input FIle Sample

<?xml version="1.0"?>
<acx>
  <connect adapter="query" />
  <execute>
    <query id="1">
            select * from navdemo:nation
    </query>
  </execute>
  <disconnect/>
</acx>

Running the XML command with the above file as input generates the following output file:

Example A-5 XML Output File Sample

<?xml version='1.0' encoding='ISO-8859-1'?>
<acx type='response'>
  <connectResponse idleTimeout='0'></connectResponse>
  <executeResponse>
    <recordset id='1'>
      <record N_NATIONKEY='0' N_NAME='ALGERIA' N_REGIONKEY='0'
              N_COMMENT='New Distributor                            '/>
      <record N_NATIONKEY='1' N_NAME='ARGENTINA' N_REGIONKEY='1'
              N_COMMENT='Far Away                                   '/>
      <record N_NATIONKEY='2' N_NAME='BRAZIL' N_REGIONKEY='1'
              N_COMMENT='Nearby                                     '/>
       ...
    </recordset>
  </executeResponse>
</acx>