FIELD statements
The FIELD statement defines a field within a segment type. Fields are referred to by PSBs when defining sensitivity to the fields or by an application program in a DL/I call segment search argument.
- A maximum of 1,000 FIELD statements that include the NAME parameter and XDFLD statements combined can be defined for all segments in a DBD generation.
- A maximum of 10,000 XDFLD statements and all FIELD statements combined can be defined for all segments in a DBD generation.
- A maximum of 255 FIELD statements and XDFLD statements combined can be defined for any segment type.
The use of /SX to define unique secondary indexes in HDAM, HIDAM, PHDAM, and PHIDAM databases causes a 4-byte RBA of the index source segment to be included as part of the key of the index record. The use of /CK to define unique secondary indexes in HISAM, HDAM, HIDAM, PHDAM, and PHIDAM databases does the same. In a PSINDEX, the /SX specification causes an 8-byte ILK to be used instead of a 4-byte RBA.
PSINDEX entries also contain the root key of the target segment.
FIELD statements are used in DBD generation:
- To define fields of a segment type as that segment type is seen when it is accessed from its physical parent segment.
- To define the fields of a real logical child segment type in a virtually paired logical relationship as seen when that segment type is accessed from its logical parent. The FIELD statements must immediately follow the SEGM statement defining the virtual logical child.
- To define system-related fields that are used for secondary indexing.
The FIELD statement parameter descriptions are documented following the syntax diagrams below.
The format of the FIELD statement for each database type is shown in the following syntax diagrams.
DEDB database FIELD statement
>>-FIELD--------------------------------------------------------> >--+-NAME=(fldname1-+---------+-)------------------------------+--> | '-,SEQ-,U-' | +-NAME=(fldname1-+---------+-)--,EXTERNALNAME=external_name-+ | '-,SEQ-,U-' | '-EXTERNALNAME=external_name--------------------------------' >--+-,BYTES=bytes--------------+--+-,START=startpos--------+----> '-,MAXBYTES=max_array_bytes-' +-,STARTAFTER=field_name-+ '-,RELSTART=relstartpos--' >--+--------------+--+-------------------------------+----------> | .-C-. | '-,DATATYPE=-+-ARRAY----------+-' '-,TYPE=-+-X-+-' +-BINARY---------+ '-P-' +-BIT------------+ +-BYTE-----------+ +-UBYTE----------+ +-CHAR-----------+ +-DATE-----------+ +-DECIMAL(pp,ss)-+ +-DOUBLE---------+ +-FLOAT----------+ +-INT------------+ +-UINT-----------+ +-LONG-----------+ +-ULONG----------+ +-OTHER----------+ +-SHORT----------+ +-USHORT---------+ +-STRUCT---------+ +-TIME-----------+ +-TIMESTAMP------+ '-XML------------' >--+---------------------+--+-----------------------+-----------> '-,CASENAME=case_name-' '-,DEPENDSON=field_name-' >--+-------------------------------+----------------------------> '-,MINOCCURS=min_array_elements-' >--+-------------------------------+--+--------------------+----> '-,MAXOCCURS=max_array_elements-' '-,PARENT=field_name-' >--+-----------------------+--+-------------------+------------>< '-,REDEFINES=field_name-' '-,REMARKS=comments-'
HDAM and PHDAM database FIELD statement
>>-FIELD--------------------------------------------------------> >--+-NAME=-+-(fldname1-+-------------+-)-+------------------------------+--> | | | .-,U-. | | | | | '-,SEQ-+-,M-+-' | | | | (1) | | | '-systrelfldname--------------' | +-NAME=-+-(fldname1-+-------------+-)-+--,EXTERNALNAME=external_name-+ | | | .-,U-. | | | | | '-,SEQ-+-,M-+-' | | | | (1) | | | '-systrelfldname--------------' | '-EXTERNALNAME=external_name-----------------------------------------' >--+-,BYTES=bytes--------------+--+-,START=startpos--------+----> '-,MAXBYTES=max_array_bytes-' +-,STARTAFTER=field_name-+ '-,RELSTART=relstartpos--' >--+------------------+--+-------------------------------+------> | .-C-. (2) | '-,DATATYPE=-+-ARRAY----------+-' '-,TYPE=-+-X-+-----' +-BINARY---------+ '-P-' +-BIT------------+ +-BYTE-----------+ +-UBYTE----------+ +-CHAR-----------+ +-DATE-----------+ +-DECIMAL(pp,ss)-+ +-DOUBLE---------+ +-FLOAT----------+ +-INT------------+ +-UINT-----------+ +-LONG-----------+ +-ULONG----------+ +-OTHER----------+ +-SHORT----------+ +-USHORT---------+ +-STRUCT---------+ +-TIME-----------+ +-TIMESTAMP------+ '-XML------------' >--+---------------------+--+-----------------------+-----------> '-,CASENAME=case_name-' '-,DEPENDSON=field_name-' >--+-------------------------------+----------------------------> '-,MINOCCURS=min_array_elements-' >--+-------------------------------+--+--------------------+----> '-,MAXOCCURS=max_array_elements-' '-,PARENT=field_name-' >--+-----------------------+--+-------------------+------------>< '-,REDEFINES=field_name-' '-,REMARKS=comments-'
- A system related field used for secondary indexing.
- The TYPE=parameter is ignored for fields with a systrelfldname.
HIDAM and PHIDAM database FIELD statements
>>-FIELD--------------------------------------------------------> >--+-NAME=-+-(fldname1-+-------------+-)-+------------------------------+--> | | | .-,U-. | | | | | '-,SEQ-+-,M-+-' | | | | (1) | | | '-systrelfldname--------------' | +-NAME=-+-(fldname1-+-------------+-)-+--,EXTERNALNAME=external_name-+ | | | .-,U-. | | | | | '-,SEQ-+-,M-+-' | | | | (1) | | | '-systrelfldname--------------' | '-EXTERNALNAME=external_name-----------------------------------------' >--+-,BYTES=bytes--------------+--+-,START=startpos--------+----> '-,MAXBYTES=max_array_bytes-' +-,STARTAFTER=field_name-+ '-,RELSTART=relstartpos--' >--+------------------+--+-------------------------------+------> | .-C-. (2) | '-,DATATYPE=-+-ARRAY----------+-' '-,TYPE=-+-X-+-----' +-BINARY---------+ '-P-' +-BIT------------+ +-BYTE-----------+ +-UBYTE----------+ +-CHAR-----------+ +-DATE-----------+ +-DECIMAL(pp,ss)-+ +-DOUBLE---------+ +-FLOAT----------+ +-INT------------+ +-UINT-----------+ +-LONG-----------+ +-ULONG----------+ +-OTHER----------+ +-SHORT----------+ +-USHORT---------+ +-STRUCT---------+ +-TIME-----------+ +-TIMESTAMP------+ '-XML------------' >--+---------------------+--+-----------------------+-----------> '-,CASENAME=case_name-' '-,DEPENDSON=field_name-' >--+-------------------------------+----------------------------> '-,MINOCCURS=min_array_elements-' >--+-------------------------------+--+--------------------+----> '-,MAXOCCURS=max_array_elements-' '-,PARENT=field_name-' >--+-----------------------+--+-------------------+------------>< '-,REDEFINES=field_name-' '-,REMARKS=comments-'
- A system related field used for secondary indexing.
- The TYPE=parameter is ignored for fields with a systrelfldname.
HISAM database FIELD statement
(1) >>-------FIELD--------------------------------------------------> >--+-NAME=-+-(fldname1-+-------------+-)-+------------------------------+--> | | | .-,U-. | | | | | '-,SEQ-+-,M-+-' | | | | (2) | | | '-systrelfldname--------------' | +-NAME=-+-(fldname1-+-------------+-)-+--,EXTERNALNAME=external_name-+ | | | .-,U-. | | | | | '-,SEQ-+-,M-+-' | | | | (2) | | | '-systrelfldname--------------' | '-EXTERNALNAME=external_name-----------------------------------------' >--+-,BYTES=bytes--------------+--+-,START=startpos--------+----> '-,MAXBYTES=max_array_bytes-' +-,STARTAFTER=field_name-+ '-,RELSTART=relstartpos--' >--+------------------+--+-------------------------------+------> | .-C-. (3) | '-,DATATYPE=-+-ARRAY----------+-' '-,TYPE=-+-X-+-----' +-BINARY---------+ '-P-' +-BIT------------+ +-BYTE-----------+ +-UBYTE----------+ +-CHAR-----------+ +-DATE-----------+ +-DECIMAL(pp,ss)-+ +-DOUBLE---------+ +-FLOAT----------+ +-INT------------+ +-UINT-----------+ +-LONG-----------+ +-ULONG----------+ +-OTHER----------+ +-SHORT----------+ +-USHORT---------+ +-STRUCT---------+ +-TIME-----------+ +-TIMESTAMP------+ '-XML------------' >--+---------------------+--+-----------------------+-----------> '-,CASENAME=case_name-' '-,DEPENDSON=field_name-' >--+-------------------------------+----------------------------> '-,MINOCCURS=min_array_elements-' >--+-------------------------------+--+--------------------+----> '-,MAXOCCURS=max_array_elements-' '-,PARENT=field_name-' >--+-----------------------+--+-------------------+------------>< '-,REDEFINES=field_name-' '-,REMARKS=comments-'
- Only CK can be coded for the systrelfldname field.
- A system related field used for secondary indexing.
- The TYPE=parameter is ignored for fields with a systrelfldname.
HSAM/SHSAM database FIELD statement
>>-FIELD--------------------------------------------------------> >--+-NAME=(fldname1-+----------------+-)------------------------------+--> | | .-,U-. | | | '-,--SEQ--+-,M-+-' | +-NAME=(fldname1-+----------------+-)--,EXTERNALNAME=external_name-+ | | .-,U-. | | | '-,--SEQ--+-,M-+-' | '-EXTERNALNAME=external_name---------------------------------------' >--+-,BYTES=bytes--------------+--+-,START=startpos--------+----> '-,MAXBYTES=max_array_bytes-' +-,STARTAFTER=field_name-+ '-,RELSTART=relstartpos--' >--+--------------+--+-------------------------------+----------> | .-C-. | '-,DATATYPE=-+-ARRAY----------+-' '-,TYPE=-+-X-+-' +-BINARY---------+ '-P-' +-BIT------------+ +-BYTE-----------+ +-UBYTE----------+ +-CHAR-----------+ +-DATE-----------+ +-DECIMAL(pp,ss)-+ +-DOUBLE---------+ +-FLOAT----------+ +-INT------------+ +-UINT-----------+ +-LONG-----------+ +-ULONG----------+ +-OTHER----------+ +-SHORT----------+ +-USHORT---------+ +-STRUCT---------+ +-TIME-----------+ +-TIMESTAMP------+ '-XML------------' >--+---------------------+--+-----------------------+-----------> '-,CASENAME=case_name-' '-,DEPENDSON=field_name-' >--+-------------------------------+----------------------------> '-,MINOCCURS=min_array_elements-' >--+-------------------------------+--+--------------------+----> '-,MAXOCCURS=max_array_elements-' '-,PARENT=field_name-' >--+-----------------------+--+-------------------+------------>< '-,REDEFINES=field_name-' '-,REMARKS=comments-'
INDEX/PSINDEX database FIELD statement
>>-FIELD--------------------------------------------------------> .-,U-. >--+-NAME=(fldname1-+------+-+-,M-+-)------------------------------+--> | '-,SEQ-' | | .-,U-. | +-NAME=(fldname1-+------+-+-,M-+-)--,EXTERNALNAME=external_name-+ | '-,SEQ-' | '-EXTERNALNAME=external_name------------------------------------' >--+-,BYTES=bytes--------------+--+-,START=startpos--------+----> '-,MAXBYTES=max_array_bytes-' +-,STARTAFTER=field_name-+ '-,RELSTART=relstartpos--' >--+--------------+--+-------------------------------+----------> | .-C-. | '-,DATATYPE=-+-ARRAY----------+-' '-,TYPE=-+-X-+-' +-BINARY---------+ '-P-' +-BIT------------+ +-BYTE-----------+ +-UBYTE----------+ +-CHAR-----------+ +-DATE-----------+ +-DECIMAL(pp,ss)-+ +-DOUBLE---------+ +-FLOAT----------+ +-INT------------+ +-UINT-----------+ +-LONG-----------+ +-ULONG----------+ +-OTHER----------+ +-SHORT----------+ +-USHORT---------+ +-STRUCT---------+ +-TIME-----------+ +-TIMESTAMP------+ '-XML------------' >--+---------------------+--+-----------------------+-----------> '-,CASENAME=case_name-' '-,DEPENDSON=field_name-' >--+-------------------------------+----------------------------> '-,MINOCCURS=min_array_elements-' >--+-------------------------------+--+--------------------+----> '-,MAXOCCURS=max_array_elements-' '-,PARENT=field_name-' >--+-----------------------+--+-------------------+------------>< '-,REDEFINES=field_name-' '-,REMARKS=comments-'
MSDB database FIELD statement
>>-FIELD--------------------------------------------------------> >--+-NAME=(fldname1-+----------+-)------------------------------+--> | '-,SEQ--,U-' | +-NAME=(fldname1-+----------+-)--,EXTERNALNAME=external_name-+ | '-,SEQ--,U-' | '-EXTERNALNAME=external_name---------------------------------' >--,BYTES=bytes--,START=startpos--+--------------+--------------> | .-C-. | '-,TYPE=-+-X-+-' +-P-+ +-H-+ '-F-' >--+-------------------------------+--+---------------------+---> '-,DATATYPE=-+-ARRAY----------+-' '-,CASENAME=case_name-' +-BINARY---------+ +-BIT------------+ +-BYTE-----------+ +-UBYTE----------+ +-CHAR-----------+ +-DATE-----------+ +-DECIMAL(pp,ss)-+ +-DOUBLE---------+ +-FLOAT----------+ +-INT------------+ +-UINT-----------+ +-LONG-----------+ +-ULONG----------+ +-OTHER----------+ +-SHORT----------+ +-USHORT---------+ +-STRUCT---------+ +-TIME-----------+ +-TIMESTAMP------+ '-XML------------' >--+-------------------+--------------------------------------->< '-,REMARKS=comments-'
SHISAM database FIELD statement
(1) >>-------FIELD--------------------------------------------------> >--+-NAME=-+-(fldname1-+-------------+-)-+------------------------------+--> | | | .-,U-. | | | | | '-,SEQ-+-,M-+-' | | | | (2) | | | '-systrelfldname--------------' | +-NAME=-+-(fldname1-+-------------+-)-+--,EXTERNALNAME=external_name-+ | | | .-,U-. | | | | | '-,SEQ-+-,M-+-' | | | | (2) | | | '-systrelfldname--------------' | '-EXTERNALNAME=external_name-----------------------------------------' >--+-,BYTES=bytes--------------+--+-,START=startpos--------+----> '-,MAXBYTES=max_array_bytes-' +-,STARTAFTER=field_name-+ '-,RELSTART=relstartpos--' >--+------------------+--+-------------------------------+------> | .-C-. (3) | '-,DATATYPE=-+-ARRAY----------+-' '-,TYPE=-+-X-+-----' +-BINARY---------+ '-P-' +-BIT------------+ +-BYTE-----------+ +-UBYTE----------+ +-CHAR-----------+ +-DATE-----------+ +-DECIMAL(pp,ss)-+ +-DOUBLE---------+ +-FLOAT----------+ +-INT------------+ +-UINT-----------+ +-LONG-----------+ +-ULONG----------+ +-OTHER----------+ +-SHORT----------+ +-USHORT---------+ +-STRUCT---------+ +-TIME-----------+ +-TIMESTAMP------+ '-XML------------' >--+---------------------+--+-----------------------+-----------> '-,CASENAME=case_name-' '-,DEPENDSON=field_name-' >--+-------------------------------+----------------------------> '-,MINOCCURS=min_array_elements-' >--+-------------------------------+--+--------------------+----> '-,MAXOCCURS=max_array_elements-' '-,PARENT=field_name-' >--+-----------------------+--+-------------------+------------>< '-,REDEFINES=field_name-' '-,REMARKS=comments-'
- Only CK can be coded for the systrelfldname field.
- A system related field used for secondary indexing.
- The TYPE=parameter is ignored for fields with a systrelfldname.
FIELD statement parameter descriptions
- BYTES=
- Specifies the length of the field being defined in bytes. For fields other than
system-related fields, BYTES must be a valid self-defining term whose value does not exceed
255.
If a concatenated key or a portion of a concatenated key of an index source segment type is defined as a system-related field, the value specified can be greater than 255, but must not exceed the length of the concatenated key of the index source segment.
A case in which the byte length can be greater than 255 is when the column is defined as not searchable by IMS. These columns cannot be defined as primary keys and cannot have the INTERNALNAME keyword specified.
The length of a /SX system-related field is always 4 bytes; therefore, when specified, the BYTES parameter is disregarded.
If this field is defined as either a structure or an array by STRUCT or ARRAY, the value specified on BYTES must be greater than or equal to the sum total of the bytes of all fields contained in the structure or array.
When XML, the BYTES parameter is optional and the valid values for BYTES range from 0 to the maximum size of the segment. If the BYTES parameter is omitted when XML, BYTES and MAXBYTES are not allowed.
- CASENAME=
- The name of the map case that this field belongs to when alternative mappings are defined for the fields in a segment. CASENAME is valid and required only to associate a FIELD statement with the preceding DFSCASE statement that defines the map case to which this field belongs. The value of CASENAME must match the value specified on the NAME parameter of the DFSCASE statement.
- DATATYPE=
- An optional 3- to 9-character alphanumeric
field that specifies the external data type of the field.
If DECIMAL is specified on the DATATYPE parameter, the default INTERNALTYPECONVERTER is signed PACKEDDECIMAL.
If DATE, TIME, or TIMESTAMP is specified on the DATATYPE parameter, you must specify either LONG or CHAR on the INTERNALTYPECONVERTER parameter in the DFSMARSH statement or specify a USERTYPECONVERTER. If a DFSMARSH statement is not included for this field, INTERNALTYPECONVERTER=LONG is the default. When LONG is used, the value is stored on DASD as the number of milliseconds since January 1, 1970.
If XML is specified on the DATATYPE parameter, the default INTERNALTYPECONVERTER is XML_CLOB, which is the only valid value when DATATYPE=XML is specified.
If STRUCT or ARRAY is specified on the DATATYPE parameter, the default INTERNALTYPECONVERTER is STRUCT or ARRAY, respectively, which are the only valid values when either one is specified on the DATATYPE parameter.
For all other values for DATATYPE, the value is used as the default INTERNALTYPECONVERTER.
If TYPE=C, DATATYPE defaults to CHAR. For any other specification of the TYPE parameter, DATATYPE defaults to BINARY.
Valid values are:- ARRAY
- When ARRAY is specified:
- The NAME parameter is not supported
- The EXTERNALNAME parameter is required
- The byte value specified on either the BYTES or MAXBYTES parameter must be equal to or greater than the sum total of the bytes of all fields contained in the array.
The MSDB database type does not support the ARRAY data type.
- BINARY
- If TYPE=P or TYPE=X is specified, BINARY is the default value of the DATATYPE parameter.
- BIT
- If you specify BIT, you must also specify BYTES=1.
- BYTE
- If you specify BYTE, you must also specify BYTES=1.
- UBYTE
- If you specify UBYTE, you must also specify BYTES=1.
- CHAR
- If TYPE=C is specified, CHAR is the default value of the DATATYPE parameter.
- DATE
- When DATE is specified, you must also specify BYTES=8, unless you also specify a DFSMARSH statement that includes either INTERNALTYPECONVERTER=CHAR or USERTYPECONVERTER=convertername.
- DECIMAL(pp,ss)
- pp
- Precision. A 1- to 2-byte numeric field greater than 0.
- ss
- Scale. A 1- to 2-byte numeric field greater than or equal to 0. The value specified for ss cannot be greater than the value of pp.
You must specify a value on the BYTES parameter that matches the decimal format that is used.
The default decimal format is signed packed decimal. To calculate the required value of the BYTES parameter for the signed packed decimal format, use the following formula: length = ceiling ( ( pp + 1) / 2 )
The default decimal format can be changed by specifying the INTERNALTYPECONVERTER parameter.
When the zoned decimal format is used, as specified by INTERNALTYPECONVERTER=ZONEDDECIMAL, use the following formula to calculate the value of the BYTES parameter: length = pp
- DOUBLE
- If you specify DOUBLE, you must also specify BYTES=8.
- FLOAT
- If you specify FLOAT, you must also specify BYTES=4.
- INT
- If you specify INT, you must also specify BYTES=4.
- UINT
- If you specify UINT, you must also specify BYTES=4.
- LONG
- If you specify LONG, you must also specify BYTES=8.
- ULONG
- If you specify ULONG, you must also specify BYTES=8.
- OTHER
- Specifies the use of a user-defined data type. When OTHER is specified, a DFSMARSH statement must also be specified with a user-provided type converter specified on the USERTYPECONVERTER parameter.
- SHORT
- If you specify SHORT, you must also specify BYTES=2.
- USHORT
- If you specify USHORT, you must also specify BYTES=2.
- STRUCT
- When STRUCT is specified, you cannot also specify the SEQ parameter if this
structure field contains a dynamic array field as a child. Dynamic array fields are defined with
DATATYPE=ARRAY and the DEPENDSON and MAXBYTES parameters, among others.
Also, the byte value specified on either the BYTES or MAXBYTES parameter must be equal to or greater than the sum total of the bytes of all fields contained in the structure.
The MSDB database type does not support the STRUCT data type.
- TIME
- When TIME is specified, you must also specify BYTES=8, unless you also specify a DFSMARSH statement that includes either INTERNALTYPECONVERTER=CHAR or USERTYPECONVERTER=convertername.
- TIMESTAMP
- When TIMESTAMP is specified, you must also specify BYTES=8, unless you also specify a DFSMARSH statement that includes either INTERNALTYPECONVERTER=CHAR or USERTYPECONVERTER=convertername.
- XML
- Restriction: DATATYPE=XML is not supported when the NAME parameter is specified.
- DEPENDSON
- Specifies the name of a field that defines the number of elements in a dynamic array. The FIELD
statement of the referenced field must precede the FIELD statement that specifies the DEPENDSON
parameter. The name specified must be the value, whether explicitly defined or accepted by default,
of the EXTERNALNAME parameter in the definition of the referenced field.
The DEPENDSON parameter is valid only when ARRAY is also specified. DEPENDSON is required if the values of MINOCCURS and MAXOCCURS are different.
The field referenced by the DEPENDSON parameter must be defined with one of the following DATATYPE values:- INT
- SHORT
- LONG
- DECIMAL with either (pp) or (pp,ss) specified, where ss is either 0 or 00.
The MSDB database type does not support the DEPENDSON parameter.
- EXTERNALNAME=
- An optional alias for the NAME= parameter. Java™
application programs use the external name to refer to the field. The external name is stored only
in the IMS™ catalog, not in the database that you are
defining.
The EXTERNALNAME parameter is required only when the NAME parameter is not specified. If the NAME parameter is not specified, you cannot search for this field.
Specify an external name as a 1- to 128-character uppercase alphanumeric string. An external name can include underscore characters.
External names must be unique within a segment.
The default value of the EXTERNALNAME parameter is the value of the NAME parameter.
Restriction: External names cannot be reserved SQL keywords or begin with DFS.If EXTERNALNAME is not specified and a reserved SQL keyword is specified in the NAME parameter, EXTERNALNAME accepts the NAME value as the default external name after appending
_COL
to the NAME value.For a list of reserved SQL keywords that are restricted by the IMS Universal drivers, see Portable SQL keywords restricted by the IMS Universal JDBC drivers.
- M or U
- See the entry for U or M later in this topic.
- MINOCCURS=
- If DECIMAL data type, the default INTERNAL TYPECONVERTER is signed PACKEDDECIMAL.
- MAXOCCURS=
- For ARRAY only, a required numeric value that specifies the maximum number of elements in an ARRAY. MAXOCCURS must be greater than or equal to MINOCCURS and not zero.
- MAXBYTES=
- Specifies the maximum size of a field in bytes when the byte-length of the field instance can
vary based on the number of elements in a dynamic array. MAXBYTES and BYTES are mutually
exclusive.
The value of MAXBYTES must be greater than or equal to the maximum possible sum total of the byte values of all fields nested under this field.
The MAXBYTES parameter is required and valid only in the following cases:- The field is defined as a dynamic array. A field is a dynamic array when the number of elements in the array can vary from one instance of the field to another. In the definition of a dynamic array, the DEPENDSON parameter references another field in the segment definition that will define the number of array elements for a given instance of the dynamic array.
- For a field defined as a static array or a structure that contains a nested field that is defined as a dynamic array.
The MSDB database type does not support the MAXBYTES parameter.
- NAME=fldname1
- Specifies the name of this field within a segment type. The name specified can be referred to by
an application program in a DL/I call SSA. Field names must be unique within a segment definition.
The fldname1 value must be a 1- to 8-character alphanumeric value.The NAME parameter is required on the following types of fields:
- Key-sequenced field types, which specify the SEQ parameter
- Field types that are referenced by a segment search argument (SSA)
- Field types that are referenced by in a SENFLD statement in a PSB
- Field types that are referenced by an XDFLD statement
For other field types, you can omit the NAME parameter when the EXTERNALNAME parameter is specified. Omitting the NAME parameter can save storage in the data management block (DMB) of a database. However, to be able to search on this field, you must specify the NAME parameter.
The NAME parameter cannot be specified on the following types of fields:- Fields that are defined as arrays. A field that is defined as an array includes ARRAY in the field definition.
- Fields that are defined as array elements. A field that is an array element specifies the name of an array field on the PARENT parameter in the FIELD statement.
- Fields that are defined as structures that contain one or more nested dynamic arrays. A field that is defined as a structure includes DATATYPE=STRUCT in the field definition.
- Fields that are contained in a structure that also contains a dynamic array. A field that is contained within a structure specifies the name of the structure field on the PARENT parameter in the FIELD statement.
- Fields that follow a dynamic array in a segment. A field that follows a dynamic array specifies the STARTAFTER parameter.
- Fields that include the RELSTART parameter to specify a starting position that is relative to the starting position of another field.
- Fields defined with XML.
- PARENT=
- Specifies the name of a field that is defined as a structure or array in which this field is contained. The referenced field must be defined with either DATATYPE=ARRAY or DATATYPE=STRUCT.
- REDEFINES=
The name of the redefined field, as specified on the EXTERNALNAME parameter of the FIELD statement that defines the redefined field. The value can be specified as a 1- to 128-character alphanumeric string.
If the redefined field does not specify the EXTERNALNAME parameter, the value of the NAME parameter can be used. If the redefined field specifies both the NAME and EXTERNALNAME parameters with different values on each, the value of the EXTERNALNAME parameter must be used.
In the DBD generation input order, the FIELD statement of the field that is being redefined must precede the FIELD statement that specifies the REDEFINES parameter.
This field must be the same length as the field that is being redefined, as specified on the BYTES parameter in each FIELD statement.
You cannot redefine a field that has been defined as an ARRAY or that contains an ARRAY.
The MSDB database type does not support the REDEFINES parameter.
- RELSTART=
- Specifies the starting position of a field that is defined as an element of
an array or, in some circumstances, a structure. Valid values are from 1 to 32767.
The value specified on RELSTART is the starting byte offset of the field relative to the start of the array or structure. For example, the first field in an array would typically specify RELSTART 1, even if the array that contains the field starts at byte 50 of a segment.
For fields that specify an array field as a parent, RELSTART is required.
For fields that specify a structure as a parent, RELSTART is required if the structure field is defined with RELSTART or STARTAFTER.
In the following example, the field DYNARRAY is a dynamic array. The field STRUCT01 is a structure. The fields FLD03 and FLD04 both specify STRUCT01 as a parent. Because a dynamic array precedes STRUCT01 in the segment, the starting offsets of FLD03 and FLD04 can be specified only relative to the start of STRUCT01.FIELD EXTERNALNAME=ARRAYNUM,DATATYPE=DECIMAL(7,0),START=1,BYTES=4 FIELD EXTERNALNAME=DYNARRAY,DATATYPE=ARRAY,START=5,MAXBYTES=100 MINOCCURS=10,MAXOCCURS=50,DEPENDSON=ARRAYNUM FIELD EXTERNALNAME=FLD01,RELSTART=1,BYTES=2,PARENT=DYNARRAY FIELD EXTERNALNAME=FLD02,STARTAFTER=DYNARRAY,BYTES=10 FIELD EXTERNALNAME=STRUCT01,DATATYPE=STRUCT,STARTAFTER=FLD02,BYTES=10 FIELD EXTERNALNAME=FLD03,RELSTART=1,BYTES=5,PARENT=STRUCT01 FIELD EXTERNALNAME=FLD04,RELSTART=6,BYTES=5,PARENT=STRUCT01
START, STARTAFTER, and RELSTART are mutually exclusive.
- 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:
- SEQ
- A subparameter of NAME, SEQ identifies this field as a sequence field in the
segment type. FIELD statements containing the keyword SEQ must be the first FIELD statements
following a SEGM statement in a DBD generation input deck.
If the sequence field of a real logical child segment consists of any part of the concatenated key of the logical parent, you must specify the PHYSICAL parameter in the SEGM statement in order for the logical child to include the concatenated key of the logical parent with the logical child in storage.
Generally, a segment can have only one sequence field. However, in the case of virtually paired bidirectional logical relationships, multiple FIELD statements can be used to define a logical sequence field for the virtual logical child segment type, as described as follows.
A sequence field must be specified for a virtual logical child segment type if, when accessing a logical child segment from its logical parent, one requires real logical child segments to be retrieved in an order determined by data in a field or fields of the real logical child segments. This sequence field can include any part of the segment as it appears when viewed from the logical parent (that is, the concatenated key of the physical parent of the real logical child followed by any intersection data). Because it might be necessary to describe the sequence field of a logical child segment as accessed from its logical parent segment in noncontiguous pieces, multiple FIELD statements with the SEQ parameter present are permitted. Each statement must contain a unique fldname1 parameter.
You can define any sequence field as a qualification in an SSA, but all succeeding sequence fields are considered as a part of the named field. Therefore, the length of the field named in the SSA is the concatenated length of the specified field plus all succeeding sequence fields. This
scattered
sequence field is permitted only when specifying the sequence field for a virtual logical child segment. If the first sequence field is not included in ascattered
sequence field in an SSA, DL/I treats the argument as a data field specification rather than a sequence field specification. DL/I must examine all segment instances on a twin chain when a data field specification is evaluated. When a sequence field specification is evaluated the search continues along the twin chain until a sequence field value that is higher than the SSA value is reached. The search stops at that point.In an MSDB, the keyword SEQ must be specified if the DATASET statement specifies REL=NO (a non-terminal-related MSDB without terminal-related keys); otherwise this keyword is invalid.
In a DEDB, SEQ must be used in the root segment and can be specified in any direct dependent segment.
Restrictions:- SEQ cannot be specified for the sequential dependent segment
- SEQ cannot be specified for a field that is defined as a structure that contains a field that is defined as a dynamic array. Structure fields are defined by DATATYPE=STRUCT. Dynamic array fields are defined by DATATYPE=ARRAY and the DEPENDSON and MAXBYTES parameters, among others.
- START=
- Specifies the starting position of the field being defined in terms of bytes
relative to the beginning of the segment. The value of START must be a numeric term whose value does
not exceed 32767. The starting position for the first byte of a segment is one. For variable-length
segments, the first 2 bytes contain the length of the segment. Therefore the first actual user data
field starts in byte 3. Overlapping fields are permitted. When defining a logical child segment, the
first n number of bytes of the segment type is the concatenated key of the
logical or physical parent. A field starting in position one would define all or a portion of this
field. A field starting in position n+1 would start with intersection data.
START can be used for a system-related field, to describe a portion of the concatenated key as a field in an index source segment type. If used in this way, START specifies the starting position of the relevant portion of the concatenated key relative to the beginning of the concatenated key. The first byte of the concatenated key is considered to have a position of one. It must be a numeric term whose value does not exceed the length of the concatenated key plus one. Subtract the value specified in the BYTES parameter. The starting position parameter for the /SX system-related field is disregarded.
START, STARTAFTER, and RELSTART are mutually exclusive.
When XML, the START parameter is optional and START 0 can be specified. If the START parameter is omitted when XML, START 0 is the default.
- STARTAFTER=
- When the starting byte offset of a field cannot be calculated because the
field starts after a dynamic array, specifies the name of the field that directly precedes this
field in the segment. The name cannot be the name provided on the INTERNALNAME keyword.
STARTAFTER is required and valid only when the starting position of a field cannot be calculated because the field is preceded at a prior offset by a field defined as a dynamic array.
Dynamic arrays make it impossible to calculate the starting offsets of subsequent fields in a segment, because the byte lengths of dynamic arrays can vary from one instance of a segment to another. The columns of dynamic array fields can be identified by the inclusion of the DEPENDSON and MAXBYTES parameters.
The STARTAFTER parameter cannot be specified on fields that define an array field as a parent. Instead, specify the RELSTART parameter.
START, STARTAFTER, and RELSTART are mutually exclusive.
- systrelfldname
- Defines a system-related field which can be used only for secondary
indexing. There are two types of system-related fields:
- All of or a portion of the concatenated key of an index source
segment type defined by the preceding SEGM statement. The name for
this type of system-related field can be up to eight characters long,
and must begin with the three characters /CK. The fourth through eighth
characters permit unique identification of the field being defined,
whose name must be unique among all other fields defined in the segment
type. This type of system-related field is defined to enable the use
of the concatenated key of an index source segment, or portions of
the concatenated key in the subsequence or duplicate data fields of
index pointer segments. Assume the concatenated key shown in the following table:
Table 1. Sample concatenated key for an index source segment type Root key (10 bytes) Dependent key (3 bytes) Dependent key (3 bytes) Dependent key (3 bytes) If three system-related fields were to consist of bytes 2 through 8 of the root key, byte 1 of the second key and bytes 2 and 3 of the fourth key, the FIELD statements specifying these fields could be as follows:
NAME=/CK1 BYTES=7 START=2 NAME=/CK2 BYTES=1 START=11 NAME=/CK3 BYTES=2 START=18
You can then specify the three system-related fields defined for use in the subsequence or duplicate data fields of index pointer segments by including the names of the system-related fields in lists for the subsequence or duplicate data fields on an XDFLD statement.
- The second type of system-related field is defined within an index source segment type to ensure uniqueness of sequence field keys in a secondary index. The name specified for this type of system-related field must begin with the characters /SX, and the name specified can be up to eight characters in length. When this type of system-related field is defined in an index source segment type, IMS generates a unique 4-byte value, and places it in the subsequence field of the index pointer segment generated from an index source segment.
On an XDFLD statement, a /CK field can be included in the list of fields specified for either the subsequence or DDATA fields or both of an index pointer segment. A /SX field can be included only in the list of fields specified for the subsequence field of index pointer segments.
For Fast Path secondary indexing, only a /CK field is valid and the /SX field is not valid.
- All of or a portion of the concatenated key of an index source
segment type defined by the preceding SEGM statement. The name for
this type of system-related field can be up to eight characters long,
and must begin with the three characters /CK. The fourth through eighth
characters permit unique identification of the field being defined,
whose name must be unique among all other fields defined in the segment
type. This type of system-related field is defined to enable the use
of the concatenated key of an index source segment, or portions of
the concatenated key in the subsequence or duplicate data fields of
index pointer segments.
- TYPE=
- Determines the type of character that IMS uses to mask or
pad the data in this field.
If the DATATYPE parameter is not explicitly set, the TYPE parameter also determines the default value of DATATYPE; however, TYPE does not otherwise affect how data is stored, converted, or presented to application programs.
For example, when application programs that use field-level sensitivity are not sensitive to this field, IMS can mask the data in a field with either X'00', X'40, or, for MSDBs, halfword or fullword binary data.
When an application program is sensitive to one or more fields in a segment, IMS masks fields if one of the following conditions is met:
- On an insert call, the segment contains fields that the application program is not sensitive to.
- On a call that replaces a variable-length segment with a segment that is longer than the existing segment, the increased portion of the segment contains fields that the application program is not sensitive to.
- On a call that retrieves a variable-length segment that does not contain the field.
If an alphanumeric field (TYPE=C) is partially present in the physical segment, the data is moved to the field in the user's I/O area and padded on the right with blanks. Partially present hexadecimal or packed decimal fields are replaced with the fill value when presented to the user.
All DL/I calls perform field comparisons on a byte-by-byte binary basis. No check is made by IMS to ensure that the data contained within a field is of the type specified by this parameter, except when the defined field is used with field sensitivity or is in an MSDB.
You can specify the following values on the TYPE parameter:- X
- Specifies hexadecimal data. When X is specified, if IMS needs to fill unused bytes in the field, IMS right justifies the value and fills the unused bytes to the left of the value with X'00'. For example, a 3-byte value X'543210' in a 5-byte field is written out as X'0000543210'.
- P
- Packed decimal data. When P is specified, if IMS needs to fill unused bytes in the field, IMS right justifies the value and fills the unused bytes to the left of the value with X'00'. For example, a 3-byte value X'54321C' in a 5-byte field is written out as X'000054321C'.
- C
- Specifies alphanumeric data or a combination of types of data. When C is specified, if IMS needs to fill unused bytes in the field, IMS left justifies the value and fills the unused bytes to the right of the value with X'40'. For example, a 3-byte value X'F5F4F3' in a 5-byte field is written out as X'F5F4F34040'.
- F
- Specifies binary fullword data.
An arithmetic field cannot be overlapped by another field in a segment definition; that is, another field cannot be defined to start or end between the starting and ending byte offsets of a field that specifies TYPE=F.
- H
- Specifies binary halfword data.
An arithmetic field cannot be overlapped by another field in a segment definition; that is, another field cannot be defined to start or end between the starting and ending byte offsets of a field that specifies TYPE=H.
For MSDB databases, types X, C, P, H, and F are valid, with the following rules applying:
- Only a C or X field can contain another field.
- A single field can have multiple definitions as long as no more than one definition is arithmetic (types P, H, and F).
- If a field contains any part of an arithmetic field, it must contain the entire field.
- The sequence field must be TYPE=C or X.
- The sequence field cannot be part of any other field.
- SSA and FSA comparisons of arithmetic fields use arithmetic rather than logical compare operations.
- Initial loading and call processing routines test for valid digits and X and P type fields.
- The following rules apply to the MSDB field length:
- TYPE=X: BYTES=1 to 256
- TYPE=P: BYTES=1 to 16
- TYPE=C: BYTES=1 to 256
- TYPE=F: BYTES=4
- TYPE=H: BYTES=2
- Field types F and H must have explicit length specifications.
- Fields should be aligned on appropriate boundaries for performance optimization if they are involved in compare or arithmetic operations and are a fullword or halfword long. The beginning of the segment is aligned on a fullword boundary.
- If the systrelfldname in the field statement is defined as either /SX or /CK, the TYPE= parameter is ignored and no type is set.
- U or M
- Subparameters of NAME, U and M qualify the type of sequence (SEQ)
field that is being specified.
The parameter U indicates that only unique values are allowed in the sequence field of occurrences of the segment type. For a dependent segment type, the sequence field of each occurrence under a given physical parent segment must contain a unique value.
The parameter M indicates that duplicate values are allowed in the sequence field of occurrences of the segment type. For a root segment type, the sequence field of each occurrence must contain a unique value, except in HDAM. The root segment type in an HDAM database does not need a key field; if a key field is defined, it does not have to be unique.
When no sequence field or a nonunique sequence field is defined for a segment, occurrences of the segment are inserted according to the rule of FIRST, LAST, or HERE as specified on the SEGM or LCHILD statement for that segment.
Recommendation: Use unique sequence fields for all segments that participate in a logical relationship. This includes physical and logical parents as well as physical and logical child segments. Multiple sequence fields for a virtual logical child segment type must be uniformly defined as either unique or nonunique.In a non-terminal-related MSDB without terminal-related keys, unique (U) values must be specified for the root sequence field. In a DEDB, unique (U) values must be specified for the sequence field of the root segment. A dependent segment in a DEDB does not require a key. However, if a key is defined, it must be unique.