Function Descriptions
USERC_open
This function opens a file for reading, writing or both. It returns one value: -1 or an integer file descriptor. The -1 value indicates an error. The integer file descriptor must be saved and supplied to a variety of other USERC functions.
USERC_open accepts two arguments:
| • |
The first argument is the pathname of the desired file to open. |
| • |
The second argument is the access mode. |
Listed below are some guidelines taken from the UNIX man page fopen(3S). For additional information, see that page.
r
|
read
|
w
|
write
|
a
|
append
|
+ mode
|
(update mode) if you must read and write the file, or you want to write to specific locations without losing previous data in the file.
|
r and r+
|
(read) modes will never create the file if it does not already exist. All four of the "w" and "a" (write and append) modes will create the file if is not there.
|
w and w+
|
Modes will truncate an existing file
|
Tips:
| • |
With instruments, it is highly advisable to use USERC_open once with mode "r" for reading, and once with mode "w" for writing. This avoids some problems in the standard I/O library that involve positioning in the I/O stream. |
USERC_close
This function closes an open file. It returns a value indicating the status. If successful, it returns 0; otherwise it returns -1.
USERC_close accepts one argument:
| • |
The file descriptor obtained from the call to USERC_open. |
It performs an fclose(3). By default, the system will call fclose for all files opened by the User C I/O facility whenever the last Program or Macro terminates. It does this with userc_end_of_prog(), which is described in $ICCAP_ROOT/src/userc_io.c.
USERC_write
This function prints anything to an open file, in ASCII. It returns a value indicating the status. If successful, it returns 0; otherwise it returns -1.
USERC_write accepts three arguments:
| • |
The first argument should be a file descriptor obtained from USERC_open. |
| • |
The second argument should be a flag (0 or 1) indicating whether the output file should be considered a device file, that is, an instrument. Use 0 unless you are reading from an instrument. |
| • |
The third argument should be a string, for example. VAL$(2), or VAL$(BF), or "TNOM="&VAL$(TNOM)&newline_string. |
Tips:
| • |
This function calls fflush(3) to ensure that a write-to-file or write-to-instrument is never delayed by the buffering present in the standard I/O facility. |
| • |
For information regarding instrument timeouts when writing, refer to Hints for Timeouts. |
USERC_readnum
This function reads one real number from a file, for example, 1.0E6. (See also USERC_readstr.) It returns one value: a real number read from a file or from an instrument. The returned value should be a valid real number if one exists; else the value is set to 9.99998E+37, for example, if EOF is encountered. (This mimics what the HP 54120 does when no valid data exists, but is a slightly different value.)
USERC_readnum accepts three arguments:
| • |
The first argument should be a file descriptor obtained from USERC_open. |
| • |
The second argument should be a flag (0 or 1) indicating whether the input file should be considered a device file, that is, an instrument. Use 0 unless you are reading from an instrument. |
| • |
The third argument should be a scanf format string, for example, "%*5s%lf%*1[\n]", which means skip over a 5-character string, then get a double number, then read and skip a newline. (Consult man page scanf(3S).) The scanf format string provides some flexibility in terms of separating the number out from any surrounding text or mnemonics that are not of interest. |
Tips:
| • |
To avoid a potential core dump, %lf should be included only once, and any other "%" specifiers should have an asterisk (*) after them. |
| • |
If reading from an instrument that must communicate multiple data points in one read, it is necessary to create a modified version of this function to obtain those multiple data points. |
| • |
For information regarding instrument timeouts when reading, refer to Hints for Timeouts. |
USERC_readstr
This function reads a string from a file and places it in an IC-CAP variable you specify. (See also USERC_readnum.) It returns a value indicating the status. If successful, it returns 0; otherwise it returns -1.
USERC_readstr accepts four arguments:
| • |
The first argument should be a file descriptor obtained from USERC_open. |
| • |
The 2nd argument should be a flag (0 or 1) indicating whether the input file should be considered a device file, that is, an instrument. Use 0 unless you are reading from an instrument. |
| • |
The third argument should be a scanf format string, for example, %*5s%s%*1[\n]. This example means skip over a 5-character string, then get a string, then read and skip a newline. (Consult man page scanf(3S).) The scanf format string provides some flexibility in terms of separating the number out from any surrounding text or mnemonics that are not of interest. |
| • |
The fourth argument should be the name of an IC-CAP variable that receives its value from the string that is read. |
Tips:
| • |
To avoid a potential core dump, %s should be included only once, and any other "%" specifiers should have an asterisk (*) after them. |
| • |
For information regarding instrument timeouts when reading, refer to Hints for Timeouts. |
USERC_seek
This function goes to a particular byte offset in a file. (This function is basically an interface to fseek(3S)). It returns a value indicating the status. If successful, it returns 0; otherwise it returns -1.
USERC_seek accepts three arguments:
| • |
The first argument should be a file descriptor obtained from USERC_open. |
| • |
The second argument should be an offset in bytes. |
| • |
The third argument should indicate the relative starting point for the offset. Use 0 if you want the seek offset to be relative to the beginning of the file, or 1 if the seek offset should be relative to the current position in the file. |
Tips:
| • |
Each line in an ASCII file uses 1 byte for a newline terminator. |
| • |
USERC_tell can be used to determine the current position, if you intend to seek elsewhere, and then return to the current position. |
| • |
It is neither useful nor advisable to use this function on device files, such as instruments or terminals. |
USERC_tell
This function shows the current byte offset in a file. (This function is basically an interface to ftell(3S).) It returns a value indicating the status. If successful, it returns 0; otherwise it returns -1.
USERC_tell accepts one argument:
| • |
The argument should be a file descriptor obtained from USERC_open. |
USERC_read_reals
This function opens a file, reads an array of reals, closes the file, and returns an array. It returns -1 if the file could not be opened for reading, else 0.
USERC_read_reals accepts one argument:
| • |
The argument should be the name of a file with real number data. |
Invoking this function produces the following sequence of actions:
| • |
Read real numbers from a file |
| • |
Return them as an array in iccap |
| • |
Open, read, and close the data file |
| • |
Close file in the event of user-requested interrupt (Ctrl-C) |
| • |
Print warning if unexpected number of points in file |
|
