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

OpenVMS Record Management Services Reference Manual


Previous Contents Index

B.3.8 Deleting Records

This service can only be used with relative and indexed files. Example B-8 illustrates the use of the Delete service.

Example B-8 Use of the Delete Service

 
        .TITLE  DELETE 
; 
; This program looks up records in the input file and 
; deletes those records. 
; 
 
        .PSECT  DATA,WRT,NOEXE 
INFAB:   $FAB   FNM = <INFILE:>,-       ; Input file logical name 
                FAC = <DEL,GET>         ; DEL access 
INRAB:   $RAB   FAB = INFAB,-           ; Pointer to FAB 
                KBF = INP_STR,-         ; Key buffer 
                KRF = 0,-               ; Primary key 
                RAC = KEY               ; Keyed access 
REC_SIZE = 132                          ; Maximum size records 
INP_STR:                                ; Key string/record buffer 
        .BLKB   REC_SIZE 
INP_STR_D:                              ; Key string descriptor 
        .LONG   REC_SIZE 
        .LONG   INP_STR 
INP_STR_LEN:                            ; Key string length 
        .BLKL   1 
KEY_PMT_D:                              ; Key value prompt string 
        .ASCID  /Please enter key value: / 
        .PSECT  CODE,NOWRT,EXE 
; 
; Initialization - Open file and connect stream 
; 
        .ENTRY  DELETE,^M<>             ; No registers to save 
        $OPEN   FAB=INFAB               ; Open input file 
        BLBC    R0,F_ERR                ; Quit on error 
        $CONNECT        RAB=INRAB       ; Connect to input 
        BLBC    R0,R_ERR                ; Quit on error 
; 
; Delete record loop 
; 
READ: 
        PUSHAB  INP_STR_LEN             ; Address for string length 
        PUSHAB  KEY_PMT_D               ; Prompt string descriptor 
        PUSHAB  INP_STR_D               ; String buffer descriptor 
        CALLS   #3,G^LIB$GET_INPUT      ; Get input string value 
        BLBS    R0,FIND                 ; Quit on error or end-of-file 
        CMPL    R0,#RMS$_EOF            ; Was error end-of-file? 
        BEQL    DONE                    ; Successful completion 
        BRB     EXIT                    ; Error otherwise 
FIND:   MOVB    INP_STR_LEN, -          ; Set key size 
                INRAB+RAB$B_KSZ 
        $FIND   RAB=INRAB               ; Locate the record 
        BLBS    R0,DEL                  ; Continue if found 
        CMPL    R0,#RMS$_RNF            ; No such record? 
        BEQL    READ                    ; Try again 
        BRB     R_ERR                   ; Error otherwise 
DEL:    $DELETE RAB=INRAB               ; Delete the record 
        BLBC    R0,R_ERR                ; Quit on error 
        BRB     READ                    ; Go back for more 
; 
; Close files and exit 
; 
F_ERR:  PUSHL   FAB$L_STV+INFAB         ; Push STV and STS on 
        PUSHL   FAB$L_STS+INFAB         ; stack in reverse order 
        CALLS   #2, G^LIB$SIGNAL        ; Signal message 
        BRB     EXIT 
R_ERR:  PUSHL   RAB$L_STV+INRAB         ; Push STV and STS on 
        PUSHL   RAB$L_STS+INRAB         ; stack in reverse order 
        CALLS   #2, G^LIB$SIGNAL        ; Signal message 
DONE:   $CLOSE  FAB=INFAB               ; Close files 
EXIT:   RET                             ; Return with status in R0 
        .END    DELETE 

This program uses a key to find and delete a record. To use the $DELETE macro, the $FAB macro for the file must set the FAB$V_DEL bit as shown in the following code example:


INFAB:  $FAB    FNM=<INFILE:>,- 
                FAC=<DEL> 

The following program statement invokes the Delete service and points to the input RAB:


$DELETE        RAB=INRAB 

B.3.9 Updating Records

Example B-9 illustrates the use of the Update service.

Example B-9 Use of the Update Service

 
        .TITLE  UPDATE 
; 
; This program looks up records in the input file and 
; updates those records. 
; 
 
        .PSECT  DATA,WRT,NOEXE 
INFAB:  $FAB    FNM = <INFILE:>,-       ; Input file logical name 
                FAC = <GET,UPD>         ; Read and Write access 
INRAB:  $RAB    FAB = INFAB,-           ; Pointer to FAB 
                KBF = INP_STR,-         ; Key buffer 
                KRF = 0,-               ; Primary key 
                RAC = KEY,-             ; Keyed access 
                RBF = INP_STR           ; Record buffer 
REC_SIZE = 132                          ; Maximum size records 
INP_STR:                                ; Key string/record buffer 
        .BLKB   REC_SIZE 
INP_STR_D:                              ; Key string descriptor 
        .LONG   REC_SIZE 
        .LONG   INP_STR 
INP_STR_LEN:                            ; Key string length 
        .BLKL   1 
KEY_PMT_D:                              ; Key value prompt string 
        .ASCID  /Please input key value: / 
DATA_PMT_D:                             ; Data value prompt string 
        .ASCID  /Please input new record value: / 
        .PSECT  CODE,NOWRT,EXE 
; 
; Initialization - Open file and connect stream 
; 
        .ENTRY  UPDATE,^M<>             ; No registers to save 
        $OPEN   FAB=INFAB               ; Open input file 
        BLBC    R0,FAB_E                ; Quit on error 
        $CONNECT        RAB=INRAB       ; Connect to input 
        BLBC    R0,RAB_E                ; Quit on error 
        BRB     READ                    ; Begin update loop 
FAB_E:  BRW     F_ERR                   ; File (FAB) error 
RAB_E:  BRW     R_ERR                   ; Record (RAB) error 
; 
; Update record loop 
; 
READ: 
; 
; Prompt for key value to look up. 
; 
        PUSHAB  INP_STR_LEN             ; Address for string length 
        PUSHAB  KEY_PMT_D               ; Prompt string descriptor 
        PUSHAB  INP_STR_D               ; String buffer descriptor 
        CALLS   #3,G^LIB$GET_INPUT      ; Get input string value 
        BLBS    R0,FIND                 ; Quit on error or end-of-file 
        CMPL    R0,#RMS$_EOF            ; Was error end-of-file? 
        BEQL    ALL_D                   ; Successful completion 
        BRW     EXIT                    ; Error otherwise 
ALL_D:  BRW     DONE 
FIND:   MOVB    INP_STR_LEN, -          ; Set key size 
                INRAB+RAB$B_KSZ 
        $FIND   RAB=INRAB               ; Locate the record 
        BLBS    R0,UPD                  ; Continue if found 
        CMPL    R0,#RMS$_RNF            ; No such record? 
        BEQL    READ                    ; Try again 
        BRB     R_ERR                   ; Error otherwise 
; 
; Prompt for new data record. 
; 
UPD: 
        PUSHAB  INP_STR_LEN             ; Address for string length 
        PUSHAB  DATA_PMT_D              ; Prompt string descriptor 
        PUSHAB  INP_STR_D               ; String buffer descriptor 
        CALLS   #3,G^LIB$GET_INPUT      ; Get input string value 
        BLBC    R0,EXIT                 ; Quit on error 
        MOVW    INP_STR_LEN, -          ; Set record size 
                INRAB+RAB$W_RSZ 
        $UPDATE RAB=INRAB               ; Write the record 
        BLBC    R0,R_ERR                ; Quit on error 
        BRW     READ                    ; Go back for more 
; 
; Close files and exit 
; 
F_ERR:  PUSHL   FAB$L_STV+INFAB         ; Push STV and STS on 
        PUSHL   FAB$L_STS+INFAB         ; stack in reverse order 
        CALLS   #2, G^LIB$SIGNAL        ; Signal message 
        BRB     EXIT 
R_ERR:  PUSHL   RAB$L_STV+INRAB         ; Push STV and STS on 
        PUSHL   RAB$L_STS+INRAB         ; stack in reverse order 
        CALLS   #2, G^LIB$SIGNAL        ; Signal message 
DONE:   $CLOSE  FAB=INFAB               ; Close files 
EXIT:   RET                             ; Return with status in R0 
        .END    UPDATE 

This program uses a key and a new record entered from the terminal to update a record in the input file.

To use the $UPDATE macro, the $FAB macro for the file must specify that the FAB$V_UPD bit is marked in the file access (FAB$B_FAC) field as shown in the following code example:


INFAB:  $FAB   FNM=<INFILE:>,- 
               FAC=<GET,UPD> 

Before updating a record, the program uses the Find service to locate the record by executing the $FIND macro located at the FIND label:


$FIND   RAB=INRAB 

B.3.10 Using Block I/O

In addition to the major types of record access provided by the sequential, random by key value or relative record number, and random by RFA access modes, RMS provides another means to access data in a file: block I/O.

Block I/O operations let you directly read or write the blocks of a file. These operations are provided for users who must keep system overhead to a minimum and need no interpretation of file data as logical records, yet still want to take advantage of RMS file accessibility. Block I/O is an intermediate step between the RMS record operations and direct use of $QIO system services.

The three block I/O services are invoked using the $READ, $SPACE, and $WRITE macros, respectively.

The Read and Write services always begin on a block boundary.

In addition to the Read, Space, and Write services, you can use the following services on a record stream connected for block I/O operations:

These services perform miscellaneous operations or disconnect the record stream. They do not work on the contents of the records themselves.

You cannot perform block I/O operations on shared files. That is, file access for block I/O operations is denied unless the FAB$V_UPI or the FAB$V_NIL bit is set in the FAB$B_SHR field.

You specify block I/O operations for a record stream by setting the FAB$V_BIO bit in the file access (FAB$B_FAC) field as input to the Open or Create services. If you intend to write to the file, you must set the PUT option in the FAB$B_FAC field; if you intend to read from the file, you must set the GET option in the FAB$B_FAC field. If you set the FAB$V_BIO bit when you create a relative or indexed file, RMS omits prolog processing for indexed files and initial space prezeroing in relative files.

For files of unknown organization, block I/O is the only form of processing allowed. Processing proceeds identically to that for block I/O to the relative file organization described previously.

B.3.11 Mixed Block and Record I/O

How and when RMS allows you to switch between record I/O and block I/O depends on the organization of the file being accessed.

When you access sequential files, RMS allows you to switch between record I/O and block I/O with each record operation, if desired. To enable I/O switching for a record stream connected to a sequential file, use the following procedure:

  1. Set the FAB$V_BRO option in the FAB$B_FAC field as input to the Create or Open service.
  2. Clear the RAB$L_ROP field RAB$V_BIO option as input to the Connect service.

This procedure informs RMS that it should check the RAB$V_BIO option in the RAB$L_ROP field after each operation.

To do a block I/O operation:

  1. Set the RAB$L_ROP field RAB$V_BIO option.
  2. Invoke a block I/O service (Read, Space, or Write).

To do a record I/O operation:

  1. Clear the RAB$L_ROP field RAB$V_BIO option.
  2. Invoke a record I/O service.

Use care if you do choose to mix record and block I/O operations for sequential files. When you switch operations on disk devices, the context of the current record, the next record, and the next block pointer is undefined. Thus, the first operation after the switch must not use sequential record access mode. For magnetic tape devices, the context of the next record or next block indicates the start of the following block on the tape for the first operation after the switch.

As previously noted, you usually set the FAB$B_FAC field FAB$V_BRO option only to indicate that you want to mix record I/O and block I/O operations. If you decide that you want to perform block I/O processing only, you can set the RAB$L_ROP field RAB$V_BIO option after you open the file but before you invoke the Connect service. This connect-time operation overrides the setting of the FAB$V_BRO option for the current record stream and indicates to the Connect service that you only intend to do block I/O for this file, thus eliminating the need to allocate internal I/O buffers. (However, you must still allocate buffers for block I/O operations in your application program.) If you set the FAB$V_BRO option when you create an indexed file, the key definition XABs for that file must be present.

When you access relative or indexed files, switching is available only if you close and reopen the file. RMS does not permit both types of I/O simultaneously. When multiple record streams are used, all record streams must use the same type of I/O, either record I/O or block I/O.

You specify the I/O type when you create or open a file by selecting either the block I/O option (FAB$V_BIO bit set) or the record I/O option (FAB$V_BIO bit clear). For relative and indexed files, the decision to use block I/O or record I/O for a file can be postponed, if desired, until the record stream is connected by the following procedure:

  1. Set the FAB$B_FAC field FAB$V_BRO option when you are opening (or creating) the file.
  2. Indicate the appropriate operation to the Connect service by either setting the RAB$V_BIO bit in the RAB$L_ROP for block I/O or by clearing it for record I/O.

B.3.12 Next Block Pointer (NBP)

For block I/O operations to sequential files on disk devices, RMS maintains an internal next block pointer (NBP) that does the following functions:

An explicit Extend service is required for relative and indexed files because RMS does not automatically extend a file's allocation when using block I/O processing.

Example B-10 illustrates how to copy a file using block I/O.

Example B-10 Use of Block I/O

        .TITLE  BLOCKIO 
; 
; This program copies the input file to the output file. 
; It illustrates block I/O using the RMS $READ and $WRITE 
; macros. 
; 
        .PSECT  DATA,WRT,NOEXE 
INFAB:  $FAB    FNM = <INFILE:>,-       ; Input file name 
                FAC = <BIO,GET>         ; Block I/O read operations 
INRAB:  $RAB    FAB = INFAB,-           ; Pointer to FAB 
                BKT = 0,-               ; Start with current block 
                UBF = REC_BUFF,-        ; Record buffer 
                USZ = REC_SIZE          ;   and size 
OUTFAB: $FAB    FNM = <OUTFILE:>,-      ; Output file name 
                FOP = CBT,-             ; Try for contiguous file 
                MRS = REC_SIZE,-        ; Maximum record size 
                FAC = <BIO,PUT>,-       ; Block I/O write operations 
                RAT = CR                ; Implied carriage control 
OUTRAB: $RAB    FAB = OUTFAB,-          ; Pointer to FAB 
                BKT = 0,-               ; Start with current block 
                RBF = REC_BUFF          ; Output uses same buffer 
                                        ;   as input 
REC_SIZE = 1024                         ; Maximum record size 
REC_BUFF: 
        .BLKB   REC_SIZE                ; Record buffer 
 
        .PSECT  CODE,NOWRT,EXE 
; 
; Initialization - Open input and output files and connect streams 
; 
        .ENTRY  BLOCKIO,^M<>            ; No registers to save 
        $OPEN   FAB=INFAB               ; Open input file 
        BLBC    R0,EXIT1                ; Quit on error 
        $CONNECT        RAB=INRAB       ; Connect to input 
        BLBC    R0,EXIT2                ; Quit on error 
        MOVL    INFAB+FAB$L_ALQ,-       ; Set proper size 
                OUTFAB+FAB$L_ALQ        ;   for output 
        $CREATE FAB=OUTFAB              ; Create output file 
        BLBC    R0,EXIT3                ; Quit on error 
        $CONNECT        RAB=OUTRAB      ; Connect to output 
        BLBC    R0,EXIT4                ; Quit on error 
; 
; Copy loop 
; 
READ:   $READ   RAB=INRAB               ; Get a block 
        BLBS    R0,WRITE                ; Write the block 
        CMPL    R0,#RMS$_EOF            ; Was error end-of-file? 
        BEQL    DONE                    ; Successful completion 
        BRB     EXIT2                   ; If not, signal error 
WRITE:  MOVW    INRAB+RAB$W_RSZ, -      ; Set the record size 
                OUTRAB+RAB$W_RSZ        ;   for output 
        $WRITE  RAB=OUTRAB              ; Write the block 
        BLBC    R0,EXIT4                ; Quit on error 
        BRB     READ                    ; Go back for more 
; 
; Error Signaling 
; 
EXIT1:  MOVL    INFAB+FAB$L_STS,R2      ; Move STS into R2 
        MOVL    INFAB+FAB$L_STV,R3      ; Move STV into R3 
        BRB     EXIT                    ; Signal error 
EXIT2:  MOVL    INRAB+RAB$L_STS,R2      ; Move STS into R2 
        MOVL    INRAB+RAB$L_STV,R3      ; Move STV into R3 
        BRB     EXIT                    ; Signal error 
EXIT3:  MOVL    OUTFAB+FAB$L_STS,R2     ; Move STS into R2 
        MOVL    OUTFAB+FAB$L_STV,R3     ; Move STV into R3 
        BRB     EXIT                    ; Signal error 
EXIT4:  MOVL    OUTRAB+RAB$L_STS,R2     ; Move STS into R2 
        MOVL    OUTRAB+RAB$L_STV,R3     ; Move STV into R3 
        BRB     EXIT                    ; Signal error 
; 
; Close files and exit 
; 
DONE:   $CLOSE  FAB=INFAB               ; Close input and 
        $CLOSE  FAB=OUTFAB              ;   output files 
        RET                             ; Return w/ success in R0 
EXIT:   PUSHL   R3                      ; Push STV and STS 
        PUSHL   R2                      ; on stack 
        CALLS   #2, G^LIB$SIGNAL        ; Signal error 
        RET                             ; Return w/ status in R0 
        .END    BLOCKIO 

This example program uses block I/O to transfer the contents of the input file to the output file. The following program data statements specify block I/O read operations from the input file by setting the FAB$V_BIO bit (block I/O) and the FAB$V_GET bit (read) in the FAB$B_FAC field of the input file's FAB:


INFAB:  $FAB    FNM = <INFILE>, -       ;Input file name 
                FAC = <BIO,GET>,- 

The following data statements specify block I/O write operations to the output file by setting the FAB$V_BIO bit (block I/O) and the FAB$V_PUT bit (write) in the FAB$B_FAC field of the output file's FAB:


OUTFAB: $FAB    FNM = <INFILE>, -       ;Output file name 
                FAC = <BIO,PUT>,- 

The input file's contents are copied until the end of file is encountered. Any errors are signaled with the convention of using both the STS and STV fields of the appropriate control block.


Index Contents

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