IBM Power Systems
Refresh Web Query Synonym
1
© 2011 IBM Corporation
IBM Power Systems
Refresh Web Query Synonym
Added to CRTWQSYN command. Available in 1.1.2 HotFix 5
Use to synchronize Web Query synonym when structure/format of underlying table
changes. Can be called from command line, CL program, Job Scheduler.
The refresh feature has 3 primary functions:
Adds new columns from the underlying table or view.
Deletes dropped columns from the underlying table or view
Updates certain column attributes that were altered in the underlying table or view.
2
© 2011 IBM Corporation
IBM Power Systems
Refresh Web Query Synonym
Available in DB2 Web Query 1.1.2 HotFix 5
Supports the refresh of synonyms created via web metadata console, Developer
Workbench, and CRTWQSYN command.
Only supported for synonyms based on DB2 cli adapter. No support for DB
Heritage, Query/400, JD Edwards, or SQL Server adapters.
*LOCAL databases only (no support for tables on remote systems, partitions, or
databases).
Supported file types:
– Table
– Physical File
– SQL View
– Logical file
*ALL and generic (wildcard) search supported in the FILE parameter. Useful for
refreshing ALL files in a library (or all files that start with ORD*)
3
© 2011 IBM Corporation
IBM Power Systems
Refresh Web Query Synonym
Example:
CRTWQSYN FILE(ORD*) SCHEMA(QWQCENT) PREFIX(MYPREFIX_)
APPFLR(*BASEAPP) OPTION(*REFRESH)
Create DB2 Web Query Synonym (CRTWQSYN)
File (table/view) name . . . .
Schema (library) name . . . .
Synonym prefix . . . . . . . .
Synonym suffix . . . . . . . .
Application folder . . . . . .
With foreign keys . . . . . .
Include library qualification
Existing synonym option . . .
Use field short name as alias
.
.
.
.
.
.
.
.
.
FILE
SCHEMA
PREFIX
SUFFIX
APPFLR
FRGNKEYS
QUALLIB
OPTION
SHORTALIAS
ORD*
QWQCENT
MYPREFIX_
*NONE
*BASEAPP
*NO
*YES
*REFRESH
*NO
*YES, *NO
*YES, *NO
*NONE, *REPLACE, *REFRESH
*YES, *NO
In this example, existing synonyms (in BASEAPP with prefix MYPREFIX_) will be
refreshed for all files that start with the characters “ORD” in the library QWQCENT.
4
QWQCENT/ORDDETAIL MYPREFIX_ORDDETAIL
QWQCENT/ORDHEADER MYPREFIX_ORDHEADER
QWQCENT/ORDERS2011 MYPREFIX_ORDERS2011
...
© 2011 IBM Corporation
IBM Power Systems
Refresh Web Query Synonym
Add new columns
If new columns are added to the underlying table or view, the refresh feature will
add them to the existing synonym. All existing synonym fields and customizations
are persevered in the Master File
SQL: ALTER TABLE ORDERS ADD COLUMN NEWFIELD CHAR (10)
CRTWQSYN FILE(ORDERS) SCHEMA(QWQCENT) PREFIX(ZZCOBB_)
OPTION(*REFRESH)
--------------------Column added to synonym-------------------Segment: zzcobb_orders
Column: NEWFIELD
Actual: A10
5
© 2011 IBM Corporation
IBM Power Systems
Refresh Web Query Synonym
Remove dropped columns
If columns are dropped from the underlying table or view, the refresh feature will
remove the corresponding field from the existing synonym unless there are
dependencies in the synonym. A dependency is defined as any one of the following.
A define/virtual field with an expression referencing the synonym field.
A computed field with an expression referencing the synonym field.
A filter with an expression referencing the synonym field.
An OLAP dimension or hierarchy referencing the synonym field.
A Business View folder containing the synonym field.
A DBA restriction based upon the synonym field.
If any of the above dependencies exist, the field is not deleted from the Master File.
This dependency checking can be ignored and the column subsequently dropped from the
synonym.
6
© 2011 IBM Corporation
IBM Power Systems
Refresh Web Query Synonym
Remove dropped columns
SQL: ALTER TABLE ORDERS DROP COLUMN OLDFIELD
CRTWQSYN FILE(ORDERS) SCHEMA(QWQCENT) PREFIX(ZZCOBB_)
OPTION(*REFRESH)
--------------------Column dropped from synonym-------------------Segment: zzcobb_orders
Column: OLDFIELD
Actual: A10
7
© 2011 IBM Corporation
IBM Power Systems
Refresh Web Query Synonym
Update altered columns
If certain column attributes are changed in the underlying table or view, the refresh
feature will apply those changes to the corresponding field in the synonym. The
following attributes are updated if the data type or length of the corresponding
table/view column is changed:
Actual
For example, if a database table column was altered from CHAR(4) to CHAR(6), the Actual
value for that field in the synonym would be changed from A4 to A6.
Usage
If the Actual value for the synonym field has changed, it is possible that the Usage value will
need to be updated accordingly.
Where appropriate, the Refresh utility attempts to preserve any customized usage
values/attributes such as C (Comma inclusion as thousands separator) and M (Floating
Currency)
8
© 2011 IBM Corporation
IBM Power Systems
Refresh Web Query Synonym
Update altered columns
SQL: ALTER TABLE ZZCOBB/ORDERS ALTER COLUMN WARRANTYEXP SET
DATA TYPE NUMERIC ( 20, 2)
CRTWQSYN FILE(ORDERS) SCHEMA(QWQCENT) PREFIX(ZZCOBB_)
OPTION(*REFRESH)
--------------------Column updated in synonym-------------------Segment: zzcobb_orders
Column: WARRANTYEXP
Prv Actual Value: P12
New Actual Value: P11
Prv Usage Value: P24.2CM
New Usage Value: P22.2CM
9
© 2011 IBM Corporation
IBM Power Systems
Refresh Web Query Synonym
Data area QWEBQRY77/QWQRFSSYN. Use to override default refresh behavior. These
settings will be added to the CRTWQSYN in a future version.
Example to update trace/debug level:
CHGDTAARA DTAARA(QWEBQRY77/QWQRFSSYN (5 1)) VALUE(‘3')
Pos
1
2
3
10
Description
Trace/debug level. Valid values are 0-3. Default is 2.
0 = No tracing
1 = Include input parameter values, errors, and summary info
2 = Same as 1 plus each segment analyzed and all specific columns added, updated, dropped
3 = Same as 2 plus print comparison of all columns before and after refresh.
Backup synonym flag. Indicates if a backup of the master file is to be made before refresh. If on, the
program will make a backup copy of the master file and use a timestamp as part of the new name.
For example, if you are refreshing a synonym named cen_orders.mas, a copy of the synonym will be made
before the synonym is refreshed and given the following name:
cen_orders_20111221144653180.mas
The backup copy resides in the same application path as the requested synonym. A backup access file (.acx
extension) is NOT made as it wasn't really necessary. The idea is to give users a way to get back their
original synonym (prior to the refresh request) in case it is somehow corrupted by the refresh.
Ignore dependencies flag. Indicates whether to ignore dependencies (like define fields and filters) when
refreshing synonym. For example, if it is on, a column removed from the table will also be removed from
synonym (even if a define field is based on that deleted column). If this setting is off, a column (that was
dropped from the table) will not be removed from the synonym if there is a dependency in the© synonym
2011 IBM Corporation
(such as a define field) based on the column.
IBM Power Systems
Refresh Web Query Synonym
Pos Description
4
Compare only flag. Turn on if you only want to generate a spool file trace of what
changes the Refresh would make. If turned on, the refresh is NOT applied to the
synonym and it remains unchanged.
Update column title. Turn on if you want to overlay all column titles with values
from table/view that synonym is based on. Useful if you changed column titles in
table/view and you want to apply those new titles to synonym.
Update column description. Turn on if you want to overlay all column descriptions
with values from table/view that synonym is based on. Useful if you changed column
descriptions in table/view and you want to apply those new descriptions to synonym.
If off, the column title values in the synonym are preserved.
Update column names. Turn on if you want to overlay all column names with
values from table/view that synonym is based on. Useful if you changed column
long names in table/view and you want to apply those new names to synonym. If off,
the column names in the synonym are preserved. Regardless of the value of this
setting, ALIAS values are NOT changed in the synonym.
5
6
7
11
© 2011 IBM Corporation
IBM Power Systems
Refresh Web Query Synonym
To help you determine what was changed during a Refresh process, a log is
generated and written to a spooled file. It can be located by issuing the WRKSPLF
command searching for File QSYSPRT and User Date RFSWQSYN.
12
© 2011 IBM Corporation
IBM Power Systems
Refresh Web Query Synonym
Sample log spooled file:
13
--------------------Input parameters--------------------File. . .: ORDERS
Schema. .: CUSTLIB
File Type: *ALL
Prefix: CUSTLIB_
Suffix: *NONE
App Folder: ODDSENDS
With Foreign Keys:*NO
Include library qualification: *YES
Existing synonym option: *REFRESH
Use field short name as alias: *NO
QWQRFSSYN Data area values
App path: /qibm/UserData/webquery/ibi/apps/
Trace level: 2
Backup master file: 1
Ignore Dependencies: 0
Compare Only Mode: 0
Update column titles: 0
Update column descriptions: 0
Update column field names: 0
--------------------------------------------------------Analyzing Web Query synonym CUSTLIB_ORDERS for refresh...
Segment Name: CUSTLIB_ORDERS
Table Name: CUSTLIB/ORDERS
--------------------Column updated-------------------Segment: CUSTLIB_ORDERS
Column: REVENUE
Prv Actual Value: P5
New Actual Value: P7
Prv Usage Value: P10.2C
New Usage Value: P14.2C
Prv Column Title Value:
New Column Title Value: REVENUE
--------------------Summary Info-------------------New columns added . . : 0
Updated columns . . . : 1
Dropped columns . . . : 0
Dropped dependencies . : 0
Number of synonyms analyzed: 1
Number of synonyms that differed from underlying based upon file: 1
Number of synonyms actually refreshed: 1
-----------End of Refresh Synonym trace-------------© 2011 IBM Corporation
IBM Power Systems
Refresh Web Query Synonym
Basic Troubleshooting
1. Check job logs and log spooled file.
2. If not enough info in log spooled file, increase trace/debug value:
CHGDTAARA DTAARA(QWEBQRY77/QWQRFSSYN (3 1)) VALUE(‘3')
3. Verify based on table/view exists
4. Verify synonym exists (with specified prefix and suffix)
5. Error QWQ0503 (No candidate objects found). Check QCCSID system value or
job CCSID. If 65535, change to appropriate language CCSID and run again.
14
© 2011 IBM Corporation