PATROL Knowledge Module Icons and Images for PATROL 3.

5 and PATROL Central

TM

Contents
Whats New .....................................................................................................................1 KM Directives..................................................................................................................1 Example KM Directives ............................................................................................... 2 MOF Package Files......................................................................................................... 3 Example MOF Package File ....................................................................................... 3 Icons and Images ........................................................................................................... 4 PATROL Console Icons .............................................................................................. 6 PATROL Central Icons................................................................................................ 6 Icon File Names .......................................................................................................... 7 Image File Names .......................................................................................................7 Icon and Image Resource Files for PATROL Central Consoles .................................8 Creating a KM Image Resource File with kmres.exe ................................................ 10 PATROL KM Product File Destinations...................................................................... 11 PATROL Console Files ............................................................................................. 12 PATROL Agent Files................................................................................................. 13 PATROL Console Server Files ................................................................................. 14 PATROL CentralMicrosoft Windows Edition Files .................................................. 15

Whats New
With the new PATROL Console Server and PATROL Central Consoles, KMs require some development and packaging changes to ensure the KMs install correctly and work with the new PATROL Central Consoles, the PATROL Console for Microsoft Windows, and the PATROL Console for Unix. The following KM development and packaging changes are discussed in this document: KM directives MOF package files icons file locations

KM Directives
KMs used with the PATROL Console Server and PATROL Central have directives in the KM file. The new directives allow the console server and PATROL Central to identify the version of the KM and provide the correct KM resources to the console. For example, a new version of a KM may have different icons than a previous version of the same KM. The following directives appear as comments at the top of the KM file: release revision package description productcode
Note The directives must be added to the KM files using a text editor. The PATROL Developer Console does not provide an interface for adding the directives to the KM files.

The following table describes the console server KM directives:

Directive release Description identifies the version and release of the KM Three levels are supported, v.r.m. The package value and the release value are concatenated to form the product-specific install directory on the console server for the KM. The release value only supports v.r.m, so any KMs that release with changes to the console server or PATROL Central Web Edition Web server resources must increase the release by one point; for v.r.m, the m value must increase.

Page 1

Directive revision

Description string that identifies the revision of the KM This value is not used by the console server in this release.

package

string that identifies the KM package The package and productcode directives must have the same value, and the value must be the registered prefix of the KM.

description

string that describes the KM This value is not used by the console server in this release.

productcode (registered prefix)

string that represents the registered prefix of the KM The productcode value and the release value are concatenated to form the product-specific install directory on the console server for the KM.

Note The package and productcode directives must have the same value, and the value must be the registered prefix of the KM.

Example KM Directives
The following example shows the syntax of the directives that are added to all KM files:
!release 2.1.01 !revision 00 !package PRD !description PATROL PRD Knowledge Module !productcode PRD

The productcode value and the release value are concatenated to form the product specific install directory on the console server for the KM. This example requires the following directory structure on the console server:
PATROL_ROOT/lib/knowledge/PRD_2_1_01/

All of the *.km files in your product must add these directives.
Note Do not add these directives to your *.kml files because the PATROL Consoles will not load a .kml file with these directives.

You must use the PATROL Console version 3.5 or later when you are working with KMs that contain these directives because older PATROL Developer Consoles remove these lines when the KM is committed to the agent.
Page 2

Note You must use the PATROL 3.5 Developer Console when you are working with KMs that contain these directives because older PATROL Developer Consoles remove these lines when the KM is committed to the agent.

MOF Package Files

For the PATROL Console Server, you must create a MOF package file (package.mof) that has the same directive values defined in the KM files.

Example MOF Package File

The following example shows the contents of the package.mof file:
instance of KM_Package { cosPath = "."; Description = "PATROL Knowledge Module"; kmPackageType = 0x201; version = "1.2.01"; revision = "00"; }; Note The kmPackageType is 0x201 and cosPath is "." for all KMs, and the version is the same value as the !release directive in the KM file.

See PATROL Console Server Files on page 14 for information on where to install the
package.mof file.

Page 3

Icons and Images

With the release of the PATROL Central Consoles, KMs provide new icons for the PATROL Central Consoles. Additionally, KMs still supply the old icons for the PATROL 3.x Consoles. The new image requirements not only apply to the traditional icons used to represent objects in PATROL, but BMP images used by the PATROL Script Language (PSL) response() function must be converted to the new format for use in the PATROL Central Consoles. See the PATROL Developer Connection for more information and tools for creating PATROL icons: http://devcon.bmc.com

Page 4

The following table describes the icon guidelines for the PATROL Consoles.

Consoles
PATROL Console for Unix PATROL Console for Windows PATROL Central Web PATROL Central Windows image Transparent bitmap .BMP

Image Type Format

image XPM X11 .XPM

mask X11 bitmap (xbm) .MSK

image Windows bitmap .BMP

mask Windows bitmap .BMK (PATROL 3.3 or higher) .MSK (up to PATROL 3.3)

image Transparent GIF

File Extension

.GIF

Size

60x60

48x48

16x16 and 32x32 Black/ White White 16-256

16x16 and 32x32 16 color

Colors

16-256

Black/ White White

16-256

Image Background

White

Unused icon color

Transparent

Transparent The pixel in the top-left corner of the icon sets the transparency color for the icon.

Image Includes Platter Example

Yes

No

No

No

For backward compatibility with older consoles and hardware, all icons should be limited to sixteen colors.

Page 5

PATROL Console Icons

The icon requirements for the 3.5 PATROL Consoles have not changed.
Unix

The PATROL Console for Unix uses standard .XPM icon formats of 60x60 pixels, and a
.MSK file is required to display the objects state. Windows

The PATROL Console for Microsoft Windows uses a non-standard .BMP format of 48x48 pixels for large icon views, and a .BMK file is required to display the objects state.

PATROL Central Icons

New icons are required for PATROL CentralWindows Edition and Web Edition.
PATROL CentralWindows Edition

PATROL CentralWindows Edition is a native Windows application that requires standard

.BMP icon files:

32x32 pixels for large icon views 16x16 pixels for small icon views PATROL CentralWindows Edition uses the color of the pixel in the top, left-hand corner of the .BMP image to set the background transparency color of the image in the console.
PATROL CentralWeb Edition

PATROL CentralWeb Edition requires .GIF icon files: 32x32 pixels for large icon views 16x16 pixels for small icon views The background of the .GIF images should be specified as transparent for PATROL CentralWeb Edition.

Page 6

Icon File Names

Icons names remain the same when used in the KM, but during development, a suffix is added to the file name to indicate the type of icon. 32x32 icons add a _32 suffix large icons for the PATROL Central 16x16 icons add a _16 suffix small icons for the PATROL Central that are used in the tree view and list views 16x16 open icons add a _o_16 suffix optional open icon indicates an open state in the tree view of the console These suffixes are for development only. The suffix is removed when the icon is placed in the KM resource archive file for the console server. The following table shows example file names for an icon with the name of base:
Icon Type
Classic 3.x icon

File Name
base.bmp (Windows) or base.xpm (Unix) 3.x icons require corresponding mask files. base.bmk (Windows) or base.msk (Unix)

32x32 BMP 16x16 BMP 16x16 open BMP 32x32 GIF 16x16 GIF 16x16 open GIF

base_32.bmp base_16.bmp base_o_16.bmp base_32.gif base_16.gif base_o_16.gif

The KM references the icon using the base name.

Image File Names

Other KM images, like images used in the PSL response() function dialog boxes, do not require any special file naming convention, but they must be added to KM resource file for PATROL Central.

Page 7

Icon and Image Resource Files for PATROL Central Consoles

Images are installed on the consoles for PATROL 3.x, but the PATROL Central Consoles get images from the PATROL Console Server, so you will provide your icons and images to the console server. For the PATROL Central Consoles, icons are placed in a resource file. Each KM package will have one resource file that contains all the icons and images for the KM. Other images that are required by the KM, including images displayed in PSL response() function dialog boxes, are in a resource file for the new PATROL Central Consoles as well. The resource file for your KM package is installed into the KM package directory and is named resource.mk4.
Note The first release of the console server includes all KM icons and other images for BMC Software KMs in one resource file. This default resource file is installed in the PATROL_ROOT/lib/knowledge/default console server directory. When you install your resource file, you must not install it in the PATROL_ROOT/lib/knowledge/default directory, or you will overwrite the default icon resource file, and KMs that depend on this resource for their images will no longer have their icons. You must install your resource file in your PATROL_ROOT/lib/knowledge/prd_KMversion product directory.

See PATROL Console Server Files on page 14 for information on where to install the
resource.mk4 file.

The resource.mk4 resource file is created using the kmres.exe command-line tool provided as part of the PATROL Console Server.
kmres.exe

The kmres.exe program is located in the bin directory of your PATROL Console Server install directory (PATROL_ROOT/bin/platform). On Windows, you can execute the
kmres.exe program from any command prompt because the bin directory is added to the

path during the console server installation. On Unix, you can put these utilities in your path by sourcing the PATROL 7 environment variables by running the following command from the $PATROL_ROOT directory:
./patrol7rc.sh

Page 8

The following table describes common kmres.exe usage:

Usage
kmres -v kmres [-h | -help] kmres -create <resfile> kmres -res <resfile> -addicon <icon_file> -name <icon_res_name> [-size <icon_size>] [-overRide] kmres -res <resfile> -addicons <icon_dir> [-overRide]

Description
prints the version prints the Help message creates a new, empty resource file adds an icon to a resource file When -overRide is specified, duplicate icon are overwritten. adds images from a directory to a resource file When -overRide is specified, duplicate icon are overwritten. adds an image to a resource file adds images from a directory to a resource file lists the contents of a resource file lists the content tree of a resource file lists the content tree of a resource file

kmres -res <resfile> -addimage <image_file> -name <image_res_name> kmres -res <resfile> -addimages <image_dir> kmres -res <resfile> -print kmres -res <resfile> -list kmres -res <resfile> -listIcons The following list describes the kmres parameters:

resfilethe name of the KM resource file (resource.mk4) icon_filethe name of the icon file, see Icon File Names on page 7 icon_res_namethe name of the icon referenced by the KM, the base icon name image_filethe name of the image file, including the file extension image_res_namethe base name of the image file, excluding the file extension

Page 9

Creating a KM Image Resource File with kmres.exe

In this task, you will create a KM image resource file for use with the PATROL Console Server.
Before You Begin

Before you create an image resource file for your KM, put all of your images in a directory on a computer that has the console server installed. The images must be in the new format required by the PATROL Central Consoles. See PATROL Central Icons on page 6 for more information on image file formats.
To Create a KM Image Resource File

1. Open a command prompt on a computer that has your image files and the console server installed. 2. Create a new resource file with the following command:
kmres -create resource.mk4

3. Add all your icons to the resource file with the following command:
kmres -res resource.mk4 -addicons icondir

Where icondir is the directory and path that contains your icon files. or Add individual icons or images to the resource file with the following command:
kmres -res resource.mk4 -addicon iconfilename -name icon_res_name

Where iconfilename is the name and path of the icon you are adding, and icon_res_name is the base icon name.

Page 10

PATROL KM Product File Destinations

The installation of a PATROL KM requires that all your KM-related files are installed in the correct location in the PATROL environment. In the PATROL 3.x architecture, files are installed to the console, agent, or both. With the PATROL Central and Console Server three-tier architecture, KM files are installed in different locations. KM files may be installed on one or more of the following components: PATROL 3.5 Console PATROL 3.5 Agent PATROL Console Server PATROL CentralWindows Edition The following sections describe where to install files for the PATROL components.

Page 11

PATROL Console Files

The following table lists the directories where your KM-related files are installed for PATROL 3.5 Consoles: Unix Path File Types
.km .kml .pkg

Windows Path
$PATROL_HOME/lib/knowledge %PATROL_HOME%\lib\knowledge $PATROL_HOME/archives %PATROL_HOME%\archives

Description
application class and PATROL KM list files

PATROL package files (for the KMDS) PATROL merge map files (for migration) KM user-defined event catalog

.map

$PATROL_HOME/lib/kmmergemap %PATROL_HOME%\lib\kmmergemap

.ctg

$PATROL_HOME/lib/knowledge %PATROL_HOME%\lib\knowledge

.bmp .bmk .xpm .msk .hlp .cnt .htm .psl .bin .lib

$PATROL_HOME/lib/images %PATROL_HOME%\lib\images

icons

$PATROL_HOME/lib/help %PATROL_HOME%\lib\help\WinHelp $PATROL_HOME/lib/psl %PATROL_HOME%\lib\psl

Help files

PSL scripts and libraries not saved as part of the PATROL KM files This includes any required directories, PATROL Agent configuration files, external scripts, or procedures.

Page 12

PATROL Agent Files

The following table lists the directories where your KM-related files are installed for PATROL 3.5 Agents: Unix Path File Types
.km .kml .pkg

Windows Path
$PATROL_HOME/lib/knowledge %PATROL_HOME%\lib\knowledge $PATROL_HOME/archives %PATROL_HOME%\archives

Description
application class and PATROL KM list files PATROL package files (for the KMDS) KM user-defined event catalog files

.ctg

$PATROL_HOME/lib/knowledge %PATROL_HOME%\lib\knowledge

.psl .bin .lib

$PATROL_HOME/lib/psl %PATROL_HOME%\lib\psl

PSL scripts and libraries not saved as part of the PATROL KM files This includes any required directories, PATROL Agent configuration files, external scripts, or procedures.

.sh .bat .cmd .txt

$PATROL_HOME/lib/psl %PATROL_HOME%\lib\psl

scripts used at install time to configure KMs like scripts to preload KMs or scripts to add PAMO templates to the registry external text files that contain build number and version information used by InfoBox commands PAMO template files for PAMO reports on machines that have Microsoft Office PATROL merge map files (for migration) icons and icon masks

$PATROL_HOME %PATROL_HOME%

.reg

Windows Only %PATROL_HOME%\lib\psl

.map

$PATROL_HOME/lib/kmmergemap %PATROL_HOME%\lib\kmmergemap

.bmp .bmk .xpm .msk .bat .sh .exe

$PATROL_HOME/lib/images %PATROL_HOME%\lib\images

$PATROL_HOME %PATROL_HOME%

console-side executables for state change actions or #%MODES% menu commands that execute on the console machine

Page 13

PATROL Console Server Files

The PATROL Console Server provides KM resources for the new PATROL Central consoles. When you install your icon resource file, you must not install it in the
PATROL_ROOT/lib/knowledge/default directory, or you will overwrite the default icon

resource file, and KMs that depend on this resource for their images will no longer have their icons. You must install your resource file in your
PATROL_ROOT/lib/knowledge/prd_KMversion product directory.

The following table lists the directories that your KM-related files are installed in during the install of your PATROL KM for PATROL Console Server: Unix Path File
resource.mk4

Windows Path
$PATROL_ROOT/lib/knowledge/prd_KMversion %PATROL_ROOT%\lib\knowledge\prd_KMversion

Description
image resource file for the KM The prd_KMversion is the versionspecific directory for the KM package. KM MOF package file for the console server The prd_KMversion is the versionspecific directory for the KM package.

package.mof

$PATROL_ROOT/lib/knowledge/prd_KMversion %PATROL_ROOT%\lib\knowledge\prd_KMversion

Page 14

PATROL CentralMicrosoft Windows Edition Files

The only KM files installed on the PATROL CentralMicrosoft Windows Edition system are the console-side executables for state change actions and local (#%MODES%) menu commands. File Type
.bat .sh .exe

Path (Windows Only)

%PATROL_HOME%

Description
console-side executables used for state change action methods and #%MODES% menu commands

The PATROL CentralMicrosoft Windows Edition files are installed in the PATROL 3.5
%PATROL_HOME% directory structure. This prevents the installation of multiple copies

of console-side executables when PATROL 3.5 and PATROL CentralMicrosoft Windows Edition are installed on the same machine.

Page 15

For more information visit BMC Software on the Web at www.bmc.com

BMC Software, the BMC Software logos and all other BMC Software product or service names are registered trademarks or trademarks of BMC Software, Inc. All other registered trademarks or trademarks belong to their respective companies. 2003, BMC Software, Inc. All rights reserved. 29295 7/03