NAG Library Function Document

nag_ip_read (h02xyc)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:    $\mathbf{name}$ – const char *Input

On entry: a character string specifying either the NAG six character name or the NAG long name of the proposed IP function. The case of the character string is disregarded.

2:    $\mathbf{opt\_file}$ – const char *Input

On entry: the name of the file which specifies the optional parameter values. If stdin is to be used, the string "stdin" should be supplied. The set of option values must be preceded by the keyword begin followed by the function name for which the set of options is being supplied. The function name may be the six character NAG name of an IP function or its associated long name.

Each option value specified in the file must be preceded by the name of the optional parameter. The argument name and value must be separated by at least one blank space or an equals symbol. nag_ip_read (h02xyc) will read to the end of file or until the keyword end is found or until another begin is found. C style comments may be placed within a set of option values to aid your documentation. Outside the option value sets, text need not be within C style comment delimiters.

N.B. Assignment to function pointers in the options structure, memory allocation to array pointers and assignment of trailing array dimensions cannot be performed from an options file. These must be assigned directly to the options structure in your calling program.

3:    $\mathbf{options}$ – Nag_H02_Opt *Input/Output

On entry: the options structure may or may not have previously been initialized, and had values assigned to its members.

On exit: the options structure, initialized and with values assigned according to the values found in the options file.

4:    $\mathbf{print}$ – Nag_BooleanInput

On entry: if Nag_TRUE a message confirming the setting of each option will be output.

5:    $\mathbf{outfile}$ – const char *Input

On entry: a character string specifying the name of the file to which confirmation messages should be output. If stdout is required then the string "stdout" should be given. When $\mathbf{print}=\mathrm{Nag\_FALSE}$ the empty string "" can be supplied as outfile will be ignored.

6:    $\mathbf{fail}$ – NagError *Input/Output

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_FIELD_UNKNOWN

(line $〈\mathit{\text{value}}〉$) ‘$〈\mathit{string}〉$’ is not a permitted structure member or option for $〈\mathit{string}〉$.

NE_INVALID_BEGIN

The Begin statement occurring in data file from which options are being read is not valid.

NE_INVALID_ENUM_RANGE

Enum value $〈\mathit{string}〉$ given to $〈\mathit{option}〉$ is not valid for this function.

NE_INVALID_INT_RANGE_1

NE_INVALID_OPTION

(line $〈\mathit{\text{value}}〉$) ‘$〈\mathit{string}〉$’ cannot be assigned to using an options file.

NE_INVALID_OPTION_NAME

(line $〈\mathit{\text{value}}〉$) ‘$〈\mathit{string}〉$’ is not a valid name for a structure member or option.

This error message is output if, for example, the specified string contains characters which are not permitted in a variable name in the C programming language.

NE_INVALID_REAL_RANGE_CONS

Value $〈\mathit{\text{value}}〉$ given to $〈\mathit{option}〉$ is not valid. The argument $〈\mathit{option}〉$ must satisfy $〈\mathit{constraint}〉$.

NE_INVALID_REAL_RANGE_F

Value $〈\mathit{\text{value}}〉$ given to $〈\mathit{option}〉$ is not valid. Correct range is $〈\mathit{option}〉$ $〈\mathit{\text{value}}〉$.

NE_INVALID_REAL_RANGE_FF

Value $〈\mathit{\text{value}}〉$ given to $〈\mathit{option}〉$ is not valid. Correct range is $〈\mathit{\text{value}}〉$ $〈\mathit{option}〉$ $〈\mathit{\text{value}}〉$.

NE_INVALID_TEXT_RANGE

Value $〈\mathit{string}〉$ given to $〈\mathit{option}〉$ not valid.

NE_INVALID_VALUE

(line $〈\mathit{\text{value}}〉$) value ‘$〈\mathit{string}〉$’ given to $〈\mathit{string}〉$ option is not of the correct type for this option.

NE_NO_VALUE

(line $〈\mathit{\text{value}}〉$) no value found for option $〈\mathit{string}〉$.

NE_NOT_APPEND_FILE

Cannot open file $〈\mathit{string}〉$ for appending.

NE_NOT_CLOSE_FILE

Cannot close file $〈\mathit{string}〉$.

NE_NOT_FUN_NAME

The string, $〈\mathit{string}〉$, supplied in the argument name is not the name of any C Library function with option setting facilities.

NE_NOT_READ_FILE

Cannot open file $〈\mathit{string}〉$ for reading.

NE_UNBALANCED_COMMENT

Unbalanced comment starting on line $〈\mathit{\text{value}}〉$ found in options file.

NE_WRITE_ERROR

Error occurred when writing to file $〈\mathit{string}〉$.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example