IDL_FileOpen()

int IDL_FileOpen(int argc, IDL_VPTR *argv, char *argk, 
   int access_mode, IDL_SFILE_FLAGS_T extra_flags, 
   int longjmp_safe, int msg_attr)

IDL_FileOpen() returns TRUE if the file has been successfully opened and FALSE otherwise.

Note: If longjmp_safe is TRUE, the usual course is to jump back to the IDL interpreter, in which case the routine won’t return.

argc

The number of arguments in argv. This value should always be 2.

argv

The arguments to IDL_File_Open(). argv[0] should be a scalar integer value giving the file unit number (LUN) to be opened. argv[1] is a scalar string giving the file name.

argk

Keywords. Set this argument to NULL.

access_mode

A bit mask that specifies the access to be allowed to the file being opened. The allowed bit values are listed in the following table:

  • IDL_OPEN_R: The file is open for input.
  • IDL_OPEN_W: The file is open for output.
  • IDL_OPEN_TRUNC: The file was truncated when it was opened. This implies that IDL_OPEN_W is also set.
  • IDL_OPEN_APND: The file was opened with the file pointer set just past the last byte of data in the file (the file is open for appending).

Conflicting bits should not be set together (for example, do not specify IDL_OPEN_TRUNC | IDL_OPEN_APND). Also, one or both of IDL_OPEN_R and IDL_OPEN_W must always be specified.

extra_flags

Used to specify additional file attributes using the flags defined in the description of the flags field of the IDL_FILE_STAT struct (see File Information). Note that some flags are set by IDL based on the actual attributes of the opened file (e.g. IDL_F_ISTTY) and that it makes no sense to set such flags in this mask.

If you intend to use the opened file as a C standard I/O (stdio) stream file, you must specify the IDL_F_STDIO flag when calling IDL_FileOpen(). Otherwise, IDL may choose not to use stdio.

longjmp_safe

If set to TRUE, IDL_FileOpen() is being called in a context where an IDL_MSG_LONGJMP IDL_Message action code is okay. If set to FALSE, the routine won’t longjmp().

IDL_FileOpen() returns TRUE if the file has been successfully opened and FALSE otherwise. If longjmp_safe is TRUE, the usual course is to jump back to the IDL interpreter, in which case the routine won’t return.

msg_attr

A zero (0), or any combination of the IDL_MSG_ATTR_ flags, used to fine tune the error handling specified by the longjmp_safe argument. Note that you must not specify any of the base IDL_MSG_ codes, but only the attributes. The base code (e.g. IDL_MSG_LONGJMP) is determined by the value of longjmp_safe. For a discussion of the IDL_MSG_ATTR_ flags, see Issuing Error Messages.

Special File Units

There are three files that are always open. The three units are:

  • IDL_STDIN_UNIT: Unit 0 (zero) is the standard input for the IDL process.
  • IDL_STDOUT_UNIT: Unit –1 is the standard output.
  • IDL_STDERR_UNIT: Unit –2 is the standard error.

Note: The constant IDL_NON_UNIT always has a value that is not a valid file unit.