Name Server Query Syntax

This section describes the OpenAPI syntax for the statements used to access the Name Server.

Create Login Statement—Create a Login Definition

This statement creates a remote user authorization.

This statement has the following syntax:

create global|private login vnode username password

This statement has the following parameters:

• global|private

  Specifies a global or private object. A global object is available to all users on the local node. A private object is available to a single user.

• vnode

  Specifies the virtual node name to be associated with this authorization.

• username

  Specifies the name of the account to be used on the host machine of a remote installation.

• password

  Specifies the password of the remote account.

Examples: Create login statement

The following example creates a private user authorization on vnode apitest for user Tom:

create private login apitest tom tompassword

The following example creates a global user authorization on vnode dbtest using an installation password:

create global login dbtest * installationpassword

Destroy Login Statement—Destroy a Login Definition

This statement deletes a remote user authorization.

This statement has the following syntax:

destroy global|private login vnode

This statement has the following parameters:

• global|private

  Specifies a global or private object. A global object is available to all users on the local node. A private object is available to a single user.

• vnode

  Specifies the virtual node name to be associated with this authorization.

Examples: Destroy login statement

The following example destroys a private user authorization on vnode apitest:

destroy private login apitest

The following example destroys a private user authorization on all the vnodes where it occurs. Using a wildcard for the vnode parameter lets you destroy all instances of a particular login with a single query text statement:

destroy private login *

Create Password Statement—Define an Installation Password

This statement creates an installation password for the local installation.

This statement has the following syntax:

create global login local_vnode * password

This statement has the following parameters:

• local_vnode

  Specifies the name that has been configured as local_vnode parameter on the local installation. You can find this name on the Parameters tab for the Name Server in the Configuration Manager utility. (Alternatively, you can use the cbf utility at the command line.)

• password

  Specifies the installation password to be assigned to this installation.

Example: Create password statement

The following example defines an installation password for the local installation, which has a local_vnode name of apitest:

create global login apitest * apitest_password

Create Connection Statements—Create a Connection Data Definition

This statement creates a connection data definition. If a connection data definition exists that matches the specified one in all respects, the operation will have no effect, and no error will be reported.

This statement has the following syntax:

create connection global|private vnode net_addr protocol port

This statement has the following parameters:

• global|private

  Specifies a global or private object. A global object is available to all users on the local node. A private object is available to a single user.

• vnode

  Specifies the virtual node name to be associated with this connection data definition.

• net_addr

  Specifies the address or name of the remote node.

  Your network administrator specified this address or name when the network software was installed. Normally, the node name, as defined at the remote node, is sufficient for this parameter.

  The format of a net address depends on the type of network software that the node is using.

• protocol

  Specifies the Ingres keyword for the protocol used to connect to the remote node. Its value can be one of the following:

  • wintcp
  • lanman
  • nvlspx
  • decent
  • tcp_ip
• port

  Specifies the unique identifier used by the remote Communications Server for interprocess communication.

  The format of a listen address depends on the network protocol.

Example: Create connection statement

The following example creates a global connection data definition on vnode apitest, where net_addr=apitest, protocol=TCP/IP, and port=mg0:

create global connection apitest apitest tcp_ip mg0

Note: The virtual node name and the host are different objects, although typically they have the same value.

Destroy Connection Statement—Destroy a Data Definition

This statement deletes a connection data definition.

This statement has the following syntax:

destroy global|private connection vnode net_addr protocol port

This statement has the following parameters:

• global|private

  Specifies a global or private object. A global object is available to all users on the local node. A private object is available to a single user.

• vnode

  Specifies the virtual node name to be associated with this connection data definition.

• net_addr

  Specifies the address or name of the remote node.

  Your network administrator specifies this address or name when the network software is installed. Normally, the node name, as defined at the remote node, is sufficient for this parameter.

  The format of a net address depends on the type of network software that the node is using.

• protocol

  Specifies the Ingres keyword for the protocol used to connect to the remote node. Its value can be one of the following:

  • wintcp
  • lanman
  • nvlspx
  • decent
  • tcp_ip
• port

  Specifies the unique identifier used by the remote Communications Server for interprocess communication.

  The format of a listen address depends on the network protocol.

Examples: Destroy connection statement

The following example destroys a private connection data definition on vnode apitest, where net_addr=apitest, protocol=TCP/IP, and port=mg2:

destroy private connection apitest apitest tcp_ip mg2

The following example destroys all global connection data definitions on vnode payroll that include the TCP/IP protocol:

destroy global connection payroll * tcp_ip *

Show Connection Statement—Display Connection Data Definitions

This statement displays a connection data definition.

This statement has the following syntax:

show global|private connection vnode net_addr protocol port

This statement has the following parameters:

• global|private

  Specifies a global or private object. A global object is available to all users on the local node. A private object is available to a single user.

• vnode

  Specifies the virtual node name to be associated with this connection data definition.

• net_addr

  Specifies the address or name of the remote node.

  Your network administrator specifies this address or name when the network software is installed. Normally, the node name, as defined at the remote node, is sufficient for this parameter.

  The format of a net address depends on the type of network software that the node is using.

• protocol

  Specifies the Ingres keyword for the protocol used to connect to the remote node. Its value can be one of the following:

  • wintcp
  • lanman
  • nvlspx
  • decent
  • tcp_ip
• port

  Specifies the unique identifier used by the remote Communications Server for interprocess communication.

  The format of a listen address depends on the network protocol.

Example: Show connection statement

The following example displays global connection data definitions on vnode apitest, where net_addr is apitest:

show global connection apitest apitest* *

The following is an example of sample output from this operation:

global connection apitest apitest tcp_ip mg2

Create Attribute Statement—Create an Attribute Data Definition

This statement creates an attribute data definition.

This statement has the following syntax:

create global|private attribute vnode attr_name attr_value

This statement has the following parameters:

• global|private

  Specifies a global or private object. A global object is available to all users on the local node. A private object is available to a single user.

• vnode

  Specifies the virtual node name to be associated with this attribute data definition.

• attr_name

  Specifies the name of the attribute.

• attr_value

  Specifies the value of the attribute.

Example: Create attribute statement

The following example creates a global attribute definition on vnode apitest, where attr_name=connection_type and attr_value=direct:

create global attribute apitest connection_type direct

Destroy Attribute Statement—Destroy an Attribute Data Definition

This statement deletes an attribute data definition.

This statement has the following syntax:

destroy global|private attribute vnode attr_name attr_value

This statement has the following parameters:

• global|private

  Specifies a global or private object. A global object is available to all users on the local node. A private object is available to a single user.

• vnode

  Specifies the virtual node name to be associated with this attribute data definition.

• attr_name

  Specifies the name of the attribute.

• attr_value

  Specifies the value of the attribute.

Examples: Destroy attribute statement

The following example destroys a private attribute definition on vnode apitest, where attr_name=connection_type and attr_value=direct:

destroy private attribute connection_type direct

The following example destroys all global attribute data definitions for vnode payroll that include the connection_type attribute:

destroy global attribute payroll connection_type *

Display Attribute Statement—Display an Attribute Data Definition

This statement displays an attribute data definition.

This statement has the following syntax:

show global|private attribute vnode attr_name attr_value

This statement has the following parameters:

• global|private

  Specifies a global or private object. A global object is available to all users on the local node. A private object is available to a single user.

• vnode

  Specifies the virtual node name to be associated with this attribute data definition.

• attr_name

  Specifies the name of the attribute.

• attr_value

  Specifies the value of the attribute.

Examples: Display attribute statement

The following example displays all global attribute data definitions on vnode apitest:

show global attribute apitest * *

The following is an example of sample output from this operation:

global attribute apitest connection_type direct

Show Server Statement—Display Servers in the Local Installation

This statement displays servers in the local installation.

This statement has the following syntax:

show server server_class

This statement has the following parameter:

• server_class

  Specifies the name of the server class of the server to be displayed. To display all servers in the local installation, specify "servers."

Examples: Show server statement

The following example displays all servers in the local installation:

show server servers

The following example displays an Ingres server in the local installation:

show server ingres

How to Use ~V Marker in the Name Server Query Text

You can use a ~V marker in any of the subfields of the objects (such as login, connection, or attribute) and in the Type field in the Name Server query text. The ~V marker must be preceded and followed by a space character. Values for the parameter markers are sent with the query using IIapi_setDescriptor() and IIapi_putParams(), in the same order as the parameter markers appear in the query text.

Example: Using the ~V marker in name server query text

The following query text is a valid query text with the ~V marker:

show server ~V

When sent with parameter value of "servers," it is identical to the query:

show server servers

The advantage is that the query using ~V does not require the application to build the query text at runtime using values not available at compile time.