The ifxdeploy command (Deprecated)

This version of the ifxdeploy command is deprecated but still supported for backward compatibility.

You can continue to use the following syntax of the ifxdeploy command to deploy a snapshot or remove a snapshot that you already deployed.

Syntax

ifxdeploy { <Deployment Parameters> <Uninstallation Parameters> }

Deployment parameters

{ -ppassword | -system (explicit id ) } [ { -config"conf_file_name" } ] [ { -file"full_path_name" | -extractcmd"command" } ]
[ { -silent [ -y] [ -verbose -l"log_file" ] | -verbose } ]
[ { -sqliportport | -namedpipe (explicit id ) } ]
[ -drdaportport ]
[ -servernumserver_number ]
[ -rootpath"path" [ -relocate (explicit id ) { path | old_path=new_path | old_path,old_offset= new_path,new_offset } ] ]
[ -6432 (explicit id ) ]
[ -installdrive (explicit id ) "drive" ]
[ -start ]
[ -autorecommend ]
[ -verbose ]
[ -force ]
[ -l"log_file" ]
[ -y ]

Uninstallation parameters

-uninstall"installation_path"
[ -delifx ]
[ -6432 (explicit id ) ]
[ { -silent [ -y] [ -verbose -l"log_file" ] | -verbose } ]
[ -l"log_file" ]
[ -y ]

Command options

Table 1. The ifxdeploy command options
Element Purpose Key considerations
-autorecommend Calculates the optimal settings for some onconfig file parameters. This option generates an alternative customized configuration file. The alternative configuration file might have suggested changes for certain configuration parameters that operate when the server is restarted.
Windows: The name of the alternative configuration file is %ONCONFIG%.autorec.
Linux and UNIX: The name of the alternative configuration file is $ONCONFIG.autorec.
-config "conf_file_name" Specifies deployment configuration file to run with utility.
-delifx
Windows: Removes user informix and the Informix-Admin group.
Linux and UNIX: Removes user informix and group informix.
 The -delifx option functions when there is only one HCL OneDB™ installation on the computer.
-drdaport port Specifies the Distributed Relational Database Architecture™ (DRDA®) service port for use with the Common Clients. The default is 9089.
-file "full_path_name"

Extracts a compressed snapshot only if the file specified in "full_path_name" is in BZIP2, GZIP, TAR, or ZIP format.
Windows: Indicate the location of the compressed image as an absolute path. Example: -file C:\IBM\informix\my_archive.zip
Linux and UNIX: Example: -file /opt/IBM/informix/ifxdir.tgz

If the snapshot is not in the BZIP2, GZIP, TAR, or ZIP compression format, use the -extractcmd option instead.
-extractcmd "command"

Extracts a compressed snapshot, regardless of compression format. This option primarily is intended for when you want to extract a snapshot that is not in BZIP2, GZIP, TAR, or ZIP format or when you have specialized extraction procedure.

Specify the command and the file that contains the snapshot files. If the snapshot is in BZIP2, GZIP, TAR, or ZIP compression format, then use the -file option instead.

Example on Windows:-extractcmd "tar -xf C:\my_archive.tar c:\informix"

Example on Linux™ and UNIX™:-extractcmd " ( cd /placetoextract ; myextract /opt/IBM/informix/ifxdir) "
-force Overwrites the existing instance settings on the target computer.
-installdrive "drive" This option is for Windows only.

Specifies the drive for the directory containing data spaces (typically, this is the IFMXDATA directory).

 The default drive is C:. You must have enough space for the HCL OneDB installation and databases.
-l "file_path" Sends status messages to a text file. Indicate the full path and file name for the log file that you want to use. If the file does not exist, it will be created for you.
-namedpipe This option is for Windows only.

Sets the default database server network protocol to a named pipe connection.

 If you specify both -namedpipe and -sqliport options, the deployment utility uses only one of them.
-p password Specifies the user informix password used to create the HCL OneDB service. Specify the password for user informix on the target computer. If you specify a password and the user informix does not exist on the target computer, the user will be created and will have the specified password.
-relocate path Specifies new parent directory of chunks in the deployed instance. You must have the appropriate ownership and permissions to modify the directories. You can specify a single new parent directory or map multiple separate chunk paths to different locations. In addition, you can substitute offsets of the old paths with new values if you are indicating multiple new parent directories.
Windows: If the parent directories have spaces in the paths, place the string of paths after the -relocate option in double quotation marks. Example:ifxdeploy -relocate "C:\Program Files\IBM\HCL OneDB\11.50\ tmp=D:\IFMXDATA\myserver"
Linux and UNIX: If multiple parent directories are specified and have spaces in the paths, place the string of paths after the -relocate option in single quotation marks. Example:ifxdeploy -relocate '/opt/IBM/informix1150/ tmp=/local/data/myserver; /opt/IBM/informix1150/ dbspace=/local2/data/myserver'
-rootpath "path" Indicates the location of the root dbspace.
Windows: Default path:drive:\ifmxdata\server_name\rootdbs_dat.000
Linux and UNIX: Default path:$INFORMIXDIR/server_name/rootdbs
-servernum server_number Specifies the server number of the instance. The number must be an integer from 0 to 255. The default is 0.
-silent Directs the utility to run in silent mode. When you use this option, messages do not display on the screen but are written in a log file. If you use the -silent option and -verbose option together, you must also include the -l argument.
-sqliport port Specifies the SQLHOSTS service port for the server instance. The default port is 9088.

If you specify both -namedpipe and -sqliport, the deployment utility uses only one of them.

-start Sets the number of seconds for the deployed instance to wait for automatic initialization of HCL OneDB shared memory to bring the database server online before returning to the command line. You must change the setting from zero to a workable number for the -start option to function. If you do not pass a value with the -start option, the default number of seconds is 600.

This option supports the deployment and starting of an instance in a single operation. Using this option, an online operational database is silently deployable.
-system This option is for Windows only.

Creates the HCL OneDB service that logs on to the operating system as system user.
-uninstall installation_path Removes a snapshot that was originally deployed by the deployment utility.
-verbose Runs the command in verbose mode.
-y Runs the command without prompting for confirmation.
-6432 This option is for Windows only.

Redirects registry access to 32-bit registry view.

Use this option if you are deploying a 32-bit HCL OneDB instance on a 64-bit computer.

Usage

Before you use this command, create a snapshot and copy it to the computer where you want to deploy the snapshot. See Creating a snapshot for deployment manually for more information.

Run this command, with options, on the computer where you want to deploy the snapshot. When you specify a value for a parameter, if the value contains a space, enclose the value in double quotation marks. You must run the command either as an Administrator user or as the root user.

You must provide the location of the snapshot by using the -extractcmd option, the -file option, or by setting the SNAPSHOT parameter in the ifxdeploy.conf file.

If the snapshot is in a different compressed format, you must extract it. Use the -file option to extract a snapshot if it is in BZIP2, GZIP, TAR, or ZIP compression format. If the snapshot is in a different compression format, use the -extractcmd option with a customized command or script.

If you included data spaces in your snapshot in compressed format, you must extract the data spaces before you run the ifxdeploy command. Alternatively, you can write a shell script to use with the -extractcmd option that specifies how to extract both the server snapshot and the data spaces snapshot.

Use the -force parameter to deploy a snapshot to multiple computers and override the database server instance settings on the target computer.

On Windows, the ifxdeploy command deploys a snapshot of HCL OneDB, which is not visible. If you do not want to use HCL OneDB, use the ifxdeploy utility to uninstall it.

Examples of deployment utility usage on Windows

Deploying the HCL OneDB instance in silent mode
In this example, the user informix is created on the target server and has the password mypassw0rd. The command will run in silent mode, without prompting for confirmation. The snapshot is extracted from the my_archive.zip file by 7-zip software if it is installed on the operating system.
ifxdeploy.exe -p mypassw0rd -y -silent
 -file C:\IBM\informix\my_archive.zip
Deploying the HCL OneDB instance as local system user and specifying an extraction method
In this example, the snapshot is extracted from the C:\my_archive.tar file on the target computer.
ifxdeploy.exe -system -extractcmd
 "tar -xf C:\my_archive.tar c:\informix"
Because the tar -xf part of the argument to the -extractcmd option contains a space, the argument and the paths after it are enclosed in double quotation marks.
Creating a new server instance
In this example, the SQLHOSTS port number is 9090, the server number for the instance is 2, and a full path is specified for the log file.
ifxdeploy.exe -silent -y -sqliport 9090
 -servernum 2 -l C:\my_log.txt
Creating an instance as local system user with DRDA enabled
In this example, the SQLHOSTS port is 9090, the DRDA port is 9096, and the command will run in verbose mode. The snapshot used here is not in a compressed file format, so neither the -file option nor the -extractcmd option are required.
ifxdeploy.exe -system -y -sqliport 9090
 -drdaport 9096 -verbose
Dynamic relocation of chunks to single parent directory
In this example, the chunks are relocated to a single parent directory and indicate location of the root dbspace:
ifxdeploy -rootpath D:\IFMX\ex1\rootdbs.001
 -relocate D:\IFMX\ex2
Chunk relocation to multiple paths
In this example, the location of the root dbspace has been specified with the ROOTPATH configuration parameter, so the command is not required to run with the -rootpath option. Each mapping between the old path and the new path is separated by a semicolon.
ifxdeploy -relocate C:\IFMXDATA=D:\IFMXDATA;
C:\IFMXLOGSPACE=E:\IFMXLOGSPACE
Chunk relocation to multiple paths with new offsets
In this example, the location of the root dbspace has been specified with the ROOTPATH configuration parameter, so the command is not required to run with the -rootpath option. The mapping of the old paths and the new paths includes offset values (in KB), which are indicated after the commas.
ifxdeploy -relocate C:\IFMXDATA,0=D:\IFMXDATA,4;
C:\IFMXDATAB,3=D:\IFMXDATAB,5
Automatic startup and initialization of the deployed instance
In this example, the command runs as follows:
  • Does not prompt for confirmation (the -y option).
  • Extracts a snapshot located at C:\work\ifxdir.zip.
  • Sets the server number of the deployed instance to 2 (the -servernum option).
  • Directs the deployed instance to attempt automatic initialization and startup (the -start option) within 300 seconds. If initialization is not complete after 300 seconds, the computer returns to the command line.
ifxdeploy -file C:\work\ifxdir.zip
 -servernum 2 -start 300 -y
Automatic startup, initialization of the deployed instance, and creation of a customized configuration file
In this example, the command runs as follows:
  • Does not prompt for confirmation (the -y option).
  • Extracts a snapshot located at C:\work\ifxdir.zip.
  • Sets the server number of the deployed instance to 2 (the -servernum option).
  • Directs the deployed instance to attempt automatic initialization and startup (the -start option) within 300 seconds. If initialization is not complete after 300 seconds, the computer returns to the command line.
  • Creates an alternative configuration file with optimal settings.
ifxdeploy -file C:\work\ifxdir.zip -servernum 2
 -start 300 -autorecommend -y
Automatic startup and initialization of the deployed instance with chunk relocation to multiple paths
In this example, the command runs as follows:
  • Runs in verbose mode (the -verbose option) and does not prompt for confirmation (the -y option).
  • Extracts a snapshot located at C:\work\ifxdir.zip.
  • Directs the deployment utility to dynamically relocate chunks to a single parent directory (the -relocate option) and sets the location of the root dbspace (the -rootpath option).
  • Sets the server number of the deployed instance to 2 (the -servernum option).
  • Directs the deployed instance to attempt automatic initialization and startup (the -start option). Because no value is set with the -start option, the computer waits the default time of 600 seconds before returning to the command line.
ifxdeploy -file C:\work\ifxdir.zip -verbose -servernum 2
-relocate C:\work\chunks\instance2 
-rootpath C:\work\chunks\instance2\rootdbs -start -y

Examples of deployment utility usage on Linux and UNIX

Extracting a snapshot saved as a .tgz file with Gzip and other options
In this example, the deployment utility extracts a snapshot saved as /opt/IBM/informix/ifxdir.tgz by using Gzip. The command will run in verbose mode, create the log file /tmp/mylog, and not prompt for confirmation.
ifxdeploy -file /opt/IBM/informix/ifxdir.tgz
 -l /tmp/mylog -verbose -y
Specifying SQLHOSTS settings and the server number for the deployed instance
In this example, the HCL OneDB files are already in place and you are creating a new instance by specifying port numbers for DRDA and the service port, as well as setting the server number for the instance. The snapshot is not compressed, so neither the -extractcmd option nor the -file option are required. The INFORMIXDIR and INFORMIXSERVER environment variables have been updated to new values as necessary.
ifxdeploy -sqliport 9093 -drdaport 9094 -servernum 3
Dynamic relocation of chunks to single parent directory
In this example, the chunks are relocated to a single parent directory and indicate location of the root dbspace:
ifxdeploy -rootpath /opt/ibm/IDS/exa/space
 -relocate /opt/ibm/IDS/exa/space2
Chunk relocation to multiple paths
In this example, the location of the root dbspace has been specified with the ROOTPATH configuration parameter, so the command is not required to run with the -rootpath option. Each mapping between the old path and the new path is separated by a semicolon.
ifxdeploy -relocate /opt/IBM/ex3=/idsb/myserver;
/opt/IBM/ex4=/idslogs/myserver
Chunk relocation to multiple paths with new offsets
In this example, the location of the root dbspace has been specified with the ROOTPATH configuration parameter, so the command is not required to run with the -rootpath option. The mapping of the old paths and the new paths includes offset values (in KB), which are indicated after the commas.
ifxdeploy -relocate /opt/IBM/dbspaces,
0=/lv1/data,4;/opt/IBM,2=/ids/myserver,6
Automatic startup and initialization of the deployed instance
In this example, the command runs as follows:
  • Does not prompt for confirmation (the -y option).
  • Extracts a snapshot located at /work/ifxdir.tgz (the -file option).
  • Sets the server number of the deployed instance to 2 (the -servernum option).
  • Directs the deployed instance to attempt automatic initialization and startup (the -start option) within 300 seconds. If initialization is not complete after 300 seconds, the computer returns to the command line.
ifxdeploy -file /work/ifxdir.tgz
 -servernum 2 -start 300 -y
Automatic startup, initialization of the deployed instance, and creation of a customized configuration file
In this example, the command runs as follows:
  • Does not prompt for confirmation (the -y option).
  • Extracts a snapshot located at /work/ifxdir.tgz (the -file option).
  • Sets the server number of the deployed instance to 2 (the -servernum option).
  • Directs the deployed instance to attempt automatic initialization and startup (the -start option) within 300 seconds. If initialization is not complete after 300 seconds, the computer returns to the command line.
  • Creates an alternative configuration file with optimal settings.
ifxdeploy -file /work/ifxdir.tgz
 -servernum 2 -start 300 -autorecommend -y
Automatic startup and initialization of the deployed instance with chunk relocation to multiple paths
In this example, the command runs as follows:
  • Runs in verbose mode (the -verbose option) and does not prompt for confirmation (the -y option).
  • Extracts a snapshot located at /work/ifxdir.tgz.
  • Directs the deployment utility to dynamically relocate chunks to a single parent directory (the -relocate option) and sets the location of the root dbspace (-rootpath option).
  • Sets the server number of the deployed instance to 2 (the -servernum option).
  • Directs the deployed instance to attempt automatic initialization and startup (the -start option). Because no value is set with the -start option, the computer waits the default time of 600 seconds before returning to the command line.
ifxdeploy -file /work/ifxdir.tgz -verbose -servernum 2
-relocate /work/chunks/instance2
-rootpath /work/chunks/instance2/rootdbs -start -y
1 -system functions on Windows™ only
2 -namedpipe functions on Windows only
3 -relocate can run without -rootpath option if ROOTPATH is set in an ONCONFIG parameter
4 -6432 functions on Windows only
5 -installdrive functions on Windows only
6 -6432 functions on Windows only