Document revision date: 15 July 2002
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

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

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
4523PRO_022.HTML