Document revision date: 15 July 2002 | |
Previous | Contents | Index |
Table RMS-4 lists the control block fields written as output by the Connect service.
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 |
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 |
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.
SYS$CREATE fab [,[err] [,suc]]
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.
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.
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 TypeDescription 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.
Table RMS-6 lists the control block fields written as output by the Create service.
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).
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. |
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. |
Previous | Next | Contents | Index |
privacy and legal statement | ||
4523PRO_022.HTML |