HP OpenVMS Systems Documentation

HP Pascal for OpenVMS
User Manual

When you use OPEN to open a file, RMS applies certain defaults when attempting to locate the physical file. Table 7-1 presents these defaults.

The OPEN procedure includes a default file-name parameter. Using this parameter, you can access the RMS default file-name parameter to set file-specification defaults. Consider the following example:

VAR
    My_File : VARYING [20] OF CHAR;
    My_File_Var : TEXT;
BEGIN
My_File := 'foo.bar';
OPEN( FILE_NAME := My_File,
      FILE_VARIABLE := My_File_Var,
      DEFAULT := '[another.dir]' );

The OPEN statement in the previous example opens the file called [ANOTHER.DIR]FOO.BAR. RMS applies the defaults in Table 7-1 to determine the node, the device, and the version number of the file.

For More Information:

• On file specifications (OpenVMS User's Manual)
• On the OPEN procedure (HP Pascal for OpenVMS Language Reference Manual)

Table 7-2 presents the status of RMS FAB fields when you call the OPEN procedure. If a field is not included in the following tables, it is initialized to zero.

Table 7-3 presents the status of RMS RAB fields when you call the OPEN procedure. If a field is not included in the following table, it is initialized to zero.

Table 7-4 presents the status of RMS XAB fields when you call the OPEN procedure. If a field is not included in the following table, it is initialized to zero.

Table 7-5 presents the status of RMS Name Block fields when you call the OPEN procedure. If a field is not included in the following table, it is initialized to zero.

For More Information:

• On opening indexed files ( Section 7.1.1)

HP Pascal determines a default line limit for TEXT files by translating the logical name PAS$LINELIMIT as a string of decimal digits. If this logical name has not been defined, there is no default line limit. You can override the default by calling the LINELIMIT procedure.

For More Information:

• On LINELIMIT (HP Pascal for OpenVMS Language Reference Manual)

The user-action parameter of the OPEN procedure allows you to access RMS facilities not explicitly available in the HP Pascal language by writing a function that controls the opening of the file. Inclusion of the user-action parameter causes the run-time library to call your function to open the file instead of calling RMS to open it according to its normal defaults.

The user-action parameter of the CLOSE procedure is similar to that of the OPEN procedure. It allows you to access RMS facilities not directly available in HP Pascal by writing a function that controls the closing of the file. Including the user-action parameter causes the run-time library to call your function to close the file instead of calling RMS to close it according to its normal defaults.

When an OPEN or CLOSE procedure is executed, the run-time library uses the procedure's parameters to establish the RMS file access block (FAB) and the record access block (RAB), as well as to establish its own internal data structures. These blocks are used to transmit requests for file and record operations to RMS; they are also used to return the data contents of files, information about file characteristics, and status codes.

In order, the three parameters passed to a user-action function by the run-time library are as follows:

• FAB address
• RAB address
• File variable

A user-action function is usually written in HP Pascal and includes the following:

• Modifications to the FAB or RAB, or both (optional)
• $OPEN and $CONNECT for existing files or $CREATE and $CONNECT for new files (required)
• Status check of the values returned by $OPEN or $CREATE and $CONNECT (required)
• Storage of FAB and RAB values in program variables (optional)
• Return of success or failure status value for the user-action function (required)

Example 7-1 shows an HP Pascal program that copies one file into another. The program features two user-action functions, which allow the output file to be created with the same size as the input file and to be given contiguous allocation on the storage media.

[INHERIT( 'SYS$LIBRARY:STARLET' )]
PROGRAM Contiguous_Copy( F_In, F_Out );

{
The input file F_In is copied to the output file F_Out.
F_Out has the same size as F_In and has contiguous
allocation.
}

TYPE
   FType = FILE OF VARYING[133] OF CHAR;

VAR
   F_In, F_Out    : FType;
   Alloc_Quantity : UNSIGNED;

FUNCTION User_Open( VAR FAB : FAB$TYPE;
                    VAR RAB : RAB$TYPE;
                    VAR F   : FType) : INTEGER;
   VAR
     Status : INTEGER;
   BEGIN          { Function User_Open }
   {Open file and remember allocation quantity }
   Status := $OPEN( FAB );
   IF ODD( Status ) THEN
      Status := $CONNECT( RAB );
   Alloc_Quantity := FAB.FAB$L_ALQ;
   User_Open := Status;
   END;           { Function User_Open }

FUNCTION User_Create( VAR FAB : FAB$TYPE;
                      VAR RAB : RAB$TYPE;
                      VAR F   : FType ) : INTEGER;
   VAR
     Status : INTEGER;
   BEGIN          { Function User_Create }
   { Set up contiguous allocation }
   FAB.FAB$L_ALQ := Alloc_Quantity;
   FAB.FAB$V_CBT := FALSE;
   FAB.FAB$V_CTG := TRUE;
   Status := $CREATE( FAB );
   IF ODD( Status ) THEN
      Status := $CONNECT( RAB );
   User_Create := Status;
   END;           { Function User_Create }

BEGIN             { main program }
{ Open files }
OPEN( F_In, HISTORY := READONLY, USER_ACTION := User_Open );
RESET(F_In );
OPEN( F_Out, HISTORY := NEW, USER_ACTION := User_Create );
REWRITE( F_Out );

{ Copy F_In to F_Out }
WHILE NOT EOF( F_In ) DO
   BEGIN
   WRITE( F_Out, F_In_^ );
   GET( F_In );
   END;

{ Close files }
CLOSE( F_In );
CLOSE( F_Out );
END.              { main program }

In this example, the record types FAB$TYPE and RAB$TYPE are defined in SYS$LIBRARY:STARLET, which the program inherits. The function User_Open is called as a result of the OPEN procedure for the input file F_In. The function begins by opening the file with the RMS service $OPEN. If $OPEN succeeds, the value of Status is odd; in that case, $CONNECT is performed. The allocation quantity contained in the FAB.FAB$L_ALQ field of the FAB is assigned to a variable so that this value can be used in the second user-action function. User_Open is then assigned the value of Status (in this case, TRUE), which is returned to the main program.

The function User_Create is called as a result of the OPEN procedure for the output file F_Out. The function assigns the allocation quantity of the input file to the FAB.FAB$L_ALQ field of the FAB, which contains the allocation size for the output file. The FAB field FAB.FAB$V_CBT is set to FALSE to disable the request that file storage be allocated contiguously on a best try basis. Then, the FAB field FAB.FAB$V_CTG is set to TRUE so that contiguous storage allocation is mandatory. Finally, the RMS service $CREATE is performed. If $CREATE is successful, $CONNECT will be done and the function return value will be that of $CREATE.

Once the OPEN procedures have been performed successfully, the program can then accomplish its main task, copying the input file F_In to the output file F_Out, which is the same size as F_In and has contiguous allocation. The last step in the program is to close the files.

For More Information:

• On the OPEN and CLOSE procedures (HP Pascal for OpenVMS Language Reference Manual)
• On RMS file access blocks ( Section 7.1.6.2)