Document revision date: 15 July 2002

The Create service constructs a new file according to the attributes you specify in the FAB for the file, whereas the Open service makes an existing file available for processing by your program. Both of these services, invoked by the $CREATE and $OPEN macros respectively, allocate resources within the system to establish access (a path) to a file. You must open or create a file to perform most file operations and any record operations on that file. Applications designed for shared access must declare the type of sharing at this time. The user specifies the various types of shared access by setting bits in the file access control (FAB$B_FAC) and share (FAB$B_SHR) fields in the appropriate FAB.

RMS provides several file-processing options for the Create service. The create-if option (FAB$V_CIF option in the FAB$L_FOP field) requests that the file be created only if it does not exist. If the file does exist in the specified directory, the file is opened, not created. The Open and Create services both establish access to the desired file, but the Create service additionally allocates disk space and performs functions related to allocation.

When you are finished processing a file, you invoke the Close service ($CLOSE macro) to close the file, disconnect all record streams associated with the file, and free all resources allocated to the file. If you do not explicitly invoke the Close service when the program image exits, RMS attempts an implicit close. All resources associated with open files are returned when the files are deaccessed at image rundown time. However, process permanent files are not implicitly closed when an image exits. These are special files that the current CLI opens outside the context of a normal image.

B.3.2 Example of Opening and Creating Files

Example B-2 illustrates the use of the Open, Create, Connect, Get, Put, and Close services to access and copy records from one file to another. Note that the arguments to the $FAB and $RAB macros are listed vertically on separate lines for ease in reading them. However, the argument list must be contiguous and a common programming error is omission of required delimiters and continuation characters when the arguments are listed in this manner.

Example B-2 Use of the Create, Open, and Close Services

.TITLE COPYFILE ; ; This program copies the input file to the output file. ; .PSECT DATA,WRT,NOEXE INFAB: $FAB FNM = <INFILE:>,- ; Primary input file name DNM = <.INV> ; Default input file type INRAB: $RAB FAB = INFAB,- ; Pointer to FAB ROP = RAH,- ; Read-ahead option UBF = REC_BUFF,- ; Record buffer USZ = REC_SIZE ; and size OUTFAB: $FAB FNM = <OUTFILE:>,- ; Primary output file name DNM = <.INV>,- ; Default output file name FOP = CTG,- ; Make contiguous file FAC = <PUT>,- ; Open for PUT operations SHR = <NIL>,- ; Exclusive file access MRS = REC_SIZE,- ; Maximum record size RAT = CR ; Implied carriage control OUTRAB: $RAB FAB = OUTFAB,- ; Pointer to FAB ROP = WBH,- ; Write-behind option RBF = REC_BUFF ; Output uses same buffer ; as input ; REC_SIZE = 132 ; Maximum record size REC_BUFF: .BLKB REC_SIZE ; Record buffer .PSECT CODE,NOWRT,EXE ; ; Initialization - Open input and output files and connect streams ; .ENTRY COPYFILE,^M<R6> ; Save R6 $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 for output OUTFAB+FAB$L_ALQ $CREATE FAB=OUTFAB ; Create output file BLBC R0,EXIT3 ; Quit on error $CONNECT RAB=OUTRAB ; Connect to output BLBS R0,READ ; Branch to READ loop BRB EXIT4 ; Trap error EXIT1: MOVAL INFAB,R6 ; Error: Keep FAB address BRB F_ERR ; Signal file error EXIT2: MOVAL INRAB,R6 ; Keep RAB address BRB R_ERR ; Signal record error EXIT3: MOVAL OUTFAB,R6 ; Keep FAB address BRB F_ERR ; Signal record error EXIT4: MOVAL OUTRAB,R6 ; If error, retain RAB addr. BRB R_ERR ; Signal record error ; ; Copy records loop ; READ: $GET RAB=INRAB ; Get a record BLBS R0,WRITE ; Write the record CMPL R0,#RMS$_EOF ; Was error end-of-file? BEQL DONE ; Successful completion BRB EXIT2 ; Error otherwise WRITE: MOVW INRAB+RAB$W_RSZ, - ; Input RAB sets record OUTRAB+RAB$W_RSZ ; size for output RAB $PUT RAB=OUTRAB ; Write the record BLBC R0,EXIT4 ; Quit on error BRB READ ; Go back for more ; ; Close files, signal any errors, and exit ; F_ERR: PUSHL FAB$L_STV(R6) ; Push STV and STS of FAB PUSHL FAB$L_STS(R6) ; on the stack CALLS #2, G^LIB$SIGNAL ; Signal error BRB EXIT R_ERR: PUSHL RAB$L_STV(R6) ; Push STV and STS of RAB PUSHL RAB$L_STS(R6) ; on the stack CALLS #2, G^LIB$SIGNAL ; Signal error DONE: $CLOSE FAB=INFAB ; Close input $CLOSE FAB=OUTFAB ; and output EXIT: RET ; Return with status in R0 .END COPYFILE

This example illustrates how you can use the sequential file organization to create a new file by copying records from an existing file. The newly created file and the source file have variable-length records.

This example assumes that an external program has identified the input file as a search list logical name using this statement:

$ ASSIGN [INV]30JUN85,[INV.OLD]30JUN85 INFILE:

This directs RMS to look for the input file in directory [INV] first, and if it does not find the file, it should look in directory [INV.OLD].

The program also specifies the default file type .INV for the input file using this statement:

DNM=<.INV> ; Default input file name

Next the program configures the RAB used for the input file (labeled INRAB). The first argument links the RAB to the associated FAB (INFAB) and this is the only required argument to a RAB. The rest of the arguments specify the read-ahead option (described in later text) and the record buffer for the input file. The Get service uses the user record buffer address (UBF) field and the user record buffer size (USZ) field as inputs to specify the record buffer and the record size, respectively.

The program then configures the FAB for the output file. The first argument uses the FNM field to equate the file name to the externally defined logical name OUTFILE. After the program specifies the default file specification extension for the output file, it specifies three additional FAB fields.

First it directs RMS to allocate contiguous space for the output file by setting the CTG bit in the FAB$L_FOP field of the FAB.

Next the program uses a program-defined variable to store the value 132 in the MRS field:

MRS=REC_SIZE REC_SIZE= 132

The program then specifies that each record is to be preceded by a line feed and followed by a carriage return whenever the record is output to a line printer or terminal:

RAT=CR

Because the program alternately reads and then writes each record, the input file and the output file may share the same buffer. However, because the Put service does not have access to the UBF and UBZ fields, the output RAB defines the buffer using the RBF and the RSZ fields.

Note that the UBF, USZ, and RBF values are set prior to run time, but that the RSZ value is set at run time, just prior to invocation of the Put service. This is done because the input file contains variable-length records and the Put service relies on the Get service to supply each record's size by way of the RSZ field, an INRAB output field.

The following statement from the sample program illustrates this feature:

WRITE: MOVW INRAB+RAB$W_RSZ, - ; Input RAB sets record OUTRAB+RAB$W_RSZ ; size for output RAB

The run-time processing macros for the input file consist of a $OPEN, a $CONNECT, a $GET, and a $CLOSE macro. Because the input file already exists, the program accesses it with a $OPEN macro. The sole argument to this macro identifies the FAB to the Open service:

$OPEN FAB=INFAB

Next, the program connects a record stream to the input file by calling the Connect service and specifying INRAB as the appropriate RAB:

$CONNECT RAB=INRAB

Note that upon completion of each service call, the program tests the condition value in R0 returned by the service before proceeding to the next call. If the call fails, the program exits with the appropriate control block address in R6.

After creating the output file and establishing its record stream, the program begins a processing loop in which the Get service reads a record from the input file and the Put service writes the record to the output file. When all file records are copied, as indicated by the detection of the end of the file, the program exits to label DONE, which closes both files.

The Close service disconnects the record stream for all RABs connected to the specified FAB. In a multistream environment (more than one RAB can be connected to a single FAB), a program may disconnect individual record streams using the Disconnect service.

B.3.3 Example of Creating a Multiple-Key Indexed File

Example B-3 creates an indexed file on a remote node from a sequential file on the local node. The indexed file contains three keys: a segmented primary key and two simple alternate keys. The segmented primary key includes the customer's last name, the first letter of the customer's first name, and the customer's middle initial.

Example B-3 Use of the Create Service for an Indexed File

.TITLE CREATEIDX - CREATE INDEXED FILE .IDENT /V001/ ; ; This program creates an indexed file with three keys from a ; sequential file containing a name and address list. The record ; format of the input file is shown below: ; ; First Name Column 00-10 ; Middle Initial Column 11-11 ; Last Name Column 12-26 ; Street Column 27-46 ; City Column 47-58 ; State Column 59-60 ; Zip Code Column 61-65 ; Reserved for ; new data Column 66-end of record ; ; The input and output files are specified by the logical names SRC ; and DST, respectively. For example: ; ; $ DEFINE SRC DBB1:[TEST]INPUT.DAT ; $ DEFINE DST TRNTO::DRA4:[RMS.FILES]OUTPUT.DAT ; $ RUN CREATEIDX ; ;******************************************************************** .SBTTL Control block and buffer storage .PSECT DATA NOEXE,LONG ; ; Define the source file FAB and RAB control blocks. ; SRC_FAB: $FAB FAC=<GET>,- ; File access for GET only FOP=<SQO>,- ; DAP file transfer mode FNM=<SRC:> ; Name of input file SRC_RAB: $RAB FAB=SRC_FAB,- ; Address of associated FAB RAC=SEQ,- ; Sequential record access UBF=BUFFER,- ; Buffer address USZ=BUFFER_SIZE ; Buffer size ; ; Define the destination file FAB and RAB control blocks. ; DST_FAB: $FAB FAC=<PUT>,- ; File access for PUT only FOP=CTG,- ; Allocate contiguous SHR = <NIL>,- ; Exclusive file access FNM=<DST:>,- ; Name of output file MRS=128,- ; Maximum record size RFM=VAR,- ; Variable length records RAT=<CR>,- ; Implied carriage control ORG=IDX,- ; Indexed file organization XAB=DST_KEY0 ; Address of start of XAB chain DST_RAB: $RAB FAB=DST_FAB,- ; Address of associated FAB MBF=3,- ; Use 3 buffers RAC=KEY,- ; Random record writes RBF=BUFFER,- ; Buffer address ROP=LOA,- ; Specify initial fill size RSZ=BUFFER_SIZE ; Buffer size ; ; Define a key definition XAB for the primary key. ; DST_KEY0: ; Primary key is Name $XABKEY REF=0,- ; Key reference number DAN=0,- ; Define data XABALL DFL=1536,- ; Define data fill of 75% FLG=<DUP>,- ; Allow duplicate keys DTP=DSTG,- ; Descending sort order IAN=1,- ; Define index XABALL IFL=1536,- ; Initial index fill 75% PROLOG=3,- ; Request prolog 3 POS=<12,0,11>,- ; Key segment positions SIZ=<15,1,1>,- ; Key segment lengths NXT=DST_KEY1 ; Address of next XAB in chain ; ; Define key definition XABs for the alternate keys. ; DST_KEY1: ; 1st alternate key is City $XABKEY REF=1,- ; Key reference number DAN=2,- ; Data level (SIDR) XABALL IAN=2,- ; Index XABALL IFL=768,- ; Initial index fill 75% POS=47,- ; Starting key position SIZ=12,- ; Key size FLG=<CHG,DUP>,- ; Duplicates and changes NXT=DST_KEY2 ; Address of next XAB in chain DST_KEY2: ; 2nd alternate key is State $XABKEY REF=2,- ; Key reference number DAN=2,- ; Data level (SIDR) XABALL IAN=2,- ; Index XABALL IFL=768,- ; Initial index fill 75% POS=59,- ; Starting key position FLG=<CHG,DUP>,- ; Duplicates and changes SIZ=2,- ; Key size NXT=DST_ALL0 ; Designate next XAB ; ; Define allocation control XABs to define multiple areas ; DST_ALL0: $XABALL AID=0,- ; Data area definition ALQ=328,- ; Allocation quantity and AOP=<CBT>,- ; contiguous best try BKZ=4,- ; Bucket size of 4 blocks DEQ=112,- ; Default extension quantity NXT=DST_ALL1 ; Designate next XAB DST_ALL1: $XABALL AID=1,- ; Primary key index area ALQ=8,- ; Allocation quantity and AOP=<CBT>,- ; contiguous best try BKZ=4,- ; Bucket size of 4 blocks DEQ=4,- ; Default extension quantity NXT=DST_ALL2 ; Designate next XAB DST_ALL2: $XABALL AID=2,- ; Alternate key data area ALQ=112,- ; Allocation quantity and AOP=<CBT>,- ; contiguous best try BKZ=2,- ; Bucket size of 2 blocks DEQ=38,- ; Default extension quantity NXT=0 ; No more XABs ; ; Allocate buffer to the size of the largest record being read. ; BUFFER: .BLKB 66 ; Buffer for input and output BUFFER_SIZE=.-BUFFER ; Buffer size ;********************************************************************* .SBTTL Mainline .PSECT CODE NOWRT,BYTE ; ; Start of program ; .ENTRY CREATEIDX,^M<R6> ; Entry point ; ; Open the source and destination files. ; $OPEN FAB=SRC_FAB ; Open input file BLBC R0,EXIT1 ; Branch on failure $CONNECT RAB=SRC_RAB ; Connect input record stream BLBC R0,EXIT2 ; Branch on failure $CREATE FAB=DST_FAB ; Create output file BLBC R0,EXIT3 ; Branch on failure $CONNECT RAB=DST_RAB ; Connect output record stream BLBC R0,EXIT4 ; Branch on failure BRB LOOP ; Bypass signaling code EXIT1: MOVAL SRC_FAB,R6 ; Keep FAB address BRB F_ERR ; Signal error EXIT2: MOVAL SRC_RAB,R6 ; Keep RAB address BRB R_ERR ; Signal error EXIT3: MOVAL DST_FAB,R6 ; Keep FAB address BRB F_ERR ; Signal error EXIT4: MOVAL DST_RAB,R6 ; Keep RAB address BRB R_ERR ; Signal error ; ; Transfer records until end-of-file is reached. ; LOOP: $GET RAB=SRC_RAB ; Read next rec from input file BLBS R0,PUT ; Branch on success CMPL R0,#RMS$_EOF ; Was it end-of-file (EOF)? BNEQ EXIT2 ; Branch if not EOF error BRB CLOSE ; Close and exit if EOF PUT: $PUT RAB=DST_RAB ; Write 66-byte record to output BLBS R0,LOOP ; On success, continue loop BRB EXIT4 ; On error, signal and exit ; ; Close the source and destination files. ; F_ERR: PUSHL FAB$L_STV(R6) ; Push STV and STS fields PUSHL FAB$L_STS(R6) ; on stack CALLS #2, G^LIB$SIGNAL ; Signal file error BRB EXIT ; Exit R_ERR: PUSHL RAB$L_STV(R6) ; Push STV and STS fields PUSHL RAB$L_STS(R6) ; on stack CALLS #2, G^LIB$SIGNAL ; Signal file error CLOSE: $CLOSE FAB=DST_FAB ; Close output file $CLOSE FAB=SRC_FAB ; Close input file EXIT: $EXIT_S ; Exit .END CREATEIDX ; Specify starting address

This example program creates an indexed file with a primary key and two alternate keys that are defined by appropriate key definition control blocks (XABKEY). For efficiency, the file is divided into areas consisting of a data area and an index area for each key using multiple allocation control blocks (XABALL).

In each XABKEY, the DAN and IAN arguments (XAB$B_DAN and XAB$B_IAN fields) indicate the area identification number (AID) of the corresponding XABALL. By setting the RAB$V_LOA bit in RAB field RAB$L_ROP, the program directs RMS to use the DFL and IFL arguments (XAB$W_DFL and XAB$W_IFL fields) to determine the maximum initial fill size (in bytes) for data and index buckets (each bucket contains the number of blocks specified in the XABALL BKZ argument, XAB$B_BKZ field).

These are the XABKEY and XABALL control blocks for the primary key (the NAME key) in this example:

DST_KEY0: ; Primary key is Name $XABKEY REF=0,- ; Key reference number DAN=0,- ; Define data XABALL DFL=1536,- ; Define data fill of 75% FLG=<DUP>,- ; Allow duplicate keys DTP=DSTG,- ; Descending sort order IAN=1,- ; Define index XABALL IFL=1536,- ; Initial index fill 75% PROLOG=3,- ; Request prolog 3 . . . DST_ALL0: $XABALL AID=0,- ; Data area definition ALQ=328,- ; Allocation quantity and AOP=<CBT>,- ; contiguous best try BKZ=4,- ; Bucket size of 4 blocks DEQ=112,- ; Default extension quantity NXT=DST_ALL1 ; Designate next XAB DST_ALL1: $XABALL AID=1,- ; Primary key index area ALQ=8,- ; Allocation quantity and AOP=<CBT>,- ; contiguous best try BKZ=4,- ; Bucket size of 4 blocks DEQ=4,- ; Default extension quantity NXT=DST_ALL2 ; Designate next XAB

The allocation information was obtained using the File Definition Language (FDL) editor which is especially useful when you are creating large indexed files. The DCL commands CREATE/FDL and CONVERT can be used to create files by using an FDL file produced by the Edit/FDL utility, without any programming. Instead of using the multiple XABs for the key definition and area allocations in this program, a simpler approach is to use the FDL file produced by the Edit/FDL utility by invoking the FDL routines FDL$PARSE and FDL$RELEASE (for more information on these routines, see the OpenVMS Utility Routines Manual).

Fixed-length records are copied from the sequential input file on the local node to the indexed file on the remote node. Each variable-length output record is initially 66 bytes long and may be extended to a maximum of 128 bytes.

	privacy and legal statement
4523PRO_040.HTML