A Using NAV_UTIL Utility

A.1 Running NAV_UTIL

This section contains information on the following topics:

• Activating NAV_UTIL

• Basic NAV_UTIL Syntax

A.2 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.

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.

A.3 CHECK

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

• check irpcd

• check network [port]

• check irpcdstat

• check tcpip

• check server

• check license

• check datasource

A.4 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.

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.

A.5 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.

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).

A.6 EXECUTE

This section contains information on the following topics:

• EXECUTE Overview

• Running SQL Statements

• EXECUTE Commands

@'NAVROOT.TMP.SQL1'

A.6.3 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

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.

A.7 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.

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

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.

A.8 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.

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.

A.9 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

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

A.10 IMS_MERGE

The IMS_MERGE command creates IMS ADDL and command files from COBOL ADDL files and IMS metadata.

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]

A.11 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]

A.12 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.

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).

A.13 PASSWORD

The PASSWORD command allows you to define a master password.

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.

A.14 SVC

The SVC command starts a server on the port specified.

To run the SVC command on z/OS platforms

• At the prompt, enter:

  svc :<port-number>

A.15 TEST

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

A.16 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.

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]]

Local> update disam nation

Local> update disam nation rows 100

Local> update disam nation EXACT

A.17 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.

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.

A.18 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.

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.

A.19 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:

To run the VERSION command on z/OS platforms

• At the prompt, enter:

  version [-history]

A.20 VERSION_HISTORY

The VERSION_HISTORY command returns a report of installations, upgrades and patches installed on the machine.

To run the VERSION_HISTORY command on z/OS platforms

• At the prompt, enter:

  version_history

A.21 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

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.

A.22 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.

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.

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

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

<?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>