Document revision date: 15 July 2002
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

Guide to OpenVMS File Applications
Previous Contents Index

9.3 Summary of Record Operation Options

This section briefly describes the options associated with the record retrieval services (Find and Get), the record insertion service (Put), the record modification service (Update), and the record deletion service (Delete).

9.3.1 Record Retrieval Options

The Find and Get services (or the equivalent language statements) can be used to locate and retrieve a record.

The options associated with the Find and Get services are summarized in the following table. These options can be set for each Find or Get service if the program can access the appropriate RAB control block fields. The RAB control block fields are preset by connect-time values or defaults and as a result of previous service calls.
Option Description
Asynchronous record
processing 		Specifies that record I/O for this record stream is done asynchronously.
  • FDL: CONNECT ASYNCHRONOUS
  • RMS: RAB$L_ROP RAB$V_ASY
Do not lock record Directs RMS not to lock the record for ensuing operations.
  • FDL: CONNECT NOLOCK
  • RMS: RAB$L_ROP RAB$V_NLK
Key buffer Specifies key buffer that must contain the desired record's key when you are locating or reading records randomly.
  • FDL: None
  • RMS: RAB$L_KBF
Key equal or next Returns the first record with a key value equal to the specified key when you are locating or reading records. If RMS does not find a record with an equal key value, it returns the record with the next higher key value when you specify ascending sort order. When you specify descending sort order, RMS returns the record with the next lower key value.
  • FDL: CONNECT KEY_GREATER_EQUAL
  • RMS: RAB$L_ROP RAB$V_EQNXT
Next key Returns the record with the next higher key value when you specify ascending sort order when you are locating or reading records. When you specify descending sort order, RMS returns the record with the next lower key value.
  • FDL: CONNECT KEY_GREATER_THAN
  • RMS: RAB$L_ROP RAB$V_NXT
Key of reference Specifies which key is used for current record stream for indexed files with multiple keys.
  • FDL: CONNECT KEY_OF_REFERENCE
  • RMS: RAB$B_KRF
Key size Specifies that all or part of the key be used when you are using a string key to locate or read records.
  • FDL: None
  • RMS: RAB$B_KSZ
Limit key Directs RMS, when locating or reading records sequentially, to return an alternate success status if the record key exceeds the specified key.
  • FDL: CONNECT KEY_LIMIT
  • RMS: RAB$L_ROP RAB$V_LIM
Locate mode Specifies the locate mode, instead of the move mode. Applies to the Get service only.
  • FDL: CONNECT LOCATE_MODE
  • RMS: RAB$L_ROP RAB$V_LOC
Lock nonexistent
record 		Indicates that RMS is to lock the record position at the location of the following record operation, regardless of whether a record exists at that location. Applies only to relative files.
  • FDL: CONNECT NONEXISTENT_RECORD
  • RMS: RAB$L_ROP RAB$V_NXR
Lock for read Locks record for reading and allows other readers (but no writers).
  • FDL: CONNECT LOCK_ON_READ
  • RMS: RAB$L_ROP RAB$V_REA
Lock for write Locks record for writing and allows other readers (but no writers).
  • FDL: CONNECT LOCK_ON_WRITE
  • RMS: RAB$L_ROP RAB$V_RLK
Manual locking Allows you to control record locking and unlocking manually.
  • FDL: CONNECT MANUAL_LOCKING
  • RMS: RAB$L_ROP RAB$V_ULK
Read ahead Improves performance at the expense of additional memory for I/O buffers. For sequential access to sequential files only.
  • FDL: CONNECT READ_AHEAD
  • RMS: RAB$L_ROP RAB$V_RAH
Read regardless Reads the specified record regardless of whether it is locked by another user.
  • FDL: CONNECT READ_REGARDLESS
  • RMS: RAB$L_ROP RAB$V_RRL
Record access Specifies the way records are accessed: sequentially, randomly by key (indexed files), by record number (relative files), or randomly by RFA.
  • FDL: None
  • RMS: RAB$B_RAC values,
    RAB$C_SEQ, RAB$C_KEY,
    RAB$C_RFA
RFA Specifies the address of the desired record when records are accessed randomly by RFA (RAB$B_RAC contains RAB$C_RFA). This value is also returned by Find and Get services regardless of the type record access used.
  • FDL: None
  • RMS: RAB$W_RFA
Record header buffer Contains the symbolic address of the record header buffer that contains the fixed portion of a VFC record. Applies to the Get service only.
  • FDL: None
  • RMS: RAB$L_RHB
Timeout period Specifies a timeout period after which an error is returned when you choose the wait-if-locked option. The number of seconds is specified by the CONNECT TIMEOUT_PERIOD or RAB$B_TMO field to eliminate a potential deadlock.
  • FDL: CONNECT TIMEOUT_PERIOD
  • RMS: RAB$L_ROP RAB$V_TMO and
    RAB$B_TMO
User buffer address Specifies the address of the user buffer that receives the record. Applies to the Get service only.
  • FDL: None
  • RMS: RAB$L_UBF
User buffer size Specifies the maximum length of the user record buffer. Applies to the Get service only.
  • FDL: None
  • RMS: RAB$L_USZ
Wait if locked Specifies that if the record is locked, RMS must wait until it is available; also allows use of the wait-timeout-period option.
  • FDL: CONNECT WAIT_FOR_RECORD
  • RMS: RAB$L_ROP RAB$V_WAT

9.3.2 Put Service Options

The Put service (or equivalent language statement) adds a record to the file.

The options associated with the Put service are summarized in the following table. These options can be set for each Put service if the program can access the appropriate RAB control block fields. The RAB control block fields are preset by connect-time values or defaults and as a result of previous service calls.
Option Description
Asynchronous record
processing 		Specifies that record I/O for this record stream is done asynchronously.
  • FDL: CONNECT ASYNCHRONOUS
  • RMS: RAB$L_ROP RAB$V_ASY
Key buffer Specifies key buffer that must contain the desired record's relative record number when adding records randomly to a relative file.
  • FDL: None
  • RMS: RAB$L_KBF
Key size Specifies a field that must have a value of 4 (the default value provided by RMS) when adding records to a relative file using random record access.
  • FDL: None
  • RMS: RAB$B_KSZ
Load buckets Fills the buckets to the level specified when the file is created. The default is that buckets fill completely before a bucket split occurs.
  • FDL: CONNECT FILL_BUCKETS
  • RMS: RAB$L_ROP RAB$V_LOA
Read allowed Allows the locked record being written to be read.
  • FDL: CONNECT LOCK_ON_WRITE
  • RMS: RAB$L_ROP RAB$V_RLK
Record access Specifies the way records are added, sequentially according to ascending key value or relative record number, randomly by key (indexed files) or by record number (relative files), or randomly by RFA.
  • FDL: None
  • RMS: RAB$B_RAC values,
    RAB$C_SEQ, RAB$C_KEY,
    RAB$C_RFA
Record header buffer Contains the symbolic address of the record header buffer that contains the fixed portion of a VFC record. Applies to the Get service only.
  • FDL: None
  • RMS: RAB$L_RHB
Record buffer
address 		Specifies the address of the record buffer that contains the record to be written.
  • FDL: None
  • RMS: RAB$L_RBF
Record buffer size Specifies the size of the record contained in the record buffer to be written.
  • FDL: None
  • RMS: RAB$W_RSZ
Timeout period Specifies a timeout period after which an error is returned when you choose the wait-if-locked option. The number of seconds is specified by the CONNECT TIMEOUT_PERIOD or the RAB$B_TMO field to eliminate a potential deadlock.
  • FDL: CONNECT TIMEOUT_PERIOD
  • RMS: RAB$L_ROP RAB$V_TMO and
    RAB$B_TMO
Truncate on Put Specifies that the file is truncated at the record being added. Requires sequential record access and only applies to sequential files.
  • FDL: CONNECT TRUNCATE_ON_PUT
  • RMS: RAB$L_ROP RAB$V_TPT
Update-if Turns the Put service into an update operation if the record already exists in the file. Care must be taken when using this option with shared files and automatic record locking (see Section 8.1). When using this option with indexed files, note that the file must not allow duplicates for the primary key. This option can only be used when random record access has been specified.
  • FDL: CONNECT UPDATE_IF
  • RMS: RAB$L_ROP RAB$V_UIF
Write-behind Improves performance at the expense of additional memory for I/O buffers. Requires sequential record access and only applies to sequential files.
  • FDL: CONNECT WRITE_BEHIND
  • RMS: RAB$L_ROP RAB$V_WBH

9.3.3 Record Update Options

The Update service (or equivalent language statement) modifies an existing record in a file. Your program must first locate the appropriate record position and optionally retrieve the record itself by calling the Find or Get service (or equivalent language statement).

The options associated with the Update service are summarized in the following table. These options can be set for each Update service if the program can access the appropriate RAB control block fields. The RAB control block fields are preset by connect-time values or defaults and as a result of previous service calls.
Option Description
Asynchronous record
processing 		Specifies that record I/O for this record stream is done asynchronously.
  • FDL: CONNECT ASYNCHRONOUS
  • RMS: RAB$L_ROP RAB$V_ASY
Record header buffer Contains the symbolic address of the record header buffer that contains the fixed portion of a VFC record. Applies to the Get service only.
  • FDL: None
  • RMS: RAB$L_RHB
Record buffer
address 		Specifies the address of the record buffer that contains the record to be written.
  • FDL: None
  • RMS: RAB$L_RBF
Record buffer size Specifies the size of the records contained in the record buffer to be written.
  • FDL: None
  • RMS: RAB$W_RSZ

9.3.4 Record Deletion Options

The Delete service (or equivalent language statement) removes a record from the file. You cannot use this service for sequential files; however, a sequential file can be truncated using the Truncate service. Like the Update service, the Delete service must be preceded by a Find or Get service to establish the current record position.

The options associated with the Delete service are summarized in the following table. These options can be set for each Delete service if the program can access the appropriate RAB control block fields. The RAB control block fields are preset by connect-time values or defaults and as a result of previous service calls.
Option Description
Asynchronous record
processing 		Specifies that record I/O for this record service will be asynchronous.
  • FDL: CONNECT ASYNCHRONOUS
  • RMS: RAB$L_ROP RAB$V_ASY
Fast delete Specifies that the record to be deleted is flagged as deleted, but parts of any alternate index key path are not completely erased until a subsequent access using the alternate key occurs. This makes deleting the record occur more quickly, but it requires additional access time for a subsequent Find or Get service.
  • FDL: CONNECT FAST_DELETE
  • RMS: RAB$L_ROP RAB$V_FDL

9.4 Run-Time Example

Example 9-2 shows how to invoke the FDL$PARSE and FDL$RELEASE routines to use the predefined control block values set by an Edit/FDL utility editing session.

Example 9-2 Using the FDL$PARSE and FDL$RELEASE Routines 

; 
;  This program calls the FDL utility routines FDL$PARSE and 
;  FDL$RELEASE.  First, FDL$PARSE parses the FDL specification 
;  PART.FDL.  Then the data file named in PART.FDL is accessed 
;  using the primary key.  Last, the control blocks allocated 
;  by FDL$PARSE are released by FDL$RELEASE. 
; 
                .TITLE  FDLEXAM 
; 
                .PSECT  DATA,WRT,NOEXE 
 
; 
MY_FAB:         .LONG   0 
MY_RAB:         .LONG   0 
FDL_FILE:       .ASCID  /PART.FDL/          ; Declare FDL file 
REC_SIZE=80 
LF=10 
REC_RESULT:     .LONG   REC_SIZE 
                .ADDRESS REC_BUFFER 
REC_BUFFER:     .BLKB   REC_SIZE 
HEADING:        .ASCID /ID   PART   SUPPLIER        COLOR /[LF]
; 
                .PSECT  CODE 
; 
;  Declare the external routines 
; 
.EXTRN          FDL$PARSE, - 
                FDL$RELEASE 
                                            ; 
.ENTRY          FDLEXAM,^M<>                ; Set up entry mask 
                PUSHAL  MY_RAB              ; Get set up for call with 
                PUSHAL  MY_FAB              ; addresses to receive the 
                PUSHAL  FDL_FILE            ; FAB and RAB allocated by 
                CALLS   #3,G^FDL$PARSE      ; FDL$PARSE 
                BLBS    R0,KEY0             ; Branch on success 
                BRW     ERROR               ; Signal error 
                                            ; 
KEY0:           MOVL    MY_FAB,R10          ; Move address of FAB to R10 
                MOVL    MY_RAB,R9           ; Move address of RAB to R9 
                MOVL    #REC_SIZE,RAB$W_USZ(R9) 
                MOVAB   REC_BUFFER,RAB$L_UBF(R9) 
                $OPEN   FAB=(R10)           ; Open the file 
                BLBC    R0,F_ERROR 
                $CONNECT RAB=(R9)           ; Connect to the RAB 
                BLBC    R0,R_ERROR 
                PUSHAQ  HEADING             ; Display the heading 
                CALLS   #1,G^LIB$PUT_OUTPUT 
                BLBC    R0,ERROR 
                BRB     GET_REC             ; Skip error handling 
                                            ; 
F_ERROR:        BRW     FAB_ERROR 
R_ERROR:        BRW     RAB_ERROR 
                                            ; 
GET_REC:        $GET    RAB=(R9)            ; Get a record 
                CMPL    #RMS$_EOF,R0        ; If not end of file, 
                BEQLU   CLEAN               ; continue 
                BLBC    R0,R_ERROR 
                MOVZWL  RAB$W_RSZ(R9),REC_RESULT  ; Move a record into 
                PUSHAL  REC_RESULT                ; the buffer 
                CALLS   #1,G^LIB$PUT_OUTPUT       ; Display the record 
                BLBC    R0,ERROR 
                BRB     GET_REC             ; Get another record 
                                            ; 
CLEAN:          $CLOSE  FAB=(R10)           ; Close the FAB 
                BLBC    R0,FAB_ERROR 
                PUSHAL  MY_RAB              ; Push RAB address on stack 
                PUSHAL  MY_FAB              ; Push FAB address on stack 
                CALLS   #2,G^FDL$RELEASE    ; Release the control blocks 
                BLBC    R0,ERROR 
                BRB     FINI                ; Successful completion 
                                            ; 
FAB_ERROR: 
                PUSHL   FAB$L_STV(R10)      ; Signal file error 
                PUSHL   FAB$L_STS(R10) 
                BRB     RMS_ERR 
                                            ; 
ERROR:          PUSHL   R0                  ; Signal error 
                CALLS   #1,G^LIB$SIGNAL 
                $CLOSE  FAB=(R10) 
                BRW     FINI                ; End program 
                                            ; 
RAB_ERROR: 
                PUSHL   RAB$L_STV(R9)       ; Signal record error 
                PUSHL   RAB$L_STS(R9) 
                                            ; 
RMS_ERR: 
                CALLS   #2,G^LIB$SIGNAL 
                                            ; 
FINI:           RET 
                .END FDLEXAM

Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
4506PRO_027.HTML