DFSMAP statements
The DFSMAP statement enables the alternate mapping of fields within a segment.
The DFSMAP statement defines a group of one or more map cases and relates the cases to a control field. The control field identifies which map case is used in a given segment instance.
The format of the DFSMAP statement for all database types is shown in the following syntax diagram.
DFSMAP statement syntax diagram for all database types
DFSMAP statement parameter description
CTLSEGNM=
- An optional parameter that specifies the NAME of the segment whose key feedback data is used to
determine which map case is used for a given segment instance. The segment specified must be in the
hierarchical path of the current segment for its value to be stored in the IMS catalog. When the
CTLSEGNM parameter is specified, the DEPENDINGON= parameter must specify the name of the control
field that is within the key range of the segment that is specified in CTLSEGNM.
The CTLSEGNM= specifies a name as a 1 to 8-character uppercase alphanumeric string. Each character must be in the range of A through Z, or 0 through 9, or be the character $, #, @. The first character cannot be numeric. The same restrictions apply as those for the NAME= parameter of the SEGM statement. The specified segment must be in the hierarchical path of the current segment.
Note:- CTLSEGNM cannot be specified for GSAM, MSDB, logical and index databases.
- The CTLSEGNM parameter is ignored if the name of the segment specified is blank or if it is the name of the current segment.
- DEPENDINGON=
- The external name of the control field within this segment that contains the value that
determines which map case is used for a given segment instance.
When the CTLSEGNM parameter is also specified, the external name of the control field must be a field within the key range of the segment specified in CTLSEGNM. Otherwise, the external name of the control field must be within this segment. When the CTLSEGNM parameter is also specified, the validation of DEPENDINGON is deferred during DFSMAP processing and is completed after all the SEGM statements are processed. If the control field does not contain a value that corresponds to a CASEID in a DFSCASE statement for this map, this map is not used for this segment instance. If the FIELD statement that defines the control field does not explicitly code the EXTERNALNAME parameter, specify the value of the NAME parameter in the DEPENDINGON field.
- NAME=
- A required 1- to 128-character alphanumeric field that defines the name of this map. Blanks are not supported.
- REMARKS=
- Optional user comments. A 1- to 256-character field.
If your comments contain special characters, such as commas or blank spaces, enclose the full comment string in single quotation marks.
The value specified on the REMARKS keyword cannot contain the following characters:- Single quotation marks, except when they are used to enclose the full comment string. If
a single quotation mark is entered before the end of the full comment string, the remainder
of the comment string is truncated. The following examples show correct and incorrect
usages of single quotation marks on the REMARKS keyword:
- CORRECT
REMARKS='These remarks apply to the XYZ application'- INCORRECT
REMARKS='These remarks apply to the 'XYZ' application'
- Double quotation marks.
- Less than (< ) symbols.
- Greater than ( >) symbols.
- Ampersands (&).
- Single quotation marks, except when they are used to enclose the full comment string. If
a single quotation mark is entered before the end of the full comment string, the remainder
of the comment string is truncated. The following examples show correct and incorrect
usages of single quotation marks on the REMARKS keyword:
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