soamreg
The command to register an application or update the application profile of a registered application.
Synopsis
soamreg application_profile_file [-d][-f]
[-u user_name] [-x password]
soamreg fragment_profile_file -p [-f]
[-u user_name] [-x password]
soamreg -h
soamreg -V
Description
Before you register an application in IBM® Spectrum Symphony:
- The consumer specified in the application profile must already exist in the specified resource group names or in the default resource groups.
- The service packages specified in the application profile or profile fragment must already be deployed for the consumer.
Remember: If the application profile resourceGroupName attribute for
the session manager and service instance manager is not defined, the default compute and management
host groups are used. In this case, the consumer must be defined in the
ComputeHost and the ManagementHost. Otherwise, the
application cannot be enabled after registration.
In IBM Spectrum Symphony Developer Edition, the consumer name is optional and not used.
The table that follows describes IBM Spectrum Symphony behavior when registering an application, based on existing conditions when soamreg was issued:
| No enabled application in consumer | No enabled application in consumer | Enabled application in consumer | Enabled application in consumer | Enabled application in consumer | Enabled application in consumer | |
|---|---|---|---|---|---|---|
| Application has open or suspended sessions | Application has open or suspended sessions | Application has no open or suspended sessions |
Application has no open or suspended sessions |
|||
| System action resulting from issuing soamreg | Register new application | Update existing application | Register new application | Update existing application | Register new application | Update existing application |
| Registers and enables the application | Yes | No | No | Yes | No | Yes |
| Registers the application, and it remains disabled | No | Yes | Yes | No | Yes | No |
| Registers the application profile fragment | No | Yes | No | Yes | No | Yes |
| Terminates all sessions | No | No | No | Yes | No | No |
| Shuts down session manager, releases resources, and starts up a new session manager | No | No | No | Yes | No | Yes |
| Updates the application profile | No | Yes | No | Yes | No | Yes |
| Dynamic update for application profile | No | Yes | No | Yes | No | Yes |
- -h
- Prints command usage to stdout and exits.
- -V
- Prints product version to stdout and exits.
Options
- application_profile_file
- Specify the path and name of the application profile or profile fragment file for the
application. If any part of the path or file name contains spaces, enclose it in double quotes ("
"). Specify the path for the application profile using absolute, relative, or UNC format. You can specify file paths using absolute or relative paths:
- Absolute
- Provide the full path to the file, from the root directory. If you specify an absolute path, all
hosts must have the same path. For example, to specify the file from your IBM Spectrum Symphony Developer Edition samples directory:
- Windows: "%SOAM_HOME%\version\samples\CPP\SampleApp\SampleApp.xml"
- Linux®: "$SOAM_HOME/version/samples/CPP/SampleApp/SampleApp.xml"
- Relative
- Provide the path to the file relative to the IBM Spectrum Symphony work directory,
%SOAM_HOME%\work in Windows and
$SOAM_HOME/work in Linux.
For example, to specify the file from your IBM Spectrum Symphony Developer Edition samples directory:
- Windows: "..\version\samples\CPP\SampleApp\SampleApp.xml"
- Linux: "../version/samples/CPP/SampleApp/SampleApp.xml"
- fragments_profile_file
- Register a profile fragment file that contains either a new session type or a new service
section, or both. When you add a new session type or Service section, the system does not
terminate running workload. When you update an existing Service section, the system only
terminates running workload associated with the updated service. The add, update, and remove actions
are also applicable for multiple services. Only the add and remove actions are applicable for
multiple session types. You can also register a profile
fragment file to add, modify, or remove Docker container definitions.
Specify file paths using absolute or relative paths as explained in application_profile_file.
Note the following rules for the profile fragment file:- For update operations (for example,
<Fragment applicationName="sympingversion" operation="Update"/>), you can only update a service, but not a session type. You can include a <Service> section, but not a <SessionTypes> section. You can update Docker container definitions. - For add or remove operations (for example,
<Fragment applicationName="sympingversion" operation="Add"/>or<Fragment applicationName="sympingversion" operation="Remove"/>), you can add or remove both a service and a session type. You can include both a <Service> and a <SessionTypes> section. You can also add or remove Docker container definitions.
- For update operations (for example,
- -f
- Registers a new application without warning. For existing applications, updates the existing
application profile and terminates application workload without warning, if there is active workload
for the application.
Registers a profile fragment and does not prompt you to confirm the addition or update.
- -p
- Registers a profile fragment with the new session types, Service, and Docker container sections, or with the updated Service and Docker container sections, or with the removed session types, Service, and Docker container sections. You can refer to the profile fragment templates to create your own profiles. You can find templates in the $SOAM_HOME/version/samples/Templates directory under IBM Spectrum Symphony Developer Edition.
- -d
- Updates the application profile dynamically. If you use this option with -f, then affected workload will be terminated without any warning.
- -u user _name
- Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command alone, the user name specified here overrides the user name entered in soamlogon.
- -x password
- Specifies the user password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command alone, the password specified here overrides the password entered in soamlogon.
Register an application
Note that the /samples directory, used in the following examples of the soamreg command, is applicable to IBM Spectrum Symphony Developer Edition.
Register an application on Linux:
soamreg soam/./samples/CPP/SampleApp/SampleApp.xml
Register a profile
fragment:
soamreg soam/version/samples/CPP/SampleApp/SampleAppFragment.xml -p
Register an application on Windows:
soamreg "\\hostA\share\SampleApp.xml"
Register a profile
fragment:
soamreg "\\hostA\share\SampleAppFragment.xml" -p