1 File_Area_Key_Properties 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. 2 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 } 3 Parameters 4 numeric-literal Specifies a positive integer. 4 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 4 file-organization-options { INDEXED } { RELATIVE } { SEQUENTIAL } Define the organization of the file. The default value for the file organization option is SEQUENTIAL. 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. 4 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. 4 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. 4 carriage-control-options { CARRIAGE_RETURN } { FORTRAN } { PRINT } Define record control information for a record. CARRIAGE_RETURN is the default value for most OpenVMS programs. 4 record-format-options { FIXED } { STREAM } { STREAM_CR } { STREAM_LF } { UNDEFINED } { VARIAABLE } { VFC } Define the format for all records in a file. 4 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. 3 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. 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 } { } 3 Parameters 4 position-type Defines the alignment of an allocated area. The default alignment value is NONE. For more information, see RMS_Keyword_Mapping_Tables. 4 numeric-literal Specifies a positive integer. 3 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. 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. 2 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 Parameters 4 null-value Specifies a null key value for an alternate index. This value is either an integer or a single character within quotation marks. 4 area-number Specifies a positive integer that corresponds to the number of a previously defined area. 4 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. 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 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 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. 2 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