DFSCASE statements
The DFSCASE statement defines a map case, which is a set of FIELD statements that together define an optional, alternative field layout for a given byte range within a segment definition.
Map cases that map the same byte range in a segment are grouped by a DFSMAP statement. The DFSMAP statement also links the map cases to a separately defined control field in the segment definition.
Each map case has a unique ID. In an instance of the segment, the ID of the map case that is in effect is stored in the control field when the segment is created.
Unless the IMS universal drivers are used, the field layouts that are defined by the map cases must be defined to the application programs that access this byte range by a COBOL copybook or other programming artifact. At the time a segment instance is accessed, the application programs determine which copybook to use by checking the value of the control field.
When application programs access IMS through the IMS Universal drivers, no additional programming artifacts are needed to define the field layouts to the application programs.
The format of the DFSCASE statement for all database types is shown in the following syntax diagram.
DFSCASE statement syntax diagram for all database types
DFSCASE statement parameter description
- CASEID
- A 1- to 128-byte field that defines a unique identifier for the
case.
A segment instance specifies the CASEID value in a user-defined control field when part or all of the field structure of the segment is mapped by this case.
When CASEIDTYPE=C, the CASEID field can contain alphanumeric characters, _, @, $, and #. Single quotation marks are supported, but not required. Blanks are not supported.
When CASEIDTYPE=X, the only valid characters in the CASEID parameter are 0-9 and A-F.
The length of the CASEID value must be supported by the length of the user-defined control field. If CASEIDTYPE=C, the length of the CASEID value must be less than or equal to the value specified on the BYTES parameter of the control field. If CASEIDTYPE=X, the length of the CASEID value must be exactly equal to twice the value specified on the BYTES parameter of the control field.
A case ID must be unique within the map that the case belongs to.
- CASEIDTYPE
- Defines the data type of the value specified in the CASEID parameter.
Valid values are C, which specifies Cp1047 (EBCDIC character encoding)
and X, which specifies hexadecimal.
Depending on whether C or X is specified on CASEIDTYPE, the valid length of the CASEID value is calculated differently. The length is valid when it is consistent with the length specified on the BYTES parameter of the field referenced by the DEPENDINGON parameter in the DFSMAP statement. For CASEIDTYPE=C, the length of the CASEID value must be less than or equal to the value specified on the BYTES parameter. For CASEIDTYPE=X, the length of the CASEID value must be exactly equal to twice the value specified on the BYTES parameter.
- MAPNAME
- The name of the map that this case belongs to, as specified on the NAME parameter in the DFSMAP statement. This field is required.
- NAME
- A required 1- to 128-character, alphanumeric field that defines
the name of this case. Blanks are not supported.
A case name must be unique within a segment.
- 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