HP OpenVMS Systems Documentation

Content starts here

OpenVMS Record Management Services Reference Manual


Previous Contents Index

Table RMS-9 and Table RMS-10 list the NAML block fields used as input and output for the Create service.

Table RMS-9 Create Service NAML Input Fields (Alpha Only)
Field Name Option Description
NAML$W_DID 1   Directory identification (input only if the FAB$L_FOP FAB$V_NAM option is set).
NAML$T_DVI 1   Device identification (input only if the FAB$L_FOP FAB$V_NAM option is set).
NAML$L_ESA   Expanded string area address.
NAML$B_ESS   Expanded string area size.
NAML$L_FILESYS_NAME 1   File system file name.
NAML$L_FILESYS_NAME_ALLOC 1   File system file name buffer size.
NAML$L_FNB   File name status bits.
NAML$L_INPUT_FLAGS   Additional flags specified as input.
NAML$L_LONG_DEFNAME   Long default file specification string address (used if FAB$L_DNA contains -1).
NAML$L_LONG_DEFNAME_SIZE   Long default file specification string size.
NAML$L_LONG_EXPAND   Long expanded string area address.
NAML$L_LONG_EXPAND_ALLOC   Long expanded string area size.
NAML$L_LONG_FILENAME   Long file specification string address (used if FAB$L_FNA contains -1).
NAML$L_LONG_FILENAME_SIZE   Long file specification string size.
NAML$L_LONG_RESULT   Long resultant string area address.
NAML$L_LONG_RESULT_ALLOC   Long resultant string area.
NAML$L_LONG_RESULT_SIZE   Long resultant string length.
NAML$B_NOP   NAML block options.
  NAML$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").
  NAML$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.
  NAML$V_NO_SHORT_UPCASE 1 Do not uppercase the directory and file specification in the NAM$L_ESA buffer.
NAML$L_RLF   Related file NAM or NAML block address.
NAML$L_RSA   Resultant string address.
NAML$B_RSL   Resultant string length.
NAML$B_RSS   Resultant string area size.

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

Table RMS-10 Create Service NAML Output Fields (Alpha Only)
Field Name Description
NAML$B_DEV Size of file specification device string.
NAML$L_DEV Address of file specification device string.
NAML$W_DID 1 Directory identification.
NAML$B_DIR Size of file specification directory string.
NAML$L_DIR Address of file specification directory string.
NAML$T_DVI 1 Device identification.
NAML$B_ESL Expanded string length. If the NAML$L_ESA field and the NAML$B_ESS field are nonzero, and you do not select the FAB$V_NAM option, or if the NAML$W_DID field is clear when you invoke the Create service, RMS copies the expanded file specification string to the buffer specified by the NAML$L_ESA field.
NAML$W_FID 1 File identification.
NAM$W_FIRST_WILD_DIR 1 First wild directory.
NAML$L_FILESYS_NAME_SIZE 1 File system name size.
NAML$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 NAML$W_DID field is clear when you invoke the Create service.
NAML$L_LONG_DEV Long device string address.
NAML$L_LONG_DEV_SIZE Long device string size.
NAML$L_LONG_DIR Long directory string address.
NAML$W_LONG_DIR_LEVELS 1 Total number of directory levels.
NAML$L_LONG_DIR_SIZE Long directory string size.
NAML$L_LONG_EXPAND_SIZE Long expanded string length.
NAML$L_LONG_NAME Long file name string address.
NAML$L_LONG_NAME_SIZE Long file name string length.
NAML$L_LONG_NODE 1 Long node name string address.
NAML$L_LONG_NODE_SIZE Long node name string length.
NAML$L_LONG_RESULT_SIZE 1 Long resultant string length.
NAML$L_LONG_TYPE Long file type string length.
NAML$L_LONG_TYPE_SIZE Long file type string address.
NAML$L_LONG_VER Long file version string address.
NAML$L_LONG_VER_SIZE Long file version string length.
NAML$B_NAME Size of file specification name string.
NAML$L_NAME Address of file specification name string.
NAML$B_NODE Size of file specification node string.
NAML$L_NODE Address of file specification node string.
NAML$L_OUTPUT_FLAGS Output flags.
NAML$B_RSL Resultant string length. If the NAML$L_RSA field and the NAML$B_RSS field are both nonzero on input, the resultant file specification is copied to the buffer specified by NAML$L_RSA.
NAML$B_TYPE Size of file specification type string.
NAML$L_TYPE Address of file specification type string.
NAML$B_VER Size of file specification version string.
NAML$L_VER Address of file specification version string.

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

Creating Files with the Create-If Option

Note that setting the create-if (FAB$V_CIF) option in the FAB$L_FOP field specifies that if a new file has the same file specification as an existing file, RMS opens the existing file and no new file is created. Some fields in the FAB, such as the file organization (FAB$B_ORG) and record format (FAB$B_RFM) fields, are input to a Create service, but are output from an Open service. For example, the indexed file organization could be specified in the FAB$B_ORG field on a create-if operation. However, if an existing sequential file has the same file specification as the indexed file that the user is attempting to create, then the existing file is opened and the FAB$B_ORG field is set to sequential.

Creating Indexed Files

An indexed file consists of a prolog, with which it begins, and one or more index structures. RMS supplies the prolog with certain information about the file, including file attributes.

RMS supports two prolog levels, called Prolog 2 and Prolog 3. Unlike Prolog 2 files, Prolog 3 files allow for file compression and additional key types. For compatibility with RMS-11 data files that are transported or copied (without conversion) between systems, you may want to choose Prolog 2.

If you want to create a Prolog 3 file, you must be sure that records in the file are not larger than 32,224 bytes and, if the primary key is segmented, that the segments of the primary key do not overlap (one or more bytes of the record are used in more than one segment). If the primary key contains overlapping segments, you can consider using that key as an alternate key instead of a primary key or you can either request, or let RMS assign you, a Prolog 2 indexed file.

Prolog 3 is the default prolog for RMS, although RMS creates a Prolog 2 file only if the key characteristics are not compatible with Prolog 3 files. You can, however, override this default by requesting a specific prolog version. The option you choose in requesting a specific prolog level affects the behavior of RMS with regard to creating the file and returning error messages.

If you explicitly request a prolog version using the XABKEY XAB$B_PROLOG field in an application program, and if other file characteristics are incompatible with that prolog, then RMS returns an error message and does not attempt to create the file. For example, if you explicitly specify Prolog 2 in the XAB$B_PROLOG field and have requested a key type that is available only with Prolog 3 (such as an 8-byte integer key type), an error is returned and the file is not created.

However, if a specific prolog version is not explicitly requested in the XAB$B_PROLOG field, RMS selects the greatest prolog level that can support the specified key characteristics and does not return an error completion code.

In summary, there are two ways in which you can specify a particular prolog version:

  • Specify the XAB$B_PROLOG field in a XABKEY block in an application program, affecting only the file being created.
  • Use the DCL command SET RMS_DEFAULT/PROLOG to change the process default.

If you do not specify the XAB$B_PROLOG field in your application program, RMS examines your process defaults to check for prolog information. If this information is not specified in your process defaults, RMS examines the system defaults. If no prolog information is specified at the system level, RMS attempts to create a Prolog 3 file.

You need not be concerned with the distinctions between Prolog 2 and Prolog 1 files. To create an indexed file with a prolog version other than Prolog 3, specify a Prolog 2 file. If all keys in the file are string keys, RMS provides a default of Prolog 1; in all other cases, Prolog 2 is the default.

Note

String keys include the STRING, DSTRING, COLLATED, and DCOLLATED data-type keys.

If the file contains all string keys and Prolog 2 is requested, RMS attempts to create a Prolog 1 file only if no binary keys are present.

Note that RMS-11 and previous versions of RMS return error messages if requested to process Prolog 3 files.

If a failure is indicated, the file may be created, but it may not be opened for processing, depending on the nature of the failure.


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$_ACS RMS$_ACT RMS$_AID
RMS$_ALN RMS$_ALQ RMS$_AOP
RMS$_ATR RMS$_ATW RMS$_BKS
RMS$_BKZ RMS$_BLN RMS$_BUG
RMS$_BUG_DAP RMS$_BUG_DDI RMS$_CDA
RMS$_CHN RMS$_COD RMS$_CRE
RMS$_CREATED RMS$_CRE_STM RMS$_CRMP
RMS$_DAN RMS$_DEV RMS$_DFL
RMS$_DIR RMS$_DME RMS$_DNA
RMS$_DNF RMS$_DNR RMS$_DTP
RMS$_DVI RMS$_ENQ RMS$_ENV
RMS$_ESA RMS$_ESS RMS$_EXENQLM
RMS$_EXP RMS$_EXTNOTFOU RMS$_FAB
RMS$_FEX RMS$_FLG RMS$_FLK
RMS$_FNA RMS$_FNF RMS$_FNM
RMS$_FOP RMS$_FSZ RMS$_FUL
RMS$_GBC RMS$_IAL RMS$_IAN
RMS$_IBK RMS$_IFA RMS$_IFI
RMS$_IFL RMS$_IMX RMS$_IOP
RMS$_KNM RMS$_KSI RMS$_LAN
RMS$_LNE RMS$_MRN RMS$_MRS
RMS$_NAM RMS$_NAML RMS$_NAMLESS
RMS$_NAMLFSINV RMS$_NAMLFSSIZ RMS$_NAMLRSS
RMS$_NET RMS$_NETFAIL RMS$_NOD
RMS$_NORMAL RMS$_NPK RMS$_ORG
RMS$_POS RMS$_PRV RMS$_QUO
RMS$_RAT RMS$_REF RMS$_RFM
RMS$_RLF RMS$_RPL RMS$_RSS
RMS$_RST RMS$_RUNDOWN RMS$_SEG
RMS$_SEMANTICS RMS$_SHR RMS$_SIZ
RMS$_STR RMS$_SUC RMS$_SUP
RMS$_SUPERSEDE RMS$_SUPPORT RMS$_SYN
RMS$_SYS RMS$_UPI RMS$_VER
RMS$_WLK RMS$_WPL RMS$_XAB

$DELETE

The Delete service removes an existing record from a relative or indexed file. You cannot use this service when processing sequential files.

RAB64 Users (Alpha Only)

On Alpha systems, RAB64 can replace the RAB or RAB prefix wherever it is used with the Delete service on OpenVMS Alpha systems.

Format

SYS$DELETE rab [,[err] [,suc]]


RETURNS


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

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


Arguments

rab


OpenVMS usage: rab
type: longword (unsigned)
access: modify
mechanism: by reference

RAB control block whose contents are to be used as indirect arguments for the Delete service call. The rab argument is the address of the RAB 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

A Delete service always applies to the current record. Therefore, immediately before invoking the Delete service, you must establish the current record by issuing a Find or Get service.

Table RMS-11 lists the control block fields read as input by the Delete service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-11 Delete Service RAB Input Fields
Field Name Option Description
RAB$W_ISI   Internal stream identifier (required).
RAB$L_ROP   Record-processing options.
  RAB$V_ASY Asynchronous: performs Delete service asynchronously.
  RAB$V_FDL Fast delete (applies to indexed files).

Table RMS-12 lists the control block fields written as output by the Delete service.

Table RMS-12 Delete Service RAB Output Fields
Field Name Description
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
RMS$_BUG_DAP RMS$_CDA RMS$_CHK
RMS$_CUR RMS$_DME RMS$_DNR
RMS$_EXT_ERR RMS$_FAC RMS$_FTM
RMS$_IAL RMS$_IBF RMS$_IOP
RMS$_IRC RMS$_ISI RMS$_NET
RMS$_NETFAIL RMS$_NORMAL RMS$_OPNOTSUP
RMS$_PENDING RMS$_RAB RMS$_RNL
RMS$_RPL RMS$_RRV RMS$_RSA
RMS$_STR RMS$_SUC RMS$_SUP
RMS$_SUPPORT RMS$_SYS RMS$_TRE
RMS$_WLK    


Previous Next Contents Index