+-------------------------------IBM Extension--------------------------------+
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:
Related Information
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 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 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 copies in the internal DDS field names for the specified DDS format.
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 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.
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 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.
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 - 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 '_'.
The REPLACING phrase is described in REPLACING Phrase.
Related Information
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.
|
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.
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 |
be copied only once under an FD. For example, if all of the formats of a file are copied under an FD, no other Format 2 COPY statement can be specified for the same file under that FD.
For example, if we assume that the file CUSTMASTER contains two formats: CUSTADR and CUSTDETL ; then the following COPY statements could be specified.
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:
This section describes the data structures generated by the COPY statement:
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:
05 format-name-I
05 format-name-O
05 format-name
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.)
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
|
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
|
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:
| |||
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
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:
COPY DDS-format-name-INDIC
will generate
05 format-name-I. (or -0 as appropriate).
COPY DDS-ALL-FORMATS-INDIC
will generate
05 file-name-RECORD.
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.
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.
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* .
|
This section provides the following information about the use of fields and formats with Format 2 of the COPY statement:
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" . . .
.
.
.
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.
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.
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.
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.
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.
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 If the current date is June 21, 1990, the current system date format value If the current time is 2 o'clock p.m., the system time If the current time is 2 o'clock p.m., the system time If you are defining a timestamp field, you must specify the default value DFT('YYYY-MM-DD-HH.MM.SS.UUUUUU')
If the DFT keyword is not specified, the default value is the current |
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.
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
|
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
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).
|
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.
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----------------------------+
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.