Using libpsio.a

The following code illustrates the basic use of the library, as well as when/how the psio_init(), psio_ipv1_config(), 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 PSI3 program.)

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

extern "C" {
  FILE *infile, *outfile;
  char *psi_file_prefix;
}

using namespace psi::MODULE_NAME;

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

  psi_start(&infile,&outfile,&psi_file_prefix,argc-1, argv+1, 0);
  ip_cwk_add(":MODULE_NAME"); // MODULE_NAME in all caps
  tstart(outfile);

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

  /* 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();
  tstop(outfile);
  ip_done();
  psi_stop(infile, outfile, psi_file_prefix);
  exit(0);
}

extern "C" {
  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.