Document revision date: 15 July 2002

For the Update, Delete, Release, and Truncate services, the current-record position reflects the location of the target record. The current-record position also facilitates sequential processing on disk devices for a stream.

The following list describes situations where the current-record position is undefined:

• When a RAB is first connected to a FAB
• When a record operation is unsuccessful
• Following the successful execution of a service other than a Get service or Find service

When the current-record position is undefined, RMS rejects the Update, Delete, Release, or Truncate service.

A Get service using sequential record access mode and immediately preceded by the Find service operates on the record specified by the current-record position. If the Find service does not lock the record (for relative and indexed files) and the current record is deleted, the Get service accesses the record at the next-record position.

Following successful execution of the Get service or the Find service, the current-record position is set to the target record's RFA. RMS also places the target record's address in the RFA field of the related RAB. The results are as follows:

• After initialization, the current-record position reflects the RFA of the record that was the object of the most recent successful Get service or Find service (unless a failure occurs on a different service).
• Unless it is modified, the RAB$W_RFA field always contains the address of the target current record. (If the operation fails, the RFA is undefined.)

Table 8-3 summarizes the effect that each successful record operation has on the context of the current record.

8.6.2 Next-Record Position

RMS uses the next-record position for doing sequential record access. For sequential record processing, the next-record position is the location of the target record for the next Find service (Get service where appropriate) or Put service. In a relative file, the target record is the record that occupies the next nonvacant cell.

The ability to look ahead significantly decreases access time for sequential processing. RMS uses its internal knowledge of file organization and structures to determine the next-record position for each record service.

The Connect service initializes the next-record position to one of the following locations:

• The first record in a sequential file or the first cell in a relative file
• The first record in the collated sequence of the specified key of reference in an indexed file
• The end of a file on disk, if the RAB$L_ROP field RAB$V_EOF option is set
• The end of a write-accessed ANSI magnetic tape file, unless the FAB$V_NEF option is set in the FAB$L_FOP field

In any record access mode, the Get service establishes the next-record position as either the next record or the next record cell in the file. This is also true for the Find service in sequential access mode.

The Truncate service establishes the end of the file at the current-record position (effectively deleting the record at that location and all records following it) so you need only use Put services to extend the file. Note that you can truncate only sequential files.

In random access mode, the Find (or Get) service and the Put service do not affect the next-record position, unless these services are used to add a record with a primary key value or a record number that lies between the corresponding values of the current record and the next record (previous record for reverse search key options). When this occurs, the current-record position is changed to reflect the location of the added record; that is, records are added after the current record, not before the next record.

In sequential access mode, the Put service initializes the next-record position to the end of the file in a sequential file. In a relative file, the Put service initializes the next-record position to the next record or record cell. For sequential accesses to an indexed file, the Put service does not define the next-record position.

Regardless of access mode, the Delete, Update, Free, and Release services have no effect on the next-record position. For sequential and relative files, the Rewind service establishes the next-record position as the first record or record cell in the file, regardless of the access mode. For indexed files, the Rewind service always establishes the next-record position as the location of the first record for the current key of reference.

Any unsuccessful record operation has no effect on the next record.

8.7 Synchronous and Asynchronous Operations

Your program can handle record operations on a file in one of two ways: synchronously or asynchronously. When operating synchronously, the program issuing the record-operation request regains control only when the request is completely satisfied. Most high-level languages support synchronous operation only. In asynchronous operations, the program can regain control before the request is completely satisfied. You can specify record operations and file operations to be either synchronous or asynchronous for each record stream.

For instance, when reading a record from a file synchronously, the program regains control only after the record is passed to the program. In other words, the program waits until the record returns; no other processing for this program takes place during this read-and-return cycle. On the other hand, when reading a record asynchronously, the program might be able to regain control before the record is passed to the program. The program can thus use the time normally required for the record transfer between the file and memory to perform some other computations. Another record operation cannot be started on the same stream until the previous record operation is complete. However, record operations on other streams can be initiated.

Whether the program regains control before the record operation finishes depends on several factors. For example, the required record may already reside in the I/O buffer, or the operating system may schedule another process, thus possibly allowing a necessary I/O operation to be completed before the original program is rescheduled.

One factor to consider in the use of asynchronous record operations is that you must include a separate completion routine or a wait request in the issuing program. This routine (or wait request) is required to determine when the record operation is completed because the results of the operation are not available, and the next record operation for that stream cannot be initiated until the previous operation is concluded.

8.7.1 Using Synchronous Operations

To declare a synchronous operation, you must clear the RAB$V_ASY option in the RAB$L_ROP field. Normally, you do not have to clear this option because it is already cleared (by default). However, if the RAB$V_ASY option had been set previously, then you must explicitly clear it.

Normally, you do not use success and error routines with synchronous operations. Instead, you test the completion status code for an error and change the flow of the program accordingly. However, if you use these routines, they are executed as asynchronous system traps (ASTs) before the service returns to your program (unless ASTs are disabled).

User-mode AST routines may be executed before the completion of a synchronous record operation (see the OpenVMS Record Management Services Reference Manual). If an AST routine attempts to perform operations on a record stream that is being called from a non-AST level, it must be prepared to handle stream-activity errors (RMS$_RSA or RMS$_BUSY).

8.7.2 Using Asynchronous Operations

To declare an asynchronous record operation, you must set the asynchronous (RAB$V_ASY) option in the RAB$L_ROP field. You can switch between synchronous and asynchronous operations during processing of a record stream by setting or clearing the RAB$V_ASY option on a per-operation basis.

You can specify completion routines to be executed as ASTs if success or error conditions occur. Within such routines, you can issue additional operations, but they should also be asynchronous. If they are not, all other asynchronous requests currently active in your program cannot have their completion routines executed until the synchronous operation completes.

If an asynchronous operation is not completed at the time of return from a call to a service, the completion status field of the RAB is 0, and a success status code of RMS$_PENDING is returned in Register 0. This status code indicates that the operation was initiated but is not yet complete.

If you issue a second record operation request for the same stream before a previous request is completed, you receive an RMS$_RSA or RMS$_BUSY error status code, indicating that the record stream is still active. This can also occur when an AST-level routine attempts to use an active record stream; the original I/O request may be synchronous or asynchronous. An additional error (RMS$_BUSY) can be encountered by attempting an operation using the same record stream (RAB) from an error or success routine when the main program is awaiting completion of the initial operation. In all cases, it is your responsibility to recognize this possibility and prevent the problem. Most problems can be prevented by using a Wait service. When the Wait service concludes, it returns control to your program.

Note that the Connect operation may be performed asynchronously. If the RAB$V_ASY option is set, a Wait service should follow the Connect service to synchronize with the completion of the Connect service. Another technique is to use the Connect service synchronously and set the RAB$V_ASY option at run time, after the Connect service.

This chapter describes the way you specify run-time options and summarizes the run-time options available to you when opening files, connecting record streams, processing records, and closing files. The run-time options that apply to record processing and to opening and closing a file can usually be preset by file-open and record stream connection values. Some options can be selected after you open a file and connect a record stream.

Note that run-time options discussed in previous sections are only summarized in this chapter. Most of the material in this chapter relates to options not previously described in this document.

9.1 Specifying Run-Time Options

This section describes the way you use the Edit/FDL utility to specify run-time options that are available to your program through the FDL$PARSE and FDL$RELEASE routines. It also describes the use of language statements and OpenVMS RMS (hereafter referred to as RMS) to specify control block values.

You select RMS options by setting appropriate values in RMS control blocks within the data portion of your program. In many cases, you can select these values by using keywords available to you in the language OPEN statement for your application or by taking suitable default values. The values may be selected using keywords in your record and file description statements or they may be selected directly within the OPEN statement.

If your application is written in a language that does not provide keywords for the various features, you can usually select the options using the File Definition Language (FDL).

Predefined FDL attributes can be supplied to your program at run time using the FDL$PARSE routine. This routine also returns the address of the record access block (RAB) to let your program subsequently change RAB values. Some RAB options are not available in FDL and can be set only by directly accessing RAB fields and subfields at run time. To invoke options after record stream connection, your program must have direct access to RMS control block fields using the address of the RAB and symbolic offsets into it.

9.1.1 Using the Edit/FDL Utility

You can use the Edit/FDL utility to specify run-time attributes, such as adding a CONNECT attribute that is used to set a control block value when the FDL$PARSE and FDL$RELEASE routines are called by your program. These attributes preset the values available for opening a file and connecting a record stream.

The following original FDL file was created with the Edit/FDL utility:

IDENT "19-JUL-1994 14:57:37 OpenVMS FDL Editor" SYSTEM SOURCE VMS FILE ORGANIZATION indexed RECORD CARRIAGE_CONTROL carriage_return FORMAT variable SIZE 0 AREA 0 ALLOCATION 8283 BEST_TRY_CONTIGUOUS yes BUCKET_SIZE 18 EXTENSION 2070 AREA 1 ALLOCATION 18 BEST_TRY_CONTIGUOUS yes BUCKET_SIZE 18 EXTENSION 18 KEY 0 CHANGES no DATA_AREA 0 DATA_FILL 100 DATA_KEY_COMPRESSION yes DATA_RECORD_COMPRESSION yes DUPLICATES no INDEX_AREA 1 INDEX_COMPRESSION yes INDEX_FILL 100 LEVEL1_INDEX_AREA 1 PROLOG 3 SEG0_LENGTH 9 SEG0_POSITION 0 TYPE string

Because the Edit/FDL utility does not include run-time attributes, you must add them to the FDL definition. You can specify run-time attributes by specifying the ACCESS, CONNECT and SHARING attributes. For example, if you want to add the CONNECT secondary attribute LOCK_ON_WRITE, you use the EDIT/FDL ADD command. This is illustrated in Example 9-1.

Example 9-1 Specifying Run-Time Attributes

OpenVMS FDL Editor Add to insert one or more lines into the FDL definition Delete to remove one or more lines from the FDL definition Exit to leave the FDL Editor after creating the FDL file Help to obtain information about the FDL Editor (1) Invoke to initiate a script of related questions Modify to change existing line(s) in the FDL definition Quit to abort the FDL Editor with no FDL file creation Set to specify FDL Editor characteristics View to display the current FDL Definition (2) Main Editor Function (Keyword)[Help] : ADD Legal Primary Attributes ACCESS attributes set the run-time access mode of the file AREA x attributes define the characteristics of file area x CONNECT attributes set various VMS RMS run-time options DATE attributes set the data parameters of the file FILE attributes affect the entire VMS RMS data file (3) JOURNAL attributes set the journaling parameters of the file KEY y attributes define the characteristics of key y RECORD attributes set the non-key aspects of each record SHARING attributes set the run-time sharing mode of the file SYSTEM attributes document operating system-specific items TITLE is the header line for the FDL file (4) Enter Desired Primary (Keyword)[FILE] : CONNECT Legal CONNECT Secondary Attributes ASYNCHRONOUS yes/no NOLOCK yes/no BLOCK_IO yes/no NONEXISTENT_RECORD yes/no BUCKET_CODE number READ_AHEAD yes/no CONTEXT number READ_REGARDLESS yes/no END_OF_FILE yes/no TIMEOUT_ENABLE yes/no FAST_DELETE yes/no TIMEOUT_PERIOD number FILL_BUCKETS yes/no TRUNCATE_ON_PUT yes/no KEY_GREATER_EQUAL yes/no TT_CANCEL_CONTROL_O yes/no (5) KEY_GREATER_THAN yes/no TT_PROMPT yes/no KEY_LIMIT yes/no TT_PURGE_TYPE_AHEAD yes/no KEY_OF_REFERENCE number TT_READ_NOECHO yes/no LOCATE_MODE yes/no TT_READ_NOFILTER yes/no LOCK_ON_READ yes/no TT_UPCASE_INPUT yes/no LOCK_ON_WRITE yes/no UPDATE_IF yes/no MANUAL_UNLOCKING yes/no WAIT_FOR_RECORD yes/no MULTIBLOCK_COUNT number WRITE_BEHIND yes/no MULTIBUFFER_COUNT number (6) Enter CONNECT Attribute (Keyword)[-] : LOCK_ON_WRITE (7) CONNECT LOCK_ON_WRITE (8) Enter value for this Secondary (Yes/No)[-] : YES Resulting Primary Section (9) CONNECT LOCK_ON_WRITE yes (10) Press RETURN to continue (^Z for Main Menu)

The following list describes the callouts used in Example 9-1:

1. This menu is the Main Editor Function menu. It displays the Edit/FDL utility commands you can use.
2. The ADD command displays the Legal Primary Attributes menu.
3. The Legal Primary Attributes menu shows the primary attributes. You can either add a new primary attribute or add a secondary attribute to an existing primary attribute. Initially, the FILE primary attribute is the default.
4. The selection of the CONNECT primary attribute displays the Legal CONNECT Secondary Attributes. You could similarly select the ACCESS, FILE, or SHARING options instead of the CONNECT primary attribute to display the Legal Secondary Attributes for the selected primary attribute.
5. This menu shows all the CONNECT secondary attributes you can add to your FDL file.
6. Select the proper CONNECT secondary attribute (in this case, LOCK_ON_WRITE).
7. The Edit/FDL utility verifies that you have selected the secondary attribute.
8. Enter the value that you want the secondary attribute to have (for instance, yes).
9. The Edit/FDL utility verifies the value for the secondary attribute you have chosen.
10. Return to the main menu. If you choose to add another secondary attribute, you will notice that CONNECT is now the default.

The FDL file containing the CONNECT primary attribute with the WRITE_BEHIND secondary attribute is shown in the following example:

IDENT "19-JUL-1994 14:57:37 OpenVMS FDL Editor" SYSTEM SOURCE VMS FILE ORGANIZATION indexed RECORD CARRIAGE_CONTROL carriage_return FORMAT variable SIZE 0 CONNECT WRITE_BEHIND yes AREA 0 ALLOCATION 8283 BEST_TRY_CONTIGUOUS yes BUCKET_SIZE 18 EXTENSION 2070 AREA 1 ALLOCATION 18 BEST_TRY_CONTIGUOUS yes BUCKET_SIZE 18 EXTENSION 18 KEY 0 CHANGES no DATA_AREA 0 DATA_FILL 100 DATA_KEY_COMPRESSION yes DATA_RECORD_COMPRESSION yes DUPLICATES no INDEX_AREA 1 INDEX_COMPRESSION yes INDEX_FILL 100 LEVEL1_INDEX_AREA 1 PROLOG 3 SEG0_LENGTH 9 SEG0_POSITION 0 TYPE string

9.1.2 Using Language Statements and RMS

Language statements such as OPEN may contain keywords, clauses, or other modifiers that correspond to the run-time attributes that are appropriate for opening files, connecting record streams, processing records, and closing files. Some languages use system-defined procedures in place of keywords and clauses. Some languages allow you to call a user-supplied routine (USEROPEN or USERACTION) to set control block values before opening the file.

For example, a user routine could be coded in VAX MACRO to take advantage of control block store macros. (For an example of a VAX BASIC USEROPEN routine, see Example 5-2.) Consult the corresponding language documentation for additional information.

With VAX MACRO, RMS control block macros allow you to establish control block values at assembly time and at run time using the same control block. (The assembly-time macros are placed in a data section of the program; the run-time macros are placed in a code section of the program.) Using VAX MACRO, control blocks are allocated within the program space at assembly time, and it may not be necessary to use the run-time macros because the program can move values to the control block fields using the instruction set. Other languages, however, may not allocate the control blocks within program storage.

If your program has access to the starting location of the control block (a record access block, for instance), the VAX MACRO assembly-time control block macro or the corresponding symbol definition (DEF) macro provides your program with certain symbolic offsets (symbols) that can be used to locate and identify the various fields in the control block. Some languages provide a means of making these symbols available to your program.

For additional information about using the control block macros and control block fields, refer to the OpenVMS Record Management Services Reference Manual.

9.2 Options Related to Opening and Closing Files

Before your program can access the records in a file, it must open the file and connect a record stream. When it finishes processing records and no longer requires access to that file, your program should close the file.

The options available for opening files, connecting record streams, and closing files include file access and file sharing options, file specification options, performance options, record access options, and options for:

• Adding records
• Acting on the file after it is closed (file disposition)
• Using indexed files
• Using magnetic tapes
• Performing nonstandard record processing
• Maintaining data reliability

As described in Chapter 7, the program must declare the desired file-access and file-sharing values before opening an existing file or creating a new file and must specify record-locking and buffering strategies when the file is opened. These options are summarized in the next table:

Option	Description
File access	Specifies the record operations that the current process performs: reading records, locating records, deleting records, adding new records, updating records, accessing blocks, and truncating the file. (For additional information, see Section 7.1.) You specify the file access values using the FDL ACCESS primary attribute or the FAB$B_FAC field.
File sharing	Specifies the types of record operations that the current process allows other file accessors to perform: reading records, locating records, deleting records, adding new records, and updating records. You can also use file sharing to enable the current process to use multiple record streams (or ensure a read-only global buffer cache), operate on the file without record interlocking, or disallow all other accessors from accessing the file. You specify file sharing values using the SHARING primary attribute or the FAB$B_SHR field.
Record locking	Allows you to provide record locking for a shared file under user control. By default, RMS automatically locks records, depending on the file access and file sharing values specified. (For additional information, see Section 7.2.) You specify the record locking values using the CONNECT primary attribute or using the record-processing options (RAB$L_ROP) field 1.

	privacy and legal statement
4506PRO_025.HTML