Defining a dynamic array to IMS

A dynamic array is an array in which the number of repeating array elements can vary from one instance of a segment type to another.

A dynamic array is defined by coding FIELD statements in the input control statements of the DBD Generation utility. The following steps assume that the corresponding DBD, DATASET, SEGM, and other utility control statements have been coded correctly:

Procedure

  1. Define the control field that will contain the number of array elements for the array in an instance of the segment.
  2. Define the array by coding a FIELD statement:
    1. Specify the external name of the array on the EXTERNALNAME parameter. Arrays do not support the NAME parameter.
    2. Specify DATATYPE=ARRAY
    3. On the MINOCCURS parameter, specify the minimum possible number of elements that the array can have in a segment instance.
      The value specified on the MINOCCURS parameter must be less than the value specified on the MAXOCCURS parameter.
    4. On the MAXOCCURS parameter, specify the maximum possible number of elements that the array can have in a segment instance.
      The value specified on the MAXOCCURS parameter must be greater than the value specified on the MINOCCURS parameter.
    5. Specify the maximum possible byte size of the array on the MAXBYTES parameter.
      The byte size specified must be equal to or greater than the sum total of the bytes sizes of all fields that make up the array with the maximum number of array elements. The MAXBYTES parameter is mutually exclusive with the BYTES parameter that is used to define the size of a static array.
    6. Specify the name of the control field on the DEPENDSON parameter.
  3. Define the repeating array element by coding the FIELD statements for each field that is contained in the element.
    In the FIELD statement for each field that is a part of the array element:
    1. Specify the external name of the field on the EXTERNALNAME parameter. Array elements do not support the NAME parameter.
    2. Specify the starting byte offset of the field in the array element on the RELSTART parameter.
    3. Specify the external name of the array on the PARENT parameter.
    4. Specify the byte size of the field on the BYTES parameter.
      If the field contains a dynamic array, use the MAXBYTES parameter instead.

The following example shows the FIELD statement definitions for a dynamic array.

In the example, the first FIELD statement defines the control field that will specify the number of array elements in an instance of the array.

The second FIELD statement defines the array. The array is named BOOKS and can contain 1 to 5 array elements, as specified on the MINOCCURS and MAXOCCURS parameters. The field NUMOF_BKS determines the number of array elements in an instance of the array.

The repeating array element is defined by the last three FIELD statements. Because the array element is made up of three fields that together total 40 bytes and the element can repeat up to 5 times, the array must be defined with a MAXBYTES value of at least 200 bytes.

The array starts at byte 5 in the segment and the first field in the first array element starts at byte 1 of the array. The subsequent array elements start at bytes 41, 81, and so on, of the array.

   FIELD EXTERNALNAME=NUMOF_BKS,DATATYPE=INT,START=1,BYTES=4
   FIELD EXTERNALNAME=BOOKS,DATATYPE=ARRAY,START=5,MAXBYTES=200        X
               MINOCCURS=1,MAXOCCURS=5,DEPENDSON=NUMOF_BKS
     FIELD EXTERNALNAME=ISBN,RELSTART=1,BYTES=10,PARENT=BOOKS
     FIELD EXTERNALNAME=BOOK_TITLE,RELSTART=11,BYTES=22,PARENT=BOOKS
     FIELD EXTERNALNAME=RETURN_DATE,RELSTART=33,BYTES=8,PARENT=BOOKS

The preceding array definition is based on the following excerpt of an example COBOL copy book:

******* COPYBOOK for STUDENT/COURSES (DYNAMIC)01 STUDENT.
	      20   NUMOF-BKS				  PIC 9(4) COMP.
	      20   BOOKS OCCURS 1 TO 5 TIMES DEPENDING ON NUMOF-BKS.
			    30   ISBN			      PIC X(10).
			    30   BOOK-TITLE		  PIC X(22).
			    30   RETURN-DATE		PIC 9(8).