Create Instance for OnDemand (CRTINSTOND)

Where allowed to run: All environments (*ALL)
Threadsafe: No
Parameters
Examples
Error messages

The Create Instance for OnDemand (CRTINSTOND) command creates an OnDemand instance.

An OnDemand instance is a logical server environment with its own library containing a unique set of database files. An instance is defined in the ARS.INI file by naming the instance (which identifies the name of the library used by the instance). All of the database files that belong to an instance run in one and only one coded character set identifier (CCSID).

You can run multiple instances on the same server, with each instance configured differently:

When you work with more than one instance, you must identify the instance name when you run OnDemand commands (such as ADDRPTOND and STRMONOND).

Each instance has different security from other instances on the same system. You must define users and groups to each instance and set application group and folder permissions for users of each instance. Each instance has its own system log.

When you are creating an instance, your user profile must have its locale set to the locale of the instance you wish to create. Because the locale is set in the user profile, you may need to change your user profile, then sign off and back on before creating the instance. Use the Change User Profile (CHGUSRPRF) command to change (if necessary) your user profile. You should also make sure that other language-related parameters in your user profile are set correctly. You can use the Display User Profile (DSPUSRPRF) command to check the locale setting. The locale Job Attributes (SETJOBATR) parameter in your user profile is used to determine which values are obtained from the locale. For OnDemand, at a minimum, you must use SETJOBATR(*CCSID).

Top

Parameters

Keyword Description Choices Notes
INSTANCE Instance Character value Required, Positional 1
LANGID Language ID Character value, *SYSVAL Optional
LOCALE Locale Path name, *SYSVAL Optional
PORT Port number 1024-65535, *DFT Optional
AUTOSTART Autostart instance server *NO, *YES Optional
ASP ASP number 1-32, 1, *ASPDEV Optional
ASPDEV ASP device Name, *ASP, *ASPGRPPRI, *SYSTEM Optional
SECURITY Server security *SYSTEM, *ONDMD Optional
DFTINST Default instance *NO, *YES Optional
STRSVR Start instance after creation *NO, *YES Optional
SBMJOB Submit to batch *YES, *NO Optional
JOBD Job description Qualified object name Optional
Qualifier 1: Job description Name, QOND400
Qualifier 2: Library Name, QRDARS, *LIBL, *CURLIB
Top

Instance (INSTANCE)

Specifies the name of the instance to create.

This is a required parameter.

instance-name
Specify the name of the instance that is to be created.

The instance name must start with an alphabetic character or @ followed by any of these characters: 0-9, A-Z, @, # and underscore (_). Be sure that no library, user profile, or authorization list by that name already exists. Further, the instance name must not start with the letter Q (except for QUSROND), and must not be named CONFIG or WWW.

Top

Language ID (LANGID)

Specifies the language identifier to be used for this instance.

Note: IBM i may support additional languages which are not supported by OnDemand system log messages. System log messages will appear in English when an instance uses a language identifier that is not supported.

*SYSVAL
The system value QLANGID is used.
language-identifier
Specify the language identifier to be used. More information on valid language identifiers is in the IBM i globalization topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ .
Top

Locale (LOCALE)

Specifies the path name of the locale that is assigned to the instance.

*SYSVAL
The system value QLOCALE is used to determine the locale path name to be assigned for the instance.
path-name
Specify the path name of the locale to be assigned for the instance.
Top

Port number (PORT)

Specify the TCP/IP port to which the instance server listens to receive requests from an OnDemand client.

*DFT
The value of *DFT means to use the default port of 1445. Only one server can be listening to a particular port at any given time. If you want to be able to run multiple instances concurrently, you will need to specify a port that is not being used on your system for some other purpose.
1024-65535
Specify the port to which the instance server listens to receive requests from an OnDemand client. Valid values range from 1024 through 65535. Ports 1 through 1023 are used by the system-supplied TCP/IP applications.

Note: You can use the Work with TCP/IP Network Status (WRKTCPSTS) with OPTION(*CNN) command to see what IPv4 ports are currently in use on your system. You can use the Work with TCP/IP Network Status (WRKTCPSTS) with OPTION(*CNN6) command to see what IPv6 ports are currently in use on your system.

Top

Autostart instance server (AUTOSTART)

Specifies whether to automatically start the instance server when running the Start TCP/IP Server (STRTCPSVR) command with SERVER(*ONDMD) and INSTANCE(*AUTOSTART) specified. If SERVER(*ONDMD) is not specified when running the STRTCPSVR command, this parameter is ignored.

*NO
Do not start the instance server when the STRTCPSVR SERVER(*ONDMD) with INSTANCE(*AUTOSTART) command is run.
*YES
Start the instance server when the STRTCPSVR SERVER(*ONDMD) with INSTANCE(*AUTOSTART) command is run.
Top

ASP number (ASP)

Specifies the number of the system or basic user auxiliary storage pool (ASP) where storage for the instance library is allocated. For instances created in an ASP, all objects in the instance library must be in the same ASP as the library. When a value other than *ASP is specified for the ASP device (ASPDEV) parameter, *ASPDEV is the only valid value that can be specified for the ASP number (ASP) parameter, if specified. Also when a value other than *ASP is specified for the ASPDEV parameter, the ASP parameter can be omitted and its defaulted value will be ignored.

1
The storage space for the instance library is allocated from the system auxiliary storage pool ASP 1.
*ASPDEV
The storage for the instance library is allocated from the primary or secondary ASP specified for the ASPDEV parameter.
number
Specify a value ranging from 1 through 32 that is the number of the system or basic user ASP.
Top

ASP device (ASPDEV)

Specifies the auxiliary storage pool (ASP) device name where storage is allocated for the instance library. When a value other than *ASPDEV is specified for the ASP number (ASP) parameter, ASPDEV(*ASP) is the only valid value for the ASP device (ASPDEV) parameter, if specified. Other values for the ASPDEV parameter are valid if the ASP parameter is omitted. In this case, the defaulted value for the ASP parameter is ignored.

*ASP
The storage for the instance library is allocated from the system or basic user ASP specified for the ASP parameter.
*ASPGRPPRI
The storage for the instance library is allocated from the primary ASP of the thread's ASP group. If no ASP group is associated with the thread, an error message is sent.
*SYSTEM
The storage for the instance library is allocated from the system ASP (ASP 1).
name
Specify the name of a primary or secondary ASP device. The storage for the instance library is allocated from the primary or secondary ASP. The primary or secondary ASP must have been activated (by varying on the ASP device) and have a status of 'Available'.

Note: To specify a specific auxiliary storage pool (ASP) device name, you must have use (*USE) authority for each ASP device in the ASP group.

Top

Server security (SECURITY)

This specifies how security will be administered for this instance.

You may select to use System i administered user profiles and passwords as the OnDemand user IDs and passwords or you may select to use user IDs and passwords that are administered by OnDemand.

*SYSTEM
Use System i user profiles and passwords as the OnDemand user IDs and passwords. This value makes it simpler for your end users because they do not have to maintain multiple user IDs and passwords.
*ONDMD
Use OnDemand managed user IDs and passwords. When this is specified, your OnDemand user IDs and passwords have no relationship to System i user profiles and passwords. All management of OnDemand user IDs and passwords must be performed using the OnDemand Administrator client.
Top

Default instance (DFTINST)

Specifies that this instance should be set as the new default (*DFT) instance in the QDFTINST data area in library QUSRRDARS.

*NO
This instance will not become the default (*DFT) instance.
*YES
This instance will become the default (*DFT) instance.

Note: If the QDFTINST data area does not exist in library QUSRRDARS, it will be created. The default (*DFT) instance specified in the QDFTINST data area in library QUSRRDARS can be overridden by creating another QDFTINST data area in a user library which can then be included in the library list of any OnDemand job that requires that default instance to be used instead.

Top

Start instance after creation (STRSVR)

Start the instance server for this instance, after the instance has been successfully created.

*NO
The instance server for this instance will not be started.
*YES
The instance server for this instance will be started.
Top

Submit to batch (SBMJOB)

Specify if you want to create the instance interactively or in a batch job.

*YES
This command should be submitted to run in a different job.
*NO
This command should be run within the current job. If you are entering this command from a terminal, this will prevent you from doing any other work from this terminal session until this command completes.
Top

Job description (JOBD)

Specifies the name of the job description used for the submitted job.

Qualifier 1: Job description

QOND400
The QOND400 job description is used as the job description for the submitted job.
jobd-name
Specify the name of the job description used for the job.

Qualifier 2: Library

QRDARS
Library QRDARS is used as the job description's library.
*LIBL
All libraries in the job's library list are searched until the first match is found.
*CURLIB
The current library for the job is used to locate the job description name. If no library is specified as the current library for the job, QGPL is used.
library-name
Specify the name of the library where the job description name is located.
Top

Examples

Example 1: Create an Instance

CRTINSTOND INSTANCE(ONDTEST) LANGID(ENU)
           LOCALE('/QSYS.LIB/EN_US.LOCALE')
           PORT(*DFT) AUTOSTART(*YES) SECURITY(*SYSTEM)

This command submits a job to batch that will create an instance called ONDTEST. The instance will be created with a server language of US English. The instance server will listen on the default TCP/IP port number and will be started automatically when the Start TCP/IP Server (STRTCPSVR) with SERVER(*ONDMD) and INSTANCE(*AUTOSTART) is specified. The instance server will use IBM i user profiles and passwords.

Example 2: Create an Instance which uses OnDemand Managed User IDs and Passwords

CRTINSTOND INSTANCE(ONDPROD) LANGID(DEU)
           LOCALE('/QSYS.LIB/DE_DE_E.LOCALE')
           PORT(1450) AUTOSTART(*YES) ASP(*ASPDEV)
           ASPDEV(ASP01) SECURITY(*ONDMD) DFTINST(*YES)
           STRSVR(*YES)

This command submits a job to batch that will create an instance called ONDPROD. The instance will be created with a server language of German with a locale which supports the Euro. The instance server will listen on TCP/IP port 1450 and will be started automatically when the Start TCP/IP Server (STRTCPSVR) with SERVER(*ONDMD) and INSTANCE(*AUTOSTART) is specified. The instance server will use user IDs and passwords which are managed using the OnDemand Administrator Client. The instance library will be created in an independent auxiliary storage pool (IASP) called ASP01. The ONDPROD instance will become the default instance server (*DFT) used by other OnDemand commands. The instance server will be started after it has been created.

Top

Error messages

*ESCAPE Messages

CPF7012
Auxiliary storage pool &4 not found for object &1.
CPFA0A9
Object not found. Object is &1.
OND0629
Job ended in error - see previous messages in the job log.
Top