Mapping fields

After you enter the data set information in the screen shown in Figure 2 the following screen is displayed:

Figure 1. File details panel
  
------------------- CICS VT: Data set mapping for VIDKSDS  -------- Row 1 of 1 
Command ===> _______________________________________________ Scroll ===> CSR_  
                                                                               
Commands: I - Insert                                                           
Actions:  U - Update                                                           
          F - Show field information                                           
          D - Delete                                                           
                                                                               
Act File type                                               Status             
--- --------- --------------------------------------------- -------------------
 _  KSDS      Bytes: 00080                                                     
              Creator:    VID                                                 +
              Table name: VID_ITEM                                            +
--- --------- --------------------------------------------- -------------------
******************************* Bottom of data ********************************
 

Specify one of the following actions:

U
Update details for this data set.
F
Select field information for this data set.
D
Delete CICS® VT information for a data set.

Option U is typically used to specify the read-only DDM module name. Expect to use option D very infrequently. Option F, which you will routinely use, allows you to specify field information and this is the next step in the manual mapping process. Option F displays the following panel:

Figure 2. List of fields for a file
 
--------------------- CICS VT: List of fields for VIDKSDS  --------------------- 
Command ===> ________________________________________________ Scroll ===> CSR_ 
                                                                               
VSAM file type : KSDS     Creator   : VID                                     +
Data set length: 00080    Table name: VID_ITEM                                +
                                                                               
Actions: S Display, U Update, I Insert, D Delete                               
                                                                               
A Field    Bytes Start Type DB2 column name                  Exit     Pic Par  
- -------- ----- ----- ---- ------------------------------   -------- --- ---  
 ******************************* Bottom of data ********************************

Initially, there are no fields defined for a new file. To insert field information, specify option I on the command line. Insert field mapping information using the following screen:

Figure 3. Insert field panel
 
----------------------------- CICS VT: Insert field ----------------------------
 Command ===> ____________________________________________ Scroll ===> CSR_     
                                                                                
 DIM name       : VIDKSDS                                                       
 Creator        : VID                                                         +
 Table          : VID_ITEM                                                    +
 Data set length: 00080                                                         
                                                                                
                                                                                
 Field name . . .  ===> VIDM0001                                                
 Field length . .  ===> 00006                (In bytes)                         
 Field type . . .  ===> C                    (C,P,U,F,H,B)     
 Column name  . .  ===> ITEM_NUMBER..................... + (Look-up available)    
 Starting position ===> 00001                ("1" = Beginning of data set)      
 Picture  . . . .  ===> __________________________  (example HH.XX.SS.NNNNNN)   
                                                         (or MMDDYY)            
                                                         (or EXITx=exit name)   
 Parameters . . .  ===> __________________________  Optional user parameters    
 Special function  ===> KEY                  ("KEY", "PTH", "BKY", or blank)    
 Mapped from table ===> P                    ("P"=primary, "X"=not mapped)      
 Build order  . .  ===> 00001                ("1"=first, "2"=second and so on)  
                                                                                
 Press: Enter=Insert  PF3=Exit  PF1=Help                                                                                                                       
Table 1. Field values
Field Description
Field name A generated 8-byte value that is unique for the data set. You will normally have one CICS VT field per copybook field.
Field length The length of the field. Assuming that you are mapping one copybook field to one DB2® column, this is the length of the copybook field.
Field type The options are as follows:
  C = Character or zoned decimal
  P = Signed packed decimal
  U = Unsigned packed decimal
  F = Fullword (4 bytes binary)
  H = Halfword (2 bytes binary)
  B = Two fullwords (8 bytes binary)
Column name The name of the DB2 column that the field maps to. If wildcard character % is used, CICS VT builds a selectable list of all matching columns in the table from the DB2 catalog. This field is scrollable, although the maximum DB2 column name is 30 characters.
Starting position The start position of this field within the VSAM record. CICS VT calculates this based on the position and length of the preceding field.
Picture The layout of date or time fields, or the name of the FBE. See Specifying a picture string.
Parameters Optional user parameters. See Specifying optional parameters.
Special function Special function applies to fields in your VSAM file that are either part of the file key or an alternate index key. A value of KEY is automatically generated for the first inserted field, as shown in Figure 3. The values PTH and BKY only apply to alternate index mapping, which is covered in Mapping the alternate index paths. Leave the field blank in all other cases.
Mapped from table Always specify P unless you are mapping a multiple field key, in which case specify X. This is explained in Multiple field key.
Build order A sequence number generated by CICS VT.
Mapping is an iterative process and is performed for each copybook field, excluding group fields. The completed mapping for the VIDKSDS file is shown in Figure 4.
Figure 4. List of fields panel Start of change
 
 ------------------- CICS VT: List of fields for VIDKSDS     Row 1 to 10 of 10
Command ===> ________________________________________________ Scroll ===> CSR 
                                                                              
VSAM file type : KSDS     Creator   : VID                                    +
Data set length: 00080    Table name: VID_ITEM                               +
                                                                              
Actions: S Display, U Update, I Insert, D Delete                              
                                                                              
A Field    Bytes Start Type DB2 column name                  Exit     Pic Par 
- -------- ----- ----- ---- ------------------------------   -------- --- --- 
_ VIDKEY   00006 00001   C  ITEM_NUMBER                    +                  
_ VIDF001  00012 00007   C  ITEM_NAME                      +                  
_ VIDF002  00006 00019   C  ITEM_COLOUR                    +                  
_ VIDF003  00004 00025   C  ITEM_WEIGHT                    +                  
_ VIDF004  00004 00029   P  ITEM_COST                      +                  
_ VIDF005  00003 00033   C  ITEM_REORDER_NO                +                  
_ VIDF006  00003 00036   C  ITEM_SUPP_CODE                 +                  
_ VIDF007  00005 00039   P  ITEM_DATE_FSHIP                +           Y      
_ VIDF008  00002 00044   C  ITEM_SHELF_LIFE                +                  
_ VIDF009  00035 00046   C  ITEM_DESCRIPTION               +                  
******************************* Bottom of data *******************************                                                                                                                     
End of change

The field VIDF007 maps to column ITEM_DATE_FSHIP, which is a DB2 data type of DATE. This requires additional mapping information, which is explained in Specifying a picture string.

Specifying a picture string

Use the Picture field to provide field-level re-engineering information to CICS VT in two specific cases:
  • If the DB2 column you specify in Column name has a data type of DATE, TIME, or TIMESTAMP. For example, if the DB2 column is a data type of DATE, you could specify CCYYMMDD as the picture layout for this field.
  • If the field will be built by a user written Assembler exit (EXITA=) or an LE/370 language exit (EXITL=).

These cases are discussed in greater detail in the CICS VT Data Reengineering and Customization Guide. Leave the Picture field value blank if neither case applies.

Specifying optional parameters

You can use nullable DB2 columns but only for columns that do not map to either the base cluster or alternate index fields. Using the optional Parameters field, you can specify up to three different single-byte values. If each byte in a VSAM field matches one of the specified values, CICS VT sets the column value to NULL.

Up to three parameters can be specified as follows:
NULL[[=input1[input2][input3]],[output],[nullif]
Where:
input1-3
Up to 3 characters that define the repeating input VSAM field value that becomes NULL in DB2
output
A single character that defines the repeating value in the entire VSAM field that is returned to your application program
nullif
A single character that the VIDLOAD utility writes in the first byte of the field in the output data. Use this with the NULLIF DB2 LOAD utility parameter.

When multiple input values and an output value are specified, the order of the input values is not significant. When multiple input values are specified without an output value, the output value defaults to the first input value.

Valid input and output values are:
L
low-values (x'00's)
H
high-values (x'FF's)
S
spaces (x'40's)
Z
zeroes (x'F0's for zoned decimal or x'0C' or x'0F' for packed decimal)
9
nines (x'F9's for zoned decimal or x'9C' or x'9F' for packed decimal)

Any displayable character is valid for the nullif parameter. The value you specify must never be the value of the first byte in a valid field that is mapped to a nullable column.

Example 1
NULL

In example 1, an input field of low-values becomes a null value in DB2. The value returned from DB2 is low-values, and the nullif character in the DB2 load file is "?".

Example 2
NULL=S

An input field of spaces becomes a null value in DB2. The value returned from DB2 is spaces, and the nullif character in the DB2 load file is"?".

Example 3
NULL=LHS,S,£

An input field of low-values, high-values or spaces becomes a null value in DB2. The value returned from DB2 is spaces, and the nullif character in the DB2 load file is "£".

Example 4
NULL=,,@

An input field of low-values becomes a null value in DB2. The value returned from DB2 is low-values, and the nullif character in the DB2 load file is "@".

Example 5
NULL=,S

An input field of low-values becomes a null value in DB2. The value returned from DB2 is spaces, and the nullif character in the DB2 load file is "?".

Be aware of the following before choosing to use nullable columns and the NULLS parameters:

  1. Ensure that the nullif parameter value you use cannot be the first character of a field that is mapped to a nullable column.
  2. Only use Z (zeros) and N (nines) for fields with types of C, P, or U. These parameter values have no relevance for the other field types.
  3. If a field potentially has multiple values that become nulls, the dual mode facility will erroneously signal errors during application testing. Some manual data cleansing in VSAM to eliminate multiple nullable values in the same field is recommended.

When you use the NULLS facility, it is recommended that you use the automated data migration facility. Alternatively, use the DB2 sample REXX DRAW command to generate the LOAD utility control cards. The utility control cards generated by DSNTIAUL have to be edited manually when the CICS VT table contains nullable columns.


Information Information

Feedback


Timestamp icon Last updated: Monday, 10 February 2014


http://pic.dhe.ibm.com/infocenter/cicsts/v5r1/topic/com.ibm.cics.vt.doc//topics/cvtug_mapping_fields.html