e04 Chapter Contents
e04 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_opt_read (e04xyc)

## 1  Purpose

nag_opt_read (e04xyc) reads a set of optional argument values from a file and assigns those values to a given options structure of type Nag_E04_Opt. Values supplied are checked as being of correct type for the specified optional argument.

## 2  Specification

 #include #include
 void nag_opt_read (const char *name, const char *opt_file, Nag_E04_Opt *options, Nag_Boolean print, const char *outfile, NagError *fail)

## 3  Description

The optimization functions of Chapter e04 have a number of optional arguments, which are set by means of a structure of type Nag_E04_Opt. Optional argument values may be assigned to members of the options structure directly in the program text and/or by supplying the optional values in a file which can be read by the function nag_opt_read (e04xyc).
When optional argument values are read from a file using nag_opt_read (e04xyc) then the options structure will be initialized automatically if this has not already been done. It is only necessary to call nag_opt_init (e04xxc) if direct assignments to the options structure are made in your program before calling nag_opt_read (e04xyc).
As well as reading from a file, nag_opt_read (e04xyc) will also read from stdin. This allows redirection to be used to supply the file; it also permits nag_opt_read (e04xyc) to be used interactively by supplying values from the keyboard.
Checks are made that the values read in are of valid type for the optional argument specified and (except for nag_opt_nlp_sparse (e04ugc)) that the value is within the range for that argument. If a value is accepted, a printed confirmation of the setting of the relevant argument will be output if ${\mathbf{print}}=\mathrm{Nag_TRUE}$. An unacceptable argument name or value will give an error message if ${\mathbf{fail}}\mathbf{.}\mathbf{print}=\mathrm{Nag_TRUE}$.

None.

## 5  Arguments

1:     nameconst char *Input
On entry: a character string specifying either the NAG six character name or the NAG long name of the proposed optimization function. The case of the character string is disregarded.
2:     opt_fileconst char *Input
On entry: the name of the file which specifies the optional argument 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 optimization function or its associated long name.
Each option value specified in the file must be preceded by the name of the optional argument. The argument name and value must be separated by at least one blank space or an equals symbol. nag_opt_read (e04xyc) 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.
Note: 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:     optionsNag_E04_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:     printNag_BooleanInput
On entry: if Nag_TRUE a message confirming the setting of each option will be output.
5:     outfileconst 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:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_STOP_LT_START and NE_CHECK_LT_ONE are specific to option setting for nag_opt_conj_grad (e04dgc), nag_opt_nlin_lsq (e04unc) and nag_opt_nlp_solve (e04wdc).
NE_CHECK_LT_ONE
Value $〈\mathit{\text{value}}〉$ given to $〈\mathit{string}〉$ is less than 1.
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
Value $〈\mathit{\text{value}}〉$ given to $〈\mathit{option}〉$ is not valid. Correct range is $〈\mathit{option}〉〈\mathit{\text{value}}〉$.
NE_INVALID_INT_RANGE_2
Value $〈\mathit{\text{value}}〉$ given to $〈\mathit{option}〉$ is not valid. Correct range is $〈\mathit{\text{value}}〉〈\mathit{option}〉〈\mathit{\text{value}}〉$.
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}〉$ not valid. The argument $〈\mathit{option}〉$ must satisfy $〈\mathit{constraint}〉$.
NE_INVALID_REAL_RANGE_E
Value $〈\mathit{\text{value}}〉$ given to $〈\mathit{option}〉$ is not valid. Correct range is $〈\mathit{option}〉〈\mathit{\text{value}}〉$.
NE_INVALID_REAL_RANGE_EF
Value $〈\mathit{\text{value}}〉$ given to $〈\mathit{option}〉$ is not valid. Correct range is $〈\mathit{\text{value}}〉〈\mathit{option}〉〈\mathit{\text{value}}〉$.
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}}〉$) is not a permitted structure member or option for $〈\mathit{string}〉$.
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.
Cannot open file $〈\mathit{string}〉$ for reading.
NE_STOP_LT_START
Value given to obj_check_stop, $〈\mathit{\text{value}}〉$, is less than value given to obj_check_start, $〈\mathit{\text{value}}〉$.
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

Not applicable.

nag_opt_read (e04xyc) may be used to read the optional ‘MPSX names’ (e.g., ${\mathbf{prob_name}}$, ${\mathbf{obj_name}}$) for nag_opt_sparse_mps_read (e04mzc). However, although nag_opt_sparse_mps_read (e04mzc) allows the names to contain non-leading blank characters, nag_opt_read (e04xyc) will not read such names correctly from an options file since blank spaces are assumed to denote the end of an option name or value within the file. All other valid MPSX names (see the documentation for nag_opt_sparse_mps_read (e04mzc) for details) will be read correctly by nag_opt_read (e04xyc).