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 is required if you want to use session pools, or if you have multiple configuration targets. 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 these descriptors:

Use the topics below for information on which attributes you must provide in your descriptor files. For descriptor examples, see Sample Configuration Descriptor File and Sample Model Variable List Descriptor File.

Notes:

Configuration Descriptor

A configuration descriptor file specifies how a model should be deployed to a server. Configuration descriptor files have four main sections:

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. Here's a sample of the XML header for a configuration descriptor:

<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">

In the above example, AccountingSystem is the name of the model (model-name). This is a required attribute that you must provide.

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.

Tip: You can use the name "default" if only one target is planned. This allows you to 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.

Here's a sample of the Deployment Targets 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>

In the above 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.

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) and/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).

Here's a sample of the Model Configurations section:

  <model-configuration name="accounting-host">
<host-name>pincher</host-name>
<host-port>21</host-port> <recording-mode>record-nothing</recording-mode>
</model-configuration>

In the above 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 will connect to port 21 of host pincher. Model debug messages recording mode by default is set to record-nothing. The other options are record-errors and record-everything. To start debugging on a production server, try record-errors first.

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.

If your model uses session pools, 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.

Here's a sample of the Session Pool Configurations section:

 <!-- A pool that uses an MVL from the MVL descriptor, and model variable override -->
   <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>
     <startup-entity>Main</startup-entity>
     <model-variable-list>user-list-one</model-variable-list>
     <variable-override name="department" value="sales" hidden="true"/>
   </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.

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.
<startup-entity>
X
The entity in the model that will serve as the session pool's startup entity.
<model-variable-list>
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>
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>\doc\help\server 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:

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. Note that 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>, etc.

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>\doc\help\server folder.

 

 



 

 

  Attachmate