ViaSQL Review Prepared for ASCAP Training ViaSQL Review Prepared for ASCAP Training Liberating Enterprise Data March 4 - 5, 2008

ViaSQL ReviewPrepared for

ASCAP Training

Liberating Enterprise DataLiberating Enterprise Data

March 4 - 5, 2008

2

ASCAP Training – Day 2• ViaSQL Data Management & DevelopmentViaSQL Data Management & Development

• Virtual tables in Legacy Data ServerVirtual tables in Legacy Data Server• Creating virtual tables using Legacy Data Manager Creating virtual tables using Legacy Data Manager

(LDM)(LDM)• Legacy Data Server / Manager featuresLegacy Data Server / Manager features• Legacy Data Manager administrative functionsLegacy Data Manager administrative functions• RSP development and testingRSP development and testing• Sybase ASE IntegrationSybase ASE Integration• Accessing ViaSQL using Visual Basic Accessing ViaSQL using Visual Basic • TroubleshootingTroubleshooting

3

Virtual Tables in Legacy Data Server

• Virtual tableVirtual table• An LDS object that is maintained in the LDS An LDS object that is maintained in the LDS

catalog and defines a single relational view of non-catalog and defines a single relational view of non-relational data stored in VSAM or DL/Irelational data stored in VSAM or DL/I

• The relational data model can be The relational data model can be described as:described as:

a collection of 2-dimensional tables, where each a collection of 2-dimensional tables, where each table has a specific number of columns, unordered table has a specific number of columns, unordered rows, and a specific item of data at the intersection rows, and a specific item of data at the intersection of every column and rowof every column and row

4

Virtual Tables in Legacy Data Server (Cont’d)

• A VSAM file or DL/I segment may contain A VSAM file or DL/I segment may contain data that are non-relational in several data that are non-relational in several aspects, among them:aspects, among them:• VSAM files and DL/I segments are maintained in a VSAM files and DL/I segments are maintained in a

specific sequence: key or index sequence, entry specific sequence: key or index sequence, entry sequence, chained-pointer sequence, etc.sequence, chained-pointer sequence, etc.

• Multiple record types may be stored in the same Multiple record types may be stored in the same VSAM file or DL/I segmentVSAM file or DL/I segment

• A VSAM record or DL/I segment may contain an A VSAM record or DL/I segment may contain an arrayarray

5


• Virtual table definitions are stored in the Virtual table definitions are stored in the LDS catalog on VSELDS catalog on VSE• LDS catalog consists of a series of VSAM data LDS catalog consists of a series of VSAM data

sets used exclusively by LDS for this purposesets used exclusively by LDS for this purpose• LDS catalog contents may be directly queried by LDS catalog contents may be directly queried by

ViaSQL clients using SQL statements that ViaSQL clients using SQL statements that reference the following tables:reference the following tables:

SYSTEM.SYSKEYSSYSTEM.SYSOPTIONSSYSTEM.SYSTABAUTHSYSTEM.SYSUSERAUTHSYSTEM.SYSVIEWDEP (*NEW*)SYSTEM.SYSVIEWS (*NEW*)

SYSTEM.SYSCATALOGSYSTEM.SYSCOLAUTHSYSTEM.SYSCOLUMNSSYSTEM.SYSDLISYSTEM.SYSFILTERSSYSTEM.SYSINDEXESSYSTEM.SYSKEYCOLS

6


• LDS virtual table attributesLDS virtual table attributes• Unique identity for the virtual tableUnique identity for the virtual table

• Creator (required but may be defaulted)• Name (required)

• Datasource (required)Datasource (required)• For VSAM: the DLBL filename• For DL/I: DBD name + PSB name + segment

name

7


• LDS virtual table attributes (Cont’d)LDS virtual table attributes (Cont’d)• Data type (required)Data type (required)

• VSAM –VSAM file accessed from the LDS partition (native VSAM)

• CICS – VSAM file accessed from the CICS partition (CICS VSAM)

• DLI – DL/I segment• Also supported:

– SAMD (sequential disk) – SAMT (sequential tape)– RSP to describe results returned by an RSP

8


• LDS virtual table attributes (Cont’d)LDS virtual table attributes (Cont’d)• Type of access (required)Type of access (required)

• R – readonly access (does not support INSERT, UPDATE, or DELETE requests)

• U – update access (supports INSERT, UPDATE, and DELETE requests)

• Record-level exit name (optional)Record-level exit name (optional)• Nullability options for:Nullability options for:

• All DATE columns in virtual table (required)• All DECIMAL/NUMERIC columns in virtual table

(required)• All CHAR columns in virtual table (required)

9


• LDS virtual table attributes (Cont’d)LDS virtual table attributes (Cont’d)• (*NEW*) Remote system ID (used only for CICS (*NEW*) Remote system ID (used only for CICS

and DLI Filetypes)and DLI Filetypes)• (*NEW*) Required key specifications:(*NEW*) Required key specifications:

• Apply only to VSAM, CICS, and DLI File Types• For SELECT requests (required)• For UPDATE requests (required)• For DELETE requests (required)

10


• LDS virtual table attributes (Cont’d)LDS virtual table attributes (Cont’d)• For each data column:For each data column:

• Column name (required)• SQL datatype (required)• Offset of value within the record or segment

(required, but calculated by LDM)

11


• For each data column (cont’d):For each data column (cont’d):• Qualifier – use dependent on SQL datatype

– For CHAR, VARCHAR, LNGVCHAR, BINARY, VARBIN, LNGVBIN, GRAPHIC:

» Length (required)– For DECIMAL and NUMERIC

» Precision, scale (required)– For DATE, TIME:

» Template (optional)– For others

» Not used

12


• For each data column (Cont’d):For each data column (Cont’d):• WithValue (optional, value that identifies subset

of records/segments that satisfy this condition)• ODO – value assigned by Legacy Data

Manager when mapping records with “occurs depending on” clause

• Column exit – name of column exit used to customize access to this column (*NEW*)

• Comments – descriptive text only, not used in ViaSQL processing

13

Creating Virtual Tables using Legacy Data Manager

• Requirements for creating virtual tablesRequirements for creating virtual tables• Creating a virtual table from COBOL copybookCreating a virtual table from COBOL copybook• Viewing data using a virtual table from LDMViewing data using a virtual table from LDM• Handling DL/I secondary indexes in virtual tablesHandling DL/I secondary indexes in virtual tables• Handling REDEFINES structures in virtual tablesHandling REDEFINES structures in virtual tables• Handling OCCURS n TIMES structures in virtual Handling OCCURS n TIMES structures in virtual

tablestables• Handling OCCURS DEPENDING ON structures in Handling OCCURS DEPENDING ON structures in

virtual tablesvirtual tables

14

Creating Virtual Tables using LDM (Cont’d)

• Requirements for creating virtual tablesRequirements for creating virtual tables• Legacy Data Manager (LDM) must be installed on Legacy Data Manager (LDM) must be installed on

a workstation with connectivity to Legacy Data a workstation with connectivity to Legacy Data Server on VSEServer on VSE

• The targeted data source(s) must be defined on The targeted data source(s) must be defined on the VSE system and accessible to Legacy Data the VSE system and accessible to Legacy Data ServerServer

• If a COBOL or PL/I copybook is to be accessed If a COBOL or PL/I copybook is to be accessed from LDM for creating a virtual table, then the VSE from LDM for creating a virtual table, then the VSE sublibrary containing the copybook must be made sublibrary containing the copybook must be made available to the LDS partition using the VSE available to the LDS partition using the VSE LIBDEF JCL statementLIBDEF JCL statement

15


• Creating a virtual table from a COBOL Creating a virtual table from a COBOL copybookcopybook• Start LDM on the workstation and connect to the Start LDM on the workstation and connect to the

ODBC DSN defined for the LDS system in which ODBC DSN defined for the LDS system in which the virtual table will be storedthe virtual table will be stored

• Click the Libraries iconClick the Libraries icon• Highlight the VSE sublibrary containing the desired Highlight the VSE sublibrary containing the desired

copybook and click the Members buttoncopybook and click the Members button• Highlight the desired copybook and click the Highlight the desired copybook and click the

MemberData buttonMemberData button• Double-click on the 01 record or the first numbered Double-click on the 01 record or the first numbered

recordrecord

16


• Create a virtual table from a COBOL Create a virtual table from a COBOL copybook (cont’d)copybook (cont’d)• LDM will prepare column definitions for the fields LDM will prepare column definitions for the fields

defined in the copybook and place them in a new defined in the copybook and place them in a new Virtual Table Definition panel in LDM. The contents Virtual Table Definition panel in LDM. The contents of the Virtual Table Definition panel may now be of the Virtual Table Definition panel may now be modified as necessary to satisfy your requirements modified as necessary to satisfy your requirements for the new virtual table. for the new virtual table.

The “help” key (F1) can be used to display context-The “help” key (F1) can be used to display context-sensitive help for each of the fields contained in the sensitive help for each of the fields contained in the Virtual Table Definition panel.Virtual Table Definition panel.

17


• Create a virtual table from a COBOL copybook Create a virtual table from a COBOL copybook (cont’d)(cont’d)• After all three tabs of the Virtual Table Definition panel have After all three tabs of the Virtual Table Definition panel have

been completed and you are ready to save the virtual table been completed and you are ready to save the virtual table definition in the LDS catalog,definition in the LDS catalog,

• Click the Create Def button.• LDM will now attempt to retrieve information from the VSE LDM will now attempt to retrieve information from the VSE

system pertinent to the File Type specified, including: VSAM system pertinent to the File Type specified, including: VSAM DSORG, index, and cluster name definitions, DL/I segment DSORG, index, and cluster name definitions, DL/I segment structures, and CICS file access attributes. If this information structures, and CICS file access attributes. If this information retrieval process is successful and the retrieved information retrieval process is successful and the retrieved information agrees with the virtual table definition, then the virtual table agrees with the virtual table definition, then the virtual table definition is stored in the LDS catalog and “Created” is definition is stored in the LDS catalog and “Created” is displayed back on the Virtual Table Definition panel in the displayed back on the Virtual Table Definition panel in the lower left corner.lower left corner.

18


• Viewing Data using a virtual table with LDMViewing Data using a virtual table with LDM• Start LDM on the workstation and connect to the ODBC DSN Start LDM on the workstation and connect to the ODBC DSN

defined for the LDS system in which the virtual table will be defined for the LDS system in which the virtual table will be storedstored

• Click the Tables iconClick the Tables icon• Highlight the desired virtual table and click the Data buttonHighlight the desired virtual table and click the Data button• (*NEW*) LDM will display the Select Data panel containing a (*NEW*) LDM will display the Select Data panel containing a

proposed SELECT * statement to retrieve the TOP 50 rows proposed SELECT * statement to retrieve the TOP 50 rows from the selected table. This SELECT statement may be from the selected table. This SELECT statement may be modified by the user as needed. To proceed with issuing the modified by the user as needed. To proceed with issuing the modified SELECT statement, click the Get Data buttonmodified SELECT statement, click the Get Data button

• The appropriate SELECT statement will be submitted to LDS The appropriate SELECT statement will be submitted to LDS and the results displayed on a grid panel at the LDM and the results displayed on a grid panel at the LDM workstationworkstation

19


• Handling DL/I Secondary Indexes in Virtual TablesHandling DL/I Secondary Indexes in Virtual Tables• Define the virtual table columns using the target segment Define the virtual table columns using the target segment

definition for the secondary indexdefinition for the secondary index• Specify the following information in the DL/I Segments section Specify the following information in the DL/I Segments section

of the General tab on the Virtual Table Definition tab:of the General tab on the Virtual Table Definition tab:PSB:

any PSB that includes a suitable PCB for accessing the database using the specified secondary index

DBD: if ACCESS=HD defined for the database, use the REF= parameter value defined in the ACCESS macro for the secondary indexif ACCESS=HDAM or ACCESS=HIDAM defined for the database, use the INDEX= parameter value defined in the LCHILD macro for the secondary index

• Code SQL statements to use the virtual table defined with the Code SQL statements to use the virtual table defined with the desired secondary indexdesired secondary index

20


• Handling REDEFINES structures in Virtual Handling REDEFINES structures in Virtual TablesTables• A REDEFINES structure in a COBOL copybook A REDEFINES structure in a COBOL copybook

reflects the use of multiple record types in the reflects the use of multiple record types in the associated fileassociated file

• To enable correct access to a REDEFINES file To enable correct access to a REDEFINES file structure by LDS, structure by LDS,

• Define one virtual table for each record type in the file

• In each virtual table definition involved, use a filter condition to uniquely identify records of that record type

21


• Handling OCCURS n TIMES structures in Virtual TablesHandling OCCURS n TIMES structures in Virtual Tables• An OCCURS n TIMES structure in a COBOL copybook reflects the An OCCURS n TIMES structure in a COBOL copybook reflects the

use of an array in the associated fileuse of an array in the associated file• To enable correct access to an OCCURS n TIMES file structure by To enable correct access to an OCCURS n TIMES file structure by

LDS, the user must select to use either “horizontal” or “vertical” LDS, the user must select to use either “horizontal” or “vertical” mapping for the arraymapping for the array

• Horizontal mapping – all items in all rows of the array are mapped to individual columns in the virtual table definition

• Vertical mapping – only a single occurrence of the array is defined in the virtual table definition. When returning rows for the virtual table, each occurrence in the array will be returned in a separate row. The term “occurrence table” is assigned to a virtual table definition which uses vertical mapping. The term “occurrence group” is assigned to the columns that define the array occurrence in the occurrence table

22


• Handling OCCURS n TIMES structures in Virtual Handling OCCURS n TIMES structures in Virtual Tables (Cont’d)Tables (Cont’d)• Defining horizontal mapping in virtual tableDefining horizontal mapping in virtual table

• Note that a virtual table definition is limited to a maximum of 900 columns

• Retrieve the copybook containing the OCCURS n TIMES structure using LDM as described earlier

• Double-click on the 01 record of the associated copybook

• LDM appends a sequential number to the end of the column name involved in the OCCURS n TIMES structure; the sequential number assigned signifies the column’s occurrence value within the underlying array

23


• Handling OCCURS n TIMES structures in Virtual Tables Handling OCCURS n TIMES structures in Virtual Tables (Cont’d)(Cont’d)• Defining vertical mapping in virtual tableDefining vertical mapping in virtual table

• Note the following:– LDS supports only one occurrence group in an occurrence

table– An OCCURRENCE column will be automatically defined as

the last column of the primary key– All ViaSQL applications that refer to the primary key should

handle the OCCURRENCE column in the same manner as other columns in the primary key

– The copybook statement that specifies the OCCURS n TIMES statement cannot include a PICTURE clause

– If the occurrence table is defined for update access, only the columns in the occurrence group can be updated using the occurrence table

– INSERT and DELETE statements are not supported on occurrence tables

24


• Defining vertical mapping in virtual table (Cont’d)Defining vertical mapping in virtual table (Cont’d)• Retrieve the copybook containing the OCCURS

n TIMES structure using LDM as described earlier

• Drag the statement containing the OCCURS statement and drop into the Occurrence Table Group Recnum field located in the lower right corner of the Member Data panel

• Double-click on the 01 record of the associated copybook

25


• Handling OCCURS DEPENDING ON (ODO) Handling OCCURS DEPENDING ON (ODO) structures in Virtual Tablesstructures in Virtual Tables• LDS requirements for supporting ODO structures:LDS requirements for supporting ODO structures:

• Not supported for DL/I data sources• Count field referenced in the ODO clause must be

positioned in the record prior to the ODO fields• Count field referenced in the ODO clause must be one of

the following datatypes: INTEGER, SMALLINT, NUMERIC, DECIMAL, PACKED DECIMAL, or CHAR containing numeric value

• DECIMAL or NUMERIC count fields must be defined with precision <= 15 and scale = 0

• Length of the ODO information generated LDM for appending to the column name cannot exceed 16 characters (this restricts use of nesting levels defined within ODO structures)

26


• Handling ODO structures in Virtual Tables Handling ODO structures in Virtual Tables (Cont’d)(Cont’d)• An ODO structure in a COBOL copybook may An ODO structure in a COBOL copybook may

reflect either:reflect either:• the use of an array in the associated file (termed

Type A), as in:… OCCURS 10 TO 50 TIMES DEPENDING ON

COUNTER PIC X(4).-or-

• a variable length field (termed Type B), as in:… OCCURS 0 TO 20 TIMES

DEPENDING ON FLD-LENGTH PIC X.

27


• Handling ODO structures in Virtual Tables Handling ODO structures in Virtual Tables (Cont’d)(Cont’d)• ODO Type A mappingODO Type A mapping

• may use vertical or horizontal mapping• If horizontal mapping,

– Handled like OCCURS n TIMES support using the maximum ODO value. For example, if the ODO term is OCCURS 10 TO 50 TIMES DEPENDING ON COUNTER, then the maximum ODO value is 50 and LDM will generate column definitions the same as OCCURS 50 TIMES using horizontal mapping.

– Default values will be returned in the columns assigned to fields which do not exist in a record

28


• Handling ODO structures in Virtual Tables Handling ODO structures in Virtual Tables (Cont’d)(Cont’d)• ODO Type B mappingODO Type B mapping

• LDM creates a single column, setting the column length to the maximum ODO value

• For CHAR columns, the column is padded with blanks as needed whenever returned by LDS to a ViaSQL client

29

Legacy Data Server/Manager Features

• Defining and Using Virtual indexesDefining and Using Virtual indexes• Defining and Using FiltersDefining and Using Filters• Record-level exitsRecord-level exits• Column exitsColumn exits• User and data access privilegesUser and data access privileges

30

LDS/LDM Manager Features (Cont’d)

• Defining and Using Virtual IndexesDefining and Using Virtual Indexes• Virtual indexes are only supported in LDS for Virtual indexes are only supported in LDS for

accessing VSAM data sourcesaccessing VSAM data sources• A virtual table may be have multiple virtual indexes A virtual table may be have multiple virtual indexes

defined for itdefined for it• A virtual index definition is associated with one and A virtual index definition is associated with one and

only one virtual tableonly one virtual table• When resolving SQL requests that will be When resolving SQL requests that will be

accessing VSAM data, LDS optimizes this access accessing VSAM data, LDS optimizes this access by using any appropriate primary or virtual index by using any appropriate primary or virtual index defined in the LDS catalog for the VSAM dataset defined in the LDS catalog for the VSAM dataset involvedinvolved

31


• Defining and Using Virtual Indexes Defining and Using Virtual Indexes (Cont’d)(Cont’d)• LDS automatically discovers any VSAM primary LDS automatically discovers any VSAM primary

index defined for a VSAM KSDS data set when a index defined for a VSAM KSDS data set when a virtual table referencing that VSAM data set is virtual table referencing that VSAM data set is created; LDS saves this information in the LDS created; LDS saves this information in the LDS catalog with the virtual table definitioncatalog with the virtual table definition

• Three types of virtual indexes are supported in Three types of virtual indexes are supported in LDS: LDS:

• VSAM alternate index • LDS normal user index• LDS partial user index

32


• Defining and Using Virtual Indexes Defining and Using Virtual Indexes (Cont’d)(Cont’d)• Requirements for using VSAM alternate index Requirements for using VSAM alternate index

(AIX) as LDS virtual index:(AIX) as LDS virtual index:• a virtual index must be explicitly defined to LDS

using the Index Definition panel in LDM• The AIX must be referenced in a VSAM PATH

defined to the VSAM base cluster involved• The VSAM PATH must be accessible to LDS

partition using same File Type (VSAM or CICS) as defined for LDS access to the base cluster

33


• Defining and Using Virtual Indexes (Cont’d)Defining and Using Virtual Indexes (Cont’d)• Requirements for using an LDS user index (normal or Requirements for using an LDS user index (normal or

partial):partial):• The user index must be a VSAM KSDS file• User index data must be maintained in the KSDS file by

another application; LDS will not maintain user index data for INSERT, UPDATE, DELETE activity on the target VSAM dataset

• The user index must be explicitly defined to LDS using the Index Definition panel in LDM

• The VSAM dataset containing the user index must be accessible to LDS partition using same File Type (VSAM or CICS) as defined for LDS access to the target VSAM dataset

34


• Requirements for using an LDS user index (normal or partial) Requirements for using an LDS user index (normal or partial) (cont’d):(cont’d):

• If the target VSAM dataset is an ESDS file, then the user index records must contain the RBA of the associated record in the target ESDS file

• If the target VSAM dataset is an RRDS file, then the user index records must contain the RRN of the associated record in the target RRDS file

• If the target VSAM dataset is a KSDS file, then the user index records must contain the primary key of the associated record in the target KSDS file

• The primary key of the user index KSDS file must consist entirely of columns defined in the target VSAM dataset

35


• Defining and Using Virtual Indexes (Cont’d)Defining and Using Virtual Indexes (Cont’d)• Defining a user index on the Index Definition panelDefining a user index on the Index Definition panel

• Start LDM on the workstation and connect to the ODBC DSN defined for the LDS system in which the virtual index definition will be stored

• Click the Index Def icon• Complete the fields on the Virtual Index Definition panel.

The “help” key (F1) can be used to display context-sensitive help for each of the fields contained in the Virtual Index Definition panel. When completed:

– Click the Create Def button.

36


• Defining and Using FiltersDefining and Using Filters• A filter is an optional virtual table attribute that consists of a A filter is an optional virtual table attribute that consists of a

where clause. The where clause limits the data defined by where clause. The where clause limits the data defined by the associated virtual table.the associated virtual table.

• A virtual table definition can have no more than one filterA virtual table definition can have no more than one filter• Any SELECT, INSERT, UPDATE or DELETE statement Any SELECT, INSERT, UPDATE or DELETE statement

referencing a virtual table with a filter will be limited to referencing a virtual table with a filter will be limited to affecting/returning only those rows that are qualified by the affecting/returning only those rows that are qualified by the filterfilter

• A filter can only reference columns that exist in the A filter can only reference columns that exist in the associated virtual table definition and constant valuesassociated virtual table definition and constant values

• All columns referenced in a filter must be fully qualified with All columns referenced in a filter must be fully qualified with the creator and table namethe creator and table name

37


• Defining and Using Filters (Cont’d)Defining and Using Filters (Cont’d)• To add a filter to an existing Virtual Table defintionTo add a filter to an existing Virtual Table defintion

• Start LDM on the workstation and connect to the ODBC DSN defined for the LDS system in which the virtual table definition is stored

• Click the Tables icon• Highlight the virtual table definition to which the filter will

be added and click the Filters button• Complete the fields on the Virtual Table Filters panel.

The “help” key (F1) can be used to display context-sensitive help for each of the fields contained on this panel. When completed:

– Click the Create/Update Filter button.

38


• Record-level exitsRecord-level exits• Customer-written programs invoked by LDS during VSAM record or Customer-written programs invoked by LDS during VSAM record or

DL/I segment processingDL/I segment processing• Used to perform local customization of record contents at run-time Used to perform local customization of record contents at run-time

in LDSin LDS• Invoked at pre-defined exit points in LDS, which include but are not Invoked at pre-defined exit points in LDS, which include but are not

limited to:limited to:• Pre-open (POPN0001), Post-open (POPN0006)• Pre-read (GNXT0004), Post-read (GNXT0005)• Pre-write (PUT00004), Post-write (PUT00005)• Pre-close (PCLO0001), Post-close (PCLO0008)

• Defining record-level exit in the virtual table definitionDefining record-level exit in the virtual table definition• Specified on the Virtual Table Definition panel, General tab, in

the User Exit field• only those virtual tables containing the record-level exit

parameter will invoke the exit when processing the underlying VSAM file or DL/I segment

39


• Record-level exits (Cont’d)Record-level exits (Cont’d)• Typical uses of record-level exits:Typical uses of record-level exits:

• Expanding compressed data after reading, before processing by LDS

• Compressing data before writing, after LDS record processing is complete

• Transforming individual fields in the record to LDS-recognizable values, for example changing locally-customized date formats to MMDDYY format usable by LDS

• access unsupported file types

40


• Record-level exits (Cont’d)Record-level exits (Cont’d)• RequirementsRequirements

• Must be coded in assembler• Must be reentrant• Linked PHASE must be stored in VSE sublibrary that is

accessible to LDS via LIBDEF PHASE, SEARCH= definition

• Samples provided in the ViaSQL distribution media stored in Samples provided in the ViaSQL distribution media stored in the LDS VSE sublibrary the LDS VSE sublibrary

• RecommendationRecommendation• Contact Viaserv technical support for assistance during

research stage of record-level exits (before you begin designing, coding, and testing)

41


• Column exits (*NEW*)Column exits (*NEW*)• Customer-written programs invoked by LDS during column Customer-written programs invoked by LDS during column

processing of virtual tableprocessing of virtual table• Used to perform local customization of specific column Used to perform local customization of specific column

contents at run-time in LDScontents at run-time in LDS• Invoked at pre-defined exit points in LDS, which include:Invoked at pre-defined exit points in LDS, which include:

• OPEN0001 - prepare SQL request that references the associated column

• CLOS0008 - terminate SQL request that references the associated column

• GNXT0005 – after column is read, before SQL processing in LDS

• PUT00004 – before column is written, after SQL processing completed by LDS

• PNT00004 – before column data is prepared for key processing in a positioning request, after SQL processing completed by LDS

42


• Column exits (Cont’d)Column exits (Cont’d)• Defining column exit in the virtual table definitionDefining column exit in the virtual table definition

• Specified on the Virtual Table Definition panel, Columns tab, in the ColExit column

• Typical uses of column exits:Typical uses of column exits:• Support locally-customized date and time formats stored

in the VSAM record or DL/I segment• Combine subsets of VSAM record or DL/I segment

contents into a single column entity for LDS SQL processing

• Provide a column entity for LDS SQL processing that contains result of complex computation involving other VSAM record or DL/I segment contents

43


• Column exits (Cont’d)Column exits (Cont’d)• RequirementsRequirements

• Must be coded in assembler• Must be reentrant• Linked PHASE must be stored in VSE sublibrary that is

accessible to LDS via LIBDEF PHASE, SEARCH= definition

• Samples provided in the ViaSQL distribution media stored in Samples provided in the ViaSQL distribution media stored in the LDS VSE sublibrary the LDS VSE sublibrary

• RecommendationRecommendation• Contact Viaserv technical support for assistance during

research stage of record-level exits (before you begin designing, coding, and testing)

44


• User and data access privilegesUser and data access privileges• LDS internal security based on the userid provided by the LDS internal security based on the userid provided by the

client application (the client userid)client application (the client userid)• The special client userid CONSOLE is applied to any SQL The special client userid CONSOLE is applied to any SQL

requests submitted to LDS from the VSE consolerequests submitted to LDS from the VSE console• Maintained using the LDM-GRANT icon or GRANT/REVOKE Maintained using the LDM-GRANT icon or GRANT/REVOKE

SQL statements (requires DBA SQL statements (requires DBA or DBCor DBC privilege) privilege)• LDS internal security controls:LDS internal security controls:

• User privileges – who can access LDS• Table privileges – who can access specific virtual tables

defined in LDS and what they can do (SELECT, INSERT, UPDATE, DELETE)

• Privileges maintained in LDS catalog

45


• User and data access privileges (Cont’d)User and data access privileges (Cont’d)• User privileges – who can access LDSUser privileges – who can access LDS

• Maintained in SYSTEM.SYSUSERAUTH table in LDS catalog

• Does not include any password protection – if password protection is required, then the client userids must be verified in CICS/VSE

• Three levels of user privilege– CONNECT privilege– DBA privilege – (*NEW*) DBC privilege, who can administer LDS

virtual table and virtual index definitions

46

LDS/LDM Manager Features (Cont’d)• User privileges (cont’d)User privileges (cont’d)

• CONNECT privilege– Controls which client userids are allowed to connect

to LDS– If CONNECT authority has been permitted to

ALLUSERS, then anyone can connect to LDS– If ALLUSERS have *not* been permitted CONNECT

authority, then each client userid to be allowed CONNECT authority must be specifically GRANTed CONNECT, DBA, or DBC authority

– CONNECT authority implies access to any tables and/or columns that have been permitted with PUBLIC access

47


• DBA privilege– Implies CONNECT and full DBC authority– Controls specific access to the following functions

» configuring LDS using the LDM – CONFIG icon» Maintaining all table privileges» Maintaining all user privileges, including

GRANT/REVOKE DBA» LDSEXEC LDS@CMD statements in LDS (used

to display/manage LDS enviroment, such as open/close files, kill tasks, etc.)

48


• DBC privilege (*NEW*)– Implies CONNECT authority– Controls specific access to the following functions

» Selective management of data access privileges using LDM only. Control is defined by USE_OWNER permissions to select table creators and READ/READWRITE access to the underlying file or segment.

» LDSEXEC LDS@CMD statements in LDS, except for those functions that display LDS storage, MANAGE_SYSTEM, and MANAGE_TASK

49


• User and data access privileges (Cont’d)User and data access privileges (Cont’d)• Data access privileges – who can access specific virtual Data access privileges – who can access specific virtual

tables and what they can dotables and what they can do• May be granted or revoked by:

– The virtual table owner– (*NEW*) A DBC with suitable permissions to DBC

functions on the virtual table, when using LDM. – Any DBA

• Data access privileges may be granted to specific client userids or to PUBLIC

• If a data access privilege has been permitted to PUBLIC, then anyone with CONNECT authority will be permitted the access defined by that privilege

• Two levels of data access privilege– Table privileges– Column privileges

50


• Data access privileges (Cont’d)Data access privileges (Cont’d)• Table privileges

– Maintained in SYSTEM.SYSTABAUTH– may qualify access to the virtual table using any

combination of the following SQL statements» SELECT» INSERT » UPDATE» DELETE

– INSERT, UPDATE, and DELETE table privileges will not override any READONLY access defined for a virtual table

– During ViaSQL installation, SELECT access to the LDS catalog tables is granted to PUBLIC

51

LDS/LDM Manager Features (Cont’d)• Data access privileges (Cont’d)Data access privileges (Cont’d)

• Column privileges– Maintained in SYSTEM.SYSCOLAUTH– may qualify access to specific columns in the virtual

table using any combination of the following SQL statements

» SELECT» UPDATE

52

LDM Troubleshooting Features

• View VSAM files and DL/I segments with View VSAM files and DL/I segments with their attributestheir attributes

• Open and close VSAM files and DL/I Open and close VSAM files and DL/I segmentssegments

• View LDS subtask activityView LDS subtask activity• Kill an active LDS subtaskKill an active LDS subtask

53

LDM Troubleshooting Features (Cont’d)

• View VSAM files and DL/I segments with View VSAM files and DL/I segments with their attributestheir attributes• LDM lists of VSAM files and DL/I segments are LDM lists of VSAM files and DL/I segments are

limited to those files/segments that are currently limited to those files/segments that are currently “allocated” in LDS“allocated” in LDS

• “allocated” used here to define those files/segments for which LDS has storage control blocks allocated which define LDS access to the file/segment

54


• View VSAM files and DL/I segments (cont’d) View VSAM files and DL/I segments (cont’d) • To obtain list of native VSAM files allocated in LDS:To obtain list of native VSAM files allocated in LDS:

• use the LDM-ADMIN icon• select the VSAM Info Options button corresponding to

the desired level of information. The most used options are:

– Summary – includes ACB name, ACB open/closed status, enabled/disabled status, VSAM string counts

– Defines - includes ACB name, readonly status, DSORG, record length, key information, and dataset name

• Click the Display VSAM File Info button

55


• View VSAM files and DL/I segments (cont’d) View VSAM files and DL/I segments (cont’d) • To obtain list of CICS VSAM files allocated in LDS:To obtain list of CICS VSAM files allocated in LDS:

• use the LDM-CICS ADM icon• select the CICS File Info Options button corresponding to


– Summary – includes CICS FCT name, open/closed status of the file allocation IN LDS (not CICS), enabled/disabled status, LDS string counts (*not* the CICS VSAM file string counts)

– Defines - includes CICS FCT name readonly status, DSORG, record length, key information, and dataset name

• Click the Display CICS File Info button

56


• View VSAM files and DL/I segments (cont’d) View VSAM files and DL/I segments (cont’d) • To obtain list of DL/I segments allocated in LDS:To obtain list of DL/I segments allocated in LDS:

• use the LDM-DL/IADM icon• select the DL/I Info Options button corresponding to the

desired level of information. The most used options are:– Summary – includes PSB name, DBD name, Segment

name, DBD organization, open/closed status of the file allocation IN LDS (not CICS), enabled/disabled status, updateable status, and current use count in LDS

– Seg Map - lists segment maps for currently allocated DL/I segments in LDS; includes PSB name, DBD name, target segment name, segment level of the segment detail that follows, segment name, segment length, key info for that segment

• Click the Display DL/I Segment Info button

57


• Open and close VSAM files and DL/I segments Open and close VSAM files and DL/I segments (Cont’d)(Cont’d)• Successful CLOSE of an OPEN VSAM file or DL/I segment Successful CLOSE of an OPEN VSAM file or DL/I segment

in LDS results in the file/segment being placed in CLOSED + in LDS results in the file/segment being placed in CLOSED + DISABLED state. Any SQL request attempting to access a DISABLED state. Any SQL request attempting to access a CLOSED + DISABLED file or segment will be failed with the CLOSED + DISABLED file or segment will be failed with the appropriate error. appropriate error.

To reOPEN a CLOSED + DISABLED file or segment in LDS, To reOPEN a CLOSED + DISABLED file or segment in LDS, use one of the following command sequences:use one of the following command sequences:

• RECYCLE• First DEALLocate, then OPEN or ALLOCate

58


• Open and close VSAM files and DL/I segments Open and close VSAM files and DL/I segments (Cont’d)(Cont’d)• To modify the OPEN/CLOSE state of a native VSAM file To modify the OPEN/CLOSE state of a native VSAM file

allocated in LDS:allocated in LDS:• use the LDM-ADMIN icon• Enter the ACB name of the VSAM file involved in the File

field below the Manage VSAM Files button. • Select the appropriate File Options button for the function

to be performed (Open, Close, etc)• If Open, Alloc, or Recycle is selected, you may specify

new values for Open Options and Nstrings• Click the Manage VSAM Files button to perform the

requested function; a Results grid will be displayed reporting success or failure of the request

59


• Open and close VSAM files and DL/I segments Open and close VSAM files and DL/I segments (Cont’d)(Cont’d)• To modify the OPEN/CLOSE state of a CICS VSAM file To modify the OPEN/CLOSE state of a CICS VSAM file

allocated in LDS:allocated in LDS:• use the LDM-CICS ADM icon• Enter the CICS FCT name of the file involved in the File

DDName below the Manage CICS Files button. • Select the appropriate File Options button for the function

to be performed (Open, Close, etc)• If Open, Allocate, or Recycle is selected, you may

specify new values for Open Options and Nstrings• Click the Manage CICS Files button to perform the


60


• Open and close VSAM files and DL/I segments Open and close VSAM files and DL/I segments (Cont’d)(Cont’d)• To modify the OPEN/CLOSE state of a DL/I segment To modify the OPEN/CLOSE state of a DL/I segment

allocated in LDS:allocated in LDS:• use the LDM-DL/I ADM icon• Enter the PSB Name, DBD Name, and SEG Name

identifying the desired DL/I segment involved. • Select the appropriate Options button for the function to

be performed (Open, Close, etc)• Click the Manage DL/I Segment button to perform the


61


• View LDS subtask activityView LDS subtask activity• To obtain list of subtasks in the LDS partition:To obtain list of subtasks in the LDS partition:

• use the LDM-ADMIN icon• You may optionally enter a qualifying string in the Task

Name to limit the subtasks included in the result list• select the Display Task Options button corresponding to


– Summary – includes subtask name, task status, associated CICS task# (if any), and client userid

– Short - includes subtask name, task status, and current subtask PSW from the task savearea

• Click the Display/Manage Tasks button to display the Manage Tasks panel which includes the result list

• To refresh the results in the Manage Tasks panel, click the Refresh button

62


• Kill an active LDS subtaskKill an active LDS subtask• To kill an active LDS subtaskTo kill an active LDS subtask

***NOTE*** use this process only as last resort in resolving a problem with an active request.

• obtain a list of subtasks in the LDS partition as described in previous topic; the Manage Tasks panel resulting from that action is used to select and terminate the desired subtask

• You must identify the subtask to be terminated using from the list reported on the Manage Tasks panel; the primary columns used to identify the subtask are the CICS_TASK# and USER_ID columns

63


• To kill an active LDS subtask (cont’d)To kill an active LDS subtask (cont’d)• Click on the TASK_NAME column in the row associated

with the identified subtask – this will insert the TASK_NAME value in the Tasks for Operations listbox below

• Click the Stop Tasks button to request termination of the selected task.

• Click the Refresh button to refresh the display. If the same task still shows ASGND-INUS with the same CICS_TASK#, you can repeat by clicking the Stop Tasks button again. LDS will attempt successively more powerful processes with each attempt to stop the same task up to 3 iterations.

64

Developing/Testing RSPs

• RSP developmentRSP development• Using MDI SPTEST for testingUsing MDI SPTEST for testing• Using ISQL / ISQLODBC for testingUsing ISQL / ISQLODBC for testing

65

Developing/Testing RSPs (Cont’d)

• RSP developmentRSP development• RSPs perform as locally-developed data sources RSPs perform as locally-developed data sources

for ViaSQL clientsfor ViaSQL clients• Invoked with EXEC CICS LINK from Access Invoked with EXEC CICS LINK from Access

Server in CICSServer in CICS• May return messages, result sets, or bothMay return messages, result sets, or both• Sample RSPs provided in VSE sublibrary used for Sample RSPs provided in VSE sublibrary used for

ViaSQL VSE installationViaSQL VSE installation

66


• RSP development (cont’d)RSP development (cont’d)• RSP coding:RSP coding:

• Must use SPAREA and RSP commands to communicate with Access Server

– STATUS used to indicate success or failure of RSP processing; if you don’t issue a STATUS, the Access Server will generate a failure STATUS

– MESSAGE used to return a message to the ViaSQL client– COMMIT, ROLLBACK must be used when commit or rollback of work

in the CICS environment is needed (do not issue EXEC CICS SYNCPOINTs within the RSP itself)

– DESCRIBE may be used to extract an SQLDA data structure from LDS or local TABDEF table for returning data with PUTPIPE

– PUTPIPE used for returning data to the ViaSQL client– GETPIPE used for receiving data sent by ViaSQL client with request– OPENPIPE, CLOSPIPE to open and close data pipes

-or-Use the MDIRSPCA support for COMMAREA RSPs (*NEW*)

67


• RSP development (Cont’d)RSP development (Cont’d)• RSP preparationRSP preparation

• Use local CICS compilation JCL/procedures with following additions:

– Include VIASQL.ASLIB in LINKEDIT step’s LIBDEF OBJ,SEARCH definitions

– Ensure resulting PHASE is linked in same AMODE as Access Server in CICS

-or-• (*NEW*) For COMMAREA RSPs, use local

CICS/compilation with no changes

68


• Using MDI SPTEST for testingUsing MDI SPTEST for testing• Use of 3270 session in CICS for testing RSP allows use of Use of 3270 session in CICS for testing RSP allows use of

CEDF function in CICS for testing EXEC CICS commands CEDF function in CICS for testing EXEC CICS commands within the RSPwithin the RSP

• Using MDI SPTEST to test an RSP that requires GETPIPE Using MDI SPTEST to test an RSP that requires GETPIPE data requires the GETPIPE data to be first be stored in a data requires the GETPIPE data to be first be stored in a CICS temp storage queue; see the RSP Programmer’s CICS temp storage queue; see the RSP Programmer’s Guide and Reference for additional detailsGuide and Reference for additional details

• Issue MDI SPTEST from clear 3270 screen in CICSIssue MDI SPTEST from clear 3270 screen in CICS• At “Stored Procedure Name ===>” prompt, enter the RSP At “Stored Procedure Name ===>” prompt, enter the RSP

namename• Enter RSP parameters below the “TS Queue Name for Input” Enter RSP parameters below the “TS Queue Name for Input”

lineline• Hit ENTER key to perform test – results will be displayed in Hit ENTER key to perform test – results will be displayed in

subsequent panel, with partial result set data displayed subsequent panel, with partial result set data displayed below the “TS Queue Name for Input” linebelow the “TS Queue Name for Input” line

69


• Using ISQLODBC for testingUsing ISQLODBC for testing• The ISQL utility (only the Sybase version) may also be used The ISQL utility (only the Sybase version) may also be used

for testing RSPs using this procedure – just use the for testing RSPs using this procedure – just use the appropriate command for using ISQL instead of ISQLODBCappropriate command for using ISQL instead of ISQLODBC

• Using ISQLODBC will test RSP execution from ODBC Using ISQLODBC will test RSP execution from ODBC interface to Access Server in CICSinterface to Access Server in CICS

• Not suitable for testing RSPs that require DB2 or MIX input Not suitable for testing RSPs that require DB2 or MIX input pipe datapipe data

• Full result data will be returned and processed through the Full result data will be returned and processed through the Open Client, and also ODBC when testing with ISQLODBCOpen Client, and also ODBC when testing with ISQLODBC

• When using TCT-based sessions as done at ASCAP, the When using TCT-based sessions as done at ASCAP, the RSP execution may still be EDFed in CICS using the TCT RSP execution may still be EDFed in CICS using the TCT session involved for diagnosing problems with EXEC CICS session involved for diagnosing problems with EXEC CICS commands in the RSPcommands in the RSP

70


• Using ISQLODBC for testing (Cont’d)Using ISQLODBC for testing (Cont’d)• To test the RSP with ISQLODBC (ISQL uses the To test the RSP with ISQLODBC (ISQL uses the

same procedure except for start command)same procedure except for start command)• Start ISQLODBC at a command prompt on a

ViaSQL workstation (one with the Viaserv ODBC driver and Open Client installed and datasource defined for the ViaSQL Gateway):ISQLODBC –Uuserid –Ppassword –SODBC_dsn

• At the 1> prompt, enter the USE PROCEDURE command for invoking the RSP:USE PROCEDURE rsp_name &arg1=value1 &arg2=value2…;

71


• Using ISQLODBC for testing (Cont’d)Using ISQLODBC for testing (Cont’d)• If the RSP uses STD input pipe data, continue

by adding the STD input pipe records one at a time at the n> prompts from ISQLODBC

• Enter GO at the last n> prompt to invoke initiation of the RSP

• Any result data returned by the RSP will be formatted back to the ViaSQL workstation display

72

Sybase ASE Integration

• Integrating ViaSQL usage in Sybase ASE Integrating ViaSQL usage in Sybase ASE includes:includes:• Passthrough mode – use an explicit passthrough Passthrough mode – use an explicit passthrough

connection to execute any ViaSQL statement connection to execute any ViaSQL statement against a ViaSQL data sourceagainst a ViaSQL data source

• Proxy tables – create a proxy table in ASE that Proxy tables – create a proxy table in ASE that represents a ViaSQL virtual table, supporting joins represents a ViaSQL virtual table, supporting joins between ASE tables and ViaSQL virtual tablesbetween ASE tables and ViaSQL virtual tables

• rpc support – use the Sybase rpc syntax to access rpc support – use the Sybase rpc syntax to access ViaSQL virtual tables, to perform ViaSQL Gateway ViaSQL virtual tables, to perform ViaSQL Gateway transfers, and invoke ViaSQL RSPstransfers, and invoke ViaSQL RSPs

73

Visual Basic Application Development

• Sample codeSample code• Ascaptst.zip: small VisualBasic application that can Ascaptst.zip: small VisualBasic application that can

test VisualBasic access to Viaserv ODBC DSN test VisualBasic access to Viaserv ODBC DSN using ADO connectionstring, as:using ADO connectionstring, as:

Cn.Open ("Provider=MSDASQL;DSN=ascaptst;UID=DWM001;PWD=DWM001")Cn.Open ("Provider=MSDASQL;DSN=ascaptst;UID=DWM001;PWD=DWM001")Rs.Open Sql, Cn, adOpenForwardOnly, adLockReadOnlyRs.Open Sql, Cn, adOpenForwardOnly, adLockReadOnly

74

Troubleshooting

• ViaSQL Gateway logging and tracingViaSQL Gateway logging and tracing• Access Server logging and tracingAccess Server logging and tracing• LDS loggingLDS logging

75

Troubleshooting (Cont’d)

• ViaSQL Gateway Logging and TracingViaSQL Gateway Logging and Tracing• To enable Gateway logging and tracing, you must configure To enable Gateway logging and tracing, you must configure

a Gateway log file name in Configure-Troubleshooting-Log a Gateway log file name in Configure-Troubleshooting-Log File OptionsFile Options

• All Gateway logging and tracing information written to the All Gateway logging and tracing information written to the same log filesame log file

• Maximum log file size also definedMaximum log file size also defined• When log file size reaches maximum, new log records

wrap to a point in log file following Gateway startup information and the new end-of-file is marked by a record containing <END>

• (*NEW*) History of 4 most recent log files per Gateway (*NEW*) History of 4 most recent log files per Gateway instance are now saved with file extensions 001 thru 004, instance are now saved with file extensions 001 thru 004, 001 being the most recent log file, 004 being the oldest.001 being the most recent log file, 004 being the oldest.

76


• ViaSQL Gateway Logging and Tracing (cont’d)ViaSQL Gateway Logging and Tracing (cont’d)• Gateway log and trace information may be configured to Gateway log and trace information may be configured to

selectively include:selectively include:• Client connections, SQL request executions, and

disconnects• Contents of client SQL requests• Shutdown requests• API calls between client and the Gateway instance• Communication between the Gateway instance and

Access Server• Enabling Enabling allall of the log and trace options in ViaSQL Gateway of the log and trace options in ViaSQL Gateway willwill negatively impact performance negatively impact performance

• (*NEW*) Gateway tracing parameters may now be queried (*NEW*) Gateway tracing parameters may now be queried and updated dynamically from Gateway Manager using the and updated dynamically from Gateway Manager using the Show Running Gateways – Gateway – Trace Level buttonShow Running Gateways – Gateway – Trace Level button

77


• ViaSQL Gateway Logging and Tracing ViaSQL Gateway Logging and Tracing (cont’d)(cont’d)• Viaserv recommends enabling the following items Viaserv recommends enabling the following items

(and only these items) for logging and tracing in (and only these items) for logging and tracing in production Gateway configurations:production Gateway configurations:

• Trace Timing and Major Steps• Trace SQL Request as Received

• Only enable other Gateway logging and tracing Only enable other Gateway logging and tracing options when requested by Viaserv technical options when requested by Viaserv technical support or when performing independent problem support or when performing independent problem analysisanalysis

78


• ViaSQL Gateway Logging and Tracing (cont’d)ViaSQL Gateway Logging and Tracing (cont’d)• Log and trace records associated with a specific connection Log and trace records associated with a specific connection

begin with an 8-character identifier. This identifier uniquely begin with an 8-character identifier. This identifier uniquely identifies all log and trace records associated with that identifies all log and trace records associated with that connection, from connection start to disconnect.connection, from connection start to disconnect.

• It is possible for an 8-character identifier to be reused for It is possible for an 8-character identifier to be reused for another new connection following disconnectanother new connection following disconnect

• (*NEW*) The logcrack.exe utility may be used to process a (*NEW*) The logcrack.exe utility may be used to process a Gateway log file and produce a report or data base records Gateway log file and produce a report or data base records that combine the log file records for each connection into a that combine the log file records for each connection into a hierarchy of request activity. Other related utilities are also hierarchy of request activity. Other related utilities are also provided to help analyze this data (actlog.exe, actcrack.exe, provided to help analyze this data (actlog.exe, actcrack.exe, actview.exe).actview.exe).

79


• Access Server Logging and TracingAccess Server Logging and Tracing• Two steps involved for Access Server Logging and Two steps involved for Access Server Logging and

TracingTracing• Generating the log/trace data• Routing generated data to requested

destination• Two options for generating log/trace dataTwo options for generating log/trace data

• Using Transient Data Logging Parameters• (*NEW*) Using Trace Control Definitions

80


• Access Server Logging and Tracing (cont’d)Access Server Logging and Tracing (cont’d)• Using Transient Data Logging ParametersUsing Transient Data Logging Parameters

• Configured using MDI ADMIN – Site Configuration – Transient Data Logging Parameters panel

• Specify CICS transient data queue ID(s) for selected log/trace data:

– Errors/Info Msgs: for high-level error and information messages; usually routed to CSMT TD Q

– Client I/O Trace: for tracing TCP/IP traffic between Access Server and ViaSQL Gateway

– Server Trace: for Viaserv technical support use– ViaSQL API Trace: for tracing RSP commands and

responses– Session Trace: for tracing start of TCP/IP sessions– (*NEW*) Request Trace: for logging SQL text and

result status of all requests received from ViaSQL Gateway

81


• Using Transient Data Logging Parameters (cont’d)Using Transient Data Logging Parameters (cont’d)• Log/trace data is routed to specified CICS TD Qs in text

format• Useful CICS TD Qs for Access Server logging/tracing:

– CSMT: used by CICS for reporting operational errors and other exceptional conditions; usually routed to the POWER LST Q

– MDIL: defined during ViaSQL installation specifically for use by MDILOGR for processing Access Server log/trace information

• ASCAP may define CICS TD Qs for their own use in processing error/info messages and/or Access Server log/trace information

82


• Using Transient Data Logging Parameters (cont’d)Using Transient Data Logging Parameters (cont’d)• Viaserv recommends enabling the following

items (and only these items) for logging and tracing in production Access Server configurations:

– Errors/Info Msgs (most important)– Request Trace (optional)

• Only enable other Access Server logging and tracing options when requested by Viaserv technical support or when performing independent problem analysis

83


• Access Server Logging and Tracing (cont’d)Access Server Logging and Tracing (cont’d)• (*NEW*) Using Trace control Definitions(*NEW*) Using Trace control Definitions

• Configured using MDI ADMIN – Trace Control Definitions panel

• Trace Selection Data Elements – used to qualify those Access Server service tasks to

be affected by the Trace Control Definition– CICS APPLID: APPLID of the CICS partition running

Access Server– Client Application Name: application name (if any)

provided by the ViaSQL client workstation– Client Service Name: name of the ViaSQL Gateway

instance servicing the connection

84


• Trace Selection Data Elements (Cont’d)– **Client Workstation Name: name of the client

workstation as defined in Windows– Remote Host IP Address: IP address of the ViaSQL

Gateway instance servicing the connection– Remote Host Network Mask: network mask to apply to

the Remote Host IP Address for selection qualification– Server Host Port Number: listening port, defined in

Access Server, which established the connection– **Userid: Client user ID as provided by the client

application– CICS transaction ID: Access Server service transaction

ID

** - these items most useful in Trace Selection criteria

85


• Using Trace control Definitions (cont’d)Using Trace control Definitions (cont’d)• Access Server Trace Output Configuration

– Trace Output Type: always specify STAT (for static output definition)

– Specify CICS transient data queue ID(s) for selected log/trace data:

» Client IO: for tracing TCP/IP traffic between Access Server and ViaSQL Gateway

» Data Server: for Viaserv technical support use» ViaSQL API: for tracing RSP commands and

responses

86


• Access Server Logging and TracingAccess Server Logging and Tracing• Routing generated data to requested destination Routing generated data to requested destination

(MDILOGR Control Defin(MDILOGR Control Definitions)itions)• Configured using MDI ADMIN – MDILOGR

Control Definitions• Three types of MDILOGR trace

– TempStorage MDILOGR Entry– Print MDILOGR Entry– Forwarding MDILOGR Entry

• Maximum of 9 MDILOGR Control Table Entries

87


• MDILOGR Control DefinMDILOGR Control Definitions (cont’d)itions (cont’d)• TempStorage MDILOGR Entry

– Routes data to the specified CICS temp storage queue ID

– Be careful defining size of TempStorage MDILOGR Entry – defining too large a value may exhaust all temp storage in the CICS partition and cause CICS to stall

– TempStorage information can be browsed using CEBR or retrieved to workstation using RSP MDIRSP01

88


• TempStorage MDILOGR Entry (cont’d)– Destination ID: captures all data written to this CICS

TD queue ID – Tempstorage AID: name of the CICS TS queue ID

the data is to be written– Tempstorage Type:

» AUX for auxiliary temp storage (DASD)» MAIN for CICS main storage

– Maximum Records: maximum number of records to be written to this QID; when maximum is reached, data is wrapped and starts writing at record #1 with the current end-of-file denoted with <END> record

89


• MDILOGR Control DefinMDILOGR Control Definitions (cont’d)itions (cont’d)• Print MDILOGR Entry

– Routes data to the POWER LST queue using EXEC CICS SPOOLWRITE

– Use the PF5 key on the Display Print MDILOGR Entry panel to close the current POWER LST queue entry and make it visible in the queue

– Destination ID: captures all data written to this CICS TD queue ID

– User ID: stored in POWER LST queue entry as the ‘FROM’ identifier

– Node ID: node ID to which the output queue is to be sent for POWER PNET

– CLASS: POWER output queue class

90


• MDILOGR Control DefinMDILOGR Control Definitions (cont’d)itions (cont’d)• Forwarding MDILOGR Entry

– Routes data to a non-ViaSQL transient data queue– Useful for processing of error/info messages by both

ViaSQL and local programming– Destination ID: captures all data written to this CICS

TD queue ID – Forward to TD Queue: non-ViaSQL transient data

queue ID to which the data is to be written

91


• Legacy Data Server (LDS) Logging and TracingLegacy Data Server (LDS) Logging and Tracing• LDS logging and tracing controlled by the LDS Trace Level LDS logging and tracing controlled by the LDS Trace Level

for each LDS subtaskfor each LDS subtask• Trace Level 0 = NONE, all logging or tracing OFF• Trace Level 1 = LOW, trace SQL request text and results

status only– (*NEW*) Trace Level 1 output in LDS is now routed to a

common POWER LST Q entry shared by all LDS subtasks; older versions of LDS generated 1 POWER LST Q entry per request when enabled

• Trace Level 2 = MED, generates moderate level of detail tracing (not recommended for production configurations)

• Trace Level 3 = HIGH, generates high level of detail tracing (not recommended for production configurations)

92


• LDS Logging and Tracing (cont’d)LDS Logging and Tracing (cont’d)• Setting LDS Trace Level Setting LDS Trace Level

• LDS configuration defines starting LDS Trace Level for each subtask, configured using LDM – CONFIG – Trace Level parameter

• LDS Trace Level for selected subtasks may be set dynamically using LDM – ADMIN – Display/Manage Tasks – Set Trace Level button (using this option usually requires setting multiple LDS subtasks to be effective)

93


• Setting LDS Trace Level (cont’d)Setting LDS Trace Level (cont’d)• (*NEW*) Trace Control Definitions in Access Server may

be used to set LDS Trace Level selectively by UserID, client workstation, originating CICS APPLID,etc.

– Define Trace Control Definition – Trace Selection Data Elements as described earlier

– Legacy Data Server Trace Output Configuration» Trace Output Type: SPRT – use shared printer support in LDS (all

output written to same Trace Output Name is written to same POWER LST Q entry)

DPRT – use dynamic print output (output from each subtask is written to separate POWER LST Q entry)

94


– Legacy Data Server Trace Output Configuration (cont’d)

» Trace Output Name/Class: specify the name for the output in the POWER

LST Q followed by the POWER output class» ModuleName / Trace Level #1: specify LDSTASK for the ModuleName and the

desired LDS Trace Level (0, 1, 2, or 3)

95


• LDS Logging and Tracing (cont’d)LDS Logging and Tracing (cont’d)• (*NEW*) Shared print logger support in LDS(*NEW*) Shared print logger support in LDS

• Trace Level 1 output showing SQL request text and result status is now routed to common POWER LST Q entry

• Requires a dedicated VSE subtask in LDS partition

• LDS Print Manager used to display and control shared print output using LDSM – LDS Print Manager

Documents

ViaSQL Review Prepared for ASCAP Training ViaSQL Review Prepared for ASCAP Training Liberating Enterprise Data March 4 - 5, 2008