ILE COBOL Language Reference

+-------------------------------IBM Extension--------------------------------+

COPY Statement - Format 2 - DDS Translate

COPY Statement - Format 2 - DDS Translate
 
>>-COPY--+-DD-format-name---+--+-------+--+--------------+------>
         +-DD-ALL-FORMATS---+  +- -I---+  +- -INDICATOR--+
         +-DDR-format-name--+  +- -O---+  +- -INDICATORS-+
         +-DDR-ALL-FORMATS--+  '- -I-O-'  '- -INDIC------'
         +-DDS-format-name--+
         +-DDS-ALL-FORMATS--+
         +-DDSR-format-name-+
         '-DDSR-ALL-FORMATS-'
 
>--+-OF-+--+---------------------+--file-name--+------+--------->
   '-IN-'  |                (1)  |             '-WITH-'
           '-library-name- ------'
 
   .-------------------------------.
   V                               |
>----+---------------------------+-+--+----------+-------------->
     +-+-I-FIELDS---+------------+    '-SUPPRESS-'
     | +-O-FIELDS---+            |
     | '-I-O-FIELDS-'            |
     +-+-INDICATOR--+------------+
     | +-INDICATORS-+            |
     | '-INDIC------'            |
     +-NULL-MAP------------------+
     +-NULL-MAP-ALPHANUM---------+
     +-NULL-KEY-MAP--------------+
     +-PREFIX--BY--literal-------+
     +-ALIAS---------------------+
     +-+-----------------------+-+
     | '-| SUBSTITUTE Phrase |-' |
     '-VLR-----------------------'
 
>--+-----------------------+--.--------------------------------><
   '-REPLACING--| phrase |-'
 
SUBSTITUTE Phrase:
 
|--SUBSTITUTE--+----------------------------+-------------------|
               '-ALL--+-------------------+-'
                      '-EXCEPT--literal-2-'
 
 

Notes:

  1. Required hyphen between library-name-file-name to qualify.

Related Information

Format 2 Considerations

The Format 2 COPY statement (DD, DDR, DDS, or DDSR option) can be used to create COBOL Data Division statements to describe a file that exists on the system. These descriptions are based on the version of the file in existence at compilation time. They do not make use of the DDS source statements for the file.

If a REPLACE statement is in effect, the COPY statement must be the first item on a line of code. This line must also include the text word that specifies the required options, up to at least the initial hyphen.

DDS supports DBCS with formats J (for fields which can contain only DBCS data), E (for fields which can contain either DBCS or alphanumeric data), or O (for fields can contain both DBCS and alphanumeric data). DDS also supports graphic data types with format G. The *PICGGRAPHIC option is used to create COBOL DBCS data items corresponding to format G DDS items. The *PICNGRAPHIC option is used to create COBOL NATIONAL data items corresponding to format G DDS items with UCS-2 ccsid 13488. All other circumstances produce alphanumeric data items capable of holding the correct number of bytes of data.

The Format 2 COPY statement can be used only in the Data Division, and it is the user's responsibility to precede the statement with a group level item that has a level-number less than 05.

The DD and ALIAS Options

The DD option or the ALIAS option is used to reference alias (alternate) names. The specification of an alias name in DDS allows a data name of up to 30 characters to be included in the COBOL program.

When the DD option or the ALIAS option is used, any alias names present replace the corresponding DDS field names. All underscores in the alias names are translated into hyphens before any replacing occurs.

The DDR Option

The DDR option or the SUBSTITUTE option does everything that the DD option does. It also replaces the invalid COBOL characters @, #, $, and _ in a field name (or alias name, if applicable) with the corresponding valid COBOL characters A, N, D, and -. As well, it removes underscores from the end of a field name.

The DDS Option

The DDS option copies in the internal DDS field names for the specified DDS format.

The DDSR Option

The DDSR option does everything that the DDS option does. It also copies the internal DDS field names in the specified DDS format, replacing the invalid COBOL characters @, #, $, and _ with the valid COBOL characters A, N, D, and - accordingly. This option also removes any underscores from the ends of the field names.

The Format-Name and ALL-FORMATS options

The format-name is the name of the DDS record format definition that is to be translated into an ILE COBOL data description entry. The format-name must follow the rules for the formation of an ILE COBOL data-name.

The ALL-FORMATS option will translate all the formats defined for a file, including names that do not conform to the data-names rules. A REPLACING phrase must be used to change any such format-name into a valid data-name. However, a REPLACING phrase cannot be used to change a format-name within an FD entry for an indexed file defined with EXTERNALLY-DESCRIBED-KEY. If the key cannot be defined using a data-name in the RECORD KEY clause, then it will be necessary to change the format-name in the DDS specifications for the file.

Note:
In this context, the compiler accepts ALL-FORMAT as the equivalent of ALL-FORMATS.

The VLR Option

The VLR option should be used with variable record files. The option specifies copying from variable-length fields. This overrides the CVTOPT(*VARCHAR) option on the CRTCBLMOD and CRTBNDCBL commands.

The PREFIX Options

The PREFIX options allows you to specify a prefix (literal) to be inserted in front of every field name. You can use it to help identify (that is, document) the contents or usage of the field. The literal can be contained within a pair of apostrophes or a pair of quotation marks. The maximum length of the literal allowed is 15 characters.

I-O

If neither -I or I-FIELDS, nor -O or O-FIELDS is specified, then -I-O or I-O-FIELDS is assumed. If -I and O-FIELDS, or -O and I-FIELDS is specified, then -I-O or I-O-FIELDS is assumed.

If a format-name is specified without the indicator attribute, and both -I and -O formats are to be generated, each record format is generated as a redefinition of a 05 elementary item defined as the size of the largest record format that will be generated.

If ALL-FORMATS is specified without the indicator attribute, each record format is generated as a redefinition of a 05 elementary item defined as either:

When the indicator attribute is specified, no redefinition takes place. Instead, each of the formats generates a separate data structure. For details, refer to INDICATOR Attribute of the Format 2 COPY Statement.

If the file is a database file, a single I-O format is generated.

For all other file types the description generated varies as follows:

The use of the Indicator attribute is discussed under INDICATOR Attribute of the Format 2 COPY Statement.

File-name is the name of an iSeries system file. The generated DDS entries represent the record format(s) defined in the file. The file must be created before the program is compiled.

Library-name is optional. If it is not specified, the current job library list is used as the default value.

SUBSTITUTE Phrase

SUBSTITUTE Phrase - Format
 
>>-SUBSTITUTE--+----------------------------+------------------><
               '-ALL--+-------------------+-'
                      '-EXCEPT--literal-2-'
 
 

The SUBSTITUTE phrase allows you to bring DDS into your program, while preserving certain characters, such as the underscore character. The underscore is not a standard ILE COBOL character, but it is required for specifying locale categories. To preserve the underscore character, for example, in copied DDS, the SUBSTITUTE phrase would be used as follows:

      ...SUBSTITUTE ALL EXCEPT '_'.
literal-2
Should be a 1-byte non-numeric literal. The character specified in literal-2 is not substituted.

REPLACING Phrase

The REPLACING phrase is described in REPLACING Phrase.

Related Information

Using Null-Capable Fields in DDS Files

When a field

is defined as ALWNULL in DDS, the COPY DDS statement identifies the field as null-capable with a comment. For example, the following two figures show the DDS file containing the null-capable field, and the resulting comment that is created for that field when it is copied into the ILE COBOL program's FILE-SECTION.

Figure 28. DDS Showing Null-Capable Fields


 ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....
      A* With the following physical file (TESTPF)
                 R TESTING
                   FLD1          5S 0
                   FLD2          8       ALWNULL
                   FLD3          6

Figure 29. Result After Null-Capable DDS File Copied into ILE COBOL Program


* A COPY DDS-TESTING OF TESTPF.
*    I-O FORMAT:TESTING    FROM FILE TESTPF    OF LIBRARY QTEMP
*
     05  TESTING.
         06 FLD1                             PIC 9(5).
         06 FLD2                             PIC X(8).
                    (null-capable field)
         06 FLD3                             PIC X(6).

To generate the null-map and null-key-map for the DDS null-capable record formats that are being copied in, the WITH NULL-MAP and WITH NULL-KEY-MAP phrases need to be specified on a new COPY DDS statement in the WORKING-STORAGE or LOCAL-STORAGE sections. Only one copy of the NULL-MAP is generated per format in the DDS. For example, if the format contains both I (input only) and B (input and output) fields, the size of the null-map generated is for all fields specified in the format. In other words, it would include all I and B fields.

For each of the null-capable fields defined in the DDS for a specific format, a data item definition is generated. The data item generated, depends on whether you specify NULL-MAP or NULL-MAP-ALPHANUM on the COPY DDS statement in the WORKING-STORAGE or LOCAL-STORAGE sections.

If you specify NULL-MAP, a null-map is created with PIC 1 values that are initialized to binary zero (0). The following statement is generated in the source for a null-capable field:

     06  <field-name>-NF     PIC 1  VALUE B"0".

If the field is not null-capable, a FILLER item is generated.

If you specify NULL-MAP-ALPHANUM, a null-map is created with PIC X values that are initialized to the character zero (0). The following statement is generated in the source for a null-capable field:

     06  <field-name>-NF     PIC X  VALUE ZERO.

If the field is not null-capable, the following statement is generated in the source:

     06  <field-name>-AN     PIC X  VALUE ZERO.

The size of a null-map generated using NULL-MAP-ALPHANUM is the same as the size of a null-map generated using NULL-MAP.

Figure 30. DDS File With Some Fields Not Null-Capable


 ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....
      A* Physical file for DDS
                 R REC
                   FLD1          1A
                   FLD2          1A     ALWNULL
                   FLD3          1A

Figure 31. ILE COBOL Code Generated From COPY DDS with NULL-MAP


*DDS Generated
  05 REC-NM
     06 FILLER          PIC X VALUE ZERO.
     06 FLD2-NF         PIC 1 VALUE B"0".
     06 FILLER          PIC X VALUE ZERO.

Considerations for Using Null-Capable Fields

It is possible that a null-map field can contain a value other than 1 or 0. For example, it is possible that SQL placed a value of 2 in a null-map field to indicate that the field contains a result of a divide by zero.

To be able to see a value other than 0 or 1 in a null-map, you must specify NULL-MAP-ALPHANUM on your COPY DDS statement.

NULL-MAP-ALPHANUM extends the range of values that can be received into or sent from the null map to include values other than 0 or 1. Only a value of 1 in a null map field indicates that the field is null. For more information on values other than 0 or 1 that can be sent or received in the null map, refer to the DB2 Universal Database for AS/400 section of the Database and File Systems category in the iSeries Information Center at this Web site - http://www.ibm.com/eserver/iseries/infocenter.

Using COPY DDS with Date Data Types

Table 38 and Table 39 list the DATFMT parameters allowed for zoned, packed, and character DDS fields, and their equivalent ILE COBOL format that is generated from COPY DDS when the CVTOPT(*CVTTODATE) conversion parameter is specified.

Table 38 lists the OS/400 DDS date data types and their equivalent ILE COBOL format. Table 38 is for character and zoned fields; USAGE DISPLAY is assumed.

Table 38. DDS Date Data Types and Their Equivalent ILE COBOL Format

i5/OS Format COBOL-Generated Format Description Format Valid Separators Length
*MDY %m/%d/%y Month/Day/Year mm/dd/yy /-.,& 8
*DMY %d/%m/%y Day/Month/Year dd/mm/yy /-.,& 8
*YMD %y/%m/%d Year/Month/Day yy/mm/dd /-.,& 8
*JUL %y/%j Julian yy/ddd /-.,& 6
*ISO @Y-%m-%d International Standards Organization yyyy-mm-dd - 10
*USA %m/%d/@Y IBM USA Standard mm/dd/yyyy / 10
*EUR %d.%m.@Y IBM European Standard dd.mm.yyyy . 10
*JIS @Y-%m-%d Japanese Industrial Standard Christian Era yyyy-mm-dd - 10

Table 11 lists the i5/OS DDS time data types and their equivalent ILE COBOL format. Table 39 is for packed fields; USAGE PACKED-DECIMAL is generated.

Table 39. DDS Time Data Types and Their Equivalent ILE COBOL Format

i5/OS Format COBOL-Generated Format Description Format Valid Separators Length
*HMS %H:%M:%S Hours:Minutes:Seconds hh:mm:ss :.,& 8
*ISO %H.%M.%S International Standards Organization hh.mm.ss . 8
*USA %I:%M @p IBM USA Standard. AM and PM can be any mix of upper and lower case. hh:mm AM or hh:mm PM : 8
*EUR %H.%M.%S IBM European Standard hh.mm.ss . 8
*JIS %H:%M:%S Japanese Industrial Standard Christian Era hh:mm:ss : 8

General Notes

 
    SELECT FILE-X
    ASSIGN TO DATABASE-CUSTMASTER.
    .
    .
    .
FD  FILE-X
    LABEL RECORDS ARE STANDARD.
01  FILE-X-RECS.
     COPY DDS-ALL-FORMATS OF
        QGPL-CUSTMASTER.   (See Note 1.)
    .
    .
    .
WORKING-STORAGE SECTION.
01  ADR-REC.
     COPY DDS-CUSTADR OF
         CUSTMASTER.     (See Note 2.)
01  DETAIL-REC.
     COPY DDS-CUSTDETL OF
         CUSTMASTER.     (See Note 2.)

Notes:

  1. This COPY statement generates only one storage area for all formats.
  2. These COPY statements generate separate storage areas.

Data Structures Generated

This section describes the data structures generated by the COPY statement:

Format (Record) Level Structures

At the beginning of each format, a table of comments is generated in the source program listing. These comments provide details of the files used during compilation of the program. If there are record keys for the file, comments are also generated to show how the keys are defined in DDS. The record key entries that may appear in the table and the table heading are listed below.

Heading Possible Entry
NUMBER
NAME
RETRIEVAL
ALTSEQ
key field number
key field name
ASCENDING, DESCENDING
NO, YES

If redefinition is required to allow for the generation of multiple formats, a group level name is generated as follows:

     05 file-name-RECORD
        PIC X(size of largest record).

for each format a group level name is assigned as follows:

Data Field Structures

Field names, PICTURE definitions, and numeric usage clauses are derived directly from the internal DDS format field names (or alias names in the case of the DD option) and data type representations. Field names and PICTURE definitions are constructed as follows:    06 field-name PIC  (See Note 1 in following table.)

Note:
See Table 40 for the appropriate COBOL definition.

Table 40. Data Field Structures

DDS COBOL DATA DIVISION
n=total field length (DDS pos. 30-34)
m=number of decimals (DDS pos. 36 & 37)

Data Type (pos. 35) Formats If DDS pos. 36 & 37 are blank If DDS pos. 36 & 37 are not blank
PHYSICAL, LOGICAL, PRINTER, AND COMMUNICATIONS FILES
  (Blank)
P
S
B
F



A
H
L
T
Z
E
J
O
G

Default
Packed decimal5
Zoned decimal/signed numeric4
Binary
Floating-Point1
Single Precision
Double Precision
Character4
Hexadecimal data
Date2
Time2
Timestamp2
DBCS-Either data
DBCS-Only data
DBCS-Open data
DBCS-Graphic data
UCS2-Graphic data
PIC X(n)3
PIC S9(n) COMP-3
PIC S9
PIC S9(n) COMP-4
PIC 9(5) COMP-4 or COMP-1
PIC 9(10) COMP-4 or COMP-2
PIC X(n)3
PIC X(n)
PIC X(n) or FORMAT DATE
PIC X(n) or FORMAT TIME
PIC X(n) or FORMAT TIMESTAMP
PIC X(n)
PIC X(n)
PIC X(n)
PIC X(2n) or PIC G(n)3
--
PIC N(2n)
PIC S9(n-m)V9(m)
PIC S9(n-m)V9(m) COMP-3
PIC S9(n-m)V9(m)
PIC S9(n-m)V9(m) COMP-4
PIC 9(5) COMP-4 or COMP-1
PIC 9(10) COMP-4 or COMP-2
DISPLAY FILES
 (Blank)
X
N
Y
I
W
A
D
F



M
L
T
Z
S
E
J
O
G

Default
Alphabetic Only
Numeric Shift
Numeric Only
Inhibit Keyboard Entry
Katakana
Alphanumeric Shift
Digits Only
Floating-point1
single precision
double precision
Numeric-only Character
Date2
Time2
Timestamp2
Signed-Numeric Shift
DBCS-either
DBCS-only
DBCS-open
DBCS-graphic
UCS2-graphic
PIC X(n)
PIC X(n)
PIC X(n)
--
PIC X(n)
PIC X(n)
PIC X(n)
PIC X(n)
PIC 9(5) COMP-4 or COMP-1
PIC 9(10) COMP-4 or COMP-2
PIC X(n)
PIC X(n) or FORMAT DATE
PIC X(n)or FORMAT TIME
PIC X(n) or FORMAT TIMESTAMP
--
PIC X(n)
PIC X(n)
PIC X(n)
PIC X(2n) or PIC G(n)
--
PIC N(2n)
PIC S9(n-m)V9(m)
--
PIC S9(n-m)V9(m)
PIC S9(n-m)V9(m)
PIC S9(n-m)V9(m)
--
--
PIC S9(n)
PIC 9(5) COMP-4 or COMP-1
PIC 9(10) COMP-4 or COMP-2
--
--
--
--
PIC S9(n-m)V9(m)
--
--
--
--

Notes:

  1. If the *NOFLOAT value of the CVTOPT parameter is in effect, then floating-point fields are brought in as FILLER items with USAGE of BINARY. If *FLOAT is specified, the fields are brought in using their given DDS names with a USAGE of COMP-1 (single-precision floating-point) or USAGE of COMP-2 (double-precision floating-point). See Floating-Point Fields.

  2. FILLER items are declared as alphanumeric by default. You can also have COBOL treat date, time, and timestamp fields as date-time data types by specifying *DATE, *TIME, or *TIMESTAMP on the CVTOPT parameter of the CRTBNDCBL or CRTCBLMOD command. See Date, Time, and Timestamp Fields.

  3. In DDS, if the field has an attribute of VARLEN, the result is two additional bytes at the beginning of the field.

  4. If you have a DDS character or zoned data type with the DATFMT keyword, ILE COBOL treats it as a date field, if the *CVTTODATE value of the CVTOPT parameter in the CRTBNDCBL or CRTCBLMOD command is specified.

  5. If you have a DDS packed data type with the DATFMT keyword, ILE COBOL treats it as a date field, if the *CVTTODATE value of the CVTOPT parameter in the CRTBNDCBL or CRTCBLMOD command is specified.

  6. In DDS, if the field with data type G and has an attribute CCSID(13488), it is a UCS-2 graphic data type. To bring in the UCS-2 graphic data type as a COBOL NATIONAL data type, specify *PICNGRAPHIC on the CVTOPT parameter of the CRTBNDCBL or CRTCBLMOD command. For more information, see ILE COBOL for AS/400 Programmer's Guide.

Indicator Structures

If indicators are requested, and exist in the format, an additional group name (06 level) is generated at the beginning of the structure, followed by entries (07 level) for the relevant individual indicators.

06  format-name-(I or O)-INDIC.
    07  INxx PIC 1 INDIC xx.

where xx is the indicator number.

For example:

06  SAMPLE1-I-INDIC.
    07  IN01 PIC 1 INDIC 01.
    07  IN04 PIC 1 INDIC 04.
    07  IN05 PIC 1 INDIC 05.
    07  IN07 PIC 1 INDIC 07.
06  FLD1 PIC  ...  .
06  FLD2 PIC  ...  .

Related Information

INDICATOR Attribute of the Format 2 COPY Statement

The INDICATOR attribute specifies whether or not data description entries are generated for indicators.

If the INDICATOR attribute is specified, data description entries are generated for indicators, but not for data fields.

An 05 group level entry is generated as follows:

The data description entries that are generated are determined by which one of the usage attributes (I, O, or I-O) is specified or assumed in the COPY statement.

The individual indicator descriptions are generated as described under Indicator Structures.

If the INDICATOR attribute is not specified, whether data description entries are generated for indicators depends on whether the file had the keyword INDARA specified in the DDS at the time it was created.

Generation of I-O Formats

When all field descriptions are identical, and you have requested INPUT or OUTPUT fields implicitly or explicitly, only one set of field descriptions is generated. This type of description is annotated with a comment line reading, "I-O FORMAT: format-name". Neither -I nor -O is appended to the record format name.

Note:
This always happens for database files because all field descriptions within a database file are identical.(See Figure 32.)

Figure 32. Generation of I-O Formats


5722WDS V5R4M0  060210 LN  IBM ILE COBOL         TESTLIB/STRTEXTD     I-SERIES1  06/02/15 11:27:50     Page  2
                                    S o u r c e
STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME   CHG DATE
  1     000100 IDENTIFICATION DIVISION.
  2     000200 PROGRAM-ID. STRTEXTD.
        000300
  3     000400 ENVIRONMENT DIVISION.
  4     000500 CONFIGURATION SECTION.
  5     000600   SOURCE-COMPUTER. IBM-ISERIES.                                                       02/02/21
  6     000700   OBJECT-COMPUTER. IBM-ISERIES.                                                       02/02/21
  7     000800 INPUT-OUTPUT SECTION.                                                                 02/02/21
  8     000900 FILE-CONTROL.
  9     001000     SELECT FILE-1 ASSIGN TO DATABASE-NAMES
 11     001100     ACCESS IS DYNAMIC RECORD KEY IS EXTERNALLY-DESCRIBED-KEY
 13     001200     ORGANIZATION IS INDEXED.
        001300
 14     001400 DATA DIVISION.
 15     001500 FILE SECTION.
 16     001600 FD  FILE-1.
 17     001700 01  RECORD-DESCRIPTION.                                                               02/02/21
        001800     COPY DDS-RDE OF NAMES.                                                            02/02/21
       +000001*    I-O FORMAT:RDE        FROM FILE NAMES      OF LIBRARY TESTLIB            RDE
       +000002*                          RECORD DESCRIPTION                                 RDE
       +000003*THE KEY DEFINITIONS FOR RECORD FORMAT  RDE                                   RDE
       +000004*  NUMBER               NAME                RETRIEVAL       ALTSEQ            RDE
       +000005*   0001   LNAME                            ASCENDING         NO              RDE
       +000006*   0002   FNAME                            ASCENDING         NO              RDE
       +000007*   0003   MINAME                           ASCENDING         NO              RDE
       +000008*   0004   MNAME                            ASCENDING         NO              RDE
 18    +000009       05  RDE.                                                               RDE
 19    +000010           06 FNAME                 PIC X(20).                                RDE
       +000011*                  FIRST NAME                                                 RDE
 20    +000012           06 MINAME                PIC X(1).                                 RDE
       +000013*                  MIDDLE INITIAL NAME                                        RDE
 21    +000014           06 MNAME                 PIC X(19).                                RDE
       +000015*                  REST OF MIDDLE NAME                                        RDE
 22    +000016           06 LNAME                 PIC X(20).                                RDE
       +000017*                  LAST NAME                                                  RDE
 23    +000018           06 PHONE                 PIC S9(10)      COMP-3.                   RDE
       +000019*                  PHONE NUMBER                                               RDE
 24    +000020           06 DATA-DDS              PIC X(40).                                RDE
       +000021*                  REST OF DATA                                               RDE
 25     001900 66  MIDDLE-NAME RENAMES MINAME THRU MNAME.
        002000
 26     002100 PROCEDURE DIVISION.
        002200 MAIN-PROGRAM SECTION.
        002300 MAINLINE.
 27     002400     OPEN INPUT FILE-1.
        002500*      .
        002600*      .
        002700*      .

Fields and Formats

This section provides the following information about the use of fields and formats with Format 2 of the COPY statement:

Redefinition of Formats

The user should pay particular attention to the REDEFINES clause that may be generated for the ALL-FORMATS or -I-O phrases. Since all formats are redefined on the same area (generally a buffer area), several field names can describe the same area of storage, and unpredictable results can occur if the entire format area is not reinitialized prior to each output operation.

Data items that are subordinate to the data item specified in a MOVE CORRESPONDING statement do not correspond and are not moved when they contain a REDEFINES clause or are subordinate to a redefining item.

To avoid reinitialization, multiple Format 2 COPY statements (DDS or DD) using -I and -O suffixes can be used to create separate areas of storage in the Working-Storage or Local-Storage sections for each format or format type (input or output). READ INTO and WRITE FROM statements can be used with these record formats. For example:

FD ORDER-ENTRY-SCREEN . . .
01 ORDER-ENTRY-RECORD . . .
   .
   .
   .
WORKING-STORAGE SECTION.
01 ORDSFL-I-FORMAT.
   COPY DDS-ORDSFL-I OF DOESCR.
01 ORDSFL-O-FORMAT.
   COPY DDS-ORDSFL-O OF DOESCR.
   .
   .
   .
PROCEDURE DIVISION.
   .
   .
   .
READ SUBFILE ORDER-ENTRY-SCREEN NEXT MODIFIED RECORD
   INTO ORDSFL-I-FORMAT FORMAT IS "ORDSFL"
   AT END SET NO-MODIFIED-SUBFILE-RCD TO TRUE.
   .
   .
   .
MOVE CORR ORDSFL-I TO ORDSFL-O.
REWRITE SUBFILE ORDER-ENTRY-RECORD FROM ORDSFL-O-FORMAT
                           FORMAT IS "ORDSFL" . . .
   .
   .
   .
Note:
The COPY statement can be used in the File, Working-Storage and Local-Storage Sections, but the results are not exactly the same. For more information, see Key Generation Examples.

Additional Notes on Field and Format Names

If the generated field name is a COBOL reserved word, the suffix -DDS is added to the field name. If the generated field name originates from a physical file (in other words, the field is an argument of the CONCAT or RENAME keyword), the suffix is also added. For more information, see the ILE COBOL for AS/400 Programmer's Guide.

The REPLACING phrase cannot be used to change the name of a key field or a format name when EXTERNALLY-DESCRIBED-KEY is used.

Floating-Point Fields

A file can contain internal floating-point fields. If the *NOFLOAT value of the CVTOPT parameter (the default) is in effect, then the floating-point fields are brought in as FILLER items with a USAGE of BINARY. If *FLOAT is specified, the fields are brought in using their given DDS names with a USAGE of COMP-1 (single precision floating-point) or COMP-2 (double precision floating-point).

Floating-point key fields are allowed. If the KEY is an internal floating-point number, the sequence of key values will be in numeric order. If the KEY is an external floating-point number, the key is alphanumeric, and the sequence of the records depends on the collating sequence used.

Date, Time, and Timestamp Fields

This section describes the following classes of date, time, and timestamp fields:

It also provides an example of how use DDS to define date, time, and timestamp fields of class date-time.

Class Date-Time

Date-time fields include date, time, and timestamp data items of class date-time, and are allowed for zoned, packed, and character DDS fields that specify the DATFMT keyword. Date data types are not the same as date, time, and timestamp fields that are brought into your program as fixed-length character fields. In ILE COBOL, date data types are converted to USAGE DISPLAY or USAGE PACKED-DECIMAL data items, and date, time, and timestamp fields are converted to alphanumeric data items (as described in Class Alphanumeric).

Date data types are converted to their equivalent ILE COBOL format from COPY DDS when the *CVTTODATE conversion parameter option (CVTOPT) is specified.

For more information about the DATFMT parameters allowed and the equivalent ILE COBOL format that is generated for them from COPY DDS when the CVTOPT(*CVTTODATE) conversion parameter is specified, refer to the ILE COBOL for AS/400 Programmer's Guide.

Class Alphanumeric

Alphanumeric date, time, and timestamp fields are brought into your program only if you specify the CVTOPT(*DATETIME) option on the CRTCBLMOD or CRTBNDCBL command, or the DATETIME option of the PROCESS statement. If *DATETIME is not specified, date, time, and timestamp fields are ignored and are declared as FILLER fields in your ILE COBOL program.

Date, time, and timestamp fields are brought in as fixed-length character fields. Your program can perform any valid character operations on them.

The date, time, and timestamp data types each have their own format.

If a field containing date, time, or timestamp information is updated by your program, and the updated information is to be passed back to your database, the format of the field must be exactly the same as it was when the field was retrieved from the database. If you do not use the same format, an error will occur.

Also, if you try to WRITE a record before moving an appropriate value to a date, time, or timestamp field, the WRITE operation will fail with a file status of 90.

For information on valid formats for each data type, see the DB2 Universal Database for AS/400 section of the Database and File Systems category in the iSeries Information Center at this Web site - http://www.ibm.com/eserver/iseries/infocenter.

Example of Date, Time, and Timestamp DDS

The following example shows you how to define date, time, and timestamp fields in DDS.

Figure 33. DDS File With Date, Time, and Timestamp Fields Defined


 ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....
      A               LOGICAL FILE LF1 FOR DATE, TIME, AND TIMESTAMP EXAMPLES
 00010A
 00020A          R RECORD1
 00030A            DATFLD1         L         DATFMT(*JUL)
 00040A                                      ALIAS(A_DATE_JUL)
 00050A            DATFLD2         L         DATFMT(*EUR)
 00060A                                      ALIAS(A_DATE_EUR)
 00070A            DATFLD3         L         DATFMT(*DMY) DATSEP('-')
 00080A                                      ALIAS(A_DATE_DMY)
 00090A            DATFLD4         L         DATSEP(' ')
 00100A            TIMFLD1         T         TIMFMT(*ISO)
 00110A                                      ALIAS(A_DATE_ISO)
 00120A            TIMFLD2         T         TIMFMT(*USA)
 00130A                                      ALIAS(A_DATE_USA)
 00140A            TIMFLD3         T         TIMSEP(' ')
 00150A            TIMFLD4         T         TIMSEP('.')
 00160A            TSFLD1          Z         DFT('1998-02-27-08.15.22.000000')
      A

If the current date is June 21, 1990, the current system date format value
is MDY, and the system date separator value is '/', DATFLD3 contains
21-06-90. DATFLD4 contains 06 21 90.

If the current date is June 21, 1990, the current system date format value
is MDY, and the current system separator is /, DATFLD1 contains 90/172 (the
172nd day of the year 1990). DATFLD2 contains
21.06.1990.

If the current time is 2 o'clock p.m., the system time
format is hhmmss, and the system time separator is ':',
TIMFLD1 contains 14.00.00. TIMFLD2 contains 2:00
PM.

If the current time is 2 o'clock p.m., the system time
format is hhmmss, and the system time separator is ':',
TIMFLD3 contains 14 00 00. TIMFLD4 contains
14.00.00.

If you are defining a timestamp field, you must specify the default value
in the following format:

    DFT('YYYY-MM-DD-HH.MM.SS.UUUUUU')

If the DFT keyword is not specified, the default value is the current
time.

Variable-Length Fields

You can bring a variable-length field into your program if you specify the CVTOPT(*VARCHAR) option on the CRTCBLMOD or CRTBNDCBL command, or the VARCHAR option of the PROCESS statement. A variable-length field that you extract from an externally-described file becomes a fixed-length group item in your program.

See the ILE COBOL for AS/400 Programmer's Guide for more detailed information about these fields.

When you perform a WRITE operation before explicitly moving a record to the record area, you will often write blanks, which have a hexadecimal value of 40 (X'40'). For variable-length fields, this means that X'4040' will be used as the current length of the field.

X'4040' translates to a decimal value of 16 448, which would probably exceed the maximum defined length of the variable-length field. This causes the WRITE operation or subsequent CLOSE operation to fail with a file status of 90.

Considerations Regarding Use of REPLACING in Format 2 COPY Statement

The REPLACING phrase can be used to replace any of the generated COBOL source, including the level numbers. (See REPLACING Phrase for additional information.) You should, however, note the following exception:

Figure 34 describes the Format 2 COPY statement without the REPLACING option:

Figure 34. Format 2 COPY Statement Without the REPLACING Option


5722WDS V5R4M0  060210 LN  IBM ILE COBOL  TESTLIB/STRTEXTD   I-SERIES1  06/02/15 11:27:50   Page   2
STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN  S COPYNAME  CHG DATE
 
 
 11    000100 FD  CUST-MASTER.
 12    000200 01  CUSTOMER-RECORD.
       000300*
       000400* COPY DDS  W I T H O U T  REPLACING OPTION
       000500*
 13    000600     COPY DDS-CUSMST OF TESTLIB-CUSMSTP.
       +000001*    I-O FORMAT:CUSMST     FROM FILE CUSMSTP    OF LIBRARY TESTLIB            CUSMST
       +000002*                          ORDER HEADER RECORD                                CUSMST
 14    +000003       05  CUSMST.                                                            CUSMST
 15    +000004           06 CUST              PIC X(5).                                     CUSMST
       +000005*                          CUSTOMER NUMBER                                    CUSMST
 16    +000006           06 NAME              PIC X(25).                                    CUSMST
       +000007*                          CUSTOMER NAME                                      CUSMST
 17    +000008           06 ADDR              PIC X(20).                                    CUSMST
       +000009*                          CUSTOMER ADDRESS                                   CUSMST
 18    +000010           06 CITY              PIC X(20).                                    CUSMST
       +000011*                          CUSTOMER CITY                                      CUSMST
 19    +000012           06 STATE             PIC X(2).                                     CUSMST
       +000013*                          STATE                                              CUSMST
 20    +000014           06 ZIP               PIC S9(5)        COMP-3.                      CUSMST
       +000015*                          ZIP CODE                                           CUSMST

The following figure describes the Format 2 COPY Statement with the REPLACING option:

Figure 35. Format 2 COPY Statement With the REPLACING Option


5722WDS V5R4M0  060210 LN  IBM ILE COBOL     TESTLIB/STRTEXTD     I-SERIES1  06/02/15 11:27:50   Page   2
STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN  S COPYNAME   CHG DATE
 
 
 30    001000 FD  CUST-MASTER.
 31    001100 01  CUSTOMER-RECORD.
       001200*
       001300* COPY DDS  W I T H  REPLACING OPTION
       001400*
 32    001500     COPY DDS-CUSMST OF TESTLIB-CUSMSTP
 33    001600          REPLACING NAME BY ADDR-LINE-1
 34    001700                    ADDR BY ADDR-LINE-2
 35    001800                    CITY BY ADDR-LINE-3.
       +000001*    I-O FORMAT:CUSMST     FROM FILE CUSMSTP    OF LIBRARY TESTLIB            CUSMST
       +000002*                          ORDER HEADER RECORD                                CUSMST
 36    +000003       05  CUSMST.                                                            CUSMST
 37    +000004           06 CUST              PIC X(5).                                     CUSMST
       +000005*                          CUSTOMER NUMBER                                    CUSMST
 38    +000006           06 ADDR-LINE-1              PIC X(25).                             CUSMST
       +000007*                          CUSTOMER NAME                                      CUSMST
 39    +000008           06 ADDR-LINE-2              PIC X(20).                             CUSMST
       +000009*                          CUSTOMER ADDRESS                                   CUSMST
 40    +000010           06 ADDR-LINE-3              PIC X(20).                             CUSMST
       +000011*                          CUSTOMER CITY                                      CUSMST
 41    +000012           06 STATE             PIC X(2).                                     CUSMST
       +000013*                          STATE                                              CUSMST
 42    +000014           06 ZIP               PIC S9(5)        COMP-3.                      CUSMST
       +000015*                          ZIP CODE                                           CUSMST

Key Generation Examples

Figure 36. Data Description Specifications for a Physical File


....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A               PHYSICAL FILE PF1 FOR KEY GENERATION EXAMPLES
     A
     A          R PFRECORD
     A
     A            MTH            2
     A            DAY            2
     A            YEAR           4
     A            ITEM           5
     A
     A
     A          K MTH
     A          K DAY

The physical file described by Figure 36 forms a basis for the examples that follow. Each example refers to a logical file (derived from the physical file) that specifies EXTERNALLY-DESCRIBED-KEY in its SELECT clause.

Related Information

Example Using CONCAT Keyword

Figure 37. Data Description Specifications Using the CONCAT Keyword


....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A               LOGICAL FILE LF1 FOR CONCAT KEYWORD EXAMPLES
     A
     A          R RECORD1                   PFILE(PF1)
     A
     A            DATE                      CONCAT(MTH DAY YEAR)
     A
     A          K MTH
     A          K DAY

For the logical file described by Figure 37, COPY DDS generates keys and key names derived from the physical file.

Figure 38. Example Using the CONCAT Keyword


    FD LF1 LABEL RECORDS ARE STANDARD.
    01  LOG-RECORD.
                COPY DDS-ALL-FORMATS OF LF1.
        05  LF1-RECORD PIC X(8).
   *  I-O FORMAT:RECORD-1   FROM FILE LF1        OF LIBRARY COPYDDS
   *
   *THE KEY DEFINITIONS FOR RECORD FORMAT  RECORD1
   *  NUMBER               NAME               RETRIEVAL    TYPE   ALTSEQ
   *   0001  MTH-DDS                           ASCENDING     AN     NO
   *         KEY NAME ORIGINATES FROM PHYSICAL FILE
   *   0002  DAY-DDS-DDS                       ASCENDING     AN     NO
   *         KEY NAME ORIGINATES FROM PHYSICAL FILE
        05 RECORD1       REDEFINES LF1-RECORD.
           06 DATE-DDS              PIC X(8).
           06 FILLER REDEFINES DATE-DDS.
              07 MTH-DDS            PIC X(2).
              07 DAY-DDS-DDS        PIC X(2).
              07 FILLER             PIC X(4).

The COPY statement adds the suffix -DDS to the field names MTH and DATE because MTH is a key that originates from the physical file, and DATE is an ILE COBOL reserved word. The COPY statement adds the suffix -DDS twice to the field name DAY because DAY is both a key that originates from the physical file and an ILE COBOL reserved word.

Note that if you move your COPY statement from the File Section to the Working-Storage Section or to the Linkage Section, the fields subordinate to DATE-DDS are no longer available:

Figure 39. Example Using the CONCAT Keyword--Working-Storage Section


    WORKING-STORAGE SECTION.
    01  WRK-RECORD.
                COPY DDS-ALL-FORMATS OF LF1.
       05  LF1-RECORD PIC X(8).
   *  I-O FORMAT:RECORD-1   FROM FILE LF1         OF LIBRARY COPYDDS
   *
       05  RECORD1      REDEFINES LF1-RECORD.
           06 DATE-DDS             PIC X(8).

Example Using RENAME Keyword

Figure 40. Data Description Specifications Using the RENAMES Keyword


....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A               LOGICAL FILE LF2 FOR RENAME KEYWORD EXAMPLES
     A
     A          R RECORD2                   PFILE(PF1)
     A
     A            MONTH                     RENAME(MTH)
     A
     A          K MTH

For the logical file described by Figure 36, COPY DDS generates a key and key name derived from the physical file:

Figure 41. Using the RENAME Keyword


    *
     FD LF2 LABEL RECORDS ARE STANDARD.
     01  LOG-RECORD.
                 COPY DDS-ALL-FORMATS OF LF2.
       05  LF2-RECORD PIC X(2).
   *  I-O FORMAT:RECORD2    FROM FILE LF2         OF LIBRARY COPYDDS
   *
   *THE KEY DEFINITIONS FOR RECORD FORMAT  RECORD2
   *  NUMBER               NAME              RETRIEVAL    TYPE   ALTSEQ
   *   0001  MTH-DDS                          ASCENDING     AN     NO
   *         KEY NAME ORIGINATES FROM PHYSICAL FILE
       05  RECORD2      REDEFINES LF2-RECORD.
           06 MONTH                PIC X(2).
           06 MTH-DDS REDEFINES MONTH PIC X(2).

The COPY statement adds the suffix -DDS to the field name MTH because MTH is a key that originates from the physical file.

Example Using SST Keyword

Figure 42. Data Description Specifications Using the SST Keyword


....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A               LOGICAL FILE LF3 FOR SST KEYWORD EXAMPLES
     A
     A          R RECORD3                   PFILE(PF1)
     A
     A            YY                 I      SST(YEAR 2 2)
     A
     A          K YY

For the logical file described by Figure 36, COPY DDS generates the following specifications:

Figure 43. Using the SST Keyword


    *
     FD LF3 LABEL RECORDS ARE STANDARD.
     01  LOG-RECORD.
                 COPY DDS-ALL-FORMATS OF LF3.
         05  LF3-RECORD PIC X(2).
    *  I-O FORMAT:RECORD3    FROM FILE LF3         OF LIBRARY COPYDDS
    *
    *THE KEY DEFINITIONS FOR RECORD FORMAT  RECORD3
    *  NUMBER               NAME              RETRIEVAL    TYPE   ALTSEQ
    *   0001  YY                               ASCENDING     AN     NO
        05  RECORD3      REDEFINES LF3-RECORD.
            06 YY                   PIC X(2).

The COPY statement does not add a suffix to the field name YY because YY is neither a key that originates from the physical file nor an ILE COBOL reserved word.

+----------------------------End of IBM Extension----------------------------+


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]