Overview of gloctl

Definition

gloctl is an interactive utility provided by GOLDILOCKS, which provides location to glocator and edits it.
gloctl communicates with glocator by using User Datagram Protocol (UDP) communication protocol.

Usage

gloctl [options]

Options

help

Description

It outputs the help message.

Example

$ gloctl --help

Usage:
 gloctl [options]

Options:

-c  --conf         User configure file
-i  --ip           Locator host ip
-p  --port         Locator port number
-o  --import       Import control FILE
-l  --silent       Suppress the display of result message and echoing commands
-r  --no-copyright Suppress display copy right and version
-h  --help         Print help message

conf

Description

It sets a Configuration file to communicate with glocator.  
If it is not set, $GOLDILOCKS_DATA/conf/goldilocks.gloctl.conf is used.

Example

$ gloctl --conf gloctl.conf

gLoctl>

The contents of gloctl.conf file above is as follows.

[GLOCTL]
# Port number (1024 ~ 49151)
PORT = 44581

# Locator address
LOCATOR_HOST = 127.0.0.1

# Locator port number (1024 ~ 49151)
LOCATOR_PORT = 42581

# Time out to receive message from glocator (second)
# second ( 0 ~ 2147483647 )
MESSAGE_TIMEOUT = 10

ip

Description

It sets IP address of glocator when starting gloctl. IP set value takes precedence when it is used together with DSN.

Example

$ gloctl --ip 127.0.0.1

gLoctl>

The port of glocator in the example above is obtained by using DSN default LOCATOR in odbc.ini.

port

Description

It sets the port of glocator when starting gloctl. The port set value takes precedence when it is used together with DSN.

Example

$ gloctl --port 42581

gLoctl>

IP of glocator in the example above is obtained by using DSN default LOCATOR in odbc.ini.

import

Description

It performs gloctl commands in batch within a file, not an interactive mode.

Example

$ gloctl --import import.txt

HELP                                                       
QUIT                                                       
IMPORT       {'FILE'}             Upload FILE to locations 
EXPORT       {'FILE'}             Download locations to FILE
ADD MEMBER   {DSN|{member_name {'host; port; db_home; agent_port;'}}} Add member location      
DROP MEMBER  {member_name}        Drop member location     
SET TIMEOUT  {second}             Set time for session timeout


Add member succeeded.

The contents of import.txt above is as follows.

HELP
ADD MEMBER G1N3 'HOST=127.0.0.1;PORT=24581;DB_HOME=g1n3_home;AGENT_PORT= 44581;'

silent

Description

It does not output the message of gloctl about the execution.

Example

$ gloctl --silent --import import.txt

no-copyright

Description

It does not output the message of gloctl's copyright and version about the execution.

Example

$ gloctl --no-copyright

gLoctl>

Interactive Command References

ADD MEMBER

Syntax

ADD MEMBER {DSN | member_name {'host; port; db_home; agent_port;'}}

Description

It adds a member to glocator. DSN existing in odbc.ini, a member name, and the required location information should be input.

The port is that of glsnr.
ADD MEMBER is used to update the information of an existing member. In this case, if the member is in the process of the failover, then the update fails.

Example

ADD MEMBER by using DSN of odbc.ini.

gLoctl> ADD MEMBER G1N1

Add member succeeded.

gLoctl>

The contents of odbc.ini is as follows.

[G1N1]
HOST=127.0.0.1
PORT=20101
DB_HOME= g1n1_home
AGENT_PORT=43581
LOCATOR_DSN=LOCATOR

Describe the location of a member, and add it.

gLoctl> ADD MEMBER G1N2 'HOST=127.0.0.1; PORT=20201; DB_HOME=g1n2_home; AGENT_PORT= 43581'

Add member succeeded.

gLoctl>

ADD SERVICE

Syntax

ADD SERVICE service_name {'member_name; ... '}

Description

It adds a service to glocator. The node belonging to the service should be managed in glocator, and it is ignored when the same node does not exist in glocator.

Example

Add the service s1 by using ADD SERVICE.

gLoctl> ADD SERVICE S1 'G1N1;G1N2;G2N1'

Add service succeeded.

gLoctl>

The contents of odbc.ini is as follows.

[GOLDILOCKS]
HOST=127.0.0.1
PORT=22581
LOCATOR_DSN=LOCATOR
LOCATOR_SERVICE=S1
[LOCATOR]
HOST=127.0.0.1
PORT=42581

When describing glocator properties in odbcinst.ini file and using glocator, then gsqlnet and other applications can access one of a server from the service list.

DROP MEMBER

Syntax

DROP MEMBER member_name

Description

It drops a member corresponding to member_name from glocator.

If a member is in the process of the failover, then the member can not be dropped.

Example

gLoctl> DROP MEMBER G1N2

Drop member succeeded.

gLoctl>

DROP SERVICE

Syntax

DROP MEMBER service_name

Description

It drops a service corresponding to service_name from glocator.

Example

gLoctl> DROP SERVICE S1

Drop service succeeded.

gLoctl>

EXPORT

Syntax

EXPORT {'FILE'}

Description

It receives the location information from glocator and stores it in a file.

Example

Download the location information in Location.txt file.

gLoctl> EXPORT 'Location.txt'

Export file succeeded.

gLoctl>

The contents of Location.txt above is as follows.

[G1N1]
PORT = 20101
AGENT_PORT = 0
HOST = 127.0.0.1
DB_HOME = g1n1_home

[G1N3]
PORT = 24581
AGENT_PORT = 44581
HOST = 127.0.0.1
DB_HOME = g1n3_home

HELP

Syntax

HELP

Description

It displays the commands list in an interactive mode of gloctl.

Example

gLoctl> HELP

HELP
QUIT
IMPORT {'FILE'} Upload FILE to locations
EXPORT {'FILE'} Download locations to FILE
ADD MEMBER {DSN|{member_name {'host; port; db_home; agent_port;'}}} Add member location
DROP MEMBER {member_name} Drop member location
SET TIMEOUT {second} Set time for session timeout
ADD SERVICE  {service_name {'member_name; ... '} } Add service
DROP SERVICE {service_name}       Drop service 

gLoctl>

IMPORT

Syntax

IMPORT {'FILE'}

Description

It transfers the location to glocator by using a file in ini form.

Example

It transfers the contents in Location.txt to glocator.

gLoctl> IMPORT 'Location.txt'

Import file succeeded.

gLoctl>

The contents of Location.txt above is as follows.

[G1N1]
PORT = 20101
AGENT_PORT = 0
HOST = 127.0.0.1
DB_HOME = g1n1_home

[G1N3]
PORT = 24581
AGENT_PORT = 44581
HOST = 127.0.0.1
DB_HOME = g1n3_home

QUIT

Description

It quits gloctl.

Syntax

QUIT

SET TIMEOUT

Description

It sets TIMEOUT of glocator.

Syntax

SET TIMEOUT {second}

Example

gLoctl> set timeout 120

Set timeout.

gLoctl>

Location File

Location file uploads or downloads the location information of a node from gloctl to glocator.

Description

Location file format is similar to that of Data Source Specification file.

[node_name]
HOST = host_address
PORT = port_no
DB_HOME = db_home_path
AGENT_PORT = agent_port_no 

[SERVICE]
service_name = node_name {, node_name}*

Location keywords of Location file are as follows.

Location infornation
Keyword	Description
node_name	It is the name of a node.
HOST	It is the IP address of a node.
PORT	It is the port number of glsnr which was executed in a node.
DB_HOME	It sets the home directory of a node.
AGENT_PORT	It is the port number of gagent which was executed in a node.

[SERVICE] is a fixed keyword which lists the service hints. Service hints which are registered or to be registered in glocator are listed below SERVICE keyword.

HOST and PORT keywords should be input, and an error occurs if they are omitted.

The following is an example of configuring a location file.

[G1N1]
HOST = 192.168.0.101
PORT = 20101
DB_HOME = g1n1_home
AGENT_PORT = 40101

[G1N2]
HOST = 192.168.0.102
PORT = 20102
DB_HOME = g1n2_home
AGENT_PORT = 40102

[G2N1]
HOST = 192.168.0.201
PORT = 20201
DB_HOME = g2n1_home
AGENT_PORT = 40201

[G1N2]
HOST = 192.168.0.202
PORT = 20202
DB_HOME = g2n1_home
AGENT_PORT = 40202


[SERVICE]
service_1 = G1N1,G2N1
service_2 = G1N1,G1N2

Configuration

The environment file of gloctl is $GOLDILOCKS_DATA/conf/goldilocks.gloctl.conf. The environment file should be altered or the environment file should be set with conf option and restart gloctl, to alter the driving environment for gloctl.

Stop gloctl and alter the driving environment, then restart it to alter the environment of gloctl and to apply it, while gloctl is being executed.

PORT

Item	Description
Name	PORT
Description	It is a port which is used by gloctl.
Data type	INT
Default value/ range	44581 / 1024 ~ 49151

It sets the port of a socket which is used by gloctl.

LOCATOR_HOST

Item	Description
Name	PORT
Description	It is the host address of glocator with which gloctl communicates.
Data type	STRING
Default value/ range	127.0.0.1

It sets the host address of glocator.

LOCATOR_PORT

Item	Description
Name	PORT
Description	It is the port of glocator with which gloctl communicates.
Data type	INT
Default value/ range	42581 / 1024 ~ 49151

It sets the port of glocator.

MESSAGE_TIMEOUT

Item	Description
Name	MESSAGE_TIMEOUT
Description	It sets the time of which gloctl waits for the response from glocator. (second)
Data type	INT
Default value/ range	10 / 0 ~ 2147483647

It sets the time of which gloctl waits for the response after transferring a packet to glocator.