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:

• Using an XML schema: An XML schema for both descriptor files, named vhi_deploy.xsd, is located in the lib\schema folder of your Verastream installation. With an XML editor such as XML Spy you can use this schema to help create descriptors files.
• By hand: You can create the descriptors by hand using a text editor such as Notepad.

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:

• If you're upgrading from an earlier version of Host Integrator, you may have a significant amount of model or session pool configuration information in the Administrative WebStation. If you want to update a model without affecting existing configuration information, do not include descriptor files in your model package.
• You should also not create descriptor files if you use an external service to handle your host passwords. In such a situation, a model variable list descriptor, which provides host user IDs and passwords, would be difficult to keep up-to-date.

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
• Deployment Targets
• Model Configurations
• 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. 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:

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
• Model Variable List

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:

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.

© 1999-2007 Attachmate Corporation. All rights reserved. Terms of Use.