HP 3000 Manuals HP 3000 Manuals
BUILD
Creates a KSAM file.
> B
BUILD filereference 1 F ,BINARY
[;REC=[recsize] [,[blockfactor] [, V ] ] ]
,ASCII
[;TEMP]
[;DEV=device]
[;CODE=filecode]
[;DISC=[numrec] [,[numextents] [,initialloc] ] ]
;KEYENTITY =filereference 2
,DUPLICATE
,DUP
;KEY=keytype, keylocation, keysize[,[keyblocking] ,RDUPLICATE
,RDUP
,DUPLICATE
;KEY=keytype, keylocation, keysize[,[keyblocking] ,DUP
,RDUPLICATE
,RDUP
[;KEYENTRIES=numentries]
[;LABELS=numlabels]
[;KEYDEV=device]
[;FIRSTREC=recnum]
[;LANG=parameter]
[;NODUPLOCKS]
The BUILD command of the KSAMUTIL utility program is used to create a
KSAM file and allocate the file to a mass storage device. Although this
command is similar to the MPE :BUILD command, it has been modified for
KSAM files. You can specify the BUILD command with the abbreviation, B.
NOTE You cannot create a KSAM file with the MPE :BUILD command.
If you are programming in COBOL, BASIC, or RPG, you must use the KSAMUTIL
BUILD command to create a KSAM file; in SPL or FORTRAN, you can create a
KSAM file either with the BUILD command or with the FOPEN intrinsic
(described in section IV).
PARAMETERS
filereference1 Actual file designator. This is the name that
identifies the KSAM file (both data and key files) and
also identifies the data file when specified
independently of the key file. It has the form:
filename [/lockword] [.groupname [.accountname] ]
All four sub-parameters are names that contain from 1 to
8 alphanumeric characters, beginning with a letter.
_______________________________________________________
NOTE If specified, account name must be that of your
log-on account; you cannot create a file in
another account.
_______________________________________________________
If file has no lockword and belongs to your log-on
group, only filename is necessary. You cannot
backreference files.
(Required parameter.)
REC=recsize Size of logical records in file. If a positive number,
this represents words; characters are represented by a
negative number, If the records are variable length,
recsize indicates the maximum length allowed for a
logical record.
Block size is determined by multiplying the specified
recsize by blockfactor. For binary files or ASCII files
with fixed-length records, an odd character count is
rounded up to the next highest even number to insure
that the record starts on a word boundary. The rounded
number should be used in calculating block size since a
block always starts on a word boundary.
(Optional parameter.)
Default: The configured record size of the particular
device is used when recsize is omitted; for disc files,
the value used is 256 characters or 128 words.
blockfactor An integer equal to the number of logical data records
in each block. This integer should result in a data
block size smaller than 4096 (4K) words. The
blockfactor is used to calculate the buffer size
established for transfer of data to and from the file.
For fixed-length records, blockfactor is the actual
number of records in a block. For variable-length
records, blockfactor is a multiplier used with recsize
to calculate block size:
block size = ( (recsize+1) * blockfactor)+1
The calculation is performed in words, not characters.
(Optional parameter.)
Default: calculated by dividing the specified recsize
into the configured block size; the result is rounded
down to an integer never less than 1.
F Data file contains fixed-length records.
(Optional parameter.)
V Data file contains variable-length records. Since KSAM
performs its own blocking and deblocking, a KSAM data
file specified as variablelength is treated by MPE as a
file with fixed-length records, each record the size of
a KSAM block (refer to blockfactor above for calculation
of block size). Although the MPE LISTF command shows
the data file as fixed-length, the KSAMUTIL VERIFY
command, option 3, shows DATA FIXED as FALSE when the
file is a variable-length KSAM file.
(Optional parameter.)
Default: If both F and V are omitted, records are
fixed-length.
BINARY Data file contains binary-coded records.
(Optional parameter.)
ASCII Data file contains ASCII-coded records.
(Optional parameters.)
Default: If both BINARY and ASCH are omitted, records
are binary.
TEMP File is created as a session/job temporary file; when
the session or job terminates, the file is deleted from
the session/job temporary file directory.
(Optional parameter.)
Default: If TEMP is omitted, file is declared permanent
and is saved in the system file domain.
DEV=device device designates the device on which the data file
resides. (The key file device is specified in the
KEYDEV parameter.) device can be specified as a device
class name of up to 8 alphanumeric characters beginning
with a letter and terminated by any non-alphanumeric
character such as a blank, or as a logical device number
consisting of a three-character numeric string, or it
can be a remote device identifier consisting of the
device class name or logical device number followed by a
pound sign (#) and a remote device class name or logical
device number.
Device class names and logical device numbers are
assigned to devices during system configuration. (See
System Manager/System Supervisor Reference Manual).
For KSAM files, the device must be a random access
device such as the disc. If the file is a newly-created
disc file specified as a device class name, then all
extents to the file must be members of the same class.
Similarly, if the device is identified by a logical
device number then all extents must have the same
logical device number.
(Optional parameter.)
Default: If omitted, the device class name DISC is
used.
CODE= filecode Code indicates that the data file is specially
formatted. The code is recorded in the file label and
is available to processes through the FGETINFO
intrinsic. It must be specified as a positive integer
in the range 0 through 1023.
(Optional parameter.)
Default: If CODE is omitted, the file code is 0.
_______________________________________________________
NOTE The CODE parameter applies only to data files; the
key file code value is always 1080.
_______________________________________________________
DISC=numrec Total maximum file capacity, in terms of logical records
(for files containing fixed-length records). For files
containing variable-length records, this is the maximum
file capacity if all the records are maximum length.
Maximum file capacity allowed is 2,097,120 sectors.
(Optional parameter.)
Default: If omitted, 1024 records is the default.
numextents Number of extents (continguously-located disc sectors)
that can be dynamically allocated to the file as logical
records are written to it. The size of each extent (in
terms of records) is determined by the numrec parameter
value divided by the numextents parameter value.
Extents can allocated on any disc in the device class
specified in the device parameter. If you want to
ensure that all extents for a file reside on the same
disc, use the logical device number of that disc or a
device class name relating to a single disc device, in
the device parameter. If specified, numextents must be
integer value from 1 to 32.
(Optional parameter.)
Default: 8.
initalloc Number of extents to be allocated to the file at the
time it is opened. Must be an integer from 1 to 32. If
attempt to allocate requested space fails, an error
message appears.
(Optional parameter.)
Default: 1.
KEYFILE Actual file designator. This is the name that
=filereference2 identifies the KSAM key file. It has the format:
filename, which is 1-8 alphanumeric characters beginning
with a letter. Unlike filereference1 (the data
filename) filereference2 may not be qualified by account
or group names, nor may it contain a lockword. The key
file contains all the key entries and key control
information, whereas the data file contains the actual
data. A KSAM file is always referenced by the data file
name, filereference1, not the key file name,
filereference2.
(Required parameter.)
KEY= One KEY specification 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 descriptions in addition to
the primary key description.
(Required parameter.)
keytype keytype is specified as BYTE,INTEGER, DOUBLE, REAL,
LONG, NUMERIC, PACKED, or *PACKED. The whole word or
only the first letter need be specified (for example, B
is equivalent to BYTE). If more than the first letter is
used, the word must be spelled correctly. (Refer to
Table 2-2 for a full description of each key type.)
(Required parameter.)
keylocation Location of the first character of the key within the
data record counting from the first character in the
record. The first character in the data record is
always numbered 1. Only one key can start at the same
location. (Required parameter.)
keysize Length of the key in characters. The length depends on
keytype as follows:
BYTE 1 to 255 characters
INTEGER 1 to 255 characters (default = 2)
DOUBLE 1 to 255 characters (default = 4)
REAL 1 to 255 characters (default = 4)
LONG 1 to 255 characters (default = 8)
NUMERIC 1 to 28 characters
PACKED 1 to 14 characters (odd number of
digits)
*PACKED 2 to 14 characters (even number of
digits)
(Required parameter for BYTE, NUMERIC, PACKED, and
*PACKED key types: defaults are provided for INTEGER,
DOUBLE, REAL, and LONG key types, as noted above.)
keyblocking Number of keys per block. The keyblocking value is an
even number greater than or equal to 4. It is used with
the key entry size (keysize paramater) to determine the
size of each key block according to the followign
formula:
5 + (keysize+1) + 4) keyblocking = key block size in words
2
Five words are used for control information in each
block, keysize specified in characters is divided by 2
to get the key size in words, and 4 words are added for
the pointers in each key entry. This key entry size in
words is multiplied by the keyblocking factor to
determine key block size. If the keyblocking value
generates a key block size greater than 2048 (2K) words,
the file cannot be created.
The resulting key block size is rounded up to a multiple
of 128 words. If the file has multiple keys, KSAM
forces all key blocks to the same size and adjusts the
number of keys per block accordingly.
Note that the value you specify for keyblocking may be
increased (never decreased) by the system in order to
produce a blocking factor that does not waste disc
space. Refer to appendix B for a discussion of how the
system determines the most efficient blocking factor
based on the value you enter for keyblocking.
Key blocking can affect access time in that the smaller
the key block, the more time it may take to retrieve a
record using the key file. In many cases, the default
blocking factor produces the most efficient key
blocking.
(Optional parameter.)
Default: key blocking is set to a value that produces a
key block size of 1024 (1K) words. (Maximum size is
2K.)
DUPLICATE DUP In order to allow duplicate key values, this word must
be included in the KEY specification. If DUPLICATE (or
DUP) is not specified, records with duplicate key values
are rejected and an error message issued when such
records are written to the file. DUP is a legal
abbreviation of DUPLICATE. When you use this option to
specify duplicate keys, each new duplicate key is
inserted at the end of the duplicate key chain. This
maintains the chronological order of duplicate keys.
RDUPLICATE RDUP This 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.
(Optional parameter.)
Default: If omitted, duplicate keys are prohibited.
KEYENTRIES= The value of numentries is used to determine the key
numentries file size. The value specified for numentries should be
the maximum number of primary key entries expected.
When there are alternate keys, KSAM automatically
adjusts the key file size to accomodate each key in
addition to the primary key.
Normally, this parameter can be omitted since KSAM
assigns it the value of numrec (number of fixed-length
data records or blocks of variable-length records). If,
however, the data records are variable length and there
are many small records, the value of numrec may be too
small. In this case, you should specify a value for
numentries greater than the value of numrec.
The number of key entries determines the size of the key
file, the file limit. When a new KSAM file is created,
the MPE end-of-file marker is set to this file limit
rather than to the end-of-data as is normal for MPE
files. This allows any key block to be accessed in case
of system failure. To determine where the actual
end-of-data is, use the KSAMUTIL VERIFY command, option
3, and look at the heading KEY FILE EOF. This shows the
record number of the next available key block (one
record past the last used key block).
(Optional parameter.)
Default: the value of numrec in the DISC= parameter or
its default value 1024 if it too is omitted.
LABELS= The number of user label records to be created for the
numlabels KSAM data file. Up to 254 labels (1 less than the MPE
maximum) can be specified; COBOL programmers are
restricted to 8 labels.
(Optional parameter.)
Default: if omitted, numlabels is equal 0.
KEYDEV=device The device on which the key file resides, specified as a
device class name or a logical device number. A device
class name indicates the general type of the device as a
string of one to eight alphanumeric characters beginning
with a letter and terminated by a non-alphanumeric
character such as a blank. The logical device number is
the threecharacter numeric string identifying a
particular device. If the data file is created on a
remote device, the key file is assigned to the same
machine, and the key file device is specified in the
KEYDEV= parameter.
Device class names and logical device numbers are
assigned to devices during system configuration.
For KSAM files, the device must be a random-access
device such as the disc.
(Optional parameter.)
Default: If omitted, the device class name DISC is
used.
FIRSTREC= Determines whether record numbers in the data file are
recnum 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 for recnum are 1 and 0.
Normally, record numbering in MPE files starts with
zero, the default value for recnum. In order to be
consistent with most commercial applications, you can
specify FIRSTREC=1 to change the record numbering scheme
so that data records are numbered starting with 1.
(Optional parameter.)
Default: if omitted, record numbering starts with zero.
LANG= parameter The name or identification number of the language to use
in determining the key sequence. The language specified
by parameter must be installed on the system. See
Appendix F for detailed information on using Native
Language Support (NLS) with KSAM files.
(Optional parameter.)
Default: if omitted, NATIVE-3000 is used.
NODUP LOCKS Prevents duplicate file locks ftom the same process.
NODUPLOCKS controls "Lock" access to a KSAM file. Each
time a process opens a file more than once and locks the
file through a different open path, KSAM checks the
file's lock access. If NODUPLOCKS was specified when
the file was created, the process is not allowed to lock
the file more than once. File locks from the same open
path are always allowed.
(Optional parameter)
Default: if omitted, duplicate file locks from the same
process are allowed.
KEY DESCRIPTION
Each key is described by specifying key type, key position, key size,
and, optionally, the blocking factor and whether duplicates are allowed.
Key type and size are defined in Table 2-2. Note that default values are
provided for keysize when key type is specified as INTEGER, DOUBLE, REAL,
or LONG. Only BYTE,INTEGER, and DOUBLE type keys can be used as generic
keys.
Table 2-2. Key Types
----------------------------------------------------------------------------------------------
| | | |
| keytype | keysize | Format |
| | (In Characters) | |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| BYTE | 1-255 | Each character requires 8 bits of a computer word. |
| | | A character may contain any of the HP ASCII |
| | | character set consisting of letters of the |
| | | alphabet, numbers, and special characters. (Refer |
| | | to appendix C.) |
| | | |
| INTEGER | 1-255 (default = 2) | Single-word fixed-point format permits two's |
| | | complement representation of positive and negative |
| | | integers. Bit 0 is a sign bit and the remaining 15 |
| | | bits define a quantity ranging from -32768 through |
| | | +32767. |
| | | |
| DOUBLE | 1-255 (default = 4) | Double-word fixed-point format is the same as the |
| | | integer format except that two words are linked |
| | | together to allow a 32-bit quantity with a range |
| | | between approximately -2 billion and +2 billion. |
| | | |
| REAL | 1-255 (default = 4) | Floating-point format with bit zero as a sign bit, |
| | | an exponent (biased by +256) in bits 1 through 9, |
| | | and a positive fraction in the remaining 22 bits of |
| | | the double word. This type cannot be used as a |
| | | generic key. |
| | | |
| LONG | 1-255 (default = 8) | Long floating-point format uses four words; an |
| | | exponent (biased by +256) in bits 1-9, as with the |
| | | real number, and a positive fraction in the |
| | | remaining 54 bits. This type cannot be used as a |
| | | generic key. |
| | | |
| NUMERIC | 1-28 | External decimal format in which each decimal digit |
| | | requires one 8-bit character and the sign is |
| | | combined with the least significant digit. (Refer |
| | | to Table 2-3 for the list of characters |
| | | representing the digit/sign combinations.) This |
| | | type cannot be used as a generic key. |
| | | |
| PACKED | 1-14 | Packed decimal format in which each digit requires |
| | | only 4 bits and the sign is specified as a |
| | | hexadecimal number in the least significant 4 bits |
| | | (1100 or C is plus and 1101 or D is minus). This |
| | | type cannot be used as a generic key. |
| | | |
| *PACKED | 2-14 | Same as PACKED except this key type contains an |
| | | even number of digits. This type cannot be used as |
| | | a generic key, |
| | | |
----------------------------------------------------------------------------------------------
Table 2-3. Character Equivalent to Signed Digit for NUMERIC Keys
-------------------------------------------------------------------------------------------------
| | | | |
| POSITIVE | POSITIVE | NEGATIVE | NEGATIVE |
| VALUES | VALUES | VALUES | VALUES |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| SIGNED DIGIT | CHARACTER | SIGNED DIGIT | CHARACTER |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| +0 | { | -0 | } |
| | | | |
| +1 | A | -1 | J |
| | | | |
| +2 | B | -2 | K |
| | | | |
| +3 | C | -3 | L |
| | | | |
| +4 | D | -4 | M |
| | | | |
| +5 | E | -5 | N |
| | | | |
| +6 | F | -6 | O |
| | | | |
| +7 | G | -7 | P |
| | | | |
| +8 | H | -8 | Q |
| | | | |
| +9 | I | -9 | R |
| | | | |
-------------------------------------------------------------------------------------------------
CREATING A KSAM FILE
Creating a KSAM file with the KSAMUTIL BUILD command is very similar to
creating a standard HP 3000 file with the MPE command :BUILD except that
a KSAM file includes a key file description. As with standard files, the
default values can be assumed for many of the file description
parameters.
To create a KSAM file from the KSAMUTIL program, you can start by simply
naming the file as the first parameter of the BUILD command. The file
name defines the data file portion of the KSAM file with the default
options: fixed-length, 128-word, binary-coded records, blocked 1 record
per block.
To fully define a KSAM file, you must also:
* name the key file
* define at least one key (the primary key) in terms of:
type
location in the data file
size
These parameters provide your minimum KSAM file description from which
the file can be created. To illustrate:
:RUN KSAMUTIL.PUB.SYS
>BUILD KSAMFILE;KEYENTITY =KFILE;KEY=I,21,2
This command assigns the name KSAMFILE to the KSAM data file; it names
the key file KFILE, and defines the primary key as an integer that starts
in character 21 of the record, and is two characters long. By default,
the blocking factor of the keyfile provides key blocks 1024 words long,
the maximum number of primary keys is set to 1023 (the same as the
maximum number of data records), duplicate keys are prohibited, and
record numbering starts with zero.
File KSAMFILE is now created. Default values were used where possible so
that the BUILD command specification shown above is the minimum needed to
create a KSAM file. You could create the same file, KSAMFILE, with the
following BUILD command in which default parameters are specified.
recsize
|
>BUILD KSAMFILE;REC=128,,F,BINARY& <------ line continuation character
> ;DEV=DISC&
> ;CODE=0&
> ;LABELS=0& |-------- numextents
> ;FIRSTREC=0&||--- initialloc
> ;DISC=1023,8,1&
^---- numrec
> ;KEYFILE=KFILE> ;KEY= I,21,2& <------ key description
> ;KEYENTRIES=1023&
> ;KEYDEV=DISC |
|
numentries
This specification of the BUILD command, although initially more
cumbersome, documents the default values with which the file is created.
Since the default keyblocking factor is a value calculated from the key
size so that each key block is 1K words long, it is not specified here.
You can use the VERIFY command to find the value KSAM has assigned as a
key blocking factor for any file you create using a default for this
value.
Only a primary key is defined for this file. Within the data file, this
key is an integer that occupies characters 21 and 22 (word 11) of each
data record.
![[]](../../pic3k/M010088/F0201B3c50.gif)
In the key file, the values in any key are ordered sequentially so that
the next higher value can always be located. The key should not begin in
the first two characters of the data record since these characters are
set to all 1's when the record is deleted. If the key value of deleted
records need never be recovered, then this restriction can be ignored.
For each alternate key in addition to the primary key, another KEY=
clause must be included. Suppose a personnel file with a primary key
containing an employee number, an alternate key containing a name, and
another alternate key containing the person's age. The first two keys
are specified as BYTE keys, the third is an INTEGER. The key file is
blocked with 10 keys per block and the maximum number of primary keys
expected is 3000:
:RUN KSAMUTIL.PUB.SYS
>BUILD EMPLOYEE;REC=,,,ASCII;KEYENTITY =EMPKEY;KEYENTRIES=3000;&
> KEY=B,3,11,10;&<---------- primary key (employee number)
> KEY=B,15,30,10;&<--------- alternate key (employee name)
> KEY=I,51,2,10&<------------ alternate key (employee age)
The keys are located in the data record as follows:
![[]](../../pic3k/M010088/F0201C3c50.gif)
Note that the keys need not be contiguous. In this example, the primary
key is located nearer to the beginning of the record than the other keys.
This is not a requirement; the primary key can physically follow any
alternate keys in the record, although the primary key is always the
first key specified in the BUILD command. For example, in the file
FSAMPLE, the primary key starts in character 21 following a secondary key
in character 3:
![[]](../../pic3k/M010088/F0201D3c50.gif)