CA Technologies CA Dataquery Administration Guide
CA Dataquery is a software product that allows users to query and modify data stored in CA Datacom databases. It provides a variety of features, including a powerful query language (DQL), a user-friendly interface, and a comprehensive set of security features. CA Dataquery is designed to meet the needs of both casual and experienced users, providing a flexible and powerful tool for data access and management. The guide should help you learn about all of the available features.
Advertisement
Advertisement
CA Dataquery™ for CA
Datacom®
Administration Guide
Version 15.00
This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to as the “Documentation”) is for your informational purposes only and is subject to change or withdrawal by CA at any time.
This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may not be disclosed by you or used for any purpose other than as may be permitted in (i) a separate agreement between you and CA governing your use of the CA software to which the Documentation relates; or (ii) a separate confidentiality agreement between you and
CA.
Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy.
The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION “AS IS” WITHOUT WARRANTY OF ANY
KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE,
DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST
INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE
POSSIBILITY OF SUCH LOSS OR DAMAGE.
The use of any software product referenced in the Documentation is governed by the applicable license agreement and such license agreement is not modified in any way by the terms of this notice.
The manufacturer of this Documentation is CA.
Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or their successors.
Copyright © 2014 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.
CA Technologies Product References
This document references the following CA products:
■
CA Datacom®/DB
■
CA Datacom® Datadictionary™
■
CA Datacom® CICS Services
■
CA Datacom® DB2 Transparency
■
CA Datacom® DL1 Transparency
■
CA Datacom® Fast Restore
■
CA Datacom® IMS/DC Services
■
CA Datacom® Presspack
■
CA Datacom® Server
■
CA Datacom® SQL
■
CA Datacom® STAR
■
CA Datacom® TOTAL Transparency
■
CA Datacom® VSAM Transparency
■
CA Dataquery™ for CA Datacom® (CA Dataquery)
■
CA Ideal™ for CA Datacom® (CA Ideal)
■
CA IPC
■
CA Librarian®
■
CA Look
■
CA Common Services for z/OS
Contact CA Technologies
Contact CA Support
For your convenience, CA Technologies provides one site where you can access the information that you need for your Home Office, Small Business, and Enterprise CA
Technologies products. At
http://ca.com/support
, you can access the following resources:
■
Online and telephone contact information for technical assistance and customer services
■
Information about user communities and forums
■
Product and documentation downloads
■
CA Support policies and guidelines
■
Other helpful resources appropriate for your product
Providing Feedback About Product Documentation
If you have comments or questions about CA Technologies product documentation, you can send a message to
[email protected]
.
To provide feedback about CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at
http://ca.com/docs
.
Contents
Chapter 1: Introducing CA Dataquery 15
Chapter 2: CA Dataquery Administrator Overview 19
Chapter 3: CA Dataquery in the CA Datacom System 25
Chapter 4: Accessing the Online Administrative Functions 31
Chapter 5: Post-Installation Tasks 37
Chapter 6: Preparing the CA Datacom/DB Multi-User Facility 43
Chapter 7: Tailoring the CA Dataquery System Option Table 47
Contents 5
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 79
Chapter 9: Implementing Online CA Dataquery 107
Chapter 10: Defining Databases 111
Chapter 11: Defining the CA Dataquery User Requirements Tables 117
Chapter 12: Initiating and Terminating CA Dataquery 121
6 Administration Guide
Chapter 13: Using CA Dataquery with CA Datacom Transparencies
Chapter 14: Language Maintenance Facility
125
127
Chapter 15: Defining or Modifying the User Profile 129
Chapter 16: Managing Your Query Library Table 137
Chapter 17: Special Considerations for DQL Language Queries 171
Chapter 18: Modifying Data Using CA Dataquery 185
Contents 7
Chapter 19: Sets 191
Chapter 20: Personal Database Facility 195
Chapter 21: Using the Language Maintenance Facility
Chapter 22: Upgrading to New Releases of Supporting Products
197
199
Chapter 23: Security Overview 201
Chapter 24: Authorizing Users 207
8 Administration Guide
Chapter 25: Securing Data Access for DQL Use 253
Chapter 26: Limiting Access to Columns and Rows 271
Contents 9
Chapter 27: Securing Data Access for SQL Use 301
Chapter 28: Considering CA Datacom System Security 305
Chapter 29: Language Maintenance Facility Overview 307
Chapter 30: Changing the Bulletin Board 323
Chapter 31: Translating CA Dataquery 327
Chapter 32: Editing the Translated Version of CA Dataquery 357
10 Administration Guide
Chapter 33: Deleting Unneeded Panels, Literals, and Vocabulary 367
Chapter 34: Customizing the American English Version 373
Chapter 35: Batch Management Overview 393
Chapter 36: Batch Sign/On Management 401
Chapter 37: Batch Online Management 415
Contents 11
Chapter 38: Executing Deferred Batch Queries 429
Chapter 39: Using the Batch Export Function 433
Chapter 40: Accessing Exported Data 443
Chapter 41: Extracting Data (FEX)
Chapter 42: Programming User Exits
Chapter 43: Query Validation Exit
Chapter 44: User-Defined Functions Exit
453
459
463
465
Chapter 45: Sign-on/off Exit 469
Chapter 46: Batch Submit Exit 473
12 Administration Guide
Chapter 47: Batch Line Printer Exit
Chapter 48: Output Exit
Chapter 49: DBID Exit
Chapter 50: Data Exit
Chapter 51: Data Stream Input Exit
Chapter 52: Data Stream Output Exit
483
485
Chapter 53: Network Printer Exit 487
Chapter 54: Solving User Problems 489
475
477
479
481
Chapter 55: Using DQL Diagnostics 493
Chapter 56: Using SQL Mode Diagnostics 499
Chapter 57: Using the Printer Control 509
Chapter 58: Monitoring Performance 513
Contents 13
Chapter 59: Tuning Your System for CA Dataquery 525
Chapter 60: Handling Errors 535
14 Administration Guide
Chapter 1: Introducing CA Dataquery
Online CA Dataquery operates under CICS, where the online portion of the CA
Dataquery system runs as a pseudo-conversational transaction, using CICS services to manage programs, storage, and terminal I/O. Online CA Dataquery also interfaces with several other CA products and facilities to complete processing of a user's query request. These include the CA Datacom Datadictionary Service Facility, the CA
Datacom/DB Multi-User Facility (MUF), and the CA IPC CAIVPE.
DQL Mode Processing
To process a DQL Mode query, CA Dataquery first parses and edits the query. This involves using the CA Datacom Datadictionary Service Facility to validate key names, column names, and authorization data. This validation process also retrieves the information necessary to determine where and how to access the requested data.
Next CA Dataquery uses information retrieved from CA Datacom Datadictionary, such as
TABLE-ID, DBID, and key name to formulate the appropriate CA Datacom/DB request to access the requested data. If CA Dataquery is running under CICS, this request is passed to CA Datacom CICS Services for staging. CA Datacom CICS Services controls CA
Datacom/DB request traffic in the CICS region. The request is then passed to the CA
Datacom/DB interface which controls traffic to the MUF. The request is then passed to the MUF for processing.
After processing is complete, the retrieved data is passed back through this same chain to CA Dataquery where further processing may take place.
Once CA Dataquery processing is complete, the results may be displayed in report format on the terminal or on a hardcopy printer. Query results may also be saved for later use.
Chapter 1: Introducing CA Dataquery 15
About This Guide
DQL Mode Sort Processing
Sort processing varies, depending on the operating system:
z/OS
If you have specified SORT, the sort routine reads the active found set from the DQF
(Found Table). CA Dataquery attempts to sort the set in core. If there is not enough memory available, CA Dataquery issues a message and a return code, then attempts to sort the set within the Index Area for the CA Dataquery database. If the Index
Area does not have enough space, CA Dataquery issues a message and terminates the query.
For batch, the process is the same except that CA Dataquery passes the set to the operating system sort routine. If the operating system sort routine cannot do the sort, CA Dataquery attempts the sort in the Index Area as it does for online. When sorting from DQBATCH, include the sort work JCL statements in your batch JCL, if needed.
SQL Mode Processing
For SQL Mode, CA Dataquery sends the entire query to CA Datacom/DB for validation and ORDER BY sorting. CA CA Datacom/DB uses CA Datacom Datadictionary to validate table and column names, and so forth, and determines where and how to access data.
Next, CA Dataquery asks CA Datacom/DB to return the data. CA Datacom/DB passes the data back. Data can be sorted in SQL Mode only by an ORDER BY statement in the query. The rows are retrieved from CA Datacom/DB in sorted order. Reports are otherwise formatted by CA Dataquery.
Batch (DQBATCH)
CA Dataquery also operates in a batch mode (DQBATCH). Batch uses standard operating system services to manage programs, storage, and I/O. Processing is the same as described for online except that the CA Datacom CICS Services is not involved.
About This Guide
Purpose
This guide provides information about and procedures for performing CA Datacom/DB systems tasks, including:
■
Establishing the operating environment
■
Creating the system databases and areas
■
Maintaining the system databases and areas
16 Administration Guide
About This Guide
Product Changes
For information about product changes, see the CA Datacom Release Notes.
Terminology
■
■
■
■
■
■
■
Customizing the CA Datacom environment
Creating databases
Maintaining databases
Writing and interfacing exit programs
Monitoring system performance
Tuning system performance
Diagnosing and resolving system problems
Intended Audience
■
■
This guide is intended for CA Dataquery Administrators, systems programmers, and
Database Administrators who are responsible for one or more of the following:
■
Installing CA Dataquery system software
■
Supporting CA Dataquery system software
■
Administering the operations of the CA Dataquery system
Maintaining data integrity
Ensuring data accessibility
■
Maintaining system performance
Some terms in this guide are used in a special context.
z/OS
The term region is used throughout this guide to represent address space for z/OS environments.
z/VSE
The term region is used throughout this guide to represent partition for z/VSE environments.
Chapter 1: Introducing CA Dataquery 17
About This Guide
Reading Syntax Diagrams
The formats of all statements and some basic language elements are illustrated using syntax diagrams. Read syntax diagrams from left to right and top to bottom.
The following terminology, symbols, and concepts are used in syntax diagrams.
JCL Example Notation
This guide uses the following JCL notation.
UPPERCASE Identifies commands, keywords, and keyword values which must be coded exactly as shown. symbols Symbols, such as commas, equal signs, and slashes, must be coded exactly as shown.
Do not type the following when they appear in the JCL examples. They are provided to clarify the JCL syntax. lowercase Identifies a value or values that you must supply.
. . . Indicates the omission of one or more keywords or parameters that you must code according to the specific installation at your site.
18 Administration Guide
Chapter 2: CA Dataquery Administrator
Overview
To effectively administer the CA Dataquery system, you must have the following qualifications:
■
You must have a thorough knowledge of CA Datacom/DB and at least a general knowledge of the other CA products that execute with CA Dataquery. You must be able to determine if problems that can arise are a result of CA Dataquery or CA
Dataquery's interaction with one of these other products.
■
You must have a general knowledge of the operating system environment. You should know the CICS environment when CA Dataquery online operates under CICS.
■
You must have a general knowledge of CA Dataquery. Depending on the environment, you may either be actively involved in creating queries or may use CA
Dataquery only when there are problems to be solved. You must understand CA
Dataquery well enough to know how CA Dataquery impacts the operation of the CA
Datacom/DB system and how to optimize CA Dataquery operation and the operation of CA Datacom/DB when CA Dataquery is being used.
It is important that you know that:
–
Users can update databases if authorized.
–
A data authorized user can read any database.
–
A user cannot log on to more than one terminal with the same user ID and password.
Tasks
CA Dataquery Administrators handle the day-to-day administration of CA Dataquery.
Following are tasks for which a CA Dataquery Administrator can be responsible:
■
Modification and tailoring following CA Dataquery installation.
–
User Requirements Tables. See Defining the CA Dataquery User Requirements
Tables.
–
Creating user signons/passwords and setting up authorizations.
–
DQSYSTBL (assemble CA Dataquery system table macro (DQOPTLST) and link edit using name DQSYSTBL).
Chapter 2: CA Dataquery Administrator Overview 19
Responsibilities
■
■
–
–
–
Other CA Dataquery tasks contained in members that are available on the CA
Datacom page on http://support.ca.com/. See the CA Datacom Release Notes.
Programming user exits.
Implementing CA Dataquery security.
–
–
–
–
–
Maintenance after CA Dataquery is operational.
–
Supporting users and diagnosing problems.
–
Managing query and JCL libraries.
–
Performing backups and restores of CA Dataquery tables.
Using batch maintenance utilities.
–
Upgrading supporting products and implementing required changes following upgrades.
Modifying the batch CA Dataquery systems options table to meet site requirements.
Executing deferred batch queries.
Maintaining CA Dataquery system tables.
Loading and backing up CA-supplied languages.
Monitoring and tuning CA Dataquery.
Responsibilities
As the CA Dataquery Administrator, you are responsible for ensuring that all the system tasks required for optimum CA Dataquery performance are performed. During use of CA
Dataquery, you ensure that the system needs of the users are met and that the system maintenance includes the CA Dataquery needs. You tune CA Dataquery and CA
Datacom/DB to improve or maintain the performance. To perform these tasks, you need to work with the Database Administrator, the systems programmer, the Security
Administrator, the CA Datacom Datadictionary Administrator, and possibly the CA
Dataquery users.
Your system responsibilities include:
■
Knowing the system defaults that affect end users.
■
Providing the Database Administrator with information about CA Dataquery end-user needs.
■
Being knowledgeable about CA Dataquery batch utilities.
20 Administration Guide
Required CA Dataquery Skills
■
■
■
Understanding the operation of any user exits designed at your site which affect the end user.
Knowing how to use CA Dataquery diagnostics and CA Datacom/DB accounting statistics in monitoring system and user performance.
Maintaining signon information.
Site Standards
Your site can have one CA Dataquery Administrator who performs all of the CA
Dataquery administrative functions, or it could have several CA Dataquery
Administrators among whom the tasks are divided, or performed for a particular group of users, such as an office with more than one department.
Required CA Dataquery Skills
Learn about CA Dataquery so that you can support your users. Also, you need to be fully authorized so that you can use all the CA Dataquery features if you need to. The following highlights those subjects that are of particular importance to you. You should know how to perform the following tasks:
■
Establish security.
Choose the SECURITY CONTROL option from the Administrative Menu. With this panel you can:
–
Authorize users to access tables and perform the FIND, UPDATE, INSERT, or
ERASE functions.
–
Authorize users to access columns protected by profile-codes.
■
Authorize a user.
–
Use the USERS option from the Administrative Menu.
–
Type USERS on the command line.
With this you can add, delete, or maintain users.
■
Force a user to log off.
Use the USERS option from the Administrative Menu. Use the PF key to display the
Directory of Active Users. Use a PF key to FORCE OFF the active user.
■
■
Override predefined system defaults for a user.
Use the USERS option on the Administrative Menu.
Use diagnostics.
Using DQL Diagnostics
Chapter 2: CA Dataquery Administrator Overview 21
Required CA Dataquery Skills
■
■
■
■
■
■
■
Get CA Dataquery statistics.
Using CA Dataquery Statistics
Create and modify JCL members for batch submission.
Maintain the Query Library Table (DQQ).
Perform online library maintenance with the online Administrator functions
Accessing the Online Administrative Functions
You can use the DQLIBRMT utility to:
–
Delete all or selected members for selected users or groups
–
Back up all queries, dialogs, terms, JCL, and PROC members or selected members from the Query Library Table to tape or disk
–
Restore all or selected members to the Query Library Table from a tape or disk file
–
Print maintenance reports that:
–
List each user's query and type
–
Show selected user's query text or JCL
–
Show maintenance functions per query
–
List any errors that occur during query maintenance
Create and send a message.
Use the USERS option from the Administrative Menu. Use the PF key to get to the
Directory of Active Users. Then use the PF keys to do a CREATE MSG or a SEND
MSG.
Broadcast a message.
CA Dataquery displays a bulletin board immediately after a user signs on. The bulletin board can be used to distribute information to all CA Dataquery users.
Select the LANGUAGE option on the Administrative Menu. For details, see
Changing the Bulletin Board
Cancel a user's query while it is processing.
Use the USERS option from the Administrative Menu. Use the PF key to get to the
Directory of Active Users. Then use the PF key to do a CANCEL FIND.
22 Administration Guide
Required CA Dataquery Skills
■
■
Use the Printer Control option on the Administrative Menu. For details, see
Using the Printer Control
Disallow use of a query.
If a query is being used that is causing system problems, you can use the CA
Dataquery Administrator Library Maintenance function to change the author's name to an unknown author and make the query private. This keeps the query from appearing in the user's library. This does not delete the query but keeps it from being used until the problem is resolved.
Chapter 2: CA Dataquery Administrator Overview 23
Chapter 3: CA Dataquery in the CA Datacom
System
CA Dataquery is the information retrieval and data manipulation component of the CA
Information Center products. CA Dataquery operates in both online and batch environments to allow you to access and manipulate data from the database and display the results in an easily read format.
Product Definition
CA Dataquery is an easy-to-use tool for accessing the most up-to-date information in your database. CA Dataquery not only retrieves the data, it also offers many options for manipulating, formatting, saving, and passing data to other programs. With special authorization, you can use CA Dataquery to change the data in your database. See
Modifying Data Using CA Dataquery
(see page 185) for more information about this
subject.
You can use a query to retrieve the data and format it on your terminal screen or print it on a printer. The query that performs these tasks for you can be written in either DQL
Language or SQL, (query languages that use easy-to-understand English).
Languages
CA Dataquery supports two query languages:
■
FIND, SORT and PRINT are examples of DQL Language.
–
FIND tells CA Dataquery which database table to read
–
SORT tells CA Dataquery how to sort the rows
–
PRINT tells CA Dataquery which data to display in columns
The DQL Language provides keywords for qualifying the retrieved data, making calculations, and controlling how the data appears in your report.
Chapter 3: CA Dataquery in the CA Datacom System 25
System Defaults
■
SELECT, FROM, and WHERE are examples of SQL.
–
SELECT tells CA Dataquery which column of a database table to retrieve
–
FROM tells CA Dataquery which database table contains the column
–
WHERE tells CA Dataquery what conditions to apply to the retrieved information
Reporting
CA Dataquery provides a wide variety of common reporting capabilities. For instance, you can sort found data by any sort criteria, limit data selection, choose to report detail or summary data, and change report formats.
System Defaults
The system defaults are defined in the DQOPTLST macro and are stored in the CA
Dataquery System Option Table at installation time. How your site defines the parameters in the DQOPTLST macro will impact your users. Assist your Database
Administrator in choosing appropriate values for the parameters defined in the System
Option Table.
User Concerns
■
■
■
■
■
■
■
Questions you can help with include:
■
How many users are there? How many batch queries will process concurrently?
■
What is the maximum number of rows any one query will find?
■
What is the largest row a query will find?
How long should a terminal be allowed to stand idle before auto signoff is invoked?
How many rows should a user be able to search?
■
What printing facilities are required?
What numeric display patterns are required?
What batch execution specifications are required?
How long should a query be allowed to process before relinquishing control to another task?
What user exits are required?
What, if any, user program should gain control after CA Dataquery signoff?
26 Administration Guide
System Table Batch Utilities
System Table Batch Utilities
CA Dataquery provides utilities to initialize, back up and restore CA Dataquery system tables.
DQLANGMT
Used to maintain the DQM, DQP and DQV tables for CA Dataquery language
maintenance. For more information, see
Using the Language Maintenance Facility
(see page 310).
DQLIBRMT
Used to maintain the CA Dataquery DQQ table for CA Dataquery library
maintenance. For more information, see
Performing Query Table Maintenance
(DQLIBRMT)
DQWFINIT
Used to maintain the DQE, DQF, and DQW tables for Found Table Initialization. For
Initializing the DQE, DQF, and DQW (DQWFINIT)
page 102).
DQUSERMT
Used to maintain the DQU tables for user maintenance. For more information, see
Performing User Table Maintenance (DQUSERMT)
DQCRRPT
Used to submit Condition and Restriction reports. For more information, see
Condition/Restriction Reporting (DQCRRPT)
DQPANPRT
Used to print CA Dataquery Panels. For more information, see
Printing CA
Dataquery Panels
User Exits
User exits allow a programmer to establish routines that occur at predetermined points in CA Dataquery's processing. These routines can provide additional security or they can be used to process retrieved data in a specialized way for your site. Any user exits in use at your site are created by programmers at your site. Familiarize yourself with these exits so that you can express your needs in this area to the Database Administrator and systems programmer who codes the exits. You should also be aware of how the exits affect the user.
Chapter 3: CA Dataquery in the CA Datacom System 27
Diagnostics and CA Datacom/DB Accounting Statistics
Diagnostics and CA Datacom/DB Accounting Statistics
CA Dataquery provides a diagnostics function to help the CA Dataquery Administrator determine the efficiency of the queries, dialogs or terms while executing with the system defaults and when the system defaults have been changed.
The CA Datacom/DB Accounting Statistics tell the CA Dataquery Administrator how the queries, dialogs or terms have executed in conjunction with CA Datacom/DB. The CA
Dataquery Accounting Statistics are designed to show statistics on a user-by-user basis.
Compound Boolean Selection statistics are included. See Using DQL Diagnostics for more information about using diagnostics. See Using the Accounting Facility for more information about CA Datacom/DB Accounting statistics.
To successfully sign on to CA Dataquery, the CA Datacom Datadictionary User
Requirements Table (URT) and the CA Dataquery User Requirements Table (URT) must be open prior to any user issuing the DQRY signon command.
A CA Dataquery signon consists of a user name and an optional password which the user must enter to access CA Dataquery. You authorize each user by creating each user signon. See Authorizing Users for more information about authorizing users.
In addition, CA Dataquery provides a User Signon/Off Exit enabling your site to interface with other security packages such as CA ACF2, or CA Top Secret. The use of other security packages can impact your standards for a valid user name and password.
It is important that you understand your site's signon procedures. Meet with the administrator in charge of security to gain a complete understanding of your site's signon security measures.
CA Dataquery Audit Facility
CA Dataquery provides a facility to audit access to data using Dataquery. The facility uses the CA Datacom/DB LOGDW command to write to the log file an entry containing user and environmental information and the text to the query. The "Audit Facility records only DQL queries.
The " Audit Facility is activated by setting the AUDIT1=parameter in the Dataquery
System Options Table (DQOPTLST) to ON.
The logged records can be read using the CA Datacom/DB READRXX facility. The format of the logged records follow.
28 Administration Guide
CA Dataquery Audit Facility
1
5
Note: This is the format of the data which follows the RXX Header documented in the
CA Datacom/DB Database and System Administration Guide section Using the Recovery
File (RXX) Read Subroutine.
Location Length Format Content
4
32
Binary
Char
37
46
47
62
101
103
7783
9
1
15
39
2
7680
218
Char
Char
Char
Char
Binary
Char
Char
Work Area Length
User ID
Internal Security: Person
External Security: Blank (ID can be obtained from the RXX Header)
Blank (reserved for future)
Environment
O = Online
B = Batch
Query Name
Blank (reserved for future)
Length of the query text that follows
Text of the query
Blank (reserved for future)
Chapter 3: CA Dataquery in the CA Datacom System 29
Chapter 4: Accessing the Online
Administrative Functions
You can access CA Dataquery's online administrative functions through the
Administrative Menu and through Administrative Commands.
Administrative Menu
To access administrative functions, sign on to CA Dataquery and press Enter after reading the bulletin board (if displayed). When CA Dataquery displays the Main Menu, select the ADMINISTRATION option, or enter ADMIN on the Command line (see
Administrative Commands). CA Dataquery displays the administrative tasks assigned to you.
The following panel shows all the administrative functions that are available to CA
Dataquery Administrators:
Administrative Menu (DQKH0)
=>
------------------------------------------------------------------------DQKH0
DATAQUERY: ADMINISTRATIVE MENU
----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> __
1. PROFILE - Display and update user profile
2. CONDITIONS - List create and maintain conditions
3. RESTRICTIONS - List create and maintain restrictions
4. PRINTER CONTROL - Request control functions for a network printer
5. JCL - List and maintain batch query JCL
6. DIAGNOSTICS - Produce storage dumps
7. LANGUAGE - Translate DATAQUERY text to another language
8. USERS - List and maintain DATAQUERY users
9. SETS - List and maintain saved sets
10. LIBRARY - Maintain query library member attributes
11. SECURITY CONTROL - Table and column security authorization
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Chapter 4: Accessing the Online Administrative Functions 31
Administrative Menu
Administrative Functions
The following is a brief explanation of each administrative function:
PROFILE
Display or update your profile. CA Dataquery allows a user to modify personal profile option defaults for the CA Dataquery online and batch features, primary and secondary language selections, and network printing options. Associate users do not have this privilege unless given the authority on the System Option Table.
Some profile options default to values specified at the time the user is added to CA
Dataquery or the privileges and authorizations are updated by a CA Dataquery
Administrator. Other profile options default to values from the System Option
Table.
CONDITIONS
(DQL Mode only) Create, delete, view, or edit a condition. A condition (when assigned to a restriction) allows a user or group of users access to some, but not all, of the rows in a table. You name the condition, identify the table and state the condition. For example, the condition might restrict access to all COMPANY records containing a value of 15 in the column for sales ID and a value of DALLAS in the CITY column.
RESTRICTIONS
(DQL Mode only) Create, delete, view, or edit a restriction. A restriction consists of one or more conditions applied to data access for a user or a group.
PRINTER CONTROL
Display a directory of outstanding network print requests. It allows a request to be canceled (flushed), stopped, or restarted from the point that it was stopped or from the beginning of the print request.
JCL
Create, delete, view, or edit JCL and JCL procs. (JCL procs members are JCL members that have variables. This guide discusses variables and procedure members in Creating a JCL PROC for Online Submission.)
DIAGNOSTICS
Display the CA Dataquery Request Table or request a storage dump in the form of a transaction dump or a module dump to assist CA Support in solving problems. For instructions about contacting CA Support, see the CA Dataquery Message Reference
Guide. You can also display Compound Boolean Selection statistics. You choose where (terminal ID) and when the dump is to be turned on or off.
32 Administration Guide
Administrative Menu
LANGUAGE
Translate and display CA Dataquery panels, program literals, and vocabulary terms to another language, or customize them to suit your site's needs. You also use this function to create messages to be placed on the CA Dataquery bulletin board.
USERS
Add, delete, view, and update users as well as list active users, users' profiles, and send messages to individual users. You can maintain a user's name, password, accounting code, group level, authorization for administrative functions and override system defaults. You can modify any user's profile. A CA Dataquery
Administrator who is authorized to perform the USERS function, can assign user signons for new users to CA Dataquery or change a user's signon characteristics as discussed previously. As a CA Dataquery Administrator, you cannot delete yourself or turn off your user maintenance authorization.
SETS
The USERS authorization is the key to all other authorizations and should be
carefully controlled.
(DQL Mode only) View, delete, and use saved found sets. Anyone (except the associate user) who runs a query can save the resulting collection of data as a saved found set. You can reuse the data in a saved set, delete the saved set, or view a listing of the saved sets.
LIBRARY
Create, delete, edit, execute, or submit a query. You can modify the extended definition of a query which includes specifying the query status as PRIVATE or
PUBLIC and modify the groups assigned to that query or the author of that query.
You can also create queries, establish dialog definitions, submit and validate queries. You can also edit queries created by others. The LIBRARY function maintains the attributes (extended definitions) of the Query Library Table members.
SECURITY CONTROL
(DQL Mode only) Authorize access to a CA Datacom/DB database (to all of its tables) or authorize access to a specific CA Datacom/DB tables within a database. DQL table security is in effect only if CA Dataquery has not been externally secured. You can display a list of all users authorized to access a particular CA Datacom/DB database, or display a list of all the tables that a user is authorized to use. You can name the CA Datacom/DB Database Identifier (DBID) and the tables that you are authorizing a user to access, or select the user and then name the DBID and the tables you want him to access. You can copy security from one user to another as well as add, delete, and update profile codes.
Chapter 4: Accessing the Online Administrative Functions 33
Administrative Commands
Administrative Commands
As a CA Dataquery Administrator, you can use many, if not all of the following administrative commands. The administrative commands can be entered as complete words or as the unique beginning letters of the commands on the command line. You can also use the end-user commands for the mode in which you are operating. See the end-user documentation for information about those commands.
ACTIVE
Displays the Directory of Active Users panel when you type ACTIVE on the command line and press Enter. You see a listing of the active CA Dataquery users on the Directory of Active Users panel.
ADMIN
(Requires authorization) Displays the Administrative Menu when you type ADMIN on the command line and press Enter. The administrative tasks that you are authorized to perform are listed on the Administrative Menu.
CONDITIONS
Displays the Directory of Conditions panel when you type CONDITION on the command line and press Enter. The Directory of Conditions panel lists the conditions that are defined for the CA Dataquery system.
DIAGNOSTIC
Displays the Diagnostic Request panel when you type DIAGNOSTIC on the command line and press Enter. The Diagnostic Request panel allows you to perform CA
Dataquery diagnostic functions.
JCL
Displays the Directory of JCL Members panel when you type JCL on the command line and press Enter. The Directory of JCL Members panel lists the JCL members that are defined for the CA Dataquery system.
LANGUAGE
Displays the Language Maintenance Menu when you type LANGUAGE on the command line and press Enter. The Language Maintenance Menu lists the language options that are available to translate or customize the CA Dataquery panels and
Language.
LIBRARY
Displays the Administrative Library List when you type LIBRARY on the command line and press Enter to allow the administrator to enter selection criteria for a directory of query library members.
34 Administration Guide
Administrative Commands
PRINTER
Displays the Directory of Spooled Print panel when you type PRINTER on the command line and press Enter. The Directory of Spooled Print panel lists the users with print requests.
PROFILE
Displays the Profile Maintenance panel when you type PROFILE on the command line and press Enter. The Profile Maintenance panel displays your user profile attributes.
RESTRICTIONS
Displays the Directory of Restrictions panel when you type RESTRICT on the command line and press Enter. The Directory of Restrictions lists the restrictions that are defined for the CA Dataquery system.
SECURITY
Displays the Security Control Selection Menu when you type SECURITY and press
Enter. The Security Control Selection Menu lists the functions of CA Dataquery security control.
SETS
Displays the Directory of Saved Sets panel when you type SETS on the command line and press Enter. The Directory of Saved Sets panel lists the found sets saved by the CA Dataquery system.
STALL
A diagnostic command, allowing the user to display extended execution statistics for the active query.
USERS
Displays the Directory of CA Dataquery Users panel when you type USERS on the command line and press Enter. The Directory of CA Dataquery Users panel lists all of the authorized CA Dataquery users.
Chapter 4: Accessing the Online Administrative Functions 35
Chapter 5: Post-Installation Tasks
Installation of CA Dataquery is described in the CA Datacom Installation and
Maintenance Guide.
CA Dataquery Storage Requirements
The CA Dataquery components are of two types, those which support the online and batch query systems and those for the utility support function. All are reusable and are reentrant. Most of the modules are operating system independent.
Function processors are provided as transient. You can change any or all of them to memory-resident.
For a description of the CA Dataquery-provided tables, see Preparing and Maintaining the CA Dataquery System Tables.
Approximate storage requirements for important CA Dataquery components follow:
Common subroutines
Approximately 28 KB
System table
Approximately 4 KB
Online or batch dependent module
Approximately 7 KB
Function processors
Site-specific
User exits
Site-specific
CA Dataquery database tables
Calculating Sizes for System Tables
Report engine modules
Approximately 256 KB
Chapter 5: Post-Installation Tasks 37
Tailoring CA Dataquery and CA Datacom/DB
Tailoring CA Dataquery and CA Datacom/DB
Once you have installed CA Dataquery as described in the CA Datacom Installation and
Maintenance Guide, you must perform several steps to prepare CA Datacom/DB and CA
Dataquery for CA Dataquery operation. The steps for customizing CA Dataquery and for tailoring CA Datacom/DB for CA Dataquery operation are listed following and discussed in more detail in following chapters.
1. Prepare the MUF and review its startup options. For more information, see
Preparing the CA Datacom/DB Multi-User Facility
2. Tailor the CA Dataquery System Option Table. For more information, see
Tailoring the CA Dataquery System Option Table
3. Prepare the CA Dataquery system tables. For more information, see Preparing and
Maintaining the CA Dataquery System Tables.
4. Prepare CICS. For more information, see
Implementing CA Dataquery Under CICS
(see page 107).
5. Set up the Accounting Facility.
If you intend to use the Accounting Facility for accounting, billing, or performance
Using the Accounting Facility
(see page 517) for more information.
6. If you intend to execute queries using the Batch Facility or print to a system printer after online query execution:
■
You can set up online batch submission JCL for selected users or groups of users.
■
You must install the internal reader.
■
You can also export columns and keys named in the PRINT or DISPLAY statement of a query to an output file. You must prepare to use the Batch
Export function. For more information, see
Using the Batch Export Function
(see page 433).
7. Prepare to extract data. (DQL Mode only.)
If you intend to extract data so that user programs can access the data, see
Extracting Data (FEX)
(see page 453) for more information.
8. Prepare for user exit use.
If you want to write and use user exits for such things as your signon procedure or
for query validation. For more information, see
Programming User Exits
page 459).
38 Administration Guide
Preparing JCL for Batch CA Dataquery Utilities
9. Set up the CA Dataquery Language Maintenance Facility.
If you want to use the Language Maintenance Facility to translate or customize the
CA Dataquery vocabulary, literals, messages, commands, menus, and panels. For
Using the Language Maintenance Facility
If you have translated portions of CA Dataquery with the last version and have run
DQLANGMT with the SYSIN RUNTYPE=LOAD,LANG=xx, (where xx is the code for your translated panels) before installing this version, you can retain your translations on those portions of CA Dataquery that have not changed. See
Upgrading to a New Version, the CA Datacom Release Notes, or the installation documentation for details.
10. Plan and implement security. For more information, see
Security Overview
page 201).
11. Add and authorize users. For more information, see
Authorizing Users
page 207).
12. Create your CA Dataquery databases. For more information, see
Defining Databases
(see page 111).
13. Define the CA Dataquery User Requirements Tables. For more information, see
Defining the CA Dataquery User Requirements Tables.
Preparing JCL for Batch CA Dataquery Utilities
Guidelines to assist you in preparing your JCL are provided in this guide. The sample code provided in this document is intended for use as a reference aid only and no warranty of any kind is made as to completeness or correctness for your specific installation.
For more information, see How to Obtain JCL and Sample Members on the bookshelf under By Scenario or Feature,
Note: In z/OS, the default name for this library is CABDAC. In z/VSE, sample PROCs are provided that allow you to make use of parameter substitution.
Any JOB statements should be coded to your site standards and specifications. All data set names and library names should be specified with the correct names for the installation at your site. In many examples, a REGION= or SIZE= parameter is displayed in an EXEC statement. The value displayed should be adequate in most instances, but you can adjust the value to your specific needs.
Chapter 5: Post-Installation Tasks 39
Preparing JCL for Batch CA Dataquery Utilities
The libraries listed for searching must include the following in the order shown:
1. User libraries you may have defined for specially assembled and linked tables, such as DBMSTLST, DBSIDPR, DDSRTLM, DQSYSTBL, or User Requirements Tables
2. CA Datacom base libraries (CABDLOAD): CA Datacom/DB, CA Datacom
Datadictionary, CA Dataquery, SQL
3. CA Common Services for z/OS or CA CIS (Common Infrastructure Services) for z/VSE base libraries
4. CA IPC libraries
5. Libraries for additional products, such as CA Datacom CICS Services, CA Datacom
VSAM Transparency, CA Ideal, and so on
CA Dataquery users also need the following libraries and data sets for the following specific functions:
■
The z/OS data set DQOUT or the z/VSE data set DQOUTD (disk) or DQOUTT (tape) is used only if the DQBATCH execution uses the EXPORT function for variable length data. If fixed length output is generated, z/os uses DQFIXD (disk) and z/VSE uses
DQFIXD (disk) or DQFIXT (tape).
■
In z/OS, running deferred queries with separate JCL members in batch requires, in addition to the SYSIN statement DEFER, the inclusion of a DD statement for the internal reader used by VPE. This DD statement should be:
//ADRSUB DD SYSOUT=(A,INTRDR)
Job Control Statements
CA Datacom/DB table definitions are not included since CA Dataquery operates with the
CA Datacom/DB MUF. Use the following job control statements to execute CA
Dataquery batch utilities.
z/OS JCL Statement
JOB
Initiates the job.
EXEC
Specifies the program name of the CA Dataquery utility to be run.
SYSPRINT DD
Defines the sequential output data set used for listing the output report.
40 Administration Guide
Preparing JCL for Batch CA Dataquery Utilities
SYSIN DD
Defines the control data set. It normally resides in the input stream; however, it can reside on a system input device or a direct access volume.
DQBKPFIL DD
Output data set for a DQLIBRMT backup of Query Library members as requested in the BACKUP control statements. Produces a sequential file that can reside on tape or disk. This statement is needed only in JCL specifying a DQLIBRMT backup.
DQRSTFIL DD
Input data set of Query Library members to be added to the Query Library Table as requested by a DQLIBRMT RESTORE control statement. This data set must have been created by a previous execution of DQLIBRMT and is needed only if a restore is requested.
z/VSE JCL Statement
JOB
Initiates the job.
EXEC
Specifies the program name of the CA Dataquery utility to run.
SYSLST
Defines the sequential output data set used for listing the output report.
SYSIPT
Defines the control data set that resides in the input stream.
DQQBKPT
Output tape data set for a DQLIBRMT backup of Query Library members as requested by BACKUP control statements. This data set must be on SYS010 and is needed only if tape backup is requested. If disk backup is requested, use the
DQQBKPD control statement.
DQQBKPD
Output disk data set for a DQLIBRMT backup of Query Library members as requested by backup control statements. This data set must be on SYS011 and is needed only if disk backup is requested. If tape backup is requested, use DQQBKPT.
Chapter 5: Post-Installation Tasks 41
Preparing JCL for Batch CA Dataquery Utilities
DQQRSTT
Input tape data set of Query Library members created by a previous execution of
DQLIBRMT. The members are to be added to the Query Library Table as requested by the DQLIBRMT RESTORE control statement. This data set must be on SYS011 and is needed only if tape restore is requested. If disk restore is requested, use
DQQRSTD.
DQQRSTD
Input disk data set of Query Library members created by a previous execution of
DQLIBRMT. The members are to be added to the Query Library Table as requested by the DQLIBRMT RESTORE control statement. This data set must be on SYS011 and is needed only if disk restore is requested. If tape restore is requested, use
DQQRSTT.
42 Administration Guide
Chapter 6: Preparing the CA Datacom/DB
Multi-User Facility
If your site is installing both CA Dataquery and CA Datacom/DB at the same time, the CA
Datacom installation generates the interface between them.
If your site is adding CA Dataquery to an existing CA Datacom/DB system or modifying
CA Datacom/DB (such as adding databases and tuning the system), the following items need to be reviewed to help ensure that CA Datacom/DB continues to support CA
Dataquery:
■
CA Datacom/DB MUF startup options
■
CA Dataquery Online User Requirements Tables
■
CA Datacom CICS Services (only if operating under CICS)
■
Execution time JCL
Preparing the MUF
All data managed by CA Datacom/DB that is to be accessed by CA Dataquery must be available on one MUF, unless CA Datacom STAR is used for distributed processing. For special considerations involving processing in a distributed environment, see your CA
Datacom STAR documentation.
The MUF must include the appropriate JCL statements for all storage areas if CA
Datacom/DB's dynamic allocation feature is not in use.
For more information about the MUF, see the CA Datacom/DB Database and System
Administration Guide.
Chapter 6: Preparing the CA Datacom/DB Multi-User Facility 43
Preparing JCL for Batch CA Dataquery Utilities
Multi-User Startup Options
CA Dataquery operates with the CA Datacom/DB MUF. The MUF with which you operate CA Dataquery must be initiated meeting the specific startup options requirements described in the table on the following pages.
Note: For complete information about all of the CA Datacom/DB MUF startup options, see the CA Datacom/DB Database and System Administration Guide.
Multi-User Startup Option
CBS dbid,buffer,maxsten,maxstio,maxage
These options control the resources available for the CA Datacom/DB Compound
Boolean Selection Facility which processes CA Dataquery queries. The values specified for these startup options affect CA Dataquery performance.
dbid
Specifies the database ID in which the Compound Boolean Selection Facility builds temporary indexes when processing queries. We recommend database 6 for this use.
buffer
Specifies the size of the buffer available for Compound Boolean Selection processing. Must be a minimum of 1024. While you are using CA Dataquery, check the CBSBFR SPILL COUNT statistic in the Statistics and Diagnostics Area report. If the count is high, you can decrease it and improve performance by increasing the
CBS buffer value.
maxsten
Limits the number of temporary index entries which the Compound Boolean
Selection Facility creates before terminating processing. If no MAXSTEN value is specified, the Compound Boolean Selection Facility creates as many temporary index entries as are necessary to satisfy a query. If your site is having problems with the Index Area filling up (receiving a CA Datacom/DB return code 8 on a SELFR when executing queries), you can use this parameter to limit how much of the Index Area one SELFR can allocate. Consider that although most SELFRs issued by CA Dataquery do not cause a temporary index to be built, it is possible to have one for each table named in a query existing simultaneously. If a SELFR terminates because this limit has been set, query execution also terminates with a CA Datacom/DB return code
91.
Note: You can use the MAXSTEN console command to temporarily change this option while MUF is operating. For details, see the CA Datacom/DB Database and
System Administration Guide.
44 Administration Guide
Preparing JCL for Batch CA Dataquery Utilities
maxstio
Limits the number of CA Datacom/DB records inspected by the Compound Boolean
Selection Facility when processing a query. If no MAXSTIO value is specified, the
Compound Boolean Selection Facility inspects as many records as necessary to satisfy a query.
Note: You can use the MAXSTIO console command to temporarily change this option while MUF is operating. For details, see the CA Datacom/DB Database and
System Administration Guide.
maxage
Allows you to specify the age beyond which unused sets can be deleted.
DATACOM entry1,entry2, ...
This option specifies the licensed CA products that execute with this MUF. DQ must be one of the entries for CA Dataquery to execute.
DATAPOOL dataln,datano
This option controls the number and size of the buffers for data access (data buffers). You can also specify an optional second set.
dataln
Specifies the size of the data buffers and, when using CA Dataquery, must be a minimum of 4096.
datano
Specifies the number of data buffers.
EXCTLNO n
Specifies the maximum number of records over which a single task can simultaneously hold under exclusive control. When using CA Dataquery, this must be a minimum of 8.
EXPAND length,number
This option controls the number and size of the buffers for expanding compressed records.
length
Specifies the size of the expand buffers which, when using CA Dataquery, must be a minimum of 4108 or 12 bytes larger than the largest record that is to be expanded.
Chapter 6: Preparing the CA Datacom/DB Multi-User Facility 45
Preparing JCL for Batch CA Dataquery Utilities
number
CA Dataquery tasks access compressed tables so include the CA Dataquery tasks in your specification. See the Master List discussion in the CA Datacom/DB documentation for details.
MAXELRQ n
Specifies the maximum number of elements which can be accessed by a request.
This option must be a minimum of 10 for CA Dataquery.
46 Administration Guide
Chapter 7: Tailoring the CA Dataquery
System Option Table
A basic System Option Table is installed when you install CA Dataquery. The DQOPTLST macro creates a System Option Table when it is assembled and link-edited. Default
DQOPTLST parameters that affect space or resource allocations are specified at installation/upgrade time. If you decide to change any parameter value at a later time, you can do so, but you must reassemble the DQOPTLST macro to re-create the System
Option Table.
The CA Dataquery System Option Table determines such CA Dataquery system options as:
■
The CA Datacom/DB database IDs of the CA Dataquery database and the CA
Datacom Datadictionary database which will be accessed by CA Dataquery
■
The amount of space to be reserved in task-related storage for a special work area
■
The method to use to build column headings and edit patterns if these are not specified in the query
■
The user and resource limitations
The system options are defined by the DQOPTLST macro. The CA Dataquery
Administrator can override some of the defined system options for specific users through a CA Dataquery administrative function. Parameters which the CA Dataquery
Administrator can override are noted in the descriptions on the following pages.
Options Which Impact CA Dataquery Performance
Evaluate the effect of the parameters which affect the number of physical blocks used for query execution, the amount of query processing time, the maximum find time, and the number of times CA Dataquery is to relinquish control to other tasks during the execution of a query, such as:
■
FNDBLKS=
■
MFTIME=
■
MXREQ=
■
MXTLR=
SQL users are not impacted by the DQOPTLST parameters MXREQ=, MFTIME=, and
MXTLR= because SQL is a database management language.
Chapter 7: Tailoring the CA Dataquery System Option Table 47
How to Modify the System Option Table
Option Table Considerations
■
■
■
■
■
■
■
Before specifying the DQOPTLST parameters, determine the answers to the following questions about your CA Dataquery environment.
■
How many users are there?
■
How many batch queries process concurrently?
■
What is the maximum number of rows any one query will find?
■
What is the largest row a query will find?
How long should a terminal be allowed to stand idle before auto signoff is invoked?
How many rows should a user be able to search?
What printing facilities are required?
■
What numeric display patterns are required?
What batch execution specifications are required?
How long should a query be allowed to process before relinquishing control to another task?
What user exits are required?
What, if any, user program should gain control after DQ signoff?
How to Modify the System Option Table
Alter the parameters of the DQOPTLST macro. (For an example, see the DQSAM03 member on the CA Datacom page on http://support.ca.com/. See the CA Datacom
Release Notes.) Then, to make these changes take effect, you must:
1. Reassemble and link edit it.
2. Have all users sign off CA Dataquery and check the CICS use count.
3. Place the updated System Option Table into effect in one of the following ways:
■
If the CICS use count is zero, do a CICS NEWCOPY of DQSYSTBL.
■ If the CICS use count is not zero, bring down the monitor and bring it back up again.
48 Administration Guide
DQOPTLST Parameters
Coding Rules
In coding the macros, standard Assembler rules apply. A statement to be continued on the next line must have a non-blank character in column 72, and the next line must begin in column 16.
Changing the DATACOM-ID of DATA-DICT
If you change the DATACOM-ID of the DATA-DICT database, update the CA Dataquery
System Option Table and reassemble and link-edit the DQSYSTBL. If you do not change the database ID designation of the CA Datacom Datadictionary in these places, the CA
Dataquery requests are resolved using the wrong CA Datacom Datadictionary database.
DQOPTLST Parameters
Following are descriptions of the DQOPTLST parameters, their valid entries, and their default values. They are listed in alphabetical order.
ASUPPRO=
Specifies whether associate users can modify their own user profile and print options.
Valid Entries:
NO or YES
Default Value:
NO
AUDIT1=
Specifies whether the Audit Facility is to be active.
Valid Entries:
OFF or ON
Default Value:
OFF
BTCHLPX=
Specifies the name of the module if the exit is to be linked as a separate module,.
The module is used in the Batch Line Printer Exit.
Valid Entries:
1- to 8-character module name
Default Value:
(No default)
Chapter 7: Tailoring the CA Dataquery System Option Table 49
DQOPTLST Parameters
BUFSIZE=
Specifies the amount of space to be reserved in task-related storage for a special work area used as an input row buffer.
Code BUFSIZE as the length of the largest user CA Datacom/DB row to be accessed by CA Dataquery. The value should not be larger than what is coded in DATALN in the CA Datacom/DB Master List. Also, the value should not be smaller than what is coded for DQESIZE=.
Valid Entries:
4600 or greater
Default Value:
4600
CADATE=
Specifies the format used to display columns which are defined as date fields with the SEMANTIC-TYPE attribute. For more information about the updateable attributes of FIELD entity-occurrences, see the CA Datacom Datadictionary Online
Reference Guide.
Valid Entries:
1- to 30-character format name
Default Value:
A
CDBIDSL=
Specifies that database IDs greater than 999 are to be used by the DBID exit. For more information about the DBID exit see the descriptions of CDBXITB= and
CDBXITO= and the information about the DBID exit in DBID Exit.
Valid Entries:
NO or YES
Default Value:
NO
CDBXITB=
Specifies the name of batch DBID exit. Must not be the same as any CA Dataquery module name.
Valid Entries:
1- to 8-character module name
Default Value:
(No default)
50 Administration Guide
DQOPTLST Parameters
CDBXITO=
Specifies the name of the online DBID exit. Must be in PPT and must not be the same as any CA Dataquery module name.
Valid Entries:
1- to 8-character module name
Default Value:
(No default)
CMTBEG=
Specifies one or two characters to indicate the beginning of a comment within the text of a query. The value must be unique among CMTEND=, DIAFILL=, DIASYMB=,
HDGSEP=, HDGSUB=, and LITMASK=.
Valid Entries:
One or two characters
Do not use:
■
The letters A through Z
■
■
The integers 0 through 9
A period (.), a comma (,), or a single quote mark (')
You must not code a single arithmetic operator (= - + / *). You may use - and + and / and * together for two character values. However, in a z/VSE environment, changing the COMMENT BEGIN character to /* causes problems when using the CA Dataquery online SUBMIT function.
Default Value:
*/
Chapter 7: Tailoring the CA Dataquery System Option Table 51
DQOPTLST Parameters
CMTEND=
Specifies one or two characters to indicate the end of a comment within a query.
The value must be unique among CMTBEG=, DIAFILL=, DIASYMB=, HDGSEP=,
HDGSUB=, and LITMASK=.
Valid Entries:
One or two characters
Do not use:
■
The letters A through Z
■
■
The integers 0 through 9
A period (.), a comma (,), or a single quote mark (')
You must not code a single arithmetic operator (= - + / *). You may use - and + and / and * together for two character values.
Default Value:
/*
CONVUSR=
Specifies the level of access provided when the external security resource cxxname.DQACCESS.CONVUSR is specified with "ALL" access. See the CA Datacom
Security Reference Guide for more details about CA Dataquery and external security.
Valid Entries:
ASSOCIATE
Default Value:
CONVENTIONAL
52 Administration Guide
DQOPTLST Parameters
DATAXIT=
Specifies the name of the user exit to examine the data rows retrieved by a DQL
Mode query. The name must be in the PPT and not the same as any CA Dataquery module.
Valid Entries:
1- to 8-character module name
Default Value:
(No default)
DATEFMT=
Specifies the format to use to print columns in DQL Mode and SQL Mode which are defined as SQL date types.
Valid Entries:
EUR (dd.mm.yyyy)
ISO (yyyy-mm-dd)
JIS (yyyy-mm-dd)
USA (mm/dd/yyyy)
Default Value:
USA
DDDBID=
Specifies the CA Datacom/DB database ID for the CA Datacom Datadictionary ordinarily accessed by CA Dataquery. Normally you would identify the locaCA
Datacom Datadictionary database. This is the CA Datacom Datadictionary in which all CA Dataquery DQL Mode security information is stored regardless of the DDDBID specified in the user's profile.
Valid Entries:
A valid database ID
Default Value:
00002
Chapter 7: Tailoring the CA Dataquery System Option Table 53
DQOPTLST Parameters
DDHDG=
Specifies the method CA Dataquery is to use to build the PRINT or DISPLAY column headings if the query does not specify a heading. (If the query provides the heading,
CA Dataquery uses it no matter how this parameter is coded.) The value consists of two subparameters separated by a comma and enclosed within parentheses.
Note: YES is honored only if the appropriate values have been coded for the column heading attributes HEADING-1 and HEADING-2 in CA Datacom Datadictionary. If none have been coded, CA Dataquery takes the NO option.
Valid Entries:
(YES,1) -- CA Dataquery obtains the heading from the CA Datacom
Datadictionary column heading attribute HEADING-1.
(YES,2) -- CA Dataquery uses the headings from the CA Datacom Datadictionary
HEADING-1 and HEADING-2 column heading attributes.
(NO,1) or (NO,2) -- CA Dataquery uses either an alternate name specified within the query or the occurrence name of the column or key, in that order.
Default Value:
(YES, 2)
DDPIC=
Specifies the edit pattern CA Dataquery is to use for numeric columns if no edit pattern is specified in the query. (If an edit pattern is specified in the query with the
PICTURE clause, CA Dataquery uses it no matter how this parameter is coded.)
If you code YES, CA Dataquery uses the edit pattern coded in CA Datacom
Datadictionary. If the column has an invalid edit pattern in CA Datacom
Datadictionary (one that does not fit the data), CA Dataquery issues an error message and does not process the query.
If you code YES but no edit pattern is provided in CA Datacom Datadictionary, CA
Dataquery builds its own edit pattern as described in the NO option.
If you code NO, CA Dataquery checks with CA Datacom Datadictionary to get the defined precision and builds a PICTURE that displays all digit positions and inserts a decimal point and sign if needed.
Valid Entries:
NO or YES
Default Value:
YES
54 Administration Guide
DQOPTLST Parameters
DECPT=
(Code only if using a language other than English.) Specifies the character to use to indicate the decimal point when printing numeric values. DECPT= is used only in conjunction with the Language Maintenance Facility.
Valid Entries:
The words PERIOD or COMMA
Default Value:
PERIOD
DIAFILL=
Specifies a dialog fill character, used in the dialog text as a space saver for variables so that values longer than their default are allowed. Use this parameter to set the dialog fill character for your site. (See the CA Dataquery User Guide or CA Dataquery
Reference Guide for information about dialogs.) The value must be unique among
LITMASK= and DIASYMB=, and it must not be the same as any part of the values assigned to CMTBEG= and CMTEND=.
Valid Entries:
Single character
Do not use:
■
■
■
The letters A through Z
The integers 0 through 9
A period (.), a comma (,), or a single quote mark (')
■
An arithmetic operator (= - + / *)
Default Value:
An underscore character ( _ )
Chapter 7: Tailoring the CA Dataquery System Option Table 55
DQOPTLST Parameters
DIASYMB=
Specifies a dialog symbol, used in the dialog text to mark a word or value as a variable. Use this parameter to set the dialog symbol for your site. The specified value must be unique among LITMASK= and DIAFILL= and must not be the same as any part of the values assigned to CMTBEG= and CMTEND=.
Valid Entries:
Single character
■
The letters A through Z
■
■
■
The integers 0 through 9
A period (.), a comma (,), or a single quote mark (')
An arithmetic operator (= - + / *)
Default Value:
? (A question mark character)
DQDBID=
Specifies the CA Datacom/DB database ID for the CA Dataquery database.
Valid Entries:
A valid database ID
Default Value:
00003
DQESIZE=
Specifies the record size of the DQE table (block size minus 14). At installation, the block size is set to 4096. A record size 4082 means the largest total column length for data is 4030 (record size minus 52). If this is not sufficient for SQL retrieval of one row, redefine the DQE table through CA Datacom Datadictionary, reallocate and reinitiate the DQE table, and change this parameter to reflect the new size.
Valid Entries:
(Block size of DQE) minus 14
Default Value:
4082
56 Administration Guide
DQOPTLST Parameters
DQIN=
Specifies the transaction ID to use in place of the DQIN transaction on this CA
Dataquery system.
Valid Entries:
Any 1- to 4-character TRANSID
Default Value:
DQIN
DQPR=
Specifies the transaction ID to use in place of the DQPR transaction on this CA
Dataquery system.
Valid Entries:
Any 1- to 4-character TRANSID
Default Value:
DQPR
DQRY=
Specifies the transaction ID to use in place of the DQRY transaction on this CA
Dataquery system.
Valid Entries:
Any 1- to 4-character TRANSID
Default Value:
DQRY
DSIEXIT=
Specifies the name of the Data Stream Input Exit, if any. Must be in CICS PPT and not the same as any CA Dataquery module.
Valid Entries:
1- to 8-character module name
Default Value:
(No default)
Chapter 7: Tailoring the CA Dataquery System Option Table 57
DQOPTLST Parameters
This parameter is no longer used by is kept for compatibility.
58 Administration Guide
DSOEXIT=
Specifies the name of the Data Stream Output Exit, if any. Must be in CICS PPT and must not be the same name as any CA Dataquery module.
Valid Entries:
1- to 8-character module name
Default Value:
(No default)
EPAGES=
This parameter is no longer used but is kept for compatibility.
ETMSO=
Specifies the number of minutes that may elapse between entries to the terminal. If the specified time is reached, CA Dataquery signs off the user the next time an entry is made at the terminal. Thus CA Dataquery prevents an unauthorized user from accessing data if the user who signed on leaves the terminal unattended for the specified length of time.
Valid Entries:
1—1440
Default Value:
1440
EXPDELM=
Specifies the name of the character to use as a delimiter in the batch export file. It is used as a delimiter between variables when the export function is used in batch
CA Dataquery. It is also used in all records: header, data, and trailer.
Valid Entries:
Any character except commas
Default Value:
, (comma)
EXPDEV=
(z/VSE only) Specifies the device type used by batch CA Dataquery for export data sets. You can change it on the Batch Execute panel if your JCL supports the selected device type. The device type specified in this parameter is used for all deferred batch jobs.
Valid Entries:
DISK or TAPE
Default Value:
TAPE
DQOPTLST Parameters
FNDBLKS=
(Online only.) Specifies the total number of logical blocks on the DQF (Found Table) one user can allocate during processing of the FIND statement of a query. This limit ensures adequate space for all the users. When the limit is exceeded, CA Dataquery ends the search with one of two messages, either:
DQ472I - LIMIT EXCEEDED - FOUND NNNNNN, or
DQ478I - LIMIT EXCEEDED - NO ROWS FOUND.
These messages are also generated whenever the limits set in the MFTIME= or
SRCHLIM= parameter are exceeded. To find out if the message you receive has been generated by a FNDBLKS=, MFTIME=, or SRCHLIM= limit, either use a PF key from the Print Output panel, or view the Find Statistics panel by issuing the STATS command and check the FIND TERMINATED BECAUSE column for one of the following:
FNDBLKS: MAX WORK TABLE BLOCKS EXCEEDED
MFTIME: MAX ELAPSED TIME EXCEEDED
SRCHLIM: SITE I/O LIMIT (DQOPTLST.SRCHLIM) EXCEEDED
To estimate the total number of logical rows that can be stored per logical block, use the following formula:
ROWS = 760 / [ 6 + (n x 18) ] where x is the number of tables named in the query.
For example, if the user names one table in a query (no RELATED, SET, or SORT statements), then:
ROWS = 760 / [ 6 + (1 x 18) ] = 33
Thus, if the default value for FNDBLKS is used (10 logical blocks), up to 330 logical rows could be stored by a user with one execution of a FIND that names only one row type.
This parameter sets the system default. You can override this value for specified
Authorizing Users
(see page 207). If you override, consider
the extra blocks when you allocate space.
Valid Entries:
1—9999999
Default Value:
10
Chapter 7: Tailoring the CA Dataquery System Option Table 59
DQOPTLST Parameters
HDGSEP=
Specifies a separator character to be used to separate line one and line two of a two-line column heading for a column or key when it is specified in the text of a query. If a single character is used for CMTBEG= and/or CMTEND=, the same character should not be used for HDGSEP=.
See the CA Dataquery User Guide or CA Dataquery Reference Guide for more information about specifying column headings.
Valid Entries:
Single character
Do not use:
■
The letters A through Z
■
■
The integers 0 through 9
A period (.), a comma (,), or a single quote mark (')
Default Value:
/ (a slash)
HDGSUB=
Specifies two characters that indicate to CA Dataquery that it should substitute the value of the control break column of a DO statement for the two characters. If two characters are used for CMTBEG= or CMTEND=, the same two characters should not be used for HDGSUB=. If a single character is used for CMTBEG= or CMTEND=, that character should not be used in HDGSUB=.
See the CA Dataquery User Guide or CA Dataquery Reference Guide for more information about the DO statement.
Valid Entries:
Two characters
Do not use:
■
The letters A through Z
■
■
The integers 0 through 9
A period (.), a comma (,), or a single quote mark (')
Default Value:
&& (two ampersands)
60 Administration Guide
DQOPTLST Parameters
KANJISI=
Specifies the hex value of the code which causes the terminal to shift into double byte character mode.
Valid Entries:
0F
Default Value:
(No default)
Note: These values are supplied by the CA Datacom/DB MUF, overlaying what is specified here.
KANJISO=
Specifies the hex value of the code which causes the terminal to shift out of double byte character mode.
Valid Entries:
0E
Default Value:
(No default)
Note: These values are supplied by the CA Datacom/DB MUF, overlaying what is specified here.
LINPRTL=
Specifies the length of each line for the printing of a batch query. This parameter is equivalent to NETPRTC= for a network printer.
Valid Entries:
80—150
Default Value:
133
LINPRTP=
Specifies the number of lines per page for the printing of a batch query. This parameter is equivalent to NETPRTP= for a network printer.
Valid Entries:
24 or greater
Default Value:
66
Chapter 7: Tailoring the CA Dataquery System Option Table 61
DQOPTLST Parameters
LITMASK=
Specifies a literal masking character to be used in literals in the WITH clause of a
FIND statement to indicate positions for which any value is acceptable. The value must not be the same as any part of the values assigned to CMTBEG= and
CMTEND= and must be unique among DIAFILL=, DIASYMB=, HDGSEP=, and
HDGSUB=.
See the CA Dataquery User Guide or CA Dataquery Reference Guide for more information about using masking characters in the WITH clause.
Valid Entries:
Single character
Do not use:
■
■
■
The letters A through Z
The integers 0 through 9
A period (.), a comma (,), or a single quote mark (')
■
An arithmetic operator (= - + / *)
Default Value:
# (pound sign)
MAXIO=
Specifies a maximum limit for I/O for DQL queries. If CA Dataquery estimates that a
DQL query will exceed this I/O limit, it issues a warning message and allows the user to choose to continue with the query or to cancel it.
Valid Entries:
0—9999999
Default Value:
9999999
62 Administration Guide
DQOPTLST Parameters
MFTIME=
(Online only.) Specifies the maximum number of seconds allowed to elapse during the execution of a FIND statement. If the specified time is exceeded, CA Dataquery ends the search with one of two messages, either:
DQ472I - LIMIT EXCEEDED - FOUND NNNNNN, or
DQ478I - LIMIT EXCEEDED - NO ROWS FOUND.
These messages are also generated whenever the limits set in the FNDBLKS= or
SRCHLIM= parameter are exceeded. To find out if the message you receive has been generated by a FNDBLKS=, MFTIME=, or SRCHLIM= limit, either use a PF key from the Print Output panel, or view the Find Statistics panel by issuing the STATS command and check the FIND TERMINATED BECAUSE column for one of the following:
FNDBLKS: MAX WORK TABLE BLOCKS EXCEEDED
MFTIME: MAX ELAPSED TIME EXCEEDED
SRCHLIM: SITE I/O LIMIT (DQOPTLST.SRCHLIM) EXCEEDED
Specifying a zero means that you want no limit placed on how long a FIND can take.
Valid Entries:
0—999999999
Default Value:
0
MXREQ=
(Online only.) Specifies the number of CA Datacom/DB I/O events CA Dataquery is to allow during a query execution before it relinquishes control of the resources in use and reschedules the remainder of the task. CA Dataquery then issues a message
"Still in progress." This feature keeps one query from monopolizing the CICS system.
MXREQ works with the MXTLR parameter to set the length of time CA Dataquery is to process before pausing to allow the user to end the query.
This parameter sets the system default. You can override this value for specified
Authorizing Users
Valid Entries:
1—9999
Default Value:
100
Chapter 7: Tailoring the CA Dataquery System Option Table 63
DQOPTLST Parameters
MXSETS=
Specifies the total number of KEEP or EXTRACT row collections a user can save in the DQF (Found Table) at any given time. MXSETS, FNDBLKS and XTRBLKS control the space requirements for the DQF.
Valid Entries:
1—999
Default Value:
5
MXTLR=
(Online only.) Specifies the number of times CA Dataquery is to relinquish control to other tasks during a query execution before pausing to allow the user to end processing. When the value is reached CA Dataquery displays the message "Do you want to continue?" See the discussion of MXREQ for details.
This parameter sets the system default. You can override this value for specified
Authorizing Users
Valid Entries:
1—9999
Default Value:
10
NETPRT=
Specifies the default network printer ID used as the destination of a query output. It can be overridden on a per user basis using the PROFILE command in online CA
Dataquery or through the Online Execution panel.
Valid Entries:
4-character CICS terminal ID of a printer
Default Value:
(No default)
NETPRTC=
Specifies the number of columns per line for print routed to an online network printer. To override the value for a specific user, use the PROFILE command in online CA Dataquery and change the specification for PRINT NUMBER OF
COLUMNS.
Valid Entries:
80—255
Default Value:
80
64 Administration Guide
DQOPTLST Parameters
NETPRTP=
Specifies the lines per page of the network printers. To override the value for a specific user, use the PROFILE command in online CA Dataquery and change the specification for PRINT NUMBER OF ROWS.
Valid Entries:
12—255
Default Value:
66
NEWPASS=
Specifies that users are allowed to change passwords on the Signon panel. If NO is specified, only an Administrator with User Maintenance authorization can change user passwords.
Valid Entries:
NO or YES
Default Value:
YES
OPNDURT=
Specifies whether to open dynamically-built User Requirements Tables for update
(U) or read-only (R) or not at all (N).
Valid Entries:
N, R, or U
Default Value:
U
OPSYS=
Specifies the operating system.
Valid Entries for z/OS:
OS
Valid Entries for z/VSE:
DOS
Chapter 7: Tailoring the CA Dataquery System Option Table 65
DQOPTLST Parameters
OUTXITO=
Specifies the name of the Online Output exit to be called as output rows are read.
Valid Entries:
1- to 8-character module name
Default Value:
(No default)
OUTXITB=
Specifies the name of the Batch Output exit to be called as output rows are read.
Valid Entries:
1- to 8-character module name
Default Value:
(No default)
PDBAREA=
Specifies the name of an existing database area to use for personal tables. The value may be overridden for each user. This area is used when using DATACOM extensions to SQL.
Valid Entries:
Name of an existing area
Default Value:
CA Datacom/DB default area if no area named
PRECISN=
Specifies the precision to use on a SET statement in DQL Mode when precision is not specified.
Valid Entries:
(I,D) Where I is the number of integer digits left of the decimal point and D is the number of decimal digits right of the decimal point and I + D is less than or equal to 18.
Default Value:
(10,5)
66 Administration Guide
DQOPTLST Parameters
PRTCTL=
Specifies the maximum number of pages of report output a user can send to a 3284 or 3286 printer for any given query.
Valid Entries:
1—999
Default Value:
10
QPAGES=
Specifies the maximum number of 24-line query pages that a query can occupy.
Each page beyond 1 requires approximately 5K additional bytes of task related storage while the transaction is active, and 5K more of auxiliary temporary storage per session if the pages are actually used. If you are using the Guided Query
Creation Facility, specify a minimum of 2.
Valid Entries:
1—4
Default Value:
1
QRYGRPS=
Specifies whether you can partition the public query library at the group level. Code
YES to use group level access authorization partitioning of the query library.
Valid Entries:
NO or YES
Default Value:
NO
RCNTDQW=
Specifies number of times DQBATCH should retry getting a DQW partition when all are marked in use before going to end of job when none are available. DQBATCH waits 30 seconds between retries.
Valid Entries:
1—9999
Default Value:
5
Chapter 7: Tailoring the CA Dataquery System Option Table 67
DQOPTLST Parameters
RPTHEAD=
Specifies a character string, enclosed within apostrophes, that CA Dataquery is to use as the first heading line of all query reports printed on a 328x hardcopy printer or line printer. This heading is printed as the primary heading on every report produced. Use the TITLE1 clause of the PRINT statement to produce a second line, and the TITLE2 clause to produce a third line.
Valid Entries:
1—30 characters, enclosed within apostrophes
Default Value:
(No default)
RTIMDQE=
Specifies the number of seconds SQL Mode batch CA Dataquery is to wait before reusing a found set in the Work Table (DQE) which is marked as being "in use." Sets may be left marked "in use" after a system failure or batch CA Dataquery abend.
Valid Entries:
60—32000
Default Value:
14400
RTIMDQW=
Specifies the number of seconds batch CA Dataquery is to wait before reusing a partition of the Work Table (DQW) which is marked as being "in use." Partitions may be left marked "in use" after a system failure or batch CA Dataquery abend.
When CA Dataquery is unable to allocate a partition, the message "CA Dataquery
WAITING FOR RESOURCES" appears.
Valid Entries:
60—32000
Default Value:
7200
68 Administration Guide
DQOPTLST Parameters
RTRNMOD=
(CICS only.) Specifies the name of a user program that is to receive control through
CICS XCTL when CA Dataquery is signed off. The specified name must be in the CICS
PPT and must not be the same as any CA Dataquery module name. The value specified in this parameter overrides the RTRTRAN specification and the session level transaction ID.
Note: If you specify either RTRNMOD or RTRTRAN, CA Dataquery ignores any value you specify for the USRCMD parameter.
Valid Entries:
Any valid 1- to 8-character module name as described above
Default Value:
(No default)
RTRTRAN=
(CICS only.) Specifies the CICS transaction ID to be initiated through CICS interval control initiate when CA Dataquery is signed off. The value specified in this parameter can be overridden by using RTRNMOD or the session level return transaction ID. RTRTRAN use is preferred over RTRNMOD use.
Note: If you specify either RTRNMOD or RTRTRAN, CA Dataquery ignores any value you specify for the USRCMD parameter.
Valid Entries:
Any 4-character transaction ID
Default Value:
(No default)
SECINF=
Specifies if CA Dataquery should use the External Security Interface to get user IDs from CA ACF2, CA Top Secret, or IBM's RACF. If SECINF=YES when executing in CA
Dataquery batch SIGN/ON mode, you can eliminate the signon card from batch executions. You must also specify the necessary external iecurity resources and privileges. For more information about implementing external security, see the CA
Datacom Security Reference Guide.
Valid Entries:
NO or YES
Default Value:
NO
Chapter 7: Tailoring the CA Dataquery System Option Table 69
DQOPTLST Parameters
SEQBUFS=
Specifies the number of batch sequential data buffers that can be used to speed the processing of some queries in batch by allowing the use of the CA Datacom/DB
GETIT and GSETL commands. CA Dataquery decides to use GETIT and GSETL based on input from the Compound Boolean Selection Facility.
Valid Entries:
2—32
Default Value:
2
SONEXIT=
Specifies the online Signon/off Exit module name. The specified name must be in the CICS PPT and must not be the same as any CA Dataquery module name. See
Sign-on/off Exit
(see page 469) for information.
Valid Entries:
1- to 8-character module name
Default Value:
(No default)
SORTCTG=
Specifies, in 4096-byte increments, the maximum contiguous storage area for in-memory sorting which CA Dataquery will request of CICS at one time. If this amount is not available when needed, CA Dataquery tries to allocate a number of smaller areas for the sort.
This parameter sets the system default. You can override the value for specific
Authorizing Users
Valid Entries:
1—16
Default Value:
16
70 Administration Guide
DQOPTLST Parameters
SORTPAG=
Specifies, in 4096-byte increments, the maximum amount of storage CA Dataquery will allocate to process a single sort request. If a request is too large to be sorted in this amount, or if the storage is unavailable in the monitor, then the CA
Datacom/DB Index sort is used.
This parameter sets the system default. You can override this value for specific
Authorizing Users
Valid Entries:
1—1024
Default Value:
64
SORTSYS=
Specifies, in 4096-byte increments, the maximum amount of storage CA Dataquery allocates to process all concurrent sorts combined system wide.
Valid Entries:
1—2048
Default Value:
64
SORTWK=
(z/VSE only) Specifies the number of disk sort work files to be used for batch system sort. Batch JCL should reflect the value specified.
Valid Entries:
0—8
Default Value:
3
SQLPRTY=
Specifies the priority for SQL requests processed by MUF. One is the lowest priority and 15 is the highest.
Valid Entries:
1—15
Default Value:
7
Chapter 7: Tailoring the CA Dataquery System Option Table 71
DQOPTLST Parameters
SRCHLIM=
Specifies the maximum number of CA Datacom/DB physical I/O events CA
Dataquery is to issue to perform the FIND statement of any one query. The value should be small enough to prohibit full table searches and expensive queries. Code it large enough to allow users to issue queries of reasonable size. The limit is specified in terms of I/O events, not CA Datacom/DB requests. This parameter is ignored by batch CA Dataquery.
If the limit you specify is exceeded, CA Dataquery ends the search with one of two messages, either:
DQ472I - LIMIT EXCEEDED - FOUND NNNNNN, or
DQ478I - LIMIT EXCEEDED - NO ROWS FOUND.
These messages are also generated whenever the limits set in the FNDBLKS= or
MFTIME= parameters are exceeded. To find out if the message you receive has been generated by a FNDBLKS=, MFTIME=, or SRCHLIM= limit, either use a PF key from the Print Output panel, or view the Find Statistics panel by issuing the STATS command and check the FIND TERMINATED BECAUSE field for one of the following:
FNDBLKS: MAX WORK TABLE BLOCKS EXCEEDED
MFTIME: MAX ELAPSED TIME EXCEEDED
SRCHLIM: SITE I/O LIMIT (DQOPTLST.SRCHLIM) EXCEEDED
Specifying a zero means that you want no limit placed on the number of I/O events.
Valid Entries:
0—99999999
Default Value:
9999999
SUBEXIT=
(Online only.) Specifies the name of the batch submit JCL exit module. The module name must be in the CICS PPT and must not be the same as any CA Dataquery module name.
Valid Entries:
1- to 8-character module name
Default Value:
(No default)
72 Administration Guide
DQOPTLST Parameters
SXBEXIT=
Specifies the name of a batch Signon/off Exit module. The module name must not be the same as any CA Dataquery module name.
Valid Entries:
1- to 8-character module name
Default Value:
(No default)
SYSDIAL=
(Valid only for sites that use the Language Maintenance Facility.) Specifies the
2-character language code for the language you have chosen as the PRIMARY language (that is, the language translation that is searched first).
This parameter sets the system default. You can override the value for specific
Authorizing Users
Valid Entries:
2-character language code previously defined in the Language Maintenance
Facility
Default Value:
(No default. Note: Some panels show AE.)
SYSLANG=
(Valid only for sites that use the Language Maintenance Facility.) Specifies the
2-character language code for the language you have chosen as the SECONDARY language (that is, the language translation that is searched second).
This parameter sets the system default. You can override the value for specific
Authorizing Users
Valid Entries:
2-character language code previously defined in the Language Maintenance
Facility
Default Value:
(No default.
Note: Some panels show AE.)
Chapter 7: Tailoring the CA Dataquery System Option Table 73
DQOPTLST Parameters
74 Administration Guide
TIMEFMT=
Specifies the format to use to print columns in DQL Mode and SQL Mode which are defined as SQL time types.
Valid Entries:
USA - hh:mm am (or pm)
ISO - hh.mm.ss
EUR - hh.mm.ss
JIS - hh:mm:ss
Default Value:
USA
TINIT=
Specifies whether CA Dataquery can be initiated from a terminal. If YES is specified,
CA Dataquery can be initiated by entering DQRY at a terminal. If NO is specified, CA
Dataquery can only be initiated from a program. For information about initiating CA
Initiating and Terminating CA Dataquery
page 121).
Valid Entries:
NO or YES
Default Value:
YES
TITLWC=
Specifies how you want report titles centered. If YES is specified, report titles are centered over the width of the presented data. If NO is specified, report titles are centered over the width of the device.
Valid Entries:
NO or YES
Default Value:
NO
UDFMOD=
Specifies whether a User-Defined Functions exit is to be used. If you specify a name, ensure that a user-written exit is provided. The specified name must be in the CICS
PPT and must not be the same as any CA Dataquery module name. For more
User-Defined Functions Exit
Valid Entries:
1- to 8-character module name
Default Value:
(No default)
DQOPTLST Parameters
URTPRTY=
Specifies the priority for requests processed by the batch program after the User
Requirements Table is opened. 1 is the lowest priority; 15 is the highest. CA
Dataquery dynamically builds batch User Requirements Tables. For more information, see Defining the CA Dataquery User Requirements Tables.
Valid Entries:
1—15
Default Value:
7
USRCMD=
Specifies the names of up to ten transactions which CA Dataquery recognizes as valid CA Dataquery commands. When one of these is entered as a CA Dataquery command, CA Dataquery initiates the transaction.
Note: If you specify either RTRNMOD or RTRTRAN, CA Dataquery ignores any value you specify for the USRCMD parameter.
Valid Entries:
(xxxx,xxxx,...) where xxxx is a 1- to 4-character transaction ID. Can be repeated up to ten times.
Default Value:
(No default)
VALEXIT=
Specifies whether a Query Validation exit is to be used. If you code a name, ensure that a user-written exit is provided. The specified name must be in the CICS PPT and must not be the ame as any CA Dataquery module name. For information about
writing a Query Validation exit, see
Query Validation Exit
Valid Entries:
1- to 8-character module name
Default Value:
(No default)
Chapter 7: Tailoring the CA Dataquery System Option Table 75
DQOPTLST Parameters
XTRBLKS=
Specifies the amount of space on the DQF (Found Table) that a single EXTRACT request can allocate at one time. This limit prevents one user from using excessive table space. If the limit is exceeded, CA Dataquery terminates the EXTRACT command and releases the assigned space. The value coded is in logical blocks; the number of logical rows that can be extracted at one time depends on the length of the logical row. For an estimate, divide 760 by the logical row length (total length of all columns and keys named by the average PRINT or DISPLAY).
Valid Entries:
1—9999
Default Value:
20
XTRSETL=
Specifies the length of a SET result in EXTRACT output. If 8 is specified and the SET result is greater than 15 digits in length, the value extracted will be zero (0). If 16 is used, all SET result values will be extracted as packed decimal length 16. If 8 is used, all SET result values will be extracted as packed decimal length 8. Setting the value to zero and continuing to process the rest of the output permits the program to continue. No other error message or error return code is set.
Valid Entries:
8 or 16
Default Value:
8
More information:
Changing the Bulletin Board
Translating CA Dataquery
Language Maintenance Facility Overview
Editing the Translated Version of CA Dataquery
Customizing the American English Version
Deleting Unneeded Panels, Literals, and Vocabulary
76 Administration Guide
Example DQOPTLST Assemblies
Example DQOPTLST Assemblies
Sample CICS Assembly in z/OS
DQOPTLST OPSYS=OS, X
ETMSO=20, X
DDDBID=2, X
DQDBID=3, X
MXREQ=100, X
MXTLR=10, X
BUFSIZE=4600, X
LINPRTP=55, X
QRYGRPS=NO, X
QPAGES=3
END
Sample CICS Assembly in z/VSE
DQOPTLST OPSYS=DOS, X
ETMSO=20, X
SORTWK=3, X
DDDBID=2, X
DQDBID=3, X
MXREQ=100, X
MXTLR=10, X
BUFSIZE=4600, X
LINPRTP=55, X
QRYGRPS=NO, X
QPAGES=3
END
Chapter 7: Tailoring the CA Dataquery System Option Table 77
Chapter 8: Preparing and Maintaining the
CA Dataquery System Tables
Following is a list of the tables which must be present in CA Datacom/DB to run CA
Dataquery with the SQL option installed.
Note: See important information in Logging, Recovery, and URI and Recovery.
DQE
Serves as an SQL Found Table containing the rows of data returned by a SQL query.
DQF
CA Dataquery Found Table - Stores the results of a query or found set. The found set that results from a query remains active until another query is executed or the user signs off. This table also contains saved sets which are pointer information to the original data in the queried database table when the KEEP command is used for
DQL Language queries. When the EXTRACT command is used, the actual data values for the columns specified in the query are saved in a special Extract Set on the CA
Dataquery Found Table (DQF). The Found Table is also used by the Deferred Batch and Print Offline functions of CA Dataquery.
DQM
CA Dataquery Literals Table - Stores literal values that are output by the CA
Dataquery system. These literal values are keywords and phrases that are commonly used by the CA Dataquery system. Storing them on this table facilitates their translation to other languages by the CA Dataquery Language Maintenance
Facility.
DQP
CA Dataquery Panel Table - Stores the image of the panels that collectively comprise the CA Dataquery External Online Interface. Storing panel images on this table facilitates their translation into other languages by the CA Dataquery
Language Maintenance Facility. Any translated versions are also stored on this table.
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 79
Example DQOPTLST Assemblies
DQQ
DQR
CA Dataquery Query Library - Primarily stores query text members, JCL members,
PROCs, terms, condition, and restriction definitions.
DQS
Functions as a Recovery Table containing one row for each Found Set in the DQE. It also contains some record keeping data, such as who created the Found Set, when it was created, and so on.
CA Dataquery Spool Table - Stores and controls the hardcopy report output of a query that has been routed to an online network printer.
DQU
CA Dataquery User Table - Stores the definitions of valid CA Dataquery users. This table contains user attributes such as name, password, language, system options and function authorizations. This information is used to validate a user attempting to sign on to the CA Dataquery system.
DQV
CA Dataquery Vocabulary Table - Stores Language and Command keywords that a
CA Dataquery user would enter into the system. Storing these keywords on this table facilitates their translation into other languages by the CA Dataquery
Language Maintenance Facility.
DQW
CA Dataquery Work Table - Performs as the batch equivalent of the DQF table. The
Work Table stores and manages found sets that result from batch queries. This table is segmented into partitions to allow the concurrent execution of several batch queries. (The KEEP and EXTRACT commands are not available in batch CA
Dataquery, so no saved or Extracted sets are present on the CA Dataquery Work
Table.)
If SQL is not installed, the DQE and DQR tables are not needed.
80 Administration Guide
Calculating Sizes for System Tables
Table Sizes
The size of each of these tables is site-specific. The ten tables are provided with the installation of CA Dataquery. Each table is in its own CA Datacom/DB area except DQM,
DQP, and DQV which share the DQM area. You must determine if the tables are large enough as provided and if not, you must regenerate the tables to meet the needs of your environment.
Logging, Recovery, and URI
Do not specify logging for any of the CA Dataquery system tables except the DQQ
(Query Library Table) and DQU (User Table). Installing or upgrading specifies logging on for these tables.
Recovery
The recovery attribute (RECOVERY) is set to yes (Y) for all CA Dataquery system tables to allow URI support to be implemented. Do not change this specification.
Calculating Sizes for System Tables
Allocate sufficient space for the CA Dataquery tables. The size of some of the CA
Dataquery tables is site-specific and impacts the efficiency of CA Dataquery. You must determine the amount of space your site requires for these tables. This section provides information about calculating optimum table sizes for the CA Dataquery system tables.
The sizes are based on the 3380 device type.
Tables with Set Allocations
Use the following guidelines:
DQM - Literals Table
(DQM area) Allocate 60 tracks to allow space for some translation.
DQP - Panel Table
(DQM area) Allocate 60 tracks to allow space for some translation.
DQQ - Query Library Table
Allocate a minimum of 20 tracks.
DQR - SQL Recovery Table
Allocate 10 tracks.
DQS - Spool Table
An allocation of 10 tracks is usually sufficient for the Spool Table (DQS).
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 81
Maintaining the CA Dataquery System Tables
DQU - User Table
Allocate a minimum of 20 tracks.
DQV - Vocabulary Table
(DQM area) Allocate 60 tracks to allow space for some translation.
The allocations for the DQE, DQF, and DQW are site-specific. Instructions for estimating the appropriate allocation for your site follow the description of each of these tables later in this chapter.
Maintaining the CA Dataquery System Tables
The physical aspects of CA Dataquery are maintained by the CA Datacom/DB database management system. The CA Dataquery database consists of rows on a CA Datacom/DB
Directory (CXX), an index, and twelve tables. Maintenance of the CA Dataquery database is no different from maintenance of any other CA Datacom/DB database, but there are specifications regarding recovery, which are documented in this guide. See the
CA Datacom/DB Database and System Administration Guide and the CA Datacom/DB
DBUTLTY Reference Guide for details about system tasks, including:
■
Maintaining the CA Datacom/DB Directory (CXX)— backing up and restoring the
Directory containing the definitions of the CA Dataquery tables. You can also print a report of those definitions.
■
Unloading tables— unloading an individual CA Dataquery table (for example, as a backup or for subsequent reloading).
■
Loading tables— loading a particular CA Dataquery area and restoring a backup copy of a table.
■
Maintaining the index— initializing, rebuilding, and reporting on the index.
■
Retrieving tables— restoring a table if the database index has been destroyed and reloading it.
■
Backing up tables— CA Dataquery tables should be included in normal site backup procedures. Regular backup for the DQQ and DQU tables is especially important since these tables contain data that is not easily re-created in case of a system
malfunction. For more information, see
Scheduling System Table Backups
page 105).
82 Administration Guide
DQE: SQL Found Table
CA Dataquery Utilities
CA Dataquery provides the following batch utilities to maintain its tables.
■
The Language Maintenance Utility, DQLANGMT, is used to backup and restore the
DQM, DQP, and DQV tables.
■
The Query Library Table Maintenance Utility, DQLIBRMT, is used to maintain the
DQQ table:
–
Delete all or selected members for selected users or groups
–
Backup queries, dialogs, terms, JCL and PROC members
–
–
–
Restore all or selected members to the DQQ from tape or disk
Print maintenance reports
Add members
■
The Found Table Maintenance Utility, DQWFINIT, used to initialize the DQE, DQF, and DQW tables.
DQE: SQL Found Table
The DQE provides space for storing the rows retrieved by SQL queries. Pointers to these rows are kept in a found set on the DQF table like a DQL query.
Description
The default block size for the DQE is 4096 (record size 4082). This means the maximum row length for a row retrieved by an SQL query is 4030, because of the header, pointer, and length fields used in the block by CA Dataquery.
Preparing the DQE
To prepare the DQE:
1. Allocate space (see instructions for calculating size, below).
2. Initialize space using DBUTLTY.
3. Null load using DBUTLTY.
4. Run DQWFINIT with a control statement to format DQE.
Note: At installation, the DQE block size for DQE defaults to 4096. The block size of the
DQE can be changed using standard procedures in CA Datacom Datadictionary for changing the definition of a table and cataloging. See the CA Datacom Datadictionary documentation or the CA Datacom Datadictionary Administrator for assistance. After changing the definition of the DQE and cataloging it, it must be reallocated and reinitialized as above. Also, the DQESIZE parameter on the System Option Table must be changed to reflect the new record size (block size minus 14) and reassembled.
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 83
DQE: SQL Found Table
Calculating the Allocation for DQE
For SQL queries, determine:
■
AVG-ROW-LEN selected = A
■
AVG-ROW-COUNT = R
■
USER-COUNT = U
Step 1:
Calculate the number of rows per block.
4096/A (round down)
Step 2:
Calculate the number of blocks per user.
R/(result of Step 1)
Step 3:
Calculate the total blocks.
(result of Step 2) x U
Step 4:
Multiply the result of step 3 by two.
(result of Step 3) x 2
Step 5:
This gives the number of physical 4096-byte blocks. Use the result of Step 4 to calculate the tracks or blocks for your device type.
■
For Count Key Data devices:
(number of tracks) = (outcome of Step 4)/b
■ where b = number of 4096-byte rows that will fit on a track on the device used to hold the table.
For FBA devices:
(number of FBA blocks) = (outcome of Step 4) x 8
Note: You multiply by 8 because it is the minimum number of 512-byte blocks needed to accommodate the 4096-byte row size of the DQE.
84 Administration Guide
DQF: Found Table
Maintaining the DQE
No backup of the DQE is required since no sets are kept or extracted in SQL Mode. CA
Dataquery uses the DQE as work space during SQL Mode query execution.
SYNCHRONIZE. When you null load and initialize the DQE, you must also null load and initialize the DQF, DQR, and DQS to maintain synchronization. Failure to synchronize these tables can result in failure to reclaim DQE space.
Recovering the DQE
If the DQE is lost due to catastrophe:
■
Allocate the table.
■
Initialize the table using DBUTLTY.
■
Null load the table using DBUTLTY.
■
Run the DQWFINIT utility to format the DQE.
DQF: Found Table
The CA Dataquery Found Table is used to store the results of a query. It can contain:
■
Found sets - which consist of pointer information to the original data in the queried database when the FIND command is used
■
Saved sets - which consist of pointer information to the original data in the queried database when the KEEP command is used
■
Extract sets - which consist of the actual values for the columns specified in the query.
■
■
Temporary sets used for offline print and network print - which consist of a copy of the request table, a copy of the found set, and optionally, the find statistics or the query text
The deferred batch queue - which consists of entries for each deferred batch request
CA Dataquery writes the pointers to the data or the data that result from a request to the DQF after the request is processed. The DQF is read to report on the stored results.
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 85
DQF: Found Table
Description
The logical row length of the DQF (Found Table) is 772 bytes long. The default block size is 4096 bytes. Each physical block holds five logical blocks, which are used as an intermediate area for holding the logical rows selected during a query execution.
The DQF (Found Table) is one physical database table, but because of its row structure it appears as multiple logical tables. Subsets of the DQF table are dynamically assigned to individual tasks when needed and later released back to the system. When row collection sets are saved with the KEEP and EXTRACT commands, entries that provide specific information about the sets are placed in the DQF table directory.
Preparing the DQF
To prepare the DQF:
1. Determine the space needed.
The actual number of logical rows that can belong to a row collection at one time during selection varies per query. The number of RELATED clauses and SET statements and the length of a SORT key are factors.
Since the logical row length is variable, you cannot always tell exactly how many can be contained in a physical block. For instructions on estimating the appropriate
DQF allocation for your site, see
DQF: Found Table
2. Allocate the space.
3. Initialize the space using the DBUTLTY INIT Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
4. Null load both the DQF and the DQS using the DBUTLTY LOAD Data Area function.
See the CA Datacom/DB DBUTLTY Reference Guide for details.
5. Run the DQWFINIT utility. For information about executing DQWFINIT, see
Initializing the DQE, DQF, and DQW (DQWFINIT)
SYNCHRONIZE. When you null load and initialize the DQF, you must also null load and initialize the DQE, DQR, and DQS to maintain synchronization. (Omit the DQR and DQE tables if the SQL option is not installed.) Failure to synchronize these tables can result in failure to reclaim DQF space.
Executing DQWFINIT completely reinitializes the table and destroys any KEEP or
EXTRACT row collections currently on the table. Queued network print requests are all lost. Unprocessed deferred batch jobs are lost.
86 Administration Guide
DQF: Found Table
Calculating the Allocation for DQF
The following parameters of the System Option Table limit allocations of space from
DQF.
FNDBLKS=
Sets a limit on the maximum space that can be allocated during execution of the
FIND steps of a query. You can override the value for FNDBLKS= for any individual by updating the FNDBLKS= parameter on panel DQUM0. The override value may be more or less than FNDBLKS=. If it is larger, consider the extra blocks when allocating table space.
MXSETS=
Limits the total number of KEEP or EXTRACT row collections an individual user can own at one time.
XTRBLKS=
Sets a limit on the maximum space that can be assigned to an EXTRACT row collection by a user.
The actual number of logical rows that can belong to a row collection at one time during selection varies per query. The number of RELATED clauses and SET statements and the length of a SORT key are factors.
Since the logical row length is variable, you cannot always tell exactly how many can be contained in a physical block. The following is provided as an aid in approximating the values.
First determine a value for each of the following:
LREC-LIMIT
Number of logical rows to be allowed in a row collection.
AVG-TABLES
Average number of tables to be related in a query (average number of RELATED clauses plus 1). For SQL queries, the AVG-TABLES is always 1.
AVG-SETS
Average number of SET statements in a query. For SQL queries, the AVG-SETS is always 0.
AVG-SORT
Average combined length of columns or keys named in a DQL Mode SORT statement. For SQL queries, the AVG-SORT is always the sum of the lengths of the columns in the ORDER BY statement.
NUM-USERS
Number of CA Dataquery users.
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 87
DQF: Found Table
For DQF calculations, you should count SQL queries too if your site has installed the SQL option. The average tables for an SQL query is always one (1). The average sets for an
SQL query is always zero (0). The average sort is the sum of the lengths of the columns in the ORDER BY statement.
Perform the following calculations next.
Step 1:
Find the average logical row length:
(average logical row length) = 6 + (18 x AVG-TABLES)
Step 2:
Calculate the number of logical rows per logical block:
(logical rows per block) = 760/n where n = average logical row length from Step 1.
Note: Round down the result of 760/n.
Step 3:
Determine the value for the DQOPTLST macro FNDBLKS= parameter:
(value of FNDBLKS= parameter) = LREC-LIMIT/y where y = the logical rows per logical block from Step 2.
Step 4:
Find the total logical row length:
(total logical row length) = n + (17 x AVG-SETS) + AVG-SORT where n = the average logical row length from Step 1.
Step 5:
Divide the result of Step 4 by the result of Step 1:
(total logical row length)/(average logical row length)
Step 6:
Find the number of logical blocks per user:
(number of blocks per user) = (z x FNDBLKS=) x 2 where z is the result of Step 5.
88 Administration Guide
DQF: Found Table
Step 7:
Find the minimum number of logical blocks required if KEEP and EXTRACT sets are not kept by doing this:
(number of blocks per user from Step 6) x NUM-USERS
Step 8:
Determine the minimum number of logical blocks required if KEEP or EXTRACT sets are allowed to be kept by doing this:
[(result of Step 7)/2] x w where w = the value you gave the MXSETS= parameter in the DQOPTLST macro.
Step 9:
Find the total logical blocks:
(total logical blocks) = (result of Step 7) + (result of Step 8)
Step 10:
Calculate the number of physical blocks:
(number of physical blocks) = (result of Step 9)/5
Step 11:
Use the result of Step 10 to calculate the tracks or blocks for your device type.
■
For Count Key Data devices:
(number of tracks) = (outcome of Step 10)/b
■ where b = number of 4096-byte rows that will fit on a track on the device used to hold the table.
For FBA devices:
(number of FBA blocks) = (outcome of Step 10) x 8
Note: You multiply by 8 because it is the minimum number of 512-byte blocks needed to accommodate the 4096-byte row size of the DQF.
Enlarging the DQF
To enlarge your DQF, perform the following steps:
1. After increasing the size of the DQF, INIT and null load it with DBUTLTY.
2. INIT and null load the DQS table, and if the SQL option is installed, INIT and null load the DQE and DQR tables.
3. Format the DQF table with the DQWFINIT utility.
4. If the SQL option is installed, format the DQE table with the DQWFINIT utility.
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 89
DQF: Found Table
Recovering the DQF
If the DQF is lost due to catastrophe:
■
Allocate the table.
■
Initialize the DQF and DQS tables (and also the DQE and DQR tables if SQL is installed) using DBUTLTY.
■
Null load the DQF and DQS (and DQE and DQR if SQL is installed) using DBUTLTY.
■
Run the DQWFINIT utility to format the DQF (and DQE) tables.
Maintaining the DQF
CA Dataquery indicates that the DQF needs to be enlarged by the frequent display of the error message DQ026I at one or more CA Dataquery terminals. DQ026E specifies that work space was not available to complete the requested function.
In DBUTLTY Directory (CXX) reports, the DQW always shows 99 percent full after
DQWFINIT has been run. A lack of available work space on the DQW is indicated by error messages. The percent full value on the report for the DQF and the DQE shows the maximum used at one time (a "high-water mark"). Space that has been used and freed shows on the report as being in use.
Backing Up the DQF
No backup of the DQF is required.
Restoring the DQF
The DQF cannot be restored from a backup. It must be reinitialized. See the information above on recovering the DQF.
90 Administration Guide
DQM Area
DQM Area
The DQM area consists of the following CA Dataquery system tables:
DQM (Literals Table)
Is used to store literal values that are output by the CA Dataquery system. These literal values are keywords and phrases that are commonly used by the CA
Dataquery system. Storing them on this table facilitates their translation to other languages by the CA Dataquery Language Maintenance Facility.
DQP (Panel Table)
Is used to store the panel images that collectively comprise the CA Dataquery
External Online Interface. Storing panel images on this table facilitates their translation into other languages by the CA Dataquery Language Maintenance
Facility. Any translated versions are also stored on this table. CA Dataquery provides a utility for printing all CA Dataquery panels, called DQPANPRT. Instructions for using this utility appear in the CA Dataquery Administrator Guide.
DQV (Vocabulary Table)
Is used to store Language and Command keywords that a CA Dataquery user would enter into the system. Storing these keywords on this table facilitates their translation into other languages by the CA Dataquery Language Maintenance
Facility.
The DQM tables are accessed when CA Dataquery is to display data on the terminal and when data is supplied to CA Dataquery by the user.
Description
The DQM area consists of a group of physical blocks that vary in size depending on the device type. The logical row length of the DQM table is 92 bytes, the DQP table is 2008 bytes, the DQV table is 92 bytes. The default block size for the DQM area is 4096 bytes.
You can modify these as needed.
Translation Concerns
During installation, the DQM area is loaded with American English text. If your site plans to translate or customize the entire CA Dataquery system, you need to allocate additional disk space to store the newly created language. For a complete translation you need 20 tracks on a 3380 disk or in CA Datacom/DB terms, you need 220 blocks of
3584 bytes.
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 91
DQM Area
Enlarging the DQM Area
To enlarge the area:
1. Backup the area using the Language Maintenance Utility (DQLANGMT). See
Loading and Unloading Languages (DQLANGMT)
2. Allocate the disk space.
3. Initialize the space using the DBUTLTY INIT Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
4. Null load the DQM using the DBUTLTY LOAD Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
5. Restore the language from the backup using DQLANGMT.
Recovering the DQM
If the DQM area is lost due to system catastrophe:
■
If you have done no translation:
–
Load the area from the CA tape following the instructions in the CA Datacom installation documentation.
–
OR, if backed up using DBUTLTY, load the area from your backup using the
DBUTLTY LOAD Data Area function. See the CA Datacom/DB DBUTLTY
Reference Guide for details.
■
If you have done translation, load the area from your backup using the DBUTLTY
LOAD Data Area function (if backed up by DBUTLTY). See the CA Datacom/DB
DBUTLTY Reference Guide for details. Or, execute the Language Maintenance Utility
JCL with RUNTYPE=LOAD, if backed up with Language Maintenance.
If you have made no backup of the area:
–
Load the area from the CA tape following the instructions in the CA Datacom installation documentation.
–
Retranslate using the Language Maintenance Utility. See the CA Dataquery
Administrator.
92 Administration Guide
DQQ: Query Library Table
Backing Up the DQM
The DQM area needs backing up at System Generation time and subsequently if it is changed. To backup the DQM: execute the Language Maintenance Utility JCL with
RUNTYPE=UNLOAD. The Language Maintenance Utility also allows you to do a selective backup (unload). To backup (unload) either a language you have created or a CA provided language, replace the RUNTYPE=UNLOAD line of the JCL with RUNTYPE=
UNLOAD,LANGUAGE=lc where lc is the language you want to unload. Or, use the
DBUTLTY backup data area function.
Restoring the DQM
To restore backup tables, execute the Language Maintenance Utility JCL with
RUNTYPE=LOAD. You cannot do a selective restore. Or, use the DBUTLTY load data area function, if backed up using DBUTLTY.
DQQ: Query Library Table
The DQQ (Query Library Table) is used to store query text members, JCL members,
PROCs, terms, condition and restriction definitions, and dialogs. The DQQ is accessed when you SAVE, UPDATE, or EDIT a query.
During installation, for new users, the DQQ is created with one sample query loaded in it.
Description
The logical row length of the DQQ is 2200 bytes long. The default block size is 4096 bytes. When allocating space for the DQQ, allow one physical block for each page of each query to be saved, one for each term, and one for each restricted condition row.
Allow some space for future growth.
Enlarging the DQQ
If you want to enlarge the table after installation:
1. Use the DBUTLTY BACKUP function to backup the table. For more information, see the CA Datacom/DB DBUTLTY Reference Guide.
2. Allocate the space.
3. Initialize the space using the DBUTLTY INIT Data Area function. For more information, see the CA Datacom/DB DBUTLTY Reference Guide.
4. Load the DQQ using the DBUTLTY LOAD Data Area function. For more information, see the CA Datacom/DB DBUTLTY Reference Guide.
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 93
DQR: SQL Recovery Table
Maintaining the DQQ
The content of the DQQ is maintained by the CA Dataquery Administrator using
DQLIBRMT. This utility is used to add, delete, backup, and restore members to maintain the content of the table but it is not intended for complete backups. Use DBUTLTY for standard table maintenance.
Backing Up the DQQ
The DQQ should be backed up on a daily basis. To backup the DQQ, use the DBUTLTY
BACKUP Data Area function.
Restoring the DQQ
To restore a backup, use the DBUTLTY LOAD Data Area function.
Recovering the DQQ
If the DQQ is lost due to system catastrophe, you must:
1. Reallocate the space.
2. Initialize the table using the DBUTLTY INIT Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
3. Load the backup using the DBUTLTY LOAD Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
DQR: SQL Recovery Table
This table is used to recover the SQL found sets in the DQE table. It also contains some record-keeping data such as, who created the SQL Found Set, when it was created, and so forth.
For recovery purposes, DQE sets are of three types:
■
Batch sets created for queries run in DQBATCH
■
Single use online sets
■
Multi-use online sets subsequently used for network or offline print
Normally, all are freed as soon as no longer needed, but in case of abends or system failures, they must be recovered.
At the start of DQBATCH, any sets older than the time specified by RTIMDQE= are freed.
At signon time online, when the operator owning the single and multi-user sets signs on, these are recovered when RTIMDQE= has expired.
94 Administration Guide
DQS: Spool Table
Preparing the DQR
To prepare the DQR:
■
Allocate ten tracks.
■
Initialize the area.
■
Null load the table.
SYNCHRONIZE. If the DQR is initialized, the DQE, DQF, and DQS must also be initialized.
If the SQL option is not installed, synchronize only the DQR and the DQF.
DQS: Spool Table
The DQS (Spool Table) is used to store and control the hardcopy report output of a query that has been routed to an online network printer. When a print is requested, the control information for the print is written to the DQS table. The DQF is read to obtain the data or the pointers to the data to be printed.
Enlarging the DQS
The installation process creates the DQS. The DQS row length is 230 bytes. The default block size is 4096 bytes. If you want to enlarge the table:
1. Allocate the space. Allocate one row for each pending network print request.
2. Initialize the space using the DBUTLTY INIT Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
3. Null load the DQS using the DBUTLTY LOAD Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
SYNCHRONIZE. The DQS must be synchronized with the DQF. If the DQS is initialized, the
DQE, DQF, and DQR must also be initialized. (Omit the DQE and DQR tables if the SQL option is not installed.)
Maintaining the DQS
The content of the table is maintained through the Printer Control Administrative function.
Backing Up and Restoring the DQS
It is not necessary to back and restore the DQS. Reinitializing the tables restores the
DQS.
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 95
DQU: User Table
Recovering the DQS
If the DQS is lost due to system catastrophe:
■
Reallocate the table.
■
Initialize the table using the DBUTLTY INIT Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
■
Null load the table using the DBUTLTY LOAD Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
If you must re-create the DQS after a catastrophe, you must also re-create the DQF,
DQE, and DQR so that the tables remain synchronous.
DQU: User Table
The DQU (User Table) stores the definitions of valid CA Dataquery users. It contains user attributes such as name, password, language, system options, and function authorizations. This information validates a user at signon and verifies function authorizations. The DQU is accessed when users are maintained and when users sign on.
The DQU can be queried.
Description
Each user requires a logical row of 350 bytes. The default block size is 4096 bytes. The maximum number of logical rows each physical block can contain is dependent upon whether or not compression is used and whether compression is effective. Give future growth due consideration when calculating space requirements.
During installation, for new users, the DQU is created with one user definition called
DATACOM-INSTALL.
Enlarging the DQU
If you want to enlarge the table after installation:
1. Use the DBUTLTY BACKUP function to backup the table. See the CA Datacom/DB
DBUTLTY Reference Guide for details.
2. Allocate the space.
3. Initialize the space using the DBUTLTY INIT Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
4. Load the DQU using the DBUTLTY LOAD Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
96 Administration Guide
DQU: User Table
Maintaining the DQU
The DQU content is maintained through the USER option of the CA Dataquery
Administrative Menu or the DQUSERMT utility. For details, see
Performing User Table
Maintenance (DQUSERMT).
Backing Up the DQU
The DQU should be backed up as changes occur. To backup the DQU, backup the table using the DBUTLTY BACKUP Data Area function. See the CA Datacom/DB DBUTLTY
Reference Guide for details.
Restoring the DQU
To restore the DQU, load the DQU backup using the DBUTLTY LOAD Data Area function.
See the CA Datacom/DB DBUTLTY Reference Guide.
SYNCHRONIZE. If you reload the DQU, you should then NULL load the DQF, DQS, DQR, and DQE tables and run DQWFINIT against the DQF and DQE tables. (Omit the DQE and
DQR tables if the SQL option is not installed.)
Recovering the DQU
If the DQU is lost due to system catastrophe:
If you have a backup:
■
Reallocate the table.
■
Initialize the table using the DBUTLTY INIT Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
■
Load the backup using the DBUTLTY LOAD Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
If you do not have a backup:
■
Reallocate the table.
■
Initialize the table using the DBUTLTY INIT Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
■
Run DQUSERMT with the input statement CREATE to add the user
DATACOM-INSTALL, then add other users.
SYNCHRONIZE. If you reload the DQU, you should then NULL load the DQF, DQS, DQR, and DQE tables and run DQWFINIT against the DQF and DQE tables. (Omit the DQE and
DQS tables if the SQL option is not installed.)
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 97
DQW: Work Table
DQW: Work Table
The DQW (Work Table) is the batch equivalent of the DQF. The DQW stores and manages found sets that result from batch queries. This table is segmented into partitions to allow the concurrent execution of several batch queries. (The KEEP and
EXTRACT commands are not available in batch CA Dataquery so no Saved or Extracted sets are present on the DQW.) The DQW is accessed to write the pointers to the data or the data resulting from a query to it. The DQW is read when you want to report on the results of a query.
Description
The logical row length of the DQW (Work Table) is 772 bytes long. The default block size is 4096 bytes. Each physical block holds four logical blocks, which are used as an intermediate area for holding the logical rows selected during a batch query execution.
The DQW (Work Table) is very similar to the DQF in structure and use. It provides CA
Dataquery batch jobs with space for the storage and manipulation of query results.
Subsets of the table are dynamically assigned to individual batch jobs as required and later released when the job is terminated.
Estimating the DQW Allocation
When estimating the minimum size for your DQW, consider the following:
■
The maximum number of CA Dataquery batch jobs which you wish to allow to run concurrently.
■
The approximate number of physical blocks in the DQW which are required to successfully execute your largest anticipated batch query.
The number of batch CA Dataquery jobs which can run simultaneously is limited to the number of operating system partitions or regions available for the CA Dataquery job class. You must specify this number in the DQW control statement when you execute
DQWFINIT. The DQW is divided into segments of which one is required for each batch query running at once.
98 Administration Guide
DQW: Work Table
Since the entire DQW is divided into segments, one per job, each job can only make use of the space in one segment. To determine the appropriate size for your DQW, you must first calculate the approximate number of physical blocks required per DQW segment for the successful execution of your largest anticipated query. To do this, perform the following calculations:
Step 1:
Find the Logical Record Length:
6 + (18 x AVG-FILES) = (Average Logical Record Length)
6 + (18 x ______________) = _________________________________
Step 2:
Calculate the number of logical records per block:
760 / n = (Logical Records per Block)
(where n = average logical record length from Step 1)
760 / _____________ = ___________________
Step 3:
Calculate the number of logical blocks needed to process a query with the largest number of logical records found.
(Logical Records Found) / (Number of Records per Logical Block)
___________________________ / ________________________ = ___________
Step 4:
Calculate the number of logical blocks needed to execute a query. (The factor of 8 allows for SET statements and SORT keys which are kept in the Found File.)
(Number Logical blocks) x 8 = (Logical Blocks for Execution)
___________________________ x 8 = ________________________
Step 5:
Calculate the number of logical blocks needed for the entire DQW. Multiply the results of Step 4 by the number of batch DQ jobs which you want to allow to run concurrently. (Number of DQ segments.)
(Results of Step 4) * (Number DQ Segments) = (Number Logical Blocks for DQW)
___________________________ x ________________________ = ____________
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 99
DQW: Work Table
Step 6:
Calculate the number of physical blocks needed for the entire DQW. Divide the results of Step 5 by 5 (which is the number of logical blocks, 760, in a physical block).
(Results of Step 5) / 5 = (Number Physical Blocks for DQW)
______________________ / 5 = _________________
Step 7:
Calculate the total number of tracks required by dividing the results of Step 6 by the number of blocks per track considering the block size of the DQW is 4096.
(Results of Step 6) / (Number Blocks per Track) = (Tracks Required)
_____________________ / ________________________ = _________________
(Example: The number of blocks per track on a 3380 is 10.)
Note: If batch CA Dataquery jobs terminate due to space limitations, re-evaluate the size of your DQW.
Maintaining the DQW
No extracts are ever kept on the DQW table. (Extract is an online function.) If problems arise with DQW, reinitialize and run the DQWFINIT to format. If the DQW is large, reinitializing may take a lot of resources. Consider backing up a freshly formatted DQW using DBUTLTY and in the event of corruption, use it instead of reinitializing.
In DBUTLTY Directory (CXX) reports, the DQW always shows 99 percent full after
DQWFINIT has been run. A lack of available work space on the DQW is indicated by error messages. The percent full value on the report for the DQF and the DQE shows the maximum used at one time (a "high-water mark"). Space that has been used and freed shows on the report as being in use.
100 Administration Guide
DQW: Work Table
Enlarging the DQW
If batch CA Dataquery jobs terminate due to space limitations, you should re-evaluate the size of your DQW.
To enlarge your DQW, perform the following procedure:
1. Initialize the space using the DBUTLTY INIT Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
2. Null load the DQW using the DBUTLTY LOAD Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
3. Initialize the DQW using the DQWFINIT utility. See Initializing the DQE, DQF, and
DQW (DQWFINIT) for details.
When the table is initialized with DQWFINIT, all the logical blocks are assigned to partitions and allocated to different batch CA Dataquery jobs as those jobs are started.
Note: Because the DQW is preformatted by the DQWFINIT utility, it will always show 99 percent full on the CA Datacom/DB Directory (CXX) report.
Recovering the DQW
If the DQW is lost due to catastrophe:
■
Allocate the table.
■
Initialize the table using the DBUTLTY INIT Data Area function. See the CA
Datacom/DB DBUTLTY Reference Guide for details.
■
Null load the table.
■
Run the DQWFINIT utility. See the following section for details.
Note: Once the DQW has been formatted with DQWFINIT, it may be backed up using
DBUTLTY BACKUP and reloaded using DBUTLTY LOAD instead of using a null load and
DQWFINIT, unless you want to change the number of DQW partitions. This is true only for the DQW table. You may not use DBUTLTY to load DQF or DQE. They must always be formatted with DQWFINIT.
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 101
DQWFI Initializing the DQE, DQF, and DQW (DQWFINIT)
DQWFI Initializing the DQE, DQF, and DQW (DQWFINIT)
DQWFINIT is the batch utility which you use to initialize the DQE (SQL Found Table), DQF
(Found Table), and DQW (Work Table). DQWFINIT initializes only the first block of the
DQF.
In DBUTLTY Directory (CXX) reports, the DQW always shows 99 percent full after
DQWFINIT has been run. A lack of available work space on the DQW is indicated by error messages. The percent full value on the report for the DQF and the DQE shows the maximum used at one time (a "high-water mark"). Space that has been used and freed shows on the report as being in use.
Tasks
■
■
Use the DQWFINIT utility to perform the following maintenance tasks:
■
Formatting the DQF, the DQW, or the DQE.
■
Enlarging the DQF, the DQW, or the DQE.
■
Changing the number of segments in the DQW.
Establishing the DQF, the DQW, or the DQE on a new device.
Re-creating the DQF, the DQW, or the DQE after a system catastrophe.
Procedures
You can run DQWFINIT after the appropriate files have been initialized and null loaded with DBUTLTY.
SYNCHRONIZE. When you null load and initialize the DQF, you must also null load and initialize the DQE, DQR, and DQS to maintain synchronization. Failure to synchronize these tables can result in failure to reclaim DQF space. (Omit the DQE and DQR tables if the SQL option is not installed.)
Executing DQWFINIT completely reinitializes the DQF table and destroys any deferred
KEEP or EXTRACT row collections currently on the table. Queued network print requests are all lost. Deferred batch jobs are lost.
Work Table Create Report
Following is an example of the Work Table Create Report produced by DQWFINIT when
DQW initialization is successful.
DATAQUERY WORK TABLE CREATE
TABLE DQW INITIALIZED SUCCESSFULLY 00586 ROWS WRITTEN
102 Administration Guide
DQWFI Initializing the DQE, DQF, and DQW (DQWFINIT)
DQWFINIT Job Control Statements
CA Datacom/DB table definitions are not included since CA Dataquery is used with the
CA Datacom/DB MUF. Use the following job control statements to execute DQWFINIT.
Sample z/OS JCL
//jobname See Preparing JCL for Batch CA Dataquery Utilities.
// EXEC PGM=DQWFINIT
//STEPLIB See Preparing JCL for Batch CA Dataquery Utilities.
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=* Print Output
//SYSIN DD * Command input
DQW 03
/*
//
jobname
Initiates the job.
EXEC PGM=
Specifies the program name (PGM=DQWFINIT).
SYSPRINT DD SYSOUT=
Defines the sequential output data set used for listing the report.
SYSIN DD
Defines the control data set. It normally resides in the input stream; however, it can reside on a system input device or a direct-access volume.
DQW
■
■
The required control statement for the DQWFINIT, which must be coded in columns
1-3, identifies the table to be initialized. Valid options follow:
■
DQE
DQF
DQW nn where nn, which must be coded in columns 5-6, specifies the number of partitions, and may be any two-digit number from 01 to 47.
Note: You must code the leading zero (for example, DQW 01).
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 103
DQWFI Initializing the DQE, DQF, and DQW (DQWFINIT)
You can use only one control statement per execution of DQWFINIT.
Sample z/VSE JCL
* $$ JOB ... See the note above and Preparing JCL for Batch CA Dataquery
Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// EXEC DQWFINIT
DQW 03
/*
/&
JOB
Initiates the job.
EXEC DQWFINIT
Specifies the program name.
DQW
The required control statement for the DQWFINIT, which must be coded in columns
1-3, identifies the table to be initialized. Valid options follow:
■
■
■
DQE
DQF
DQW nn where nn, which must be coded in columns 5-6, specifies the number of partitions, and may be any two-digit number from 01 to 47.
Note: You must code the leading zero (for example, DQW 01).
You can use only one control statement per execution of DQWFINIT.
104 Administration Guide
Scheduling System Table Backups
Scheduling System Table Backups
Schedule system backups regularly to backup DQQ, DQU, DQM, and DQT. Use the
BACKUP function of CA Datacom/DB Utility (DBUTLTY) for your system backups. See the
CA Datacom/DB DBUTLTY Reference Guide for details on executing DBUTLTY.
If the DQU is restored from a database backup, DQWFINIT must be run to reinitialize the
DQF and DQE tables after null-loading DQF, DQE, DQS, and DQR.
All Tables
For details on how each of the CA Dataquery tables should be backed up, check the information on previous pages for the individual tables.
DQE and DQF
DQF and DQE should never be loaded from a backup. They should always be null-loaded and reinitialized with DQWFINIT.
DQW
The DQW table may be loaded from a backup if the backup was made immediately after initializing it with DQWFINIT.
DQM, DQP, and DQV
Use the DQLANGMT utility to backup and restore the Literals Table (DQM), the Panel
Table (DQP), and the Vocabulary Table (DQV). These tables store literal values, panel images, and language and command keywords, respectively. For more information, see
Loading and Unloading Languages (DQLANGMT)
Chapter 8: Preparing and Maintaining the CA Dataquery System Tables 105
Chapter 9: Implementing Online CA
Dataquery
The online facilities of CA Dataquery are available under CICS.
Implementing CA Dataquery Under CICS
CICS Prerequisites
When operating under CICS, CA Dataquery requires CA Datacom CICS Services. For the supported version levels of CICS/VS and the required version level of CA Datacom CICS
Services, see the CA Datacom Installation and Maintenance Guide.
Note: For additional instructions on accommodating CA Dataquery when upgrading
Upgrading to New Releases of Supporting Products
When adding CA Dataquery to an existing system operating under the CICS/VS monitor, you must ensure that:
■
All requirements described in the CA Datacom installation guides have been met.
■
The CA Dataquery libraries are available to CICS.
Under CICS, CA Dataquery supports only terminals which can be defined as 3270 devices.
CA Dataquery's requirements for CICS tables (PCT and PPT) can be found in the installation source library.
CICS TRANSID
Considerations regarding CICS TRANSID priority in the PCT of which to be aware includes making the DQRY and DQIN TRANSIDs higher than the DQPR TRANSID.
Ensure that CA Dataquery execution libraries are included in the CICS startup deck.
CICS region/partition priority should be less than the priority of the MUF.
Note: For information about the CA Datacom/DB MUF startup options and User
Requirements Table parameters in relation to CICS, see the CICS information in the CA
Datacom/DB Database and System Administration Guide.
Chapter 9: Implementing Online CA Dataquery 107
Implementing CA Dataquery Under CICS
CA Dataquery Requirements Under CICS/VS
Operation
CA Dataquery does not issue terminal read operations but instead uses pseudo-conversational programming techniques to initiate a transaction when the terminal has input ready for processing. Most core requirements are therefore restricted to the brief interval needed to actually process the input stream and to write to the display screen.
TRANSIDs
Following is a list of the CA Dataquery TRANSIDs and their functions. For information on
ordering transaction IDs in the CICS Program Control Table (PCT), see
Implementing CA
Dataquery Under CICS
DQIN
Used internally by CA Dataquery to reschedule CA Dataquery and need not be known by terminal users.
DQPR
Used internally by CA Dataquery for online printing to a 328x printer.
DQRY
Initiates a CA Dataquery session.
Limits
It is important that CA Dataquery transactions are not limited in such a way as to inhibit other system functions. This could happen, for example, if the DQIN transaction is put in a CICS task class that does not allow an asynchronous task to be dispatched.
CICS MRO
If you are operating in a CICS MRO environment, the Network Printers must be local to the transaction owning region. If the printers are not local to the transaction owning region, your print requests will fail.
108 Administration Guide
Implementing CA Dataquery Under CICS
CA Dataquery Memory Requirements
Program Storage
For CA Dataquery executable code you need approximately 256K of program storage.
Working Storage
For CA Dataquery working storage during processing (per concurrent transaction) you need to calculate:
50K + [ 5K * (x - 1) ] where x = the value of the QPAGES= parameter in DQOPTLST.
CA Dataquery uses temporary storage under CICS. You should allow about 24 KB of auxiliary temporary storage per active user if QPAGES=1 in the DQOPTLST macro. Add 5
KB for each increment in the value specified for QPAGES= if that value is greater than 1.
In-Core Sort
For the approximate number of bytes in the in-core sort work area, use the formula:
rows * [ 10 + sort key length + (18 * tables joined) ]
Chapter 9: Implementing Online CA Dataquery 109
Chapter 10: Defining Databases
Authorized CA Dataquery users can access any database that meets CA Datacom/DB specifications. There are some recommendations for creating databases that will improve CA Dataquery effectiveness.
Designing the Database
If you are designing databases that will be accessed by CA Dataquery users, your key choice is the most important issue. When choosing a key, imagine how people will select data and make that criteria a key. For example, if you wanted to query all employees who made more than $50,000 a year, you should make salary a key.
For tables that you will join, consider what you would use to join those tables and make that a key. For example, if you wanted to join the payroll and personnel tables by employee, you would make the employee number or employee name a key and ensure that the data in both tables was stored as the same type and length.
Defining Entity-Occurrences in the Datadictionary
When you define entity-occurrences in CA Datacom Datadictionary, choose names that are obvious and meaningful to CA Dataquery users. If CA Dataquery user can use an alias in a query without having to know the actual entity-occurrence name. You can define aliases in CA Datacom Datadictionary when you create or add a entity-occurrence, or as maintenance to an existing entity-occurrence. You can use the UPDATE ALIAS line command in online or the 1103 Alias Transaction in batch. See the CA Datacom
Datadictionary User Guide for information about assigning aliases.
Always use the description and text columns when defining CA Datacom Datadictionary entity-occurrences that will be accessed by CA Dataquery. The CA Dataquery user can view the description and text to ensure which entity-occurrences he wants to query.
Chapter 10: Defining Databases 111
Defining Tables
Defining Tables
Do not specify logging for any of the CA Dataquery system tables, except the DQQ table
(Query Library).
When defining tables, make the entity-occurrence names different for TABLE, KEY, and
COLUMN entity-occurrences so that CA Dataquery can unambiguously resolve references in queries. Make the COLUMN, ELEMENT, and KEY entity-occurrence names unique within each row. Do not give a column the same name as a key in the same row.
CA Dataquery selects the first entity-occurrence it finds with the requested name and ignores any other entity-occurrence with that name. Do not use CA Dataquery reserved words as TABLE, COLUMN, or KEY entity-occurrence names. If it is necessary to do so, you can define aliases to use when accessing the data with CA Dataquery. See the CA
Dataquery User Guide or CA Dataquery Reference Guide for a list of reserved words.
Each table should have at least one unique key defined for it.
Defining Keys
Keys are recommended for use in the JOIN operation or as selection criteria.
Adding Keys
Each table should have at least one unique key defined for it.
No two keys in the same table should have the same value for the KEY-ID. These tables would be duplicated in a FIND.
Equivalent keys in different tables should be defined similarly. That is, the order, length, and type of constituent columns should be the same.
Naming Keys
Equivalent columns or keys in different tables should be named the same to avoid confusion and to facilitate relating tables together. Make the entity-occurrence names unique within each table. Do not give a column the same name as a key in the same table. CA Dataquery selects the first entity-occurrence it finds with the requested name and ignores any other entity-occurrence with that name. Do not use CA Dataquery reserved words as entity-occurrence names. If it is necessary to do so, you can define aliases to use in accessing the data through CA Dataquery. See the CA Dataquery User
Guide or CA Dataquery Reference Guide for a list of reserved words.
112 Administration Guide
Defining Columns
Nil Value Columns
When using nil valued columns in a key, users must be aware of which keys have been defined with INCLUDE-NIL-KEY=NO and what effect it has on their requests. If the value range of a Compound Boolean Selection Facility traversal key candidate includes either blanks or binary zeros, the key is not used because it cannot access all possible rows.
This can adversely affect performance.
Signed Data
When predicates in a FIND statement see columns containing signed numeric data of packed or zoned decimal format, it is important to be as specific as possible in the CA
Datacom Datadictionary TYPE-NUMERIC attribute about what sign codes the columns contain. This allows CA Dataquery to pass this information to the Compound Boolean
Selection Facility, which in turn allows the Compound Boolean Selection Facility to evaluate the selection criteria more efficiently because it restricts the traversal key value range.
For example, if the data contains only positive values with the X'C' sign code, then specify P for this attribute. This attribute must agree with the actual data or incorrect results will be obtained.
Removing Keys
Be careful when you remove keys because existing queries may cease to function.
Note: You can use the DBUTLTY CXXMAINT ALTER CBSUSE to disable use of a key by the
Compound Boolean Selection Facility. This enables you to check the impact of deleting a key prior to actually deleting it. For details, see the CA Datacom/DB Database and
System Administration Guide and the CA Datacom/DB DBUTLTY Reference Guide.
Defining Columns
Naming Columns
Make the entity-occurrence names unique within each table. Do not give a column the same name as a key in the same table. CA Dataquery selects the first entity-occurrence it finds with the requested name and ignores any other entity-occurrence with that name.
Do not use CA Dataquery reserved words as entity-occurrence names. If it is necessary to do so, you can define aliases to use in accessing the data through CA Dataquery. See the CA Dataquery User Guide or CA Dataquery Reference Guide for a list of reserved words.
Equivalent columns or keys in different tables should be named the same to avoid confusion and to facilitate relating tables together.
Chapter 10: Defining Databases 113
Defining Columns
Repeating Columns and Redefines
CA Datacom Datadictionary allows you to define simple or compound columns as repeating columns with the total number of repetitions to be expressed in the column's definition. This is important for defining an arrayed column with up to two levels of subscripts. Avoid the use of redefines and arrays if the columns are to be used with CA
Dataquery.
Securing Columns
The PROFILE-CODE attribute in a column (FIELD entity-occurrence) definition in CA
Datacom Datadictionary provides column security for CA Dataquery usage. The CA
Dataquery Security Administrator and the CA Dataquery Administrator determine what columns to secure. Then the CA Datacom Datadictionary Administrator updates the CA
Datacom Datadictionary FIELD entity-occurrence attribute with the profile-code. This can be done through CA Datacom Datadictionary online using the Attribute Update panel or through CA Datacom Datadictionary batch using the 4014 COLUMN transaction. See the CA Datacom Datadictionary User Guide, CA Datacom
Datadictionary Online Reference Guide, or the CA Datacom Datadictionary Batch
Reference Guide for details.
A CA Dataquery user may be authorized to one or more profile-codes. This authorization gives the user access to columns that have been classified and secured by profile-codes.
See Defining or Modifying the User Profile and How to Limit Access to Columns for more information about profile-codes.
Defining Column Headings
When defining the COLUMN entity-occurrences, you can define headings. CA Dataquery uses these headings as column titles in reports. The HEADING-1 attribute allows you to enter the first line of a heading that can be used in a columnar report. The HEADING-2 attribute allows you to enter the second line of a heading that can be used in a columnar report.
These headings will only be used if the System Option Table DQOPTLST parameter
DDHDG= is coded with one of the YES entries. See
Tailoring the CA Dataquery System
Option Table
(see page 47) for more information.
In CA Datacom Datadictionary online, use the Attribute Update panel to define headings. See the CA Datacom Datadictionary Online Reference Guide for details.
In CA Datacom Datadictionary batch, use the 4013 COLUMN transaction to add headings that CA Dataquery uses as column titles in reports and panels. See the CA Datacom
Datadictionary Batch Reference Guide for details.
114 Administration Guide
Modifying/Maintaining Datadictionary Definitions
Defining Numeric Display Patterns
You can use CA Datacom Datadictionary to designate whether a column is left or right justified, the decimal position in numeric columns, and the addition of edit-patterns. CA
Dataquery uses these options when printing reports. For use with CA Dataquery, you should follow CA Dataquery standards when defining these edit patterns.
The EDIT-PATTERN attribute allows you to enter an edit pattern for the column.
The edit-pattern will only be used if the System Option Table DQOPTLST parameter
Tailoring the CA Dataquery System Option Table
for more information.
In CA Datacom Datadictionary online, use the Attribute Update panel to define the edit pattern. See the CA Datacom Datadictionary Online Reference Guide for details.
In CA Datacom Datadictionary batch, use the 4014 COLUMN transaction to add or change the edit pattern of the column. See the CA Dataquery Reference Guide for valid edit pattern formats. See the CA Datacom Datadictionary Batch Reference Guide for details.
Modifying/Maintaining Datadictionary Definitions
CA Datacom Datadictionary definitions are modified and maintained using standard CA
Datacom Datadictionary procedures. CA Datacom Datadictionary disables these definitions and their structures in the process.
Disabling a Structure
When a structure or definition was disabled because it was modified or maintained in
CA Datacom Datadictionary or when it has been subject to the CA Datacom
Datadictionary DISABLE function, it is not available for use by other products such as CA
Dataquery.
Enabling a Structure
A disabled structure or definition in CA Datacom Datadictionary must be enabled with the CA Datacom Datadictionary ENABLE function before other products, such as CA
Dataquery, can use the structure or substructure.
See the CA Datacom Datadictionary documentation for details.
Chapter 10: Defining Databases 115
Updating the Directory
Updating the Directory
Before CA Dataquery can use the CA Datacom Datadictionary definition, CA Datacom
Datadictionary must accurately reflect the database definitions in the Directory (CXX).
This means the definitions must be cataloged to the Directory. If the row/column sizes in CA Datacom Datadictionary do not match those in the Directory, CA Dataquery will issue an error.
You cannot use the DBUTLTY CXXMAINT DDPROD NEWDBID= parameter with CA
Dataquery.
See the CA Datacom/DB DBUTLTY Reference Guide for more information.
Allocating the Index Area
When enough storage is available, CA Dataquery processes sort requests using storage in memory. In-memory sorting space allocation is determined by specifications in the
System Option Table DQOPTLST macro parameters. If enough space is not available, CA
Dataquery uses the Index Area (IXX) of the CA Dataquery database for sorting. If the
Index Area is not large enough to accommodate the sorting, an index full database return code will be encountered. See the CA Datacom/DB Database and System
Administration Guide for information about the Index Area.
116 Administration Guide
Chapter 11: Defining the CA Dataquery User
Requirements Tables
The CA Dataquery User Requirements Table describes to CA Datacom/DB the CA
Dataquery system tables that can be accessed during online execution. The parameters of the CA Datacom/DB macro DBURTBL define the User Requirements Table.
DBURTBL Requirements
Whether you create a new User Requirements Table or modify existing ones, you must ensure that the following requirements are met in the coding of DBURTBL.
You must define DBURTBL macros for eleven of the twelve CA Dataquery tables. The work table (DQW) is not used online, so should not be included in the online User
Requirements Table. A batch User Requirements Table used for the DQW is built dynamically at execution time.
■
Code the parameters to reflect your environment.
■
Code DBID= with the ID you specified in the System Option Table DQDBID= parameter.
■
Code UPDATE=YES for the CA Dataquery system tables.
■
Specify each of the following CA Dataquery system tables using the TBLNAM= parameter:
–
DQE (Found Table if SQL is used)
–
DQF (Found Table)
–
DQM (Literals Table)
–
–
–
DQP (Panel Table)
DQQ (Query Library Table)
DQR (Recovery Table if SQL is used)
–
–
DQS (Spool Table)
DQU (User Table)
–
DQV (Vocabulary Table)
Chapter 11: Defining the CA Dataquery User Requirements Tables 117
Allocating the Index Area
Sample User Requirements Table for CICS
Under CICS, a sample User Requirements Table, named DBURT003, is provided in the
DQSAM10 member. You can use this as a model either for creating the User
Requirements Tables for your site or in modifying User Requirements Tables that already exist in your environment. For information on the sample programs (sample assemblies and jobs), see the CA Datacom Installation Guide.
CICS Startup
Under CICS, all User Requirements Tables will be opened at CICS startup unless specified otherwise through either the AUTO[n]= or DEFER[n]= parameters of the DBCVTPR macro or through the DBOC AUTO= or DBOC DEFER= commands. These parameters and commands permit you to delay opening any User Requirements Table until a CA
Datacom/DB application requiring its use begins processing (AUTO) or to defer its opening until explicitly opened through a DBOC OPEN= command (DEFER).
If a User Requirements Table is specified as AUTO, you do not have to open it prior to issuing the DQRY signon command.
Note: For information on specifying the manner in which User Requirements Tables are to be opened, see the CA Datacom CICS Services System Guide.
Batch
In batch, User Requirements Tables are not required for CA Dataquery under z/OS or z/VSE.
Dynamic User Requirements Table Support
The CA Datacom CICS Services Version 2.4 (or later) allows CA Dataquery users to access some tables which are not in a User Requirements Table. In CA Dataquery a user can create a personal table which also is not in a User Requirements Table. CA Dataquery automatically and dynamically builds the needed User Requirements Table in a manner that is transparent to the user.
In DQL Mode, it is possible to access tables without assembling/linking User
Requirements Tables. When a request for a particular table is received, CA Dataquery checks the online User Requirements Table's for the table. If the query gets an RC05
(TABLE NOT OPEN), CA Dataquery does an internal check to see if the table is in reality in an existing User Requirements Table that is closed, in which case the query correctly receives a return code.
118 Administration Guide
Allocating the Index Area
If the table is not in a User Requirements Table, one is generated containing the table
(or tables if the query is joining) used by the query. The User Requirements Table is not deleted after the query completes because there is no way to be sure another product
(such as CA Ideal) had not started processing against the table using the new User
Requirements Table. To avoid closing a User Requirements Table on another transaction, CA Dataquery leaves the User Requirements Table. It can be closed later using DBOC and then deleted.
SQL queries use the SQL User Requirements Table.
An exception to the above concerns a table created by the STORE command. Although
SQL statements are used during the table creation, the table is actually populated using
ADDITs which, since they are native commands, need a User Requirements Table. This
User Requirements Table is, however, deleted after the table is created/populated on the assumption that it will most likely be accessed only through SQL. Because the process is the same, this only applies to tables created through STORE.
Chapter 11: Defining the CA Dataquery User Requirements Tables 119
Chapter 12: Initiating and Terminating CA
Dataquery
CA Dataquery can be initiated from a terminal or from a program. CA Dataquery can be terminated through a standard CA Dataquery signoff procedure or can pass control to a user program at signoff.
Executing CA Dataquery from a Program in CICS
You can execute CA Dataquery from a program under CICS using CICS Interval Control
Services. Your program can provide to CICS Interval Control Services the following:
■
CA Dataquery transaction ID (DQRY)
■
Terminal ID where you want CA Dataquery initiated
■
One internal control data record, which can include the following:
–
Transaction ID of a program to be initiated at signoff
–
User ID
–
–
–
User password
A CA Dataquery command
15 bytes of data
You can initiate CA Dataquery from a program either with or without data. Initiating CA
Dataquery with data bypasses the signon panel. Both methods are described in the following sections. Invoking CA Dataquery from a CA Ideal program is basically the interval control start without data, described below.
Starting CA Dataquery without Data
To start CA Dataquery without data, use the interval control (IC) start (EXEC CICS START) as follows:
1. START (schedule) transaction ID (DQRY).
2. CA Dataquery displays the signon panel to prompt for name/password.
3. At session end, CA Dataquery checks for RTRNMOD=, and if present, does XCTL to it.
If RTRNMOD= is not present but RTRTRAN= is specified, CA Dataquery does an interval control start without data.
Chapter 12: Initiating and Terminating CA Dataquery 121
Executing CA Dataquery from a Program in CICS
Options for Starting CA Dataquery
To start CA Dataquery with data, you can use the interval control PUT command or EXEC
CICS START as follows, with input data having the format:
Position Length Description
1
33
42
46
61
133 (optional) 1
32
9
4
15
72
User name, left-justified, blank padded
Password
Return transaction ID
Return parameter
Input command
Optional startup with or without data. See the following Note. (N for NO is the default, Y for YES can be entered.)
The input record can be 132 or 133 bytes in length. All of the above items are optional.
If any item is to be omitted, it should be initialized to spaces. If a user name is omitted, the signon panel will be presented.
Note: To give CA Dataquery the option of starting a return transaction with data or without data, add a one-byte character field at position 133. To start the transaction with data, enter Y. To start without data, enter an N or any other character. This extra byte permits CA Dataquery to start the return transaction correctly in CICS 3.2 and also permits existing programs to work. If the input data to CA Dataquery is 132 bytes in length, the return transaction will be started with data. If the input is 133 bytes, the return transaction will be started with data only if a Y is in position 133.
Initiating a Transaction at CA Dataquery Signoff
1
33
37
If you supply a transaction ID to be initiated at signoff, CA Dataquery returns the following to that transaction at signoff:
Position Length Description
52
53
32
4
15
1
6
User name, left-justified, blank padded
DQRY
Parameter supplied on input (unaltered by CA
Dataquery)
Unused
Last issued CA Dataquery message number
122 Administration Guide
Executing CA Dataquery from a Program in CICS
Position
59
Length
72
Description
Last issued CA Dataquery message text
Getting Control from CA Dataquery at Signoff
You can set up CA Dataquery to pass control to a program at signoff. You can pass control in three ways:
■
By coding the RTRNMOD= parameter in DQOPTLST with the name of a program.
■
By supplying CA Dataquery the transaction ID of a program when initiating CA
Dataquery through a program.
■
By coding the RTRTRAN= parameter in DQOPTLST with the transaction ID of a program.
Using RTRNMOD= overrides the transaction ID passed to CA Dataquery by a program, and also overrides the value coded for the RTRTRAN= parameter. We recommend using
RTRTRAN= instead of RTRNMOD=.
Note: If you specify either the RTRNMOD= or the RTRTRAN= parameter, CA Dataquery ignores any value you specify for the USRCMD= parameter.
Return Module Subroutines
To use a Return Module subroutine, you must code the RTRNMOD= parameter in the
DQOPTLST macro with the name of the Return Module. See DQOPTLST Parameters for information about valid entries for RTRNMOD=.
The named module is given control by CICS XCTL when the CA Dataquery session is signed off. The name specified in the RTRNMOD= parameter overrides the value coded for the RTRTRAN= parameter and the session level return transaction ID from the startup record.
Chapter 12: Initiating and Terminating CA Dataquery 123
Chapter 13: Using CA Dataquery with CA
Datacom Transparencies
If you want to use CA Dataquery to access databases that have been migrated using the
CA Datacom VSAM Transparency, the CA Datacom DL1 Transparency, or the CA
Datacom TOTAL Transparency, you must look at your CA Datacom Datadictionary definitions and consider your plans to use INSERT, UPDATE, or ERASE.
VSAM Transparency
If you plan to use CA Dataquery to access databases that were migrated using CA
Datacom VSAM Transparency, ensure that you have meaningful names for column and keys in CA Datacom Datadictionary or that you create aliases that are meaningful to your users.
CA Dataquery does not use the "occurs depending on" information to process variable-length rows. Be careful when you reference an occurring column in a query to ensure that the subscript is in the range of the depending on column's value. CA
Dataquery always processes the rows as if they were the maximum row length.
See your CA Datacom VSAM Transparency documentation for more information.
DL1 Transparency
If you plan to use CA Dataquery to access databases that were migrated using CA
Datacom DL1 Transparency, you should do the following:
■
Ensure that you have meaningful names for columns and keys in CA Datacom
Datadictionary or that you create aliases that are meaningful to your users.
■
Define additional columns and keys to CA Datacom Datadictionary.
■
Redefine the CA Datacom DL1 Transparency prefix column in CA Datacom
Datadictionary to maintain the delete bits.
■
Redefine the concatenated keys (PPCK, LPCK) into individual columns in CA
Datacom Datadictionary so that you can do joins.
■
Ensure that the integrity of the migrated data is not compromised if you use
INSERT, UPDATE, or ERASE. CA Dataquery is not aware of the special DL1 relationships in the data.
See your CA Datacom DL1 Transparency documentation for more information.
Chapter 13: Using CA Dataquery with CA Datacom Transparencies 125
Executing CA Dataquery from a Program in CICS
TOTAL Transparency
If you plan to use CA Dataquery to access databases that were migrated using CA
Datacom TOTAL Transparency, you should ensure that:
■
You have meaningful names for column and keys in CA Datacom Datadictionary or that you create aliases that are meaningful to your users.
■
The integrity of the migrated data is not compromised if you use INSERT, UPDATE, or ERASE. CA Dataquery is not aware of the special relationships in the data.
See your CA Datacom TOTAL Transparency documentation for more information.
126 Administration Guide
Chapter 14: Language Maintenance Facility
CA Dataquery has an optional feature called the Language Maintenance Facility that
your site may choose to implement at any time. See
Using the Language Maintenance
Facility.
Chapter 14: Language Maintenance Facility 127
Chapter 15: Defining or Modifying the User
Profile
Access
You can define or modify a user profile by performing either of the following. You must have User Maintenance authorization.
■
Typing USERS on the command line and pressing ENTER to display the Directory of
CA Dataquery Users panel. Place the cursor on the user name and press <PF10>
PROFILE to display the User Profile panel.
■
Signing on as that user and selecting the PROFILE option from the Administrative
Menu.
When you change another user's profile, all field changes take effect when that user signs on next.
When changing your profile, some changes take effect immediately and some are changed for the duration of the current session only. The CA Datacom Datadictionary database ID always reverts back to the site default at sign-off. The SQL Authorization ID returns to the user's default at sign-off.
Chapter 15: Defining or Modifying the User Profile 129
Executing CA Dataquery from a Program in CICS
CA Dataquery supplies entries to the panel from the User table, the Option table, and the previous session (if any).
CA Dataquery displays the User Profile panel, an example of which follows:
User Profile (DQKL0)
=>
Overtype the values to be modified and press PF4 to complete the update
--------------------------------------------------------------------------DQKL0
DATAQUERY: USER PROFILE FOR => ________________________________
-------------------------------------------------------------------------------
PROFILE ITEM EXPLANATION
-------------------------------------------------------------------------------
DATADICTIONARY DATABASE ID => _____ Five digit DB ID number for DD access
LIST AND DISPLAY ALIASES => ___ YES show aliases, NO supresss aliases
GROUP DISPLAY => ___ YES break out simple columns, NO do not
SUPPRESS DUPLICATE COLUMNS => ___ YES turn on suppression, NO turn off
SUPPRESS PFKEYS ON PRINT => ___ YES turn on suppression, NO turn off
SUPPRESS EXECUTE PANEL => ___ YES turn on suppression, NO turn off
PRIMARY LANGUAGE => __ TWO character primary language ID
SECONDARY LANGUAGE => __ TWO character secondary language ID
DECIMAL POINT CHARACTER => _ Character to be used for decimal point
QUERY LANGUAGE => ___ Language for queries - SQL or DQL
SQL AUTHORIZATION ID => __________________
-------------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISP GROUPS <PF4> UPDATE
<PF5> PRINT OPT <PF6> NOT USED <PF7> NOT USED <PF8> NOT USED
DATADICTIONARY DATABASE ID
(Required) Enter the CA Datacom/DB database ID that specifies the CA Datacom
Datadictionary database to be accessed. The database specified must be a CA
Datacom Datadictionary database accessible to CA Dataquery. CA Dataquery supplies the CA Datacom/DB database ID from the System Option Table. This value can be changed by the user signed on only.
LIST AND DISPLAY ALIASES
(Required) Enter YES or NO. Specify YES to include CA Datacom Datadictionary aliases in the Directory of DQL Tables, and Keys and Columns Display panels. NO excludes CA Datacom Datadictionary aliases from these display panels. (See the CA
Dataquery end user documentation for details on these panels.)
130 Administration Guide
Executing CA Dataquery from a Program in CICS
GROUP DISPLAY
(Required) Enter YES or NO. Determines the way a compound field is displayed on a report. If you specify YES, fields making up the compound field are shown as individual fields. When you specify NO, a compound field is shown as a single alphanumeric field, even though one or more of the simple fields contained in the compound field is a numeric field which cannot be printed. If an invalid value is entered, the parameter defaults to NO.
SUPPRESS DUPLICATE COLUMNS
(Required) Enter YES or NO. Determines if duplicate values for columns specified as control break columns are suppressed in the generated report. If you specify YES, the value contained in a control break column is displayed only once. Each time the value in the control break column changes, the new value is displayed. If the output continues to the top of a new page, the current value in the control break column is displayed at the top of the new page.
SUPPRESS PFKEYS ON PRINT
(Required) Enter YES or NO. Specify YES to suppress the PF key descriptions on the print panel that displays the report. NO causes the PF keys descriptions to be displayed.
SUPPRESS EXECUTE PANEL
(Required) Enter YES or NO. Specify YES to suppress the display of the Online
Execution Query panel. NO causes the Online Execute Query panel to be displayed.
A user would want to suppress the display of the Online Execution Query panel if their queries always read and collect data and display it on their terminals.
Suppressing the display saves a step during the execution process by accepting the execution defaults.
PRIMARY LANGUAGE
(Required) Enter 2 characters. Specifies the primary language to be used during the current CA Dataquery session. A valid 2-character entry overrides the language specified in the System Option Table at installation. (AE American English is the default if no other language is specified on the System Option Table.)
SECONDARY LANGUAGE
(Required) Enter 2 characters. Specifies the secondary language to be used during the current CA Dataquery session. A valid 2-character entry overrides the language specified in the System Option Table at installation. (AE American English is the default if no other language is specified on the System Option Table.)
Chapter 15: Defining or Modifying the User Profile 131
Executing CA Dataquery from a Program in CICS
DECIMAL POINT CHARACTER
(Optional) Enter 1 character. Specifies the decimal point character for this ID. The default is the value of the DECPT= parameter in the System Option Table.
QUERY LANGUAGE
(Required) Enter either DQL or SQL. Specifies the query language to be used for this
ID. Y (yes) must have been specified on the User Table Maintenance in the field SQL
AND DQL ALLOWED for the user to be able to change from DQL to SQL in this field.
This value can be changed by the user signed on only.
SQL AUTHORIZATION ID
(Required) Enter a 1- to 18-character authorization ID. Specifies the SQL authorization ID for execution of SQL statements for this ID. This value can be changed by the user signed on only and is valid for the current session only. To change this value for another user, you must use User Table Maintenance.
When the SQL authorization ID is changed by the PROFILE or AUTHID command, it changes only on the user profile, and not on the User Table. The private SQL authorization ID attaches to the table name regardless of the authid in use during creation of the table. When the DISPLAY, LIST, EXECUTE, or CREATE functions are used, the profile authid is used.
PF Keys
Each PF key for the User Profile panel is listed below.
<PF3> DISP GROUPS
Display group to which user is assigned.
<PF4> UPDATE
Save the values displayed on this panel. Refresh User Profile panel.
<PF5> PRINT OPT
Display print options for profile. Print Options panel appears. See the section on
printer options
132 Administration Guide
Displaying a User's Group Assignments
Displaying a User's Group Assignments
Action
To view the groups to which a user is assigned, follow these steps:
Step 1
Select the USERS option from the Administrative Menu, or type USERS on the command line and press <ENTER>. CA Dataquery displays the Directory of Users panel.
Step 2
Place the cursor on the user name and press <PF10> PROFILE. CA Dataquery displays the User Profile panel.
Step 3
Press <PF3> DISP GROUPS. CA Dataquery displays the Group Display panel.
CA Dataquery does not allow you to change any values on the display. With authorization, you can change these values only on the User Table Maintenance panel.
A sample Group Display panel follows.
Sample Group Display (DQK20)
=>
The named operator is currently assigned to these group(S)
--------------------------------------------------------------------------DQK20
DATAQUERY: GROUP DISPLAY FOR =>
-------------------------------------------------------------------------------
GROUP ONE =>
GROUP TWO =>
GROUP THREE =>
-------------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Chapter 15: Defining or Modifying the User Profile 133
Displaying Hardcopy Print Options
Displaying Hardcopy Print Options
Access
To view a user's print options, select <PF 5> PRINT OPT on the User Profile panel.
These options apply to print output on a network printer or in DQBATCH, except for number of rows and number of columns. All fields are required.
User Profile - Print Options (DQKM0)
=>
Overtype the values to be modified and press PF4 to complete the update
------------------------------------------------------------------------DQKM0
DATAQUERY: USER PROFILE FOR => ________________________________
-----------------------------------------------------------------------------
HARDCOPY PRINT OPTIONS EXPLANATION
-----------------------------------------------------------------------------
NETWORK PRINTER-ID => ____ Four Character ID of Network printer
PRINT QUERY TEXT => ___ YES print the query text, NO do not
PRINT STATISTICS => ___ YES print the query stats, NO do not
PRINT BANNER PAGE => ___ YES print the banner page, NO do not
PRINT USING WINDOWS => ___ YES window format, NO wrap format
PRINT PAGES TOGETHER => ___ YES pages together, NO windows together
PRINT NUMBER OF COLUMNS => ___ Three digit column width of hardcopy
PRINT NUMBER OF ROWS => ___ Three digit page length in rows
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISP GROUPS <PF4> UPDATE
<PF5> PROFILE <PF6> NOT USED <PF7> NOT USED <PF8> NOT USED
Panel Description
NETWORK PRINTER-ID
Enter a 1- to 4-character printer ID. CA Dataquery displays the value entered in the
System Option Table, if one has not been entered for the user.
PRINT QUERY TEXT
Y (yes), the default, if the text of the query that produced the report is to be printed when the report is printed on a network printer.
N (no) does not print the query text.
134 Administration Guide
Displaying Hardcopy Print Options
PRINT STATISTICS
Y (yes), the default, if the statistics of the query that produced the report are to be printed when the report is printed on a network printer.
N (no) does not print the query statistics.
PRINT BANNER PAGE
Y (yes), the default, if the print jobs are to be preceeded with a banner page containing user name, date, and time, to aid in distributing the reports.
N (no) suppresses the printing of the banner page.
PRINT USING WINDOWS
Y (yes) if the report extends beyond 80 columns and you do not want the report lines to wrap.
N (no) the default, states that you want the print to wrap or continue on the next line.
PRINT PAGES TOGETHER
Use this field when printing a report composed of two or more adjacent
(side-by-side) pages. If the first page (left-hand page) is labeled A and the second page (right-hand page) is labeled B and the report is three pages in length, specifying:
Y (yes), the default, would result in these pages being printed in the order of 1A, 1B,
2A, 2B, 3A, 3B.
N (no) results in a printing order of 1A, 2A, 3A, 1B, 2B, 3B.
This applies to both network and system printers.
PRINT NUMBER OF COLUMNS
Indicate a 1- to 3-character numeric value. Specify the width of the hardcopy on the network printer by stating the number of columns to be printed.
PRINT NUMBER OF ROWS
This is a 3-character numeric field. Specify the number of rows to be printed on one page of hardcopy on the network printer.
When you have completed your input to either User Profile panel (DQKL0 or DQKM0), or both, press <PF4> UPDATE to save changes. The new print options are in effect at the next sign-on with this ID.
Chapter 15: Defining or Modifying the User Profile 135
Chapter 16: Managing Your Query Library
Table
One of the functions of a CA Dataquery Administrator is to maintain the CA Dataquery
Query Library Table.
We recommend that you follow a regular backup schedule of the Query Library Table.
You can use the BACKUP function of CA Datacom/DB Utility (DBUTLTY), or one of the other system backup functions. (See the CA Datacom/DB DBUTLTY Reference Guide for details.) Maintenance involves the following tasks:
■
Editing queries of other users
■
Deleting queries
■
Maintaining extended definitions for queries
Each task is discussed in this chapter.
QRYGRPS=NO
If the System Option Table parameter QRYGRPS=NO, the Query Library Table is not partitioned at the group level. This means that a user can:
■
Access any public query or dialog
■
Update any public query or dialog for which he is the author
■
Access his own private queries and dialogs regardless of the group levels that are assigned to him as a user or to the queries or dialogs
QRYGRPS=YES
If QRYGRPS=YES, group level access authorization partitioning of the Query Library Table is in effect. A user can access only those queries or dialogs that have matching group levels. The user cannot update any public queries or dialogs unless he has LIBRARY authorization.
Group level assignments limit the scope of queries to which the LIBRARY authorization extends. If the group level assignments do not match the Administrator's group level assignments, the Administrator cannot access the query. If the Administrator has no assigned groups, then his access to the query library is unlimited. Query group level
assignments apply to both DQL Mode and SQL Mode (see
Assigning Group Levels
page 232)).
Chapter 16: Managing Your Query Library Table 137
Accessing the Administrative Library List
Accessing the Administrative Library List
The Administrative Library List panel allows the Administrator to select the type of query list. You may select by user, status, or type.
Access
Select LIBRARY from the Admin Menu or type the LIBRARY command on the command line and press Enter.
Administrative Library List (DQEM0)
=>
Select the Options you wish - default is ALL
------------------------------------------------------------------------DQEM0
DATAQUERY: ADMINISTRATIVE LIBRARY LIST
-----------------------------------------------------------------------------
USER ________________________________ USER and STATUS are mutually
STATUS exclusive
_ Public - List only Public
_ Private - List only Private
TYPE
_ Queries - List only Queries
_ Dialogs - List only Dialogs
_ Terms - List only Terms
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
138 Administration Guide
Accessing the Admin DIRECTORY OF QUERIES AND TERMS
Panel Description
USER
(Optional) The name of the specific user you want to display. Must be a valid 1-32 character name.
STATUS
(Optional) Mark either Public or Private to look at only that status.
TYPE
(Optional) Mark one type to restrict directory list to that type. If none are marked, the default is "ALL" types.
Note: If no options are selected on this panel, the default is all queries, terms, and dialogs for all users in both public and private status as secured by the QRYGRPS parameter (see previous page for a discussion of this parameter).
Accessing the Admin DIRECTORY OF QUERIES AND TERMS
Use the Admin DIRECTORY OF QUERIES AND TERMS to access the administrative Query
Library Table maintenance functions.
Access
Enter selection criteria from panel DQEM0 and press Enter to display the query Library
Directory.
The Admin DIRECTORY OF QUERIES AND TERMS panel looks like the DIRECTORY OF
QUERIES AND TERMS panel for users. However, each user only sees a listing of the queries, dialogs, and terms for which he is authorized. You see a listing of all users' queries, terms, and dialogs at your site which have a group level authorization that matches your group level authorization if your query library is partitioned by groups
(QRYGRPS=YES in the DQ System Option Table).
The Admin DIRECTORY OF QUERIES AND TERMS lists queries and dialogs for either DQL mode or SQL mode, depending on the mode of the Administrator. (The LIST QUERY command displays a directory that contains only those queries for the current setting of the query language.)
Chapter 16: Managing Your Query Library Table 139
Accessing the Admin DIRECTORY OF QUERIES AND TERMS
An example of the Admin DIRECTORY OF QUERIES AND TERMS panel follows.
DIRECTORY OF QUERIES AND TERMS (DQA30)
=>
Place the cursor on the desired name and press the appropriate PF key
------------------------------------------------------------------------DQA30
DATAQUERY: ADMIN DIRECTORY OF QUERIES AND TERMS START WITH: ________________
-----------------------------------------------------------------------------
QUERY NAME | TYPE | CREATED | USED | DESCRIPTION
-----------------------------------------------------------------------------
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
--------------------------------------------------------------------------- ==>
<PF1> HELP <PF2> RETURN <PF3> EXECUTE <PF4> EDIT
<PF5> NOT USED <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
<PF9> SUBMIT <PF10> EXTENDED DEF <PF11> NOT USED <PF12> RIGHT
Action
The START WITH: field, located in the upper-right corner of this panel is where you enter the full or partial name of the query or term where you want the listing to start. When you press Enter, CA Dataquery refreshes the DIRECTORY OF QUERIES AND TERMS panel with the query, dialog, or term that you specified on the first line of the listing. You can also page forward using <PF8> FORWARD until you reach the member that you wish to view or edit.
Panel Description
The following list describes each column of the DIRECTORY OF QUERIES AND TERMS panel:
QUERY NAME
Lists alphabetically all existing query, dialog, and term names.
TYPE
Specifies whether this is a query, dialog, or term, SQL query, or SQL dialog.
CREATED
Displays the date the named query, dialog, or term was created.
140 Administration Guide
Accessing the Admin DIRECTORY OF QUERIES AND TERMS
USED
Displays the date this query, dialog, or term was last accessed.
DESCRIPTION
Displays a description of this query, dialog, or term as entered on the Editor panel.
STATUS
Displays the status (public or private) as assigned to this query, dialog, or term.
AUTHOR
Displays the name of the author of this query, dialog, or term.
GROUPS
Lists Level 1, Level 2, and Level 3 groups assigned to this query, dialog, or term, if any.
To view the STATUS, AUTHOR and GROUPS columns press <PF12> RIGHT. This PF key shifts the panel display to the right.
Note: <PF11> NOT USED exists on the panel until you press <PF12> RIGHT to view the last three columns. Use <PF11> LEFT to shift the panel display to its original state.
Action
CA Dataquery uses the DIRECTORY OF QUERIES AND TERMS panel to perform several functions on queries by PF key selection. Your use of these PF keys is for a different purpose than that of the average user. Following are listed some examples of how to use the functions:
■
To execute a query or dialog to test or debug that query or dialog by executing only the selection, computation, sorting, or reporting portion of that query or dialog.
■
To view or edit a user's query to aid the user with problem resolution, to edit the query to meet site standards, or to edit the query after the author leaves your company's employment or changes positions within the company.
■
■
To delete queries as they are no longer used, are not functional or no longer meet the needs of your company, and so forth.
To submit your own queries.
■
■
To access a user's queries, dialogs or terms, when a user's status changes, such as a change in job position responsibilities or a departure from your company. You can delete any unnecessary ones and reassign the usable ones to other users and or groups.
To change the status of a user's queries from PRIVATE to PUBLIC or from PUBLIC to
PRIVATE.
Chapter 16: Managing Your Query Library Table 141
Accessing the Admin DIRECTORY OF QUERIES AND TERMS
PF Keys
The following list describes each PF key for the DIRECTORY OF QUERIES AND TERMS panel.
Key Objective Result
CLEAR
<PF1> HELP
<PF2> RETURN
<PF3> EXECUTE
<PF4> EDIT
<PF5> NOT USED
Return to Main Menu.
Display HELP panel.
Return to previous panel.
Execute this query, dialog, or term.
Modify a query, dialog, or term.
Not in use.
Returns to the Main Menu.
CA Dataquery displays the HELP panel.
Returns to previous panel, or
Main Menu.
CA Dataquery executes this query, dialog, or term.
Displays the query, dialog, or term.
<PF6> DELETE
<PF8> FORWARD
Delete a query, dialog, or term.
<PF7> BACKWARD Scroll to previous page of list.
CA Dataquery removes query, dialog, or term.
Displays previous page of list.
Scroll to next page of list. Displays more of list.
<PF9> SUBMIT
<PF10> EXTENDED
DEF
Submit a query, dialog, or term for batch execution.
View this query, term, or dialog for group assignments.
<PF11> NOT USED Not in use OR shift display to left.
<PF12> RIGHT Shift display to right.
CA Dataquerydisplays the Query
Execution Facility panel.
CA Dataquery displays the
Administrative Extended
Attributes panel.
Displays previous three columns.
Displays next three columns.
142 Administration Guide
Submitting a Query or Dialog
Submitting a Query or Dialog
A CA Dataquery Administrator may submit any query or dialog to which he has access.
Access
From the DIRECTORY OF QUERIES AND TERMS panel place the cursor on the desired query or dialog and press <PF9> SUBMIT.
Batch Execution (DQEN0)
=>
------------------------------------------------------------------------DQEN0
DATAQUERY: BATCH EXECUTION
-----------------------------------------------------------------------------
Enter name of query to submit: ACTIVE-QUERY
Select the type of execution: _ Immediate
X Defer execution until time 18 : 00
Enter the name of the JCL member to use: $$DQJCL
Enter nonblank to use JCL for deferred: _
Select the report type:
_ Detail and totals _ When/do column functions only
_ Detail only (no totals) _ No detail (totals and when/do)
_ Totals only (summary) _ Suppress report
To export print data to a sequential file, select output record type:
_ Variable comma separated _ Fixed-length record
For variable, enter name of output set _______________
For variable, select output type: _ Detail
_ Totals
Select the output file device type: _ Tape
_ Disk
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> SUBMIT <PF4> NOT USED
The following steps explain how to use the BATCH EXECUTION panel.
Step 1
Verify the name of the query that you want to submit. A default query appears in the name of the query field but you may change it.
Step 2
Select the type of execution: Immediate or Deferred. (See Type of Execution following.)
Step 3
Enter the preferred JCL member name in the JCL name field.
Chapter 16: Managing Your Query Library Table 143
Submitting a Query or Dialog
Step 4
Select the report type. (Explanations of each follow.)
Step 5
(Optional) Data produced by the query may be exported. Select the output record type.
Step 6
After all desired options have been entered, press <PF3> to continue with batch submission.
Type of Execution
There are two types of execution, each is explained below:
Immediate
Schedules the query as soon as you press <PF3> SUBMIT.
Deferred
A batch job may be deferred by typing any character in the blank before Defer
execution until time __ : __ and filling in the time for execution in the appropriate space. The format for the time is based on a 24-hour clock, with midnight being
00:00. This panel tells the job to run at 6:00 PM.
The following fields appear on this panel:
Panel Description
QUERY NAME
(Required) The name of the query being submitted.
JCL NAME
(Required) The name of the JCL member or JCL PROC to use to run the selected query in batch.
JCL FOR DEFERRED
(Optional) The JCL member named above is to be used for deferred DQBATCH execution.
REPORT TYPE
(Optional) The totaling options for the query.
EXPORT RECORD TYPE
(Optional) To use the export function select either:
VARIABLE COMMA SEPARATED
For output of variable-length comma separated record to the export file.
144 Administration Guide
Editing a Query, Dialog, or Term
FIXED LENGTH RECORD
For output of fixed-length records to the export file.
EXPORT FILE
(Optional) The file name for variable record output. Not used for fixed-length export data.
EXPORT OUTPUT TYPE
(Optional) The output type to write to the export file for variable record output.
Not used for fixed-length export data.
OUTPUT DEVICE
(Optional) The device for the exported file, disk, or tape, for DOS only.
Editing a Query, Dialog, or Term
A CA Dataquery Administrator can create queries, dialogs, and terms from time to time, for use by individuals or groups. The creation of queries, dialogs, and terms is discussed in the CA Dataquery end user documentation. The CA Dataquery Administrator can also edit public members belonging to other users.
Access
When the Admin DIRECTORY OF QUERIES AND TERMS panel appears, position the cursor on the line containing the query, dialog, or term name and press <PF4> EDIT. CA
Dataquery then displays the Editor panel. This panel allows you to edit a query, dialog, or term or perform several other functions by PF key selection.
See the CA Dataquery User Guide or CA Dataquery Reference Guide for Editor usage.
Chapter 16: Managing Your Query Library Table 145
Deleting Queries, Dialogs, and Terms
Deleting Queries, Dialogs, and Terms
Accessing the Admin DIRECTORY OF QUERIES AND TERMS
reading this section.
To view the query, dialog, or term before deleting it, position the cursor next to the query, dialog, or term name, and press <PF4> EDIT. CA Dataquery then displays the member to be deleted on the Editor panel. Queries, dialogs and terms can also be deleted from the Editor panel.
To delete a query, dialog, or term, access the Administrative DIRECTORY OF QUERIES
AND TERMS panel, and position the cursor on the line of the query, dialog, or term that you want to delete and press <PF6> DELETE.
Caution Make sure that the cursor is on the line of the query that you want to delete. If you accidentally delete the wrong item you have to re-create it.
Note: If the query, dialog, or term has been viewed and deleted from the Editor panel, and you wish to undo the delete, you can resave the query, dialog, or term by doing the following:
1. Pressing <PF4> SAVE from the Editor panel.
2. Entering EDIT * or EDIT ACTIVE-QUERY on the command line and pressing Enter to see if the query, dialog, or term is still active.
If it is active you have saved the query, dialog, or term that you just deleted. You must execute this sequence of functions right after the delete. A query remains active until another query is edited or executed.
Changing the Extended Attributes of a Query, Dialog or Term
When a user changes job responsibilities or leaves your company, you can retain that user's queries, dialogs or terms for company use and you can assign a new owner/author, status, or groups to the query, dialog, or term.
Background
If your site chooses partitioning of the Query Library, the LIBRARY option is limited by the groups assigned to the CA Dataquery Administrator. If the Administrator has group values, only those queries, dialogs or terms assigned to the same group values as the
Administrator's can be accessed. If the Administrator's groups are blank, he has access to all queries. (To edit a member belonging to another user, you must select it from the
Administrative Directory. To edit a private member, first change its status to public.
While you can edit a private member, you cannot update it.)
146 Administration Guide
Deleting Queries, Dialogs, and Terms
Access
On the Admin DIRECTORY OF QUERIES AND TERMS panel, locate the query, dialog, or term you wish to change. Position the cursor beside that item and press <PF10>
EXTENDED DEFINITIONS. CA Dataquery displays the Administrative Extended Attributes panel.
Action
When you have completed all the fields on the Directory Extended Attributes panel to your satisfaction, press <PF4> SAVE to save your input. CA Dataquery makes these changes effective immediately.
A sample Administrative Extended Attributes panel displaying the fields and their values follows:
Administrative Extended Attributes (DQKB0)
=>
PRESS ENTER TO PREVIEW THE RESULTS OF ANY CHANGES
------------------------------------------------------------------------DQKB0
DATAQUERY: ADMINISTRATIVE EXTENDED ATTRIBUTES
-----------------------------------------------------------------------------
NAME: TYPE:
ATED
DESCRIPTION: ____________________________________________________________
AUTHOR: ________________________________
STATUS: _______ (PUBLIC or PRIVATE)
GROUPS: _______________ _______________ _______________
AUTHOR GROUPS _______________ _______________ _______________
AUTHOR RECORD ON OPERATOR FILE: YES NO
AUTHOR AND QUERY GROUPS DO NOT AGREE
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> UNUSED <PF4> SAVE
Chapter 16: Managing Your Query Library Table 147
Deleting Queries, Dialogs, and Terms
A list of the fields and their descriptions on the Administrative Extended Attributes panel follows:
Panel Description
NAME
Name assigned to this dialog, term, or query. To change the name, you must access this dialog, term, or query through the Editor panel.
TYPE
Specification of type as either query, term, or dialog. To change the type, you must access this dialog, term, or query through the Editor panel.
DESCRIPTION
Brief informational statement about this query, term, or dialog. To change the description, access this item through the Editor panel.
AUTHOR
Name of the owner of this query, dialog, or term. You can change this value by overtyping the displayed name.
STATUS
Specification of the status as PUBLIC or PRIVATE for this query, dialog, or term.
PUBLIC status gives all users within the same groups access to this query, dialog, or term, if the System Option Table parameter QRYGRPS=YES. If QRYGRPS=NO, group assignments are ignored by CA Dataquery. PRIVATE status limits access to the owner/author. You can reassign the status by typing over the displayed status value.
GROUPS
Names of the groups which are permitted access to this query, dialog, or term in the order of Group Level 1, Group Level 2, Group Level 3. Type over any displayed names as needed.
AUTHOR GROUPS
Names of the author's groups in the order of:
■
■
■
Group Level 1
Group Level 2
Group Level 3
The AUTHOR GROUP and the GROUPS values are not required to be identical.
Assure that group assignments meet your company's security standards as defined
by your Security Administrator and explained in
Assigning Group Levels
page 232).
148 Administration Guide
Performing Query Table Maintenance (DQLIBRMT)
AUTHOR RECORD ON OPERATOR FILE
YES is the CA Dataquery indicator that this author is a valid user in the CA Dataquery system. NO tells you that CA Dataquery does not have this author listed as a current user. We suggest that you to have all queries, dialogs, and terms assigned to existing users.
AUTHOR AND QUERY GROUPS
AGREE shows that the groups listed in the GROUPS field and the groups listed in the
AUTHOR GROUPS field are matching. NO indicates that these two fields do not have the same groups listed for both fields. Assure that group assignments meet your company's security standards as defined by your Security Administrator.
Performing Query Table Maintenance (DQLIBRMT)
Use the DQLIBRMT utility to perform the following maintenance tasks on the Query
Library Table:
■
Delete all or selected members for selected users, or groups.
■
Back up all queries, dialogs, terms, JCL, and PROC members or selected members from the Query Library Table to tape or disk.
Note: You can select members for deletion and backups by group, date or user, but not a combination of the three.
■
■
Restore all or selected members to the Query Library Table from a tape or disk file.
This allows selected queries to be moved from one system to another, such as from a test system to a production system.
Add a member from SYSIN in z/OS or SYSIPT in z/VSE.
Note: Do not use DQLIBRMT as a system backup. You can back up only queries, dialogs, terms, JCL, and PROC members. Conditions and restrictions are not backed up. To back up every Query Library Table member, use the DBUTLTY BACKUP function. See the CA Datacom/DB DBUTLTY Reference Guide for details.
Print Reports
The DQLIBRMT utility can be used to print maintenance reports that provide the following types of information:
■
Directory report lists selected user's query and type.
■
Query Text report shows selected user's query text, or JCL.
■
Query Utility report shows maintenance functions per query.
■
Status report lists any errors that occur during query maintenance.
Chapter 16: Managing Your Query Library Table 149
Performing Query Table Maintenance (DQLIBRMT)
The CA Dataquery Query Library Table (DQQ), stores queries, dialogs, terms, PROCs, JCL members, conditions, and restrictions. CA Dataquery controls additions and modifications of these members and definitions in the Query Library Table in the online environment. The Query Utility and Status Listing reports are created while the maintenance functions are being performed. The Directory and Query Text report functions can be run at any time. They are not dependent upon the performance of the maintenance functions.
Use the DQLIBRMT utility to back up, restore, or delete Query Library Table members selectively. For example, whenever a CA Dataquery user leaves the company or is transferred, run a Query Text report to view the user's Query Library Table members.
Decide to reassign or delete the Query Library Table members.
Utility Maintenance Control Statements
Use the following maintenance control statements to identify the maintenance functions to be performed by DQLIBRMT. A maximum of 60 report and maintenance control statements are allowed.
SIGN/ON
(Required) Specifies the user ID and password. Only one SIGN/ON statement is allowed and it must be the first statement in the job stream.
BACKUP
(Optional) Copies specified members on the Query Library Table to a sequential tape or disk file. Multiple backup statements are allowed, but all members to be backed up are written to one backup data set.
RESTORE
(Optional) Adds members to the Query Library Table from a sequential tape or disk file created using the DQLIBRMT backup facility. Only one RESTORE statement is permitted per run. All records on input are restored to the Query Library Table using the user from the same option as the control statement. If the control statement member option is used, only that member on the input file is restored.
ADD
(Optional) Adds a query, dialog, term, PROC, or JCL to the Query Library Table for the specified users, dates or groups. Supply the text of the item being added on multiple lines following the ADD statement.
REMOVE
(Optional) Removes queries, dialogs, terms, PROCs, or JCL from the Query Library
Table for the specified users, dates or groups. Multiple REMOVE statements can be used. Only one user can be named on each REMOVE statement.
150 Administration Guide
Performing Query Table Maintenance (DQLIBRMT)
Maintenance on the Query Library Table is performed before a REPORT control statement, even if the REPORT control statement appears before a maintenance control statement. If you want a report to reflect the state of the table before any maintenance, execute the REPORT control statement in a separate job step, before executing any type of maintenance on the table.
Control Statement Format
All control statement types are formatted as follows:
When adding a member to the query library, the member to be added is supplied by one or more 80-byte input statements following the ADD statement. A DQLIBRMT control statement in column 1 is interpreted as end of query text input. Therefore, no statement containing text to be added should begin with a DQLIBRMT control type in column 1, such as SIGN/ON, REPORT, RESTORE, BACKUP, REMOVE, ADD, or USER.
1-10
Identifies the type of control statement. Valid entries are: BACKUP, RESTORE, ADD,
REMOVE. Left justify the value with trailing blanks. For BACKUP and REMOVE you must insert 4 blanks, for RESTORE insert 3 blanks before the option keyword.
11-72
Specifies the option key words and their values. You can enter the options in any order. Use the following format:
┌──────────────────────────────┐
►►─ STATEMENT ─▼─ OPTION= value
,MEMBER= value
, ─┴───────────────────────────────►◄
There are no spaces in the keyword portion of the statement. An equal sign (=) separates an option from its value and a comma (,) separates options. Do not enter options past column 72. Following is a sample input statement:
----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+
BACKUP NAME=userid,MEMBER=dqqmem
Select any of the following options:
STATUS=
Designates which type of member is to be processed. This option can appear on all statements except the REMOVE statement.
Valid Entries:
PUBLIC, PRIVATE, or ALL
Default Value:
ALL
Chapter 16: Managing Your Query Library Table 151
Performing Query Table Maintenance (DQLIBRMT)
MEMBER=
Designates the QUERY, DIALOG, or JCL member name. If specified, the maintenance function affects all library members of this name that meet selection criteria (user
ID, groups, or date, status, and type) and those that the signon statement user is permitted to access. To avoid duplication, if there are multiple members of the same name on the restore input file, groups and status keywords must be used to distinguish which is to be restored to the file with the userid on the NAME= keyword.
This option can appear on all functions. Do not use if TYPE=JCL.
Valid Entries:
A 1- to 15-character Query Library Table member name.
Default Value:
(No default)
TYPE=
Specifies the type of Query Library Table member to be processed by the maintenance function.
Valid Entries:
TERM, SQL, SQLD, QUERY, DIALOG, PROC, or ALL. Use JCL for BACKUP,
RESTORE, and REMOVE only if DATE= and MEMBER= are not used.
Default Value:
ALL
GROUPS=
List of groups used to select members for processing. Is edited against SIGN/ON user's groups.
Valid Entries:
One to three group names of 1 to 15 characters separated by commas.
Default Value:
(No default)
NAME=
Designates the USER ID. Used to select members for processing on Backup and
Restore requests. This option is required for the USER and RESTORE statements. On
Restore requests, this userid will be assigned to all queries selected for Restore.
Valid Entries:
A 1- to 32-character user ID.
Default Value:
(No default)
152 Administration Guide
Performing Query Table Maintenance (DQLIBRMT)
DATE=
Date the query was last accessed in MM/DD/YY format. Used to select members for processing. BACKUP, RESTORE, or REMOVE will honor anything equal to or prior to the date specified here. Do not use if TYPE=JCL.
Valid Entries:
A valid access date.
Default Value:
(No default)
FILE=
(z/VSE only) Specifies whether the input table for RESTORE or the output table for
BACKUP is to reside on TAPE or DISK.
Valid Entries:
DISK or TAPE
Default Value:
(No default)
Control Statement Options
The following list describes valid options for each statement:
Control
Statement
Function
Valid Options
(Use only 1 of italicized options)
Required
YES/NO
ADD
BACKUP
RESTORE
NAME
MEMBER
TYPE
STATUS
GROUPS
NAME
GROUPS
DATE
STATUS
MEMBER
FILE (z/VSE only)
TYPE
NAME
GROUPS
MEMBER
FILE (z/VSE only)
STATUS
YES
YES
YES
NO
NO
YES
NO
YES
YES
NO
NO
NO
YES
NO
NO
YES
NO
Default Value
No default
No default
DQL Query
Private
No groups
No default
ALL
ALL
ALL
ALL MEMBERS
No default
ALL
No default
ALL
ALL MEMBERS
NONE
ALL
Chapter 16: Managing Your Query Library Table 153
Performing Query Table Maintenance (DQLIBRMT)
Control
Statement
Function
REMOVE
Valid Options
(Use only 1 of italicized options)
NAME
GROUPS
MEMBER
TYPE
DATE
Required
YES/NO
YES
YES
NO
NO
YES
Default Value
No default
No default
ALL MEMBERS
ALL
No default
Note: Options in italics are mutually exclusive, within their respective functions. You can execute a BACKUP with the NAME, or GROUPS, or DATE option. One of the three is required, but not a combination of the three options; they are mutually exclusive.
Sample Control Statements
Following are sample control statements of BACKUP, RESTORE, and REMOVE functions and an explanation of what they do.
BACKUP
----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+
BACKUP GROUPS=ALL
This BACKUP control statement backs up all queries, dialogs, terms, JCL and PROC members on the Query Library Table, provided that the user on the SIGN/ON statement has all blanks for the three group levels. Remember that DQLIBRMT does not backup conditions and restrictions.
Back up all of these members and restore them to a user ID with blank groups, for a backup source other than the system backups that your site performs.
----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+
BACKUP MEMBER=ACCTPRT,GROUPS=CAI,DALLAS,ACCT
This BACKUP control statement backs up the member name ACCTPRT with the assigned groups of CAI,DALLAS,ACCT. This is a selective backup and does not backup any other members.
RESTORE
----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+
RESTORE NAME=DAVIS,MEMBER=NATACCT,STATUS=PRIVATE
This RESTORE control statement restores the member name NATACCT with a status of
PRIVATE from the input table, to the user ID DAVIS. This is a selective restore.
154 Administration Guide
Performing Query Table Maintenance (DQLIBRMT)
REMOVE
----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+
REMOVE DATE=01/01/92
This REMOVE control statement removes all members that were created prior to and not accessed since 01/01/92. This is a selective remove that can be performed if you want to remove members that have not been accessed in a long time.
QRYGRPS= Option
If the QRYGRPS= option on the System Option Table is YES, the user on the SIGN/ON statement is able to BACKUP, RESTORE, or REMOVE only those members that have the same groups.
If QRYGRPS=YES and DATE is used, CA Dataquery ignores the group assignment. If
QRYGRPS=YES and NAME is used, the assignments are honored.
For example, User 1 has the groups DALLAS, DATACOM, DATAQUERY. The QRYGRPS= option is YES, so User 1 would only be able to access those members that had the same groups assigned to them. If User 1 had the groups DALLAS with Group Level 2 and Group
Level 3 blank, all members with Group Level 1 DALLAS would be accessible no matter what Group Level 2 and Group Level 3 are.
If User 1 had group levels 1, 2 and 3 all blank, he could access any query for maintenance. You can RESTORE queries that belong to specific groups to a user ID that is not on the DQU table. Before executing the RESTORE, CA Dataquery assigns blank groups to this user when it checks the DQU table for this user. The blank groups make these queries available to all users or groups of users.
For example, there can be some CA Dataquery users who leave the company, who are in different groups and have written queries that you want the rest of the CA Dataquery users to access. If you RESTORE the queries of the users who have left the company to a new user ID with no groups specified, these queries now can be accessed by any CA
Dataquery user.
Chapter 16: Managing Your Query Library Table 155
Performing Query Table Maintenance (DQLIBRMT)
Sample Job Stream
Following is an example of a report job stream:
SIGN/ON userid PASSWORD password
REPORT TITLE=DIRECTORY
USER NAME=SPECIALJOB
USER NAME=VORTEX
REPORT TITLE=QUERYTEXT,STATUS=PRIVATE
USER NAME=EMPLOY
USER NAME=ORTHO
USER NAME=SAM
Note: If you do not supply a USER control statement, the reports reflect all of the users.
Following is an example of a maintenance job stream:
SIGN/ON userid PASSWORD password
RESTORE NAME=OPERID,STATUS=PUBLIC
REMOVE NAME=DEPARTED,MEMBER=QUERY2
BACKUP NAME=OPERONE,MEMBER=SPECIAL,FILE=TAPE
BACKUP NAME=OPERTEN,FILE=TAPE
Utility Report Control Statements
Use the report control statements to identify the report functions to be performed by
DQLIBRMT. A maximum of 60 report and maintenance control statements is allowed.
There are three types of report control statements:
SIGN/ON
(Required) Specifies the user ID and password. Only one SIGN/ON statement is allowed and it must be the first statement in the job stream.
REPORT
Selects the type of report to be produced with this run. This is required only if
Query Text or Directory reports are needed. Multiple statements are allowed. CA
Dataquery produces maintenance reports only if BACKUP, REMOVE or RESTORE is requested.
156 Administration Guide
Performing Query Table Maintenance (DQLIBRMT)
USER
(Optional) Specifies a particular user to be included in the report. One or more
USER statements must follow each REPORT statement if you have any. Each USER statement can include options that override those specified by the REPORT statements.
■
■
■
When no USER statements are input, selection for all users is assumed.
When multiple USER statements follow one REPORT statement, REPORT remains in effect until another REPORT statement is encountered in the job stream. A
SIGN/ON remains in effect throughout a single execution of DQLIBRMT. Another
SIGN/ON statement is accepted only if it is the first statement in a different execution of DQLIBRMT. An example of the sequencing is:
SIGN/ON
REPORT
USER
■
■
■
REPORT
USER
USER
SIGN/ON Control Statement
The SIGN/ON control statement is formatted as follows:
►►─ SIGN/ON ─ userid
─ PASSWORD ─ password
───────────────────────────────────►◄
userid
Specifies the user ID of the person executing the DQLIBRMT utility.
Valid Entries:
A 1- to 32-character user ID.
Default Value:
(No default)
password
Specifies the password of the person executing the DQLIBRMT utility.
Valid Entries:
A 1- to 9-character password.
Default Value:
(No default)
Chapter 16: Managing Your Query Library Table 157
Performing Query Table Maintenance (DQLIBRMT)
REPORT Control Statement
Format each REPORT control statement as follows:
1-10
Identifies the type of control statement. The only valid entry is REPORT. Left justify the value with trailing blanks as necessary.
11-72
Specifies the option keywords and their values. You can enter the options in any order. (Available options are listed below.)
Use one of the following formats:
┌──────────────────────────────────────────────────┐
►►─ REPORT ─▼─ TITLE=DIRECTORY<,
►►─ REPORT ─▼─ TITLE=QUERYTEXT<, option=value
┌──────────────────────────────────────────────────┐ option=value
><,
><, option=value option=value
>, ─┴──────────────►◄
>, ─┴──────────────►◄
There are no spaces in the keyword portion of the statement. An equal sign (=) separates an option type from its value, and a comma separates the options. Do not enter options past column 72. Following is an example:
----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+
REPORT TITLE=QUERYTEXT,GROUPS=ALL,STATUS=PUBLIC
Required Keyword
TITLE=
Designates which type of report is being requested. This option is required on
REPORT statements.
Valid Entries:
DIRECTORY (for a statistics report on the queries owned by each user)
QUERYTEXT (for a report on the text of each query)
Default Value:
(No default)
Optional Keywords
GROUPS=
Designates the hierarchical groups that the user can be assigned to. The order must be Group Level 1, Group Level 2, Group Level 3.
Valid Entries:
A 1- to 15-character group name
Default Value:
ALL
158 Administration Guide
Performing Query Table Maintenance (DQLIBRMT)
STATUS=
Designates which type of queries are to be processed. This option can appear on
REPORT, BACKUP and RESTORE statements.
Note: If QRYGRPS=YES, the STATUS= option is ignored if the USER control statement is used, and only members marked PRIVATE are accessed.
Valid Entries:
PRIVATE, PUBLIC, or ALL
Default Value:
ALL
TYPE=
Specifies the type of Query Library Table member to be processed by the maintenance function.
Valid Entries:
TERM, SQL, SQLD, QUERY, DIALOG, PROC, REPORT, ALL, or JCL (for BACKUP,
RESTORE, and REMOVE)
Default Value:
ALL
USER Control Statement
Format each USER control statement as follows:
1-10
Identifies the type of control statement. The only valid entry is USER. Left justify the value with trailing blanks as necessary.
11-37
Specifies the NAME= keyword and its values.
Use the following format:
►►─ USER ─ NAME= user-id
──────────────────────────────────────────────────────►◄
NAME=
Designates the user's ID. This option is required on the USER statement.
Valid Entries:
A 1- to 32-character user ID
Default Value:
(No default)
Chapter 16: Managing Your Query Library Table 159
Performing Query Table Maintenance (DQLIBRMT)
Directory Information
The Directory report can be run at anytime without performing any type of maintenance on the Query Library Table. If you have a user that has left the company, you could run a
Directory report on this user to find out what the user had in the Query Library Table.
This report lists both SQL and DQL Language queries. SQL queries are specified in the
TYPE= option as SQL. DQL Language queries are specified as QUERY in the TYPE= option.
The query type is displayed on the report.
To run a Directory report, you need to add a SIGN/ON and a REPORT control statement to your JCL member as follows.
Sample z/OS JCL
//jobname See Preparing JCL for Batch CA Dataquery Utilities.
//S1 EXEC PGM=DQLIBRMT
//STEPLIB See Preparing JCL for Batch CA Dataquery Utilities.
//SYSUDUMP DD SYSOUT=*
//SNAPER DD SYSOUT=*
//SYSPRINT DD SYSOUT=* Print Output
//SYSIN DD * Command input
SIGN/ON userid PASSWORD password
REPORT TITLE=DIRECTORY
/*
//
160 Administration Guide
Performing Query Table Maintenance (DQLIBRMT)
Sample z/VSE JCL
* $$ JOB ... See Preparing JCL for Batch CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// EXEC DQLIBRMT
SIGN/ON userid PASSWORD password
REPORT TITLE=DIRECTORY
/*
/&
* $$ EOJ
Sample Report
Following is an example of the CA Dataquery Query Maintenance Report showing directory information:
Date: mm/dd/ccyy *********************************************************************** Page: 1
* CA Dataquery for CA Datacom *
Time: hh.mm.ss * Query Maintenance Report * Version: 14.0
* Copyright © 1990-2011 CA. All rights reserved. *
DQ Base 3 *********************************************************************** DD Base 2
QUERY DIRECTORY REPORT
REPORT FOR INPUT RECORD: USER NAME=DQUSER 00000618
* MEMBER-NAME * *TYPE* *STA* *----------- AUTHOR -----------* *-- GROUP 1 --* *-- GROUP 2 --* *-- GROUP 3 --*
DATE-ADDED LAST-USED *---------------------- DESCRIPTION -----------------------* testupshift QUERY PVT DQUSER
10/03/98 testing upshift for language
A QUERY PVT DQUSER DALLAS DATACOM DATAQUERY
07/11/98
ABC1 QUERY PVT DQUSER DALLAS DATACOM DATAQUERY
10/02/97 07/12/98
ADR-CUST-RECS QUERY PUB DQUSER DALLAS DATACOM DATAQUERY
07/26/02 09/13/02 ADR-CUST-RECS FOR TEXAS
ASSOC-ERROR QUERY PUB DQUSER DALLAS DATACOM DATAQUERY
06/08/98 08/12/98 QUERY HAS VALIDATION ERROR
A10 JCL PVT DQUSER
05/13/98 05/13/98 JCL
A11 JCL PVT DQUSER
05/13/98 JCL
A12 JCL PVT DQUSER
05/13/98 05/13/98 JCL
A13 JCL PVT DQUSER
05/13/98 JCL
A14 JCL PVT DQUSER
05/13/98 JCL
A15 JCL PVT DQUSER
05/13/98 JCL
Chapter 16: Managing Your Query Library Table 161
Performing Query Table Maintenance (DQLIBRMT)
Following is an explanation of the directory information found on the report:
Report Description
MEMBER-NAME
Lists each member affected by the Query Library Table maintenance.
TYPE
STA
Shows whether the member named is a query, dialog, JCL member, PROC, or term.
Shows whether the member is public (PUB) or private (PVT).
AUTHOR
Shows the name of the member's author.
DESCRIPTION
Gives a description of the member, if one exists.
DATE-ADDED
Gives the date the query was created or copied.
LAST-USED
Gives the last date the query was used.
GROUPS
Gives the groups associated with the particular Query Library Table member printed.
162 Administration Guide
Performing Query Table Maintenance (DQLIBRMT)
Query Text Information
The Query Text report can also be run at anytime and does not require any type of maintenance to be performed to the Query Library Table. Use the Query Text report to view the text of the Query Library Table members that were on the user's online table.
To run a Query Text report, add a SIGN/ON and a REPORT control statement to your JCL member as follows.
Sample z/OS JCL
//jobname See Preparing JCL for Batch CA Dataquery Utilities.
//STEP1 EXEC PGM=DQLIBRMT
//STEPLIB See Preparing JCL for Batch CA Dataquery Utilities.
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=* Print Output
//SYSIN DD * Command input
SIGN/ON userid PASSWORD password
REPORT TITLE=QUERYTEXT
/*
//
Chapter 16: Managing Your Query Library Table 163
Performing Query Table Maintenance (DQLIBRMT)
Sample z/VSE JCL
* $$ JOB ... See Preparing JCL for Batch CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// EXEC DQLIBRMT
SIGN/ON userid PASSWORD password
REPORT TITLE=QUERYTEXT
/*
/&
* $$ EOJ
Note: You can use more than one REPORT control statement in your JCL member. Each
REPORT control statement should occur on a separate line.
164 Administration Guide
Performing Query Table Maintenance (DQLIBRMT)
Sample Report
Following is an example of the CA Dataquery Query Maintenance Report showing Query
Text information:
Date: mm/dd/ccyy *********************************************************************** Page: 1
* CA Dataquery for CA Datacom *
Time: hh.mm.ss * Query Maintenance Report * Version: 14.0
* Copyright © 1990-2011 CA. All rights reserved. *
DQ Base 3 *********************************************************************** DD Base 2
QUERY TEXT REPORT
REPORT FOR INPUT RECORD: USER NAME=DQUSER 00000603
* MEMBER-NAME * *TYPE* *STA* *----------- AUTHOR -----------* *-- GROUP 1 --* *-- GROUP 2 --* *-- GROUP 3 --*
*--------------------------------- QUERY-TEXT ---------------------------------* testupshift QUERY PVT DQUSER
find all company
------------------------------------------------------------------------------------------------------------------------
A QUERY PVT DQUSER DALLAS DATACOM DATAQUERY
TESTING
------------------------------------------------------------------------------------------------------------------------
ABC1 QUERY PVT DQUSER DALLAS DATACOM DATAQUERY
FIND 50 PAYROLL
WITH YTD-WAGES > 5000
RELATED BY NUMBER TO PERSONNEL
SORT BY (STATE-ADDRESS) AND (ZIP-CODE-LOC) AND PAYROLL (ACTIVITY-STATUS)
PRINT PERSONNEL STATE-ADDRESS
ZIP-CODE-LOC
PAYROLL ACTIVITY-STATUS
(YTD-COMMISSION)
(YTD-WAGES)
(CURRENT-RATE)
(YTD-TAX)
ACTIVITY-CODE
NUMBER
FROM PERSONNEL
SOCIAL-SECURITY
Following is an explanation of the query text information found on the report:
Report Description
MEMBER-NAME
Lists the name of the member.
TYPE
STA
Shows whether the member is a query, dialog, JCL member, PROC, or term.
Shows whether the member is public (PUB) or private (PVT).
Chapter 16: Managing Your Query Library Table 165
Performing Query Table Maintenance (DQLIBRMT)
AUTHOR
Shows the name of the member's owner.
QUERY-TEXT
Gives a reproduction of each member.
GROUPS
Gives the groups associated with each Query Library Table member printed.
Query Utility Information
The Query Utility report is generated automatically for BACKUP, RESTORE, and REMOVE.
This report shows the type of maintenance function that was performed by DQLIBRMT for the Query Library Table member named.
Sample Report
Following is an example of the CA Dataquery Query Maintenance Report showing query utility information:
Date: mm/dd/ccyy *********************************************************************** Page: 1
* CA Dataquery for CA Datacom *
Time: hh.mm.ss * Query Maintenance Report * Version: 14.0
* Copyright © 1990-2011 CA. All rights reserved. *
DQ Base 3 *********************************************************************** DD Base 2
QUERY UTILITY REPORT
* MEMBER-NAME * *TYPE* *STA* *----------- AUTHOR -----------* *-- GROUP 1 --* *-- GROUP 2 --* *-- GROUP 3 --*
FUNCTION *---------------------- DESCRIPTION -----------------------* testupshift QUERY PVT DQUSER
BACKUP testing upshift for language
CONTROL STATEMENT: BACKUP NAME=DQUSER 00000588
------------------------------------------------------------------------------------------------------------------------
A QUERY PVT DQUSER DALLAS DATACOM DATAQUERY
BACKUP
CONTROL STATEMENT: BACKUP NAME=DQUSER 00000588
------------------------------------------------------------------------------------------------------------------------
ABC1 QUERY PVT DQUSER DALLAS DATACOM DATAQUERY
BACKUP
CONTROL STATEMENT: BACKUP NAME=DQUSER 00000588
------------------------------------------------------------------------------------------------------------------------
ADR-CUST-RECS QUERY PUB DQUSER DALLAS DATACOM DATAQUERY
BACKUP ADR-CUST-RECS FOR TEXAS
CONTROL STATEMENT: BACKUP NAME=DQUSER 00000588
------------------------------------------------------------------------------------------------------------------------
ASSOC-ERROR QUERY PUB DQUSER DALLAS DATACOM DATAQUERY
BACKUP QUERY HAS VALIDATION ERROR
CONTROL STATEMENT: BACKUP NAME=DQUSER 00000588
------------------------------------------------------------------------------------------------------------------------
FNAME1 QUERY PVT DQUSER DALLAS DATACOM DATAQUERY
BACKUP
CONTROL STATEMENT: BACKUP NAME=DQUSER 00000588
166 Administration Guide
Performing Query Table Maintenance (DQLIBRMT)
Following is an explanation of the log information found on the report:
Report Description
FUNCTION
Shows the type of maintenance function performed by DQLIBMT for the query named.
BACKUP
The query has been copied to a sequential tape or disk file.
REMOVE
The query has been removed from the Query Library Table for the named user.
RESTORE
The query has been added to the Query Library Table from a backup tape or disk file.
MEMBER-NAME
Identifies the member on which maintenance was performed.
TYPE
STA
Shows whether the member is a query, dialog, JCL member, PROC, term.
Shows whether the member named is public (PUB) or private (PVT). Under PUB or
PVT is the item CONTROL STATEMENT, which shows the job control statement used to perform the maintenance function.
AUTHOR
Identifies the query's author.
DESCRIPTION
Provides the member description, if any, attached by the author.
GROUPS
Lists the groups associated with each Query Library Table member that is printed.
Chapter 16: Managing Your Query Library Table 167
Performing Query Table Maintenance (DQLIBRMT)
Status Report Information
DQLIBRMT produces a status report listing. The listing provides a record of each input request and a report of the number of input request records.
Sample Report
Following is an example.
Date: mm/dd/ccyy *********************************************************************** Page: 1
* CA Dataquery for CA Datacom *
Time: hh.mm.ss * Query Maintenance Report * Version: 14.0
* Copyright © 1990-2011 CA. All rights reserved. *
DQ Base 3 *********************************************************************** DD Base 2
STATUS REPORT
*--------DISPOSITION------------------* *-----------------------INPUT RECORD-------------------------------------------*
OK REPORT TITLE=DIRECTORY 00000617
OK USER NAME=DQUSER 00000618
REPORT COMPLETE 002 INPUT REQUEST RECORDS PROCESSED
Following is a description of the items on the status report.
Report Description
DISPOSITION
Prints a copy of the error message. See the CA Dataquery Message Reference Guide for recovery instructions. OK means no error occurred for this input record.
INPUT RECORD
Prints a copy of the input record control statement.
JCL Examples
You can use the following examples to execute DQLIBRMT.
The DQLIBRMT Utility control statements process the maintenance functions BACKUP,
RESTORE, and REMOVE before processing any REPORT control statements. If you put a
REPORT control statement before a BACKUP control statement in your job stream,
DQLIBRMT processes the BACKUP control statement first. The data from the BACKUP control statement is not reflected on the report that was created by the preceding
REPORT control statement.
168 Administration Guide
Performing Query Table Maintenance (DQLIBRMT)
Sample z/OS JCL
//jobname See Preparing JCL for Batch CA Dataquery Utilities.
// EXEC PGM=DQLIBRMT
//STEPLIB See Preparing JCL for Batch CA Dataquery Utilities.
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=* Print Output
A//DQBKPFIL DD DSN=... See Preparing JCL for Batch CA Dataquery Utilities.
//DQRSTFIL DD DSN=... See Preparing JCL for Batch CA Dataquery Utilities.
//SYSIN DD * Command input
(DQLIBRMT Utility Control Statements)
/*
//
A
DQBKPFIL is an output data set for a DQLIBRMT backup of Query Library members.
DQBKPFIL is a sequential file that can reside on tape or disk. This statement is needed only in JCL specifying a DQLIBRMT backup.
DQRSTFIL is an input data set of Query Library members to be added to the Query
Library Table as requested by a DQLIBRMT RESTORE control statement. This data set must have been created by a previous execution of DQLIBRMT and is needed only if a restore is requested.
Chapter 16: Managing Your Query Library Table 169
Performing Query Table Maintenance (DQLIBRMT)
Sample z/VSE JCL
* $$ JOB ... See Preparing JCL for Batch CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// ASSGN SYS010,X'...' See Preparing JCL for Batch CA Dataquery Utilities.
A
// TLBL DQQBKPT
// EXEC DQLIBRMT
(DQLIBRMT Utility Control Statements)
/*
/&
* $$ EOJ
A
DQQBKPT is an output tape data set for a DQLIBRMT backup of Query Library members as requested by BACKUP control statements. This data set must be on
SYS010 and is needed only if tape backup is requested. If disk backup is requested, use the DQQBKPD control statement.
DQQBKPD is an output disk data set for a DQLIBRMT backup of Query Library members as requested by backup control statements. This data set must be on
SYS011 and is needed only if disk backup is requested.
DQQRSTT is an input tape data set of Query Library members created by a previous execution of DQLIBRMT. The members are to be added to the Query Library Table as requested by the DQLIBRMT RESTORE control statement. This data set must be on SYS011 and is needed only if a restore from tape is requested. If restore from disk is requested, use DQQRSTD.
DQQRSTD is an input disk data set of Query Library members created by a previous execution of DQLIBRMT. The members are to be added to the Query Library Table as requested by the DQLIBRMT RESTORE control statement. This data set must be on SYS011 and is needed only if restore from disk is requested.
170 Administration Guide
Chapter 17: Special Considerations for DQL
Language Queries
Another administrative function is to help the user write effective DQL Language queries. This chapter includes the following topics:
■
Establishing data selection status
■
Viewing query statistics
■
Defining query performance
■
Including User-Defined functions to perform mathematical calculations on a query's data
Your understanding of these topics will enable you to help the CA Dataquery user to write more efficient queries.
Data Selection Status
When using DQL Language, if your query or dialog runs longer than permitted by the values specified in the MXREQ and MXTLR fields on the User Table Maintenance Menu,
CA Dataquery displays the Data Selection Status panel. An example follows:
Data Selection Status (DQE50)
=>
Press the appropriate PF key.
------------------------------------------------------------------------DQE50
DATAQUERY: DATA SELECTION STATUS
------------------------------------------------------------------
-----------
Number of records selected =>
Press PF3 to end SELECTION and report on only the records selected so far.
Press PF4 to continue execution of the SELECTION Step.
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> END SELECT <PF4> CONTINUE
Chapter 17: Special Considerations for DQL Language Queries 171
Estimated Statistics
Panel Description
The Data Selection Status panel shows how many rows have been selected by the execution of the FIND statement in your query or dialog up to this point in the execution of the query. The panel appears because CA Dataquery has paused during execution of your query so that you can indicate whether you want to end the selection step, continue the query selection step, or return to the Online Execution panel.
PF Keys
Key
CLEAR
<PF1> HELP
Objective
Return to Main Menu.
Display HELP panel.
<PF2> RETURN
<PF3> END SELECT
<PF4>CONTINUE
Return to previous panel.
End the row selection, but continue executing the query or dialog.
Continue the query or dialog selection.
Result
Returns to the Main Menu.
CA Dataquery displays the
Help panel.
Returns to previous panel, or
Main Menu.
CA Dataquery executes the remainder of the query or dialog.
CA Dataquery continues to select rows.
Estimated Statistics
The Option Table parameter, MAXIO, allows a site to specify an I/O threshold giving a number of estimated I/Os. When this number is exceeded by the number of I/Os estimated to process a DQL FIND statement, the following new panel will be displayed.
The user has the option to continue <PF4> CONTINUE or not <PF2> RETURN. The I/O threshold may be set for an individual user using the online User Table Maintenance.
The user's threshold value if any would take precedence over the System Option Table value. The Estimated Statistics panel is displayed after optimization but before retrieving any data.
172 Administration Guide
Estimated Statistics
Estimated Statistics (DQMI0)
=>
Estimated statistics have exceeded maximum limits. To proceed with query:
press the PF4 key. To cancel execution of query; press the PF2 key.
------------------------------------------------------------------------DQMI0
DATAQUERY: ESTIMATED STATISTICS QUERY NAME: DEMOJOIN
-----------------------------------------------------------------------------
NUMBER REQUESTED: ALL
FIND TERMINATED BECAUSE: TOTAL ESTIMATED I/O EXCEEDS ESTIMATED MAX I/O
ESTIMATED
---------
TOTAL ESTIMATED ROWS: 24
TOTAL JOINS EXAMINED: 2
VALID JOINS EXAMINED: 2
TOTAL ESTIMATED I/O 26 **
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> CONTINUE
Action
To continue and retrieve the rows, press <PF4> CONTINUE.
To stop, press <PF2> RETURN or <CLEAR>.
Panel Description
TOTAL ESTIMATED ROWS
Number of rows to be retrieved by the FIND.
TOTAL JOINS EXAMINED
Number of possible ways to join tables named in FIND.
VALID JOINS EXAMINED
Number of valid joins.
TOTAL ESTIMATED I/O
Estimated I/O to execute FIND - based on the lowest cost join.
Chapter 17: Special Considerations for DQL Language Queries 173
DQL Language FIND Statistics
DQL Language FIND Statistics
For a DQL Language query, <PF6> STATS displays the Find Statistics panel as shown in the following sample. The panel provides statistical information on the execution of your query or dialog.
Find Statistics (DQEF0)
=>
Current Dataquery FIND/SELECT Statistics.
------------------------------------------------------------------------DQEF0
DATAQUERY: FIND STATISTICS QUERY NAME:
-----------------------------------------------------------------------------
NUMBER REQUESTED: ALL COMPLETION DATE: 01/06/2000
NUMBER FOUND: 9 COMPLETION TIME: 15:37:40
FIND TERMINATED BECAUSE: NORMAL END OF SEARCH WAS REACHED
OVERALL OPTIMIZATION SEARCH
------- ------------ ------
ELAPSED TIME (SECONDS): 1 0 0
I/O EVENTS: 0 0 0
SELFR TOTAL: 0 0 0
SELNR TOTAL: 0 0
TOTAL BYTES: 0
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Panel Description
A brief explanation of the fields on the Find Statistics panel follows:
QUERY NAME:
Name of the query to which these statistics apply.
NUMBER REQUESTED:
Number of rows requested in your query.
NUMBER FOUND:
Number of rows found or counted in the database.
COMPLETION DATE:
Date that the search for this query ended.
COMPLETION TIME:
Time that the search for this query ended.
174 Administration Guide
DQL Language FIND Statistics
Error Messages
You may receive the following messages:
NORMAL END OF SEARCH WAS REACHED
The FIND process completed normally.
SITE I/O LIMIT EXCEEDED
The FIND exceeded the value set for the I/O limit in the System Option Table parameter SRCHLIM=. Either reduce the number of rows which CA Dataquery is to
FIND, or request that your CA Dataquery Administrator increase the value in the
SRCHLIM= System Option Table parameter so that your query can finish the FIND processing.
MAX WORK FILE BLOCKS EXCEEDED
The FNDBLKS= parameter for the user is too small. Consider increasing the value
specified for this user on the User Table Maintenance panel. See
Adding a New User
(see page 212) for more information.
MAX ELAPSED TIME EXCEEDED
The maximum time allowed for the processing of a query FIND has been exceeded.
Either simplify the FIND so that the FIND processing time is shorter or request that the CA Dataquery Administrator increase the maximum time allowed in the
MFTIME= System Option Table parameter.
FIND CANCELED FROM REQUESTING TERMINAL
This query has been canceled from the requesting user's terminal.
FIND CANCELED FROM ANOTHER TERMINAL
This query was canceled from another terminal.
ELAPSED TIME (SECONDS)
OVERALL
The overall time elapsed in seconds to process the FIND statement.
OPTIMIZATION
The process of determining the FIND strategy for searching the database efficiently.
SEARCH
The actual search time against the database for the FIND statement.
Chapter 17: Special Considerations for DQL Language Queries 175
DQL Language FIND Statistics
I/O EVENTS
OVERALL
The overall number of CA Datacom/DB physical I/O events for the processing of the
FIND statement.
OPTIMIZATION
The number of CA Datacom/DB physical I/O events used for determining the database search strategy.
SEARCH
The number of CA Datacom/DB physical I/O events used for the search of the database by the FIND statement.
SELFR TOTAL
OVERALL
The overall number of CA Datacom/DB Compound Boolean Selection SELFR (select first) commands that were issued to execute the FIND statement.
OPTIMIZATION
The number of CA Datacom/DB Compound Boolean Selection SELFR (select first) commands that were issued for determining the database search strategy.
SEARCH
The number of CA Datacom/DB Compound Boolean Selection SELFR (select first) commands that were issued for the search of the database by the FIND statement.
SELNR TOTAL
OVERALL
The overall number of CA Datacom/DB Compound Boolean Selection SELNR (select next) commands that were issued to execute the FIND statement.
OPTIMIZATION
(Nothing is printed under OPTIMIZATION.)
SEARCH
The number of CA Datacom/DB Compound Boolean Selection SELNR (select next) commands that were issued for the search of the database by the FIND statement.
176 Administration Guide
DQL Language FIND Statistics
TOTAL BYTES
OVERALL
The overall number of bytes that were required to hold the internal control blocks that CA Dataquery built to process the FIND statement.
OPTIMIZATION
(Nothing is printed under OPTIMIZATION.)
SEARCH
(Nothing is printed under SEARCH.)
Extended Statistics
The following statistics appear on this panel if the STALL command has been used:
TOTAL JOINS:
The number of times tables were joined during query processing.
VALID JOINS:
The number of joins that could be used. Valid joins never exceed total joins. The more tables there are involved, the smaller the percentage of joins that are valid.
CA Dataquery considers every possible join and chooses the optimum combination.
ESTIMATED I/O:
An estimate from the lowest cost join.
ESTIMATED ROWS:
An estimate from the lowest cost join.
Chapter 17: Special Considerations for DQL Language Queries 177
DQL Language FIND Statistics
Table Statistics
When the STALL command is used or when <PF6> STATS is pressed at any time after having used the STALL command, the following panel can be accessed by pressing <PF3>
TABLE STATISTICS during FIND STATISTICS display.
Find Statistics (DQEC0)
=>
Current Dataquery FIND/SELECT Statistics.
------------------------------------------------------------------------DQEC0
DATAQUERY: FIND STATISTICS QUERY NAME: PROGRAMS
-----------------------------------------------------------------------------
TNM-BID STRG NQ RELS RELO I/O E-I/O E-ROWS CARD RQAS KEY F-BUF
------- ----- -- ---- ---- ------- ------- ------- ------- ---- -------- -----
PGM- 2 336 N 5 N/A N/A N/A 72
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> OVERALL STATS
Action
Note the query statistics if a problem occurs during query execution and be prepared to report the information if you require assistance with problem resolution.
The FIND/SELECT Statistics panel appears when you display query output on your screen, press <PF6> STATS, and press <PF3> TABLE STATISTICS after the Query Statistics panel (DQEF0) appears. It provides further statistical information about query processing.
Panel Description
TNM-BID
Table name and database ID.
STRG
Length of permanent storage for this table, including the request area, RQA size, nonqualifying with list, and overhead. (CA Dataquery and the Compound Boolean
Selection facility of CA Datacom/DB dynamically handle the search optimization. CA
Dataquery uses predicates (a WITH in a DQL Mode query FIND statement) to build a
Compound Boolean Selection Request Qualification Area (RQA), converting the selection criteria in a query's statements into the Compound Boolean Selection format.)
178 Administration Guide
DQL Language FIND Statistics
NQ
Nonqualifying predicates.
RELS
Related subject, column, key or value.
RELO
Related object, column, or key.
I/O
Number of I/Os for this execution.
E-I/O and E-ROWS
Estimated I/O from Compound Boolean Selection and estimate calls for join optimization. E-I/O and E-ROWS apply to a single table. The values are calculated using the E-I/O and E-ROWS values for each table, the relative cardinalities of the tables, whether the related objects are indexed or not, and the number of rows requested in the query. The numbers shown are normally the values received from the Compound Boolean Selection Facility only for the first table listed on DQEC0.
The other tables have been adjusted based on relative cardinality, and so forth.
CARD
The number of rows on the table, if joining. The relative cardinality of the tables figures into join optimization.
RQAS
Shows whether a query is nearing the 9999 RQA limitation.
KEY
Means one of two things, depending on whether the name is followed by an R or a
G.
R indicates that Compound Boolean Selection used this key because it is a related object in the table and the ratio of table cardinalities indicated that the key might optimize the join.
G indicates that Compound Boolean Selection suggested using the key if executing in batch and only for the primary table in the search.
F-BUF
Storage used for buffering for nonqualifying predicates or cross-joined WITH statements.
Chapter 17: Special Considerations for DQL Language Queries 179
DQL Language Query Performance Considerations
DQL Language Query Performance Considerations
When writing queries, be aware of the general CA Dataquery performance considerations discussed in this section. CA Dataquery uses the CA Datacom/DB
Compound Boolean Selection Facility to evaluate the row selection criteria in a DQL
Mode query's FIND statement. CA Dataquery and the Compound Boolean Selection
Facility dynamically handle the search optimization.
CA Dataquery uses predicates (a WITH in a DQL Mode query FIND statement) to build a
Compound Boolean Selection Request Qualification Area (RQA), converting the selection criteria in a query's statements into the Compound Boolean Selection format.
Consider the following when using predicates in queries that use:
■
Indexed columns (keys)
■
Signed numeric data
■
Predicates that do not convert to the Compound Boolean Selection format
■
Multiple table queries
Use of Keys
It is important to use predicates with keys as much as possible. The Compound Boolean
Selection can utilize the CA Datacom/DB index rather than searching rows to evaluate the selection criteria of a query.
In the case where predicates with only nonindexed columns are used, Compound
Boolean Selection must examine each data row in the table to evaluate the predicates
(full table search). Performance can be enhanced with the use of predicates with keys.
There is some overhead involved with maintaining keys on a table. This must be weighed against the potential of performance improvements in CA Dataquery.
Signed Numeric Data
When the predicates in a query statement refer to columns containing signed numeric data of packed or zoned decimal format, it is important to be as specific as possible with the CA Datacom Datadictionary TYPE-NUMERIC attribute. For example, by specifying P for the TYPE-NUMERIC attribute when the data that a query is accessing contains only positive values, enables CA Datacom/DB's Compound Boolean Selection to search the index for entries with only positive values, because the traversal key value range is restricted.
Note: The TYPE-NUMERIC attribute must, however, agree with the actual data or incorrect results can be obtained. (Check with your Database Administrator for more information.)
180 Administration Guide
DQL Language Query Performance Considerations
Nonconvertible Predicates
Most predicates that can be used in a query can be easily converted to Compound
Boolean Selection format, however, there are some special cases that are impossible to convert. These special cases are referred to as nonqualifying predicates. These nonqualifying predicates are handled outside of the Compound Boolean Selection.
The following types of DQL Mode predicates are passed to the Compound Boolean
Selection.
KEY TO COLUMN
When the data type of the column is character or zoned.
KEY TO VALUE
When masking is used, the comparator must be either EQ or NE. When containing is used in a compare, the columns which comprise the key must be contiguous.
COLUMN TO VALUE
When masking is used, the comparator must be EQ or NE. If the field is numeric it must have no more than 15 digits, and if masking is used the field must not be packed decimal.
KEY TO KEY
When one or both of the keys are comprised of discontiguous columns, the two keys must have the same number and length of component fields.
COLUMN TO COLUMN
The columns must be of the same data types. If the columns are numeric they must have the same precision and if they are numeric must be of no more than 15 decimal digits.
Note: Arithmetic expressions in predicates do not qualify.
It is possible for predicates that would normally be passed to Compound Boolean
Selection to be disqualified because they were connected by an OR to nonqualifying predicates. For example, in the following query NAME does not qualify because the comparator is GTE, whereas DIAG-COD and CITY-STATE-ZIP would qualify.
FIND DA19-PATIENT WITH
NAME GTE 'C#' AND DIAG-COD EQ ' ' AND CITY-STATE-ZIP = 'DALLAS#'
PRINT NAME DIAG-COD CITY-STATE-ZIP
Chapter 17: Special Considerations for DQL Language Queries 181
DQL Language Query Performance Considerations
For example, if NAME and DIAG-COD were indexed columns and CITY-STATE-ZIP were nonindexed:
■
CA Dataquery would pass DIAG-COD and CITY-STATE-ZIP to Compound Boolean
Selection.
■
NAME would be disqualified because of masking used with GTE.
■
Compound Boolean Selection would use the key to find all rows that had DIAG-COD equal to blanks.
■
Compound Boolean Selection would then check the data rows to find the
CITY-STATE-ZIP columns.
■
Then Compound Boolean Selection would send the data back to CA Dataquery and
CA Dataquery would have to qualify the NAME predicate.
The data that met all three qualifications would be found.
In the next example:
■
DIAG-COD would not qualify because of the OR with NAME, a nonqualifying predicate due to masking used with GTE.
■
The predicate CITY-STATE-ZIP would qualify.
■
CA Dataquery would pass CITY-STATE-ZIP to Compound Boolean Selection, which would then check the data columns to find the CITY-STATE-ZIP columns that meet the qualification.
■
Then Compound Boolean Selection would send the data back to CA Dataquery and
CA Dataquery would have to qualify the NAME and DIAG-COD predicates.
FIND DA19-PATIENT
(NAME GTE 'C#' OR DIAG-COD EQ ' ') AND CITY-STATE-ZIP = 'DALLAS#'
PRINT NAME DIAG-COD CITY-STATE-ZIP
Multiple Table Queries
When two tables are related in a query, they are normally joined by columns or keys in the two rows. When the search is performed, the link-column in the second table that is searched is used to create an additional KEY-VALUE or COLUMN-VALUE predicate using a value extracted from the link-column in the table that is searched first.
CA Dataquery allows tables to be joined when the link-column is not indexed in either of the tables. This should be done with care if the second table in the relationship to be searched does not have key criteria. Compound Boolean Selection could be forced to perform repeated full searches on that table.
182 Administration Guide
Mathematical Functions
When multiple tables are related in a query, CA Dataquery determines every possible way that the search could be done, dynamically estimates the cost of each and selects the lowest cost strategy.
FIND ALL CA-ACCTS-REC
PRINT TITLE1 'SAMPLE ORDER ENTRY DATABASE'
TITLE2 'ACCOUNTS TABLE'
ORD-ID
BILL-DT
ORD-AMT
In the previous DQL Language example, no predicates are used. Compound Boolean
Selection reads the index in native key sequence for CA-ACCTS-REC and returns the row
IDs to CA Dataquery. The data rows were not accessed during processing of the FIND statement.
Mathematical Functions
CA Dataquery provides mathematical functions which help to simplify certain arithmetic problems. Two basic types of functions exist, standard and user-defined. Both types work with column values at the row level and not with a mixture of column values and column totals. See CA Dataquery end-user documentation for more information. For
User-Defined Functions Exit
Queries should include numeric columns and not have a great disparity in the data values that add up to the total amount.
Chapter 17: Special Considerations for DQL Language Queries 183
Chapter 18: Modifying Data Using CA
Dataquery
To modify data, the user creates a query containing the appropriate keywords. When the query executes, CA Dataquery presents the Table Maintenance panel. The user checks the panel, then presses the APPLY PF key.
DQL Language
Online CA Dataquery provides three DQL Language functions to modify data. The functions are ERASE, INSERT and UPDATE. These special DQL Language verbs can be used in queries by authorized users to delete, add, or change data contained in CA
Datacom/DB databases. The user must be explicitly authorized for each function for each table to perform this maintenance.
Note: In DQL Mode, data manipulation is only available in online processing, that is, you
cannot do data manipulation in DQL Mode if you are using batch processing.
SQL Mode
You need authorization to use SQL Data Maintenance to be able to use SQL verbs
DELETE, INSERT, and UPDATE. Data Maintenance is available in both online and batch
Authorizing Users
(see page 207) for more information.
Dialogs
A great deal of flexibility can be obtained by making queries containing these verbs into dialogs. With this technique the user executing the query can be prompted for the column values in INSERT and UPDATE queries. See the CA Dataquery User Guide for more information about dialog creation.
Chapter 18: Modifying Data Using CA Dataquery 185
DQL Language Data Modification
DQL Language Data Modification
A brief description of each DQL Mode data manipulation command follows:
ERASE
Allows you to remove rows from the database. Include selection criteria in the form of a WITH statement contained in a FIND statement of a query. This criteria qualifies the selection to help ensure that you delete the proper row or rows from the database. Use qualification to alleviate the possibility of deleting the wrong rows.
INSERT
Adds rows to the database. The row name you specify in the INSERT statement must be defined to CA Datacom Datadictionary. An INSERT statement includes one set clause for each column for which you are designating a value. If you do not specify a value for a column contained in the specified row, CA Dataquery provides a default value when you add the row, unless the column is defined as a repeating field. Character columns default to blanks and numeric columns default to zeros.
Note: Include a SET clause to specify the values for the columns in the Master Key for that row.
UPDATE
Replaces the value of one or more columns within a row already in the database with another value. Use selection criteria in the form of a WITH statement used in a
FIND statement of a query. This criteria qualifies the rows you want to modify. Use qualification to alleviate the possibility of modifying the wrong rows.
The UPDATE statement requires one SET clause for each column you want to modify within the row. CA Dataquery only modifies the columns named in the SET clauses.
Your Tasks
Your company may ask you to create queries that perform one or more of these functions or to modify an existing query so that the new version performs one of these functions. In either case, verify that the user or group of users who plan to execute these queries are authorized to perform these functions. Any user who executes a query that performs a FIND, UPDATE, INSERT, or ERASE against a table must be authorized for that function by the administrator who has SECURITY CONTROL authorization. (If CA
Dataquery is externally secured, any user must be authorized through external security to perform any data maintenance functions on a table.) This is one of CA Dataquery's security features that allows your site to maintain control over the integrity of your data.
186 Administration Guide
DQL Language Data Modification
The format of UPDATE, INSERT, and ERASE are identical to the format of FIND as documented in the CA Dataquery end-user documentation with the exception of the
SET statement. In a FIND, the SET statement creates a new column but in the UPDATE or
INSERT, the column named in the SET statement must be the name of a column in a table. The following examples of these functions are based on the Sample Order Entry
Database.
DQL Language Examples
Sample ERASE Query
ERASE CA-DETAIL-REC WITH ORD-ID = 9000
Sample INSERT Query
INSERT CA-DETAIL-REC
SET ORD-ID = 9000
SET ITM-ID = 'X10000'
SET ORD-QTY = 99
SET SHIP-QTY = 99
SET UNIT-PRICE = 99.99
SET DISC-PCT = 0.0
SET ACT-YR = '87'
SET ACT-MO = '01'
SET ACT-DAY = '01'
Sample UPDATE Query
UPDATE CA-DETAIL-REC WITH ORD-ID = 9000
SET ORD-QTY = 01
SET SHIP-QTY = 01
SET UNIT-PRICE = 100.00
SET DISC-PCT = 0.0
SET ACT-YR = '87'
SET ACT-MO = '04'
SET ACT-DAY = '21'
Chapter 18: Modifying Data Using CA Dataquery 187
DQL Language Data Modification
Executing a DQL Query
You execute a query with an ERASE, INSERT, or UPDATE statement by pressing the
APPLY PF key when the Table Maintenance panel (DQEI0) appears.
A sample Table Maintenance panel for INSERT follows:
Table Maintenance (DQEI0)
=>
Press PF3 to apply changes to table
------------------------------------------------------------------------DQEI0
DATAQUERY: TABLE MAINTENANCE PAGE: _____
-----------------------------------------------------------------------------
TABLE: ________________________________
FUNCTION: ______ NUMBER SELECTED: _____ LIMIT EXCEEDED
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> APPLY <PF4> NOT USED <PF5> NOT USED
<PF6> NOT USED <PF7> BACKWARD <PF8> FORWARD <PF9> LEFT <PF10>RIGHT
Purpose
The Table Maintenance panel displays the rows that are to be maintained on a CA
Datacom/DB table. This panel displays only. To perform the actual maintenance on the table, press <PF3> APPLY. This panel gives you a chance to view the rows that you are intending to maintain, before the maintenance actually takes place. In other words, you have a second chance before you UPDATE or ERASE the rows.
Panel Description
The following list describes each field of the Table Maintenance panel:
TABLE
The name of the table to be updated.
FUNCTION
The maintenance function to be performed, ERASE, INSERT, or UPDATE.
188 Administration Guide
SQL Mode Data Modification
NUMBER SELECTED
The number of records to be updated, inserted or erased.
PAGE
The page number of the display.
LIMIT EXCEEDED
If this appears, the number of records to be updated, or erased has exceeded the number of found table blocks that the user can use. (Make the selection criteria more selective or increase the FNDBLKS= parameter.)
Action
When you are satisfied that the rows displayed on this panel are the ones to be maintained press <PF3> APPLY to ERASE, INSERT, or UPDATE the rows according to your query.
SQL Mode Data Modification
For a CA Dataquery user to use the SQL data maintenance commands, the user must be authorized. This is done on the User Table Maintenance panel or through external security, if CA Dataquery is externally secured.
A brief description of each SQL Mode data manipulation command follows:
DELETE
Allows you to remove one or more rows in a table. The rows to be deleted are chosen by the SEARCH function. An example of the DELETE statement follows:
DELETE FROM DEPTTBL
WHERE DEPTNO = 'D1'
INSERT
Adds one or more rows to a table. The data to be inserted can be specified directly in the INSERT statement, or data can be retrieved from an existing table using a subselect statement.
Simple INSERT of one Row
INSERT INTO EMP
VALUES ('000315', 'JOHN', 'T', 'SMITH',)
Selected INSERT of Multiple Rows
INSERT INTO SMITH.TEMPEMP
SELECT *
FROM EMP
Chapter 18: Modifying Data Using CA Dataquery 189
SQL Mode Data Modification
UPDATE
Replaces the value of one or more columns within one or more rows of a table with another value. You can use selection criteria similar to that used in a SEARCH statement of a query. This criteria qualifies the rows you want to modify. Use qualification to alleviate the possibility of modifying the wrong rows. An example of the UPDATE statement follows:
UPDATE CAI_TEMP
SET PHONENO = '3565'
WHERE EMPNO = '009123'
If no search condition is specified, CA Dataquery updates all rows in the named table.
Executing an SQL Query
Use the CA Dataquery Editor to write the SQL commands, DELETE, INSERT and UPDATE and follow the usual execution procedures.
190 Administration Guide
Chapter 19: Sets
The KEEP function of CA Dataquery saves the pointers to a set of data selected by an executed query. The EXTRACT function of CA Dataquery saves the actual set of data selected by an executed query. Each user is allocated a certain number of Found Table blocks of storage for his sets. When the user's Found Table blocks are exceeded, any further attempts by the user to perform a KEEP or EXTRACT function, results in an error condition.
Note: KEEP and EXTRACT should only be used on data that is not updated frequently. If the data is updated since the last KEEP or EXTRACT functions, the saved pointers in the
KEPT data could point to different data, and the reports that used the extracted data would be in error. (This function is available only in DQL Mode. For information about saving data in SQL Mode, see STORE in the CA Dataquery Reference Guide.)
Administrative Menu
The SET option on the Administrative Menu is a maintenance function that you use to maintain the saved and extracted sets stored in the Found Table (DQF).
It is your responsibility to monitor the listing of your users' sets. You should delete the
Found Table blocks of those users who have left the company, or those who have transferred to another department within the company. Also delete those sets that are aging past site standards. You can request your Database Administrator to allocate more blocks to the Found Table (DQF) when there is a valid need.
Directory
When you select the SETS option from the Administrative Menu, or use the SETS command from the command line, CA Dataquery displays a listing of saved sets on the
Directory of Saved Sets panel.
Chapter 19: Sets 191
SQL Mode Data Modification
A sample Directory of Saved Sets panel follows:
Directory of Saved Sets (DQA60)
=>
Place the cursor on the desired name and press the appropriate PFkey
------------------------------------------------------------------------DQA60
DATAQUERY: DIRECTORY OF SAVED SETS
-----------------------------------------------------------------------------
USER NAME | NAME | TYPE |BLOCKS |DATE ADDED
-----------------------------------------------------------------------------
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DELETE <PF4> USE
<PF5> NOT USED <PF6> NOT USED <PF7> BACKWARD <PF8> FORWARD
Panel Description
The following list describes each column of the Directory of Saved Sets panel:
USER NAME
ID of user who saved set.
NAME
Name of the saved set.
TYPE
Type of saved set - K is KEEP, E is EXTRACT.
BLOCKS
Number of Found Table blocks used.
DATE ADDED
Date the saved set was added to the Found Table.
192 Administration Guide
SQL Mode Data Modification
PF Keys
The following list describes each PF key for the Directory of Saved Sets panel:
Key Objective Result
CLEAR
<PF1> HELP
Return to Main Menu.
Display HELP panel.
Return to Main Menu.
CA Dataquery displays the Help panel.
<PF2> RETURN
<PF3> DELETE
<PF4> USE
<PF5> NOT USED
<PF6> NOT USED
<PF7> BACKWARD
<PF8> FORWARD
Return to previously displayed panel.
Delete saved set.
Activate a set for use in a query without reexecuting a find.
Not used.
Not used.
Scroll to previous page of
Saved Sets, if any.
Scroll to next Saved
Set screen, if any.
Returns you to previously displayed panel or Main Menu.
Deletes saved set.
Displays Online Execution panel.
Display previous page of Saved
Sets, if any.
Display more Saved Set screen, if any.
Note: For more information about the <PF4> USE key, see the CA Dataquery User Guide.
Chapter 19: Sets 193
Chapter 20: Personal Database Facility
The personal database facility is a tool that allows a user to have a separate group of tables that are created by a user and reserved for his use. The user can create, populate, maintain, and delete these tables using a simple menu-driven interface. The user can access the tables with queries and dialogs that he creates. The SQL option must be installed at your site for personal tables to work.
Uses for Personal Tables
A user can use the STORE command to create tables containing SQL query output. Once a user executes a SQL query he may issue STORE which dynamically creates a table in the user's private authorization ID, and populates it with the Found Set. Queries executed against a personal table can have a faster processing time than queries run against public tables.
The user can manipulate personal table data for special needs, for specialized reports, for forecasting, or use the manipulated data in a business chart to help with decision making. Since all the data in the user's personal tables is generated by the user, the user is completely in charge of what is done with the data.
Here are some considerations for the use of PDB (personal data base) and the STORE command. With these functions, tables are CREATED (by using SQL) into an area specified in the user's profile (this profile information is still used even when external security is in effect for CA Dataquery). The area must be in a database for which the user has both "create" authority and CA Dataquery authority to do maintenance. The area and database should be built separately for each user (or group of users) that are allowed PDB authority, so that these tables are not put into any arbitrary database. See the CA Datacom/DB Database and System Administration Guide for information about how to set up a database for SQL use.
Chapter 20: Personal Database Facility 195
CA Dataquery Administrator Responsibilities
CA Dataquery Administrator Responsibilities
The CA Dataquery Administrator has the responsibility of authorizing users for personal
database and for naming the area in CA Datacom/DB. See
Authorizing Users
page 207).
When a user is added with a private SQL authorization specified, CA Dataquery automatically creates a schema in CA Datacom Datadictionary for the SQL authorization
ID. A schema defines the individual user's SQL environment. Users must have a schema associated with an authorization ID to use SQL. A schema contains all table, view, and privilege definitions owned by a given authorization ID. Any definitions created by the user using the Personal Database Facility are automatically added to the schema for the authorization ID specified when the user creates the SQL object.
Authorizing Users to Access Another Users Personal Tables
Access to another user's personal tables can be convenient for both users. For example, if an office manager maintains weekly status reports on his personal database and he wishes a secretary to compile a monthly report, the CA Dataquery Administrator can give the secretary access to the manager's tables.
DQL Language
The user must be authorized to access (read, update, insert, or erase) these tables just like any other CA Datacom/DB table.
SQL Mode
To give another user access to someone's personal tables, simply provide the authorization ID. In SQL Mode, the creator of the table may give another user access to his personal tables by using the SQL GRANT command. See the CA
Datacom/DB SQL User Guide. If access through SQL Mode query or dialog is needed, the user can supply the authorization ID as part of the table name, as in:
FROM authid.table-name
The user cannot change his private SQL authorization ID. They may change the currently used authid, but it will not be used by the PDB facility. CA Datacom/DB Security, including GRANT, will govern accessibility of another user's tables, whether the authid is known and supplied, or not.
196 Administration Guide
Chapter 21: Using the Language
Maintenance Facility
Summary
CA Dataquery provides a LANGUAGE option for the Administrative Menu. You might be authorized to translate the CA Dataquery vocabulary, literals, messages, commands, menus, and panels into another language, or to customize them using terms with which your site's users feel more familiar. You can translate/customize everything or only certain items.
Functions
■
■
Use the Language Maintenance Facility to:
■
Translate menus, help panels, vocabulary terms, literals, and error messages to another language (such as, American English to Spanish).
■
Customize error messages to include information specific to your company such as,
"Contact John Franks at extension 6670 if you encounter this message."
■
Change the bulletin board.
Create a dialect from a base language.
Edit panels, vocabulary terms and literals.
■
■
Delete panels vocabulary terms and literals.
List all literals, panels, and vocabulary terms.
Information for changing the bulletin board is documented in Changing the Bulletin
Board.
Chapter 21: Using the Language Maintenance Facility 197
Chapter 22: Upgrading to New Releases of
Supporting Products
Modifying or upgrading supporting products may affect CA Dataquery. Before upgrading, carefully study the changes from the prior version and the upgrade procedures for each of the products to gauge the impact on CA Dataquery. See the
DQSAM01 through DQSAM11 sample members. For information on the sample programs (sample assemblies and jobs), See the CA Datacom Installation Guide for information on the sample members that contain job control statements which modify the CA Dataquery environment and run the batch utility programs.
Procedures
Upgrade procedures for each product can also be found in the Source Library. Use the following as a check list when upgrading the environment in which CA Dataquery operates.
CICS
DQDECPR in the DQSAM11 member is the only CA Dataquery module that contains command level CICS. When a new version of CICS is installed, reassemble the
DQDECPR module and link edit it to produce a modified DQDECPR.
When a new version of CICS is installed, ensure that the PPT and PCT system tables include entries for CA Dataquery. Ensure that the CA Datacom CICS Services is installed and operational.
CA Datacom/DB
When upgrading CA Datacom/DB, follow the instructions distributed with CA
Datacom/DB for reloading the CA Dataquery database and reassembling the Master
Lists and File Tables.
CA Datacom Datadictionary
If the database ID for CA Datacom Datadictionary is changed, change the coding of the DDDBID= parameter of the DQOPTLST macro (see Tailoring the CA Dataquery
System Option Table). Then reassemble and relink edit DQOPTLST with the new parameter coding for DDDBID=.
Chapter 22: Upgrading to New Releases of Supporting Products 199
Chapter 23: Security Overview
Purpose
The intention of this section is to give you an understanding of CA Dataquery Security concepts and a suggested plan for the implementation of those concepts. Read this section thoroughly and use the information to plan for your site's security. It is important that your security plan ensures the security of your site's data and the CA
Dataquery system and the integrity of your data.
Planning
■
■
■
■
■
CA Dataquery permits several levels of use and data access. Therefore, CA Dataquery security requires careful thought and planning involving:
■
Your site's data
■
The way the data is to be used
■
Who is to be allowed access to the data
Who is to administer access to data
Who is to administer authorization to use CA Dataquery
Who is to plan and administer CA Dataquery security
The usage of DQL and SQL modes
Coordination of security with the site Database Administrator and CA Datacom
Datadictionary Administrator and with the CA Dataquery Administrator
Note: CA Datacom/DB database IDs can range from 1 to 5000. However, CA Dataquery internal security only allows three digits for a database ID. Therefore, if you have tables in databases with IDs greater than 999 that need to be secured, you must use external security.
Concepts
■
■
Following are some of the tasks discussed on the following pages:
■
Understanding CA Dataquery and external security
■
Authorizing users to access data
■
Securing data access for DQL use
Limiting access to columns
Securing data access for SQL use
Chapter 23: Security Overview 201
Authorizing Users to Access Another Users Personal Tables
■
■
Miscellaneous security control techniques
Considering CA Datacom system security
CA Suggests
After your plan has been in effect for some time, you might need to make changes to your original plan. CA Dataquery is very flexible and allows you to make the changes easily. We suggest that you reread this document before making changes, to ensure that the changes are consistent with the concepts discussed here and your site-defined plan.
You can establish security through CA Dataquery and you can choose to use any external security management product, such as CA ACF2 and CA Top Secret, to define your CA Datacom/DB and CA Dataquery access rights. CA Dataquery users must be assigned access to CA Datacom/DB tables through the security in force for CA
Datacom/DB before they can access tables using CA Dataquery. See the CA Datacom
Security Reference Guide for details.
CA Dataquery Security
■
■
■
■
CA Dataquery provides several types of security. You can limit access to:
■
CA Dataquery through a signon procedure and/or a signon/off exit
■
Data through user authorization
■
System functions through user authorization
■
Data through group authorization
Administrative functions through user authorization
Tables through SECURITY CONTROL
Rows through restricted conditions
Columns through CA Datacom Datadictionary profile-codes
You must communicate with the CA Dataquery Security Administrator regarding the CA
Datacom/DB and CA Datacom Datadictionary security environment and to determine how security should be implemented for CA Dataquery. You must ensure consistency across the system for security use.
CA Dataquery security must be specified in addition to CA Datacom/DB security unless the CA Dataquery user's definition specifies DATA AUTHORIZED as YES. CA Dataquery security must be specified to use INSERT, UPDATE, or ERASE functions. CA Dataquery
Security is used to determine a user's authorization to access data only in DQL Mode.
202 Administration Guide
Securing CA Dataquery Access Through Signon Procedures
Securing CA Dataquery Access Through Signon Procedures
You can restrict access to CA Dataquery through a CA Dataquery signon procedure or through a signon/off exit.
Signon Procedure
The CA Dataquery Administrator creates each user signon. The user signon consists of a user name and an optional password. When the user is created, a PERSON entity-occurrence is automatically added to CA Datacom Datadictionary. To ensure that your security procedures are simple and efficient, ensure that the CA Dataquery signon
procedures conform to the standards set for the site. See
Adding a New User
page 212) for information on creating user signons.
Signon/off Exit
You can use the signon/off exit to interface CA Dataquery with other security packages
or to perform your own security checks. See
Sign-on/off Exit
User Program Signon
If you want to control access to CA Dataquery by a program written at your site, you can
Initiating and Terminating CA Dataquery
(see page 121) for more information.
Securing Data Access Through User Authorization
The CA Dataquery user authorization consists of authorizing users for specific functions.
These functions include:
■
Read-only access to all data available to CA Dataquery (DATA AUTHORIZED=Y)
■
Query creation and maintenance (ASSOCIATE USER=N)
■
Batch query submission (SUBMIT ALLOWED=Y)
■
Ability to export data (EXPORT ALLOWED=Y)
■
Administrative functions
Chapter 23: Security Overview 203
Securing Access to Tables, Rows, Columns, and Queries
Securing Access to Tables, Rows, Columns, and Queries
CA Dataquery provides several methods to secure access to data. You can limit access to:
■
Tables
■
Rows and columns
■
Queries
Limiting Access to Tables in DQL Mode
The Security Administrator should work with you to list all the CA Datacom/DB tables, rows, and columns that the users will be querying and to determine which users will need access to which tables. The Administrator assigned to the security control function implements the assignment of users to a table or tables to a user. This assignment is stored in the CA Datacom Datadictionary DBID named in the System Option Table
DQOPTLST DDDBID= parameter.
Additionally, CA Datacom/DB Security can be used to secure tables. For SQL Mode, you can use the SQL GRANT/REVOKE commands to control security. See the CA Datacom/DB security documentation for more information.
Limiting Access to Rows in DQL Mode
When you need to allow users access to some, but not all, of the rows in a table, you use restricted conditions. When you restrict access by column content, you restrict
access to all data within that row. See
Limiting Access to Rows Using Conditions and
Restrictions
Limiting Access to Columns in DQL Mode
CA Dataquery provides the Security Administrator with the ability to restrict access to columns through CA Datacom Datadictionary profile-codes. A profile-code is a special attribute of a column entity that is used to put sensitive columns into categories. You and the Security Administrator should meet to decide what columns should be secured and what the profile-code should be. The profile-code must be included in the column definition in CA Datacom Datadictionary. Only users who are authorized for that
profile-code can FIND and/or UPDATE data in the protected columns. See
How to Limit
Access to Columns
(see page 271) for more information.
Limiting Access to Queries in SQL Mode and DQL Mode
The Security Administrator can limit access to queries by assigning the query to a group
ID or by defining a query as private. The System Option Table DQOPTLST macro parameter, QRYGRPS=, must be specified as YES so that the Security Administrator can
implement the group assignments for queries. For more information, refer to
Limiting
Access to Queries
204 Administration Guide
Adding Users
Adding Users
When CA Dataquery is installed for new users, a user named DATACOM-INSTALL is created and placed in the DQU table. The password for DATACOM-INSTALL is NEWUSER.
You can use this ID to define each person who is to use CA Dataquery. When you add or modify a user definition, that definition is stored in the User Table (DQU).
Ensure that you know which users have access to administrative functions and have overrides to system defaults since their actions can affect system operation.
CA Dataquery and External Security
External security provides the ability to control and administer user access to CA
Datacom products and company data based on the security profiles that exist in CA
ACF2 or CA Top Secret. With internal security, product access and data access are controlled with the security systems built into each product. The difference between external and internal security is where the user access authorizations are maintained.
CA Dataquery security protects product functions unique to CA Dataquery. These functions include CA Dataquery online and batch activity. Internal security uses a secondary product signon for each accessor and permits you to define table authorizations in CA Dataquery security. External security uses the external security user identification and validates table access according to the authorizations defined in CA
Datacom/DB security. If external security is used, CA Dataquery provides only column
level security.
To use external security with CA Dataquery, it is necessary for each CA Dataquery user to sign on to the externally secured monitor (CICS) under which CA Dataquery operates.
The monitor must be externally secured so that the monitor signon effects a signon to the external security package. If external security is specified for CA Dataquery without the monitor being externally secured, the user name retrieved by CA Dataquery from the security package may not be correct. In batch, the SIGN/ON card is ignored if external security is present.
If CA Dataquery is not externally secured, it is not necessary to execute the monitor signon to use CA Dataquery. In this case, when a user issues the DQRY transaction, CA
Dataquery presents its signon panel (DQZ10) and CA Dataquery internal security is in effect.
Note: If your site is moving from CA Dataquery internal security to external security, make sure that you provide security information, such as IDs and table authorizations, that matches your current system.
Chapter 23: Security Overview 205
CA Dataquery and External Security
The Security Administrator controls whether the CA Datacom products are secured with external security. If external security is selected, internal security authorizations are ignored. No modifications are required to any CA Datacom product to implement external security. CA Datacom security information is provided in the CA Datacom
Security Reference Guide.
When external security is used, you may omit reading
Authorizing Users
Securing Data Access for DQL Use
(see page 253). You should read
Limiting Access to Columns and Rows
(see page 271) for information relating to DQL Mode column
security (profile-codes, conditions and restrictions). SQL Mode is always secured by CA
Datacom/DB and by external security when it is in effect. If the SQL option is used at
your site, you should also read
Securing Data Access for SQL Use
Note: PDB and the STORE command use SQL.
206 Administration Guide
Chapter 24: Authorizing Users
Once the security plan for your site is developed, and the CA Dataquery users are identified, you must define each CA Dataquery user to CA Dataquery. When you add or modify a user definition, CA Dataquery stores that definition in the User Table (DQU). (If the user table is enabled, you can execute queries against it. Use the table name
DATAQUERY-DQU.) You can define or modify a user by using online CA Dataquery. It is a fast, simple and efficient method.
CA Dataquery provides two options on the CA Dataquery Administrative Menu (USERS and PROFILE) for adding and maintaining users.
Obtaining Authorizations
Within the CA Dataquery system exists a System Option Table created by a macro
(DQOPTLST) with a number of parameters which define the CA Dataquery system at
Tailoring the CA Dataquery System Option Table
page 47)). These parameters define system-wide limits on such things as:
■
Terminal idle time before automatic signoff
■
Maximum number of rows a query can find
■
Space and system limits on processing time per query
Within the environment defined by the System Option Table, the CA Dataquery
Administrator classifies people with signons as CA Dataquery Administrators, users, or associate users. Within those classifications, the CA Dataquery Administrator can define what each user is allowed to do, and can override a few of the System Option Table parameters regarding system storage allotments for individual users. Table and field
authorizations are handled in other ways. See
Securing Data Access for DQL Use
Limiting Access to Columns and Rows
Within the individual user authorizations set up by the CA Dataquery Administrator, each user can change some personal specifications by accessing and changing the user's
User Profile panel. (Associate users can only access their profiles if the System Option
Table parameter ASUPPRO= is set to YES.)
The flexibility of User Table Maintenance makes it possible to assign authorizations according to actual work responsibilties. When you authorize a new user as an associate user, that user becomes limited to functions accessible by PF key on the associate user panels. For an associate user, you can only add the following authorizations on the User
Table Maintenance panel:
■
Data Authorized
■
Personal Database (SQL Option required)
■
Submit Allowed
Chapter 24: Authorizing Users 207
CA Dataquery and External Security
■
■
Export Allowed
SQL and DQL Allowed (SQL option required)
To authorize a person as a user, do not select Associate User. You can add any or all of the above authorizations.
■
■
■
■
■
■
The only difference between a user and an administrator is that the administrator is a user who has been given one or more of the following authorizations:
■
Conditions
■
Restrictions
■
Printer Control
JCL Maintenance
Diagnostics
■
Language
User Maintenance
■
Saved Set Maintenance
Query Library Maintenance
Security
Active User Control
External Security
If CA Dataquery is externally secured, all CA Dataquery security functions and user authorizations must be done through the external security package. When an external security package is in effect, users' access to databases and tables is controlled by that package. External security overrides CA Dataquery security at the database and table level. See the CA Datacom Security Reference Guide for details on external security.
Users Option
You can enter information online with the USERS option to:
■
Add, delete, or maintain users
■
Authorize users to SQL and DQL Language
■
Authorize users for system management tasks
■
Control data access
■
Override predefined system options (CA Dataquery System Option Table)
For more information about the System Option Table parameters, see
Tailoring the CA
Dataquery System Option Table
208 Administration Guide
CA Dataquery and External Security
When a user is added with a private SQL authorization specified, such as is required for
SQL use, CA Dataqueryautomatically creates a schema in CA Datacom Datadictionary for the SQL authorization ID. A schema defines the individual user's SQL environment. Users must have a schema associated with an authorization ID to use SQL. A schema contains all table, view and privilege definitions owned by a given authorization ID. Any definitions created by the user are automatically added to the schema for the authorization ID specified when he creates the SQL object.
Note: A system utility (DQUSERMT) allows you to maintain the user in batch. See
Performing User Table Maintenance (DQUSERMT)
Profile Option
The PROFILE option, <PF10> on the Directory of CA Dataquery Users panel, allows the modification of the individual user-defined profile option defaults for the following CA
Dataquery functions and actions:
■
Online and batch features
■
Primary and secondary language selections
■
Network printing options
■
SQL Mode and DQL Mode selection
CA Dataquery and External Security
If external security is active on the system, CA Dataquery obtains the user's signon ID from the external security package. Once the signon ID is retrieved, CA Dataquery checks the user's eligibility to sign on to CA Dataquery.
After CA Dataquery determines that a user is eligible for signon, CA Dataquery makes additional resource checks to determine the user's access to functions from external security. If a DQU record for the user exists, the record is updated with the latest authorizations from external security. If one does not exist, one is created, since the
DQU record also contains various profile options maintainable by the individual user.
The authorizations in effect at the beginning of a CA Dataquery session determine the functions appearing on CA Dataquery menus and the commands allowed throughout the CA Dataquery session. When an externally secured function is requested by command or PF key or from a menu, the function is checked to determine if the user is still authorized.
If external security is not in effect, CA Dataquery internal security is in effect.
Chapter 24: Authorizing Users 209
Accessing User Information
Internal Overrides
If secured within CA Dataquery, column level security functions, profile codes, and condition/restriction are in effect whether or not CA Dataquery is externally secured.
Implementation of external security in CA Dataquery allows the Security Administrator to define authorizations to perform all CA Dataquery functions and to execute the CA
Dataquery batch utility functions using the user's external security definitions. External security for data (CA Datacom/DB tables) is provided through CA Datacom/DB. When external security is in effect on the system, the signon ID is retrieved from the external security product in both online and batch mode and in the batch utilities.
Accessing User Information
To view, update, add, or maintain users, begin by displaying the Directory of CA
Dataquery Users panel (DQK90). Select Users from the Administration menu or type the
USERS command and press Enter. A sample panel follows:
Directory of CA Dataquery Users (DQK90)
=>
Place the cursor on a name to delete or update. Use PF3 to add new users
------------------------------------------------------------------------DQK90
DATAQUERY: DIRECTORY OF DATAQUERY USERS START WITH => ________ _______
-----------------------------------------------------------------------------
USER NAME | DATE ADDED | DATE USED | TERMINAL USED
-----------------------------------------------------------------------------
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> ADD <PF4> UPDATE
<PF5> ACTIVE USERS <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
<PF9> PASSWORDS <PF10> PROFILE
210 Administration Guide
Accessing User Information
Action
The START WITH field, located in the upper-right corner of this panel, is where you enter the full or partial name of the user where you want the listing to start. When you press
Enter, CA Dataquery displays the user that you specified on the first line of the listing.
You can also page forward using <PF8> FORWARD or backward using <PF7> BACKWARD until you reach the member that you want to view and/or edit.
Panel Description
The following list describes each column of the Directory of CA Dataquery Users:
USER NAME
Alphabetical listing of all CA Dataquery user names.
DATE ADDED
Date this user was added to the CA Dataquery system.
DATE USED
Date this user last signed on to CA Dataquery.
TERMINAL USED
Terminal ID from which this user last signed on.
CA Dataquery allows you to invoke several user functions by selecting a PF key. Adding a user is the only PF key selection discussed in this section of this guide. Update, delete, active users, passwords, and profiles are discussed in the following sections of this chapter.
PF Keys
The following list explains unique PF keys for the Directory of CA Dataquery Users panel.
Key Objective Result
<PF3> ADD
<PF4> UPDATE
Add a new user. CA Dataquery displays User Table
Maintenance panel.
Modify user options. CA Dataquery displays User
Maintenance panel for user selected by cursor.
<PF5> ACTIVE
<PF6> DELETE
Display active users. CA Dataquery displays Directory of
Active Users.
Delete a user. CA Dataquery deletes user selected by cursor.
Chapter 24: Authorizing Users 211
Accessing User Information
Key
<PF9>
PASSWORDS
<PF10> PROFILE
Objective
Modify system and group passwords.
Display/modify user's profile.
Result
CA Dataquery displays Directory of
Defined Dataquery Groups.
CA Dataquery displays User Profile for user selected by cursor.
Adding a New User
To add a new user, begin by selecting the USERS option from the Administrative Menu, or typing USERS on the command line and pressing Enter. CA Dataquery then displays the Directory of CA Dataquery Users panel. To add a user, press <PF3> ADD. CA
Dataquery displays the User Table as follows. Input the appropriate values for the new user. Each field is explained on the following pages.
User Table Maintenance (DQUU0)
=>
Enter the user information and press the appropriate PF key
------------------------------------------------------------------------DQUU0
DATAQUERY: USER TABLE MAINTENANCE
-----------------------------------------------------------------------------
USER NAME :
PASSWORD : GROUPS:
ACCOUNTING CODE : LEVEL 1:
QUERY LANGUAGE : LEVEL 2:
PRIVATE SQL AUTHID : LEVEL 3:
DQ SYSTEM STATUS.
DATA AUTHORIZED : ASSOCIATE USER : PERSONAL DATABASE :
SUBMIT ALLOWED : EXPORT ALLOWED : :
SQL AND DQL ALLOWED : SQL DATA DEF ALLOWED : SQL DATA MAINT ALLOWED :
SYSTEM ADMINISTRATIVE MENU ITEMS AUTHORIZED FOR.
CONDITIONS : RESTRICTIONS : PRINTER CONTROL :
JCL MAINTENANCE : DIAGNOSTICS : LANGUAGE :
USER MAINTENANCE : SAVED SET MAINT : QUERY LIBRARY MAINT :
SECURITY : ACTIVE USER CONTROL :
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> ADD <PF4> ADDITIONAL OPTIONS
212 Administration Guide
Accessing User Information
Panel Description
Default values appear on the User Table Maintenance panel and can be changed. Other options relating to overriding system defaults are also available by pressing <PF4>
ADDITIONAL OPTIONS. When changes are complete, press <PF3> ADD to add the user.
USER NAME
(Required) Enter a unique 1- to 32-character alphanumeric user name. (The length must not exceed the PERSON entity name length in CA Datacom Datadictionary. See your Security Administrator for this length. Each CA Dataquery user has a matching
PERSON entity-occurrence in CA Datacom Datadictionary that is generated automatically by CA Dataquery.)
PASSWORD
(Optional) Enter a 1- to 9-character alphanumeric password. This field is used to assign an individual user password.
ACCOUNTING CODE
(Optional) Specify the CA Datacom/DB accounting code to be used with CA
Datacom/DB accounting for CA Dataquery. See your Database Administrator for this information.
QUERY LANGUAGE
(Required) Analyze the language needs of your site. You can authorize use of SQL,
DQL Language, or both. Since DQL Mode has security controls that SQL Mode does not offer, and vice versa, you need to ensure that users are authorized for the mode best suited to their job functions and that appropriate CA Datacom/DB security measures are implemented. The CA Dataquery Administrator specifies the query language when he adds or updates a user and designates if a user can switch between modes. You decide which users are allowed to perform SQL Data
Definition statements and Data Maintenance statements, and which statements that the user is authorized to use when adding or updating a user.
SQL if SQL or DQL, the default, if DQL Language is authorized for this user. YES in the SQL AND DQL ALLOWED field authorizes the user to both query languages.
PRIVATE SQL AUTHID
(Required if language authorized for this user is SQL, or if the user is authorized to
use both SQL and DQL Language, or if personal database is authorized for this user.)
Enter a 1- to 18-character authorization ID. This is the user's default authorization
ID for personal database and for all SQL Mode. See the CA Datacom/DB SQL User
Guide for further information.
Note: If a user changes his SQL authorization ID either by the PROFILE or AUTHID command, it changes only on the user profile, not on the User Table Maintenance.
Therefore, if a user creates a table in PDB, his private SQL authorization ID will be attached to the table name regardless of the authid he was using when he created the table. When the DISPLAY or LIST, EXECUTE or CREATE functions are used, the profile authid is used by CA Dataquery.
Chapter 24: Authorizing Users 213
Accessing User Information
GROUPS: LEVEL 1
(Optional) Enter a valid 1- to 15-character alphanumeric group level 1 name for CA
Dataquery security control. See
Assigning Group Levels
information.
GROUPS: LEVEL 2
(Optional) Enter a valid 1- to 15-character alphanumeric group level 2 name as specified in CA Dataquery security control. If you enter a group level 2 name, you
must also enter a group level 1 name. See
Assigning Group Levels
more information.
GROUPS: LEVEL 3
(Optional) Specify a valid 1- to 15-character alphanumeric group level 3 name as specified in CA Dataquery security control. If you enter a group level 3 name, you
must also enter a group level 1 and a group level 2 name. See
Assigning Group
Levels
(see page 232) for more information.
CA Dataquery System Status
DATA AUTHORIZED
(Required) (Applies to DQL Mode only.) Authorizes the user to read-only access to all data available to CA Dataquery.
Y (yes), you allow the user read-only access to data. CA Dataquery does not perform any data security check. (External security and Database security will be applied to table access.)
N (no), the default, CA Dataquery qualifies this user's access to data by the data authorizations specified in security control. However, Conditions and Restrictions
and profile codes are applied to the appropriate table. See
Securing Data Access for
DQL Use
Limiting Access to Columns and Rows
for more information.
ASSOCIATE USER
(Required) Decide whether to authorize each user as a associate user thereby limiting the user's ability to query the database. A associate user can only run queries created by others and cannot create or maintain queries. If you do not
designate the user as an associate user, CA Dataquery assigns conventional user
authorization to that user.
Note: A conventional user can create and edit queries.
Y (yes) specifies that this user can only perform associate user tasks.
N (no), the default, does not limit this user to associate user tasks. This enables this user to create and edit queries, view database information, use commands, and so on.
214 Administration Guide
Accessing User Information
PERSONAL DATABASE
(Required) A user who has a need to create tables using the data retrieved by a query for his own use for forecasting is a good candidate for authorization of the
Personal database facility. Both DQL Mode and SQL Mode users can be authorized for Personal database, but SQL must be installed at your site to use the Personal database facility. You specify which users can use personal tables and the area of the database where the tables are to be stored when adding or updating a user in
CA Dataquery.
Y (yes) if this user is allowed to create and maintain personal tables using the personal database facility. This authorizes a user to create personal tables within his
PRIVATE SQL authorization ID (schema) for his individual use. (See
Using Schemas
(see page 303) for more information.) Specify the area of the database where personal tables are to be stored on the Override System Defaults panel. See
Overriding System Defaults
(see page 219) for more information.
N (no), the default, prohibits the user from using the personal database facility.
SUBMIT ALLOWED
(Required) Most queries are executed using online CA Dataquery. However, your site might choose to submit long-running queries to batch CA Dataquery to make better use of your system resources. Determine which users have a need to submit batch queries and authorize them to do so.
Batch CA Dataquery can also be initiated from other software packages. You can secure batch CA Dataquery in this type of environment by using security packages like CA ACF2 and optionally, by use of the Batch Signon Exit.
Indicate whether this user is allowed to submit batch queries from online CA
Dataquery.
Y (yes), the default, permits the submission of batch queries
N (no) does not.
Chapter 24: Authorizing Users 215
Accessing User Information
EXPORT ALLOWED
(Required) CA Dataquery provides the capability to build a batch export file whereby data accessed from the database is exported and saved on a sequential file for later use. A user's need for this capability is directly related to his job responsibilities. A data entry clerk most likely will not need to export data to fulfill a customer order. However, a systems programmer might need to export data to test complex queries or to compile statistics. The exported data is in either comma separated value format which can be accessed by a personal computer for those users with that specific need or fixed-length record format.
Note: You might want to consider limiting the use of the Export capability.
Y (yes), the default, allows the user to export data. This user is permitted to build a
CA Dataquery batch export file whereby data accessed from the database is exported and saved for later use. It allows the user to use the EXPORT command while using batch CA Dataquery.
N (no) prohibits the user from exporting data.
SQL AND DQL ALLOWED
(Optional)
Y (yes) to allow this user to change query languages on his profile.
N (no), the default, restricts the user from changing to the alternate language and restricts him to one query language.
SQL DATA DEF ALLOWED
(Optional) Consider limiting the use of SQL Data Definition to the CA Dataquery
Administrator. This authorization can easily be misused and affect data integrity.
Specify N for both SQL Data Definition and SQL Data Maintenance to limit the user to creating only SQL queries using the SELECT statement keywords.
Y (yes) to allow this user to use SQL Data definition statements.
N (no), the default, restricts the user from using CREATE, COMMENT ON, and DROP statements.
SQL DATA MAINT ALLOWED
(Optional) Consider limiting the use of SQL Data Maintenance to the CA Dataquery
Administrator. This authorization can easily be misused and affect data integrity.
Specify N for both SQL Data Maintenance and SQL Data Definition fields to limit the user to creating only SQL queries using the SELECT statement keywords.
Y (yes) to allow this user to use SQL Data maintenance statements.
N (no), the default, restricts the user from using INSERT, UPDATE, and DELETE.
216 Administration Guide
Accessing User Information
CONDITIONS
Y (yes) to allow this user to create, view, delete, or edit a condition.
N (no), the default, restricts this user from the CONDITIONS option on the
Administrative Menu.
RESTRICTIONS
Y (yes) if this user is to have the administrative ability to create, delete, view, or edit a restriction.
N (no), the default, denies the user access to the RESTRICTIONS option on the
Administrative Menu.
PRINTER CONTROL
Y (yes) permits this user to start, stop, restart, and cancel spooled print jobs.
N (no), the default, restricts access to these spooled print job functions using the
PRINTER CONTROL option on the Administrative Menu.
JCL MAINTENANCE
Y (yes) if this user is to create, delete, view, or edit a CA Dataquery JCL member.
N (no), the default, restricts this user from creating, modifying, or deleting a JCL member using the JCL option on the Administrative Menu.
DIAGNOSTICS
Y (yes) to permit this user to request a CA Dataquery Request Table and/or a storage dump in the form of a transaction dump or a module dump.
N (no), the default, restricts the user from requesting a CA Dataquery Request Table or a storage dump through the DIAGNOSTICS option on the Administrative Menu.
LANGUAGE
Y (yes) if the user is to translate, edit, delete, or display CA Dataquery panels, the bulletin board, program literals, and vocabulary terms to another language.
N (no), the default, restricts access to the LANGUAGE option on the Administrative
Menu.
USER MAINTENANCE
Y (yes) if this user is to have the administrative function of adding, deleting, and maintaining users, as well as access to active users, passwords, and other users' profiles.
N (no), the default, prohibits this user from viewing and/or accessing the USERS option on the Administrative Menu. If a user is authorized for User Maintenance, that user cannot change his own authorization to N (no). :nt text='Caution'. Any user with authorization for this function has the ability to authorize anyone to perform administrative functions. Take care when deciding who and how many users may have this authority as this is a key to security.
Chapter 24: Authorizing Users 217
Accessing User Information
SAVED SET MAINT
Y (yes) to allow the creation, deletion, or modification of a set.
N (no), the default, prohibits access to set definitions using SETS on the
Administrative Menu.
QUERY LIBRARY MAINT
Y (yes) if you wish this user to create, maintain, execute, and/or submit queries listed on the Admin Directory of Queries and Terms panel.
N (no), the default, does not allow this user to select the LIBRARY option on the
Administrative Menu.
SECURITY
Y (yes) if the user is to relate users to a table, tables to a user, or profile codes to a user. This field authorizes this user record and field security control functions.
N (no), the default, restricts this user from performing security control functions.
ACTIVE USER CONTROL
Y (yes), if this user is to have the administrative function of creating and sending messages, forcing another user off CA Dataquery, and cancel query processing during FIND.
Note: An administrator with user maintenance authority automatically has active user control authority but an administrator with active user control authority only may not add, update, or delete users or passwords, or view other users profiles.
N (no), restricts the user from active user administrative functions.
218 Administration Guide
Accessing User Information
Overriding System Defaults
Summary
Part of the task of adding a new user or modifying an established user's profile is determining whether that user should be able to override system defaults established by the System Option Table. CA Dataquery allows you to override some predefined system defaults. From the User Table Maintenance panel select <PF4> ADDITIONAL
OPTIONS to display the Override System Defaults panel.
Override System Defaults (DQUM0)
=>
Enter the user information and press the appropriate PF key
------------------------------------------------------------------------DQUM0
DATAQUERY: USER TABLE MAINTENANCE - OVERRIDE SYSTEM DEFAULTS
----------------------------------------------------------------------------
USER NAME : ________________________________
USER OVERRIDES TO SYSTEM DEFAULTS.
MXREQ : SORTPAG : ESTIMATED MAX I/O :
MXTLR : SORTCTG :
FNDBLKS : NETPRT ID :
PRIMARY : SECONDARY :
AREA FOR PERSONAL DATABASE TABLES:
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> ADD <PF4> NOT USED
Chapter 24: Authorizing Users 219
Accessing User Information
Action
To override the defaults shown, type over them according to the following information.
When the panel is complete, press <PF3> ADD to save the changes. Then press <PF2>
RETURN to return to the User Table Maintenance panel.
Panel Description
MXREQ
(Optional. DQL mode only.) A numeric value from 1 through 99999 to specify a search limit for this user that overrides the system default. This feature limits the amount of time CA Dataquery is to process before pausing to allow the user to end the query. MXREQ keeps one query from monopolizing the system. (The system default is used if this value is zeros.)
SORTPAG
(Optional. DQL mode only.) A value from 1 through 1024 to specify, in 4096-byte pages, the maximum amount of storage CA Dataquery is to allocate to process a single sort request without using the database index for sorting. The value specified here overrides the system default for this user.
ESTIMATED MAX I/O
(Optional. DQL mode only.) A value from 1 through 99999 to specify a threshold count of I/O required to process the query. During optimization, if the estimated number of I/Os required to execute the FIND statement exceeds this number, a screen is presented to the user explaining that the MAX I/O has been exceeded, and asking the user if query execution should continue. If not specified, the default value is the value of the MAX I/O parameter from the CA Dataquery System Option
Table.
MXTLR
(Optional. DQL mode only.) A value from 1 through 99999 to specify the number of times CA Dataquery is to relinquish control to other tasks during a query execution before pausing to allow a user to end processing. (The system default is used if this value is zeros.)
The first two features work together, CA Dataquery allows MXREQ to occur MXTLR times before asking the user if he wants to terminate the query.
220 Administration Guide
Accessing User Information
SORTCTG
(Optional) A value from 1 through 16 to specify, in 4096-byte pages, the maximum amount of contiguous storage area for in-core sorting which CA Dataquery will request of CICS at one time. If this amount is not available when needed, CA
Dataquery tries to allocate a number of smaller areas for the sort.
FNDBLKS
(Optional) A value from 1 through 99999 to specify the total number of physical blocks on the DQF (online work table) that this user can own at one time during a query execution. Ensure that the value specified for this user still leaves adequate space for all other users. (The system default is used if this value is zeros.)
NETPRT ID
(Optional) Specify the 1- to 4-character network printer ID where reports are to be printed for this user.
PRIMARY
(Optional) The 2-character primary language ID for this user's primary language. AE
(American English), the default, is automatically distributed with CA Dataquery.
Your site can also have German, French, or any other language of your company's choosing for a full or partial translation.
SECONDARY
(Optional) The 2-character secondary language ID for this user's secondary language. AE (American English), the default, is automatically distributed with CA
Dataquery. Your site can also have German, French, or any other language of your company's choosing. (This should be a full translation.)
AREA FOR PERSONAL DATABASE TABLES
(Optional) The 1- to 32-character name for the CA Datacom/DB area to be used for this user's personal database tables. This can be used only with CA Datacom extensions to SQL. Check with the Database Administrator for this information.
Updating a User
Choose one of the following to update a user:
■
Select the USERS option from the Administrative Menu.
■
Type USERS on the command line and press Enter.
When the Directory of CA Dataquery Users panel is displayed, position the cursor on a user name and press <PF4> UPDATE. You may request that the list be positioned on a certain name by entering the command followed by the user's name.
Chapter 24: Authorizing Users 221
Accessing User Information
For example:
USER JONES
CA Dataquery then displays the User Table Maintenance panel. This panel and all its
fields are explained in detail starting in
Adding a New User
needed changes to the appropriate fields. When you have completed your input, press
<PF3> UPDATE to save the new user definition.
Managing Active Users
Summary
You can manage the activities of any user currently signed on to your CA Dataquery system. You are able to:
■
Force a user off.
■
Send a message to one or more users.
■
Cancel any query processing during a FIND.
■
Cancel printing for any user.
(Anyone with PRINTER CONTROL authorization can start, stop, restart, and cancel spooled print jobs using the PRINTER CONTROL option on the Administrative Menu.
Adding a New User
(see page 212) to assign printer control.)
Purpose
This section describes how to operate the ACTIVE command and tells how to perform these activities.
Choose one of the following to display the active users:
■
Select the USERS option from the Administrative Menu, then press <PF5> ACTIVE
USERS from the Directory of DATAQUERY USERS panel.
■
Type ACTIVE on the command line and press Enter.
222 Administration Guide
Accessing User Information
CA Dataquery displays the Directory of Active Users panel, allowing you to view the active CA Dataquery users, an example of which follows:
Directory of Active Users (DQAJ0)
=>
Place any character next to the name and press the appropriate PF key
------------------------------------------------------------------------DQAJ0
DATAQUERY: DIRECTORY OF ACTIVE USERS START WITH: => _______________________
-----------------------------------------------------------------------------
SEL | USER NAME | TERMID | STAGE | TIME ON | ELAPSED
-----------------------------------------------------------------------------
_ | | | | |
_ | | | | |
_ | | | | |
_ | | | | |
_ | | | | |
_ | | | | |
_ | | | | |
_ | | | | |
_ | | | | |
_ | | | | |
_ | | | | |
_ | | | | |
_ | | | | |
_ | | | | |
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> FORCE OFF <PF4> CREATE MSG.
<PF5> SEND MSG. <PF6> CANCEL FIND <PF7> BACKWARD <PF8> FORWARD
Panel Description
Each column on the Directory of Active Users panel is explained in the following list:
SEL
Type any character on the blank to select a user.
USER NAME
Alphabetical listing of all users currently signed on.
TERMID
User's terminal ID.
STAGE
Function the user is performing.
ADMIN
The user is performing an ADMINISTRATION function.
DISPL
The user is using a display function (PF keys or commands).
Chapter 24: Authorizing Users 223
Accessing User Information
EDIT
The user is on the EDIT panel.
EXEC
The user is executing a query.
FIND
The FIND function is running for an executing DQL query.
GRAPH
The GRAPH function is operating.
GUIDE
The GUIDE function is operating.
HELP
The HELP function is operating.
LIST
A LIST function is operating.
MENU
The user is on the MAIN Menu.
PDB
The user is using the Personal Database Facility.
PERR
An error is being displayed.
SELECT
An executing SQL query is processing the SELECT clause.
SQL
The user is using SQL Mode.
TIME ON
Time this user signed on in hours, minutes, and seconds.
ELAPSED
Amount of time this user has been signed on to CA Dataquery.
224 Administration Guide
Accessing User Information
Activities
Refer to the following list for instructions on managing active users:
Terminate an active user.
Enter a character next to one or more users' names and press <PF3> FORCE OFF.
Note: We recommend that you warn users by sending a message so they can terminate current processes.
Broadcast a message.
1. Press <PF4> CREATE MSG.
2. Enter a one-line message on the Create a Message panel.
3. Press <PF2> RETURN.
4. Mark users, with any character, to receive the current message.
5. Press <PF5> SEND MSG.
Interrupt query or dialog processing during data selection.
1. Select a user.
2. Check that Stage is Find.
3. Press <PF6> CANCEL FIND.
SQL Mode
The CANCEL FIND function may not be used for an SQL query in the SELECT stage. If long running SQL queries appear to be a problem at your site, contact your Database
Administrator for assistance with canceling the long running SQL query and/or reducing the value of the REQTHD parameter of the CA Datacom CICS Services DBCVTPR macro.
The Database Administrator can cancel a long running SQL query in either of two ways:
■
Use the COMM function of DBUTLTY to cancel the query's CA Datacom/DB request.
See the CA Datacom/DB DBUTLTY Reference Guide for further information. The
Database Administrator can temporarily reduce the size of the REQTHD parameter of the CA Datacom CICS Services DBCVTPR macro by using the DBOC GENOPTS function. See the CA Datacom CICS Services documentation for more information.
■
Limit the future occurrence of any long running queries (both SQL and DQL) by permanently reducing the size of the REQTHD parameter. This parameter limits the number of CA Datacom/DB requests that any logical unit of work can make. Any tasks exceeding this limitation will be abended. See the CA Datacom CICS Services documentation for more information.
Chapter 24: Authorizing Users 225
Accessing User Information
Deleting a User
If you need to delete a user who has left the company or has been transferred, review the user's queries, terms, dialogs, personal database, and so on, to see if they need to
be removed, or assigned to another user. (See
Changing the Extended Attributes of a
Query, Dialog or Term
(see page 146) for more information.)
Caution Reassign the JCL members and authorizations that you wish to keep before deleting a user because CA Dataquery deletes the user, the user's JCL member and his authorizations. The user's CA Datacom Datadictionary PERSON entity-occurrence is not deleted.
An example of a Directory of CA Dataquery Users Panel follows:
Directory of CA Dataquery Users (DQK90)
=>
Place the cursor on a name to delete or update. Use PF3 to add new users
------------------------------------------------------------------------DQK90
DATAQUERY: DIRECTORY OF DATAQUERY USERS START WITH => _______________
-----------------------------------------------------------------------------
USER NAME | DATE ADDED | DATE USED | TERMINAL USED
-----------------------------------------------------------------------------
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> ADD <PF4> UPDATE
<PF5> ACTIVE USERS <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
<PF9> PASSWORDS <PF10> PROFILE
Action
The START WITH field, located in the upper-right corner of this panel is where you enter the full or partial name of the user where you want the listing to start. When you press
Enter, CA Dataquery refreshes the Directory of CA Dataquery USERS panel with the user that you specified on the first line of the listing. You can also page forward using <PF8>
FORWARD or backward using <PF7> BACKWARD until you reach the member that you want to view and/or edit.
226 Administration Guide
Accessing User Information
Choose one of the following to delete the user:
■
Choose the USERS option from the Administrative Menu.
■
Type USERS on the command line and press Enter.
When CA Dataquery displays the Directory of CA Dataquery Users panel, place the cursor on the user name that you want to delete. (You cannot delete yourself.) Press
<PF6> DELETE to delete that user. CA Dataquery then redisplays the Directory of CA
Dataquery Users panel.
Adding a New User
(see page 212) for an explanation of the Directory of CA
Dataquery Users panel and its PF keys.
Authorizing Administrative Functions
Concept
Because of the impact on security, the number of administrators with User Table
Maintenance authorization should be kept to a minimum. You can authorize an administrator for all of the administrative tasks, or you can selectively authorize an administrator for one or more tasks. You should evaluate your site's needs thoroughly before making administrative assignments. CA Dataquery permits you to reassign any of these administrative functions should your needs change.
Administrative Menu (DQKH0)
=>
------------------------------------------------------------------------DQKH0
DATAQUERY: ADMINISTRATIVE MENU
-----------------------------------------------------------------------------
Enter DESIRED OPTION NUMBER ===> __
1. PROFILE - Display and update user profile
2. CONDITIONS - List create and maintain conditions
3. RESTRICTIONS - List create and maintain restrictions
4. PRINTER CONTROL - Request control functions for a network printer
5. JCL - List and maintain batch query JCL
6. DIAGNOSTICS - Produce storage dumps
7. LANGUAGE - Translate DATAQUERY text to another language
8. USERS - List and maintain DATAQUERY users
9. SETS - List and maintain saved sets
10. LIBRARY - Maintain query library member attributes
11. SECURITY CONTROL - Table and column security authorization
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Chapter 24: Authorizing Users 227
Accessing User Information
Panel Description
The following is a brief explanation of each administrative function as seen on the panel:
PROFILE
Display or update your profile. CA Dataquery allows each user (who is not an associate user) to modify his profile option defaults for CA Dataquery's online and batch features, primary and secondary language selections, and network printing options. The administrator can modify any user's profile from the Directory of
Dataquery Users panel. Several of the fields in a user's profile default to values specified at the time the user is created or maintained using the USERS function discussed below. If you do not specify an option, it defaults to the DQSYSTBL system defaults.
CONDITIONS
Create, delete, view, or edit a condition. A condition (when listed in a restriction) allows a user or group of users access to some, but not all, of the rows in a table based on the content of one or more columns. The administrator names the condition, identifies the table and states the condition. For example, the condition may restrict access to all COMPANY rows containing a value of 20 in the column for sales ID and a value of DALLAS in the city column. You can print a report of each of the conditions with a list of the restrictions where the condition applies. Conditions
are discussed in more detail in the section on
Using Restricted Conditions
page 284)l.
RESTRICTIONS
Create, delete, view, or edit a restriction. A restriction is a list of conditions restricting user or group access to view or manipulate data. The administrator can restrict user access at the user level or at the user's group ID level. Restrictions are
Using Restricted Conditions
print a report which lists all of the restrictions and the conditions within the restrictions.
PRINTER CONTROL
Display a directory of outstanding network print requests. It allows a request to be canceled (flushed), restarted, or stopped.
JCL
Create, delete, view, or edit JCL members and PROCs. The JCL directory lists the JCL members and PROCs used for executing batch query jobs.
DIAGNOSTICS
Display the CA Dataquery Request Table or request a storage dump in the form of a transaction dump or a module dump. DIAGNOSTICS is to be used only under the direction of CA Support for the purpose of resolving problems as quickly as possible.
The administrator chooses where (terminal ID) and when the dump is to be turned on or off.
228 Administration Guide
Accessing User Information
LANGUAGE
Translate, edit, delete, and display CA Dataquery panels, program literals, and vocabulary terms to another language. You can use this function to edit CA
Dataquery to reflect a different language, language dialect, or terminology used in your company's daily business. The administrator also uses this function to place messages on the CA Dataquery bulletin board.
USERS
Add, delete, view, and update users, list active users, and send messages. The administrator can maintain a user's name, password, accounting code, group level, and authorization for administrative functions. The administrator can also override system defaults as well as list and deactivate active users and send messages.
A CA Dataquery Administrator who is authorized for the USERS function, can establish any new user to CA Dataquery or change a user's signon characteristics as discussed above. They can also assign system and group passwords. Administrators cannot delete themselves or turn off their USERS maintenance authorization.
The USERS authorization is the key to all other authorizations and you should carefully control authorization to this function.
SETS
View, delete, and use all saved found sets. Anyone (except the associate user) who runs a query can save the resulting collection of data as a saved found set. The administrator can reuse the data in a found set, delete the found set, or view a listing of the found sets.
LIBRARY
Create, delete, edit, execute, or submit a query, dialog, or term. The administrator has the ability to define or modify the extended definition of a query, dialog, or term which includes specifying it as private or public. He can also modify the groups assigned to the query, dialog, or term and/or to the author. The administrator can create queries, establish dialog definitions, and submit and validate queries. The
LIBRARY function maintains the attributes (extended definitions) of the query library.
If QRYGRPS=YES is specified in the DQOPTLST macro, you can partition the public query library. Once a query, dialog, or term is designated as public, only an administrator with LIBRARY authorization can make changes to it and its extended attributes because queries designated PUBLIC belong to the group not the author.
Group level assignments limit the scope of a query, dialog, or term to which the
LIBRARY authorization extends. If the group level assignments do not match the administrator's group level assignments, the administrator cannot access the query, dialog, or term. If no group level assignment is made, the access is unlimited.
Chapter 24: Authorizing Users 229
Adding and Changing Passwords
SECURITY CONTROL
Enables access to data by authorizing DQL Mode users to a database and tables, tables to a user, or profile codes to a user as well as to copy profile codes and authorizations from user to another. This function provides table and column security authorization for a user.
Each of the above administrative functions is a tool for the maintenance of your CA
Dataquery system. Consider all aspects of your CA Dataquery security as discussed in this chapter before delegating responsibilities. (You can always make reassignments later.) It is useful to assign LIBRARY authorization to one user in each group so that this user can administer public queries, dialogs, and terms for the group. It is imperative that you carefully consider your site's needs and allocate the authority to use each
administrative function to the appropriate user(s). See
Adding a New User
page 212), specifically the ASSOCIATE USER option.
Limiting User Functions to Manipulate Data
CA Dataquery allows you to limit a user's ability to FIND, UPDATE, INSERT, and ERASE data based on their ability to access that data. Once you have identified all tables, rows, and columns and their related restrictions, you should decide which functions you will permit the user to perform on the accessible data. Users should always be permitted to
FIND the data in the authorized tables. However, you most likely want to limit some users' ability to UPDATE, INSERT, and/or ERASE data. The administrator with SECURITY
CONTROL authorization assigns the FIND, UPDATE, INSERT, or ERASE functions when he authorizes each user to a table or profile code in DQL Mode.
Adding and Changing Passwords
Types of Passwords
Passwords can be added or changed on one of three levels:
Individual Password
An individual password is assigned to an individual user to allow access to the CA
Dataquery system.
Group Password
A group password is assigned to members of a group.
230 Administration Guide
Adding and Changing Passwords
System Password
A system password protects the CA Dataquery system from unauthorized access from any users who do not use the system password when signing on to CA
Dataquery.
Which Password?
Only one of the three types of passwords accesses CA Dataquery. The highest level password is SYSTEM, the next highest level is GROUP and the lowest level password is the individual user password. The highest level password assigned is the only one that will access the system.
All passwords are one to nine characters in length. The passwords are not displayed at any time. If a user forgets his individual password, assign a new password.
Assigning Passwords to Users and to Groups
Concept
CA Dataquery protects access to the CA Dataquery system on one of three levels, which means that a user can have only one password, individual, group or system:
■
Each individual user can have a unique password to allow access to CA Dataquery, which may be changed as necessary if NEWPASS= YES is specified in the DQOPTLST macro.
■
A group can have a unique password to allow users assigned to that group level access to CA Dataquery when they use the group password. The group password supersedes the individual password.
■
All users on the system are assigned a common password that allows access to CA
Dataquery. The system password supersedes the group and individual passwords.
CA Dataquery protects passwords from indiscriminate viewing by never displaying them.
Assigning and changing passwords are the responsibilities of the CA Dataquery
Administrator, with user maintenance authorization.
Chapter 24: Authorizing Users 231
Adding and Changing Passwords
Assigning Group Levels
Concept
A group ID is a defined group of users who are given access to queries, and JCL members
(DQL Mode and SQL Mode). The group ID also extends to those users to whom restricted conditions can be assigned (DQL Mode only). Passwords can be assigned by group level.
There are three descending levels of group IDs which may be assigned to a user:
■
Level 1 is the high-order group,
■
Level 2 is the middle-order group, and
■
Level 3 is the low-order group.
If a user is assigned to a level 3 group, the user must also be assigned to a level 2 and a level 1 group. If the user is assigned to a level 2 group, the user must also be assigned to a level 1 group. This group specification limits the user's access to specific data in accordance with the definition established for each group.
For example, if your company were divided into departments called Accounting,
Production, Research, and Sales, these categories might be your high-order level 1 groups. If the company were also divided into branches, your middle-order level 2 groups might be Austin, Dallas, Houston, and Midland. Each user could be further categorized according to position for the low-order level 3 groups, for example, Clerical,
Executive, Representative, and Supervisor. For instance, a data entry user in Austin could have the following groups:
■
Level 1 group: Production
■
Level 2 group: Austin
■
Level 3 group: Clerical
Groups are a convenient way of organizing and classifying users. Also, you can optionally use groups to partition the public query library and limit users' access to queries. When group level assignments are made to a user or query, those assignments should match, except in the case where the user or query has no group level assignment for one or more levels.
For example, if a user is assigned to group levels as discussed above and a query is assigned to level 1 - Production, level 2 - Austin, and level 3 - Supervisor, that user could not access this query because the query's level 3 assignment is Supervisor, not Clerical.
However, if the query had no level 3 assignment (it is left blank), users in the Austin production group could access the query.
Under your direction, group IDs should be made for each user at the time that user is authorized to access CA Dataquery. Group assignments may be modified at any time.
232 Administration Guide
Adding and Changing Passwords
Assigning a Password to a User
Only an authorized administrator can change an individual password. Assign an individual password as follows:
Step 1
Select the USERS option on the Administrative Menu or enter USERS on the command line. Press Enter. CA Dataquery displays the Directory of CA Dataquery Users panel.
Step 2
Place cursor on the user's name. Press <PF4> UPDATE. CA Dataquery displays the User
Table Maintenance panel.
Step 3
Tab over to the PASSWORD field. Enter the password. Press <PF4> UPDATE. CA
Dataquery processes the new password which is in effect the next time the user signs on.
Note: The System Option Table parameter NEWPASS= must be YES to allow users to change their individual password on the CA Dataquery signon panel. If NEWPASS= is NO, then only a CA Dataquery Administrator can change individual passwords.
Assigning a Password to a Group or a System
Only an authorized administrator can assign a group or a system password. To assign a group or system password:
Step 1
Select the USERS option on the Administrative Menu, or type USERS on the command line. Press Enter. CA Dataquery displays the Directory of CA Dataquery Users panel.
Step 2
Press <PF9> PASSWORDS. CA Dataquery displays the Directory of Defined Dataquery
Groups (DQDB0) panel.
Chapter 24: Authorizing Users 233
Adding and Changing Passwords
Directory of Defined Dataquery Groups (DQDB0)
=>
Place cursor by group assignment and press appropriate PF key.
------------------------------------------------------------------------DQDB0
DATAQUERY: DIRECTORY OF DEFINED DATAQUERY GROUPS START WITH: _______________
-----------------------------------------------------------------------------
GROUP LEVEL 1 | GROUP LEVEL 2 | GROUP LEVEL 3 | PASSWORD ASSIGNED
-----------------------------------------------------------------------------
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> GROUP PSWD <PF4> SYSTEM PSWD
<PF5> NOT USED <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
This directory is composed of four columns. Each row names the group levels assigned to a user. CA Dataquery specifies a YES or NO in the PASSWORD ASSIGNED column to indicate if a password is assigned for this user. Read the panel to find if any passwords are currently assigned.
234 Administration Guide
Adding and Changing Passwords
Assigning Group Passwords
Assign a group password as follows:
Step 1
On the Directory of Defined Dataquery Groups panel, place the cursor on the group name. Press <PF3> GROUP PSWD. CA Dataquery displays the Password Maintenance -
Assign New Password panel.
Password Maintenance - Assign New Password (DQKQ0)
=>
Enter the new password and press PF3 to assign the password
------------------------------------------------------------------------DQKQ0
DATAQUERY: PASSWORD MAINTENANCE - ASSIGN NEW PASSWORD
-----------------------------------------------------------------------------
GROUP LEVEL 1 _______________
LEVEL 2 _______________
LEVEL 3 _______________
NEW PASSWORD _________
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> ASSIGN PASSWORD <PF4> NOT USED
Step 2
Enter the new password in the NEW PASSWORD field. Press <PF3> ASSIGN PASSWORD.
CA Dataquery processes the new password which is in effect the next time the user signs on.
Chapter 24: Authorizing Users 235
Adding and Changing Passwords
Assigning System Passwords
Assign a system password as follows:
Step 1
From the Directory of Defined Dataquery Groups panel, press <PF4> SYSTEM PSWD. CA
Dataquery displays the Password Maintenance - Assign New Password panel.
Password Maintenance - Assign New Password (DQKQ0)
=>
Enter the new password and press PF3 to assign the password
------------------------------------------------------------------------DQKQ0
DATAQUERY: PASSWORD MAINTENANCE - ASSIGN NEW PASSWORD
-----------------------------------------------------------------------------
DATAQUERY SYSTEM
NEW PASSWORD _________
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> ASSIGN PASSWORD <PF4> NOT USED
Step 2
Enter the new password in the NEW PASSWORD field. Press <PF3> ASSIGN PASSWORD.
CA Dataquery processes the new password which is in effect the next time the user signs on.
236 Administration Guide
Performing User Table Maintenance (DQUSERMT)
Deleting Passwords
<PF6> DELETE
Deletes a password for group or system.
Delete an individual password as follows:
Action:
Enter the user's signon and current password. Then, enter NONE in the NEW
PASSWORD field on the CA Dataquery signon panel. Or, blank the password field on the user maintenance panel.
Result:
This will delete the current password for this user.
Delete a group or system password:
Action:
From the Directory of Defined Dataquery Groups panel, position the cursor on the appropriate line and press <PF6> DELETE.
Result:
This will delete the group or system password.
Performing User Table Maintenance (DQUSERMT)
Use the DQUSERMT utility to perform the following maintenance tasks on the User
Table (DQU):
■
Add user authorization
■
Update user authorization
■
Delete user authorization
■
Report by user identifier or group level designation on all or selected users
The CA Dataquery User Table (DQU) stores definitions of valid CA Dataquery users. It contains user attributes (such as name and password) which are used to validate a user.
The utility, DQUSERMT, is used to perform the same functions in batch as online. This utility is especially useful for adding a large group of users at one time to the DQU, for example when CA Dataquery is installed.
Note: If the user table is enabled, you can execute queries against it. Use the table name DATAQUERY-DQU.
Chapter 24: Authorizing Users 237
Performing User Table Maintenance (DQUSERMT)
User Table Maintenance Control Statements
Use the table maintenance control statements to identify the functions to be performed by DQUSERMT. A maximum of 60 report and maintenance control statements is allowed. There are five types of maintenance control statements:
SIGN/ON
(Required) Specifies the user ID and password. Only one SIGN/ON statement is allowed and it must be the first statement in the job stream.
ADD
Selects adding a user as the type of maintenance this run performs.
UPDATE
Selects updating a user as the type of maintenance this run performs.
DELETE
Selects deleting a user as the type of maintenance this run performs.
REPORT
Selects the type of report this run produces.
Enter the control statements in the following sequence.
■
SIGN/ON
■
ADD, UPDATE, DELETE, or REPORT (use one)
SIGN/ON Statements
For all of the functions the first control statement is the SIGN/ON statement. The
SIGN/ON control statement is formatted as follows:
►►─ SIGN/ON ─ userid
─ PASSWORD ─ password
───────────────────────────────────►◄
SIGN/ON
(Required) Specifies the user ID and password. Only one SIGN/ON statement is allowed and it must be the first statement in the job stream. The SIGN/ON statement begins in column 1.
userid
Specifies the user ID of the person executing the DQUSERMT utility. The user ID begins in column 11.
Valid Entries:
A 1- to 32-character user ID
Default Value:
(No default)
238 Administration Guide
Performing User Table Maintenance (DQUSERMT)
password
Specifies the password of the person executing the DQUSERMT utility. (PASSWORD keyword is required unless no password is assigned.)
Valid Entries:
A 1- to 9-character password
Default Value:
(No default)
ADD and UPDATE Statements
For the ADD or UPDATE functions, the second statement in the job stream is ADD or
UPDATE.
►►─┬─ ADD ────┬───────────────────────────────────────────────────────────────►
└─ UPDATE ─┘
┌──────────────────────┐
►─ USER= userid
─┬──────────────────┬─▼─┬──────────────────┬─┴────────────────►◄
└─
,option1=value
─┘ └─
,option2=value
─┘
ADD
To add a new user ID, specify the ADD statement beginning in column 1.
UPDATE
To modify an existing user ID, specify the UPDATE statement beginning in column 1.
USER=
(Required) Beginning in column 11, specify USER= followed by the user ID to be added or updated.
Valid Entries:
A 1- to 32-character user ID
Default Value:
(No default)
Chapter 24: Authorizing Users 239
Performing User Table Maintenance (DQUSERMT)
,option1= and ,option2=
(Optional) Following the user ID, code optional keywords which specify the characteristics of the user ID being added or modified.
■
■
The available options are listed on the following pages under the following categories:
■
User Authorization Options - page ADD and UPDATE Statement Optional
Keywords
■
Administrative Functions - page ADD and UPDATE Statement Optional
Keywords
■
Override System Defaults - page ADD and UPDATE Statement Optional
Keywords
Profile Options - page ADD and UPDATE Statement Optional Keywords
Printer Options - page ADD and UPDATE Statement Optional Keywords
If you omit an option, CA Dataquery uses the default for that option.
Leave no spaces in the keyword portion of the statement. Use an equal sign (=) to separate an option type from its value, and a comma (,) to separate the options. Do not enter options past column 72. Enter an X (or any non-blank character) in column 72 to indicate that the line is continuing. There are 20 lines allowed for continuations.
ADD and UPDATE Statement Optional Keywords
The COPYFROM= keyword is only valid on an ADD statement. All other keywords are valid on either an ADD or an UPDATE statement.
COPYFROM=
(Optional) Specifies that the characteristics of the new user ID being added are to be copied from an existing user ID. Follow COPYFROM= with an existing user ID.
This option can only be used with the ADD statement. This is a very useful option for adding a large number of users.
User Authorization Options
For both the ADD and UPDATE statement the following options are valid:
ACNTCODE= (Accounting Code)
(Optional) Specify the CA Datacom/DB accounting code to be used with CA
Datacom/DB accounting for CA Dataquery. See your Database Administrator for this information. (No default)
240 Administration Guide
Performing User Table Maintenance (DQUSERMT)
ASSOCUSR= (Associate User)
(Optional)
Y (yes) specifies that this user can only perform associate user tasks.
N (no), the default, does not limit this user to associate user tasks; thus enabling this user to create and edit queries, view database information, use commands, and so on.
AUSRMNT= (Access User Maintenance)
(Optional)
Y (yes) permits user to see a list of active CA Dataquery users and perform such functions as broadcasting messages, forcing signoff, and cancel FIND in progress.
N (no), the default, does not allow the user to perform active user functions.
DATAAUTH= (Data Authorized)
(Optional) Authorizes the user read-only access to all data available to CA
Dataquery.
Y (yes), allows the user read-only access to data. CA Dataquery does not perform any data security check.
N (no), the default, CA Dataquery qualifies this user's access to data by the data authorizations specified in security control.
EXPORT= (Export Allowed)
(Optional) Specify if this user is permitted to build a CA Dataquery batch export file whereby data accessed from the database is exported and saved for later use. It allows the user to use the EXPORT command while using batch CA Dataquery.
Y (yes), the default, allows the user to export data.
N (no) prohibits the user from exporting data.
GROUP1= (GROUP LEVEL 1)
(Optional) Enter a valid 1- to 15-character alphanumeric group level 1 name for CA
Dataquery security control. (No default.) See the discussion in
Assigning Group
Levels
(see page 232) for more information.
GROUP2= (GROUP LEVEL 2)
(Optional) Enter a valid 1- to 15-character alphanumeric group level 2 name as specified in CA Dataquery security control. If you enter a group level 2 name, you
must also enter a group level 1 name. (No default.) See the discussion in
Assigning
Group Levels
(see page 232) for more information.
Chapter 24: Authorizing Users 241
Performing User Table Maintenance (DQUSERMT)
GROUP3= (GROUP LEVEL 3)
(Optional) Specify a valid 1- to 15-character alphanumeric group level 3 name as specified in CA Dataquery security control. If you enter a group level 3 name, you must also enter a group level 1 and a group level 2 name. (No default.) See the
Assigning Group Levels
(see page 232) for more information.
PASSWORD=
(Optional) Enter a 1- to 9-character alphanumeric password. This field is used to assign an individual user password. (No default.)
QRYLANG= (Query Language)
(Required) Specify SQL if SQL, or DQL if DQL Language, is authorized for this user.
DQL is the default and limits the user to DQL Language only. Specifying
QRYLANG=SQL and SQLDQL=Y (see page ADD and UPDATE Statement Optional
Keywords) authorizes the user to both query languages. (Default is DQL.)
REPTFAC=
This parameter is no longer supported but is retained for compatibility
SQLDDEF= (SQL Data Definition Allowed)
(Optional)
Y (yes) to allow this user to use SQL Data definition statements.
N (no), the default, restricts the user from using CREATE, COMMENT ON, GRANT,
REVOKE and DROP statements.
SQLDMNT= (SQL Data Maintenance Allowed)
(Optional)
Y (yes) to allow this user to use SQL Data maintenance statements.
N (no), the default, restricts the user from using INSERT, UPDATE, and DELETE.
SQLDQL= (SQL and DQL Allowed)
(Optional)
Y (yes) to allow this user to change query languages on his profile.
N (no), the default, restricts the user from changing from DQL to SQL on his profile.
Specifying QRYLANG=SQL (see page ADD and UPDATE Statement Optional
Keywords) and SQLDQL=Y authorizes the user to both query languages. (Default is
DQL.)
SUBMIT= (SUBMIT Allowed)
(Required) Indicate whether this user is allowed to submit batch queries.
Y (yes), the default, permits the submission of batch queries.
N (no) does not.
242 Administration Guide
Performing User Table Maintenance (DQUSERMT)
Administrative Functions
The following options enable (or deny) the user access to any or all administrative functions.
COND= (Conditions)
(Required)
Y (yes) if this user is to have the administrative ability to create, view, delete, or edit a condition.
N (no), the default, denies this user access to the CONDITIONS option on the
Administrative Menu.
DIAG= (Diagnostics)
(Required)
Y (yes) if this user is to have the administrative ability to request a CA Dataquery
Request Table and/or a storage dump in the form of a transaction dump or a module dump.
N (no), the default, denies the user access to the DIAGNOSTICS option on the
Administrative Menu.
FNDSMNT= (Found Set Maintenance)
(Required)
Y (yes) if this user is to have the administrative ability to create, delete, or modify a set.
N (no), the default, denies the user access to the SETS option on the Administrative
Menu.
JCLMNT= (JCL Maintenance)
(Required)
Y (yes) if this user is to have the administrative ability to create, delete, view, or edit a CA Dataquery JCL member.
N (no), the default, denies this user access to the JCL MAINTENANCE option on the
Administrative Menu.
LANG= (Language)
(Required)
Y (yes) if the user is to have the administrative ability to translate, edit, delete, or display CA Dataquery panels, program literals, and vocabulary terms to another language.
N (no), the default, denies access to the LANGUAGE option on the Administrative
Menu.
Chapter 24: Authorizing Users 243
Performing User Table Maintenance (DQUSERMT)
MAXIO= (Estimated Maximum I/O for a FIND)
(Optional) A value from 1 through 99999 used to specify a threshold value for estimated I/O for DQL find processing. When this value is exceeded, the user will be presented a panel and asked if he wants to continue. The system default from the
CA Dataquery System Option Table is used if this value is zero.
PDB= (Personal Database)
(Required)
Y (yes) if this user is allowed to create and maintain personal tables. Also authorizes a user to create personal tables for his own individual use. Specify the area of the database where personal tables are to be stored in Override System Options.
N (no), the default, prohibits the user from having personal tables.
PRTCTL= (Printer Control)
(Required)
Y (yes) if this user is to have the administrative ability to start, stop, restart, and cancel spooled print jobs.
N (no), the default, denies the user access to the spooled print job functions on the
Administrative Menu.
QRYLMNT= (Query Library Maintenance)
(Required)
Y (yes) if this user is to have the administrative ability to create, maintain, execute, and/or submit queries listed on the Admin Directory of Queries and Terms panel.
N (no), the default, denies this user access to the LIBRARY option on the
Administrative Menu.
REST= (Restrictions)
(Required)
Y (yes) if this user is to have the administrative ability to create, delete, view, or edit a restriction.
N (no), the default, denies the user access to the RESTRICTIONS option on the
Administrative Menu.
SECMNT= (Security Maintenance)
(Required)
Y (yes) if the user is to have the administrative ability to relate users to a table, tables to a user, or profile codes to a user. This field authorizes this user record and field security control functions.
N (no), the default, denies the user access to the Security Control option on the
Administrative Menu.
244 Administration Guide
Performing User Table Maintenance (DQUSERMT)
USERMNT= (User Maintenance)
(Required)
Y (yes) if this user is to have the administrative function of adding, deleting, and maintaining users, as well as access to active users, passwords, and profile.
N (no), the default, prohibits this user from viewing and/or accessing the USERS and
PROFILE options on the Administrative Menu. :nt text='Caution'. Any user that has authorization for this function has the ability to authorize themselves or others to perform any of the administrative functions. Care should be taken when deciding who and how many users may have this authority as this is a key to security. If a user is authorized for User Maintenance, that user cannot change his own authorization to N (no).
Override System Defaults
The following options enable the user to override system default options.
AUTHID= (SQL Authorization ID)
(Required if the query language authorized for this user is SQL, or if personal
database is authorized for this user, or if SQL AND DQL ALLOWED=YES.) Enter a 1- to
18-character authorization ID. This establishes the user's default authorization ID for personal database and for all SQL Mode. (No default)
FNDBLKS= (DQF Blocks Available)
(Optional) Enter a value from 1 through 99999 to specify the total number of physical blocks on the DQF (found table) that this user can own at one time during a query execution. Ensure that the value specified for this user still leaves adequate space for all other users. (The system default is used if this value is zeros.)
MXREQ= (Maximum Number of Requests)
(Optional) Input a numeric value from 1 through 99999 to specify a search limit for this user that overrides the system default. This feature limits the amount of time
CA Dataquery is to process before pausing to allow the user to end the query.
MXREQ keeps one query from monopolizing the system. (The system default is used if this value is zeros.)
MXTLR=
(Optional) Indicate a value from 1 through 99999 to specify the number of times CA
Dataquery is to relinquish control to other tasks during a query execution before pausing to allow a user to end processing. (The system default is used if this value is zeros.)
Chapter 24: Authorizing Users 245
Performing User Table Maintenance (DQUSERMT)
NETPRTID= (Network Printer ID)
(Optional) Specify the 1- to 4-character network printer ID to be used by this user.
PDBAREA= (Area for Personal Database Tables)
(Optional) Specify the 1- to 32-character name for the CA Datacom/DB area to be used for this user's personal tables. Check with the CA Datacom/DB Administrator for this information. The default is in the System Option Table or if this is blank, the default is the CA Datacom/DB SQL DEFAULT area specified in MUF startup options
(see the CA Datacom/DB Database and System Administration Guide for more information on MUF startup options).
PRIMARY= (Primary Language)
(Optional) Specify the 2-character primary language ID for this user's primary language. AE (American English), the default, is automatically distributed with CA
Dataquery. Your site can also have German, French, or any other language of your company's choosing. (Default is AE.)
SECONDARY= (Secondary Language)
(Optional) Specify the 2-character secondary language ID for this user's secondary language. AE (American English), the default, is automatically distributed with CA
Dataquery. Your site can also have German, French, or any other language of your company's choosing. (Default is AE.)
SORTCTG= (SORTCTG)
(Optional) Input a value from 1 through 16 to specify, in 4096-byte pages, the maximum amount of contiguous storage area for in-core sorting which CA
Dataquery requests of CICS at one time. If this amount is not available when needed, CA Dataquery tries to allocate a number of smaller areas for the sort.
SORTPAG= (SORTPAG)
(Optional) Enter a value from 1 to 1024 to specify, in 4096-byte pages, the maximum amount of storage CA Dataquery is to allocate to process a single sort request without using the database index for sorting. The value specified here overrides the system default for this user. (The system default is used if this value is zeros.)
246 Administration Guide
Performing User Table Maintenance (DQUSERMT)
Profile Options
The following options enable the user to override system default options.
ALIASES= (List and Display Aliases)
(Optional)
Y (yes) to include CA Datacom Datadictionary aliases in the Directory of Tables, Keys and Fields Display, Fields Display, and Keys Display panels.
N (no), the default, excludes CA Datacom Datadictionary aliases from these display panels. (See the CA Dataquery end user documentation for details on these panels.)
DPCHAR= (Decimal Point Character)
(Optional) Enter 1 character. Specifies the character that the user wishes to use as a decimal point. Do not list as the last option on a statement. If necessary, add the
QUERYLANG= option for the mode in use after DPCHAR=. The default is the value of the DECPT= parameter in the System Option Table.
DUPCOLSP= (Suppress Duplicate Columns)
(Optional) Determines if duplicate values for columns specified as control break columns are suppressed in the generated report.
Y (yes), the default, the value contained in a control break column is displayed only once. Each time the value in the control break column changes, the new value is displayed. If the output continues to the top of a new page, the current value in the control break column is displayed at the top of the new page.
N (no), value prints on every detail line.
EXPNLSP= (Suppress Execute Panel)
(Optional)
Y (yes) to suppress the display of the Online Execute Query panel. Users would want to suppress the display of the Online Execute Query panel if their queries always read and collect data and display it on their terminals. Suppressing the display saves a step during the execution process by accepting the execution defaults.
N (no), the default, causes the Online Execute Query panel to be displayed.
GROUPDIS= (Group Display)
(Optional) Determines the manner in which a compound field is represented when displayed on a report.
Y (yes), fields comprising the compound field are shown as individual fields.
N (no), the default, a compound field is shown as though it is a single alphanumeric field, even though one or more of the simple fields contained in the compound field is a numeric field which cannot be printed. (Default is N)
Chapter 24: Authorizing Users 247
Performing User Table Maintenance (DQUSERMT)
PRTPFKSP= (Suppress PFKeys on Print)
(Optional)
Y (yes) to suppress the PF key descriptions on the print panel that displays the report.
N (no), the default, causes the PF keys descriptions to be displayed.
Printer Options
The valid printer options are:
PBANNER= (Print Banner Page)
(Optional)
Y (yes), the default, if this user's print jobs are to be preceded with a banner page containing user name, date, and time, to aid in distributing the reports.
N (no) suppresses the printing of the banner page.
PCOLS= (Printer Number of Columns)
(Optional) Specify the width of the hardcopy on the network printer by stating the number of columns to be printed. Indicate a 3-character numeric value. Valid entries are 00 or 80 to 255. (Default is 0.)
PPGTOGETHER= (Print Pages Together)
(Optional) Use this field when printing a report composed of two adjacent
(side-by-side) pages. If the first page (left-hand page) is labeled A and the second page (right-hand page) is labeled B and the report is three pages in length.
Y (yes), the default, would result in these pages being printed in the order of 1A, 1B,
2A, 2B, 3A, 3B.
N (no) results in a printing order of 1A, 2A, 3A, 1B, 2B, 3B.
PQRYSTAT= (Print Query Statistics)
(Optional)
Y (yes), the default, if the statistics of the query that produced the report are to be printed when the report is printed on the network printer.
N (no) does not print the query statistics.
PQRYTXT= (Print Query Text)
(Optional)
Y (yes), the default, if the text of the query that produced the report is to be printed when the report is printed on an online network printer.
N (no) does not print the query text.
248 Administration Guide
Performing User Table Maintenance (DQUSERMT)
PROWS= (Printer Number of Rows/Page)
(Optional) Specify the number of rows to be printed on one page of hardcopy on the network printer. Indicate a 3-character numeric value. Valid entries are 00 or 12 to 255. 1 through 11 are not valid entries. (Default is 0.)
PRTWINDOWS= (Print Using Windows)
(Optional)
Y (yes) if the report extends beyond 80 columns and you do not want the report lines to wrap.
N (No), the default, if you want the print lines to use wrapping.
JCL Examples
Note: Use the following as a guide to prepare your JCL. The JCL statements are for example only. Lowercase letters in a statement indicate a value you must supply. Code all statements to your site and installation standards.
Sample z/OS JCL
//jobname See the note above and Preparing JCL for Batch CA Dataquery Utilities.
// EXEC PGM=DQUSERMT
//STEPLIB See the note above and Preparing JCL for Batch CA Dataquery Utilities.
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=* Print Output
//SNAPER DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSIN DD *
SIGN/ON username PASSWORD password
control statements
/*
//
Chapter 24: Authorizing Users 249
Performing User Table Maintenance (DQUSERMT)
Sample z/VSE JCL
* $$ JOB ... See the note above and Preparing JCL for Batch CA Dataquery
Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// EXEC DQUSERMT
SIGN/ON username PASSWORD password
control statements
/*
/&
* $$ EOJ
DELETE Statement
The DELETE control statement follows the SIGN/ON statement in the job stream. The
DELETE control statement is formatted as follows:
1-10
Identifies the type of control statement. The valid entry is DELETE. Left-justify the value with trailing blanks as necessary.
11-72
Specifies the option keyword USER and its value. Enter the user name as the value.
There are no spaces in the keyword portion of the statement. An equal sign (=) separates an option type from its value.
►►─ DELETE ─ USER= userid
─────────────────────────────────────────────────────►◄
USER=
Specifies the ID of the person to be deleted from the CA Dataquery system.
Valid Entries:
A 1- to 32-character user ID
Default Value:
(No default)
250 Administration Guide
Performing User Table Maintenance (DQUSERMT)
REPORT Statement
The REPORT control statement follows the SIGN/ON statement in the job stream. The
REPORT control statement is formatted as follows:
1-10
Identifies the type of control statement. The valid entry is REPORT. Left-justify the value with trailing blanks as necessary.
11-72
Specifies the option keyword and its value, as described below.
►►─ REPORT ─┬─ USER= ────────────────────────────────────────────────┬────────►◄
├─┬─ userid
└─ GROUP1=
─┬───────────────────────────────────────────┤
│ └─ *ALL* ──┘ │ value ─┬─────────────────────────────────────┬─┘
└─ ,GROUP2= value ─┬─────────────────┬─┘
└─ ,GROUP3= value ─┘
USER=
Specifies the user ID of the person whose authorizations are to be reported. To report the authorizations for every user defined to the system, code USER=*ALL*.
Valid Entries:
A 1- to 32-character user ID or *ALL*
Default Value:
(No default)
GROUP1=, GROUP2=, and GROUP3=
Specifies the group ID of the group whose authorizations are to be reported. If you specify GROUP3=, you must also specify GROUP2=. If you specify GROUP2=, you must also specify GROUP1=.
Valid Entries:
A 1- to 32-character group ID
Default Value:
(No default)
Chapter 24: Authorizing Users 251
Chapter 25: Securing Data Access for DQL
Use
Securing access to your company's data is a major part of assuring data integrity. If you determined (using the USERS administrative option) that all users are to have unlimited read-only access, they can access all tables, rows, and columns in your database that are not protected by conditions and restrictions. If you do not authorize users for unlimited read-only access, each user can access only those tables (and their rows and columns) that you specifically assign to them.
Summary
This section describes the concepts of assigning users to specific tables, rows, and columns. It also describes how to limit the users' ability to manipulate the data accessed. This section applies only to DQL Mode.
Securing Data Access for SQL Use
(see page 301) for information about SQL
data access.
Limiting Access to Database Tables
Summary
The Database Administrator can list all CA Datacom/DB tables, rows, and columns that the users are going to query. Determine which users need to access which tables and list each user and the tables to which they need access. If your site security is controlled by an external security package, make sure the Security Administrator who manages that package has this information. CA Dataquery uses the external CA Datacom/DB security for table and database level access.
Table assignments control what each user sees on the Directory of Tables panel. When a list of tables is requested, the current authorization ID of the user will be used to read the CA Datacom Datadictionary table for all tables, views, and synonyms for that authorization ID. Items on the list will be checked for read(SELECT) authorization by a call to CA Datacom/DB. Although your site might have specified multiple CA Datacom
Datadictionary DBIDs, all of the data entered under the SECURITY CONTROL administrative function is stored in the CA Datacom Datadictionary DBID named in the
DQOPTLST macro DDDBID= parameter.
Chapter 25: Securing Data Access for DQL Use 253
Authorizing Data Using the Security Maintenance Menu
When you add a user to CA Dataquery using the User Table Maintenance panel under the USERS administrative function, CA Dataquery automatically creates a CA Datacom
Datadictionary PERSON entity-occurrence. This entity-occurrence is added to the dictionary named in the DDDBID= parameter in the DQOPTLST macro. This entity-occurrence name is the same as the CA Dataquery user ID.
For CA Dataquery Security to work there can be no LOCK or password on the following
CA Datacom Datadictionary tables:
■
Person tables
■
Authorization
■
Relationship
Personal tables created in DQL Mode cannot be accessed by another user unless the user knows the full name of the table including its AUTHID.
Note: CA Datacom/DB database IDs can range from 1 to 5000. However, CA Dataquery internal security only allows three digits for a database ID. Therefore, if you have tables in databases with IDs greater than 999 that need to be secured, you must use external security.
In SQL Mode, access to personal tables can only be given by the table creator, using the
GRANT command or through CA Datacom/DB security. The REVOKE command removes the authorization. See the CA Datacom Security Reference Guide documentation for more information on CA Datacom/DB security. See the CA Datacom/DB SQL User Guide for more information about GRANT and REVOKE.
Authorizing Data Using the Security Maintenance Menu
Concept
In a secure operating environment, each user is authorized to access only the data necessary to perform their job. Usually, only a select few have a valid need to freely access the database (such as an administrator).
Determine whether you want to allow each user read-only access to all the data in your database through CA Dataquery. CA Dataquery allows you to give users authorization for unlimited read-only access to the database and performs no further table security check on the user when he has this authorization (except restricted conditions in DQL
Mode). CA Datacom/DB security or an external security product is always in effect. We suggest you limit this authorization to only a few administrators.
254 Administration Guide
Authorizing Data Using the Security Maintenance Menu
If a user is assigned unlimited read-only access by specifying Y (yes) for the DATA
AUTHORIZED parameter on the User Table Maintenance panel, that user can access all tables, rows, and columns in your database that are not protected by CA Datacom/DB security, or do not have any restrictions assigned to the user or his group(s). This user can also access anyone's personal tables.
If you specify N (no) for this field, that user can access only those tables (and their rows and columns) that you specifically assign to that user using the SECURITY CONTROL administrative function. The user can still access other users' personal tables in SQL
Mode, if privileges are granted to him.
Regardless of the DATA AUTHORIZED parameter setting, you must authorize the user, if data is to be modified from DQL Language queries (for INSERT, UPDATE, and ERASE specifically).
How to Limit Access to Tables
Sign on to CA Dataquery and select the SECURITY CONTROL option from the
Administrative Menu or enter the SECURITY command on the command line. CA
Dataquery then displays the Security Maintenance Menu.
Security Maintenance Menu (DQLA0)
=>
--------------------------------------------------------------------DQLA0
DATAQUERY: SECURITY MAINTENANCE MENU
-------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ___
1. DATABASE - Authorize by CA Datacom/DB Bases and Tables to Users
2. USER - Authorize by User to CA Datacom/DB Bases and Tables
----------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Chapter 25: Securing Data Access for DQL Use 255
Specifying Table Options Using the USER Option
The CA Dataquery SECURITY CONTROL function provides you with the following options to assign a user to a CA Datacom/DB table:
Panel Description
DATABASE
This option allows you to name the CA Datacom/DB ID and tables that you are allowing a user to access.
For details about using this option, see
Naming a CA Datacom/DB Database and
Table for User Access
USER
This option allows you to select the user to be assigned and then select the CA
Datacom/DB ID and table(s) to which this user is allowed to perform the FIND,
UPDATE, INSERT, or ERASE commands. You may also copy one user's security to another. The above options allow you to specify whether the user can FIND,
UPDATE, INSERT or ERASE the data on that table. We suggest that you authorize users to the FIND function for the tables they require. Without this authorization, the user cannot read the data in the table.
For details about using this option, see
Specifying Table Options Using the USER
Option
Specifying Table Options Using the USER Option
Access
To authorize a user to perform FIND, UPDATE, INSERT, or ERASE on specific tables, choose the SECURITY CONTROL option from the Administrative Menu. Then select USER from the Security Maintenance Menu. To go directly to the Security User Directory panel, enter SECURITY USER on the command line. If you must relate many users to
many tables, an alternative to online entry exists. For more information, see
Using the
Datadictionary to Relate Multiple Users to Tables
(see page 268). CA Dataquery will
display the Security User Directory panel.
256 Administration Guide
Specifying Table Options Using the USER Option
Security User Directory (DQLM0)
=>
Place the cursor on a name and press the appropriate PF key.
------------------------------------------------------------------------DQLM0
DATAQUERY: SECURITY USER DIRECTORY START WITH => _______________
-----------------------------------------------------------------------------
USER NAME | DATE ADDED | DATE USED
-----------------------------------------------------------------------------
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> SHOW TABLES <PF4> SHOW CODES
<PF5> COPY SECURITY <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
<PF9> NOT USED <PF10> NOT USED <PF11> DELETE TABLES <PF12> DELETE CODES
Action
The START WITH field, located in the upper-right corner of this panel, is where you enter the full or partial name of the user where you want the listing to start. When you press
ENTER, CA Dataquery refreshes the SECURITY USER DIRECTORY panel with the user that you specified on the first line of the listing. You can also page forward using <PF8>
FORWARD or backward using <PF7> BACKWARD until you reach the member that you want to view and/or edit.
Panel Description
The panel provides you with a list of users who are defined in the CA Dataquery system.
It does not, however tell you which users are authorized to access CA Dataquery with the external security package. The panel enables you to perform many tasks specified by the PF keys. The following list explains each column on the panel.
USER NAME
Names each user currently authorized on CA Dataquery.
DATE ADDED
Lists the date the user was added to CA Dataquery.
DATE USED
Lists the date that the user last accessed CA Dataquery.
Chapter 25: Securing Data Access for DQL Use 257
Specifying Table Options Using the USER Option
PF Keys
The following list describes the unique PF keys for the panel-name panel.
Key Objective Result
<PF3>
SHOW
TABLES
<PF4>
SHOW
CODES
Display tables authorized for user selected with cursor
CA Dataquery displays the Security
Table List panel
<PF5>
COPY
SECURITY
<PF6>
DELETE
Display profile codes authorized for user selected with cursor.
How to Limit Access to
Columns
CA Dataquery displays Security Profile
Code List panel
Copy user authorization from user selected with cursor to another user
CA Dataquery displays Directory of
User Copy Targets panel
Delete both table and profile code authorizations for user selected with cursor
CA Dataquery displays message indicating results
Delete table authorizations for user selected with cursor
CA Dataquery displays message indicating results
<PF11>
DELETE
TABLES
<PF12>
DELETE
CODES
Delete profile code authorizations for cursor
CA Dataquery displays message user selected with indicating results
258 Administration Guide
Specifying Table Options Using the USER Option
Modifying Table Authorizations Related to One User
Specifying Table Options Using the USER Option
(see page 256) for instructions
about selecting a user name on the Security User Directory panel and pressing <PF3>
SHOW TABLES to see the Security Table List panel.
Security Table List (DQLG0)
=>
Place the cursor on a file name to delete or update. Use PF 3 to add tables.
------------------------------------------------------------------------DQLG0
DATAQUERY: SECURITY TABLE LIST USER: ________________________________
-----------------------------------------------------------------------------
Database ID | DB Table Name | Find Update Insert Erase
-----------------------------------------------------------------------------
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> ADD <PF4> UPDATE
<PF5> NOT USED <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
Panel Description
The panel lists tables currently related to the user ID you specified on the Security User
Directory panel with their function authorizations. The following list explains each column on the panel.
Database ID
Lists each table name's database ID.
DB Table Name
Names each table currently secured to the user.
FIND, UPDATE, INSERT, ERASE
Represent the CA Dataquery functions which the users can be authorized to perform. A Y in one of these columns indicates the user can perform that particular function for the named database ID and table.
Chapter 25: Securing Data Access for DQL Use 259
Specifying Table Options Using the USER Option
The fields on this screen are for display only. No data can be entered.
Action
To make any necessary changes or additions on the Security Table List panel, place the cursor on the line with the DB Table Name and Database ID to be modified and press the appropriate PF key. <PF3> ADD, <PF4> UPDATE, and <PF6> DELETE are discussed in detail on the following pages.
PF Keys
The following list describes the PF keys:
Key Objective
CLEAR
<PF1> HELP
Return to Security User
List panel Menu
Display Help panels
<PF2> RETURN
<PF3> ADD
<PF4> UPDATE
Return to previous panel
Add new database ID and table for this user
Update a function authorization for this user
<PF5> NOT USED Not in use
<PF6> DELETE Delete a database ID and table for this user
<PF7> BACKWARD Scroll to previous page
<PF8> FORWARD Scroll to next page of list, if any
Result
CA Dataquery displays the
Security User List panel
CA Dataquery displays the Help panel
Returns to previous panel, or
Main Menu
CA Dataquery displays Security
Table Maintenance panel
CA Dataquery displays Security
Table Maintenance panel
CA Dataquery displays message indicating results
Displays previous page
Displays the next page of list, if any
Note: To use <PF4> ADD or <PF6> DELETE, you must select a table/DBID using cursor position.
260 Administration Guide
Specifying Table Options Using the USER Option
Changing Authorizations
To change function authorizations, select a DBID and table name with the cursor and press <PF4> UPDATE. CA Dataquery displays the following panel:
Security Table Maintenance (DQLH0)
=>
Enter the security information and press the appropriate PF key.
------------------------------------------------------------------------DQLH0
DATAQUERY: SECURITY TABLE MAINTENANCE USER: ________________________________
-----------------------------------------------------------------------------
Data Base ID :
DB Table Name : (Enter *ALL* for all tables of the
database ID)
Find:
Update:
Insert:
Erase:
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> UPDATE D
Note: Removing all the authorizations for a particular user deletes that user from the list the next time the user attempts to access that table and does not allow access to that table. If external security is in effect, it overrides any changes you might make on database or table authorizations.
Enter Y or N next to the functions.
If a user had access to only selected tables in a database, to authorize that user access to the entire database, enter *ALL* as the Table Name. The *ALL* authorization supersedes, but does not delete, the individual table authorizations.
For example, if a user had only FIND access to some tables and you want to give that user full access to the entire database, enter *ALL* as the Table Name and, on the next panel, add the user with FIND, UPDATE, INSERT, and ERASE authority. With the *ALL* authorization the user now has FIND, UPDATE, INSERT, and ERASE access to all tables in the database.
Chapter 25: Securing Data Access for DQL Use 261
Specifying Table Options Using the USER Option
If the user previously had FIND and UPDATE access to a specific table and (with the
*ALL* authorization) you specify FIND access to all tables in the database, the user is able to FIND any table but able to UPDATE only the specific table.
When checking authorization, CA Dataquery looks for individual specific table authorization and if that is not found, CA Dataquery looks for *ALL* authorization.
Adding Authorizations
To add a new database ID for the selected user, press <PF3> ADD. CA Dataquery displays the Security Table Maintenance panel.
Security Table Maintenance (DQLH0)
=>
Enter the security information and press the appropriate PF key.
------------------------------------------------------------------------DQLH0
DATAQUERY: SECURITY TABLE MAINTENANCE USER: ________________________________
-----------------------------------------------------------------------------
Data Base ID :
DB Table Name : (Enter *ALL* for all tables of the
database ID)
Find:
Update:
Insert:
Erase:
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> ADD <PF4> NOT USED
If external security is in effect, it overrides any changes you might make on user, database, or table authorizations.
262 Administration Guide
Specifying Table Options Using the USER Option
Panel Description
The panel provides the means to add authorizations to the user ID you specified on the
Security Table List panel. The following list explains each column on the panel:
DATABASE ID
List the 1-3 digit database ID.
DB TABLE NAME
Names the table to be related to the user.
FIND, UPDATE, INSERT, ERASE
Represent the CA Dataquery functions which the users can be authorized to perform. A Y following a table name and database ID in one of these columns indicates the user can perform that particular function.
To add a table to this user's list of accessible tables, enter the 3-digit database ID and the table name, or enter *ALL* to give the user access to all tables in this database.
Press <PF3> ADD to process.
Copying Authorizations
Summary
Copying authorizations from one user to another is a quick way to authorize new users to access the same tables and columns as an existing user. If a user has similar needs to an existing user, you can modify the authorizations after completing the copy function.
You can copy tables only, codes only, or both tables and codes to the new user (target).
Copying Security
Copying security is copying database tables and profile codes from one user to another.
To copy security, choose the SECURITY CONTROL option from the Administration Menu.
Then select USER on the Security Maintenance Menu.
The new user and the existing user have to be listed on the Security User Directory
panel. For information about creating new user IDs, see
Authorizing Users
page 207).
If external security is in effect, it overrides any changes you may make on user, database, or table authorizations.
Chapter 25: Securing Data Access for DQL Use 263
Specifying Table Options Using the USER Option
Place the cursor on the name of the user to be copied and press <PF5> COPY SECURITY.
CA Dataquery displays the following panel:
Directory of User Copy Targets (DQLK0)
=>
Place the cursor on a name for the copy target and press the PF5/17 key.
------------------------------------------------------------------------DQLK0
DATAQUERY: DIRECTORY OF USER COPY TARGETS START WITH => _______________
-----------------------------------------------------------------------------
Using user : ______________________________ for copy source
-----------------------------------------------------------------------------
USER NAME | DATE ADDED | DATE USED
-----------------------------------------------------------------------------
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> COPY TABLES <PF4> COPY CODES
<PF5> COPY BOTH <PF6> NOT USED <PF7> BACKWARD <PF8> FORWARD
Place the cursor on the user name who is to receive the authorizations.
Copying Tables
To copy only table authorizations to the new user, place the cursor on the new user name and select <PF3> COPY TABLES.
Copying Codes
To copy only profile code authorizations to the new user, place the cursor on the new user name and press <PF4> COPY CODES.
Copying All Authorizations
To copy all of the authorizations from one user to another, place the cursor on the new user name and select <PF5> COPY BOTH. CA Dataquery displays a message indicating that the copy was successful.
Changing the Copied Security
To change any of the copied security, return to the Security User Directory panel, use the PF keys to show codes or tables, then press the PF key to update the codes or
Specifying Table Options Using the USER Option
264 Administration Guide
Naming a CA Datacom/DB Database and Table for User Access
Naming a CA Datacom/DB Database and Table for User Access
If external security is in effect, it overrides any changes you might make on user, database, or table authorizations. You should make sure that external and CA Dataquery authorizations match if you want to maintain user, database and table security with CA
Dataquery and with the external package.
Action
To use CA Dataquery to specify a CA Datacom/DB database for a user to access:
Step 1
Choose the SECURITY CONTROL option from the Administrative Menu.
Step 2
Select DATABASE from the Security Maintenance Menu.
CA Dataquery displays the following panel:
Security Table Name (DQLB0)
=>
Enter the appropriate information and press PF4.
------------------------------------------------------------------DQLB0
DATAQUERY: SECURITY TABLE NAME
------------------------------------------------------------------------
Enter the three digit CA Datacom/DB Database Identifier to be used:
Database ID : ___
Enter the three character CA Datacom/DB Table name:
Table name: ___
(Leave blank if you wish to process by
CA Datacom/DB Database Identifier only)
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> DISPLAY USERS
Chapter 25: Securing Data Access for DQL Use 265
Naming a CA Datacom/DB Database and Table for User Access
Action
Complete the panel and press <PF4> DISPLAY USERS.
Panel Description
DATABASE ID:
Enter a valid 1- to 3-digit database ID. This ID specifies the database that this user is to be authorized to access.
TABLE NAME:
Enter a valid 1- to 3-alphabetic database table name. This name is the name of the table that this user is authorized to access. Leave blank if you want to authorize the user for all tables in the specified database ID.
After you name a database and table on the Security Table Name panel, and press
<PF4> DISPLAY USERS, CA Dataquery displays the Security User List panel.
Security User List (DQLC0)
=>
Place the cursor on a name to delete or update. Use PF3 to add new users.
------------------------------------------------------------------------DQLC0
DATAQUERY: SECURITY USER LIST DBID: ___ TABLE: _____
-----------------------------------------------------------------------------
User name | Find | Update | Insert | Erase
-----------------------------------------------------------------------------
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> ADD <PF4> UPDATE
<PF5> NOT USED <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
266 Administration Guide
Naming a CA Datacom/DB Database and Table for User Access
PF Keys
The following list describes the unique PF keys on the Security User List panel.
Key Objective Result
<PF3> ADD Add a user to the security list of users authorized to access this table.
Displays Security User Maintenance panel.
<PF4> UPDATE
<PF6> DELETE
Updates the user's authorizations.
Deletes a name from the Security List panel.
Displays the Security User
Maintenance panel.
Removes the authorization for the user.
Note: To use <PF4> UPDATE or <PF6> DELETE, you must select a user with the cursor position.
To see the entire list, press <PF8> FORWARD until you see the message, LAST PAGE, at the bottom of the screen.
Adding a User to a Table
To add a new user, from the Security User List panel:
Step 1
Press <PF3> ADD. CA Dataquery displays the Security User Maintenance panel.
Step 2
Enter the user name and place a Y in the space opposite each authorized function for that user. This will authorize the functions for which you wish that user to be authorized. You should always authorize users for FIND in any table they are to access.
After you have added a user and authorized the functions, press <PF3> ADD. CA
Dataquery verifies the user authorization.
Chapter 25: Securing Data Access for DQL Use 267
Naming a CA Datacom/DB Database and Table for User Access
Security User Maintenance (DQLD0)
=>
Enter the security information and press the appropriate PF key.
-------------------------------------------------------------------------
DATAQUERY : SECURITY USER MAINTENANCE
--------------------------------------------------------------------DQLD0
User Name :
Find:
Update:
Insert:
Erase:
------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> ADD <PF4> NOT USED
Using the Datadictionary to Relate Multiple Users to Tables
When you need to add many table/user authorizations, you can use CA Datacom
Datadictionary as an alternative to using the online CA Dataquery facility. Follow these steps:
Step 1
Build a entity-occurrence for the AUTHORIZATION entity-type for the performance of a function on a particular table. The format is:
$DQ-tttt-fffiii
$DQ
Constant
tttt
■
■
Identifier for the type of access or update:
■
DISR for FIND (retrieval)
■
UPDR for UPDATE
ADDR for INSERT
DELR for ERASE
268 Administration Guide
Naming a CA Datacom/DB Database and Table for User Access
fff
CA Datacom/DB table name
iii
DATABASE ID
For example, the entity-occurrence for a table named CMP in database 001 for FIND is:
$DQ-DISR-CMP001
Define your entity-occurrences to CA Datacom Datadictionary and put them in production status. See the CA Datacom Datadictionary Online Reference Guide for more information.
Step 2
Add the user in online CA Dataquery. This creates a entity-occurrence within the
PERSON entity-type in PROD status. For more information, see
Adding a User to a Table
(see page 267)
Step 3
Relate the PERSON in Step 2 to the appropriate AUTHORIZATIONS in Step 1. See the CA
Datacom Datadictionary Online Reference Guide for instructions.
Chapter 25: Securing Data Access for DQL Use 269
Chapter 26: Limiting Access to Columns and
Rows
CA Dataquery provides you with the ability to restrict users' access to data using profile codes, restrictions, and conditions. These security measures are maintained by CA
Dataquery and are not overridden by external security.
How to Limit Access to Columns
Profile codes are used to restrict access to data in a specific column, whereas restricted conditions limit access to data in a specific row based on a particular value in the column. Effective use of profile codes allows you to prohibit unwarranted access to sensitive data at the column level.
Using Profile Codes
A PROFILE-CODE is a CA Datacom Datadictionary attribute of the FIELD entity-type that is used by CA Dataquery to classify fields (columns) into various security groups. Once the profile-code is established and included in the field definition, only users who are authorized for that profile-code can FIND and/or UPDATE data in the protected fields.
The assignment of profile codes controls which fields the user sees on the Display Fields panel, unless the user is Data Authorized. If Data Authorized=yes on the User
Authorization panel, the user can display fields but cannot update if they are protected by a profile-code.
At installation, all CA Datacom Datadictionary FIELD entity-occurrences have a null profile-code. This means that once table level authorization is granted to a user, that user has the ability to FIND every field (column) in that table. If you assign a profile-code to a column however, only those users authorized for that profile-code can FIND and/or
UPDATE that column.
For example, say you have columns occurring on several rows that contain financial information. Perhaps one column contains prices of inventory items, another contains information on discount rates for certain customers. If you do not want all of your users to have access to this information, you assign a profile-code to each column, or you use one profile-code for both. For this example, use the code MONY for both columns. Then decide which users can access MONY columns.
If a simple column is named in a query and does not have a profile-code assigned, it is secured by the profile-code of its parent or grandparent, if one exists. If these columns do not have profile codes, the simple columns stated in the query are unprotected and available to any user with table level authorization.
Chapter 26: Limiting Access to Columns and Rows 271
How to Limit Access to Columns
If a compound field is named in a query and does not have a profile-code assigned, it receives a profile-code belonging to its parents or grandparents if one exists. If its parents or grandparents do not have a profile-code, the code of its children or grandchildren is in effect. If none of these fields has a profile-code, the field is unprotected and available to any user with table level authorization. If a compound field has a profile-code assigned, be aware that all columns that make up the compound column will have the same profile-code.
Note: TheCA Datacom Datadictionary REDEFINES attribute, which is not recognized by
CA Dataquery, needs to be handled separately. For example, if FIELD X is assigned a profile-code ABC, and FIELD Y redefines X, the profile-code ABC does not carry over to
FIELD Y. You need to assign the profile-code ABC to FIELD Y.
If you are planning your CA Dataquery security needs prior to creation of your database, contact the Database Administrator regarding your field security needs, so that profile codes can be established and included in the field definitions. Establish the users' authorizations to profile codes using the CA Dataquery SECURITY CONTROL administrative function.
The CA Dataquery SECURITY CONTROL function provides the following options:
SHOW CODES
This option allows you to assign CA Datacom Datadictionary profile codes which protect sensitive column data to users who need to access the protected data. A profile-code is an attribute of a column that is used by CA Dataquery to classify columns into various security groups. Once a profile-code is established and included in the column definition, only users who are authorized for that code can access data in the protected columns. If Y (yes) has been specified on the DATA
AUTHORIZED field on the User Table Maintenance panel, a user without profile-code authorization can read the data.
COPY SECURITY
This option allows you to copy to another user one or all of the authorizations that have been assigned to one user. The security access can remain the same or be further modified for the new user.
COPY CODES
This option allows you to copy the profile codes assigned to one user to another user. Another method of restricting access to data is the use of conditions and restrictions. Conditions are created which qualify access to rows of data based on
Limiting Access to Rows Using Conditions and Restrictions
page 276). for more information.
272 Administration Guide
Authorizing Access to Protected Columns
Authorizing Access to Protected Columns
Authorizing Access to Protected Columns
Relating a user to a profile-code allows that user to access columns protected by CA
Datacom Datadictionary profile codes. Plan carefully before using this function. See your
Security Administrator to gain a complete understanding of the implications of profile-code relationships to be sure that you are following the Security Administrator's security plan.
To establish, display, modify, or delete profile-code relationships for one user, choose the SECURITY CONTROL option from the Administrative Menu. Then select USER on the
Security Maintenance Menu. CA Dataquery displays the Security User Directory panel.
To go directly to the Security User Directory panel, enter SECURITY USER on the command line.
Chapter 26: Limiting Access to Columns and Rows 273
Authorizing Access to Protected Columns
Viewing and Modifying Profile Codes Related to One User
Place the cursor on the user name on the Security User Directory panel. Press <PF4>
SHOW CODES, to see the Security Profile Code List panel.
Security Profile Code List (DQLI0)
-------------------------------------------------------------------DQLI0
DATAQUERY: SECURITY PROFILE CODE LIST USER:
------------------------------------------------------------------------
PROFILE CODE | FIND | UPDATE
------------------------------------------------------------------------
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
LAST PAGE--------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> ADD <PF4> UPDATE
<PF5> NOT USED <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
Listed under the PROFILE CODE column heading are the profile codes currently related to the user. A Y in the columns, FIND and UPDATE, indicates that the user can perform those functions. You can add, modify or delete profile codes and function authorizations on this screen using the PF keys.
Deleting
To delete a profile-code authorization, place the cursor on the profile-code on the
Security Profile Code List panel (DQLI0) and press <PF6> DELETE.
Changing
To add or delete a function authorization to an existing authorized profile-code, place the cursor on the profile-code and press <PF4> UPDATE. Place a Y opposite the function to be added. To remove authorization for a function, tab to the appropriate field and enter an N. Removing all the authorizations for a particular profile-code deletes that code from the list the next time the function is selected.
274 Administration Guide
Authorizing Access to Protected Columns
Adding Profile-Code Authorizations
To assign a user authorization to a profile-code and/or its functions, press <PF3> ADD.
CA Dataquery displays the following panel:
Security Code Maintenance (DQLJ0)
=>
Enter the security information and press the appropriate PF key.
--------------------------------------------------------------------------DQLJ0
DATAQUERY: SECURITY CODE MAINTENANCE USER: _________________________ ______
-------------------------------------------------------------------------------
PROFILE CODE :
FIND:
UPDATE:
-------------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> ADD <PF4> NOT USED
Enter the name of the profile-code and place a Y opposite the function to be assigned to this user. Press the <PF3> ADD key to process this assignment. CA Dataquery displays a message indicating that the add is successful.
Chapter 26: Limiting Access to Columns and Rows 275
Limiting Access to Rows Using Conditions and Restrictions
Limiting Access to Rows Using Conditions and Restrictions
CA Dataquery provides you with the ability to restrict users' access to data using profile codes, restrictions, and conditions. These security measures are maintained by CA
Dataquery and are not overridden by external security.
As the CA Dataquery Administrator, you can restrict access to data in a named database according to the value of the data itself. The vehicle which names the values that cannot be retrieved is called a restriction.
You assign a restriction to an individual user or a user group. A restriction consists of one or more conditions that prevent retrieval of specific data. A typical condition is ZIP
CODE NOT EQUAL 75044. When a query (or dialog) executes against the restricted database, CA Dataquery inserts the conditions in the query and thus qualifies the data that is retrieved. With this method, you apply additional qualifications to a user's queries, allowing the user to view only those rows which satisfy both the query and the user's assigned restricted condition(s).
To restrict a user, follow these steps:
Step 1
Define the condition, giving it a name.
Step 2
List its name on the panel that defines a named restriction.
Step 3
Decide which user or group of users to restrict with the condition. Use the
RESTRICTIONS option on the Administrative Menu to assign the condition to an individual user.
276 Administration Guide
Limiting Access to Rows Using Conditions and Restrictions
Maintaining Conditions
A condition is appended with an AND to any query or dialog in which the user accesses a table for which data access is restricted. For example,
FIND ALL SALES WITH YTD-SALES GT 1000
AND id=15 AND CITY=DALLAS
The above condition limits the users access to data based on the content of the data in two columns. id=15 allows the user to access only those rows in the table in which the value of the ID is equal to 15. Any other rows where the ID is not equal to 15 are not accessible. Furthermore, this condition limits access to those rows in which ID=15 and
CITY=DALLAS. If a row met the first condition criteria, id=15, but did not meet the second condition criteria, CITY=DALLAS, the user would be unable to access any data in that row. The only data the user can access is in the rows that meet the criteria specified in the condition.
Access Conditions
To create, view, or edit a condition, begin by selecting the CONDITIONS option from the
Administrative Menu, or use the CONDITION command from the command line. CA
Dataquery displays the Directory of Conditions. A sample Directory of Conditions panel follows:
Directory of Conditions (DQKW0)
=>
Place the cursor on a name to delete or edit and press the appropriate PFkey
------------------------------------------------------------------------DQKW0
DATAQUERY: DIRECTORY OF CONDITIONS START WITH: _______________
-----------------------------------------------------------------------------
CONDITION NAME | TABLE NAME
-----------------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> CREATE <PF4> EDIT
<PF5> NOT USED <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
Chapter 26: Limiting Access to Columns and Rows 277
Limiting Access to Rows Using Conditions and Restrictions
Action
The START WITH: field, located in the upper-right corner of this panel, is where you enter the full or partial condition where you want the listing to start. When you press
Enter, CA Dataquery displays the condition specified on the first line of the listing. You can also page forward using <PF8> FORWARD or backward using <PF7> BACKWARD until you reach the member that you want to view and/or edit.
Panel Description
The following list describes each column of the Directory of Conditions panel.
CONDITION NAME
Alphabetical listing of all existing conditions.
TABLE NAME
Name of the table to which this condition applies.
PF Keys
The following PF keys are unique to the Directory of Conditions panel. The remainder of this section explains each function.
Key Objective Result
Create a new condition CA Dataquery displays the Editor panel <PF3>
CREATE
<PF4>
EDIT
<PF6>
DELETE
Display or modify an existing condition
Delete a condition
Display that condition on the Editor panel
CA Dataquery removes that condition
Note: <PF4> EDIT and <PF6> DELETE require selection of a condition using the cursor position.
278 Administration Guide
Limiting Access to Rows Using Conditions and Restrictions
Creating a Condition
When you want to create a new condition, choose the CONDITIONS option from the
Administrative Menu, or use the CONDITION command on the command line. When the
Directory of Conditions panel appears, press <PF3> CREATE to create a new condition.
CA Dataquery then displays the Editor panel allowing you to input your condition. An explanation of the Editor panel appears in the CA Dataquery User Guide.
Following is a sample Editor panel that appears when you press <PF3> CREATE during display of the Directory of Conditions.
Sample Editor Panel from the Dir. of Conditions
=>
CREATION PANEL
------------------------------------------------------------------------DQD10
DATAQUERY: EDITOR CURRENT TABLE: ________________________________
-----------------------------------------------------------------------------
NAME: _______________ TYPE: COND__
DESCRIPTION: ___________________________________________________________
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+.
.. ================================ T O P =====================================
..
..
..
..
..
..
..
..
..
.. ============================ B O T T O M ===================================
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> SAVE
<PF5> NOT USED <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
<PF9> UPDATE <PF10> NOT USED <PF11> RIGHT/LEFT <PF12> NOT USED
Chapter 26: Limiting Access to Columns and Rows 279
Limiting Access to Rows Using Conditions and Restrictions
Action
Complete the top of the panel and write the condition in the text area of the panel.
NAME
Enter the 1- to 15-character alphanumeric name for this condition. Supply the table name on which this condition is based in the Current Table field. Remember to give your condition a unique name.
TYPE
CA Dataquery supplies COND to specify that this is a condition and is to be saved in the condition library.
DESCRIPTION
Enter explanatory information about this condition. CA Dataquery displays this description on the Directory of Conditions panel and other condition-related panels.
When the top of the panel is complete, enter the condition. Conditions can either include WITH or not. Either way is valid. Follow the rules for WITH clauses as described in the CA Dataquery Reference Guide. Press <PF4> SAVE to save the condition.
Next Step
The next step in applying the condition to a specific table is to assign the condition to a
restriction definition. Select RESTRICTIONS from the Administrative Menu and see
Using
Conditions to Restrict Access to Rows of Data
Examples
Some examples of conditions are:
ZIPCODE='75243'
CITY NE 'DALLAS'
280 Administration Guide
Limiting Access to Rows Using Conditions and Restrictions
Modifying Existing Conditions
To modify an existing condition, select the CONDITIONS option from the Administrative
Menu, or use the CONDITION command from the command line. When CA Dataquery displays the Directory of Conditions panel, scroll through the listing of condition names until you display the condition you wish to edit. Position the cursor beside that condition and press <PF4> EDIT. CA Dataquery displays that condition on the Editor panel.
When you have finished making changes to the condition, press <PF9> UPDATE to update the condition library with this new version. If you leave the Editor panel without pressing <PF9> UPDATE, CA Dataquery does not replace the original version of the condition with the displayed modified version. If you want to retain your original version and also save your modified version, type a new name over the original name and press
<PF4> SAVE to save the new version.
Deleting Conditions
To delete a condition from CA Dataquery, select the CONDITIONS option from the
Administrative Menu, or use the CONDITION command from the command line. When
CA Dataquery displays the Directory of Conditions panel, scroll through the listing of condition names until you display the condition you wish to delete. Position the cursor beside that condition and press <PF6> DELETE. CA Dataquery immediately deletes that condition and refreshes the panel. All restrictions containing the deleted condition should be updated, although, the deleted condition is ignored when the restriction is applied at query execution.
Once you have deleted a condition from the Directory of Conditions panel, that condition no longer exists. If you have made an error, you must re-create that condition or restore it from a backup.
You can also delete a condition while viewing it on the Editor panel. Because the condition displayed on the Editor panel is in the Active Query Area, the deleted condition can be immediately restored by entering EDIT * in the command field. When
CA Dataquery redisplays the condition, you must save that condition as if it were a new condition by pressing <PF4> SAVE.
Chapter 26: Limiting Access to Columns and Rows 281
Limiting Access to Rows Using Conditions and Restrictions
Using Conditions to Restrict Access to Rows of Data
Summary
A restriction is a list of 1 to 40 conditions which are to be applied to the specified user or group(s) when they access a given table.
Another method of restricting access to data is the use of profile codes. Profile codes are applied through CA Datacom Datadictionary to specific columns in a table so that only users who are related to the profile codes can access the data in a restricted column. (Data authorized users have read-only access even on columns protected by profile codes.) Conditions prevent access to a whole row based on data values.
The user and/or group(s) can access only the rows (based on the content of the data in the row) in the specified table that do not contain restricted data. The table specified in
the restriction must match the table specified in each listed condition. See
Maintaining
Conditions
(see page 277) which discusses conditions. There can be only one restriction
per user per table and one restriction per group per table. If an individual user is assigned both an individual and a group restriction, both are applied.
282 Administration Guide
Limiting Access to Rows Using Conditions and Restrictions
Action
Once you know which table-related conditions you want to apply to a user or group to limit their access to a particular table, select RESTRICTIONS from the Administrative
Menu, or use the RESTRICT command from the command line. CA Dataquery responds by displaying the Directory of Restrictions panel. A sample Directory of Restrictions panel follows:
Directory of Restrictions (DQKX0)
=>
Place cursor on a name and press the appropriate PFkey
------------------------------------------------------------------------DQKX0
DATAQUERY: DIRECTORY OF RESTRICTIONS START WITH: ____________________________
-----------------------------------------------------------------------------
USER NAME OR GROUP ID | TABLE NAME
-----------------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> CREATE <PF4> EDIT
<PF5> NOT USED <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
Action
The START WITH: field, located in the upper-right corner of this panel, is where you enter the full or partial name of the user name or group ID where you want the listing to start. When you press Enter, CA Dataquery refreshes the Directory of Restrictions panel with the user or group ID that you specified on the first line of the listing. You can also page forward using <PF8> FORWARD or backward using <PF7> BACKWARD until you reach the member that you want to view and/or edit.
Chapter 26: Limiting Access to Columns and Rows 283
Limiting Access to Rows Using Conditions and Restrictions
Panel Description
The following list describes each column of the Directory of Restrictions panel.
USER NAME or GROUP ID
Alphabetical listing of all existing users and groups for which there is a restricted condition.
TABLE NAME
Table for which this condition has been created.
PF Keys
The following list describes the PF keys on the Directory of Restrictions panel.
Key Objective Result
<PF3> CREATE
<PF4> EDIT
Create a new restriction
Modify an existing restriction
CA Dataquery displays the Editor panel
Displays that restriction
<PF6> DELETE Delete a restriction CA Dataquery removes that restriction
Note: <PF4> EDIT and <PF6> DELETE require selecting a restriction using the cursor position.
Using Restricted Conditions
When you need to allow users access to some, but not all, of the rows in a table, you use restricted conditions. When you restrict access by column content (the value at the intersection of every row and column) you restrict access to part of the data within that table. You define the condition, giving it a name, identifying the table, and stating the condition. For instance, the condition may restrict access to all SALES rows containing a value of 15 in the column for sales ID and a value of DALLAS in the city column. The administrator who is authorized to access the CONDITIONS function creates the condition following your specifications.
A condition results in restricting the user's access to data in that table. That user can only access data that meets the qualifications of the condition. In the condition shown below, the user is permitted to access only those rows that have an ID of 20 and a city of
Dallas.
WITH id=20 AND CITY=DALLAS
CA Dataquery automatically appends the condition to the DQL Language query or DQL
Language dialog. The condition is transparent to the user.
284 Administration Guide
Limiting Access to Rows Using Conditions and Restrictions
You also decide which user or group of users to restrict with the condition. The administrator with RESTRICTIONS authorization assigns the condition(s) to an individual user. If you have assigned group levels to users that identify them as belonging to specific groups, you can restrict the condition(s) to a group(s).
■
■
For example, if you have defined a high-order (level 1) group named Sales, a middle-order (level 2) group named Dallas, and a low-order (level 3) group named
Clerical, and if your company maintains sales rows for all branches in the same table and each row contains a branch code. The branch codes may be:
Austin - 10
Dallas - 20
■
■
Houston - 30
Midland - 40
If you want clerical users in the Dallas branch to access only the rows for their branch, you create a restricted condition that prevents them from accessing rows that do not contain a 20 in the column for branch codes. Then you assign that restricted condition to all users having a high-order level 1 group of Sales, middle-order level 2 group of
Dallas, and a low-order level 3 group of Clerical. You could, of course, assign the restriction to each user individually, if you prefer. Assigning by groups simplifies administration when personnel change job functions or move within the organization of your company frequently.
A restriction can contain multiple conditions. The maximum is 40 conditions and the minimum is 1 condition. The condition must apply to the same CA Datacom/DB table as the restriction. The restriction is then assigned to a user and/or a group level(s).
You cannot restrict access to data using Conditions and Restrictions in SQL Mode.
Chapter 26: Limiting Access to Columns and Rows 285
Limiting Access to Rows Using Conditions and Restrictions
Creating or Modifying a Restriction
To create or modify an existing restriction, choose the RESTRICTIONS option from the
Administrative Menu, or use the RESTRICT command from the command line. When the
Directory of Restrictions panel appears, position the cursor next to a restriction and press <PF3> EDIT to modify an existing restriction. CA Dataquery then displays the
Restriction Edit panel, as shown in the following example, allowing you to modify the existing restriction relative to a user or group.
Restriction Edit (DQKA0)
=>
OVERTYPE THE CONDITIONS TO BE MODIFIED AND PRESS <PF4> TO COMPLETE THE UPDATE
------------------------------------------------------------------------DQKA0
DATAQUERY: RESTRICTION EDIT
-----------------------------------------------------------------------------
USER ________________________________
GROUP ID: LV1 _______________ LV2 _______________ LV3 _______________
TABLE: ________________________________
-----------------------------------------------------------------------------
CONDITIONS:
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISPLAY CONDITION <PF4> SAVE
<PF5> LIST CONDS <PF6> DELETE <PF7> NOT USED <PF8> NOT USED
Panel Description
A list of the fields and descriptions from the Restriction Edit panels follows.
USER
Enter the user name to whom this restriction applies. If you do not enter a user name, you must specify a Group ID.
GROUP ID:
Specify one of the following against which this restriction is to apply.
■
A group level 1 (LV1)
■
■
A group level 1 (LV1) and a group level 2 (LV2),
A group level 1 (LV1) and a group level 2 (LV2), and a group level 3 (LV3) group
ID
If you do not enter a group ID, you must enter a user name.
286 Administration Guide
Limiting Access to Rows Using Conditions and Restrictions
TABLE:
Enter the CA Datacom Datadictionary TABLE entity-name that names the table to which you want to limit access. CA Dataquery requires that the condition applies to the same table as the associated restriction.
CONDITIONS:
Enter one or more condition names which are to restrict the user's and group's access to the named table. The conditions named are connected by AND and processed at query execution time.
Displaying a Condition
To review a condition that you have listed on the Restriction Edit panel, press <PF3>
DISPLAY CONDITION. (The cursor must be positioned by the condition name.) CA
Dataquery displays that condition on the Editor panel. Press <PF2> RETURN when you have finished viewing the condition to return to the Restriction Edit panel.
Saving Your Restriction
When you are creating or editing a restriction on the Restriction Edit panel, you must save your work. Simply press <PF4> SAVE before leaving this panel. CA Dataquery saves your new restriction, lists it on the Directory of Restrictions panel, and puts it into effect for the designated user(s) and/or group(s) when they execute a query that accesses the table to which this restriction applies. (If you have applied a condition to a user who is outside of your group, the assignment will not be listed on your panel, even though it exists.)
Viewing a Listing of Existing Conditions
When you are viewing the Restriction Edit panel, you might want to refresh your memory as to what the names of the existing conditions are and their associated table names. When you press <PF5> LIST CONDS, CA Dataquery displays the Directory of
Conditions panel for that purpose. (Review
Maintaining Conditions
information about the Directory of Conditions panel.)
Chapter 26: Limiting Access to Columns and Rows 287
Limiting Access to Rows Using Conditions and Restrictions
Deleting a Condition Within a Restriction
When you wish to remove one or more conditions imposed on a user and/or a group, begin by selecting the RESTRICTIONS option from the Administrative Menu, or use the
RESTRICT command from the command line. When CA Dataquery displays the Directory of Restrictions panel, position the cursor beside the user name or group ID that you wish to modify. Then press <PF4> EDIT to display the Restriction Edit panel.
Position the cursor on the condition name that you wish to delete and blank it out, or use Erase End of Field and press <PF4> SAVE to save. CA Dataquery immediately deletes that condition and refreshes the panel. The change in the restriction is not applicable to any user or group ID listed in the restriction until the next time that a query is executed that accesses that restricted table.
CA Dataquery requires that a restriction must contain at least one condition.
288 Administration Guide
Limiting Access to Rows Using Conditions and Restrictions
Deleting a Restriction
When you need to remove a restriction from a user or group, begin by selecting the
RESTRICTIONS option from the Administrative Menu, or using the RESTRICTIONS command from the command line. CA Dataquery displays the Directory of Restrictions panel, as shown in the following example:
Directory of Restrictions (DQKX0)
=>
Place cursor on a name and press the appropriate PFkey
------------------------------------------------------------------------DQKX0
DATAQUERY: DIRECTORY OF RESTRICTIONS START WITH: ____________________________
-----------------------------------------------------------------------------
USER NAME OR GROUP ID | TABLE NAME
-----------------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> CREATE <PF4> EDIT
<PF5> NOT USED <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
Action
Scroll through this panel until you locate the user or group name and its associated table name. Position the cursor beside the user or group and press <PF6> DELETE. CA
Dataquery immediately deletes that restriction and refreshes the panel. The restriction is no longer in effect when the user or a user assigned to the group accesses the previously restricted table.
Using Conditions to Restrict Access to Rows of Data
explanation of the fields and PF keys for the Directory of Restrictions panel.
Chapter 26: Limiting Access to Columns and Rows 289
Limiting Access to Rows Using Conditions and Restrictions
Sample Condition and Restriction
The following is a step-by-step example of how to create a restricted condition using the
Sample Order Entry Database.
Assume that your company has sales offices in New York, San Francisco, Dallas, and
Atlanta. In each sales office is an accounting department. The accounting department in
Dallas does not need to access data for any state except Texas from the CA-CUST-REC table. To restrict the CPAs in the Dallas sales office to records from the CA-CUST-REC table with STATE=TX, perform the following steps:
Step 1
Assign these group levels to all CPAs in Dallas using the USERS option on the
Administrative Menu:
■
Group Level 1 = SALES
■
Group Level 2 = DALLAS
■
Group Level 3 = ACCOUNTING
Sample User File (Table) Maintenance (DQKN0)
=>
Enter the user information and press the appropriate PF key
------------------------------------------------------------------------DQKN0
DATAQUERY: USER FILE MAINTENANCE
-----------------------------------------------------------------------------
USER NAME : DALCPA1
PASSWORD : OPTIONAL
ACCOUNTING CODE : OPTIONAL
QUERY LANGUAGE : DQL SQL OR DQL
SQL AUTHORIZATION ID: REQUIRED FOR SQL OR PDB
GROUP LEVEL 1 : SALES OPTIONAL
GROUP LEVEL 2 : DALLAS IF USED, LEVEL 1 REQUIRED
GROUP LEVEL 3 : ACCOUNTING IF USED, LEVEL 2 REQUIRED
DQ SYSTEM STATUS.
DATA AUTHORIZED : ASSOCIATE USER : PERSONAL DATABASE :
SUBMIT ALLOWED : EXPORT ALLOWED : :
SQL AND DQL ALLOWED : SQL DATA DEF ALLOWED : SQL DATA MAINT ALLOWED :
SYSTEM ADMINISTRATIVE MENU ITEMS AUTHORIZED FOR.
CONDITIONS : RESTRICTIONS : PRINTER CONTROL :
JCL MAINTENANCE : DIAGNOSTICS : LANGUAGE :
USER MAINTENANCE : FOUND SET MAINT : QUERY LIBRARY MAINT :
SECURITY :
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> ADD <PF4> OVERRIDE DEFAULTS
290 Administration Guide
Limiting Access to Rows Using Conditions and Restrictions
Step 2
Create a condition using the CONDITIONS option on the Administrative Menu for the
CA-CUST-REC table which states:
WITH STATE = 'TX'
Sample Condition
=>
CREATION PANEL
------------------------------------------------------------------------DQD10
DATAQUERY: EDITOR CURRENT TABLE: CA-CUST-REC____________________
-----------------------------------------------------------------------------
NAME: CPA-COND_______ TYPE: COND__ _
DESCRIPTION: ___________________________________________________________
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+.
.. ================================ T O P =====================================
.. WITH STATE = 'TX'
..
..
..
..
..
..
..
..
..
=========================== B O T T O M ==================================
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISPLAY FIELDS <PF4> DISPLAY KEYS
<PF5> DISPLAY ALL <PF6> LIST TABLES<PF7> BACKWARD <PF8> FORWARD
<PF9> TEMPLATE <PF10> VALIDATE <PF11> RIGHT/LEFT <PF12> PROCESS MODE
Chapter 26: Limiting Access to Columns and Rows 291
Limiting Access to Rows Using Conditions and Restrictions
Step 3
Create a restriction for the CA-CUST-REC table specifying the groups as SALES, DALLAS, and ACCOUNTING and listing the condition created in Step 2 named CPA-COND. Press
<PF4> SAVE to save the restriction.
Sample Restriction
=>
OVERTYPE THE CONDITIONS TO BE MODIFIED AND PRESS <PF4> TO COMPLETE THE UPDATE
------------------------------------------------------------------------DQKA0
DATAQUERY: RESTRICTION EDIT
-----------------------------------------------------------------------------
OPERATOR ________________________________
GROUP ID: LV1 SALES__________ LV2 DALLAS_________ LV3 ACCOUNTING_____
TABLE: CA-CUST-REC____________________
-----------------------------------------------------------------------------
CONDITIONS:
CPA-COND_______ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
_______________ _______________ _______________ _______________
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISPLAY CONDITION <PF4> SAVE
<PF5> LIST CONDS <PF6> DELETE <PF7> NOT USED <PF8> NOT USED
You have now successfully restricted access to data in the CA-CUST-REC table. Users whose group assignments match these are restricted using the CPA-COND condition when they try to access the CA-CUST-REC table. An additional selection criteria, WITH
STATE = 'TX' has been added to any qualifying criteria which the user presents to access this table.
292 Administration Guide
Condition/Restriction Reporting (DQCRRPT)
Condition/Restriction Reporting (DQCRRPT)
If you have condition/restriction authorization specified on the Administrative Menu you can request Condition/Restriction reports using the DQCRRPT utility. A Status
Report is printed at the end of the report that indicates if the request was successful or if an error was found in the request.
■
Condition reports print the following for each condition:
–
The name of the condition
–
The table name
–
The text of the condition
–
A list of the restrictions in which the condition appears
■
Restriction reports print the following for each restriction:
–
The name of the restriction
–
The user or group to which the restriction applies
–
A list of all conditions within the restriction
–
The text of each condition
Action
Use the report control statements to identify the functions to be performed by
DQCRRPT. A maximum of 60 report and maintenance control statements is allowed.
There are five types of report control statements:
SIGN/ON
(Required) Specifies the user ID and password. Only one SIGN/ON statement is allowed and it must be the first statement in the job stream.
REPORT
(Required) Specifies the title of the report to be produced with this run, and the
Restrictions and the Table name to be reported.
CONDITION
(Optional) Specifies the Condition name for the report to be produced with this run.
USER
(Optional) Specifies the userid for the report to be produced.
Chapter 26: Limiting Access to Columns and Rows 293
Condition/Restriction Reporting (DQCRRPT)
GROUP
(Optional) Selects the group for the report to be produced.
■
■
Enter the control statements in the following sequence:
For Condition Reports:
■
SIGN/ON
For Restriction Reports:
■
SIGN/ON
REPORT
CONDITION
■
■
■
REPORT
USER
GROUP
SIGN/ON Statement
For all of the functions the first control statement is the SIGN/ON statement. The
SIGN/ON control statement is formatted as follows:
►►─ SIGN/ON ─ userid ─ PASSWORD ─ password ───────────────────────────────────►◄
SIGN/ON
Specifies the user ID and password. Only one SIGN/ON statement is allowed and it must be the first statement in the job stream.
userid
Specifies the user ID of the person executing the DQCRRPT utility.
Valid Entries:
A 1- to 32-character user ID
Default Value:
(No default)
294 Administration Guide
Condition/Restriction Reporting (DQCRRPT)
password
Specifies the password of the person executing the DQCRRPT utility. The password is only required when one has been assigned to the user ID.
Valid Entries:
A 1- to 9-character password
Default Value:
(No default)
The control statement SIGN/ON is formatted as follows:
1-8
Identifies the type of control statement. The valid entry is SIGN/ON. Left justify the value with one trailing blank, followed by the user ID.
Condition Reports
►►─ REPORT ─ TITLE=CONDITION ─┬───────────────────────────┬───────────────────►
└─ ,TABLE= ─┬─
►─┬────────────────────────────┬─┬─────────────────────────────────┬─────────►◄
└─ ,RESTRICTIONS= ─┬─ YES ─┬─┘ └─ CONDITION NAME=
└─ NO ──┘ tablename ─┬─┘
└─ ALL ◄ ─────┘ condition name ─┘
REPORT Statement
The condition REPORT statement follows the SIGNON statement in the job stream. The control statement REPORT is formatted as follows:
1-10
Identifies the type of control statement. The only valid entry is REPORT. Left justify the value with trailing blanks as necessary.
11-72
Specifies the option keywords and their values:
TITLE=
Specifies the type of report to be executed.
Valid Entries: CONDITION
Default Value: (No default)
Chapter 26: Limiting Access to Columns and Rows 295
Condition/Restriction Reporting (DQCRRPT)
,TABLE=
Specifies the name of the table for which conditions are to be reported (or ALL to report conditions for all tables).
Valid Entries: A 1- to 32-character table name or ALL
Default Value: ALL
,RESTRICTIONS=
Specifies whether you wish to have the restrictions reported for each condition.
Valid Entries: YES or NO
Default Value: NO
There are no spaces in the keyword portion of the statement. An equal sign (=) separates an option type from its value and a comma separates the options. Do not enter options past column 72. Left justify the value with trailing blanks as necessary.
CONDITION Statement
If specified, the CONDITION statement follows the REPORT statement in the job stream.
Unless a CONDITION statement is coded, all conditions are reported. Any table named on REPORT statement applies to the CONDITION statements that follow. The
CONDITION statement is formatted as follows:
1-10
Identifies the type of control statement. The only valid entry is CONDITION. Left justify the value with trailing blanks as necessary.
11-72
Specifies the optional keywords and values. The NAME= keyword is required if a condition statement is coded.
NAME=
Specifies the name of the condition to be reported.
Valid Entries: A 1- to 15-character condition name
Default Value: (No default)
Note: You can request multiple reports that list single conditions by using the
NAME= statement.
296 Administration Guide
Condition/Restriction Reporting (DQCRRPT)
Restriction Reports
►►─ REPORT ─ TITLE=RESTRICTION ─┬────────────────────┬────────────────────────►
└─ ,TABLE=
├─ USER ─ NAME= userid
└─ GROUP ─ LEVELS= ─┬─ tablename
│ └─
│ └─
─┘
►─┬────────────────────────────────────────────────────────────┬─────────────►◄
───────────────────────────────────────┤ level1
─┬─────────────────────────┬─┬─┘
,level2
─┬───────────┬─┘ │
,level3
─┘ │
└─ ALL ────────────────────────────────┘
REPORT Statement
The Restriction REPORT statement follows the SIGNON statement in the job stream. The control statement REPORT is formatted as follows:
1-10
Identifies the type of control statement. The valid entry is REPORT.
11-72
Specifies the option keywords and their values. All Conditions within a Restriction are listed on a Restriction Report. The valid entries are:
TITLE=
(Required) Specifies the type of report to be executed.
Valid Entries: RESTRICTION
Default Value: (No default)
,TABLE=
(Optional) Specifies the name of the table to be reported.
Valid Entries: A 1- to 9-character table name
Default Value: All tables are reported.
Any table named on REPORT statement applies to USER and GROUP statements that follow. The default is ALL.
There are no spaces in the keyword portion of the statement. An equal sign (=) separates an option type from its value, and a comma separates the options. Do not enter options past column 72.
Chapter 26: Limiting Access to Columns and Rows 297
Condition/Restriction Reporting (DQCRRPT)
USER and GROUP Statements
The optional USER or GROUP statement is formatted as follows:
1-10
Identifies the type of control statement. Valid entries are USER and GROUP.
11-72
Specifies the option keywords and their values, as described below:
NAME=
Identifies the userid to be reported. NAME= is required if a USER statement is coded.
Valid Entries: A CA Dataquery userid
Default Value: All users are reported
LEVELS=
Specifies one to three group names to be reported. LEVELS= is required if a
GROUP statement is coded. To report on all groups, code LEVELS=ALL or omit the GROUP statement.
Valid Entries: A CA Dataquery userid
Default Value: All users are reported
There are no spaces in the keyword portion of the statement. An equal sign (=) separates an option type from its value, and a comma separates the options. Do not enter options past column 72. If no USER or GROUP statements are coded, CA
Dataquery reports all restrictions. You can use multiple USER and GROUP statements following the REPORT statement.
298 Administration Guide
Condition/Restriction Reporting (DQCRRPT)
DQCRRPT JCL Samples
The following is a sample DQCRRPT JCL.
Note: Use the following as a guide to prepare your JCL. The JCL statements are for example only. Lowercase letters in a statement indicate a value you must supply. Code all statements to your site and installation standards.
Sample z/OS JCL
//jobname See the note above and Preparing JCL for Batch CA Dataquery Utilities.
// EXEC PGM=DQCRRPT
//STEPLIB See the note above and Preparing JCL for Batch CA Dataquery Utilities.
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=* Print Output
//SNAPER DD SYSOUT=*
//SYSIN DD * Command input
SIGN/ON userid PASSWORD password
REPORT TITLE=CONDITION,TABLE=PAYROLL
CONDITION NAME=TAXES
REPORT TITLE=CONDITION
REPORT TITLE=RESTRICTION,TABLE=PAYROLL
GROUP LEVELS=LEVEL1,LEVEL2,LEVEL3
GROUP LEVELS=LEVEL1
USER NAME=userid
REPORT TITLE=RESTRICTION
/*
//
Chapter 26: Limiting Access to Columns and Rows 299
Condition/Restriction Reporting (DQCRRPT)
Sample z/VSE JCL
* $$ JOB ... See the note above and Preparing JCL for Batch CA Dataquery
Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// EXEC DQCRRPT
SIGN/ON userid PASSWORD password
REPORT TITLE=CONDITION,TABLE=PAYROLL
CONDITION NAME=TAXES
REPORT TITLE=CONDITION
REPORT TITLE=RESTRICTION,TABLE=PAYROLL
GROUP LEVELS=LEVEL1,LEVEL2,LEVEL3
GROUP LEVELS=LEVEL1
USER NAME=userid
REPORT TITLE=RESTRICTION
/*
/&
* $$ EOJ
300 Administration Guide
Chapter 27: Securing Data Access for SQL
Use
Security is an important consideration in the use of SQL.
When you authorize users to use SQL, only CA Datacom/DB data security is in effect which means that CA Dataquery assumes that the user can access the entire database.
Consult with the CA Datacom/DB Security Administrator for a complete understanding of CA Datacom/DB security.
CA Dataquery Security provides the following security measures for SQL Mode:
■
Password access on a system, query group, or individual level
■
SQL Mode authorization to use
–
SQL
–
Specific SQL commands
INSERT, UPDATE, and DELETE
CREATE, COMMENT ON, DROP, GRANT, and REVOKE
–
Personal tables
■
Query access
Assigning Password Access
CA Dataquery provides the ability to assign passwords on:
■
An individual level allowing each user to access CA Dataquery who has an authorized password
■
Query group level allowing authorized users to access CA Dataquery if they have the authorized group password
■
A system level allowing all users to access CA Dataquery who use the assigned system password
Chapter 27: Securing Data Access for SQL Use 301
Limiting SQL Authorization
Limiting SQL Authorization
CA Dataquery provides your users with access to SQL with the option of using:
■
SELECT only
■
Data Definition Language with use of CREATE, COMMENT ON, DROP, GRANT, and
REVOKE commands
■
Data Maintenance Language with use of INSERT, UPDATE, and DELETE commands
We suggest that you limit authorization to Data Definition Language and Data
Maintenance Language to a CA Dataquery Administrator. The CA Dataquery
Administrator can create the necessary queries to perform these functions on the tables and/or data where appropriate, thus safeguarding the integrity of your system and its data.
Limiting Access to Queries
When the DQOPTLST parameter, QRYGRPS=YES, is specified, you can assign group IDs to a query allowing only the users assigned to those group IDs access to that query. When
QRYGRPS=YES, only the administrator authorized to the LIBRARY function can update or delete that query. If QRYGRPS=NO, the author of a public or private query and the CA
Dataquery Administrator can update or delete the query.
The mode (DQL or SQL) and the authorization control access to a query. DQL Mode users can access a DQL Language query, but cannot access SQL queries unless they are authorized to use SQL and are using SQL Mode at the time. SQL users can access only
SQL queries unless authorized to use DQL Mode as well.
If the query is private, only the author of the query and the authorized administrator are permitted to access the query regardless of the value assigned to the QRYGRPS= parameter. If QRYGRPS=YES, and the query is public and not assigned to a group, all users can access the query. If a query's group assignments are all blank, all users can access that query. All of the user's accessible queries are displayed on that user's query library listing.
Since queries access the information in the database as defined in the query itself, the definition of the query as public or private and the assignment of the query to a group or multiple groups impacts the integrity of your data security. A user can only access those queries that he has created (if he is a conventional user), those that are public, and, if QRYGRPS=YES, those that are assigned to the group IDs matching the user's group IDs and the matching mode.
The DQOPTLST macro parameter, QRYGRPS=, has to be specified as YES so that you can implement the group assignments to queries. If QRYGRPS=NO, CA Dataquery ignores group level IDs in determining access to a query.
302 Administration Guide
Using Schemas
Using Schemas
When a user is added with a private SQL authorization specified, such as is required for
SQL use, CA Dataquery automatically creates a schema in CA Datacom Datadictionary for the SQL authorization ID. A schema defines the individual user's SQL environment.
Users must have a schema associated with an authorization ID to use SQL. A schema contains all table, view and privilege definitions owned by a given authorization ID. Any definitions created by the user are automatically added to the schema for the authorization ID specified when he creates the SQL object.
AUTHIDs or schemas are not used for security. SQL security (CA Datacom/DB security) is based on accessor ID and not an AUTHID.
Creating Personal Tables
The user can use the STORE command to create tables using the data retrieved by a query for his own use. The STORE command creates a table in the user's personal authorization ID and populates the table with the results of the current query. The user can have the data in his own personal tables and then update the tables once a week or whenever convenient.
The Personal Database Facility adds the necessary authorizations required by DQL
Language, automatically to personal tables, except when external security is in use. A user who is allowed to use both DQL Language and SQL can access his personal tables from either query mode. A user who is authorized to use SQL only can access another user's personal tables if access privileges have been granted by the owner. (See the CA
Datacom/DB SQL User Guide for information on the GRANT and REVOKE commands for accessing tables.) Allow users access to personal tables that they require to perform their job functions.
Here are some considerations for the use of PDB (personal data base) and the STORE command. With these functions, tables are created (by using SQL) into an area specified in the user's profile (this profile information is still used even when external security is in effect for CA Dataquery). The area must be in a database for which the user has both
"create" authority and CA Dataquery authority to do maintenance. The area and database should be built separately for each user (or group of users) that are allowed
PDB authority, so that these tables are not put into any arbitrary database. See the CA
Datacom/DB Database and System Administration Guide for information about how to set up a database for SQL use.
You can select portions of tables for a user to access, then use the CA Dataquery Editor to create a view of a portion of a table. The use of views allows users access to the portion of data that they require to perform their job and protects the rest of the data from unnecessary access. See the CA Datacom/DB SQL User Guide for more information on the use of views.
Chapter 27: Securing Data Access for SQL Use 303
Assigning Access to Portions of Tables
Assigning Access to Portions of Tables
In SQL Mode, if a user has the need to use only part of a table but does not need to access the entire table, you can create a view of the necessary data and protect the remainder of the table.
You can select portions of tables for a user to access, then have the CA Dataquery
Administrator (or whoever you have authorized to use Data Definition Language) use the CA Dataquery Editor to create a view of a portion of a table. The use of views allows users access to the portion of data that they require to perform their job and protects the rest of the data from unnecessary access. See CA Datacom/DB documentation for more information on the use of views.
Creating Views
You can use the CA Dataquery Editor to create a view of a portion of a table. The following is an example of a view created for a user to use to access columns in the
CASUPL table. The view states the selected columns names and a search criteria.
Following is an example of an SQL view named SUPPLY:
CREATE VIEW SUPPLY
(SNUM, SNAME, STATUS, CITY)
AS SELECT ALL
SNUM, SNAME, STATUS, CITY
FROM CASUPL
WHERE STATUS > 10
Now when the user accesses the logical table, SUPPLY, the user only accesses the rows of CASUPL when the column status contains a value GT 10.
For more information about Personal Database, see
Personal Database Facility
page 195).
Using SYNONYM Access
The use of a synonym provides an alternate name for a table. The synonym is a convenience that allows the user to avoid naming both the authorization ID and the table name (authid.tablename) in the query. It has no effect on security. The CREATE
SYNONYM command names the authorization ID of the owner and the alternate table name. The other user accesses the table by using the alternate table name in his queries.
304 Administration Guide
Chapter 28: Considering CA Datacom
System Security
SQL security in CA Datacom/DB can be used in addition to CA Dataquery security to control access to tables. If SQL security is activated at your site, users need to be assigned access to tables before they can access the data in the tables using CA
Dataquery. For CA Dataquery SQL Mode, SQL security is the only access control in effect.
If your site has an open security system, the security is open to all of your users unless access is specifically prohibited. If your site has a closed security system, the security is closed to all users unless specific access is authorized.
Note: In a closed security system, a user, known to SQL security as USERA, can execute an SQL statement CREATE TABLE USERB.TAB1 to create a table in the schema USERB.
However, USERB would not be able to access this table until USERA grants the privileges through the GRANT command. For details on open and closed security systems and on assigning SQL access authorization to users, see the CA Datacom Security Reference
Guide.
It is important that you communicate with your site Database Administrator to gain a clear understanding of the existing security systems and the current CA Datacom
Datadictionary profile-codes. You should also make them aware of your needs for establishing a secure CA Dataquery environment. Ongoing communication is imperative, whereby you make your requests known (such as, requesting the creation of new profile-codes) and assure that any changes made within the CA Datacom security environment or in the CA Datacom Datadictionary profile-codes include appropriate plans for maintaining CA Dataquery data integrity and security.
If your site uses CA Ideal, meet with your Database Administrator to ensure that your signon procedures and standards for CA Dataquery security coordinate with those established for the CA Ideal system.
Chapter 28: Considering CA Datacom System Security 305
Chapter 29: Language Maintenance Facility
Overview
Base Languages
CA Dataquery executes in the language you specify during system generation. This means all panels, literals, and vocabulary appear on your terminal screen in the language you designated as your base language during system generation. CA provides
American English as the base CA Dataquery language, but German, and French are also available. Contact your CA representative for more information on obtaining one of these languages.
Other Languages
But what if you would prefer to see CA Dataquery execute in Spanish or some other language?
The Language Maintenance Facility allows you to translate the CA Dataquery vocabulary, literals, messages, commands, menus, and panels into another language.
You can translate everything or you can select only specific panels to translate or customize. The ability to translate CA Dataquery is useful if your corporation has several international sites or a site with employees who speak different languages. You can translate CA Dataquery into all languages used. Then, each employee can use CA
Dataquery in their own language.
Functions
■
■
■
You can use the Language Maintenance Facility to:
■
Create a partial translation from a base language.
■
Translate all parts of CA Dataquery including menus, Help panels, vocabulary, literals, and error messages to another language. (For example, American English to
Spanish.)
■
Customize error messages to include information specific to your company such as,
"Contact John Franks at extension 6670 if you encounter this message. "
Change the bulletin board.
Edit panels, literals, and vocabulary terms.
■
Delete panels, literals, and vocabulary terms.
List all panels, literals, and vocabulary terms.
Chapter 29: Language Maintenance Facility Overview 307
Before You Begin Translation
System Tables
Performing query creation, maintenance, and storage functions involves commands, panels, vocabulary, messages, Help panels, and menus. CA Dataquery stores these messages, panels, commands, and vocabulary terms in the following tables:
■
DQM contains all literals (words generated by CA Dataquery).
■
DQP contains all panels (including Help, menus, error messages).
■
DQV contains all vocabulary (commands and DQL Language keywords).
Before You Begin Translation
Before you begin translation, understand the basics of CA Dataquery. If you are not familiar with signing on to CA Dataquery and using the menus, see the CA Dataquery
User Guide. The basic concepts of the Language Maintenance Facility follow.
Authorization
To use the Language Maintenance Facility, you must be authorized to do so by your CA
Dataquery Administrator. Your CA Dataquery Administrator authorizes you by placing a
Y in the LANGUAGE field on the User Table Maintenance panel. See
Adding a New User
(see page 212) for more information. If CA Dataquery is externally secured, you must be authorized through external security.
Getting Hard Copies of CA Dataquery Panels
To create hard copies of CA Dataquery panels, select the LANGUAGE function from the
Specific Guidelines
(see page 375) for operation instructions
for the Directory of Panels. Scroll through the list of panels and display each panel you want to customize. While viewing a panel, use your screen print function to create a hard copy.
You can also submit a batch job with the DQPANPRT utility. See
Printing CA Dataquery
Panels
308 Administration Guide
Language Maintenance Utility
Additional Software Allocation
If you plan to translate or customize your entire CA Dataquery system, allocate additional disk space to store the newly created language. You need 60 tracks on a 3380 disk initially plus 50 tracks for a full translation. Or, in CA Datacom/DB terms, you need
500 blocks of 3584 bytes.
Language Maintenance Help Panels
CA Dataquery provides Help panels to assist you during your translation process. You can access these panels whenever you see <PF1> HELP listed on the PF key menu at the bottom of your screen except when actually typing in your translation for a panel.
If you receive an error message, press <PF1> HELP and CA Dataquery displays a message
Help panel. This Help panel further explains the error message with possible causes and corrective action.
Language Maintenance Utility
You use the Language Maintenance Utility to back up and restore CA Dataquery languages. You can also use it to change all panels to uppercase.
Back up Language Tables
To back up language tables, execute the Language Maintenance Utility JCL with
RUNTYPE=UNLOAD. The Language Maintenance Utility also allows you to do a selective back up (unload). To back up (unload) either a language you have created or a
CA-provided language, replace the RUNTYPE=UNLOAD line of JCL with:
RUNTYPE=UNLOAD,LANGUAGE=lc where lc is the language code for the language you want to unload.
Restore Backup Tables
To restore backup tables, execute the Language Maintenance Utility JCL with
RUNTYPE=LOAD. You cannot do a selective load.
Change Panels to Uppercase
To change panels to uppercase, run DQLANGMT with:
RUNTYPE=UPSHIFT,LANGUAGE=lc
This is the same as an unload. The output data set has all panels in uppercase. The upshifted panels may be restored to the panel file by running DQLANGMT with
RUNTYPE=LOAD.
Chapter 29: Language Maintenance Facility Overview 309
Lowercase Terminals
To change individual panels to uppercase, run DQLANGMT with:
RUNTYPE=UPSHIFT,LANGUAGE=lc,C=PNL,N=xxx where lc=language code and xxx is the three-character panel ID.
Follow the upshift by a load to restore upshifted panels.
Lowercase Terminals
You can use lowercase and uppercase letters in your translations. Before you can use uppercase and lowercase letters, you must change your primary language code to something other than American English (AE) and define your terminal for mixed case to
CICS.
Using the Language Maintenance Facility
The Language Maintenance Facility allows an Administrator to translate the CA
Dataquery vocabulary, literals, messages, commands, menus, and panels into another language, or to customize them using terms with which your site's users may feel more familiar.
Specifying a Language
Select the language you want to use by specifying the language code in your user profile in response to PRIMARY or SECONDARY. If you do not specify a code for PRIMARY, the language specified in the System Option Table SYSDIAL= parameter becomes the first choice. If you do not specify a code for SECONDARY, the language specified in the
System Option Table SYSLANG= parameter becomes the second choice. If no language code is specified, CA Dataquery executes in American English.
Specify the System Option Table DQOPTLST parameter SYSDIAL= with the PRIMARY language, for the translation you want searched first for the language item to be displayed. Specify SYSLANG= with the SECONDARY language, for the translation you want searched second.
310 Administration Guide
Using the Language Maintenance Facility
Translating or Customizing CA Dataquery
If you plan to translate or customize the CA Dataquery system, prepare the DQM, DQP, and DQV system tables as described in Preparing and Maintaining the CA Dataquery
System Tables. If you want to use mixed case for your translation, define your terminal for mixed case to CICS.
To translate or customize the CA Dataquery system:
■
Update the user with the language code.
■
Specify the language code on the Edit/Translate panel.
■
Do your translation.
■
Specify the System Option Table DQOPTLST parameters SYSDIAL and SYSLANG if they are changing.
Translating CA Dataquery
Loading and Unloading Languages (DQLANGMT)
The Language Maintenance Utility (DQLANGMT) is a batch facility. DQLANGMT performs two major functions:
■
Loading a language.
■
Backing up (unloading) a language.
American English is the default language. Use DQLANGMT to load and use any of the other languages or to back up a translation which you have created.
Loading CA-Provided Languages
To load a language supplied on the version tape, you must:
1. Specify RUNTYPE=LOAD in the DQLANGMT JCL. RUNTYPE=LOAD can be abbreviated
R=LOAD in the JCL.
2. Execute the utility.
JCL examples are provided in this chapter.
Chapter 29: Language Maintenance Facility Overview 311
Using the Language Maintenance Facility
Backing Up (Unloading) Your Language
To back up (unload) your language, you must:
1. Specify RUNTYPE=UNLOAD in the DQLANGMT JCL. RUNTYPE=UNLOAD can be abbreviated R=UNLOAD in the JCL. LANG=XX or abbreviated L=XX may be used to unload only one language.
2. Execute the utility.
JCL examples are provided in this chapter.
Upgrading to a New Version
To keep the translated version of your CA Dataquery panels when you upgrade to a new version, run the DQLANGMT utility with the SYSIN RUNTYPE=UNLOAD,LANG=xx to take a back up of translated panels. After the upgrade, run DQLANGMT again with the new version with SYSIN RUNTYPE=LOAD and the file from the previous UNLOAD as input to put the translated panels, literals, and vocabulary on the new version's files. This is the only way translated files can get to the upgraded system.
To see which panels do not have translated versions, select Language Maintenance from the Administration Menu. Display lists of panels, vocabulary, or literals online to see which do not have translated versions. The online displays list AE (American English) version first, followed by the "xx" version, unless "xx" happens to sort higher in the list than AE. In any case, they will be together on the lists so new ones can be easily seen.
Installing Language Changes
If most CA Dataquery users at your site need to use the language you have created, you need to generate this language as the system language. You do this by coding the system language in the DQOPTLST macro and reassembling the CA Dataquery System
Option Table. The options table applies to all users.
During system generation, CA Dataquery defaults to American English as the base language. To change the default language:
1. Code the SYSLANG= parameter in the DQOPTLST.
2. Reassemble the CA Dataquery System Option Table.
312 Administration Guide
Using the Language Maintenance Facility
You can also add the SYSDIAL= parameter to the DQOPTLST. You can use this parameter to specify a partial translation as the systemwide default. The language code found in the SYSDIAL= parameter is searched first. If CA Dataquery does not find the panel, message, literal, help text, or DQL Language vocabulary word with this language code, the SYSLANG= language code is searched. Only DQL Language verbs can be translated.
The values in the primary and secondary language fields on your user profile override the SYSDIAL= and SYSLANG= parameters, respectively. This can be useful when there are only a few users who want to use a different language than the language defined in
DQOPTLST.
CA Dataquery defaults to a period for a decimal point. To change this default to a comma, enter COMMA in the DECPT= parameter in the DQOPTLST.
After you change the DQOPTLST parameters, you must reassemble the CA Dataquery
Example DQOPTLST Assemblies
Chapter 29: Language Maintenance Facility Overview 313
Using the Language Maintenance Facility
Sample z/OS JCL
Unload
Use the following JCL to run a batch language maintenance job to unload the table. To unload a single language, replace the R=UNLOAD with R=UNLOAD,LANGUAGE=cc where cc is the 2-character language code you want to back up.
//jobname See Preparing JCL for Batch CA Dataquery Utilities.
// EXEC PGM=DQLANGMT
//STEPLIB See Preparing JCL for Batch CA Dataquery Utilities.
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=* Print Output
//* Specify the following according to your site standards:
//SNAPER DD ...
//SYSOUT DD ...
//DQLMUNL DD DSN=dq.lang.backup.dataset,UNIT=device,...
// DCB=(RECFM=VB,LRECL=2010,BLKSIZE=2014,DSORG=PS)
//SYSIN DD *
R=UNLOAD
/*
//
DQLMUNL
DQLMUNL is the output data set for a DQLANGMT unload of panels. It can reside on tape or disk. This statement is needed only in JCL specifying a DQLANGMT UNLOAD.
314 Administration Guide
Using the Language Maintenance Facility
Load
Use the following JCL to run a batch language maintenance job to load a backup tape
(either a user-created backup or a CA-provided load or revision tape).
//jobname See Preparing JCL for Batch CA Dataquery Utilities.
// EXEC PGM=DQLANGMT
//STEPLIB See Preparing JCL for Batch CA Dataquery Utilities.
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=* Print Output
//* Specify the following according to your site standards:
//SNAPER DD ...
//SYSOUT DD ...
//DQLMLOD DD DSN=dq.lang.backup.dataset
//SYSIN DD *
R=LOAD
/*
//
DQLMLOD
DQLMLOD is the input data set for a DQLANGMT load of panels. It can reside on tape or disk. This statement is needed only in JCL specifying a DQLANGMT LOAD.
Chapter 29: Language Maintenance Facility Overview 315
Using the Language Maintenance Facility
Sample z/VSE JCL
Unload to Disk
Use the following JCL to run a batch language maintenance job to unload the table to a disk file. To unload a single language, replace the R=UNLOAD with
R=UNLOAD,LANGUAGE=cc where cc is the 2-character language code you want to back up.
* $$ JOB ... See Preparing JCL for Batch CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
* Specify the following according to your site standards:
// ASSGN SYSnnn,DISK,VOL=volser,SHR
// DLBL DQLMUND,'dq.lang.backup.dataset',,SD
// EXTENT SYSnnn,volser
// EXEC DQLANGMT,SIZE=50K
DOSFILE=DISK
R=UNLOAD
/*
/&
* $$ EOJ
DLBL DQLMUND,
DQLMUND is an output data set for a DQLANGMT unload of panels. If it is to reside on disk, a control statement specifying DOSFILE=DISK must be included.
DOSFILE=
If DOSFILE=DISK is specified, the output data set must have a name of DQLMUND and the panel output must be written to disk.
316 Administration Guide
Using the Language Maintenance Facility
Unload to Tape
Use the following JCL to run a batch language maintenance job to unload the table to a tape.To unload a single language, replace the R=UNLOAD with
R=UNLOAD,LANGUAGE=cc where cc is the 2-character language code you want to back up.
* $$ JOB ... See Preparing JCL for Batch CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
* Specify the following according to your site standards:
// ASSGN SYS020,cuu
// TLBL DQLMUNT,'dq.lang.backup.dataset'
// EXEC DQLANGMT,SIZE=50K
DOSFILE=TAPE
R=UNLOAD
/*
/&
* $$ EOJ
TLBL DQLMUNT,
DQLMUNT is an output data set for a DQLANGMT unload of panels. If it is to reside on tape, a control statement specifying DOSFILE=TAPE must be included.
DOSFILE=
If DOSFILE=TAPE is specified, the output data set must have a name of DQLMUNT and the panel output must be written to tape.
Chapter 29: Language Maintenance Facility Overview 317
Using the Language Maintenance Facility
Load from Disk
Use the following JCL to run a batch language maintenance job to do a load from a disk file.
* $$ JOB ... See Preparing JCL for Batch CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
* Specify the following according to your site standards:
// ASSGN SYSnnn,DISK,VOL=volser,SHR
// DLBL DQLMLOD,'dq.lang.backup.dataSet',,SD
// EXTENT SYSnnn,volser
// EXEC DQLANGMT,SIZE=50K
DOSFILE=DISK
R=LOAD
/*
/&
* $$ EOJ
DLBL DQLMLOD,
DQLMLOD is an intput data set for a DQLANGMT load of panels. If the data set resides on disk, a control statement specifying DOSFILE=DISK must be included.
DOSFILE=
If DOSFILE=DISK is specified, the input data set must have a name of DQLMLOD and the panel input must come from disk.
318 Administration Guide
Using the Language Maintenance Facility
Load from Tape
Use the following JCL to run a batch language maintenance job to do a load from either a user-created backup tape or a CA-provided tape.
* $$ JOB ... See Preparing JCL for Batch CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
* Specify the following according to your site standards:
// ASSGN SYSnnn,cuu
// TLBL DQLMLOT,'dq.lang.backup.data set'
// EXEC DQLANGMT,SIZE=50K
DOSFILE=TAPE
R=LOAD
/*
/&
* $$ EOJ
TLBL DQLLMLOT,
DQLMLOT is an input data set for a DQLANGMT load of panels. If the data set resides on tape, a control statement specifying DOSFILE=TAPE must be included.
DOSFILE=
If DOSFILE=TAPE is specified, the input data set must have a name of DQLMLOT and the panel input must come from tape.
Chapter 29: Language Maintenance Facility Overview 319
Using the Language Maintenance Facility
Printing CA Dataquery Panels
The panel print utility allows you to print the CA Dataquery panels by submitting a batch job, just as with any other batch utility. You can print selected panels or all the panels for one language. Panels are printed in a 24 X 80 format, one panel per report page. No descriptive text appears on the page with the panel. Error messages appear on separate pages.
Processing
When you request a panel/language which exists, the panel is printed; otherwise an error message is printed. When CA Dataquery processing of the print request is complete, the operating system completion code is set as follows:
0
Normal completion
4
Syntax error on control statement input
8
Error in operation
16
Utility abend
Control Statement Format
Keyword parameters may start in any position on the statement. Keyword parameters must be followed by an equal sign (=) and a value. Commas should be used to separate keywords, and there should be no embedded blanks in the list of parameters. Multiple control statements may be used. Keywords and valid values are:
REQ=PRINT
This must be used as written. In this version, print is the only valid request handled by this utility.
NAME=xxx
Where xxx is the name of a panel to print. This is a required parameter. To print panel DQD10, NAME=D10 would be used. To print all the panels for a language,
NAME=*** would be used.
LANG=yy
Where yy is the code of a language to print. This is an optional parameter. If not used, the default is AE (American English). To print all panels in more than one language, a control statement for each language must be used.
320 Administration Guide
Using the Language Maintenance Facility
Sample JCL
Sample z/OS JCL
//jobname See Preparing JCL for Batch CA Dataquery Utilities.
// EXEC PGM=DQPANPRT
//STEPLIB See Preparing JCL for Batch CA Dataquery Utilities.
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=* Print Output
//SNAPER DD SYSOUT=*
//SYSIN DD *
REQ=PRINT,NAME=AA0,LANG=AE
/*
//
Sample z/VSE JCL
* $$ JOB ... See Preparing JCL for Batch CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// EXEC DQPANPRT
REQ=PRINT,NAME=AA0,LANG=AE
/*
/&
* $$ EOJ
Chapter 29: Language Maintenance Facility Overview 321
Chapter 30: Changing the Bulletin Board
CA Dataquery displays a bulletin board immediately after a user signs on. The bulletin board can be used to distribute information to all CA Dataquery users. Although you must use the Language Maintenance Facility to change and update the bulletin board, it is actually an administrative function usually performed by the CA Dataquery
Administrator.
You can change any or all parts of the bulletin board. CA Dataquery does not protect any part of the panel. Use the following steps to change the bulletin board.
Action
To get to the Language Maintenance Menu (DQLN0), do one of the following:
■
From the Administrative Menu, select the LANGUAGE option.
■
Type LANGUAGE on the command line and press Enter.
The following panel shows the Language Maintenance Menu.
Language Maintenance Menu (DQLN0)
=>
------------------------------------------------------------------------DQLN0
DATAQUERY: LANGUAGE MAINTENANCE MENU
-----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> _ LANGUAGE CODE===> __ (default ALL)
1. PANELS - Translate, edit, delete, and display panels
2. LITERALS - Translate, edit, delete, and display program literals
3. VOCABULARY - Translate, edit, delete, and display vocabulary terms
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Select the Panels option to access the Directory of Panels Menu.
Chapter 30: Changing the Bulletin Board 323
Using the Language Maintenance Facility
After you select the Panels option, CA Dataquery displays the Directory of Panels as follows:
Directory of Panels (DQL10)
=>
Place the cursor on the desired name and press the appropriate PFkey
------------------------------------------------------------------------DQL10
DATAQUERY: DIRECTORY OF PANELS START WITH: ___
-----------------------------------------------------------------------------
PANEL NAME |LANGUAGE| DESCRIPTION | PFKEY LEGEND | COLUMNS
-----------------------------------------------------------------------------
AA0 | AE | LST- QUERY/TERM DIR 2 | YAA | 80
AA0 | DX | LST- QUERY/TERM DIR 2 | YAA | 80
AA0 | FR | LST- QUERY/TERM DIR 2 | YAA | 80
AA0 | RM | LST- QUERY/TERM DIR 2 | YAA | 80
AA1 | AE | HLP- DIR OF QRY - TERM 1 | YZ0 | 80
AA1 | DX | HLP- DIR OF QRY - TERM 1 | YZ0 | 80
AA1 | GE | HLP- VERZ. ABFR.- TERM 1 | YZ0 | 80
AA2 | AE | HLP- DIR OF QRY - TERM 2 | YZ0 | 80
AA2 | DX | HLP- DIR OF QRY - TERM 2 | YZ0 | 80
AB0 | AE | LST- QUERY/TERM DIR 3 | YAB | 80
AB0 | DX | LST- QUERY/TERM DIR 3 | YAB | 80
AB0 | GE | LST- ABFR./ERSATZ DIR 3 | YAB | 80
AZ0 | AE | SYS- BULLETIN BOARD | | 80
AZ0 | GE | INFOS | | 80
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISPLAY PANEL <PF4> EDIT PANEL
<PF5> DELETE PANEL <PF6> TRANSLATE <PF7> BACKWARD <PF8> FORWARD
Action
The START WITH: field, located in the upper-right corner of this panel, is where you enter the full or partial name of the panel where you want the listing to start. When you press Enter, CA Dataquery refreshes the DIRECTORY OF PANELS panel with the panel that you specified on the first line of the listing. You can also page forward using <PF8>
FORWARD or backward using <PF7> BACKWARD until you reach the member that you want to view or edit.
From this directory you can select the bulletin board. Position the cursor on the line containing the American English version bulletin board named AZ0 with a description of
SYS- BULLETIN BOARD and press <PF4> EDIT PANEL. (If you have translated the bulletin board into a language other than American English, select your translated version.)
After you select the bulletin board, CA Dataquery displays the Panel Edit/Translate panel as follows.
324 Administration Guide
Using the Language Maintenance Facility
Panel Edit/Translate (DQL20)
=>
------------------------------------------------------------------------DQL20
DATAQUERY: PANEL EDIT/TRANSLATE
-----------------------------------------------------------------------------
PANEL: AZ0 LANGUAGE CODE: AE
-----------------------------------------------------------------------------
TRANSLATE TO LANGUAGE CODE==> __
-----------------------------------------------------------------------------
DESCRIPTION: SYS - Bulletin Board
NEW DESCRIPTION ===> SYS - Bulletin Board____
The selected panel is displayed in an updatable format. Key the
translation or changes in the appropriate literal areas. When you have
completed the changes for the entire panel, use the Enter key to finish
the function. Use the CLEAR key to cancel the function.
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Action
No changes are permitted on this screen. Press Enter. After you press Enter during display of DQL20, CA Dataquery displays the bulletin board in unprotected format as shown in the following sample bulletin board.
Sample Bulletin Board (DQAZ0)
=>
Press the Enter key to continue.
------------------------------------------------------------------------DQAZ0
DATAQUERY: BULLETIN BOARD
-----------------------------------------------------------------------------
WELCOME TO DATAQUERY 10.0
1. PLEASE REPORT ANY PROBLEMS OR SUGGESTIONS TO THE DATAQUERY
ADMINISTRATOR.
2. TO ALL USERS, PLEASE DELETE QUERIES THAT YOU NO LONGER NEED.
Chapter 30: Changing the Bulletin Board 325
Using the Language Maintenance Facility
Action
Enter your new bulletin board information in any style that fits within the confines of the bulletin board panel. Press Enter to save your changes or press CLEAR to exit without saving your changes.
Timing
Any user who signs on after the changes have been saved views the revised bulletin board.
326 Administration Guide
Chapter 31: Translating CA Dataquery
If American English, German, or French does not satisfy your corporate needs, the
Language Maintenance Facility allows you to translate part or all of CA Dataquery to another language or to site-specific terminology. You can even translate DQL Language keywords since they are native to CA Dataquery. You cannot, however, translate the
SQL Language keywords (like SELECT, FROM, and so forth).
After you have translated any or all of CA Dataquery, you must specify that language in your User Profile if you want to use it. Or, if you want most of the users on your system to use it, you can have it specified as the system default in the System Option Table. For
Defining or Modifying the User Profile.
Chapter 31: Translating CA Dataquery 327
Translation and Customization Principles
Translation and Customization Principles
To translate or customize CA Dataquery panels, including menus, messages, and Help panels, you simply view the panels and type your translation or customization over the existing information.
To translate or customize vocabulary and literals, CA Dataquery provides an
Edit/Translate panel where you enter the translation or customization.
To make it easier to choose items for translation or customization, CA Dataquery provides complete lists and directories of all panels, literals and vocabulary words. You initiate translation and customization from these lists and directories. A sample panel directory page follows:
Directory of Panels (DQL10)
=>
Place the cursor on the desired name and press the appropriate PFkey
------------------------------------------------------------------------DQL10
DATAQUERY: DIRECTORY OF PANELS START WITH: ___
-----------------------------------------------------------------------------
PANEL NAME |LANGUAGE| DESCRIPTION | PFKEY LEGEND | COLUMNS
-----------------------------------------------------------------------------
L10 | AE | ADM- PANEL LIST | YL1 | 80
L11 | AE | HLP- DIRECT OF PANELS 1 | YZ0 | 80
L12 | AE | HLP- DIRECT OF PANELS 2 | YZ0 | 80
L13 | AE | HLP- DIRECT OF PANELS 3 | YZ0 | 80
L14 | AE | HLP- DIRECT OF PANELS 4 | YZ0 | 80
L15 | AE | HLP- DIRECT OF PANELS 5 | YZ0 | 80
L20 | AE | ADM- PANEL TRANSLATE | YL2 | 80
L21 | AE | HLP- PANEL EDIT/TRANS 1 | YZ0 | 80
L22 | AE | HLP- PANEL EDIT/TRANS 2 | YZ0 | 80
L23 | AE | HLP- PANEL EDIT/TRANS 3 | YZ0 | 80
L24 | AE | HLP- PANEL EDIT/TRANS 4 | YZ0 | 80
L25 | AE | HLP- PANEL EDIT/TRANS 5 | YZ0 | 80
L26 | AE | HLP- PANEL EDIT/TRANS 6 | YZ0 | 80
L30 | AE | ADM- LITERAL LIST | YL3 | 80
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISPLAY PANEL <PF4> EDIT PANEL
<PF5> DELETE PANEL <PF6> TRANSLATE <PF7> BACKWARD <PF8> FORWARD
328 Administration Guide
Guidelines for Translated DQL Language Queries
Guidelines for Translated DQL Language Queries
The DQL Language is designed so that queries resemble actual requests you may make, such as FIND ALL ROWS .... CA Dataquery is programmed using English language structure. Queries must always follow the English language structure. You must adhere to this structure when using translated vocabulary to create queries.
Translating CA Dataquery
The following lists the steps to perform to translate all of CA Dataquery. Later in this chapter each step is detailed.
Step 1:
Sign on to CA Dataquery and move to the Language Maintenance Menu.
Step 2:
Assign a language code to your translation.
Step 3:
Translate all panels, messages, and Help.
Step 4:
Translate all literals.
Step 5:
Translate all vocabulary.
Step 6:
Update the User Profiles with the translated version language code.
Step 7:
Notify the Database Administrator to change the System Option Table parameters, if applicable.
Chapter 31: Translating CA Dataquery 329
Language Codes
Language Codes
Requirements
Before you begin actual translation, you must select a language code. A language code:
■
Must be two characters in length
■
Cannot be AE, GE, or FR
You must assign this two-character language code to each vocabulary term, panel, or literal you translate or change. CA Dataquery uses this code to identify the language to which the translated item belongs.
CA Dataquery uses AE as the language code to identify its American English version, GE for its German version, and FR for its French version.
If you want CA Dataquery to execute in a language other than the language specified at system installation, you must specify this language code in your User Profile. For an
Using the Language Maintenance Facility
(see page 310). The User Profile
contains two fields for identifying the language in which you want to see CA Dataquery execute. These fields are:
■
PRIMARY LANGUAGE
■
SECONDARY LANGUAGE
When you specify a language code in your User Profile in the Primary or Secondary fields CA Dataquery uses this code to search for items that have been translated using that code.
Search Order
During normal CA Dataquery execution, CA Dataquery displays menus, panels, messages, literals, vocabulary and Help panels in the following order:
1. Primary Language
2. Secondary Language
3. American English
If CA Dataquery does not find the item in the Primary or Secondary language, CA
Dataquery displays the item in the base language (American English).
This search order is important when you create partial translations. Listing the language code of a partial translation as your primary language allows CA Dataquery to use translated items where available. If a translated item is not available, CA Dataquery looks for that item in the secondary language. If no secondary item is found, CA
Dataquery defaults to American English.
330 Administration Guide
Language Codes
Defaults
If you do not have a Primary Language specified in your profile, CA Dataquery defaults the Primary Language to the value specified in the SYSDIAL= parameter during CA
Dataquery system generation.
If you do not have a Secondary Language specified, CA Dataquery defaults to the value specified in the SYSLANG= parameter during CA Dataquery system generation.
Primary
SYSDIAL=
Secondary
SYSLANG=
The SYSDIAL= and SYSLANG= parameters are located in the CA Dataquery System Option
Table.
Example
A company translates the entire CA Dataquery system into Spanish for several employees recently transferred from Spain. After the system has been completely translated they want to further customize some error and informational messages. The company assigns the codes as follows:
Specification Code Description
PRIMARY
SECONDARY
SYSDIAL=
CO
ES
AE
Company customization of translated language
Complete translation to Spanish
English speaking users
This company uses the primary language to further customize error messages in the complete Spanish translation. Because this customization is a partial customization
(applying only to error messages) the language code is placed in the Primary Language field. This means that CA Dataquery searches for an item with the CO language code assigned first. If the item is not found with the CO language code, CA Dataquery searches for that item in the ES (Spanish) version. If CA Dataquery cannot find that item in ES (Spanish), CA Dataquery defaults to English.
This structure accommodates all users of the system. If users require Spanish, they specify CO as their primary language and ES as their secondary language. American
English-speaking employees leave the language fields in their User Profile blank.
Chapter 31: Translating CA Dataquery 331
User Profile
User Profile
To use a translated or customized version of CA Dataquery, you must inform CA
Dataquery on your User Profile.
The User Profile panel contains two language fields:
■
PRIMARY
■
SECONDARY
Use these fields to specify the language code assigned to the language you want to use.
The following is a sample User Profile panel:
User Profile
=>
Overtype the values to be modified and press PF4 to complete the update
------------------------------------------------------------------------DQKL0
DATAQUERY: USER PROFILE FOR => LIZ
-----------------------------------------------------------------------------
PROFILE ITEM EXPLANATION
-----------------------------------------------------------------------------
DATADICTIONARY DATABASE ID => 00002 Five digit DB ID number for DD access
LIST AND DISPLAY ALIASES => NO YES show aliases, NO suppress aliases
GROUP DISPLAY => NO YES break out simple cols, NO do not
SUPPRESS DUPLICATE COLUMNS => YES YES turn on suppression, NO turn off
SUPPRESS PFKEYS ON PRINT => NO YES turn on suppression, NO turn off
SUPPRESS EXECUTE PANEL => NO YES turn on suppression, NO turn off
PRIMARY LANGUAGE => AE Two character PRIMARY Language ID
SECONDARY LANGUAGE => AE Two character SECONDARY Language ID
DECIMAL POINT CHARACTER => . Character to be used for decimal point
QUERY LANGUAGE => DQL Language for queries - SQL or DQL
SQL AUTHORIZATION ID => LIZ
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISP GROUPS <PF4> UPDATE
<PF5> PRINT OPT <PF6> NOT USED <PF7> NOT USED <PF8> NOT USED
332 Administration Guide
User Profile
Action
Place your first language code choice in the primary language field and your second language code choice in the secondary language field.
If the SYSDIAL= and SYSLANG= parameters contain the language choices, you do not need to specify anything on the User Profile.
Anyone who wants to use a translated or customized version specifies that language code in their User Profile. Each user's profile can reflect their language choice. The possibilities for using the different language options on the User Profile make system customization easy. You can:
■
Customize for user groups by updating only select user profiles.
■
Translate and use several languages on one system.
If the majority of the users at your site want to use a translated version, specify that language code in the SYSDIAL= parameter during installation.
Example
Using the scenario described in
Language Codes
(see page 330), the following illustrates
using User Profiles to further customize a company's system. Following are the codes available in the sample company:
Specification Code Description
PRIMARY
SECONDARY
SYSDIAL=
SYSLANG=
CO
ES
AC
AE
Company customization of translated language
Complete translation to Spanish
Company customization of American English
Majority of users are English speaking
Two of the sample company's employees have different language needs:
1. Hall - an American English user
2. Reyna - a user whose primary language is Spanish
Chapter 31: Translating CA Dataquery 333
User Profile
334 Administration Guide
The User Profile for HALL, (the American English user) would look like this:
=>
Overtype the values to be modified and press PF4 to complete the update
------------------------------------------------------------------------DQKL0
DATAQUERY: USER PROFILE FOR => HALL
-----------------------------------------------------------------------------
PROFILE ITEM EXPLANATION
-----------------------------------------------------------------------------
DATADICTIONARY DATABASE ID => 00189 Five digit DB ID number for DD access
LIST AND DISPLAY ALIASES => NO YES show aliases, NO suppress aliases
GROUP DISPLAY => NO YES break out simple cols, NO do not
SUPPRESS DUPLICATE COLUMNS => YES YES turn on suppression, NO turn off
SUPPRESS PFKEYS ON PRINT => NO YES turn on suppression, NO turn off
SUPPRESS EXECUTE PANEL => NO YES turn on suppression, NO turn off
PRIMARY LANGUAGE => __ Two character PRIMARY Language ID
SECONDARY LANGUAGE => __ Two character SECONDARY Language ID
DECIMAL POINT CHARACTER => . Character to be used for decimal point
QUERY LANGUAGE => DQL Language for queries - SQL or DQL
SQL AUTHORIZATION ID => HALL
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISP GROUPS <PF4> UPDATE
<PF5> PRINT OPT <PF6> NOT USED <PF7> NOT USED <PF8> NOT USED
Leaving the PRIMARY and SECONDARY fields blank allows CA Dataquery to default to the languages defined in SYSLANG= and SYSDIAL= of the CA Dataquery System Option
Table.
The User Profile for Reyna (a Spanish-speaking employee) would look like this:
=>
Overtype the values to be modified and press PF4 to complete the update
------------------------------------------------------------------------DQKL0
DATAQUERY: USER PROFILE FOR => REYNA
-----------------------------------------------------------------------------
PROFILE ITEM EXPLANATION
-----------------------------------------------------------------------------
DATADICTIONARY DATABASE ID => 00002 Five digit DB ID number for DD access
LIST AND DISPLAY ALIASES => NO YES show aliases, NO suppress aliases
GROUP DISPLAY => NO YES break out simple cols, NO do not
SUPPRESS DUPLICATE COLUMNS => YES YES turn on suppression, NO turn off
SUPPRESS PFKEYS ON PRINT => NO YES turn on suppression, NO turn off
SUPPRESS EXECUTE PANEL => NO YES turn on suppression, NO turn off
PRIMARY LANGUAGE => CO Two character PRIMARY Language ID
SECONDARY LANGUAGE => ES Two character SECONDARY Language ID
DECIMAL POINT CHARACTER => . Character to be used for decimal point
QUERY LANGUAGE => DQL Language for queries - SQL or DQL
SQL AUTHORIZATION ID => REYNA
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISP GROUPS <PF4> UPDATE
<PF5> PRINT OPT <PF6> NOT USED <PF7> NOT USED <PF8> NOT USED
Reserved Words
Reyna wants to use the company-wide customization of the Spanish translation (CO) and where an item has not been customized, he wants the translated version (ES).
It is also possible to install German as the SYSDIAL= language and specify AE for anyone who wants to execute CA Dataquery in American English.
Remember, you do not have to specify a language code in your user profile if the language you want to use has been specified in the SYSDIAL= parameter.
Reserved Words
The translation of a reserved word becomes a reserved word. This means when you are translating CA Dataquery, you should be aware of the American English versions of the reserved words. The guidelines follow.
When assigning names to such things as tables, sets, queries, columns, keys, temporary result columns, do not use words from the following categories:
■
CA Dataquery commands
■
CA Dataquery Editor commands
■
CA Dataquery Language statements
■
CA Dataquery Language ignored words, such as rows or by
■
SQL keywords
The reserved words and categories may be found in the Appendix of the CA Dataquery
Reference Guide.
Failure to avoid these words that have special meaning to CA Dataquery or are ignored by CA Dataquery will cause problems when you execute any query containing them where CA Dataquery does not expect them, as in a table name.
Chapter 31: Translating CA Dataquery 335
Getting Started Using the Language Maintenance Facility
Getting Started Using the Language Maintenance Facility
Before you can use the Language Maintenance Facility, you must sign on to CA
Dataquery and display the Language Maintenance Menu. Remember, you must be authorized to use the Language Maintenance Facility. You can display the Language
Maintenance Menu by using the LANGUAGE command or by using the menus.
Using the Menus
Step 1
Sign on to CA Dataquery as you normally would. If you are not familiar with the signon procedure, see the CA Dataquery User Guide for details. After signon, CA
Dataquery displays the bulletin board. Press Enter to view the Main Menu.
Step 2
From the Main Menu, enter the number for ADMINISTRATION and press Enter. This selects the Administrative Menu.
OR
Type the LANGUAGE command on the command line and press Enter. Skip Step 3.
Step 3
On the Administrative Menu, select the option number for LANGUAGE, and press
Enter. This selects the Language Maintenance Facility. From this panel you can select the option you need to perform your task.
Translating Panels
Translating panels is as simple as adding the translation by typing over the existing information.
CA Dataquery stores all menus, messages, and Help panels in the DQP table. You perform the various panel maintenance functions by selecting the panel maintenance option on the Language Maintenance Menu.
Background
Each menu, message and Help panel has a unique name. Message names precede the actual message. Menu and Help panel names are located in the upper-right corner of each panel.
Panel Directory
After you select the panel maintenance option on the Language Maintenance
Menu, CA Dataquery displays the panel directory. The Directory of Panels provides a list of all panel names. You locate the panel you want to translate by paging through the directory. Included in this directory are error messages and informational messages.
336 Administration Guide
Translating Panels
PF Keys
CA Dataquery sometimes uses the same PF key definitions in several panels. You can see which panels share PF key definitions by looking at the PF key Legend column on the Directory of Panels. For example, the PF key Panel YA1 is used by several panels. When you translate the PF keys in a panel that uses YA1, all panels that use YA1 reflect this translation.
User Profile
Before you can use a translated panel, you must update your User Profile.
Remember to change your User Profile to specify the language you want to use. For more information on changing the user profile see Defining or Modifying the User
Profile.
General Guidelines
Follow these guidelines during translation:
1. Some panels contain words that are literals and vocabulary terms also. If a word is a vocabulary term (command or query keyword), literal, and used on panel DQD30 or
DQD40 you must translate all three words using the same translation. See the chart
Translating Literals
(see page 344) for a complete list.
2. Do not use special characters or embedded blanks in your translation of these words.
3. Do not translate two different literals or vocabulary terms to the same translation within the same language.
4. If a field is a repeating character, translate that character only one time. All others are translated automatically. You can identify the repeating fields when CA
Dataquery displays the panel in unprotected format. All translatable information appears in red on a color terminal, or is highlighted on a monochrome terminal. If a character is a repeating character, only the first occurrence appears in red or is highlighted and all others remain in blue on a color terminal, or not highlighted on a monochrome terminal.
Chapter 31: Translating CA Dataquery 337
Translating Panels
Specific Guidelines
The following are guides to specific areas of concern in translating CA Dataquery.
Blank Lines
Generally, CA Dataquery does not allow you to type over blank lines in a panel. If you attempt to type over blank lines on protected panels, your keyboard locks.
The following panels allow you to type over blank lines:
■
■
■
■
Error messages (DQ000 - DQ999)
Bulletin board (DQAZ0)
Help topic panels (DQN10 - DQO99)
Help panels (names do not begin with DQY and do not end in 0)
Space
On most panels you have a limited amount of space for translating statements. As a general rule, keep your translation to less than or equal to the length of the
American English version of the statement or description.
Menu Numbers
Do not translate or change the menu item numbers. CA Dataquery does not prohibit you from changing the menu item numbers. However, if you do, CA
Dataquery will not be able to identify the function you are indicating.
Error Messages
Some error messages contain blanks which CA Dataquery uses to return action-specific information. You must leave enough blanks for CA Dataquery to return that information. For example, message DQ027 returns the specific CA
Datacom/DB return code for the error you encountered. The following messages need seven blank spaces immediately after the last character in the message.
Add seven blanks following the last character to:
DQ041 DQ066 DQ237
DQ062
DQ063
DQ067
DQ068
DQ242
DQ270
DQ064
DQ065
DQ160
DQ161
DQ412
DQ414
DQ467
DQ471
DQ472
DQ479
338 Administration Guide
Translating Panels
Messages DQ027 and DQ330 require 21 blanks immediately following the last character in the message.
If you do not leave the correct amount of spaces, CA Dataquery overwrites characters in those positions.
Do not change the error message numbers. The error message number includes the characters DQ and the space before the dash ( - ) and the space after the dash.
Blank Messages
CA Dataquery provides you with 10 blank error messages. You use these panels to document errors which may result from your tailoring of the system. These messages panels are numbered DQ990 - DQ999. You must create or change these panels using the EDIT or TRANSLATE function of the Language Maintenance Facility.
Underscores
If you want to translate error message DQ106, read and apply the following information.
CA Dataquery uses error message DQ106 to inform you that a term has not been defined correctly. When you receive the error message during normal CA Dataquery execution, CA Dataquery returns the term, string, and the error found. When you begin to translate this message, you must leave the positions where CA Dataquery fills in the term, string, and error intact.
This means that you should leave the two sets of 15 underscores and at least six blanks at the end of the message. CA Dataquery allows you to translate the text longer or shorter as long as the underscores and blanks are the correct length and in the same relative positions. If you only leave 10 underscores, CA Dataquery automatically expands the underscores to 15, overtyping any text you defined in those other five positions.
If you translate error message DQ502, you must leave the underscores exactly where they appear. If you do not, CA Dataquery overwrites any characters in those positions.
PF Key Legend
The following PF key legend panels do not appear with a main panel during translation. If you are doing a complete translation, translate each of these separately. If you are doing a partial translation, translate the PF keys legends if the corresponding main panel is part of the partial translation. Notice that only the last three characters of the panel name are shown.
PF Key Legends - Main Panels
YED EB0
YE2 with D10
YE3 with D10
YE7 with D10
YD6 with D60
YE4 with D60
YKA with D60
Y10 with B00, B10, B20,
B30, B50, B60
Y20 with B50, B90
YKZ with KG0
YK8 with K10
Chapter 31: Translating CA Dataquery 339
Translating Panels
Procedure
During the deletion procedure, the Directory of Panels is displayed. Use one of the following procedures to locate the panel you want to translate.
There are several ways you can locate a panel once you have displayed the Directory of
Panels.
<PF7> and <PF8>
Use <PF7> to page the Directory of Panels backward and <PF8> to page forward.
+ and -
Page through the directory using the plus and minus sign. For example, entering
+20 scrolls forward 20 pages and -20 scrolls backward 20 pages.
TOP and BOTTOM
You can use the TOP and BOTTOM commands. TOP takes you to the first panel of the directory and BOTTOM takes you to the end of the directory.
START WITH
If you know the name of the panel you are searching for, you can use the START
WITH field on the Directory of Panels. This field allows you to specify one to three characters with which CA Dataquery can begin searching for a panel name. If you know the panel name, you can specify the last three characters of the name and press Enter. CA Dataquery scrolls that panel name to the top of the display. If you specify one or two characters, CA Dataquery locates the first panel which contains those characters and scrolls it to the top of the directory.
If no panel is located with those characters, CA Dataquery scrolls you to the next greater name on the Directory of Panels.
Operation
Before you can begin translating panels, you must be signed on to CA Dataquery and
display the Language Maintenance Menu. See
Getting Started Using the Language
Maintenance Facility
(see page 336) for exact instructions on displaying the Language
Maintenance Menu.
Step 1
On the LANGUAGE MAINTENANCE MENU select Option 1, PANELS. Press Enter.
340 Administration Guide
Translating Panels
LANGUAGE MAINTENANCE MENU (DQLN0)
=>
------------------------------------------------------------------------DQLN0
DATAQUERY: LANGUAGE MAINTENANCE MENU
----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> 1 LANGUAGE CODE===> __ (default ALL)
1. PANELS - Translate, edit, delete, and display panels
2. LITERALS - Translate, edit, delete, and display program literals
3. VOCABULARY - Translate, edit, delete, and display vocabulary terms
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Step 2
CA Dataquery displays a directory of all panels. From this directory you can select the panel you wish to translate. Notice that only the last three characters of the panel name are shown. See the section in this chapter on locating panels for more information on scrolling through the directory. After you have located the panel you wish to translate, move the cursor down beside the panel name and press <PF6>
TRANSLATE. <PF6> TRANSLATE creates a copy of the panel.
=>
Place the cursor on the desired name and press the appropriate PFkey
------------------------------------------------------------------------DQL10
DATAQUERY: DIRECTORY OF PANELS START WITH: ___
-----------------------------------------------------------------------------
PANEL NAME |LANGUAGE| DESCRIPTION | PFKEY LEGEND | COLUMNS
-----------------------------------------------------------------------------
L10 | AE | ADM- PANEL LIST | YL1 | 80
L11 | AE | HLP- DIRECT OF PANELS 1 | YZ0 | 80
L12 | AE | HLP- DIRECT OF PANELS 2 | YZ0 | 80
L13 | AE | HLP- DIRECT OF PANELS 3 | YZ0 | 80
L14 | AE | HLP- DIRECT OF PANELS 4 | YZ0 | 80
L15 | AE | HLP- DIRECT OF PANELS 5 | YZ0 | 80
L20 | AE | ADM- PANEL TRANSLATE | YL2 | 80
L21 | AE | HLP- PANEL EDIT/TRANS 1 | YZ0 | 80
L22 | AE | HLP- PANEL EDIT/TRANS 2 | YZ0 | 80
L23 | AE | HLP- PANEL EDIT/TRANS 3 | YZ0 | 80
L24 | AE | HLP- PANEL EDIT/TRANS 4 | YZ0 | 80
L25 | AE | HLP- PANEL EDIT/TRANS 5 | YZ0 | 80
L26 | AE | HLP- PANEL EDIT/TRANS 6 | YZ0 | 80
L30 | AE | ADM- LITERAL LIST | YL3 | 80
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISPLAY PANEL <PF4> EDIT PANEL
<PF5> DELETE PANEL <PF6> TRANSLATE <PF7> BACKWARD <PF8> FORWARD
Chapter 31: Translating CA Dataquery 341
Translating Panels
DIRECTORY OF PANELS (DQL10)
=>
PLACE THE CURSOR ON THE DESIRED NAME AND PRESS THE APPROPRIATE PFKEY
------------------------------------------------------------------------DQL10
DATAQUERY: DIRECTORY OF PANELS START WITH: ___
-----------------------------------------------------------------------------
PANEL NAME |LANGUAGE| DESCRIPTION | PFKEY LEGEND | COLUMNS
-----------------------------------------------------------------------------
AA0 | AE | LST- QUERY/TERM DIR 2 | YAA | 80
AA1 | AE | HLP- DIR OF QRY - TERM 1 | YZ0 | 80
AA2 | AE | HLP- DIR OF QRY - TERM 2 | YZ0 | 80
AB0 | AE | LST- QUERY/TERM DIR 3 | YAB | 80
AZ0 | AE | SYS- BULLETIN BOARD | | 80
A00 | AE | HLP- DIRECTORY MENU HELP | YA1 | 80
A01 | AE | HLP- DIRECTORY MENU HELP | YZ0 | 80
A02 | AE | HLP- DIRECTORY MENU #2 | YZ0 | 80
A10 | AE | LST- COMMAND PROMPTER | YA1 | 80
A20 | AE | LST- FILE DIR | YA2 | 80
A21 | AE | HLP- DIR OF FILES 1 | YZ0 | 80
A22 | AE | HLP- DIR OF FILES 2 | YZ0 | 80
A30 | AE | LST- QUERY/TERM DIR 3 | YA3 | 80
A31 | AE | HLP- DIR OF QRY - TERM 1 | YZ0 | 80
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISPLAY PANEL <PF4> EDIT PANEL
<PF5> DELETE PANEL <PF6> TRANSLATE <PF7> BACKWARD <PF8> FORWARD
342 Administration Guide
Translating Panels
Step 3
CA Dataquery displays the Panel Edit/Translate panel. Fill in the TRANSLATE TO
LANGUAGE CODE field with your language code. You can also translate the description by typing the translated description in the NEW DESCRIPTION field. Your description cannot exceed 24 characters. After completing the panel, press Enter.
Panel Edit/Translate (DQL20)
=>
------------------------------------------------------------------------DQL20
DATAQUERY: PANEL EDIT/TRANSLATE
-----------------------------------------------------------------------------
PANEL: DQL20 LANGUAGE CODE: AE
-----------------------------------------------------------------------------
TRANSLATE TO LANGUAGE CODE==> es
-----------------------------------------------------------------------------
DESCRIPTION: ADM- MAIN MENU
NEW DESCRIPTION ===> menu principal _________
The selected panel will be displayed in an updateable format. Key the
translation or changes in the appropriate literal areas. When you have
completed the changes for the entire panel, use the Enter key to finish
the function. Use the CLEAR key to cancel the function.
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Chapter 31: Translating CA Dataquery 343
Translating Literals
Step 4
The panel now appears in an unprotected format. On color monitors, the unprotected information appears in red. On monochrome monitors, the unprotected information is highlighted. You can translate the panel including any PF keys. Enter your translation by typing over the existing information.
=>
------------------------------------------------------------------------DQZ60
DATAQUERY: menu principal - DQL MODE
entre aqui el numero de la funcion deseada => _
1. directorios - hacer listas de Averiguaciones, termino
2. CREATE - Query, Dialog or Term creation
3. GUIDE - Structured query creation
4. PDB - List, create and maintain personal tables
5. ADMINISTRATION - DATAQUERY system management
6. HELP - Display Help Information
7. OFF - DATAQUERY session termination
Step 5
Press Enter to save your translation. CA Dataquery then returns you to the panels directory. To exit without saving your translation, press CLEAR or <PF2>.
Translating Literals
CA Dataquery displays words which are informational or are used in building queries in guided mode. These words are called literals. These words appear throughout CA
Dataquery on many different panels. An example of a literal is the word MORE. MORE appears at the bottom of a panel to inform you more information follows on the next panel. CA Dataquery stores all literals in the DQM table.
CA Dataquery allows you to translate the literals contained in the DQM table. Each literal has been assigned a unique number. Use this number to identify the literal you want to translate. To access the DQM table directory, select the literal maintenance option on the Language Maintenance Menu.
344 Administration Guide
Translating Literals
Rules
When translating literals follow these rules:
1. If you translate a word which is a vocabulary term, literal, and used on a panel,
you must translate all three identically.
2. Literal translations must be less than or equal to the literal length listed on the
Edit/Translate Panel.
3. If a literal is also a vocabulary term, do not use embedded blanks or special characters in the translation.
4. Do not use the same translation for two different literals within the same language.
Translation Aid
A list of most frequently-used words that are used as vocabulary, literals, and on panels follows. Use the literal number listed to help locate the words on the Directory of
Literals. If the word is used on a panel, the panel name follows the literal number.
ACTIVE-QUERY
073
ALL
054
BREAKS
/(DQD40)
BY
110 /(DQD30)
DETAIL
094
DIALOG
072
DISPLAY
025 /(DQD40)
DO
030 /(DQD40)
Chapter 31: Translating CA Dataquery 345
Translating Literals
FROM
/(DQD40)
GT
GTE
016
017
JCL
009
LT
014
LTE
015
NOT
012
NO-TOTALS
096
PICTURE
028
DOWN
/(DQD30)
EQ
013
ERASE
069
FIND
053 /(DQD30)
FINISHED
048 /(DQD40)
FIRST
023 /(DQD30)
346 Administration Guide
Translating Literals
024 /(DQD40)
PRIVATE
004
PUBLIC
003
QUERY
008
ROWS
/(DQD30)
RELATED
020 /(DQD30)
SET
052 /(DQD30)
SORT
074 /(DQD30)
TERM
005
TITLE1
026
TITLE2
027
TO
021 /(DQD30)
TOTALS-ONLY
095
UPDATE
068
VIA
022 /(DQD30)
Chapter 31: Translating CA Dataquery 347
Translating Literals
WHEN
029 /(DQD40)
WITH
011 /(DQD30)
Example
Following is the right way to translate the word WITH to Spanish:
■
Vocabulary term -con
■
Literal word -con
■
Panel word -con
Following is the wrong way to translate WITH to Spanish:
■
Vocabulary term -con
■
Literal word -con
■
Panel word -with
The right way translates WITH identically for the literal, vocabulary term, and on the panel DQD30. The wrong way translates WITH for some but not all language items.
Operation
If you are not already signed on to CA Dataquery, you must sign on to CA Dataquery and display the Language Maintenance Menu. From the Language Maintenance Menu you
Getting Started Using the Language Maintenance Facility
(see page 336) for exact instructions on displaying the Language Maintenance Menu.
348 Administration Guide
Translating Literals
Step 1:
On the Language Maintenance Menu select Option 2, LITERALS and press Enter.
Language Maintenance Menu (DQLN0)
=>
------------------------------------------------------------------------DQLN0
DATAQUERY: LANGUAGE MAINTENANCE MENU
-----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> 2 LANGUAGE CODE===> __ (default ALL)
1. PANELS - Translate, edit, delete, and display panels
2. LITERALS - Translate, edit, delete, and display program literals
3. VOCABULARY - Translate, edit, delete, and display vocabulary terms
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Step 2:
CA Dataquery displays a directory of all literals. From this panel you can select the literal you want to translate.
Procedure
The following lists panel locations and their descriptions.
<PF7> and <PF8>
Use <PF7> to page the literal directory backward and <PF8> to page forward.
+ and -
Page through the directory using the plus and minus sign. For example, entering
+20 scrolls forward 20 pages and -20 scrolls backward 20 pages.
TOP and BOTTOM
You can also use the TOP and BOTTOM commands. TOP takes you to the first panel of the directory and BOTTOM takes you to the end of the directory.
Chapter 31: Translating CA Dataquery 349
Translating Literals
After you have located the literal you want to translate, move the cursor down beside the literal and press <PF6> TRANSLATE. <PF6> TRANSLATE creates a copy of the literal.
Directory of Literals (DQL30)
=>
PLACE THE CURSOR ON THE DESIRED NAME AND PRESS THE APPROPRIATE PFKEY
------------------------------------------------------------------------DQL30
DATAQUERY: DIRECTORY OF LITERALS
-----------------------------------------------------------------------------
ITEM | LANGUAGE | LITERAL
-----------------------------------------------------------------------------
001 | AE | MORE ....
002 | AE | LAST PAGE
003 | AE | PUBLIC
004 | AE | PRIVATE
005 | AE | TERM
006 | AE | COND
007 | AE | MODEL
008 | AE | QUERY
009 | AE | JCL
010 | AE | PROC
011 | AE | WITH
012 | AE | NOT
013 | AE | EQ
014 | AE | LT
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> EDIT ITEM
<PF5> DELETE ITEM <PF6> TRANSLATE <PF7> BACKWARD <PF8> FORWARD
350 Administration Guide
Translating Literals
Step 3:
CA Dataquery displays the Literal Edit/Translate Panel. The panel displays information about the literal such as length and language code. Enter your language code, the new literal value. Your translated version of the literal cannot exceed the literal length displayed on this panel. To save your translation press ENTER. To exit without saving your changes, press Clear or <PF2>.
Literal Edit/Translate (DQL40)
=>
FILL IN THE DATA BELOW AND PRESS ENTER TO COMPLETE FUNCTION
------------------------------------------------------------------------DQL40
DATAQUERY: LITERAL EDIT/TRANSLATE
-----------------------------------------------------------------------------
ITEM NUMBER : 001 LANGUAGE CODE: AE
-----------------------------------------------------------------------------
LITERAL LENGTH: 9 TRANSLATE TO LANGUAGE CODE==> es
-----------------------------------------------------------------------------
LITERAL:
MORE ...
KEY NEW LITERAL VALUE BELOW:
mas ...._____________________________________________________________________
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
After you have saved your translation, CA Dataquery returns you to the directory.
Because CA Dataquery displays the directory in alphabetical order, your translation does not always appear immediately under the base language version.
Chapter 31: Translating CA Dataquery 351
Translating Vocabulary
Translating Vocabulary
CA Dataquery stores all commands and query keywords as vocabulary terms in the DQV table. You can access this table by selecting the vocabulary maintenance option on the
Language Maintenance Menu. CA Dataquery allows you to translate all vocabulary terms. CA Dataquery provides a directory list of all vocabulary terms. From this list, you select the word you want to translate. CA Dataquery then displays a panel. On this panel you fill in the Language Code and the actual translation.
Rules
Follow these rules when translating vocabulary terms:
1. Vocabulary terms must be translated into single words. Do not use embedded blanks or special characters.
2. If you translate a word which is a literal, vocabulary term, and used on a panel,
you must translate all three identically.
3. Do not use the same translation for two different vocabulary terms within a single language.
Translating Literals
(see page 344) for a complete list of words which must be
translated identically.
Operation
If you are not already signed on to CA Dataquery, you must sign on to CA Dataquery and display the Language Maintenance Menu. From the Language Maintenance Menu you
Getting Started Using the Language Maintenance Facility
(see page 336) for exact instructions on displaying the Language Maintenance Menu.
Step 1:
On the LANGUAGE MAINTENANCE MENU select Option 3, VOCABULARY, and press
Enter.
352 Administration Guide
Translating Vocabulary
LANGUAGE MAINTENANCE MENU (DQLN0)
=>
------------------------------------------------------------------------DQLN0
DATAQUERY: LANGUAGE MAINTENANCE MENU
-----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> 3 LANGUAGE CODE===> __ (default ALL)
1. PANELS - Translate, edit, delete, and display panels
2. LITERALS - Translate, edit, delete, and display program literals
3. VOCABULARY - Translate, edit, delete, and display vocabulary terms
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Step 2:
CA Dataquery displays a directory of all vocabulary terms with their English equivalent. From this panel you can select the vocabulary term you want to translate.
Procedure
The following lists panel locations and their descriptions.
<PF7> and <PF8>
Use <PF7> to page the vocabulary directory backward and <PF8> to page forward.
+ and -
Page through the directory using the plus and minus sign. For example, entering
+20 scrolls forward 20 pages and -20 scrolls backward 20 pages.
TOP and BOTTOM
You can also use the TOP and BOTTOM commands. TOP takes you to the first panel of the directory and BOTTOM takes you to the end of the directory.
Chapter 31: Translating CA Dataquery 353
Translating Vocabulary
After you have located the vocabulary term you want to translate, move the cursor down beside the word and press <PF6> TRANSLATE which creates a copy of the vocabulary term.
Directory of Vocabulary (DQL50)
=>
PLACE THE CURSOR ON THE DESIRED NAME AND PRESS THE APPROPRIATE PFKEY
------------------------------------------------------------------------DQL50
DATAQUERY: DIRECTORY OF VOCABULARY
-----------------------------------------------------------------------------
LANGUAGE| VALUE | ENGLISH VALUE
-----------------------------------------------------------------------------
AE | ACTIVE | ACTIVE
AE | ACTIVE-QUERY | ACTIVE-QUERY
AE | ADMIN | ADMIN
AE | ALL | ALL
AE | AND | AND
AE | ASCENDING | ASCENDING
AE | AVERAGE | AVERAGE
AE | BOTTOM | BOTTOM
AE | BREAK | BREAK
AE | BREAKS | BREAKS
AE | BY | BY
AE | CONDITIONS | CONDITIONS
AE | CONTAINING | CONTAINING
AE | COUNT | COUNT
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> EDIT ITEM
<PF5> DELETE ITEM <PF6> TRANSLATE <PF7> BACKWARD <PF8> FORWARD
Step 3:
CA Dataquery displays the VOCABULARY EDIT/TRANSLATE panel with the English value. Enter your language code in the TRANSLATE TO LANGUAGE CODE field. Enter the translation in the NEW VALUE field. Your translation cannot exceed 40 characters and must be a single word with no embedded blanks. Press Enter to save your translation. If you want to leave this panel without saving your translation, press the CLEAR key or <PF2>.
354 Administration Guide
Translating Vocabulary
VOCABULARY EDIT/TRANSLATE (DQL60)
=>
FILL IN THE DATA BELOW AND PRESS ENTER TO COMPLETE FUNCTION
------------------------------------------------------------------------DQL60
DATAQUERY: VOCABULARY EDIT/TRANSLATE
-----------------------------------------------------------------------------
LANGUAGE CODE: AE TRANSLATE TO LANGUAGE CODE==> es
-----------------------------------------------------------------------------
VALUE : BY
ENGLISH VALUE : BY
NEW VALUE =======> por_____________________________________
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
After saving your translation, CA Dataquery returns you to the directory. Because CA
Dataquery displays the directory in alphabetical order, your translation does not always appear under the base language version.
Chapter 31: Translating CA Dataquery 355
Chapter 32: Editing the Translated Version of CA Dataquery
The Edit function of the Language Maintenance Facility allows you to correct mistakes in your translation without having to re-create the translated item. You can use the edit function to correct literals, vocabulary, and panels.
You cannot edit American English panels. For more information about changing
Custmizing the American English Version
Editing Panels
During the deletion procedure, the DIRECTORY OF PANELS is displayed. Use one of the following procedures to locate the panel you want to edit.
There are several ways you can locate a panel once you have displayed the DIRECTORY
OF PANELS.
<PF7> and <PF8>
You can use <PF7> to page the DIRECTORY OF PANELS backward and <PF8> to page forward.
+ and -
Page through the directory using the plus and minus sign. For example, entering
+20 scrolls forward 20 pages and -20 scrolls backward 20 pages.
TOP and BOTTOM
You can use the TOP and BOTTOM commands. TOP takes you to the first panel of the directory and BOTTOM takes you to the end of the directory.
START WITH
If you know the name of the panel you are searching for, you can use the START
WITH field on the DIRECTORY OF PANELS. This field allows you to specify one to three characters with which CA Dataquery can begin searching for a panel name. If you know the panel name, you can specify the last three characters of the name and press Enter. CA Dataquery scrolls that panel name to the top of the display. If you specify one or two characters, CA Dataquery locates the first panel which contains those characters and scrolls it to the top of the directory.
If no panel is located with those characters, CA Dataquery scrolls you to the next greater name on the DIRECTORY OF PANELS.
Chapter 32: Editing the Translated Version of CA Dataquery 357
Editing Panels
Editing Steps
Before you can begin editing panels you must be signed on to CA Dataquery and display the LANGUAGE MAINTENANCE MENU. For exact instructions on displaying the Language
Getting Started Using the Language Maintenance Facility
page 336).
Step 1:
On the LANGUAGE MAINTENANCE MENU select Option 1, PANELS and the language code of the panel you want to edit. CA Dataquery limits selection to panels which contain that language code. If no language code is entered, CA Dataquery defaults to ALL. After all entries are made, press Enter.
LANGUAGE MAINTENANCE MENU (DQLN0)
=>
------------------------------------------------------------------------DQLN0
DATAQUERY: LANGUAGE MAINTENANCE MENU
-----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> 1 LANGUAGE CODE===> ES (default ALL)
1. PANELS - Translate, edit, delete, and display panels
2. LITERALS - Translate, edit, delete, and display program literals
3. VOCABULARY - Translate, edit, delete, and display vocabulary terms
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
358 Administration Guide
Editing Panels
Step 2:
CA Dataquery displays the DIRECTORY OF PANELS. After you have located the panel you want to edit, move the cursor down beside the panel name and press <PF4>
EDIT PANEL. <PF4> EDIT PANEL edits an existing panel.
DIRECTORY OF PANELS (DQL10)
=>
PLACE THE CURSOR ON THE DESIRED NAME AND PRESS THE APPROPRIATE PFKEY
------------------------------------------------------------------------DQL10
DATAQUERY: DIRECTORY OF PANELS START WITH: ___
-----------------------------------------------------------------------------
PANEL NAME |LANGUAGE| DESCRIPTION | PFKEY LEGEND | COLUMNS
-----------------------------------------------------------------------------
AA2 | ES | HLP- dir of aver term 2 | YZ0 | 80
D10 | ES | EDI- crear | YE1 | 80
KE0 | ES | ADM- menu administrativo | | 80
KE1 | ES | HLP- administrativo 1 | YZ0 | 80
K00 | ES | ADM- menu literals | YK0 | 80
L30 | ES | ADM- directorio literal | YL3 | 80
L50 | ES | ADM- directorio de vocab | YL3 | 80
YE1 | ES | SFX- d10 | | 80
YK0 | ES | SFX- K00,K80,L00 | | 80
YL3 | ES | SFX- L30,L50 | | 80
YZ0 | ES | SFX- Help panels | | 80
Z00 | ES | SYS- menu principal | | 80
| | | |
| | | |
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISPLAY PANEL <PF4> EDIT PANEL
<PF5> DELETE PANEL <PF6> TRANSLATE <PF7> BACKWARD <PF8> FORWARD
Chapter 32: Editing the Translated Version of CA Dataquery 359
Editing Panels
Step 3:
CA Dataquery displays the Edit/Translate Panel. This panel displays the name of the panel you intend to update, the language code, and the original description.
You can change the panel description but not the Language Code. Your new description cannot exceed 24 characters. After making the desired changes, press
Enter.
PANEL EDIT/TRANSLATE (DQL20)
=>
------------------------------------------------------------------------DQL20
DATAQUERY: PANEL EDIT/TRANSLATE
-----------------------------------------------------------------------------
PANEL: DQL20 LANGUAGE CODE: ES
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
DESCRIPTION: ADM- MAIN MENU
NEW DESCRIPTION ===> menu principal _________
The selected panel will be displayed in an updateable format. Key the
translation or changes in the appropriate literal areas. When you have
completed the changes for the entire panel, use the Enter key to finish
the function. Use the CLEAR key to cancel the function.
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Step 4:
CA Dataquery presents the panel in an unprotected format. After making all desired changes, press Enter to save and return to the DIRECTORY OF PANELS. To exit without saving your changes, press CLEAR or <PF2>.
360 Administration Guide
Editing Literals
Editing Literals
Use the edit function to make changes in an existing translation. For example, if you translated a literal, then later decided you prefer to translate that literal using another word, rather than deleting the existing translation and creating another literal you can use the edit function to change the existing translation.
You cannot use the edit function to change a literal in American English. See
Customizing the American English Version
(see page 373) for more information.
Rules
If you edit a word which is a literal, vocabulary, and used on a panel, you must make the same edits to all three. In other words, all three words must be identical.
For a complete list of words that must follow these guidelines, see the chart shown in
Translating Literals
Operation
Step 1:
On the LANGUAGE MAINTENANCE MENU select Option 2, LITERALS, specify the language code of the literal you want to edit, and press Enter.
LANGUAGE MAINTENANCE MENU (DQLN0)
=>
------------------------------------------------------------------------DQLN0
DATAQUERY: LANGUAGE MAINTENANCE MENU
----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> 2 LANGUAGE CODE===> ES (default ALL)
1. PANELS - Translate, edit, delete, and display panels
2. LITERALS - Translate, edit, delete, and display program literals
3. VOCABULARY - Translate, edit, delete, and display vocabulary terms
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Chapter 32: Editing the Translated Version of CA Dataquery 361
Editing Literals
Step 2:
CA Dataquery displays a directory of all literals. The literal number appears in the first column, the language code in the second, and the literal values appear in the third column. From this panel you can select the literal you want to edit.
Procedure
The following lists panel locations and their descriptions.
<PF7> and <PF8>
Use <PF7> to page the literal directory backward and <PF8> to page forward.
+ and -
Page through the directory using the plus and minus sign. For example, entering
+20 scrolls forward 20 pages and -20 scrolls backward 20 pages.
TOP and BOTTOM
You can also use the TOP and BOTTOM commands. TOP takes you to the first panel of the directory and BOTTOM takes you to the end of the directory.
After you have located the literal you want to edit, move the cursor down beside the literal and press <PF4> EDIT ITEM.
DIRECTORY OF LITERALS (DQL30)
=>
PLACE THE CURSOR ON THE DESIRED NAME AND PRESS THE APPROPRIATE PFKEY
------------------------------------------------------------------------DQL30
DATAQUERY: DIRECTORY OF LITERALS
-----------------------------------------------------------------------------
ITEM | LANGUAGE | LITERAL
-----------------------------------------------------------------------------
001 | ES | mas ....
002 | ES | ultima pa
003 | ES | public
004 | ES | privado
005 | ES | term
006 | ES | cond
007 | ES | averi
008 | ES | jcl
009 | ES | proc
010 | ES | con
011 | ES | ne
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> EDIT ITEM
<PF5> DELETE ITEM <PF6> TRANSLATE <PF7> BACKWARD <PF8> FORWARD
362 Administration Guide
Editing Vocabulary Terms
Step 3:
CA Dataquery displays the LITERAL EDIT/TRANSLATE Panel. The panel displays information about the literal such as length and language code. Your version of this literal cannot exceed the literal length displayed. Make your changes and press
Enter.
LITERAL EDIT/TRANSLATE (DQL40)
=>
FILL IN THE DATA BELOW AND PRESS ENTER TO COMPLETE FUNCTION
------------------------------------------------------------------------DQL40
DATAQUERY: LITERAL EDIT/TRANSLATE
-----------------------------------------------------------------------------
ITEM NUMBER : 012 LANGUAGE CODE: ES
-----------------------------------------------------------------------------
LITERAL LENGTH: TRANSLATE TO LANGUAGE CODE==> __
-----------------------------------------------------------------------------
LITERAL:
ne
KEY NEW LITERAL VALUE BELOW:
No___________________________________________________________________________
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Editing Vocabulary Terms
The Edit Function can be used to correct a mistake in an existing translation. For example, you may use the Edit function to correct a misspelled word in a translation.
You can also use the Edit Function to change a word in an existing translation. When you use the Edit function CA Dataquery displays the vocabulary term but does not create a new copy of the vocabulary term.
You cannot use the edit function to change a vocabulary term in American English. See
Customizing the American English Version
(see page 373) for information.
Operation
Before you can begin editing, you must first sign on to CA Dataquery and display the
LANGUAGE MAINTENANCE MENU. See section
Getting Started Using the Language
Maintenance Facility
(see page 336) for exact instructions on displaying the LANGUAGE
MAINTENANCE MENU. Also, review the restrictions which apply to changing vocabulary.
These restrictions are listed in
Translating Literals
Chapter 32: Editing the Translated Version of CA Dataquery 363
Editing Vocabulary Terms
Step 1:
On the LANGUAGE MAINTENANCE MENU select Option 3, VOCABULARY, the language code of the vocabulary term you want to edit and press Enter.
LANGUAGE MAINTENANCE MENU (DQLN0)
=>
------------------------------------------------------------------------DQLN0
DATAQUERY: LANGUAGE MAINTENANCE MENU
-----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> 3 LANGUAGE CODE===> __ (default ALL)
1. PANELS - Translate, edit, delete, and display panels
2. LITERALS - Translate, edit, delete, and display program literals
3. VOCABULARY - Translate, edit, delete, and display vocabulary terms
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Step 2:
CA Dataquery displays a directory of all vocabulary terms. From this panel you can select the vocabulary term you want to edit.
Procedure
The following lists panel locations and their descriptions.
<PF7> and <PF8>
Use <PF7> to page the vocabulary directory backward and <PF8> to page forward.
+ and -
Page through the directory using the plus and minus sign. For example, entering
+20 scrolls forward 20 pages and -20 scrolls backward 20 pages.
TOP and BOTTOM
You can also use the TOP and BOTTOM commands. TOP takes you to the first panel of the directory and BOTTOM takes you to the end of the directory.
364 Administration Guide
Editing Vocabulary Terms
After you have located the vocabulary term you want to edit, move the cursor down beside the word and press <PF4> EDIT ITEM.
DIRECTORY OF VOCABULARY (DQL50)
=>
PLACE THE CURSOR ON THE DESIRED NAME AND PRESS THE APPROPRIATE PFKEY
------------------------------------------------------------------------DQL50
DATAQUERY: DIRECTORY OF VOCABULARY
-----------------------------------------------------------------------------
LANGUAGE| VALUE | ENGLISH VALUE
-----------------------------------------------------------------------------
ES | admin | ADMIN
ES | buscare | FIND
ES | condicions | CONDITIONS
ES | crear | CREATE
ES | ejecutar | EXECUTE
ES | eq | EQ
ES | exhibir | DISPLAY
ES | exportar | EXPORT
ES | gte | GTE
ES | hacer | DO
ES | por | BY
ES | primero | FIRST
ES | revisar | EDIT
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> EDIT ITEM
<PF5> DELETE ITEM <PF6> TRANSLATE <PF7> BACKWARD <PF8> FORWARD
Chapter 32: Editing the Translated Version of CA Dataquery 365
Editing Vocabulary Terms
Step 3:
CA Dataquery displays the VOCABULARY EDIT/TRANSLATE Panel with the language code, current value and English value. Enter your replacement in the NEW VALUE field. Your replacement cannot exceed 40 characters and must be a single word with no embedded blanks. Press Enter to save your edit. If you want to leave this panel without saving your edit, press the CLEAR key or <PF2> RETURN.
VOCABULARY EDIT/TRANSLATE (DQL60)
=>
FILL IN THE DATA BELOW AND PRESS ENTER TO COMPLETE FUNCTION
------------------------------------------------------------------------DQL60
DATAQUERY: VOCABULARY EDIT/TRANSLATE
-----------------------------------------------------------------------------
LANGUAGE CODE: ES
-----------------------------------------------------------------------------
VALUE : BUSCARE
ENGLISH VALUE : FIND
NEW VALUE =======> buscar _________________________________
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
After saving your edit, CA Dataquery returns you to the literal directory.
366 Administration Guide
Chapter 33: Deleting Unneeded Panels,
Literals, and Vocabulary
When a panel, literal, or vocabulary is no longer used or needed, you can delete it using the DELETE function of the Language Maintenance Facility.
Deleting Panels
CA Dataquery allows you to delete a panel that is no longer valid. CA Dataquery does not allow you to delete an American English panel.
Procedure
During the deletion procedure, the Directory of Panels is displayed. Use one of the following procedures to locate the panel you want to delete.
There are several ways you can locate a panel once you have displayed the Directory of
Panels.
The following lists panel locations and their descriptions.
<PF7> and <PF8>
You can use <PF7> to page the Directory of Panels backward and <PF8> to page forward.
+ and -
Page through the directory using the plus and minus sign. For example, entering
+20 scrolls forward 20 pages and -20 scrolls backward 20 pages.
TOP and BOTTOM
You can use the TOP and BOTTOM commands. TOP takes you to the first panel of the directory and BOTTOM takes you to the end of the directory.
START WITH
If you know the name of the panel you are searching for, you can use the START
WITH field on the Directory of Panels. This field allows you to specify one to three characters with which CA Dataquery can begin searching for a panel name. If you know the panel name, you can specify the last three characters of the name and press Enter. CA Dataquery scrolls that panel name to the top of the display. If you specify one or two characters, CA Dataquery locates the first panel which contains those characters and scrolls it to the top of the directory.
If no panel is located with those characters, CA Dataquery scrolls you to the next greater name on the Directory of Panels.
Chapter 33: Deleting Unneeded Panels, Literals, and Vocabulary 367
Deleting Panels
Operation
Before you can begin deleting, you must first sign on to CA Dataquery and display the
LANGUAGE MAINTENANCE MENU. For exact instructions on displaying the LANGUAGE
Getting Started Using the Language Maintenance Facility
(see page 336).
Use the following steps to delete a panel.
Step 1:
On the LANGUAGE MAINTENANCE MENU select Option 1, PANELS and enter the language code of the panel you want to delete. CA Dataquery limits selection to panels which contain that language code. If you do not enter a language code, CA
Dataquery defaults to ALL languages on the system. After making all desired entries press Enter.
LANGUAGE MAINTENANCE MENU (DQLN0)
=>
------------------------------------------------------------------------DQLN0
DATAQUERY: LANGUAGE MAINTENANCE MENU
-----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> 1 LANGUAGE CODE===> ES (default ALL)
1. PANELS - Translate, edit, delete, and display panels
2. LITERALS - Translate, edit, delete, and display program literals
3. VOCABULARY - Translate, edit, delete, and display vocabulary terms
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Step 2:
CA Dataquery displays the Directory of Panels. Column 1 contains the panel name, column 2 contains the language code, column 3 contains the description, column 4 contains the PF key legend and column 5 lists the number of columns. After you have located the panel you want to delete, move the cursor down beside the panel name and press <PF5> DELETE. If you try to delete an American English panel you receive an error message.
368 Administration Guide
Deleting Literals
Deleting Literals
CA Dataquery allows you to delete a literal that you no longer want or need to use. CA
Dataquery does not allow you to delete an American English literal.
Remember, some words which are both literals and vocabulary and contained on panels
DQD40 and DQD30 must be translated or customized identically. If you delete the literal version of this word, also delete the vocabulary version and replace the word on the customized or translated panel.
Operation
Before you can begin deleting, you must first sign on to CA Dataquery and display the
LANGUAGE MAINTENANCE MENU. For exact instructions on displaying the LANGUAGE
Getting Started Using the Language Maintenance Facility
(see page 336).
Step 1:
On the LANGUAGE MAINTENANCE MENU select Option 2, LITERALS. Enter the language code of the literal you want to delete. CA Dataquery limits selection to literals which contain that language code. If you do not enter a language code, CA
Dataquery defaults to ALL languages on the system. After making all desired entries press Enter.
LANGUAGE MAINTENANCE MENU (DQLN0)
=>
------------------------------------------------------------------------DQLN0
DATAQUERY: LANGUAGE MAINTENANCE MENU
-----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> 2 LANGUAGE CODE===> ES (default ALL)
1. PANELS - Translate, edit, delete, and display panels
2. LITERALS - Translate, edit, delete, and display program literals
3. VOCABULARY - Translate, edit, delete, and display vocabulary terms
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Step 2:
CA Dataquery displays the DIRECTORY OF LITERALS. Column 1 contains the literal numbers, column 2 contains the language codes and column 3 contains the literals.
Chapter 33: Deleting Unneeded Panels, Literals, and Vocabulary 369
Deleting Vocabulary Terms
Procedure
The following lists panel locations and their descriptions.
<PF7> and <PF8>
Use <PF7> to page the literal directory backward and <PF8> to page forward.
+ and -
Page through the directory using the plus and minus sign. For example, entering
+20 scrolls forward 20 pages and -20 scrolls backward 20 pages.
TOP and BOTTOM
You can also use the TOP and BOTTOM commands. TOP takes you to the first panel of the directory and BOTTOM takes you to the end of the directory.
After you have located the literal you want to delete, move the cursor down beside the literal name and press <PF5> DELETE. If you try to delete a literal with AE (American
English) as the language code, you receive an error message.
Deleting Vocabulary Terms
If you no longer need or want a vocabulary term, CA Dataquery allows you to delete it.
Remember, some words which are both literals and vocabulary and contained on panels
DQD40 and DQD30 must be translated or customized identically. If you delete the vocabulary version of this word, also delete the literal and replace the word on the customized or translated panel.
Operation
Before you can begin deleting, you must first sign on to CA Dataquery and display the
LANGUAGE MAINTENANCE MENU. For exact instructions on displaying the LANGUAGE
Getting Started Using the Language Maintenance Facility
(see page 336).
Step 1:
On the LANGUAGE MAINTENANCE MENU select Option 3, VOCABULARY. Enter the language code of the literal you want to delete. CA Dataquery limits selection to panels which contain that language code. If you do not enter a language code, CA
Dataquery defaults to ALL languages on the system. After making all desired entries, press Enter.
370 Administration Guide
Deleting Vocabulary Terms
LANGUAGE MAINTENANCE MENU (DQLN0)
=>
------------------------------------------------------------------------DQLN0
DATAQUERY: LANGUAGE MAINTENANCE MENU
-----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> 3 LANGUAGE CODE===> ES (default ALL)
1. PANELS - Translate, edit, delete, and display panels
2. LITERALS - Translate, edit, delete, and display program literals
3. VOCABULARY - Translate, edit, delete, and display vocabulary terms
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Step 2:
CA Dataquery displays a directory of all vocabulary terms with the American English version of the word. From this panel you can select the vocabulary term you want to delete.
Procedure
The following lists panel locations and their descriptions.
<PF7> and <PF8>
Use <PF7> to page the vocabulary directory backward and <PF8> to page forward.
+ and -
Page through the directory using the plus and minus sign. For example, entering
+20 scrolls forward 20 pages and -20 scrolls backward 20 pages.
TOP and BOTTOM
You can use the TOP and BOTTOM commands. TOP takes you to the first panel of the directory and BOTTOM takes you to the end of the directory.
DELETE
After you have located the vocabulary term you want to delete, move the cursor down beside the word and press <PF5> DELETE. <PF5> deletes the word and returns you to the vocabulary directory. If you try to delete an American English vocabulary term, you receive an error message.
Chapter 33: Deleting Unneeded Panels, Literals, and Vocabulary 371
Deleting Vocabulary Terms
DIRECTORY OF VOCABULARY (DQL50)
=>
PLACE THE CURSOR ON THE DESIRED NAME AND PRESS THE APPROPRIATE PFKEY
------------------------------------------------------------------------DQL50
DATAQUERY: DIRECTORY OF VOCABULARY
-----------------------------------------------------------------------------
LANGUAGE| VALUE | ENGLISH VALUE
-----------------------------------------------------------------------------
ES | admin | ADMIN
ES | buscare | FIND
ES | condicions | CONDITIONS
ES | crear | CREATE
ES | ejecutar | EXECUTE
ES | eq | EQ
ES | exhibir | DISPLAY
ES | exportar | EXPORT
ES | gte | GTE
ES | hacer | DO
ES | por | BY
ES | primero | FIRST
ES | revisar | EDIT
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> EDIT ITEM
<PF5> DELETE ITEM <PF6> TRANSLATE <PF7> BACKWARD <PF8> FORWARD
372 Administration Guide
Chapter 34: Customizing the American
English Version
CA Dataquery does not allow you to change American English panels, messages, vocabulary, or literals. You use the same principles which apply to a translation to create a customized version of CA Dataquery.
You can customize Help panels or informational messages. You can also customize error messages to include system or company specific information.
■
Select the item to be customized from the directory.
■
Assign a language code to the item.
■
Make the changes.
■
Save the changes.
■
Update your User Profile.
For more information on Language Codes, see
Language Codes
Customizing Panels
Customize panels by:
1. Viewing the panel that you want to change
2. Adding the changes by typing over the existing information
CA Dataquery stores all menus, messages, and Help panels in the DQP table.
Background
You perform the various panel maintenance functions by selecting the panel maintenance option on the LANGUAGE MAINTENANCE MENU.
Each menu, message and Help panel has a unique name. Message names precede the actual message. Menu and Help panel names are located in the upper-right corner of each panel.
After you select the panel maintenance option on the Language Maintenance Menu, CA
Dataquery displays the DIRECTORY OF PANELS. The DIRECTORY OF PANELS provides a list of all panel names. You locate the panel you wish to customize by paging through the directory. Included in this directory are error messages and informational messages.
Chapter 34: Customizing the American English Version 373
Customizing Panels
CA Dataquery sometimes uses the same PF key definitions in several panels. You can see what panels share PF key definitions by looking at the PF key Legend column on the
DIRECTORY OF PANELS. For example, the PF key Panel, YA1, is used by several panels.
When you customize the PF keys in a panel that uses YA1, all panels that use YA1 reflect this customization.
Before you can use a customized panel you must update your User Profile. Remember to change your User Profile to specify the customization you want to use. For more
information on changing the user profile, see
Defining or Modying the user Profile
page 129).
General Guidelines
Follow these guidelines when customizing panels:
1. Some panels contain words that are literals and vocabulary terms also. If a word is a vocabulary term (command or query keyword), literal, and used on panels DQD30 and DQD40, you must customize all three words using the same customization. See
Customizing Literals
(see page 382) for a complete list.
2. Do not use special characters or embedded blanks in your customization of these words.
3. Do not change two different vocabulary terms or literal words using the same word or term.
4. If a field is a repeating character, change that character one time and all others are changed automatically. You can identify the repeating fields when CA Dataquery displays the panel in unprotected format. All changeable information appears in red on a color terminal, or is highlighted on a monochrome terminal. If a character is a repeating character, only the first occurrence appears in red or is highlighted and all others remain in blue on a color terminal or not highlighted on a monochrome terminal.
374 Administration Guide
Customizing Panels
Specific Guidelines
The following are guides to specific areas of concern in translating CA Dataquery.
Blank Lines
Generally, CA Dataquery does not allow you to type over blank lines. If you attempt to type over blank lines on protected panels, your keyboard locks.
The following panels allow you to type over blank lines:
■
■
■
■
Error messages (DQ000 - DQ999)
Bulletin Board (DQAZ0)
Help topic panels (DQN10 - DQO99)
Help panels (panel names do not begin with Y and do not end in 0)
Space
On most panels, you have a limited amount of space for customizing statements. As a general rule, keep your translation to less than or equal to the length of the
American English version of the statement or description.
Menu Numbers
Do not translate or change the menu item numbers. CA Dataquery does not prohibit you from changing the menu item numbers. However, if you do, CA
Dataquery will not be able to identify the function you are indicating.
Error Messages
Some error messages contain blank spaces which CA Dataquery uses to return action specific information. You must leave enough blank spaces for CA Dataquery to return that information. For example, message DQ027 returns the specific CA
Datacom/DB return code for the error you encountered. The following messages need seven blank spaces immediately after the last character in the message.
Add seven blanks following the last character to:
DQ041 DQ066 DQ237
DQ062
DQ063
DQ067
DQ068
DQ242
DQ270
DQ064
DQ065
DQ160
DQ161
DQ412
DQ414
DQ467
DQ471
DQ472
DQ479
Chapter 34: Customizing the American English Version 375
Customizing Panels
Messages DQ027 and DQ330 require 21 blanks immediately following the last character in the message.
If you do not leave the correct amount of spaces, CA Dataquery overwrites characters in those positions.
Do not change the error message numbers. The error message number includes the characters DQ and the space before the dash ( - ) and the space after the dash.
Blank Messages
CA Dataquery provides you with ten blank error messages. You use these panels to document errors which may result from your tailoring of the system. These messages panels are number DQ990 through DQ999. You must create or change these panels using the EDIT or TRANSLATE function of the Language Maintenance
Facility.
If you want to customize error message DQ106, read and apply the following
information.
■
CA Dataquery uses error message DQ106 to inform you that a term has not been defined correctly. When you receive the error message during normal CA
Dataquery execution, CA Dataquery returns the term, string, and the error found. When you begin to translate this message, you must leave the positions where CA Dataquery fills in the term, string, and error intact.
■
This means that you should leave the two sets of 15 underscores and at least 6 blanks at the end of the message. CA Dataquery allows you to translate the text longer or shorter as long as the underscores and blanks are the correct length and in the same relative positions. If you only leave 10 underscores, CA
Dataquery automatically expands the underscores to 15, overtyping any text you defined in those other five positions.
If you customize error message DQ502, you must leave the underscores exactly where they appear. If you do not, CA Dataquery overwrites any characters in those positions.
PF Key Legends
The following PF key legend panels do not appear with a main panel during translation. If you are doing a complete translation, translate each of these separately. If you are doing a partial translation, translate the PF keys legends if the corresponding main panel is part of the partial translation. Only the last three characters of the panel name are shown.
PF Key Legends - Main Panels
YED with EB0
YE2 with D10
YE3 with D10
YE7 with D10
YD6 with D60
YE4 with D60
YKA with D60
Y10 with B00, B10, B20,
B30, B50, B60
Y20 with B50, B90
YKZ with KG0
YK8 with K10
376 Administration Guide
Customizing Panels
Procedure
During the deletion procedure, the DIRECTORY OF PANELS is displayed. Use one of the following procedures to locate the panel you want. There are several ways you can locate a panel once you have displayed the DIRECTORY OF PANELS.
The following lists panel locations and their descriptions.
<PF7> and <PF8>
You can use <PF7> to page the DIRECTORY OF PANELS backward and <PF8> to page forward.
+ and -
Page through the directory using the plus and minus sign. For example, entering
+20 scrolls forward 20 pages and -20 scrolls backward 20 pages.
TOP and BOTTOM
You can use the TOP and BOTTOM commands. TOP takes you to the first panel of the directory and BOTTOM takes you to the end of the directory.
START WITH
If you know the name of the panel you are searching for, you can use the START
WITH field on the DIRECTORY OF PANELS. This field allows you to specify one to three characters with which CA Dataquery can begin searching for a panel name. If you know the panel name, you can specify the last three characters of the name and press Enter. CA Dataquery scrolls that panel name to the top of the display. If you specify one or two characters, CA Dataquery locates the first panel which contains those characters and scrolls it to the top of the directory.
If no panel is located with those characters, CA Dataquery scrolls you to the next greater name on the DIRECTORY OF PANELS.
Chapter 34: Customizing the American English Version 377
Customizing Panels
Operation
Before you can begin customizing panels, you must be signed on to CA Dataquery and display the LANGUAGE MAINTENANCE MENU. For exact instructions about displaying
the LANGUAGE MAINTENANCE MENU, see
Getting Started Using the Language
Maintenance Facility
Step 1:
On the LANGUAGE MAINTENANCE MENU select Option 1, PANELS. Press Enter.
=>
------------------------------------------------------------------------DQLN0
DATAQUERY: LANGUAGE MAINTENANCE MENU
-----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> 1 LANGUAGE CODE===> __ (default ALL)
1. PANELS - Translate, edit, delete, and display panels
2. LITERALS - Translate, edit, delete, and display program literals
3. VOCABULARY - Translate, edit, delete, and display vocabulary terms
Step 2:
CA Dataquery displays a directory of all panels. From this directory you can select the panel you wish to customize. See the section in this chapter on locating panels for more information. After you have located the panel you wish to customize, move the cursor down beside the panel name and press <PF6> TRANSLATE. <PF6>
TRANSLATE creates a copy of the panel.
378 Administration Guide
Customizing Panels
DIRECTORY OF PANELS (DQL10)
=>
PLACE THE CURSOR ON THE DESIRED NAME AND PRESS THE APPROPRIATE PFKEY
------------------------------------------------------------------------DQL10
DATAQUERY: DIRECTORY OF PANELS START WITH: ___
-----------------------------------------------------------------------------
PANEL NAME |LANGUAGE| DESCRIPTION | PFKEY LEGEND | COLUMNS
-----------------------------------------------------------------------------
039 | AE | MSG: DQ039E | YZ1 | 80
041 | AE | MSG: DQ041E | YZ1 | 80
046 | AE | MSG: DQ046E | YZ1 | 80
049 | AE | MSG: DQ049E | YZ1 | 80
050 | AE | MSG: DQ051E | YZ1 | 80
051 | AE | MSG: DQ051E | YZ1 | 80
052 | AE | MSG: DQ052E | YZ1 | 80
058 | AE | MSG: DQ058E | YZ1 | 80
059 | AE | MSG: DQ059E | YZ1 | 80
060 | AE | MSG: DQ060E | YZ1 | 80
062 | AE | MSG: DQ062I | YZ1 | 80
063 | AE | MSG: DQ063I | YZ1 | 80
064 | AE | MSG: DQ064I | YZ1 | 80
065 | AE | MSG: DQ065I | YZ1 | 80
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISPLAY PANEL <PF4> EDIT PANEL
<PF5> DELETE PANEL <PF6> TRANSLATE <PF7> BACKWARD <PF8> FORWARD
Chapter 34: Customizing the American English Version 379
Customizing Panels
Step 3:
CA Dataquery displays the PANEL EDIT/TRANSLATE panel. Fill in the TRANSLATE TO
LANGUAGE CODE field with your language code. You can customize the description by typing over the existing description in the NEW DESCRIPTION field. After completing the panel, press Enter.
PANEL EDIT/TRANSLATE (DQL20)
=>
------------------------------------------------------------------------DQL20
DATAQUERY: PANEL EDIT/TRANSLATE
-----------------------------------------------------------------------------
PANEL: DQ039 LANGUAGE CODE: AE
-----------------------------------------------------------------------------
TRANSLATE TO LANGUAGE CODE==> ac
-----------------------------------------------------------------------------
DESCRIPTION: MSG: DQ039E
NEW DESCRIPTION ===> MSG: DQ039E ____________
The selected panel will be displayed in an updatable format. Key the
translation or changes in the appropriate literal areas. When you have
completed the changes for the entire panel, use the Enter key to finish
the function. Use the CLEAR key to cancel the function.
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
380 Administration Guide
Customizing Panels
Step 4:
The panel now appears in an unprotected format. On color monitors the unprotected information appears in red. On monitors which are not color, the unprotected information is highlighted. You can customize the panel including any
PF keys. Enter your customization by typing over the existing information.
=>
------------------------------------------------------------------------DQ039
DATAQUERY: HELP PANEL FOR ERROR MESSAGE
-----------------------------------------------------------------------------
DQ039E - Printer requested not available. Call operations at ext. 3456.
CAUSE: You requested that the output report from your query be sent to a
printer that is not in service.
ACTION: Either wait until the printer is back in service or direct your
output to another printer. Please report any problems to Karen
at extension 3456.
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
This example took the original error message and added the company specific
information.
Step 5:
Press Enter to save your customization. CA Dataquery then returns you to the panels directory. To exit without saving your customization, press CLEAR or <PF2>.
Editing Panels
After a panel has been customized using the TRANSLATE function, you can use the EDIT function to make corrections or changes. When you use the edit function, CA Dataquery does not create a new copy of the panel. CA Dataquery allows you to change the description but not the language code. CA Dataquery then displays the panel in unprotected format.
You cannot edit an American English panel. The EDIT function of the Language
Maintenance Facility is described in
Editing Panels
Chapter 34: Customizing the American English Version 381
Customizing Literals
Deleting Panels
If after you have created a customized panel and you no longer want or need that panel, you can delete the panel. CA Dataquery does not allow you to delete an American
English panel.
For more information about deleting panels, see
Deleting Panels
Customizing Literals
CA Dataquery displays words which are informational or are used in building queries in guided mode. These words are called literals. These words appear throughout CA
Dataquery on many different panels. An example of a literal is the word MORE. MORE appears at the bottom of a screen to inform you more information follows on the next screen. CA Dataquery stores all literals in the DQM table.
CA Dataquery allows you to change the literals contained in the DQM table. To access the DQM table directory, select the literal maintenance option on the LANGUAGE
MAINTENANCE MENU.
Rules
When changing literals, follow these rules:
1. If you change a word which is a vocabulary term, literal, and used on a panel, you must make the same changes to all words.
2. Literal customizations must be less than or equal to the literal length listed on the
Edit/Translate Panel.
3. If a literal is also a vocabulary term, do not use embedded blanks or special characters.
4. Do not use the same word for two different literals.
Customization Aid
A list of most frequently-used words that are used as vocabulary, literals, and on panels follows. Use the literal number listed to help locate the words on the Directory of
Literals panel. If the word is used on panels DQD30 or DQD40, the panel name is listed in column 3.
ACTIVE-QUERY
073
ALL
054
382 Administration Guide
Customizing Literals
BREAKS
(DQD40)
BY
110 (DQD30)
DETAIL
094
DIALOG
072
DISPLAY
025 (DQD40)
DO
030 (DQD40)
DOWN
(DQD30)
EQ
013
ERASE
069
FIND
053 (DQD30)
FINISHED
048 (DQD40)
FIRST
023 (DQD30)
FROM
(DQD40)
GT
016
Chapter 34: Customizing the American English Version 383
Customizing Literals
GTE
017
JCL
009
LT
014
LTE
NOT
015
012
NO-TOTALS
096
PICTURE
028
024 (DQD40)
PRIVATE
004
PUBLIC
003
QUERY
008
ROWS
(DQD30)
RELATED
020 (DQD30)
SET
052 (DQD30)
SORT
074 (DQD30)
384 Administration Guide
TERM
005
TITLE1
026
TITLE2
027
TO
021 (DQD30)
TOTALS-ONLY
095
UPDATE
068
VIA
022 (DQD30)
WHEN
029 (DQD40)
WITH
011 (DQD30)
Customizing Literals
Chapter 34: Customizing the American English Version 385
Customizing Literals
Operation
If you are not already signed on to CA Dataquery, you must sign on to CA Dataquery and display the LANGUAGE MAINTENANCE MENU. From the LANGUAGE MAINTENANCE
MENU you can initiate customization. For exact instructions about displaying the
LANGUAGE MAINTENANCE MENU, see
Getting Started Using the Language Maintenance
Facility
Step 1:
On the LANGUAGE MAINTENANCE MENU select Option 2, LITERALS and press
Enter.
LANGUAGE MAINTENANCE MENU (DQLN0)
=>
------------------------------------------------------------------------DQLN0
DATAQUERY: LANGUAGE MAINTENANCE MENU
-----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> 2 LANGUAGE CODE===> __ (default ALL)
1. PANELS - Translate, edit, delete, and display panels
2. LITERALS - Translate, edit, delete, and display program literals
3. VOCABULARY - Translate, edit, delete, and display vocabulary terms
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
386 Administration Guide
Customizing Literals
Step 2:
CA Dataquery displays a directory of all literals. From this panel you can select the literal you wish to customize.
Procedure
The following lists panel locations and their descriptions.
<PF7> and <PF8>
Use <PF7> to page the literal directory backward and <PF8> to page forward.
+ and -
Page through the directory using the plus and minus sign. For example, entering
+20 scrolls forward 20 pages and -20 scrolls backward 20 pages.
TOP and BOTTOM
You can also use the TOP and BOTTOM commands. TOP takes you to the first panel of the directory and BOTTOM takes you to the end of the directory.
After you have located the literal you wish to customize, move the cursor down beside the literal and press <PF6> TRANSLATE. <PF6> TRANSLATE creates a copy of the literal.
=>
PLACE THE CURSOR ON THE DESIRED NAME AND PRESS THE APPROPRIATE PFKEY
------------------------------------------------------------------------DQL30
DATAQUERY: DIRECTORY OF LITERALS
-----------------------------------------------------------------------------
ITEM | LANGUAGE | LITERAL
-----------------------------------------------------------------------------
001 | AE | MORE ....
002 | AE | LAST PAGE
003 | AE | PUBLIC
004 | AE | PRIVATE
005 | AE | TERM
006 | AE | COND
007 | AE | MODEL
008 | AE | QUERY
009 | AE | JCL
010 | AE | PROC
011 | AE | WITH
012 | AE | NOT
013 | AE | EQ
014 | AE | LT
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> EDIT ITEM
<PF5> DELETE ITEM <PF6> TRANSLATE <PF7> BACKWARD <PF8> FORWARD
Chapter 34: Customizing the American English Version 387
Customizing Literals
Step 3:
CA Dataquery displays the Literal Edit/Translate Panel. The panel displays information about the literal such as length and language code. Enter your language code, the new literal value, and press Enter. To exit without saving your changes, press CLEAR or <PF2>.
=>
FILL IN THE DATA BELOW AND PRESS ENTER TO COMPLETE FUNCTION
------------------------------------------------------------------------DQL40
DATAQUERY: LITERAL EDIT/TRANSLATE
-----------------------------------------------------------------------------
ITEM NUMBER : 001 LANGUAGE CODE: AE
-----------------------------------------------------------------------------
LITERAL LENGTH: 9 TRANSLATE TO LANGUAGE CODE==> ac
-----------------------------------------------------------------------------
LITERAL:
MORE ....
KEY NEW LITERAL VALUE BELOW:
continued____________________________________________________________________
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
This example changes the literal MORE to CONTINUED.
Editing Literals
You cannot use the edit function to change a literal in American English. You can use the
EDIT function to change a literal you have already created through the translate function. Use the edit function of the Language Maintenance Facility to correct already existing literals.
For exact instructions for using the edit function, see
Translating Literals
Deleting Literals
If you have created a literal that you no longer want or need, CA Dataquery allows you to DELETE that literal. CA Dataquery does not allow you to delete an American English
literal. For exact instructions, see
Deleting Literals
388 Administration Guide
Customizing Vocabulary Terms
Customizing Vocabulary Terms
CA Dataquery stores all commands and query keywords as vocabulary terms in the DQV table. You can access this table by selecting the vocabulary maintenance option on the
LANGUAGE MAINTENANCE MENU. CA Dataquery allows you to customize all vocabulary terms. CA Dataquery provides a directory list of all vocabulary terms. From this list you select the word you wish to change. CA Dataquery then displays a menu. On this menu you fill in the Language Code and then enter the actual changes.
Rules
Follow these rules when making changes to vocabulary terms:
1. Vocabulary terms must be single words. Do not use embedded blanks or special characters.
2. If you change a word which is a literal, vocabulary, and panel word, you must change all three and make the same changes to all three.
3. Do not change two different words to the same word.
Customizing Literals
(see page 382) for a complete list of word which must be
customized identically.
If you are not already signed on to CA Dataquery, you must sign on to CA Dataquery and display the LANGUAGE MAINTENANCE MENU. From the LANGUAGE MAINTENANCE
MENU you can initiate customization. For exact instructions about displaying the
LANGUAGE MAINTENANCE MENU, see
Getting Started Using the Language Maintenance
Facility
Step 1:
On the LANGUAGE MAINTENANCE MENU select Option 3, VOCABULARY, and press
Enter.
=>
------------------------------------------------------------------------DQLN0
DATAQUERY: LANGUAGE MAINTENANCE MENU
-----------------------------------------------------------------------------
ENTER DESIRED OPTION NUMBER ===> 3 LANGUAGE CODE===> __ (default ALL)
1. PANELS - Translate, edit, delete, and display panels
2. LITERALS - Translate, edit, delete, and display program literals
3. VOCABULARY - Translate, edit, delete, and display vocabulary terms
Chapter 34: Customizing the American English Version 389
Customizing Vocabulary Terms
Step 2:
CA Dataquery displays a directory of all vocabulary terms. From this panel you can select the vocabulary term you wish to customize.
Procedure
The following lists panel locations and their descriptions.
<PF7> and <PF8>
Use <PF7> to page the vocabulary directory backward and <PF8> to page forward.
+ and -
Page through the directory using the plus and minus sign. For example, entering
+20 scrolls forward 20 pages and -20 scrolls backward 20 pages.
TOP and BOTTOM
You can also use the TOP and BOTTOM commands. TOP takes you to the first panel of the directory and BOTTOM takes you to the end of the directory.
After you have located the vocabulary term you want to customize, move the cursor down beside the word and press <PF6> TRANSLATE. <PF6> TRANSLATE creates a copy of the vocabulary term.
=>
PLACE THE CURSOR ON THE DESIRED NAME AND PRESS THE APPROPRIATE PFKEY
------------------------------------------------------------------------DQL50
DATAQUERY: DIRECTORY OF VOCABULARY
-----------------------------------------------------------------------------
LANGUAGE| VALUE | ENGLISH VALUE
-----------------------------------------------------------------------------
AE | ACTIVE | ACTIVE
AE | ACTIVE-QUERY | ACTIVE-QUERY
AE | ADMIN | ADMIN
AE | ALL | ALL
AE | AND | AND
AE | ASCENDING | ASCENDING
AE | AVERAGE | AVERAGE
AE | BOTTOM | BOTTOM
AE | BREAK | BREAK
AE | BREAKS | BREAKS
AE | BY | BY
AE | CONDITIONS | CONDITIONS
AE | CONTAINING | CONTAINING
AE | COUNT | COUNT
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> EDIT ITEM
<PF5> DELETE ITEM <PF6> TRANSLATE <PF7> BACKWARD <PF8> FORWARD
390 Administration Guide
Customizing Vocabulary Terms
Step 3:
CA Dataquery displays the VOCABULARY EDIT/TRANSLATE panel. Enter your language code in the TRANSLATE TO LANGUAGE CODE field. Enter the customization in the NEW VALUE field. Your customization cannot exceed 40 characters and must be a single word with no embedded blanks. Press Enter to save your customization. If you want to leave this panel without saving your customization, press the CLEAR key or <PF2>.
VOCABULARY EDIT/TRANSLATE (DQL60)
=>
FILL IN THE DATA BELOW AND PRESS ENTER TO COMPLETE FUNCTION
------------------------------------------------------------------------DQL60
DATAQUERY: VOCABULARY EDIT/TRANSLATE
-----------------------------------------------------------------------------
LANGUAGE CODE: AE TRANSLATE TO LANGUAGE CODE==> ac
-----------------------------------------------------------------------------
VALUE : BOTTOM
ENGLISH VALUE : BOTTOM
NEW VALUE =======> end_____________________________________
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
This example changes the vocabulary term BOTTOM to END.
After saving your customization, CA Dataquery returns you to the literal directory.
Because CA Dataquery displays the vocabulary list in alphabetical order, your customization does not always appear under the base language version of the word.
Editing Vocabulary Terms
You cannot use the edit function to change a vocabulary term in the American English version. You can use the edit function to make a correction to a vocabulary term you have already created through the translate function.
For exact instructions for using the edit function, see
Translating Vocabulary
page 352).
Deleting Vocabulary Terms
CA Dataquery allows you to delete a vocabulary term that is no longer valid. CA
Dataquery does not allow you to delete an American English vocabulary term. For exact
instructions to delete vocabulary terms, see
Deleting Vocabulary Terms
Chapter 34: Customizing the American English Version 391
Chapter 35: Batch Management Overview
Batch CA Dataquery is available to allow long running or high-volume queries to be processed without consuming online system resources. You can effectively improve online performance by taking advantage of this batch processing capability.
When a user executes queries or dialogs in batch, two choices are available: Batch
Sign/On and Batch Online SUBMIT. In Batch Sign/On, the user must create or adapt and use JCL with a product other than CA Dataquery from which the JCL and the input CA
Dataquery statements are submitted to the operating system for batch execution. In
Batch Online SUBMIT, the user uses a CA Dataquery online panel to submit CA
Dataquery JCL from a CA Dataquery library that carries instructions for query execution.
Both types of batch query execution take place offline, conserving resources for online use. The online facilities of CA Dataquery do not have to be up for batch CA Dataquery execution. The execution JCL for batch CA Dataquery points to the load libraries containing the CA Dataquery modules.
One or more users can be given CA Dataquery Administrator authorization for creating and maintaining the CA Dataquery online JCL libraries. The CA Dataquery Administrator maintains the JCL and provides end users with information about which JCL members are appropriate (if the user is given JCL member names in order to be able to use more than one JCL member). With Batch Online SUBMIT, the CA Dataquery Administrator can also create JCL PROCs which permit users to change specific values in a JCL member, as needed.
The following chapters provide background information about CA Dataquery JCL statements, along with examples. For authoritative advice regarding the use of JCL statements, see your systems programmer.
Look in this chapter for overview information about Batch CA Dataquery. The next chapter provides Batch Sign/On JCL statements and examples of both DQL and SQL JCL for Batch Sign/On. The chapter on managing Batch Online provides information about the task of maintaining JCL libraries.
Chapter 35: Batch Management Overview 393
Batch Execution Method Comparison
Batch Execution Method Comparison
Two methods of batch execution work with CA Dataquery: Batch Online and Batch
Signon. Both methods require submitting JCL that contains the information needed by
CA Dataquery to process the query. Batch Online JCL is submitted from the Batch
Execution panel and does not require signon or CA Dataquery input statements. Those items are provided by the online system. Batch Sign/On is submitted from another product and submits JCL and CA Dataquery statements as part of the job stream. Batch
Sign/On requires control cards that may specify various options and must specify the statements for any query or dialog to be executed. The following table shows significant differences between these two batch methods:
Difference Batch Online SUBMIT Batch Sign/On
Requires control statements after the input statement.
Permits the use of
#DQOPERATORNAME as the JCL user ID, allowing ID substitution.
Permits the use of variables.
No
Yes
Yes
Yes
No
No
Batch Online SUBMIT
End users can be authorized by the CA Dataquery Administrator to submit batch jobs with an online panel called Batch Execution (DQE40). This panel submits a JCL member containing information needed to process the query. Maintaining the JCL member is a
CA Dataquery Administrator responsibility.
Users can submit queries or dialogs for batch execution with a panel in online CA
Dataquery and the jobs will execute offline either immediately or at a deferred time.
See the CA Dataquery User Guide for user information about batch online.
As the CA Dataquery Administrator, you can create JCL PROCs for users of Batch Online,
permitting users to perform variable substitution. See
Creating a JCL PROC for Online
Submission
(see page 424) for details. CA Dataquery Administrator information about
Batch Online Management
394 Administration Guide
Batch Execution Method Comparison
Batch Sign/On
The Batch Sign/On method requires JCL that submits CA Dataquery statements to the operating system from another product and processes a query or dialog. End users do not commonly use Batch Sign/On Mode. The JCL can be accessed through CA Roscoe IE,
CA Vollie, TSO or any other batch job submission method and submitted for CA
Dataquery signon and execution. Sign/On mode allows a user who cannot access a CICS monitor to submit batch CA Dataquery jobs through CA Roscoe IE or some other job
Batch Sign/On Management
information about batch Sign/On.
Prerequisites for Using Batch CA Dataquery
To use batch CA Dataquery, you must:
1. Tailor the active System Option Table (DQOPTLST) for batch job submission. The following are the DQOPTLST parameters that impact batch job submission:
■
DQDBID=
■
EXPDEV= (z/VSE only)
■
■
LINPRTL=
LINPRTP=
■
■
■
■
RTIMDQE= (SQL Mode only)
RTIMDQW=
SEQBUFS=
SORTWK= (z/VSE only)
■
■
■
SUBEXIT=
SXBEXIT=
URTPRTY=
2. After modifying the DQOPTLST macro, reassemble and link edit it.
3. Place the updated System Option Table into effect in one of the following ways:
■
■
If the CICS RES count is zero, do a CICS NEWCOPY of DQSYSTBL.
If the CICS RES count is not zero, bring down the monitor and bring it back up again.
4. Check the parameters of the DQW (Work Table). See DQW: Work Table for instructions.
5. Set up the JCL members. Sample JCL for executing DQBATCH in Sign/On mode in z/OS and z/VSE is included at the end of this chapter.
Chapter 35: Batch Management Overview 395
Installing the Internal Reader
Installing the Internal Reader
If your users plan to execute queries using EXECUTE with a report destination of system printer or using SUBMIT, you must first install the CAIVPE internal reader.
z/VSE
See the CA CIS for VSE documentation.
z/OS
Use the JES internal reader supplied by IBM for job submission. The statements of the job stream are written to a sequential file. The file is assigned to the JES internal reader with a DD statement. CAIVPE-based products executing in a partition can share a common JES reader. Interleaving of data from different products assigned to the same reader is prevented by the CAIVPE enqueue mechanism.
For the name of the sequential file under the CICS TP monitor, make an entry in the
Destination Control Table (DCT) for the DESTID or use the default. Unless the default is changed during IPC installation, it is IRDR. Following is a sample for making the entry after signing on to CICS:
1. Verify if the entry is there. If not, go to step 5.
CEDA VIEW TDQUEUE(IRDR) GROUP(*)
2. If you need to change an attribute, specify ALTER to the right of the entry and press Enter. Overtype to modify values and press PF3.
3. Disable and close the TDQUEUE to CICS through:
CEMT INQUIR TDQUEUE(IRDR)
If it shows enabled (ENA) and open (OPE(N)), then overtype these two values with the following commands:
DIS (disabled)
CLS (closed)
4. If IRDR needs to be defined, issue the following commands:
CEDA DEFINE TDQUEUE(IRDR) GROUP(DQGRP) TYPE(EXTRA)
DDNAME(ADRSRB)
TYPEFILE(OUTPUT) RECORDSIZE(80) RECORDFORMAT(FIXED)
BLOCKFORMAT(UNBLOCKED)
5. Install the modified definition into CICS through the following command:
CEDA INSTALL GROUP(DQGRP)
Make sure there is a DD statement that assigns the file to the internal reader. The
DSCNAME keyword in the DFHDCT macro provides the ddname. This entry may already exist as the result of another CA product installation.
396 Administration Guide
Executing Deferred Batch Queries
Executing Deferred Batch Queries
Online CA Dataquery allows a user on an online system to create a query or dialog, or to select a query or dialog from a directory of queries and dialogs. The user can then use the batch execution facility of an online query to submit that query to execute in the batch mode, either immediately or at a deferred time. Executing a deferred batch query is a two step process. Jobs submitted as deferred batch queries do not run until a separate CA Dataquery Batch job with a DEFER control statement executes them.
How a Deferred Batch Query Works
When you request deferred batch execution, an entry is made in a queue in the DQF table, but no job is submitted. The date and time your request was submitted establishes its place in the queue of jobs that are eligible to be run. When you later submit a CA Dataquery batch job with a DEFER input statement, CA Dataquery responds to the DEFER by retrieving and sequentially executing all deferred queries in the queue of eligible jobs.
CA Dataquery stores the queue of deferred batch queries in the DQF table.
Considerations for the System Programmer
Because all the deferred queries in the queue can be sequentially executed by the submission of a single CA Dataquery Batch job that includes a DEFER statement, make certain that the JCL contains everything the queued queries need, for example DD statements for external SORT work areas for system SORT, EXPORT DD statements, and sufficient region/partition size.
Also remember to take into consideration that when you use the DQWFINIT utility to reinitialize the DQF, the queue of deferred queries is destroyed.
If your users plan to defer execution of batch queries, you must:
■
Assess when the best time to run the deferred queries is: consider the needs of your users and your system
■
If you set up a regular schedule for executing deferred batch queries, communicate the schedule to your CA Dataquery Administrator
■
Submit the jobs at the appropriate time
Executing Deferred Batch Queries
(see page 429) for more information.
Chapter 35: Batch Management Overview 397
Preparing for Batch Export Function Use
Preparing for Batch Export Function Use
The CA Dataquery batch export function allows the user to export the columns and keys named in the PRINT or DISPLAY statement of the query to an output table in the order specified in the query. This exported data is then available for use in user-written programs.
Types of Export Files
CA Dataquery places the requested exported data in a sequential output file. Thus, you must allocate a data set for the exported data. There are two different types of export output file:
■
For export as comma-separated values, the output data set must be a sequential file with variable-length rows and blocked format with a block size of 4096 bytes.
The maximum length of any data row is 4088.
If the user executes more than one comma-separated value EXPORT per any execution of DQBATCH, CA Dataquery writes all of the output sets to the same output sequential data set.
The exported data set can be downloaded to a PC, since it is in PC file format (CSV).
■
For export of fixed-length records, the output data set must be a sequential file with a record length equal to that of the exported rows.
The user may not execute more than one fixed-length EXPORT per any execution of
DQBATCH. If a second fixed-length EXPORT is performed within a single execution of DQBATCH, CA Dataquery overwrites the data from the first EXPORT.
z/VSE Requirements
In a z/VSE environment, the System Option Table EXPDEV= parameter specifies the default device for exported data. This default can be overridden for nondeferred jobs at submit time when the system prompts the user for the device. If the exported files will be stored on disk, you should assign some specific space for that purpose. For more
Accessing Exported Data
398 Administration Guide
Sample JCL for Batch Sign/On Mode
Sample JCL for Batch Sign/On Mode
When using CA Dataquery through the Sign/On mode, all of the input to batch CA
Dataquery is made through the use of SYSIN or SYSIPT control statements for z/OS and z/VSE respectively. Provide individual control statements for each CA Dataquery command, with only one command per statement. Examples follow:
Sample z/OS JCL
//jobname See Preparing JCL for Batch CA Dataquery Utilities.
// EXEC PGM=DQBATCH
//STEPLIB See Preparing JCL for Batch CA Dataquery Utilities.
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=* Print Output
//SNAPER DD SYSOUT=*
//USRPRINT DD SYSOUT=*
//SYSIN DD * Command input
SIGN/ON dq-user-id PASSWORD ppppppppp
EXEC sample-query
/*
//
Chapter 35: Batch Management Overview 399
Sample JCL for Batch Sign/On Mode
Sample z/VSE JCL
* $$ JOB ... See Preparing JCL for Batch CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// EXEC DQBATCH
SIGN/ON dq-user-id PASSWORD ppppppppp
EXEC sample-query
/*
/&
* $$ EOJ
400 Administration Guide
Chapter 36: Batch Sign/On Management
You can submit JCL for processing CA Dataquery queries or dialogs through CA Roscoe IE or a similar product, although online submission through CA Dataquery is easier.
■
■
You can use the batch Sign/On mode to perform the following:
■
Submit a DQL Language query
■
Submit a dialog
■
Submit a SQL query
Create a Personal Database Facility table with the STORE command
Export a DQL Language query
CA Dataquery Batch Control Statements Overview
Use the CA Dataquery control statements to identify the functions to be performed in batch query. There are many types of control statements. The following table shows the possible statements in the order they are used. The table provides a brief description along with information about whether each statement is required or optional and whether it is used in DQL Mode, SQL Mode, or both modes. Details about each statement appear in alphabetical order in the next section.
Batch Sign/On Statements in Required Order
Only two Batch Sign/On statements are required for a batch job. They are:
■
SIGN/ON
■
EXECUTE
The following table shows the order and a brief overview of each Batch Sign/On statement. The next section in this chapter provides details for using the statements.
Statement
SIGN/ON
OPTION DDBASE=
Description DQL, SQL, or Both
(Required.) Specifies the user ID and password (if any).
Both
Names the database ID of the CA
Datacom Datadictionary database if different from the default.
Both
Chapter 36: Batch Sign/On Management 401
CA Dataquery Batch Control Statements Overview
Statement
OPTION QUERYLANG=
OPTION AUTHID=
OPTION DIAGNOSTICS=
OPTION PLANOPTS,MSG=
OPTION PLANOPTS,DISPLAY=
OPTION PLANOPTS,OPT=
OPTION STATISTICS=ON
OPTION WINDOWING=NO
OPTION QUERYTEXT=YES
OPTION PAGESTOGETHER=YES
SELECT, UPDATE, DELETE, and INSERT
FIND and COUNT
EXECUTE
EXPORT
Description
Specifies language to use if user is authorized for both. Otherwise the last online mode at signoff will be used.
DQL, SQL, or Both
Both
Specifies the authorization ID to be used in the query.
SQL
With option CBS, tells CA Dataquery to produce Compound Boolean
Selection diagnostic reports. If option RQT is used, this statement should follow
FIND or EXECUTE.
DQL
Tells CA Datacom/DB whether to produce detail or summary messages about preparation and execution time.
Tells CA Datacom/DB whether to print preparation and execution time messages during execution.
SQL
SQL
Tells CA Datacom/DB whether to use user-specified join order or
SQL-chosen join order.
SQL
Both Provides statistical information on execution.
Specifies WRAP (NO) or NOWRAP
(YES) selections for reports.
Prints text of query.
Both
Both
Both Print report pages together (YES) or print front pages and then back pages (NO).
SQL query keywords. Each must be on a separate line.
DQL query keywords.
SQL
DQL
(Required.) Executes the query or dialog named in the statement.
Both
Exports data found by the query to a sequential file.
Both
402 Administration Guide
CA Dataquery Control Statements
Statement
STORE
Description
Creates a new Personal Database
Facility table containing query or dialog output.
DQL, SQL, or Both
Both
CA Dataquery Control Statements
The following is a detailed description of each control statement used in submitting a
DQL Language or SQL query. Statements appear in alphabetical order.
OPTION AUTHID=
(Optional - Valid in SQL Mode only.) Allows you to specify the authorization ID that is to be used in the query. The format of the OPTION AUTHID= statement is as follows:
►►─ OPTION ─ AUTHID= nnnnnnnn ─────────────────────────────────────────────────►◄
Where nnnnnnnn is a 1- to 18-character authorization ID.
Valid Entries:
A valid 1- to 18-character ID that specifies the authorization ID used in your query
Default Value:
If no OPTION AUTHID= statement is used, your private authorization ID
EXECUTE
(Required in both SQL Mode and DQL Mode.) Tells CA Dataquery to execute the query.
EXEC can also be used. If this keyword is omitted, the query does not execute and no printed output is produced.
►►─ EXECUTE ─
►─ (
►►─ EXECUTE ─ name
─ ( variable-list
) ─ ( stage-1
) ─
(thru
─ stage-2)
──────────► total-option
) ───────────────────────────────────────────────────────────►◄ name
─ ( total-option
) ──────────────────────────────────────────►◄
name
(Required in both SQL Mode and DQL Mode.) Specifies a name of a query or dialog to execute.
Valid Entries:
A 1- to 15-character query name, or an asterisk (*) to specify execution of the active query. To use the active query, enter it in the JCL stream immediately preceding the EXECUTE statement, using the FIND statement of the DQL query or any SQL query statement. The active query cannot be a dialog.
Default Value:
(No default)
Chapter 36: Batch Sign/On Management 403
CA Dataquery Control Statements
(variable-list)
(Optional - Valid in both SQL Mode and DQL Mode.) The variable-list is a list naming the variables which can be substituted for a dialog executed by this batch job. This is optional and if not given for a dialog, the query is executed with the default values.
If it is necessary to continue a statement when naming values for dialog variables, place any non-blank character in column 72 of the SYSIN or SYSIPT statement. The statement to be continued can end at any comma in the variable list and the next variable can begin in any position on the next statement. To enter a very long variable value, continue the variable through column 71 with the continuation character in column 72, and begin the continuation in column 1 of the next statement. Only a variable-list can continue from one statement to another. All of the other parameters on the statement must be totally contained on one SYSIN or
SYSIPT statement variable. Identify each variable by its dialog number. Separate each variable value with a comma.
Valid Entries:
Enter the variable number indicated in the dialog, an equal sign, and the value.
Default Value:
The default values assigned to the dialog variable
The following is a sample valid variable-list entry:
1='EASTERN',15='986',3='CAI'
(stage-1)
(Optional - Valid in DQL Mode only.) Specifies at which stage query execution should begin. This is optional and is only used when specifying that execution stop at a specific stage before producing output. An example of an instance when you might choose to stop execution before producing output is: selecting data for
EXPORT without printing it first. In DQL Mode, batch execution only permits stage-1 to be FIND. Enter stage-1 when specifying that execution stop at a specific stage.
(See stage-2, next.) Names the first stage of the query to execute, which in batch CA
Dataquery must be FIND.
Valid Entries:
FIND
Default Value:
FIND
404 Administration Guide
CA Dataquery Control Statements
(thru-stage-2)
(Required when stage-1 is specified - Valid in DQL Mode only.) Indicates the last stage of the query to be executed. (THRU is an optional word.)
Valid Entries:
SET, SORT, PRINT, or DISPLAY
Default Value:
Defaults to the last CA Dataquery keyword in the query.
total-option
(Optional - Valid in both SQL Mode and DQL Mode.) Indicates the type of totaling to be done, if any. In DQL Mode, indicates the type of totaling to be done, if any. In
SQL Mode, TOTALS option will have meaning only for a query developed online for which a report format has been generated.
Valid Entries:
NO-TOTALS or TOTALS-ONLY
Default Value:
Defaults to the value specified in the query.
EXECUTE Examples
The following is an example of an EXECUTE statement for a dialog with totals:
EXEC MYDIALOG 1="JUNE',3='TEXAS',4=500.00 TOTALS-ONLY
The following is an example of an EXECUTE statement that is not a dialog but uses all options:
EXEC MYQUERY FIND THRU SORT TOTALS-ONLY
EXPORT
(Optional - Valid in both SQL Mode and DQL Mode.) Tells CA Dataquery to export the data. The format for the EXPORT statement is:
►►─ EXPORT ─ set-name
─ data-type
─ output-type
─ data-format
────────────────►◄
set-name
Identifies the set being exported.
Valid Entries:
A valid 1- to 15-character set name enclosed in apostrophes.
Default Value:
(No default)
Chapter 36: Batch Sign/On Management 405
CA Dataquery Control Statements
data-type
Indicates whether detail or total records are exported.
Valid Entries:
DETAIL or TOTALS (Use 2 EXPORT statements to have both details and totals reported.) Only DETAIL is valid for use with a FIXED format. See data-format
Default Value:
DETAIL
output-type
(Optional - Valid in z/VSE DQL Mode only.) Indicates the device type.
Valid Entries:
TAPE or DISK
Default Value:
The value specified in the System Option Table TYPE= option.
data-format
(Optional) Indicates the format for data on the output data set. Available formats are CSV and FIXED. CSV means variable-length records with values separated by a character specified in the CA Dataquery System Option Table. FIXED means fixed-length records. Only one EXPORT of fixed-length records is permitted per execution in Batch Sign/On Mode.
Valid Entries:
CSV or FIXED
Default Value:
CSV
For more information on the EXPORT function, see
Using the Batch Export Function
page 433).
406 Administration Guide
CA Dataquery Control Statements
FIND or COUNT
(Optional - Valid in DQL Mode only.) One of these keywords must be the first word of a query input on an input statement in batch CA Dataquery, since an active found set does not exist for batch CA Dataquery. The COUNT keyword provides no print of the query.
Use only FIND or only COUNT. When using CA Dataquery through the Sign/On mode, all of the input to batch CA Dataquery is made through the use of SYSIN or SYSIPT control statements for z/OS and z/VSE respectively. Provide individual control statements for each CA Dataquery keyword, with only one keyword per statement. However, you can have an entire query on one statement if you follow these rules:
■
Begin the query on line 1 of the control statement.
■
Put a non-blank character in column 72 and continue on the next line if the query exceeds 71 characters.
■
Do not split words at the end of one line.
■
■
Do not use a continuation (non-blank) character in column 72 of the last line of a query.
Use a maximum of n times 24 lines for your query, where n is the number of pages of query text specified in the CA Dataquery System Option Table in the QPAGES= parameter.
Options can be reset between queries if you are submitting several queries at one time.
Following is a sample valid query:
----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+
FIND ALL COMPANY +
SORT COMPANY-NUMBER +
PRINT COMPANY-NUMBER BILLED PAID
FIND
The format for the FIND keyword is as follows:
►►─ FIND ─ data ──────────────────────────────────────────────────────────────►◄
data
Is the rest of the user's query text.
Valid Entries: Enter a valid query text.
Default Value: (No default)
COUNT
(Optional - Valid in DQL Mode only.) The COUNT keyword provides the number of rows found. The format for the COUNT keyword is as follows:
►►─ COUNT ─ data ─────────────────────────────────────────────────────────────►◄
Chapter 36: Batch Sign/On Management 407
CA Dataquery Control Statements
data
Is the rest of the user's query text.
Valid Entries:
Enter a valid query text.
Default Value:
(No default)
OPTION DDBASE=
(Optional - Valid in both SQL Mode and DQL Mode.) Names the database ID of the tables specified in the batch query if different from the one defined in the CA Dataquery
System Option Table. The format of the OPTION DDBASE= statement is as follows:
►►─ OPTION ─ DDBASE= nnnnn
────────────────────────────────────────────────────►◄
nnnnn
Is the numeric database ID.
Valid Entries:
The valid CA Datacom Datadictionary database ID that contains the table specified in the user's query.
Default Value:
The database ID from the CA Dataquery System Option Table.
OPTION DIAGNOSTICS=
(Optional - Valid in DQL Mode only.) Produces Compound Boolean Selection diagnostics report or the request table. The format of the OPTION DIAGNOSTICS statement is as follows:
►►─ OPTION ─ DIAGNOSTICS= ─┬─ CBS ───┬────────────────────────────────────────►◄
├─ OFF ◄ ─┤
└─ RQT ───┘
This option specifies printing of a Compound Boolean Selection diagnostics report, the request table, or no diagnostics.
Valid Entries:
CBS, OFF, or RQT
Default Value:
OFF
Note: If RQT is used, this statement should follow either the FIND or EXECUTE statement. Otherwise, it should precede the FIND or EXECUTE statement.
408 Administration Guide
CA Dataquery Control Statements
OPTION PLANOPTS, DISPLAY
(Optional - Valid in SQL Mode only.) Specifies printing messages requested with OPTION
PLANOPTS,MSG= statement. This statement should follow the EXECUTE statement.
OPTION PLANOPTS,DISPLAY
OPTION PLANOPTS,MSG=
(Optional - Valid in SQL Mode only.) Specifies the kinds of SQL Plan Optimization messages to be produced. This statement should precede the query and the EXECUTE statement.
OPTION PLANOPTS,MSG=xy
xy
x specifies messages about preparation time and y specifies messages about execution time.
Valid Entries:
N - No messages
S - Summary messages
D - Detail messages
Default Value:
NN
OPTION PLANOPTS,OPT=
(Optional - Valid in SQL Mode only.) Specifies the type of join order to be used.
OPTION PLANOPTS,OPT= M
P
This option specifies that CA Dataquery use the order specified in the query or that CA
Dataquery use the order chosen by SQL.
Valid Entries:
M - Order from user
P - Order from SQL
Default Value:
Order decided by SQL at statement preparation time.
Chapter 36: Batch Sign/On Management 409
CA Dataquery Control Statements
OPTION PAGESTOGETHER=
(Optional - Valid in both DQL Mode and SQL Mode.) Used only when windowing is requested with OPTION WINDOWING statement. Specifies if the report pages are printed with all windows of a page together (1A, 1B, 1C...2A, 2B, and so forth) or all pages of a window together (1A, 2A, 3A,...1B, 2B, 3B, and so forth). The format of the
OPTION PAGESTOGETHER statement is:
►►─ OPTION ─ PAGESTOGETHER= ─┬─ YES ─┬────────────────────────────────────────►◄
└─ NO ──┘
The option specifies whether to print windows of a page together (YES) or to print pages of a window together (NO).
Valid Entries:
NO or YES
Default Value:
Your profile value for hardcopy print options.
OPTION WINDOWING=
(Optional - Valid in both DQL Mode and SQL Mode.) Specifies the WRAP and NOWRAP selections for reports. The format of the OPTION WINDOWING statement is as follows:
►►─ OPTION ─ WINDOWING= ─┬─ YES ─┬────────────────────────────────────────────►◄
└─ NO ──┘
This option specifies whether to have CA Dataquery print the report with the lines wrapped (NO) or to have CA Dataquery to print the report without wrapping (YES).
Valid Entries:
NO or YES
Default Value:
Your profile value for hardcopy print options.
OPTION QUERYLANG=
(Optional - Valid in both DQL Mode and SQL Mode.) Specifies the query language (either
DQL or SQL) to be used in the query. Causes the named query language to be used, rather than the last language used online. The format of the OPTION QUERYLANG= statement is as follows:
►►─ OPTION ─ QUERYLANG= ─┬─ DQL ─┬────────────────────────────────────────────►◄
└─ SQL ─┘
410 Administration Guide
CA Dataquery Control Statements
This option specifies the query language ID.
Valid Entries:
DQL or SQL
Default Value:
The CA Dataquery query language ID specified on your profile.
OPTION STATISTICS=
(Optional - Valid in both DQL Mode and SQL Mode.) Tells CA Dataquery to provide statistical information on the execution of the query or dialog. The format of the
OPTION STATISTICS statement is as follows:
►►─ OPTION ─ STATISTICS= ─┬─ ALL ─┬───────────────────────────────────────────►◄
├─ ON ──┤
└─ OFF ─┘
Specify ON to have CA Dataquery print the statistics, OFF for CA Dataquery to print no statistics page, or ALL for CA Dataquery to print extended statistics (DQL only.)
Valid Entries:
ON, OFF, or ALL
Default Value:
Your profile value for hardcopy print options.
OPTION QUERYTEXT=
(Optional - Valid in both DQL Mode and SQL Mode.) Specifies whether the text of the query that produced the report is printed when the report is printed. The format of the
OPTION QUERYTEXT statement is as follows:
►►─ OPTION ─ QUERYTEXT= ─┬─ YES ─┬────────────────────────────────────────────►◄
└─ NO ──┘
Specifies YES to have CA Dataquery print the text of the query and NO to have CA
Dataquery to print no query.
Valid Entries:
NO or YES
Default Value:
Your profile value for hardcopy print options.
PRINT-ONLY
Indicates that the report is produced on the system printer. This is the default.
Chapter 36: Batch Sign/On Management 411
CA Dataquery Control Statements
SELECT and Other SQL Statements
(Optional - Valid in SQL Mode only.) These keywords must be the first word of a query input on an input statement in batch CA Dataquery if the query is to select columns from a table. Use only one of these statements: SELECT, UPDATE, DELETE, INSERT,
CREATE, DROP, ALTER, GRANT, REVOKE, and any other SQL keyword that can be used in online CA Dataquery. Use these keywords as they would be used online in a SQL Mode query. See the CA Dataquery Reference Guide for details about use.
You can have an entire query on one statement if you follow these rules:
■
Begin the query on line 1 of the control statement.
■
Put a non-blank character in column 72 and continue on the next line if the query exceeds 71 characters.
■
Do not split words at the end of one line.
■
■
Do not use a continuation (non-blank) character in column 72 of the last line of a query.
Use a maximum of n times 24 lines for your query, where n is the number of pages of query text specified in the CA Dataquery System Option Table in the QPAGES= parameter.
The format for the SQL keyword is:
►►─ sqlkeyword ─ data ────────────────────────────────────────────────────────►◄
sqlkeyword
data
Is any valid SQL keyword (see the CA Dataquery Reference Guide).
Is the rest of your query text.
SIGN/ON
(Required) Identifies the CA Dataquery user to CA Dataquery. Only one SIGN/ON statement is allowed and it must be the first statement in the job stream. The
PASSWORD keyword is required if a password is assigned, optional if there is no password.
userid
Is the CA Dataquery user identification assigned to you.
Valid Entries:
A 1- to 32-character CA Dataquery user ID
Default Value:
(No default)
412 Administration Guide
CA Dataquery Control Statements
password
Is the your password, if one is assigned.
Valid Entries:
A 1- to 9-character password
Default Value:
(No default)
STORE
(Optional - Valid in both DQL Mode and SQL Mode.) With unique table name operand, creates a personal table from active found set of data in DQL Mode or SQL Mode. The format of STORE follows:
►►─ STORE ─ new-table-name
───────────────────────────────────────────────────►◄
new-table-name
A 1- to 32-character Personal Database Facility table name for the new personal table which is to contain the output from this query.
Chapter 36: Batch Sign/On Management 413
Chapter 37: Batch Online Management
Users can submit queries through online batch job execution using the Batch Execution panel or by normal batch job submission.
Authorizing Users for Batch
Users must be authorized for batch submission by specifying Y (yes) in the SUBMIT
ALLOWED field on the User Table Maintenance panel, accessed from the USERS option
on the Administrative Menu. (See
Adding a New User
Using Batch Online
When a user submits a query from the online batch execution panel, CA Dataquery searches the CA Dataquery JCL library for the appropriate Batch Online JCL member. To use a specific JCL member, users can type a valid JCL name over the displayed value. A user's only access to JCL names is by having access to the JCL library (authorization) or by being told a JCL name. If a user knows a JCL name, he can use it automatically if he is authorized for Batch Online.
CA Dataquery will not allow users to input a JCL member name when they specify the system printer for the report destination. CA Dataquery searches the JCL library in the order described in the next section and uses the first JCL member which meets the criteria.
Understanding the System
End users can share JCL if:
■
A DQ PROC (a special DQ JCL member) is set up with a variable for the user's ID, or
■
The DQ JCL member contains the #DQOPERATORNAME variable so that the user's
ID will replace the variable when the JCL is used. For more information on PROCs,
PROC Example
(see page 427), or for more information on the
#DQOPERATORNAME variable, see the next section.
CA Dataquery searches the JCL library in the following order for:
■
JCL member whose name matches the user ID
■
JCL member whose name matches the user's Group Level 3 ID
Chapter 37: Batch Online Management 415
Understanding the System
■
■
■
JCL member whose name matches the user's Group Level 2 ID
JCL member whose name matches the user's Group Level 1 ID
Default JCL member named $$DQJCL
When CA Dataquery finds a JCL member name that matches one of the above criteria,
CA Dataquery supplies that value on the Batch Execution panel. When the Batch
Execution panel (DQEN0) is used, the name of a JCL member appears on the panel. The name is selected according to the above criteria. The user may change the name to any valid JCL member or PROC name.
Sharing JCL
End users can share JCL if it contains the #DQOPERATORNAME variable ID so that when the user enters a valid JCL name, the #DQOPERATORNAME is automatically replaced by the user's ID. Only the first occurrence of #DQOPERATORNAME is replaced per line (80 byte card image). If replacing #DQOPERATORNAME in the JCL causes the line to go past column 71, the DQ506E error message is displayed and the JCL needs to be changed for the variable to be used.
An example for using the #DQOPERATORNAME variable is as follows:
■
The site has CA Top Secret external security on their system
■
The user signed on to CA Top Secret with a user's ID of TSS-USER
■
The user signed on to CICS with a user's ID of CICS-USER
■
When the user ran the following JCL, #DQOPERATORNAME was replaced with
TSS-USER
An example for z/OS would be:
// jobname JOB (accounting information),MSGCLASS=X,CLASS=A,
// USER=#DQOPERATORNAME,PWD=ABCD
// EXEC PROC=procname
// EXEC PGM=DQBATCH
// SYSIN DD *
/* DQ INPUT
//
416 Administration Guide
Understanding the System
When these jobs run, everywhere #DQOPERATORNAME was found in the above JCL, it was replaced with the TSS userid of TSS-USER. For more information about DQ user ID's and security, see the CA Datacom Security Reference Guide. Another way to accomplish this is to set up DQ PROC (special DQ JCL) members that allow substitution of several
PROC Example
(see page 427), for an example.
An example for z/VSE would be:
* $$ JOB JNM=DQBATCH,....
// JOB #DQOPERATORNAME
// ID USER=#DQOPERATORNAME,PWD=ABCD
// EXEC PROC=procname
* * #DQOPERATORNAME
// EXEC DQBATCH
/* DQ INPUT
/*
/&
* $$ EOJ
Note: There is not a special DQ variable to obtain the password from TSS and pass it to the //ID statement in your JCL. In this case, the password had to be hardcoded. Another way to handle variable substitution is mentioned in the above z/OS example.
Chapter 37: Batch Online Management 417
Using the System Default Member ($$DQJCL)
Using the System Default Member ($$DQJCL)
CA Dataquery requires that you name the system default JCL member for the online submission of a batch query $$DQJCL. No other default name is acceptable. The next sections provide sample $$DQJCL jobs. Use your Systems Programmer as the authority when creating user JCL members. The following $$DQJCL samples demonstrate the required statements for the $$DQJCL system default JCL.
Sample z/OS JCL
Following is a sample of a $$DQJCL job for z/OS.
//jobname See Preparing JCL for Batch CA Dataquery Utilities.
// EXEC PGM=DQBATCH
//STEPLIB See Preparing JCL for Batch CA Dataquery Utilities.
//SYSPRINT DD SYSOUT=* Print Output
//SYSUDUMP DD SYSOUT=*
//SNAPER DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//DQOUT DD ... Code according to your site standards if using EXPORT, or
//DQFIXD DD ... Code according to your site standards if using EXPORT
//SYSIN DD * Command input
/* DQ INPUT
//
DQ INPUT is provided by the active member submitted by the user.
418 Administration Guide
Library Management
Sample z/VSE JCL
Following is a sample $$DQJCL member for z/VSE.
* $$ JOB ... See Preparing JCL for Batch CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// EXEC DQBATCH
// DLBL DQOUTD Code according to your site standards if using EXPORT, or
// TLBL DQOUTT Code according to your site standards if using EXPORT, or
// DLBL DQFIXD Code according to your site standards if using EXPORT, or
// TLBL DQFIXT Code according to your site standards if using EXPORT
/* DQ INPUT
/*
/&
* $$ EOJ
DQ INPUT is provided by the active member submitted by the user.
Library Management
■
■
Maintaining the JCL library is an important CA Dataquery administrative job function.
You use the JCL option on the Administrative Menu to perform the following tasks:
■
Viewing a listing of JCL members
■
Creating JCL members
■
Editing JCL members
Deleting JCL members
Adding new copies of JCL members to the JCL library
■
Establishing definitions for variables in a JCL procedure member (See
PROC for Online Submission
Creating a JCL
Chapter 37: Batch Online Management 419
Selecting a Batch Online JCL Member
There is no limit to the number of JCL members that you can have in your JCL library.
However, you need at least one member, named $$DQJCL, which is required as the system default JCL member.
The Submit panel allows entry of any JCL member name. $$DQJCL is used as a default only if no JCL member is found under the user's name or any of the user's groups. All JCL members are used to submit batch queries or print requests to the system offline batch printer. A JCL member is assigned to a user by naming it with the user's name or to a
group of users by naming it with the group name. See
Creating or Editing a JCL Member
(see page 422) for more information.
Selecting a Batch Online JCL Member
When you select the JCL option from the Administrative Menu, or use the JCL command from the command line, CA Dataquery displays the DIRECTORY OF JCL MEMBERS panel as shown following.
DIRECTORY OF JCL MEMBERS (DQDS0)
=>
Place the cursor on a name to delete or edit. Use PF3 to add JCL members
------------------------------------------------------------------------DQDS0
DATAQUERY: DIRECTORY OF JCL MEMBERS
START WITH: _______________________________ START TYPE: P Proc or Jcl
-----------------------------------------------------------------------------
USER NAME OR GROUP-ID | TYPE | DESCRIPTION
-----------------------------------------------------------------------------
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
-------------------------------------------------------------------------- ===>
<PF1> HELP <PF2> RETURN <PF3> CREATE <PF4> EDIT
<PF5> NOT USED <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
<PF9> NOT USED <PF10> NOT USED <PF11> NOT USED <PF12> RIGHT
420 Administration Guide
Selecting a Batch Online JCL Member
Action
The START WITH: field, located in the upper-left corner of this panel, is where you enter the full or partial name of the JCL where you want the listing to start. When you press
Enter, CA Dataquery refreshes the Directory of JCL MEMBERS panel with the JCL that you specified on the first line of the listing. You can also page forward using <PF8>
FORWARD, or backward using <PF7> BACKWARD until you reach the member that you want to view or edit. START TYPE tells if the START WITH is a JCL or PROC name (P is the default).
Panel Description
The following list describes each column of the Directory of JCL Members panel.
USER NAME
OR GROUP-ID
Alphabetical listing of all existing JCL member names. Usually the JCL member is a user ID or group level ID.
TYPE
Date the named JCL member was last accessed.
DESCRIPTION
Description of this JCL member as described on the EDITOR panel when it was created.
PF Keys
The following list describes the PF keys on the DIRECTORY OF JCL MEMBERS panel.
Key Objective Result
CLEAR Return to the Main Menu
<PF1> HELP
Return to the Main
Menu
Display HELP panel
<PF2> RETURN
<PF3> CREATE
<PF4> EDIT
<PF5> NOT USED
<PF6> DELETE
Return to previous panel
Create a new JCL member
Modify a JCL member
Not in use
Delete a JCL member
CA Dataquery displays the
HELP panel
Previous panel or Main Menu is displayed
CA Dataquery displays the
EDITOR panel
Display that JCL member
CA Dataquery removes that JCL member
Chapter 37: Batch Online Management 421
Creating or Editing a JCL Member
Key
<PF7>BACKWARD
<PF8> FORWARD
Objective
Scroll to previous screen of JCL members, if any
Scroll to next screen of
JCL members, if any
Result
Display previous JCL members, if any
Display more JCL members, if any
Creating or Editing a JCL Member
You must build the JCL members for the end users. If you have existing JCL, it is still functional if it meets the criteria discussed in this chapter.
Use your Systems Programmer as the authority when creating user JCL members.
Action
When you want to create a new Batch Online JCL member or edit an existing Batch
Online JCL member, begin by selecting the JCL option from the Administrative Menu, or use the JCL statement from the statement line. When the DIRECTORY OF JCL MEMBERS panel appears, press <PF3> CREATE, to create a new member, or <PF4> EDIT, to modify an existing member. CA Dataquery displays the EDITOR panel with the TYPE field specified as JCL. A sample JCL EDITOR panel follows:
JCL EDITOR (DQD10)
=>
------------------------------------------------------------------------DQD10
DATAQUERY: EDITOR
-----------------------------------------------------------------------------
NAME: TEMP TYPE: JCL
DESCRIPTION: ____________________________________________________________
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+.
.. ================================ T O P =====================================
01
02
03
04
05
06
.. =========================== B O T T O M ==================================
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> SAVE
<PF5> PROC DEF <PF6> DELETE <PF7> BACKWARD <PF8> FORWARD
<PF9> UPDATE <PF10> VALIDATE <PF11> RIGHT/LEFT <PF12> NOT USED
422 Administration Guide
Creating or Editing a JCL Member
Use and operation of the CA Dataquery EDITOR is fully described in the CA Dataquery
User Guide.
CA Dataquery does not perform syntax checking on JCL statements. If errors are present in your JCL member, the submitted job does not execute properly. JCL errors are detected and reported by the operating system. Test JCL by submitting sample jobs.
Saving a JCL Member
When you create a new JCL member, you must press <PF4> SAVE to save that member in the JCL library. You cannot update or edit a new member until it has been saved. CA
Dataquery does not know that that member exists until you save it.
Copying a JCL Member
To copy an existing member, select the JCL option from the Administrative Menu, or use the JCL statement from the statement line. When the DIRECTORY OF JCL MEMBERS appears, position the cursor on the member name and press <PF4> EDIT. When the member appears on the EDITOR panel, type the new member name over the old member name and press <PF4> SAVE. CA Dataquery redisplays the EDITOR panel with the new member stored on the JCL library. Edit the new member as needed.
Deleting a JCL Member
To delete a JCL member, begin by selecting the JCL option from the Administrative
Menu or use the JCL command from the command line. When the DIRECTORY OF JCL
MEMBERS panel appears, locate the cursor beside the JCL member that you wish to delete and press <PF6> DELETE.
Note: Once you delete a JCL member, that member is deleted and cannot be restored or reaccessed. The entire member, including the variable definition for PROCs, is deleted.
Chapter 37: Batch Online Management 423
Creating a JCL PROC for Online Submission
Creating a JCL PROC for Online Submission
CA Dataquery provides a method of tailoring JCL at submission time. Special JCL members called PROCs, can be defined with substitutable variables. You can create JCL members that contain variables for which values can be substituted when the JCL is submitted. A PROC is to JCL what dialogs are to queries. The PROC variables are identified with dialog symbols and use dialog fill characters.
Comparison
The differences between PROCs and dialogs are:
■
You do not validate a PROC. You submit it using different values for the variables to test the validity of the PROC.
■
PROC variables must occur on the end of the line in the JCL if they contain a comma.
Uses
PROCs can serve a variety of functions. You may need to establish naming conventions at your site, or limit the execution of certain programs or use of data sets. Whatever the requirements are for your site, you can create one PROC with substitutable values for each one.
As you learn about CA Dataquery and create a few PROCs of your own, you will think of more uses for them. Since you can list valid values and specify ranges for numeric variables, you can make sure that only the values you authorize are used in your PROCs.
424 Administration Guide
Creating a JCL PROC for Online Submission
Before You Begin
It is advisable to create a working JCL member, save it, validate it and execute it before adding the variables and making it into a PROC. If errors occur after you make it into a
PROC, it is easier to locate the problem.
A sample JCL member follows that is used as the basis of a PROC that changes the job name, user ID and password.
01 //jobname Code according to site standards (See Preparing JCL for Batch CA
Dataquery Utilities).
01 //DQBATCH JOB (DAL-BO7,DQ110103),DQ,MSGCLASS=T,
02 // USER=DQUSER,
03 // PASSWORD=DQU
04 // EXEC PGM=DQBATCH
05 //STEPLIB See Preparing JCL for Batch CA Dataquery Utilities.
06 .
07 .
08 .
09 .
10 //SYSPRINT DD SYSOUT=*
Display the JCL member
To create a PROC from an existing public JCL member, begin by selecting the JCL option from the Administrative Menu or use the EDIT command to display the JCL member. CA
Dataquery displays the EDITOR panel containing a copy of the JCL member, with the original name, type, status and description.
The EDITOR panel allows you to copy and modify an existing JCL member by assigning it a new name, type and description. You can modify any part of the JCL member shown.
For more information about the EDITOR panel, see
Creating or Editing a JCL Member
(see page 422).
Chapter 37: Batch Online Management 425
Creating a JCL PROC for Online Submission
Important Concepts
To understand creating PROCs, see the CA Dataquery User Guide for details on creating dialogs. You may also want to see the user instructions for responding to JCL PROCs in the same book. Creation and terminology for PROC creation is the same as for dialog creation. This section provides special information for PROCs only.
Variable
Designate any part of a JCL member a variable. The user submitting the JCL substitutes another value, such as a job name, DSN, or VOLSER, for the variable.
Default
A PROC variable must have a default value that the user can submit without changing the variable. The default variable can be blanks by using all dialog fill characters.
Defaults must be acceptable to CA Dataquery without the variable ID.
Commas in JCL
If a JCL variable ends with a comma, the variable must be on the end of the line because a blank is required to indicate the end of the variable.
Save or Update
After you set up your variables in the JCL member, you should save the JCL member if you have not already, or update it if you have saved it previously.
426 Administration Guide
Creating a JCL PROC for Online Submission
PROC Example
The following panel shows how the variable IDs and fill characters for this PROC were inserted. (Select PROCESS MODE with <PF12> and press <PF4> SAVE to save the PROC.)
Sample PROC EDITOR Panel
=>
------------------------------------------------------------------------DQD10
DATAQUERY: EDITOR
-----------------------------------------------------------------------------
NAME: SITEJCL________ TYPE: PROC__
DESCRIPTION: NEW COMPANY JCL ___
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+.
.. ================================ T O P =====================================
01 //1?DQBATCH_ JOB (DAL-BO7,DQ110103),DQ,MSGCLASS=T,
02 // USER=2?USERID,____________
03 // PASSWORD=3?PASSWORD
04 // EXEC PGM=DQBATCH
05 //STEPLIB DD DSN=datacom.products.loadlib
06 .
07 .
08 .
09 .
10 //SYSPRINT DD SYSOUT=*
=========================== B O T T O M ==================================
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISPLAY COLUMNS<PF4> DISPLAY KEYS
<PF5> DISPLAY ALL <PF6> LIST TABLES<PF7> BACKWARD <PF8> FORWARD
<PF9> TEMPLATE <PF10> VALIDATE <PF11> RIGHT/LEFT <PF12> PROCESS MODE
The following list explains each entry/selection. These items are only examples and are not hardcoded.
1?DQBATCH_
Change the job name.
2?USERID,_______
Change the user ID.
3?PASSWORD__
Change the password.
PROCESS MODE
<PF4> SAVE
Save the PROC definition so far.
Chapter 37: Batch Online Management 427
Removing JCL Members When Deleting a User
Other Things You Could Do
You could make any other logical part of the JCL member a variable by adding variable
IDs and where needed, dialog fill characters. You can use variables for:
■
Data set names
■
VOLSERs
■
Region size
■
Partition size
■
Program name to be executed
Removing JCL Members When Deleting a User
When you use a DELETE function to remove a user, the corresponding JCL members are also removed from the set of JCL members stored on the DQQ table. The user's authorization records stored on the CA Datacom Datadictionary are deleted as well.
However the person entity-occurrence is not deleted. Consult with the administrator in charge of security about reassigning the JCL members before you delete a user.
428 Administration Guide
Chapter 38: Executing Deferred Batch
Queries
The SUBMIT command is used by an online user to submit a CA Dataquery batch job for execution. The batch online panel provides an option allowing you to defer the execution submitted until after a specified time. You can also request a specific JCL member to use to execute the deferred query. Deferred query execution allows you to:
■
Run jobs at times when resources are cheaper
■
Run the job when there is less competition for resources
■
Run after updating has completed
Deferral is especially useful for long-running queries.
When you construct batch queries and submit them through the Batch Execution panel, you can either request that queries process immediately or be deferred until a later time. If you choose to defer the execution, you must designate a time, and the query can only be executed after that time has passed. This needs the coordination of the users and operations staff so that specified times fit in with the systems schedule for starting up the deferred queries.
Chapter 38: Executing Deferred Batch Queries 429
Removing JCL Members When Deleting a User
Action
To start up a batch execution that you deferred, build a job stream to activate the batch processor.
Sample z/OS JCL
Specify DEFER after the SYSIN control card as shown in the following z/OS example.
//jobname See Preparing JCL for Batch CA Dataquery Utilities.
// EXEC PGM=DQBATCH
//STEPLIB See Preparing JCL for Batch CA Dataquery Utilities.
//SYSPRINT DD SYSOUT=* Print Output
//SYSUDUMP DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSIN DD *
DEFER
/*
//
Sample z/VSE JCL
Specify DEFER after the EXEC control card as shown in the following z/VSE example.
* $$ JOB ... See Preparing JCL for Batch CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// EXEC DQBATCH
DEFER
/*
/&
* $$ EOJ
430 Administration Guide
Removing JCL Members When Deleting a User
How It Works
CA Dataquery searches the DQF work table queue for queries that are ready to execute
(those queries for which the time specified by the user has passed) and executes them.
The printer prints a page that identifies you before printing each executed query. When all queries for that specified time are processed, the batch query processor stops processing.
Chapter 38: Executing Deferred Batch Queries 431
Chapter 39: Using the Batch Export
Function
The CA Dataquery batch export function allows the user to export the columns and keys named in the PRINT or DISPLAY statement of the query to an output file in the order specified in the query. The tables and keys named in the PRINT or DISPLAY statements of the query determine the columns in the output record. This exported data is then available for use in user-written programs. The user must be authorized for SUBMIT
ALLOWED and EXPORT ALLOWED on the User Table Maintenance panel.
JCL Member Creation
Because CA Dataquery places the requested exported data in a sequential output file, a data set must be allocated for the exported data. When you create your JCL member for exporting data, specify the name of the data set to which the export data is to be written.
Device Type
The JCL member can specify any device type supported by IBM QSAM (z/OS). In a z/OS environment, you can specify either a tape or disk file in your JCL member.
In a z/VSE environment, the System Option Table option specifies whether the default is tape or disk. This default can be overridden for nondeferred jobs at submit time when the system prompts the user for the device. The user's response must match the device specified in the JCL member. Deferred jobs always take the System Option Table value.
DDname
CA Dataquery has specific requirements for the DDname in your export JCL member name.
Variable Length
In z/OS, for variable length a comma separates value output, the DDname must be
DQOUT. You must also specify tape or disk in a subsequent JCL statement.
In z/VSE, the DLBL name must be DQOUTD. The dftname used for tape is DQOUTT, but an unlabeled tape is created.
Chapter 39: Using the Batch Export Function 433
Removing JCL Members When Deleting a User
Fixed Length
For fixed length output in z/OS, the DDNAME must be DQFIXD.
In z/VSE, the DLBL name must be DQFIXD. The dtfname used for tape is DQFIXT, but an unlabeled tape is created.
User Action
The user requests data to be exported by specifying either: variable-length or fixed-length data records on the BATCH EXECUTION panel, or by using the EXPORT command in SIGN/ON mode in batch CA Dataquery.
Variable-Length Output
The user can also request two types of variable-length output: either DETAIL or TOTALS or both (both is supported only on the BATCH EXECUTION panel). If both types are requested, the output consists of two sets of output records, one for DETAIL and one for
TOTALS. DETAIL type formats the values of the columns in the PRINT statement of the query in the data record. TOTAL formats subtotals each time a value in a sort field changes when PRINT LINE TOTALING is requested. DETAIL is the default and can be omitted. TAPE and DISK are used only in z/VSE and are ignored for z/OS. If TAPE and
DISK are omitted for z/VSE, the defaults specified in the System Option Table are used.
No grand totals are exported.
Fixed-Length Output
Every column named in the print or display statement of a DQL query or named in the select clause of an SQL query is written to the output row, using the data type and length as on the database table from which it was retrieved.
Exception: In SQL mode, data type SQL-date will be exported as a 10-byte character,
SQL time as an 8-byte character, and SQL-timestamp as a 24-byte character.
Note: To print control breaks for SQL queries, use a REPORT DEFINITION (TOTALS and
CONTROL BREAKS).
434 Administration Guide
Removing JCL Members When Deleting a User
Batch Sign/on
In sign/on mode, you can execute more than one query per execution of DQBATCH. CA
Dataquery allows multiple EXPORT control cards.
Variable-Length Output
A sample format for multiple EXPORT control statements follows:
EXPORT 'SETNAME' TOTALS TAPE
EXPORT 'SETNAME' DETAIL TAPE
EXPORT 'SETNAME' TOTALS DISK
EXPORT 'SETNAME' DETAIL DISK
Fixed Output
For fixed output, only one EXPORT per DQBATCH execution is permitted. You may not have multiple export cards. In fixed output, 'NAME' and DETAIL may be omitted.
A sample format for an EXPORT control card follows:
EXPORT 'NAME' DETAIL DISK FIXED
EXPORT 'NAME' DETAIL TAPE FIXED
If you execute more than one EXPORT per any execution of DQBATCH, CA Dataquery writes all of the output sets to the same output sequential data set. In SIGN/ON mode you can specify the device type on the EXPORT command input card, but all exports in any execution must be to the same output data set. You can write only one output data set per one execution of DQBATCH.
Note: The job control cards used to execute DQBATCH must contain the necessary data definition statements to define the output data set for the EXPORT command.
Chapter 39: Using the Batch Export Function 435
Removing JCL Members When Deleting a User
Data Set Definition
For z/VSE, the data definition statements must define a data set of the type requested on the EXPORT command or the BATCH EXECUTION panel. In z/VSE, the type of the output data set in deferred batch is determined from the EXPDEV= parameter in the CA
Dataquery System Option Table.
For OS/MSP the type of device is determined only by the data definition statements in the JCL.
For Fixed-Length Output
The output is sequential. The record size is determined by columns being output and records are blocked with a maximum block size of 4092. The fields are output in type and length as retrieved from the database. No record descriptor word is written and no header or trailer records are written and data records do not have DATA in the first 4 bytes.
For Variable-Length Output
The output data set is a sequential file. The records are variable length, blocked format with a block size of 4096. The maximum length of any data record is 4088.
The data records are written in character format. Leading zeros in numeric fields and trailing blanks in character fields are suppressed. All blank character fields or all zero numeric fields are indicated by a comma immediately following the comma for the preceding field. Numbers containing decimal places appear with a decimal point followed by a zero for each decimal place.
Sample Record
The following table shows a sample record.
Record Descriptor Word FIELDA
Record
Type
FIELDB
Data
FIELDC
Data
436 Administration Guide
Sample EXPORT JCL
The first 4 bytes of any record contain the record descriptor word. The first field is a keyword indicating the record type which consists of:
■
Header record type containing a description of the exported data
■
Data record type containing the data values, such as character format with leading zeros suppressed in numeric fields and trailing blanks truncated in character fields
■
Trailer record type containing the total record count including the trailer and header
Every output data set contains these three record types.
The data set can be downloaded to a PC, since this is in PC file format known as CSV.
Sample EXPORT JCL
Sample z/OS JCL
The following is a sample z/OS EXPORT job:
//jobname See Preparing JCL for Batch CA Dataquery Utilities.
// EXEC PGM=DQBATCH
//STEPLIB See Preparing JCL for Batch CA Dataquery Utilities.
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=* Print Output
//SNAPER DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//DQOUT DD DSN= .... Specify according to your site standards.
//SYSIN DD * Command input
SIGN/ON dquser
FIND ALL CAI-DETAIL-REC X
PRINT ITMID-ORDID=KEY ORD-QTY SHIP-QTY UNIT-PRICE DISC-PCT ACT-DT
EXECUTE *
EXPORT 'DOCUMENT1' DETAIL
/*
//
Chapter 39: Using the Batch Export Function 437
Sample EXPORT JCL
Sample z/VSE JCL
The following is a sample z/VSE EXPORT job:
* $$ JOB ... See Preparing JCL for Batch CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// DLBL DQOUTD,'DATACOM.DQ.EXPORT',1
// EXTENT ,volser,1,0,strk,ntrks
// EXEC DQBATCH
SIGN/ON dquser
FIND ALL CAI-DETAIL-REC X
PRINT ITM-ORDID-KEY ORD-QTY SHIP-QTY UNIT-PRICE DISC-PCT ACT-DT
EXECUTE *
EXPORT 'DOCUMENT1' DETAIL
/*
/&
* $$ EOJ
438 Administration Guide
Sample Export File
Sample Export File
After printing the report, CA Dataquery exports the data as indicated in the query to the named data set. Each set of data is labeled by its set name specified in the export control card or on the BATCH EXECUTION panel. It is important that you give each set a unique name so that it can be easily located in the data set.
A sample variable length EXPORT file contents display follows:
HEADER,DOCUMENT1,DETAIL,042887,144204,RECORD,CAI-DETAIL-REC,DTL,000,
KEY,ITMID-ORDID-KEY,02,C,0010,00,N,N,005,00,N,FIELD,ORD-QTY,N,007,
00,Y,FIELD,SHIP-QTY,N,007,00,Y,FIELD,UNIT-PRICE,N,007,02,Y,
FIELD,DISC-PCT,N,003,01,Y,FIELD,ACT-DT,C,0006,00,N
DATA,"C10000 01008",2,2,29.50,.0,"991106"
DATA,"C10001 01008",4,4,21.00,.0,"991106"
DATA,"C10002 01008",6,6,14.00,.0,"991106"
DATA,"C10005 01008",2,2,66.75,.0,"991106"
DATA,"A60005 01009",1,1,219.99,.0,"991106"
DATA,"A60008 01009",2,2,179.99,.0,"991106"
DATA,"A70000 01009",4,4,99.99,.0,"991106"
DATA,"H10000 01010",2,2,59.99,.0,"991106"
DATA,"H10002 01010",10,10,4.99,.0,"991106"
DATA,"H20001 01010",3,3,21.99,.0,"991106"
DATA,"H20002 01010",5,5,39.99,.0,"991106"
DATA,"H20004 01010",2,2,21.99,.0,"991106"
DATA,"H20006 01010",5,5,12.99,.0,"991106"
DATA,"H30000 01010",4,4,124.99,.0,"991106"
DATA,"H30002 01010",6,6,69.99,.0,"991106"
DATA,"H30003 01010",3,3,59.99,.0,"991106"
DATA,"H40000 01010",15,15,15.99,.0,"991106"
DATA,"H70001 01010",100,100,38.99,.0,"991106"
DATA,"H80002 01010",20,20,73.99,.0,"991106"
DATA,"H80004 01010",10,10,23.99,.0,"991106"
TRAILER,0022
Chapter 39: Using the Batch Export Function 439
Sample Export File
Header Format for Variable-Length Output
The following is the format of the header statement from the sample z/OS EXPORT report:
HEADER FIELD FIELD DESCRIPTION
Header Describes the data records
SET-NAME Name of the output set
SET-TYPE DETAIL or TOTALS
FIND DATE Date that data was found
FIND TIME Time that data was found
Descriptors Name of the records, keys or fields
Record Record descriptor follows
RECORD-NAME Name of the record
DB-NAME 3-character DB file name
DB ID Database ID for the file
Key Key descriptor follows
KEY-NAME Name of a key whose value was exported
COUNT Number of the fields in the key
*DATATYPE Type of data exported:
C = Character field, not nullable
N = Numeric field, not nullable
K = Nullable character
M = Nullable numeric
*LENGTH Length of field if TYPE=C
or no. of digits if TYPE=N
*DECIMALS Number of decimal places if TYPE=N
or no. of zeros if TYPE=C
*SIGN Y if signed, TYPE=N default is N
(Fields marked with * repeat if KEY COUNT is greater than 1)
440 Administration Guide
Sample Export File
Field Field descriptor follows
FIELD-NAME Name of the output field
DATATYPE Type of data exported:
C=character, N=numeric
LENGTH Length of field if TYPE=C
or no. of digits if TYPE=N
DECIMALS Number of decimal places if TYPE=N
or no. of zeros if TYPE=C
SIGN Y if signed, TYPE=N default is N
FIELDS IN DATA RECORDS:
Data Indicates data values follow
DATA Comma separated values, as
described by the Header
FIELDS IN TRAILER RECORDS:
Trailer Indicates this is a trailer record
COUNT A count of total number of records
Chapter 39: Using the Batch Export Function 441
Chapter 40: Accessing Exported Data
The CA Dataquery batch export function allows the user to export the columns and keys named in the PRINT or DISPLAY statement of the query to an output table in the order specified in the query. The columns and keys named in the PRINT or DISPLAY statements of the query determine the columns in the output row. This exported data is then available for use in user-written programs. The user must be authorized for SUBMIT
ALLOWED and EXPORT ALLOWED on the User Table Maintenance panel under the administrative USERS option to be able to use the export function.
Export File Formats
CA Dataquery supports export of data in two formats:
■
Comma-separated values to a sequential file with variable-length records
■
Fixed-position fields to a sequential file with fixed-length records
Operation
CA Dataquery places the requested exported data in a sequential output file, therefore you must allocate a data set for the exported data.
The user requests that data be exported by filling in a name for the output set of data records on the Batch Execution panel, or by using the EXPORT command in Sign/On mode in batch CA Dataquery. CA Dataquery exports the data as indicated in the query to the named data set.
The user may also request two types of output, either DETAIL or TOTALS or both. If both types are requested, the output will consist of two sets of output rows, one for DETAIL and one for TOTALS. DETAIL type formats the values of the columns in the PRINT statement of the query in the data row. TOTAL prints subtotals when the data in a SORT column changes.
z/VSE Requirements
For z/VSE, the DQOPTLST option specifies whether the default is tape or disk. This default can be overridden for nondeferred jobs at submit time when the system prompts the user for the device. The user's response must match the device specified in the JCL member. Deferred jobs always take the DQOPTLST value.
Chapter 40: Accessing Exported Data 443
Comma-Separated Values
Comma-Separated Values
For this option, the output data set is a sequential file. The rows are variable length, blocked format with a block size of 4096. The maximum length of any data row is 4088.
The data rows are written in comma-separated value format, with leading zeros in numeric fields and trailing blanks in character fields being suppressed. All blank character fields and all zero numeric fields are indicated by a comma immediately following the comma for the preceding field. Each set of data is labeled by its set name specified in the EXPORT command. It is important that you give each set a unique name so that it can be easily located in the data set.
Sample Record
Following is a sample record:
Record Descriptor Word FIELDA FIELDB FIELDC
Record Data Data
Type
The first 4 bytes of any record contain the record descriptor word.
The first 2 bytes of this record descriptor word contain the length of the record, including the RDW. The first field is a keyword indicating the record type. Types used are:
■
Header record type containing a description of the exported data
■
Data record type containing the data values
■
Trailer record type containing the total record count including the trailer and header
Every output data set contains these three record types. The remaining fields are data values, separated by commas.
The data set can be downloaded to a PC, since this is in PC file format known as CSV.
444 Administration Guide
Comma-Separated Values
Procedure
When you create your JCL member for exporting data, you need to specify the name of the data set to which the export data is to be written. The JCL member can specify any device type supported by IBM QSAM (z/OS). You can specify either a tape or disk file in your JCL member.
CA Dataquery has specific requirements for the DDname in your export JCL member name. In z/OS, the DDname must be DQOUT. In z/VSE, the DLBL name must be
DQOUTD; the tape is unlabled.
In Sign/On mode, you can execute more than one query per execution of CA Dataquery
Batch. CA Dataquery allows multiple EXPORT control statements. The EXPORT statements should follow the EXECUTE statement.
EXPORT Control Statement (z/OS)
A sample format for z/OS EXPORT control statements follows:
►►─ EXPORT ─
'setname'
─┬────────────┬────────────────────────────────────────►◄
├─ DETAIL ◄ ─┤
└─ TOTALS ───┘
EXPORT Control Statement (z/VSE)
A sample format for z/VSE EXPORT control statements follows:
►►─ EXPORT ─ 'setname' ─┬─────────────────────┬─┬─ DISK ─┬────────────────────►◄
└─ DETAIL ◄ ─ TOTALS ─┘ └─ TAPE ─┘
The EXPORT command may specify two types of output, either DETAIL or TOTALS.
DETAIL type formats the values of the columns in the PRINT statement of the query in the data row. TOTAL prints subtotals when the data in a SORT column changes.
Note: DETAIL is the default and can be omitted.
TAPE and DISK are used only in z/VSE and are ignored for z/OS. In z/VSE, you must specify either TAPE or DISK to indicate the output media.
If you execute more than one EXPORT per any execution of CA Dataquery, batch writes all of the output sets to the same output sequential data set. In Sign/On mode you can specify the device type on the EXPORT command input statement, but all exports in any execution must be to the same output data set. You can write only one output data set per one execution of DQBATCH.
Note: The job control statements used to execute DQBATCH must contain the necessary data definition statements to define the output data set for the EXPORT command.
The type of device is determined only by the data definition statements in the JCL.
Chapter 40: Accessing Exported Data 445
Comma-Separated Values
Sample JCL (Comma-Separated Values)
Sample z/OS JCL
The following is a sample z/OS EXPORT job:
//jobname See the note above and Preparing JCL for Batch CA Dataquery Utilities.
// EXEC PGM=DQBATCH
//STEPLIB See the note above and Preparing JCL for Batch CA Dataquery Utilities.
//SYSPRINT DD SYSOUT=* Print Output
//SYSUDUMP DD SYSOUT=*
//SNAPER DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//DQOUT DD DSN= ... Specify according to your site standards
//SYSIN DD * Command input
SIGN/ON DQUSER
FIND ALL CA-DETAIL-REC X
PRINT ITMID-ORDID=KEY ORD-QTY SHIP-QTY UNIT-PRICE DISC-PCT ACT-DT
EXECUTE *
EXPORT 'DOCUMENT1' DETAIL
/*
//
446 Administration Guide
Comma-Separated Values
Sample z/VSE JCL
The following is a sample z/VSE EXPORT job to output to a data set on disk:
* $$ JOB ... See the note on the previous page and Preparing JCL for Batch
CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// DLBL DQOUTD,'datacom.dq.export',99/365
// EXTENT ,VSEDT4
// EXEC DQBATCH
SIGN/ON DQUSER
FIND ALL CA-DETAIL-REC X
PRINT ITMID-ORDID-KEY ORD-QTY SHIP-QTY UNIT-PRICE DISC-PCT ACT-DT
EXECUTE *
EXPORT 'DOCUMENT1' DETAIL DISK
/*
/&
* $$ EOJ
The following is a sample z/VSE EXPORT job to output to a data set on tape:
* $$ JOB ... See the note on the previous page and Preparing JCL for Batch
CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// EXEC DQBATCH
SIGN/ON DQUSER
FIND ALL CA-DETAIL-REC X
PRINT ITMID-ORDID-KEY ORD-QTY SHIP-QTY UNIT-PRICE DISC-PCT ACT-DT
EXECUTE *
EXPORT 'DOCUMENT1' DETAIL TAPE
/*
/&
* $$ EOJ
Chapter 40: Accessing Exported Data 447
Fixed-Format Records
Fixed-Format Records
For this option, the output data set is a sequential file. The rows are fixed length with a record length equal to the length of detail records generated by the query to be output.
CA Dataquery writes the data as returned, one row per output record and does not export totals, header, or trailer records. The output columns have the same data types and lengths as the columns in the CA Datacom/DB table from which they were retrieved. Nullable fields are preceded with a 1-byte null indicator:
blank
Indicates that the field is not null.
N
Indicates that the field has a null value.
Only one set of data is available in the fixed record formatted file. CA Dataquery overwrites any data in the file when it exports data. Therefore, if you are doing several successive batch exports, specify a different data set in the job stream for each export.
Procedure
When you create your JCL member for exporting data, you need to specify the name of the data set to which the export data is to be written. The JCL member can specify any device type supported by IBM QSAM (z/OS). You can specify either a tape or disk file in your JCL member.
CA Dataquery has specific requirements for the DDname in your export JCL member name. In z/OS, the DDname must be DQFIXD. In z/VSE, the DLBL must be DQFIXD. specifies the devices as tape or disk.
When exporting fixed-format records, you can execute only one query per execution of
CA Dataquery Batch. CA Dataquery allows only one EXPORT FIXED control statement per execution. The EXPORT FIXED statement should follow the EXECUTE statement.
EXPORT Control Statement (z/OS)
A sample format for z/OS EXPORT FIXED control statement follows:
►►─ EXPORT ─ 'setname' ─ FIXED ───────────────────────────────────────────────►◄
EXPORT Control Statement (z/VSE)
A sample format for z/VSE EXPORT FIXED control statement follows:
►►─ EXPORT ─ 'setname' ─ FIXED ─┬─ DISK ─┬────────────────────────────────────►◄
└─ TAPE ─┘
448 Administration Guide
Fixed-Format Records
TAPE and DISK are used only in z/VSE and are ignored for z/OS. In z/VSE, you must specify either TAPE or DISK to indicate the output media.
Note: The job control statements used to execute DQBATCH must contain the necessary data definition statements to define the output data set for the EXPORT command.
The type of device is determined only by the data definition statements in the JCL.
Sample JCL (Fixed-Format Records)
Sample z/OS JCL
The following is a sample z/OS EXPORT job:
//jobname See the note above and Preparing JCL for Batch CA Dataquery Utilities.
// EXEC PGM=DQBATCH
//STEPLIB See the note above and Preparing JCL for Batch CA Dataquery Utilities.
//SYSPRINT DD SYSOUT=* Print Output
//SYSUDUMP DD SYSOUT=*
//SNAPER DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//DQFIXD DD DSN= .... Specify according to your site standards.
//SYSIN DD * Command input
SIGN/ON DQUSER
FIND ALL CA-DETAIL-REC X
PRINT ITMID-ORDID=KEY ORD-QTY SHIP-QTY UNIT-PRICE DISC-PCT ACT-DT
EXECUTE *
EXPORT 'DOCUMENT1' FIXED
/*
//
Chapter 40: Accessing Exported Data 449
Fixed-Format Records
Sample z/VSE JCL
The following is a sample z/VSE EXPORT job to output to a data set on disk:
* $$ JOB ... See the note on the previous page and Preparing JCL for Batch
CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// DLBL DQFIXD,'datacom.dq.export',99/365
// EXTENT ,VSEDT4
// EXEC DQBATCH
SIGN/ON DQUSER
FIND ALL CA-DETAIL-REC X
PRINT ITMID-ORDID-KEY ORD-QTY SHIP-QTY UNIT-PRICE DISC-PCT ACT-DT
EXECUTE *
EXPORT 'DOCUMENT1' FIXED DISK
/*
/&
* $$ EOJ
450 Administration Guide
Fixed-Format Records
The following is a sample z/VSE EXPORT job to output to a data set on tape:
* $$ JOB ... See the note on the previous page and Preparing JCL for Batch
CA Dataquery Utilities.
* $$ LST ...
// JOB name
// EXEC PROC=procname Whether you use PROCs or LIBDEFs, see Preparing JCL for Batch
CA Dataquery Utilities.
// ASSIGN SYS011,X'...'
// EXEC DQBATCH
SIGN/ON DQUSER
FIND ALL CA-DETAIL-REC X
PRINT ITMID-ORDID-KEY ORD-QTY SHIP-QTY UNIT-PRICE DISC-PCT ACT-DT
EXECUTE *
EXPORT 'DOCUMENT1' FIXED TAPE
/*
/&
* $$ EOJ
Chapter 40: Accessing Exported Data 451
Chapter 41: Extracting Data (FEX)
Data collected by a query and stored using the EXTRACT command can be accessed by user application programs. By calling the Extract Interface (FEX), these user programs can access the extract data table created by the EXTRACT command. FEX handles both batch and online extracts.
Extracted data is stored in the DQF. Unlike Saved sets and Found sets, an extract extracts and stores data not pointers. Thus an extract can require a significant amount of space. If you plan to use the EXTRACT command, you should review the size of your
DQF table. If you need to enlarge it, see
DQF: Found Table
Operation
By calling the Extract Interface (FEX), these user programs can access the extract data table created by the EXTRACT command. The Extract Interface handles both batch and online applications. In batch, it can be used by CA Datacom/DB Reporting Facility to create reports or sequential output tables. See CA Datacom/DB Reporting Facility documentation for further information on these reporting capabilities.
Procedure
Use a standard CALL statement to communicate with FEX. For each call, provide a place for the FEX to return a code set to indicate the result. Each call with a return code of zero puts the next logical row of the EXTRACT member in the data area you provide. The sequence is specified by the SORT statement of the original query. All six parameters are required and must be specified.
The format of the call is as follows:
COBOL
CALL 'DQFEXPR' USING parm1 parm2 ... parm6
FORTRAN
CALL DQFEXPR (parm1,parm2, ... parm6)
Assembler
PL/I
CALL DQFEXPR,(parm1,parm2, ... parm6)
CALL DQFEXPR,(parm1,parm2, ...parm6)
Chapter 41: Extracting Data (FEX) 453
Fixed-Format Records
Parameters for FEX
The six parameters you must provide to the FEX are as follows:
WORK AREA
An 1100-byte area reserved for use by the FEX. Your program should initialize this area to blanks or binary zeros prior to the first request for an EXTRACT member, or when changing from one member to another before EOF is encountered on the first member. The program must not modify the work area between requests for the
same member.
Set up the work area in working storage or in the linkage section of the program on a fullword boundary (a 01-level field for COBOL). If the program is online and reentrant, define the work area in a task-related storage area described in the program's linkage section.
MEMBER NAME
Names the eight-character field containing the member name of the EXTRACT member being accessed.
OPERATOR ID
Names the 32-character signon ID of the user who created the EXTRACT member being accessed.
PASSWORD
Refers to the nine-character password specified in the EXTRACT command. If a password was not specified, provide a blank field.
ROW LENGTH
Refers to a two-byte binary field containing the length of the logical rows in the
EXTRACT member. See the section in this chapter on logical row format.
DATA AREA
Names the data area into which the FEX is to return EXTRACT member rows. You are responsible for correctly defining data values within this area. To avoid unpredictable results, ensure that this area is large enough to accept the logical rows passed from the FEX.
454 Administration Guide
Fixed-Format Records
Return Codes
When the call to the FEX is completed, a code is returned to the calling program to indicate the results of the request. The program must interrogate the code each time to determine whether to continue. The return code is a two-byte character field located in the first two positions of the work area provided as the first parameter of the call.
Following are FEX return codes:
0
Good return - the data requested was successfully returned to the program.
4
Logical end of file - no more data exists for the requested EXTRACT member.
8
The requested EXTRACT member does not exist or the user ID (or password) is invalid.
12
An error was returned from CA Datacom/DB during a request to read the DQF
(Found Table). The second two positions (bytes 3-4) of the work area contain the CA
Datacom/DB return code.
16
Length error - the actual length of a logical row for the EXTRACT member specified exceeds the row length specified in the input parameter list.
Logical Row Format
EXTRACT member data rows are formatted as follows:
■
The data fields are concatenated, end to end, so that they are sequenced just as they were in the PRINT or DISPLAY statement of the original query.
■
Each data field in the EXTRACT member row appears as it originally appeared on the database. The format of each data field should always conform to the CA Datacom
Datadictionary definition for the CA Datacom/DB files from which the data field was extracted.
Chapter 41: Extracting Data (FEX) 455
Fixed-Format Records
■
■
Each exported field which is nullable on the database is preceded by a 1-byte null indicator. In the EXTRACT row, this null indicator is blank if the field is not null and N if the field is null. The field data immediately follows the null indicator. If the null indicator is N, you should ignore any data in the field.
Data fields computed from a SET statement appear in the EXTRACT member row as
8-byte signed, packed fields, unless the DQOPTLST parameter XTRSETL=16 is specified. If it is, they are 16-byte signed, packed fields.
Note: If a SET result field would normally have an error code printed during the report due to invalid data or some other problem or the result contains more than
15 decimal digits and XTRSETL=16 was not specified in DQOPTLST, the FEX defaults the field to zero, a SET result field which is a result of a calculation on a nullable field is also nullable and is preceded by a 1-byte null indicator in the row output by
FEX.
Implementing the FEX Online
To implement an online version of the FEX, write and link-edit the program just as you would any other CA Datacom/DB online program, with these additions:
■
Ensure that the DQF table is specified as one of the tables to be accessed in the CA
Datacom/DB User Requirements Table associated with the online application under which this program is to execute. The following macro statements must be added:
URT TITLE 'DQURT - DQFEXPR'
DBURINF X
OPEN=DB X
URTABLE=ASM, X
BACKSPT=YES *other user options may be coded*
DBURSTR X
ABEND=YES
DBURTBL X
TBLNAM=DQF, X
UPDATE=NO, X
SYNONYM=NO, X
DBID=nnnnn
DBUREND
DBID=nnnnn is the database ID of the DQF (Found Table) usually 00003.
■
The calling program must be linked with DBCSVPR and DQFEXPR as shown in the following link-edit control statements:
INCLUDE user program
INCLUDE DBCSVPR
INCLUDE DQFEXPR
ENTRY user program
456 Administration Guide
Fixed-Format Records
Implementing the FEX in Batch
To implement a batch version, write and link-edit the program as you would any other batch CA Datacom/DB program, with these additions:
■
Specify the DQF in the CA Datacom/DB User Requirements Table as one of the tables to be accessed. Add the following macro statements:
URT TITLE 'DQURT - DQFEXPR'
DBURINF X
OPEN=DB X
URTABLE=ASM, X
BACKSPT=YES *other user options may be coded*
DBURSTR X
ABEND=YES
DBURTBL X
TBLNAM=DQF, X
UPDATE=NO, X
SYNONYM=NO, X
DBID=nnnnn
DBUREND
DBID=nnnnn is the database ID of the DQF (Found Table) usually 00003.
■
■
The program must be linked with the User Requirements Table and DQFEXPR as shown in the following link-edit control statements:
INCLUDE user program
INCLUDE user requirements table
INCLUDE DQFEXPR
ENTRY BEGIN
Under z/OS and z/VSE, the execution JCL for the program must include DD statements for the DQF and for the CA Datacom/DB Directory (CXX) and Index Area
(IXX) unless the dynamic allocation feature of CA Datacom/DB is installed.
Note: For additional information about installing or using CA Datacom/DB programs, see the CA Datacom/DB Programming" Guide and the CA Datacom/DB Database and
System Administration Guide.
Chapter 41: Extracting Data (FEX) 457
Chapter 42: Programming User Exits
CA Dataquery provides user exits to allow you to establish routines that will occur at predetermined points in the CA Dataquery processing.
Prerequisites to Using User Exits
To make any of the exits presented in this chapter available for use, you must:
1. Write the user exit according to the directions presented in this chapter.
2. Take one of the following actions:
■ Code the appropriate System Option Table DQOPTLST parameters from the following list according to the directions provided in this document.
Batch Submit Exit SUBEXIT=
Query Validation Exit
Signon/off Exit Batch
Signon/off Exit Online
VALEXIT=
SXBEXIT=
SONEXIT=
User-Defined Functions Exit
Data Stream Input Exit
Data Stream Output Exit
DBID Exit Batch
UDFMOD=
DSIEXIT=
DSOEXIT=
CDBXITB=
DBID Exit Online
Data Exit
Online Output Exit
Batch Output Exit
Batch Line Printer Exit
CDBXITO=
DATAXIT=
OUTXITO=
OUTXITB=
BTCHLPX=
■
Link the exit module with the DQSYSTBL module:
Batch Line Printer Exit
Network Print Exit
BATCHLP
DQEXIT
Chapter 42: Programming User Exits 459
Fixed-Format Records
Available User Exits
Name of
User Exit
Description
Batch Line
Printer Exit
Batch
Submit Exit
DBID Exit
Location of
Details
This exit enables you to control output in DQBATCH.
This exit must do all output to the system line printer. CA Dataquery passes the length and address of each line to be printed, and a top of page indicator to the user-written program. This allows nonstandard control codes to be inserted into the print lines to accommodate special printers.
Chapter 47,
Batch Line
Printer Exit
page 475)"
This exit enables you to inspect and modify the JCL used for batch query execution initiated through the online submit function. CA Dataquery passes the user name, user password, and the JCL member that is to be used to submit the query to the user-written program when a query is submitted for execution using the Batch Execution panel. This exit provides you with the opportunity to validate the user or modify the JCL member.
CICS:
Batch Submit
Exit in CICS
page 473)
In batch or online, when a query is validated, this exit is called once for each table named in the query and has the opportunity to change the CA
Datacom/DB ID of any table.
Chapter 49,
DBID Exit
page 479)"
Provides CA Dataquery with the correct CA
Datacom/DB identifier prior to execution of a DQL
Language query. When query validation is complete, CA Dataquery gives control to this exit and passes the following to the exit:
■
■
■
CA Datacom Datadictionary entity-name
CA Dataquery user identification
CA Datacom/DB table name
■
CA Datacom/DB database ID
The exit can change the CA Datacom/DB table name causing CA Dataquery to update its processing control blocks to reflect the new information. This process occurs one time for every table for each query.
460 Administration Guide
Fixed-Format Records
Name of
User Exit
Data Exit
Data Stream
Input Exit
Data Stream
Output Exit
Network
Printer Exit
Output Exit
Query
Validation
Exit
Description Location of
Details
This exit is called every time CA Dataquery is ready to include a row in the found set of a query. It can reject the row, preventing its inclusion in the set. In online and batch, passes user's name, 3-character
CA Datacom/DB name for the table being accessed,
DBID, and the row itself. The exit may examine the row and return an indicator as to whether the user should have access to the row.
Chapter 50,
Data Exit
page 481)"
The Data Stream Input exit receives control when an input data stream is received by CA Dataquery from a terminal. It can examine and modify the data stream.
Chapter 51,
Data Stream
Input Exit
page 483)"
The exit can inspect and modify the data stream in place but must not change its location or length.
The Data Stream Output exit receives control just before CA Dataquery writes a data stream to a terminal. It can inspect and modify the data stream.
Chapter 52,
Data Stream
Output Exit
(see page 485)"
This exit enables you to inspect and modify the print lines produced by an online query whose output destination is a network printer. CA
Dataquery passes the address where the exit should build the data stream, the address of the image where the data stream should be built, the address of a flag that indicates whether a page ejection should occur and the number of columns per row in the data stream image to the user-written program.
This allows nonstandard control codes to be inserted into the print lines to accommodate special printers.
Chapter 53,
Network
Printer Exit
page 487)"
This exit allows you to access individual rows of output data before the output is printed.
Chapter 48,
Output Exit
(see page 477)"
This exit enables you to make changes to a query before the query is executed. CA Dataquery passes the query and user name that has been submitted for execution to the user-written program. The program may limit the number of rows searched by a query on a particular CA Datacom/DB table. This is an effective technique for enforcing site standards on queries.
Chapter 43,
Query
Validation Exit
(see page 463)"
Chapter 42: Programming User Exits 461
Fixed-Format Records
Name of
User Exit
Signon/off
Exit
User-Defined
Functions
Exit
Description
In batch and online, passes the user ID, password, and time of signon to the user-written program.
The program can use this data to further validate the user, to track how frequently the user is accessing CA Dataquery, to enhance security, and so on. This exit must be used if CA Dataquery is to communicate with other security packages.
This exit enables you to manipulate the data resulting from a query execution by performing mathematical procedures in the form of SET statements. CA Dataquery passes the retrieved data resulting from a query execution to a user-written program.
Location of
Details
Chapter 45,
Sign-on/off
Exit
page 469)"
Chapter 44,
User-Defined
Functions Exit
(see page 465)"
462 Administration Guide
Chapter 43: Query Validation Exit
CA Dataquery supports a user Query Validation Exit which allows you to enforce site standards. You can code the exit to the following:
■
Analyze the contents of a query
■
Modify the query
■
Continue processing as usual
■
Reject the query
Operation
A query can be rejected by your Query Validation Exit with a standard error message or a special error code to be used in conjunction with panels 990 through 999 as described in the information about register 15 below. (See DQOPTLST Parameters for more information about the VALEXIT= parameter of the System Option Table.)
Procedure
CA Dataquery provides ten panels that can be used to document errors that may result from tailoring your system. If you set return code 990-999, CA Dataquery will give error panels 990-999. You can create error messages.
Code this exit in the Assembler language. Make it reentrant or reusable. It must be linked to the CA Dataquery load library and have a PPT entry if under CICS.
Monitor calls and I/O requests cannot be issued by the Query Validation Exit.
When writing the exit, note the following register conventions:
Register 1
Points to a parameter list consisting of the following entries (in order from the beginning of the list):
■
Address of an area that contains the query to be edited. The length is determined from the option table. The length is the value of the QPAGES= parameter times 24.
■
Address of an area, 32 characters long, that contains the user's signon ID, left justified and blank filled on the right.
■
Address of a 256-byte area (doubleword aligned) to be used as needed by the exit. The area is not initialized on entry.
Chapter 43: Query Validation Exit 463
Fixed-Format Records
Register 13
Contains the address of a register SAVE area which you must use to save and restore CA Dataquery's registers according to standard linkage conventions.
Register 14
Contains the return address within CA Dataquery.
Register 15
Contains the address of the entry point of the exit.
Prior to returning control to CA Dataquery, the exit must place one of the following return codes in register 15.
■
0 signifies a normal return.
■
■
The exit passes back to CA Dataquery the query pointed at by the first entry of the parameter list. (The query may have been modified as specified by the exit.)
990—999 or any nonzero code signifies an error return.
CA Dataquery issues user written error panels based on the decimal value in register 15 (990—999). The system suspends further edit processing for the query.
You can use special error codes 990 through 999 in conjunction with panels 990 through 999. Panels 990—999 can be customized with error messages of your own choosing.
Any nonzero return code other than 990—999 suspends processing with error message DQ048E, with return code displayed.
DBID Exit
(see page 479) for an explanation of return codes and their meanings.
Implementation
To implement the Query Validation Exit:
1. Code the VALEXIT= parameter in the DQOPTLST macro and reassemble the CA
Dataquery System Option Table. (See :spotref refid=valex for more information about the VALEXIT= parameter of the System Option Table.)
2. If running under CICS/VS: a. Assemble and link edit the user exit into the regular CICS program library under the name specified in the VALEXIT= parameter. b. Add an entry for the exit to the CICS PPT.
For samples, see the CA Datacom website.
464 Administration Guide
Chapter 44: User-Defined Functions Exit
CA Dataquery supports a User-Defined Functions (UDF) Exit for DQL Mode which allows you to provide CA Dataquery users with special mathematical functions, such as exponentiation or extraction of roots. See DQOPTLST Parameters for details about the
UDFMOD= parameter of the System Option Table.
Operation
CA Dataquery gives the User-Defined Functions Exit control when it recognizes the UDF identifier during SET statement processing. (The UDF identifier is UDF and is located in a
SET statement, such as, SET A =UDF(7,X,Y).)
Procedure
This exit must be coded in Assembler language and should be reentrant or reusable. This exit cannot issue monitor calls and I/O requests. When you write this exit, make certain it contains processing routines for every mathematical function you anticipate needing.
A maximum of 255 are allowed.
Following the UDF identifier is a parameter list, enclosed within parentheses, that provides details about the function wanted and the operands to use.
Upon entry to the User-Defined Functions Exit the following is provided to the exit:
Register 1
Points to a seven-word parameter list consisting of the following entries (in order from the beginning of the list):
Address of a 1-byte binary function code indicating the function requested.
A 1-byte binary count of the input arguments specified by the UDF function list in the SET statement, followed by a 3-byte address of a list of the argument values.
The argument values are each 9-bytes long and consist of a high-order byte containing a binary count of the number of decimal places contained in the value and an 8-byte packed decimal field containing the argument. If a query has multiple
SET statements, a maximum of eight input arguments can be passed to the exit. Up to twelve parameters can be passed when only one SET statement is specified.
Address of an area where the result of the function is to be stored. This area consists of a 1-byte binary count of the number of decimal places in the result followed by a packed decimal field containing the result.
Address of a 172-byte area (doubleword aligned) to be used as needed by the exit.
The area is not initialized on entry. The high-order byte of this word contains the length of this area in binary.
Chapter 44: User-Defined Functions Exit 465
Fixed-Format Records
Note: The following three parameters have been added to support numbers having more than 15 decimal digits. Version 8.0 and above supports up to 18 digits, while prior version supported only fifteen. These new parameters need only be used when arguments or results might exceed 15 digits. Otherwise, UDF exits coded to use the four-word parameter list (previous versions) will continue to function as always.
A 4-byte address of a list of the argument values. The argument values are each 17 bytes long and consist of a high-order byte containing a binary count of the number of decimal places contained in the value and a 16-byte packed decimal field containing the argument. The high-order byte of this parameter does not contain the argument count.
A 4-byte address of a 1-byte overflow indicator. This indicator is set to a character Y if any of the arguments contains more than 15 decimal digits. In this case, the exit should use the argument list containing 16-byte packed decimal values, provide a
16-byte packed decimal result, and set the result length to '16.' Otherwise error 18 results when the value is formatted in a report, for example, ***E18***.
A 4-byte address of a 2-character result length indicator. This indicator is preset to
08 and must be changed to 16 by the exit when a 16-byte result is returned. A
16-byte result is always permitted. It is necessary to avoid the error 18 on the report when any of the arguments has more than 15 digits. When the length indicator is not changed to 16, the packed result field addressed by PARM word 3 is expected to be 8 bytes long, as was assumed in prior versions of CA Dataquery. This allows UDF exits coded before 18-digit support was implemented to continue functioning unchanged.
Register 13
Contains the address of a register SAVE area which you must use to save and restore CA Dataquery's registers according to standard linkage conventions.
Register 14
Contains the return address within CA Dataquery.
466 Administration Guide
Fixed-Format Records
Register 15
Contains the address of the entry point of the exit.
Prior to returning control to CA Dataquery, the exit must place one of the following return codes in register 15:
0
Signifies a normal return. No errors were found. The result has been stored in the area pointed at by word three of the parameter list.
80—99
If your exit has detected any type of error while performing a function on the data, an error code can be returned to CA Dataquery. Register 15 should contain a binary error number within the range of 80—99 (decimal). CA
Dataquery will place a special error flag in the pertinent column of the output report in the following form, where nn indicates the error code:
**Enn**
Implementation
To implement the User-Defined Functions Exit:
1. Code UDFMOD= parameter in the option table's DQOPTLST macro with an
8-character name, reassemble, and link the CA Dataquery System Option Table. See
DQOPTLST Parameters for details about the UDFMOD= parameter of the System
Option Table.
2. If running under CICS/VS: a. Assemble and link edit the user exit into the regular CICS program library under the name specified in the DQOPTLST macro's UDFMOD= parameter. b. Add an entry for the exit to the CICS PPT.
For samples, see the CA Datacom website.
Chapter 44: User-Defined Functions Exit 467
Chapter 45: Sign-on/off Exit
Two parameters in the DQOPTLST macro are related to Signon/off Exits. SONEXIT= is used in online applications. SXBEXIT= is used in batch applications.
Online Signon/off Exit
In online, the name you specify in the SONEXIT= parameter is the name of the exit you want to call at signon and signoff time. See DQOPTLST Parameters for information about the valid entries and default value of the SONEXIT= parameter.
A user-written Signon/off Exit for CICS must be a command or macro level CICS program. Information is passed to the user exit in an 80-byte CICS temporary storage record. The user exit reads the temporary storage record. The following is the format of the 8-character name for the temporary storage record:
DQnnnnSO where nnnn is the CICS terminal ID.
The information passed consists of the following 80-byte area as follows:
USRFUNC DS CL3 Function: SON=signon
SOF=signoff
EOJ= end of job
USROPID DS CL32 User's DQ user ID
USRPASS DS CL9 User's DQ password
USRDATE DS CL8 Date signed-on on(off), MM/DD/YY
USRSOTIM DS XL4 Signon time in seconds
USRSFTIM DS XL4 Signoff (or EOJ) time in seconds
USRRETCD DS X Return code: 0 if signon valid
<>0 to deny signon
DS CL(80-(*-USRDSECT)) RFFU
Chapter 45: Sign-on/off Exit 469
Batch Signon/off Exit
Batch Signon/off Exit
In batch, the name you specify in the SXBEXIT= parameter is the name of the exit you want DQBATCH to call at signon and signoff time. See DQOPTLST Parameters for information about the valid entries and default value of the SXBEXIT= parameter.
Upon entry to the Batch Signon/off Exit:
Register 1
A one word parameter list that is the address of an 80-byte parameter area formatted as follows:
USRFUNC DS CL3 Function: SON=signon
SOF=signoff
EOJ=end of job
USROPID DS CL32 User's DQ user ID
USRPASS DS CL9 User's DQ password
USRDATE DS CL8 Date signed on(off), MM/DD/YY
USRSOTIM DS XL4 Signon time in seconds
USRSFTIM DS XL4 Signoff (or EOJ) time in seconds
USRRETCD DS X Return code: 0 if signon valid
<>0 to deny signon
DS CL(80-*-USRDSECT) FFU
Register 13
Contains the address of a register SAVE area which you must use to save and restore CA Dataquery's registers according to standard linkage conventions. The exit saves the calling program's registers at offset 12 from the address in register
13.
Register 14
Contains the return address within CA Dataquery.
Register 15
Contains the address of the entry point of the exit.
470 Administration Guide
Batch Signon/off Exit
CA Dataquery Batch calls the user Signon/off Exit one time for every signon statement in signon mode. If there is only one signon statement, the exit is called one time for signon, one time for signoff, and one time for end of job. For multiple signon statements, the exit is called one time for signon and one time for signoff for every signon statement, and one additional time for end of job.
For jobs submitted from online DQ by the SUBMIT function, processing is the same as for one signon statement. Deferred batch is treated as multiple signon statements if there are multiple jobs ready to be run.
Signon can be denied by the user exit by putting any nonzero return code in the parameter field USRRETCD. If signon is denied, the query that was submitted will not be executed. The return code in USRRETCD is ignored for all functions except signon.
Sample
For samples, see the CA Datacom website.
Chapter 45: Sign-on/off Exit 471
Chapter 46: Batch Submit Exit
The Batch Submit Exit allows you to examine and modify JCL/EXEC statements before they are submitted for batch execution. See DQOPTLST Parameters for details about the
SUBEXIT= parameter of the System Option Table.
Batch Submit Exit in CICS
Operation
If you use a Batch Submit Exit, CA Dataquery invokes your user-written Batch Submit
Exit program whenever a job stream is submitted to the system. For CICS, this user exit must be a command-level or macro-level CICS program. Information is passed to the user exit in an 80-byte CICS temporary storage record. The user exit reads the temporary storage record. The following is the format for the 8-character name of the temporary storage record:
DQnnnnSX where nnnn is the CICS terminal ID.
The information passed consists of the 80-byte area as follows:
USRDSECT DSECT User Batch Submit Exit Parameter DSECT
USRCURL DS F Number of Lines of JCL
USRMAXL DS F Maximum Number of Lines Allowed
USRRETCD DS F Return Code to CA Dataquery
USRJCLAD DS F Address of JCL
USRNAME DS CL32 Name of Submitting User
USRPASS DS CL9 User's Password (encrypted)
USREXPNM DS CL15 Name of export set, if any
USROTEXT DS XL4 Address of query text
USREXPTP DS CL1 Type (V-Variable, F-Fixed, Blank-Not Export)
DS CL(80-(*-USRDSECT))
Chapter 46: Batch Submit Exit 473
Batch Submit Exit in CICS
Procedure
Use the SUBEXIT= parameter in the DQOPTLST macro to specify a name for an exit called by the submit processor before the JCL for a batch job is submitted to the internal reader. If you specify blanks for SUBEXIT=, it means you want no exit. Blanks is the default value.
The user exit can update the JCL in place as needed. The exit can also do any CICS monitor calls except that it cannot do a write to the terminal or create a transaction boundary. After performing any functions required, the exit needs to:
1. Place a return code in the USRRETCD field of the temporary storage record.
2. Update the temporary storage record.
3. Return control to CA Dataquery.
The updated JCL is at the address passed to the exit in the USRJCLAD field. Any return code except zero causes cancellation of the job submission.
Sample
For samples, see the CA Datacom website.
474 Administration Guide
Chapter 47: Batch Line Printer Exit
Use the Batch Line Printer Exit if you want to control output yourself instead of allowing
CA Dataquery Batch to write to SYSPRINT or SYSLST.
Operation
The module that does the output to SYSPRINT calls BATCHLP instead of writing to
SYSPRINT.
On return, the contents of all registers except 15 are restored to what they contained before BATCHLP was called. Register 15 contains a return code on return. A zero return code indicates successful completion. A nonzero return code causes CA Dataquery to abend because no output can be done.
Procedure
Call the Batch Line Printer Exit by linking a module named BATCHLP (or having an entry point named BATCHLP) with the CA Dataquery module DQSYSTBL. The DQSYSTBL is assembled and linked with a WXTRN for BATCHLP. The WXTRN is resolved if BATCHLP is linked with DQSYSTBL.
Alternately, the exit may be linked as a separate load module. Specify the 1- to
8-character name of the module in the BTCHLPX= parameter of DQOPTLST. Then reassemble the module DQSYSTBL.
Your printer exit must do all the output for the entire execution.
When the exit is called, registers are used as follows:
Register 1
Address of the parmeter list as follows:
Word1=
00000014 (20) if this is an output line
00000020 (32) if this is close (EOJ)
Word2=
AL1(length of line)
AL3(address of line)
Word3=
Address of a 1-byte top of page indicator.
If Bit 2 (X'20) is on, top of page is requested.
Chapter 47: Batch Line Printer Exit 475
Batch Submit Exit in CICS
Register 13
Contains the address of a register SAVE area which the exit must use to save and restore the CA Dataquery registers according to standard linkage conventions.
Register 14
Contains the return address within CA Dataquery.
Register 15
Contains the address of the exit's entry point.
476 Administration Guide
Chapter 48: Output Exit
The Output exit can be invoked in either batch or online CA Dataquery. This exit allows users to access individual rows of output before printing the data on the screen or page.
To access a data stream (screen or page image), see
Data Stream Output Exit
page 485). For details about the OUTXITO= and OUTXITB= parameters of the System
Option Table, see DQOPTLST Parameters.
Online Output Exit
In online, the name you specify in the OUTXITO= parameter is the name of the exit you want to call just after a row is read from CA Datacom/DB. Only those rows meeting selection criteria are available to this exit. See DQOPTLST Parameters for information about the valid entries and default value of the OUTXITO= parameter.
A user-written Output Exit for CICS must be a command-level or macro-level CICS program. Information is passed to the user exit in an 80-byte CICS temporary storage record. The user exit reads the temporary storage record. The following is the format for the 8-character name of the temporary storage record:
DQnnnnSO where nnnn is the CICS terminal ID.
For TSO, this information is provided in the batch interface.
The information passed consists of the following 80-byte area:
TSURECD DS 0CL80
TSURECDA DS F USER RECORD ADDRESS
TSOPID DS CL32 OPERATOR ID
TSDDREC DS CL32 DD RECORD NAME
TSTBL DS CL3 3 BYTE TABLE NAME
TSDBID DS CL2 2 BYTE HEX DBID
TSFILL DS CL7 AVAILABLE
Chapter 48: Output Exit 477
Batch Submit Exit in CICS
Batch Output Exit
In batch, the name you specify in the OUTXITB= parameter is the name of the exit you want DQBATCH to call just after a row is read from CA Datacom/DB. See DQOPTLST
Parameters for information about the valid entries and default value of the OUTXITB= parameter.
Upon entry to the Batch Output Exit:
Register 1
A one word parameter list that is the address of an 80-byte parameter area formatted as follows:
TSURECD DS 0CL80
TSURECDA DS F USER RECORD ADDRESS
TSOPID DS CL32 OPERATOR ID
TSDDREC DS CL32 DD RECORD NAME
TSTBL DS CL3 3-BYTE TABLE NAME
TSDBID DS CL2 2-BYTE HEX DBID
TSFILL DS CL7 AVAILABLE
Register 13
Contains the address of a register SAVE area which you must use to save and restore CA Dataquery's registers according to standard linkage conventions. The exit you name saves the calling program's registers at offset 12 from the address in register 13.
Register 14
Contains the return address within CA Dataquery.
Register 15
Contains the address of the entry point of the exit.
CA Dataquery Batch calls the user Output Exit one time for every row returned by the query. Data can be changed by modifying the row pointed to by TSURECDA.
For samples, see the CA Datacom website. Do not change the column lengths or data
types. Numeric cannot be replaced by alphabetic data, and so on.
478 Administration Guide
Chapter 49: DBID Exit
The DBID exit can be invoked in either batch or online CA Dataquery. See DQOPTLST
Parameters for information on the System Option Table parameters CDBIDSL=,
CDBXITB=, and CDBXITO=.
Operation
When a query is validated, this exit is called once for each table named in the query and has the opportunity to change the database ID of any table. If database IDs greater than
999 are to be used, the CDBIDSL= parameter of the System Option Table must be set to
YES. When this parameter is set to YES the database ID field passed between CA
Dataquery and the user exit program is always 3 bytes, packed, regardless of the actual length of the database ID.
CICS Procedure
In the CICS environment, the exit should be a command-level or macro-level CICS program. Input to the exit is a CICS temporary storage record named DQttttCD, where tttt is the ID of the terminal that the CA Dataquery session is running. The exit must read this record whose contents are:
USER-NAME CHARACTER 32 BYTES SIGNED ON USER NAME
TABLE-NAME CHARACTER 32 BYTES OCCURRENCE NAME OF CA Datacom/DB TABLE
TABLE-DBID
(CDBIDSL=NO) CHARACTER 3 BYTES CA Datacom/DB DATABASE ID
(CDBIDSL=YES) PACKED 3 BYTES CA Datacom/DB DATABASE ID
RETURN-CODE BINARY 4 BYTES RETURN CODE FROM THE EXIT
QUERY-ADDR BINARY 4 BYTES ADDRESS OF QUERY
QUERY-LEN BINARY 2 BYTES LENGTH OF QUERY
After processing, the exit should rewrite the temporary storage record. No change should be made to the query itself. Any changes made will not be honored by CA
Dataquery.
Chapter 49: DBID Exit 479
Batch Submit Exit in CICS
The exit is expected to set the return code field in the record as follows:
0
No errors occurred in the exit. In this case, if the exit has altered the database ID associated with the table in the temporary storage record, CA Dataquery uses the new database ID.
990—999
An error occurred in the exit. CA Dataquery attempts to display an error message having this message number. This range of error numbers is reserved for messages created by site administration. You should be sure that an error message has been created if your exit supplies a return code in this range. Query validation fails.
Any other
CA Dataquery displays DQ048E with the return code from the exit appended. Query validation fails.
Batch Procedure
The exit should be an Assembler language program that observes standard program linkage conventions. On entry to the exit, register 1 points to a fullword that contains the address of the area described above. The exit should modify this area in place before returning control to CA Dataquery.
480 Administration Guide
Chapter 50: Data Exit
This exit is called every time CA Dataquery is ready to include a row in the found set of a query. It can reject the row, preventing its inclusion in the set. See DQOPTLST
Parameters for information about the DATAXIT= parameter of the System Option Table.
Prerequisites
The exit should be in Assembler language and cannot use monitor or operating system services.
Linkage
Standard linkage conventions apply. On input to the exit, register 1 points to a parameter list as follows:
PARM1:
Address of the data record
PARM2:
Address of 3-byte CA Datacom/DB table name
PARM3:
Address of 2-byte CA Datacom/DB database ID (binary)
PARM4:
Address of 4-byte return code word
PARM5:
Address of 32-byte user name
PARM6:
Address of 100-byte work area for use by the exit
Return Code
On return, all registers except R15 should be restored to their values on entry to the exit. A return code should be placed in R15. The exit should set the return code word to binary zero if the data record can be included in the found set, and any nonzero value if the record should not be included.
Chapter 50: Data Exit 481
Chapter 51: Data Stream Input Exit
The Data Stream Input exit receives control when an input data stream is received by CA
Dataquery from a terminal. It can examine and modify the data stream. See DQOPTLST
Parameters for information about the DSIEXIT= parameter of the System Option Table.
Procedure
In the CICS environment, the exit receives no parameters. It is given control as an ordinary CICS program and can be either command or macro level. It can locate the
TIOA through normal CICS facilities and can then modify it in any manner, including freeing it and allocating another of a different size. When finished, the exit should return control to CICS using CICS facilities.
Linkage
Standard linkage conventions apply. The exit must save and restore the CA Dataquery registers in a save area addressed by register 13. It must return to the address in register 14 when finished.
Chapter 51: Data Stream Input Exit 483
Chapter 52: Data Stream Output Exit
The exit can inspect and modify the data stream in place but must not change its location or length. The Data Stream Output exit receives control just before CA
Dataquery writes a data stream (screen or page image) to a terminal. It can inspect and
modify the data stream. To access individual rows of output, see
Output Exit
page 477). To see information about the DSOEXIT= parameter of the System Option
Table, see DQOPTLST Parameters.
Procedure
This exit should be an Assembler language program and is called using standard linkage conventions. On input to the exit, register 1 points to a parameter list as follows:
PARM1:
Address of the data stream
PARM2:
The WCC followed by a 3-byte length of the data stream
PARM3:
Address of the user's two-character language dialect code followed by his two-character primary language code.
Note: The exit cannot use monitor or operating system services.
Chapter 52: Data Stream Output Exit 485
Chapter 53: Network Printer Exit
Use the Network Printer Exit to control the data stream written to the network printer yourself instead of allowing CA Dataquery to write the data stream to be written to a network printer.
Procedure
To use a Network Printer Exit, you must link DQSYSTBL with entry point DQEXIT. The exit is called each time a message is sent to any Network Printer. You are responsible for building the data stream.
Register 1 points to a parameter list as follows:
PARM1:
Address of area for print output (TP stream, max 6000 bytes)
PARM2:
Address of message image (can contain pseudo attribute bytes (X'00'-X'0D') which normally should print as spaces)
Note: The image area is 3564 bytes long. The exit can determine the number of rows in the image by starting at the last row in the area and searching backwards for the last row that is not entirely spaces.
PARM3:
Address of page-eject indicator byte (if X'20' bit is on, new page is indicated)
PARM4:
Binary fullword: number of columns on the network printer
Register usage for the Network Printer Exit:
Register 1
(OUTPUT) Must contain the length of the resulting data stream. No I/Os or monitor calls are allowed. The exit must build the data stream at PARM1 and return the length in Register 1.
Register 13
The area in which to save CA Dataquery's registers. You are responsible for saving and restoring the registers.
Chapter 53: Network Printer Exit 487
Batch Submit Exit in CICS
Register 14
Contains the return address.
Register 15
Contains the exit entry address.
488 Administration Guide
Chapter 54: Solving User Problems
As the CA Dataquery Administrator, you need to know what to do when user problems occur, both for online and batch CA Dataquery.
It is your responsibility to:
■
Identify the source of the user's problem. For example, did the user specify the correct JCL member when he executed the batch job?
■
Help the user to resolve his problem wherever possible. For example, direct the user to the proper section in the CA Dataquery end-user documentation.
■
Be aware of your site standards and their impact on the user. For example, if your site uses CA Top Secret, CA ACF2, or another security package, it can impact your site's CA Dataquery signon procedures.
■
■
Interface with the Security Administrator, Systems Programmer, and Database
Administrator when appropriate. For example, a user cannot save his found sets because there is insufficient storage available in the Found Table and he cannot delete any saved found sets, so you need to request more blocks of storage.
Interface with CA Support whenever a user encounters an internal error, or you are unable to resolve the user's problem.
User Exits
■
■
■
■
■
There are user exits that your site can elect to use.
■
Batch Line Printer Exit
■
Batch Submit Exit
■
Network Printer Exit
■
Query Validation Exit
Database ID Exit
Signon/off Exit Batch
Signon/off Exit Online
■
User-Defined Functions Exit
Output Exit - Online
Output Exit - Batch
Chapter 54: Solving User Problems 489
Solving Online CA Dataquery Problems
If your site has made use of any of these exits, make sure that you are familiar with them and that they are executing properly and issuing the expected return codes to CA
Dataquery. Your Systems Programmer can provide you with more information about the user exits in use at your site.
The CA Dataquery HELP function <PF1> can assist users in answering many problems that they encounter while using CA Dataquery. However, there can be problems that arise that only the CA Dataquery Administrator has the authority or access to the particular functions to solve.
Solving Online CA Dataquery Problems
When you receive a transaction abend, CICS sends a message to your terminal in the following format:
TRANSACTION tttt PROGRAM xxxxxxxx ABEND cccc
Format
tttt
Is the CICS transaction ID of the abended transaction. DQIN for example.
xxxxxxxx cccc
Is the internal program name.
Is the completion code of the type ASRA, AICA, APCT, and so on.
Action
When you encounter a transaction abend, collect the following information:
■
The transaction dump from the CICS dump data set. (Request the Systems
Programmer to provide this dump.)
■
The name and number of the panel last displayed before the abend.
■
The user name of the user encountering the abend.
■
A list of the series of events that occurred prior to the abend. For example, list the function key that was pressed, what was running at the time - a query, dialog, term, and so forth, and what was displayed on the terminal. The more information of this type that you can furnish to CA Support, the easier it is to correct the problem.
Contact CA Support when all of the above information has been collected.
490 Administration Guide
Encountering Serious CA Dataquery Errors
Encountering Serious CA Dataquery Errors
CA Dataquery could encounter an error which makes it impossible to continue processing. When this occurs, CA Dataquery displays messages similar to the following error messages:
■
DQ001E - AN INTERNAL ERROR HAS BEEN DETECTED WITHIN CA Dataquery
■
This is an internal processing problem, a CA Dataquery system problem.
DQ215I - AN INTERNAL VALIDATION ERROR HAS OCCURRED - A SNAP DUMP WAS
TAKEN
This is also an internal error. The query cannot be validated. A SNAP dump of all of the transaction and program storage in use at the time of the CICS dump data set error was taken.
Action
Whenever you encounter errors of this type, perform the following:
■
Have the System Programmer print the SNAP dump from the CICS dump data set.
■
Note the error message number and the text of the error message.
■
Note the CA Dataquery panel name and number from which the error message was displayed.
■
■
Note what you did before receiving the error message. For example, list the function key that was pressed, what was running - a query, dialog, term, and so forth, and what was displayed on the terminal. The more information of this type that you can furnish to CA Support, the easier it is to correct the problem.
Call CA Support.
Encountering Other CA Dataquery Errors
Initial Action
Whenever a user encounters an error that is not a transaction abend, or an internal error message, attempt to determine the cause of the error with careful analysis. Collect the following information to help you with your analysis:
■
Name and number of the CA Dataquery panel that was displayed with the error message.
■
Name and number of the CA Dataquery panel that was displayed prior to the panel with the error message.
■
Sequence of events that led up to the error message.
Chapter 54: Solving User Problems 491
Solving Batch CA Dataquery Problems
Query Problems
If a query or dialog was being validated, executed or submitted, collect the following information:
■
Text of the query that was being validated, executed or submitted.
■
User name of the user who received the error, and a list of any groups to which he is assigned.
■
Any restricted conditions assigned to this user or to the user's assigned groups.
■
Any defined terms or user-defined functions within the query.
With this information, you and the user should be able to solve the problems.
■
■
Items that frequently cause problems include:
■
Incorrect TABLE, KEY, or FIELD entity-occurrence definitions in CA Datacom
Datadictionary.
■
TABLE, KEY, and FIELD entity-occurrences named the same.
■
TABLE, KEY, and FIELD entity-occurrences named the same as CA Dataquery keywords.
CA Datacom/DB tables closed and not accessible to CA Dataquery.
Terms named the same as CA Dataquery keywords or TABLE, KEY, and FIELD entity-occurrences.
Solving Batch CA Dataquery Problems
When a user encounters problems with batch CA Dataquery, collect the following information:
■
All the SYSOUT printed from the job, including any job log messages, SNAPER data sets, SYSPRINT, SYSOUT data sets and JCL listings
■
User name of the user who submitted the job and the names of any groups that are assigned to that user
■
Text of the query or dialog
■
Any restricted conditions applied to this user or his assigned groups
■
Any defined terms or user-defined functions in the query or dialog text
Review all of the information carefully. If you cannot resolve the problem with the help of your Systems Programmer, call CA Support.
492 Administration Guide
Chapter 55: Using DQL Diagnostics
Diagnostics is an administrative function that is accessed from the Administrative Menu, but is only used on a request from CA Support.
For example, a user has written a query that has been edited and validated, but yet does not execute, has performance problems, or gets the wrong results. In some cases, CA
Dataquery returns an error message instructing the user to contact his CA Dataquery
Administrator. The CA Dataquery Administrator, in turn, if the problem is with CA
Datacom/DB, can call CA Support. CA Support can request that you perform diagnostics on the query to provide more information.
Function
The Diagnostic function allows the CA Dataquery Administrator to produce a CA
Dataquery request table, a transaction dump, a module dump, or a Compound Boolean
Selection Facility Diagnostic Report.
Overview
The diagnostic information contained in the request table shows how the query was coded, which definition it was looking for in CA Datacom Datadictionary, and so on. The
Compound Boolean Selection Facility Diagnostic report shows exactly what CA
Dataquery passed to the Compound Boolean Selection Facility and how the Compound
Boolean Selection Facility interpreted it. This report shows whether it is CA Dataquery or the Compound Boolean Selection Facility causing the problem.
Action
To produce a request table, you must first validate the query. When CA Dataquery returns an error message, go to the Administrative Menu and select the DIAGNOSTICS option or use the DIAG command from the command line. CA Dataquery displays the
DIAGNOSTICS REQUEST panel, examples of which follows on the next page and in the next chapter.
Chapter 55: Using DQL Diagnostics 493
Diagnostics Request
Diagnostics Request
Diagnostics Request (DQKU0)
=>
------------------------------------------------------------------------DQKU0
DATAQUERY: DIAGNOSTICS REQUEST
-----------------------------------------------------------------------------
Place any character next to the desired diagnostic facility and enter any
required information. Press Enterall perform the request.
----------------------------------------------------------------------------
SELECT THE TYPE OF DIAGNOSTICS TO PERFORM:
_ DISPLAY DATAQUERY REQUEST TABLE
_ STORAGE DUMP (ENTER 1 or 2)
1. TRANSACTION DUMP
2. MODULE DUMP
TURN DUMP ON AT TERMINAL ____
TURN DUMP OFF AT TERMINAL ____
_ TURN CBS DIAGNOSTICS ON AT THIS TERMINAL
_ TURN CBS DIAGNOSTICS OFF AT THIS TERMINAL
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
Panel Description
The following is a brief explanation of each field on the Diagnostics Request panel.
DISPLAY DATAQUERY REQUEST TABLE
Enter any character to execute a CA Dataquery Request Table.
STORAGE DUMP (ENTER 1 or 2)
Enter 1 to execute a transaction dump.
Enter 2 to execute a module dump.
TURN DUMP ON AT TERMINAL
Enter the terminal ID of the terminal where the query or dialog is to be executing.
TURN DUMP OFF AT TERMINAL
Enter the terminal ID of the terminal where the dump is to be turned off.
TURN CBS DIAGNOSTICS ON AT TERMINAL
Enter any character to execute Compound Boolean Selection diagnostics.
TURN CBS DIAGNOSTICS OFF AT TERMINAL
Enter any character to turn off Compound Boolean Selection diagnostics.
494 Administration Guide
Diagnostics Request
PF Keys
Key Objective
CLEAR
<PF2>
RETURN
Return to Main Menu.
<PF1> HELP Display HELP panel PF key options.
Return to previous panel.
Result
Return to the Main Menu.
CA Dataquery displays the HELP panel.
Previous panel or Main Menu is displayed.
Compound Boolean Selection Facility Diagnostics
Enter any character in the TURN CBS DIAGNOSTICS ON field at this terminal option and press Enter to turn the Compound Boolean Selection Facility Diagnostic report on.
Compound Boolean Selection Facility Diagnostics are available in CA Dataquery batch.
The following message appears at the top of the Diagnostics Request panel:
DQ525I - CBS DIAGNOSTICS FACILITY HAS BEEN ACTIVATED SUCCESSFULLY
A report is produced for every query or dialog that is executed at the specified terminal, until Compound Boolean Selection Facility Diagnostics is turned off. See the CA
Datacom/DB DBUTLTY Reference Guide for full details about the Compound Boolean
Selection Facility Diagnostic report and how to produce it.
Chapter 55: Using DQL Diagnostics 495
Diagnostics Request
Request Table
Enter any character in the DISPLAY DATAQUERY REQUEST TABLE option field and press
Enter to perform the request. CA Dataquery displays the Current CA Dataquery Request
Table panel, an example of which follows:
Current CA Dataquery Request Table (DQKF0)
=>
------------------------------------------------------------------------DQKF0
DATAQUERY: CURRENT DATAQUERY REQUEST TABLE
-----------------------------------------------------------------------------
C 0004C3D8 00000
N 0006D5FFFFFF 00004
F 0035C600D7C1E8D9D6D3D3404040404040404040404040404040404040404040404040 0000A
400001D7C1E80001C5D4D7D5D6C5D4D7D5D6
+ 00054EE600 0003F
I 0032C900E8E3C460C3D6D4D4C9E2E2C9D6D54040404040404040404040404040404040 00044
40000100D500080602D50017C3
R 0004D902 00076
V 000CE500000000000200000F 0007A
+ 00054ED900 00086
F 0035C600D7C1E8D9D6D3D3404040404040404040404040404040404040404040404040 0008B
400001D7C1E80001C5D4D7D5D6C5D4D7D5D6D
K 0033D240D5E4D4C2C5D940404040404040404040404040404040404040404040404040 000C0
40C5D4D7D5D6D405D500050500D5000
F 0035C600D7C5D9E2D6D5D5C5D340404040404040404040404040404040404040404040 000F3
400001D7D4C60001C5D4D7D5D6C5D4D7D5D6
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> NOT USED
<PF5> NOT USED <PF6> NOT USED <PF7> BACKWARD <PF8> FORWARD
The information displayed by the execution of the CA Dataquery Request Table is used by CA Support to help solve certain problems.
PF Keys
Key
CLEAR
<PF1> HELP
<PF2> RETURN
Objective
Return to Main Menu.
Display HELP panel
PF key options.
Result
Return to the Main Menu.
CA Dataquery displays the HELP panel.
Return to previous panel. Previous panel or Main Menu is displayed.
Not used. <PF3> NOT USED
<PF4> NOT USED
<PF5> NOT USED
<PF6> NOT USED
496 Administration Guide
Diagnostics Request
Key Objective
<PF7>BACKWARD Scroll to previous CA
Dataquery Request Table screen, if any.
<PF8> FORWARD Scroll to next screen of CA Dataquery Request
Table, if any.
Result
Display previous CA Dataquery
Request Table screen, if any.
Display more CA Dataquery
Request Table, if any.
If the problem with the query or dialog cannot be solved from the information received from the CA Dataquery Request Table, CA Support can request that you produce a transaction or module storage dump.
Transaction or Module Dump
To produce a transaction or module dump, select the DIAGNOSTICS option from the
Administrative Menu, or use the DIAG command from the command line and:
Step 1
Enter 1 for a transaction dump, or 2 for a module dump next to the STORAGE
DUMP option.
Step 2
Enter the terminal ID of the user who executed the query in the space following the
TURN DUMP ON AT TERMINAL prompt.
Step 3
Execute the query from the specified terminal.
Step 4
When it is time to turn the dump off, place the same terminal ID used to turn the dump on in the space following the TURN DUMP OFF AT TERMINAL prompt.
CA Dataquery turns on a transaction dump or module dump at the specified terminal.
The transaction dump produces a dump for every screen displayed on the selected terminal, while a module dump produces a dump for every program that is invoked by
CA Dataquery to process a screen. These dumps are written to the CICS dump data sets.
Contact your systems programmer to print the dumps. The dumps have special identifiers for CA Dataquery.
CA Support can review the dumps or the CA Dataquery Request Table with you or the systems programmer over the telephone, or request that you send the dumps to the CA
Support office.
Chapter 55: Using DQL Diagnostics 497
Chapter 56: Using SQL Mode Diagnostics
An important feature of the relationship between CA Dataquery SQL Mode and CA
Datacom/DB is the plan defined in CA Datacom/DB for processing SQL queries. You can specify some options of the plan as they pertain to queries and you can use the abilities of the plan to request diagnostic information if query processing problems arise. You should only request diagnostics if asked to do so by CA Support.
Function
The Diagnostic function allows the CA Dataquery Administrator to produce a CA
Dataquery request table, a transaction dump, or a module dump. It also allows you to set the optimization options for the current session.
Overview
The diagnostic information contained in the request table shows how the query was coded, which definition it was looking for in CA Datacom Datadictionary, and so on. A dump provides information needed by CA Support.
Three panels, one command, and two batch mode parameters allow you to access the
CA Datacom/DB plan.
Diagnostics Request
Panel DQKU0
Allows you to request a request table or a dump if needed by CA Support, or to set options for plan optimization.
Plan Optimization Options
Panel DQKT0
For the current online session, allows you to specify the types of messages you want to receive and to specify that the plan should use the join order specified in the FROM clause of the SQL query.
Optimization Messages Display
Panel DQKV0
For the current online session, displays messages requested and allows you to delete messages after viewing.
PLAN command
Displays the Plan Optimization Options panel.
Chapter 56: Using SQL Mode Diagnostics 499
Diagnostics Request
PLANOPTS,MSG= Option
Card Parameter
Allows plan optimization in batch mode.
PLANOPTS,OPT= Option
Card Parameter
Allows plan optimization in batch mode.
Diagnostics Request
The Diagnostic function allows the CA Dataquery Administrator to produce a CA
Dataquery request table or a dump, set the optimization options or view the
Optimization Messages Display panel (DQKV0).
The diagnostic information contained in the request table shows how the query was coded, which definition it was looking for in CA Datacom Datadictionary, and so on.
Diagnostics Request (DQKU0)
=>
------------------------------------------------------------------------DQKU0
DATAQUERY: DIAGNOSTICS REQUEST
-----------------------------------------------------------------------------
Place any character next to the desired diagnostic facility and enter any
required information. Press Enter to perform the request.
----------------------------------------------------------------------------
SELECT THE TYPE OF DIAGNOSTICS TO PERFORM:
_ DISPLAY DATAQUERY REQUEST TABLE
_ STORAGE DUMP (ENTER 1 or 2)
1. TRANSACTION DUMP
2. MODULE DUMP
TURN DUMP ON AT TERMINAL ____
TURN DUMP OFF AT TERMINAL ____
_ SET PLAN OPTIMIZATION OPTIONS
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
500 Administration Guide
Diagnostics Request
Panel Description
The following is a brief explanation of each field on the Diagnostics Request panel.
DISPLAY DATAQUERY REQUEST TABLE
Enter any character to execute a CA Dataquery Request Table.
STORAGE DUMP (ENTER 1 or 2)
Enter 1 to execute a transaction dump.
Enter 2 to execute a module dump.
TURN DUMP ON AT TERMINAL
Enter the terminal ID of the terminal where the query or dialog is to be executing.
TURN DUMP OFF AT TERMINAL
Enter the terminal ID of the terminal where the dump is to be turned off.
SET PLAN OPTIMIZATION OPTIONS
Enter any character to display the Plan Optimization Options panel for specifying messages and mode for the current session.
To exercise the message table you are required to have PPT (Processing Program
Table) entries in a URT with a TABLE id=MSG and DBID=15.
PF Keys
Key Objective Result
CLEAR
<PF1> HELP
Return to Main Menu.
Display HELP panel.
Return to the Main Menu.
CA Dataquery displays the HELP panel.
<PF2> RETURN Return to previous panel. Previous panel or Main Menu is displayed.
Chapter 56: Using SQL Mode Diagnostics 501
Diagnostics Request
Request Table
Enter any character in the DISPLAY DATAQUERY REQUEST TABLE option field and press
Enter to perform the request. CA Dataquery displays the Current CA Dataquery Request
Table panel, an example of which follows:
Current CA Dataquery Request Table (DQKF0)
=>
------------------------------------------------------------------------DQKF0
DATAQUERY: CURRENT DATAQUERY REQUEST TABLE
-----------------------------------------------------------------------------
C 0004C3D8 00000
N 0006D5FFFFFF 00004
F 0035C600D7C1E8D9D6D3D3404040404040404040404040404040404040404040404040 0000A
400001D7C1E80001C5D4D7D5D6C5D4D7D5D6
+ 00054EE600 0003F
I 0032C900E8E3C460C3D6D4D4C9E2E2C9D6D54040404040404040404040404040404040 00044
40000100D500080602D50017C3
R 0004D902 00076
V 000CE500000000000200000F 0007A
+ 00054ED900 00086
F 0035C600D7C1E8D9D6D3D3404040404040404040404040404040404040404040404040 0008B
400001D7C1E80001C5D4D7D5D6C5D4D7D5D6D
K 0033D240D5E4D4C2C5D940404040404040404040404040404040404040404040404040 000C0
40C5D4D7D5D6D405D500050500D5000
F 0035C600D7C5D9E2D6D5D5C5D340404040404040404040404040404040404040404040 000F3
400001D7D4C60001C5D4D7D5D6C5D4D7D5D6
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> NOT USED <PF4> NOT USED
<PF5> NOT USED <PF6> NOT USED <PF7> BACKWARD <PF8> FORWARD
The information displayed by the execution of the CA Dataquery Request Table is used by CA Support to help solve certain problems.
PF Keys
Key
CLEAR
<PF1> HELP
<PF2> RETURN
Objective
Return to Main Menu.
Display HELP panel
PF key options.
Result
Return to the Main Menu.
CA Dataquery displays the HELP panel.
Return to previous panel. Previous panel or Main Menu is displayed.
Not used. <PF3> NOT USED
<PF4> NOT USED
<PF5> NOT USED
<PF6> NOT USED
502 Administration Guide
Diagnostics Request
Key Objective
<PF7>BACKWARD Scroll to previous CA
Dataquery Request Table screen, if any.
<PF8> FORWARD Scroll to next screen of CA Dataquery Request
Table, if any.
Result
Display previous CA Dataquery
Request Table screen, if any.
Display more CA Dataquery
Request Table, if any.
If the problem with the query or dialog cannot be solved from the information received from the CA Dataquery Request Table, CA Support can request that you produce a transaction or module storage dump.
Transaction or Module Dump
To produce a transaction or module dump, select the DIAGNOSTICS option from the
Administrative Menu, or use the DIAG command from the command line and:
Step 1
Enter 1 for a transaction dump, or 2 for a module dump next to the STORAGE
DUMP option.
Step 2
Enter the terminal ID of the user who executed the query in the space following the
TURN DUMP ON AT TERMINAL prompt.
Step 3
Execute the query from the specified terminal.
Step 4
When it is time to turn the dump off, place the same terminal ID used to turn the dump on in the space following the TURN DUMP OFF AT TERMINAL prompt.
CA Dataquery turns on a transaction dump or module dump at the specified terminal.
The transaction dump produces a dump for every screen displayed on the selected terminal, while a module dump produces a dump for every program that is invoked by
CA Dataquery to process a screen. These dumps are written to the CICS dump data sets.
Contact your systems programmer to print the dumps. The dumps have special identifiers for CA Dataquery.
CA Support can review the dumps or the CA Dataquery Request Table with you or the systems programmer over the telephone, or request that you send the dumps to the CA
Support office.
Chapter 56: Using SQL Mode Diagnostics 503
Diagnostics Request
Plan Optimization Options
Display the Plan Optimization Options panel by selecting Plan Optimization Options on the Diagnostics Request panel or by typing PLAN on the command line. Any user authorized to perform diagnostic functions can use this panel. From it, you can specify production of optimization messages, specify join optimization, or display messages.
=>
------------------------------------------------------------------------DQKT0
DATAQUERY: PLAN OPTIMIZATION OPTIONS AUTHID: PUBLIC
-----------------------------------------------------------------------------
Select the plan optimization options desired by placing any character in the
space next to your choice and press PF4 to update your plan options.
Press PF3 to display existing optimization messages.
-----------------------------------------------------------------------------
OPTIMIZATION MESSAGE OPTIONS FOR PLAN NAME DQxxxxOM
PREPARATION TIME EXECUTION TIME
_ NO MESSAGES (DEFAULT) _ NO MESSAGES (DEFAULT)
_ SUMMARY MESSAGES _ SUMMARY MESSAGES
_ DETAIL MESSAGES _ DETAIL MESSAGES
OPTIMIZATION MODE
_ MANUAL JOIN ORDER (ORDER LISTED IN "FROM" CLAUSE)
_ PREPARATION TIME ORDER (DEFAULT)
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DISPLAY MESSAGES <PF4> UPDATE
Message Options
The Plan Optimization Options panel allows you to request that optimization messages be produced by CA Datacom/DB when SQL queries are prepared or executed. These are diagnostic messages that are written to the MSG table. You can view them online using the Display Messages PF key or you can query the MSG table through online CA
Dataquery or in DQBATCH. Use the messages to help you solve problems with SQL queries.
Panel Description
The following list describes your message options.
Plan Name
DQxxxxOM where xxxx is the terminal ID. The plan is the set of information required by CA
Datacom/DB to execute the SQL query. It is created dynamically by CA Dataquery whenever a query is validated.
504 Administration Guide
Diagnostics Request
Preparation Time
Select the type of messages you want retained regarding preparation time for processing the active query. Preparation time is the time needed for preparation of
SQL statements for execution when a query is validated by CA Dataquery. The selections are:
No Messages
No messages are captured.
Summary Messages
Only messages summarizing processing are captured.
Detail Messages
All messages produced during processing are captured.
Execution Time
Select the type of messages you want retained regarding execution time for processing the active query. The selections are:
No Messages
No messages are captured.
Summary Messages
Only messages summarizing processing are captured.
Detail Messages
All messages produced during processing are captured.
Optimization Mode
The Plan Optimization Options panel allows you to request that the tables named in the
FROM clause be joined in the order listed in the query as opposed to optimum order determined by CA Datacom/DB at preparation time.
Chapter 56: Using SQL Mode Diagnostics 505
Diagnostics Request
Optimization Messages Display
The Optimization Messages Display panel displays plan optimization messages which were produced by CA Datacom/DB for the last SQL query prepared or executed for which messages were requested. These messages can be used for problem solving for
SQL queries.
This panel appears when you select DISPLAY MESSAGES from the Plan Optimization
Options panel. Any user authorized for diagnostic functions may view this panel.
=>
------------------------------------------------------------------------DQKV0
DATAQUERY: OPTIMIZATION MESSAGES DISPLAY
-----------------------------------------------------------------------------
STMT ID SEQ # MESSAGE TEXT
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> DELETE MESSAGES <PF4> NOT USED
<PF5> NOT USED <PF6> NOT USED <PF7> BACKWARD <PF8> FORWARD
From this panel you can request that these messages be deleted from the MSG table when they are no longer needed by pressing <PF3> DELETE MESSAGES. See the CA
Datacom/DB Message Reference Guide for information about the messages that appear on this panel.
506 Administration Guide
SQL Plan Options
SQL Plan Options
CA Datacom/DB has a plan option which allows CA Dataquery to specify the character to be used for the decimal point indicator in decimal, numeric, and floating point literals.
CA Dataquery uses the user's profile setting for the decimal point when creating the plan to be used to execute an SQL query.
Therefore, if a user's profile specifies a comma (,) for the decimal point character, this user must use a comma for the decimal point indicator in any literals in all SQL (or DQL) queries. This is a change from Version 8.0 in which SQL only recognized the period (.) as the decimal point character.
To pass SQL plan options to be used by CA Dataquery, you must code the options as CA
Dataquery comments beginning on line 1 of the query. Line 1 must have the CA
Dataquery comment-begin characters in columns 1 and 2. Immediately following, in column 3, you must enter $DBSQLOPT as shown in the example following, which used */ for CA Dataquery comment-begin characters and /* for CA Dataquery comment-end characters.
*/$DBSQLOPT option=value option=value option=value
option=value option=value ... /*
Follow each option=value with at least one space. No option=value may be continued from one query line to another, but you may use more than one line to include all of the required option=value statements. The last option=value must be followed by at least one space and the CA Dataquery comment-end characters (/*).
Any options specified in this manner are only used for the current execution of the query in which they are placed.
Following are SQL plan options and values that are significant for CA Dataquery:
DATE=
This option specifies the DATE output format. Valid values for DATE= are ISO, USA,
EUR, or JIS. If this option is not specified, or an invalid value is specified, the default value will be taken from the CA Dataquery option table value for the SQL date format.
DECPOINT=
This option specifies if you want a comma (,) to be the decimal point indicator in decimal, numeric, and floating-point literals. Valid values are C or P, C representing the comma (,) and P representing the period (.). The default if the option is not specified or an invalid value is used is the user's profile setting for the decimal point character.
Chapter 56: Using SQL Mode Diagnostics 507
SQL Plan Options
508 Administration Guide
ISOLEVEL=
This option specifies the isolation level, or degree to which a unit of recovery is isolated from the updating operations of other units of recovery. Valid entries are
U, C, or R. If not specified, or an invalid value is given, the default is C.
PLNCLOSE=
This option specifies when the plan and URT are closed. Valid entries are T or R. The default is T if not specified or an invalid value is given.
SQLMODE=
This option specifies the mode in which CA Datacom/DB will process the query.
Valid entries are ANSI, DATACOM, DB2, or FIPS. Default will be DATACOM when the option is not specified or an incorrect value is given.
STRDELIM=
This option specifies whether you want the string delimiter, used to delimit character string literals in SQL statements to be an apostrophe (') or a quotation mark ("). The escape character, used to enclose delimited SQL identifiers, is the apostrophe if the string delimiter is the quotation mark, or the quotation mark if the string delimiter is the apostrophe. Valid values are A or Q. If the option is not used, or an invalid value is given, the default is the apostrophe (').
TIME=
This option specifies the TIME output format. Valid values for TIME= are ISO, USA,
EUR, or JIS. If this option is not specified, or an invalid value is specified, the default value will be taken from the CA Dataquery option table value for the SQL time format.
TIMEMIN=
This option specifies exclusive control wait time in minutes. Valid entries are 0 to
120. If not specified or an incorrect value is given, default is 0. If TIMEMIN is specified, TIMESEC is set to 0.
TIMESEC=
This option specifies the exclusive control wait time limit in seconds. Valid entries are 0 to 120. If not specified, or an incorrect value is given, default is 10. TIMESEC will be set to 0 if TIMEMIN is specified.
WORKSPACE=
Use WORKSPACE= only at the direction of CA Support.
This option specifies an increase in the amount of workspace used at plan execution time. Valid entries are 0 to 128. The default is 0 if not specified or an incorrect value is given.
Note: For a complete list and full details on plan options, see the CA Datacom/DB SQL
User Guide.
Chapter 57: Using the Printer Control
Printer Control is an administrative function that is used solely for query reports routed to your site's network printers. For example, a user needs to reprint a query report due to a printer malfunction, or a query report needs to be stopped due to a priority need for the network printer by another user. Printer Control allows a CA Dataquery
Administrator to handle these and other types of problems with your site's network printers.
Functions
A CA Dataquery Administrator can perform the following printer functions from the
Directory of Spooled Print panel:
■
Stop an active query report
■
Restart the report from the point that it was stopped
■
Restart the report from page one
■
Flush the active query report from the print queue
Chapter 57: Using the Printer Control 509
SQL Plan Options
Action
Access the Administrative Menu and select the Printer Control option, or use the
PRINTER command from the command line after a query or dialog has been executed and the report destination is to a network printer. CA Dataquery displays the Directory of Spooled Print panel, an example of which follows:
Sample Directory of Spooled Print (DQKI0)
=>
Place the cursor on a name and press the appropriate PFKey.
------------------------------------------------------------------------DQKI0
DATAQUERY: DIRECTORY OF SPOOLED PRINT
-----------------------------------------------------------------------------
PRT ID | REQUESTING USER | STATUS | P-CMD | DATE/TIME SENT
-----------------------------------------------------------------------------
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN <PF3> GO <PF4> STOP
<PF5> RESTART <PF6> FLUSH/CANCEL <PF7> BACKWARD <PF8> FORWARD
Panel Description
The following describes each column of the Directory of Spooled Print panel.
PRT ID
Network printer ID.
REQUESTING USER ID
ID of CA Dataquery user who executed the query.
STATUS
The status of the query or dialog in the print queue.
510 Administration Guide
SQL Plan Options
P-CMD
Indication that a command has been issued and is pending execution.
DATE / TIME SENT
Date and time the request was queued for the printer.
Note: The network printer ID can be the user's default network printer ID, that is defined to CA Dataquery from the Profile panel, or another network printer ID that is valid for the user's site.
A command that is issued after the print request, is placed in the P-CMD column until the command is processed. For example, if you submit a print request to a network printer and use <PF4> STOP to stop the print, the STATUS remains ACTIVE and P-CMD is
STOP until the stop is processed. When the stop is processed, the STATUS reads STOP.
Status Column
The Directory of Spooled Print panel displays three statuses in the STATUS column.
ACTIVE
The query report is printing on the network printer.
READY
The query is in the print queue awaiting print.
STOP
The user has stopped the printing of the query report.
P-CMD Column
The Directory of Spooled Print panel displays four commands in the P-CMD column.
STP
RST
The user has stopped the printing of the query report.
The user has restarted the printing of the query report from the beginning.
FSH
The user has canceled the printing of the query report.
GO
The user has restarted the printing of the query report from the stop point.
Chapter 57: Using the Printer Control 511
SQL Plan Options
PF Keys
Key
CLEAR
<PF1> HELP
<PF2> RETURN
<PF3> GO
<PF4> STOP
<PF5> RESTART
<PF6>FLUSH/CANCEL
<PF7> BACKWARD
<PF8> FORWARD
Objective
Return to Main
Menu.
Display HELP panel.
Result
Return to the Main Menu.
CA Dataquery displays the
HELP panel.
Return to previous panel. Previous panel or Main
Menu is displayed.
Restart a stopped query report from stop point.
Stop an active query report.
Restarts a stopped query report from stop point.
Stops an active query report.
Restart active query report from the beginning.
Restarts an active query report from the beginning.
Remove a query report from the print queue.
Flushes a query from the print queue.
Scroll to previous screen of printer
IDs, if any.
Displays previous printer
IDs, if any.
Scroll to next screen of printer IDs, if any.
Displays more printer IDs, if any.
Note: Use the FLUSH/CANCEL function with caution. Any querys that are accidentally flushed from the print queue, or are canceled while printing, cannot be restarted and have to be reexecuted.
512 Administration Guide
Chapter 58: Monitoring Performance
You monitor your performance to ensure that you are getting the best performance you can. This chapter discusses the tools you can use to monitor your performance:
■
The Statistics and Diagnostics Area (PXX) Report
■
CA Dataquery statistics
■
CA Look for Datacom
■
Accounting Facility
■
Compound Boolean Selection Facility Diagnostic Report
Using the Statistics and Diagnostics Area (PXX) Report
■
■
CA Datacom/DB provides a database statistics report that displays information about:
■
Service requests
■
Exclusive control
■
Buffer availability
Request wait time frequency
I/O events
The report consists of three parts, each of which is accumulated and reported on separately:
■
System statistics
■
I/O statistics
■
User request statistics
Look at the number of Index buffers and data buffers used. Be sure there are enough.
Look at the CBSBFR SPILL COUNT. If it is high, increase the appropriate MUF startup option CBS value. See the CA Datacom/DB Database and System Administration Guide and CA Datacom/DB DBUTLTY Reference Guide for information about how to use the
Statistics and Diagnostics Area report.
Chapter 58: Monitoring Performance 513
Using CA Dataquery Statistics
Using CA Dataquery Statistics
After a user has executed a query or a dialog and routed the report to a printer or a terminal, he can produce statistical information on the execution of the query or dialog.
The statistics are printed to the printer automatically if he was authorized with
STATISTICS specified Y. To display the statistics, he can use a PF key or issue the
STATISTICS command. The statistics are reset with each query execution.
The terminal display of the statistics is as follows:
=>
CURRENT DATAQUERY FIND/SELECT STATISTICS.
------------------------------------------------------------------------DQEB0
DATAQUERY: FIND STATISTICS QUERY NAME:
-----------------------------------------------------------------------------
NUMBER REQUESTED: COMPLETION DATE:
NUMBER FOUND: COMPLETION TIME:
FIND TERMINATED BECAUSE:
OVERALL OPTIMIZATION SEARCH
------- ------------ -------
ELAPSED TIME (SECONDS):
I/O EVENTS:
SELFR TOTAL:
SELNR TOTAL:
TOTAL BYTES:
-----------------------------------------------------------------------------
<PF1> HELP <PF2> RETURN
The following is a brief explanation of the fields on the Find Statistics panel.
QUERY NAME:
Name of the query to which these statistics apply.
NUMBER REQUESTED:
Number of rows requested in your query.
NUMBER FOUND:
Number of rows found in the database.
514 Administration Guide
Using CA Dataquery Statistics
COMPLETION DATE:
Date that the search for this query ended.
COMPLETION TIME:
Time that the search for this query ended.
Field Reason
FIND TERMINATED
BECAUSE:
NORMAL END OF SEARCH
WAS REACHED
Explanation
The FIND process completed normally.
SITE I/O LIMIT
(DQOPTLST.SRCHLIM)
EXCEEDED
The FIND exceeded the value set for the I/O limit in the System
Option Table (DQOPTLST) parameter SRCHLIM=. Either reduce the number of rows which
CA Dataquery is to FIND, or increase the value in the
SRCHLIM= parameter so that your query can finish the FIND processing.
MAX WORK TABLE BLOCKS
EXCEEDED
The number of blocks specified in the FNDBLKS= parameter has been exceeded. You must evaluate the limit you have set and determine what is best for your site. If needed, you can override the FNDBLKS= value for this user using the USERS option.
MAX ELAPSED TIME
EXCEEDED
FIND CANCELED
FROM REQUESTING
TERMINAL
FIND CANCELED
FROM ANOTHER
TERMINAL
The maximum time allowed for the processing of a query FIND has been exceeded. Either simplify the
FIND so that the FIND processing time is shorter or increase the maximum time allowed using the
System Option Table MFTIME= parameter.
This query has been canceled from the requesting user's terminal.
This query was canceled from another terminal.
Chapter 58: Monitoring Performance 515
Using CA Dataquery Statistics
Field
ELAPSED TIME
(SECONDS):
Column
OVERALL
OPTIMIZATION
SEARCH
OVERALL I/O EVENTS:
SELFR TOTAL:
SELNR TOTAL:
OPTIMIZATION
SEARCH
OVERALL
OPTIMIZATION
SEARCH
OVERALL
OPTIMIZATION
Description
The overall time elapsed in seconds to process the FIND statement.
The process of determining the FIND strategy for searching the database efficiently.
The actual search time against the database for the FIND statement.
The overall number of CA
Datacom/DB physical I/O events for the processing of the FIND statement. (I/Os are calculated on
USER databases. No I/Os are calculated to the terminal or DQF or
DQW.)
The number of CA Datacom/DB physical I/O events used for determining the database search strategy.
The number of CA Datacom/DB physical I/O events used for the search of the database by the FIND statement.
The overall number of CA
Datacom/DB CBS SELFR (select first row) commands that were issued to execute the FIND statement.
The number of CA Datacom/DB CBS
SELFR (select first row) commands that were issued for determining the database search strategy.
The number of CA Datacom/DB CBS
SELFR (select first row) commands that were issued for the search of the database by the FIND statement.
The overall number of CA
Datacom/DB CBS SELNR (select next row) commands that were issued to execute the FIND statement.
(Nothing is displayed in this column.)
516 Administration Guide
Using the Accounting Facility
Field
TOTAL BYTES:
Column
SEARCH
OVERALL
OPTIMIZATION
SEARCH
Description
The number of CA Datacom/DB CBS
SELNR (select next row) commands that were issued for the search of the database by the FIND statement.
The overall number of bytes that were required to hold the internal control blocks that CA Dataquery built to process the FIND statement.
(Nothing is displayed in these columns.)
When the statistics are printed, they are the same as those displayed.
Using the Accounting Facility
CA Datacom/DB's Accounting Facility enables you to accumulate statistics on system use for programs running under the MUF. You can use these statistics for accounting, billing, tuning, and monitoring security. You select the statistics you want to accumulate by defining accounting columns for a user-specified tables. CA Datacom/DB writes the use-statistics to the tables. You can access the tables using CA Dataquery.
You can use CA Dataquery interactively to select, join, sort, total, report graph the accounting data. You can also use CA Dataquery to purge selected rows. One method of simplifying the purge routines is to specify either month or year in the row definition and use a specific date as the selection criteria for deletion.
Defining the Accounting Tables
You and the CA Dataquery Administrator should meet to determine what statistics you want to keep. Then, you must define the accounting tables according to the description in the CA Datacom/DB Database and System Administration Guide.
The UIDnn accounting column can be used to capture detailed information about CA
Dataquery use. The format of the User Information Block is as follows:
Column Offset Length Information
UID01 1 3
UID04 4 8
DQ, unless CA Dataquery diagnostics are on, then it is $$$.
(Character column.) The user accounting code from the DQU row. Assigned during user authorization.
Chapter 58: Monitoring Performance 517
Using the Accounting Facility
Column
UID12
UID27
UID31
Offset
12
27
28
31
32
Length
15
1
3
1
1
Information
(Character column.) The name of the currently executing query, if any. This name may not be entirely accurate if, for example, a query has been fetched from the library, modified, and then executed. In this situation, the statistics reflect the modified query, and not the one on the library.
(Binary column.) The processing stage code.
The codes are as follows:
0
General processing - not query execution
1
FIND statement processing
2
SET statement processing
3
SORT statement processing
4
PRINT/DISPLAY statement processing
Reserved.
(Binary column.) The CA Dataquery system indicator code as follows:
0
Online
1
Batch
Reserved
The UIDnn column is defined as described in the CA Datacom/DB Database and System
Administration Guide, where nn is the starting position relative to 01. Both CA Ideal and
CA Dataquery use the UIDnn column. To avoid collecting data that you do not want, use a conditional statement when you define your table in CA Datacom Datadictionary.
You can use the Accounting Facility to monitor performance. To do so, you set up accounting tables to monitor the activities on your system. With the Accounting Facility, you can monitor such things as:
■
What queries are using the most resources?
■
What queries are used most?
■
What operations are queries using?
518 Administration Guide
Using the Accounting Facility
■
■
What databases are being queried most?
How long does a query run?
To use the Accounting Facility to monitor performance, you must follow the procedures discussed in the CA Datacom/DB Database and System Administration Guide. The following is an example of how you may use the Accounting Facility to monitor your performance.
Identifying a Problem Job
First, you want to look to see if you have a problem job. You can create an accounting table with the following:
UID01
To collect data on CA Dataquery jobs only.
UID04
To collect data on a particular user or group of users.
UID12
To collect data on a particular job.
EXCPS/EXCIX/EXCDT
To collect data about the physical I/Os.
LOGIO/LOGIX/LOGDT
To collect data about the logical I/Os.
REQS
To collect data about the number of requests issued to CA Datacom/DB
You can use CA Dataquery to report on the data collected.
Identifying the Problem Stage of a Job
If you decide that a particular job may be a problem, you can set up additional accounting tables to analyze that job. You can set up an accounting table to identify what stage of the job is causing the problem. This accounting table may include the following:
UID01
To collect data on CA Dataquery jobs only.
UID04
To collect data on a particular user or group of users.
UID12
To collect data on a particular job.
Chapter 58: Monitoring Performance 519
Using the Accounting Facility
UID27
To collect data on a particular stage of a job.
EXCPS/EXCIX/EXCDT
To collect data about the physical I/Os.
LOGIO/LOGIX/LOGDT
To collect data about the logical I/Os.
REQS
To collect data about the number of requests issued to CA Datacom/DB
Identifying Reasons for CBS Optimizer Choices
Also, you can set up an accounting table to get detailed reasons why the Compound
Boolean Selection Facility Optimizer has chosen a particular action. This accounting table may include following:
UID01
To collect data on CA Dataquery jobs only.
UID04
To collect data on a particular user or group of users.
UID12
To collect data on a particular job.
UID27
To collect data on a particular stage of a job.
CBSOR
To collect data about the Compound Boolean Selection Facility Optimizer reasons.
Identifying Scheduling Problems
If you think you may be having a scheduling problem, you can set up an accounting table to monitor how much wait time a job experiences. This accounting table may include the following:
UID01
To collect data on CA Dataquery jobs only.
UID04
To collect data on a particular user or group of users.
UID12
To collect data on a particular job.
520 Administration Guide
Using the Accounting Facility
UID27
To collect data on a particular stage of a job.
SDATE
To collect the start date.
STIME
To collect the start time.
ETIME
To collect the elapsed time between the time MUF receives the request and the time the request is returned to the user.
WTIME
To collect the amount of time the job had to wait due to exclusive control, I/O, and so on.
Reporting the Accounting Data
You can create a meaningful report of the accounting data by creating a query that produces a report. See the CA Dataquery User Guide or CA Dataquery Reference Guide for more information.
Accounting Example
The Accounting Facility can provide a great deal of useful information about CA
Dataquery usage. For example, suppose that you wanted to know the number of CA
Datacom/DB requests generated by queries and how many actual I/O events that were needed to complete these requests. It would also be useful for this information to be grouped and ordered by query name and user name.
Following is an example of such a query and the resulting report. In it, the CA Dataquery
User Table (DQU) is related to the Accounting Table by the CA Dataquery Accounting
Code UIB04. Because of this relationship you can trace collected statistics to the actual
CA Dataquery user that caused the activity to take place.
Chapter 58: Monitoring Performance 521
Using the Accounting Facility
The following panel shows the text of the DQL query that was executed.
-----------------------------------------------------------------------------
DATAQUERY: QUERY TEXT QUERY NAME: ACCOUNTING-SAMP
-----------------------------------------------------------------------------
FIND ALL CAI-ACT-A04 RECORDS
WITH UIB01 = 'DQ'
RELATED BY UIB04 VIA ACCOUNTING-CODE TO DATAQUERY-DQU
SORT BY (USER-NAME)
CAI-ACT-A04 UIB12
TITLE1 'DATAQUERY USAGE STATISTICS'
TITLE2 'DB REQUESTS AND I/O BY QUERY BY USER'
DATAQUERY-DQU USER-NAME 'USER'
CAI-ACT-A04 UIB12 'QUERY NAME'
(REQS) 'DB /REQUESTS' PIC 'ZZZZZZZZZ9-'
(EXCPS) 'DB /IOS' PIC 'ZZZZZZZZZ9-'
522 Administration Guide
Using the Accounting Facility
The following shows a sample of the report resulting from the execution of the
ACCOUNTING-SAMP query.
May 5, 2000 DATAQUERY USAGE STATISTICS PAGE 1
16:31:05 DB REQUESTS AND I/O BY QUERY BY USER DETAIL
DB DB
USER QUERY NAME REQUESTS IOS
-------------------------------- --------------- ------------ ------------
CAI-INSTALL 4029 2471
CAI-PRINT-ITEMS 10 0
CAI-PRINT-RECPT 10 0
DBIO 460 28
DQ-ACCT-REPORT 3996 202
SAMPLE 106 12
TOTAL USER CAI-INSTALL
8611 2713
BOB TEST-BOB 629 47
TOTAL USER BOB
629 47
BUN CAI-PRINT-ACCTS 1002 70
CAI-PRINT-SALES 536 28
TOTAL USER BUN
1538 98
FULTON DBIO-PER-USER 4203 162
TOTAL USER FULTON
4203 162
GSMITH CAI-PRINT-CUST 1411 50
CAI-PRINT-ORDER 692 29
GEH-PAYROLL 5598 715
GEHTX 199 32
HARRIS 64 9
REQS-PER-FIND 960 46
RWH-TEST1 271 18
TOTAL USER GSMITH
9195 899
Chapter 58: Monitoring Performance 523
Using the Compound Boolean Selection Facility Diagnostics Report
Using the Compound Boolean Selection Facility Diagnostics
Report
The Compound Boolean Selection Facility Diagnostics Report can help you diagnose the efficiency of executing a SELFR command. See the CA Datacom/DB Database and
System Administration Guide for full details on this report. Use the CA Dataquery
Diagnostics Request panel to turn on CBS diagnostics at a terminal. Diagnostics are only collected for the first SELFR command for each table.
When to Use Compound Boolean Selection Facility Diagnostic Report
Use this report when:
■
A query is running slowly. The report can display information to determine if the cause is access to CA Datacom/DB.
■
A query is going to be put into a high-volume production environment. The report can determine if the access to CA Datacom/DB is suitably efficient.
■
Accounting Facility reports indicate that you are experiencing an inefficient execution of SELFR commands.
TYPE OPTIMIZATION......: POPULATION DEPENDENT
You can use this report in two ways:
■
To determine whether CA Dataquery has correctly communicated the request stated in the query to the Compound Boolean Selection Facility. You can look at the
WHERE: columns and can see which WITHs could not be passed to the Compound
Boolean Selection Facility.
■
To determine how the Compound Boolean Selection Facility performed the selection: what keys were used, what keys were not used due to INCLUDE-NIL-KEY, and whether a temporary index was needed. This can show that performance would improve if you add a key or change one to INCLUDE-NIL-KEY=YES, for example.
524 Administration Guide
Chapter 59: Tuning Your System for CA
Dataquery
CA Dataquery performance is not only dependent on how well you tune CA Dataquery within the environment, but also on how well you tune the other components of the environment.
The discussions that follow provide information on tuning.
Tuning CICS
CA Dataquery functions as a short term task that does not issue terminal reads. There are rarely any problems with CA Dataquery contending for CICS resources.
To further enhance efficiency, CA Dataquery allows other tasks to process during the execution of a query. For example, when long searches are required, CA Dataquery periodically relinquishes control so that other tasks can process and allows the user to issue requests to terminate the query.
The MXREQ= and MXTLR= parameters in the System Option Table DQOPTLST macro control the timing of the breaks in control. They set limits that prevent individual users
and queries from monopolizing the system. See
Tailoring the CA Dataquery System
Option Table
(see page 47) for more information.
When a DQL Mode user attempts to access a table, not a CA Dataquery or CA Datacom
Datadictionary table, which is not in a User Requirements Table, CA Dataquery requests
CA Datacom CICS Services (Version 2.4 or higher) to dynamically build and open a User
Requirements Table to access this table. If CA Datacom CICS Services successfully builds and opens this User Requirements Table, CA Dataquery can then access the table. This makes it possible to use DQL Mode to access Personal Database Tables which are not in any User Requirements Table. Tables which are accessed regularly through CA
Dataquery should be in user requirements tables which are assembled and linked for performance and ease of maintenance. See the CA Datacom CICS Services documentation for more information on dynamic User Requirements Tables.
Chapter 59: Tuning Your System for CA Dataquery 525
Tuning the CA Datacom/DB Operating Environment
Tuning the CA Datacom/DB Operating Environment
Multi-User Facility
Some companies can profit from having an additional MUF to handle very heavy batch workloads. They may even wish to put the second MUF on a completely separate CPU.
CA Dataquery can run in batch on this machine.
Coding the CA Datacom/DB MUF startup options appropriately can affect the efficiency of CA Dataquery row searches. In a MUF environment with several applications running at the same time, consider how adjustments to the MUF startup option affect CA
Dataquery and all the active applications. Expect to make trade-offs.
Here are some CA Datacom/DB MUF tuning recommendations:
■
When a query does not specify a key, CA Dataquery uses the Native Key to search the entire table. To reduce processing time at sites where table type searches are common:
–
Determine which type of indexing will best meet the needs of CA Dataquery users and add the necessary keys.
–
Increase the number of data index buffers and data buffers. (This provides more data per I/O event but increases the transfer time of data and the storage required.)
–
Increase the size specified for the data buffers (DATAPOOL MUF startup option) and the user data table block sizes. (This provides more data per I/O event but increases the transfer time of data and the storage required.)
■
For heavily used systems, provide enough data buffers to keep the data block in storage until CA Dataquery is finished with it.
Data Set Placement
High activity data sets (CA Dataquery tables) should be placed on different
DASD/channels. When analyzing the performance of the active data sets: utilization for disk should be less than 50 percent and utilization for channels should be less than 30 percent. If the percentages are higher than this, you should consider moving the data sets to a different channel.
High activity data sets (CA Dataquery tables) should be placed on separate packs. Often it is advantageous to place them near the center of the pack. This is good for the DQF and DQM tables.
526 Administration Guide
Tuning the CA Datacom/DB Compound Boolean Selection Facility
Tuning the CA Datacom/DB Compound Boolean Selection
Facility
CA Dataquery uses the Compound Boolean Selection Facility to evaluate the row selection criteria specified in the FIND statements of queries. Because of this, search optimization is done dynamically by the Compound Boolean Selection Facility. Each logical expression in a WITH statement is a predicate. The predicates supplied in the query as selection criteria are used to build a Compound Boolean Selection Facility request qualification area (RQA).
When the predicates in a FIND statement refers to columns containing signed numeric data of packed or zoned decimal format, it is important to be as specific as possible in the CA Datacom Datadictionary TYPE-NUMERIC attribute about what sign codes the columns contain. This will allow CA Dataquery to pass this information along to the
Compound Boolean Selection Facility, which in turn allows the Compound Boolean
Selection Facility to evaluate the predicates more efficiently because it restricts the traversal key value range.
For example, if the data contains only positive values with the X'C' sign code, then specify P for this attribute. This attribute must agree with the actual data or incorrect results will be obtained.
Tuning Datadictionary
■
■
Performance suffers unless care has been taken in creating the CA Datacom
Datadictionary definitions that are used by CA Dataquery.
■
Entity-occurrence names should be different for TABLE, KEY, and FIELD entity-occurrences so that CA Dataqueryy can unambiguously resolve references in queries.
■
Choose names that are obvious and meaningful to CA Dataquery users.
■
Each table should have at least one unique key defined for it.
■
No two keys in the same row should have the same value for the KEY-ID.
Equivalent keys in different tables should be defined similarly. That is, the order, length, and type of constituent columns should be the same.
Equivalent fields or keys in different tables should be named the same to avoid confusion and to facilitate relating rows together.
Chapter 59: Tuning Your System for CA Dataquery 527
Tuning the CA Dataquery System Option Table
Tuning the CA Dataquery System Option Table
The following DQOPTLST parameters can be used to tune CA Dataquery performance through the System Option Table.
MXREQ= MXTLR= SRCHLIM=
MFTIME=
SORTPAG=
FNDBLKS=
SORTSYS=
SEQBUFS=
SORTCTG=
Tailoring the CA Dataquery System Option Table
(see page 47) for information about
these parameters.
Tuning Queries
Your queries will run more efficiently if you consider the following suggestions when you build your queries.
Key Usage
Keys minimize processing. Therefore, you can build keys to improve Compound Boolean
Selection Facility performance.
When the predicates of a query uses keys, Compound Boolean Selection Facility can use the CA Datacom/DB index to evaluate the predicates more efficiently and can avoid having to access data rows. When the predicates includes no keys, Compound Boolean
Selection Facility must examine the data rows in the table to evaluate the predicate.
Predicate Structure
Use predicates that can be easily converted to Compound Boolean Selection Facility format. There are predicates that are difficult or impossible to convert to Compound
Boolean Selection Facility format. These are handled by CA Dataquery. The predicates that are not passed to the Compound Boolean Selection Facility are:
■
Predicates in which a key is compared to a value:
–
And the value is masked and the comparison operator is neither equal or not equal
–
And the comparison is for CONTAINING and the key has multiple noncontiguous columns
528 Administration Guide
Tuning Queries
■
■
■
■
■
Predicates in which a column is compared to a value and the value is masked and the comparison operator is neither equal or not equal.
Predicates in which a key is compared to a column and the data type of the column is not character, zoned, or pure double byte characters.
Predicates in which a key is compared to a key and one or both of the keys has noncontiguous component columns and the keys do not have the same number and length of component columns.
Predicates in which a column is compared to a column:
–
And the columns are of different data types
–
And the columns are numeric but have different precisions
Predicates which include an arithmetic expression.
When a predicate that cannot be converted to Compound Boolean Selection Facility format is ANDed to a predicate that can be converted, the predicate that can be converted is passed to Compound Boolean Selection Facility. The predicate that cannot be converted is processed by CA Dataquery and then the results from Compound
Boolean Selection Facility and CA Dataquery are ANDed.
When the predicates are ORed, if any predicate cannot be processed by the Compound
Boolean Selection Facility, none of the ORed predicates can be processed by the
Compound Boolean Selection Facility.
Example:
A FIND statement has three predicates: P1, P2, and P3. P3 cannot be converted to
Compound Boolean Selection Facility format.
■
WITH P1 AND P2 AND P3
In this case, since there are no ORs, P1 and P2 are passed to the Compound
Boolean Selection Facility and P3 is then applied to the result set.
■
WITH P1 AND (P2 OR P3)
In this case, P2 cannot be processed by Compound Boolean Selection Facility along with P3 since they are ORed, so only P1 is passed to the Compound
Boolean Selection Facility. The condition P2 OR P3 is then applied to the result set from Compound Boolean Selection Facility.
Join Column Selection
When two tables are related in a query, they are normally joined by columns or keys in the two rows. When the search is performed, the link column in the table searched secondly is used to create an additional key-value or column-value predicate using a value extracted from the link column of the first table. With CA Dataquery you can join tables when the link column is not a key in either table. This should be done with care because if there are no keyed criteria supplied for the table searched secondly in the relationship, repeated full table searches of that table can be required.
Chapter 59: Tuning Your System for CA Dataquery 529
Tuning Queries
Examples
When multiple tables are related in a query, CA Dataquery does not necessarily search the tables in the order stated. Instead, it determines every possible way that the search can be done, dynamically estimates the cost of each, and selects the lowest cost estimate.
Important! The use of outer joins and disjoins in a query causes the CA Dataquery optimization process to be bypassed. CA Dataquery processes any query containing either an outer join or a disjoin keyword by accessing the database tables in the order they appear within the query. The use of OUTER-JOIN, RIGHT-JOIN, or RIGHT-DISJOIN adds additional time to the processing of the FIND statement since CA Dataquery must read each table named on the "right side" twice to accomplish the join. The use of
LEFT-JOIN or LEFT-DISJOIN does not cause this additional processing.
Usage Procedures
Establish procedures for users to follow to realize resource conservation:
■
For a new query, limit the initial search to test the query and check the results.
For example, this can be done by specifying FIND 20 ROWS instead of FIND ALL
ROWS.
■
Include criteria in the query that uses a key or the first column of a key to limit the scope of the search.
–
When CA Dataquery cannot use keyed access, the entire table is read sequentially.
–
Make users aware of the DISPLAY command as a tool to display key definitions.
P1
P2
P3
P4
P5
The following examples illustrate how typical queries are processed.
Predicate Type Qualified for Compound Boolean Selection
Facility
Field-Value
Key-Value
Key-Value
Key-Value
Key-Field
YES
YES
YES
NO
YES
530 Administration Guide
Tuning Queries
Example 1
Query text:
FIND TABLE1
Results:
Compound Boolean Selection Facility accesses the Native Key index sequentially.
Every row ID is returned to CA Dataquery.
In this case, since no predicates at all are supplied, Compound Boolean Selection Facility simply reads the Index for TABLE1 and returns the row IDs to CA Dataquery. Data rows are not accessed.
Example 2
Query text:
FIND TABLE1 WITH P1
Results:
Compound Boolean Selection Facility reads each data row in Native Key sequence to evaluate P1.
Compound Boolean Selection Facility returns the IDs of qualifying rows to CA
Dataquery.
In this case, a nonindexed predicate is passed to Compound Boolean Selection, so it must read the rows in the CA Datacom/DB region to determine which qualify. No data rows are passed to the CA Dataquery region. This requires a full table search in the
Compound Boolean Selection Facility region.
Example 3
Query text:
FIND TABLE1 WITH P2
Results:
Compound Boolean Selection Facility uses the Index to locate entries that satisfy
P2.
Compound Boolean Selection Facility returns the IDs of qualifying rows to CA
Dataquery.
In this case, an indexed predicate is passed to Compound Boolean Selection, so it can evaluate P2 without accessing data rows.
Chapter 59: Tuning Your System for CA Dataquery 531
Tuning Queries
Example 4
Query text:
FIND TABLE1 WITH P5
Results:
Compound Boolean Selection Facility reads each data row to evaluate P5.
Compound Boolean Selection Facility returns the IDs of qualifying rows to CA
Dataquery.
In this case, an indexed predicate is passed to Compound Boolean Selection, but the indexed item is compared to another column in the row, rather than to a literal value.
Data rows must be read in the Compound Boolean Selection Facility region to evaluate
P5. Data rows are not passed to the CA Dataquery region. This requires a full table search in the Compound Boolean Selection Facility region.
Example 5
Query text:
FIND TABLE1 WITH P3 AND P4
Results:
Compound Boolean Selection Facility uses the Index to locate entries satisfying P3.
Compound Boolean Selection Facility passes the data rows for these entries to CA
Dataquery.
CA Dataquery evaluates P4 using the data rows.
In this case, an indexed predicate is passed to Compound Boolean Selection, and another indexed but nonqualifying predicate ANDed with the first causes CA Dataquery to have to examine the data rows that satisfied P3 in order to evaluate P4.
532 Administration Guide
Tuning Queries
Example 6
Query text:
FIND TABLE1 WITH P2 OR P3
Results:
Compound Boolean Selection Facility uses the Index to locate entries satisfying P2.
Compound Boolean Selection Facility uses the Index to locate entries satisfying P3.
Compound Boolean Selection Facility builds a temporary index to eliminate duplicate values.
Compound Boolean Selection Facility passes the qualifying IDs to CA Dataquery.
In this case, two ORed indexed predicates are passed to the Compound Boolean
Selection Facility. Compound Boolean Selection Facility uses the Index to locate entries that qualify for each predicate, and a special temporary index to eliminate the duplicates. No data rows are accessed by the Compound Boolean Selection Facility or CA
Dataquery.
Example 7
Query text:
FIND TABLE1 WITH P3 OR P4
Results:
Compound Boolean Selection Facility passes all data rows to the CA Dataquery region.
CA Dataquery evaluates P3 or P4.
In this case, two ORed indexed predicates are used, but one is nonqualifying. Since they are ORed, neither can be passed to the Compound Boolean Selection Facility and a full table search is done in the CA Dataquery region.
Chapter 59: Tuning Your System for CA Dataquery 533
Tuning Queries
Example 8
Query text:
FIND TABLE1 WITH P2 RELATED BY KEY1 TO TABLE2
Results:
Compound Boolean Selection Facility uses the index to locate entries in TABLE1 satisfying P2.
Compound Boolean Selection Facility passes the row IDs and data for these to CA
Dataquery.
Compound Boolean Selection Facility uses the index to locate entries in TABLE2 satisfying the link column predicate.
Compound Boolean Selection Facility passes those row IDs to CA Dataquery.
In this case, two tables, one with a qualifying indexed predicate, are joined. Compound
Boolean Selection Facility can evaluate P2 in the index, but must read and pass to CA
Dataquery the data rows for the entries that satisfy P2 so that CA Dataquery can extract the value needed to build the key-value predicate for KEY1 on TABLE2. Compound
Boolean Selection Facility can then locate the qualifying rows in TABLE2 without accessing its data rows.
534 Administration Guide
Chapter 60: Handling Errors
Error handling is a joint project shared by the CA Dataquery Administrator, the systems programmer, the end user, and you. Your responsibility is to assess those problems that are caused by:
■
System Option Table definitions
■
CA Datacom/DB
■
CA Datacom Datadictionary definitions
■
CA Dataquery system table allocations
■
Database availability
Assessing Errors
With online CA Dataquery, when an error occurs, an error message appears on the message line. You can press <PF1> HELP to get the Help Panel for Error Message. This panel provides an expanded explanation of the message. The information on the Help
Panel for Error Message is designed for the end user.
The CA Dataquery Message Reference Guide provides error messages and explanations of those messages. The explanation included in the guide is more detailed and includes information for each audience that may deal with the error. There are some unnumbered batch error messages also included in that guide.
You can also receive CA Datacom/DB error messages and return codes from CA
Dataquery. These error messages and return codes are described in the CA Datacom/DB
Message Reference Guide.
Message Categories
■
■
The CA Dataquery error messages that you will handle fall into the following general categories:
■
Errors resulting from incorrectly specified System Option Table parameters
■
Errors resulting from problems with CA Datacom/DB (for example, MUF startup option specifications)
■
Errors resulting from CA Datacom Datadictionary definitions (for example, structures not defined)
Errors resulting from system tables not being large enough
Errors resulting from tables not being available
Chapter 60: Handling Errors 535
Assessing Errors
Each of these categories of errors has a suggested method for solving it.
Errors resulting from incorrectly specifying the System Option Table parameters are solved by locating the parameter, specifying the correct value, and reassembling the macro.
Errors resulting from problems with CA Datacom/DB are solved by locating the error message or return code in the CA Datacom/DB Message Reference Guide and following the instructions provided there.
Errors resulting from CA Datacom Datadictionary definitions are solved by locating the
CA Datacom Datadictionary definition, or creating it if needed, and synchronizing the CA
Datacom Datadictionary definition with the needs of CA Dataquery.
Errors resulting from system tables not being large enough are solved by enlarging the tables as described in Preparing and Maintaining the CA Dataquery System Tables.
Errors resulting from tables not being available are solved by determining the table that is not available, determining the reason that the table is not available, and either making the table available or communicating when it will be available.
When the error message directs you to contact CA Datacom support, and if you have a maintenance agreement, you need to do the following:
■
Document the steps that led up to the error.
■
Note the five-character ID of the panel on which the error message appeared.
■
Follow the instructions provided by the online HELP for the message.
When you have gathered all the materials, have one person from your site call support and take responsibility for getting the solution and communicating it. When many people call about a problem it complicates the situation. See the CA Dataquery Message
Reference Guide for further instructions.
536 Administration Guide
Using Diagnostics
Using Diagnostics
Diagnostics is an administrative function that is accessed from the Administrative Menu, but is only used on a request from CA Support.
For example, a user may have written a query that has been edited and validated, but yet does not execute, has performance problems, or gets the wrong results. In some cases, CA Dataquery returns an error message instructing the user to call CA Support. CA
Support may request that you perform diagnostics on the query because they need more information about the query.
The Diagnostic function allows the CA Dataquery Administrator to produce a CA
Dataquery request table, a transaction dump or a module dump, or, in DQL mode, a
Compound Boolean Selection Facility Diagnostic Report.
The diagnostic information contained in the request table shows how the query was coded, which definition it was looking for in CA Datacom Datadictionary, and so on. The
Compound Boolean Selection Facility Diagnostic report shows exactly what CA
Dataquery passed to the Compound Boolean Selection Facility and how the Compound
Boolean Selection Facility interpreted it. This report shows whether CA Dataquery is causing the problem or the Compound Boolean Selection Facility.
SQL Mode diagnostics functions somewhat differently, in that you can request summary, detail, or no messages about query processing.
Using DQL Diagnostics
Using SQL Mode
Diagnostics
(see page 499) for detailed instructions about using the diagnostics facility.
Chapter 60: Handling Errors 537
Download
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement
Key features
Powerful query language
User-friendly interface
Comprehensive set of security features
Flexible and powerful tool for data access and management
Data modification capabilities
Batch processing functionality
Extensive documentation and support resources
Frequently asked questions
CA Dataquery is a software product for querying and modifying data stored in CA Datacom databases.
CA Dataquery offers a powerful query language (DQL), a user-friendly interface, and comprehensive security features. It also includes data modification capabilities, batch processing functionality, and extensive documentation and support resources.
CA Dataquery is used to access, query, and modify data stored in CA Datacom databases. It is a versatile tool that can be used by both casual and experienced users.
