Using XML to format definitions

XML is the standard format used for structuring data as input and output files for your stored definitions. The contents of all your tags within the document, including tag names and elements, are not case sensitive.

The Document Type Definition (DTD) (kcp_slabatch.dtd) defines what is the valid XML format for the kcp_slabatch utility and verifies if you have created data that can be imported without any problems.

The top level of your XML document must have encoding. The default setting for encoding is ISO-8859-1 and this must be added on the first row of any exported file. Because ISO-8859-1 is the default setting, if you do not supply this line, the processing will continue.

For example:

<?xml version='1.0 encoding='ISO-8859-1' ?>

The next line in your document must have a reference to the DTD file, which allows you to validate that your XML format is correct. The kcp_slabatch utility uses the DTD file when importing a document. By default, the DTD file is found in the same folder as your XML file. If this is not the case, you must perform one of the following actions:

Copy the DTD file into the same folder as the XML file.
Edit this line in the XML file so the path to the DTD file (for example, C:\IBM\ITM\CNP\kcp_slabatch.dtd) is correct:

<!DOCTYPE CicsSlaDefinitions SYSTEM "kcp_slabatch.dtd">
---
</CicsSlaDefinitions>

The<CicsSlaDefinitions> tag is the root element for the document and all subsequent elements are nested within this tag. When you export definitions, the output has a timestamp and a description of the log file location. The timestamp is displayed as a comment line in the file.

The XML document can list the primary elements in any order, but the utility imports all elements of a particular type in order. That is, all Workloads first, then Service Class, then Service Policy, then Control, and ActivePolicy. Each instance represents a single row within the respective SLA table. The order in which these tags are displayed is not enforced (for example, a Workload element could be defined first, then a Service Class element, followed by a second Workload element), but when the file is processed it is completed in order. For example, if a Service Class element refers to a Workload element, then that Workload element must have already been defined in the file or existed previously in the SLA tables.

For example:

<Workload>
---
</Workload>
<ServiceClass>
---
</ServiceClass>
<ServicePolicy>
---
<ServicePolicy>

The tags on the next level of the document identify the elements for each component.

The structure of the Workload element contains a name and a description.

For example:

<Workload>
      <Name>...</Name>
      <Description>...</Description>
</Workload>

These are the tags for the Workload element and their values:

Table 1. Tags for the Workload element and their values
Element name	Description
`<Name>...</Name>`	A maximum of eight characters in length. These are the valid characters: A-Z, a-z, 0-9 and any of the following, $ @ # . / - _ % & ¢ ? ! : \| = ¬ ; < >. Note, the comma (,) and double quote (") characters are not valid. Any lowercase characters you supply are converted to uppercase.
`<Description>...</Description>`	A maximum of 24 characters in length. The valid characters are any basic Latin ASCII characters.

The structure of the ServiceClass element adds the first complexity by requiring a BaseGoal attribute to be defined.

For example:

<ServiceClass>
      <Name>...</Name>
      <WorkloadName>...</WorkloadName>
      <Rule>...</Rule>
      <BaseGoal>
        <ResponseTime>...</ResponseTime>
        <PercentOfGoal>...</PercentOfGoal>
      </BaseGoal>
</ServiceClass>

Note: The WorkloadName element referred to in this example must already exist in the WORKLOAD table for the ServiceClass element to be created successfully.

Table 2. The ServiceClass element and their values
Element name	Description
`<Name>...</Name>`	A maximum of eight characters in length. These are the valid characters: A-Z, a-z, 0-9 and any of the following, $ @ # . / - _ % & ¢ ? ! : \| = ¬ ; < >. Note, the comma (,) and double quote (") characters are not valid. Any lowercase characters you supply are converted to uppercase.
`<WorkloadName>...</WorkloadName>`	A maximum of eight characters in length. These are the valid characters: A-Z, a-z, 0-9 and any of the following, $ @ # . / - _ % & ¢ ? ! : \| = ¬ ; < >. Note, the comma (,) and double quote (") characters are not valid. Any lowercase characters you supply are converted to uppercase.
`<Rule>...</Rule>`	A maximum length of 1000 characters and does not convert the expression into another format from the Reverse Polish Notation (RPN). Contains the rule used to identify the transactions that are applicable to this ServiceClass attribute in RPN. These are the valid characters: A-Z, a-z, 0-9 and any of the following, $ @ # . / - _ % & ¢ ? ! : \| = ¬ ; < >. Note, the comma (,) and double quote (") characters are not valid. Any lowercase characters you supply are converted to uppercase. Note: Ensure that your RPN is valid before attempting to import definitions. Any lowercase characters you supply for rule values are converted to uppercase. The rule type labels (TranID, UserID, CICSname, LUname) are case sensitive and must be written in this form.
`<BaseGoal>...</BaseGoal>`	Identifies the data that appears within the GOAL table.
`<ResponseTime>...</ResponseTime>`	A four byte integer that represents the time goal in thousands of a second (0.001 seconds).
`<PercentOfGoal>...</PercentOfGoal>`	An integer running between 0 and 100. If the value is 0, then the monitoring agent interprets this as an average goal rather than a percentage.

The ServicePolicy element is similar to ServiceClass element in that goals can be defined; for example, an OverrideGoal. Only BaseGoals that have been overridden are shown in this example:

<ServicePolicy>
      <Name>...</Name>
      <Description>...</Description>
      <OverrideGoal>
		      <ServiceClassName>...</ServiceClassName>
            <ResponseTime>...</ResponseTime>
            <PercentOfGoal>...</PercentOfGoal>
      </OverrideGoal>
</ServicePolicy>

Note, that unlike the Service Class description, which must have a single base goal, a ServicePolicy element can have zero, one, or many override goals. At most there would be an override goal definition for each Service Class element that has been defined. The constraints on the various fields are the same as for the Workload and Service Class elements. When you are defining an OverrideGoal element, the Service Class element you are overriding, must specify the base goal.

Table 3. The ServicePolicy element and their values
Element name	Description
`<Name>...</Name>`	A maximum of eight characters in length. These are the valid characters: A-Z, a-z, 0-9 and any of the following, $ @ # . / - _ % & ¢ ? ! : \| = ¬ ; < >. Note, the comma (,) and double quote (") characters are not valid. Any lowercase characters you supply are converted to uppercase.
`<Description>...</Description>`	A maximum of 24 characters in length. The valid characters are any basic Latin ASCII characters.

The Control element represents the collection interval and workload management of SLA definitions. For example:

<Control>
		<CollectionInterval>...</CollectionInterval>
		<WLMType>...</WLMType>
</Control>

The CollectionInterval value determines the summarization interval for historical collection.

The CollectionInterval value is the time of the format HHMM, where HH is 00 or 01 and MM (if HH is 00) is 01 or 05 or 15 or 30.

SLA collection allows only one of these values:

0001
0005
0015
0030
0100

If you want to change the collection interval from the default 15 minutes to 1 hour, define the value as follows:

<CollectionInterval>0100</CollectionInterval>

If you want to change the collection interval to 1 minute, define the value in the following XML format:

<Control>
		<CollectionInterval>0001</CollectionInterval>
</Control>

The WLMType is one of following values:

OMEGAMON®
z/OS®
AUTO

These values are the different Workload Manager types; the same values that appear in the CICS® SLA view. If you want to switch to the OMEGAMON WLM type, you define the value in the following XML format:

<Control>
		<WLMType>OMEGAMON</WLMType>
</Control>

The value within the tags is not case sensitive.

The final tag for this level of the XML document represents the active service policy.

For example:

<ActivePolicy>
---
</ActivePolicy>