Writing the Descriptors


Descriptors are .xml files that describe a model's configuration and how it should be deployed. For each model package that you create you can supply a configuration descriptor and a model variable list descriptor.

A configuration descriptor file specifies how a model should be deployed to a server. A configuration descriptor is an efficient means to deploy to multiple targets using a command line.

A variable list descriptor is required if your model uses one or more model variable lists. Because model variable lists contain model variable values for all sessions in a session pool, you cannot have a model variable list descriptor file unless you also have a configuration descriptor file.

There are two ways that you can create a descriptor:

Notes:

Configuration Descriptor

Configuration descriptor files have four main sections: XML root tag, deployment targets, model configurations, and session pool configurations.

XML Root Tag

The configuration descriptor header provides standard XML root tag information, such as XML namespace and schema information, and also provides the name of the model you are deploying.

Example XML header for a configuration descriptor:

In this example, AccountingSystem is the name of the model (model-name). You must provide this required attribute.

<model-configuration-descriptor
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.wrq.com/vhi schema/vhi_deploy.xsd"
   xmlns="http://www.wrq.com/vhi"
   model-name="AccountingSystem"
   version="1.0">

Deployment Targets

The Deployment Targets section is where you specify a unique name to identify one or more configuration targets. This is a required attribute for any configuration descriptor file. The name you provide is used when you execute the activatemodel command.

If there is only one deployment target, you can use the name "default". You can then omit the target parameter when issuing the activatemodel command.

You can also specify one or more model configurations and session pool configurations, which you define later in the file. All of these names -- deployment target name, model configuration name, and session pool configuration name -- are unique names that you create in this file. They do not necessarily relate to names you provided while creating a model file.

Example of the Deployment Targets section:

In this example, executing the activatemodel command on deployment target two-pools specifies activation of the AccountingSystem model (defined under XML Root Tag) using 1) accounting-host, a model configuration you define in the Model Configurations section, and 2) pool-one-cfg and pool-two-cfg, session pool configurations you define in the Session Pool Configurations section.

<deployment-target name="two-pools">
	<pool-config-ref>pool-one-cfg</pool-config-ref>
	<pool-config-ref>pool-two-cfg</pool-config-ref>
</deployment-target>

For a given named model and session server combination, only one deployment target at a time can be active. You can configure multiple session pools in the same target, and you can run activatemodel multiple times to use the same target with multiple servers. However, you cannot run activatemodel multiple times with different targets on the same server -- only the last target specified is in effect.

Model Configurations

The Model Configurations section is where you provide the name or IP address of the host on which the modeled application is running, as well as the port number. This collection of information is called the model configuration. You can specify one model configuration or several, if the modeled application is running on several hosts. Model Configurations are referenced in Session Pool Configurations (required if using session pools) or in the Deployment Targets (optional, to override the host configured in the model). If you have no model configuration defined, the model deploys to the default host configured within the model (Design Tool > Connection Menu > Session Setup> Host name or IP address).

The Model Configurations section of the descriptor is where you also specify the Web service settings you want to use for the non-pooled model session. Model Web service settings are not inherited by the pool; you should configure each pool separately. These settings are described in detail in the Administrative Console help.

Example of the Model Configurations section:

In this example, the user has defined host pincher and port 21 on pincher as the accounting-host model configuration. Using this example with the example under Deployment Targets, the model called AccountingSystem connects to port 21 of host pincher. The default model debug messages recording mode is record-nothing. The other options are record-errors, record-errorsessions, and record-everything. To start debugging on a production server, try record-errors first.

<model-configuration name="accounting-host">
    <host-name>pincher</host-name>
    <host-port>21</host-port>
    <recording-mode>record-nothing</recording-mode>
    <ws-config>
        <publish-service-enabled>true</publish-service-enabled>
        <ws-resource-enabled>true</ws-resource-enabled>
        <execute-sql-statement-enabled>false</execute-sql-statement-enabled>
        <process-string-enabled>false</process-string-enabled>
        <method-timeout-msec>60000</method-timeout-msec>
        <suspend-timeout-minutes>60</suspend-timeout-minutes>
        <ws-namespace>urn:xmlns:model-namespace</ws-namespace>
    </ws-config>
</model-configuration>

The Web service configuration is defined in the ws-config section. The ws-config section and the elements contained within the section are optional. Any elements you include must be listed in the order shown in this example. If a setting is not included, session server default values are used.

You can use the Administrative Console to set properties, including Web service settings, for each model configuration. All of these configuration settings are described in the Administrative Console. To open this view, open the Administrative Console, and from the Host Integrator perspective, open the View menu, and select Models. This view shows models that are associated with the objects you select in the Session Server Explorer or other views in the Administrative Console. Right-click and choose the various property pages for each model.

You can use the ws-namespace value to provide a custom namespace for a model or pool during deployment.

If you want to revert to the original default session server settings for a particular model or pool, you can:

Session Pool Configurations

Session Pools are sets of host sessions preconfigured for access by data objects. These host sessions can be configured with model variables and a starting entity, which allows faster host session allocation and access to the host system because the host session can be logged on and waiting at the host application's main entry screen (entity) when a data object is ready to use it.

The Host Integrator Administrative Console provides a Pools view that contains the data you need to create and monitor session pools, including Web service settings. To open the Pools view, open the Administrative Console, and from the Host Integrator perspective, open the View menu, and select Pools. This view shows pools that are associated with the objects you select in the Session Server Explorer or other views in the Administrative Console. Choose the Properties page for each pool.

If your model uses session pools, you can use the Session Pool Configurations section to define which session pools are configured. Each session pool configuration name, such as pool-one-cfg, is also referenced in the Deployment Targets section by any target where you want to create the session pool on activation.

You can also configure Web service information for the pooled session. Each pool must be configured separately or session server defaults are used. The Web service elements are optional, but if they are included, they must be shown in the order below. If an element is not used, the session server default is used.

Sample of the Session Pool Configurations section:
<!-- A pool that uses an MVL from the MVL descriptor, model variable override, session pool, and Web service information -->
<pool-configuration name="pool-one-cfg">
    <pool-name>PrimaryAccounting</pool-name>
    <model-config-ref>accounting-host</model-config-ref>
    <min-sessions>5</min-sessions>
    <max-sessions>200</max-sessions>
    <max-free-sessions>150</max-free-sessions>
    <initial-free-sessions>20</initial-free-sessions>
    <max-pending-sessions>30</max-pending-sessions>
    <connect-delay>30</connect-delay>
    <max-retries>4</max-retries>
    <pool-started>true</pool-started>
    <startup-entity>Main</startup-entity>
    <model-variable-list>user-list-one</model-variable-list>
    <variable-override name="department" value="sales" hidden="true"/>
    <ws-config>
        <publish-service-enabled>true</publish-service-enabled>
        <ws-resource-enabled>true</ws-resource-enabled>
        <execute-sql-statement-enabled>false</execute-sql-statement-enabled>
        <process-string-enabled>false</process-string-enabled>
        <method-timeout-msec>60000</method-timeout-msec>
        <suspend-timeout-minutes>60</suspend-timeout-minutes>
        <ws-namespace>urn:xmlns:pool-namespace</ws-namespace>
    </ws-config>
</pool-configuration>

<!-- A pool that uses an MVL from the MVL descriptor -->
<pool-configuration name="pool-two-cfg">
    <pool-name>SecondaryAccounting</pool-name>
    <model-config-ref>accounting-host</model-config-ref>
    <min-sessions>10</min-sessions>
    <max-sessions>40</max-sessions>
    <startup-entity>Main</startup-entity>
    <model-variable-list>user-list-one</model-variable-list>
</pool-configuration>

For each session pool configuration, the sub-nodes <pool-name>, <model-config-ref>, <min-sessions>, <max-sessions>, and <startup-entity> are required. If the session pool uses a model variable list, <model-variable-list> is also required. Use one or more variable override names to set a variable's value for all sessions in the pool to the same value.

When you enter values in this section of the file each entry must occur in the order laid out below.

Setting pool properties and scheduling is more easily accomplished using the user interface in the Administrative Console since it is handled by the management server. However, you can use this section to enter values.

Use the following table as a guide for filling out this section:

Item Required Details
<pool-configuration name>
X
The name of the pool configuration, referenced in the Deployment Targets section.
<pool-name>
X
How the pool is referenced when it's on the server.
<model-config-ref>
X
A reference to the model configuration name. The Deployment Targets section and one or more pools will refer to this name.
<min-sessions>
X
The minimum number of sessions that the pool should contain.
<max-sessions>
X
The maximum number of sessions that the pool should contain.
<max-free-sessions>
Optional
Maximum idle sessions. Maximum idle sessions cannot exceed the Maximum concurrent sessions defined for the pool, or your licensed session limit, which is displayed as the maximum value for this option.
<initial-free-sessions>
Optional
Initial idle sessions. Specifies the number of sessions that are preloaded by the server. This is the number of sessions that a server should preconnect.
<max-pending-sessions>
Optional
Maximum pending sessions. The maximum number of sessions trying to connect to the host simultaneously. The actual number may be much less if the sessions start and login rapidly.
<connect-delay>
Optional
Connection throttle delay (seconds). The amount of time to wait since the last host connection before attempting another.
<max-retries>
Optional
Maximum retry backoff (n=0 is 1 second, n=1 is 2 seconds, n=2 is 4 seconds, n=3 is 8 seconds, and so forth). Each time there is an error starting host sessions in a pool, the pool waits for an increasing amount time before trying again (it backs off). This option limits the retry backoff so the delay doesn't become too long.
<pool-started>
Optional
Indicates if the pool should start automatically when deployed, true or false.
<startup-entity>
X
The entity in the model that will serve as the session pool's startup entity.
<model-variable-list>
Optional
If the pool has a model variable list, this is where you provide its name. This is the name of the model variable list, as the server knows it. Its contents are defined in the model variable list descriptor file.
<variable-override-name>
Optional
If the pool has one or more model variable overrides, list them here.

Sample Configuration Descriptor File

A sample configuration descriptor file (deploy-ex3.xml) is in your <VHI install folder>\Help\plugins\com.attachmate.vhi.help\html\reference folder.

Model Variable List Descriptor

A model variable list descriptor file defines the contents of one or more model variable lists. These lists are referenced by name from the configuration descriptor file's Session Pool Configurations section.

Model variable list descriptor files have two main sections, described below.

XML Root Tag

The model variable list descriptor header provides standard XML root tag information, such as XML namespace and schema information, as well as the name of the model you are deploying. Here's a sample of the XML header for a model variable list descriptor:

<mvl-descriptor xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   
   xsi:schemaLocation="http://www.wrq.com/vhi schema/vhi_deploy.xsd"    
   xmlns="http://www.wrq.com/vhi" 
   version="1.0">

Model Variable List

The Model Variable List section is where you provide the contents of one or more variable lists for your model:

<model-variable-list name="user-list-one">
   <model-variable name="userID" hidden="false" unique="true"/>
   <model-variable name="password" hidden="true" unique="false"/>
   <value-row>
        <value>fred</value>
        <value>pass</value>
   </value-row>
   <value-row>
        <value>jimbo</value>
        <value>pass</value>
    </value-row>
</model-variable-list>

For each model variable list, the sub-nodes <model-variable-list name>, <model-variable name>, <value-row>, and <value> are required. The first <value> in each <value-row> corresponds to the value of the first <model-variable>, the second corresponds to the value of the second <model-variable>, and so forth.

Use the following table as a guide for filling out this section:

Item Required Details
<model-variable-list name>
X
The name of the model variable list.
<model-variable name>
X
How a model variable is referenced when it's on the server. Model variables can be hidden or visible (hidden=true or hidden=false) and unique or non-unique (unique=true or unique=false). A variable marked as hidden can be optionally encrypted in the model package file. A variable marked as unique must have entirely unique values.
<value-row>
X
A group of variable values, usually a user name and password for a host application.
<value>
X
An individual value in a value row - usually a user name or password for a host application.

Sample Model Variable List Descriptor File

A sample model variable list descriptor (mvl-example.xml) is in your <VHI install folder>\help\plugins\com.attachmate.vhi.help\html\reference folder.

 

Related Topics
Bullet Deployment Overview
Bullet Using Commands to Deploy a Model Package