CICS VSAM Transparency for z/OS, Version 1.2


Variable length records in VSAM

Unless the last column in the DB2® table is VARCHAR, CICS® VT assumes that a file contains fixed length records. This may impose restrictions on your tabledesign.

There are two typical cases where variable length records are used in VSAM:

In all cases, the VARCHAR column size must be the difference between the shortest and longest VSAM records.

Identifying varying record lengths

Any VSAM file can contain variable length records. If MAXLRECL is greater than AVGLRECL when you list the base VSAM cluster, your file might contain varying length records. However, if MAXLRECL equals AVGLRECL the file can contain variable length records. The only reliable way to establish that a file contains varying length records is to review the programs that insert new records.

Auto-mapping implications

There are two situations where the auto-mapper assumes that a file contains varying length records:

  • If MAXRECL is not equal to AVGRECL and the last field in the copybook is not numeric, the last field is mapped to a VARCHAR column. If the file records are genuinely variable length, it is possible that more than just the last field is part of the varying length. In this case you have to manually update the DDL to combine these fields into a single column, and manually update the mapping.
  • If OCCURS DEPENDING ON is specified for the last field or group field, the auto-mapper combines the entire array into a single VARCHAR column.

The auto-mapper issues an appropriate status message when it encounters either of these situations, as shown in Figure 1.

Figure 1. Identifying potential varying length records
 
 --------------------- CICS VT: Edit columns in AAAV21 -------- Row 24 from 27
Command ===> ________________________________________________ Scroll ===> CSR 
                                                                              
Commands: MAP  SAVE  PREVIEW  SUSPEND/RESUME  CHANGE/UNDO  SHOW               
Actions:  S Display, U Update, D Delete, I Insert            Status message / 
A Pos   Copybook field name / DB2 column name     Type Len   Exit      Pic Par
- ----- ----+----1----+----2----+----3----+----   ---- ----- -----------------
_ 129   ZONED-RIPE-FOR-DEC-A                    +      6                      
        ZONED_RIPE_FOR_DEC_A..........          +  DEC 6,0                    
_ 135   ZONED-RIPE-FOR-DEC-B                    +      6                      
        ZONED_RIPE_FOR_DEC_B..........          +  DEC 6,2                    
_ 141   ZONED-NOT-RIPE-FOR-DEC                  +      8                      
        ZONED_NOT_RIPE_FOR_DEC........          + CHAR 8                      
_ 149   VARCHAR-ME-UP                           +      565   Assumed varying  
        VARCHAR_ME_UP.................          + VARC 565                    
******************************* Bottom of data *******************************                         

There are no issues if a file containing fixed length records is mapped to a DB2 table with VARCHAR as the last column. The reverse situation almost inevitably causes problems in your application.

Variable record lengths in CICS VT

The variable length field should always be the last field in a VSAM record. Similarly, a variable length column should always be the last column in the DB2 table. On a retrieval type call, CICS VT adds the VARCHAR column length from DB2 to the length of the record preceding the VARCHAR column, and returns this length to your application program. For PUT, WRITE,or REWRITE, CICS VT gets the record length from your program, subtracts the length of the fixed part of the record, and uses the remainder as the VARCHAR column length.

If no VARCHAR column exists in the table, CICS VT assumes the VSAM record is fixed length.

The VARCHAR column must be able to contain the entire variable area. This means that the difference in size between the shortest and the longest records in the file determines the VARCHAR column size.

DB2 table design example 1

Consider the copybook shown in Figure 2.

Figure 2. Variable record copybook example 1
       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).

The maximum record length for the file using this copybook is 1024 bytes and the field EXAMPLE-1-DATA contains between 0 and 1000 bytes of data. This means that the shortest record length is 24 bytes. The record length of the DIM that is specified in the mapping for a variable length record file is always the maximum length, which is 1024 bytes in this case. The correct mapping for this copybook is to map the last 1000 bytes (for EXAMPLE-1-DATA) as a single field mapped to a DB2 column defined as VARCHAR(1000). The DDL is shown in Figure 3 .

Figure 3. Variable record DDL example 1
       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));

DB2 table design example 2

When variable length records occur because of an array, the solution is similar to example 1. The last column in the DB2 table must be VARCHAR and must contain the entire variable area.

In the copybook shown in Figure 4, the auto-mapper is processing it as varying length because MAXLRECL is not equal to AVGLRECL. There is no DEPENDING ON clause for the array EXAMPLE-2-DEBT-INFO in this situation.

Figure 4. Variable record copybook example 2
       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).    

The maximum record length for the file using this copybook is 697 bytes. The fixed length portion of the copybook is 57 bytes and the group field EXAMPLE-2-DEBT-INFO is 32 bytes. Because the group field occurs 20 times, the total length of the array is 640 bytes.

Each record in the VSAM file contains between 0 and 20 instances of the group field, controlled by the application. This entire area must be mapped to a single DB2 column defined as VARCHAR(640). This is shown in Figure 5.

Figure 5. Variable record DDL example 2
       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));

Defining variable length files in CICS

The CICS VT DST entry for files mapped as variable length must have RECORDF=VAR specified. Otherwise a LENGERR error is returned to your application.





Last updated: February 8, 2013 20:43:1