BUILD



BUILD

     Creates and immediately allocates a new empty file on disk. (CM)

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 }
{;KSAM64 }

[;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.

A complete summary of all filecodes can be found
under filecode.

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.

The combination of record size, blocking factor, maximum number of
records, record and file type is taken together to determine the
maximum size of a file. The following table lists the maximum file
sizes for different types of files:

File Type Maximum Bytes

Byte stream record files ....................... 2,147,483,647
Standard, fixed length record files ............ 137,438,953,472
KSAM64 files ................................... 137,438,953,472
All other files ................................ 4,294,901,760

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, Defines the type of file. The default, STD, is a
standard MPE/iX disk file.

MSG 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.

CIR 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 KSAMXL specified a native mode KSAM file (KSAM/XL file).

SPOOL 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.

KSAM64 KSAM64 specifies a KSAM file that is capable of
supporting file sizes beyond 4GB, but is in every
other way identical to a KSAMXL file. All BUILD
command parameters that refer to KSAM or KSAMXL
files also apply to KSAM64 files.

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 or KSAM64 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 or KSAM64 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 and KSAM64
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 and KSAM64 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 and KSAM64
files. DEFBLK specifies that the data block size
will be the default data block size of 4096 bytes.
OPTMBLK specifies that the OS 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)