CREATE: make a new file

Description

A powerful file utility that creates new files by merging data from existing files or raw data elements.

Categories

Program Development
Conversion

Related files

CREATE: Object file for program.

DISPLAY: The Wang DISPLAY utility is used to show the results of the session.

User Instructions

CREATE is a powerful file utility that allows you to combine selected data from existing files or raw data elements to form a new data file. It can be used to modify existing files, create a new file from scratch, merge data from several files, or to extract sample data from production files. (Note: the following information assumes an understanding of data storage, file types, and disk file processing on the VS.)

To use, define the destination file at the OUTPUT screen and the data sources at the INPUT, ALTPATHS, LITERAL, FILE, ASCII, PAD, COUNT, and RECSIZE screens. When all sources have been defined, execute CREATE to make the new file.

Each group of input parameters in CREATE is referred to as a block, and may contain specifications for a number of data sources. These parameters match the input sources to characters in the output file, and each block should define the entire area of the output record. Note that CREATE allows areas to be overlapped; for example, the entire record area is set to spaces with the PAD option before any other information is written. Any number of blocks may be used to merge information from a variety of files.

The steps to make a file are as follows:

1. Define the output file's characteristics at the OUTPUT screen.

2. If the output file is indexed, set the processing mode (the MODE field in OUTPUT). The default value ('OUTPUT') is valid only if the input information is already in primary key order; set to 'IO' if this is not the case.

3. If the output file is alternate-indexed, you may include or exclude the alternate key from an input source at the ALTKEYS screen.

4. Define input data for each block example by entering a file name and location or by pressing one of the PF keys shown. Data for each block may include literal character elements, repeated characters (the PAD option), a sequential number (the ASCII option), or specific elements in an existing file (the FILE option; see examples for consecutive and indexed files). A maximum record count can be set for each block, limiting the number of records created from each source. The INPUT screen can be repeated as many times as necessary.

5. Process the file.

When processing is complete, the DISPLAY utility may be invoked from within CREATE to check the completed file. If desired, CREATE may be run again from this point.

Programmer Instructions

With many GETPARM screens and a confusing array of options, CREATE is best run from a procedure for any production use. A sample procedure may be created for a given task by using the PROCFORM or PROCGEN utilities or through the GETPARMs defined below.

Virtually all of CREATE is GETPARM screens, so it can be run entirely under program control. Many of the GETPARM screens are used repetitively, so special care must be made the PF keys associated with the screen.

OUTPUT      Press (RETURN) to continue, PF(14) for additional
            documentation, or PF(16) to exit without
            processing.

  FILE      (blank)     Location of the file to be created.
  LIBRARY   [outlib]    Defaults to the user's defaults for
  VOLUME    [outvol]    output files.

  TYPE      (blank)     The organization of the output file.

  RECSIZE   (blank)     The record size of the output file.
                        If variable length records, the
                        maximum record size.

  MULTIPLE  NO          Change to YES for multiple record
                        sizes.

  COMPRESS  YES         Change to NO for fixed-length records.

  RECORDS   (blank)     Approximate number of records to be
                        created.

  CLASS     [fileclas]  File protection class.

  RETAIN    0           Retention period.  Defaults zero days.

  RELEASE   YES         Set to NO to retain unused file space
                        after processing.

  KEYPOS    (blank)     Character position and length of
  KEYLEN    (blank)     primary index.  Applies to indexed or
                        alternate-indexed files only.

  MODE      OUTPUT      The file creation mode.  Use OUTPUT
  ERRLIST   NO          only when all records are in key
                        order; otherwise use IO mode.

ALTKEYS     Optional; applies only if the file is
            alternate-indexed.  Press (RETURN) to continue or
            PF(01) to return to the OUTPUT screen.

  KEYPOSx   (blank)     Character location of alternate
  KEYLENx   (blank)     indexes.  May be repeated up to 16
  FLAGSx    (blank)     times (e.g. KEYPOS1/./././KEYPOS16).

RECSIZE     Optional; applies only if the file is
            variable-length.  Press (RETURN) to continue or
            PF(16) to end input and process (create output
            file).

  RECSIZE   (max)       Displays the record size as entered
                        on the OUTPUT screen.  May be reduced
                        for each block if desired.

ALTPATHS:   Optional; applies only if the file is
            alternate-indexed.  Press (RETURN) to continue or
            PF(16) to end input and process (create output
            file).

  ALTKEY1   (blank)     Allows selection of alternate key
                        paths by block.  To include alternate
                        key, a non-blank must be entered for
                        each applicable alternate key field.
                        May be repeated up to 16 times (e.g.
                        ALTKEY1/./././ALTKEY16).

INPUT       Press (RETURN) to specify data elements from an
            input file, PF(01) to specify a literal string
            field, PF(02) to specify a repeated (pad) field,
            PF(03) to specify an ASCII numbering field,
            PF(04) to set the maximum number of records to be
            created from this block, or PF(16) to end
            specification and process (create output file).

  FILE      (blank)     Location of the file to be used as
  LIBRARY   [inlib]     input.  Initially defaults to the
  VOLUME    [invol]     user's INLIB values.

FILE        Optional; (RETURN) from INPUT screen.  Press
            (RETURN) to continue, PF(01) to return to the
            INPUT screen, PF(02) to switch from ASCII to
            hexadecimal notation (toggle), or PF(14) to see
            additional descriptions of the field options.
            The hexadecimal option (PF(02)) applies to the
            START, END, and CSTRING parameters only.

  INPOS     1           Location of input and output
  OUTPOS    1           characters to be moved.  Can be
  LENGTH    (max)       repeated several times within the
  COUNT     1           same record via the COUNT keyword.

  START     (min)       The starting and ending records
  END       (max)       in the input file to be considered.
                        May be the record number (consecutive
                        files) or the index range (indexed
                        files).  Defaults to the first and
                        last records in the file.

  INCRMENT  1           Optional field; applies only to
                        consecutive input files.  The number
                        of records to be used.

  CINPOS    (blank)     Area in the input file to be used for
  CLENGTH   (blank)     record selection.  Specifies the
  COMPARE   (blank)     position, length, test relationship,
  CSTRING   (blank)     and character information to be used.

LITERAL     Optional; PF(01) from the INPUT screen.  Press
            (RETURN) to continue or PF(01) to return to the
            INPUT screen without processing.

  STRING    (blank)     64-character literal string.

  POSITION  (blank)     The position and length of the string
  LENGTH    (blank)     in the output file.  LENGTH will
                        default to the non-blank length of
                        the string.

PAD         Optional; PF(02) from the INPUT screen.  Press
            (RETURN) to continue, PF(01) to return to the
            INPUT screen without processing or (02) to switch
            from ASCII to hexadecimal mode (a toggle).

  PAD       (blank)     Single character to be repeated.

  POSITION  (blank)     The position and number of times the
  LENGTH    (blank)     string is repeated in the output
                        file.  Always entered in decimal form.

ASCII       Optional; PF(03) from the INPUT screen.  Press
            (RETURN) to continue or PF(01) to return to the
            INPUT screen without processing.

  START     (blank)     The starting and ending number for
  END       (blank)     the sequence.

  INCRMENT  (blank)     The value of each incremental change.

  POSITION  (blank)     The position and length of the
  LENGTH    (blank)     number sequence.

  REPEAT    NO          Set to YES to repeat the same number
                        without change.

COUNT       Optional; PF(04) from the INPUT screen.  Press
            (RETURN) to continue or PF(01) to return to the
            INPUT screen without processing.

  RECORDS   (blank)     The maximum number of records to be
                        created from this input block.

EOJ         Press PF(01) to restart, PF(14) to display the
            file just created, or PF(16) to exit CREATE.

Output options: the only report option is the optional error report showing duplicate keys.

Example of use

As the name implies, CREATE is used to make new files. It's difficult to imagine limits for CREATE uses. Some likely possibilities include:
• Create empty work files for batch update files.

• Concatenate multiple backup listings into a single file for later review.

• Merge literals and existing data files into a single, new file.

• Use in procedures for general file revisions.

Comments

A powerful utility that can replace programs in many cases. Very comprehensive, but somewhat difficult to use. Due to the large number of options, production use usually requires a procedure to reduce the number of parameters and, thus, the chances for error.