[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Guide to OpenVMS File Applications

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

Contents

Index