Document revision date: 15 July 2002

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:

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.

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.

	privacy and legal statement
4523PRO_042.HTML