Summary: This section describes how to create a new custom component. Please note that it is not possible to create custom components to interact with the CAST Management Studio installation packs: PMC, PMC_LOCAL, CORE_PMC and PMC_CENTRAL.

Define the .pck file for the component

CAST recommends naming the .pck file with the same name as defined in the "PackName" attribute in the .pck file and with a CUST_ prefix. So for example:

Use the following template to define your .pck file:

<?xml version="1.0" encoding="iso-8859-1" ?>
<Package PackName = "CUST_xxxx" Type = "SPECIFIC" SupportedServer=" " Version = "x.x.x.x" Display=" " Description=" " DatabaseKind=" ">
   <Include>
      <PackName>SYSTEM</PackName>
      <Version>1.0.0</Version>
   </Include>
   <Exclude>
      <!-Do not use for Custom component->
   </Exclude>
   <Install>
      <!-Add step for installation->
   </Install>
   <Update>
      <!-Add step for update->
   </Update>
   <Refresh>
      <!-Add step for refresh->
   </Refresh>
   <Remove>
      <!-Do not use for Custom component->
   </Remove>
</Package>

The following table explains the attributes that need to be defined in the root "package" tag:

Name

Description

Information

Status

PackName

Component Name

Must be unique (used as a reference key).  CAST recommends prefixing your PackName with CUST_

Mandatory

Version

Component version

<VerMaj>.<VerMin>.<Rev>.<Build>

Mandatory

Display

Display string

<used only in log file>

Optional

Description

Description

<used only in log file>

Optional

DatabaseKind

Describes the target CAST schema

Can be any of the following:

  • KB_LOCAL (Analysis Service)
  • KB_CENTRAL (Dashboard Service)
  • KB_AAD (Measurement Service)
  • KB_PMC (Management Service)
Mandatory

Note that "PackName" must not use a name that is already used by the CAST AIP schema installation process. This includes (but is not an exhaustive list):

Define installation and update operations in the .pck file

INSTALL tag

The commands defined within the INSTALL tags are executed once during the initial installation of a new component. Use this zone only to install critical objects that must not be dropped (e.g.: tables for persistent data storage). For working tables, reference tables, procedures and functions use the REFRESH tag instead.

REFRESH tag

Commands defined within the REFRESH tags are executed each time the component is installed, upgraded or reinstalled. CAST Server Manager processes the script and drops existing objects before creation if they exist on the server (data in tables will be lost). Use this zone for:

IMPORTANT: always try to use the REFRESH tag where possible

UPDATE tag

Commands defined within the UPDATE tags are executed during a migration. Use the migration process only when necessary:

Define an operation step in the .pck file

Operation steps are added to the .pck in the zones specified above (INSTALL, REFRESH and UPDATE). A step can be defined between the <Step xxxx> and <\Step> tags. "xxxx" defines all the information required for the execution of this step. Steps are executed in the order of their definition in the .pck file.

Name

Description

Information

Zone
INSERT (I)/UPDATE (U)/REFRESH (R)

Status

Type

Operation type

Authorized values:

  • PROC and TABLE - used to process SQL script files for creation of either PROCEDURES or TABLES in the target AIP schema. For example:
<Step Type="PROC" Option="[value]" File="[path\to\some_file.sql]">
<Step Type="TABLE" Option="[value]" File="[path\to\some_file.sql]">
  • DATAperforms a scoped import into existing tables of the content of XMLTODB data .xml file, with the scope defined in .xml model file (i.e a DML placeholder). For example:
<Step Type="DATA" File="[path\to\some_data_file.xml]" Model="[path\to\some_model_file.xml]" Scope="[scope]">

//Format of some_data_file.xml
 
<?xml version="1.0" encoding="UTF-8" ?>
<DATA>
	<TEST_TABLE>
		<OBJECT_ID>1</OBJECT_ID>
		<OBJECT_DESCRIPTION>Description 1</OBJECT_DESCRIPTION>
	</TEST_TABLE>
	<TEST_TABLE>
		<OBJECT_ID>2</OBJECT_ID>
		<OBJECT_DESCRIPTION>Description 2 </OBJECT_DESCRIPTION>
	</TEST_TABLE>
	
</DATA>

//Format of some_model_file.xml

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="..\CAST_XMLDB_Format.xsd" >
 
	<table name="TEST_TABLE"  description="Give description of table" >
		<column name="OBJECT_ID" type="int" nullable="false" description="Column description" />
		<column name="OBJECT_DESCRIPTION" type="string" nullable="true" length="250" description="Column description"  />
		<index name="IDX_TEST_TABLE" type="index" >
			<column name="OBJECT_ID" sort="asc" />
		</index>
	</table>
 
  <scope name="TESTSCOPE">
		<scopetable name="TEST_TABLE"/>
  </scope>
  
</config>
  • XML_MODEL - (mostly used internally by CAST) performs a scoped import into new tables of the content of XMLTODB data .xml file with a scope (i.e. a DDL placeholder). For example:
<Step Type="XML_MODEL" File="[path\to\some_data_file.xml]" Scope="[scope]">

//Format of some_data_file.xml
 
<?xml version="1.0" encoding="UTF-8" ?>
<DATA>
	<TEST_TABLE>
		<OBJECT_ID>1</OBJECT_ID>
		<OBJECT_DESCRIPTION>Description 1</OBJECT_DESCRIPTION>
	</TEST_TABLE>
	<TEST_TABLE>
		<OBJECT_ID>2</OBJECT_ID>
		<OBJECT_DESCRIPTION>Description 2 </OBJECT_DESCRIPTION>
	</TEST_TABLE>
	
</DATA>


I / U / R

Mandatory

Option

Parameter handling

Numeric value, one of the following:

  • Option = "0" (Normal flow)
  • Option = "4" (OVERWRITE - force drop for existing objects in UPDATE scripts)
  • Option = "8" (ADD_GRANT)
  • Option = "16" (ADD_VOLATILE)
  • Option = "32" (NOT_LOGGED)
  • Option = "64" (SKIP_EXEC)
  • Option = "128" (NO_RETRY)
  • Option = "256" (PLAY_INDEX_ONLY - install index only)
  • Option = "512" (PLAY_TABLE_ONLY - install table only)

U

Optional

File

File name

Path for file:

  • Relative path file with .pck directory as reference.
  • SQL script file or XML file (depending on Type)

I / U / R

Mandatory

ToVersion

Destination version

New version for the component

U

Mandatory

FromVersion

Initial version

Initial version for the component

U

Mandatory / Optional

ServerVersion

Supported version

Provides a means to configure different scripts for Microsoft SQLServer. Warning: not to be used to specify scripts for different RDBMS (Oracle / Microsoft SQLServer / CSS)

I / U / R

Optional

Model

XML Model File

Path file for XML model file to use in data transfer (relative path)

I / U / R

Mandatory for type DATA

DataWay

Way of transfer ToDb / ToXML

Use this to perform an export or import of data into/out of the database (with datatransfer)


Optional. Default = ToDB

Scope

import xml parameter

Scope defined in Model XML


Optional

Example with comments

Component name: CUST_COMPONENT

First release of component

.pck file

<?xml version="1.0" encoding="iso-8859-1" ?>
<PackagePackName = "CUST_COMPONENT" Type = "SPECIFIC" Version ="1.0.0.1" SupportedServer = "ALL" Display="" Description="" DatabaseKind=" ">
   <Include>
      <PackName>SYSTEM</PackName>
      <Version>1.0.0</Version>
   </Include>
   <Exclude>
   </Exclude>
   <Install>
      <Step Type="TABLE" File ="fileTable1.sql></Step>
      <Step Type="DATA" File="fileXMLData1.xml" Model = "ModelXML.xml"></step>
   </Install>
   <Update>
   </Update>
   <Refresh>
      <Step Type="TABLE" File=" fileTable2.sql"></step>
      <Step Type="TABLE" File=" fileTable3.sql"></step>
      <Step Type="PROC" File=" fileProc2.sql"></step>
      <Step Type="DATA" File="fileXMLData2.xml" Model = "ModelXML.xml"></step>
   </Refresh>
   <Remove>
   </Remove>
</Package>

Initial execution will run:

Second execution using reinstall will run

Second release of component

.pck file

<?xml version="1.0" encoding="iso-8859-1" ?>
<Package PackName = "CUST_COMPONENT "Type = "SPECIFIC" Version ="1.1.0.1" SupportedServer = "ALL" Display="" Description="" DatabaseKind=" ">
   <Include>
      <PackName>SYSTEM</PackName>
     <Version>1.0.0</Version>
   </Include>
   <Exclude>
   </Exclude>
   <Install>
      <Step Type="TABLE" File ="fileTable1.sql></Step>
      <Step Type="TABLE" File ="fileNewTable1.sql"></Step>
      <Step Type="DATA" File="fileXMLData1.xml" Model = "ModelXML.xml"></step>
   </Install>
   <Update>
      <Step Type="TABLE" File ="fileNewTable1.sql" FromVersion="1.0.0.1" ToVersion=1.1.0.1></Step>
      <Step Type='DATA" File="fileXMLData1.xml" Model = "ModelXML.xml" FromVersion="1.0.0.1" ToVersion=1.1.0.1></step>
   </Update>
   <Refresh>
      <Step Type="TABLE" File=" fileTable2.sql"></step>
      <Step Type="TABLE" File=" fileTable3.sql"></step>
      <Step Type="PROC" File=" fileProc2.sql"></step>
      <Step Type="PROC" File=" FileNewTableProc.sql"></step>
      <Step Type="DATA" File="fileXMLData2.xml" Model = "ModelXML.xml"></step>
   </Refresh>
   <Remove>
  </Remove>
</Package>

First execution on previously installed database (version 1.0.0.1):

Specific information for UPDATE

The migration process for user components may be complex. For example, suppose you have the following case:

Your component might be impacted by a modification made between each version of CAST. Upgrades should be written from one version to the next without using cumulative updates. A migration from V1 to V3 will not be V1 to V2 + V2 to V3 but a direct migration from V1 to V3. For this example you will need to write two migration processes: V1 to V3 and V2 to V3. In the .pck file this update is added to the UPDATE zone as follows:

<Step Type="TABLE" File ="updateV1V3.sql" FromVersion="V1" ToVersion=V3></Step>
<Step Type="TABLE" File ="updateV2V3.sql" FromVersion="V2" ToVersion=V3></Step>

In this case:

Further information

CAST Server Manager automatically performs the following tasks:

Writing SQL script for CAST Server Manager

Separators need to be added between each statement:

Finish the script file with a separator on a separate line.