HP OpenVMS Systems Documentation

OpenVMS Record Management Services Reference Manual

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

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.

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.

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

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).