The FILE Command

FILE commands are processed by FIO (File Input Output Support) on behalf of all other SUs. FIO assumes the basic syntax:-

FILE su_id stream_no file_spec options

as described in the User's Manual. Beyond this it makes no other assumptions so SU writers are free to dream up any options they like. FIO collects all the information from the FILE commands into an internal data structure and then SUs can use FIO_QUERY and FIO_OPTION_VALUE to interrogate them.

The main query routine is FIO_QUERY which can test any element of any FILE command. Multiple FILE commands with the same SU id and stream number can be supplied as the way to represent file concatenation. FIO_QUERY incorporates the concept of FIRST, NEXT and CURRENT as a way of stepping through such multiple commands. For example:-

      include 'su_mnemonics.inc'

      character*80  c_file
      logical       file_exists, fio_query


      file_exists = FIO_QUERY( KSU_USR, 2, 'FIRST_FILE', c_file)
      do while ( file_exists )
        print *, c_file
        file_exists = FIO_QUERY( KSU_USR, 2, 'NEXT_FILE', c_file)
      enddo

will print all the file names associated with the USR 2 stream, while:-

      file_exists = FIO_QUERY( KSU_USR, 2, 'CURRENT_FILE', c_file)
      if ( file_exists ) then
        print *, c_file
      else
        print *, 'No current file'
      endif

prints the current file, which is the first file until moved on by FIO_QUERY.

Having positioned on a FILE command, options can be examined. Suppose we have:-

FILE USR 2 MY_OPTION MY_VALUE=3

then:-

      character*20  option_str, value_str
      logical       fio_query

      if ( FIO_QUERY( KSU_USR, 2, 'MY_OPTION', option_str) )
     +   print *, 'Option string: ', option_str
      if ( FIO_QUERY( KSU_USR, 2, 'MY_VALUE', value_str) )
     +   print *, 'Value string: ', value_str

produces:-

Option string:
Value string: 3

FIO_QUERY can be used to see if an option exits (test the function result) and if so what, if any, value has been associated. Often values are numeric and defaults provided if omitted and then FIO_OPTION_VALUE can be used to relieve some of the tedium. For example:-

      include  'token.inc'

      integer       val
      logical       fio_query

      value = 10
      call FIO_OPTION_VALUE( KSU_USR , 2 , 'MY_VALUE' ,
     +                       KTKN_INT , 1 , 27 , val )

works as follows:-

1. If no MY_VALUE has been supplied, leave val set to 10.

2. If MY_VALUE has been supplied translate it as integer. If it is not a valid integer or is outside the passed range of 1 to 27 report an error and leave val unchanged.

3. If supplied value is valid and in range update val.

KTKN_INT can be replaced by KTKN_FLOAT for floating point numbers.