BUILD

Generated from C.60.01 /SYS/PUB/CICAT last modified on Thu Jan 11 09:18:52 2001

Back to Main Index


BUILD


     Creates and immediately allocates a new empty file on disk.

SYNTAX


     BUILD filereference

                                        [F]
       [;REC=[[recsize][,[blockfactor][,[U][,BINARY]]]]]
                                        [V][,ASCII ]
                                        [B]
        [{;CCTL  }]
         {;NOCCTL}

        [;TEMP]
        [;DEV=[[dsdevice]#][device]]
        [;CODE=filecode]
        [;DISC=[numrec][,[numextents][,[initialloc]]]]

        [{;RIO  }]
         {;NORIO}

         {;STD   }
         {;MSG   }
        [{;CIR   }]
         {;KSAMXL}
         {;SPOOL }

        [;ULABEL=numlabels]

        [;KEY={^filereference2}]
              {keyinfo        }

        [;FIRSTREC=recnum]
        [{;REUSE  }]
         {;NOREUSE}

        [;LANG={langid  }]
               {langname}

        [{;DEFBLK}]
         {;OPTMBLK}


PARAMETERS


filereference       Actual name of the file to be created.

                    The filereference can be either in MPE or HFS
                    syntax.

                    MPE Syntax

                    If the filereference does not begin with a dot or a
                    slash, it is parsed according to the MPE syntax and
                    has the following format:

                    filename[/lockword][.groupname[.acctname]]

                    MPE names must contain from one to eight
                    alphanumeric characters, beginning with an
                    alphabetic character.  If acctname is specified,
                    you must have create directory (CD) access to the
                    target group in the account.  The default groupname
                    and acctname are the logon group and account.

                    HFS Syntax

                    If the filereference begins with a dot (.) or a
                    slash (/), it is parsed according to the HFS syntax.
                    In this case the filereference can consist of 1 to
                    253 characters for relative pathnames (for example,
                    ./253chars), and 254 characters for absolute names
                    (for example, /254chars).

                    The following syntax rules apply:


                    File names are not upshifted.

                    File names can be up to 254 characters in length for
                    absolute pathnames, and 253 characters for relative
                    pathnames.

                    File names can begin with, and contain, any of the
                    following characters:

                       a-z, A-Z, 0-9, _, .

                    File names can contain (but not begin with ) a
                    dash (-).

                    File names are of the form

                      path/filename

                    where the path/filename combination may have a
                    maximum of 255 characters.


recsize             Record size.  A positive number indicates words,
                    while a negative number indicates bytes for new
                    files only.  For fixed length files, this is the
                    logical record size.  For undefined length files,
                    this is the maximum record size. For variable length
                    files, this is the maximum logical record size if
                    blockfactor is 1.  If not, this is used to calculate
                    the maximum logical record size and physical record
                    size. For byte stream files, recsize is 1 byte.

                    Records always begin on word boundaries.  Therefore,
                    the record size is rounded up to the nearest word
                    boundary for block size calculations. For a binary
                    file or a variable length ASCII file, odd byte
                    lengths are rounded up and the extra byte is
                    available for data.

                    However, if an odd byte length record size is
                    specified for a fixed or undefined length record
                    file, the extra byte is not available for data.
                    Default is the configured physical record width of
                    the associated device.  If you do not use the DEV=
                    parameter, the default will be DISC with 1023
                    records.

                    For example, a fixed length ASCII file with a record
                    size specified as 11 bytes will have only 11 bytes
                    available for data in each logical record.  However,
                    to determine actual block size, 12 bytes will be
                    used for the record size (block size = 12 bytes
                    multiplied by the blockfactor).  If the file was
                    specified as a binary file, the 11 bytes would be
                    rounded up to 12 bytes (6 words), all of which are
                    available for each logical record.

blockfactor         The number of logical records per physical block in
                    a new file.  The default is calculated by dividing
                    the specified recsize into the configured block
                    size; this value is rounded downward to an integer
                    that is never less than 1.  For variable length
                    record files, blockfactor and recsize are used to
                    calculate the maximum logical and physical record
                    size.  The blockfactor is then set to 1.  For files
                    containing undefined length records, the blockfactor
                    is ignored.  The maximum size of blockfactor is 255.

                    For byte-stream files, blockfactor is set to 1.

F, U, V or B        Defines the length of the records of
                    the file. A file may contain fixed length records
                    (F), undefined length records (U), or variable
                    length records (V) or byte stream format (B).
                    For disk files, the default is F.

BINARY or ASCII     Indicates the type of records the file contains.
                    BINARY indicates binary coded records and is the
                    default.  ASCII indicates ASCII coded records.

CCTL or NOCCTL      Indicates whether or not carriage control characters
                    are supplied along with data written to an ASCII
                    file. CCTL indicates carriage control characters
                    accompany the data; NOCCTL indicates carriage
                    control characters are not specified. The default is
                    NOCCTL.

TEMP                Indicates that the file will be created as a
                    temporary file and will be saved in the job/session
                    temporary file domain when closed.  The default is
                    that a permanent file is created.

dsdevice            The device class name or logical device number used
                    to open a communications link to a remote computer
                    that contains the source file.  The default is the
                    local system, or the computer on which the transfer
                    request originates.  A # symbol is a delimited
                    between the file name of the remote computer and the
                    remote device file name.

device              Specifies either the devclass or ldev on which the
                    file is to reside.  A device class name, devclass,
                    consists of up to eight alphanumeric characters
                    beginning with an alphabetic character, such
                    as DISC.  The DEV= parameter does not accept
                    device names.  It does accept volume class (an
                    asterisk (*) and double asterisk (**) must precede
                    volume name). When you specify devclass, the file
                    is allocated to any available device in that
                    class. If you are opening a file destined for a
                    mountable volume, you must specify a device class
                    which includes the drives upon which the home
                    volume set is mounted.  The file is then allocated
                    to any of the home volume set's volumes that fall
                    within that device class.

                    The logical device number (ldev) consists of a one-
                    to three-digit number specifying a particular
                    device.  Default is the device class name DISC.

filecode            A code indicating a specially formatted file.  This
                    code is recorded in the file label and is available
                    to processes accessing the file through the
                    FFILEINFO or FGETINFO intrinsic. Although any user
                    can specify a positive integer ranging from 0 to
                    32,767 or mnemonic name for this parameter, certain
                    reserved integers and mnemonics have particular
                    system-defined meanings.  Default is the unreserved
                    file code of 0.

                    Using 1090 (LOG) as your designated file code may
                    not yield the number of records you specify in the
                    ;DISC= parameter. Most files use the number of
                    records specified in the ;DISC= parameter as the
                    maximum limit; user logging uses this specified
                    number as a minimum.

numrec              The maximum number of logical records in a new file.
                    The maximum for fixed and undefined length records
                    is 2,147,483,647. The default is 1023.

NOTE


The file system uses these values to compute other characteristics of
the file as well.  Therefore, the values (or default values) specified
on the BUILD command may be valid within their respective fields, but
may cause overflow errors in the computation of internally needed file
specifications.

numextents          Maximum number of disk extents.  This is a value
                    of -1, or a value from 1 to 32.  The default is 8.
                    Specifying a value of -1 tells MPE/iX to use the
                    default value.

initialloc          Number of extents to be initially allocated to the
                    file at the time it is opened.  This is a value from
                    1 to 32. Default is 0.  You may use the value -1
                    for this parameter.  It causes the default value
                    to be used.

RIO or NORIO        RIO creates a relative I/O file, which is a special
                    file access method primarily used by COBOLII
                    programs.  You can, however, access these files from
                    programs written in any language.  Specifying RIO
                    implicitly changes the record length parameter to F,
                    or fixed record length.  The default, NORIO, creates
                    a nonrelative I/O file.

                    RIO and NORIO specifications affect only the
                    physical characteristics of the file.  If NOBUF is
                    specified in the FILE command, the file will be
                    accessed in non-RIO mode; otherwise, RIO access is
                    used with RIO files.  Special operations on RIO
                    files, such as replicating a RIO file, uses NOBUF
                    access.  Refer to the MPE/iX Intrinsics Reference
                    Manual (32650-90028) for a discussion of relative
                    I/O.

STD, MSG, CIR,      Defines the type of file.  The default, STD, is a
KSAMXL, OR SPOOL    standard MPE/iX disk file.  A MSG, or message, file
                    allows communication between any set of processes in
                    a first in, first out (FIFO) manner.  Records are
                    read from the start of the file and logically
                    deleted and/or are appended to the end of the file.
                    A CIR, or circular, file acts as a normal sequential
                    file until full.  When full, the first physical
                    block is deleted when the next record is written,
                    and remaining blocks are logically shifted to the
                    front of the file.  A circular file cannot be
                    simultaneously accessed by readers and writers.

                    KSAMXL specified a native mode KSAM file (KSAM/XL
                    file).  SPOOL specifies an output spoolfile.  The
                    default OUTPRI on the file is 8; the default number
                    of copies is 1; the default device is as configured
                    in Sysgen.

NUMLABELS           The number of user label records to be created for
                    the new file.  Up to 255 labels can be specified.
                    This parameter applies to any type of file.

^FILEREFERENCE2 or  FILEREFERENCE2 is a file containing KEYINFO.
KEYINFO             This parameter only applies to, and is required for,
                    new KSAM files.  The "^" means that the contents of
                    the file will be used.

                    KEYINFO has the following format:

                      ;KEY=(KEYTYPE,KEYLOCATION,KEYSIZE[{,DUP }]
                                                        {,RDUP}
                                   .
                                   .
                                   .
                           ;KEYTYPE,KEYLOCATION,KEYSIZE[{,DUP }]
                                                        {,RDUP}
                            )

                    One key specification (KEYTYPE, KEYLOCATION,
                    KEYSIZE, [DUP OR RDUP]) must be included for each
                    key in the KSAM file.  The first occurrence of the
                    key specification describes the primary key; each
                    subsequent key specification describes an alternate
                    key.  There may be up to 15 alternate key
                    specifications in addition to the primary key
                    description.

KEYTYPE             KSAM XL key type, specified as BYTE, INTEGER, REAL,
                    IEEEREAL, NUMERIC, PACKED, or *PACKED.  The whole
                    word or only the first letter need be specified.
                    Valid abbreviations are B, I, R, E, N, P, and *,
                    respectively.  If more than one letter is specified,
                    the word must be spelled correctly.

KEYLOCATION         Location of the first byet of the key within the
                    data record counting from the first byte in the
                    record. The first byte in the data record is always
                    numbered 1.  Only one key can start at the same
                    location.  This parameter applies only to KSAM
                    files.

KEYSIZE             Length of the KSAM XL key in bytes.  The length
                    depends on keytypes as follows:

                        BYTE      1 TO 255 BYTES
                        INTEGER   1 TO 255 BYTES
                        REAL      1 TO 255 BYTES
                        IEEEREAL  4, 8, OR 16 BYTES
                        NUMERIC   1 TO 28 BYES
                        PACKED    1 TO 14 BYTES (ODD NUMBER OF DIGITS)
                        *PACKED   2 TO 14 BYTES (EVEN NUMBER OF DIGITS)

                    This parameter is required for all key types.

DUP or RDUP         These two options apply only to KSAM XL files. The
                    DUP option allows the user to specify that duplicate
                    key values are permitted.  If DUP is not specified,
                    records with duplicate key values are rejected and
                    an error message results when such records are
                    written to the file.  When the DUP option is used,
                    each new duplicate key is inserted at the end of the
                    duplicate key chain.  This maintains the
                    chronological order of duplicate keys.

                    The RDUP option specifies that duplicate keys are
                    allowed and are to be inserted randomly in the
                    duplicate key chain.  This method makes insertion of
                    such keys faster, but does not maintain the
                    chronological order of the duplicate key chain.

                    The default is that duplicate keys are not allowed.

RECNUM              Determines whether record numbers in the new KSAM
                    data file are to start with zero or one.  If the
                    integer 1 is specified, then records are numbered
                    beginning with 1; otherwise they will start with 0.
                    The only acceptable values of RECNUM are 1 and 0.

                    The default is record numbering starting with zero.

;REUSE or ;NOREUSE  The REUSE option forces KSAM XL files to reuse
                    deleted record space.  All records are assigned to
                    the first available space.  The REUSE option forces
                    the RDUP flags to be set to TRUE.

                    If the NOREUSE option is used, deleted record space
                    will not be reused.  The default is NOREUSE.

                    This option can only be used for KSAM XL files.

LANGID              An integer number indicating the native language of
                    the KSAM file to be built.  The default is 0, or
                    NATIVE-3000.  The language must be currently
                    configured on the system.

LANGNAME            The name indicating the native language for the KSAM
                    file to be built.  The default language is NATIVE-
                    3000.  The language must be currently configured on
                    the system. See the native language documentation
                    for more information.

;Defblk or ;Optmblk These two options apply only to KSAM XL files.
                    DEFBLK specifies that the data block size will be
                    the default data block size of 4096 bytes.
                    OPTMBLK specifies that KSAM XL will select the
                    optimal data block size based on the record size.

                    The default is DEFBLK


OPERATION


     This command builds a new file on disk.  If it is an ASCII
     file, the file space is initialized to blanks.  If it is a
     binary file, the file space is initialized to zeros.

     Unless the TEMP parameter is specified, the file is saved in
     the permanent file domain.  To create a permanent file, you
     must have SF (Save Files) capability and save access to the
     group to which the new file will belong.  You can only build
     a file belonging to your logon account.

     If specified, the ;DEV= parameter must be consistent with
     the group to which the new file will belong.  If the group's
     home volume set is not mounted, BUILD will implicitly
     generate a volume set reservation request.  If the volume is
     not recognized by the system, the command will fail.  Volume
     Management (32650-90045).

     The default characteristics of a file created with the
     BUILD command are fixed length records of 128 words each,
     a blocking factor of 1, binary formatted, permanent file, a
     record limit of 1023, and a maximum of 8 extents with 0
     extent initially allocated.  This is equivalent to entering

     BUILD FILENAME;REC=128,1,F,BINARY;DEV=DISC;DISC=1023,8,0


NOTE:


     The characteristics of a file created with the SPOOL keyword
     are:

     o variable-length records of 1008 bytes each

     o a blocking factor of 1

     o ASCII format

     o permanent file

     o record limit of 1023

     o undefined maximum number of extents with 0 extents initially
       allocated


     These characteristics override any other characteristics, such
     as BINARY format, which may be specified.




EXAMPLE(S)


     The following example creates a permanent disk file named
     workfile, which can reside on any disk.  Workfile has fixed
     length records of 80 bytes each.  The records are blocked 3
     records per block (which is the blockfactor), and are
     written in ASCII code.  The file has a maximum capacity of
     2000 records divided into 10 extents with 2 extents
     allocated immediately.

     BUILD WORKFILE;REC=-80,3,F,ASCII;DISC=2000,10,2

     The second example uses the BUILD command to create a
     permanent disk file, named VFILE, belonging to the logon
     (default) group that resides in the volume class specified
     by VCLASS1

     BUILD VFILE;DISC=500,10,1;REC=-80;DEV=VCLASS1

     ** VCLASS1 IS THE NAME OF EXISTING VOLUME CLASS. **

     The following example uses the CODE= parameter to create a
     logging file called NEWDATA

     BUILD NEWDATA;DISC=3000,1,1;CODE=LOG


ADDITIONAL INFORMATION


COMMANDS:    LISTF, LISTFTEMP, PURGE, RENAME, COPY, NEWLINK, FILE

MANUALS  :   Performing System Operation Tasks (32650-90137)
             MPE/iX Intrinsics Reference Manual (32650-90028)

Back to Main Index