Defining alternative field maps for a segment
You can define multiple alternative field maps for a single sequence of bytes in a segment definition. When an instance of the segment is created in the database, the application program selects one of the fields maps to map the data and indicates the field map that is in effect by inserting the ID of the field map into a control field.
The control field that identifies the map case that is
used for a segment instance is in one of the following locations:- The current segment.
- Another segment that is within the same hierarchical path as the current segment if CTLSEGNM= is specified on the DFSMAP statement.
When an application program accesses a sequence of bytes in a segment instance that uses field mapping, the application program must evaluate the control field to determine which field map is in effect.
Each field map, or map case, in a segment definition is defined to IMS by coding a DFSCASE statement. The fields that make up a field map are defined by FIELD statements that specify the name of the map case on the CASENAME parameter.
A set of map cases that map the same sequence of bytes in a segment share the same control field. In the segment definition, a DFSMAP statement links the set of related map cases to the control field. The map case definitions must specify the name of the DFSMAP statement on the MAPNAME parameter in the DFSCASE statement.
The FIELD statements for the fields that are contained in a map must follow the DFSCASE statement that defines the map that they belong to. Each field in the map must specify the map name on the CASENAME parameter.
To define alternative field maps for a sequence of bytes in a segment definition:
Procedure
- Define the control field to contain the case ID that determines
which map case is in effect in a segment instance. Case IDs can be either a character value or a hexadecimal value. The data type and byte length specified in the control field definition must accommodate the data type and lengths of the case IDs specified in the definitions of the map cases.
- Define a DFSMAP statement that will group the collection of map cases. The external name of the control field must be specified on the DEPENDINGON parameter.
- Define a DFSCASE statements for each map case. The length of the control field must support the length and data type of the value that you specify on the CASEID parameter.
- Define the FIELD statements for the fields that belong
to each map case. Specify the name of the map case that each field belongs to in the CASENAME parameter.
- Optionally, specify the CTLSEGNM= on the DFSMAP statement if you want
to use a DEPENDINGON= field from a segment in the same segment hierarchy. Specify the CTLSEGNM= and perform the DBDGEN, ACBGEN, and IMS Catalog Populate utility to write the CTLSEGNM to the IMS Catalog. The IMS Universal Drivers will issue a GUR call to retrieve the CTLSEGNM value from the IMS Catalog and then use that value to determine how to map the fields in the result set returned to the application.The Universal Driver will see the CTLSEGNM= as valid only if it exists in the parent segment hierarchy in relation to the segment where the DFSMAP statement resides. However, it is possible to specify a CTLSEGNM= in a child segment hierarchy and access it via Secondary Index, which has the effect of reversing the hierarchical view of the database, effectively making the CTLSEGNM= valid. Since the Universal Driver only validates CTLSEGNM= that exists in the parent hierarchical path, CTLSEGNM= that exists in the parent and child hierarchical path of the current segment being retrieved will not be populated into the result set at the same time. Mapped fields with CTLSEGNM= intended to be used for Secondary Index view (indicating that they exist in the child segment) will not be displayed in a Result Set retrieved using the default or primary view and vice versa.
Mapping example: DFSMAP and DFSCASE
The following example shows how mapping might be used in the DBD source to define a single segment that is used to store data about three different types of insurance policy: an auto insurance policy, a home insurance policy, and a boat insurance policy. Each policy type requires different fields to hold the information that is unique to that policy type.
In the DBD source, the fields for each policy type are mapped by a different DFSCASE statement. The three map cases in the example are named AUTOMAP, HOMEMAP, and BOATMAP. The fields that make up the map defined by a given DFSCASE statement each specify the name of the DFSCASE statement that they belong to on the CASENAME parameter in their FIELD statement. The DFSCASE statements are grouped by the DFSMAP statement POLICYMAPS in the segment CUSTOMERPOLICY.
The value specified on the CASEID parameter of each map case uniquely identifies the map case and serves as the control field value. When a segment instance is first inserted into the database, the ID of the map case that the segment instance uses is inserted into the control field. In the example, the control field is named POLICYTYPE. At run time, when an application program retrieves the segment from the database, the application program must evaluate the control field value to determine the correct mapping of the fields.
DBD NAME=POLICYDB, C
ENCODING=CP1047, C
ACCESS=(DEDB), C
RMNAME=(RMOD3), C
PASSWD=NO
AREA DD1=PLCYAR01, C
DEVICE=3330, C
SIZE=(2048), C
UOW=(15,10), C
ROOT=(10,5), C
REMARKS='AREA NUMBER 1 FOR POLICYDB DATABASE'
SEGM NAME=CUSTOMER, C
PARENT=0, C
BYTES=(390,20)
FIELD NAME=(CUSTKEY,SEQ,U), C
BYTES=12, C
START=1, C
TYPE=C
SEGM NAME=POLICY, C
EXTERNALNAME=CUSTOMERPOLICY, C
ENCODING=CP1047, C
PARENT=CUSTOMER, C
BYTES=(900), C
TYPE=DIR, C
RULES=(LLL,HERE)
***********************************************************************
* CONTROL FIELD:
***********************************************************************
FIELD EXTERNALNAME=POLICYTYPE, C
BYTES=4, C
START=1, C
DATATYPE=CHAR
***********************************************************************
* DFSMAP STATEMENT:
***********************************************************************
DFSMAP NAME=POLICYMAPS, C
DEPENDINGON=POLICYTYPE
***********************************************************************
* DFSCASE STATEMENT 1:
***********************************************************************
DFSCASE NAME=AUTOMAP, C
CASEID=AUTO, C
CASEIDTYPE=C, C
MAPNAME=POLICYMAPS, C
REMARKS='DEFINES THE FIELDS OF AN AUTO INSURANCE POLICY'
FIELD EXTERNALNAME=AUTOMAKE, C
CASENAME=AUTOMAP, C
BYTES=15, C
START=5, C
DATATYPE=CHAR
FIELD EXTERNALNAME=MODEL, C
CASENAME=AUTOMAP, C
BYTES=15, C
START=20, C
DATATYPE=CHAR
FIELD EXTERNALNAME=YEAR, C
CASENAME=AUTOMAP, C
BYTES=4, C
START=35, C
DATATYPE=CHAR
***********************************************************************
* DFSCASE STATEMENT 2:
***********************************************************************
DFSCASE NAME=HOMEMAP, C
CASEID=HOME, C
CASEIDTYPE=C, C
MAPNAME=POLICYMAPS, C
REMARKS='DEFINES THE FIELDS OF A HOME INSURANCE POLICY'
FIELD EXTERNALNAME=DWELLING_TYPE, C
CASENAME=HOMEMAP, C
BYTES=20, C
START=5, C
DATATYPE=CHAR
FIELD EXTERNALNAME=ROOMS, C
CASENAME=HOMEMAP, C
BYTES=5, C
START=25, C
DATATYPE=CHAR
FIELD EXTERNALNAME=SQ_FOOT, C
CASENAME=HOMEMAP, C
BYTES=6, C
START=30, C
DATATYPE=CHAR
***********************************************************************
* DFSCASE STATEMENT 3:
***********************************************************************
DFSCASE NAME=BOATMAP, C
CASEID=BOAT, C
CASEIDTYPE=C, C
MAPNAME=POLICYMAPS, C
REMARKS='DEFINES THE FIELDS OF A BOAT INSURANCE POLICY'
FIELD EXTERNALNAME=CLASS, C
CASENAME=BOATMAP, C
BYTES=10, C
START=5, C
DATATYPE=CHAR
FIELD EXTERNALNAME=LENGTH, C
CASENAME=BOATMAP, C
BYTES=6, C
START=15, C
DATATYPE=CHAR
FIELD EXTERNALNAME=BOATMAKE, C
CASENAME=BOATMAP, C
BYTES=10, C
START=21, C
DATATYPE=CHAR
DBDGEN
FINISH
END