Using libpsio.a

The following code illustrates the basic use of the library, as well as when/how the psio_init() and psio_done() functions should be called in relation to initialization of libipv1. (See section 3.1 later in the manual for a description of the basic elements of C-language PSI3 program.)

#include <stdio.h>
#include <libipv1/ip_lib.h>
#include <libpsio/psio.h>
#include <libciomr/libciomr.h>

FILE *infile, *outfile;

int main()
{
  int i, M, N;
  double enuc, *some_data;
  psio_address next;  /* Special page/offset structure */

  ffile(&infile,"input.dat",2);
  ffile(&outfile,"output.dat",1);
  ip_set_uppercase(1);
  ip_initialize(infile,outfile);
  ip_cwk_add(":DEFAULT");
  ip_cwk_add(progid);

  /* Initialize the I/O system */
  psio_init();

  /* Open the file and write an energy */
  psio_open(31, PSIO_OPEN_NEW);
  enuc = 12.3456789;
  psio_write_entry(31, "Nuclear Repulsion Energy", (char *) &enuc,
                   sizeof(double));
  psio_close(31,1);

  /* Read M rows of an MxN matrix from a file */
  some_data = init_matrix(M,N);

  psio_open(91, PSIO_OPEN_OLD);
  next = PSIO_ZERO;/* Note use of the special macro */
  for(i=0; i < M; i++)
      psio_read(91, "Some Coefficients", (char *) (some_data + i*N),
                N*sizeof(double), next, &next);
  psio_close(91,0);

  /* Close the I/O system */
  psio_done();

  ip_done();
}

char *gprgid()
{
   char *prgid = "CODE_NAME";
   return(prgid);
}

The interface to the PSI3 I/O system has been designed to mimic that of the old wreadw() and wwritw() routines of libciomr (see the next section of this manual). The table of contents system introduces a few complications that users of the library should be aware of:

• As pointed out earlier, deletion of TOC entries is allowed using psio_tocdel() and psio_tocclean(). However, since only the TOC reference is removed from the file and the corresponding data is not, a data hole will be left in the file if the deleted entry was not the last one in the TOC. A utility function designed to "defrag" a PSI file may become necessary if such holes ever present a problem.
• One may append data to an existing TOC entry by simply writing beyond the entry's current boundary; the ending address data in the TOC will be updated automatically. However, no safety measures have been implemented to prevent one from overwriting data in a subsequent entry thereby corrupting the TOC. This feature/bug remains because (1) it is possible that such error checking functions may slow the I/O codes significantly; (2) it may be occasionally desirable to overwrite exiting data, regardless of its effect on the TOC. Eventually a utility function which checks the validity of the TOC may be needed if this becomes a problem, particularly for debugging purposes.