How can I get started from the interactive command line?

The best way to get started is to use CMSAVEDIR to make a directory of the contents of an already-existing SAVE file:

   cmsavedir, 'myfile.sav'

This functionality is exclusive to the CMSVLIB library. I personally find this procedure very useful, because I often create save files and later forget what they contain.

The second way to get started is to use CMSAVE and CMRESTORE. CMSAVE is essentially a drop-in replacement for the built-in IDL SAVE procedure, with more features. Perhaps one of the most useful features will be to append additional variables to an existing file. In this way you can incrementally build up an archive of session data. The syntax to CMSAVE is the same as for SAVE, with the addition of the APPEND keyword:

   CMSAVE, var1, var2, ..., filename='myfile.sav', /APPEND

CMRESTORE is a drop-in replacement for RESTORE. The coolest thing about this procedure is the ability to restore only a few selected variables from a file, rather than all the variables at once. This is the easiest way (restoring variables 3 and 7 out of a larger set):

   CMRESTORE, 'myfile.sav', var3, var7

How can I get started as a programmer?

The easiest way to get started is to use the higher level routines CMSAVEDIR, CMSAVE and CMRESTORE rather than the built-in IDL SAVE and RESTORE procedures. The same benefits that apply to interactive command line usage, also apply to programmers.

Use CMSAVEDIR to interrogate the contents of a SAVE file without actually restoring it. Programmers can silently retrieve a listing of the variables using the N_VARIABLES and VAR_NAMES keywords. To find out the names of any named structures or classes in a file, use the NAMED_STRUCTS and NAMED_CLASSES keywords. Here are examples:

   CMSAVEDIR, 'myfile.sav', /QUIET, VAR_NAMES=vnames
   CMSAVEDIR, 'myfile.sav', /QUIET, NAMED_CLASSES=classes

You can use CMSAVE and CMRESTORE to save and restore variables from a file, but unlike their built-in counterparts, these versions allow you to pass variables in multiple ways, and to rename variables. This can be extremely helpful to safely restore variables without polluting the calling procedure's name space.

The mid-level procedures CMSVREAD and CMSVWRITE can be used like the Gumley binary I/O library to write most kinds of simple SAVE files. The essential restriction is that no heap or pointer data are permitted at this level. Here is a summary of the different ways to call the library routines at the higher and middle levels.

  save, a, b, c, file=filename

  restore, a, b, c, file=filename

cmsave, a, b, c, file=filename

cmrestore, a, b, c, file=filename

struct={a:a, b:b, c:c}
cmsave, data=struct, $
  file=filename

cmrestore, pass_meth='STRUCT', $
  data=struct, file=filename

pheap = [ptr_new(a), ptr_new(b), $
    ptr_new(c)]
cmsave, data=pheap, file=filename

cmrestore, pass_meth='POINTER', $
  data=pheap, file=filename

openw, unit, filename
cmsvwrite, unit, a, name='A'
cmsvwrite, unit, b, name='B'
cmsvwrite, unit, c, name='C'
close, unit

openr, unit, filename
cmsvread, unit, a, name='A'
cmsvread, unit, b, name='B'
cmsvread, unit, c, name='C'
close, unit

The lowest level functions provide raw access to the data in a SAVE file, but it is recommended that only experienced programmers attempt this. The higher- and mid-level procedures provide sufficient functionality that these lower-level routines will probably be needed seldomly. Users wishing to use the low-level procedures must place the following query code in their initialization routine to verify that the complete library is present:

  catch, catcherr
  if catcherr EQ 0 then lib = cmsvlib(/query) else lib = 0
  catch, /cancel
  if lib EQ 0 then $
    message, 'ERROR: The CMSVLIB library must be in your IDL path.'

Programmers interested in reading and writing heap data should consult the instructions in the individual procedure documentation.

Why would I use CMSAVE/CMRESTORE instead of SAVE/RESTORE?

Generally speaking the CMSAVE/CMRESTORE routines are equivalent to SAVE/RESTORE. However there are some differences. Here is a comparison of the built-in versus the CMSVLIB library routines.

I think I have discovered a bug. What do I do?

I would appreciate feedback from users. Generally I can't help you with your programming questions. However if there are bugs I would like a bug report.

The first step is to run CMSV_TEST and examine the results. You should not experience any failures (listed as a "FAILED test"). If you do experience a failure, please send the full report to me.

If CMSV_TEST succeeded but you still think there is a bug, then I still need the output of CMSV_TEST. Please reduce the problem to as simple a test case script as possible. Send the script to me. Also send any appropriate files, such as successful or partial save files, as attachments.

What are the compatibility issues?

The CMSVLIB library can read and write most kinds of save files. As for file compatibility, it should be possible to read save files produced by IDL versions 4 - 5.4, and to write new save files readable the same IDL versions. The library is able to read files produced by the buggy IDL 5.4. However, there are some limitations. It is not possible to read or write compressed files, files larger than 2 gigabytes, or object data.

If you absolutely need these features then you should stick with the standard built-in routines.

There are also some program-level compatibility issues. Under IDL 5.2 and earlier it is not possible to have CMRESTORE restore variables into the caller's namespace unless the variables have already been defined. It is not supported to run the library routines under IDL 4, but it should be able to read files originally written by IDL 4.

Can I write pointers and heap data?

Yes, but extra processing is required. See the documentation in CMSV_RDATA and CMSV_WREC for more information.

It is not possible to read or write object pointer data. However, it is possible to determine that these data exist in the file.

Is the format of a SAVE file documented anywhere?

Yes! See the SAVE File web page (under documentation) for more information. The document is provided in web-format, PDF, and Postscript.

Can I use the CMSVLIB library to read compiled IDL procedures and functions?

No, sorry. This functionality was available briefly, but has subsequently been removed, because of a request from RSI and Kodak.

What kinds of saved procedures can I translate with PROTRANS?

None. PROTRANS is no longer available.

Why can't I compile procedures translated by PROTRANS?

No longer an issue. PROTRANS is no longer available.