Document revision date: 30 March 2001

## OpenVMS Record Management Services Reference Manual

Previous | Contents | Index

Table RMS-4 lists the control block fields written as output by the Connect service.

Table RMS-4 Connect Service RAB Output Fields
Field Name | Description
--- | ---
RAB$W_ISI | Internal stream identifier
RAB$L_STS | Completion status code (also returned in Register 0)
RAB$L_STV | Status value

### Condition Values Returned

> The following condition values can be returned. Use the Help Message utility to access online message descriptions. For more information about interpreting condition values, see Section 2.4.

RMS$_ACT | RMS$_BLN | RMS$_BUG_DAP
RMS$_CCR | RMS$_CDA | RMS$_CRMP
RMS$_DME | RMS$_EXT_ERR | RMS$_EXTNOTFOU
RMS$_FAB | RMS$_GBC | RMS$_IAL
RMS$_IFA | RMS$_IFI | RMS$_KRF
RMS$_MBC | RMS$_NET | RMS$_NETFAIL
RMS$_NORMAL | RMS$_OPNOTSUP | RMS$_PENDING
RMS$_RAB | RMS$_RFM | RMS$_ROP
RMS$_RPL | RMS$_STR | RMS$_SUC
RMS$_SUP | RMS$_SUPPORT |

## $CREATE

> The Create service constructs a new file according to the attributes you specify in the FAB. If any XABs are chained to the FAB, then the characteristics described in the XABs are applied to the file. This service performs implicit Open and Display services.

### Format

> SYS$CREATE fab [,[err] [,suc]]

### RETURNS

> OpenVMS usage: | cond_value
> type: | longword
> access: | write only
> mechanism: | by value

> The value is returned in symbolic offset FAB$L_STS. Symbolic offset FAB$L_STV may contain additional status information.

### Arguments

> #### fab

> OpenVMS usage: | fab
> type: | longword (unsigned)
> access: | modify
> mechanism: | by reference

> FAB control block whose contents are to be used as indirect arguments for the Create service call. The fab argument is the address of the FAB control block.

> #### err

> OpenVMS usage: | ast_procedure
> type: | procedure value
> access: | call without stack unwinding
> mechanism: | by reference

> AST-level error completion routine that the service invokes if the operation is unsuccessful. The err argument is the address of the entry mask of this user-written completion routine.

> #### suc

> OpenVMS usage: | ast_procedure
> type: | procedure value
> access: | call without stack unwinding
> mechanism: | by reference

> AST-level success completion routine that the service invokes if the operation is successful. The suc argument is the address of the entry mask of this user-written completion routine.

### Description

> The Create service first uses the information from the specified FAB. If an allocation control XAB is present, however, its allocation quantity (XAB$L_ALQ), allocation options (XAB$B_AOP, only for the XAB$V_CTG and XAB$V_CBT options), bucket size (XAB$B_BKZ), and default extension quantity (XAB$W_DEQ) fields are used instead of the corresponding fields of the FAB. When either key definition or allocation XABs are present, they can be grouped in any order. If a name block (NAM) or long name block (NAML) is also connected to the FAB, RMS fills in its fields with information about the created file. The Create service leaves the file opened.

> When a search list logical name is used, the file is placed in the first resultant search list file specification unless the create-if (FAB$V_CIF) option is specified. If you select the FAB$V_CIF option, RMS searches all search list file specifications to locate the file. If it finds the file, RMS opens it rather than create a new file. If RMS does not find the file, it creates a new file using the first resultant search list file specification.

> You do not have to explicitly specify the FAB$V_PUT option when invoking a Create service because write is the default access mode when you create a file.

> Table RMS-5 lists the control block fields read as input by the Create service. For additional information on the fields accessed by this service, see Chapter 4.

> Note If you specify the FAB$V_RWO option as input to the Create service, RMS overwrites the tape beginning with the first file.

> Table RMS-5 Create Service FAB and XAB Input Fields
> Field Name | Option or XAB Type | Description
> --- | --- | ---
> FAB$B_ACMODES |  | File access modes.
> | FAB$V_CHAN_MODE 1 | Assigns the channel access mode by setting either the FAB$V_UFO or the FAB$V_NFS bit in the FAB$L_FOP field (see Section 4.17). If neither bit is set, this field can be used to override the access mode protection for a specified I/O operation. See Section 4.8.
> | FAB$V_LNM_MODE 1 | Specifies the logical name translation access mode.
> FAB$L_ALQ |  | Allocation quantity; ignored if an allocation XAB is present.
> FAB$B_BKS |  | Bucket size; ignored if an allocation XAB is present.
> FAB$W_BLS |  | Block size (applies to magnetic tape only).
> FAB$W_DEQ |  | Default file extension quantity; ignored if an allocation XAB is present.
> FAB$L_DNA |  | Default file specification string address.
> FAB$B_DNS |  | Default file specification string size.
> FAB$B_FAC |  | File access.
> | FAB$V_BIO | Block I/O access to file.
> | FAB$V_BRO | Block or record I/O access to file.
> | FAB$V_DEL | Delete access to file.
> | FAB$V_GET 2 | Read access to file.
> | FAB$V_PUT 2 | Write access to file and explicit file extension.
> | FAB$V_TRN | Truncate access to file.
> | FAB$V_UPD | Update access to file and explicit file extension.
> FAB$L_FNA 3 |  | File specification string address.
> FAB$B_FNS 3 |  | File specification string size.
> FAB$L_FOP |  | File-processing options.
> | FAB$V_ASY | Asynchronous; indicates that the specified task is to be done asynchronously.
> | FAB$V_CBT | Contiguous best try: indicates that the file is to be allocated contiguously on a "best effort" basis. To specify a single extent, use the FAB$V_CTG option.
> | FAB$V_CIF | Create-if: opens a file if it already exists or creates a file if it does not already exist.
> | FAB$V_CTG | Contiguous: indicates that the space for a file is to be allocated contiguously.
> | FAB$V_DFW 1 | Deferred write: writing back to the file from the modified buffer is deferred. Applies to relative and indexed files and sequential files opened for shared access.
> | FAB$V_DLT | Delete: indicates that the file is to be deleted when closed.
> | FAB$V_MXV | Maximize version: indicates that the created file be given the specific version number requested or a version number that is one greater than the highest version number of an existing file.
> | FAB$V_NAM 1 | Name block inputs: indicates that the NAM$W_DID and NAM$T_DVI fields in the specified NAM block are used as input.
> | FAB$V_NFS 1 | Non-file-structured: indicates that the accessed volume is to be processed in a non-file-structured manner.
> | FAB$V_OFP | Output file parse: specifies that the resultant file specification string of the related file, if used, is to provide file name and file type defaults only.
> | FAB$V_POS | Current position (applies to magnetic tapes only).
> | FAB$V_RCK | Read-check: indicates that transfers from disk are to be followed by a read-compare operation.
> | FAB$V_RWC | Rewind on close (applies to magnetic tape only).
> | FAB$V_RWO | Rewind on open (applies to magnetic tape only).
> | FAB$V_SCF | Submit command file: indicates that the file is to be submitted as a batch-command file to the process default batch queue (SYS$BATCH) when the file is closed (applies to sequential files only).
> | FAB$V_SPL | Spool: indicates that the file is to be spooled to the process default print queue (SYS$PRINT) when the file is closed (applies to sequential files only).
> | FAB$V_SQO | Sequential only: indicates that the file can be processed in a sequential manner only, usually to enable DECnet for OpenVMS file transfer.
> | FAB$V_SUP | Supersede: allows an existing file to be superseded by a new file of the same name, type, and version.
> | FAB$V_TEF | Truncate at end of file: indicates that the unused space allocated to a file is deallocated when that file is closed (applies to sequential files only).
> | FAB$V_TMD | Temporary marked for delete: indicates that a temporary file is to be created, and then deleted when the file is closed.
> | FAB$V_TMP | Temporary: indicates that a temporary file is to be created and retained, but no directory entry is made for this file.
> | FAB$V_UFO 1 | User file open: indicates that the file is to be created or opened only (no further processing of that file is allowed).
> | FAB$V_WCK | Write-check: indicates that transfers to disk are to be followed by a read-compare operation.
> FAB$B_FSZ |  | Fixed control area size.
> FAB$W_GBC 1 |  | Global buffer count for shared files.
> FAB$W_IFI |  | Internal file identifier (must be 0).
> FAB$L_MRN |  | Maximum record number (applies to relative files only).
> FAB$W_MRS |  | Maximum record size.
> FAB$L_NAM 4 |  | NAM or NAML block address.
> FAB$B_ORG |  | File organization: sequential (FAB$C_SEQ 2), relative (FAB$C_REL), or indexed (FAB$C_IDX).
> FAB$B_RAT |  | Record attributes.
> FAB$B_RFM |  | Record format: fixed-length (FAB$C_FIX), variable-length (FAB$C_VAR), VFC (FAB$C_VFC), stream (FAB$C_STM), stream with line feed terminator (FAB$C_STMLF), stream with carriage return terminator (FAB$C_STMCR), or unidentified format (FAB$C_UDF 2).
> FAB$B_RTV 1 |  | Retrieval window size.
> FAB$B_SHR |  | File sharing.
> | FAB$V_SHRDEL | Allows other users to delete records from the file.
> | FAB$V_SHRGET | Allows other users to read the file; also used with the FAB$V_MSE and FAB$V_GET bits to specify a read-only global buffer cache when global buffering is enabled.
> | FAB$V_MSE 1 | Allows multistream access.
> | FAB$V_NIL | Prohibits any type of file sharing by other users.
> | FAB$V_SHRPUT | Allows other users to write records to the file and extend it.
> | FAB$V_SHRUPD | Allows other users to update records in the file and extend it.
> | FAB$V_UPI | Allows one or more users write access to a shared file open for block I/O (applies to sequential files only).
> FAB$L_XAB |  | Extended attribute block address.
> | XABALL | Allocation XAB; see Chapter 9.
> | XABDAT | Date and time XAB; see Chapter 10.
> | XABFHC | File header characteristics XAB; see Chapter 11.
> | XABITM | Item list XAB; see Chapter 12.
> | XABKEY | Key definition XAB; see Chapter 14.
> | XABPRO | Protection XAB; see Chapter 15.
> | XABRDT | Revision date and time XAB; see Chapter 16.
> | XABSUM | Summary XAB; see Chapter 18.

1This field is not supported for DECnet for OpenVMS operations.
2These are the default values supplied by RMS.
3These fields must be specified unless you select the FAB$V_TMD or the FAB$V_TMP option.
4FAB$L_NAL is available as an alternative definition for C programmers to allow for appropriate type checking of a NAML block.

Table RMS-6 lists the control block fields written as output by the Create service.

Table RMS-6 Create Service FAB and XAB Output Fields
Field Name | Option or XAB Type | Description
--- | --- | ---
FAB$L_ALQ |  | Allocation quantity: contains actual number of blocks allocated.
FAB$B_BKS |  | Bucket size: applies only to relative and indexed files. When multiple areas are defined for an indexed file, the largest bucket size is returned.
FAB$W_BLS |  | Device block size (applies to files of sequential organization only).
FAB$W_DEQ |  | Default file extension quantity.
FAB$L_DEV |  | Device characteristics.
FAB$B_FAC |  | File access.
FAB$B_FSZ |  | Fixed-length control area size for VFC format.
FAB$W_GBC |  | Global buffer count.
FAB$W_IFI |  | Internal file identifier.
FAB$L_MRN |  | Maximum record number.
FAB$W_MRS |  | Maximum record size.
FAB$B_ORG |  | File organization.
FAB$B_RAT |  | Record attributes.
FAB$B_RFM |  | Record format.
FAB$L_SDC |  | Secondary device characteristics.
FAB$B_SHR |  | File sharing.
FAB$L_STS |  | Completion status code (also returned in register 0).
FAB$L_STV |  | Status value: contains the I/O channel number if the operation is successful.
FAB$L_XAB |  | Next XAB field.
| XABALL | Allocation XAB; see Chapter 9.
| XABDAT | Date and time XAB; see Chapter 10.
| XABFHC | File header characteristics XAB; see Chapter 11.
| XABITM | Item list XAB; see Chapter 12.
| XABKEY | Key definition XAB; see Chapter 14.
| XABPRO | Protection XAB; see Chapter 15.
| XABRDT | Revision date and time XAB; see Chapter 16.
| XABSUM | Summary XAB; see Chapter 18.

Use of the NAM Block for Creating Files

Table RMS_7 and Table RMS-8 list the NAM block fields used as input and output for the Create service (provided that the name block address field [FAB$L_NAM] is specified).

Table RMS-7 Create Service NAM Input Fields
Field Name | Option | Description
--- | --- | ---
NAM$W_DID 1 |  | Directory identification (input only if the FAB$L_FOP FAB$V_NAM option is set).
NAM$T_DVI 1 |  | Device identification (input only if the FAB$L_FOP FAB$V_NAM option is set).
NAM$L_ESA |  | Expanded string area address.
NAM$B_ESS |  | Expanded string area size.
NAM$B_NOP |  | NAM block options.
| NAM$V_PWD | Password: indicates that a password contained in a DECnet for OpenVMS access control string, if present in a file specification, is to be left unaltered in the expanded and resultant strings (instead of being replaced by the word "password").
| NAM$V_NOCONCEAL | Do not conceal device name: indicates that when a concealed device logical name is present, the concealed device logical name is to be replaced by the actual physical device name in the resultant string.
| NAM$V_NO_SHORT_UPCASE 1 | Do not uppercase the directory and file specification in the NAM$L_ESA buffer.
NAM$L_RLF |  | Related file NAM or NAML block address.
NAM$L_RSA |  | Resultant string address.
NAM$B_RSL |  | Resultant string length.
NAM$L_FNB |  | File name status bits.
NAM$B_RSS |  | Resultant string area size.

1This field or option is not supported for DECnet for OpenVMS operations.

Table RMS-8 Create Service NAM Output Fields
Field Name | Description
--- | ---
NAM$B_DEV | Size of file specification device string.
NAM$L_DEV | Address of file specification device string.
NAM$W_DID 1 | Directory identification.
NAM$B_DIR | Size of file specification directory string.
NAM$L_DIR | Address of file specification directory string.
NAM$T_DVI 1 | Device identification.
NAM$B_ESL | Expanded string length. If the NAM$L_ESA field and the NAM$B_ESS field are nonzero, and you do not select the FAB$V_NAM option, or if the NAM$W_DID field is clear when you invoke the Create service, RMS copies the expanded file specification string to the buffer specified by the NAM$L_ESA field.
NAM$W_FID 1 | File identification.
NAM$W_FIRST_WILD_DIR 1 | First wild directory.
NAM$L_FNB | File name status bits. This is an output field from the Create service only if the NAM bit in FAB$L_FOP field is clear, or if the NAM$W_DID field is clear when you invoke the Create service.
NAM$W_LONG_DIR_LEVELS 1 | Total number of directory levels.
NAM$B_NAME | Size of file specification name string.
NAM$L_NAME | Address of file specification name string.
NAM$B_NODE | Size of file specification node string.
NAM$L_NODE | Address of file specification node string.
NAM$B_RSL | Resultant string length. If the NAM$L_RSA field and the NAM$B_RSS field are both nonzero on input, the resultant file specification is copied to the buffer specified by NAM$L_RSA.
NAM$B_TYPE | Size of file specification type string.
NAM$L_TYPE | Address of file specification type string.
NAM$B_VER | Size of file specification version string.
NAM$L_VER | Address of file specification version string.

1This field is not supported for DECnet for OpenVMS operations.

Previous | Next | Contents | Index

| privacy and legal statement |
4523PRO_021.HTML