The SEGNAME attribute identifies the IMS segments you can access. The SEGNAME value is the name of the IMS segment from the SENSEG record in the PCB.

FOCUS retrieves segments in top-to-bottom, left-to-right sequence as described by the Master File. Therefore, the order of segments in the Master File should be the same as their order in the PCB in order to maintain the correct hierarchical sequence. However, FOCUS retrieves unique segments (only one instance per parent—no twins) prior to any non-unique segments that have the same parent.

The SEGTYPE attribute does the following:

• Identifies the characteristics of the key field for the segment. A segment can have a unique key, a non-unique key, or no key.

  If a segment has a unique key, at least one FIELD record in the DBD must specify NAME=(fieldname,SEQ,U) or NAME=(fieldname,SEQ). Similarly, if the segment has a non-unique key, at least one FIELD record in the DBD must specify NAME=(fieldname,SEQ,M). If no FIELD record in the DBD specifies a SEQ attribute, the segment has no key. The key referred to by the SEGTYPE attribute may actually be a secondary index (see Using a Secondary Index). The characteristics of the key determine the types of SSAs and the number of DL/I calls the adapter must issue to satisfy a retrieval request. To handle keys made up of multiple fields, describe the multiple fields as a group in the Master File (see Group Fields). If you do not specify a key field (.KEY) for a keyed SEGTYPE (for example, S1), a FOC4277 message will result.

• Identifies unique segments. A segment is unique if it has no twins. A segment can be parent to at most one instance of a unique segment type. The SEGM record in the DBD for a unique segment specifies PTR=NOTWIN.
• Identifies whether the data from the segment can be retrieved (data sensitive) or if only the key is accessible (key sensitive). For a key sensitive segment, the SENSEG record in the PCB includes the parameter PROCOPT=K. Key sensitive segments are used for access to lower level segments.

The following table lists the valid SEGTYPE values:

SEGTYPE	Definition	PROCOPT=KIn PCB?	NAME=From DBD
U	Data sensitive, unique segment	No	Not Applicable
S0	Data sensitive, no key	No	(name)
S or S1	Data sensitive, non-unique key	No	(name,SEQ,M)
S2	Data sensitive, unique key	No	(name,SEQ,U) or (name,SEQ)
SH or SH1	Key sensitive, non-unique key	Yes	(name,SEQ,M)
SH2	Key sensitive, unique key	No	Not Applicable

The PARENT attribute identifies the parent of the segment in the hierarchy. It appears in the PARENT parameter of the SENSEG record in the PCB. The only exception is in the root segment, where the PCB either omits the PARENT parameter or specifies PARENT=0. In the Master File, you can specify the PARENT attribute of the root segment as PARENT=, or you can omit it.

IMS field names are acceptable values if they meet the following naming conventions:

• Names can consist of letters, digits, and underscore characters. Special characters and embedded blanks are not advised.
• The name must contain at least one letter.

Since field names appear as default column titles for reports, select names that are representative of the data.

You can use field names, aliases, or a unique truncation of either in requests. For example, consider the following Master File:

FILENAME=MFD1
  SEGNAME=SEG1
   FIELDNAME=S1, ALIAS=K1.KEY, USAGE=A4, ACTUAL=A4,$

The following commands are all equivalent in a FOCUS request:

PRINT S1
PRINT S
PRINT K1.KEY
PRINT K1
PRINT K

Duplicate field names (the same field names and aliases) within a segment are not permitted. Report requests can qualify duplicate field names from different segments with the name of the Master File and/or segment. That is, using the Master File from the previous example, the following are equivalent:

PRINT SEG1.S1
PRINT MFD1.S1
PRINT MFD1.SEG1.S1

You need this type of qualification if two segments in the Master File or in a join have a field defined with the same field name and alias. For more information about field qualifiers, see your FOCUS documentation.

Note: Field names in OCCURS segments may not be qualified.

The ALIAS value in the Master File distinguishes between fields that are defined in the IMS DBD and fields that are not defined to IMS. The adapter uses this information in constructing DL/I calls to IMS.

If a field used in a screening test (IF or WHERE) is a sequence or search field, the adapter may be able to create an SSA that instructs IMS to apply the screening test and return the appropriate records to FOCUS. If the field is not defined in the DBD, the adapter must retrieve all records sequentially from IMS so that FOCUS can screen them.

In certain cases, the adapter can instruct IMS to screen values based on a secondary index. Using a Secondary Index describes the technique for taking advantage of a secondary index.

The ALIAS value for a field defined in the DBD is composed of the following:

• The name of the field as specified in the IMS DBD.
• A separation character, the period (.).
• A suffix value that describes whether the field is a sequence field (suffix KEY), a search field (suffix IMS), or the key of the root segment of an HDAM database (suffix HKY).

You can assign fields not defined in the DBD any name that complies with FOCUS field naming conventions. Do not include periods or suffix values for such alias names.

In requests, you can reference a field by its field name, its alias, or by a unique truncation of either. Note that the IMS field name is a unique truncation of the alias value. For example, if the IMS key field is named IMSNAME, then the alias for that field in the Master File is IMSNAME.KEY. A FOCUS request can reference the field by the name IMSNAME (without .KEY) because this name is a unique truncation of the alias.

The USAGE attribute indicates the display format of the field. An acceptable value must include the field type and length and may contain diaplay options. USAGE formats (A, D, F, I, P) are available. For additional information about USAGE formats for non-FOCUS data sources, see the Describing Data manual.

The ACTUAL attribute indicates the FOCUS representation of IMS field formats.

For fields defined in the DBD (sequence and search fields), use the format specified in the DBD.

Use the following chart as a guide for describing ACTUAL formats of those fields not defined in the DBD:

COBOL FORMAT	COBOL PICTURE	BYTES OF STORAGE	ACTUAL FORMAT	USAGE FORMAT
DISPLAY	X(4)	4	A4	A4
DISPLAY	S99	2	Z2	P3
DISPLAY	9(5)V9	6	Z6.1	P8.1
DISPLAY	99	2	A2	A2
COMP	S9	4	I2	I1
COMP	S9(4)	4	I2	I4
COMP	S9(5)	4	I4	I5
COMP	S9(9)	4	I4	I9
COMP-1	-	4	F4	F6
COMP-2	-	8	D8	D15
COMP-3	9	1	P1	P1
COMP-3	S9V99	2	P2	P5.2
COMP-3	9(4)V9(3)	4	P4	P8.3
FIXED BINARY(7) (COMP-4)	B or XL1	4	I4	I7

CHECK FILE filename HOLD
TABLE FILE HOLD
WRITE MAX.LWORD
END

FILE=DI21PART    ,SUFFIX=IMS,$
SEGNAME=PARTROOT ,PARENT=,SEGTYPE=S2,$
  FIELD=PARTKEY  ,ALIAS=PARTKEY.HKY  ,USAGE=A17  ,ACTUAL=A17  ,$
  FIELD=SKIP1    ,ALIAS=SKIP1        ,USAGE=A33  ,ACTUAL=A33  ,$
SEGNAME=STANINFO ,PARENT=PARTROOT,SEGTYPE=S2,$
  FIELD=STANKEY  ,ALIAS=STANKEY.KEY  ,USAGE=A2   ,ACTUAL=A2   ,$
  FIELD=SKIP2    ,ALIAS=SKIP2        ,USAGE=A83  ,ACTUAL=A83  ,$
SEGNAME=STOKSTAT ,PARENT=PARTROOT,SEGTYPE=S2,$
  FIELD=STOCKEY  ,ALIAS=STOCKEY.KEY  ,USAGE=A16  ,ACTUAL=A16  ,$
  FIELD=SKIP3    ,ALIAS=,SKIP3       ,USAGE=A124 ,ACTUAL=A124 ,$
SEGNAME=CYCCOUNT ,PARENT=STOKSTAT,SEGTYPE=S2,$
  FIELD=CYCCKEY  ,ALIAS=CYCCKEY.KEY  ,USAGE=A2   ,ACTUAL=A2   ,$
  FIELD=SKIP4    ,ALIAS=SKIP4        ,USAGE=A23  ,ACTUAL=A23  ,$
SEGNAME=BACKORDR ,PARENT=STOKSTAT,SEGTYPE=S2,$
  FIELD=BACKEY   ,ALIAS=BACKEY.KEY   ,USAGE=A10  ,ACTUAL=A10  ,$
  FIELD=SKIP5    ,ALIAS=SKIP5        ,USAGE=A65  ,ACTUAL=A65  ,$

Each element of the group can have a different format. However, retrieval is more efficient if each USAGE format is of the same type (for example, alphanumeric or packed) as its ACTUAL format. The lengths may differ.

GROUP=gname, ALIAS=alias, ELEMENTS=n,$
 FIELD=fld1,,usage1,actual1,$
 .
 .
 .
 FIELD=fldn,,usagen,actualn,$

where:

gname

Is the group name. It can be any name that complies with field naming conventions.

alias

Is the IMS field name from the DBD if the group field is a sequence or search field. Possible values are:

imsfield.KEY is the alias for a field that is an IMS key field. Form the alias by appending the suffix KEY to the name of the IMS field.

imsfield.IMS is the alias for a field that is an IMS search field. Form the alias by appending the suffix IMS to the name of the IMS field.

imsfield.HKY is the alias for a field that is the key of the root segment in an HDAM data source. Form the alias by appending the suffix HKY to the name of the IMS field.

Note: The keyword ALIAS is required.

n

Is the number fields in the group.

fld1,...,fldn

Are field names for the individual elements that compose the group.

usage1,...,usagen

Are USAGE formats for the individual elements. For efficient retrieval, each individual USAGE format must be of the same data type as its corresponding ACTUAL format, but their lengths can differ.

actual1,...,actualn

Are ACTUAL formats for the individual elements. For efficient retrieval, each individual USAGE format must be of the same data type as its corresponding ACTUAL format, but their lengths can differ.

The following is an example of a group key definition in the Master File:

GROUP=G1, ALIAS=FILEKEY.KEY, ELEMENTS=3 ,$
  FIELD=F1,,A4,A4,$
  FIELD=F2,,P6,P3,$
  FIELD=F3,,I9,I4,$

The GROUP in the example describes an IMS key named FILEKEY that is 11 bytes long and consists of a 4-byte alphanumeric field, a 3-byte packed number, and a 4-byte integer.

The ACTUAL length of the GROUP is 11 (4+3+4).

The USAGE length of the GROUP is 16 (4+8+4) because it counts the packed field as 8.

Since the group components are of mixed data types, you must use individual fields in the WHERE expression of a query.

WHERE F1 = ABCD
WHERE F1 BETWEEN A AND B
WHERE F2 = 245

If you reference either the group or the first elementary field from the group in your request, the adapter generates qualified SSAs in its DL/I calls for retrieval. Thus, IMS does the screening and returns the segments that pass the screening test back to the adapter.

However, if you reference an elementary field that is not the first field in the group, the adapter constructs DL/I calls to retrieve the segments sequentially, and then FOCUS applies the screening test to the returned data.

Note: The adapter does not support a group field within a group field. You may be able to use DEFINE fields in the Master File instead.

Each element of the group can have a different format. However, retrieval is more efficient if the USAGE format for each element is the same type as its ACTUAL format (for example, alphanumeric or packed); the lengths may differ.

The syntax for a GROUP record and its subordinate FIELD records is

GROUP=gname, ALIAS=alias, USAGE=An, ACTUAL=Am,$

FIELD=fld1,al1,use1,act1,$
 .
 .
 .
FIELD=fldn,aln,usen,actn,$

where:

gname

Is the group name. It can be any name that complies with FOCUS field naming conventions.

alias

Is an alias for an IMS field. Note that the keyword ALIAS is required. Possible values follow:

imsname.KEY is the alias for an IMS key field (except for the root key of an HDAM database). Append the suffix KEY to the name of the IMS field.

imsname.IMS is the alias for an IMS search field. Append the suffix IMS to the name of the IMS field.

imsname.HKY is the alias for the key of the root segment in an HDAM database. Append the suffix HKY to the name of the IMS field.

anyname is the alias for a field not listed in the DBD. The alias is any name that complies with FOCUS field naming conventions. The alias value can also be blank.

An

Is the USAGE format for the GROUP. It must be alphanumeric and its length must count all F fields as length 4, all D fields as length 8, and all integer fields as length 4, regardless of the length specified in the ACTUAL format. For alphanumeric fields, USAGE length must equal ACTUAL length. For P (packed) fields, the length depends on the USAGE of the packed field:

USAGE of Packed Field	Length for GROUP USAGE
Pn or Pn.d, n≤15, P16	8
P16	8
P16.d	16
Pn or Pn.d, 16<n≤31	16

Am

Is the ACTUAL format for the GROUP. Its length is the sum of the lengths of the IMS fields.

fld1,...,fldn

Are FOCUS field names for the individual elements in the group.

al1,...,aln

Are alias names for the individual elements. They can be any names that comply with FOCUS field naming conventions.

use1,...,usen

Are USAGE formats for the individual elements. For efficient retrieval, each individual USAGE format must be of the same data type as its corresponding ACTUAL format, but their lengths can differ.

act1,...,actn

Are ACTUAL formats for the individual elements. For efficient retrieval, each individual USAGE format must be of the same data type as its corresponding ACTUAL format, but their lengths can differ.

The following is an example of a group key definition in the Master File:

GROUP=G1, ALIAS=FILEKEY.KEY, USAGE=A16, ACTUAL=A11 ,$
  FIELD=F1,F1,A4,A4,$
  FIELD=F2,F2,P6,P3,$
  FIELD=F3,F3,I9,I4,$

Note:

• If the key to an IMS segment is composed of multiple fields, you must define the key as a GROUP. Only one field in a segment can have the .KEY suffix. For a group key, this field must be the GROUP field.
• The GROUP in the example describes an IMS key named FILEKEY that is 11 bytes long and consists of a 4-byte alphanumeric field, a 3-byte packed number, and a 4-byte integer.
• The ACTUAL length of the GROUP is 11 (4+3+4).
• The USAGE length of the GROUP is 16 (4+8+4), because it counts the packed field as 8.

You can use the group field or any individual field in a FOCUS query. For example:

WHERE G1 EQ 'ABCD'/245/-20 or
IF G1 GT ABCD/245/-20
IF G1 FROM ABCD/245/-20 TO ABCD/300/50
IF G1 IS ABCD/245F/-20  (field F2 has a non-standard sign, F) 
IF G1 IS A$*
IF F1 IS ABCD
IF F1 FROM A TO B
IF F2 IS 245

You must use a slash (/) to separate the individual fields when you reference the group name.

If you reference either the group or the first elementary field from the group in your request, the adapter generates qualified SSAs in its DL/I calls for retrieval. Thus, IMS does the screening and returns the segments that pass the screening test back to FOCUS.

However, if you reference an elementary field that is not the first field in the group, FOCUS constructs DL/I calls to retrieve the segments sequentially, and then FOCUS applies the screening test to the returned data.

Reporting Efficiencies contains a detailed explanation of screening conditions and SSA generation.

Note: The adapter does not support a group field within a group field. See the Describing Data manual for information on DEFINE fields in the Master File.

If multiple values identify the same record type (for example, S or T for a shipment record), use the ACCEPT attribute to enumerate the list or range of acceptable values. In this case, define the ALIAS value as blank.

The syntax is

FIELDNAME=RECTYPE, ALIAS= , USAGE=usage, ACTUAL=actual,

ACCEPT = val1 [OR] val2 [ [OR] ...valn] ,$

   ACCEPT = val1 TO val2,$

where:

usage

Is the FOCUS display format for the field.

actual

Is the FOCUS definition of the IMS field format and length (n).

val1,val2,valn

Defines a list or range of values that identifies the record type. A list can be continued on more than one line. Enclose values that contain embedded blanks or special characters in single quotation marks.

The following examples illustrate the ACCEPT attribute:

ACCEPT = AAA TO RRR
ACCEPT = 136 TO 1029
ACCEPT = RED OR WHITE OR BLUE
ACCEPT = RED WHITE BLUE
ACCEPT = 6 OR 11 OR 922 OR 1000
ACCEPT = RED WHITE 'GREEN GREY'

Refer to the Logical Parent Segment feature in IMS Overview and Mapping Concepts, for more information on RECTYPEs.

Sometimes the sequence of fields within an OCCURS segment is significant. For example, each instance of the repeating field may represent one quarter of the year, but the segment may not have a field that identifies the quarter to which it applies.

ORDER is an optional counter used to identify the sequence number within a group of repeating fields. You should include it when the order of data is important. The ORDER field does not represent an existing field in the database. It is used only for internal processing.

The ORDER field must be the last field described in the OCCURS segment. The syntax is

FIELDNAME=fieldname, ALIAS=ORDER, USAGE=In, ACTUAL=I4 ,$

where:

fieldname

Is a valid field name.

In

Is an integer format.

Note:

• The ALIAS value must be ORDER.
• The ACTUAL format must be I4.
• The ORDER field must be the last field defined in the OCCURS segment.

In report requests, you can use the value of the ORDER field. You can also use a DEFINE field in your session or in the Master File to translate it to more meaningful values. For example:

DEFINE ...
QTR/A3 = DECODE ORDER(1 '1ST' 2 '2ND' 3 '3RD' 4 '4TH')
 .
 .
 .

A subsequent request could include:

PRINT TOT.TAXES IF QTR IS 1ST

or

PRINT QTR BALANCE INTEREST

In the following example, the IMS segment, IMS1, includes a group (consisting of the two fields MONTH and AMOUNT) that repeats 12 times. The COBOL FD for the segment follows:

01  IMS1
    05  ACCOUNT  PIC X(9)
    05  TYPE     PIC XXX
    05  PAYMENT OCCURS 12 TIMES
        10 MONTH PIC 99
        10 AMT   PIC S9(3)V(99)COMP-3

The Master File uses two segments to describe this IMS variable length segment:

1. SEGNAME=IMS1,PARENT=,SEGTYPE=S2 
    FIELD=ACT_NUM ,ALIAS=ACCOUNT.KEY ,A9  ,A9,$
    FIELD=TYPE    ,ALIAS=TYPE        ,A3  ,A3,$ 
2. SEGNAME=OCC1,PARENT=IMS1,OCCURS=12
    FIELD=MM      ,ALIAS=MONTH       ,A2  ,A2,$
    FIELD=AMT     ,ALIAS=AMT         ,P6.3,P3,$

1. Segment IMS1 is the base segment. It has the same name as the IMS segment and describes the two non-repeating fields, ACT_NUM and TYPE.
2. The OCCURS segment, OCC1, identifies IMS1 as its parent. It has no SEGTYPE, and it includes the OCCURS attribute. The two repeating fields are described in this segment.

In the following example, the repeating group is not at the end of the segment, but is embedded in the segment before the LNAME field. The COBOL FD for this situation is:

01  IMS1
    05  ACCOUNT PIC X(9)
    05  TYPE    PIC XXX
    05  PAYMENT OCCURS 12 TIMES
        10 MONTH PIC 99
        10 AMT   PIC S9(3)V(99)COMP-3
    05  LNAME    PIC X(20)

The Master File must include LNAME in the base segment. It must also describe where the repeating fields fit into the base segment by defining a place-holder field before LNAME, equal to the length of the 12 occurrences and by pointing to the place-holder field with the POSITION attribute:

   SEGNAME=IMS1,PARENT=,SEGTYPE=S2 
    FIELD=ACT_NUM   ,ALIAS=ACCOUNT.KEY  ,A9 ,A9 ,$
    FIELD=TYPE      ,ALIAS=TYPE         ,A3 ,A3 ,$ 
1.  FIELD=HOLDIT    ,ALIAS=             ,A60,A60,$
    FIELD=LNAME     ,ALIAS=LAST_NAME    ,A20,A20,$ 
2. SEGNAME=OCC1,PARENT=IMS1,OCCURS=12, POSITION=HOLDIT
    FIELD=MM        ,ALIAS=MONTH        ,A2  ,A2,$
    FIELD=AMT       ,ALIAS=AMT          ,P6.3,P3,$

1. The HOLDIT field is the place holder for the repeating group in the base segment (IMS1). Since the repeating group consists of 12 occurrences, each of which is 5 bytes long (A2 and P3, described in segment OCC1), the HOLDIT field is defined as A60.
2. The attribute POSITION=HOLDIT in the OCCURS segment declaration describes where the repeating group is located in the actual (base) segment.

In this example, the value of the TIMES field is the number of occurrences. The following COBOL FD describes this situation:

01  IMS1
    05  ACCOUNT PIC X(9)
    05  TYPE    PIC XXX
    05  TIMES   PIC S999  COMP-3 
    05  PAYMENT OCCURS DEPENDING ON TIMES
        10 MONTH PIC 99
        10 AMT   PIC S9(3)V(99)COMP-3

The Master File attribute, OCCURS=TIMES, identifies the TIMES field as containing the number of repetitions. The Master File also defines the optional ORDER field as the last field in the OCCURS segment:

   SEGNAME=IMS1,SEGTYPE=S2 
    FIELD=ACT_NUM ,ALIAS=ACCOUNT.KEY ,A9   ,A9,$
    FIELD=TYPE    ,ALIAS=TYPE        ,A3   ,A3,$
    FIELD=TIMES   ,ALIAS=TIMES       ,P4   ,P2,$ 

1. SEGNAME=OCC1,PARENT=IMS1, OCCURS=TIMES
    FIELD=MM     ,ALIAS=MONTH        ,A2   ,A2,$
    FIELD=AMT    ,ALIAS=AMT          ,P6.3 ,P3,$ 
2.  FIELD=WHICH  ,ALIAS=ORDER        ,I4   ,I4,$ 

1. The attribute OCCURS=TIMES identifies the value in the TIMES field as the number of instances of the repeating group.
2. The field named WHICH is the optional ORDER field (ALIAS=ORDER). It is an internal counter defined as the last field in the OCCURS segment. It associates a sequence number with each occurrence of the repeating group. With the ORDER field defined, a request can include a test that selects a specific occurrence, for example:

   WHERE WHICH EQ 3

This example describes a segment in which the number of occurrences must be calculated from the length of the segment. The first field in the segment must be a 2-byte counter field that contains the true length of the segment and is defined to IMS in the DBD. The COBOL FD for this variable length segment follows:

01  IMS1
    05  COUNTER PIC 99 COMP
    05  ACCOUNT PIC X(9)
    05  TYPE    PIC XXX
    05  PAYMSCHED OCCURS 1 TO 12 TIMES
        10 MONTH PIC 99
        10 AMT   PIC S9(3)V(99)COMP-3

The Master File must specify OCCURS=VARIABLE and must describe the counter field with the attribute ALIAS=IMSname.CNT:

   SEGNAME=IMS1,SEGTYPE=S2  
1.  FIELD=COUNTFLD  ,ALIAS=COUNTER.CNT ,I2   ,I2,$
    FIELD=ACT_NUM   ,ALIAS=ACCOUNT.KEY ,A9   ,A9,$
    FIELD=TYPE      ,ALIAS=TYPE        ,A3   ,A3,$ 
2. SEGNAME=OCC1,PARENT=IMS1, OCCURS=VARIABLE
    FIELD=MM        ,ALIAS=MONTH       ,A2   ,A2,$
    FIELD=AMT       ,ALIAS=AMT         ,P6.3 ,P3,$

1. The two-byte counter field must be the first field in the base segment. Its alias is formed by appending the suffix CNT to the field name defined in the IMS DBD, ALIAS=COUNTER.CNT.
2. In the OCCURS segment definition, the attribute OCCURS=VARIABLE indicates that the first field defined in the Master File contains the segment length and that the number of repetitions must be calculated from this length.