Introduction to NCAR's Mass Storage System

Obtaining MSREAD/MSWRITE error messages with MSERROR

The subroutines and functions discussed in this section are in the MSS library, which you need to include in the compile (or loader) command. The following example includes the MSS library with the f90 command:

f90 -L /usr/local/lib -l mss test.f

To obtain the error message associated with a failed MSREAD or MSWRITE attempt from within your Fortran or C program, use MSERROR. In Fortran:

CHARACTER*80  ebuf
CALL MSERROR(ebuf)
PRINT *,ebuf

The MSERROR routine places the error message of the last failed MSREAD or MSWRITE into ebuf. You may then format this message as you like.

Calling MSERROR is only valid immediately after the failed attempt of MSREAD or MSWRITE.

The C version looks like this:

char  *ebuf
ebuf = MsError();

See the mserror man page for more information about the Fortran and C versions.

Accessing MSS files from Fortran and C using MSREAD/MsRead

The subroutines and functions discussed in this section are in the MSS library, which you need to include in the compile (or loader) command. The following example includes the MSS library with the f90 command:

f90 -L /usr/local/lib -l mss test.f

You can read (transfer) an MSS file to disk from a Fortran or C program by using the MSREAD/MsRead routines. It performs much like the msread shell command.

In Fortran, the MSREAD subroutine has the following syntax:

CALL  MSREAD(ier,  lflnm,  mflnm,  pass,  opts)

where:

ier

The integer return code. A 0 means success; a nonzero may imply an error. If ier = 3, a file with the name in lflnm already exists and the transfer did not occur.

lflnm

A character string or variable containing the local filename.

mflnm

A character string or variable containing the MSS filename.

pass

A character string or variable containing the read password of the MSS file. If there is not a read password on the MSS file, specify a blank string for Fortran or a null pointer (0) for C.

opts

A character string or variable containing a list of options. Specify a blank string if you do not want options assigned to this file.

The syntax of the C function is:

ier  =  MsRead(lflnm,  mflnm,  pass,  opts);

The arguments and return code are the same as those described for the Fortran version.

Example

Read MSS file /PAT/file.to.read, which has a read password of READPW to the disk file named disk.file:

CALL MSREAD(ier, 'disk.file', '/PAT/file.to.read','READPW',' ')

See the msread man page for more information about the Fortran and C versions.

Waiting for asynchronous MSS reads and writes using MSRECALL

---

The subroutines and functions discussed in this section are in the MSS library, which you need to include in the compile (or loader) command. The following example includes the MSS library with the f90 command:

f90 -L /usr/local/lib -l mss test.f

Sometimes you need to be sure that a read or write has completed before doing another read or write. You can use the Fortran or C-callable MSRECALL routine within your program to wait for the completion of an asynchronous MSS transfer that has been initiated via the "nowait" option of the MSREAD or MSWRITE call.

In general usage, you would make a series of asynchronous transfer requests using MSWRITE or MSREAD, and then at some later point in the program, call MSRECALL to wait for a particular transfer to complete. When control returns, you can use MSRECALL again for the next transfer.

Examples

Fortran example:

 CALL MSREAD(IER, "/usr/tmp/file1", "/MSS/FILE1", " ", "NOWAIT")
       ...
 CALL MSRECALL("/usr/tmp/file1")
       ... MSREAD is complete

C example:

char[] loc_flnm = "/usr/tmp/file1";
char[] mss_flnm = "/MSS/FILE1";
if(MsRead(loc_flnm, mss_flnm, 0, "NOWAIT"))
goto read_failed;
...
MsRecall(loc_flnm);
/* ...MsRead is complete... */

See the msrecall man page for more information about the Fortran and C versions.

Checking the status of asynchronous reads/writes with MSWAIT

---

The subroutines and functions discussed in this section are in the MSS library, which you need to include in the compile (or loader) command. The following example includes the MSS library with the f90 command:

f90 -L /usr/local/lib -l mss test.f

The MSWAIT routine checks on the status of files read or written asynchronously via the MSREAD or MSWRITE routines.

The Fortran syntax is:

istat  =  MSWAIT ()

In general usage, you would make a series of asynchronous transfer requests using the MSWRITE or MSREAD subroutines, and then at some later point in the program, call MSWAIT to verify that all the files with the NOWAIT option have been transferred. If all asynchronous read and/or write requests have completed, MSWAIT returns with 0. Otherwise, MSWAIT returns with 1.

It is not necessary to use this function when reading or writing files asynchronously. It is merely a convenience for users who want to verify that the file transfers have actually taken place.

The C syntax is:

MsWait ();

See the mswait man page for more information about the Fortran and C versions.

Writing files to the MSS from Fortran and C with MSWRITE

---

The subroutines and functions discussed in this section are in the MSS library, which you need to include in the compile (or loader) command. The following example includes the MSS library with the f90 command:

f90 -L /usr/local/lib -l mss test.f

To copy a file to the MSS from your Fortran or C program, use the MSWRITE routine. In Fortran, it has the following arguments:

       CALL  MSWRITE(ier,  lflnm,  mflnm,  pass,  retpd,  opts)

where:

ier

The integer return code. A code of 0 (zero) implies success. A nonzero return code means there was an error. See MSERROR.

lflnm

A character string or variable containing the local filename.

mflnm

A character string or variable containing the MSS filename.

pass

The read and competedwrite passwords to be assigned to this file. The format is rpass,wpass. Specify a blank string if you do not want passwords assigned to this file.

opts

A string made up of keywords, some of which are followed by a value. Some of the most common keywords used are:

   CMNT=string     Comment field (80 chars max).
   FORMAT=fmt      Formats are TR (default), CH, and BI.
   NOWAIT          Enables the asynchronous feature.
   PROJ=string     The eight-digit project number to use for the file.
   REL[IABILITY]=value     Class of service reliability you want.
   USA[GE]=value   Class of service usage you want.

For a complete list of options, please refer to the mswrite man page for the Fortran-callable version (man 3f mswrite). Also see "msclass" for more information on Class of Service.
Example:

   CHARACTER*80 OPTS
   OPTS = "REL=ECONOMY"

   CALL MSWRITE(IER, "file01", "/USER/file01", " ", 365, OPTS)

This would write the local file "file01" to the MSS. The name of the MSS file would be "/USER/file01". There are no read or write passwords, the retention period would be 365 days, and it would be "economy" reliability (single tape copy), rather than the default "standard" reliability (two tape copies).

retpd

An integer retention period. Specify 1-4096 days.

The C function is very similar:

   ier  =  MsWrite(lflnm,  mflnm,  pass,  retpd,  opts)

The arguments and return code are the same as for the Fortran version.

CAUTION: You must explicitly close the file before calling MSWRITE or MsWrite to ensure that all data are in the disk file prior to writing the file to the MSS.

See the mswrite man page for more information about the Fortran and C versions.

If you have questions about this document, please contact SCD Customer Support. You can also reach us by telephone 24 hours a day, seven days a week at 303-497-1278. Additional contact methods: consult1@ucar.edu and during business hours in NCAR Mesa Lab Suite 39.

Last update: 09/05/2006

© Copyright 1992-2006. University Corporation for Atmospheric Research (UCAR). All Rights Reserved.