HP OpenVMS Systems Documentation

OpenVMS Record Management Services Reference Manual

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 service transfers a specified number of bytes to memory.
The Space service positions a file forward or backward a specified number of blocks.
The Write service writes a specified number of bytes to a file.

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:

The Disconnect service ($DISCONNECT macro)
The Flush service ($FLUSH macro)
The Next Volume service ($NXTVOL macro)
The Rewind service ($REWIND macro)

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:

Set the FAB$V_BRO option in the FAB$B_FAC field as input to the Create or Open service.
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:

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

To do a record I/O operation:

Clear the RAB$L_ROP field RAB$V_BIO option.
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:

Set the FAB$B_FAC field FAB$V_BRO option when you are opening (or creating) the file.
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:

Points to the beginning of the file following execution of a Connect service if the RAB$V_EOF option in the RAB$L_ROP field of the RAB is cleared. If the RAB$L_ROP field RAB$V_EOF option is set, the NPB points to the block following the end of the file. The RAB$V_EOF option is relevant only for sequential files doing block I/O processing.
Points to the block following the highest numbered block transferred by a read or write operation.
Points to the next block following an operation invoked by the Space service.

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