A
Control Utility Reference

Purpose:  

This command allows you to dynamically change the password of a listener. This will not change unencrypted passwords already established in a listener configuration file. It only establishes a new password, or changes a password that has been encrypted in the listener configuration file.  

Prerequisites:  

None  

Password Required:  

Yes  

Syntax:  

change_password [listener_name]

Arguments:  

listener_name  

Usage Notes:  

The control utility prompts you for your old password, then for the new one. It asks you to re-enter the new one, then changes it. Neither the old nor the new password displays during this procedure.  

Example:  

LSNRCTL> change_password
Old password:
New password:
Reenter new password:
Connecting to (ADDRESS=(PROTOCOL=ipc)(KEY=iris))
Password changed for LISTENER
The command completed successfully

Purpose:  

This command starts the SNMP subagent for an Oracle database running on the same node.  

Prerequisites:  

Must be run locally  

Password Required:  

No  

Syntax:  

LSNRCTL> dbsnmp_start

Arguments:  

None  

Usage Notes:  

None  

Example:  

LSNRCTL> dbsnmp_start

Purpose:  

This command verifies whether the SNMP subagent for an Oracle database is running.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

LSNRCTL> dbsnmp_status

Arguments:  

None  

Usage Notes:  

DBSNMP STATUS must be run on the same node the Oracle database is on.  

Example:  

LSNRCTL> dbsnmp_status

Purpose:  

This command stops the SNMP subagent for an Oracle database running on the same node.  

Prerequisites:  

Must be run locally  

Password Required:  

No  

Syntax:  

LSNRCTL> dbsnmp_stop

Arguments:  

None  

Usage Notes:  

None  

Example:  

LSNRCTL> dbsnmp_stop

Purpose:  

This command quits LSNRCTL and returns you to the operating system prompt  

Prerequisites:  

None  

Password Required:  

Yes  

Syntax:  

LSNRCTL> EXIT

Arguments:  

None  

Usage Notes:  

This command is identical to QUIT  

Example:  

LSNRCTL> EXIT

Purpose:  

Provides a list of all the LSNRCTL commands available  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

LSNRCTL> help

Arguments:  

None  

Example:  

LSNRCTL> help
The following operations are available 
An asterisk (*) denotes a modifier or extended command: 
start               stop                status 
services            version             reload 
trace               spawn               dbsnmp_start 
dbsnmp_stop         dbsnmp_status       change_password 
quit                exit                set* show*

Purpose:  

This command quits LSNRCTL and returns you to the operating system prompt  

Prerequisites:  

None  

Password Required:  

Yes  

Syntax:  

LSNRCTL> QUIT

Arguments:  

None  

Usage Notes:  

This command is identical to EXIT  

Example:  

LSNRCTL> QUIT

Purpose:  

This command shuts down everything except listener addresses, and re-reads the LISTENER.ORA file. This command enables you to add or change services without actually stopping the listener.  

Prerequisites:  

This will not work on valid nodes. In this case, the listener must be stopped and restarted.

Password Required:  

Yes

Syntax:  

LSNRCTL> reload [listener name]

Arguments:  

Name of listener  

Usage Notes:  

If there are any passwords in the listener configuration file, you must use the SET PASSWORD command before you can use the RELOAD command.

You must set the password from within the LSNRCTL program; you cannot set it from the operating system command line. The method for setting the password depends on whether you are using the encrypted password feature. If you are not using an encrypted password, enter the password on the LSNRCTL command line.  

Example:  

LSNRCTL> reload

Purpose:  

This command creates a backup of your listener configuration file (called LISTENER.BAK) and updates the actual configuration file (LISTENER.ORA) itself to reflect any changes.  

Password Required:  

Yes

Syntax:  

LSNRCTL> save_config [listener name]

Arguments:  

Name of listener

Usage Notes:  

This is used by an administrator to save all on-line configuration changes to the listener configuration file.

Example:  

LSNRCTL> SAVE_CONFIG LISTENER

Purpose:  

This command provides detailed information about the services the listener listens for. For example, how many connections have been established, how many refused. It displays three different types of services (dedicated servers from LISTENER.ORA, dispatcher information, and prespawned shadows.)  

Prerequisites:  

None

Password Required:  

Yes

Syntax:  

LSNRCTL> services [listener name]

Arguments:  

Name of listener

Usage Notes:  

This is used by a database administrator to get information about the services of the listener.

Example:  

LSNRCTL> SERVICES [listener name]

The output of a LSNRCTL SERVICES command follows:

LSNRCTL for SunOS: Version 8.0.3.0.0 - 
Production on 10-FEB-97 07:14:55
Copyright (c) Oracle Corporation 1993.  All 
rights reserved.
Connecting to 
(ADDRESS=(PROTOCOL=IPC)(KEY=ruth))
Services Summary...
ruth has 1 service handlers
DEDICATED SERVER established:99 refused:0

Purpose:  

This command lists the parameter values that can be set using the SET command.  

Prerequisites:  

None

Password Required:  

Yes

Syntax:  

LSNRCTL> set

Arguments:  

None

Usage Notes:  

You must have set a valid password to be able to use this command if one is listed in the listener configuration parameter, PASSWORDS_listener_name.

If there are any passwords in the listener configuration file, you must use the SET PASSWORD command before you can use the SET command.

You must set the password from within the LSNRCTL program; you cannot set it from the operating system command line. The method for setting the password depends on whether you are using the encrypted password feature. If you are not using an encrypted password, enter the password on the LSNRCTL command line.  

Example:  

LSNRCTL> set

The following operations are available after set

An asterisk (*) denotes a modifier or extended command:

password trc_file trc_directory

trc_level log_file log_directory

log_status current_listener connect_timeout

save_config_on_stop startup_waittime

use_plugandplay  

Purpose:  

This command determines the amount of time the listener will wait for a valid connection request after a connection has been started.  

Prerequisites:  

None  

Password Required:  

No

Syntax:  

LSNRCTL> set connect_timeout time

Arguments:  

time in seconds  

Usage Notes:  

None  

Example:  

LSNRCTL> set connect_timeout 20
Connecting to 
(ADDRESS=(PROTOCOL=ipc)(KEY=iris))
LISTENER parameter "connect_timeout" set to 20
The command completed successfully

Purpose:  

This command sets or shows parameters when for multiple listeners.  

Prerequisites:  

You must enter SET CURRENT_LISTENER from within the LSNRCTL utility  

Password Required:  

No

Syntax:  

LSNRCTL> set current_listener [listener name]

Arguments:  

[listener name]  

Default Argument  

LISTENER  

Usage Notes:  

If there is more than one listener on a node, any LSNRCTL command acts on the default listener (LISTENER) unless another listener has been set.

Any subsequent LSNRCTL commands within the same LSNRCTL session would then apply to the second listener, unless CURRENT_LISTENER were reset.

You can also display the current listener by using the LSNRCTL SHOW command.

You must enter SET CURRENT_LISTENER from within the LSNRCTL utility. When you exit the utility, the setting will be lost.  

Example:  

LSNRCTL> set current_listener [listener name]

Purpose:  

This command sets a non-default location for the log file or to return the location to the default.  

Prerequisites:  

None  

Password Required:  

No

Syntax:  

LSNRCTL> set log_directory [directory]

Arguments:  

[directory]  

Example:  

LSNRCTL> set log_directory /usr/oracle/admin 
Connecting to 
(ADDRESS=(PROTOCOL=ipc)(KEY=iris))LISTENER 
parameter "log_directory" set to /usr/oracle/
admin
The command completed successfully

Purpose:  

This command sets a non-default name for the log file  

Prerequisites:  

None  

Password Required:  

No

Syntax:  

LSNRCTL> set log_file [filename]

Arguments:  

[filename]  

Example:  

LSNRCTL> set log_file list.log
Connecting to 
(ADDRESS=(PROTOCOL=ipc)(KEY=iris))LISTENER 
parameter "log_file" set to list.log
The command completed successfully

Purpose:  

This command turn listener logging on or off  

Prerequisites:  

None  

Password Required:  

No

Syntax:  

LSNRCTL> set log_status [on | off]

Arguments:  

ON or OFF  

Example:  

LSNRCTL> set log_status on

Purpose:  

This command changes the password sent from the LSNRCTL utility to the listener process for authentication purposes only. To change the password on the listener itself, use the change_password command.  

Password Required:  

Yes

Syntax:  

LSNRCTL> set password

Arguments:  

[password]

Usage Notes:  

You may enter this command when you start up the shell or any time during your session. (You must enter the SET PASSWORD command before you can stop the listener.)

The preferred, secure way to enter your password is in interactive mode. The listener supports encrypted and unencrypted passwords.  

Example:  

LSNRCTL> SET PASSWORD
enter listener password: password

Purpose:  

This command saves any changes made by the LSNRCTL SET command permanently if parameter is ON. The saving of all parameters occurs right before the listener exits. To have all parameters saved right away, use the SAVE_CONFIG command.  

Password Required:  

Yes

Syntax:  

LSNRCTL> set save_config_on_stop [ON | OFF]

Arguments:  

ON or OFF  

Example:  

LSNRCTL> set save_config_on_stop ON

Purpose:  

This command sets the amount of time the listener sleeps before responding to a START command:  

Prerequisites:  

None  

Password Required:  

No

Syntax:  

LSNRCTL> set startup_waittime time

Arguments:  

time in seconds

Example:  

LSNRCTL> set startup_waittime 10
Connecting to 
(ADDRESS=(PROTOCOL=ipc)(KEY=iris))LISTENER 
parameter "startup_waittime" set to 10

The command completed successfully  

Purpose:  

This command sets a non-default location for the trace file or to return the location to the default.  

Prerequisites:  

None  

Password Required:  

No

Syntax:  

LSNRCTL> set trc_directory [directory]

Arguments:  

[directory]

Example:  

LSNRCTL> set trc_directory /usr/oracle/admin

Connecting to (ADDRESS=(PROTOCOL=ipc)(KEY=iris))

LISTENER parameter "trc_directory" set to /usr/oracle/admin

The command completed successfully  

Purpose:  

This command sets a non-default name for the trace file  

Prerequisites:  

None  

Password Required:  

No

Syntax:  

LSNRCTL> set trc_file [filename]

Arguments:  

[filename]

Example:  

LSNRCTL> set trc_file list.trc

Connecting to (ADDRESS=(PROTOCOL=ipc)(KEY=iris))

LISTENER parameter "trc_file" set to list.trc

The command completed successfully  

Purpose:  

This command turns on tracing for the listener.  

Prerequisites:  

None  

Password Required:  

Yes

Syntax:  

LSNRCTL> SET TRC_LEVEL level

Arguments:  

OFF, USER, ADMIN, SUPPORT  

Usage Notes:  

Selecting USER provides a limited level of tracing; ADMIN provides a more detailed trace. This command overrides the setting in the LISTENER.ORA file.

You must have set a valid password, if one is listed in the LISTENER.ORA file parameter PASSWORDS_listener_name to be able to use this command

This command is identical to TRACE.  

Example:  

LSNRCTL> SET TRC_LEVEL ADMIN

Purpose:  

All of the SET commands listed except SET PASSWORD have equivalent SHOW commands. In response to one of the SHOW commands, LSNRCTL displays the current setting of the listener for that parameter.  

Prerequisites:  

None  

Password Required:  

see equivalent SET commands

Syntax:  

LSNRCTL> show [listener name] subcommand

Arguments:  

[listener name] subcommand  

Usage Notes:  

There are two parameters that can be shown, but not set, through LSNRCTL:

SHOW [listener name] SNMP_VISIBLE



displays whether the listener is accessible to SNMP clients

Example:  

LSNRCTL> show

The following operations are available after show

An asterisk (*) denotes a modifier or extended command:

• current_listener
• connect_timeout
• log_file
• log_directory
• log_status
• save_config_on_stop
• snmp_visible
• startup_wait
• trc_file
• trc_directory
• trc_level
• use_plugandplay

Purpose:  

The SPAWN command starts a program stored on the machine on which the listener runs, and which is listed with an alias in the LISTENER.ORA file.  

Prerequisites:  

None

Password Required:  

No

Syntax:  

LSNRCTL> spawn [listener name] alias 
(ARGUMENTS=arg1,arg2,)

Arguments:  

[listener name] - listener name, if any

alias - the alias of the program as listed in the listener configuration file

arg1 - the arguments sent to the program that is to be spawned

Example:  

LSNRCTL> spawn nstest_alias (ARGUMENTS='')

Purpose:  

This command starts the named listener.  

Prerequisites:  

Listener must be stopped

Password Required:  

No

Syntax:  

LSNRCTL> start [listener name] 

Arguments:  

Name of the listener. If no listener name is entered, LISTENER is started by default.  

Usage Notes:  

To start a listener configured in the LISTENER.ORA file with a name other than LISTENER, include that name.

For example, if the listener name is TCP_LSNR, enter:

LSNRCTL START TCP_LSNR 

Or, from the LSNRCTL program prompt, enter:

LSNRCTL> START TCP_LSNR

Example:  

LSNRCTL> start [listener name]

Purpose:  

This command displays basic information: version, start time, uptime, what LISTENER.ORA file is used, and whether tracing is turned on.  

Prerequisites:  

None

Password Required:  

No

Syntax:  

LSNRCTL> status [listener name]

Arguments:  

Name of listener.

Usage Notes:  

The status command allows you to perform the following:

• check the current setting of the logging and tracing options.
• the list of database SIDs available through this listener. These are defined in the SID mapping in LISTENER.ORA.
• whether a password is encrypted in LISTENER.ORA. (If you encrypt the listener password you can have only one password.)
• whether the network listener can respond to queries from an SNMP-based network management system
• the address(es) the TNSLSNR is listening on

Example:  

LSNRCTL> status [listener name]
LSNRCTL for SunOS:
Copyright (c) Oracle Corporation 1997. All rights reserved.
Connecting to 
(ADDRESS=(PROTOCOL=IPC)(HOST=orchid)(port=1334))
STATUS of the LISTENER
------------------------
Alias                  LISTENER
Version TNSLSNR for SunOS: 
Start Date             10-FEB-97 07:06:34
Uptime                 0 days 0 hr. 0 min. 44 sec
Trace Level            ADMIN
Security               ON
...
The command completed successfully

Purpose:  

This command stops the named listener.  

Prerequisites:  

The listener must be running

Password Required:  

Yes

Syntax:  

LSNRCTL> stop [listener name] 

Arguments:  

Name of listener.

Usage Notes:  

If you have configured passwords, you must use the SET PASSWORD command before you can use the STOP command.

You must set the password from within the LSNRCTL program; you cannot set it from the operating system command line. The method for setting the password depends on whether you are using the encrypted password feature. If you are not using an encrypted password, enter the password on the LSNRCTL command line.

Be careful when stopping a listener. On some platforms and with some protocols, when a listener is stopped any Net8 connections currently running are shut down. In some situations the connections continue, but it is then not possible to start the listener again until the running processes have been closed. It is good practice to send a warning message to all network users before stopping a listener.  

Example:  

LSNRCTL> stop [listener name] 

Purpose:  

This command turns on tracing for the listener.  

Prerequisites:  

valid password required

Password Required:  

Yes

Syntax:  

LSNRCTL> trace [OFF|USER|ADMIN|SUPPORT] [listener name]

Arguments:  

[OFF|USER|ADMIN|SUPPORT] [listener name]  

Usage Notes:  

USER provides a limited level of tracing. ADMIN provides a more detailed trace. This command overrides the setting in the LISTENER.ORA file.

This command has the same functionality as SET TRC_LEVEL.  

Example:  

LSNRCTL> trace [level] [listener name]

Purpose:  

Displays the current TNS listener, and protocol adapter version.  

Prerequisites:  

None

Password Required:  

No

Syntax:  

LSNRCTL> version [listener name]

Arguments:  

Name of service  

Example:  

LSNRCTL> version [listener name]

Purpose:  

Defines a domain as the start of a subregion of the current region  

Prerequisites:  

none  

Password Required:  

No  

Syntax:  

From the operating system prompt:

NAMESCTL _DELEGATE_DOMAIN domain_name ns_name ns_addr

From the NAMESCTL program:

_DELEGATE_DOMAIN domain_name ns_name ns_addr

Arguments:  

domain_name ns_name ns_addr are mandatory. domain_name and ns_name must be legal domain names. ns_addr must be a legal TNS address.  

Usage Notes:  

This command provides a dynamic way to subdivide the namespace.

The domain domain_name is defined with ns_name as the name of the Names Server. ns_name is defined with its address set to ns_addr.

Unless a domain is delegated from a region, the servers in that region will assume authority over all sub-domains. Once a domain is delegated, a new region is created and the servers in the current region are no longer authoritative for the new domain or any sub-domain of the new domain. After delegation, Names Servers in the current domain will forward subsequent operations for objects in the new domain to its Names Servers.  

Examples:  

NAMESCTL> _DELEGATE_DOMAIN webwidgets.acme.com 
ns1.webwidgets.acme.com (address=(protocol=tcp) 
(host=fred.webwidgets.acme.com) (port=1575))

Purpose:  

Provides the Names Servers in the current region with the name and address of a Names Server in another region.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL _DOMAIN_HINT domain_name ns_name ns_addr

From the NAMESCTL program:

_DOMAIN_HINT domain_name ns_name ns_addr

Arguments:  

domain_name ns_name and ns_addr are mandatory. domain_name and ns_name must be legal domain names. ns_addr must be a legal TNS address.  

Usage Notes:  

This command provides a dynamic way to define the path to other regions in the namespace.

The domain domain_name is defined with ns_name as the name of its Names Server. ns_name is defined with its address set to ns_addr.

Any region that is not the root region will need at least the root region defined using this command in order to find objects in any other region. You may provide additional hints as optimizations to provide local Names Servers with direct access to certain other regions.  

Examples:  

NAMESCTL> _DOMAIN_HINT acme.com ns0.acme.com 
(address=(protocol=tcp) (host=top.acme.com) (port=1575))

Purpose:  

The EXIT command closes the NAMESCTL program.

Prerequisites:  

The NAMESCTL program must be loaded.  

Password Required:  

No  

Syntax:  

From the NAMESCTL program: EXIT  

Arguments:  

None  

Usage Notes:  

EXIT has no effect on any Names Servers.

It affects only the NAMESCTL program.

The EXIT command is identical to the QUIT command.  

Example:  

NAMSCTL> EXIT
NAMESCTL finished. 

Purpose:  

Drops all stored non-authoritative data from the Names Server cache.  

Prerequisites:  

Only relevant with an environment with multiple regions. (In central administration there is no non-authoritative data.)  

Password Required:  

Yes  

Syntax:  

From the operating system prompt:

NAMESCTL FLUSH [server] ...

From the NAMESCTL program:

FLUSH [server] ...

Arguments:  

Zero or more Server names separated by a space. When no arguments are supplied, only the current Names Server's cache is flushed of the foreign names  

Usage Notes:  

FLUSH erases all foreign data that has been cached. Typically, you should flush the foreign data cache when:

- A large volume of data changes in the network and the normal TTL aging mechanism will take too long.

- When unidentifiable errors in name resolution of cached foreign data are occurring. Flushing all foreign data from the cache forces it to be looked up again when it is requested the next time.  

Examples:  

NAMESCTL>FLUSH
Confirm [yes or no]: yes

Purpose:  

Drops one or more specific non-authoritative names from the current Names Server's cache.  

Prerequisites:  

Only meaningful with an environment with multiple regions. (In central administration, there is no non-authoritative data.)  

Password Required:  

Yes  

Syntax:  

From the operating system prompt:

NAMESCTL FLUSH_NAME name

From the NAMESCTL program:

FLUSH_NAME name

Arguments:  

A single name  

Usage Notes:  

FLUSH_NAME erases only data cached from outside the Names Server's region (that is, non-authoritative data). It is typically flushed when a name is behaving unusually, suggesting the source copy may have changed.

FLUSH_NAME removes the name from the current foreign data cache as well as any other Servers between the current region and the authoritative region.

Names are flushed from the current Names Server. The current Names Server is either the default preferred Names Server or the one set by using the SET SERVER command.  

Examples:  

NAMESCTL>FLUSH_NAME MOUNTAIN.ACME.COM

Purpose:  

Provides details of the NAMESCTL commands.

Prerequisites:  

None.  

Password Required:  

No  

Syntax:  

From the operating system prompt:

NAMESCTL HELP [command]

From the NAMESCTL program:

HELP [command]

Arguments:  

commands  

Usage Notes:  

Help provides brief reminders of the function of each command in NAMESCTL. When no arguments are supplied, help shows the list of valid commands.

When you supply an argument, a one line description of that command's function is displayed.

Example:  

NAMESCTL> HELP

The following operations are available

An asterisk (*) denotes a modifier or extended 
command:
exit
flush
flush_name
log_stats
ping
query
quitreload
repeat*
reset_stats
restart set*
show
shutdown
start
startup
status
stop version

Purpose:  

Logs the current set of Names Server statistics to the configured log file for that Names Server.  

Prerequisites:  

None  

Password Required:  

Yes  

Syntax:  

From the operating system prompt:

NAMESCTL LOG_STATS [server] ...

From the NAMESCTL program:

LOG_STATS [server]

Arguments:  

Zero or more Names Server names separated by a space. When no arguments are supplied, only the statistics for the current Names Server are reset.  

Usage Notes:  

Statistics may be logged if the STATUS command or other behavior indicates some data that you would like to capture in the log. LOG_STATS does not affect the current LOG_STATS_INTERVAL.  

Example:  

NAMESCTL>LOG_STATS
Statistics counters logged.

Purpose:  

Registers the password for privileged Names Server operations such as RELOAD and STOP.  

Prerequisites:  

The NAMESCTL program must be loaded.  

Password Required:  

N/A  

Syntax:  

From the NAMESCTL program:

PASSWORD [password]

Arguments:  

Text string matching the value encrypted in the current Names Server parameter NAMES.PASSWORD.  

Usage Notes:  

PASSWORD does not change the Names Server's password. It simply sets a NAMESCTL variable. Then, the value stored is sent from NAMESCTL with any command request to the Names Server, and the value is compared to the value configured on the Names Server. If they match, operations requiring passwords are allowed.

Only "privileged" operations are affected, that is, operations that alter the functioning of the Names Server. Operations such as SHOW or STATUS are not considered privileged, and do not require a password.

The password can either be passed as an argument of the PASSWORD command, or if no argument is given, it will be prompted for. Note that the input is not displayed on the screen as it is typed.

When passed over the network the password is ALWAYS encrypted, regardless of how it is set.  

Example:  

NAMESCTL> PASSWORD OPEN_SESAME
NAMESCTL> PASSWORD
Enter name server password: 

Purpose:  

Contacts the current Names Server, or named server(s), and display the request/response time.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system prompt:

NAMESCTL PING [server_name] ...

From the NAMESCTL program:

PING [server_name] ...

Arguments:  

Zero or more Names Server names separated by a space. When no arguments are supplied, only the current Names Server is pinged.  

Usage Notes:  

Ping serves two basic purposes:

It ensures that a Names Server is functioning.

-It shows typical response times from the location of the NAMESCTL user to a Names Server.  

Example:  

NAMESCTL> ping NSERVER.world
Round trip time is 0.04 seconds

Purpose:  

Tests or retrieves the contents of a network object stored in the Names Server.  

Prerequisites:  

None  

Password Required:  

No  

Syntax  

From the operating system prompt:

NAMESCTL QUERY object_name [object_type] 
[modifiers]

From the NAMESCTL program:

QUERY name  [type]  [modifiers]

VALID TYPES:

• A.SMD: Network addresses, as with database service definitions.
• CNAME.SMD:Alias name (sometimes referred to as "canonical name").
• DL.RDBMS.OMD: Database link.
• NS.SMD: Names Server addresses. System data used to communicate between Names Servers.
• V1ADD.NPO.OMD: SQL*Net Version 1 connect string

VALID MODIFIERS:

• AUTHORITY - Forces the query to be resolved at the source of the data (in the administrative region where the data is considered local) even if the data is in the local cache. This could be used if the administrator suspects that the data has changed at the source.
• NOFORWARD - Query for the data, but don't forward the request. When the data is not local, and noforward is specified, the query will not be resolved.
• TRACE - Allows a trace of the path to the answer. This is useful whenever you want to find out which Names Servers the request went to.

Arguments:  

Mandatory network object name and network object type  

Usage Notes:  

QUERY can be used to test that a defined piece of data can be found, and that the contents are correct.

The QUERY command always operates on the current Names Server, either the default, or as specified using the SET SERVER command.

If the QUERY command is used with just a name as a parameter, the Names Server responds with the number of pieces of data with that name, and the time required to complete the operation.

If the QUERY command is used with the name and type supplied as arguments; the specific name is looked up and returned to the user.

The QUERY command can take multiple arguments if appropriate. For example:

QUERY NAME.WORLD A.SMD AUTHORITY TRACE

Example:  

NAMESCTL> QUERY BONES.DEM.MEDICINE A.SMD
Total response time:0.04 seconds
Response status:normal, successful completion
Authoritative answer:yes
Number of answers:1
Canonical name:bones.dem.medicine
TTL: 1 day
Alias translations:
    from:bones.dem.medicine
    to: bones.dem.medicine
Answers:
    data type is "a.smd"
        Syntax is 
ADDR:...(DESCRIPTION=(ADDRESS=
(PROTOCOL=TCP)(Host=cowboy)
(Port=1522))(CONNECT_DATA=(SID=rodeo)))

Purpose:  

Quits the NAMESCTL program.

Prerequisites:  

The NAMESCTL program must be loaded.  

Password Required:  

No  

Syntax:  

From the NAMESCTL program:

QUIT

Arguments:  

None  

Usage Notes:  

QUIT has no effect on any Names Servers. It affects only the NAMESCTL program.

The QUIT command is functionally equivalent to the EXIT command.  

Example:  

NAMESCTL> EXIT
NL-00851: NAMESCTL Finished

Purpose:  

Registers a network object to a Names Server  

Prerequisites:  

None  

Syntax:  

From the NAMESCTL program:
register object_name [-t type_of_service] 
[-d address_data] [-h hostname] 
[-l listener_name]

Arguments:  

Mandatory object name. The service, address data, and host are not necessary to make the registration process appear to work. However, they are necessary to make the registration useful. In other words, an object name registered without an address cannot be used.  

Usage Notes:  

Provides a manual mechanism for registering a service, its type, its hostname, and its address. Both the type of service and the data may be any valid string, but the typical registration has either "database" or "listener" as type of service, and the TNS address as the data.

The object registration is propagated to all other well known Names Servers in the region.  

Example:  

NAMESCTL> register parts -t oracle_database -d (DESCRIPTION= 
(ADDRESS= (PROTOCOL=TCP)(HOST=nineva)(PORT=1521)) 
(CONNECT_DATA=(SID=db3)))

Purpose:  

Forces the server to check immediately for data changes in its administrative region, and if there are any, reloads all database service names, global database links, and aliases.  

Prerequisites:  

None  

Password Required:  

Yes  

Syntax:  

From the operating system prompt:

NAMESCTL RELOAD [servers] ...

From the NAMESCTL program:

RELOAD [servers] ...

Arguments:  

Zero or more Names Server names separated by a space. When no arguments are supplied, only the current Names Server is reloaded.  

Usage Notes:  

All Names Servers load their data directly from the database specified by the names.admin_region configuration parameter in the Names Server configuration file.

In an environment with multiple regions, RELOAD affects only the data for the current administrative region. All foreign data in the cache is unchanged.  

Example:  

NAMESCTL>RELOAD
Server reloaded.

Purpose:  

Creates the file which lists local Names Servers and their addresses.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system prompt:

NAMESCTL REORDER_NS [NS_ADDRESS] 

From the NAMESCTL program:

REORDER_NS [NS_ADDRESS] 

Arguments:  

An optional Names Server address will be used as the initial server to contact.  

Usage Notes:  

This command generates the file which defines Names Server names and addresses to enable clients to contact Names Servers for name lookup.

The REORDER_NS command does the following;

1. Finds a Names Server. It looks in the local profile (SQLNET.ORA) for a Preferred Names Server parameter, or trys calling a well-known servers. It uses the address argument if it is present.
2. Sends a query for all the Names Servers in the local region.
3. Sends a 'ping' to each of these servers.
4. Sorts the list of servers by increasing order of response time.
5. Writes a Names Server List file with the sorted list of names and addresses.

Example:  

NAMESCTL> REORDER_NS (address= 
(protocol=tcp)(host=nineva)(port=1383))

Purpose:  

Used to perform QUERY, REGISTER, TIMED_QUERY, or UNREGISTER multiple times to compute average return rates.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system prompt:

NAMESCTL REPEAT number QUERY type

From the NAMESCTL program:

REPEAT number QUERY type 

where number is an integer and type is as shown in the QUERY command.  

Arguments:  

None  

Usage Notes:  

Repeat is useful for understanding the average response time over a number of requests.

Do not specify too large a number here; while the number of iterations are occurring, the NAMESCTL program cannot do anything else.  

Example:  

NAMESCTL> repeat 10 query manatee a.smd
Number of requests: 10
Average response time: 0.01 seconds
Minimum response time: 0.01 seconds
Maximum response time:0.04 seconds
Total response time:0.14 seconds
Response status:normal, successful completion
Authoritative answer:yes
Number of answers: 1
TTL: 1 day
Answers:
    data type is "a.smd"
        Syntax is ADDR:(DESCRIPTION=(ADDRESS=
(PROTOCOL=TCP)(Host=salmon)
(Port=1522))(CONNECT_DATA=(SID=otter)))

Purpose:  

Resets the Names Server statistics to the original values of the Names Server at startup.  

Prerequisites:  

None  

Password Required:  

Yes  

Syntax:  

From the operating system prompt:

NAMESCTL RESET_STATS [server]

From the NAMESCTL program:

RESET_STATS [server]

Arguments:  

Zero or more Names Server names separated by a space. When no arguments are supplied, only the current Names Server's statistics are reset.  

Usage Notes:  

RESET_STATS has the same effect as waiting for the RESET_STATS_INTERVAL to conclude, except that it happens immediately.  

Example:  

NAMESCTL> RESET_STATS
Confirm [yes or no]: yes
Server statistics reset.

Purpose:  

Initiates a reset of a Names Server to its original state at startup.  

Prerequisites:  

None  

Password Required:  

Yes  

Syntax:  

From the operating system prompt:

NAMESCTL RESTART [server]

From the NAMESCTL program:

RESTART [server]

Arguments:  

Zero or more Names Server names separated by a space. When no arguments are supplied, only the current Names Server is restarted.  

Usage Notes:  

RESTART is the same as STARTUP except that the Names Server is already running.

Data is reloaded, statistics are reset, and all foreign data is flushed. Valid foreign cache data (that is, data with a TTL greater than 0) is retrieved from the checkpoint files. (The TTL value must be set to more than 0.)  

Example:  

NAMESCTL> RESTART
Confirm [yes or no]: yes
Server restarted.

Purpose:  

Sets how often all collected information about foreign regions is saved in the Names Server cache file.  

Syntax:  

From the operating system:

NAMESCTL SET CACHE_CHECKPOINT_INTERVAL time

From NAMESCTL program:

SET CACHE_CHECKPOINT_INTERVAL time

Arguments:  

Time is in seconds

For example, to increase the CACHE_CHECKPOINT_INTERVAL to 36 hours, the following will work:

SET CACHE_CHECKPOINT_INTERVAL 129600

Usage Notes  

Minimum: 10 seconds

Maximum: 259200 (3 days)

Default: 0 (disabled)  

Example:  

NAMESCTL> SET CACHE_CHECKPOINT_INTERVAL 10

Purpose:  

Sets or changes the default domain for the NAMESCTL client.

Prerequisites:  

The NAMESCTL program must be loaded.  

Password Required:  

No  

Syntax:  

From the NAMESCTL program:

SET DEFAULT_DOMAIN domain_name

Arguments:  

one domain name  

Usage Notes:  

The existence of the DEFAULT_DOMAIN parameter allows names to be unqualified for names in that domain. For example, with DEFAULT_DOMAIN set to US.ACME the global name WIDE.US.ACME could be queried using:

NAMESCTL> QUERY WIDE

The initial value of DEFAULT_DOMAIN is set when the NAMESCTL program is started from the NAMES.DEFAULT_DOMAIN parameter in the client profile (SQLNET.ORA).

When no arguments are specified, the default is read and assigned from the client profile (SQLNET.ORA).

SET DEFAULT_DOMAIN could be used to simplify working on a set of names within a single domain, then a set in another.  

Example:  

NAMESCTL> SET DEFAULT_DOMAIN US.ACME
Default domain is now "US.ACME"

Purpose:  

Turns on or off name request forwarding for a Names Server  

Prerequisites:  

Names Server must be running  

PasswordRequired:  

Yes  

Syntax:  

From the operating system:

NAMESCTL SET FORWARDING_AVAILABLE OFF

From the NAMESCTL program:

SET FORWARDING_AVAILABLE OFF

Arguments:  

Time arguments are:

[[ON|OFF] [YES|NO]]

Restrictions:  

Default Value: 0 (ON)  

Usage Notes:  

This setting is intended only for Names Servers that have no local clients and are exclusively handling requests from foreign Names Servers. This usually would only apply to Names Servers in the root region when the root is configured without clients or services. If such a server is a performance bottleneck in cross-region request processing then disabling forwarding in that Names Server will cut its workload in half. Rather than forward the request and return the answer the Names Server simply tells the requestor the address of the Names Server that can answer the request. Note that there is no overall reduction in work; the work is simply displaced from the non-forwarding Names Server to the requesting Names Server.

WARNING: If SET FORWARDING_AVAILABLE is set to off, any clients who rely directly on that Names Server will be unable to resolve foreign names. Clients are not capable of redirecting their requests as Names Servers would. Their requests will fail at that point, even if other Names Servers are listed in the NAMES.PREFERRED_SERVERS configuration parameter.  

Example:  

NAMESCTL> SET FORWARDING_AVAILABLE OFF 
Request processing is now disabled. 

Purpose:  

Changes the log filename.  

Prerequisites:  

None  

PasswordRequired:  

Yes  

Syntax:  

From the operating system:

NAMESCTL SET LOG_FILE_NAME filename

From the NAMESCTL program:

SET LOG_FILE_NAME filename

Arguments:  

filename of the log file.  

Usage Notes:  

The LOG_FILE_NAME changes the destination of all logging messages.  

Example:  

NAMESCTL> SET LOG_FILE_NAME namesvr1

Purpose:  

Changes the frequency with which the statistics are logged to the log file.  

Prerequisites:  

None  

PasswordRequired:  

Yes  

Syntax:  

From the operating system:

NAMESCTL SET LOG_STATS_INTERVAL time

From the NAMESCTL program:

NAMESCTL>SET LOG_STATS_INTERVAL time

Arguments:  

Time is in one of the following formats:

seconds

or

[<n> DAY[S]] [<hh>:<mi>:<ss>]

For example, to increase the LOG_STATS_INTERVAL to 36 hours, either of the following will work:

SET LOG_STATS_INTERVAL 129600

SET LOG_STATS_INTERVAL 1 DAY 12:00:00

You can specify any valid combination, such as the number of days combined with number of hours, minutes, and seconds; or just the number in hours (and not specify the number of days).  

Restrictions:  

Minimum Value: 10 seconds

Maximum Value: no maximum

Special Value: 0 (which means never reset)

Default value: 0 (no logging)  

Usage Notes:  

The LOG_STATS_INTERVAL value is initially set based on the value configured in the Oracle Network Manager, or the value in NAMES.LOG_STATS_INTERVAL in the SQLNET.ORA file when the Names Server is loaded. By default, the value is 0 (no logging). This command is intended to override that value during server operation.  

Example:  

NAMESCTL> SET LOG_STATS_INTERVAL 7200
Statistic counter logging interval is now 2 
hours

Purpose:  

Sets the level at which the NAMESCTL program can be traced.  

Prerequisites:  

None  

PasswordRequired:  

Yes  

Syntax:  

From the operating system:

NAMESCTL SET NAMESCTL_TRACE_LEVEL 
[OFF|USER|ADMIN|SUPPORT]

From the NAMESCTL program:

NAMESCTL>SET NAMESCTL_TRACE_LEVEL 
[OFF|USER|ADMIN|SUPPORT]

Arguments:  

OFF, USER, ADMIN, SUPPORT  

Usage Notes:  

Tracing assists in diagnosing unexpected or unidentifiable failures in processing the NAMESCTL program. Tracing writes a series of events from normal NAMESCTL processing to an operating system file for review by the administrator.

Tracing output is at three levels OFF (none), USER (basic information), or ADMIN.

When no arguments are supplied, the setting is reset to the value in the client's SQLNET.ORA file. The default setting is OFF.  

Example:  

NAMESCTL> SET NAMESCTL_TRACE_LEVEL ADMIN
Controller's local trace level changed from 0 to 4

Purpose:  

Register the password for privileged Names Server operations such as RELOAD and STOP.  

Prerequisites:  

The NAMESCTL program must be loaded.  

Password Required:  

N/A  

Syntax:  

From the NAMESCTL program:

NAMESCTL>SET PASSWORD [password]

Arguments:  

Text string matching the value stored in the current Names Server parameter NAMES.PASSWORD.  

Usage Notes:  

SET PASSWORD does not change the Names Server's password. It simply sets a NAMESCTL variable that is sent over to the Names Server with any NAMESCTL command and is compared to the value configured on the Names Server. If they match, operations requiring passwords are allowed.

Only "privileged" operations are affected, that is, operations that alter the functioning of the Names Server. Operations such as SHOW or STATUS are not considered privileged, and do not require a password.

The password can either be passed as an argument of the SET PASSWORD command, or if no argument is given, it will be prompted for. Note that the input is not displayed on the screen as it is typed.

When passed over the network the password is ALWAYS encrypted, regardless of how it is set.  

Example:  

NAMESCTL> SET PASSWORD OPEN_SESAME
NAMESCTL> SET PASSWORD
Enter name server password: 

Purpose:  

Determine whether the current Names Server will respond to requests.  

Prerequisites:  

None  

Password Required:  

Yes  

Syntax:  

From the operating system:

NAMESCTL REQUESTS_ENABLED [ON|OFF]

From the NAMESCTL program:

NAMESCTL>SET REQUESTS_ENABLED [ON|OFF]

Arguments:  

ON or OFF  

Usage Notes:  

Setting this property to OFF will send refusals to all clients that approach with Names requests. This is primarily useful for diagnostics when a Names Server is functioning unexpectedly.  

Example:  

NAMESCTL> SET REQUESTS_ENABLED OFF
Confirm [yes or no]: yes
General request processing is now disabled

Purpose:  

Changes the time between the statistics being reset to zero or initial values in the current server.  

Prerequisites:  

None  

Password Required:  

Yes  

Syntax:  

From the operating system:

NAMESCTL SET RESET_STATS_INTERVAL time

From the NAMESCTL program:

NAMESCTL>SET RESET_STATS_INTERVAL time

Arguments:  

Time is in one of the following formats:

seconds

[n DAY[S]] [hh:mi:ss]

For example, to increase the RESET_STATS_INTERVAL to 72 hours, either of the following will work:

SET RESET_STATS_INTERVAL 259200

SET RESET_STATS_INTERVAL 3 DAYS  

Restrictions:  

Minimum Value: 10 seconds

Maximum Value: no maximum

Default value: 0 (never reset)  

Usage Notes:  

The RESET_STATS_INTERVAL value is initially set based on the NAMES.RESET_STATS_INTERVAL parameter when the Names Server is loaded. This command is intended to override that value during Names Server operation.  

Example:  

NAMESCTL> SET RESET_STATS_INTERVAL 1 DAY
Statistic counter reset interval is now 24 hours

Purpose:  

Change the current Names Server.  

Prerequisites:  

The NAMESCTL program must be loaded  

Password Required:  

No  

Syntax:  

From the NAMESCTL program:

NAMESCTL>SET SERVER [server_name or server_address]

Arguments:  

valid server name or valid server address  

Usage Notes:  

SET SERVER allows switching between multiple Names Servers while running the NAMESCTL utility. The qualifier can be a name where the name is defined in the memory of the current Names Server, or it can be the TNS address of any Names Server.

The Names Server name specified is resolved through normal name lookup. Another Names Server can only be set if the current Names Server knows or can retrieve its address. If no current Names Server is set, you must type a TNS address to complete this command. IF there are no arguments, use NAMES.PREFERRED_SERVERS.  

Example:  

NAMESCTL> SET SERVER SERVER1.US.ACME

Purpose:  

Changes the trace destination filename  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SET TRACE_FILE_NAME filename

From NAMESCTL program:

NAMESCTL>SET TRACE_FILE_NAME filename

Arguments:  

filename  

Example:  

NAMESCTL> SET TRACE_FILE_NAME namesvr1

Purpose:  

Changes the TRACE_LEVEL for tracing the current Names Server.  

Prerequisites:  

None  

Password Required:  

Yes  

Syntax:  

From the operating system:

NAMESCTL SET TRACE_LEVEL 
[OFF|USER|ADMIN|SUPPORT]

From the NAMESCTL program:

NAMESCTL>SET TRACE_LEVEL 
[OFF|USER|ADMIN|SUPPORT] 

Arguments:  

OFF, USER, ADMIN, SUPPORT  

Usage Notes:  

Tracing assists in diagnosing unexpected or unidentifiable failures in processing the current Names Server. Tracing writes a series of events from normal Names Server processing to an operating system file for review by the administrator.

Tracing output is at three levels OFF (none), USER (basic information), ADMIN (information required for administrator), or SUPPORT (information required for customer support).

After the TRACE_LEVEL is set, tracing begins immediately. All operations are traced until it is reset to trace level OFF.

Trace files can grow very large. Remember to turn trace level off after diagnosing the problem.  

Example:  

NAMESCTL> SET TRACE_LEVEL ADMIN
Trace level is now 6. 

Purpose:  

Shows the frequency with which the Names Server's cache is written to the checkpoint file.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW CACHE_CHECKPOINT_INTERVAL

From the NAMESCTL program:

NAMESCTL>SHOW CACHE_CHECKPOINT_INTERVAL

Arguments:  

None  

Usage Notes:  

The CACHE_CHECKPOINT_INTERVAL is initially set with the value in NAMES.CACHE_CHECKPOINT_INTERVAL in the NAMES.ORA file. By default, the value is 0, which disables cache_checkpoint. Data written to the cache checkpoint file includes service names and addresses, and Names Server addresses which were learned by the Names Server as a result of forwarding a query to a foreign region on behalf of the client.  

Example:  

NAMESCTL> SHOW CACHE_CHECKPOINT_INTERVAL
Cache checkpoint interval is currently 8 
minutes 20 seconds

Purpose:  

Shows whether the Names Server is forwarding requests for foreign names or redirecting them.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW FORWARDING_AVAILABLE

From the NAMESCTL program:

NAMESCTL>SHOW FORWARDING_AVAILABLE

Arguments:  

Zero or more Names Servers separated by a space. If no names are given, then the setting is displayed for the current server.  

Usage Notes:  

By default, all Names Servers forward requests for foreign names. If forwarding is disabled, then requests for foreign names will be redirected to a Names Server in the region which is authoritative to the requested name.

Disabling forwarding can reduce the load on a particular server, and will also make it impossible for direct clients of that server to resolve foreign names. Clients cannot be redirected, only other Names Servers. See also SET FORWARDING_AVAILABLE.  

Example:  

NAMESCTL> SHOW FORWARDING_AVAILABLE
Request forwarding is currently enabled

Purpose:  

Display the default domain for the NAMESCTL client.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW DEFAULT_DOMAIN

From the NAMESCTL program:

NAMESCTL> SHOW DEFAULT_DOMAIN

Arguments:  

None  

Usage Notes:  

The existence of the DEFAULT_DOMAIN parameter allows names to be unqualified for names in that domain. For example, with DEFAULT_DOMAIN set to ACME.WORLD, the global name WIDE.ACME.WORLD could be queried using:

NAMESCTL> QUERY WIDE
Total response time:   0.20 seconds
Response status: normal, successful completion
Authoritative answer:  yes
Number of answers:     0
TTL:                   1 day

The initial value of DEFAULT_DOMAIN is set when the NAMESCTL program is started from the NAMES.DEFAULT_DOMAIN parameter in the SQLNET.ORA file.

SHOW DEFAULT_DOMAIN is used when the user is unsure of the current default domain, or wants to know the default for the current configuration.  

Example:  

NAMESCTL> SHOW DEFAULT_DOMAIN
Current default domain is "world"

Purpose:  

Shows the name of the file where the Names Server writes the logging information.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW LOG_FILE_NAME

From the NAMESCTL program:

SHOW LOG_FILE_NAME

Arguments:  

None  

Usage Notes:  

The LOG_FILE_NAME is initially set with the value in NAMES.LOG_FILE_NAME in the NAMES.ORA file.The default value is platform-specific, but is typically NAMES.LOG and is located in the network/log subdirectory during Oracle installation. This file must be writable to the Names Server.  

Example:  

NAMESCTL> SHOW LOG_FILE_NAME
Log file name is currently 
/private/ora23/network/names.log

Purpose:  

Displays the frequency with which the statistics are logged to the log_file.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW LOG_STATS_INTERVAL

From NAMESCTL program:

SHOW LOG_STATS_INTERVAL

Arguments:  

Zero or more Names Servers separated by a space. If no names are given, then the setting is displayed for the current server.  

Usage Notes:  

The LOG_STATS_INTERVAL is initially set with the value in NAMES.LOG_STATS_INTERVAL in the NAMES.ORA file. By default, the value is 0, or no logging.  

Example:  

NAMESCTL> SHOW LOG_STATS_INTERVAL
Statistic counter logging is currently disabled

Purpose:  

Displays control of the level at which the NAMESCTL program is being traced.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW NAMESCTL_TRACE_LEVEL

From the NAMESCTL program:

SHOW NAMESCTL_TRACE_LEVEL

Arguments:  

None  

Usage Notes:  

Tracing assists in diagnosing unexpected or unidentifiable failures in processing the NAMESCTL program. Tracing writes a series of events from normal NAMESCTL processing to an operating system file for review by the administrator.

Tracing output is at three levels OFF (none), USER (basic information), or ADMIN (maximum amount of information).

SHOW NAMESCTL_TRACE_LEVEL is the only guaranteed source of what the current tracing level is.  

Example:  

NAMESCTL> SHOW NAMESCTL_TRACE_LEVEL
Controller's trace level is currently 0

Purpose:  

Shows whether or not the Names Server is responding to requests.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW REQUESTS_ENABLED

From the NAMESCTL program:

SHOW REQUESTS_ENABLED

Arguments:  

Zero or more Names Servers separated by a space. If no names are given, then the setting is displayed for the current server.  

Usage Notes:  

If REQUESTS_ENABLED is off, all requests to the Names Server will be refused. This parameter is intended for diagnostic purposes only.  

Example:  

NAMESCTL> SHOW REQUESTS_ENABLED
General request processing is currently 
enabled.

Purpose:  

Shows the interval set on how often the statistics are dumped to the log file.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW RESET_STATS_INTERVAL

From the NAMESCTL program:

SHOW RESET_STATS_INTERVAL

Usage Notes:  

If RESET_STATS_INTERVAL is initially set with the value in NAMES.RESET_STATS_INTERVAL. By default the value is set to 0, or no reset. This results in the Names Server accumulating statistics the entire time it runs. For example, if statistics are reset every day, then the statistics will represent totals for the day rather than the entire time the server has been running.  

Example:  

NAMESCTL> SHOW RESET_STATS_INTERVAL
Statistic counter reset interval is currently 
5 minutes

Purpose:  

Displays the current Names Server  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW SERVER

From the NAMESCTL program:

SHOW SERVER

Arguments:  

None  

Usage Notes:  

SHOW SERVER displays the current Names Server that commands will operate on.  

Example:  

NAMESCTL> SHOW SERVER
currently managing name server 
"NameServer.us.oracle.com

Purpose:  

Display the general status information about the Names Server.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW STATUS

From the NAMESCTL program:

SHOW STATUS

Arguments:  

Zero or more Names Servers separated by a space. If no names are given, then the setting is displayed for the current server.  

Usage Notes:  

Shows the current state of a Names Server.

Identical to the command STATUS.  

Example:  

NAMESCTL> SHOW STATUS

Purpose:  

Display the next occurrence of all system queries.  

Prerequisites:  

This is only relevant for distributed configurations. There are no system queries with only one administrative region.  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW SYSTEM_QUERIES

From the NAMESCTL program:

SHOW SYSTEM_QUERIES

Arguments:  

None  

Usage Notes:  

System queries are performed at intervals to keep information among Names Servers current.

There is no specific action that can change the activities listed as system queries. Being able to show them gives the administrator an understanding of when a system change will occur, and may assist in a decision to RESTART, thus forcing system data to be reloaded sooner.  

Example:  

NAMESCTL> SHOW SYSTEM_QUERIES
System query index number:1
Query ID:49824
Query next issued in:2 hours 55 min 3.84 
seconds
Query state:2
Name:""
Desired data type:ns.smd

Purpose:  

Displays the TRACE_FILE_NAME for the current Names Server.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW TRACE_FILE_NAME

From the NAMESCTL program:

SHOW TRACE_FILE_NAME

Arguments:  

None  

Usage Notes:  

The TRACE_FILE_NAME is initially set with the value in the NAMES.TRACE_FILE_NAME in the NAMES.ORA file.The default value is platform-specific, but is typically NAMES.TRC and is located in the network/trace subdirectory during the Oracle installation. This file must be a valid filename, and the file must be writable to the Names Server.

This file is only used if tracing is enabled using the NAMES.TRACE_LEVEL.  

Example:  

NAMESCTL> SHOW TRACE_FILE_NAME
Trace file name is currently 
/private/ora23/network/names.trc

Purpose:  

Displays the TRACE_LEVEL for tracing the current Names Server.  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW TRACE_LEVEL

From the NAMESCTL program:

SHOW TRACE_LEVEL

Arguments:  

None  

Usage Notes:  

Tracing assists in diagnosing unexpected or unidentifiable failures in processing the current Names Server. Tracing writes a series of events from normal Names Server processing to an operating system file for review by the administrator.

Tracing output is at three levels OFF (none), USER (basic information), or ADMIN (maximum amount of information).

SHOW TRACE_LEVEL is the only guaranteed source of what the current tracing level is. Even if the TRACE_LEVEL is configured in the Names Server configuration file, a previous call from the NAMESCTL program may have overridden it.  

Example:  

NAMESCTL> SHOW TRACE_LEVEL
Trace level is currently 0

Purpose:  

Displays the current version and name of the Names Server  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL SHOW VERSION

From the NAMESCTL program:

SHOW VERSION

Arguments:  

Zero or more Names Servers separated by a space. If no names are given, then the setting is displayed for the current server.  

Usage Notes:  

This banner identifies the server by name and version. This can be useful when clearing up minor difficulties. This command is enabled every time you connect NAMESCTL to a server.  

Example:  

NAMESCTL> SHOW VERSION

Purpose:  

Stops one or more Names Servers.  

Prerequisites:  

Names Server must be started.  

Password Required:  

Yes  

Syntax:  

From the operating system:

NAMESCTL SHUTDOWN [server]

From the NAMESCTL program:

SHUTDOWN [server]

Arguments:  

Zero or more Names Server names separated by a space. When no arguments are supplied, only the current Names Server is shut down.  

Usage Notes:  

SHUTDOWN stops the current Names Server and unloads the program from memory. A Names Server should only be shut down for operational reasons like upgrades or machine maintenance. The preferred way to stop and start a Names Server is using the RESTART command because you can perform it from anywhere in the network. If SHUTDOWN and START are processed individually, they must occur on the Names Server machine.

SHUTDOWN is identical to STOP.  

Example:  

NAMESCTL> SHUTDOWN
Confirm [yes or no] yes
Server shut down.

Purpose:  

Loads the Names service program and starts loading system and local administrative region data.  

Prerequisites:  

Names Server must be stopped.  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL START  

From the NAMESCTL program:

NAMESCTL> START names.parameter = value

Arguments:  

None  

Usage Notes:  

START is the command used to initially load a Names Server into memory. At startup, the Names Server reads its configuration files to set up its operating parameters, then loads all data for the administrative region.

Security on Names Server startup is supplied through the operating system Names is installed on. Because Names must be started from a local session, network security is not an issue. See the Oracle installation manual for your platform for more details.

START is identical to STARTUP.  

Example:  

Starting "/oracle/bin/names"...server 
successfully started
Currently managing name server "NSERVER.world"
...
Server name: NSERVER.world
Server has been running for: 0.86 seconds
Request processing enabled: yes
Request forwarding enabled: no
Requests received: 0
Requests forwarded: 0
Data items cached: 0...

Purpose:  

Starts the client cache daemon process.  

Prerequisites:  

The client cache daemon process must be stopped.

A Names Server List must exist before you run the client cache daemon process.  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL START_CLIENT_CACHE 

From the NAMESCTL program:

NAMESCTL> START_CLIENT_CACHE

Arguments:  

None  

Usage Notes:  

Once started, the client cache daemon process will store all information received from a Names Server.  

Purpose:  

This command is identical to START  

Prerequisites:  

Names Server must be stopped.  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL STARTUP names.parameter = value

From the NAMESCTL program:

NAMESCTL> STARTUP names.parameter = value

Arguments:  

None  

Usage Notes:  

STARTUP is identical to START.  

Example:  

See example for START.  

Purpose:  

Displays statistics for one or more Names Servers as well as many of its internal settings.  

Prerequisites:  

Names Server must be started.  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL STATUS [server]

From NAMESCTL program:

STATUS [server]

Arguments:  

Zero or more Names Server names separated by a space. When no arguments are supplied, status is given only for the current Names Server.  

Usage Notes:  

STATUS shows the activity of the Names Server over time and its state at a point in time.  

Example:  

NAMESCTL> STATUS

Purpose:  

Stops one or more Names Servers  

Prerequisites:  

Names Server must be started.  

Password Required:  

Yes  

Syntax:  

From the operating system:

NAMESCTL STOP  [server]

From the NAMESCTL program:

STOP  [server]

Arguments:  

Zero or more Names Server names separated by a space. When no arguments are supplied, only the current Names Server is stopped.  

Usage Notes:  

STOP stops the current Names Server and unloads the program from memory. A Names Server should only be shut down for operational reasons like upgrades or machine maintenance. The preferred way to stop and start a Names Server is using the RESTART command because you can issue it from anywhere in the network. If STOP and START are processed individually, they must occur on the Names Server machine.

STOP is identical to SHUTDOWN.  

Example:  

NAMESCTL> STOP
Confirm [yes or no]: yes
Server shut down

Purpose:  

Show all registered data in the Names Server cache.  

Syntax:  

From the operating system:

NAMESCTL TIMED_QUERY

From the NAMESCTL program:

TIMED_QUERY [time] 

Usage Notes:  

TIMED_QUERY returns all objects that have been registered automatically by the listener or manually through NAMESCTL. The time argument returns all objects registered after a given time. To use the time argument, the first TIMED_QUERY dumps out all information available since startup. At the end of the first dump is a "last timestamp" number which gives a bookmark as to where the last dump of information ended. To see all logged data since that point, provide the "last timestamp" number in the time argument.  

Purpose:  

To remove a network object from a Names Server  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system

NAMESCTL UNREGISTER OBJECT_NAME 
(-d address_data) [-h hostname]
[-l listener_name]
From the NAMESCTL program:
UNREGISTER OBJECT_NAME (-d address_data) [-h hostname] [-l 
listener_name]

Arguments:  

Mandatory object name and the address, listener, or hostname that it was registered with.  

Usage Notes:  

Provides a manual mechanism for unregistering a service. The definition for that object is removed from the Names Servers in the region. If the object was registered with an address, listener name, or a hostname, the address, listener name, or hostname must be provided on the command line in order to unregister the object.  

Example:  

NAMESCTL> unregister parts -t oracle_database -d 
(DESCRIPTION= (ADDRESS=
(PROTOCOL=TCP)(HOST=nineva)(PORT=1387)) 
(CONNECT_DATA=(SID=db3)))

Purpose:  

Displays the current version and name of the Names Server  

Prerequisites:  

None  

Password Required:  

No  

Syntax:  

From the operating system:

NAMESCTL VERSION

From the NAMESCTL program:

VERSION

Arguments:  

Zero or more Names Servers separated by a space. If no names are given, then the setting is displayed for the current server  

Usage Notes:  

This banner identifies the server by name and version. This can be useful when clearing up minor difficulties. This command is enabled every time you connect NAMESCTL to a server.  

Example:  

NAMESCTL> VERSION

Purpose:  

To exit out of the CMCTL utility program.  

Prerequisites:  

None  

Example:  

CMCTL> exit

Purpose:  

To start Oracle Connection Manager.  

Prerequisites:  

Oracle Connection Manager must not be running.  

Arguments:  

cman - start both the administration and main processes

cm - start only the main process

adm - start only the administration process  

Example:  

CMCTL> start process_type

Purpose:  

To display basic statistical information including total relays, active relays, most relays out of total, total refused.  

Prerequisites:  

None  

Arguments:  

cman - display main process statistics

cm - display main process statistics  

Example:  

CMCTL> stats process_type

Purpose:  

To display basic information: version, start time, uptime.  

Prerequisites:  

None  

Arguments:  

cman - display both administration and main process information

cm - display only main process information

adm - display only administration process information  

Example:  

CMCTL> status process_type

Purpose:  

To stop Oracle Connection Manager.  

Prerequisites:  

Oracle Connection Manager must be running.  

Arguments:  

cman - stop both the administration and main processes

cm - stop only the main process

adm - stop only the administration process  

Usage Notes:  

Verify that all current connections have closed before stopping Oracle Connection Manager. If you issue a stop command while connections remain active, Oracle Connection Manager will remain open. Oracle Connection Manager will not stop until all active connections close. During this time, new users will not be able to connect through Oracle Connection Manager.  

Example:  

CMCTL> stop process_type