The file definition, area, and key properties define the physical
characteristics of a Record Management Services (RMS) database
file.
In most cases, the properties correspond to the RMS file and
allocation control field blocks (FABs or XABs). CDO does not
provide properties corresponding to the RMS record access block
attributes (RABs).
See the OpenVMS documentation on RMS for detailed descriptions
and the values accepted for each property listed in this
chapter.
1 – file_def_prop
Format
{ ALLOCATION numeric-literal }
{ BUCKET_SIZE numeric-literal }
{ MT_BLOCK_SIZE numeric-literal }
{ }
{ GLOBAL_BUFFER_COUNT numeric-literal }
{ MAX_RECORD_NUMBER numeric-literal }
{ MAX_RECORD_SIZE numeric-literal }
{ }
{ FILE_PROCESSING_OPTIONS [ file-processing-options ] ,... }
{ FOP [ file-processing-options ] ,... }
{ ORGANIZATION file-organization-options }
{ }
{ file-access-block-properties }
1.1 – Parameters
1.1.1 – numeric-literal
Specifies a positive integer.
1.1.2 – file-processing-options
[ BEST_TRY_CONTIGUOUS ]
[ CONTIGUOUS ]
[ CREATE_IF ]
[ DEFERRED_WRITE ]
[ DELETE_ON_CLOSE ]
[ MAXIMIZE_VERSION ]
[ MT_CLOSE_REWIND ]
[ MT_CURRENT_POSITION ]
[ MT_NOT_EOF ]
[ MT_OPEN_REWIND ]
[ NO_DIRECTORY_ENTRY ]
[ NON_FILE_STRUCTURED ]
[ PRINT_ON_CLOSE ]
[ READ_CHECK ]
[ SEQUENTIAL_ONLY ]
[ SUBMIT_ON_CLOSE ]
[ SUPERSEDE ]
[ TEMPORARY ]
[ TRUNCATE_ON_CLOSE ]
[ USER_FILE_OPEN ]
[ WRITE_CHECK ]
Define optional file operations for a program. The file
processing options fall into the following seven functional
categories:
o Allocation and extension options
o File disposition options
o File name parsing modifiers
o Magnetic tape processing options
o Nonstandard processing options
o Performance options
o Reliability options
1.1.3 – file-organization-options
{ INDEXED }
{ RELATIVE }
{ SEQUENTIAL }
Define the organization of the file. The default value for the
file organization option is SEQUENTIAL.
1.1.4 – file-access-block-attributes
{ EXTENSION numeric-literal }
{ CONTROL_FIELD_SIZE numeric-literal }
{ WINDOW_SIZE numeric-literal }
{ LOGICAL_NAME_MODE access-mode }
{ CHANNEL_ACCESS_MODE access-mode }
{ ACCESS [ file-access-control-options ] ,... }
{ FAC [ file-access-control-options ] ,... }
{ CARRIAGE_CONTROL carriage-control-options }
{ BLOCK_SPAN }
{ FORMAT record-format-options }
{ SHARING [ share-options ] ,... }
Define file access characteristics and certain run-time options.
1.1.5 – access-mode
{ NONE }
{ EXECUTIVE }
{ SUPER }
{ USER }
Defines an access mode for a channel. NONE is the default value,
which is interpreted by RMS as the executive mode.
1.1.6 – file-access-control-options
{ BLOCK_IO }
{ RECORD_IO }
{ DELETE }
{ GET }
{ PUT }
{ TRUNCATE }
{ UPDATE }
Define the type of record access operations that a program can
perform.
1.1.7 – carriage-control-options
{ CARRIAGE_RETURN }
{ FORTRAN }
{ PRINT }
Define record control information for a record. CARRIAGE_RETURN
is the default value for most OpenVMS programs.
1.1.8 – record-format-options
{ FIXED }
{ STREAM }
{ STREAM_CR }
{ STREAM_LF }
{ UNDEFINED }
{ VARIAABLE }
{ VFC }
Define the format for all records in a file.
1.1.9 – share-options
{ DELETE }
{ GET }
{ MULTISTREAM }
{ PROHIBIT }
{ PUT }
{ UPDATE }
{ USER_INTERLOCK }
Define the type of record operations that a program can perform
when sharing access to a file with other programs.
1.2 – Description
File definition properties define file characteristics and
certain run-time options for a logical RMS database element.
For a description and valid values for a particular keyword, see
the OpenVMS documentation on RMS.
For a mapping of CDO keywords to symbolics, see RMS_Keyword_
Mapping_Tables.
1.3 – Examples
CDO> DEFINE RMS_DATABASE EMPLOYEE_
INFO DESCRIPTION IS "INFORMATION ON"
cont> "CURRENT EMPLOYEE".
cont> RECORD EMPLOYEE_REC.
cont> FILE_DEFINITION
cont> ORGANIZATION INDEXED
cont> CHANNEL_ACCESS_MODE SUPER
cont> CARRIAGE_CONTROL CARRIAGE_RETURN
cont> ACCESS RECORD_IO
cont> FILE_PROCESSING_OPTIONS BEST_TRY_CONTIGUOUS
cont> FORMAT VARIABLE
cont> SHARING GET, USER_INTERLOCK.
cont> AREAS.
cont> AREA 0
cont> ALLOCATE 1000
cont> BUCKET_SIZE 10
cont> EXTENSION 100
cont> CONTIGUOUS.
cont> AREA 1
cont> ALLOCATE 1000
cont> BUCKET_SIZE 1
cont> EXTENSION 100
cont> BEST_TRY_CONTIGUOUS.
cont> AREA 2
cont> ALLOCATE 1000
cont> BUCKET_SIZE 1
cont> EXTENSION 100
cont> BEST_TRY_CONTIGUOUS.
cont> END AREAS.
cont> KEYS.
cont> KEY 0
cont> DATA_AREA 0
cont> INDEX_AREA 0
cont> SEGMENT EMP_ID IN EMPLOYEE_REC.
cont> KEY 1
cont> DUPLICATES
cont> DATA_AREA 1
cont> INDEX_AREA 2
cont> SEGMENT LAST_NAME IN EMPLOYEE_REC.
cont> END KEYS.
cont> END EMPLOYEE_INFO RMS_DATABASE.
This example is the complete logical RMS database definition
for EMPLOYEE_INFO. Seven file definition properties appear in
the DEFINE RMS_DATABASE command:
o The option for file organization is INDEXED.
o The channel access mode is SUPER.
o The carriage control option is CARRIAGE_RETURN, although it
is not necessary to code this because CARRIAGE_RETURN is the
default.
o The type of record access operation this program can perform
is RECORD_IO.
o An optional file processing operation is BEST_TRY_
CONTIGUOUS.
o Record format for this definition is VARIABLE.
o The types of record operations that this program can perform
when sharing access to a file with other programs are GET
and USER_INTERLOCK.
2 – area_properties
Format
{ EXACT_POSITIONING }
{ ANY_CYLINDER }
{ BEST_TRY_CONTIGUOUS }
{ }
{ CONTIGUOUS }
{ POSITION position-type }
{ VOLUME numeric-literal }
{ }
{ ALLOCATE numeric-literal }
{ BUCKET_SIZE numeric-literal }
{ EXTENSION numeric-literal }
{ }
2.1 – Parameters
2.1.1 – position-type
Defines the alignment of an allocated area. The default alignment
value is NONE. For more information, see RMS_Keyword_Mapping_Tables.
2.1.2 – numeric-literal
Specifies a positive integer.
2.2 – Description
Area properties provide additional control over file or area
space allocation on disk devices to optimize performance.
You usually include areas using indexed files. A file can contain
up to 255 areas. Define areas in numerical order, beginning with
0.
For a description and valid values for a particular keyword, see
the OpenVMS documentation on RMS.
For a mapping of CDO keywords to symbolics, see RMS_Keyword_
Mapping_Tables.
2.3 – Examples
1.CDO> DEFINE RMS_DATABASE EMPLOYEE_INFO DESCRIPTION IS "INFORMATION ON"
cont> "CURRENT EMPLOYEE".
cont> RECORD EMPLOYEE_REC.
.
.
.
cont> AREAS.
cont> AREA 0
cont> ALLOCATE 1000
cont> BUCKET_SIZE 10
cont> EXTENSION 100
cont> CONTIGUOUS.
cont> AREA 1
cont> ALLOCATE 1000
cont> BUCKET_SIZE 1
cont> EXTENSION 100
cont> BEST_TRY_CONTIGUOUS.
cont> AREA 2
cont> ALLOCATE 1000
cont> BUCKET_SIZE 1
cont> EXTENSION 100
cont> BEST_TRY_CONTIGUOUS.
cont> END AREAS.
.
.
.
cont> END EMPLOYEE_INFO RMS_DATABASE.
CDO>
This example shows the syntax for defining the ALLOCATE,
BUCKET_SIZE, EXTENSION, CONTIGUOUS, and BEST_TRY_CONTIGUOUS
properties for three areas in the EMPLOYEE_INFO RMS database
element.
2.CDO> DEFINE RMS_DATABASE MORE_EMPLOYEE_INFO
cont> "DESCRIPTION IS " DATA ON CURRENT EMPLOYEES ".
cont> RECORD EMPLOYEE_REC.
cont> FILE_DEFINITION
cont> AREA 1
cont> POSITION NONE.
.
.
.
cont> END MORE_EMPLOYEE_INFO RMS_DATABASE.
CDO>
This example shows the syntax that defines the NONE position
type option for the area property POSITION in the MORE_
EMPLOYEE_INFO RMS database element.
3 – key_properties
Format
{ DUPLICATES }
{ CHANGES }
{ NULL_KEY }
{ }
{ NULL_VALUE null-value }
{ DATA_AREA area-number }
{ DATA_FILL numeric-literal }
{ }
{ DATA_KEY_COMPRESSION }
{ DATA_RECORD_COMPRESSION }
{ INDEX_AREA area-number }
{ }
{ INDEX_COMPRESSION }
{ INDEX_FILL numeric-literal }
{ LEVEL1_INDEX_AREA area-number }
{ }
{ NODATA_KEY_COMPRESSION }
{ NODATA_RECORD_COMPRESSION }
{ NOINDEX_COMPRESSION }
{ }
{ PROLOG numeric-literal }
{ SEGMENT within-name-clause }
{ SORTED BY ASCENDING }
{ }
{ SORTED BY DESCENDING }
3.1 – Parameters
3.1.1 – null-value
Specifies a null key value for an alternate index. This value is
either an integer or a single character within quotation marks.
3.1.2 – area-number
Specifies a positive integer that corresponds to the number of a
previously defined area.
3.1.3 – numeric-literal
Specifies a positive integer. See the OpenVMS documentation on
RMS for the valid values for a particular keyword. For a mapping
of CDO keywords to the corresponding RMS symbolic field offset,
see RMS_Keyword_Mapping_Tables.
3.1.4 – within-name-clause
field-name { IN record-name } ...
Specifies the field or record names that are part of a segmented
key. A segmented key allows you to define a key that accesses
noncontiguous fields in a record. The record name is the same
name that defines the data structure of the RMS database in the
DEFINE RMS_DATABASE command.
3.2 – Description
Key properties define the characteristics of a key in an indexed
file. You define keys in numerical order, starting with 0. By
default, Key 0 always has a value of DATA_AREA 0.
A segmented key allows you to define a key that accesses non-
contiguous fields in a record. You can specify from 2 to 8
segments for each segmented key in an indexed file. For example:
o A field in a record
o A field in a record that is in a record
o A field in a structure in a record
You must specify a segment for each key you define. A segmented
key can contain up to 8 segments.
The field element or elements specified by the keyword SEGMENT
determine the data type of the key. A key with only 1 segment can
point to a field that has any of the following RMS data types:
DSC$K_DTYPE_B
DSC$K_DTYPE_BU
DSC$K_DTYPE_W
DSC$K_DTYPE_WU
DSC$K_DTYPE_L
DSC$K_DTYPE_LU
DSC$K_DTYPE_Q
DSC$K_DTYPE_QU
DSC$K_DTYPE_P
DSC$K_DTYPE_T
See the OpenVMS documentation on RMS for more information on
valid RMS data types.
Each segment of a key can contain up to 255 characters. The
sum of all characters for all key segments must not exceed 255
characters.
When defining a segment, you cannot use a field that is in the
variant portion of a record.
If you specify NULL_VALUE without specifying NULL_KEY, CDO
automatically specifies NULL_KEY. If you specify NULL_KEY without
specifying NULL_VALUE, the default value for NULL_VALUE is
0. When you display a RMS database element with a NULL_VALUE
property, the null value appears as a decimal value.
For a description and valid values for a particular keyword, see
the OpenVMS documentation on RMS.
For a mapping of CDO keywords to symbolics, see RMS_Keyword_
Mapping_Tables.
3.3 – Examples
CDO> DEFINE RMS_DATABASE EMPLOYEE_
INFO DESCRIPTION IS "INFORMATION ON"
cont> "CURRENT EMPLOYEE".
cont> RECORD EMPLOYEE_REC.
.
.
.
cont> KEYS.
cont> KEY 0
cont> DATA_AREA 0
cont> INDEX_AREA 0
cont> SEGMENT EMP_ID IN EMPLOYEE_REC.
cont> KEY 1
cont> DUPLICATES
cont> DATA_AREA 1
cont> INDEX_AREA 2
cont> SEGMENT LAST_NAME IN EMPLOYEE_REC.
cont> END KEYS.
cont> END EMPLOYEE_INFO RMS_DATABASE.
CDO>
This example shows the syntax for defining the DATA_AREA,
INDEX_AREA, SEGMENT, and DUPLICATES key properties in the
EMPLOYEE_INFO RMS database element.
4 – RMS Keyword Mapping Tables
The following tables show the mapping of the different keywords
used when creating a logical RMS database in a CDO dictionary.
Table 4-1 Mapping of Keywords to Symbolic Field Offsets
Keyword Symbolic Field Offset
Area Properties
ALLOCATE XAB$L_ALQ
ANY_CYLINDER XAB$V_ONC
BEST_TRY_CONTIGUOUS XAB$V_CBT
BUCKET_SIZE XAB$B_BKZ
CONTIGUOUS XAB$V_CTG
EXACT_POSITIONING XAB$V_HRD
EXTENSION XAB$W_DEQ
POSITION XAB$B_ALN
VOLUME XAB$W_VOL
File Access Block Properties
ACCESS FAB$B_FAC
BLOCK_SPAN FAB$V_BLK
CARRIAGE_CONTROL FAB$B_RAT
CHANNEL_ACCESS_MODE FAB$V_CHAN_MODE
CONTROL_FIELD_SIZE FAB$B_FSZ
EXTENSION FAB$W_DEQ
FAC FAB$B_FAC
FORMAT FAB$B_RFM
LOGICAL_NAME_MODE FAB$V_LNM_MODE
SHARING FAB$B_SHR
WINDOW_SIZE FAB$B_RTV
File Definition Properties
ALLOCATION FAB$L_ALQ
BUCKET_SIZE FAB$B_BKS
FILE_PROCESSING_OPTIONS FAB$L_FOP
FOP FAB$L_FOP
GLOBAL_BUFFER_COUNT FAB$W_GBC
MAX_RECORD_NUMBER FAB$L_MRN
MAX_RECORD_SIZE FAB$W_MRS
MT_BLOCK_SIZE FAB$W_BLS
ORGANIZATION FAB$B_ORG
Key Properties
ASCENDING XAB$B_DTP
CHANGES XAB$V_CHG
DATA_AREA XAB$B_DAN
DATA_FILL XAB$W_DFL
DATA_KEY_COMPRESSION XAB$V_KEY_NCMPR
DATA_RECORD_COMPRESSION XAB$V_DAT_NCMPR
DESCENDING XAB$B_DTP
DUPLICATES XAB$V_DUP
INDEX_AREA XAB$B_IAN
INDEX_COMPRESSION XAB$V_IDX_NCMPR
INDEX_FILL XAB$W_IFL
LEVEL1_INDEX_AREA XAB$B_LAN
NODATA_KEY_COMPRESSION XAB$V_KEY_NCMPR
NODATA_RECORD_COMPRESSION XAB$V_DAT_NCMPR
NOINDEX_COMPRESSION XAB$V_IDX_NCMPR
NULL_KEY XAB$V_NUL
NULL_VALUE XAB$B_NUL
PROLOG XAB$B_PROLOG
Mapping of Keywords to Symbolic Constants shows the mapping of
keywords to symbolic constants.
Table 4-2 Mapping of Keywords to Symbolic Constants
Symbolic
Keyword Constant Constant Type
Access Mode
EXECUTIVE PSL$C_EXEC FAB$V_CHAN_MODE
NONE (default) 0 FAB$V_CHAN_MODE
SUPER PSL$C_SUPER FAB$V_CHAN_MODE
USER PSL$C_USER FAB$V_CHAN_MODE
File Access Control
BLOCK_IO FAB$V_BIO FAB$B_FAC
DELETE FAB$V_DEL FAB$B_FAC
GET FAB$V_GET FAB$B_FAC
PUT FAB$V_PUT FAB$B_FAC
RECORD_IO FAB$V_BRO FAB$B_FAC
TRUNCATE FAB$V_TRN FAB$B_FAC
UPDATE FAB$V_UPD FAB$B_FAC
File Organization
INDEXED FAB$C_INX FAB$B_ORG
RELATIVE FAB$C_REL FAB$B_ORG
SEQUENTIAL FAB$C_SEQ FAB$B_ORG
(default)
Position Type
CYLINDER XAB$C_CYL XAB$B_ALN
FILE_ID XAB$C_RFI XAB$B_ALN
LOGICAL XAB$C_LBN XAB$B_ALN
NONE (default) XAB$C_ANY XAB$B_ALN
VIRTUAL XAB$C_VBN XAB$B_ALN
Record Format
FIXED FAB$C_FIX FAB$B_RFM
STREAM FAB$C_STM FAB$B_RFM
STREAM_CR FAB$C_STMCR FAB$B_RFM
STREAM_LF FAB$C_STMLF FAB$B_RFM
UNDEFINED FAB$C_UDF FAB$B_RFM
VARIABLE FAB$C_VAR FAB$B_RFM
VFC FAB$C_VFC FAB$B_RFM
Mapping of Keywords to Symbolic Bit Offsets shows the mapping of
keywords to symbolic bit offsets.
Table 4-3 Mapping of Keywords to Symbolic Bit Offsets
Symbolic Bit
Keyword Offset Symbolic Bit Offset Type
Carriage Control Options
CARRIAGE_RETURN FAB$V_CR FAB$B_RAT
(default)
FORTRAN FAB$V_FTN FAB$B_RAT
PRINT FAB$V_PRN FAB$B_RAT
File Processing Options-Allocation and Extension
BEST_TRY_ FAB$V_CBT RMS
CONTIGUOUS
CONTIGUOUS FAB$V_CTG RMS
TRUNCATE_ON_CLOSE FAB$V_TEF RMS
File Processing Options-Disposition
DELETE_ON_CLOSE FAB$V_DLT RMS
PRINT_ON_CLOSE FAB$V_SPL RMS
SUBMIT_ON_CLOSE FAB$V_SCF RMS
TEMPORARY FAB$V_TMD RMS
NO_DIRECTORY_ FAB$V_TMP RMS
ENTRY
File Processing Options-Name Parsing Modifiers
CREATE_IF FAB$V_CIF RMS
MAXIMIZE_VERSION FAB$V_MXV RMS
SUPERSEDE FAB$V_SUP RMS
File Processing Options-Magnetic Tape
MT_NOT_EOF FAB$V_NEF RMS
MT_CURRENT_ FAB$V_POS RMS
POSITION
MT_CLOSE_REWIND FAB$V_RWC RMS
MT_OPEN_REWIND FAB$V_RWO RMS
File Processing Options-Nonstandard
NON_FILE_ FAB$V_NFS RMS
STRUCTURED
USER_FILE_OPEN FAB$V_UFO RMS
File Processing Options-Performance
DEFERRED_WRITE FAB$V_DFW RMS
SEQUENTIAL_ONLY FAB$V_SQO RMS
File Processing Options-Reliability
READ_CHECK FAB$V_RCK RMS
WRITE_CHECK FAB$V_WCK RMS
Share Options
DELETE FAB$V_SHRDEL FAB$B_SHR
GET FAB$V_SHRGET FAB$B_SHR
MULTISTREAM FAB$V_MSE FAB$B_SHR
PROHIBIT FAB$V_NIL FAB$B_SHR
PUT FAB$V_SHRPUT FAB$B_SHR
UPDATE FAB$V_SHRUPD FAB$B_SHR
USER_INTERLOCK FAB$V_UPI FAB$B_SHR
Mapping of CDO Area Properties to RMS Symbolic Field Offsets
and Mapping of CDO Position Type Options to XAB$B_ALN Symbolic
Constants show the mapping of area properties keywords to
symbolic field offsets and constants.
Table 4-4 Mapping of CDO Area Properties to RMS Symbolic Field
Offsets
CDO Property RMS Symbolic Field Offset
ALLOCATE XAB$L_ALQ
ANY_CYLINDER XAB$V_ONC
BEST_TRY_CONTIGUOUS XAB$V_CBT
BUCKET_SIZE XAB$B_BKZ
CONTIGUOUS XAB$V_CTG
EXACT_POSITIONING XAB$V_HRD
EXTENSION XAB$W_DEQ
POSITION XAB$B_ALN
VOLUME XAB$W_VOL
Table 4-5 Mapping of CDO Position Type Options to XAB$B_ALN
Symbolic Constants
CDO Option Symbolic Constant
CYLINDER XAB$C_CYL
FILE_ID XAB$C_RFI
LOGICAL XAB$C_LBN
NONE (default) XAB$C_ANY
VIRTUAL XAB$C_VBN
Mapping of CDO Key Properties to RMS Symbolic Field Offsets
shows the mapping of key properties keywords to symbolic field
offsets.
Table 4-6 Mapping of CDO Key Properties to RMS Symbolic Field
Offsets
CDO Property RMS Symbolic Field Offset
ASCENDING XAB$B_DTP
DESCENDING XAB$B_DTP
DUPLICATES XAB$V_DUP
CHANGES XAB$V_CHG
NULL_KEY XAB$V_NUL
NULL_VALUE XAB$B_NUL
DATA_AREA XAB$B_DAN
DATA_FILL XAB$W_DFL
DATA_KEY_COMPRESSION XAB$V_KEY_NCMPR
DATA_RECORD_COMPRESSION XAB$V_DAT_NCMPR
INDEX_AREA XAB$B_IAN
INDEX_COMPRESSION XAB$V_IDX_NCMPR
INDEX_FILL XAB$W_IFL
LEVEL1_INDEX_AREA XAB$B_LAN
NODATA_KEY_COMPRESSION XAB$V_KEY_NCMPR
NODATA_RECORD_COMPRESSION XAB$V_DAT_NCMPR
NOINDEX_COMPRESSION XAB$V_IDX_NCMPR
PROLOG XAB$B_PROLOG