XML File Rules

Control‑M/EM utilities read input text files that are used to enter information into the Control-M/EM database. Control‑M/EM export utilities export data from the database in text files. Both the input and the output files are formatted with XML. For example, the defcal input file specifies new Calendar definitions to enter into the database. Different parts of the input file are defined by tags composed of punctuation marks. For an example, see XML File Example.

XML files have the following characteristics:

• XML is a structured format for organizing and specifying data.

• Data in an XML file is classified by type.

• Words enclosed in angle brackets (< >), called tags, are used to classify and organize the data.

In the XML files used by the Control‑M/EM utilities, tags are used to classify job processing definitions, Calendar, folder, and SMART folder parameters, and values. Each Control-M/EM utility is composed of a combination of at least two of the following parts:

• An invocation command.

• An input file containing either data to enter into the Control-M/EM database or arguments for selecting specific data from the database.

• An output file containing data specified in the arguments file, if it was used.

• Optional switches for controlling how the utility runs.

For example, the defjob utility has three parts; the invocation command, a file of job processing definitions that are imported into the Control-M/EM database, and an optional switch. You prepare the file containing the job processing definitions.

The exportdefjob utility uses an invocation command, a file containing arguments for specifying the job processing definitions that are exported from the Control-M/EM database, an optional switch, and an output file containing the exported job processing definitions. You prepare the arguments file. The output file is created by the exportdefjob utility.

Each utility contains a table of elements (job, calendar, and folder parameters) and attributes (sub parameters). If the valid value is a string, see the description of the appropriate parameter in Control‑M Parametersfor information about valid values and their formats. If working in an I18N environment, a header must be placed at the top of the arguments file, as described in XML File for I18N Environment.

XML File Example

In this example, the TERMS input file displayed all non-cyclic jobs with job name Job5. The action performed on the selected jobs is determined by the type of utility that is calling the TERMS file. Using this TERMS file with deldefjob deletes all job processing definitions in the database for non-cyclic jobs with job name Job5.

This file contains one TERMS statement. The statement specifies that non-cyclic jobs with Job Name Job5 are to be selected.

<TERMS><TERM>
<PARAM NAME="JOBNAME" OP="EQ" VALUE="Job5"/>
<PARAM NAME="CYCLIC" OP="EQ" VALUE="0"/>
</TERM>
</TERMS>

The statement begins with the word TERMS enclosed in angle brackets (<TERMS>). The end of the file is indicated by the closing TERMS tag. That this is the end of the TERMS statement is indicated by the presence of the slash (/), so that the closing statement looks like </TERMS>.

Between the <TERMS> tags is a search term for identifying and selecting specific job processing definitions. It is indicated by the tags <TERM></TERM>. Between the TERM tags are the parameters of the search, indicated by the <PARAM/> tag. All the attributes of the tag are contained within the single set of brackets. No closing tag is needed. As a result, the slash (/) is included in the single tag, preceding the closing angle bracket, <PARAM/>.

As noted, the PARAM tag contains the search terms, NAME, OP, and VALUE.

NAME is the name of a job processing definition parameter.

OP is an operator. The most common operators are described in the following table.

VALUE is the value of the parameter to which a comparison is being made.

XML File for I18N Environment

When working in an I18N environment, the following header must be placed at the top of the argument file:

<?xml version=’1.0’ encoding=’UTF-8’?>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE TERMS SYSTEM "terms.dtd">
<TERMS>
<TERM>
<PARAM NAME="JOBNAME" OP="EQ" VALUE="Job5"/>
<PARAM NAME="CYCLIC" OP="EQ" VALUE="0"/>
</TERM>
</TERMS>

XML File Validation

The contents of an XML file are determined by a set of criteria that are contained in a document type definition (dtd) file. The .dtd file is used by Control‑M/EM to validate the input file (or arguments file) when the utility runs. The .dtd file includes the following information:

• Names of all of the elements and attributes that can be entered in an input or arguments file in XML format.

Valid values for an element or attribute.

• Whether the valid values for an element or attribute are mandatory or optional.

• Hierarchical relationship between the various elements and attributes in the file.

Formatting and value information for Control‑M parameters is described in Control‑M Parameters.

Each utility input file has its own .dtd file. The arguments files share the same .dtd file. Utility .dtd files are stored in the Control‑M EM <9.0.00>\Default\data\Resource directory (on Windows).

Creating an XML File

This procedure describes how to create an input file.

Begin

1. Open any text editor or an XML editor.

2. Enter the data for the utility that you are using, the format described in the parameter description tables, and examples that are provided with the utility.

3. Check the syntax of the file for errors. If errors remain, they are identified when the file is submitted to the utility. Possible errors include:

   • Misplaced or missing tag.

   • Misplaced or missing part of a tag (for example, a missing slash /).

   • Parameter value that is not specified as a valid value for that parameter (For example: the letter Y instead of a 1)

     Control-M/EM database validates every file you submit, rejecting those that have errors. When a file is rejected, the lines containing errors are specified for you.

4. Save the file.

   The file must be saved as a text file. It can have any file extension you want. However, BMC recommends that you use .xml

Reserved Character Codes

Certain characters are reserved for formatting the XML file. These characters cannot be used in job parameter values submitted with the XML‑based utilities. Instead, each reserved character must be replaced by a code. The reserved characters and the codes are replaced and are listed in the following table:

Wildcards

Multiple jobs can be selected and copied using the * (asterisk) wildcard character to represent multiple values. The asterisk is used to represent zero or more alphanumeric characters. An asterisk can also be used to replace characters in the middle of an expression.

The asterisk has a special function when used in find and replace operations in selected utilities. The following utilities use find and replace operations:

• copydefcal

• copydefjob

• duplicatedefjob

• updatedef

In the FROM (find) statement of an argument, an asterisk replaces a text string (as shown in the example above). The asterisk in the TO statement of the argument represents the same string as the asterisk in the FROM statement of the argument. The placement of the asterisk can be changed.