Product Information
This document applies to IBM Cognos 8 Version 8.4 and may also apply to subsequent releases. To check for newer versions of this document, visit the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html).
Copyright
Copyright 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC is an IBM Company. Portions of Cognos ULC software products are protected by one or more of the following U.S. Patents: 6,609,123 B1; 6,611,838 B1; 6,662,188 B1; 6,728,697 B2; 6,741,982 B2; 6,763,520 B1; 6,768,995 B2; 6,782,378 B2; 6,847,973 B2; 6,907,428 B2; 6,853,375 B2; 6,986,135 B2; 6,995,768 B2; 7,062,479 B2; 7,072,822 B2; 7,111,007 B2; 7,130,822 B1; 7,155,398 B2; 7,171,425 B2; 7,185,016 B1; 7,213,199 B2; 7,243,106 B2; 7,257,612 B2; 7,275,211 B2; 7,281,047 B2; 7,293,008 B2; 7,296,040 B2; 7,318,058 B2; 7,325,003 B2; 7,333,995 B2. Cognos and the Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated) in the United States and/or other countries. IBM and the IBM logo are trademarks of International Business Machines Corporation in the United States, or other countries or both. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others. While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or technical inaccuracies may exist. Cognos does not accept responsibility for any kind of loss resulting from the use of information contained in this document. This document shows the publication date. The information contained in this document is subject to change without notice. Any improvements or changes to the information contained in this document will be documented in subsequent editions. U.S. Government Restricted Rights. The software and accompanying materials are provided with Restricted Rights. Use, duplication, or disclosure by the Government is subject to the restrictions in subparagraph (C)(1)(ii) of the Rights in Technical Data and Computer clause at DFARS 252.227-7013, or subparagraphs (C)(1) and (2) of the Commercial Computer Software - Restricted Rights at 48CFR52.227 as applicable. The Contractor is Cognos Corporation, 15 Wayside Road, Burlington, MA 01803. This document contains proprietary information of Cognos. All rights are reserved. No part of this document may be copied, photocopied, reproduced, stored in a retrieval system, transmitted in any form or by any means, or translated into another language without the prior written consent of Cognos.
Table of Contents
Introduction
5 7
Chapter 1: Data Manager Connector for SAP R/3 Access to SAP Data 7 Access to SAP Function Modules 8 Joins 8 Temporary Files 8 Alternate Temporary File Directories 9 Easy to Understand Business Names 10 Chapter 2: Table Selector for SAP R/3
11
The Dictionary File 11 Create a Dictionary File 11 Open a Dictionary File 12 Add Tables to a Dictionary File 12 Delete Tables from a Dictionary File 13 View Dictionary File Properties 13 View Table Properties 13 View Column Properties 14 View Index Properties 14 Chapter 3: Writing an SAP Query
15
SAP ABAP Functions 15 Filter Source Data 16 Join R/3 Source Data 16 Determine Table Types 17 Joins Using Transparent Tables 17 Joins Using Clustered and Pooled Tables 18 Joins Using Function Modules 20 Sort Source Data 20 SAP Data Types 21 Chapter 4: Samples Overview
23
Overview of the Data Manager Connector for SAP R/3 Catalog 23 Connections 23 JobStreams 23 Staging Fact Builds 24 Data Integrity Checking 24 Index
25
User Guide 3
Table of Contents
Introduction
This document is intended for use with Data Manager Connector for SAP R/3. This document describes how to extract data from SAP R/3 data sources and how to work with that data in Data Manager.
Audience
You should be familiar with Microsoft Windows and SQL. You should also have an understanding of multi-dimensional data analysis or Business Intelligence.
Related Documentation
Our documentation includes user guides, getting started guides, new features guides, readmes, and other materials to meet the needs of our varied audience. The following documents contain related information and may be referred to in this document. Note: For online users of this document, a Web page such as The page cannot be found may appear when clicking individual links in the following table. Documents are made available for your particular installation and translation configuration. If a link is unavailable, you can access the document on the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html).
Document
IBM Cognos 8 New Features Data Manager User Guide
Description
Describing features that are new in this release Using Data Manager to create data warehouses and data repositories
Data Manager Installation and Configuration Installing and configuring Data Manager Guide Cognos SQL Describing the Cognos SQL data manipulation language (DML) as defined in ANSI/ISO SQL standards
Finding Information
Product documentation is available in online help from the Help menu or button in IBM Cognos products. To find the most current product documentation, including all localized documentation and knowledge base materials, access the IBM Cognos Resource Center (http://www.ibm.com/software/ data/support/cognos_crc.html). You can also read PDF versions of the product readme files and installation guides directly from IBM Cognos product CDs.
User Guide 5
Introduction
Getting Help
For more information about using this product or for technical assistance, visit the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html). This site provides information on support, professional services, and education.
To extract the data, normally a SAP administrator must write a custom ABAP extraction program, that is installed into the SAP environment, for each required extract. Data Manager Connector for SAP R/3 enables extraction of SAP R/3 data from within the Data Manager environment, whilst observing all the security roles within the SAP R/3 system. This is achieved by working through the SAP security layer. Data Manager Connector for SAP R/3 allows the following types of SAP tables to be brought into Data Manager in the same way as any other database system table: transparent tables pooled tables clustered tables
User Guide 7
Chapter 1: Data Manager Connector for SAP R/3 The SAP R/3 data is accessed using a Data Manager data source component that can be defined using standard SQL style extraction. You do not need to manage the different types of table structures in the SAP R/3 system and the different limitations associated with each table type.
Joins
Data Manager Connector for SAP R/3 leverages the OpenSQL ability to join tables in queries. The format of the SQL join determines how the join is performed. Explicit join syntax should be used instead of implicit join syntax. For more information, see Cognos SQL. The example SQL queries that follow are equivalent in terms of the final result.
select T1.COLA, T2.COLB from T1 inner join T2 on T1.COLX = T2.COLY
This example uses an implicit join that is expressed using the WHERE clause. Data Manager Connector for SAP R/3 determines the type of tables used in the explicit join. If the query contains expressions that can be passed to the SAP application server, then the query is passed to SAP. If the query contains expressions that are not supported by SAP, then the query is decomposed into a set of queries that can be used to retrieve the data. Typically, this involves more than one query being passed to SAP and the result computed by Data Manager. If joins are expressed using explicit SQL, then Data Manager Connector for SAP R/3 determines automatically how the query should be resolved. To determine how query decomposition is occurring, in the Data Manager SQLTerm window, click the Show executed query button ExecutedSQL logging option. , or use the
For more information on using the Show executed query button, see Execute an SQL Query in the SQLTerm and SQL Helper chapter of the Data Manager User Guide. For more information on the logging option, see Save Execution Information to a Log File in the Executing Builds and JobStreams chapter of the Data Manager User Guide.
Temporary Files
During query execution, temporary data files may be created on the ABAP server. These temporary files are created in the location defined in the SAP profile. File names are created using the following
Chapter 1: Data Manager Connector for SAP R/3 naming convention where <workstation_name> is the name of the workstation where the query initiated, <job_counter> is a unique number inside the process, <process_id> is the process id of the workstation, and <ext> can be either TMP, _PAR, or _C. <workstation_name><job_counter><process_id>.<ext> Note: Temporary files are usually purged automatically. However, program failure may result in them remaining. Your SAP administrator may want to purge these files. Before they do so, all Data Manager processes and requests within SAP must have completed or have been stopped.
The logical path and the logical file must be created on the SAP system. The SAP standard library routine FILE_GET_NAME is used to obtain a physical name from the logical name. The process of creating a logical name is described in the SAP documentation. For more information, see Platform-independent File Name Assignment, in the SAP Library - BC Extended Application Function Library documentation. For additional SAP information, see http: //help.sap.com/saphelp_46c/helpdata/en/2a/fa0290493111d182b70000e829fbfe/frameset.htm If you create a logical file definition, it must follow this format: <PARAM_1><PARAM_2> Data Manager Connector for SAP R/3 uses <PARAM_1> for the file name and <PARAM_2> for the file extension. If the logical names have not been implemented on the SAP system, the default TEMP directory is used.
User Guide 9
Request name
C46K900106
Owner
MYACCT
Description
Request for logical path
Steps
1. From the File menu, click New .
The SAP Dictionary Properties dialog box appears. 2. Click the Properties tab. 3. In the Name box, type a name for the dictionary file. 4. If required, in the Description box, type a description for the dictionary file. 5. Click the Connection tab. 6. Select the Save login info check box so that you are not prompted to enter your user ID and password every time you open the dictionary file. 7. Select the Run in background check box to communicate with the SAP server using a batch job. If you do not select this check box, communication with the SAP server is through a dialog process. Dialog processes are subject to a time limit, typically 10 minutes, after which it is stopped by the SAP system. 8. Enter the remaining information required to connect to the database. 9. Click OK. If the connection is not successful, a message appears informing you of this.
User Guide 11
Steps
1. From the File menu, click Open The Open dialog box appears. 2. Click the dictionary file to open. 3. Click Open. Table Selector for SAP R/3 automatically connects to the database. .
Steps
1. From the Edit menu, click Add Tables .
2. Specify how the search is to be performed: To specify the type of search information, click Table name, or SAP R/3 Short Text. To further define the search information, click Matches, Starts with, Contains, or Ends with. 3. Type the search information. Note: Wild cards may not be used. 4. If you clicked SAP R/3 short text in step 2, you can specify whether the search should be case sensitive. 5. Choose whether to include views in the search: To include views, select the Include views check box. To select only the tables, clear the Include views check box.
6. Click Search. All the tables in the database that meet your search criteria are listed. 7. Click the tables that you want to add to the dictionary file. Note: You can only add tables that are not already in the dictionary file. 8. Click Add.
3. Click Yes to confirm that you want to delete the table. The table and its column and index information is deleted from the dictionary file.
Steps
1. Click the file for which you want to view properties. 2. From the Edit menu, click Properties .
The SAP Dictionary Properties dialog box appears. 3. Click the Properties tab. The name of the file and a description, which you can change here, appears. For saved files, details such as the file path, the date the file was created, and the date the file was last modified appear. 4. Click the Connection tab. 5. Select the Save login info check box so that you are not prompted to enter your user ID and password every time you open the dictionary file. 6. Select the Run in background check box to communicate with the SAP server using a batch job. If you do not select this check box, communication with the SAP server is through a dialog process. Dialog processes are subject to a time limit, typically 10 minutes, after which it is stopped by the SAP system. 7. Change other connection details if you require. 8. Click OK.
User Guide 13
Chapter 2: Table Selector for SAP R/3 2. From the Edit menu, click Properties .
The Table Properties dialog box appears. It shows the table name, the type of table, a description of the table, the last user to modify the table, the date it was last modified and the estimated number of records. If a description was not entered, the short text description automatically appears. 3. Click OK.
The Column Properties dialog box appears showing details about the column. If a description was not entered, the short text description automatically appears. 3. Click OK.
The Index Properties dialog box appears showing the index name and description, and the estimated number of records. 3. Click OK.
For information about the SQL interface, see Cognos SQL. Additional SQL statements are provided to access function modules. Examples of these statements follow in the remainder of this chapter.
Syntax
<call procedure> ::= CALL <procedure name> [ ( <parameter list> ) ] <parameter list> ::= [ <argument-value pair> [ { , <argument-value pair> }...] <argument-value pair> ::= <argument name> = <value literal>
Examples
User Guide 15
Chapter 3: Writing an SAP Query This example reports the salary column returned by the Employee_Info function based on the input values SMITH and 40.
SELECT T1.SALARY, T1.START_DT, T1.FULLNAME FROM CALL Employee_Info(name='SMITH' ,age=40) T1 WHERE SALARY < 10000 AND START_DT > DATE '2000-12-31' ORDER BY T1.START_DT
This example reports an ordered set of columns returned by the Employee_Info function based on the input values SMITH and 40. It has additional filtering based on the SALARY and START_DT fields in the returned table.
SELECT * FROM CALL Employee_Info(name='SMITH' ,age=40, startdt= DATE '2006-09-01' T1
This example reports a set of columns returned by the Employee_Info function based on the input values SMITH,40 and 2006-09-01.
For more information on using the Show executedquery button, see Execute an SQL Query in the SQLTerm and SQL Helper chapter of the Data Manager User Guide. For more information on the logging option, see Save Execution Information to a Log File in the Executing Builds and JobStreams chapter of the Data Manager User Guide.
Chapter 3: Writing an SAP Query When constructing joins, it is important to consider the limitations of different table types within the R/3 system. Clustered and pooled table types do not support direct join operations in SAP OpenSQL. For these table types, Data Manager Connector for SAP R/3 processes the joins by decomposing the query into ABAP code that performs nested loop join logic on the R/3 system. When the join logic cannot be processed in this manner, the query is split into smaller queries that retrieve data to Data Manager where the joins are then processed. Tip: If you want Data Manager Connector for SAP R/3 to decompose and process the join, you must express the join query using explicit join syntax. If you use implicit join syntax, all the source data is retrieved from the R/3 system and is processed by Data Manager. To override the default join behavior you can use implicit join logic. For information on explicit and implicit joins, see "Joins" (p. 8).
Steps
1. In Table Selector for SAP R/3, open the dictionary file. Tip: You can find the name of the file from the Data Manager Connection Properties dialog box. 2. Click the table for which you want to know the type. 3. From the Edit menu, click Properties .
User Guide 17
Chapter 3: Writing an SAP Query Explicit joins that involve expressions in the join are checked to determine if the expression is supported by OpenSQL. If the expression is not supported, the query is decomposed into multiple requests and the data is joined by Data Manager. Source queries that involve outer joins are decomposed into queries that contain any inner join portion of the query, and the outer join portion is processed as a separate query. The outer join is then performed by Data Manager. The following example returns all Sales Document Header (VBAK) and Sales Document Item (VBAP) records that have been entered on 19 May 2004:
SELECT "VBAK"."MANDT" as "Client", "VBAK"."VBELN" as "Sales Document", "VBAK"."AUDAT" as "Document Date", "VBAP"."MATNR" as "Material Number" FROM "VBAK" INNER JOIN "VBAP" ON ( "VBAK"."MANDT" = "VBAP"."MANDT" AND "VBAK"."VBELN" = "VBAP"."VBELN" ) WHERE "VBAK"."AUDAT" = DATE '2004-05-19'
Join description
Equi-join using explicit inner join syntax Outer join using explicit join syntax
Processing method
Nested join by the R/3 system Locally by Data Manager Connector for SAP R/3
Join expression not supported by the R/3 Locally by Data Manager Connector for SAP R/3 system Any implicit join Locally by Data Manager Connector by SAP R/3
The following example returns Accounting Document Header (BKPF) and Accounting Document Segment (BSEG) records that match a filter criterion.
SELECT "BKPF"."MANDT", "BKPF"."BUDAT", "BSEG"."BUKRS", "BKPF"."BELNR",
This query contains a clustered table (BSEG). The join between BKPF and BSEG must be processed using nested loop joins. In this case, the filter expression can be processed by the R/3 system. Any expression that cannot be processed is removed from the query and processed by Data Manager Connector for SAP R/3 as the data is retrieved from the R/3 system.
Steps
1. In Table Selector for SAP R/3, open the dictionary file. Tip: You can find the name of the file from the Data Manager Connection Properties dialog box. 2. Click the table for which you want to know the type. 3. In the right pane, double-click the primary key.
User Guide 19
This query contains a function module and a transparent table. It is decomposed into a request for the results of the function module, and a request for the data from the transparent table. Data Manager Connector for SAP R/3 then joins the results.
Processing method
The R/3 system The R/3 system
Ordered queries containing clustered or pooled Data Manager Connector for SAP R/3 tables, or function modules
Data Manager
CHAR
SAP
ACCP CHAR CLNT CUKY LANG LCHR LRAW NUMC PREC RAW UNIT CURR DEC QUAN DATS FLTP INT1 INT2 INT4
User Guide 21
Connections
The catalog contains two connections named Source and Target. The Source connection must be configured to your SAP location. The dictionary file "The Dictionary File" (p. 11) must also be specified (sap_dictionary.dbm). The Target connection is to the ds_sap_mart Access database which has been provided as part of the installed samples.
JobStreams
The JobStream named Complete_Job has four JobStream nodes named Step1_Dimensions, Step2_Dimensions, FI_Fact_Build, and SD_Fact_Builds. They are executed in a specified order to ensure that staging data is processed and dimensions are built before the fact builds are processed as these are dependent on the dimensions.
User Guide 23
Chapter 4: Samples Overview The JobStream nodes named Step1_Dimensions and Step2_Dimensions contain all the staging fact builds and dimension builds that are required for the FI_Fact_Build and SD_Fact_Builds JobStream nodes. The JobStream node named FI_Fact_build contains the fact build FI_Fact_GL_Balance, and the JobStream node named SD_Fact_Build contains the fact builds named SD_Fact_Sales_Order and SD_Fact_Sales_Statistics. Note: Care should be taken executing this JobStream, as it loads the complete data structure.
Index
A
ABAP functions, 15 accessing SAP data, 7 SAP function modules, 8 acronymns, 10 adding tables to dictionary files, 12 finding information, 5 function modules, 8
H
help getting, 6
I B
business names, 10 IBM Cognos Resource Center, 6 index properties viewing, 14 information finding, 5 integrity checking, 24
C
catalogs, 23 connections, 23 fact builds, 24 JobStreams, 23 clustered tables, 7 columns viewing properties, 14 connections, 23 copyright material printing, 6 creating dictionary files, 11
J
JobStreams, 23 joins, 8
M
modifying tables, 12
O
opening dictionary files, 12
D
data integrity checking, 24 data types SAP, 21 dictionary files, 11 adding tables, 12 creating, 11 deleting tables, 13 opening, 12 viewing, 13
P
pooled tables, 7 preferred language, 10 printing copyright material, 6
Q
queries writing, 15
R F
fact builds, 24 files dictionary, 11 related documentation, 5 running in background, 11
User Guide 25
Index
S
samples, 23 catalog, 23 connections, 23 data integrity checking, 24 fact builds, 24 JobStreams, 23 SAP ABAP functions, 15 data types, 21 SAP data accessing, 7 SAP queries writing, 15 security layer, 7 staging fact builds, 24
T
tables adding to dictionary files, 12 deleting from dictionary file, 13 deleting from dictionary files, 13 viewing properties, 13 Table Selector for SAP R/3, 11 table types, 7 temporary files, 8 transparent tables, 7
V
viewing column properties, 14 database connections, 13 dictionary files, 13 index properties, 14 table properties, 13
W
writing SAP queries, 15