BUILD

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 of the form

   path/filename

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

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

Maximum number of disk extents. You may specify a value of -1, or any number from 1 to 32. Default is 8.

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 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 for a discussion of relative I/O.

Defines the type of file.

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:

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

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 is a file containing key information. 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

COPY, LISTFILE, LISTF, LISTFTEMP, PURGE, RENAME

MPE/iX Intrinsics Reference Manual

Native Mode Spooler Reference Manual