1 Fip$    File Information Packet routines -- Gregory C. Lowney -- 9/4/84

 A FIP is a data structure designed to hold all information relevant to
 the processing of a file.

 The FIP package provides an easy way to access and manipulate VAX-11 files.
 It allows you to use, from a high level language, those capabilities of
 RMS that were previously relegated to assembly language.
2 FIP
 A FIP is a file information packet.  It is a data structure containing
 within itself several RMS data structures used to manipulate files, as
 well as some additional information for internal reference.

 The FIP package contains one FIP, called FIP0, which is used by default
 when you do not provide an alternate FIP to one of the routines.

 Additional FIPs will be allocated for you automatically when you provide
 a zeroed fip-parameter to any of the routines.  The routine will call
 FIP$ALOFIP, which will create a new fip in free memory and return the
 address to you in the same parameter.
2 Parameters    
 Each routine takes six parameters, in three groups of two.  Any or all
 may be optional, and some may be ignored by a particular routine.

      status = fip$function( [fip], [file], [new], [old], [ofile], [olen] )

 Each parameter is described below.
3  Fip
 This parameter specifies which FIP the routine should act upon.
 The parameter is a modifiable longword, containing the address of a FIP.

 If the longword contains zero, a new FIP is allocated, and its address
 is returned in this longword.

 If this parameter is not provided, the default FIP, FIP0 will be used.
3  File
 If this parameter is provided, it should contain the address of a
 sting descriptor containing the name of the file that should be acted
 upon.  The name will be parsed and put into the FIP specified by the
 Fip parameter before the routine acts upon it.

 A special case is called the Next facility.  A Next descriptor is
 a zero-filled quadword, and when this is provided in the File parameter
 to any routine, and if you have previously parsed a filename containing
 wildcards, then instead of attempting to parse a new name, the routines
 will preform a search operation to get the next file matching the
 previous file specification.  If none is found, an appropriate error
 status (RMS$_NMF, "no more files") is returned.

 The Next facility makes it easier to perform a series of operations on
 a number of files, without explicitly calling FIP$SEARCH.  For example,
 after calling FIP$PARSE( ,'*.*;*' ), then you can keep calling
 FIP$GET_SIZE( ,next,,size,ofile) until you get an error status, and each
 call will return the name and size of the next file in the directory.
3  New
 This parameter varies depending upon the routine, but it is usually
 some information provided to the routine by the calling program.
 For instance, it could be the new file protection mask for FIP$SET_PROT,
 or it could be the FID of the file you want FIP$OPEN_R to access.
3 Old
 This parameter varies depending upon the routine, but it is usually
 a buffer to receive some information from the routine.
 For instance, it could be a longword to recieve the file's owner-uic
 from FIP$GET_UIC, or it could be a two-longword buffer to recieve the
 beginning and ending virtual addresses of a file mapped into virtual
 memory by FIP$MAP.
3 Ofile
 This parameter can contain a descriptor to a string which will recieve
 the name of the file upon which the routine acted.  This name will
 usually be the Resultant File Name, that is the name of a particular
 file with all wild cards resolved.  However, if no such file can be
 found, or the routine does not need this much information, the Expanded
 File Name will be returned, which will have all defaults resolved, but
 may still contain wildcards and probably no version number.

 If there is an error in parsing the given file name, the error status
 RMS$_FNM ("error in filename") will be returned and the output file
 buffer will not be modified.
3 Olen
 This parameter can be a word buffer to recieve the logical length of
 the file name returned in the Ofile parameter.

 If there is an error in parsing the given file name, the error status
 RMS$_FNM ("error in filename") will be returned and the output length
 buffer will not be modified.
2 Return_value
 All routines may be called as subroutines, or as functions returning
 longword values containing their completion status.  This value is
 always a standard DEC status, which may be used by SYS$EXIT or
 SYS$PUTMSG to identify any runtime errors.  As always, odd values
 signify success, while even values specify error of varying severity.
 See HELP ERRORS for information on status values.
2 Lists
 One of the most powerful features of the FIP package is its support of
 File Lists.  In addition to parsing one name, and then being able to 
 search through all the files matching that wildcard description, you 
 can also "parse" a list of filenames, and search your way through 
 successive names as well as wildcard matches.

 To use this capability, you first call FIP$PARSE_LIST, just as you would
 FIP$PARSE, but the file-name parameter may also be a list of names, 
 separated by commas, or a list surrounded by parentheses and separated by
 commas or spaces.

 Thereafter, each call to FIP$SEARCH, or use of the Next facility (see 
 HELP FIP$ INPUT_FILE_CONVENTIONS) will return another file.  All files
 matching a wildcard specification will be returned before the next name
 in the list is parsed.  The status RMS$_NMF ("no more files") signifies
 that the list is totally exhausted.  It is important to remember that
 other error statuses are not fatal: one can get a File Not Found error
 but still go on to successfully find the next file in the list. 
2 Input_file_conventions
 When you need to specify what file a certain routine should operate on,
 there are basically two methods of doing so.  The first method is to
 provide a FIP already pointing to the file, and the second is to provide
 the name of the file.

 If you provide the address of a FIP in the routine's first parameter,
 this FIP will be used, and may be filled in before hand to point to
 the file you want to use.  If this address is zero, a new FIP is
 allocated and its address returned in this parameter.  If this
 parameter is not provided, then the default FIP, FIP0 is used.

 If you provide a filename in the routine's second parameter, then that
 name is put into the specified (or defaulted) FIP, and processed
 appropriately before the routine uses it.

 Note that these methods are not mutually exclusive; either or both
 can be specified, although the information currently in the FIP
 parameter is discarded if the File parameter is provided.

 Another important note is FIP support of lists of filenames.
 See HELP FIP$ LISTS for more information on this topic.
2 Output_file_conventions
 The last two parameters to a routine are used to return the name of
 the file acted upon, and its length.

 If you provided the address of a string descriptor in the fifth
 parameter, then the name of the file will be returned this string.

 If you provided the address of a word buffer in the sixth parameter,
 then it will be filled with the length of the file name.
2 
Routines:                                                              
2 PARSE
     status = fip$parse( [fip], [file], [default], , [ofile], [olen] )

 This will invoke the Parse service, which will expand a file name,
 filling in all defaults and translating logical names.  This must
 be done before any other operations are performed, but is called
 automatically by the other rouines if a File name parameter is provided.

 This routine only fills out the Expanded File Name, which can stil contain
 wildcards and does not point to an actual file.
2 SEARCH
      status = fip$search( [fip], [file], , , [ofile], [olen] )

 This will find an actual file, and fill out its Resultant File Name.
 If the parsed filename contained wildcards, then each call to FIP$SEARCH
 will return the name of the next file matching that specification.
2 DISPLAY
      status = fip$display( [fip], [file], , , [ofile], [olen] )

 This will fill out all the file information areas of the FIP with
 details about the file.  The information can then be retrieved using
 the various information routines.  You must have read access to the
 file to get this information.
2 PARSE_LIST
      status = fip$parse_list( [fip], [file-list], [default], , , )

 This initializes the file-list support feature of the FIP package.
 The string provided as the File parameter may contain a filename,
 or a list of filenames separated by commas, or a list surrounded by
 parentheses and separated by commas or spaces.

 See HELP FIP$ LISTS for more information.
2 OPEN
      status = fip$open_r ( [fip], [file], [fid], , [ofile], [olen] )
      status = fip$open_w ( [fip], [file], [fid], , [ofile], [olen] )
      status = fip$open_rw( [fip], [file], [fid], , [ofile], [olen] )
      status = fip$open_u ( [fip], [file], [fid], , [ofile], [olen] )

 These routines will open a file, either for Read and/or Write access,
 or with a DEC User-File-Open.

 If the third parameter is given, it should contain the address of
 the three word FID of the file you wish to open.  If you open by
 FID instead of by name, you cannot recieve the file's name.
2 CLOSE
      status = fip$close( [fip], [file], , , [ofile], [olen] )

 To close a file previously opened by one of the Open routines.

 Note that even though files are closed automatically when your
 program terminates, that is not the same as performing a Close
 operation upon them.  If you use an information routine to change
 file characteristics (e.g. FIP$SET_PROT), then you must close the
 file using FIP$CLOSE before you exit, or the change will not be
 performed. (See HELP FIP$ INFORMATION_ROUTINES SET_PROT for details.)
2 MAP
      status = fip$map( [fip], [file], [inadr], [retadr], [ofile], [olen] )

 This is used to map a file into virtual memory.

 Inadr is a quadword containing the beginning and ending virtual
 addresses into which the file (or a portion thereof) is to be read.
 If it is not specified, then the file will be added on to the end
 of the user's P0 space.  Currently, there is no provision for files
 which do not fit in the user's virtual memory space.

 Retadr is a quadword to recieve the actual starting and ending addresses
 of the file in virtual memory.
2 UNMAP
      status = fip$unmap( [fip], , , [retadr], [ofile], [olen] )

 This is to release a file which has been mapped into virtual memory
 by FIP$MAP, and free the space it takes up.  This will allow you to
 re-use the same space if you subsequently map another file.
2 DELETE
      status = fip$delete( [fip], [file], , , [ofile], [olen] )

 This will delete a file.
2 REMOVE
      status = fip$remove( [fip], [file], , , [ofile], [olen] )

 This will remove the pointer to a file from a directory.
 It does not actually delete the file, so you should not remove a file
 unless there are other pointers to it.
2 CREATE
      status = fip$create( [fip], [file], , , [ofile], [olen] )

 This can be used to create a standard text file, with variable length,
 carriage-return formatted records.
2 ENTER
      status = fip$enter( [fip], [file], fid, , [ofile], [olen] )

 This will enter a pointer to a file into a directory.
 The Fip and/or File parameters specify the name and location of the
 new pointer, while the 2-WORD FID PROVIDED IN THE THIRD PARAMETER
 identifies the actual file the pointer will refer to.

 You can use FIP$GET_FID to find the fid of a file, which can then
 be entered using FIP$ENTER.
2 RENAME
    * status = fip$rename( [fip], [file], ?, ?, [ofile], [olen] )

 Not yet available.
2 GET_NAME
      status = fip$get_name( [fip], [file], , , [ofile], [olen] )

 To get then name of the file.  If the file exists, then the Resultant
 File Name (RS) will be returned, otherwise the Expanded File Name (ES)
 will be returned.  The appropriate name and its length will, of course,
 be returned in the Ofile and Olen parameters.
2 GET_ES
      status = fip$get_es( [fip], [file], , , [ofile], [olen] )

 Will return the Expanded File Name (ES), which has all defaults, but
 no wildcards resolved.
2 GET_RS
      status = fip$get_rs( [fip], [file], , , [ofile], [olen] )

 Will return the Resultant File Name (RS), which is the actual name of
 the file with all fields filled in, unless the file cannot be found,
 in which case the Expanded File Name will be returned, and an error
 status will result.
2 GET_FID
      status = fip$get_fid( [fip], [file], , [old], [ofile], [olen] )

 Returns the three word File Identification code of the file.
2 GET_DID
      status = fip$get_did( [fip], [file], , [old], [ofile], [olen] )

 Returns the three word File Identification code of the file's
 parent directory.
2 GET_DATE
      status = fip$get_date( [fip], [file], , [old], [ofile], [olen] )

 Returns the file's creation date, in 64-bit format.
2 GET_SIZE
      status = fip$get_size( [fip], [file], , [old], [ofile], [olen] )

 Returns the file's actuall size, in blocks, as a longword value.
2 GET_ALQ
      status = fip$get_alq( [fip], [file], , [old], [ofile], [olen] )

 Returns the file's allocation quantity, as a longword value.
 The ALQ is the second number you see when you do DIRECTORY/SIZE=ALL,
 and is the total number of blocks allocated for the file, even if they
 are not being used.
2 GET_RVN
      status = fip$get_rvn( [fip], [file], , [old], [ofile], [olen] )

 Returns the file's Revision Number as a word value.
 This is the number of times the file has been opened for write access.
2 GET_RDT
      status = fip$get_rdt( [fip], [file], , [old], [ofile], [olen] )

 Returns the file's Revision Date and Time, in 64-bit format.
 This is the last time the file was opened for write access.
2 GET_UIC
      status = fip$get_uic( [fip], [file], , [old], [ofile], [olen] )

 Returns the file owner's User Identification Code, as a longword value.
2 SET_PROT
      status = fip$set_prot( [fip], [file], [new], [old], [ofile], [olen] )

 This will return a file's protection mask, as a word value.
 If the New parameter is provided, it should contain a word value which
 will be set as the file's new protection mask.
 See HELP SPECIFY PROTECTION for more details.
2 WILDCARD
      status = fip$wildcard( [fip], [file], , , [ofile], [olen] )

 This will return true if the file specification contains wildcards,
 or if the FIP is using a file-list containing more than on filename.
 (See HELP FIP$ LIST for details on file-list support.)
2 ALOFIP
      status = fip$alofip( fip )

 This will allocate space in the user's P0 region for a new FIP,
 and call FIP$INIFIP to initialize the structure.  The address of
 the new FIP is returned in the first parameter.

 If this routine is called with a non-zero address, no action is taken.
2 FREFIP
      status = fip$frefip( fip )

 This will free the virtual memory taken up by the FIP, destroying it
 and any information it may contain.  If a file is currently open on
 the FIP, it is closed prior to destruction.  The address of the FIP
 given in the first parameter is cleared.

 If the routine is called with a zero address, no action is taken.
2 INIFIP
      status = fip$inifip( fip )

 This will initialize a FIP, creating the appropriate data structures
 and pointers, clearing and then overwriting the previous data in that
 area.
2 MOVFIP
      status = fip$movfip( [fip], [fip] )

 This will copy the contents of one FIP onto another.
 As usual, if either parameter is not provided, it defaults to the
 default FIP, FIP0.
