Generated from C.65.00 /SYSADMIN/PUB/MYCICAT last modified on Sun Aug 29 15:08:37 2004
Creates and immediately allocates a new empty file on disk. (CM)
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}
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.
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, MSG, CIR, Defines the type of file. The default, STD, is a KSAMXL, SPOOL, standard MPE/iX disk file. A MSG, or message, file OR KSAM64 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. 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
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
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.
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
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