applicationxtender reports management scripting - dell emc · applicationxtender reports management...

AppXRptMgmtScriptUG.book Monday, February 9, 2009 10:04 AM

EMC® ApplicationXtender®Reports Management Scripting

6.0

User’s Guide300-008-286

REV A01

EMC Corporation Corporate Headquarters:

Hopkinton, MA 01748-9103

1-508-435-1000 www.EMC.com

2


Copyright © 1994-2009 EMC Corporation. All rights reserved.

Published March, 2009

EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED “AS IS.” EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.

For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com.

All other trademarks used herein are the property of their respective owners.

ApplicationXtender Reports Management Scripting User’s Guide

Contents


Preface.............................................................................................................................. 5

Chapter 1 BI Gateway ScriptsOverview of the BI Gateway Script Feature ................................... 8Send Email Notification Sample ....................................................... 9Copy Export File Sample ................................................................. 10Write to Database Sample................................................................ 11

Chapter 2 Report Error ScriptsOverview of Report Error Scripts .................................................. 14Send Email Notification Sample ..................................................... 15Write Log to File Sample.................................................................. 16Write to Database Sample................................................................ 17

Chapter 3 XDS SCRIPT FunctionOverview of the XDS SCRIPT Function ........................................ 20Date Format Conversion Sample.................................................... 21Key Value Lookup Function............................................................ 23Key Value Check Function............................................................... 25

Index ................................................................................................................................ 27

ApplicationXtender Reports Management Scripting User’s Guide 3

Contents


ApplicationXtender Reports Management Scripting User’s Guide4


Preface

This document provides instructions for using the features in ApplicationXtender Reports Management (AppXtender Reports Mgmt) that call custom script files.

As part of an effort to improve and enhance the performance and capabilities of its product lines, EMC periodically releases revisions of its hardware and software. Therefore, some functions described in this document may not be supported by all versions of the software or hardware currently in use. For the most up-to-date information on product features, refer to your product release notes.

If a product does not function properly or does not function as described in this document, please contact your EMC representative.

Audience The information in this document is intended for users who are responsible for using ApplicationXtender Reports Management and custom script files.

Related documentation

Post-release information is contained in the Release Notes for this product. This document is available at http://Powerlink.EMC.com. Refer to the web site periodically to view the latest Release Notes.

Related documents include:

◆ ApplicationXtender Reports Management Administrator’s Guide

◆ ApplicationXtender Reports Management Quick Reference

◆ ApplicationXtender Reports Management XDS Quick Reference

◆ ApplicationXtender Reports Management Technical Notes

Most of these documents can be found in the Documentation directory on the product media kit. All documents are in Adobe


http://powerlink.emc.com

http://Powerlink.EMC.com

6

Preface


Acrobat Portable Document Format (PDF), and can be viewed by downloading and installing the Adobe Acrobat Reader. The Reader is available on the EMC® ApplicationXtender/ApplicationXtender Web Access media kit, or directly from Adobe at www.adobe.com. To install and use the Reader on the preferred platform, refer to the instructions on the Adobe web site.

Conventions used in this document

EMC uses the following conventions for special notices.

Note: A note presents information that is important, but not hazard-related.

CAUTION!A caution contains information essential to avoid data loss or damage to the system or equipment. The caution may apply to hardware or software.

IMPORTANT!An important notice contains information essential to operation of the software. The important notice applies only to software.

Where to get help EMC support, product, and licensing information can be obtained as follows.

Product information — For documentation, release notes, software updates, or for information about EMC products, licensing, and service, go to the EMC Powerlink website (registration required) at:

http://Powerlink.EMC.com

Technical support — For technical support, go to EMC Customer Service on Powerlink. To open a service request through Powerlink, you must have a valid support agreement. Please contact your EMC sales representative for details about obtaining a valid support agreement or to answer any questions about your account.


http://powerlink.emc.com


1BI Gateway Scripts

This chapter describes the feature within the BI Gateway interface of ApplicationXtender® Reports Management (AppXtender Reports Mgmt) that initiates a script file following completion of the data export file.

◆ Overview of the BI Gateway Script Feature..................................... 8◆ Send Email Notification Sample ........................................................ 9◆ Copy Export File Sample .................................................................. 10◆ Write to Database Sample ................................................................. 11

BI Gateway Scripts 7

8

BI Gateway Scripts


Overview of the BI Gateway Script FeatureThe BI Gateway interface includes the ability to initiate a script file, written in either VBScript or JavaScript, immediately following completion of the data export file. The only requirement for the script file is that it must start with the following function statement:

Function ERMXDataExport(strReportType, strExportFile, strWorkStation)

The parameters passed in this function are supplied automatically by AppXtender Reports Mgmt when the script is executed. The strReportType parameter returns the report type name. The strExportFile parameter returns the full path for the export file of data values. The strWorkStation parameter returns the workstation ID. The only restriction for using the script at this time is that it cannot be used to initiate a GUI interface, such as opening another application.

The following sections provide specific sample scripts for using this feature:

◆ “Send Email Notification Sample”

◆ “Copy Export File Sample”

◆ “Write to Database Sample”


BI Gateway Scripts


Send Email Notification SampleThe following VBScript sample may be used to send an email message upon completion of the data export in AppXtender Reports Mgmt. This sample, which uses the NewMail object from the CDONTS library, requires that the SMTP Service be installed and running with Microsoft IIS on the AppXtender Reports Mgmt Report Processor Server.

Public Function ERMXDataExport(strReportType, strExportFile, strWorkStation)

Dim objNewMail Set objNewMail = CreateObject("CDONTS.NewMail") objNewMail.Send "[email protected]",

"[email protected]", "ERMX BI Gateway Export Completed", _

"Data export has been completed for the " + strReportType & " report type. The data export file is located at " + strExportFile, 1

Set objNewMail = NothingEnd Function

The Send() method of the NewMail object uses the following syntax to compose the email message:

NewMail.Send "sender's address", "recipient's address", "subject", "body text", importance

Thus, to customize this message you would just need to insert the appropriate sender and recipient email addresses and, if desired, edit the subject and body text.

In the sample provided, the function parameters strReportType and strExportFile are used to insert the actual report type name and the full path of the export data file into the email message text.

The VBScript file for this sample is located in:

\<AppXtender Reports Management installation directory>\AppXtenderRptsMgmtScripting\BIGatewayScriptSamples\SendEMail.vbs.

Send Email Notification Sample 9

10

BI Gateway Scripts


Copy Export File SampleThe following VBScript sample may be used to copy the export file to another location. This sample uses the CopyFile() method of the File System Object, which is referenced through the Microsoft Scripting Runtime library. The source and destination paths may absolute or relative or even a network path or share name.

Function ERMXDataExport(strReportType, strExportFile, strWorkStation)

Dim oFileCopy Set oFileCopy =

CreateObject("Scripting.FileSystemObject") oFileCopy.CopyFile strExportFile, "e:\Cx50_Docs\" Set oFileCopy = NothingEnd Function

The CopyFile() method of the File System Object uses the following syntax:

FileSystemObject.CopyFile Source, Destination [, OverwriteFiles]

In the sample, the function parameter strExportFile is used to provide the source, and the destination folder is given as "e:\Cx50_Docs\" (since the destination only specifies a folder, the same file name from the source will be used for the file name in the destination). Thus, to customize this sample you would only need to substitute the desired destination in place of "e:\Cx50_Docs\". The parameter OverwriteFiles is a Boolean flag indicating whether an existing file is to be overwritten (default value is True).


\<AppXtender Reports Management installation

directory>\AppXtenderRptsMgmtScripting\BIGatewayScriptSa

mples\CopyFile.vbs.


BI Gateway Scripts


Write to Database SampleThe following VBScript sample may be used to copy the report type, export file name, and workstation ID to a specified database table. The database connection is established using the Connection object of the ADO object model. The sample includes code statements for connecting to either a SQL, Oracle, or Access database.

Public Function ERMXDataExport(strReportType, strExportFile, strWorkStation)

Dim sql, cn 'create the connection string

'the following is a SQL Server connection string, enter the correct information

Const ConnectString = "Provider=sqloledb;Data Source=SERVER_NAME;Initial Catalog=DATABASE_NAME;User Id=username;Password=passwd;"

'the following is an Oracle connection string, enter the correct information

'Const ConnectString = "Provider=MSDAORA.1;Data Source=SERVICE_NAME;User Id=username;Password=passwd;"

'the following is an Access connection string, enter the correct information

'Const ConnectString = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=PATH_TO_.MDB_FILE"

Set cn = CreateObject("ADODB.Connection")

'open the connection cn.Open ConnectString

'the following sql command is run on a database with a table named ERMX_EXPORT with three VARCHAR columns: REPORT_TYPE,EXPORT_FILE and WORKSTATION_ID

sql = "INSERT INTO ERMX_EXPORT(REPORT_TYPE,EXPORT_FILE,WORKSTATION_ID) VALUES('" & strReportType & "','" & strExportFile & "','" & strWorkStation & "')"

cn.execute (sql) 'if this is an Oracle database don't forget the

commit statement 'sql = "commit;"

Write to Database Sample 11

12

BI Gateway Scripts


'execute the commit 'cn.execute(sql)

'close the connection cn.Close

End Function

To customize the sample, information (as indicated in the sample) must be substituted to specify your unique data source, database table and column names, user ID, and password. You must also be sure to either delete or comment out the code statements for the types of databases to which you will not be connecting.



directory>\AppXtenderRptsMgmtScripting\BIGatewayScriptSa

mples\DatabaseScript.vbs.



2Report Error Scripts

This chapter describes the feature in AppXtender Reports Mgmt that provides the ability to initiate a script file immediately following a report processing failure.

◆ Overview of Report Error Scripts .................................................... 14◆ Send Email Notification Sample ...................................................... 15◆ Write Log to File Sample ................................................................... 16◆ Write to Database Sample ................................................................. 17

Report Error Scripts 13

14

Report Error Scripts


Overview of Report Error Scripts AppXtender Reports Mgmt includes the ability to initiate a script file, written in either VBScript or JavaScript, immediately following a report processing failure. The only requirement for the script file is that it must start with the following function statement:

Function ERMXReportError(ReportType, InstanceId, MessageLogText)

The parameters passed in this function are supplied automatically by AppXtender Reports Mgmt when the script is executed. The ReportType parameter returns the report type name. The InstanceId parameter returns the report instance identifier. The MessageLogText parameter returns the actual message log text (restricted to 4K). The only restriction for using the script at this time is that it cannot be used to initiate a GUI interface, such as opening another application.

The following sections provide specific script samples for this script function:

◆ “Send Email Notification Sample”

◆ “Write Log to File Sample”

◆ “Write to Database Sample”




Send Email Notification SampleThe following VBScript sample may be used to send an email message upon a report processing failure in AppXtender Reports Mgmt. This sample, which uses the NewMail object from the CDONTS library, can be used only on Windows Server platforms (Windows 2003) and requires that the SMTP Service be installed and running with Microsoft IIS on the AppXtender Reports Mgmt Report Processor Server.

Public Function ERMXReportError(ReportType, InstanceId, MessageLogText)

Dim objNewMail Set objNewMail = CreateObject("CDONTS.NewMail") objNewMail.Send "[email protected]",

"[email protected]", "ERMX Report Processing Failed", _

"Report processing has failed for the " + ReportType & " report type. The report instance identifier is: " + InstanceId & ". The message log text is: " + MessageLogText, 1

Set objNewMail = NothingEnd Function

The Send() method of the NewMail object uses the following syntax to compose the email message:

NewMail.Send "sender's address", "recipient's address", "subject", "body text", importance

Thus, to customize this message you would just need to insert the appropriate sender and recipient email addresses and, if desired, edit the subject and body text.

In the sample provided, the function parameters ReportType, InstanceId, and MessageLogText are used to insert the actual report type name, report instance identifier, and message log text into the email message text.


\<AppXtender Reports Management installation directory>\AppXtenderRptsMgmtScripting\RptErrorScriptSamples\RptErrSendEMail.vbs.

Send Email Notification Sample 15

16



Write Log to File SampleThe following VBScript sample may be used to write the message log text to a text file, the file name of which contains the report type name and instance identifier. This sample uses the CreateTextFile() method of the File System Object, which is referenced through the Microsoft Scripting Runtime library.

Function ERMXReportError(ReportType, InstanceId, MessageLogText)

Dim fso, LogFile Set fso = CreateObject("Scripting.FileSystemObject") Set LogFile = fso.CreateTextFile("C:\Temp\" +

ReportType + "_" + InstanceId + ".log", True) LogFile.Write(MessageLogText) LogFile.Close Set LogFile = nothing Set fso = nothingEnd Function

The CreateTextFile() method of the File System Object uses the following syntax:

FileSystemObject.CreateTextFile Filename [, Overwrite[, Unicode]])

In the sample, the file is written to the C:\Temp directory and the function parameters ReportType and InstanceId are used to insert the report type name and instance identifier in the file name. To customize this sample you simply need to substitute the desired directory in place of "C:\Temp". The optional parameter Overwrite is a Boolean flag indicating whether an existing file is to be overwritten (default value is False).


\<AppXtender Reports Management installation directory>\AppXtenderRptsMgmtScripting\RptErrorScriptSamples\RptErrWriteLog.vbs.




Write to Database SampleThe following VBScript sample may be used to copy the report type, export file name, and workstation ID to a specified database table. The database connection is established using the Connection object of the ADO object model. The sample includes code statements for connecting to either a SQL, Oracle, or Access database.

Public Function ERMXReportError(ReportType, InstanceId, MessageLogText)

Dim sql, cn 'create the connection string

'the following is a SQL Server connection string, enter the correct information

Const ConnectString = "Provider=sqloledb;Data Source=SERVER_NAME;Initial Catalog=DATABASE_NAME;User Id=username;Password=passwd;"

'the following is an Oracle connection string, enter the correct information

'Const ConnectString = "Provider=MSDAORA.1;Data Source=SERVICE_NAME;User Id=username;Password=passwd;"

'the following is an Access connection string, enter the correct information

'Const ConnectString = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=PATH_TO_.MDB_FILE"

Set cn = CreateObject("ADODB.Connection")

'open the connection cn.Open ConnectString

'the following sql command is run on a database with a table named ERMX_EXPORT with three VARCHAR columns: REPORT_TYPE,INSTANCE_ID and MESSAGE_LOG_TEXT

sql = "INSERT INTO ERMX_EXPORT(REPORT_TYPE,INSTANCE_ID,MESSAGE_LOG_TEXT) VALUES('" & ReportType & "','" & InstanceId & "','" & MessageLogText & "')"

cn.execute (sql) 'if this is an Oracle database don't forget the

commit statement 'sql = "commit;"

Write to Database Sample 17

18



'execute the commit 'cn.execute(sql)

'close the connection cn.Close

End Function

To customize the sample, information (as indicated in the sample) must be substituted to specify your unique data source, database table and column names, user ID, and password. You must also be sure to either delete or comment out the code statements for the types of databases to which you will not be connecting.



directory>\AppXtenderRptsMgmtScripting\RptErrorScriptSam

ples\RptErrDatabase.vbs.



3XDS SCRIPT Function

This chapter describes the SCRIPT function in the AppXtender Reports Mgmt Extract Definition Script (XDS) that calls custom script files.

◆ Overview of the XDS SCRIPT Function.......................................... 20◆ Date Format Conversion Sample..................................................... 21◆ Key Value Lookup Function............................................................. 23◆ Key Value Check Function................................................................ 25

XDS SCRIPT Function 19

20

XDS SCRIPT Function


Overview of the XDS SCRIPT FunctionThe XDS language, which is used to write the scripts for extracting index values from reports using the AppXtender Reports Mgmt Report Processor, has been enhanced with a new function called SCRIPT. The SCRIPT function works in conjunction with the IF, SET, and ADDTO instructions to call a function from a specified VBScript or JavaScript file during the extraction process. Inside the script, various operations may be performed, including executing a database table lookup or calling any other COM objects. For the IF instruction, the script file can be called and if a specified function returns true, then the following instructions will be executed. For the SET and ADDTO functions, a script file function can be called to help define a value for a specified variable. For precise syntax instructions for using the SCRIPT function, refer to the XDS Reference help file available in AppXtender Reports Mgmt.

The following guidelines should be heeded when creating scripts:

◆ Do not perform heavy operations using the script as it could negatively affect the extraction performance

◆ Reuse resources, such as database connections and file handles, in each function call

◆ The script environment will free all resources after report instance processing, so there is no need to explicitly free resources

◆ Do not rely on the script static/state variable for the result calculation as the script environment may reinitialize the script

The following sections provide specific script samples that can be initiated by the SCRIPT function:

◆ “Date Format Conversion Sample”

◆ “Key Value Lookup Function”

◆ “Key Value Check Function”


XDS SCRIPT Function


Date Format Conversion SampleThe following VBScript function converts a string with a date format of ’DDMMMYY’ to a format of ’YYYY-MM-DD’. To see how it works in conjuction with an XDS procedure, an AppXtender Reports Mgmt Report Type configuration file (STMT.cfg) has been included to demonstrate specifying the VBScript file name in the procedure settings, calling a function from the VBScript file using the SCRIPT function within the SET instruction, and then storing the returned date value as an index field value with the STORE instruction.

Function dateFormatConvert(ByVal sDate)

'The length of the date being passed 'in should be 7. If it is not then 'return an empty string and exit the 'function. If (len(sDate) <> 7) Then dateFormatConvert = "" Exit Function End If

'Regular expression. Dim regEx 'Create a regular expression. regEx = New RegExp 'Set date pattern(DDMMMYY). regEx.Pattern = "\d{2}[A-Za-z]{3}\d{2}"

'Test for date pattern. If it exists 'convert date. If not return an empty 'string and exit the function. Dim sMonth, sDay, sYear If (regEx.Test(sDate)) Then

'Extract day value. sDay = mid(sDate, 1, 2) 'Extract month value. sMonth = mid(sDate, 3, 3) 'Extract year value. sYear = mid(sDate, 6, 2)

'Convert the alpha month to a numeric 'value. If the function fails return 'an empty string and exit the function. If Not monthToNumeric(sMonth) Then dateFormatConvert = "" Exit Function End If

Date Format Conversion Sample 21

22

XDS SCRIPT Function


'Convert the two-digit year to a 'four-digit year. sYear = yearConvert(CHECK_YEAR, sYear)

'Return the new date and exit the function. dateFormatConvert = sMonth + "-" + sDay + "-"

+ sYear Exit Function

Else dateFormatConvert = "" Exit Function End If

End Function

There are two other functions included in the same VBScript file (DataConvert.vbs), one that converts a month value from a three-letter abbreviation format to a two-digit numeric format, and one that converts a year value from a two-digit format to a four-digit format.



directory>\AppXtenderRptsMgmtScripting\XDSScriptSamples\

DateConvert.vbs.

The AppXtender Reports Mgmt Report Type configuration file is located in:

\<AppXtender Reports Management installation directory>\AppXtenderRptsMgmtScripting\XDSScriptSamples\STMT.cfg


XDS SCRIPT Function


Key Value Lookup FunctionThe following VBScript function looks up a key value in an Excel spreadsheet. If the key value is found, a second value associated with the key value is returned. To see how it works in conjuction with an XDS procedure, an AppXtender Reports Mgmt Report Type configuration file (STMT_TYPE.cfg) has been included to demonstrate specifying the VBScript file name in the procedure settings, calling a function from the VBScript file using the SCRIPT function within the SET instruction, and then storing the returned value as an index field value with the STORE instruction.

'Const string holds the Excel file path.const DATA_FILE = "W:\ERMXTest\config\Account.xls"'Global ADODB connection objectDim g_cn'Global ADODB recordset objectDim g_rs

Function keyLookup(sKey)

'String that holds the SQL command Dim sQuery 'String to hold return value Dim sValue

'On error handle On Error resume next

'Check to see if the ADODB objects have been 'initialized. If they have not then create them. if IsEmpty(g_cn) then Set g_cn = CreateObject("ADODB.Connection") Set g_rs = CreateObject("ADODB.Recordset") end if 'Set our database connection properties and 'open the Excel file. With g_cn .Provider = "Microsoft.Jet.OLEDB.4.0" .ConnectionString = "Data Source=" & DATA_FILE & ";"

& _ "Extended Properties=Excel 8.0;" .Open End With 'Create a SQL command that will return the Value 'based on the key

Key Value Lookup Function 23

24

XDS SCRIPT Function


'sQuery = "SELECT VALUE FROM [ERMX$] WHERE KEY = " & "'" & sKey & "'"

sQuery = "SELECT VALUE FROM [ERMX$] WHERE KEY = " & sKey

'Open the recordset and execute the query g_rs.Open sQuery, g_cn 'Set the return value sValue = g_rs.Fields.Item(0) 'Close the recordset g_rs.Close 'Close the connection 'g_cn.Close 'return the value associated with the key value. keyLookup=sValueEnd Function




ExcelSample.vbs.


\<AppXtender Reports Management installation directory>\AppXtenderRptsMgmtScripting\XDSScriptSamples\STMT_TYPE.cfg

The Excel spreadsheet file referenced in the VBScript file is located in:



Account.xls. (Note that you will need to change the specified path for this file in the VBScript file.)


XDS SCRIPT Function


Key Value Check FunctionThe following VBScript function looks up a key value in an Excel spreadsheet. If the key value is found, the function returns True. To see how it works in conjuction with an XDS procedure, an AppXtender Reports Mgmt Report Type configuration file (STMT_CHECK.cfg) has been included to demonstrate specifying the VBScript file name in the procedure settings and calling a function from the VBScript file using the SCRIPT function within the IF instruction. If the called VBScript function returns True, then the instructions that follow the IF instruction will be executed.

'Const string holds the Excel file path.const DATA_FILE = "W:\ERMXTest\config\Account.xls"'Global ADODB connection objectDim g_cn'Global ADODB recordset objectDim g_rs

Function keyCheckUp(sKey) 'String which holds the SQL command Dim sQuery 'String to hold return value Dim sValue 'On error handle On Error resume next

'Check to see if the ADODB objects have been 'initialized. If they have not then create them. if IsEmpty(g_cn) then Set g_cn = CreateObject("ADODB.Connection") Set g_rs = CreateObject("ADODB.Recordset") end if 'Set our database connection properties and open the

Excel file. With g_cn .Provider = "Microsoft.Jet.OLEDB.4.0" .ConnectionString = "Data Source=" & DATA_FILE & ";"

& _ "Extended Properties=Excel 8.0;" .Open End With 'Create a SQL command that will return the Value based

on the key 'sQuery = "SELECT VALUE FROM [ERMX$] WHERE KEY = " & "'"

& sKey & "'"

Key Value Check Function 25

26

XDS SCRIPT Function


sQuery = "SELECT COUNT(*) FROM [ERMX$] WHERE KEY = " & sKey

'Open the recordset and execute the query g_rs.Open sQuery, g_cn 'Set the return value if g_rs.Fields.Item(0) > 0 then keyCheckUp = "true" else keyCheckUp = "false" end if 'Close the recordset g_rs.Close 'Close the connection 'g_cn.Close End Function




ExcelSample.vbs.




STMT_CHECK.cfg.

The Excel spreadsheet file referenced in the VBScript file is located in:



Account.xls. (Note that you will need to change the specified path for this file in the VBScript file.)


Index


CCopy Export File Sample 10

DDate Format Conversion Sample 21documentation, related 5

KKey Value Check Function 25Key Value Lookup Function 23

OOverview of Report Error Scripts 14Overview of the BI Gateway Script Feature 8Overview of the XDS SCRIPT Function 20

SSend Email Notification Sample 9, 15

WWrite Log to File Sample 16Write to Database Sample 11


28

Index



applicationxtender reports management scripting - dell emc · applicationxtender reports management...

Documents