CICS VSAM Transparency for z/OS

https://www.ibm.com/docs/en/cics-vt
Admin
CICS VSAM Transparency for z/OS enables transparent access and management of migrated VSAM data sets...
Tokens:131,082
Snippets:1,283
Trust Score:10
Update:10 months ago
Show doc for...
Tokens:
Raw
### CICS VT Configuration and Setup

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=fbes-working-variable-length-data

Guides users through the initial configuration and setup procedures for CICS VSAM Transparency for z/OS. This includes essential steps for installation and basic operational readiness.

```N/A
// Covers tasks like defining datasets, setting up control files, and configuring CICS resources.
```

--------------------------------

### Example TRACE and TRACSET with Skip Only

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=tracing-trace-parameters

Demonstrates an example where only the SKIP parameter is used with the TRACSET statement, alongside a TRACE statement. This allows tracing to begin after a specified number of initial calls.

```JCL
TRACE P01,P03,P04,P05,P07,P08,P09,DIM=VIDKSDS,VIDKX01
TRACSET SKIP=001990
```

--------------------------------

### Add VID.SVIDLPA Dataset to LPA

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=subsystem-dynamic-ssi-installation

Dynamically adds the VID.SVIDLPA dataset to the LPA (Link Pack Area) using the SETPROG command. This makes the modules in the dataset available for system-wide use. The MASK parameter ensures that only modules starting with 'VID' are considered.

```MVS Console
SETPROG LPA,ADD,DSNAME=VID.SVIDLPA,MASK=VID*
```

--------------------------------

### COBOL Copybook for Variable Record Design Example 2 (Array)

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=vt-variable-length-records-in-vsam

Defines a COBOL record layout that includes an array (EXAMPLE-2-DEBT-INFO). This copybook demonstrates handling variable record lengths due to array occurrences, mapping the array to a VARCHAR column.

```COBOL
       01  EXAMPLE-2-REC.                                        
           05  EXAMPLE-2-KEY.                                    
               10  EXAMPLE-2-APP-NUM               PIC 9(12).    
               10  EXAMPLE-2-SEQ-NUM               PIC 9(01).    
           05  EXAMPLE-2-COMMON-DATA.                            
               10  EXAMPLE-2-UNIFIED-CR-TRAN-ID    PIC X(18).    
               10  EXAMPLE-2-EFX-PERSISTENT-KEY    PIC X(12).    
               10  EXAMPLE-2-CREATE-DATE           PIC 9(08).                        
               10  EXAMPLE-2-CREATE-TIME           PIC 9(06).                        
           05  EXAMPLE-2-DEBT-INFO OCCURS 20 TIMES.              
               10  EXAMPLE-2-PAYMENT-AMOUNT        PIC S9(09)V99. 
               10  EXAMPLE-2-PAYMENT-CODE          PIC X(01).    
               10  EXAMPLE-2-AFFILIATE-TYPE        PIC X(01).    
               10  EXAMPLE-2-AFFILIATE-ID          PIC X(02).    
               10  EXAMPLE-2-ACCOUNT-NUMBER        PIC X(14).    
               10  EXAMPLE-2-MARKET                PIC X(03).    
```

--------------------------------

### CICS VT FBE for a Key or IBM AIX Field (Example)

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=fbes-working-variable-length-data

Illustrates a specific example of coding a Field-Based Exit (FBE) designed to handle a key field or an IBM AIX field within CICS VT. This provides a concrete implementation scenario.

```PL/I
DCL KEY_FIELD CHAR(10);

/* Example: Ensure key field is unique */
IF CHECK_UNIQUENESS(KEY_FIELD) NE 0 THEN DO;
    /* Handle duplicate key error */
    RETURN ERROR_CODE;
END;

```

--------------------------------

### JCL for CICS VT VSAM File Migration (Initial)

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=set-making-jcl-changes-before-migration

This JCL snippet shows the initial setup for CICS VT to access a migrated Item Detail VSAM file. It includes DD statements for program libraries and the VSAM files, with the ITEMDET DD referencing CICS VT migration.

```JCL
//jobcard
//STEP5   EXEC PGM=ORD0105
//STEPLIB  DD DSN=appl.prog.lib,DISP=SHR
//         DD DSN=appl.DRIVERS.LOAD,DISP=SHR
//         DD DSN=VID.SVIDLODE,DISP=SHR
//ITEMDET  DD SUBSYS=(ssi,db2id,VTITEM)
//ITEMDET@ DD DSN=ITEMDT.VID.DUMMY,DISP=SHR
//AUDIT    DD DSN=AUDIT.VSAM.FILE,DISP=SHR  
		
```

--------------------------------

### Assembler Generic FBE Example

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=me-working-storage-section

An example of a generic assembler Field-Based Exit (FBE). This snippet demonstrates the basic structure and entry/exit points for an assembler routine designed to perform field-level data reengineering.

```Assembler
***********************************************************************
* Generic Assembler FBE                                               *
***********************************************************************
FBE       CSECT
          USING FBE,R12
          STM   R0,R12,12(R13)      Save registers
          LR    R12,R15             Base register for FBE CSECT
          USING *,R12               Establish addressability
          LA    R13,SAVEAREA        Point to save area
          ST    R13,4(R11)          Save backward pointer
          ST    R11,8(R13)          Save forward pointer

          ...                       Field reengineering logic here

          L     R15,8(R13)          Load forward pointer
          L     R13,4(R13)          Restore previous save area pointer
          LM    R0,R12,12(R13)      Restore registers
          BR    R14                 Return to caller

          SAVEAREA   DS    18F        Save area
          END   FBE

```

--------------------------------

### Configure IEFSSNxx Member for CICS VT SSI

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=subsystem-permanent-ssi-installation

This code snippet shows the command to add the CICS VT subsystem to your current IEFSSNxx member. It specifies the subsystem name (VIDS) and the initialization routine (VIDSSINT). This is a crucial step for the permanent installation of the SSI.

```jcl
SUBSYS SUBNAME(VIDS) INITRTN(VIDSSINT)
```

--------------------------------

### Generic Assembler FBE Example

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=exit-error-handling

This is a placeholder for a generic Assembler Field-Based Exit (FBE). It would contain the common structure and entry/exit points for FBEs, with specific logic to be implemented based on the reengineering task.

```assembler
FBE-ENTRY.
        SAVE-REGISTERS.
        GET-COMMUNITY-AREA.
        PROCESS-FBE-LOGIC.
        RESTORE-REGISTERS.
        GOBACK.
```

--------------------------------

### COBOL Copybook for Variable Record Design Example 1

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=vt-variable-length-records-in-vsam

Defines a COBOL record layout with a variable length data field (EXAMPLE-1-DATA). This copybook is used to illustrate mapping variable data to a DB2 VARCHAR column.

```COBOL
       01  EXAMPLE-1-REC.
           05  EXAMPLE-1-KEY.
               10  EXAMPLE-1-APPL-NUMB  PIC X(12).
               10  EXAMPLE-1-BUREAU     PIC X(2).
               10  EXAMPLE-1-VIEW-NUMB  PIC 9(2).
               10  EXAMPLE-1-SEG.
                   15 EXAMPLE-1-SEG-2   PIC X(2).
                   15 EXAMPLE-1-SEG-4   PIC X(2).
               10  EXAMPLE-1-SEG-SEQ    PIC 9(4).
               10  EXAMPLE-1-SEG-SEQ-X REDEFINES \
                   EXAMPLE-1-SEG-SEQ    PIC X(4).
           05  EXAMPLE-1-DATA           PIC X(1000).
```

--------------------------------

### Add New CICS VT Subsystem

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=subsystem-dynamic-ssi-installation

Dynamically adds the new CICS VT subsystem to the system using the SETSSI command. This registers the subsystem with the specified name (VIDS) and points to its initialization routine (VIDSSINT).

```MVS Console
SETSSI ADD,SUB=VIDS,I=VIDSSINT
```

--------------------------------

### ISPF Panel Configuration for CICS VT Setup

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=application-tailoring-panel-1-4

This ISPF panel collects essential configuration data for CICS VT installation tailoring. It requires fully qualified data set names for CICS VT and custom libraries, specification of the MVS assembler program (ASMA90 or IEV90), and an output device type. A skeleton job card can also be optionally defined.

```text
-------------------------- CICS VT Setup (Screen 1/4) ------------------------
 Command ===> _________________________________________________________________
 Insert data set names in the following screens. Do not use quotes.   
                                                                                
 CICS VT VIDCNFG library : cvt210.SVIDCNFG_______________________________        
                                                                                
 Custom VIDCNFG library  : my.SVIDCNFG.custom____________________________        
                                                                                
 CICS VT VIDSAMP library : cvt210.SVIDSAMP_______________________________        
                                                                                
 Custom VIDSAMP library  : my.SVIDSAMP.custom____________________________        
                                                                                
 MVS Assembler program   : ASMA90 (ASMA90/IEV90)                                
                                                                                
 Output Device Type      : SYSDA__Generic device type (example: SYSDA) 
 
 Job card statement:                                                               
 //VIDJOB JOB (ACCT,PGMer-name),CLASS=L,MSGCLASS=X,NOTIFY=&SYSUID       
 ________________________________________________________________________       
 ________________________________________________________________________       
 ________________________________________________________________________       
                                                                                
 Press Enter to continue, PF3 to Exit or PF1 for Help                            

```

--------------------------------

### COBOL Example: Calling VIDCONV Utility in CICS VT

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=reengineering-reformatting-date-field

This snippet demonstrates the standard parameter list for calling the VIDCONV utility in COBOL. It's crucial for understanding how to invoke CICS VT's built-in conversion routines. Note that not all parameters are always used, depending on the source field type (e.g., VSAM vs. DB2).

```COBOL
       IDENTIFICATION DIVISION.
       PROGRAM-ID. DATEFBE.
       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.
       SOURCE-COMPUTER. IBM-370.
       OBJECT-COMPUTER. IBM-370.
       SPECIAL-NAMES.
           CICS
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  VSAM-FIELD           PIC S9(9) COMP-3.
       01  VS-SOURCE-FIELD      PIC S9(7) COMP-3.
       LINKAGE SECTION.
       01  DFHCOMMAREA.
      * Parameters for VIDCONV
       05  VIDCONV-PARM-LIST.
           10  PARM1      PIC X(04).
           10  PARM2      PIC X(08).
           10  PARM3      PIC X(08).
           10  PARM4      PIC X(01).
           10  PARM5      PIC X(08).
           10  PARM6      PIC X(08).
           10  PARM7      PIC X(08).
           10  PARM8      PIC X(08).
           10  PARM9      PIC X(08).
           10  PARM10     PIC X(08).
           10  PARM11     PIC X(08).
           10  PARM12     PIC X(08).
           10  PARM13     PIC X(08).
           10  PARM14     PIC X(08).
           10  PARM15     PIC X(08).
           10  PARM16     PIC X(08).
           10  PARM17     PIC X(08).
           10  PARM18     PIC X(08).
           10  PARM19     PIC X(08).
           10  PARM20     PIC X(08).
           10  PARM21     PIC X(08).
           10  PARM22     PIC X(08).
           10  PARM23     PIC X(08).
           10  PARM24     PIC X(08).
           10  PARM25     PIC X(08).
           10  PARM26     PIC X(08).
           10  PARM27     PIC X(08).
           10  PARM28     PIC X(08).
           10  PARM29     PIC X(08).
           10  PARM30     PIC X(08).
           10  PARM31     PIC X(08).
           10  PARM32     PIC X(08).
           10  PARM33     PIC X(08).
           10  PARM34     PIC X(08).
           10  PARM35     PIC X(08).
           10  PARM36     PIC X(08).
           10  PARM37     PIC X(08).
           10  PARM38     PIC X(08).
           10  PARM39     PIC X(08).
           10  PARM40     PIC X(08).
       PROCEDURE DIVISION.
       MAIN-PROCEDURE.
      * Example of moving VSAM field to working storage
           MOVE VSAM-FIELD TO VS-SOURCE-FIELD.
      * Call VIDCONV (dynamic invocation required)
           CALL 'VIDCONV' USING DFHCOMMAREA.
      * ... rest of the program ...
           GOBACK.

```

--------------------------------

### VIDFMSPX Module Sample Source

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=set-making-jcl-changes-before-migration

This is the sample source code for the VIDFMSPX module. It defines processing modes and default settings for CICS VT. Modifications are needed here to direct application VSAM calls after migration.

```Assembler
VIDFMSPX CSECT                                             
VIDFMSPX AMODE 31                                              
VIDFMSPX RMODE ANY                                             
VERIFY   DC    CL8'VIDFMSPX'                                 
		 DC    A(VSAMONLY)                                 
		 DC    A(DMFDFLT)                                  
		 DC    A(DMFOVER)                                  
*                                                              
VSAMONLY DS    0H                                              
*        LIST OF DIMS TO BE PROCESSED IN VSAMONLY MODE     
*        DC    CL8'VIDKSDS'                                
VSAMEND  DC    XL8'FFFFFFFFFFFFFFFF'                       
*                                                              
DMFDFLT  DS    0H                                              
*        SYSTEM DEFAULT DMF SWITCH - 'Y' = ON AND 'N' = OFF
         DC    CL1'N'                                      
*                                                              
DMFOVER  DS    0H                                              
*        LIST OF DIMS TO OVERRIDE DMFDFLT                  
*        DC    CL8'VIDKSDS'                                
DMFEND   DC    XL8'FFFFFFFFFFFFFFFF'                       
*                                                              
         END                                                
						
```

--------------------------------

### Introduction to CICS VT

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=fbes-working-variable-length-data

Provides a high-level introduction to CICS VSAM Transparency for z/OS, explaining its purpose, benefits, and core functionalities. It sets the context for understanding the rest of the documentation.

```N/A
// Introduces the concept of transparently accessing VSAM data from CICS without
// significant application modification.
```

--------------------------------

### DB2 DDL for Variable Record Design Example 1

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=vt-variable-length-records-in-vsam

SQL Data Definition Language (DDL) to create a DB2 table corresponding to the COBOL copybook in Example 1. The EXAMPLE-1-DATA field is mapped to a VARCHAR(1000) column.

```SQL
       CREATE TABLE VARIABLE_EXAMPLE1(
           EXAMPLE1_APPL_NUMB    CHAR(12) NOT NULL  
          ,EXAMPLE1_BUREAU       CHAR(02) NOT NULL   
          ,EXAMPLE1_VIEW_NUMB    DEC(2,0) NOT NULL
          ,EXAMPLE1_SEG_2        CHAR(02) NOT NULL
          ,EXAMPLE1_SEG_4        CHAR(02) NOT NULL
          ,EXAMPLE1_SEG_SEQ      CHAR(04) NOT NULL
          ,EXAMPLE1_DATA         VARCHAR(1000)
          ,PRIMARY KEY (EXAMPLE_APPL_NUMB));
```

--------------------------------

### Example TRACE and TRACSET Usage

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=tracing-trace-parameters

Provides an example combining TRACE and TRACSET statements to activate specific trace points and filter calls. This is useful for debugging batch programs that issue many calls.

```JCL
TRACE P01,P03,P04,P05,P08,DIM=VIDKSDS
TRACSET CALLS=0013,SKIP=000007
```

--------------------------------

### JCL for VIDREAD Utility to Verify Data Migration

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=manually-step-4-verify-data-migration

This JCL sample demonstrates how to use the VIDREAD utility program to verify data migration. It includes necessary DD statements for load libraries, system output, input datasets, and trace control. The FILEINV DD statement is crucial for enabling DMF.

```JCL
//CHECKIT EXEC PGM=VIDREAD

//STEPLIB   DD DSN=appl.drivers.load,DISP=SHR
//          DD DSN=VID.SVIDLODE,DISP=SHR
//SYSPRINT  DD SYSOUT=*
//FILEINV   DD DSN=appl.base.cluster.file,DISP=SHR
//FILEIN@   DD DSN=appl.base.cluster.file.DUMMY,DISP=SHR
//FILEIN    DD SUBSYS=(ssi,db2id,dimname,FILEINV)
//VIDTRCE   DD SYSOUT=*
//VIDTRCEP  DD *
TRACE P01,P03,P04,P05,P08,DIM=dimname
//

```

--------------------------------

### Assembler Example for PACKDEC Exit

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=vt-supported-numeric-formats

An example of an assembler Field-Based Exit (FBE) named PACKDEC. This exit is designed to handle potential issues with packed decimal fields within a key, specifically addressing the conversion of spaces to zero for numeric fields.

```assembler
PACKDEC START
        USING PACKDEC,R15
        LR    R4,R1
        CLI   0(R4),X'40'  Test for spaces in numeric field
        BNE   NOTSPACES
        mvc   0(2,R4),=x'0000'  Move zeros to numeric field
NOTSPACES
        BR    R14
PACKDEC END
```

--------------------------------

### Sample JCL for STEPLIB or JOBLIB DD Statements

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=set-steplib-joblib-changes

This JCL snippet demonstrates how to include the CICS VT load library and the application driver library in the STEPLIB or JOBLIB DD statement. Ensure the application drivers library precedes the CICS VT system library for correct execution.

```JCL
//STEPLIB  DD DSN=appl.prog.lib,DISP=SHR
//         DD DSN=appl.drivers.load,DISP=SHR
//         DD DSN=VID.SVIDLODE,DISP=SHR
```

--------------------------------

### DB2 DDL for Variable Record Design Example 2 (Array)

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=vt-variable-length-records-in-vsam

SQL Data Definition Language (DDL) to create a DB2 table for the COBOL copybook in Example 2. The array field EXAMPLE-2-DEBT-INFO is mapped to a VARCHAR(640) column, accommodating its maximum possible length.

```SQL
       CREATE TABLE VARIABLE_EXAMPLE2(
           EXAMPLE2_APPL_NUMB            CHAR(12) NOT NULL  
          ,EXAMPLE2_SEQ_NUM              CHAR(01) NOT NULL   
          ,EXAMPLE2_UNIFIED_CR_TRAN_ID   CHAR(18) NOT NULL
          ,EXAMPLE2_EFX_PERSISTENT_KEY   CHAR(12) NOT NULL
          ,EXAMPLE2_CREATE_DATE          DATE     NOT NULL
          ,EXAMPLE2_CREATE_TIME          TIME     NOT NULL	
          ,EXAMPLE2_DEBT_INFO            VARCHAR(640) NOT NULL
          ,PRIMARY KEY (EXAMPLE_APPL_NUMB, EXAMPLE2_SEQ_NUM));
```

--------------------------------

### Sample JCL for VIDLOAD Utility

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=manually-step-2-convert-unloaded-data

This JCL demonstrates the execution of the VIDLOAD utility program. It specifies DD statements for the program library (STEPLIB), input unload data (LOADIN), and the output DB2 load file (LOADOUT), along with system print output (SYSPRINT). The `PARM` parameter requires the DIM name.

```JCL
//VIDLOAD   EXEC PGM=VIDLOAD,PARM=dimname        
//STEPLIB   DD DSN=appl.drivers.load,DISP=SHR   
//          DD DSN=VID.SVIDLODE,DISP=SHR    
//SYSPRINT  DD SYSOUT=*                             
//LOADIN    DD DSN=appl.sequential.unload,DISP=SHR  
//LOADOUT   DD DSN=appl.sequential.db2load,UNIT=SYSDA,
//             DISP=(,CATLG,DELETE),RECFM=FB,LRECL=100,                
//             SPACE=(CYL,(25,5),RLSE) 

```

--------------------------------

### Enable DMF for Batch Programs using JCL

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=dmf-batch-programs

This JCL example demonstrates how to enable the Dual Mode Facility (DMF) for batch programs in CICS VT. It shows the required additional SUBSYS parameter and DD statement for a batch job, specifying the original VSAM data set.

```JCL
//VIDIVPCO JOB CICSVT,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID   
//*                                                      
//RUNVID  EXEC PGM=VIDIVPCO,REGION=2M                    
//STEPLIB  DD  DISP=SHR,DSN=VID.SVIDLODE              
//         DD  DISP=SHR,DSN=DB2.SDSNLOAD              
//SYSPRINT DD  SYSOUT=*                                  
//SYSOUT   DD  SYSOUT=*                                  
//IVPREPT  DD  SYSOUT=*,LRECL=130,RECFM=FBA              
//SYSUDUMP DD  SYSOUT=*                                  
//VIDKSDS@ DD  DSN=VID.VIDKSDS.DUMMY,DISP=SHR  
//VIDKSDSV DD  DSN=VID.VIDKSDS,DISP=SHR 
//VIDKSDS  DD  SUBSYS=(VIDS,DB2_ssid,VIDKSDS,VIDKSDSV)
//VIDTRCE  DD  SYSOUT=*,RECFM=FBA,LRECL=133,BLKSIZE=13300
//VIDTRCEP DD  *
TRACE P01,P08,DIM=VIDKSDS 

```

--------------------------------

### VIDFMSPX Module Job Log Message Example

Source: https://www.ibm.com/docs/en/cics-vt/2.1_topic=set-making-jcl-changes-before-migration

This message, VIDSS250, appears in the job log when a program opens a VSAM file after the VIDFMSPX module has been configured. It confirms that CICS VT is processing VSAM data for the specified DD name.

```Log
VIDSS250 SUBSYSTEM NAME=VIDZ VSAM ONLY FOR DDNAME=ITEMDET 						
```
Tokens:
Raw