5.1 pgx_jadmin

Name

pgx_jadmin -- Setup and operation of PL/extJava

Synopsis

pgx_jadmin init-domain --shareddir directory [--domainport port1,port2,port3]
                       --dbadminuser username
                      [--pgdata directory | -D directory]
                      [--cluster-standbynode]

pgx_jadmin delete-domain [-y] [--force] [--cluster-standbynode]

pgx_jadmin list-domain

pgx_jadmin modify-domain-port --domainport port1,port2,port3 
                             [--cluster-standbynode]

pgx_jadmin create-container --dbname database_name [--instanceport port1,port2]
                           [--dbport port] --dbuser username
                            --dbpassword password
                           [--cluster-standbynode]

pgx_jadmin delete-container --dbname database_name [--cluster-standbynode]

pgx_jadmin list-container --dbname database_name

pgx_jadmin add-instance --dbname database_name
                        --instanceport port1,port2 [--cluster-standbynode]

pgx_jadmin delete-instance --dbname database_name [--cluster-standbynode]

pgx_jadmin modify-instance-port --instance name
                                --instanceport port1,port2 [--cluster-standbynode]

pgx_jadmin modify-container-db --dbname database_name [--dbport port]
                              [--dbuser username] [--dbpassword password]

pgx_jadmin list-jvm-options --dbname database_name

pgx_jadmin modify-jvm-options --dbname database_name [--heapsize size]
                             [--permsize size]

pgx_jadmin backup --backupdir directory

pgx_jadmin restore --backupdir directory [--cluster-standbynode]

Description

The pgx_jadmin unified command is used in Symfoware Server Java Application Server, which incorporates the PL/extJava environment into Symfoware Server.The pgx_jadmin command consists of several subcommands. Each subcommand corresponds to an operation in the PL/extJava environment.

In init-domain subcommand, creates a domain for using the PL/extJava environment. This command creates a domain only once after Symfoware Server is installed.

In delete-domain subcommand, deletes the domain for using the PL/extJava environment.

In list-domain subcommand, displays domain information.

In modify-domain-port subcommand, modifies the domain management port numbers.

In create-container subcommand, creates a container in a domain. When you create a container, a server instance (JavaVM) is simultaneously created in the container. Create one container per database within an instance. To use Java functions in multiple databases, create a container for each one.

In delete-container subcommand, deletes a container from a domain.

In list-container subcommand, displays container information.

In add-instance subcommand, add a server instance (JavaVM) to a container.

In delete-instance subcommand, deletes a server instance (JavaVM) from a container. If multiple server instances (JavaVM) have been created in a container, this command deletes the one that was added last.

In modify-instance-port subcommand, modifies the server instance management port numbers.

In modify-container-db subcommand, modifies the database connection information of a container.

In list-jvm-options subcommand, displays JavaVM option information of a container.

In modify-jvm-options subcommand, modifies the JavaVM settings of a container.

In backup subcommand, backup the PL/extJava.

In restore subcommand, restore the PL/extJava.

Options

--backupdir directory

Specify the full path of the directory. Specify the directory name in up to 120 bytes.

You can use the following characters in the directory name:

Alphanumeric characters
Spaces
Underscores "_"
Hyphens "-"
Parentheses "( )"

Do not specify the following directories:

Same directory as the instance data storage directory, the backup storage directory and the domain root directory
Directory in the instance data storage directory, the backup storage directory and the domain root directory
Directory that exists under the instance data storage directory, the backup storage directory and the domain root directory is under the backup storage directory for PL/extJava

--cluster-standbynode: Specify this option to execute the command for the standby node in a cluster environment.

-D directory --pgdata directory

Specify the instance data storage directory.

If you omit this option, the command references the environment variable (PGDATA).

--dbadminuser username: Specify the name of the instance administrator. Refer to "User of PL/extJava" in "Setting up and Operating PL/extJava" of the Operation Guide for information on the instance administrator. Specify the user name in up to 8 bytes. After creating a domain, you cannot change the instance administrator set during creation of the domain.

--dbadminuser username: Specify the name of the instance administrator. Specify the user name in up to 8 bytes. After creating a domain, you cannot change the instance administrator set during creation of the domain.

--dbname database_name

Specify the database name using 1 to 28 bytes of the database corresponding to the container. You can use the following characters in the database name:

Alphanumeric characters
Underscores "_"

You cannot specify an underscore as either the leading or trailing character. You cannot specify a database name already registered, even if you change name capitalization. For example, if the database name "database001" has already been registered, you cannot create a container with the database name "DATABASE001". You cannot specify the following as a database name:

domain
default
server
resources

The database name to the instance is not revokable. Recreate the container when you change the database name.

--dbpassword password

Specify the password of the user who will connect to the database.

Ensure that it matches the password of the user registered in the instance.

Specify --dbpassword option or --dbuser option when you modify the database connection information.

--dbport port

Specify the port number of the instance.

If you omit the port number, the default value of 26500 for the instance is used.

--dbuser username

Specify a user name for connecting to the database. You must register the user in the instance in advance.

Specify --dbuser option or --dbpassword option when you modify the database connection information.

--domainport port1,port2,port3: Specify the domain management port numbers separated with a comma. Three port numbers are required. If you omit the port numbers, the default values are used. Refer to "Preparation for portnumber" in "Setting up and Operating PL/extJava" of the Operation Guide for information on port numbers. Specify the portnumber not changed in order of specification for the init-domain subcommand when specifying it for the modify-domain-port subcommand.

--force: Specify this option to forcibly delete the domain even if it has containers.If you omit this option, the domain will fail to be deleted if it has containers.

--heapsize size

Specify the size of the heap area in megabytes.Specify a value of 64 or greater for the size of the heap area.

Specify --heapsize option or --permsize option when you modify the JavaVM settings.

--instance name

Specify the server instance name(JavaVM).

You can check the names of server instances(JavaVM). registered in a container by using the list-container subcommand.

--instanceport port1,port2: Specify the server instance management port numbers separated with a comma. two port numbers are required. If you omit the port numbers, the default values are used. Refer to "Preparation for portnumber" in "Setting up and Operating PL/extJava" of the Operation Guide for information on port numbers.

--permsize size

Specify the size of the Perm area in megabytes.Specify a value of 64 or greater for the size of the Perm area.

Specify --permsize option or --heapsize option when you modify the JavaVM settings.

--shareddir directory

Specify the full path of the directory (domain root) that will store the domain resources. Specify the directory that does not exist in the directory name in up to 255 bytes.

Specify the directory that there is a writing authority of the user who has the administrator authority in the parent directory of the domain root.

Specify the directory that there is a writing authority of the user who has the instance administrator authority in the parent directory of the domain root.

You can use the following characters in the directory name:

Alphanumeric characters
Spaces
Underscores "_"
Hyphens "-"
Parentheses "( )"

Do not specify the following directories for the domain root:

Same directory as the instance data storage directory
Directory in the instance data storage directory
Directory for which the instance data storage directory is under the domain

-y

Specify this option to skip the message prompting you to confirm deletion of the domain.

If you omit this option, a message prompting you to confirm deletion of the domain will be displayed.

Environment

PGDATA: Specify the data directory. You can overwrite using the -D option.

Diagnostics

0 : On success

otherwise : On error

Notes

The Executing of this command cannot be done at the same time.

Using an escape character

To use any of the following characters as the value of an option or operand in the command, you must escape it with "\". However, do not specify escape character when you specify --dbuser and --dbpassword excluding the metacharacter for the modify-container-db subcommand.

Windows

Character type	Description	Characters
Java escape equence	Character used as an escape character in Java	\" etc
Special character of the pgx_jadmin command	Special character used as a delimiter or escape character in subcommands	.-:=

Linux

Character type	Description	Characters
Metacharacter	Character used as a metacharacter	;&()\|><?[]~+-@!"'\ `${}^ (1)
Java escape sequence	Character used as an escape character in Java	\"
Special character of the pgx_jadmin command	Special character used as a delimiter or escape character in subcommands	.-:=

*1: The characters treated as metacharacters vary depending on the type of shell being used.

To set the password of the user who will connect to the instance to "pass\word!":

pgx_jadmin create-container --dbname db01 --dbuser user1 --dbpassword pass\\word\!

pgx_jadmin create-container --dbname db01 --dbuser user1 --dbpassword pass\\\\word\!

Stop of instance

The following subcommand can only be executed when the database server is stopping.

init-domain
create-container
add-instance
delete-instance
modify-domain-port
modify-instance-port
modify-container-db
modify-jvm-options
delete-container
delete-domain
backup
restore

Command executing user

The all subcommand execute this command as:

User with administrator privileges on the operating system

The init-domain subcommand and the delete-domain subcommand and the backup subcommand and the restore subcommand execute this command as:

Operating system administrator

The others subcommand execute this command as:

instance administrator

The list-domain subcommand is the Executing by the above-mentioned user.

Deletion of domain: Delete of domain before uninstalling Symfoware Server. Deleting a domain deletes the domain root directory. Back up the required directories and files before executing this command.

Backup storage directory of PL/extJava

Do not update or delete files in the backup storage directory of PL/extJava. Otherwise, you may not be able to recover the PL/extJava.

Do not store other files in the backup storage directory of PL/extJava.

Examples

Create a domain

The following example omits the domain management port numbers and the instance data storage directory.

pgx_jadmin init-domain --shareddir C:\domain --dbadminuser dbadmin1

pgx_jadmin init-domain --shareddir /domain --dbadminuser dbadmin1

The following example specifies the domain management port numbers and the instance data storage directory.

pgx_jadmin init-domain --shareddir C:\domain --dbadminuser dbadmin1
                           --domainport 26530,26521,26522 --pgdata C:\database\inst1

pgx_jadmin init-domain --shareddir /domain --dbadminuser dbadmin1
                       --domainport 26530,26521,26522 --pgdata /database/inst1

Delete a domain

The following example shows the command when the domain has no containers.

pgx_jadmin delete-domain

The following example forcibly deletes the containers in the domain.

pgx_jadmin delete-domain --force

Display domain information

To display the domain information:

pgx_jadmin list-domain

Contents of list-domain

domain status:  (1)
shareddir:      (2)
domainport:     (3)
dbadminuser:    (4)
datadir:        (5)

(1) Domain status
    running        : Start state
    not running    : Stop state 
(2) Directory (domain root) that will store the domain resources
(3) Domain management port number (x 3)
(4) Instance (database) administrator
(5) Instance data storage directory

Display example

domain status: running
shareddir: C:\domain
domainport: 26530,26521,26522
dbadminuser: dbadmin1
datadir: C:\database\inst1

Display example

domain status: running
shareddir: /domain
domainport: 26530,26521,26522
dbadminuser: dbadmin1
datadir: /database/inst1

Modify the domain management port numbers

To modify the domain management ports:

pgx_jadmin modify-domain-port --domainport 26600,26601,26602

Create a container

The following example omits the port number of the instance and the port number of the server instance.

pgx_jadmin create-container --dbname db01 --dbuser user1 --dbpassword password1

The following example specifies the port number of the instance and the port number of the server instance.

pgx_jadmin create-container --dbname db01 --dbuser user1 --dbpassword password1
                            --dbport 26011 --instanceport 26531,26532

Delete a container

To delete a container:

pgx_jadmin delete-container --dbname db01

Display container information

To display container information:

pgx_jadmin list-container --dbname db01

Contents of list-container display

container status:  (1)
dbname:            (2)
instance:          (3) (4)
dbport:            (5)
dbuser:            (6)

(1) Container status 
    running           : Start state (all server instances are started) 
    partially running : Degrading start (some server instances are stopped) 
    not running       : Stop state (all server instances are stopped) 
(2) Database name
(3) Server instance name
(4) Server instance management port number (x 2)
(5) Instance port number
(6) User name for connecting to the instance

Display example

container status: running 
dbname: db01
instance: db01-1 26531,26532
instance: db01-2 26801,26802
dbport: 26011
dbuser: user1

Add a server instance(JavaVM)

To add a server instance(JavaVM):

pgx_jadmin add-instance --dbname db01 --instanceport 26801,26802

Delete a server instance(JavaVM)

To delete a server instance(JavaVM):

pgx_jadmin delete-instance --dbname db01

Modify the server instance(JavaVM) management port numbers

To modify the server instance(JavaVM) management port numbers:

pgx_jadmin modify-instance-port --instance db01-1 --instanceport 26701,26702

Modify the instance connection information

To modify the user name and password used for connecting to the database:

pgx_jadmin modify-container-db --dbname db01 --dbuser user02 --dbpassword passwd2

Display JavaVM option information of a container

To display the JavaVM options of a container:

pgx_jadmin list-jvm-options --dbname db01

Modify the JavaVM settings

To modify the JavaVM heap area size and the Perm area size:

pgx_jadmin modify-jvm-options --dbname db01 --heapsize 1024 --permsize 384

Backup the PL/extJava

To backup the PL/extJava:

pgx_jadmin backup --backupdir D:\backup

pgx_jadmin backup --backupdir /backup

Restore the PL/extJava

To restore the PL/extJava:

pgx_jadmin restore --backupdir D:\backup

pgx_jadmin restore --backupdir /backup