HP 3000 Manuals HP 3000 Manuals
BUILD
Creates and immediately allocates a new empty file on disk.
Syntax
[ [ [ [ [F] ]]]]
BUILD filereference [;REC=[[recsize][,[blockfactor][,[U][,BINARY]]]]]
[ [ [ [ [V][,ASCII ]]]]]
[ [ [ [ [B] ]]]]
[ [dsdevice# ]]
[;CCTL ] [;TEMP] [;DEV= [dsdevice#device]] [;CODE=filecode]
[;NOCCTL] [ [device ]]
[;MSG ]
[;CIR ]
BUILD[;DISC=[[numrec][,[numextents][,initialloc]]]] [;RIO ] [;STD ]
[;NORIO] [;KSAMXL]
[;SPOOL ]
[;ULABEL=numlabels] [;KEY={^filereference}] [;FIRSTREC=recnum] [;REUSE ]
[ {keyinfo }] [;NOREUSE]
[;langid={langid }] [{;DEFBLK }]
[ {langname}] [{;OPTMBLK}]
Parameters
filereference Actual name of the file to be created. The
filereference can be either in MPE of 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 length 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 is DISC with 1023
records.
For example, a fixed length ASCII file with a
record size specified as 11 bytes has only 11 bytes
available for data in each logical record.
However, to determine actual block size, 12 bytes
is used for the record size (block size = 12 bytes
multiplied by the blockfactor). If the file is
specified as a binary file, the 11 bytes are
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), 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 is created as a temporary
file and is 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 delimiter
between the file name of the remote computer and
the remote device file name.
device Either the devclass or ldev on which the file is to
reside. A device class name (devclass), such as
DISC consists of up to eight alphanumeric
characters beginning with an alphabetic character.
The DEV= parameter does not accept device names,
volume classes, or volume names. 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 that 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 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 a 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 length and undefined
length records is 2,147,483,647. The default is
1023.
numextents Maximum number of disk extents. You may specify a
value of -1, or any number from 1 to 32. Default
is 8.
initialloc Number of extents to be initially allocated to the
file at the time that it is opened. If you specify
-1 for this parameter, the default value is 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 length record. 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 is not
accessed in RIO mode; otherwise, RIO access is used
with RIO files. Special operations on RIO files,
such as replicating an RIO file, set NOBUF access.
Refer to the Accessing Files Programmer's Guide
(32650-60010) for a discussion of relative I/O.
STD, MSG, CIR, Defines the type of file.
KSAMXL, SPOOL
The default is STD (standard MPE/iX disk file).
You do not need to specify STD; in fact, if you do
specify it, you will see the error message The STD
keyword is not appropriate in the context of a
BUILD command. (CIERR 216).
A MSG (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 are logically deleted and/or are
appended to the end of the file.
CIR (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 specifies a native mode KSAM file (KSAM XL
file).
SPOOL specifies an unlinked output spool file. The
default outpri on the spool file is 8; the default
number of copies is 1. The unlinked output spool
file must be created on a disk device. Specify the
target printer device at SPOOLF...;PRINT time; if
you do not, an error results.
The characteristics of a file created with the
SPOOL keyword are:
* variable length records of 1008 bytes each
* a blocking factor of 1
* ASCII format
* permanent file
* record limit of 1023
* undefined maximum number of extents with 0
extents initially allocated
These characteristics override any other
characteristics, such as binary format, which may
be specified.
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.
^filereference or filereference is a file containing key information.
keyinfo This parameter only applies to new KSAM files; it
is required for new KSAM files. The caret (^)
indicates 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|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 key type, specified as BYTE, INTEGER, REAL,
IEEEREAL, NUMERIC, PACKED, OR *PACKED. Specify the
whole word or only the first letter; valid
abbreviations are B, I, R, E, N, P, and *. If more
than one letter is specified, the word must be
spelled correctly.
keylocation Location of the first byte 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 key in bytes. The length
depends on keytype 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 bytes
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 files. The
DUP option allows you to specify that duplicate key
values are permitted. If DUP is not specified,
records with duplicate key values are rejected and
an error message is issued 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 the duplicate keys.
The RDUP option specifies that duplicate keys are
allowed and 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
file are to start with zero or one. If the integer
1 is specified, records are numbered beginning with
1; otherwise, they start with 0. The only
acceptable values for recnum are 1 and 0. This
option can only be used for new KSAM files.
REUSE or NOREUSE The REUSE option forces KSAM files to reuse deleted
record space. The REUSE option forces RDUP to be
set to TRUE for all keys.
If the NOREUSE option is used, deleted record space
is not reused. If the DUP option is specified for
a key, duplicate records are placed chronologically
at the tail end of the file. The default is
NOREUSE.
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. See the Native Language
documentation for more information.
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 files. DEFBLK
specifies that the data block size will be the
default data block size of 4096 bytes. OPTMBLK
specifies that KSAMXL will select the optional data
block size based on the record size. The default
is DEFBLK.
NOTE The file system uses the values specified on the BUILD command line
to compute other characteristics of the file. Therefore, the
values (or default values) may be valid within their respective
fields, but may cause overflow errors in the computation of
internally needed file specifications.
Operation Notes
This command builds a new file on disk. If it is an ASCII file, the
initially allocated 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 save
file (SF) capability and SAVE access in the group to which the new file
belongs. 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 belongs. If the group's home volume set is not
mounted, BUILD implicitly generates a volume set reservation request. If
the volume is not recognized by the system, the command fails. Refer to
Volume Management Reference Manual (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,
Use
This command may be issued from a session, a job, a program, or in break
mode. Pressing Break has no effect on this command.
Examples
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 initially
allocated.
BUILD WORKFILE;REC=-80,3,F,ASCII;DISC=2000,10,2
The following example uses the CODE= parameter to create a logging file
called NEWDATA:
BUILD NEWDATA;DISC=3000,1,1;CODE=LOG
Related Information
Commands COPY, LISTFILE, LISTF, LISTFTEMP, PURGE, RENAME
Manuals MPE/iX Intrinsics Reference Manual (32650-90028)
Native Mode Spooler Reference Manual (32650-90166)