CREATE Statement

The CREATE statement defines the contents of a record to be written directly as an output record or to be made available to an exit routine you supply. An output record is constructed by referring to previously defined fields by name or by providing a pattern ("picture") to be placed in the record. You can generate multiple records with a single CREATE statement.

An output record is constructed in the following order:

A fill character, specified or default (binary zero), is initially loaded into each byte of the output record.
If the INPUT operand is specified on the CREATE statement, and not on an FD statement, the input records are left-aligned in the corresponding output record.
If the INPUT operand specifies a ddname in any FD statement, only the fields described by the FD statement(s) are placed in the output record.
FD fields, if any, are placed in the output record in the order of the appearance of their names in the CREATE statement. The location of the fields in the output record depends upon whether the field has a specified starting location (STARTLOC).
For instance, if you do not specify a starting location for any field, the fields will be placed in order in the output record, starting at the first position of the output record. Figure 1 shows the addition of field X to two different records. In record 1, field X is the first field referred to by the CREATE statement; therefore, field X begins in the first byte of the output record. In record 2, two fields, field A and field B, have already been referred to by a CREATE statement; field X, the next field referred to, begins immediately after field B. Field X does not have a special starting location in this example.

Figure 1. Default Placement of Fields within an Output Record Using IEBDG

If FD fields have starting locations specified explicitly, each field is placed in the output record beginning at the location specified. These fields are written to the output record in the order they appear on the CREATE statement. Thus, if a field has the same starting location as another field, or has a starting location that overlaps another field, the field that appears later on the CREATE statement is the field whose contents occupy those positions. Figure 2 shows an example of two fields with specified starting locations that result in an overlap of the fields.

Figure 2. Placement of Fields with Specified Output Locations

If some fields specify a starting location and others do not, the location of the fields will depend on the order in which you specify them in the CREATE statement. A field with an unspecified starting location will begin immediately following the last record written.

For instance, Figure 3 shows how two fields, one with a starting location specified and one without, are written to an output record. Record 1 shows FIELD1, with a specified starting location, written first. FIELD1 starts at location 20, and occupies 20 bytes. FIELD2 is then written next, and so begins at position 40. Record 2 shows FIELD2, with an unspecified starting location, written first. FIELD2 is placed starting at the first position of the output record. FIELD1 is then placed at position 20, even though it overlaps FIELD2, which has a length of 30.

Figure 3. Placement of Fields with Only Some Output Locations Specified
A CREATE statement picture, if any, is placed in the output record.

Figure 4 shows three ways in which output records can be created from utility control statements.

Figure 4. Creating Output Records with Utility Control Statements

When defining a picture in a CREATE statement, you must specify its length and starting location in the output record. The specified length must be equal to the number of specified alphabetic or numeric characters. (When a specified decimal number is converted to packed decimal or binary, it is automatically right-aligned.)

You can use another data set as a source for input records for creating output records, or you can include input records in the input stream or SYSIN data set. Only one input data set can used for an individual CREATE statement.

The syntax of the CREATE statement is:

Label	Statement	Parameters
[label]	CREATE	[QUANTITY=n] [,FILL={'character '\|X'nn' }] [,INPUT={ ddname\|SYSIN[({ cccc\|$$$E })]}] [,PICTURE= length,startloc, {'character-string '\| P'n '\|B'n'}] [,NAME={( namelist)\| (namelist-or-(copygroup ))} [,EXIT=routinename]

where:

Note: Each keyword should appear no more than once on any CREATE statement.

QUANTITY=n

specifies the number of records that this CREATE statement is to generate; the contents of each record are specified by the other parameters. If both QUANTITY and INPUT are coded, and the quantity specified is greater than the number of records in the input data set, the number of records created is equal to the number of input records to be processed plus the generated data up to the specified number.

Default: If QUANTITY is omitted and INPUT is not specified, only one output record is created. If QUANTITY is omitted and INPUT is specified, the number of records created is equal to the number of records in the input data set.

If both QUANTITY and INPUT are coded, but the QUANTITY is less than the number of records in the input data set, then only the number of records specified by QUANTITY are written to the output data set.

FILL={'character'|X'nn'}

specifies a value that is to be placed in each byte of the output record before any other operation in the construction of a record. These values can be coded:

'character': specifies a character that is to be translated to EBCDIC and placed in each byte of the output record.
X'nn': specifies 2 hexadecimal digits (for example, FILL=X'40', or FILL=X'FF') to be placed in each byte of the output record.

Default: Binary zeros (X'00') are placed in the output record.

INPUT={ddname|SYSIN [({cccc|$$$E})]}

defines an input data set whose records are to be used in the construction of output records. If INPUT is coded, QUANTITY should also be coded, unless the remainder of the input records are all to be processed by this CREATE statement. If INPUT is specified in an FD statement referenced by this CREATE statement, there must be a corresponding ddname specified in the CREATE statement in order to get the input records read. These values can be coded:

ddname: specifies the ddname of a DD statement defining an input data set.
SYSIN[({cccc|$$$E})]: specifies that the SYSIN data set contains records (other than utility control statements) to be used in the construction of output records. If SYSIN is coded, the input records follow this CREATE statement (unless the CREATE statement is in a REPEAT group, in which case the input records follow the last CREATE statement of the group). The "cccc" value can be any combination of from 1 to 4 characters. If cccc is coded, the end of the input records is indicated by a record containing those characters beginning in column 1.
The default value for cccc is $$$E. If you do not code a value for cccc when you use INPUT=SYSIN, you must use $$$E to mark the end of the input records in SYSIN. The first three characters are dollar signs, which are X'5B'.

PICTURE=length,startloc, {'character-string'| P'n'|B'n'}

specifies the length, starting position and the contents of a user-supplied pattern. If both PICTURE and NAME are omitted, the fill character specified in the CREATE statement appears in each byte of applicable output records. These values can be coded:

length: specifies the number of bytes that the pattern ("picture") will occupy. Length must be equal to or less than the LENGTH parameter value in the FD statement.
startloc: specifies a starting position (within any applicable output record) in which the picture is to begin.
'character-string': specifies a character string that is to be placed in the applicable records. The character string is left-aligned at the defined starting position. A character string may be broken in column 71, if you place a nonblank character in column 72 and continue the string in column 4 of the next statement.
P'n': specifies a decimal number that is to be converted to packed decimal and right-aligned (within the boundaries of the defined length and starting position) in the output records or defined field.
B'n': specifies a decimal number that is to be converted to binary and right-aligned (within the boundaries of the defined length and starting position) in the output records or defined field.

NAME={(namelist)| (namelist-or-(copygroup))}

specifies the name or names of previously defined fields to be included in the applicable output records. If both NAME and PICTURE are omitted, the fill character specified in the CREATE statement appears in each byte of the applicable output record. These values can be coded:

(namelist)

specifies the name or names of a field or fields to be included in the applicable output records. Multiple field names must be separated with commas. Each field (previously defined in the named FD statement) is included in an output record in the order in which its name is encountered in the CREATE statement. If only one name is coded, the parentheses are optional.

(namelist-or-(copygroup))

specifies that some or all fields are to be copied in the output records; that is, selected fields are to appear in an output record more than once. The copied fields are specified as:

(COPY=n,name1[,name2] [,...]): where n specifies that the fields indicated are to be treated as a group and copied n number of times in each output record produced by this CREATE statement. Any number of copygroups can be included with NAME. A maximum of 20 field names can be included in a copygroup.

The names of fields that are not to be copied can be specified with copygroups in the NAME parameter, either before, after, or between copygroups.

For example:

NAME=(NAME1,(COPY=2,NAME2),NAME3,(COPY=4,NAME4)).

EXIT=routinename

specifies the name of your routine that is to receive control from IEBDG before writing each output record.

Related reading: For information about specifying an exit routine with IEBDG, see Specifying User Exits with Utility Programs.