originc\doc_gen.cfm

Documentation Browser

Origin C Language Reference

This help system gives detailed descriptions of all Origin C classes, methods, global functions and macros. You can navigate through the help using the contents list to the left or search for a particular function using the keyword search.


fft_bandblock

Function: fft_bandblock
Prototype:
int fft_bandblock(Curve& crvSignal, double dFLow, double dFHigh, bool bAddOffset = true)
Remarks: Performs band block filtering of signal. The filtering is performed by using NAG FFT functions.
Parameters:
crvSignal:	Input: signal data; Output: filtered signal
dFLow:		lower cutoff frequency
dFHigh: 	higher cutoff frequency
bAddOffset:	add back DC offset after filtering

Return values:
0:			success
-1:			curve does not meet time resoultion criterion
-2:			curve is invalid
-3:			invalid cutoff frequency
positive:	NAG error code

Example:
        int iRet = fft_bandblock(crvSignal, dFLow, dFHigh);

Summary:
Sample data:
Header file: fft_utils.h
See also:


fft_bandpass

Function: fft_bandpass
Prototype:
int fft_bandpass(Curve& crvSignal, double dFLow, double dFHigh, bool bAddOffset = true)
Remarks: Performs band pass filtering of signal. The filtering is performed by using NAG FFT functions.
Parameters:
crvSignal:	Input: signal data; Output: filtered signal
dFLow:		lower cutoff frequency
dFHigh: 	higher cutoff frequency
bAddOffset:	add back DC offset after filtering

Return values:
0:			success
-1:			curve does not meet time resoultion criterion
-2:			curve is invalid
-3:			invalid cutoff frequency
positive:	NAG error code

Example:
        int iRet = fft_bandpass(crvSignal, dFLow, dFHigh);

Summary:
Sample data:
Header file: fft_utils.h
See also:


fft_convolute

Function: fft_convolute
Prototype:
int fft_convolute(vector& vecSignal, vector& vecResponse, vector& vecResult, bool bNormalize = true, bool bWrap = true)
Remarks: Performs circular convolution of signal with response function. The convolution is performed by calling the NAG convolution function. The length of the signal may be truncated by a few points to make length compatible with NAG call. See nag_convolution_real for more details
Parameters:
vecSignal: vector with Signal data
vecResponse: vector with Response data
vecResult: vector to return result of convolution
bNormalize = true: normalize sum of response elements to unity, false: do not normalize
bWrap = true: wrap response so that max value is at 0th element, false: do not wrap

Return values:
Returns 0 for no errors, positive number for any NAG-returned error code.

Example:
        int iRet = fft_convolute(vecSignal, vecResponse, vecResult);

Summary:
Sample data:
Header file: fft_utils.h
See also:


fft_correlate

Function: fft_correlate
Prototype:
int fft_correlate(vector& vecSignal1, vector& vecSignal2, vector& vecCorrelation, bool bNormalize = true)
Remarks: Performs correlation of two signals. The correlation is performed by calling NAG FFT functions. If specified, the correlation result is normalized to be in the range of +1 to -1. The normalization is performed by dividing the result by the following factor: square root( (sum of FFT amplitudes of signal 1) * (sum of FFT amplitudes of signal 2) ).
Parameters:
vecSignal1: vector with Signal1 data
vecSignal2: vector with Signal2 data
vecCorrelation: vector with correlation result
bNormalize = true: normalize corelation result to +/-1 range

Return values:
Returns 0 for no errors, positive number for any FFT-related error code.

Example:
        int iRet = fft_correlate(vecSignal1, vecSignal2);

Summary:
Sample data:
Header file: fft_utils.h
See also:


fft_deconvolute

Function: fft_deconvolute
Prototype:
int fft_deconvolute(vector& vecSignal, vector& vecResponse, vector& vecResult, bool bNormalize = true, bool bWrap = true)
Remarks: Performs deconvolution of signal with response function. The deconvolution is performed by calling NAG FFT functions. The length of the signal may be truncated by a few points to make length compatible with NAG call. See nag_convolution_real for more details
Parameters:
vecSignal: vector with Signal data
vecResponse: vector with Response data
vecResult: vector to return result of deconvolution
bNormalize = true: normalize sum of response elements to unity, false: do not normalize
bWrap = true: wrap response so that max value is at 0th element, false: do not wrap

Return values:
Returns 0 for no errors, positive number for any NAG-returned error code.

Example:
        int iRet = fft_deconvolute(vecSignal, vecResponse, vecResult);

Summary:
Sample data:
Header file: fft_utils.h
See also:


fft_highpass

Function: fft_highpass
Prototype:
int fft_highpass(Curve& crvSignal, double dFc, bool bAddOffset = true)
Remarks: Performs high pass filtering of signal. The filtering is performed by using NAG FFT functions.
Parameters:
crvSignal:	Input: signal data; Output: filtered signal
dFc:		cutoff frequency
bAddOffset:	add back DC offset after filtering

Return values:
0:			success
-1:			curve does not meet time resoultion criterion
-2:			curve is invalid
-3:			invalid cutoff frequency
positive:	NAG error code

Example:
        int iRet = fft_highpass(crvSignal, dFc);

Summary:
Sample data:
Header file: fft_utils.h
See also:


fft_lowpass

Function: fft_lowpass
Prototype:
int fft_lowpass(Curve& crvSignal, double dFc)
Remarks: Performs low pass filtering of signal. The filtering is performed by using NAG FFT functions.
Parameters:
crvSignal:	Input: signal data; Output: filtered signal
dFc:		cutoff frequency

Return values:
0:			success
-1:			curve does not meet time resoultion criterion
-2:			curve is invalid
-3:			invalid cutoff frequency
positive:	NAG error code

Example:
        int iRet = fft_lowpass(crvSignal, dFc);

Summary:
Sample data:
Header file: fft_utils.h
See also:


fft_threshold_filter

Function: fft_threshold_filter
Prototype:
int fft_threshold_filter(Curve& crvSignal, double dThreshold)
Remarks: Performs threshold filtering of the signal. All components below the specified threshold amplitude in the frequency spectrum of the signal are removed. The filtering is performed by using NAG FFT functions.
Parameters:
crvSignal:	Input: signal data; Output: filtered signal
dThreshold:	threshold value; must be greater than 0

Return values:
0:			success
-1:			curve does not meet time resoultion criterion
-2:			curve is invalid
-3:			invalid threshold
positive:	NAG error code

Example:
        int iRet = fft_threshold_filter(crvSignal, dThreshold);

Summary:
Sample data:
Header file: fft_utils.h
See also:


convert_random_xyz_to_matrix_nag

Function: convert_random_xyz_to_matrix_nag
Prototype:
int convert_random_xyz_to_matrix_nag(vector& vecX, vector& vecY, vector& vecZ,matrix& matResult, double& dXmin, double& dXmax, double& dYmin, double& dYmax,int iMethod = 0, double dQIL = 1, double dWFL = 1)
Remarks: Performs gridding of random XYZ data. The gridding is performed by calling NAG functions. Two gridding methods, Renka-Cline and Modified Shepard's method are available. For more details on these methods, see documentation for NAG function e01_sac.
Parameters:
vecX,Y,Z:		Input: random XYZ data
matResult:		matrix with gridded data
dXmin, dXmax:	min, max of x data - can use for setting coordinates of Matrix object
dYmin, dYmax:	min, max of y data - can use for setting coordinates of Matrix object
iMethod:		0: Renka-Cline gridding; <>0: Modified Shepard's method
dQIL:			Quadratic Interpolant Locality - used only by Shepard's method
dWFL:			Weight Function Locality - used only by Shepard's method

Return values:
0:		success
-1:		Error in creating matrix
NAG 	error codes:
70: 	Parameter method had an illegal value.
11: 	The number of points is less than 3.
73: 	Memory allocation failed.
245: 	All the (x,y) pairs are collinear.
246: 	Data pair is not unique. Duplicate points are found in the (x,y) pair.
247: 	Invalid dQIL and dWFL for Shepard's method.
249: 	(Warning)The minimum number of data points that lie within the radius of
any node is smaller that the interpolant may be unsatisfactory in regions
where the data points are sparse.
251: 	(Warning)The evaluation point lies outside the triangulation boundary.
The returned value was computed by extrapolation.
252: 	On entry,the interpolant cannot be evaluted because the evaluation
point is outside the support region of the input data points.
See Also:
convert_regular_xyz_to_matrix

Example:
        int iRet = random_gridding_nag(vecX, vecY, vecZ)	// Renka-Cline method
        int random_gridding_nag(vecX, vecY, vecZ, 1)		// Shepard's method

Summary:
Sample data:
Header file: analysis_utils.h
See also:


convert_regular_xyz_to_matrix

Function: convert_regular_xyz_to_matrix
Prototype:
int convert_regular_xyz_to_matrix(vector& vecX, vector& vecY, vector& vecZ, matrix& matData, double& dXmin,double& dXmax, double& dYmin, double& dYmax, bool bCheckData = true)
Remarks: Converts regular XYZ data to a matrix. If asked for, data is examined for deviations.
Parameters:
vecX,Y,Z:		Input: regular XYZ data
dXmin, dXmax:	min, max of x data - can use for setting coordinates of Matrix object
dYmin, dYmax:	min, max of y data - can use for setting coordinates of Matrix object
bCheckData:		true: check data for irregularities; false: do no checking
If user knows data is perfectly regular, can set to false for faster operation

Return values:
0:			success
1:			XYZ vectors are of unequalsize, or result matrix smaller than 2x2
2:			could not find steps in data
3:			groups in x/y do not match group length in y/x
4:			too much deviation in x/y data

Example:
        //This example fill a matrix with values in Data1.
        //For this samples to work, Data1 must exist in the project contains 3 column A, B, C
        void run_convert_regular_xyz_to_matrix()
        {
            Dataset dsX("Data1_A"), dsY("Data1_B"), dsZ("Data1_C");
            vector vecX(dsX), vecY(dsY), vecZ(dsZ);

            MatrixLayer ml;						//Create a new Matrix to get the result
            ml.Create();
            Matrix matData(ml);

            double dXmax, dXmin;
            vecX.GetMinMax(dXmin, dXmax);		//Get the maximum and minimum values of X

            double dYmax, dYmin;
            vecY.GetMinMax(dYmin, dYmax);		//Get the maximum and minimum values of Y

            convert_regular_xyz_to_matrix(vecX, vecY, vecZ, matData, dXmin, dXmax, dYmin, dYmax);
        }

Summary:
Sample data:
Header file: analysis_utils.h
See also:


convert_sparse_find_min_max_step

Function: convert_sparse_find_min_max_step
Prototype:
int convert_sparse_find_min_max_step(vector& vec, double& dMin, double& dMax, double& dStep)
Remarks: Compute min, max and step value for sparse matrix conversion.
Parameters:
vec:				vector with data
dMin, dMax, dStep:	min, max and step values

Return values:
0:			success
See Also:
convert_sparse_xyz_to_matrix

Example:
        int iRet = convert_sparse_find_min_max_step(vec, dMin, dMax, dStep);

Summary:
Sample data:
Header file: analysis_utils.h
See also:


convert_sparse_xyz_to_matrix

Function: convert_sparse_xyz_to_matrix
Prototype:
int convert_sparse_xyz_to_matrix(vector& vecX, vector& vecY, vector& vecZ, matrix& matResult, double dXbegin, double dXend, double dXstep, double dYbegin, double dYend, double dYstep, int iPrecision = 8)
Remarks: Converts sparse XYZ data to a matrix. Sparse data is regular data with some rows missing.
Parameters:
vecX,Y,Z:				Input: regular XYZ data
matResult:				Output: resulting matrix
dXmin, dXmax: dXStep:	Input: min, max and stepsize in X.
Call convert_sparse_find_min_max_step to estimate these values.
dYmin, dYmax: dYStep: 	Input: min, max and stepsize in Y.
Call convert_sparse_find_min_max_step to estimate these values.
iPrecision:				Input: precision used to locate values; same as under Data_list() function

Return values:
0:				All points were converted
-1:				xyz vectors are of different/incorrect size
-2:				Matrix size too large - could be due to very small step value
-3:				Error in creating matrix object
positive:		Number of points that were discarded

Example:
        //This example convert Data1_A, Data1_B, Data1_C into a sparse matrix.
        //For this sample to run, Data1 with column A, B, C must exist.
        void run_convert_sparse_xyz_to_matrix()
        {
            Dataset dsX("Data1_A"), dsY("Data1_B"), dsZ("Data1_C");
            vector vecX(dsX), vecY(dsY), vecZ(dsZ);

            MatrixLayer ml;
            ml.Create();				// Create a new matrix to get the result
            Matrix matData(ml);

            double dXend, dXbegin;
            double dYend, dYbegin;
            double dXstep;
            double dYstep;

            convert_sparse_find_min_max_step(vecX, dXbegin, dXend, dXstep); //Find the step
            convert_sparse_find_min_max_step(vecY, dYbegin, dYend, dYstep);	//Find the step

            convert_sparse_xyz_to_matrix(vecX, vecY, vecZ, matData, dXbegin, dXend, dXstep,
                        dYbegin, dYend, dYstep);
        }

Summary:
Sample data:
Header file: analysis_utils.h
See also:


xyz_remove_duplicates

Function: xyz_remove_duplicates
Prototype:
int xyz_remove_duplicates(vector& vecX, vector& vecY, vector& vecZ)
Remarks: Removes duplicate points from XYZ data. Duplicates are replaced with mean Z value.
Parameters:
vecX,Y,Z:		Input: XYZ data; Output: XYZ vectors with duplicates removed

Return values:
0:			success
1:			XYZ vectors are of incorrect length

Example:
        //This example removes the duplicated values in Data1.
        //For this samples to run, Data1 should exist in the project with A, B, C columns.
        void run_xyz_remove_duplicates()
        {
            Dataset dsX("Data1_A"), dsY("Data1_B"), dsZ("Data1_C");
            vector vecX(dsX), vecY(dsY), vecZ(dsZ);

            xyz_remove_duplicates(vecX, vecY, vecZ);

            dsX = vecX;
            dsY = vecY;
            dsZ = vecZ;
        }

Summary:
Sample data:
Header file: analysis_utils.h
See also:


area

Function: area
Prototype:
double area(Curve &crv, double dYoffset = 0)
Remarks: Get the area under a curve.
Parameters:
crv=Input Origin C Curve object
dYoffset=Y offset subtracted from curve

Return values:
Returns the area under a curve.

Example:
        // Assumes Data1_A and Data1_B exist and contain data
        Curve crv("Data1_A","Data1_B");
        double dA = area(crv);
        printf("Area under curve is %g",dA);

Summary: Get the area under a curve.
Sample data:
Header file: data.h
See also: fwhm


Curve_bspline

Function: Curve_bspline
Prototype:
int Curve_bspline(curvebase* pcrvData, curvebase* pcrvResults, double dSmoothness = BSPLN_AUTO, Dataset* pdsWeights = NULL)
Remarks: Create a B Spline curve with optional weighting. The smoothness parameter can either be an arbitrary value >= 0 or an enumerated constant. The resulting B Spline curve will copy the source X data set if an empty X data set is provided or it will use a specified X data set as long as the range is within the source X range.
Parameters:
pcrvData=Input source curve
pcrvResults=Output result curve
dSmoothness=Smoothness factor can be any arbitrary value >= 0 or a predefined constant (BSPLN_AUTO=-3,
BSPLN_INTERPOLATE and BSPLN_WEIGTHED_LEAST_SQUARE_POLYNOMIAL) enumerated in OC_const.h. The
enumerated constants are negative numbers to distinguish them from arbitrary smoothness factors.
pdsWeights=Dataset containing weights for the input curve. If not NULL the number of points in the weight
data set must equal the number of points in the source curve. The default weighting is 1 for all points.

Return values:
Returns zero on successful exit and a non-zero error code on failure.
Errors:
-1=System can not allocate enough memeory
-2=Curve data type error
-4=The result curve range can not be set
5=The smoothness parameter must be equal to or greater than 0
11=The number of data points is less than 4
63=The sequence of X in source data is not increasing
73=Memory allocation failed
240=The weights are not all positive
254=The smoothness parameter is too small

Example:
        // Assumes Data1_A and Data1_B exist and contain Sample Data
        // Assumes Data2_A and Data2_B exist
        Worksheet wks("Data1");
        Curve crvInput(wks,0,1);

        Worksheet wks2("Data2");
        Curve crvResult(wks2,0,1);

        Curve_bspline(&crvInput, &crvResult);

Summary: Create a B Spline curve with optional weighting.
Sample data: 57.93992 83.52885 66.22726 75.17097 70.83567 87.96739 72.25362 91.59955 72.39297 81.93563 76.73526 89.47048 77.71110 67.86902
Header file: data.h
See also: Curve_derivative


Curve_derivative

Function: Curve_derivative
Prototype:
int Curve_derivative(curvebase* pcrvData, curvebase* pcrvResults, int nOrder = 1, double dSmoothness = BSPLN_OFF, Dataset* pdsWeights = NULL )
Remarks: Create the n-th Order derivative of a source curve with optional weighting. The smoothness parameter can either be an arbitrary value >= 0 or an enumerated constant. The resulting derivative curve will copy the source X data set if an empty X data set is provided or it will use a specified X data set as long as the range is within the source X range. Please note that in Origin 7.0, the defualt argument dSmoothness was BSPLN_AUTO, in 7.5 it was changed to BSPLN_OFF.
Parameters:
pcrvData=Input source curve
pcrvResults=Output result curve
nOrder=The order of the derivative
dSmoothness=Smoothness factor can be any arbitrary value >= 0 or a predefined constant (BSPLN_AUTO,
BSPLN_INTERPOLATE and BSPLN_WEIGTHED_LEAST_SQUARE_POLYNOMIAL, BSPLN_OFF) enumerated in OC_const.h. The
enumerated constants are negative numbers to distinguish them from arbitrary smoothness factors.
pdsWeights=Dataset containing weights for the input curve. If not NULL the number of points in the weight
data set must equal the number of points in the source curve. The default weighting is 1 for all points.
if dSmoothness equals BSPLN_OFF, only the first order derivative will be calculated.

Return values:
Returns zero on successful exit and a non-zero error code on failure.
Errors:
-1=System can not allocate enough memeory
-2=Curve data type error
-4=The result curve range can not be set
5=The smoothness parameter must be equal to or greater than 0
11=The number of data points is less than 4
63=The sequence of X in source data is not increasing
73=Memory allocation failed
240=The weights are not all positive
254=The smoothness parameter is too small

Example:
        // assumes data already in col(A), col(B)
        Worksheet wks = Project.ActiveLayer();
        Curve crvInput(wks,0,1);
        int nXCol, nYCol;
        Column cx = wks.Columns("DerivX");
        if(!cx)
            nXCol = wks.AddCol("DerivX");
        else
            nXCol = cx.GetIndex();

        wks.Columns(nXCol).SetType(OKDATAOBJ_DESIGNATION_X);

        Column cy = wks.Columns("DerivY");
        if(!cy)
            nYCol = wks.AddCol("DerivY");
        else
            nYCol = cy.GetIndex();

        Curve crvResult(wks,nXCol,nYCol);
        out_int("num of Rows before call = ", crvResult.GetSize());

        Curve_derivative(&crvInput, &crvResult);

        crvResult.Update(TRUE);// this will update the crvResult object to internal values inside Origin, that has been modified by Curve_derivative
        out_int("num of Rows after call = ", crvResult.GetSize());

Summary: Create the n-th Order derivative of a source curve with optional weighting.
Sample data:
Header file: data.h
See also: Curve_bspline


Curve_integrate

Function: Curve_integrate
Prototype:
BOOL Curve_integrate(curvebase* pcrvData, IntegrationResult* pirResult, curvebase* pcrvBaseline=NULL, Dataset* pdsIntegral=NULL, BOOL bPaintShade=FALSE)
Remarks: Integrate the given Curve relative to the X axis unless a baseline is specified.
Parameters:
pcrvData=Pointer to Curve to integrate
pirResult=Pointer to IntegrationResult structure (see OC_types.h)
pcrvBaseline=Pointer to baseline Curve
pdsIntegral=Pointer to Dataset holding cumulative integration result
bPaintShade=TRUE shades area of graph between integrated Curve and X axis (or baseline)

Return values:
Returns TRUE if integration is successful and FALSE otherwise. Also returns a pointer to an IntegrationResult
structure (see OC_types.h) and a pointer to dataset holding the cumulative integration result.

Example:
        BOOL bErr;
        Curve crvMyCurve( "Data1_A", "Data1_B" );		// Create Curve object to integrate
        Curve crvMyBaseline( "Data1_A", "Data1_C" );	// Create Curve object of integration baseline
        IntegrationResult irMyResults;					// Origin C structure to store integration results
        Dataset dsCumIntRes( "Data1_D" );				// Cumulative integration result
        dsCumIntRes.SetSize( crvMyCurve.GetSize() );	// Set size of dsCumIntRes to size of cvMyCurve
        bErr = Curve_integrate( &crvMyCurve, &irMyResults, &crvMyBaseline, &dsCumIntRes, TRUE ); // Perform integration
        printf( "Area = %f\n", irMyResults.Area );

Summary: Integrate the given Curve.
Sample data: A B C D (column D is returned by Example) 2 5 2 -- 4 5 2 6 6 5 2 12 8 5 2 18
Header file: data.h
See also:


Curve_MinMax

Function: Curve_MinMax
Prototype:
BOOL Curve_MinMax(const curvebase* pcuvData, double* pxMin, double* pxMax, BOOL bScanData=FALSE, double* pyMin=NULL, double* pyMax=NULL)
Remarks: Get X and Y range of the Curve
Parameters:
pcuvData=Pointer to Curve
pxMin = pointer to double for X min, NULL if no need to get this value
pxMax = pointer to double for X max, NULL if no need to get this value
bScanData = TRUE will scan both XY dataset of the curve for min and max, FALSE will reuse internal cached values. Typically there is no need to scan unless data has changed
pyMin = pointer to double for Y min, NULL if no need to get this value
pyMax = pointer to double for Y max, NULL if no need to get this value

Return values:
True for success

Example:
        double x1, x2;
        Curve cuv( "Data1_A", "Data1_B" );		// Create Curve object
        if(Curve_MinMax(&cuv, &x1, &x2))
            printf("%s X range is from %f to %f\n", cuv.GetName(), x1, x2);

Summary:
Sample data:
Header file: data.h
See also: Data_sum


Curve_x

Function: Curve_x
Prototype:
double Curve_x(curvebase* pcrvData, int nIndex)
Remarks: Get X value of Curve at specified index.
Parameters:
pcrvData=Pointer to Curve
nIndex=Zero based index

Return values:
For given Curve returns value of X at specified value of nIndex.

Example:
        double dXatI;
        Curve crvMyCurve( "Data1_A", "Data1_B" );		// Create Curve object
        dXatI = Curve_x( &crvMyCurve, 2 );				// Get X value at 0 based index I=2
        printf( "X at I=2:\t%f\n", dXatI );

Summary: Get X value of Curve at specified index.
Sample data:
Header file: data.h
See also: Curve_y Curve_xfromY Curve_yfromX


Curve_xfromY

Function: Curve_xfromY
Prototype:
double Curve_xfromY(curvebase* pcrvData, double dY)
Remarks: Get interpolated/extrapolated X value of Curve at specified Y value.
Parameters:
pcrvData=Pointer to Curve
dY=Value of Y

Return values:
For given Curve returns interpolated/extrapolated value of X at specified value of Y.

Example:
        double dXfromY;
        Curve crvMyCurve( "Data1_A", "Data1_B" );		// Create Curve object
        dXfromY = Curve_xfromY( &crvMyCurve, 0.25 );	// Get X value at Y=0.25
        printf( "X from Y=0.25:\t%f\n", dXfromY );

Summary: Get interpolated/extrapolated X value of Curve at specified Y value.
Sample data:
Header file: data.h
See also: Curve_y Curve_x Curve_yfromX


Curve_y

Function: Curve_y
Prototype:
double Curve_y(curvebase* pcrvData, int nIndex)
Remarks: Get Y value of Curve at specified index.
Parameters:
pcrvData=Pointer to Curve
nIndex=Zero based index

Return values:
For given Curve returns value of Y at specified value of nIndex.

Example:
        double dYatI;
        Curve crvMyCurve( "Data1_A", "Data1_B" );		// Create Curve object
        dYatI = Curve_y( &crvMyCurve, 2 );				// Get Y value at 0 based index I=2
        printf( "Y at I=2:\t%f\n", dYatI );

Summary: Get Y value of Curve at specified index.
Sample data:
Header file: data.h
See also: Curve_x Curve_xfromY Curve_yfromX


Curve_yfromX

Function: Curve_yfromX
Prototype:
double Curve_yfromX(curvebase* pcrvData, double dX)
Remarks: Get interpolated/extrapolated Y value of Curve at specified X value.
Parameters:
pcrvData=Pointer to Curve
dX=Value of X

Return values:
For given Curve returns interpolated/extrapolated value of Y at specified value of X.

Example:
        double dYfromX;
        Curve crvMyCurve( "Data1_A", "Data1_B" );		// Create Curve object
        dYfromX = Curve_yfromX( &crvMyCurve, 3.0 );		// Get Y value at X=3.0
        printf( "Y from X=3.0:\t%f\n", dYfromX );

Summary: Get interpolated/extrapolated Y value of Curve at specified X value.
Sample data:
Header file: data.h
See also: Curve_y Curve_x Curve_xfromY


Data_copy

Function: Data_copy
Prototype:
BOOL Data_copy(Dataset* pdsDest, Dataset* pdsSrc, int nSrcFrom = 0, int nSrcTo=-1, int nDestFrom=-1, BOOL bIgnoreMask=TRUE)
Remarks: Copy a range of data from one data set to another. If need be the destination data set will be automatically resized.
Parameters:
pdsDest=Input pointer to destination data set
pdsSrc=Input pointer to source data set
nSrcFrom=Input starting index of the source data set (0 based offset)
nSrcTo=Input ending index of the source data set (0 based offset, default -1 copies to upper index)
nDestFrom=Input starting index of the destination data set (0 based offset, default -1 uses nSrcFrom)
bIgnoreMask=TRUE ignores masking in source data set, FALSE copies masked values as missing values

Return values:
Returns TRUE if successful and FALSE if:
1) nSrcFrom < 0 or nSrcFrom > source UpperIndex
2) nSrcTo  < nSrcFrom or nSrcTo > UpperIndex
3) nDestFrom < -1 (-1 means to use nSrcFrom)

Example:
        Worksheet wks = Project.ActiveLayer();
        Dataset ds1(wks,0);
        Dataset ds2(wks,1);
        // Copy from row 3 to row 10 of column 1 into row 20 to 27 of column 2
        Data_copy(&ds2, &ds1, 2, 9, 19);

Summary: Copy a range of data from one data set to another.
Sample data:
Header file: data.h
See also:


Data_list

Function: Data_list
Prototype:
int Data_list(double dX, Dataset* pdsData, int nPrecision = 8)
Remarks: Search for the first occurrence of a given value in a data set.
Parameters:
dX=Value to lookup
pdsData=Dataset to look in for value
nPrecision=Indicates precision to use when determining if the given x value matches a value in the
data set. Pass -1 to use Origin's default internal double comparison precision as specified by the @ND
system variable. Otherwise, pass a positive integer to specify precision (significant digits). When
either the x or the data set value is non-zero, the following condition indicates whether or not a match
has been found:	abs((v2-v1)/(abs(v1)+abs(v2))) < 10^(-nPrecision).

Return values:
Returns the row index of the first occurence of a given value found in a data set. Returns -1 if
value is not found.

Example:
        Dataset dsDataIn("Data1_A");
        dsDataIn.SetSize(4);
        dsDataIn[0]=0.28019;
        dsDataIn[1]=0.93577;
        dsDataIn[2]=0.81075;
        dsDataIn[3]=0.04418;

        double tol, v1, v2;
        int nrow;

        v1=0.81075;
        nrow=Data_list(v1, &dsDataIn); // use default precision
        printf("\nnrow = %d",nrow);

        v1=0.82;
        v2=dsDataIn[2];
         tol=fabs((v2-v1)/(fabs(v1)+fabs(v2)));
         printf("\ntol = %f",tol);

         nrow=Data_list(v1, &dsDataIn, 2); // tol is < 10^-2 so select row 2
        printf("\nnrow = %d",nrow);
        nrow=Data_list(v1, &dsDataIn, 3); // tol is not < 10^-3 so don't select row 2
        printf("\nnrow = %d",nrow);

Summary: Find first occurrence of value in data set.
Sample data:
Header file: data.h
See also: Data_table


Data_sort

Function: Data_sort
Prototype:
BOOL Data_sort(Dataset* pdsData, BOOL bDescending = FALSE, BOOL bMissingAsMin = FALSE)
Remarks: Function to sort a data set inplace.
Parameters:
pdsData=Pointer to dataset
bDescending=If TRUE sort in descending order otherwise sort in ascending order (default)
bMissingAsMin=If TRUE evaluate Origin missing values as smallest value otherwise as largest value (default)

Return values:
If successful returns TRUE and a sorted dataset otherwise returns FALSE.

Example:
        int iSize;
        Dataset dsRawDATA("Data1_A");
        iSize=dsRawDATA.GetSize();
        Dataset dsSortedDATA(dsRawDATA);	// Create temporary copy of raw data
        Data_sort(&dsSortedDATA);			// Sort temporary dataset

        vector<double> vSortedDATA;			// Create dynamic structure to hold sorted data
        vSortedDATA.SetSize(iSize);			// Dynamically set size of vector
        vSortedDATA=dsSortedDATA;			// Assign sorted datset to vector
        dsRawDATA.Detach();
        dsSortedDATA.Detach();

Summary: Function to sort a data set inplace.
Sample data:
Header file: data.h
See also:


Data_table

Function: Data_table
Prototype:
double Data_table(double dX, Dataset* pdsYdata, Dataset* pdsXdata = NULL)
Remarks: Table lookup with interpolation from two data sets (X and Y) of monotonic data. To find the y value at a given row number pass the Y data set but pass NULL for the X data set. To find the y value at a given x value pass the Y data set and the X data set. To find the row number of a given y value pass a data set containing row numbers as the Y data set and pass the Y data set as the X data set. Function Data_list provides table lookup without interpolation.
Parameters:
dX=The index value used to perform the lookup
pdsYdata=The Y data set
pdsXdata=The X data set

Return values:
Returns the interpolated lookup value from two sets of monotonic data.

Example:
        double Xval, Yval, RowNumber;
        // To find Y value at given row number pass desired row number in place of X value and specify
        // NULL for X data set (Data_table will interpolate for fractional row numbers)
        RowNumber=2;
        Dataset dsYData("Data1_B");
        Yval=Data_table(RowNumber,&dsYData,NULL);
        printf("\nData1_B at row number %f = %f",RowNumber,Yval);

        // To find Y value at given X value pass X value and specify X data set (Data_table will interpolate
        // for all X values)
        Xval=25;
        Dataset dsXData("Data1_A");
        Yval=Data_table(Xval, &dsYData, &dsXData);
        printf("\nData1_B at X = %f is %f",Xval,Yval);

        // To find row number of given Y value, pass Y value in place of X value, specify Y data set as X data set, and
        // pass a data set containing row numbers {1,2,3,4...} for Y data set (Data_table will interpolate to fractional
        // row numbers)
        Yval=4.5;
        Dataset dsRowNums("Data1_C");
        RowNumber=Data_table(Yval, &dsRowNums, &dsYData);
        printf("\nRow Number where Data1_B = %f is %f",Yval,RowNumber);

Summary: Table lookup with interpolation.
Sample data: A B C 10 2 1 20 4 2 30 6 3
Header file: data.h
See also: Data_list


FFT

Function: FFT
Prototype:
int FFT(matrix<complex>& matSource, matrix<complex>& matFFTResult, int nColProcess = -1)
Remarks: This function performs 1-dimensional Fast Fourier Transform on each row of data in a matrix. Data matrix should be of type complex. If user have the data matrix in integer form, user should first transform it to complex.
Parameters:
matSource: The data source matrix
matFFTResult: The matrix containing the 1 dimension FFT results
nColProcess: The number of columns user provided. If it is -1, function will not do any padding
or truncating. But if it is larger than the size of the  matrix, it will pad zero to meet the size
if less than, it will truncate the data matrix.

Return values:
If succeed, it will return 0;	Otherwise it returns error indications.
Error:
-1: Provided column number or row number. Must be -1 or positive integer
-2: The data source matrix is empty
-3: When calling member function, it fails.
-4: When calling GetReal or GetImage member function of matrix class, it failed.
Nag Error:
11: The column or the row size of matrix is less then 1
73: System failed to allocate memory

Example:
        This example computes the 1 dimension fast fourier transform on each row of the matrix mSource.

    void FFT_test()
    {
        matrix <double> mRe = {{1,2.5,3.5,2,1.0,2.3},{3.2,4.1,2.2,1.0,4,2}};
        matrix <double> mIm = {{1,0.5,1.0,0.8,3.1,0.3},{2.2,3.2,3.0,1.5,2,2.1}};
        int ii , jj;

        matrix <complex> mSource, mResult;
        mSource.MakeComplex(mRe,mIm);

        //test 1d fft function for complex source matrix.//

        int Err = FFT(mSource, mResult);

        if ( 0 != Err )
        {
               ASSERT(false);
               printf("one-dimension FFT fails\n");
        }
        else
        {
            for(ii = 0; ii < mResult.GetNumRows();  ii++)
            {
                for(jj = 0; jj < mResult.GetNumCols(); jj++)
                    printf("(%f, %fi)  ",mResult[ii][jj].m_re,mResult[ii][jj].m_im);
                printf("\n");

            }
        }
    }

    The output is as following:
        (5.021454, 2.735264i)  (-1.018762, -1.546554i)  (0.139563, 0.547811i)  (-0.530723, 1.428869i)  (-1.486782, -1.078534i)  (0.324740, 0.362634i)
        (6.736097, 5.715476i)  (1.620196, 0.240945i)  (-0.760729, -1.970818i)  (0.938971, 0.163299i)  (-0.831440, 0.786898i)  (0.135272, 0.453077i)

Summary:
Sample data:
Header file: matrix.h
See also:
Function: FFT
Prototype:
int FFT(matrix& matSource, matrix<complex>& matFFTResult, int nColProcess = -1)
Remarks: These two Functions will do the 1 dimension Fast Fourier Transform. Data matrix should be of type double. If user have the data matrix in integer form, user should first transform it to double using the member function of matrixbase "CastToDouble".
Parameters:
matSource: The data source matrix
matFFTResult: The matrix containing the 1 dimension FFT results
nColProcess: The number of columns user provided. If it is -1, function will not do any padding
or truncating. But if it is larger than the size of the  matrix, it will pad zero to meet the size
if less than, it will truncate the data matrix.

Return values:
If succeed, it will return 0;	Otherwise it returns error indications.
Error:
-1: Provided column number or row number. Must be -1 or positive integer
-2: The data source matrix is empty
-3: When calling member function, it fails.
-4: When calling GetReal or GetImage member function of matrix class, it failed.
Nag Error:
11: The column or the row size of matrix is less then 1
73: System failed to allocate memory

Example:
        This example computes the 1 dimension fast fourier transform on each row of the matrix mRe.

    void test_FFT()
    {
        matrix <double> mRe = {{1,2.5,3.5,2,1.0,2.3},{3.2,4.1,2.2,1.0,4,2}};
        int ii , jj;

        matrix <complex> mResult;

        //test 1d fft function for arbitrary source matrix.//
        int Err = FFT(mRe, mResult, -1);

        if ( 0 != Err )
        {
               ASSERT(false);
               printf("one-dimension FFT fails.\n");
        }

        else
        {
            for(ii = 0; ii < mResult.GetNumRows();  ii++)
            {
                for(jj = 0; jj < mResult.GetNumCols(); jj++)
                    printf("(%f, %fi)  ",mResult[ii][jj].m_re,mResult[ii][jj].m_im);
                printf("\n");
            }
        }
    }

    The output is as following:
        (5.021454, 0.000000i)  (-0.347011, -0.954594i)  (-0.673610, 0.813173i)  (-0.530723, 0.000000i)  (-0.673610, -0.813173i)  (-0.347011, 0.954594i)
        (6.736097, 0.000000i)  (0.877734, -0.106066i)  (-0.796084, -1.378858i)  (0.938971, 0.000000i)  (-0.796084, 1.378858i)  (0.877734, 0.106066i)

Summary:
Sample data:
Header file: matrix.h
See also:
Function: FFT
Prototype:
int FFT(vector<complex>& vecSource, vector<complex>& vecFFTResult)
Remarks: This function performs 1-dimensional Fast Fourier Transform on data in a complex vector. Data vector should be of type complex. If user have the data vector in integer or double form, user should first transform it or copy it to a complex vector. This function in turn calls the matrix-based FFT function.
Parameters:
vecSource: The data source vector
vecFFTResult: The vector containing the 1-dimensional FFT result

Return values:
If succeed, it will return 0;	Otherwise it returns error indications.
Error:
-5: source vector is of zero length
n:	other error codes returned by matrix-based FFT function

Example:
        This example computes the 1-dimensional Fast Fourier Transform on a complex vector

    void FFT_test()
    {
         vector vR = { 1,2.5,3.5,2,1.0,2.3 };
        vector vI = { 1,0.5,1.0,0.8,3.1,0.3 };
        vector <complex> vC(vR, vI), vResult(vC.GetSize());

        //tedt 1d fft function on data in a complex vector
        int Err = FFT(vC, vResult);

        if ( 0 != Err )
        {
               ASSERT(false);
               printf("one-dimension FFT fails\n");
        }
        else
        {
            for(int ii = 0; ii < vResult.GetSize();  ii++)
            {
                   printf("(%f, %fi)  ",vResult[ii].m_re,vResult[ii].m_im);
                printf("\n");
            }

        }
    }

    The output is as following:
        (5.021454,  2.735264i)
        (-1.018762, -1.546554i)
        (0.139563,  0.547811i)
        (-0.530723, 1.428869i)
        (-1.486782, -1.078534i)
        (0.324740,  0.362634i)

Summary:
Sample data:
Header file: matrix.h
See also:


FFT2

Function: FFT2
Prototype:
int FFT2(matrix& matSource, matrix<complex>& matFFT2Result, int nRowProcess = -1, int nColProcess = -1)
Remarks: This function performs a 2-dimensional Fast Fourier Transform. Data matrix should be of type double. If user have the data matrix in integer form, user should first transform it to double using the member function of matrixbase "CastToDouble".
Parameters:
matSource: The data source matrix
matFFT2Result: The matrix containing the 2 dimension FFT results
nRowProcess:
nColProcess: The number of rows or columns user provided. If they are -1, there is no padding
or truncating. If they are more than the sizes of the matrix, the function will pad zero to meet the size
If less than, it will truncate the data matrix.

Return values:
If succeed, it will return 0;	Otherwise it returns error indications.
Error:
-1: Provided column number or row number. Must be -1 or positive integer
-2: The data source matrix is empty
-3: When calling member function, it fails.
-4: When calling GetReal or GetImage member function of matrix class, it failed.
Nag Error:
11: The column or the row size of matrix is less then 1
73: System failed to allocate memory

Example:
        This example computes the 2 dimension fast fourier transform of the matrix mRe.

    #include <matrix.h>
    void test_FFT2()
    {
        matrix<double> mRe = {{-1.486782,-0.530723,0.139563,-1.018762},
                           {-0.831440 ,0.938971,-0.760729,1.620196},
                           {- 0.7794,-0.5500 ,0.6640, -0.4333},
                           {-2.0366,1.9275,0.3313,1.1098}};

        matrix <complex> mResult;

        int ii,jj,Err;

        //test function FFT2 for arbitrary source matrix
        Err = FFT2(mRe, mResult);

        if ( 0 != Err )
        {
            ASSERT(false);
            printf("two-dimension FFT2 fails\n");
        }
        else
        {
            for(ii = 0; ii < mResult.GetNumRows();  ii++)
            {
                for(jj = 0; jj < mResult.GetNumCols(); jj++)
                    printf("(%f, %fi)  ",mResult[ii][jj].m_re,mResult[ii][jj].m_im);
                printf("\n");
            }
        }
    }

    The output is as following:
        (-0.424101, 0.000000i)  (-1.377089, -0.126954i)  (-1.955942, 0.000000i)  (-1.377089, 0.126954i)
        (-0.449501, 0.091251i)  (0.328995, -0.725482i)  (-0.166409, -0.147816i)  (-0.420468, -0.423113i)
        (-1.573601, 0.000000i)  (-0.157784, -0.058716i)  (2.491026, 0.000000i)  (-0.157784, 0.058716i)
        (-0.449501, -0.091251i)  (-0.420468, 0.423113i)  (-0.166409, 0.147816i)  (0.328995, 0.725482i)

Summary:
Sample data:
Header file: matrix.h
See also:
Function: FFT2
Prototype:
int FFT2(matrix<complex>& matSource, matrix<complex>& matFFT2Result, int nRowProcess = -1, int nColProcess = -1)
Remarks: This function performs a 2-dimensional Fast Fourier Transform. Data matrix should be of type complex. If user have the data matrix in integer form, user should first transform it to complex.
Parameters:
matSource: The data source matrix
matFFT2Result: The matrix containing the 2 dimension FFT results
nRowProcess:
nColProcess: The number of rows or columns user provided. If they are -1, there is no padding
or truncating. If they are more than the sizes of the matrix, the function will pad zero to meet the size
If less than, it will truncate the data matrix.

Return values:
If succeed, it will return 0;	Otherwise it returns error indications.
Error:
-1: Provided column number or row number. Must be -1 or positive integer
-2: The data source matrix is empty
-3: When calling member function, it fails.
-4: When calling GetReal or GetImage member function of matrix class, it failed.
Nag Error:
11: The column or the row size of matrix is less then 1
73: System failed to allocate memory

Example:
        This example computes the 2 dimension fast fourier transform of the matrix mSource.

    void test_FFT2()
    {
        matrix<double> mRe = {{-1.486782,-0.530723,0.139563,-1.018762},
                           {-0.831440 ,0.938971,-0.760729,1.620196},
                           {- 0.7794,-0.5500 ,0.6640, -0.4333},
                           {-2.0366,1.9275,0.3313,1.1098}};

        matrix<double> mIm = {{2.482,3.5723,0.9553,-1.01842},
                           {-1.8317 ,4.38271,-1.0729,1.226},
                           {0.7724,-0.5540 ,1.540, -1.333},
                           {2.0456,-1.935,2.6513,1.2708}};

        matrix <complex> mSource, mResult;

        mSource.MakeComplex(mRe,mIm);

        int ii,jj,Err;

        //test function FFT2 for arbitrary source matrix
        Err = FFT2(mSource, mResult);

        if ( 0 != Err )
        {
            ASSERT(false);
            printf("two-dimension FFT2 fails\n");
        }
        else
        {
            for(ii = 0; ii < mResult.GetNumRows();  ii++)
            {
                for(jj = 0; jj < mResult.GetNumCols(); jj++)
                    printf("(%f, %fi)  ",mResult[ii][jj].m_re,mResult[ii][jj].m_im);
                printf("\n");
            }
        }
    }

    The output is as following:
        (-0.424101, 3.288348i)  (-0.046932, -0.278304i)  (-1.955942, 0.482652i)  (-2.707247, -0.024397i)
        (-0.781648, 1.482696i)  (1.243650, -1.742534i)  (-3.635011, -0.976811i)  (-1.411672, 1.741090i)
        (-1.573601, -0.080057i)  (1.196919, 0.472184i)  (2.491026, 2.058758i)  (-1.512486, 0.589616i)
        (-0.117354, 1.300194i)  (0.570738, 2.587315i)  (3.302194, -0.681179i)  (-0.585660, -0.291571i)

Summary:
Sample data:
Header file: matrix.h
See also:


fitpoly

Function: fitpoly
Prototype:
BOOL fitpoly(Curve &crv, int ipolyorder, double *coeff, int inumer = 0, int idenom = 0)
Remarks: Fit a polynomial equation to a curve or curve segment and return the parameter coefficients. If specified, only the Nth segment of M equal curve segments is fit.
Parameters:
crv=Input curve to fit
ipolyorder=Input degree of polynomial equation
coeff=Output array containing parameter coefficients
inumer=Input Nth segment of M equal curve segments (default 0 fits entire range as one segment)
idenom=Input number M of equal curve segments (default 0 fits entire range as one segment)

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        // Assumes Data1_A and Data1_B exist and contain data
        Curve crv("Data1_A","Data1_B");
        double coeff[3];
        fitpoly(crv, 2, &coeff, 1, 3); // Fit 2nd degree polynomial to first of 3 equal curve segments

Summary: Fit a polynomial equation to a curve or curve segment.
Sample data:
Header file: data.h
See also: fitpoly_range initNLSF fitNLSF


fitpoly_range

Function: fitpoly_range
Prototype:
BOOL fitpoly_range(Curve &crv, int ibeg, int iend, int ipolyorder, double *coeff)
Remarks: Fit a polynomial equation to a range of a curve and return the parameter coefficients.
Parameters:
crv=Input curve to fit
ibeg=Input beginning index to fit
iend=Input ending index to fit
ipolyorder=Input degree of polynomial equation
coeff=Output array containing parameter coefficients

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        // Assumes Data1_A and Data1_B exist and contain data
        Curve crv("Data1_A","Data1_B");
        double coeff[3];
        fitpoly_range(crv, 0, crv.GetUpperBound(), 2, &coeff); // Fit 2nd degree polynomial to entire curve

Summary: Fit a polynomial equation to a range of a curve.
Sample data:
Header file: data.h
See also: fitpoly initNLSF fitNLSF


fwhm

Function: fwhm
Prototype:
double fwhm(Curve &crv, double dYoffset = 0)
Remarks: Get the peak width of a curve at half the maximum Y value.
Parameters:
crv=Input Origin C Curve object
dYoffset=Y offset subtracted from curve

Return values:
Returns the peak width of a curve at half the maximum Y value.

Example:
        // Assumes Data1_A and Data1_B exist and contain data
        Curve crv("Data1_A","Data1_B");
        double dWx = fwhm(crv);
        printf("Peak width at half maximum Y is %g", dWx);

Summary: Get the peak width of a curve at half the maximum Y value.
Sample data:
Header file: data.h
See also: area


IFFT

Function: IFFT
Prototype:
int IFFT(matrix<complex>& matSource, matrix<complex>& matFFTResult, int nColProcess = -1)
Remarks: This function performs 1-dimensional inverse Fast Fourier Transform on each row of data in a matrix. Data matrix should be of type complex. If user have the data matrix in integer form, user should first transform it to complex.
Parameters:
matSource:The data source matrix
matIFFT2Result: The matrix containing the 1 dimension inverse FFT results
nColProcess:The number of columns user provided. if it is -1, there is no padding
or truncating. if it is more than the size of the  matrix, it will pad zero to meet the size
if less than, it will truncate the data matrix.

Return values:
If succeed, it will return 0;	Otherwise it returns error indications.
Error:
-1: Provided column number or row number must be -1 or positve integer
-2: The data source matrix is empty
-3: When calling member function, it fails.
-4: When calling GetReal or GetImage member function of matrix class, it failed.
Nag Error:
11: The coloumn or the row size of matrix is less then 1;
73: System failed to allocate memory

Example:
        int test_IFFT()
        {
            matrix matSource = {{1,2,3,4,5},{6,7,8,9,10}};

            int nRet;
            matrix<complex> matResult;
            nRet = FFT(matSource,matResult, -1);
            if(nRet)
                return nRet;
            int nNumCols = matResult.GetNumCols();
            int nNumRows = matResult.GetNumRows();
            int ii, jj;
            for( ii = 0; ii < nNumRows; ii++)
            {
                for(jj = 0; jj < nNumCols; jj++)
                    printf("%f + %f i",matResult[ii][jj].m_re, matResult[ii][jj].m_im);
                printf("\n");
            }

            printf("now do the padding\n");
            nRet = FFT(matSource,matResult, 14);
            if(nRet)
                return nRet;
            //after The padding

            nNumCols = matResult.GetNumCols();
            nNumRows = matResult.GetNumRows();

            for( ii = 0; ii < nNumRows; ii++)
            {
                for(jj = 0; jj < nNumCols; jj++)
                    printf("%f + %f i",matResult[ii][jj].m_re, matResult[ii][jj].m_im);
                printf("\n");
            }
            printf("now do the truncting\n");
            //after truncting
            nRet = FFT(matSource,matResult, 6);
            if(nRet)
                return nRet;
            nNumCols = matResult.GetNumCols();
            nNumRows = matResult.GetNumRows();

            for( ii = 0; ii < nNumRows; ii++)
            {
                for(jj = 0; jj < nNumCols; jj++)
                    printf("%f + %fi ",matResult[ii][jj].m_re, matResult[ii][jj].m_im);
                printf("\n");
            }

            return nRet;
        }

Summary:
Sample data:
Header file: matrix.h
See also:
Function: IFFT
Prototype:
int IFFT(vector<complex>& vecSource, vector<complex>& vecFFTResult)
Remarks: This function performs 1-dimensional inverse Fast Fourier Transform on data in a complex vector. Data vector should be of type complex. If user have the data vector in integer or double form, user should first transform it or copy it to a complex vector. This function in turn calls the matrix-based FFT function.
Parameters:
vecSource:The data source vector
vecIFFTResult: The vector containing the 1-dimensional inverse FFT results

Return values:
If succeed, it will return 0;	Otherwise it returns error indications.
Error:
-5: source vector is of zero length
n:	other error codes returned by matrix-based FFT function

Example:
        int test_IFFT()
        {
            vector vR = { 1,2.5,3.5,2,1.0,2.3 };
            vector vI = { 1,0.5,1.0,0.8,3.1,0.3 };
            vector <complex> vC(vR, vI), vResult(vC.GetSize());

            //tedt 1d ifft function on data in a complex vector
            int Err = IFFT(vC, vResult);

            if ( 0 != Err )
            {
                   ASSERT(false);
                   printf("one-dimension IFFT fails\n");
            }
            else
            {
                for(int ii = 0; ii < vResult.GetSize();  ii++)
                {
                       printf("(%f, %fi)  ",vResult[ii].m_re,vResult[ii].m_im);
                    printf("\n");
                }
            }
        }

        The output is as following:
            (5.021454, 2.735264i)
            (0.324740, 0.362634i)
            (-1.486782, -1.078534i)
            (-0.530723, 1.428869i)
            (0.139563, 0.547811i)
            (-1.018762, -1.546554i)

Summary:
Sample data:
Header file: matrix.h
See also:


IFFT2

Function: IFFT2
Prototype:
int IFFT2(matrix<complex>& matSource, matrix<complex>& matIFFT2Result, int nRowProcess = -1, int nColProcess = -1)
Remarks: This function performs a 2-dimensional inverse Fast Fourier Transform. Data matrix should be of type complex. If user have the data matrix in integer form, user should first transform it to complex.
Parameters:
matSource: The data source matrix
matIFFT2Result: The matrix containing the 2 dimension inverse FFT results
nRowProcess:
nColProcess:The number of rows or columns user provided. if they are -1, there are no padding
or truncating. if they are larger than the size of the matrix, the function will pad zero to meet
the size. If less than, it will truncate the data matrix.

Return values:
If succeed, it will return 0;	Otherwise it returns error indications.
Error:
-1: Provided column number or row number. Must be -1 or positive integer
-2: The data source matrix is empty
-3: When calling member function, it fails.
-4: When calling GetReal or GetImage member function of matrix class, it failed.
Nag Error:
11: The column or the row size of matrix is less then 1
73: System failed to allocate memory

Example:
        This example computes the 2 dimension inverse fast fourier transform of the matrix mSource.

    void test_IFFT2()
    {
        matrix<double> mRe = {{-1.486782,-0.530723,0.139563,-1.018762},
                           {-0.831440 ,0.938971,-0.760729,1.620196},
                           {- 0.7794,-0.5500 ,0.6640, -0.4333},
                           {-2.0366,1.9275,0.3313,1.1098}};

        matrix<double> mIm = {{2.482,3.5723,0.9553,-1.01842},
                           {-1.8317 ,4.38271,-1.0729,1.226},
                           {0.7724,-0.5540 ,1.540, -1.333},
                           {2.0456,-1.935,2.6513,1.2708}};

        matrix <complex> mSource, mResult;

        mSource.MakeComplex(mRe,mIm);

        int ii,jj,Err;

        Err = IFFT2(mSource, mResult);

        if ( 0 != Err )
        {
            ASSERT(false);
            printf("two-dimension IFFT2 fails\n");
        }
        else
        {
            for(ii = 0; ii < mResult.GetNumRows();  ii++)
            {
                for(jj = 0; jj < mResult.GetNumCols(); jj++)
                    printf("(%f, %fi)  ",mResult[ii][jj].m_re,mResult[ii][jj].m_im);
                printf("\n");
            }
        }
    }

    The output is as following:
        (-0.424101, 3.288348i)  (-2.707247, -0.024397i)  (-1.955942, 0.482652i)  (-0.046932, -0.278304i)
        (-0.117354, 1.300194i)  (-0.585660, -0.291571i)  (3.302194, -0.681179i)  (0.570738, 2.587315i)
        (-1.573601, -0.080057i)  (-1.512486, 0.589616i)  (2.491026, 2.058758i)  (1.196919, 0.472184i)
        (-0.781648, 1.482696i)  (-1.411672, 1.741090i)  (-3.635011, -0.976811i)  (1.243650, -1.742534i)

Summary:
Sample data:
Header file: matrix.h
See also:


nlfFit

Function: nlfFit
Prototype:
double nlfFit(double dx, int nDepend = 0)
Remarks: Get the value of the specified dependent variable for the specified value of the independent variable. This function is used in conjunction with the internal Origin Non-linear Least Squares Fitter (NLSF) object and uses the most recent fitting function and parameter values specified through the NLSF interface or through script.
Parameters:
dx=Input value of the independent variable
nDepend=Input dependent variable (0 based offset)

Return values:
Returns the value of the specified dependent variable for the given value of the independent variable.

Example:
        // Assumes the Sample Data has been plotted in an Origin graph and has just been fit
        // using the Origin Analysis:Fit Exponential Decay:First Order menu item
        double dDVal,dIVal = 7.22;
        dDVal = nlfFit( dIVal );
        printf("The value of the fit curve at x = %g is y = %g", dIVal, dDVal );

Summary: Get the value of the specified dependent variable for the specified value of the independent variable.
Sample data: 2 10.54362 4 8.85013 6 7.51005 8 6.23363 10 5.31886 12 5.04538 14 5.47292 16 5.6315 18 5.09736 20 4.94923 22 5.10317 24 5.02472
Header file: data.h
See also: nlfXfromY


nlfXfromY

Function: nlfXfromY
Prototype:
int nlfXfromY(double dy, double* parX, int nMaxX, int nDependent=0)
Remarks: Get the value(s) of the independent variable for the specified value of the specified dependent variable. This function is used in conjunction with the internal Origin Non-linear Least Squares Fitter (NLSF) object and uses the most recent fitting function and parameter values specified through the NLSF interface or through script.
Parameters:
dy=Input value of the dependent variable
parX=Output array for the x values
nMaxX=Size of array pointed to by parX
nDepend=Input dependent variable (0 based offset)

Return values:
Returns 1 if successful and returns the value(s) of the independent variable for the given value of the
dependent variable.

Example:
        // Assumes the Sample Data has been plotted in an Origin graph and has just been fit
        // using the Origin Analysis:Fit Exponential Decay:First Order menu item
        int nMaxX=1; // 1st Order exponentional decay funtion is 1 to 1 so there is only 1 independent value per dependent value
        double dDVal = 8.067, dIVal;
        int iErr;
        iErr = nlfXfromY( dDVal, &dIVal, nMaxX );
        printf("The value of x where y = %g is %g", dDVal, dIVal );

Summary: Get the value(s) of the independent variable for the specified value of the specified dependent variable.
Sample data: 2 10.54362 4 8.85013 6 7.51005 8 6.23363 10 5.31886 12 5.04538 14 5.47292 16 5.6315 18 5.09736 20 4.94923 22 5.10317 24 5.02472
Header file: data.h
See also: nlfFit


smooth

Function: smooth
Prototype:
BOOL smooth(Curve &crv, int imethod=0, int ileftpts = 3, int irightpts = 3, int ipolydeg = 2)
Remarks: Smooth a curve using Adjacent Averaging, FFT, or Savitzky-Golay.
Parameters:
crv=Input Origin C Curve object
imethod=Input method: Adjacent Averaging (default 0), FFT (1), or Savitzky-Golay (2)
ileftpts=Input left points (default is 3)
irightpts=Input right points (default is 3, Savitzky-Golay only)
ipolydeg=Input degree of polynomial (default is 2, Savitzky-Golay only)

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        // Assumes Data1_A and Data1_B exist and contain data
        Curve crv("Data1_A","Data1_B");
        BOOL bErr = smooth(crv);

Summary: Smooth a curve using Adjacent Averaging, FFT, or Savitzky-Golay.
Sample data:
Header file: data.h
See also:


sort

Function: sort
Prototype:
BOOL sort(Curve &crv)
Remarks: Sort a curve in ascending order of X.
Parameters:
crv=Input Origin C Curve object

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        // Assumes Data1_A and Data1_B exist and contain data
        Curve crv("Data1_A","Data1_B");
        BOOL bErr = sort(crv);

Summary: Sort a curve in ascending order of X.
Sample data:
Header file: data.h
See also: Sort


SVD

Function: SVD
Prototype:
int SVD(matrix<complex>& matSource, matrix& matS, matrix<complex>& matU, matrix<complex>& matV)
Remarks: These four functions are used to do the singular value decomposition. matSource = matU* matS* matV'
Parameters:
matSource: The  m * n source data matrix
matS: The min(m, n) diaganol sigular matrix
matU: The left side  m * m unitary matrix
matV: The right side n* n unitary matrix

Return values:
if succeed, it will return 0

Example:
        int test_SVD()
        {
            matrix matData= { { 2, 2.5, 2.5}, {2.0, 2.5, 2.5}, {1.6, -0.4, 2.8}, {2.0, -0.5, 0.5}, {1.2, -0.3, -2.9}};
            printf("The source data\n");

            int nNumCols = matData.GetNumCols();
            int nNumRows = matData.GetNumRows();
            int ii, jj;

            for( ii = 0; ii < nNumRows; ii++)
            {
                for(jj = 0; jj < nNumCols; jj++)
                    printf("%f ",matData[ii][jj]);
                printf("\n");
            }
            matrix matS;
            printf("Find the singular value\n");

            int nRet;
            if(nRet = SVD(matData, matS))
                return nRet;

            nNumCols = matS.GetNumCols();
            nNumRows = matS.GetNumRows();
            for( ii = 0; ii < nNumRows; ii++)
            {
                for(jj = 0; jj < nNumCols; jj++)
                    printf("%f ",matS[ii][jj]);
                printf("\n");
            }
            printf("Find the U and V\n");
            matrix matU, matV;
            if(nRet = SVD(matData, matS, matU, matV))
                return nRet;
            printf("U is\n");
            nNumCols = matU.GetNumCols();
            nNumRows = matU.GetNumRows();
            for( ii = 0; ii < nNumRows; ii++)
            {
                for(jj = 0; jj < nNumCols; jj++)
                    printf("%f ",matU[ii][jj]);
                printf("\n");
            }
            printf("V is \n");
            nNumCols = matV.GetNumCols();
            nNumRows = matV.GetNumRows();
            for( ii = 0; ii < nNumRows; ii++)
            {
                for(jj = 0; jj < nNumCols; jj++)
                    printf("%f ",matV[ii][jj]);
                printf("\n");
            }

            return nRet;
        }

Summary:
Sample data:
Header file: matrix.h
See also:
Function: SVD
Prototype:
int SVD(matrix<complex>& matSource, matrix<complex>& matS)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: matrix.h
See also:
Function: SVD
Prototype:
int SVD(matrix& matSource, matrix& matS)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: matrix.h
See also:
Function: SVD
Prototype:
int SVD(matrix& matSource, matrix& matS, matrix& matU, matrix& matV)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: matrix.h
See also:


Trace

Function: Trace
Prototype:
int Trace(matrix<short> & matSource, int & nSum)
Remarks: These four functions will give the trace of a matrix we do not support every matrix type.
Parameters:
matSource: The source matrix
nSum:
dSum:
cSum:
These are the variables to store the trace.

Return values:
if succeed, it will return 0

Example:
         int test_Trace()
         {
            matrix matSource = {{1,2,3},{5,6,7},{9,10,11}};
            printf("the source matrix\n");
            int ii, jj;

            int nNumCols = matSource.GetNumCols();
            int nNumRows = matSource.GetNumRows();

            for(ii = 0; ii < nNumRows; ii++)
            {
                for(jj = 0; jj < nNumCols; jj++)
                    printf("%f  ",matSource[ii][jj]);
                printf("\n");
            }
            int nRet;
            double dTrace;
            if(nRet = Trace(matSource, dTrace))
                return nRet;
            printf("The trace is: %f",dTrace);
            return nRet;
         }

Summary:
Sample data:
Header file: matrix.h
See also:
Function: Trace
Prototype:
int Trace(matrix<int> & matSource, int & nSum)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: matrix.h
See also:
Function: Trace
Prototype:
int Trace(matrix<double> & matSource, double & dSum)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: matrix.h
See also:
Function: Trace
Prototype:
int Trace(matrix<complex> & matSource, complex & cSum)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: matrix.h
See also:


xatasymt

Function: xatasymt
Prototype:
double xatasymt(Curve &crv)
Remarks: Get the value of X at a vertical asymptote. If the asymptote has two branches then X is defined as X = (xatymax+xatymin)/2 and if the asymptote has a single branch then X is defined as either xatymax or xatymin depending on where the reciprocal of the slope of the curve is closest to zero.
Parameters:
crv=Input curve whose asymptote is found

Return values:
Returns the value of X at a vertical asymptote.

Example:
        // Assumes Data1_A and Data1_B exist and contain the Sample Data
        Curve crv("Data1_A","Data1_B");
        double dXatVA = xatasymt(crv);
        printf("The value of X at the Vertical Asymptote is %g",dXatVA);

Summary: Get the value of X at a vertical asymptote.
Sample data: -20 -3.04762 -14 -3.06667 -8 -3.11111 -2 -3.33333 -1 -3.5 0 -4 1 -- 2 -2 3 -2.5 4 -2.66667 10 -2.88889 16 -2.93333 22 -2.95238
Header file: data.h
See also: yatasymt xatymax xatymin


xaty50

Function: xaty50
Prototype:
double xaty50(Curve &crv)
Remarks: Get the value of X at the 50th percentile Y value of a curve.
Parameters:
crv=Input Origin C Curve object

Return values:
Returns the value of X at the 50th percentile Y value of a curve.

Example:
        // Assumes Data1_A and Data1_B exist and contain data
        Curve crv("Data1_A","Data1_B");
        double dXatY50 = xaty50(crv);
        printf("Value of X at 50th Percentile of Y is %g", dXatY50);

Summary: Get the value of X at the 50th percentile Y value of a curve.
Sample data:
Header file: data.h
See also: xatymin xatymax yatxmin yatxmax


xatymax

Function: xatymax
Prototype:
double xatymax(Curve &crv)
Remarks: Get the value of X at the maximum Y value of a curve.
Parameters:
crv=Input Origin C Curve object

Return values:
Returns the value of X at the maximum Y value of a curve.

Example:
        // Assumes Data1_A and Data1_B exist and contain data
        Curve crv("Data1_A","Data1_B");
        double dXatYmax = xatymax(crv);
        printf("Value of X at maximum Y is %g", dXatYmax);

Summary: Get the value of X at the maximum Y value of a curve.
Sample data:
Header file: data.h
See also: xatymin yatxmin yatxmax xaty50


xatymin

Function: xatymin
Prototype:
double xatymin(Curve &crv)
Remarks: Get the value of X at the minimum Y value of a curve.
Parameters:
crv=Input Origin C Curve object

Return values:
Returns the value of X at the minimum Y value of a curve.

Example:
        // Assumes Data1_A and Data1_B exist and contain data
        Curve crv("Data1_A","Data1_B");
        double dXatYmin = xatymin(crv);
        printf("Value of X at minimum Y is %g", dXatYmin);

Summary: Get the value of X at the minimum Y value of a curve.
Sample data:
Header file: data.h
See also: xatymax yatxmin yatxmax xaty50


y25

Function: y25
Prototype:
double y25(Dataset &ds)
Remarks: Get the 25th percentile of a data set.
Parameters:
ds=Input Origin C Dataset object

Return values:
Returns the 25th percentile of a data set.

Example:
        // Assumes Data1_A exists and contains data
        Dataset dsA("Data1_A");
        double dP25 = y25(dsA);
        printf("25th Percentile of Data1_A is %g", dP25);

Summary: Get the 25th percentile of a data set.
Sample data:
Header file: data.h
See also: y50 y75


y50

Function: y50
Prototype:
double y50(Dataset &ds)
Remarks: Get the 50th percentile of a data set.
Parameters:
ds=Input Origin C Dataset object

Return values:
Returns the 50th percentile of a data set.

Example:
        // Assumes Data1_A exists and contains data
        Dataset dsA("Data1_A");
        double dP50 = y50(dsA);
        printf("50th Percentile of Data1_A is %g", dP50);

Summary: Get the 50th percentile of a data set.
Sample data:
Header file: data.h
See also: y25 y75


y75

Function: y75
Prototype:
double y75(Dataset &ds)
Remarks: Get the 75th percentile of a data set.
Parameters:
ds=Input Origin C Dataset object

Return values:
Returns the 75th percentile of a data set.

Example:
        // Assumes Data1_A exists and contains data
        Dataset dsA("Data1_A");
        double dP75 = y75(dsA);
        printf("75th Percentile of Data1_A is %g", dP75);

Summary: Get the 75th percentile of a data set.
Sample data:
Header file: data.h
See also: y25 y50


yatasymt

Function: yatasymt
Prototype:
double yatasymt(Curve &crv)
Remarks: Get the value of Y at a horizontal asymptote. If the asymptote has two branches then Y is defined as Y = (yatxmax+yatxmin)/2 and if the asymptote has a single branch then Y is defined as either yatxmax or yatxmin depending on where the slope of the curve is closest to zero.
Parameters:
crv=Input curve whose asymptote is found

Return values:
Returns the value of Y at a horizontal asymptote.

Example:
        // Assumes Data1_A and Data1_B exist and contain the Sample Data
        Curve crv("Data1_A","Data1_B");
        double dYatHA = yatasymt(crv);
        printf("The value of Y at the Horizontal Asymptote is %g",dYatHA);

Summary: Get the value of Y at a horizontal asymptote.
Sample data: -20 -3.04762 -14 -3.06667 -8 -3.11111 -2 -3.33333 -1 -3.5 0 -4 1 -- 2 -2 3 -2.5 4 -2.66667 10 -2.88889 16 -2.93333 22 -2.95238
Header file: data.h
See also: xatasymt yatxmax yatxmin


yatxmax

Function: yatxmax
Prototype:
double yatxmax(Curve &crv)
Remarks: Get the value of Y at the maximum X value of a curve.
Parameters:
crv=Input Origin C Curve object

Return values:
Returns the value of Y at the maximum X value of a curve.

Example:
        // Assumes Data1_A and Data1_B exist and contain data
        Curve crv("Data1_A","Data1_B");
        double dYatXmax = yatxmax(crv);
        printf("Value of Y at maximum X is %g", dYatXmax);

Summary: Get the value of Y at the maximum X value of a curve.
Sample data:
Header file: data.h
See also: xatymin yatxmin xatymax xaty50


yatxmin

Function: yatxmin
Prototype:
double yatxmin(Curve &crv)
Remarks: Get the value of Y at the minimum X value of a curve.
Parameters:
crv=Input Origin C Curve object

Return values:
Returns the value of Y at the minimum X value of a curve.

Example:
        // Assumes Data1_A and Data1_B exist and contain data
        Curve crv("Data1_A","Data1_B");
        double dYatXmin = yatxmin(crv);
        printf("Value of Y at minimum X is %g", dYatXmin);

Summary: Get the value of Y at the minimum X value of a curve.
Sample data:
Header file: data.h
See also: xatymin xatymax yatxmax xaty50


out_double

Function: out_double
Prototype:
int out_double(LPCSTR lpcstr, double dbValue)
Remarks: a simple function to print a double value, output will be the current output window, can be the Script Window, the output log or the labtalk console.
Parameters:

Return values:
the number of characters printed

Example:
        double	vv = sin(3.14);
        out_double("vv = ",vv);

Summary:
Sample data:
Header file: stdio.h
See also: out_str out_int


out_int

Function: out_int
Prototype:
int out_int(LPCSTR lpcstr, int nValue)
Remarks: a simple function to print an integer, output will be the current output window, can be the Script Window, the output log or the labtalk console.
Parameters:

Return values:
the number of characters printed

Example:
        int	nn = 4;
        out_int("nn = ",nn);

Summary:
Sample data:
Header file: stdio.h
See also: out_double out_str


out_str

Function: out_str
Prototype:
int out_str(LPCSTR lpcstr)
Remarks: a simple function to print a string, output will be the current output window, can be the Script Window, the output log or the labtalk console.
Parameters:

Return values:
the number of characters printed

Example:
        string	str = "test";
        out_str(str);

Summary:
Sample data:
Header file: stdio.h
See also: out_double out_int


printf

Function: printf
Prototype:
int printf(LPCSTR lpcszFormat, ...)
Remarks: Standard C printf function. Output will be the current output window, can be the Script Window, the output log or the labtalk console.
Parameters:

Return values:

Example:
        double vv = cos(3.14);
        int		nn = 45;
        string	str = "Test";
        printf("For str(%s) and nn=%d, vv=%f\n",str, nn, vv);

Summary:
Sample data:
Header file: stdio.h
See also: format


out_complex

Function: out_complex
Prototype:
int out_complex(LPCSTR lpcstr, complex z)
Remarks: outputs a complex value
Parameters:
lpcstr = a pointer to a string which will preceed the value.
z = the complex value to be output.

Return values:
number of characters that are output.

Example:
        void	run_complex_out_complex()
        {
            complex		cc(4.5, 7.8);

            out_complex("The value = ", cc);
        }

Summary:
Sample data:
Header file: complex.h
See also:


out_tree

Function: out_tree
Prototype:
bool out_tree(TreeNode& tr, int nLevel = 0)
Remarks: quick display of a tree, only the tagName and Text are shown
Parameters:
tr = TreeNode to dump to output
nLevel = 0, this function is called recursively inside, so there is no need to use this parameter from your code

Return values:
TRUE if given tree is a valid TreeNode
See Also:
tree_dump

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_dump

Function: tree_dump
Prototype:
bool tree_dump(const TreeNode& tr, LPCSTR lpcsz = NULL, int nOutput = WRITE_SCRIPT_WINDOW)
Remarks: dump a tree to a specified output, also show standard attributes if any
Parameters:
tr = TreeNode to dump to output
lpcsz = optional string to diplay before the dump
nOutput = one of the constants defined in oc_const.h,
enum {WRITE_SCRIPT_WINDOW, WRITE_STATUS_BAR, WRITE_OUTPUT_LOG, WRITE_MESSAGE_BOX, WRITE_COMPILER_OUTPUT};
nLevel = 0, this function is called recursively inside, so there is no need to use this parameter from your code

Return values:
TRUE if given tree is a valid TreeNode
See Also:
out_tree

Example:

Summary: = NULL, 0, 0
Sample data:
Header file: tree_utils.h
See also:


atoc

Function: atoc
Prototype:
complex atoc(LPCSTR lpcsz)
Remarks:
Parameters:

Return values:

Example:
        void 	run_complex_atoc()
        {
            complex 	cc;
            string 		str = "  2 + 1.35i";

            cc = atoc(str);

            // Display the value:
            out_complex("value = ",cc);
        }

Summary:
Sample data:
Header file: complex.h
See also:


_stricmp

Function: _stricmp
Prototype:
int _stricmp(LPCSTR lpString1, LPCSTR lpString2)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: string.h
See also:


lstrcat

Function: lstrcat
Prototype:
LPSTR WINAPI lstrcat(LPSTR lpString1, LPCSTR lpString2)
Remarks: The lstrcat (alias strcat) function appends one string to another.
Parameters:
lpString1=Pointer to a null-terminated string. The buffer must be large enough to contain both strings.
lpString2=Pointer to the null-terminated string to be appended to the string specified in the lpString1 parameter.

Return values:
If the function succeeds, the return value is a pointer to the buffer.  If the function fails, the return value is NULL.

Example:
        char		szStr[80] = "This is the first part. ";
        string		str1 = "This is the second part.";
        // Concatenate:
        lstrcat(szStr, str1);
        out_str(szStr);

Summary:
Sample data:
Header file: string.h
See also:


lstrcmp

Function: lstrcmp
Prototype:
int WINAPI lstrcmp(LPCSTR lpString1, LPCSTR lpString2)
Remarks: The lstrcmp (alias strcmp) function compares two character strings. The comparison is case sensitive.
Parameters:
lpString1=Pointer to the first null-terminated string to be compared.
lpString2=Pointer to the second null-terminated string to be compared.

Return values:
If the string pointed to by lpString1 is less than the string pointed to by lpString2, the return value is negative.
If the string pointed to by lpString1 is greater than the string pointed to by lpString2, the return value is positive.
If the strings are equal, the return value is zero.

Example:
        string	str1 = "Hello World!";
        int 	cmp = lstrcmp(str1, "HELLO WORLD!");	// cmp equals -1.
        out_int("cmp = ", cmp);

Summary:
Sample data:
Header file: string.h
See also:


lstrcmpi

Function: lstrcmpi
Prototype:
int WINAPI lstrcmpi(LPCSTR lpString1, LPCSTR lpString2)
Remarks: The lstrcmpi (alias stricmp) function compares two character strings. The comparison is not case sensitive.
Parameters:
lpString1=Pointer to the first null-terminated string to be compared.
lpString2=Pointer to the second null-terminated string to be compared.

Return values:
If the string pointed to by lpString1 is less than the string pointed to by lpString2, the return value is negative.
If the string pointed to by lpString1 is greater than the string pointed to by lpString2, the return value is positive.
If the strings are equal, the return value is zero.

Example:
        string	str1 = "Hello World!";
        int 	cmp = lstrcmpi(str1, "HELLO WORLD!");	// cmp equals 0.
        out_int("cmp = ", cmp);

Summary:
Sample data:
Header file: string.h
See also:


lstrcpy

Function: lstrcpy
Prototype:
LPSTR WINAPI lstrcpy(LPSTR lpString1, LPCSTR lpString2)
Remarks: The lstrcpy (alias strcpy) function copies a string to a buffer.
Parameters:
lpString1=Pointer to the destination buffer to receive the contents of the string pointed to by the lpString2 parameter.
The buffer must be large enough to contain the string, including the terminating null character.
lpString=Pointer to the null-terminated source string to be copied.

Return values:
If the function succeeds, the return value is a pointer to the destination buffer. If the function fails,
the return value is NULL.

Example:
        char		szStr[80];
        string		str1 = "Here is some text";
        // Copy str1 to szStr:
        lstrcpy(szStr, str1);
        out_str(szStr);

Summary:
Sample data:
Header file: string.h
See also:


lstrcpyn

Function: lstrcpyn
Prototype:
LPSTR WINAPI lstrcpyn(LPSTR lpString1, LPCSTR lpString2, int iMaxLength)
Remarks: The lstrcpyn (alias strncpy) function copies a specified number of characters from a source string into a buffer.
Parameters:
lpString1=Pointer to a buffer into which the function copies characters. The buffer must be large enough to contain
the number of characters specified by iMaxLength, including room for a terminating null character.
lpString2=Pointer to a null-terminated string from which the function copies characters.
iMaxLength=Specifies the number of characters to be copied from the string pointed to by lpString2 into the buffer
pointed to by lpString1, including a terminating null character.

Return values:
If the function succeeds, the return value is a pointer to the buffer.  If the function fails, the return value is NULL.

Example:
        string		str1 = "Hello World!";
        char		szStr[80];
        lstrcpyn(szStr, str1, 5);
        out_str(szStr);	// Should be "Hell"

Summary:
Sample data:
Header file: string.h
See also:


lstrlen

Function: lstrlen
Prototype:
int WINAPI lstrlen(LPCSTR lpString)
Remarks: The lstrlen (alias strlen) function returns the length of a string in bytes.
Parameters:
lpString=Pointer to a null-terminated string.

Return values:
the length of the string (not including zero termination).

Example:
        string		str1 = "Hello World!";
        int			len = lstrlen(str1);	// len is 12 (the length of str1).
        out_int("The length is ", len);

Summary:
Sample data:
Header file: string.h
See also:


memchr

Function: memchr
Prototype:
LPVOID memchr( LPCVOID buf, int c, size_t count )
Remarks: Find a pointer to first occurrence of character.
Parameters:
buf=Buffer to search in
c=Character to search for
count=Number of characters to search in buffer

Return values:
Returns a pointer to first occurrence of character.

Example:
        char * pChar;
        char str1[] = "Mississippi";
        pChar=(char*) memchr(str1,'s',11);
        out_str(pChar);

Summary: Find a pointer to first occurrence of character.
Sample data:
Header file: string.h
See also:


memcmp

Function: memcmp
Prototype:
int memcmp(LPCVOID lpMem1, LPCVOID lpMem2, UINT uSize)
Remarks: Compares characters between two buffers.
Parameters:
lpMem1: First buffer
lpMem2: Second buffer
nSize:  Number of characters to compare.

Return values:
Returns an integer < 0 if lpMem1 is less than lpMem2, returns 0 if lpMem1 is identical to lpMem2, and returns
an integer > 0 if lpMem1 greater than lpMem2.

Example:
        char	szFirst[] = "12345678901234567890";
        char	szSecond[] = "12345678901234567891";
        int		nNumerOfBytesToCompare = 19;	// change this to 20 to see a different result

        int		nResult = memcmp(szFirst, szSecond, nNumerOfBytesToCompare);
        if (0 == nResult)
            out_str("Equal");
        else if (0 > nResult)
            out_str("First is less than second");
        else
            out_str("First is greater than second");

Summary: Compares characters between two buffers.
Sample data:
Header file: string.h
See also:


memcpy

Function: memcpy
Prototype:
LPVOID memcpy(LPVOID lpDestination, const LPVOID lpSource, UINT uSize)
Remarks: Copy characters between buffers.
Parameters:
lpDestination=New buffer
lpSource=Buffer to copy from
nSize=Number of characters to copy

Return values:
The value of lpDestination.

Example:
        struct myStruct
        {
                int myint;
                double mydouble;
        };

        myStruct aa, bb;
        memset(&aa, 5, sizeof(myStruct));	// Set every byte of structure aa to 5.
        memset(&bb, 0, sizeof(myStruct));	// Set every byte of structure bb to 0.
        memcpy(&aa, &bb, sizeof(myStruct));	// Now every byte of structure aa is 0 too.

Summary: Copy characters between buffers.
Sample data:
Header file: string.h
See also:


memmove

Function: memmove
Prototype:
LPVOID memmove( LPVOID dest, LPCVOID src, size_t count )
Remarks: Move contents of one buffer to another.
Parameters:
dest=Destination buffer
src=Source buffer
count=Number of characters to move

Return values:
Returns a pointer to moved characters.

Example:
        char * pRet;
        char str1[40];
        char str2[] = "Hello World!xxxxxxxx";
        printf( "String1 = %s\n", str1 );
        printf( "String2 = %s\n", str2 );
        pRet = (char *) memmove(str1,str2,12);
        out_str(pRet);
        printf( "String1 = %s\n", str1 );
        printf( "String2 = %s\n", str2 );

Summary: Move contents of one buffer to another.
Sample data:
Header file: string.h
See also:


memset

Function: memset
Prototype:
LPVOID memset(LPVOID lpMem, int nValue, UINT uSize)
Remarks: Set buffers to a specified character.
Parameters:
lpMem=Pointer to lpMem
nValue=Integer value to set
nSize=Number of integer value

Return values:
The value of lpMem.

Example:
        int aa;
        memset(&aa, 10, sizeof(int));

Summary: Set buffers to a specified character.
Sample data:
Header file: string.h
See also:


sprintf

Function: sprintf
Prototype:
int sprintf( LPSTR lpszBuffer, LPCSTR lpcszFormat, ... )
Remarks: Write data values stored in a series of user specified variables into a string according to a standard C format specification.
Parameters:
lpcszBuffer=String where formated data is written
lpcszFormat=Standard C format specification
...=A comma separated list of user specified variables holding data values

Return values:
Returns the number of characters which are written into the string.

Example:
        char str1[] = "Hello", str2[50];
        char cChar = 'C';
        int N, iInt = 15;
        float fFloat = 17.56;
        N = sprintf( str2, "%s %c %d %f", str1, cChar, iInt, fFloat);
        out_str(str1);
        printf("%c\n",cChar);
        out_int("",iInt);
        out_double("",fFloat);
        out_str(str2);

Summary: Write data into a string according to a standard C format specification.
Sample data:
Header file: string.h
See also: Format


sscanf

Function: sscanf
Prototype:
int sscanf( LPCSTR lpcszBuffer, LPCSTR lpcszFormat, ... )
Remarks: Read data from a string according to a standard C format specification and return data values in a series of user specified receptor variables.
Parameters:
lpcszBuffer=String to search through for formated data
lpcszFormat=Standard C format specification
...=A comma separated list of receptor variables to hold returned data values

Return values:
Returns the number of data values which are returned in receptor variables and data values
in receptor variables.

Example:
        char str2[10], str1[]="Hello C 15 17.56";
        char cChar;
        int iInt;
        float fFloat;
        int N;
        N = sscanf( str1, "%s %c %d %f", str2, &cChar, &iInt, &fFloat);
        out_str(str1);
        out_str(str2);
        printf("%c\n",cChar);
        out_int("",iInt);
        out_double("",fFloat);

Summary: Read data from a string according to a standard C format specification.
Sample data:
Header file: string.h
See also:


strcat

Function: strcat
Prototype:
LPSTR strcat(LPSTR lpString1, LPCSTR lpString2)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: string.h
See also:


strchr

Function: strchr
Prototype:
LPSTR strchr(LPCSTR lpcszStr, int cc)
Remarks: Find the first occurrence of a character in a string.
Parameters:
lpcszStr=NULL terminated source string
cc=Character to be located

Return values:
Returns a pointer to the first occurrence of a character in a string.

Example:
        string	str1 = "Hello World!";
        out_str(strchr(str1,'W'));
        ASSERT(strchr(str1,'A')==NULL);

Summary: Find the first occurrence of a character in a string.
Sample data:
Header file: string.h
See also:


strcmp

Function: strcmp
Prototype:
int strcmp(LPCSTR lpString1, LPCSTR lpString2)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: string.h
See also:


strcpy

Function: strcpy
Prototype:
LPSTR strcpy(LPSTR lpString1, LPCSTR lpString2)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: string.h
See also:


strcspn

Function: strcspn
Prototype:
size_t strcspn( LPCSTR lpcszString, LPCSTR lpcszCharSet )
Remarks: Find a prefix substring in a string not containing any characters in a specified character set.
Parameters:
lpcszString=String to search through
lpcszCharSet=String containing specified character set

Return values:
Returns the 0 based index of the first character in a string that is
in a specified character set. All characters before returned index
are not in character set.

Example:
        char str1[] = "Mississippi";
        ASSERT(strcspn( str1, "qrst" )==2);

Summary: Find a prefix substring in a string not containing any characters in a specified character set.
Sample data:
Header file: string.h
See also:


strerror

Function: strerror
Prototype:
LPSTR strerror( int iErrNum )
Remarks: Get a system error message (strerror) or print a user-supplied error message (_strerror).
Parameters:
iErrNum=Error number whose error message is returned

Return values:
Returns a pointer to the first character of an error message associated with iErrNum.

Example:
        char * pErr;
        string strPrevious;
        int ii = 0;
        for(;1;)
        {
            strPrevious = pErr;
            pErr = strerror(ii++);
            if( strcmp(pErr,strPrevious)==0 )
                break;
            out_str(pErr);
        }

Summary: Get a system error message (strerror) or print a user-supplied error message (_strerror).
Sample data:
Header file: string.h
See also:


stricmp

Function: stricmp
Prototype:
int stricmp(LPCSTR lpString1, LPCSTR lpString2)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: string.h
See also:


strlen

Function: strlen
Prototype:
int strlen(LPCSTR lpString)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: string.h
See also:


strncat

Function: strncat
Prototype:
LPSTR strncat( LPSTR lpszDestination, LPCSTR lpcszSource, size_t count )
Remarks: Append the first N characters of one string to a second string.
Parameters:
lpszDestination=String that is appended to
lpcszSource=String that is appended
count=Number of characters to append

Return values:
Returns a pointer to the destination string with N characters from source string appended.

Example:
        char str1[]="Hello world from ";
        strncat( str1, "strcpy!xxxxxxxx", 7 );
        out_str( str1 );

Summary: Append the first N characters of one string to a second string.
Sample data:
Header file: string.h
See also:


strncmp

Function: strncmp
Prototype:
int strncmp( LPCSTR lpcszString1, LPCSTR lpcszString2, size_t count )
Remarks: Compare the first N characters of two strings.
Parameters:
lpcszString1=First of two strings to compare
lpcszString2=Second of two strings to compare
count=Number of characters N to compare

Return values:
Returns an integer < 0 if the first N characters of string1 are alpha-numerically less than
string2, returns 0 if the first N characters of string1 are the same as string2, and returns
an integer > 0 if the first N characters of string1 are alpha-numerically greater than string2.

Example:
        char str1[] = "Hello world!xxxxxxxx";
        char str2[] = "Hello world!";
        printf( "String1 = %s\n", str1 );
        printf( "String2 = %s\n", str2 );
        ASSERT(strcmp(str1,str2)!=0);
        ASSERT(strncmp(str1,str2,12)==0);

Summary: Compare the first N characters of two strings.
Sample data:
Header file: string.h
See also:


strncpy

Function: strncpy
Prototype:
LPSTR strncpy(LPSTR lpString1, LPCSTR lpString2, int iMaxLength)
Remarks: The strncpy function copies a specified number of characters from a source string into a buffer.
Parameters:
lpString1=Pointer to a buffer into which the function copies characters. The buffer must be large enough to contain the number of characters specified by iMaxLength.
lpString2=Pointer to a null-terminated string from which the function copies characters.
iMaxLength=Specifies the number of characters to be copied from the string pointed to by lpString2 into the buffer pointed to by lpString1, without a terminating null character.
Return values:
If the function succeeds, the return value is a pointer to the buffer.  If the function fails, the return value is NULL.

Return values:

Example:
        string		str1 = "Hello World!";
        char		szStr[80];
        strncpy(szStr, str1, 5);
        out_str(szStr);	// Should be "Hello"

Summary:
Sample data:
Header file: string.h
See also:


strpbrk

Function: strpbrk
Prototype:
LPSTR strpbrk( LPCSTR lpcszString, LPCSTR lpcszCharSet )
Remarks: Scan strings for characters in a specified character set.
Parameters:
lpcszString=String to search through
lpcszCharSet=String containing specified character set

Return values:
Returns a pointer to the first occurrence of a character in a string that is in specified a character set.

Example:
        char str1[] = "I saw 3 blind mice";
        char* pdest = strpbrk(str1,"123456789");
        out_str(pdest);
        ASSERT(strcmp(pdest,"3 blind mice")==0);

Summary: Scan strings for characters in a specified character set.
Sample data:
Header file: string.h
See also:


strrchr

Function: strrchr
Prototype:
LPSTR strrchr(LPCSTR lpcszStr, int cc)
Remarks: Scan a string for the last occurrence of a character.
Parameters:
lpcszStr=Null terminated source string
cc=Character to be located

Return values:
Returns a pointer to the last occurrence of a character in a string.

Example:
        string	str1 = "Hello World!";
        out_str(strrchr(str1,'o'));
        ASSERT(strrchr(str1,'A')==NULL);

Summary: Scan a string for the last occurrence of a character.
Sample data:
Header file: string.h
See also:


strspn

Function: strspn
Prototype:
size_t strspn( LPCSTR lpcszString, LPCSTR lpcszCharSet )
Remarks: Find a prefix substring in a string consisting entirely of characters in a specified character set.
Parameters:
lpcszString=String to search through
lpcszCharSet=String containing specified character set

Return values:
Returns the 0 based index of the first character in a string that is
not in a specified character set. All characters before returned index
are in the character set.

Example:
        char str1[] = "Mississippi";
        ASSERT(strspn( str1, "Mis" )==8);
        ASSERT(strspn( str1, "Misp" )==strlen(str1));

Summary: Find a prefix substring in a string consisting entirely of characters in a specified character set.
Sample data:
Header file: string.h
See also:


strstr

Function: strstr
Prototype:
LPSTR strstr( LPCSTR lpcszString, LPCSTR lpcszCharSet )
Remarks: Find a substring.
Parameters:
lpcszString=String to search through
lpcszCharSet=Substring to search for

Return values:
Returns a pointer to the first character of a substring.

Example:
        char str1[] = "I saw 3 blind mice";
        char * pdest = strstr(str1,"blind");
        out_str(pdest);
        ASSERT(strcmp(pdest,"blind mice")==0);

Summary: Find a substring.
Sample data:
Header file: string.h
See also:


strtok

Function: strtok
Prototype:
LPSTR strtok( LPCSTR lpszStrToken, LPCSTR lpcszDelimit )
Remarks: Find the next token in a string.
Parameters:
lpszStrToken=String containing tokens to be parsed
lpcszDelimit=String containing delimiters

Return values:
Returns a pointer to the first character of the next token.

Example:
        char str9[] = "This,is a.list\tof:tokens";
        char str10[] = ", .\t:";
        char * ptok;
        ptok = strtok(str9,str10);
        out_str(ptok);
        while(ptok=strtok(NULL,str10))
            out_str(ptok);

Summary: Find the next token in a string.
Sample data:
Header file: string.h
See also:


append_blanks_to_size

Function: append_blanks_to_size
Prototype:
void append_blanks_to_size(string &str, int nSize)
Remarks: It appends to the string str the ' ' characters until its size reaches nSize.
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: sys_utils.h
See also:


atof

Function: atof
Prototype:
double atof(LPCSTR lpcsz)
Remarks: Converts string to a double.
Parameters:
lpcsz = the string to convert

Return values:
a double value.

Example:
        void	run_atof()
        {
            char	szString[] = "-234.789";
            double	rr = atof(szString);
            out_double("value = ", rr);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


atoi

Function: atoi
Prototype:
int atoi(LPCSTR lpcsz)
Remarks: Converts string to an integer.
Parameters:
lpcsz = the string to convert.

Return values:
an integer value.

Example:
        void	run_atoi()
        {
            char	szString[] = "-234987";
            int		nn = atoi(szString);
            out_int("value = ", nn);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


atol

Function: atol
Prototype:
long atol(LPCSTR lpcsz)
Remarks: Converts string to a long.
Parameters:
lpcsz = the string to convert.

Return values:
a long value

Example:
        void	run_atol()
        {
            char	szString[] = "-556677";
            long	nn = atol(szString);
            out_int("value = ", nn);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


GetDecimalChar

Function: GetDecimalChar
Prototype:
char GetDecimalChar()
Remarks: GetDecimalChar is used to return the character used inside Origin for decimal in numbers
Parameters:

Return values:
numeric decimal character, typically period('.') or comma(',').

Example:
        void	run_GetDecimalChar()
        {
            char	chDecimalCharacter = GetDecimalChar();

            printf("Decimal character is %c\n", chDecimalCharacter);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


memory_replace

Function: memory_replace
Prototype:
int memory_replace(LPSTR lpBuff, int nSize, LPSTR chOldList, int nOldListSize, char chNew)
Remarks: Replace all occurances of certain characters in given buffer with a new character
Parameters:
lpBuff = input and output buffer to replace characters with
nSize = size in bytes of lpBuff
chOldList = an array of bytes that we need to replace, zero is allowed
nOldListSize = size of the chOldList array
chNew = new character to replace any of the characters in chOldList

Return values:
number of replacement, or -1 if error

Example:
        char szTemp[10] = "A\tB\r\nC";
        char szNonePrintable[] = "\t\r\n";
        memory_replace(szTemp, lstrlen(szTemp),szNonePrintable,lstrlen(szNonePrintable),'.');
        out_str(szTemp);

Summary:
Sample data:
Header file: utilities.h
See also:


CreateObject

Function: CreateObject
Prototype:
Object CreateObject(LPCSTR lpcszObjectName)
Remarks: Create an automation (COM) object. This function is available only for OriginPro versions, or with a special COM enabled license
Parameters:
lpcszObjectName=Name of the object to be created

Return values:
Returns a reference to the created object.

Example:
        void	run_CreateObject()
        {
            Object	obj;
            // Create an MS Word application object:
            obj = CreateObject("Word.Application");
            // Make the application visible
            obj.Visible = true;
        }

Summary: Create an automation (COM) object.
Sample data:
Header file: utilities.h
See also:


SetEventHandlerForObject

Function: SetEventHandlerForObject
Prototype:
int SetEventHandlerForObject(Object *pObj, LPCSTR lpcszEventName, Function *pOCFunc)
Remarks: It sets up an event handler for an automation object. This function is available only for OriginPro versions, or with a special COM enabled license
Parameters:
pObj = pointer to an existing COM object reference  which must have been initialized.
lpcszEventName = event name (it can retrieved from the object library for the given object)
pOCFunc = pointer to a Function object which has been intialized with an existing Origin C function.

Return values:
0 if the event handler was set up successfully, 2 if an events COM interface cannot be retrieved from
the object, 3 if the event name was wrong,

Example:
        Object	obj;	// this is the object which will fire an event
        // This is the event handler which catches the event. The prototype must agree
        // with the event's declaration, which can be found out by inspecting
        // the object library for each particular object.
        void	MyEventHandler()
        {
            printf("Event hanled\r\n");
        }
        void	run_SetEventHandlerForObject()
        {
            // Declare a function object (the function MyEventHandler must have been defined before)
            Function		fnEventHandler(MyEventHandler);

            Object obj = CreateObject("SomeObject.SomeObject");

            int		iRet;
            // This sets up the event handler. It tells the object obj: Call the function
            // MyEventHandler when event "SomeEvent" happens.
            iRet = SetEventHandlerForObject(&obj, "SomeEvent", &fnEventHandler);
            if (0 == iRet)
                out_str("Eevent handler set up successfully.");
        }

Summary:
Sample data:
Header file: utilities.h
See also:


AllSpoll

Function: AllSpoll
Prototype:
extern void __stdcall AllSpoll(int boardID, Addr4882_t * addrlist, PSHORT results)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


DevClear

Function: DevClear
Prototype:
extern void __stdcall DevClear(int boardID, Addr4882_t addr)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


DevClearList

Function: DevClearList
Prototype:
extern void __stdcall DevClearList(int boardID, Addr4882_t * addrlist)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


EnableLocal

Function: EnableLocal
Prototype:
extern void __stdcall EnableLocal(int boardID, Addr4882_t * addrlist)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


EnableRemote

Function: EnableRemote
Prototype:
extern void __stdcall EnableRemote(int boardID, Addr4882_t * addrlist)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


FindLstn

Function: FindLstn
Prototype:
extern void __stdcall FindLstn(int boardID, Addr4882_t * addrlist, Addr4882_t * results, int limit)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


FindRQS

Function: FindRQS
Prototype:
extern void __stdcall FindRQS(int boardID, Addr4882_t * addrlist, PSHORT dev_stat)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


GetCommState

Function: GetCommState
Prototype:
BOOL WINAPI GetCommState(HANDLE hFile,LPDCB lpDCB)
Remarks: The GetCommState function retrieves the current control settings for a specified communications device.
Parameters:

Return values:
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero.

Example:
        file ff;

        //Open comm port
        if (!ff.Open("COM1:",  file::modeReadWrite ))
        {
            ASSERT(FALSE);
            return FALSE;
        }

        UINT hCom = ff.GetHandle();

        if (hCom == file::hFileNull )
        {
            ASSERT(FALSE);
            return FALSE;
        }

        DCB dcb;

        if (!GetCommState((HANDLE)hCom, &dcb))
        {
            ASSERT(FALSE);
            return FALSE;
        }

        //dcb parameters for user
        dcb.BaudRate = CBR_9600;  		// set the baud rate
        dcb.ByteSize = 8;   			// data size, xmit, and rcv
        dcb.Parity = NOPARITY;        	// no parity bit
        dcb.StopBits = ONESTOPBIT;    	// one stop bit

        //dcb fixed parameters
        dcb.fBinary=1;
        dcb.fParity=0;
        dcb.fOutxCtsFlow=0;
        dcb.fOutxDsrFlow=0;
        dcb.fDtrControl=0;
        dcb.fDsrSensitivity=0;

        dcb.fTXContinueOnXoff=0;
        dcb.fRtsControl=0;

        if (!SetCommState((HANDLE)hCom, &dcb))
        {
            ASSERT(FALSE);
            return FALSE;
        }

        //...

        if( !ff.Close() ) // Close() function will happen automatically by the file class destructor.
        {
            ASSERT(FALSE);
            return FALSE;
        }
    Parameters
        hFile = Handle to the communications device.
        lpDCB = Pointer to a DCB structure that receives the control settings information.

Summary:
Sample data:
Header file: mscomm.h
See also: Open GetHandle


GetCommTimeouts

Function: GetCommTimeouts
Prototype:
BOOL WINAPI GetCommTimeouts(HANDLE hFile,LPCOMMTIMEOUTS lpCommTimeouts)
Remarks: The GetCommTimeouts function retrieves the time-out parameters for all read and write operations on a specified communications device.
Parameters:
hFile = Handle to the communications device.
lpCommTimeouts = Pointer to a COMMTIMEOUTS structure in which the time-out information is returned.

Return values:
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero.

Example:
        file ff;

        //Open comm port
        if (!ff.Open("COM1:",  file::modeReadWrite ))
        {
            ASSERT(FALSE);
            return FALSE;
        }

        UINT hCom = ff.GetHandle();

        if ( hCom == file::hFileNull )
        {
            ASSERT(FALSE);
            return FALSE;
        }

        COMMTIMEOUTS tTimeout;
        // get the timeout
        if( !GetCommTimeouts((HANDLE)hCom,&tTimeout) )
        {
            ASSERT(FALSE);
            return FALSE;
        }

        //...

        if( !ff.Close() ) // Close() function will happen automatically by the file class destructor.
        {
            ASSERT(FALSE);
            return FALSE;
        }

Summary:
Sample data:
Header file: mscomm.h
See also: Open GetHandle


ibask

Function: ibask
Prototype:
extern int __stdcall ibask(int ud, int option, PINT v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibbnaA

Function: ibbnaA
Prototype:
extern int __stdcall ibbnaA(int ud, LPCSTR udname)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibcac

Function: ibcac
Prototype:
extern int __stdcall ibcac(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibclr

Function: ibclr
Prototype:
extern int __stdcall ibclr(int ud)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibcmd

Function: ibcmd
Prototype:
extern int __stdcall ibcmd(int ud, PVOID buf, long cnt)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibcmda

Function: ibcmda
Prototype:
extern int __stdcall ibcmda(int ud, PVOID buf, long cnt)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibconfig

Function: ibconfig
Prototype:
extern int __stdcall ibconfig(int ud, int option, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibdev

Function: ibdev
Prototype:
extern int __stdcall ibdev(int boardID, int pad, int sad, int tmo, int eot, int eos)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibdiag

Function: ibdiag
Prototype:
extern int __stdcall ibdiag(int ud, PVOID buf, long cnt)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibdma

Function: ibdma
Prototype:
extern int __stdcall ibdma(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibeos

Function: ibeos
Prototype:
extern int __stdcall ibeos(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibeot

Function: ibeot
Prototype:
extern int __stdcall ibeot(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibfindA

Function: ibfindA
Prototype:
extern int __stdcall ibfindA(LPCSTR udname)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibgts

Function: ibgts
Prototype:
extern int __stdcall ibgts(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibist

Function: ibist
Prototype:
extern int __stdcall ibist(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


iblines

Function: iblines
Prototype:
extern int __stdcall iblines(int ud, PSHORT result)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibln

Function: ibln
Prototype:
extern int __stdcall ibln(int ud, int pad, int sad, PSHORT listen)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibloc

Function: ibloc
Prototype:
extern int __stdcall ibloc(int ud)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


iblock

Function: iblock
Prototype:
extern int __stdcall iblock(int ud)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibonl

Function: ibonl
Prototype:
extern int __stdcall ibonl(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibpad

Function: ibpad
Prototype:
extern int __stdcall ibpad(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibpct

Function: ibpct
Prototype:
extern int __stdcall ibpct(int ud)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibpoke

Function: ibpoke
Prototype:
extern int __stdcall ibpoke(int ud, long option, long v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibppc

Function: ibppc
Prototype:
extern int __stdcall ibppc(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibrd

Function: ibrd
Prototype:
extern int __stdcall ibrd(int ud, PVOID buf, long cnt)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibrda

Function: ibrda
Prototype:
extern int __stdcall ibrda(int ud, PVOID buf, long cnt)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibrdfA

Function: ibrdfA
Prototype:
extern int __stdcall ibrdfA(int ud, LPCSTR filename)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibrpp

Function: ibrpp
Prototype:
extern int __stdcall ibrpp(int ud, PCHAR ppr)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibrsc

Function: ibrsc
Prototype:
extern int __stdcall ibrsc(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibrsp

Function: ibrsp
Prototype:
extern int __stdcall ibrsp(int ud, PCHAR spr)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibrsv

Function: ibrsv
Prototype:
extern int __stdcall ibrsv(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibsad

Function: ibsad
Prototype:
extern int __stdcall ibsad(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibsic

Function: ibsic
Prototype:
extern int __stdcall ibsic(int ud)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibsre

Function: ibsre
Prototype:
extern int __stdcall ibsre(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibstop

Function: ibstop
Prototype:
extern int __stdcall ibstop(int ud)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibtmo

Function: ibtmo
Prototype:
extern int __stdcall ibtmo(int ud, int v)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibtrg

Function: ibtrg
Prototype:
extern int __stdcall ibtrg(int ud)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibwait

Function: ibwait
Prototype:
extern int __stdcall ibwait(int ud, int mask)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibwrt

Function: ibwrt
Prototype:
extern int __stdcall ibwrt(int ud, PVOID buf, long cnt)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibwrta

Function: ibwrta
Prototype:
extern int __stdcall ibwrta(int ud, PVOID buf, long cnt)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ibwrtfA

Function: ibwrtfA
Prototype:
extern int __stdcall ibwrtfA(int ud, LPCSTR filename)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


PassControl

Function: PassControl
Prototype:
extern void __stdcall PassControl(int boardID, Addr4882_t addr)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


PPoll

Function: PPoll
Prototype:
extern void __stdcall PPoll(int boardID, PSHORT result)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


PPollConfig

Function: PPollConfig
Prototype:
extern void __stdcall PPollConfig(int boardID, Addr4882_t addr, int dataLine, int lineSense)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


PPollUnconfig

Function: PPollUnconfig
Prototype:
extern void __stdcall PPollUnconfig(int boardID, Addr4882_t * addrlist)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


RcvRespMsg

Function: RcvRespMsg
Prototype:
extern void __stdcall RcvRespMsg(int boardID, PVOID buffer, long cnt, int Termination)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ReadStatusByte

Function: ReadStatusByte
Prototype:
extern void __stdcall ReadStatusByte(int boardID, Addr4882_t addr, PSHORT result)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


Receive

Function: Receive
Prototype:
extern void __stdcall Receive(int boardID, Addr4882_t addr, PVOID buffer, long cnt, int Termination)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ReceiveSetup

Function: ReceiveSetup
Prototype:
extern void __stdcall ReceiveSetup(int boardID, Addr4882_t addr)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ResetSys

Function: ResetSys
Prototype:
extern void __stdcall ResetSys(int boardID, Addr4882_t * addrlist)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


Send

Function: Send
Prototype:
extern void __stdcall Send(int boardID, Addr4882_t addr, PVOID databuf, long datacnt, int eotMode)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


SendCmds

Function: SendCmds
Prototype:
extern void __stdcall SendCmds(int boardID, PVOID buffer, long cnt)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


SendDataBytes

Function: SendDataBytes
Prototype:
extern void __stdcall SendDataBytes(int boardID, PVOID buffer, long cnt, int eot_mode)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


SendIFC

Function: SendIFC
Prototype:
extern void __stdcall SendIFC(int boardID)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


SendList

Function: SendList
Prototype:
extern void __stdcall SendList(int boardID, Addr4882_t * addrlist, PVOID databuf, long datacnt, int eotMode)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


SendLLO

Function: SendLLO
Prototype:
extern void __stdcall SendLLO(int boardID)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


SendSetup

Function: SendSetup
Prototype:
extern void __stdcall SendSetup(int boardID, Addr4882_t * addrlist)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


SetCommState

Function: SetCommState
Prototype:
BOOL WINAPI SetCommState(HANDLE hFile,LPDCB lpDCB)
Remarks: The SetCommState function configures a communications device according to the specifications in a device-control block (a DCB structure). The function reinitializes all hardware and control settings, but it does not empty output or input queues.
Parameters:
hFile = handle to the communications device.
lpDCB = Pointer to a DCB structure that contains the configuration information for the specified communications device.

Return values:
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero.

Example:
        file ff;

        //Open comm port
        if (!ff.Open("COM1:",  file::modeReadWrite ))
        {
            ASSERT(FALSE);
            return FALSE;
        }

        UINT hCom = ff.GetHandle();

        if (hCom == file::hFileNull )
        {
            ASSERT(FALSE);
            return FALSE;
        }

        DCB dcb;

        if (!GetCommState((HANDLE)hCom, &dcb))
        {
            ASSERT(FALSE);
            return FALSE;
        }

        //dcb parameters for user
        dcb.BaudRate = CBR_9600;  		// set the baud rate
        dcb.ByteSize = 8;   			// data size, xmit, and rcv
        dcb.Parity = NOPARITY;        	// no parity bit
        dcb.StopBits = ONESTOPBIT;    	// one stop bit

        //dcb fixed parameters
        dcb.fBinary=1;
        dcb.fParity=0;
        dcb.fOutxCtsFlow=0;
        dcb.fOutxDsrFlow=0;
        dcb.fDtrControl=0;
        dcb.fDsrSensitivity=0;

        dcb.fTXContinueOnXoff=0;
        dcb.fRtsControl=0;

        if (!SetCommState((HANDLE)hCom, &dcb))
        {
            ASSERT(FALSE);
            return FALSE;
        }

        //...

        if( !ff.Close() ) // Close() function will happen automatically by the file class destructor.
        {
            ASSERT(FALSE);
            return FALSE;
        }

Summary:
Sample data:
Header file: mscomm.h
See also: Open GetHandle


SetCommTimeouts

Function: SetCommTimeouts
Prototype:
BOOL WINAPI SetCommTimeouts(HANDLE hFile,LPCOMMTIMEOUTS lpCommTimeouts)
Remarks: The SetCommTimeouts function sets the time-out parameters for all read and write operations on a specified communications device.
Parameters:
hFile = Handle to the communications device.
lpCommTimeouts = Pointer to a COMMTIMEOUTS structure that contains the new time-out values.

Return values:
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero.

Example:
        file ff;

        //Open comm port
        if (!ff.Open("COM1:",  file::modeReadWrite ))
        {
            ASSERT(FALSE);
            return FALSE;
        }

        UINT hCom = ff.GetHandle();

        if ( hCom == file::hFileNull )
        {
            ASSERT(FALSE);
            return FALSE;
        }

        COMMTIMEOUTS tTimeout;
        tTimeout.ReadIntervalTimeout = MAXWORD;
        tTimeout.ReadTotalTimeoutMultiplier = 0;
        tTimeout.ReadTotalTimeoutConstant = 500; // pas de time out = 0
        tTimeout.WriteTotalTimeoutMultiplier = 0;
        tTimeout.WriteTotalTimeoutConstant = 0;

        // config the timeout
        if( !SetCommTimeouts((HANDLE)hCom,&tTimeout) )
        {
            ASSERT(FALSE);
            return FALSE;
        }

        //...

        if( !ff.Close() ) // Close() function will happen automatically by the file class destructor.
        {
            ASSERT(FALSE);
            return FALSE;
        }

Summary:
Sample data:
Header file: mscomm.h
See also: Open GetHandle


SetRWLS

Function: SetRWLS
Prototype:
extern void __stdcall SetRWLS(int boardID, Addr4882_t * addrlist)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


TestSRQ

Function: TestSRQ
Prototype:
extern void __stdcall TestSRQ(int boardID, PSHORT result)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


TestSys

Function: TestSys
Prototype:
extern void __stdcall TestSys(int boardID, Addr4882_t * addrlist, PSHORT results)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ThreadIbcnt

Function: ThreadIbcnt
Prototype:
extern int __stdcall ThreadIbcnt(void)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ThreadIbcntl

Function: ThreadIbcntl
Prototype:
extern long __stdcall ThreadIbcntl(void)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ThreadIberr

Function: ThreadIberr
Prototype:
extern int __stdcall ThreadIberr(void)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


ThreadIbsta

Function: ThreadIbsta
Prototype:
extern int __stdcall ThreadIbsta(void)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


Trigger

Function: Trigger
Prototype:
extern void __stdcall Trigger(int boardID, Addr4882_t addr)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


TriggerList

Function: TriggerList
Prototype:
extern void __stdcall TriggerList(int boardID, Addr4882_t * addrlist)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


WaitSRQ

Function: WaitSRQ
Prototype:
extern void __stdcall WaitSRQ(int boardID, PSHORT result)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: NI488-2.h
See also:


cabs

Function: cabs
Prototype:
double cabs(complex z)
Remarks: returns the amplitude (modulus) of the complex value.
Parameters:
z = the complex value whose amplitude is sought.

Return values:
The amplitude

Example:
        void	run_complex_cabs()
        {
            complex		cc(1., -1.);

            // Display the amplitude:
            out_double("amplitude = ", cabs(cc));	// shoulde be 1.4142 (=sqrt(2))
        }

Summary:
Sample data:
Header file: complex.h
See also:


Conj

Function: Conj
Prototype:
complex Conj(complex cc)
Remarks: it returns the complex conjugate of the value
Parameters:
cc = the complex value whose conjugate is sought.

Return values:
The complex conjugate

Example:
        void	run_complex_Conj()
        {
            complex		cc(1.2, 3.4);
            complex		cconj = Conj(cc);

            // Display the values:
            out_complex("original value = ", cc);
            out_complex("conjugate value = ", cconj);
        }

Summary:
Sample data:
Header file: complex.h
See also:


cos

Function: cos
Prototype:
complex cos(complex z)
Remarks: it returns the complex cosine of the complex value
Parameters:
z = the complex value whose cosine is sought.

Return values:
The cosine

Example:
        void	run_complex_cos()
        {
            complex		cc(0.5, 0.8);

            out_complex("cos = ", cos(cc));
        }

Summary:
Sample data:
Header file: complex.h
See also:
Function: cos
Prototype:
double cos(double x)
Remarks: Calculate the cosine.
Parameters:
Angle in radians.

Return values:
The cos function returns the cosine of x.

Example:
        This program computes and displays the cosine of x.

        #include <origin.h>

        int test_cos()
        {
            double vv;
            vv = cos(-3*PI);
            out_double("cos(-3*PI)=", vv);	//output should be cos(-3*PI)=-1
            ASSERT( is_equal(vv, -1) );
            vv = cos(0);
            out_double("cos(0)=", vv);		//output should be cos(0)=1
            ASSERT( is_equal(vv, 1) );
            vv = cos(15.5);
            out_double("cos(15.5)=", vv);	//cos(15.5)=-0.97845
            ASSERT( is_equal(round(vv,5), -0.97845) );

            return 1;
        }

Summary:
Sample data:
Header file: msmath.h
See also:


cpow

Function: cpow
Prototype:
complex cpow(complex z1, complex z2)
Remarks: returns the power of the complex value such that the power is a complex value
Parameters:
z1 = the complex value whose power is sought.
z2 = the power

Return values:
z1^z2

Example:
        void	run_complex_cpow()
        {
            complex			z1(2., 1.);
            complex			z2(3., 2.);

            complex			cresult = cpow(z1, z2);

            out_complex("base = ", z1);
            out_complex("power = ", z2);
            out_complex("cpow = ", cresult);
        }

Summary:
Sample data:
Header file: complex.h
See also:


exp

Function: exp
Prototype:
complex exp(complex z)
Remarks: returns the exponent exp(z) of the complex value.
Parameters:
z = the complex value whose exponent is sought.

Return values:
exp(z)

Example:
        void	run_complex_exp()
        {
            complex		cc(0.5., 0.3.);

            out_complex("exp = ", exp(cc));
        }

Summary:
Sample data:
Header file: complex.h
See also:
Function: exp
Prototype:
double exp(double x)
Remarks: Calculate the exponential (the base of natural logarithm to the power x)
Parameters:
x = independent variable

Return values:
exp(x)

Example:
        void	run_exp()
        {
            double	rExp = 2.;
            double	val = exp(rExp);

            printf("exp(%f) = %f\n", rExp, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


ipow

Function: ipow
Prototype:
complex ipow(complex z, int n)
Remarks: returns the power of the complex value such that the power is an integer
Parameters:
z = the complex value whose power is sought.
n = the power

Return values:
z^n

Example:
        void	run_complex_ipow()
        {
            complex			cc(sqrt(3.), 1.);	// the complex number whose real part
                                                // is the square root of 3, and imaginary part is 1.
                                                // so that its phase is 30 degrees and amplitude is 2.
            int				n = 3;

            complex			cresult = ipow(cc, n);

            out_complex("Input = ", cc);
            out_int("power = ", n);
            out_complex("ipow = ", cresult);	// the result should be such that its amplitude is 8 (which
                                                // is 2 to the power 3) and whose phase is 90 degrees (which
                                                // is 30 degrees times 3).
        }

Summary:
Sample data:
Header file: complex.h
See also:


log

Function: log
Prototype:
complex log(complex z)
Remarks: returns the logarithm of the complex value.
Parameters:
z = the complex value whose logarithm is sought.

Return values:
The logarithm

Example:
        void	run_complex_log()
        {
            complex		cc(100., 3.);

            // Display the log:
            out_complex("log = ", log(cc));
        }

Summary:
Sample data:
Header file: complex.h
See also:
Function: log
Prototype:
double log(double x)
Remarks: Natural logarithm.
Parameters:
x = independent variable

Return values:
log(x)

Example:
        void	run_log()
        {
            double		x = 7.389056;
            double		val = log(x);

            printf("log(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also: ln log10


rpow

Function: rpow
Prototype:
complex rpow(complex z, double x)
Remarks: returns the power of the complex value such that the power is a double value
Parameters:
z = the complex value whose power is sought.
x = the power

Return values:
z^x

Example:
        void	run_complex_rpow()
        {
            complex			cc(sqrt(3.), 1.);	// the complex number whose real part
                                                // is the square root of 3, and imaginary part is 1.
                                                // so that its phase is 30 degrees and amplitude is 2.
            double			x = 3.;

            complex			cresult = rpow(cc, x);

            out_complex("Input = ", cc);
            out_double("power = ", x);
            out_complex("rpow = ", cresult);	// the result should be such that its amplitude is 8 (which
                                                // is 2 to the power 3.) and whose phase is 90 degrees (which
                                                // is 30 degrees times 3.).
        }

Summary:
Sample data:
Header file: complex.h
See also:


sin

Function: sin
Prototype:
complex sin(complex z)
Remarks: it returns the complex sine of the complex value
Parameters:
z = the complex value whose sine is sought.

Return values:
The sine

Example:
        void	run_complex_sin()
        {
            complex		cc(0.5, 0.8);

            out_complex("sin = ", sin(cc));
        }

Summary:
Sample data:
Header file: complex.h
See also:
Function: sin
Prototype:
double sin(double x)
Remarks: Calculate sines.
Parameters:
Angle in radians.

Return values:
The sin function returns the sines of x.

Example:
        This program computes and displays the sines of x.

        #include <origin.h>

        int test_sin()
        {
            double vv;
            vv = sin( 0 );
            out_double("sin(0)=", vv);		//output should be sin(0)=0
            ASSERT( is_equal(vv, 0) );
            vv = sin( PI/6);
            out_double("sin(PI/6)=", vv);	//output should be sin(PI/6)=0.5
            ASSERT(is_equal(round(vv,5), 0.5) );
            vv = sin(5.20);
            out_double("sin(5.20)=", vv);	//output should be sin(5.20)=-0.88345
            ASSERT(is_equal(round(vv,5), -0.88345) );

            return 1;
        }

Summary:
Sample data:
Header file: msmath.h
See also:


sqrt

Function: sqrt
Prototype:
complex sqrt(complex z)
Remarks: it returns the complex square root of the complex value
Parameters:
z = the complex value whose square root is sought.

Return values:
The square root

Example:
        void	run_complex_sqrt()
        {
            complex		cc(0., 8.);

            out_complex("sqrt = ", sqrt(cc));
        }

Summary:
Sample data:
Header file: complex.h
See also:
Function: sqrt
Prototype:
double sqrt(double x)
Remarks: Calculates the square root.
Parameters:
x = independent variable

Return values:
square root of x

Example:
        void	run_sqrt()
        {
            double		rr = 625;
            double		val = sqrt(rr);

            printf("sqrt(%f) = %f\n", rr, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


tan

Function: tan
Prototype:
complex tan(complex z)
Remarks: it returns the complex tangent of the complex value
Parameters:
z = the complex value whose tangent is sought.

Return values:
The tangent

Example:
        void	run_complex_tan()
        {
            complex		cc(0.5, 0.8);

            out_complex("tan = ", tan(cc));
        }

Summary:
Sample data:
Header file: complex.h
See also:
Function: tan
Prototype:
double tan(double x)
Remarks: Calculates the trigonometric tangent.
Parameters:
x = independent variable

Return values:
tan(x)

Example:
        void	run_tan()
        {
            double		x = 0.78;
            double		val = tan(x);

            printf("tan(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


add_curve_to_graph_layer

Function: add_curve_to_graph_layer
Prototype:
bool add_curve_to_graph_layer(curvebase& cuv, GraphLayer &grl, int nColor = 2, bool bRescale = false, int nPlotType = IDM_PLOT_LINE)
Remarks: It adds the curve cuv to the layer grl.
Parameters:
cuv=[in] the input curve
grl=[in] the layer to add the curve to.
nColor=[in] nthe color the curve should have.
bRescale=[in] to rescale the layer with the curve or not.
nPlotType=[in] the plot type of the curve to add.

Return values:
TRUE if OK, otherwise FALSE.

Example:
        //This example add Data1_B to the first layer of Graph1.
        //For this example to run, Graph1 should exist in the current project.
        void run_add_curve_to_graph_layer()
        {
            Curve crvPlotted( "Data1_B" );
            GraphLayer gl( "Graph1", 0 );
            if(crvPlotted && gl)
            {
                bool bOK = add_curve_to_graph_layer(crvPlotted, gl);
                if(bOK)
                {
                    out_str("Success in adding Data1_B to Graph1.");
                }
                else
                {
                    out_str("Fail to add Data1_B to Graph1.");
                }
            }
        }

Summary:
Sample data:
Header file: analysis_utils.h
See also:


curve_both_in_layer

Function: curve_both_in_layer
Prototype:
bool curve_both_in_layer(const curvebase& cuv1, const curvebase& cuv2, GraphLayer& glayerFound)
Remarks: Search the layer where two curves are both plotted. glayerFound can be set to a layer to search first, or it can be let uninitialized
Parameters:
cuv1 = [in] Curve to try to add to another curve's layer
cuv2 = [in] Curve that is likely already plotted in some layer
glayerFound = [out] Graph that cuv2 is currently plotted

Return values:
FALSE if not in same layer, or cuv2 not plotted at all

Example:
        if(cuvFit)
        {
            GraphLayer gl;
            if(!curve_both_in_layer(cuvFit, cuvData, gl) && gl) // there maybe many, we will just use 1st for now
            {
                // cuvData plotted in gl but cuvFit not, so we will make the plot
                int nPlot = gl.AddPlot(cuvFit, IDM_PLOT_LINE);
                DataPlot dp = gl.DataPlots(nPlot);
                dp.SetColor(1); // set to red
            }
        }

Summary:
Sample data:
Header file: analysis_utils.h
See also:


curve_duplicate_active

Function: curve_duplicate_active
Prototype:
curvebase& curve_duplicate_active(LPCSTR lpcszNewColName = NULL, bool bReuseIfInWks = false)
Remarks: duplicate the active curve in the active graph layer so that analysis routine like derivatives and smoothing can be performed on the copied curve
Parameters:
lpcszNewColName = name of the Y column for the copied curve
bReuseIfInWks = option to always create new copy of can reuse if named column is already in the same worksheet as the original

Return values:
NULL if no active graph layer with active curve found, or if the operation failed

Example:
        //This example copy the active curve Data1_B in Graph1.
        //For this sample to run, Data1_B and Graph1 should exist.
        void run_curve_duplicate_active()
        {
            Curve crv("Data1_B");
            GraphLayer gl("Graph1", 0);
            if(crv && gl)
            {
                add_curve_to_graph_layer(crv, gl);			//Add the curve to the graphlayer
                set_active_layer(gl);						//Set the graphlayer to active
                Curve crvCopy = curve_duplicate_active();
                if(crvCopy)
                {
                    out_str("Copy successfully.");
                }
            }
        }

Summary:
Sample data:
Header file: analysis_utils.h
See also:


curve_get_wks_col_names

Function: curve_get_wks_col_names
Prototype:
string curve_get_wks_col_names(const curvebase& cuv, string& strX, string& strY)
Remarks: Find Worksheet and Column names from a Curve
Parameters:
cuv = [in] Curve to find info about
strX = [out] X column name, can be empty if Curve has no X column
strY = [out] Y column name.

Return values:
name of the Worksheet, will be empty if input Curve is invalid

Example:
        //This example get the dataset name of the curve in Graph1.
        //For this sample to work, Graph1 must exist in the project.
        void run_curve_get_wks_col_names()
        {
            GraphLayer gl("Graph1", 0);				//Get the first layer of Graph1
            if(gl)
            {
                DataPlot dp = gl.DataPlots(0);      // Get first data plot in graph layer
                if(dp)                              // If valid DataPlot...
                {
                    Curve crv(dp);   				// Get Curve from DataPlot
                    string strX, strY, strWks;
                    strWks = curve_get_wks_col_names(crv, strX, strY);
                    out_str("The first DataPlot in Graph1: ");
                    out_str("X: "+ strWks + "_" + strX);
                    out_str("Y: "+ strWks + "_" + strY);
                }
            }
        }

Summary:
Sample data:
Header file: analysis_utils.h
See also:


curve_in_layer_get_index

Function: curve_in_layer_get_index
Prototype:
int curve_in_layer_get_index(const curvebase& cuv, const GraphLayer& gl)
Remarks: check if Curve is in a graph layer and return its plot index if true
Parameters:
cuv = [in] Curve to test
gl = [in] graph layer to test

Return values:
plot index if in layer, or -1 if not

Example:
        //This example return the index of Data1_B in Graph1.
        //For this sample to work, Graph1 and Dataset Data1_B must exist in the project.
        void run_curve_in_layer_get_index()
        {
            Curve crvPlotted( "Data1_B" );
            GraphLayer gl( "Graph1", 0 );
            if(crvPlotted && gl)
            {
                int nIndex = curve_in_layer_get_index(crvPlotted, gl);
                out_int("The index of Data1_B in Graph1 is ", nIndex );
            }
        }

Summary:
Sample data:
Header file: analysis_utils.h
See also:


curve_in_page_get_indices

Function: curve_in_page_get_indices
Prototype:
BOOL curve_in_page_get_indices(const curvebase& cuv, const GraphPage &gpg, int *pnLayerIndex = NULL, int *pnDataPlotIndex = NULL)
Remarks: It looks for the curve in the graph page.
Parameters:
cuv=[in] the curve to look for
gpg=[in] the graph page to look in.
pnLayerIndex=[in] optional pointer to an integer to receive the index of the layer in which the curve was found
pnDataPlotIndex=[in] optional pointer to an integer to receive the index of the dataplot in the layer if found.

Return values:
TRUE if found, otherwise FALSE.

Example:
        //This example use function curve_in_page_get_indices() to check whether Data1_B
        //exists in Graph1. For this sample to work, Data1_B and Graph1 should exist.
        void run_curve_in_page_get_indices()
        {
            Curve crvPlotted( "Data1_B" );
            GraphPage gp1( "Graph1" );
            if(crvPlotted && gp1)
            {
                bool bOK = curve_in_page_get_indices(crvPlotted, gp1);
                if(bOK)
                {
                    out_str("Data1_B exists in Graph1.");
                }
                else
                {
                    out_str("Data1_B does not exist in Graph1.");
                }
            }
        }

Summary:
Sample data:
Header file: analysis_utils.h
See also:


curve_update

Function: curve_update
Prototype:
bool curve_update(curvebase& cuvResult, const curvebase& cuvInput, const TreeNode& trInput, int nColor, bool bRescale = false)
Remarks: find the input curve layer and plot the result curve
Parameters:
cuvResult = [in] Curve to plot
cuvInput = [in] reference Curve to find where to plot the cuvResult
trInput  = [in] if given, this will provide the graph layer location to plot cuvResult
nColor = [in] color of the cuvResult curve
bRescale = [in] rescale layer or not

Return values:
TRUE if correct layer is found and cuvResult is plotted successfully

Example:
        //This example shows how to plot Data1_C to the same graph layer as Data1_B in red.
        //For this sample codes to run, a worksheet named "Data1" with column B and C
        //should exist in the current project and a graph with Data1_B plotted exists too.

        void run_curve_update()
        {
            Curve crvPlotted( "Data1_B" );
            Curve crvToBePlot( "Data1_C" );
            TreeNode trInput;
            int nColor = 1; 			//Red

            if(crvPlotted && crvToBePlot)
            {
                curve_update(crvToBePlot, crvPlotted, trInput, nColor);
            }
        }

Summary:
Sample data:
Header file: analysis_utils.h
See also:


curve_update_in_page

Function: curve_update_in_page
Prototype:
bool curve_update_in_page(curvebase& cuv, int nColor, GraphPage &gpg, bool bRescale = false)
Remarks: It searches for the dataplot containing the given curve. If found, just refreshes the graph page, otherwise it adds the curve to the first layer of the page.
Parameters:
cuv=[in] the input curve
nColor=[in] nthe color the curve should have.
gpg=[in] the graph page in which to look for the curve.
bRescale=[in] to rescale the layer with the curve or not.

Return values:
TRUE if OK, otherwise FALSE.

Example:
        //This example add curve Data1_B to Graph1.
        //For this sample codes to run, Graph1 should exist in the current project.
        void run_curve_update_in_page()
        {
            Curve crvPlotted( "Data1_B" );
            GraphPage gp1( "Graph1" );
            int nColor = 0;  			// Black
            if(gp1 && crvPlotted)
            {
                curve_update_in_page(crvPlotted, nColor, gp1);
            }
        }

Summary:
Sample data:
Header file: analysis_utils.h
See also:


set_curve

Function: set_curve
Prototype:
bool set_curve(const curvebase& cuv, TreeNode& trNode)
Remarks: add to TreeNode the X and Y dataset names of the given curve
Parameters:
cuv = [in] Curve to get names from
trNode = [out] tree node to add the needed info

Return values:
TRUE if success
See Also:
set_active_layer

Example:
        //This example show the info. of the curve.
        //For this sample to work, dataset Data1_B should exist.
        #include <tree_utils.h>
        void run_set_curve()
        {
            Curve crvPlotted( "Data1_B" );
            Tree trNode;
            if(crvPlotted)
            {
                bool bOK = set_curve(crvPlotted, trNode);
                if(bOK)
                {
                    out_tree(trNode);
                }
            }
        }

Summary:
Sample data:
Header file: analysis_utils.h
See also:


GetSystemTime

Function: GetSystemTime
Prototype:
void WINAPI GetSystemTime(SYSTEMTIME* lpSystemTime)
Remarks: This function retrieves the current system date and time. The system time is expressed in Coordinated Universal Time (UTC).
Parameters:
lpSystemTime = pointer to the SYSTEM struct to receive the date and time

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also: SetFileTime FileTimeToSystemTime SystemTimeToJulianDate


get_date_str

Function: get_date_str
Prototype:
string get_date_str(double dDateTime, WORD wFormat = LDF_SHORT_AND_HHMMSS_SEPARCOLON)
Remarks: convert a Julian date value into a string
Parameters:
dDateTime = A Julian date time value, where the integral part represent the Julian Days while the fractional part as fraction of a Day
wFormat = must be the enumeration LDF_SHORT, LDF_LONG, LDF_ALPHAMONTH_NUMERICDAY, etc

Return values:
A string containing the converted date/time.

Example:
        void	test_get_date_str()
        {
            SYSTEMTIME st;
            GetSystemTime(&st);              // gets current time
            double dDate;
            SystemTimeToJulianDate(&dDate, &st);
            out_str(get_date_str(dDate, LDF_LONG));
        }

Summary:
Sample data:
Header file: utilities.h
See also:


systemtime_to_date_str

Function: systemtime_to_date_str
Prototype:
BOOL systemtime_to_date_str(SYSTEMTIME *pSysTime, LPSTR lpstr, WORD wFormat=LDF_SHORT)
Remarks: Convert a SYSTEMTIME structure to a formatted string.
Parameters:
pSysTime = pointer to the source SYSTEMTIME structure
lpstr = pointer to the buffer to receive the formatted string
wFormat = a date format flag to determine the appearance of the formatted string. See LDF_* definitions in OC_Const.h

Return values:
If successful then TRUE else FALSE

Example:
        SYSTEMTIME syst;
        syst.wYear = 2003;
        syst.wMonth = 1;
        syst.wDayOfWeek = 2;
        syst.wDay = 28;
        syst.wHour = 11;
        syst.wMinute = 17;
        syst.wSecond = 33;
        syst.wMilliseconds = 0;

        string str;
        LPSTR lpstr = str.GetBuffer(255);
        if( lpstr )
        {
            systemtime_to_date_str(&syst, lpstr, LDF_LONG);
            str.ReleaseBuffer();
        }

Summary:
Sample data:
Header file: utilities.h
See also:


SystemTimeToJulianDate

Function: SystemTimeToJulianDate
Prototype:
BOOL SystemTimeToJulianDate(double *lpdDate, SYSTEMTIME *lpSysTime)
Remarks: Convert a SYSTEMTIME structure to a Julian date value.
Parameters:
lpdDate = pointer to the destination value
lpSysTime = pointer to the source SYSTEMTIME structure

Return values:
TRUE if successful, else FALSE

Example:
        void	test_get_date_str()
        {
            SYSTEMTIME st;
            GetSystemTime(&st);              // gets current time
            double dDate;
            SystemTimeToJulianDate(&dDate, &st);
            out_str(get_date_str(dDate, LDF_LONG));
        }

Summary:
Sample data:
Header file: utilities.h
See also:


fclose

Function: fclose
Prototype:
int fclose(FILE * stream)
Remarks: The fclose function closes stream. _fcloseall closes all open streams except stdin, stdout, stderr (and, in MS-DOS®, _stdaux and _stdprn). It also closes and deletes any temporary files created by tmpfile. In both functions, all buffers associated with the stream are flushed prior to closing. System-allocated buffers are released when the stream is closed. Buffers assigned by the user with setbuf and setvbuf are not automatically released.
Parameters:
stream	:Pointer to FILE structure

Return values:
fclose returns 0 if the stream is successfully closed. It return EOF to indicate an error.

Example:
        The following example opens a file named "data" and "data2". It then uses fclose to close "data" and "data2"

        void test_fclose()
        {
            FILE *stream, *stream2;

            // Open for read (will fail if file "data" does not exist)
            stream  = fopen( "data", "r" );
            if( stream == NULL )
                printf( "The file 'data' was not opened\n" );
            else
                printf( "The file 'data' was opened\n" );

            // Open for write
            stream2 = fopen( "data2", "w+" );
            if( stream2 == NULL )
                printf( "The file 'data2' was not opened\n" );
            else
                printf( "The file 'data2' was opened\n" );

            // Close stream
            if( fclose( stream ) )
                printf( "The file 'data' was not closed\n" );
            // Close stream2
            if( fclose( stream2 ) )
                printf( "The file 'data2' was not closed\n" );
        }

Summary:
Sample data:
Header file: stdio.h
See also: fflush fopen


feof

Function: feof
Prototype:
int feof(FILE *stream )
Remarks: The feof routine determines whether the end of stream has been reached. When end of file is reached, read operations return an end-of-file indicator until the stream is closed.
Parameters:
stream	:Pointer to FILE

Return values:
Returns a nonzero value after the first read operation that attempts to read past the end of the file. It returns 0 if the current position is not end of file. There is no error return.

Example:
        The following example uses feof to indicate when it reaches the end of your current C file. It also checks for errors with ferror.

    void test_feof()
    {
        int  count, total = 0;
        char buffer[100];
        FILE *stream;

        // open your current using C file for read
        stream = fopen( __FILE__, "r" );
        if(stream == NULL )
            printf( "The current C file was not opened\n" );

        // Cycle until end of file reached:
        while( !feof( stream ) )
        {
            // Attempt to read in 10 bytes:
            count = fread( buffer, sizeof( char ), 100, stream );
            if( ferror( stream ) )
                printf("Read Error");

            // Total up actual bytes read
            total += count;
        }

        printf( "Number of bytes read = %d\n", total );
        fclose( stream );
    }

Summary:
Sample data:
Header file: stdio.h
See also: ferror


ferror

Function: ferror
Prototype:
int ferror(FILE *stream)
Remarks: The ferror routine tests for a reading or writing error on the file associated with stream. If an error has occurred, the error indicator for the stream remains set until the stream is closed or rewound, or until clearerr is called against it.
Parameters:
stream	:Pointer to FILE

Return values:
If no error has occurred on stream, ferror returns 0. Otherwise, it returns a nonzero value.

Example:
        The following example uses feof to indicate when it reaches the end of your current C file. It also checks for errors with ferror.

    void test_ferror()
    {
        int  count, total = 0;
        char buffer[100];
        FILE *stream;

        // open your current using C file for read
        stream = fopen( __FILE__, "r" );
        if(stream == NULL )
            printf( "The current C file was not opened\n" );

        // Cycle until end of file reached:
        while( !feof( stream ) )
        {
            // Attempt to read in 10 bytes:
            count = fread( buffer, sizeof( char ), 100, stream );
            if( ferror( stream ) )
                printf("Read Error");

            // Total up actual bytes read
            total += count;
        }

        printf( "Number of bytes read = %d\n", total );
        fclose( stream );
    }

Summary:
Sample data:
Header file: stdio.h
See also: feof fopen


fflush

Function: fflush
Prototype:
int fflush(FILE *stream)
Remarks: The fflush function flushes a stream. If the file associated with stream is open for output, fflush writes to that file the contents of the buffer associated with the stream. If the stream is open for input, fflush clears the contents of the buffer. Also, fflush(NULL) flushes all streams opened for output. The stream remains open after the call. fflush has no effect on an unbuffered stream. Buffers are normally maintained by the operating system, which determines the optimal time to write the data automatically to disk: when a buffer is full, when a stream is closed, or when a program terminates normally without closing the stream. The commit-to-disk feature of the run-time library lets you ensure that critical data is written directly to disk rather than to the operating-system buffers. Without rewriting an existing program, you can enable this feature by linking the program’s object files with COMMODE.OBJ. In the resulting executable file, calls to _flushall write the contents of all buffers to disk. Only _flushall and fflush are affected by COMMODE.OBJ.
Parameters:
stream	:Pointer to FILE

Return values:
fflush returns 0 if the buffer was successfully flushed. The value 0 is also returned in cases in which the specified stream has no buffer or is open for reading only. A return value of EOF indicates an error.
Note:  If fflush returns EOF, data may have been lost due to a write failure.

Example:
        void test_fflush()
        {
            FILE  *stream = fopen("C:\\text.txt", "w+" );
            if( NULL == stream )
            {
                printf("Failed to open file test.txt\n");
                return;
            }

            char input[6] = {'h', 'e', 'l', 'l', 'o'};

            fwrite( input, sizeof(char), 6, stream );  // Write a string into the file.

            fflush(stream);
            fclose(stream);   //set a breakpoint at this line, use Windows Explorer to open the test.txt, you should be able to see that the string have been written to the file
        }

Summary:
Sample data:
Header file: stdio.h
See also: fclose


fgetc

Function: fgetc
Prototype:
int fgetc(FILE *stream)
Remarks: fgetc reads a single character from the current position of a file associated with stream. The function then increments the associated file pointer (if defined) to point to the next character. If the stream is at end of file, the end-of-file indicator for the stream is set.
Parameters:
stream	:Pointer to FILE

Return values:
fgetc return the character read as an int or return EOF to indicate an error or end of file.
Use feof or ferror to distinguish between an error and an end-of-file condition.
If a read error occurs, the error indicator for the stream is set.

Example:
        The following example uses getc to read the first 80 input characters(or until the end of input) and place them into a string named buffer.

        void test_fgetc()
        {
            FILE *stream;
            char buffer[81];
            int  i, ch;

            // Open the current C file to read line from:
            stream = fopen( __FILE__, "r" );
            if(stream == NULL )
                printf("The current C file cannot be opened");

            // Read in first 80 characters and place them in "buffer":
            ch = fgetc( stream );
            for( i=0; (i < 80 ) && ( feof( stream ) == 0 ); i++ )
            {
                buffer[i] = (char)ch;
                ch = fgetc( stream );
            }

            // Add null to end string
            buffer[i] = '\0';
            printf( "%s\n", buffer );
            fclose( stream );
        }

Summary:
Sample data:
Header file: stdio.h
See also: fputc


fgets

Function: fgets
Prototype:
char* fgets(char *str, int nLen, FILE *stream)
Remarks: fgets reads a string from the input stream argument and stores it in string. fgets reads characters from the current stream position to and including the first newline character, to the end of the stream, or until the number of characters read is equal to n-1, whichever comes first. The result stored in string is appended with a null character. The newline character, if read, is included in the string.
Parameters:
str		:Storage location for data
nLen	:Maximum number of characters to read
stream	:Pointer to FILE

Return values:
Each of these functions returns string. NULL is returned to indicate an error or an end-of-file condition. Use feof or ferror to determine whether an error occurred.

Example:
        The following example uses fgets to display a line from a file and then print out this line

        void test_fgets()
        {
           FILE *stream;
           char line[100];
           stream = fopen( __FILE__, "r" );
           if(stream != NULL )
           {
              if( fgets( line, 100, stream ) == NULL)
                 printf( "fgets error\n" );
              else
                 printf( "%s", line);
              fclose( stream );
           }
        }

Summary:
Sample data:
Header file: stdio.h
See also: fputs


fopen

Function: fopen
Prototype:
FILE* fopen(const char * filename, const char *mode)
Remarks: This function opens the file specified by filename. The character string mode specifies the type of access requested for the file, as follows: "r" :Opens for reading. If the file does not exist or cannot be found, the fopen call fails. "w" :Opens an empty file for writing. If the given file exists, its contents are destroyed. "a" :Opens for writing at the end of the file (appending) without removing the EOF marker before writing new data to the file; creates the file first if it doesn’t exist. "r+":Opens for both reading and writing. (The file must exist.) "w+":Opens an empty file for both reading and writing. If the given file exists, its contents are destroyed. "a+":Opens for reading and appending; the appending operation includes the removal of the EOF marker before new data is written to the file and the EOF marker is restored after writing is complete; creates the file first if it doesn’t exist.
Parameters:
filename	:Filename
mode		:Type of access permitted

Return values:
returns a pointer to the open file. A null pointer value indicates an error.

Example:

        This following example open files named "data", and "data2". It uses fclose to close "data" and "data2"

        void test_fopen()
        {
            FILE *stream, *stream2;

            // Open for read (will fail if file "data" does not exist)
            stream  = fopen( "data", "r" );

            if(stream == NULL )
                printf( "The file 'data' was not opened\n" );
            else
                printf( "The file 'data' was opened\n" );

            // Open for write
            stream2 = fopen( "data2", "w+" );
            if(stream2 == NULL )
                printf( "The file 'data2' was not opened\n" );
            else
                printf( "The file 'data2' was opened\n" );

            // Close stream
            if( fclose( stream ) )
                printf( "The file 'data' was not closed\n" );

            // Close stream2
            if( fclose( stream2 ) )
                printf( "The file 'data2' was not closed\n" );
        }

Summary:
Sample data:
Header file: stdio.h
See also: fclose


fprintf

Function: fprintf
Prototype:
int fprintf(FILE *stream, const char *format, ...)
Remarks: Formats and prints a series of characters and values to the output stream. Each function argument (if any) is converted and output according to the corresponding format specification in format. For fprintf, the format argument has the same syntax and use that it has in printf.
Parameters:
stream	:Pointer to FILE structure
format	:Format-control string

Return values:
Returns the number of bytes written. Returns a negative value instead when an output error occurs.

Example:

        The following example uses fprintf to format various data and print it the the file named FPRINTF.OUT.

    void test_fprintf()
    {
        FILE *stream;
        int    i = 10;
        double fp = 1.5;
        char   s[] = "this is a string";
        char   c = '\n';

        stream = fopen( "fprintf.out", "w" );
        if(stream == NULL)
            printf( "The file fprintf.out was not opened\n" );;
        fprintf( stream, "%s%c", s, c );
        fprintf( stream, "%d\n", i );
        fprintf( stream, "%f\n", fp );
        fclose( stream );
    }

Summary:
Sample data:
Header file: stdio.h
See also: fscanf


fputc

Function: fputc
Prototype:
int fputc(int c, FILE *stream)
Remarks: Each of these functions writes the single character c to a file at the position indicated by the associated file position indicator (if defined) and advances the indicator as appropriate. In the case of fputc and fputwc, the file is associated with stream. If the file cannot support positioning requests or was opened in append mode, the character is appended to the end of the stream. Routine-specific remarks follow.
Parameters:
c		:Character to be written
stream	:Pointer to FILE

Return values:
Each of these functions returns the character written. For fputc and _fputchar, a return value of EOF indicates an error. For fputwc and _fputwchar, a return value of WEOF indicates an error.

Example:
        The following example uses fputc and send a character array to FPUTC.out

        void test_fgetc()
        {
            char strptr1[] = "This is a test of fputc!!\n";
            char *p;
            FILE *stream = fopen( "FPUTC.out", "w+t" );
            if(stream != NULL )
            {
                p = strptr1;
                while( (*p != '\0') && fputc( *(p++), stream ) != EOF ) ;
                fclose(stream)
            }
        }

Summary:
Sample data:
Header file: stdio.h
See also: fgetc


fputs

Function: fputs
Prototype:
int fputs(const char *str, FILE *stream )
Remarks: This function copies string to the output stream at the current position.
Parameters:
str		:Output string
stream	:Pointer to FILE

Return values:
Returns a nonnegative value if it is successful. On an error, fputs returns EOF.

Example:

        The following example use fputs to write a single line to the file FPUTS.out

        void test_fputs()
        {
            FILE *stream;

            // Open for write
            stream = fopen( "FPUTS.out", "w+" );
            if( stream == NULL )
                printf( "The file 'data' was not opened\n" );
            else
            {
                fputs( "Hello world from fputs.\n", stream );

                // Close stream
                fclose( stream );
            }
        }

        // If a code executed after opening the file and before closing it and the code excution leads
        // to execution error, the file stays open. to avoid such circumstance, one may use a try catch block
        // to assure the file is closed either way. plese check the following code

        void test(FILE *ff2)
        {
            FILE *ff;
            ff = fopen("C:\\MyFile3.txt", "w");
            fprintf(ff, "Hello World");
            try
            {
                fprintf(ff2, "Hello World");// ff2 is supplied by caller and could be junk
            }
            catch (int nErrorCode)
            {
                fclose(ff);

            }
            fclose(ff);
        }

Summary:
Sample data:
Header file: stdio.h
See also: fgets


fread

Function: fread
Prototype:
size_t fread(void *buffer, size_t size, size_t count, FILE *stream)
Remarks: The fread function reads up to count items of size bytes from the input stream and stores them in buffer. The file pointer associated with stream (if there is one) is increased by the number of bytes actually read. If the given stream is opened in text mode, carriage return–linefeed pairs are replaced with single linefeed characters. The replacement has no effect on the file pointer or the return value. The file-pointer position is indeterminate if an error occurs. The value of a partially read item cannot be determined.
Parameters:
buffer	:Storage location for data
size	:Item size in bytes
count	:Maximum number of items to be read
stream	:Pointer to FILE

Return values:
fread returns the number of full items actually read, which may be less than count if an error occurs or if the end of the file is encountered before reaching count. Use the feof or ferror function to distinguish a read error from an end-of-file condition. If size or count is 0, fread returns 0 and the buffer contents are unchanged.

Example:
        The following opens a file named FREAD.OUT and writes 25 characters to the file. It then tries to open FREAD.OUT and read in 25 characters.If the attempt succeeds,the program displays the number of actual items read.

        void test_fread()
        {
            FILE *stream;
            char list[30];
            int  i, numread, numwritten;

            // Open file in text mode:
            stream = fopen( "fread.out", "w+t" );
            if(stream != NULL )
            {
                for ( i = 0; i < 25; i++ )
                    list[i] = (char)('z' - i);

                // Write 25 characters to stream
                numwritten = fwrite( list, sizeof( char ), 25, stream );
                printf( "Wrote %d items\n", numwritten );
                fclose( stream );
            }
            else
                printf( "Problem opening the file\n" );

            stream = fopen( "fread.out", "r+t" );
            if(stream != NULL )
            {
                // Attempt to read in 25 characters
                numread = fread( list, sizeof( char ), 25, stream );
                printf( "Number of items read = %d\n", numread );
                printf( "Contents of buffer = %.25s\n", list );
                fclose( stream );
            }
            else
                printf( "File could not be opened\n" );
        }

Summary:
Sample data:
Header file: stdio.h
See also: fwrite


fscanf

Function: fscanf
Prototype:
int fscanf(FILE *stream, const char *format , ...)
Remarks: Reads data from the current position of stream into the locations given by argument (if any). Each argument must be a pointer to a variable of a type that corresponds to a type specifier in format. format controls the interpretation of the input fields and has the same form and function as the format argument for printf. If copying takes place between strings that overlap, the behavior is undefined.
Parameters:
stream	:Pointer to FILE structure
format	:Format-control string

Return values:
Returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is EOF.

Example:
        The following example writes formatted data to a file. It then uses fscanf to read the various data back from the file.

    void test_fscanf()
    {
        FILE *stream;
        long l;
        float fp;
        char s[81];
        char c;

        stream = fopen( "fscanf.out", "w+" );
        if( stream == NULL )
            printf( "The file fscanf.out was not opened\n" );
        else
        {
            fprintf( stream, "%s %ld %f%c", "a-string",
                   65000, 3.14159, 'x' );

            // Set pointer to beginning of file:
            fseek( stream, 0L, SEEK_SET );

            // Read data back from file:
            fscanf( stream, "%s", s );
            fscanf( stream, "%ld", &l );
            fscanf( stream, "%f", &fp );
            fscanf( stream, "%c", &c );

            // Output data read:
            printf( "%s\n", s );
            printf( "%ld\n", l );
            printf( "%f\n", fp );
            printf( "%c\n", c );

            fclose( stream );
        }
    }

Summary:
Sample data:
Header file: stdio.h
See also: fprintf


fseek

Function: fseek
Prototype:
int fseek(FILE *stream, long, int)
Remarks: The fseek function moves the file pointer (if any) associated with stream to a new location that is offset bytes from origin. The next operation on the stream takes place at the new location. On a stream open for update, the next operation can be either a read or a write. The argument origin must be one of the following constants, defined in COMMON.H: SEEK_CUR :Current position of file pointer SEEK_END :End of file SEEK_SET :Beginning of file You can use fseek to reposition the pointer anywhere in a file. The pointer can also be positioned beyond the end of the file. fseek clears the end-of-file indicator and negates the effect of any prior ungetc calls against stream. When a file is opened for appending data, the current file position is determined by the last I/O operation, not by where the next write would occur. If no I/O operation has yet occurred on a file opened for appending, the file position is the start of the file. For streams opened in text mode, fseek has limited use, because carriage return, linefeed translations can cause fseek to produce unexpected results. The only fseek operations guaranteed to work on streams opened in text mode are: * Seeking with an offset of 0 relative to any of the origin values. * Seeking from the beginning of the file with an offset value returned from a call to ftell.
Parameters:
stream	:Pointer to FILE
offset	:Number of bytes from origin
origin	:Initial position

Return values:
If successful, fseek returns 0. Otherwise, it returns a nonzero value. On devices incapable of seeking,
the return value is undefined.

Example:
        The following example open the file FSEEK.OUT and moves the pointer to the file's beginning

        void test_fseek()
        {
            FILE *stream;
            char line[81];
            int  result;

            stream = fopen( "fseek.out", "w+" );
            if( stream == NULL )
                printf( "The file fseek.out was not opened\n" );
            else
            {
                fprintf( stream, "The fseek begins here: "
                               "This is the file 'fseek.out'.\n" );
                result = fseek( stream, 23L, SEEK_SET);
                if( result )
                    printf( "Fseek failed" );
                else
                {
                    printf( "File pointer is set to middle of first line.\n" );
                    fgets( line, 80, stream );
                    printf( "%s", line );
                }
                fclose( stream );
            }
        }

Summary:
Sample data:
Header file: stdio.h
See also: ftell


ftell

Function: ftell
Prototype:
long ftell(FILE *stream)
Remarks: The ftell function gets the current position of the file pointer (if any) associated with stream. The position is expressed as an offset relative to the beginning of the stream. Note that when a file is opened for appending data, the current file position is determined by the last I/O operation, not by where the next write would occur. For example, if a file is opened for an append and the last operation was a read, the file position is the point where the next read operation would start, not where the next write would start. (When a file is opened for appending, the file position is moved to end of file before any write operation.) If no I/O operation has yet occurred on a file opened for appending, the file position is the beginning of the file.
Parameters:
stream	:Pointer to Target FILE

Return values:
ftell returns the current file position. The value returned by ftell may not reflect the physical byte offset for streams opened in text mode, because text mode causes carriage return–linefeed translation. Use ftell with fseek to return to file locations correctly. On error, ftell returns –1L and errno is set to one of two constants, defined in ERRNO.H. The EBADF constant means the stream argument is not a valid file-handle value or does not refer to an open file. EINVAL means an invalid stream argument was passed to the function. On devices incapable of seeking (such as terminals and printers), or when stream does not refer to an open file, the return value is undefined.

Example:
        The following example opened a file named the current C file for reading and tries to read 100 characters. It then uses ftell to determine the position of the file pointer and displays this position.

        void test_fseek()
        {
            FILE *stream;
            long position;
            char list[100];

            stream = fopen( __FILE__, "rb" );
            if(stream != NULL )
            {
                // Move the pointer by reading data:
                fread( list, sizeof( char ), 100, stream );
                // Get position after read:
                position = ftell( stream );
                printf( "Position after trying to read 100 bytes: %ld\n",position );
                fclose( stream );
            }
        }

Summary:
Sample data:
Header file: stdio.h
See also: fseek


fwrite

Function: fwrite
Prototype:
size_t fwrite(const void *buffer, size_t size, size_t count, FILE *stream)
Remarks: The fwrite function writes up to count items, of size length each, from buffer to the output stream. The file pointer associated with stream (if there is one) is incremented by the number of bytes actually written. If stream is opened in text mode, each carriage return is replaced with a carriage-return - linefeed pair. The replacement has no effect on the return value.
Parameters:
buffer	:Pointer to data to be written
size	:Item size in bytes
count	:Maximum number of items to be written
stream	:Pointer to FILE

Return values:
fwrite returns the number of full items actually written, which may be less than count
if an error occurs. Also, if an error occurs, the file-position indicator cannot be determined.

Example:
        The following opens a file named FREAD.OUT and writes 25 characters to the file. It then tries to open FREAD.OUT and read in 25 characters.If the attempt succeeds,the program displays the number of actual items read.

        void test_fread()
        {
            FILE *stream;
            char list[30];
            int  i, numread, numwritten;

            // Open file in text mode:
            stream = fopen( "fread.out", "w+t" );
            if(stream != NULL )
            {
                for ( i = 0; i < 25; i++ )
                    list[i] = (char)('z' - i);

                // Write 25 characters to stream
                numwritten = fwrite( list, sizeof( char ), 25, stream );
                printf( "Wrote %d items\n", numwritten );
                fclose( stream );
            }
            else
                printf( "Problem opening the file\n" );

            stream = fopen( "fread.out", "r+t" );
            if(stream != NULL )
            {
                // Attempt to read in 25 characters
                numread = fread( list, sizeof( char ), 25, stream );
                printf( "Number of items read = %d\n", numread );
                printf( "Contents of buffer = %.25s\n", list );
                fclose( stream );
            }
            else
                printf( "File could not be opened\n" );
        }

Summary:
Sample data:
Header file: stdio.h
See also: fread


CloseHandle

Function: CloseHandle
Prototype:
BOOL WINAPI CloseHandle(HANDLE hObject)
Remarks: This function closes an open object handle.
Parameters:
hObject = [in/out] Handle to an open object.

Return values:
TRUE for success

Example:

Summary:
Sample data:
Header file: mswin.h
See also: CreateFile


CompareFileTime

Function: CompareFileTime
Prototype:
LONG WINAPI CompareFileTime(const FILETIME *lpFileTime1,const FILETIME *lpFileTime2)
Remarks: compares two 64-bit file times
Parameters:
lpFileTime1 = pointer to the first file time
lpFileTime2 = pointer to the second file time

Return values:
-1 First file time is less than second file time.
0 First file time is equal to second file time.
+1 First file time is greater than second file time.

Example:
        // Note that the file c:\myfile.txt must exist for this example to run.
        void	run_CompareFileTime()
        {
            string						strFile = "c:\\myfile.txt";
            WIN32_FILE_ATTRIBUTE_DATA	fileInfo;
            // Get the attributes structure of the file
            if ( GetFileAttributesEx(strFile, 0, &fileInfo) )
            {
                int		nCompare = CompareFileTime(&fileInfo.ftLastAccessTime, &fileInfo.ftLastWriteTime);
                if (nCompare < 0)
                    out_str("Last access time is less than last write time");
                else if (0 == nCompare)
                    out_str("Last access time is the same as last write time");
                else
                    out_str("Last access time is greater than last write time");
            }
            else
                out_str("Cannot get file attributes!");
        }

Summary:
Sample data:
Header file: mswin.h
See also:


CopyFile

Function: CopyFile
Prototype:
BOOL WINAPI CopyFile(LPCSTR lpExistingFileName, LPCSTR lpNewFileName, BOOL bFailIfExists = FALSE)
Remarks: This function copies an existing file to a new file
Parameters:
lpExistingFileName = [in] Pointer to a null-terminated string that specifies the name of an existing file.
lpNewFileName =	[in] Pointer to a null-terminated string that specifies the name of the new file.
The name is limited to MAX_PATH characters.
bFailIfExists =	[in] Specifies how this operation is to proceed if a file of the same name as that specified by lpNewFileName already exists.
If this parameter is TRUE and the new file already exists, the function fails.
If this parameter is FALSE and the new file already exists, the function overwrites the existing file and succeeds.

Return values:
TRUE for success.

Example:
        void	test_CopyFile()
        {
            string strTemp = GetAppPath() + "Origin.ini";
            string strNew =  GetAppPath() + "junk.ini";
            if(!strTemp.IsFile())
            {
                out_str("No Origin.ini found");
                return;
            }
            if(strNew.IsFile())
                out_str("junk.ini already existed before we copy");

            if (!CopyFile(strTemp, strNew))
            {
                out_str("Copy file failed");
                return;
            }
            if(!strNew.IsFile())
                out_str("Error: Copy file did not create the junk.ini even though it said it did");
        }

Summary:
Sample data:
Header file: mswin.h
See also:


CreateDirectory

Function: CreateDirectory
Prototype:
BOOL WINAPI CreateDirectory(LPCSTR lpPathName,SECURITY_ATTRIBUTES * lpSecurityAttributes)
Remarks: The CreateDirectory function creates a new directory. If the underlying file system supports security on files and directories, the function applies a specified security descriptor to the new directory
Parameters:
lpPathName = Pointer to a null-terminated string that specifies the path of the directory to be created.
There is a default string size limit for paths of 248 characters. This limit is related to how the CreateDirectory function parses paths.
lpSecurityAttributes = Pointer to a SECURITY_ATTRIBUTES structure.
The lpSecurityDescriptor member of the structure specifies a security descriptor for the new directory. If lpSecurityAttributes is NULL, the directory gets a default security descriptor. The target file system must support security on files and directories for this parameter to have an effect.

Return values:
TRUE the function succeeds.

Example:
        void	run_CreateDirectory()
        {
            char	szDirPath[] = "c:\\TEXTRO\\";
            if (!CreateDirectory(szDirPath, NULL))
            {
                out_str("Couldn't create new directory.");
            }
        }

Summary:
Sample data:
Header file: mswin.h
See also:


CreateFile

Function: CreateFile
Prototype:
HANDLE WINAPI CreateFile(LPCSTR lpFileName, DWORD dwDesiredAccess, DWORD dwShareMode, SECURITY_ATTRIBUTES* lpSecurityAttributes, DWORD dwCreationDisposition, DWORD dwFlagsAndAttributes, HANDLE hTemplateFile)
Remarks: This function creates or opens an objects and returns a handle that can be used to access the object.
Parameters:
lpFileName = [in] A fullpath file name
dwDesiredAccess = [in] Specifies the type of access to the object. This parameter can be 0, GENERIC_READ, GENERIC_WRITE
dwShareMode = [in] Specifies how the object can be shared. If dwShareMode is 0, and CreateFile succeeds, the object cannot be shared and cannot be opened again until the handle is closed.
lpSecurityAttributes = [in] Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. Use NULL if no need for the handle to be inherited.
dwCreationDisposition = [in] Specifies which action to take on files that exist, and which action to take when files do not exist. Can be CREATE_NEW, CREATE_ALWAYS, OPEN_EXISTING, OPEN_ALWAYS, TRUNCATE_EXISTING
dwFlagsAndAttributes = [in] Specifies the file attributes and flags for the file.
hTemplateFile = [in] Specifies a handle with GENERIC_READ access to a template file. The template file supplies file attributes and extended attributes for the file being created.

Return values:
If the function succeeds, the return value is an open handle to the specified file.
If the function fails, the return value is INVALID_HANDLE_VALUE.

Example:
        //opens an existing file for reading.
        bool test_read_file(LPCSTR lpcszFilename)
        {
            HANDLE hFile;
            hFile = CreateFile(lpcszFilename,
                            GENERIC_READ,              // open for reading
                            FILE_SHARE_READ,           // share for reading
                            NULL,                      // no security
                            OPEN_EXISTING,             // existing file only
                            FILE_ATTRIBUTE_NORMAL,     // normal file
                            NULL);                     // no attr. template
            if (hFile == INVALID_HANDLE_VALUE)
            {
                out_str("Could not open file.");   // process error
                return false;
            }
            // codes to read the file
            CloseHandle(hFile);// must close file after reading
            return true;
        }

Summary:
Sample data:
Header file: mswin.h
See also: CloseHandle


DeleteFile

Function: DeleteFile
Prototype:
BOOL WINAPI DeleteFile(LPCTSTR lpFileName)
Remarks: Delete an existing file.
Parameters:
lpFileName = null-terminated string that specifies the file to be deleted.

Return values:
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero.

Example:
        string str = "c:\\mytempfile.txt";
        if( DeleteFile(str) )
            printf("%s deleted\n", str);
        else
            printf("%s was not deleted\n", str);

Summary: Delete an existing file.
Sample data:
Header file: mswin.h
See also:


FileTimeToLocalFileTime

Function: FileTimeToLocalFileTime
Prototype:
BOOL WINAPI FileTimeToLocalFileTime(const FILETIME *lpFileTime,FILETIME* lpLocalFileTime)
Remarks: The FileTimeToLocalFileTime function converts a file time to a local file time. This function uses the current settings for the time zone and daylight saving time. Therefore, if it is daylight saving time, this function will take daylight saving time into account, even if the time you are converting is in standard time.
Parameters:
lpFileTime = pointer to file time to convert
lpLocalFileTime = pointer to a FILETIME struct to receive the converted value
lpFileTime
  file time to convert
lpLocalFileTime
  receives system time

Return values:
TRUE if success, FALSE if error

Example:
        bool show_file_time(LPCSTR lpcsFilename)
        {
            WIN32_FILE_ATTRIBUTE_DATA	fileInfo;

            if(GetFileAttributesEx(lpcsFilename, 0, &fileInfo))
            {
                FILETIME localFiletime;
                if(FileTimeToLocalFileTime(&fileInfo.ftLastWriteTime, &localFiletime))
                {
                    SYSTEMTIME sysTime;
                    if(FileTimeToSystemTime(&localFiletime, &sysTime))
                    {
                        printf("%s is last modified at %.2d-%.2d-%4d %.2d:%.2d:%.2d\n",
                        lpcsFilename,
                        sysTime.wMonth,sysTime.wDay,sysTime.wYear,
                        sysTime.wHour, sysTime.wMinute, sysTime.wSecond);
                        return TRUE;
                    }
                }
            }
            return FALSE;
        }

Summary:
Sample data:
Header file: mswin.h
See also:


FileTimeToSystemTime

Function: FileTimeToSystemTime
Prototype:
BOOL WINAPI FileTimeToSystemTime(const FILETIME *lpFileTime,SYSTEMTIME* lpSystemTime)
Remarks: Converts a 64-bit file time (in form of a FILETIME structure) to system time format.
Parameters:
lpFileTime = the pointer to the 64-bit file time (usually obtained from GetFileAttributesEx() function as one of the
members of the WIN32_FILE_ATTRIBUTE_DATA structure).
lpSystemTime = the pointer to the SYSTEMTIME structure which will receive the result. The members of SYSTEMTIME
structure provide a human-readable form of date and time.

Return values:
nonzero for success, 0 for failure.

Example:
        // The example displays system time of one file.
        // Note that the file c:\myfile.txt must exist for this example to run.
        void	run_FileTimeToSystemTime()
        {
            string						strFile = "c:\\myfile.txt";
            WIN32_FILE_ATTRIBUTE_DATA	fileInfo;
            // Get the attributes structure of the file
            if ( GetFileAttributesEx(strFile, 0, &fileInfo) )
            {
                SYSTEMTIME		stSystemTime;
                // Convert the last access time to SYSTEMTIME structure:
                if ( FileTimeToSystemTime(&fileInfo.ftLastAccessTime, &stSystemTime) )
                {
                    printf("Year = %d,  Month = %d,  Day = %d,  Hour = %d,  Minute = %d\n", stSystemTime.wYear, stSystemTime.wMonth, stSystemTime.wDay, stSystemTime.wHour, stSystemTime.wMinute);
                }
            }
            else
                out_str("Cannot get file attributes!");
        }

Summary:
Sample data:
Header file: mswin.h
See also: SystemTimeToFileTime


FindClose

Function: FindClose
Prototype:
BOOL WINAPI FindClose(HANDLE hFindFile)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also: FindFirstFile


FindFirstFile

Function: FindFirstFile
Prototype:
HANDLE WINAPI FindFirstFile(LPCSTR lpFileName, WIN32_FIND_DATAA *lpFindFileData)
Remarks: Searches a directory for a file whose name matches the specified file name (wildcards are allowed). One can use this function in combination with FindNextFile and FindClose to find all the files in the specified directory.
Parameters:
lpFileName = the wildcard pattern which the file name must match
lpFindFileData = pointer to a structure WIN32_FIND_DATAA which will receive the information
about each file

Return values:

Example:
        // a DOS dir command
        // can type into ScriptWindow "dir c:\*.*", for example.
        //
        void dir(string strFile)
        {
            WIN32_FIND_DATAA	find;
            HANDLE	hFile;

            //out_str(strFile);
            int	nCount = 0;

            if((hFile=FindFirstFile(strFile,&find)) != INVALID_HANDLE_VALUE)
            {
                out_str(find.cFileName);
                nCount++;
                while(FindNextFile(hFile,&find))
                {
                    out_str(find.cFileName);
                    nCount++;
                }
                printf("%d files found\n",nCount);
                FindClose(hFile);		// must close  the hadle
            }
            else
                printf("%s: file(s) not found\n",strFile);
        }

Summary:
Sample data:
Header file: mswin.h
See also: FindNextFile


FindNextFile

Function: FindNextFile
Prototype:
BOOL WINAPI FindNextFile(HANDLE hFindFile, WIN32_FIND_DATAA *lpFindFileData)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also: FindFirstFile


GetFileAttributes

Function: GetFileAttributes
Prototype:
DWORD WINAPI GetFileAttributes(LPCSTR lpcszFilename)
Remarks: Retrieves given file attributes.
Parameters:
lpcszFilename = full pathname of the file.

Return values:
a bitfield with the following possible bits:
FILE_ATTRIBUTE_READONLY             0x00000001
FILE_ATTRIBUTE_HIDDEN               0x00000002
FILE_ATTRIBUTE_SYSTEM               0x00000004
FILE_ATTRIBUTE_DIRECTORY            0x00000010
FILE_ATTRIBUTE_ARCHIVE              0x00000020
FILE_ATTRIBUTE_ENCRYPTED            0x00000040
FILE_ATTRIBUTE_NORMAL               0x00000080
FILE_ATTRIBUTE_TEMPORARY            0x00000100
FILE_ATTRIBUTE_SPARSE_FILE          0x00000200
FILE_ATTRIBUTE_REPARSE_POINT        0x00000400
FILE_ATTRIBUTE_COMPRESSED           0x00000800
FILE_ATTRIBUTE_OFFLINE              0x00001000
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED  0x00002000

Example:
        void	run_GetFileAttributes()
        {
            DWORD	dwAttributes = GetFileAttributes("c:\\config.sys");
            printf("File attributes are: %#x\n", dwAttributes);
        }

Summary:
Sample data:
Header file: mswin.h
See also:


GetTempFileName

Function: GetTempFileName
Prototype:
BOOL GetTempFileName(string &strFile, LPCSTR lpcszPrefix = NULL)
Remarks: This function constructs a temporary file name in the Windows Temp path
Parameters:
strFile = a string to receive the temp file full path file name
lpcszPrefix = The function uses the first three characters of this string as the prefix of the file name.
If left as NULL, "OTF" will be used.

Return values:
TRUE if success, FALSE if not able to fine a temp path.

Example:
        string strTempFile;
        if(GetTempFileName(strTempFile,"ABC"))
        {
            printf("You can use this file name as temp file:%s\n", strTempFile);
        }

Summary:
Sample data:
Header file: sys_utils.h
See also:
Function: GetTempFileName
Prototype:
DWORD WINAPI GetTempFileName(LPCSTR lpPathName,LPCSTR lpPrefixString,DWORD uUnique,LPSTR lpTempFileName)
Remarks: This function creates a name for a temporary file.
Parameters:
lpPathName = A null-terminated string that specifies the directory path for the filename.
lpPrefixString = A null-terminated prefix string. The function uses the first three characters of this string as the prefix of the filename
uUnique = An unsigned integer that the function converts to a hexadecimal string for use in creating the temporary filename.
If nonzero, the function appends the hexadecimal string to lpPrefixString. In this case, the function does not create the specified file nor test whether the filename is unique.
If zero, the function uses a hexadecimal string derived from the current system time. In this case, the function uses different values until it finds a unique filename, and then it creates the file in the lpPathName directory.
lpTempFileName = Buffer that receives the filename. The buffer size should be at least MAX_PATH.

Return values:
If the function succeeds, the return value specifies the unique numeric value used in the temporary filename. If the uUnique parameter is nonzero, the return value specifies that same number.
If the function fails, the return value is zero.

Example:
        void test_TempFileNameInTempPath()
        {
            string strFile;
            char sz[MAXFULLPATH];
            DWORD dw = GetTempPath(MAXFULLPATH, sz);
            if( dw )
            {
                strFile = sz;
                dw = GetTempFileName(strFile, "Origin", 0, sz);
                if( dw )
                    strFile = sz;
                else
                    strFile.Empty();
            }
            out_str(strFile);
        }

Summary:
Sample data:
Header file: mswin.h
See also:


GetTempPath

Function: GetTempPath
Prototype:
DWORD WINAPI GetTempPath(DWORD nBufferLength,LPSTR lpBuffer)
Remarks: The GetTempPath function retrieves the path of the directory designated for temporary files.
Parameters:
nBufferLength = Specifies the size, in TCHARs, of the string buffer identified by lpBuffer.
lpBuffer = Pointer to a string buffer that receives the null-terminated string specifying the temporary file path. The returned string ends with a backslash, for example, C:\TEMP\.

Return values:
If the function succeeds, the return value is the length, not including the terminating null character.
If the return value is greater than nBufferLength, the return value is the size of the buffer required to hold the path.
If the function fails, the return value is zero.

Example:
        void	run_GetTempPath()
        {
            char		sztemp[MAXFULLPATH];
            DWORD		aa = GetTempPath(MAXFULLPATH, sztemp);
            out_str(sztemp);
        }

Summary:
Sample data:
Header file: mswin.h
See also:


SetFileAttributes

Function: SetFileAttributes
Prototype:
BOOL WINAPI SetFileAttributes(LPCSTR lpcszFilename,DWORD dwFileAttributes)
Remarks: It sets file attributes.
Parameters:
lpcszFilename = full pathname of the file.
dwFileAttributes = new attributes

Return values:
nonzero if it succeeds, 0 if it fails.

Example:
        // This example shows how to change file attributes of a file.
        // Note that the file c:\myfile.txt must exist for this example to run.
        void	run_SetFileAttributes()
        {
            string		strFile = "c:\\myfile.txt";

            // First get and display the old attributes:
            DWORD	dwAttributes = GetFileAttributes(strFile);
            printf("File attributes are: %#x\n", dwAttributes);

            // Change the attributes:
            SetFileAttributes(strFile, 0x22);

            // Display again:
            dwAttributes = GetFileAttributes(strFile);
            printf("File attributes are: %#x\n", dwAttributes);
        }

Summary: set a file's attributes
Sample data:
Header file: mswin.h
See also:


SetFileTime

Function: SetFileTime
Prototype:
BOOL WINAPI SetFileTime(HANDLE hFile, const FILETIME *lpCreationTime, const FILETIME *lpLastAccessTime, const FILETIME *lpLastWriteTime)
Remarks: This function sets the date and time that a file was created, last accessed, or last modified. Parameters hFile = [in] Handle to the file for which to set the dates and times. The file handle must have been created with GENERIC_WRITE access to the file. lpCreationTime = [in] Pointer to a FILETIME structure that contains the date and time the file was created. This parameter can be NULL if the application does not need to set this information. lpLastAccessTime = [in] Pointer to a FILETIME structure that contains the date and time the file was last accessed. The last access time includes the last time the file was written to, read from, or (in the case of executable files) run. This parameter can be NULL if the application does not need to set this information. lpLastWriteTime = [in] Pointer to a FILETIME structure that contains the date and time the file was last written to. This parameter can be NULL if the application does not want to set this information.
Parameters:

Return values:
TRUE if success, FALSE if error

Example:
        BOOL SetFileToCurrentTime(LPCSTR lpcszFilename)
        {
            BOOL bRet = FALSE;
            HANDLE hFile = CreateFile(lpcszFilename, GENERIC_WRITE, FILE_SHARE_READ, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);
            if (hFile != INVALID_HANDLE_VALUE)
            {
                FILETIME ft;
                SYSTEMTIME st;
                GetSystemTime(&st);              // gets current time
                SystemTimeToFileTime(&st, &ft);  // converts to file time format
                bRet = SetFileTime(hFile,NULL, NULL, &ft);
                CloseHandle(hFile);
            }
            return bRet;
        }

Summary:
Sample data:
Header file: mswin.h
See also: FileTimeToSystemTime


add_file_extension

Function: add_file_extension
Prototype:
bool add_file_extension(string& strFilename, LPCSTR lpcszExt)
Remarks: Add file extension to given string
Parameters:
strFilename = filename to check and add extension
lpcszExt = file extension, without the dot.

Return values:
true if extension is added, false if filename already has given extension

Example:
        string str = GetAppPath() + "origin.ini";
        bool bRet = add_file_extension(str, "ini");
        ASSERT(!bRet);
        bRet = add_file_extension(str, "txt");
        ASSERT(bRet);
        string strFilename = GetFileName(str);
        ASSERT(strFilename == "origin.ini.txt");

Summary:
Sample data:
Header file: sys_utils.h
See also:


FileCopy

Function: FileCopy
Prototype:
BOOL FileCopy(LPCSTR lpcszSrc, LPCSTR lpcszDest, DWORD dwAttribute = FILE_ATTRIBUTE_NORMAL, bool bSetCurrentTime = false)
Remarks: Copy file and also set destination file's attribute This function will call CopyFile with default bFailIfExists = FALSE
Parameters:
lpcszSrc = [in] Pointer to a null-terminated string that specifies the name of an existing file.
lpcszDest =	[in] Pointer to a null-terminated string that specifies the name of the new file.
dwAttribute = the file attribute to set on the new file lpcszDest
bSetCurrentTime = set the destination file to the current time or not

Return values:
Returns TRUE for success, otherwise failure.

Example:
    string strThemeFile = get_theme_file_name(nSelRow, flx);
    string strPath = GetAppPath();
    strPath += "Deleted";
    if(CheckMakePath(strPath))
    {
        string strTemp = GetFileName(strThemeFile);
        FileCopy(strThemeFile, strPath + "\\" + strTemp);
        DeleteFile(strThemeFile);
        load_themes_to_grid();
    }

Summary:
Sample data:
Header file: sys_utils.h
See also:


FindFiles

Function: FindFiles
Prototype:
BOOL FindFiles(StringArray& saResult, LPCSTR lpcszPath, LPCSTR lpcszExt, bool bCheckExist = false)
Remarks: List all files of a specified file type found in a folder
Parameters:
saResult = the referrence of string array will receive the finding results
lpcszPath = the file path to search for files
lpcszExt = the file extension to search for
bCheckExist = true will check the given saReult to see if the file is already in that array

Return values:
Returns TRUE for success, otherwise failure.

Example:
    string strExePath = GetAppPath();
    StringArray saResult;
    FindFiles(saResult, strExePath, "otw");

Summary:
Sample data:
Header file: sys_utils.h
See also:


get_next_file_name

Function: get_next_file_name
Prototype:
bool get_next_file_name(string& strFilename, bool bCheckCreatePath = true)
Remarks: Check to find the filename that does not already exist
Parameters:
strFilename = filename to check and update if needed
bCheckCreatePath = if path dose not existed, to create or just return false

Return values:
true strFilename is a good new file name that is not in conflict with existing files

Example:
        string str = GetAppPath() + "origin.ini";
        bool bRet = get_next_file_name(str);
        ASSERT(bRet);
        string strOld = GetAppPath() + "origin.ini";
        ASSERT(strOld != str);// since origin.ini must already existed

Summary:
Sample data:
Header file: sys_utils.h
See also:


GetFileModificationDate

Function: GetFileModificationDate
Prototype:
string GetFileModificationDate(LPCSTR lpcstrPathAndFilename, WORD wFormat=LDF_SHORT)
Remarks: Get the file modification date of a file from an input string containing a path and filename.
Parameters:
strPathAndFilename=Input string containing a path and filename with filetype extension

Return values:
Returns a Windows like file modification date formatted for display.

Example:
        string strFileDate, strDataFile = "C:\\Origin80\\Origin.ini";
        strFileDate = GetFileModificationDate(strDataFile);

Summary:
Sample data:
Header file: sys_utils.h
See also:


is_str_valid_for_filename

Function: is_str_valid_for_filename
Prototype:
bool is_str_valid_for_filename(LPCSTR lpcszFilename)
Remarks: Check to see if specified string is a valid file name, no path is allowed
Parameters:
lpcszFilename = filename to check

Return values:
true if lpcszFilename is not empty and does not contain illegal characters, return false if lpcszFilename contains path or has other invalid characters for filename

Example:
        string str = "origin*.ini";
        ASSERT(!is_str_valid_for_filename(str));
        str = "origin.ini";
        ASSERT(is_str_valid_for_filename(str));
        str = GetAppPath() + "origin.ini";
        ASSERT(str.IsFile());
        ASSERT(!is_str_valid_for_filename(str));

        ASSERT(!is_str_valid_for_filename("abc?ef"));
        ASSERT(is_str_valid_for_filename("abcef"));

Summary:
Sample data:
Header file: sys_utils.h
See also:


_chdir

Function: _chdir
Prototype:
int _chdir( const char *lpcszPath )
Remarks: Change the current working directory.
Parameters:
*lpcszPath = Path of new working directory.

Return values:
0 if successful. A return value of -1 indicates that the specified path could not be found

Example:
        void	run_chdir()
        {
            string		strNewCurrentDir = "c:\\";
            if (0 == _chdir(strNewCurrentDir))
            {
                // If it succeded, display the new current directory:
                char		szcurDirectory[MAXFULLPATH];
                if ( _getcwd(szcurDirectory, MAXFULLPATH) != NULL )
                {
                    out_str(szcurDirectory);
                }
            }
        }

Summary: change the current working directory to the specified path
Sample data:
Header file: utilities.h
See also:


_chdrive

Function: _chdrive
Prototype:
int _chdrive( int drive )
Remarks: Changes the current working drive.
Parameters:
drive: Number of new working drive, A drive is 1, B drive is 2, C drive is 3, and so on.

Return values:
returns a value of 0 if the working drive is successfully changed. A return value of -1 indicates an error.

Example:
        void	run_chdrive()
        {
            int		nCurrentDrive = _getdrive();
            printf("Current drive is %c\n", (char)(nCurrentDrive + 'A' - 1));

            if (0 == _chdrive(4))
            {
                nCurrentDrive = _getdrive();
                printf("Current drive is %c\n", (char)(nCurrentDrive + 'A' - 1));
            }
            else
                out_str("Failed to change current drive!");
        }

Summary: change the current working drive
Sample data:
Header file: utilities.h
See also:


_getcwd

Function: _getcwd
Prototype:
char* _getcwd( char *buffer, int maxlen )
Remarks: Get the current working directory.
Parameters:
buffer = Storage location for path to be returned by the function
maxlen = Maximum length of path in characters

Return values:
returns a pointer to buffer. A NULL return value indicates an error.

Example:
        void	run_getcwd()
        {
            char		szcurDirectory[MAXFULLPATH];
            if ( _getcwd(szcurDirectory, MAXFULLPATH) != NULL )
            {
                out_str(szcurDirectory);
            }
        }

Summary: get the current working path
Sample data:
Header file: utilities.h
See also:


_getdrive

Function: _getdrive
Prototype:
int _getdrive( )
Remarks: Get the current working drive.
Parameters:
None.

Return values:
returns the current (default) drive (1 = A, 2 = B, and so on).

Example:
        void	run_getdrive()
        {
            int		nCurrentDrive = _getdrive();
            printf("Current drive is %c\n", (char)(nCurrentDrive + 'A' - 1));
        }

Summary: get the current working drive
Sample data:
Header file: utilities.h
See also:


check_add_file_ext

Function: check_add_file_ext
Prototype:
BOOL check_add_file_ext(LPSTR lpszFilename, LPCSTR lpcszExt, LPSTR lpszExt2 = NULL)
Remarks: Add extension to file name if not present, or to get file extension string This function assumes that lpszFilename has extra space to append file extension if lpcszExt ==NULL, then return false if has extension and copied to into lpszExt2 if not NULL if lpcszExt !=NULL, then if lpszExt2 == NULL, then replace/append ext regardless if existed or not, return FALSE if no change if lpszExt2 != NULL, then it is assumed to be 2nd ext, replace/append if not either, return FALSE if no change
Parameters:
lpszFilename = filename with or without path, typically from a buffer with MAXFULLPATH in size
lpcszFileExt = file extension, without the dot.
lpszExt2 = optional buffer, see Remark

Return values:
It depends on the various combinations of the arguments, but in general TRUE indicates that extension is added or updated. FALSE indicate that there is no change to lpszFilename

Example:
        void run_check_add_file_ext()
        {
            char szTemp[20];
            char strFileName[100];
            string str = GetAppPath(1) + "origin.ini";
            lstrcat(strFileName, str);

            BOOL bRet = check_add_file_ext(strFileName,NULL,szTemp);
            out_str(szTemp);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


CheckMakePath

Function: CheckMakePath
Prototype:
BOOL CheckMakePath(LPCSTR lpcszFullPath)
Remarks: Check the given path to see if is existed, if not, then create all the needed folders
Parameters:
lpcszFullPath= full path string to check for making folders

Return values:
TRUE if either the path already existed (can call string::IsPath if don't want to waste time).
FALSE if error occurs when attempting to create the needed folders

Example:
        void	test_CheckMakePath()
        {
            string	str = GetAppPath() + "junk\\some more junk";
            ASSERT(!str.IsPath());
            if(CheckMakePath(str))
            {
                ASSERT(str.IsPath());
            }
            else
                out_str("err in creating path");
        }

Summary:
Sample data:
Header file: utilities.h
See also:


file_compare

Function: file_compare
Prototype:
int file_compare(LPCSTR lpcszFilename1, LPCSTR lpcszFilename2)
Remarks: Comare the contents of two files. This function does a byte by byte binary compare
Parameters:
lpcszFilename1 = fullpath filename of the first file
lpcszFilename2 = fullpath filename of the second file

Return values:
0 if two files match in contents
1 if two files are different
-1 if error

Example:
        void	run_file_compare()
        {
            string	strPath = GetAppPath();
            string strLineOTP = strPath + "Line.otp";
            string strOriginOTP = strPath + "Origin.otp";
            if(file_compare(strLineOTP, strOriginOTP) == 0)
                out_str("Line graph template is using default template");
            else
                out_str("Line graph template is different from default Origin template");
        }

Summary:
Sample data:
Header file: utilities.h
See also:


FindFile

Function: FindFile
Prototype:
BOOL FindFile(LPCTSTR lpcszName, LPSTR lpPath, LPCTSTR lpSubFolder1st = NULL, BOOL bExcluded = TRUE)
Remarks: Find a file in a given path. If lpSubFolder1st is given (not NULL), then A. if bExcluded = FALSE, then find this subfolder first, B. if bExcluded = TRUE, skip this subfolder
Parameters:
lpcszName = File name to search for.
lpPath = on input, the starting path to search for a file. Output, to receive the full path of the file if found.
lpSubPath = Optional subfolder of the given path(lpPath) to search in.
bExcluded = whether to skip searching the subfolder (lpSubFolder1st) (FALSE to search it first)

Return values:
If the file is found then TRUE else FALSE.

Example:
        void	run_FindFile()
        {
            char		szTemp[MAXFULLPATH];
            lstrcpy(szTemp, GetAppPath());
            if(FindFile("APP_UTILS.c", szTemp, "Originlab", FALSE))
            {
                out_str("ok, found it");
                out_str(szTemp);
            }
            else
                out_str("Not found!");
        }

Summary:
Sample data:
Header file: utilities.h
See also:


GetFileName

Function: GetFileName
Prototype:
string GetFileName(LPCSTR lpcszFullPathFileName, BOOL bRemoveExt=FALSE)
Remarks: Extracts the file name from a full path file name string.
Parameters:
lpcszFullPathFileName=Pointer to a string containing a files full path name.
bRemoveExt=TRUE will remove file extension so only the file name part will be returned

Return values:
A string containing only the file name with extension or not depending on bRemoveExt.

Example:
        void	run_GetFileName()
        {
            string	str = "c:\\c\\test.dat";
            string	strFileName = GetFileName(str);
            out_str(strFileName);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


GetFilePath

Function: GetFilePath
Prototype:
string GetFilePath(LPCSTR lpcszFullPathFileName)
Remarks: Extracts the path from a full path file name string.
Parameters:
lpcszFullPathFileName = Pointer to a string containing a files full path name.

Return values:
A string containing only the path portion, including the last '\' character.
If no path is present then the returned string is empty.

Example:
        void	run_GetFilePath()
        {
            string	str = "c:\\c\\test.dat";
            string	strFilePath = GetFilePath(str);
            out_str(strFilePath);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


RenameFile

Function: RenameFile
Prototype:
BOOL RenameFile(LPCSTR lpcszNewFilename, LPCSTR lpcszOldFilename)
Remarks: Rename a file with full path specified for both old and new file names The old file name must point to a valid file that can be renamed and the new file name specified must be a full path in the same folder as the original.
Parameters:
lpcszNewFilename= full path file name to rename to
lpcszOldFilename = full path file name of the existing file to rename

Return values:
TRUE if success

Example:
        void	test_RenameFile()
        {
            string	str = GetAppPath() + "origin.ini";
            CopyFile(str, GetAppPath() + "junk1.ini");
            string strNewName = GetAppPath() + "junk2.ini";
            ASSERT(!strNewName.IsFile());
            RenameFile(strNewName, GetAppPath() + "junk1.ini");
            ASSERT(strNewName.IsFile());
        }

Summary:
Sample data:
Header file: utilities.h
See also:


get_system_font_name

Function: get_system_font_name
Prototype:
string get_system_font_name(int nType = ANSI_VAR_FONT, int* lpnCharSet = NULL)
Remarks: Get system font name
Parameters:
nType = OEM_FIXED_FONT, SYSTEM_FONT etc const, can also pass in GSFI_TYPE_DEFAULT, GSFI_TYPE_FIXED_WIDTH, GSFI_TYPE_SCALABLE for Origin fonts

Return values:
name of the specified font type, or an empty string if specified type is not valid

Example:
        void show_sys_fonts()
        {
            vector<string> vsNames = {
                "SYSTEM_FONT", "DEVICE_DEFAULT_FONT", "DEFAULT_GUI_FONT", "ANSI_VAR_FONT", "OEM_FIXED_FONT",
                "ANSI_FIXED_FONT", "SYSTEM_FIXED_FONT"};
            vector<int> vnIDs = {
                SYSTEM_FONT, DEVICE_DEFAULT_FONT, DEFAULT_GUI_FONT, ANSI_VAR_FONT, OEM_FIXED_FONT,
                ANSI_FIXED_FONT, SYSTEM_FIXED_FONT};

            printf("%20s\t%s\n", "Font", "Font Face");
            out_str("-------------------------------------");
            for(int ii = 0; ii < vsNames.GetSize(); ii++)
                printf("%20s\t%s\n", vsNames[ii], get_system_font_name(vnIDs[ii]));
        }

Summary:
Sample data:
Header file: sys_utils.h
See also:


get_system_font_info

Function: get_system_font_info
Prototype:
BOOL get_system_font_info(int nType, int* lpnFontSize, byte* lpnCharSet, LPSTR lpszFontName, int nNameSize)
Remarks: Get system fonts details
Parameters:
nType = OEM_FIXED_FONT, SYSTEM_FONT etc const, can also pass in GSFI_TYPE_DEFAULT, GSFI_TYPE_FIXED_WIDTH, GSFI_TYPE_SCALABLE for Origin fonts
lpnFontSize = pointer to int to receive font size
lpnCharSet = pointer to a byte to receive Character Set type
lpszFontName = buffer to receive font face name
nNameSize = size of lpszFontName

Return values:

Example:
        string get_system_font_name(int nType, int* lpnCharSet) // = ANSI_VAR_FONT, NULL);
        {
            int nFontSize;
            byte nCharSet = ANSI_CHARSET;

            string str;
            char	szTemp[LF_FACESIZE + 1];
            if(get_system_font_info(nType, &nFontSize, &nCharSet, szTemp, LF_FACESIZE))
                str = szTemp;
            if(lpnCharSet)
                *lpnCharSet = nCharSet;

            return str;
        }

Summary:
Sample data:
Header file: utilities.h
See also:


GetFontName

Function: GetFontName
Prototype:
string GetFontName(int nID, int* plfHeight)
Remarks: Get font name.
Parameters:
nID = OEM_FIXED_FONT, ANSI_FIXED_FONT, ANSI_VAR_FONT, SYSTEM_FONT, etc
plfHeight = if not NULL, to receive LOGFONT.lfHeight

Return values:
A string containing the font name.

Example:
        void	test_GetFontName()
        {
            string	str;
            str = GetFontName(SYSTEM_FONT);
            out_str(str);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


get_graph_layer

Function: get_graph_layer
Prototype:
GraphLayer get_graph_layer(const TreeNode& trNode)
Remarks: retrive the graph layer from the tree node
Parameters:
trNode = [in] tree node that may contains the needed info prepared by set_active_layer

Return values:
a valid graph layer if successful
See Also:
set_active_layer

Example:
        //This example get the active graph layer.
        void run_get_graph_layer()
        {
            GraphPage gp;
            gp.Create();

            Tree trNode;
            set_active_layer(trNode);				//Get the Info. of the active layer

            GraphLayer gl = get_graph_layer(trNode);

            ASSERT(gp.GetName() == gl.GetPage().GetName());

            out_str("The active graph layer is: " + gl.GetPage().GetName() + "(" + gl.GetIndex() + ")");
        }

Summary:
Sample data:
Header file: analysis_utils.h
See also:


set_active_layer

Function: set_active_layer
Prototype:
bool set_active_layer(TreeNode& trNode)
Remarks: add to TreeNode the name of the active graph page and the active layer number
Parameters:
trNode = [out] tree node to add the needed info

Return values:
TRUE if the active layer is a graphic layer, FALSE if no active graph layer available
See Also:
get_graph_layer

Example:

Summary:
Sample data:
Header file: analysis_utils.h
See also:
Function: set_active_layer
Prototype:
bool set_active_layer(Layer& layr)
Remarks: set the given layer to be active layer, if page not open, will open it to be active page as well
Parameters:
layr = [in] typically a GraphLayer to be set as active

Return values:
true  if successful
See Also:
set_active_layer

Example:
        GraphLayer gl("Graph1",0);
        set_active_layer(gl);

Summary:
Sample data:
Header file: analysis_utils.h
See also:


export_page

Function: export_page
Prototype:
bool export_page(Page &pg, LPCSTR lpcszFileName, const TreeNode &trExport)
Remarks: Export a page to an image using settings from a tree node.
Parameters:
pg = reference to the page to export
lpcszFileName = pointer to the target file name
trExport = a tree node containing the export settings

Return values:

Example:

Summary:
Sample data:
Header file: sys_utils.h
See also:
Function: export_page
Prototype:
bool export_page(Page &pg, LPCSTR lpcszFileName, LPCSTR lpcszFormat = "EPS")
Remarks: Export a page to an image using the page's export settings
Parameters:
pg = reference to the page to export
lpcszFileName = pointer to the target file name
lpcszFormat = pointer to the target format

Return values:
Returns 0 for success, non-zero for error.

Example:
    void run_export_page()
    {
        GraphPage		gp;
        gp.Create();
        if( !gp)
        {
            return;
        }

        string strExt("bmp");
        string strImagePath;
        strImagePath = GetAppPath(1) + "Test." + strExt;
        bool bRet = export_page(gp,strImagePath,strExt);
    }

Summary:
Sample data:
Header file: sys_utils.h
See also:


export_page_to_image

Function: export_page_to_image
Prototype:
bool export_page_to_image(Page &pg, LPCSTR lpcszFileName, LPCSTR lpcszFormat, BOOL bShowOptions=FALSE)
Remarks: Export a page to an image using current ini settings or prompt user with export options
Parameters:
lpcszFileName = pointer to the target file name
lpcszFormat = pointer to the target format
pg = reference to the page to export
bShowOptions = TRUE to show the export options dialog, FALSE to use current settings

Return values:
Returns 0 for success, non-zero for error.

Example:
    PageBase pbActive;
    pbActive = Project.Pages();
    string strPgName = pbActive.GetName();
    Page pg(strPgName);
    export_page_to_image( pg, "c:\\test.bmp", "bmp", false);

Summary:
Sample data:
Header file: sys_utils.h
See also:
Function: export_page_to_image
Prototype:
bool export_page_to_image(LPCSTR lpcszFileName, LPCSTR lpcszFormat, Page &pg, int nWidth, int nHeight, int nBitsPerPixel, int nCompression=0)
Remarks: Export a page to an image using the specified settings
Parameters:
lpcszFileName = pointer to target file name
lpcszFormat = pointer to target image format
pg = reference to source page
nWidth = target image width in pixels.  If nHeight parameter is zero then nWidth specifies dots per inch.
nHeight = target image height in pixels.  If zero then nWidth specifies dots per inch.
nBitsOrHeight = target image bits per pixel
nCompression = target image compression level.  This parameter is ignored by some image formats.

Return values:
Returns TRUE for success, FALSE for failure.

Example:
    void run_export_page_to_image()
    {
        GraphPage gp;
        gp.Create();
        if( !gp )
        {
            return;
        }

        string 	strImagePath("C:\\Test.bmp");
        int nRet = export_page_to_image(strImagePath, "bmp", gp, 1029, 789, 8, 0);
    }

Summary:
Sample data:
Header file: sys_utils.h
See also:


set_page_import_info

Function: set_page_import_info
Prototype:
BOOL set_page_import_info(Page &pgTarget, LPCSTR lpcszFile, int iDataType)
Remarks: Set the page.info.import properties.
Parameters:
pgTarget = reference to the page that will receive the import info
lpcszFile = pointer to the name of the file imported
iDataType = the type of data

Return values:
TRUE for success, FALSE for failure

Example:

Summary:
Sample data:
Header file: sys_utils.h
See also:


tree_get_page_image_export_settings

Function: tree_get_page_image_export_settings
Prototype:
bool tree_get_page_image_export_settings(TreeNode &trSettings, Page &pg, LPCSTR lpcszFormat)
Remarks: Get the image export settings from a page.
Parameters:
trSettings = tree node to receive the settings
pg = page to get the settings from
lpcszFormat = pointer to the image format

Return values:
true for success, false for error

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_read_image_export_settings

Function: tree_read_image_export_settings
Prototype:
bool tree_read_image_export_settings(TreeNode &trSettings, LPCSTR lpcszFormat)
Remarks: Read the export settings, for a specified format, into a tree node.
Parameters:
trSettings = tree node to receive the settings
lpcszFormat = pointer to the image format whose settings are to be read

Return values:
true for success, false for error

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_set_page_image_export_settings

Function: tree_set_page_image_export_settings
Prototype:
bool tree_set_page_image_export_settings(TreeNode &trSettings, Page &pg, LPCSTR lpcszFormat, bool bClearSection=false)
Remarks: Set the image export settings into a page.
Parameters:
trSettings = tree node containing the settings
pg = page to set the settings into
lpcszFormat = pointer to the image format

Return values:
true for success, false for error

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_write_image_export_settings

Function: tree_write_image_export_settings
Prototype:
bool tree_write_image_export_settings(TreeNode &trSettings, LPCSTR lpcszFormat, bool bClearSections=false)
Remarks: Write the export settings, for a specified format, into a tree node.
Parameters:
trSettings = tree node containing the settings
lpcszFormat = pointer to the image format whose settings are to be written

Return values:
true for success, false for error

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


AscImpReadFileStruct

Function: AscImpReadFileStruct
Prototype:
int AscImpReadFileStruct(LPCSTR lpcszFilename, ASCIMP* pASCIMPstruct, DWORD dwCntrl=0)
Remarks: Scan and analyse the given file to gather information for ascii import into worksheets. This function will look read the file to look for consistent structure by trying different separators that will yield the largest number of columns.
Parameters:
lpcszFilename = a full path ASCII file name
pASCIMPstruct = pointer to an ASCIMP struct that is not initialized on input but will be set when function returns
dwCntrl = additional flags to control the reading, only AIRF_USE_ASCIMP is defined for now.
dwCntrl = 0 for pASCIMPstruct to be used only as output, if AIRF_USE_ASCIMP, then it will be used as starting point for further scanning

Return values:
Returns 0 if no error, otherwise an error code is returned

Example:
        ASCIMP	ascimp;
        string strFile = GetOpenBox("*.dat");
        if(AscImpReadFileStruct(strFile,&ascimp)==0)
        {
            out_int("# of header lines= ", ascimp.iHeaderLines);
            out_int("# of columns = ", ascimp.iNumcolumns);
        }

Summary:
Sample data:
Header file: utilities.h
See also: ImportASCII


GetSPCLog

Function: GetSPCLog
Prototype:
string GetSPCLog(LPCSTR lpcszWksName, int nCol)
Remarks: Get SPC log information from worksheet
Parameters:
lpcszWksName = worksheet name
nCol = column index from 0

Return values:
The string contents ASCII format log

Example:
         For this example to run, a worksheet named Data1 should exist in the project.

        void run_GetSPCLog()
        {
                string strInfo;
                strInfo = GetSPCLog("Data1", 0);
                out_str(strInfo);
                out_str(strInfo);
        }

Summary:
Sample data:
Header file: wksheet.h
See also:


GetSPCMainHeader

Function: GetSPCMainHeader
Prototype:
BOOL GetSPCMainHeader(LPCSTR lpcszWksName, int nCol, OSPCMAINHeader *SPCMainHeader)
Remarks: Get SPC main header information from worksheet
Parameters:
lpcszWksName = worksheet name
nCol = column index from 0
SPCMainHeader = SPC main header structure

Return values:
TRUE means the header information is retrieved successfully
FALSE indicates the failure in retrieving header information

Example:
        string strWks = "Data1";
        Worksheet wks(strWks);
        OSPCMAINHeader spcMainHeader;
        for(int jj = 0; jj< wks.GetNumCols();jj++)
        {
            if( GetSPCMainHeader(strWks, jj, &spcMainHeader) )
            {
                //read information from the main header
                int iNumOfSubs = spcMainHeader.fnsub;
                OSPCSUBHeader spcSubHeader;

                for( int ii=0; ii<iNumOfSubs; ii++ )
                {
                    if( GetSPCSubHeader(strWks, jj, &spcSubHeader, ii) )
                        //read information from the subheader
                }
            }

            string strLog;
            strLog = GetSPCLog(strWks, jj);
        }

Summary:
Sample data:
Header file: wksheet.h
See also:


GetSPCSubHeader

Function: GetSPCSubHeader
Prototype:
BOOL GetSPCSubHeader(LPCSTR lpcszWksName, int nCol, OSPCSUBHeader *SPCSubHeader, int nIndex)
Remarks: Get SPC subheader information from worksheet. This function requires the subheader counter from the main header structure. Therefore, the OSPCMAINHeader information has to be retrieved successfully first to be able to use this function.
Parameters:
lpcszWksName = worksheet name
nCol = column index from 0
SPCSubHeader = SPC sub header structure
nIndex = the index of subheader from 0

Return values:
TRUE means the subheader information is retrieved successfully
FALSE indicates the failure in retrieving subheader information

Example:
        string strWks = "Data1";
        Worksheet wks(strWks);
        OSPCMAINHeader spcMainHeader;
        for(int jj = 0; jj< wks.GetNumCols();jj++)
        {
            if( GetSPCMainHeader(strWks, jj, &spcMainHeader) )
            {
                //read information from the main header
                int iNumOfSubs = spcMainHeader.fnsub;
                OSPCSUBHeader spcSubHeader;

                for( int ii=0; ii<iNumOfSubs; ii++ )
                {
                    if( GetSPCSubHeader(strWks, jj, &spcSubHeader, ii) )
                        //read information from the subheader
                }
            }

            string strLog;
            strLog = GetSPCLog(strWks, jj);
        }

Summary:
Sample data:
Header file: wksheet.h
See also:


info_get_section

Function: info_get_section
Prototype:
bool info_get_section(OriginObject& obj, TreeNode& trSection, LPCSTR lpcszStorageSection)
Remarks: Get a section from an OriginObject's Info.
Parameters:
obj = the OriginObject to get the section from
trSection = the tree node to put the section into
lpcszStorageSection = pointer to the storage and section name

Return values:
If success then true else false

Example:
        Page pg("Data1");
        if( info_get_section(pg, trSection, "User.Variables") )
        {
        }

Summary:
Sample data:
Header file: page_utils.h
See also:


info_set_section

Function: info_set_section
Prototype:
bool info_set_section(OriginObject& obj, TreeNode& trSection, LPCSTR lpcszStorageSection)
Remarks: Set a section into an OriginObject's Info.
Parameters:
obj = the OriginObject to set the section into
trSection = the tree node containing the section
lpcszStorageSection = pointer to the storage and section name

Return values:
If success then true else false

Example:
        void Run_info_set_section()
        {
            Tree    trSection;
            trSection.user.var.nVal = 1;

            Page pg("Data1");
            bool bRet = info_set_section(pg, trSection, "user.var");
        }

Summary:
Sample data:
Header file: page_utils.h
See also:


page_get_info_var_value

Function: page_get_info_var_value
Prototype:
bool page_get_info_var_value(Page& pg, LPCSTR lpcszVarName, string& strVal, LPCSTR lpcszStorageSection=NULL)
Remarks: Get the value of a variable in a Page's Info section
Parameters:
pg = the page to get the value from
lpcszVarName = pointer to the name of the variable
strVal = the string to receive the value
lpcszInfo = pointer to the name of the section.  If NULL then the Variables section is used.

Return values:
If success then true else false

Example:
        void Run_page_get_info_var_value()
        {
            string 	strVal;
            Page pg("Data1");
            bool bRet = page_get_info_var_value(pg,"var",strVal,"user.var");
        }

Summary:
Sample data:
Header file: page_utils.h
See also:
Function: page_get_info_var_value
Prototype:
bool page_get_info_var_value(Page& pg, LPCSTR lpcszVarName, double& dVal, LPCSTR lpcszStorageSection=NULL)
Remarks: Get the value of a variable in a Page's Info section
Parameters:
pg = the page to get the value from
lpcszVarName = pointer to the name of the variable
dVal = the double to receive the value
lpcszInfo = pointer to the name of the section.  If NULL then the Variables section is used.

Return values:
If success then true else false

Example:
        void Run_page_get_info_var_value()
        {
            double 	dVal;
            Page pg("Data1");
            bool bRet = page_get_info_var_value(pg,"var",dVal,"user.var");
        }

Summary:
Sample data:
Header file: page_utils.h
See also:


page_get_storage_str

Function: page_get_storage_str
Prototype:
bool page_get_storage_str(Page& pg, LPCSTR lpcszName, string &strValue)
Remarks: Get a binary storage from a page into a string.
Parameters:
pg = the page containing the binary storage
lpcszName = pointer to the name of the binary storage
strVal = the string to receive the value

Return values:
If success then true else false

Example:
        void  Run_page_get_storage_str()
        {
            Page pg("Data1");
            string strName = "var";
            string strVal;
            bool bRet = page_get_storage_str(pg,strName,strVal);
            out_str(strVal);
        }

Summary:
Sample data:
Header file: page_utils.h
See also:


page_set_info_var_value

Function: page_set_info_var_value
Prototype:
bool page_set_info_var_value(Page& pg, LPCSTR lpcszVarName, LPCSTR lpcszVarVal, LPCSTR lpcszStorageSection=NULL)
Remarks: Set the value of a variable in a Page's Info section
Parameters:
pg = the page containing the variable to set
lpcszVarName = pointer to the name of the variable
lpcszVarVal = pointer to the string value
lpcszInfo = pointer to the name of the section.  If NULL then the Variables section is used.

Return values:
If success then true else false

Example:
        void Run_page_set_info_var_value()
        {
            Page pg("Data1");
            bool bRet = page_set_info_var_value(pg,"var","abc","user.var");
        }

Summary:
Sample data:
Header file: page_utils.h
See also:
Function: page_set_info_var_value
Prototype:
bool page_set_info_var_value(Page& pg, LPCSTR lpcszVarName, double dVal, LPCSTR lpcszStorageSection=NULL)
Remarks: Set the value of a variable in a Page's Info section
Parameters:
pg = the page containing the variable to set
lpcszVarName = pointer to the name of the variable
lpcszVarVal = pointer to the string value
lpcszInfo = pointer to the name of the section.  If NULL then the Variables section is used.

Return values:
If success then true else false

Example:
        void Run_page_set_info_var_value()
        {
            Page pg("Data1");
            bool bRet = page_set_info_var_value(pg,"var",12.25,"user.var");
        }

Summary:
Sample data:
Header file: page_utils.h
See also:


page_set_storage_str

Function: page_set_storage_str
Prototype:
bool page_set_storage_str(Page& pg, LPCSTR lpcszName, LPCSTR lpcstrValue)
Remarks: Set a string into a page as a binary storage
Parameters:
pg = the page to contain the binary storage
lpcszName = pointer to the name of the binary storage
lpcszVarVal = pointer to the string value

Return values:
If success then true else false

Example:
        void  Run_page_set_storage_str()
        {
            Page pg("Data1");
            string strName = "var";
            string strVal = "Testing";
            bool bRet = page_set_storage_str(pg,strName,strVal);
        }

Summary:
Sample data:
Header file: page_utils.h
See also:


GetROI

Function: GetROI
Prototype:
ROIObject GetROI()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: graph.h
See also:


LT_evaluate

Function: LT_evaluate
Prototype:
BOOL LT_evaluate(LPCSTR lpcszLabTalkExpression, double * lpdbResult)
Remarks: Evaluate an expression in LabTalk syntax.
Parameters:
lpcszLabTalkExpression = Pointer to a string containing the expression in LabTalk syntax.
lpdbResult = Pointer to a double value to receive the results.

Return values:
TRUE if expression is valid, FALSE if expression leads to missing value

Example:
        void	run_LT_evaluate()
        {
            double		vv;
            LT_get_var("@D",&vv); // get machine curremt date/time as Julian value
            out_double("@D = ", vv);
            LT_evaluate("0^0",&vv); // evaluate expression using LabTalk interpreter
            out_double("0^0 = ", vv);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


LT_execute

Function: LT_execute
Prototype:
BOOL LT_execute(LPCSTR lpcszLabTalkStr, int wCntrl = 0)
Remarks: Execute LabTalk script code.
Parameters:
lpcszLabTalkStr = Pointer to a string containing the LabTalk script code to execute.
wCntrl = not used (must be 0)

Return values:
TRUE if success, FALSE if LabTalk execution leads to error

Example:
        void	run_LT_execute()
        {
            // Execute the LabTalk script which will bring up a message box and display
            // the value of the system string %Y:
            LT_execute("type -b %Y");
        }

Summary:
Sample data:
Header file: utilities.h
See also:


LT_get_str

Function: LT_get_str
Prototype:
BOOL LT_get_str(LPCSTR lpcszLabTalkString, char* pBuffer, int nBufferSize)
Remarks: lstrcpyn is used inside Origin to copy LabTalk string into the buffer supplied, so that if the buffer is too small, the result string will have one less character than specified to leave room for the terminating character.
Parameters:
lpcszLabTalkString = LabTalk global string, or any other LabTalk string expression
pBuffer = character buffer to receive the string
nBufferSize = size of the buffer including the terminating zero

Return values:
Return TRUE if success, return FALSE if string variable is not correctly specified or string is
too long.

Example:
        void	run_LT_get_str()
        {
            char	szBuffer[200];
            // Get the value of the string variable %Y (it usually contains the
            // Origin's client path)
            LT_get_str("%Y", szBuffer, 200);
            out_str(szBuffer);
        }

Summary: Get LabTalk string
Sample data:
Header file: utilities.h
See also:


LT_get_var

Function: LT_get_var
Prototype:
BOOL LT_get_var(LPCSTR lpcszLabTalkVarName, double * lpdbResult)
Remarks: You can use this command to get LabTalk variables, including system variables whose names begin with @ This command is similar to LT_evaluate but you can tell if given name corresponds to a LabTalk variable even if its value is missing value, while LT_evaluate will not be able to differentiate. Also, using LT_evaluate to get value of a variable is slower.
Parameters:
lpcszLabTalkVarName = LabTalk variable name, case insensitive
lpdbResult = the double variable pointed to by lpdbResult recieves the LabTalk variable value

Return values:
TRUE if lpcszLabTalkVarName is a LabTalk variable, and FALSE if it is not

Example:
        void	run_LT_get_var()
        {
            double vv;
            LT_get_var("X2", &vv); // get the current X axis right limit (the variable "X2")
            out_double("vv = ", vv);
            LT_get_var("@D",&vv); // get machine curremt date/time as Julian value (the system variable @D)
            out_double("vv = ", vv);
            if(LT_get_var("XYZ", &vv))	// try to get the value of the variable "XYZ"
                printf("in LabTalk, XYZ = %lf\n", vv);
            else
                out_str("XYZ is not a LabTalk variable");
        }

Summary: Get LabTalk variable value
Sample data:
Header file: utilities.h
See also:


LT_set_str

Function: LT_set_str
Prototype:
BOOL LT_set_str(LPCSTR lpcszVar, LPCSTR lpcszContent)
Remarks: Sets the value of a LabTalk global string variable or a LabTalk object string property.
Parameters:
lpcszVar = Origin string variables, %A through %Z, as well as LabTalk Object string properties
lpcszContent = string content to be copied to Origin string variable, can be NULL to empty a string

Return values:
Return TRUE if success, return FALSE if string variable is not correctly specified or string is
too long.

Example:
        void	run_LT_set_str()
        {
            char	szBuffer[200];
            // Get the value of the string variable %L
            LT_get_str("%L", szBuffer, 200);

            // Display the value:
            out_str(szBuffer);

            // Now set it to a new value:
            LT_set_str("%L", "New string value!");
            // Get the value of the string variable %L
            LT_get_str("%L", szBuffer, 200);

            // Display the value:
            out_str(szBuffer);
        }

Summary: Set LabTalk string variable
Sample data:
Header file: utilities.h
See also:


LT_set_var

Function: LT_set_var
Prototype:
BOOL LT_set_var(LPCSTR lpcszLabTalkVarName, double dbValue)
Remarks: It sets the value of a LabTalk variable
Parameters:
lpcszLabTalkVarName = LabTalk variable name, case insensitive
dbValue = the new value

Return values:
TRUE if OK, and FALSE if it fails.

Example:
        void	run_LT_set_var()
        {
            double vv;
            if(LT_get_var("X", &vv))
            {
                vv += 10;
                // Set the new value:
                if(LT_set_var("X", vv))
                    out_str("set X in LabTalk succeeded");
                else
                    out_str("set X in LabTalk failed");

                LT_get_var("X", &vv);
                out_double("new value is ", vv);
            }
        }

Summary: Set LabTalk variable value
Sample data:
Header file: utilities.h
See also:


_hypot

Function: _hypot
Prototype:
double _hypot(double x, double y)
Remarks: Calculates the hypotenuse (the longest side) of a right triangle given the two sides of the right angle
Parameters:
x, y = two sides of the right angle of a right triangle

Return values:
hypotenuse

Example:
        void	run_hypot()
        {
            double		x = 3., y = 4.;
            double		val = _hypot(x, y);

            printf("_hypot(%f, %f) = %f\n", x, y, val);	// the result should be 5.
        }

Summary:
Sample data:
Header file: math.h
See also:


_j0

Function: _j0
Prototype:
double _j0(double x)
Remarks: Compute the Bessel function. The _j0, _j1, and _jn routines return Bessel functions of the first kind: orders 0, 1, and n, respectively.
Parameters:
x	Floating-point value

Return values:
The _j0 returns a Bessel function of x.

Example:
        This program illustrates Bessel functions.

        #include <origin.h>

        int test_J0()
        {
            double vv;

            vv = _j0( 0 );
            out_double( "_j0(0)=", vv );				//output should be _j0(0)=1
            ASSERT( is_equal(vv, 1) );

            vv = _j0(1.3);
            out_double( "_j0(1.3)=", vv );
            ASSERT( is_equal(round(vv,5), 0.62009) );	//output should be _j0(1.3)=0.62009
            ASSERT( is_equal(_j0(-2), _j0(2)) );

            return 1;
        }

Summary:
Sample data:
Header file: msmath.h
See also:


_j1

Function: _j1
Prototype:
double _j1(double x)
Remarks: Compute the Bessel function. The _j0, _j1, and _jn routines return Bessel functions of the first kind: orders 0, 1, and n, respectively.
Parameters:
x	Floating-point value

Return values:
The _j1 returns a Bessel function of x.

Example:
        This program illustrates Bessel functions.

        #include <origin.h>

        int test_J1()
        {
            double vv;

            vv = _j1( 0 );
            out_double( "_j1(0)=", vv );			//output should be _j1(0)=0
            ASSERT( is_equal(vv, 0) );

            vv = _j1(1.3);
            out_double( "_j1(1.3)=", vv );		    //output should be _j1(1.3)=0.52202
            ASSERT( is_equal(round(vv,5), 0.52202) );

            out_double( "_j1(2)=", _j1(2) );		//output should be _j1(2)=0.57672

            out_double( "_j1(-2)=", _j1(-2) );	    //output should be _j1(-2)=-0.57672
            ASSERT( is_equal(_j1(-2), -_j1(2)) );

            return 1;
        }

Summary:
Sample data:
Header file: msmath.h
See also:


_jn

Function: _jn
Prototype:
double _jn(int n, double x)
Remarks: Compute the Bessel function. The _j0, _j1, and _jn routines return Bessel functions of the first kind: orders 0, 1, and n, respectively.
Parameters:
x	Floating-point value
n	Integer order of Bessel function

Return values:
The _jn returns a Bessel function of x.

Example:
        This program illustrates Bessel functions.

        #include <origin.h>

        int test_Jn()
        {
            double vv;

            vv = _jn( 1,1 );
            out_double("_jn(1,1)=", vv);			//output should be _jn(1,1)=0.44005
            ASSERT( is_equal( round(vv, 5), 0.44005) );

            vv = _jn( 0,0 );
            out_double("_jn(0,0)=", vv);			//output should be _jn(0,0)=1
            ASSERT( is_equal(vv, 1) );

            vv = _jn(2,3.5);
            out_double("_jn(2,3.5)=", vv);		    //output should be _jn(2,3.5)=0.45863
            ASSERT( is_equal(round(vv,5), 0.45863) );

            return 1;
        }

Summary:
Sample data:
Header file: msmath.h
See also:


_y0

Function: _y0
Prototype:
double _y0(double x)
Remarks: Compute the Bessel function. The _y0, _y1, and _yn routines return Bessel functions of the second kind: orders 0, 1, and n, respectively.
Parameters:
x	Floating-point value

Return values:
The _y0 returns a Bessel function of x.

Example:
        This program illustrates Bessel functions.

        #include <origin.h>

        int test_Y0()
        {
            double vv;

            vv = _y0(0);
            out_double( "_y0(0)=", vv ); 		//output should be _y0(0)=--
            ASSERT( is_equal(vv, NANUM) );

            vv= _y0(11);
            out_double( "_y0(11)=", vv );		//output should be _y0(11)=-0.16885
            ASSERT( is_equal(round(vv, 5), -0.16885) );

            return 1;
        }

Summary:
Sample data:
Header file: msmath.h
See also:


_y1

Function: _y1
Prototype:
double _y1(double x)
Remarks: Compute the Bessel function. The _y0, _y1, and _yn routines return Bessel functions of the second kind: orders 0, 1, and n, respectively.
Parameters:
x	Floating-point value

Return values:
The _y1 returns a Bessel function of x.

Example:
        This program illustrates Bessel functions.

        #include <origin.h>

        int test_Y1()
        {
            double vv;

            vv = _y1(0);
            out_double( "_y1(0)=", vv );	    //output should be _y1(0)=--
            ASSERT( is_equal(vv, NANUM) );

            vv= _y1(11);
            out_double( "_y1(11)=", vv );		//output should be _y1(11)=0.16371
            ASSERT( is_equal(round(vv, 5), 0.16371) );

            return 1;
        }

Summary:
Sample data:
Header file: msmath.h
See also:


_yn

Function: _yn
Prototype:
double _yn(int n, double x)
Remarks: Compute the Bessel function. The _y0, _y1, and _yn routines return Bessel functions of the second kind: orders 0, 1, and n, respectively.
Parameters:
x	Floating-point value
n	Integer order of Bessel function

Return values:
The _yn returns a Bessel function of x.

Example:
        This program illustrates Bessel functions.

        #include <origin.h>

        int test_Yn()
        {
            double vv;

            vv = _yn( 0,0 );
            out_double("_yn(0,0)=", vv);			//output should be _yn(0,0)=--
            ASSERT( is_equal(vv, NANUM) );

            vv = _yn( 1,1 );
            out_double("_yn(1,1)=", vv);			//output should be _yn(1,1)=-0.78121
            ASSERT( is_equal(round(vv, 5), -0.78121) );

            return 1;
        }

Summary:
Sample data:
Header file: msmath.h
See also:


abs

Function: abs
Prototype:
double abs(double x)
Remarks: Absolute value of a floating-point (double). This function is implemented in internal.c as a compatibility function for the labtalk version of abs(x) function. Please note that this function will simply call the fabs(x) function
Parameters:
x=Input value whose absolute value is returned

Return values:
Returns the absolute value of x.

Example:
        void	run_abs()
        {
            double		x = -5.9;
            double		val = abs(x);

            printf("abs(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also: fabs
Function: abs
Prototype:
int abs(int n)
Remarks: Absolute value (for integers). Note that this built-in C library abs function returns an int while the LabTalk abs function returns a double. The standard C library function fabs should typically used for doubles. To making it easier for Origin users, especially in defining fitting functions, an Origin C version of abs(double) has been added into internal.c, which is compiled automatically on Origin startup.
Parameters:
n=Integer value whose absolute value is returned

Return values:
Returns the absolute value of an integer.

Example:
        // This program computes and displays the absolute values of several numbers.
        #include <origin.h>
        int test_abs()
        {
            int nn;
            nn = abs( 0 );
            out_int("abs(0)=", nn);		//output should be abs(0)=0
            ASSERT( nn == 0 );
            nn = abs( -9 );
            out_int("abs(-9)=", nn);	//output should be abs(-9)=9
            ASSERT( nn == 9 );
            nn = abs( 200 );
            out_int("abs(200)=", nn);	//output should be abs(200)=200
            ASSERT( nn == 200 );
            nn = abs( -3.5 );
            out_int("abs(-3.5)=", nn);	//output should be abs(-3.5)=3
            ASSERT( nn == 3 );
            return 1;
        }

Summary: Returns the absolute value of an integer.
Sample data:
Header file: msmath.h
See also: fabs


acos

Function: acos
Prototype:
double acos(double x)
Remarks: Calculate the arccosine.
Parameters:
x = independent variable

Return values:
acos(x)

Example:
        void	run_acos()
        {
            double		x = -1.;
            double		val = acos(x);

            printf("acos(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


angle

Function: angle
Prototype:
double angle( double x, double y)
Remarks: Returns the phase (angle) in radians of a planar vector with coordinates (x, y)
Parameters:
x = x-coordinate
y = y-coordinate

Return values:
the phase (angle)

Example:
        void	run_angle()
        {
            double		x = 1.;
            double		y = 1.;
            double		rAngle = angle(x, y);
            printf("angle(%f, %f) = %f\n", x, y, rAngle);
        }

Summary:
Sample data:
Header file: math.h
See also:


asin

Function: asin
Prototype:
double asin(double x)
Remarks: Calculate the arcsine.
Parameters:
x = independent variable

Return values:
asin(x)

Example:
        void	run_asin()
        {
            double		x = -1.;
            double		val = asin(x);

            printf("asin(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


atan

Function: atan
Prototype:
double atan(double x)
Remarks: Calculates the arctangent of x.
Parameters:
Any numbers.

Return values:
The atan function returns the arctangent of x.

Example:
        This program computes and displays the arctangent of x.

        #include <origin.h>

        int test_atan()
        {
            double vv;
            vv = atan(1);
            out_double("atan(1)=", vv);		//output should be atan(1)=0.7854
            ASSERT( is_equal(vv, PI/4) );
            vv = atan(0);
            out_double("atan(0)=", vv);		//output should be atan(0)=0
            ASSERT( is_equal(vv, 0) );
            vv = atan(-1);
            out_double("atan(-1)=", vv);	//output should be atan(-1)=-0.7854
            ASSERT( is_equal(vv, -PI/4) );

            return 1;
        }

Summary:
Sample data:
Header file: msmath.h
See also:


atan2

Function: atan2
Prototype:
double atan2(double y, double x)
Remarks: Calculates the arctangent of y/x.
Parameters:
Any numbers.

Return values:
The atan2 function returns the arctangent of y/x.

Example:
        This program computes and displays the arctangent of y/x.

        #include <origin.h>

        int test_atan2()
        {
            double vv;
            vv = atan2(2.5,2.5);
            out_double("atan2(2.5,2.5)=", vv);		//output should be atan2(2.5,2.5)=0.7854
            ASSERT( is_equal(vv, PI/4) );
            vv = atan2(0,0);
            out_double("atan2(0,0)=", vv);			//output should be atan2(0,0)=0
            ASSERT( is_equal(vv, 0) );
            vv = atan2(0,180000);
            out_double("atan2(0,180000)=", vv);		//output should be atan2(0,180000)=0
            ASSERT( is_equal(vv, 0) );
            vv = atan2(0.0000023, 0);
            out_double("atan2(0.0000023, 0)=", vv);	//output should be atan2(0.0000023, 0)=1.5708
            ASSERT( is_equal(vv, PI/2) );
            vv = atan2(-1234567,-2345677);
            out_double("atan2(-1234567,-2345677)=", vv);	//output should be atan2(-1234567,-2345677)=-2.65711
            ASSERT( is_equal(round(vv, 5), -2.65711) );

            return 1;
        }

Summary:
Sample data:
Header file: msmath.h
See also:


beta

Function: beta
Prototype:
double beta( double a, double b )
Remarks: computes the beta function
Parameters:
a, b are standard arguments of beta function

Return values:
beta function of a, b

Example:
        void	run_beta()
        {
            double	a = 2, b = 4.;
            double	val = beta(a, b);
            printf("beta(%f, %f) = %f\n", a, b, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


ceil

Function: ceil
Prototype:
double ceil( double x )
Remarks: Calculates the double value corresponding to the smallest integer that is greater than or equal to x.
Parameters:
x = independent variable

Return values:
ceil(x)

Example:
        void	run_ceil()
        {
            double	x1 = -4.6, x2 = 4.6;

            printf("ceil(%f) = %f\nceil(%f) = %f\n", x1, ceil(x1), x2, ceil(x2));
        }

Summary:
Sample data:
Header file: math.h
See also:


cosh

Function: cosh
Prototype:
double cosh(double x)
Remarks: Calculates hyperbolic cosine.
Parameters:
x = independent variable

Return values:
cosh(x)

Example:
        void	run_cosh()
        {
            double		x = 2.;
            double		val = cosh(x);
            printf("cosh(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


fabs

Function: fabs
Prototype:
double fabs(double x)
Remarks: Absolute value of a floating-point (double).
Parameters:
x=Input value whose absolute value is returned

Return values:
Returns the absolute value of x.

Example:
        void	run_fabs()
        {
            double		x = -5.9;
            double		val = fabs(x);

            printf("fabs(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also: abs


floor

Function: floor
Prototype:
double floor( double x )
Remarks: Calculates the double value corresponding to the largest integer that is less than or equal to x.
Parameters:
x = independent variable

Return values:
floor(x)

Example:
        void	run_floor()
        {
            double	x1 = -4.6, x2 = 4.6;

            printf("floor(%f) = %f\nfloor(%f) = %f\n", x1, floor(x1), x2, floor(x2));
        }

Summary:
Sample data:
Header file: math.h
See also:


gammaln

Function: gammaln
Prototype:
double gammaln( double x )
Remarks: This function returns the natural logarithm of the gamma function.
Parameters:
x = the double value

Return values:
the natural logarithm of the gamma function of x.

Example:
        void	run_gammaln()
        {
            double		x = 17.;
            double		val = gammaln(x);
            printf("gammaln(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


get_missing_value

Function: get_missing_value
Prototype:
double get_missing_value(int nOption =0)
Remarks: Used to get the missing value as a value recognized by Origin.
Parameters:
nOption = (optional) not used, must be 0

Return values:
the missing value as a double value recognized by Origin.

Example:
        void	run_get_missing_value()
        {
            // Deliberately generate a missing value:
            double		rr = 7./0.;

            if (get_missing_value() == rr)
                out_str("Missing value!");
            else
                out_str("Not missing value");
        }

Summary:
Sample data:
Header file: math.h
See also:


grnd

Function: grnd
Prototype:
double grnd(int nSeed=0)
Remarks: On every call it generates a normally distributed random double value with mean = 0. and standard deviation = 1.
Parameters:
nSeed = (optional) pass any nonzero value to set the seed for random number generation, or 0
to use the current seed.

Return values:
A normally distributed random number.

Example:
        // The example displays 10 normally distributes random numbers with mean=0 and
        // standard deviation = 1.
        void	run_grnd()
        {
            for (int ii = 0; ii < 10; ii++)
            {
                double	rr = grnd();
                out_double("value = ", rr);
            }
        }

Summary: normally distributed random number with mean=0 and sd=1, nSeed > 0 to set random seed (returns 0)
Sample data:
Header file: math.h
See also:


incbeta

Function: incbeta
Prototype:
double incbeta( double x, double a, double b )
Remarks: Computes the incomplete beta function.
Parameters:
x, a, b are standard arguments of incomplete beta function

Return values:
incomplete beta function of x, a, b

Example:
        void	run_incbeta()
        {
            double	x = 0.5., a = 3, b = 5.;
            double	val = incbeta(x, a, b);
            printf("incomplete beta(%f, %f, %f) = %f\n", x, a, b, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


incgamma

Function: incgamma
Prototype:
double incgamma( double x, double a )
Remarks: computes the incomplete gamma function.
Parameters:
x, a are standard arguments of incomplete gamma function

Return values:
incomplete gamma function of x, a

Example:
        void	run_incgamma()
        {
            double	a = 2, x = .5;
            double	val = incgamma(x, a);
            printf("incgamma(%f, %f) = %f\n", x, a, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


is_equal

Function: is_equal
Prototype:
BOOL is_equal(double x, double y, int nCode='=')
Remarks: compare two double values and see if they are equal or not equal in the same sense as in LabTalk. This function uses the LabTalk system variable @ND to test if (abs(x)-abs(y))/((abs(x)+abs(y)) is less then @ND or not. If @ND = 0, it does standard arithmetic comparison x == y.
Parameters:
nCode = '=' for testing for equality; any other value will test for inequality.

Return values:

Example:
        void	run_is_equal()
        {
            double		a = 1.;

            // add 1.e-17:
            a += 1.e-17;

            // Compare with 1.:
            if (is_equal(a, 1.))
            {
                // If @ND still has the default value, which is 1.e-16, this will be true.
                out_str("a is 1.");
            }
            else
            {
                out_str("a is not 1.");
            }

            // add 1.e-14
            a += 1.e-14;
            if (is_equal(a, 1.))
            {
                // If @ND still has the default value, which is 1.e-16, this will be false.
                out_str("a is 1.");
            }
            else
            {
                out_str("a is not 1.");
            }
        }

Summary:
Sample data:
Header file: math.h
See also:


is_missing_value

Function: is_missing_value
Prototype:
BOOL is_missing_value(double x)
Remarks: Test given double value to determine whether it is a missing value recorgnized by Origin
Parameters:
x = the double value to test

Return values:
TRUE if missing value, otherwise FALSE.

Example:
        void	run_is_missing_value()
        {
            // Deliberately generate a missing value:
            double		rr = 7./0.;

            if (is_missing_value(rr))
                out_str("Missing value!");
            else
                out_str("Not missing value");
        }

Summary: return TRUE if given value is a missing value
Sample data:
Header file: math.h
See also:


is_numeric

Function: is_numeric
Prototype:
BOOL is_numeric(LPCSTR lpcstr, BOOL bThousoudSeparatorOK = TRUE, BOOL bLeadZeroOK = TRUE)
Remarks: Test given string to determine whether it is a numeric string
Parameters:
lpcstr = the alpha numeric string to test
bThousoudSeparatorOK = to decide if thousand's separator can be used, like 1,234,567
bLeadZeroOK = to decide if 01060 is a number (TRUE) or it should be considered not a number (bLeadZeroOK=FALSE)

Return values:
TRUE if given string is numeric, otherwise FALSE.

Example:
        double	convert_str_to_num(string str)
        {
            if (is_numeric(str))
                return atof(str);
            else
                return NANUM;
        }

Summary:
Sample data:
Header file: math.h
See also:


J0

Function: J0
Prototype:
double J0( double x )
Remarks: Compute the Bessel function of the first kind of order 0.
Parameters:
x = independent variable

Return values:
J0(x)

Example:
        void	run_J0()
        {
            double		x = 4.;
            double		val = J0(x);

            printf("J0(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


J1

Function: J1
Prototype:
double J1( double x )
Remarks: Compute the Bessel function of the first kind of order 1.
Parameters:
x = independent variable

Return values:
J1(x)

Example:
        void	run_J1()
        {
            double		x = 4.;
            double		val = J1(x);

            printf("J1(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


Jn

Function: Jn
Prototype:
double Jn( double x, int n )
Remarks: Compute the Bessel function of the first kind of order n.
Parameters:
x = independent variable
n = order

Return values:
Jn(x)

Example:
        void	run_Jn()
        {
            double		x = 4.;
            int			n = 2;
            double		val = Jn(x, n);

            printf("Jn(%f, %d) = %f\n", x, n, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


ln

Function: ln
Prototype:
double ln(double x)
Remarks: Natural logarithm, same as log(x)
Parameters:
x = independent variable

Return values:
ln(x)

Example:
        void	run_ln()
        {
            double		x = 123.;
            double		val = ln(x);

            printf("ln(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also: log log10


log10

Function: log10
Prototype:
double log10(double x)
Remarks: logarithm of base 10
Parameters:
x = independent variable

Return values:
log10(x)

Example:
        void	run_log10()
        {
            double		x = 10000.;
            double		val = log10(x);

            printf("log10(%f) = %f\n", x, val);
        }

Summary: log base 10; see log or ln functions for log base e
Sample data:
Header file: math.h
See also: ln log


max

Function: max
Prototype:
double max(Dataset &ds)
Remarks: Get the maximum value of a data set.
Parameters:
ds=Input Origin C Dataset object

Return values:
Returns the maximum value of a data set.

Example:
        // Assumes Data1_A exists and contains data
        Dataset dsA("Data1_A");
        double dMax = max(dsA);
        printf("Maximum value of Data1_A is %g", dMax);

Summary: Get the maximum value of a data set.
Sample data:
Header file: data.h
See also: min
Function: max
Prototype:
double max(double da, double db)
Remarks: Returns the larger of two doubles.
Parameters:
da, db = the two double values whose maximum is sought

Return values:
the greater of the two values supplied

Example:
        void	run_max()
        {
            double		r1 = 7., r2 = 9.;

            double		rmax = max(r1, r2);

            printf("max of %f and %f is %f\n", r1, r2, rmax);
        }

Summary:
Sample data:
Header file: math.h
See also:
Function: max
Prototype:
float max(float fa, float fb)
Remarks: Returns the larger of two floats.
Parameters:
fa, fb = the two float values whose maximum is sought

Return values:
the greater of the two values supplied

Example:
        void	run_max()
        {
            float		r1 = 7., r2 = 9.;

            float		rmax = max(r1, r2);

            printf("max of %f and %f is %f\n", r1, r2, rmax);
        }

Summary:
Sample data:
Header file: math.h
See also:
Function: max
Prototype:
int max(int ia, int ib)
Remarks: Returns the larger of two ints.
Parameters:
ia, ib = the two integer values whose maximum is sought

Return values:
the greater of the two values supplied

Example:
        void	run_max()
        {
            int		n1 = 7, n2 = 9;

            int		nmax = max(n1, n2);

            printf("max of %d and %d is %d\n", n1, n2, nmax);
        }

Summary:
Sample data:
Header file: math.h
See also:
Function: max
Prototype:
uint max(uint na, uint nb)
Remarks: Returns the larger of two uints.
Parameters:
na, nb = the two unsigned integer values whose maximum is sought

Return values:
the greater of the two values supplied

Example:
        void	run_max()
        {
            uint		n1 = 7, n2 = 9;

            uint		nmax = max(n1, n2);

            printf("max of %d and %d is %d\n", n1, n2, nmax);
        }

Summary:
Sample data:
Header file: math.h
See also:
Function: max
Prototype:
short max(short na, short nb)
Remarks: Returns the larger of two shorts.
Parameters:
na, nb = the two short values whose maximum is sought

Return values:
the greater of the two values supplied

Example:
        void	run_max()
        {
            short	n1 = 7, n2 = 9;

            short	nmax = max(n1, n2);

            printf("max of %d and %d is %d\n", n1, n2, nmax);
        }

Summary:
Sample data:
Header file: math.h
See also:
Function: max
Prototype:
ushort max(ushort wa, ushort wb)
Remarks: Returns the larger of two ushorts.
Parameters:
wa, wb = the two unsigned short values whose maximum is sought

Return values:
the greater of the two values supplied

Example:
        void	run_max()
        {
            short	n1 = 7, n2 = 9;

            short	nmax = max(n1, n2);

            printf("max of %d and %d is %d\n", n1, n2, nmax);
        }

Summary:
Sample data:
Header file: math.h
See also:


min

Function: min
Prototype:
double min(Dataset &ds)
Remarks: Get the minimum value of a data set.
Parameters:
ds=Input Origin C Dataset object

Return values:
Returns the minimum value of a data set.

Example:
        // Assumes Data1_A exists and contains data
        Dataset dsA("Data1_A");
        double dMin = min(dsA);
        printf("Minimum value of Data1_A is %g", dMin);

Summary: Get the minimum value of a data set.
Sample data:
Header file: data.h
See also: max
Function: min
Prototype:
double min(double da, double db)
Remarks: Returns the smaller of two doubles.
Parameters:
da, db = the two double values whose minimum is sought

Return values:
the smaller of the two values supplied

Example:
        void	run_min()
        {
            double		r1 = 7., r2 = 9.;

            double		rmin = min(r1, r2);

            printf("min of %f and %f is %f\n", r1, r2, rmin);
        }

Summary:
Sample data:
Header file: math.h
See also:
Function: min
Prototype:
float min(float fa, float fb)
Remarks: Returns the smaller of two floats.
Parameters:
fa, fb = the two float values whose minimum is sought

Return values:
the smaller of the two values supplied

Example:
        void	run_min()
        {
            float		r1 = 7., r2 = 9.;

            float		rmin = min(r1, r2);

            printf("min of %f and %f is %f\n", r1, r2, rmin);
        }

Summary:
Sample data:
Header file: math.h
See also:
Function: min
Prototype:
int min(int ia, int ib)
Remarks: Returns the smaller of two ints.
Parameters:
ia, ib = the two integer values whose minimum is sought

Return values:
the smaller of the two values supplied

Example:
        void	run_min()
        {
            int			n1 = 7, n2 = 9;

            int			nmin = min(n1, n2);

            printf("min of %d and %d is %d\n", n1, n2, nmin);
        }

Summary:
Sample data:
Header file: math.h
See also:
Function: min
Prototype:
uint min(uint na, uint nb)
Remarks: Returns the smaller of two uints.
Parameters:
na, nb = the two unsigned integer values whose minimum is sought

Return values:
the smaller of the two values supplied

Example:
        void	run_min()
        {
            uint		n1 = 7, n2 = 9;

            uint		nmin = min(n1, n2);

            printf("min of %d and %d is %d\n", n1, n2, nmin);
        }

Summary:
Sample data:
Header file: math.h
See also:
Function: min
Prototype:
short min(short na, short nb)
Remarks: Returns the smaller of two shorts.
Parameters:
na, nb = the two short values whose minimum is sought

Return values:
the smaller of the two values supplied

Example:
        void	run_min()
        {
            short			n1 = 7, n2 = 9;

            short			nmin = min(n1, n2);

            printf("min of %d and %d is %d\n", n1, n2, nmin);
        }

Summary:
Sample data:
Header file: math.h
See also:
Function: min
Prototype:
ushort min(ushort wa, ushort wb)
Remarks: Returns the smaller of two ushorts.
Parameters:
wa, wb = the two unsigned short values whose minimum is sought

Return values:
the smaller of the two values supplied

Example:
        void	run_min()
        {
            ushort			n1 = 7, n2 = 9;

            ushort			nmin = min(n1, n2);

            printf("min of %d and %d is %d\n", n1, n2, nmin);
        }

Summary:
Sample data:
Header file: math.h
See also:


mod

Function: mod
Prototype:
long mod( long x, long y )
Remarks: Divides x by y and returns the remainder.
Parameters:
x = dividend
y = divisor

Return values:
remainder of division of x by y

Example:
        void	run_mod()
        {
            int		m = 36, n = 10;
            int		nmod = mod(m, n);

            printf("mod(%d, %d) = %d\n", m, n, nmod);
        }

Summary:
Sample data:
Header file: math.h
See also:


nint

Function: nint
Prototype:
int nint( double x )
Remarks: Returns the closest int to the double argument.
Parameters:
x = double value the nearest integer to which is sought.

Return values:
the nearest integer to x

Example:
        void	run_nint()
        {
            double	r1 = 3.6;
            double	r2 = 3.4;

            printf("nearest integer to %f is %d\nnearest integer to %f is %d\n", r1, nint(r1), r2, nint(r2));
        }

Summary:
Sample data:
Header file: math.h
See also:


pow

Function: pow
Prototype:
double pow(double x, double y)
Remarks: Calculates x raised to the power of y.
Parameters:
x = base
y = exponent

Return values:
x to the power of y

Example:
        void run_pow( void )
        {
           double x = 2.0, y = 3.0, z;

           z = pow( x, y );
           printf( "%.1f to the power of %.1f is %.1f\n", x, y, z );
        }

        Output
        2.0 to the power of 3.0 is 8.0

Summary:
Sample data:
Header file: math.h
See also:


prec

Function: prec
Prototype:
double prec(double x, int nSignificantDigits)
Remarks: Calculates a double value which is equal to x up to nSignificantDigits significant digits
Parameters:
x = independent variable

Return values:
x with the precision of nSignificantDigits significant digits.

Example:
        void	run_prec()
        {
            double		x = 34.56789;
            int			nSignificantDigits = 5;

            printf("prec(%f, %d) = %f", x, nSignificantDigits, prec(x, nSignificantDigits));
        }

Summary:
Sample data:
Header file: math.h
See also:


rand

Function: rand
Prototype:
int rand()
Remarks: The rand function returns a pseudorandom integer in the range 0 to RAND_MAX.
Parameters:

Return values:
The rand returns a pseudorandom number.

Example:
        This program seeds the random-number generator.

        #include <origin.h>

        int test_rand()
        {
            int nn1, nn2;
            nn1 = rand();
            out_int("rand()=", nn1);
            nn2 = rand();
            out_int("rand()=", nn2);

            return 1;
        }

Summary:
Sample data:
Header file: msmath.h
See also:


rmod

Function: rmod
Prototype:
double rmod( double x, double y )
Remarks: Divides double x by double y and returns the remainder.
Parameters:
x = dividend
y = divisor

Return values:

Example:
        void	run_rmod()
        {
            double		x = 6.9, y = 2.1;
            double		val = rmod(x, y);
            printf("rmod(%f, %f) = %f\n", x, y, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


rnd

Function: rnd
Prototype:
double rnd(int nSeed=0)
Remarks: Also defined as ran(_nSeed). On every call it generates a random double value between 0. and 1.
Parameters:
nSeed = (optional) pass any nonzero value to set the seed for random number generation, or 0
to use the current seed.

Return values:
A uniformly random number between 0. and 1.

Example:
        // The example displays 10 random numbers between 0. and 1.
        void	run_rnd()
        {
            for (int ii = 0; ii < 10; ii++)
            {
                double	rr = rnd();
                out_double("value = ", rr);
            }
        }

Summary:
Sample data:
Header file: math.h
See also:


round

Function: round
Prototype:
double round( double x, int nDecimalPlaces )
Remarks: Calculates a double value which is equal to x up to nDecimalPlaces decimal places
Parameters:
x = independent variable

Return values:
x with nDecimalPlaces decimal places.

Example:
        void	run_round()
        {
            double		x = 34.56789;
            int			nDecimalPlaces = 3;

            printf("round(%f, %d) = %f", x, nDecimalPlaces, round(x, nDecimalPlaces));
        }

Summary: force given value to be nDecimalPlaces
Sample data:
Header file: math.h
See also:


sinh

Function: sinh
Prototype:
double sinh(double x)
Remarks: Calculates hyperbolic sine.
Parameters:
x = independent variable

Return values:
sinh(x)

Example:
        void	run_sinh()
        {
            double		x = 2.;
            double		val = sinh(x);
            printf("sinh(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


srand

Function: srand
Prototype:
void srand(unsigned int n)
Remarks: The srand function sets the starting point for generating a series of pseudorandom integers.
Parameters:
n 	a random starting point for random-number generation

Return values:
None.

Example:
        #include <origin.h>

        int test_srand()
        {
            int nn;
            srand(1);
            nn = rand();
            out_int("rand()=", nn);

            srand(1000);
            nn = rand();
            out_int("rand()=", nn);
            return 1;
        }

Summary:
Sample data:
Header file: msmath.h
See also:


tanh

Function: tanh
Prototype:
double tanh(double x)
Remarks: Calculate the hyperbolic tangent.
Parameters:
Angle in radians.

Return values:
The tanh returns the hyperbolic tangent of x.

Example:
        This program computes and displays the sines of x.

        #include <origin.h>

        int test_tanh()
        {
            double vv;
            vv = tanh(0);		//output should be tanh(0) =0
            out_double("tanh(0) =", vv);
            ASSERT( is_equal(vv, 0) );
            vv = tanh(4.567898);
            out_double("tanh(4.567898) =", vv);	//output should be tanh(4.567898) =0.99978
            ASSERT( is_equal(round(vv,5), 0.99978) );
            vv = tanh(-0.98765);
            out_double("tanh(-0.98765) =", vv);	//output should be tanh(-0.98765) =-0.75636
            ASSERT( is_equal(round(vv,5), -0.75636) );

            return 1;
        }

Summary:
Sample data:
Header file: msmath.h
See also:


Y0

Function: Y0
Prototype:
double Y0( double x )
Remarks: Compute the Bessel function of the second kind of order 0.
Parameters:
x = independent variable

Return values:
Y0(x)

Example:
        void	run_Y0()
        {
            double		x = 4.;
            double		val = Y0(x);

            printf("Y0(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


Y1

Function: Y1
Prototype:
double Y1( double x )
Remarks: Compute the Bessel function of the second kind of order 1.
Parameters:
x = independent variable

Return values:
Y1(x)

Example:
        void	run_Y1()
        {
            double		x = 4.;
            double		val = Y1(x);

            printf("Y1(%f) = %f\n", x, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


Yn

Function: Yn
Prototype:
double Yn( double x, int n)
Remarks: Compute the Bessel function of the second kind of order n.
Parameters:
x = independent variable
n = order

Return values:
Yn(x)

Example:
        void	run_Yn()
        {
            double		x = 4.;
            int			n = 2;
            double		val = Yn(x, n);

            printf("Yn(%f, %d) = %f\n", x, n, val);
        }

Summary:
Sample data:
Header file: math.h
See also:


ran

Function: ran
Prototype:
double ran(int nSeed = 0)
Remarks: This function is essentially the same as the rnd() function
Parameters:
nSeed = (optional) pass any nonzero value to set the seed for random number generation, or 0
to use the current seed.

Return values:
A uniformly random number between 0. and 1.

Example:
        // The example displays 10 random numbers between 0. and 1.
        void	run_rnd()
        {
            for (int ii = 0; ii < 10; ii++)
            {
                double	rr = ran();
                out_double("value = ", rr);
            }
        }

Summary:
Sample data:
Header file: sys_utils.h
See also:


GlobalAlloc

Function: GlobalAlloc
Prototype:
HGLOBAL WINAPI GlobalAlloc(UINT uFlags, DWORD dwBytes)
Remarks:
Parameters:
uFlags = Memory allocation attributes. If zero is specified, the default is GMEM_FIXED.
This parameter can be one or more of the following values, except for the incompatible combinations that are specifically noted.
dwBytes = Number of bytes to allocate. 	If this parameter is zero and the uFlags parameter specifies GMEM_MOVEABLE,
the function returns a handle to a memory object that is marked as discarded.

Return values:
If the function succeeds, the return value is a handle to the newly allocated memory object.
If the function fails, the return value is NULL.

Example:
        void Test_Global_Memory()
        {
            string 		strTemp = "Test GlobalAlloc!";
            int nMemSize = strTemp.GetLength() + 1;

            HANDLE hData = GlobalAlloc(GHND,nMemSize);
            if( !hData )
            {
                out_str("failed!");
                return;
            }

            DWORD	dSize = GlobalSize(hData);
            if( dSize != nMemSize )
            {
                out_str("failed!");
            }

            LPSTR lpData = (LPSTR)GlobalLock(hData);
            lstrcpyn(lpData, strTemp, nMemSize);
            GlobalUnlock(hData);

            if( NULL == GlobalReAlloc(hData, nMemSize*2, GMEM_MOVEABLE) )
            {
                out_str("failed");
                return;
            }
            else
            {
                if( nMemSize*2 != GlobalSize(hData))
                {
                    out_str("failed!");
                }
            }

            if( NULL != GlobalFree(hData) )
            {
                out_str("failed!");
            }
        }

Summary:
Sample data:
Header file: mswin.h
See also:


GlobalFree

Function: GlobalFree
Prototype:
HGLOBAL WINAPI GlobalFree(HGLOBAL hMem)
Remarks:
Parameters:
hMem = Handle to the global memory object.

Return values:
If the function succeeds, the return value is NULL.
If the function fails, the return value is equal to a handle to the global memory object.

Example:

Summary:
Sample data:
Header file: mswin.h
See also: GlobalAlloc


GlobalLock

Function: GlobalLock
Prototype:
LPVOID WINAPI GlobalLock(HGLOBAL hMem)
Remarks:
Parameters:
hMem = Handle to the global memory object.

Return values:
If the function succeeds, the return value is a pointer to the first byte of the memory block.
If the function fails, the return value is NULL.

Example:

Summary:
Sample data:
Header file: mswin.h
See also: GlobalAlloc


GlobalReAlloc

Function: GlobalReAlloc
Prototype:
HGLOBAL WINAPI GlobalReAlloc(HGLOBAL hMem, DWORD dwBytes, UINT uFlags)
Remarks:
Parameters:
hMem = Handle to the global memory object to be reallocated.
dwBytes = New size of the memory block, in bytes. If uFlags specifies GMEM_MODIFY, this parameter is ignored.
uFlags = Reallocation options.

Return values:
If the function succeeds, the return value is a handle to the reallocated memory object.
If the function fails, the return value is NULL.

Example:

Summary:
Sample data:
Header file: mswin.h
See also: GlobalAlloc


GlobalSize

Function: GlobalSize
Prototype:
DWORD WINAPI GlobalSize(HGLOBAL hMem)
Remarks:
Parameters:
hMem = Handle to the global memory object.

Return values:
If the function succeeds, the return value is the size of the specified global memory object, in bytes.

Example:

Summary:
Sample data:
Header file: mswin.h
See also: GlobalAlloc


GlobalUnlock

Function: GlobalUnlock
Prototype:
BOOL WINAPI GlobalUnlock(HGLOBAL hMem)
Remarks:
Parameters:
hMem = Handle to the global memory object.
Return values:
If the memory object is still locked after decrementing the lock count, the return value is a nonzero value.
If the function fails, the return value is zero.

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also: GlobalAlloc


calloc

Function: calloc
Prototype:
void * calloc(UINT nElements, UINT nSize)
Remarks: calloc function is used to allocate an array in memory with elements initialized to 0.
Parameters:
nElements = Number of elements
nSize = Length in bytes of each element

Return values:
returns a pointer to the allocated space, or NULL if there is insufficient memory available.

Example:
        void	run_calloc()
        {
            int			*pn;
            UINT		nNumerOfIntegersToAllocate = 200;
            pn = (int*)calloc(nNumerOfIntegersToAllocate, sizeof(int));
            if (pn != NULL)
                out_str("Allocation succesful");
            else
                out_str("Allocation failed!");

            // free the allocated memory:
            free(pn);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


free

Function: free
Prototype:
void free(void * pmem)
Remarks: Deallocates or frees a memory block that was allocated with malloc or calloc.
Parameters:
pmem = Previously allocated memory block to be freed.

Return values:
None.

Example:
        void	run_free()
        {
            char		*pstr;
            UINT		nNumerOfBytesToAllocate = 200;
            pstr = (char*)malloc(nNumerOfBytesToAllocate);
            if (pstr != NULL)
                out_str("Allocation succesful");
            else
                out_str("Allocation failed!");

            // free the allocated memory:
            free(pstr);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


GetHexDump

Function: GetHexDump
Prototype:
string GetHexDump(const LPVOID lpcMemory, int nSize, BOOL bAddGap=TRUE)
Remarks: Convert the given memory into a hex string with every byte represented by two hexidecimal characters.
Parameters:
lpcMemory = a memory pointer
nSize = size of the memory in bytes to convert
bAddGap = TRUE will add a space character between the hex characters

Return values:
the string for the hex dump.

Example:
        char szTemp[10] = "A\t\r\n";
        string strDump = GetHexDump(szTemp, 4);
        out_str(strDump);

Summary:
Sample data:
Header file: utilities.h
See also:


malloc

Function: malloc
Prototype:
void * malloc(UINT nBytes)
Remarks: Allocates a certain number of bytes on heap.
Parameters:
nBytes =  Bytes to allocate.

Return values:
Returns a void pointer to the allocated space, or NULL if there is insufficient memory available.

Example:
        void	run_malloc()
        {
            char		*pstr;
            UINT		nNumerOfBytesToAllocate = 200;
            pstr = (char*)malloc(nNumerOfBytesToAllocate);
            if (pstr != NULL)
                out_str("Allocation succesful");
            else
                out_str("Allocation failed!");

            // free the allocated memory:
            free(pstr);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


get_create_Note

Function: get_create_Note
Prototype:
bool get_create_Note(string &strNoteWnd)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: sys_utils.h
See also:


GetAppPath

Function: GetAppPath
Prototype:
string GetAppPath(BOOL bServerPath = FALSE)
Remarks: Get Origin's software path including the last '\\' character. Origin's program path is typically where Origin's EXE and DLL files are located. In a network version, this is typically a remove path on a server computer where the server version of Origin is installed. In a single user installation, this is always the location where Origin's EXE and DLL files are installed. Origin C system files are always installed inside the program path. Origin's User Files path is typically assigned by the user when running Origin for the first time. This is where all the files related to a particular customization of Origin is located. You will find origin.ini and other templates and CNF files in this location.
Parameters:
bServerPath = TRUE to get the Origin's program path and to FALSE to get the User Files path.

Return values:
A string containing the requested path.

Example:
        void	run_GetAppPath()
        {
            string strFile = GetAppPath(true) + "originc\\system\\wksheet.h";
            ASSERT(strFile.IsFile());  // system header should be installed only in program path
            strFile = GetAppPath(false) + "originc\\system\\wksheet.h";
            ASSERT(!strFile.IsFile()); // should not have this in user files path
            strFile = GetAppPath() + "origin.ini";
            ASSERT(strFile.IsFile());
        }

Summary:
Sample data:
Header file: utilities.h
See also:


GetFullPath

Function: GetFullPath
Prototype:
string GetFullPath(LPCSTR lpcszFileName, LPCSTR lpSubPath = NULL, BOOL bLocalized=FALSE)
Remarks: Seach Origin's client and then server path to return the full path name of the specified file This function will separately look for server and client path only if Origin is a network version. For single user version, this function will simply return the full path from Origin's software path
Parameters:
lpcszFileName = File name to search for.
lpSubPath = Optional subfolder of the Origin software path to search in.
bLocalized = TRUE if the given file can be localized so that we will need to first try the localization location first

Return values:
If the file was found then a string containing the full path file name is returned else an empty string is returned.

Example:
        void	run_GetFullPath()
        {
            string strFile = "origin.ini";
            string strFullPath = GetFullPath(strFile);
            if( !strFullPath.IsEmpty() )
            {
                string strPath = GetFilePath(strFullPath);
                printf("File %s was found in %s folder.\n", strFile, strPath);
            }
        }

Summary:
Sample data:
Header file: utilities.h
See also:


GetProjectAttachedFilesPath

Function: GetProjectAttachedFilesPath
Prototype:
string GetProjectAttachedFilesPath()
Remarks: get the path of the temp folder in which the OPJ attached files are placed.
Parameters:

Return values:
empty string is no such path

Example:
        #include <origin.h>

        void test()
        {
            string strPath;
            strPath = GetProjectAttachedFilesPath();
            if(strPath.IsEmpty())
                out_str("Not files attached to project");
            else
                out_str(strPath);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


gpage_get_plots

Function: gpage_get_plots
Prototype:
int gpage_get_plots(const GraphPage &pg, TreeNode &tr)
Remarks: Get Graphpage's DataPlots contents into a tree
Parameters:
pg = the Graph page to get the contents from
tr = Tree to retrive the contents

Return values:
If success then return the plot type for the next added plot, or return 0 if error

Example:
        void Run_gpage_get_plots()
        {
            Tree tr;
            GraphPage gp("graph1");
            int nRet = gpage_get_plots(gp,tr);
            out_tree(tr);
        }

Summary:
Sample data:
Header file: page_utils.h
See also:


page_active_layer_index

Function: page_active_layer_index
Prototype:
int page_active_layer_index(Page& pg)
Remarks: Get the active layer number from the given page, if page is not the active window, then return -1
Parameters:
pg = the page to get the layer number

Return values:
0-offset layer number if given page is the active window, otherwise return -1

Example:
        void Run_page_active_layer_index()
        {
            GraphPage gp("Graph1");
            int nIndex = page_active_layer_index(gp);
        }

Summary:
Sample data:
Header file: page_utils.h
See also:


GetDatasetXFromStep

Function: GetDatasetXFromStep
Prototype:
BOOL GetDatasetXFromStep(LPCSTR lpcszDatasetName, double* lpdbFrom, double* lpdbStep)
Remarks: get dataset From and Step values that are used for plotting with Row# as X
Parameters:
lpcszDatasetName = [in] Dataset name
double =  [out] plotting X from
lpdbStep =[out] plotting X increment

Return values:
Returns TRUE if the given dataset is a valid dataset and it is in a worksheet with no X column, or is a loose dataset, so the From/Step values are available,

Example:
        double dFrom, dStep;
        string str = "Data1_b";
        if(GetDatasetXFromStep(str, &dFrom, &dStep))
            printf("%s is a loose dataset, or its worksheet has No X column, so it has From/Step = %g/%g\n", str, dFrom, dStep);

Summary:
Sample data:
Header file: data.h
See also:


Data_percentiles

Function: Data_percentiles
Prototype:
BOOL Data_percentiles(Dataset* pdsData, const double ardPercents[], double ardPercentiles[], int nValues, BOOL bInterpolate=FALSE)
Remarks: Calculate percentiles at given percent values for the given dataset.
Parameters:
pdsData=Input Dataset for which percentiles are computed
ardPercents=Input array of percents at which percentiles are computed
ardPercentiles=Output array of percentiles
nValues=Input number of percentile values to compute
bInterpolate=Input flag indicating whether or not to average (interpolate) when needed such as when computing
the 50th percentile for an even number of data values

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        // Assumes Data1_A exists in Origin and contains data
        Dataset dsA( "Data1_A" );
        double dPercent = 50, dPercentile;
        Data_percentiles( &dsA, &dPercent, &dPercentile, 1 );
        printf( "The 50th percentile is %g\n", dPercentile );

        double ardPercents[3] = { 5, 25, 95 };
        double ardPercentiles[3];
        Data_percentiles( &dsA, ardPercents, ardPercentiles, 3, TRUE );
        for(int ii = 0; ii < 3; ii++ )
            printf( "The %gth percentile is %g\n", ardPercents[ii], ardPercentiles[ii] );

Summary: Calculate percentiles at given percent values for the given dataset.
Sample data:
Header file: data.h
See also:


Data_sum

Function: Data_sum
Prototype:
BOOL Data_sum(Dataset* pdsData, BasicStats* pbsStat, Dataset* pdsSumData=NULL)
Remarks: Compute basic summary (descriptive) statistics on an Origin data set.
Parameters:
pdsData=Pointer to input dataset
pbsStat=Pointer to returned BasicStats structure (see OC_types.h)
pdsSumData=Pointer to returned dataset containing cumulative sum

Return values:
Returns TRUE, a BasicStats structure (see OC_types.h), and if specified, a data set containing
a cumulative sum of the input data set on success and returns FALSE on failure.

Example:
        int iSize;
        Dataset dsDataIn("Data1_B");
        iSize=dsDataIn.GetSize();
        Dataset dsSumOfDataIn("Data1_C");
        dsSumOfDataIn.SetSize(iSize);
        BasicStats bsStat;
        Data_sum( &dsDataIn, &bsStat, &dsSumOfDataIn );
        printf( "Min = %f\nMax = %f\nMean = %f\nSD = %f\nTotal = %f\nSSDM = %f\nN = %d\nMissing = %d\niMax = %d\niMin = %d",
        bsStat.min, bsStat.max, bsStat.mean, bsStat.sd, bsStat.total, bsStat.ssdm,
        bsStat.N, bsStat.Missing, bsStat.iMax, bsStat.iMin );

Summary: Dataset basic summary (descriptive) statistics.
Sample data:
Header file: data.h
See also:


MatrixBasicStats

Function: MatrixBasicStats
Prototype:
int MatrixBasicStats(matrix & mData, MatrixStats & sMatStatsSum, matrix * mpWeights = NULL)
Remarks: This function will give the summary of the statistics of a source data contained in a matrix If data does not have the weight, then the default weight 1 will be used
Parameters:
mData: The Data Source
sMatStatsSum: The Results
mpWeights: The pointer to a weight matrix if any

Return values:
Return 0 if succeed.
MAT_ERR_WEIGHTS_DATA_SIZE_NOT_MATCH: The weight matrix sizes do not match those of the source

Example:
            int test_Matrix_Stat_summary()
            {
                MatrixStats sMatStatsSum;

                matrix mData = {{193.0, 215.0, 112.0, 161.0}, {92.0, 140.0, 38.0, 33.3}, {279.0,
                                249.0, 473.0, 339.0}, {60.0, 130.0, 20.0, 50.0}, {257.0, 284.0,
                                447.0, 52.0}, {67.0, 61.0, 150.0, 2220.0}};

                matrix mWeights;
                int nNumCols = mData.GetNumCols();
                int nNumRows = mData.GetNumRows();
                   mWeights.SetSize(nNumRows, nNumCols);
                mWeights = 1;
                int nRet;
                if(nRet = MatrixBasicStats(mData, sMatStatsSum, &mWeights))
                    return nRet;

                   printf("Number of cases is %d\n", sMatStatsSum.nMissingValue);
                   printf("And there is no weight\n");
                   printf("The input is following : x=\n");
                for(int ii = 0; ii < nNumRows; ii++)
                {
                    for(int jj = 0; jj < nNumCols; jj++)
                        printf("%10.1f", mData[ii][jj]);
                    printf("\n");
                }

                printf("\nsucess is%d\n", nRet);
                if(nRet == 0)
                {
                    printf("\nsucessfully call of the nag_summary_stats_1var function\n");
                    printf("the output is following:\n");
                    printf("No of missing cases         %10d\n", sMatStatsSum.nMissingValue);
                    printf("mean                      %10.1f\n", sMatStatsSum.dMean);
                    printf("std devn                  %10.1f\n", sMatStatsSum.dSD);
                    printf("Minimun                   %10.1f\n", sMatStatsSum.dMin);
                    printf("Maximum                   %10.1f\n", sMatStatsSum.dMax);
                    printf("Sum of weights            %10.1f\n", sMatStatsSum.dWSum);
                }
                else
                {
                    printf(" \n There are some problems.");
                }

                return nRet;
            }

Summary:
Sample data:
Header file: matrix.h
See also:


erf

Function: erf
Prototype:
double erf(double dx)
Remarks: Error function (or normal error integral).
Parameters:
dx=Upper limit (dx is any Real) of the definite integral in the erf function.

Return values:
erf(x)=2/sqrt(pi)*(definite integral of exp(-u^2)du from 0 to +x).

Example:
        double dy,dx=1;
        dy=erf(dx); // results in dy==0.8427008

Summary: Error function.
Sample data:
Header file: Stat.h
See also: inverf


Ftable

Function: Ftable
Prototype:
double Ftable(double dP, UINT nNumDof, UINT nDenDof)
Remarks: Returns F distribution for significance level 0<dP<1, nNumDof>0, and nDenDof>0.
Parameters:
dP=Significance level where 0<dP<1.  dP equals the area under the F distribution curve to the left
of the returned value of F.
nNumDof=Numerator degrees of freedom where nNumDof>0.
nDenDof=Denominator degrees of freedom where nDenDof>0.

Return values:
Value of F for given values of dP, nNumDof, and nDenDof.  Returns F value such that the area under
the F distribution curve to the left of F equals dP.

Example:
        double dP=0.95;
        UINT nNumDof=2;
        UINT nDenDof=15;
        double dF;
        dF=Ftable(dP,nNumDof,nDenDof); // results in dF==3.68232
        nNumDof=4;
        nDenDof=10;
        dF=Ftable(dP,nNumDof,nDenDof); // results in dF==3.47805

Summary: F distribution.
Sample data:
Header file: Stat.h
See also: invf


inverf

Function: inverf
Prototype:
double inverf(double dy)
Remarks: Inverse error function.
Parameters:
dy=Normal integral error (dy is any Real).

Return values:
Upper limit of the definite integral in the erf function that returns a value of dy.

Example:
        double dx,dy=0.8427008;
        dx=inverf(dy); // results in dx==1

Summary: Inverse error function.
Sample data:
Header file: Stat.h
See also: erf


invf

Function: invf
Prototype:
double invf(double dF, UINT nNumDof, UINT nDenDof)
Remarks: Inverse F distribution.
Parameters:
dF=Value of F (F>0) for which inverse F is returned.
nNumDof=Numerator degrees of freedom where nNumDof>0.
nDenDof=Denominator degrees of freedom where nDenDof>0.

Return values:
Inverse F distribution for dF, nNumDof, and nDenDof.  Reurns the area under the F distribution curve
to the left of dF.

Example:
        double dF=3.68232;
        UINT nNumDof=2;
        UINT nDenDof=15;
        double dP;
        dP=invf(dF,nNumDof,nDenDof); // results in dP==0.95

Summary: Inverse F distribution.
Sample data:
Header file: Stat.h
See also: Ftable


invncp

Function: invncp
Prototype:
double invncp(double dA)
Remarks: Inverse cumulative probability density for a normal distribution. This function is related to invprob by the following relationship invprob(x) = invncp((x+1)/2)
Parameters:
dA=Area under the normal curve between negative infinity and z where 0<dA<1.

Return values:
The z value such that the area under the normal curve between -INF and z is dA.

Example:
        double dz,dA=0.8413447;
        dz=invncp(dA); // results in dz==1

Summary:
Sample data:
Header file: Stat.h
See also: invprob


invprob

Function: invprob
Prototype:
double invprob(double dA)
Remarks: Inverse probability density for a normal distribution.
Parameters:
dA=Area under the normal curve between -z and +z where 0<dA<1.

Return values:
The z value such that the area under the normal curve between -z and +z is dA.

Example:
        double dz,dA=0.6826895;
        dz=invprob(dA); // results in dz==1

Summary: Inverse probability density for a normal distribution.
Sample data:
Header file: Stat.h
See also: prob


invt

Function: invt
Prototype:
double invt(double dt, UINT nDof)
Remarks: Student's inverse t distribution for value of t (all Reals) and nDof>0.
Parameters:
dt=Value of t (t can be any Real number) for which inverse t is returned.
nDof=Degrees of freedom where nDof>0.

Return values:
Student's inverse t distribution for abs(dt) and nDof.  Reurns the area under the t distribution curve
to the left of abs(dt).

Example:
        double dt=1.761;
        UINT nDof=14;
        double dP;
        dP=invt(dt,nDof); // results in dP==0.95
        dt=-1.761;
        dP=invt(dt,nDof); // results in dP==0.05

Summary: Student's inverse t distribution.
Sample data:
Header file: Stat.h
See also: tTable probt


prob

Function: prob
Prototype:
double prob(double dz)
Remarks: Probability density for a normal distribution.
Parameters:
dz=Range of z values (-z to +z) for which the area under the normal curve is returned (dz can be any Real number).

Return values:
Area under the normal curve between -z and +z.  prob(x)=1/sqrt(2*pi)*(definite integral of exp((-t^2)/2)dt
from -x to +x).

Example:
        double dA,dz=1;
        dA=prob(dz); // results in dA==0.6826895

Summary: Probability density for a normal distribution.
Sample data:
Header file: Stat.h
See also: invprob


probt

Function: probt
Prototype:
double probt(double dt, UINT nDof)
Remarks: Student's inverse t distribution.
Parameters:
dt=Value of t (t can be any real number) for which inverse t is returned.
nDof=Degrees of freedom where nDof>0.

Return values:
Student's inverse t distribution for dt [not abs(dt)] and nDof.  Reurns the area under the t distribution
curve to the left of dt.

Example:
        double dt=1.761;
        UINT nDof=14;
        double dP;
        dP=probt(dt,nDof); // results in dP==0.95
        dt=-1.761;
        dP=probt(dt,nDof); // results in dP==0.05

Summary: Student's inverse t distribution.
Sample data:
Header file: Stat.h
See also: tTable invt


QCD2

Function: QCD2
Prototype:
double QCD2(UINT nn)
Remarks: Quality Control D2 Factor.
Parameters:
nn=Sample or subgroup size where nn>0.

Return values:
Quality Control D2 Factor which is used to estimate the standard deviation of a parent distribution
(or population) from an average range.  The standard deviation of the parent distribution=average range/factor.
The returned factors assume sampling from a normal population.

Example:
        UINT nn=4;
        double dD2;
        dD2=QCD2(nn); // results in dD2==2.058750

Summary: Quality Control D2 Factor.
Sample data:
Header file: Stat.h
See also: QCD3 QCD4


QCD3

Function: QCD3
Prototype:
double QCD3(UINT nn)
Remarks: Quality Control D3 Factor.
Parameters:
nn=Sample or subgroup size where nn>0.

Return values:
Quality Control D3 Factor for determining the 3-sigma lower control limit for R charts (Range of Sample Charts)
from the average range.  The Lower Control Limit for R=(factor)*(Average Range).  The calculations for the factors
are based on the normal distribution.

Example:
        UINT nn=11;
        double dD3;
        dD3=QCD3(nn); // results in dD3==0.256

Summary: Quality Control D3 Factor.
Sample data:
Header file: Stat.h
See also: QCD2 QCD4


QCD4

Function: QCD4
Prototype:
double QCD4(UINT nn)
Remarks: Quality Control D4 Factor.
Parameters:
nn=Sample or subgroup size where nn>0.

Return values:
Quality Control D4 Factor for determining the 3-sigma upper control limit for R charts (Range of Sample Charts)
from the average range.  The Upper Control Limit for R=(factor)*(Average Range).  The calculations for the factors
are based on the normal distribution.

Example:
        UINT nn=11;
        double dD4;
        dD4=QCD4(nn); // results in dD4==1.744

Summary: Quality Control D4 Factor.
Sample data:
Header file: Stat.h
See also: QCD2 QCD3


tTable

Function: tTable
Prototype:
double tTable(double dP, UINT nDof)
Remarks: Returns Student's t distribution for significance level 0<dP<1 and nDof>0.
Parameters:
dP=Significance level where 0<dP<1.  dP equals the area under the t distribution curve to the left of the
returned value of t.
nDof=Degrees of freedom where nDof>0.

Return values:
Value of t for given values of dP and nDof.  Returns a t value such that the area under the t distribution
curve to the left of t equals dP.

Example:
        double dP=0.95;
        UINT nDof=14;
        double dt;
        dt=tTable(dP,nDof); // results in dt==1.761
        dt=tTable(0.05, 14); // results in dt==-1.761

Summary: Student's t distribution.
Sample data:
Header file: Stat.h
See also: invt probt


CloseClipboard

Function: CloseClipboard
Prototype:
BOOL WINAPI CloseClipboard(void)
Remarks: This function closes the clipboard When the window has finished examining or changing the clipboard, close the clipboard by calling CloseClipboard. This enables other windows to access the clipboard. Do not place an object on the clipboard after calling CloseClipboard.
Parameters:

Return values:
Returns TRUE for success.

Example:
        void empty_clipboard()
        {
            if(OpenClipboard(NULL))
            {
                EmptyClipboard();
                CloseClipboard();
            }
        }

Summary:
Sample data:
Header file: mswin.h
See also:


EmptyClipboard

Function: EmptyClipboard
Prototype:
BOOL WINAPI EmptyClipboard(void)
Remarks: This function empties the clipboard and frees handles to data in the clipboard. The function then assigns ownership of the clipboard to the window that currently has the clipboard open. Before calling EmptyClipboard, an application must open the clipboard by using the OpenClipboard function. If the application specifies a NULL window handle when opening the clipboard, EmptyClipboard succeeds but sets the clipboard owner to NULL.
Parameters:

Return values:
Returns TRUE for success.

Example:
        void empty_clipboard()
        {
            if(OpenClipboard(NULL))
            {
                EmptyClipboard();
                CloseClipboard();
            }
        }

Summary:
Sample data:
Header file: mswin.h
See also:


GetClipboardData

Function: GetClipboardData
Prototype:
HANDLE WINAPI GetClipboardData(UINT uFormat)
Remarks: This function function retrieves data from the clipboard in a specified format. The clipboard must have been opened previously. The clipboard controls the handle that the GetClipboardData function returns, not the application. The application should copy the data immediately. The application must not free the handle nor leave it locked. The application must not use the handle after the EmptyClipboard or CloseClipboard function is called, or after the SetClipboardData function is called with the same clipboard format. The system performs implicit data format conversions between certain clipboard formats when an application calls the GetClipboardData function. For example, if the CF_OEMTEXT format is on the clipboard, a window can retrieve data in the CF_TEXT format. The format on the clipboard is converted to the requested format on demand.
Parameters:
uFormat = [in] Specifies a standard or registered clipboard format, like CF_TEXT, CF_DIB etc

Return values:
If the function succeeds, the return value is the handle to a clipboard object in the specified format.
If the function fails, the return value is NULL.

Example:
        void test_clipboard()
        {
            if(!OpenClipboard(NULL))
                return;

            if(IsClipboardFormatAvailable(CF_TEXT))
            {
                HANDLE hData = GetClipboardData(CF_TEXT);
                LPCSTR lpData = (LPCSTR)GlobalLock(hData);
                string str = lpData;
                GlobalUnlock(hData);
                out_str(str);
            }
            else
                out_str("No Text in clipboard");

            CloseClipboard();
        }

Summary:
Sample data:
Header file: mswin.h
See also:


GetEnvironmentVariable

Function: GetEnvironmentVariable
Prototype:
DWORD WINAPI GetEnvironmentVariable(LPCSTR lpcszName, LPSTR lpBuffer, DWORD nSize)
Remarks: This function retrieves the value of the specified variable from the environment block of the calling process. The value is in the form of a null-terminated string of characters.
Parameters:
lpcszName = environment variable name
lpBuffer = buffer for variable value
nSize =    size of buffer
.

Return values:
If the function succeeds, the return value is the number of characters stored into the buffer
pointed to by lpBuffer, not including the terminating null character.
If the specified environment variable name was not found in the environment block for the current process,
the return value is zero.
If the buffer pointed to by lpBuffer is not large enough, the return value is the buffer size, in characters,
required to hold the value string and its terminating null character.

Example:
    // usage:
    // show_environment_str path;
    // show_environment_str temp;
    void show_environment_str(string strName)
    {
        char szTemp[MAXFULLPATH];

        int	nResult = GetEnvironmentVariable(strName, szTemp, MAXFULLPATH);

        if(nResult > 0)
        {
            if(nResult == lstrlen(szTemp))
                out_str(szTemp);
            else
                printf("The %s environment variable is too big (%d bytes)\n",strName,nResult);
        }
        else
            out_str("Error: Environment variable not found.");
    }

Summary:
Sample data:
Header file: mswin.h
See also:


GetKeyState

Function: GetKeyState
Prototype:
short WINAPI GetKeyState(int nVirtKey)
Remarks: This function retrieves the status of the specified virtual key. The status specifies whether the key is up, down, or toggled (on, off - alternating each time the key is pressed).
Parameters:

Return values:

Example:
    Example:This function get the state of the Tab key.
        void run_GetKeyState()
        {
            short i = GetKeyState(0x09);
            printf("%d",i);
        }

Summary:
Sample data:
Header file: mswin.h
See also:


GetSystemMetrics

Function: GetSystemMetrics
Prototype:
int WINAPI GetSystemMetrics(int nIndex)
Remarks: This function retrieves various system metrics (widths and heights of display elements) and system configuration settings. All dimensions retrieved by GetSystemMetrics are in pixels. System metrics may vary from display to display.
Parameters:
nIndex = [in] Specifies the system metric or configuration setting to retrieve. All SM_CX* values are widths. All SM_CY* values are heights.

Return values:
If the function succeeds, the return value is the requested system metric or configuration setting.	If the function fails, the return value is zero.

Example:
        void run_GetSystemMetrics()
        {
            int i = GetSystemMetrics(4);
            printf("%d",i);  //output should be 19
        }

Summary:
Sample data:
Header file: mswin.h
See also:


GetTickCount

Function: GetTickCount
Prototype:
UINT WINAPI GetTickCount()
Remarks: The GetTickCount function retrieves the number of milliseconds that have elapsed since the system was started. It is limited to the resolution of the system timer. It is often used to measure time needed to complete an operation (see the example).
Parameters:
None.

Return values:
the number of milliseconds ellapsed since the system was restarted.

Example:
        // This example measures how much time (in milliseconds) it takes
        // to execute an empty for-loop of 1000.
        void	run_GetTickCount()
        {
            DWORD dw1 = GetTickCount();

            for(int ii = 0; ii < 1000; ii++)
                ;

            printf("Empty loop of 1000 takes %d ms\n",GetTickCount()-dw1);
        }

Summary: Retrieve number of milliseconds elapsed since the system was started
Sample data:
Header file: mswin.h
See also:


GetVersion

Function: GetVersion
Prototype:
UINT WINAPI GetVersion()
Remarks: Retrieve current version number of the operating system.
Parameters:
None.

Return values:
the version number. The low byte of the low word is the major OS version, the high byte
of the low word is the minor OS version. The highest bit determines the platform: it is
on for Windows 95, 98, and Me, it is off for Windows NT, 2000, XP.

Example:
        // This example checks if the operating system is of "NT-type"
        // (which means Windows NT, 2000, XP).
        bool is_OS_NT_type()
        {
            DWORD	dwVersion = GetVersion();
            // Get major and minor version numbers of Windows
            WORD loword = LOWORD(dwVersion);
            int lowbyte = LOBYTE(loword);
            int hibyte =  HIBYTE(loword);

            printf("Window major version = %d and minor version = %d\n", lowbyte, hibyte);

            if(!(dwVersion & 0x80000000))                // Windows NT, 2000, XP
                return TRUE;
            else         // Windows 95, 98, ME
                return FALSE;
        }

Summary:
Sample data:
Header file: mswin.h
See also:


GetWindow

Function: GetWindow
Prototype:
HWND GetWindow(int nWin = OGW_MAIN)
Remarks: retrieves the Windows handle of Origin's internal windows.
Parameters:
nWin = one of the OGW_MAIN,OGW_MDICLIENT, OGW_SCRIPT_WINDOW, OGW_CODEBUILDER etc const

Return values:
The window handle of an Origin window.

Example:
        void	run_GetWindow()
        {
              HWND	hwnd = GetWindow();
            MessageBox(hwnd, "This is a test", "TestGetWindow");
        }

Summary: get Origin window handle
Sample data:
Header file: mswin.h
See also:


IsClipboardFormatAvailable

Function: IsClipboardFormatAvailable
Prototype:
BOOL WINAPI IsClipboardFormatAvailable(UINT uFormat)
Remarks: This function determines whether the clipboard contains data in the specified format.
Parameters:
uFormat = [in] Specifies a standard or registered clipboard format, like CF_TEXT, CF_DIB etc

Return values:
Returns TRUE if the clipboard format is available, otherwise returns FALSE

Example:
        void any_text_in_clipboard()
        {
            if(OpenClipboard(NULL))
            {
                if(IsClipboardFormatAvailable(CF_TEXT))
                    out_str("Yes,  Text in clipboard");
                else
                    out_str("No Text in clipboard");

                CloseClipboard();
            }
        }

Summary:
Sample data:
Header file: mswin.h
See also:


IsWindowVisible

Function: IsWindowVisible
Prototype:
BOOL WINAPI IsWindowVisible(HWND hWnd)
Remarks: This function retrieves the visibility state of the specified window. Because the return value specifies whether the window has the WS_VISIBLE style, it may be TRUE even if the window is totally obscured by other windows.
Parameters:
hWnd = [in] Handle to the window to test.

Return values:
If the specified window, its parent window, its parent's parent window, and so forth, have the WS_VISIBLE style, the return value is TRUE.
Otherwise, the return value is FALSE.

Example:
        if(!IsWindowVisible(GetWindow()))
            out_str("The Origin window is hidden.");

Summary:
Sample data:
Header file: mswin.h
See also:


OpenClipboard

Function: OpenClipboard
Prototype:
BOOL WINAPI OpenClipboard(HWND hWndNewOwner)
Remarks: This function opens the clipboard for examination and prevents other applications from modifying the clipboard content. . OpenClipboard fails if another window has the clipboard open. An application should call the CloseClipboard function after every successful call to OpenClipboard. The window identified by the hWndNewOwner parameter does not become the clipboard owner unless the EmptyClipboard function is called.
Parameters:
hWndNewOwner = [in] Handle to the window to be associated with the open clipboard. If this parameter is NULL, the open clipboard is associated with the current task.

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
        void test_clipboard()
        {
            if(!OpenClipboard(NULL))
                return;

            if(IsClipboardFormatAvailable(CF_TEXT))
            {
                HANDLE hData = GetClipboardData(CF_TEXT);
                LPCSTR lpData = (LPCSTR)GlobalLock(hData);
                string str = lpData;
                GlobalUnlock(hData);
                out_str(str);
            }
            else
                out_str("No Text in clipboard");

            CloseClipboard();
        }

Summary:
Sample data:
Header file: mswin.h
See also:


SetClipboardData

Function: SetClipboardData
Prototype:
HANDLE WINAPI SetClipboardData(UINT uFormat, HANDLE hMem)
Remarks: This function places data on the clipboard in a specified clipboard format. The window must be the current clipboard owner, and the application must have called the OpenClipboard function. Before calling SetClipboardData, an application must open the clipboard by using the OpenClipboard function. The hMem data will be passed to the clipboard, which means that the application must create this data and not to lock and not to free it after giving it to the clipboard
Parameters:
uFormat = [in] Specifies a standard or registered clipboard format, like CF_TEXT, CF_DIB etc.
hMem = [in] Handle to the data in the specified format.

Return values:
If the function succeeds, the return value is the handle to the data. If the function fails, the return value is NULL.

Example:
        void put_text_to_clipboard(string str)
        {
            int nMemSize = str.GetLength() + 1;// need terminating zero
            HANDLE hData = GlobalAlloc(GHND,nMemSize);
            LPSTR lpData = (LPSTR)GlobalLock(hData);
            lstrcpyn(lpData, str, nMemSize);
            GlobalUnlock(hData);
            if(OpenClipboard(NULL))
            {
                EmptyClipboard();
                SetClipboardData(CF_TEXT,hData);
                CloseClipboard();
            }
        }

Summary:
Sample data:
Header file: mswin.h
See also:


SetEnvironmentVariable

Function: SetEnvironmentVariable
Prototype:
BOOL WINAPI SetEnvironmentVariable(LPCSTR lpcszName, LPCSTR lpcszValue)
Remarks: This function sets the value of an environment variable for the current process.
Parameters:
lpcszName = environment variable name
lpcszValue = new value for environment variable
.

Return values:
TRUE for success

Example:
    // usage:
    // set_environment_str test "A new string for testing";
    // show_environment_str test;
    void set_environment_str(string strName, string strValue)
    {
        if(SetEnvironmentVariable(strName, strValue))
            return;
        out_str("error calling SetEnvironmentVariable");
    }

Summary:
Sample data:
Header file: mswin.h
See also:


ShowWindow

Function: ShowWindow
Prototype:
BOOL WINAPI ShowWindow(HWND hWnd, int nCmdShow)
Remarks: This function sets the specified window's show state
Parameters:
hWnd = [in] Handle to the window to test.
nCmdShow = SW_HIDE, SW_NORMAL, SW_MINIMIZE, SW_MAXIMIZE etc.

Return values:
If the window was previously visible, the return value is TRUE.
If the window was previously hidden, the return value is FALSE.

Example:
        // make the Origin main window minimized
        HWND  hWnd = GetWindow();
        if(hWnd)
               ShowWindow(hWnd, SW_MINIMIZE);

Summary:
Sample data:
Header file: mswin.h
See also:


Sleep

Function: Sleep
Prototype:
void WINAPI Sleep(DWORD dwMilliseconds)
Remarks: It puts the application to a halt for the specified number of milliseconds.
Parameters:
dwMilliseconds - the number of milliseconds to sleep.

Return values:
none

Example:
        void	run_Sleep()
        {
            out_str("Before Sleep");
            Sleep(1000);	// sleep for one second
            out_str("After Sleep");
        }

Summary:
Sample data:
Header file: mswin.h
See also:


GetClipboardText

Function: GetClipboardText
Prototype:
BOOL GetClipboardText( string& strData )
Remarks: Get the text data copied onto the clipboard.
Parameters:
strData = Output text copied from clipboard

Return values:
Returns TRUE and a string containing text copied onto the clipboard
on success or returns FALSE and an empty string on failure or if
the Clipboard is empty.

Example:
        string strClipboardText;
        BOOL bSuccess;
        bSuccess = GetClipboardText( strClipboardText );
        if( bSuccess )
            out_str( strClipboardText );
        else
            out_str( "Error reading Clipboard or Clipboard is empty." );

Summary:
Sample data:
Header file: sys_utils.h
See also:


is_win2k

Function: is_win2k
Prototype:
bool is_win2k(bool bAndLater = true)
Remarks: Test Windows version to see if it is Windows 2000 or later
Parameters:
bAndLater = false if you need to test to see if OS is exactly Windows 2000

Return values:
TRUE or FALSE

Example:

Summary:
Sample data:
Header file: sys_utils.h
See also:


load_default_checkboxes

Function: load_default_checkboxes
Prototype:
bool load_default_checkboxes(LPCSTR lpcszDlgName, vector<byte>& vbValues, LPCSTR lpcszValName = NULL)
Remarks: Setrive a array of boolean values saved by save_default_checkboxes in the registry.
Parameters:
lpcszDlgName = name of the dialog, this is used as the section name in the registry under /Dialogs/lpcszDlgName
vbValues = array of 1 and 0 that each will represent each bit in the DWORD value saved into registry
lpcszValName = Value name in registry to save, if not specified, CheckBoxes will be used

Return values:
True for success, false if lpcszDlgName section does not have the item in registry.

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


save_default_checkboxes

Function: save_default_checkboxes
Prototype:
bool save_default_checkboxes(LPCSTR lpcszDlgName, const vector<byte>& vbValues, LPCSTR lpcszKey = NULL)
Remarks: Save the given array of boolean values into a single DWORD in the registry.
Parameters:
lpcszDlgName = name of the dialog, this is used as the section name in the registry under /Dialogs/lpcszDlgName
vbValues = array of 1 and 0 that each will be assigned to a bit in the DWORD value saved into registry
lpcszValName = Value name in registry to save, if not specified, CheckBoxes will be used

Return values:
True for success, false for error.

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


ExecuteApp

Function: ExecuteApp
Prototype:
BOOL ExecuteApp(LPCSTR lpApp, LPCSTR lpArg, BOOL bTransferControl = TRUE, BOOL bTryWinExec = FALSE)
Remarks: launch an application
Parameters:
lpApp = module name
lpArg = Command line.
bTransferControl = if FALSE and if lpApp is not NULL, this function will not return until the application is terminated
bTryWinExec = try the older WinExec function from Windows if the standard method failed.

Return values:
TRUE if sucess, FALSE if failed

Example:

Summary:
Sample data:
Header file: utilities.h
See also:


GetRegKey

Function: GetRegKey
Prototype:
string GetRegKey(BOOL bLanguage = TRUE)
Remarks: get the registry key in the general area for the Origin software
Parameters:
bLanguage = TRUE if to get to the subpath for language specific users, which is most typically the case

Return values:
A string containing the full path (key) that can be used in the Registry class

Example:
        #include <settings.h>
        void test()
        {
            Registry reg(HKEY_CURRENT_USER);
            string strUserPath;
            if(reg.GetValue(GetRegKey(), "Path", strUserPath))
                printf("User path is stored as %s\n", strUserPath);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


tree_add_info

Function: tree_add_info
Prototype:
bool tree_add_info(TreeNode& trNode, const OriginObject& orgObj, LPCSTR lpcszObjName = NULL, LPCSTR lpcszObjLabel = NULL, int nObjIndex = -1)
Remarks: add all Info storage into given treenode
Parameters:
trNode = tree node to add info storage
orgObj = Origin object, can be Page, Layer, Column
lpcszObjName = name of the Origin object, if NULL, will use GetName
lpcszObjLabel = label of the Origin object, if NULL, will use GetLabel
nObjIndex = index >= 0 for additional info to be stored in the StrData of the tree node for each item, use NPLOT_FOR_WKS if this is for text label display in a worksheet

Return values:
TRUE for success

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_copy_values

Function: tree_copy_values
Prototype:
int tree_copy_values(TreeNode& trSrc, const TreeNode& trDest, WORD wOptions = TREE_COPY_SKIP_HIDDEN | TREE_COPY_ATTRIB_ENABLE)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_count_items

Function: tree_count_items
Prototype:
int tree_count_items(TreeNode& tr, int* lpnSections = NULL)
Remarks: count number of leafs in the given tree
Parameters:
tr = TreeNode to count
lpnSections = if given, then count the number of branches that contain these leafs

Return values:
total number of leafs

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_get_ini_section

Function: tree_get_ini_section
Prototype:
TreeNode tree_get_ini_section(TreeNode &trIni, LPCSTR lpcszSection)
Remarks: Get the tree node that represents a specified ini section.
Parameters:
trIni = tree node that represents an ini file
lpcszSection = pointer to an ini section name

Return values:
If a tree node representing the specified ini section then it is returned, else an invalid tree node is returned.

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_get_node

Function: tree_get_node
Prototype:
TreeNode tree_get_node(TreeNode& trRoot, int nRow, int* lpInc = NULL)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_get_values

Function: tree_get_values
Prototype:
void tree_get_values(TreeNode& tr, vector<string>& vs)
Remarks: walk tree and copy all the values into given string vector
Parameters:
tr = TreeNode to walk
vs = a linearized array of string values that should map to every tree node

Return values:

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_node_changed

Function: tree_node_changed
Prototype:
bool tree_node_changed(TreeNode& trNode, bool bSet = false, LPCSTR lpcszOldValue = NULL)
Remarks: if bSet, then NULL will clear changed
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_node_get_double

Function: tree_node_get_double
Prototype:
double tree_node_get_double(TreeNode& tr, string& strLabel, double dDefault = _ONAN)
Remarks: get both the numeric value of a tree node as well as its associated label
Parameters:
tr = TreeNode to get
strLabel = the text label if present, otherwise the tagName
dDefault = default value in case node is not a valid node

Return values:

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_node_get_int

Function: tree_node_get_int
Prototype:
int tree_node_get_int(TreeNode& tr, int nDefault = 0)
Remarks: get int value from a tree node, whether it is valid or not
Parameters:
tr = TreeNode to get
nDefault = default value in case node is not a valid node

Return values:

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_read_ini

Function: tree_read_ini
Prototype:
bool tree_read_ini(TreeNode &trIni, LPCSTR lpcszFile)
Remarks: Read an ini file into a tree node.
Parameters:
trIni = tree node to receive the ini file
lpcszSection = pointer to an ini file name

Return values:
true for success, false for error

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:
Function: tree_read_ini
Prototype:
bool tree_read_ini(TreeNode &trIni, INIFile &iniFile)
Remarks: Read an ini file into a tree node.
Parameters:
trIni = tree node to receive the ini file
iniFile = the ini file to read from

Return values:
true for success, false for error

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_read_ini_section

Function: tree_read_ini_section
Prototype:
bool tree_read_ini_section(TreeNode &trIni, LPCSTR lpcszFile, LPCSTR lpcszSection)
Remarks: Read an ini section into a tree node.
Parameters:
trIni = tree node to receive the ini section
lpcszFile = pointer to an ini file name
lpcszSection = pointer to an ini section name

Return values:
true for success, false for error

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:
Function: tree_read_ini_section
Prototype:
bool tree_read_ini_section(TreeNode &trIni, INIFile &iniFile, LPCSTR lpcszSection)
Remarks: Read an ini section into a tree node.
Parameters:
trIni = tree node to receive the ini section
iniFile = the ini file to read from
lpcszSection = pointer to an ini section name

Return values:
true for success, false for error

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_remove_attribute

Function: tree_remove_attribute
Prototype:
int tree_remove_attribute(TreeNode& tr, LPCSTR lpcszAttribute)
Remarks: walk all tree nodes to delete specified attribute
Parameters:
tr = TreeNode to walk
lpcszAttribute = attribute name to delete

Return values:
total number of nodes the specified attribute is deleted

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_update_changes

Function: tree_update_changes
Prototype:
int tree_update_changes(TreeNode& tr, const vector<string>& vs)
Remarks: walk tree and store attribute "OldValue" into all the nodes that has different value then the specified string the vs array can be obtained by tree_get_values.
Parameters:
tr = TreeNode to walk
vs = a linearized array of string values that should map to every tree node

Return values:
total number of nodes that has OldValue attributes added (changed)

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_write_ini

Function: tree_write_ini
Prototype:
bool tree_write_ini(TreeNode &trIni, LPCSTR lpcszFile, bool bClearSections=false)
Remarks: Write a tree node, that represents an ini file, to an ini file.
Parameters:
trIni = tree node representing an ini file
lpcszFile = pointer to an ini file name

Return values:
true for success, false for error.

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:
Function: tree_write_ini
Prototype:
bool tree_write_ini(TreeNode &trIni, INIFile &iniFile, bool bClearSections=false)
Remarks: Write a tree node, that represents an ini file, to an ini file.
Parameters:
trIni = tree node representing an ini file
iniFile = ini file to be written to

Return values:
true for success, false for error

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


tree_write_ini_section

Function: tree_write_ini_section
Prototype:
bool tree_write_ini_section(TreeNode &trIniSection, INIFile &iniFile, bool bClearSection=false)
Remarks: Write a tree node, that represents an ini section, to an ini file.
Parameters:
trIniSection = tree node representing an ini section
iniFile = ini file to be written to

Return values:
true for success, false for error

Example:

Summary:
Sample data:
Header file: tree_utils.h
See also:


GetNBox

Function: GetNBox
Prototype:
bool GetNBox(TreeNode& trNode, LPCSTR lpcszTitle=NULL, LPCSTR lpcszDescription=NULL, PAPPLY_FUNC pfnApply = NULL, PEVENT_FUNC pfnEvent = NULL, HWND hWndParent = NULL)
Remarks: Opens a simple dialog to get multiple values from user
Parameters:
trNode = a TreeNode constructed by the GETN_BOX or GETN_TREE macro
lpcszTitle = Dialog title
lpcszDescription = a line of text above the editable list of parameters
pfnApply = if specified, an Apply button will show and call this handler
pfnEvent = if specified, it will be called at the beginning with Row number = -1 for each control type, and if user change any editable parameters, the event handler will also be called
hWndParent = parent window. If NULL, Origin main window will be used, also the location of the dialog will be reset to where it was brought up the time before.
If hWndParent is specified, the dialog will be open at its default location, so the event handler can move the dialog to a desired location.

Return values:
TRUE if user click OK, FALSE if user click Cancel

Example:
        // this will bring up the simple form with dialog look
        void test_get_n_box()
        {
            double x0, x1;
            GETN_BOX(trTemp)
            GETN_NUM(xFrom, "X From", 1.3)
            GETN_NUM(xStep, "X Step", -0.5)
            if(GetNBox(trTemp, "Row# as X", "Please specify initial X value and increment"))
            {
                x0 = trTemp.xFrom.dVal;
                x1 = trTemp.xStep.dVal;
                printf("X from %f with increment %f\n", x0, x1);
            }
        }
        // the following example shows a tree that allow more info to be edited
        static bool fit_expdecay_event(TreeNode& myTree, int nRow, int nType, Dialog& dlgGetNBox)
        {
            if(nRow < 0) // On dialog init, nothing to do
                return false;

            // only handle the button for file path for now
            if(TRGP_STR_BUTTON == nType)
            {
                string str = BrowseGetPath(GetAppPath() + "OriginC\\", "Browse");
                myTree.Path.strVal = str;
                return true;
            }
            return false;
        }
        void test_get_n_tree()
        {
            GETN_TREE(myTree)
            GETN_COMBO(numExp, "Number of Terms", 1, "1|2|3")

            GETN_BEGIN_BRANCH(DecayTime, "Decay Times")
                GETN_NUM(decayT1, "1st Decay Time (t1)", 0.0)
                GETN_NUM(decayT2, "2nd Decay Time (t2)", 0.0)
                GETN_NUM(decayT3, "3rd Decay Time (t3)", 0.0)
            GETN_END_BRANCH(DecayTime)

            GETN_CHECK(PartialRange, "Fit Partial Data", false)
            GETN_BUTTON(Path, "File path", "c:\\")

            GETN_COLOR(FitCurveColor, "Fit Curve color", 1)

            if(GetNBox(myTree, "Fit Exp Decay", "Fit Exponential Decay 1,2,3", NULL, fit_expdecay_event))
            {
                if(myTree.numExp.nVal > 1)
                    out_str("Multiple exponential");
                if(myTree.DecayTime.decayT1.dVal <= 0)
                    out_str("Invalid decay time specified");
            }
        }

Summary:
Sample data:
Header file: GetNbox.h
See also:


MessageBeep

Function: MessageBeep
Prototype:
BOOL WINAPI MessageBeep( UINT uType )
Remarks: MessageBeep plays a waveform sound. The waveform sound for each sound type is identified by an entry in the registry which can be accessed from the Sounds or Multi-Media applet in the Window's Control Panel.
Parameters:
uType=-1 for standard beep using the computer speaker or MB_ICONASTERISK, MB_ICONEXCLAMATION, MB_ICONHAND,
MB_ICONQUESTION, or MB_OK (for system default)

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
        MessageBeep( -1 ); // Beep standard computer speaker

Summary:
Sample data:
Header file: mswin.h
See also:


MessageBox

Function: MessageBox
Prototype:
int WINAPI MessageBox( HWND hWnd, LPCSTR lpText, LPCSTR lpCaption = NULL, UINT uType = MB_OK )
Remarks: Open a Window's message box.
Parameters:
hWnd = Handle of parent window
lpText = Text of the message to be displayed
lpCaption = Title of the message box, default is NULL
uType = Constants describing the characteristics of the message box. One constant from each group below
can be combined using the bitwise OR operator "|", default is MB_OK
Buttons on message box:			MB_OK, MB_OKCANCEL, MB_ABORTRETRYIGNORE, MB_YESNOCANCEL, MB_YESNO,
MB_RETRYCANCEL
Icon on message box:			MB_ICONHAND, MB_ICONQUESTION, MB_ICONEXCLAMATION, MB_ICONASTERISK,
MB_ICONINFORMATION, MB_ICONSTOP
Default button of message box:	MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3
Modality of message box:		MB_APPLMODAL, MB_SYSTEMMODAL, MB_TASKMODAL
Mask of message box:			MB_TYPEMASK, MB_ICONMASK, MB_DEFMASK, MB_MODEMASK, MB_MISCMASK

Return values:
Returns one of the following integer constants depending on which button is clicked: IDOK=1,
IDCANCEL=2, IDABORT=3, IDRETRY=4, IDIGNORE=5, IDYES=6, IDNO=7, IDCLOSE=8, IDHELP=9

Example:
        void	run_MessageBox()
        {
            if( MessageBox( GetWindow(), "Undo not available. Do you want to continue?", "Warning!" , MB_YESNO | MB_ICONQUESTION | MB_DEFBUTTON2 ) == IDNO )
            {
                out_str("\"No\" was clicked.");
                return;
            }
            out_str("\"Yes\" was clicked.");
        }

Summary: Open a Windows message box.
Sample data:
Header file: mswin.h
See also:


BrowseGetPath

Function: BrowseGetPath
Prototype:
string BrowseGetPath( LPCSTR lpcszPath = NULL, LPCSTR lpcszDialogName = NULL )
Remarks: Open an FDLog Browse (OpenPath) dialog box.
Parameters:
lpcszPath=Initial path when dialog opens, default NULL uses FDLog tracking
lpcszDialogName=Title of the dialog box, default NULL uses "Open"

Return values:
Returns the path browsed to or an empty string if Cancel button in dialog
box is clicked.

Example:
        string strPath;
        strPath = BrowseGetPath();                                      // or
        strPath = BrowseGetPath( "C:\\Program Files\\" );               // or
        strPath = BrowseGetPath( GetAppPath() + "OriginC\\", "Browse" );

Summary:
Sample data:
Header file: sys_utils.h
See also:


GetMultiOpenBox

Function: GetMultiOpenBox
Prototype:
int GetMultiOpenBox( StringArray& saFilePaths, StringArray &saFiletypes, LPCSTR lpcszPath = NULL, LPCSTR lpcszFilename = NULL,LPCSTR lpcszDialogName = NULL, bool bMultiSelection = true )
Remarks: Open an FDLog Open dialog box passing the file types to list in an array of strings. Optionally uses a simple Open dialog with multiple selection enabled or a Multi-Open dialog box.
Parameters:
saFilePaths=Output vector of strings containing path and filename of all selected files
saFiletypes=Input vector containing file types to list in the dialog box, each element
of vector must follow syntax of LabTalk FDLog.TypeN$ object property
lpcszPath=Input initial path when dialog opens, default NULL uses FDLog tracking
lpcszFileName=Input initial filename when dialog opens, default NULL uses an empty string
lpcszDialogName=Input title of the dialog box, default NULL uses "Open"
bMultiSelection=Input flag specifiying to use multi-selection Open (default true) or Multi-Open (false) dialog box

Return values:
Returns the path and filename of all selected files or an empty string if Cancel button
in dialog box is clicked. Also returns the number of files selected.

Example:
        int iNumSelFiles;
        string strPath;
        StringArray saFiletypes, saFilePaths;
        saFiletypes.SetSize( 3 );
        saFiletypes[0]="[Project (*.OPJ)] *.OPJ";
        saFiletypes[1]="[Old version (*.ORG)] *.ORG";
        saFiletypes[2]="[Worksheets (*.OGW)] *.OGW";
        iNumSelFiles = GetMultiOpenBox( saFilePaths, saFiletypes ); // or
        iNumSelFiles = GetMultiOpenBox( saFilePaths, saFiletypes, "C:\\Program Files\\" ); // or
        iNumSelFiles = GetMultiOpenBox( saFilePaths, saFiletypes, "C:\\Program Files\\", "Origin" ); // or
        iNumSelFiles = GetMultiOpenBox( saFilePaths, saFiletypes, "C:\\Program Files\\", "Origin", "OpenOPJ" ); // or
        iNumSelFiles = GetMultiOpenBox( saFilePaths, saFiletypes, "C:\\Program Files\\", "Origin", "OpenOPJ", true );

Summary:
Sample data:
Header file: sys_utils.h
See also:
Function: GetMultiOpenBox
Prototype:
int GetMultiOpenBox( StringArray& saFilePaths, LPCSTR lpcszFileType = NULL, LPCSTR lpcszPath = NULL, LPCSTR lpcszFilename = NULL,LPCSTR lpcszDialogName = NULL, bool bMultiSelection = true )
Remarks: An easier to use version of GetMultiOpenBox that works for a single file type. Optionally uses a simple Open dialog with multiple selection enabled or a Multi-Open dialog box.
Parameters:
saFilePaths=Output vector of strings containing path and filename of all selected files
lpcszFileType=Input file type string like "*.ext description", "[decription (*.ext)] *.ext", or just "*.ext"
lpcszPath=Input initial path when dialog opens, default NULL uses FDLog tracking
lpcszFileName=Input initial filename when dialog opens, default NULL uses an empty string
lpcszDialogName=Input title of the dialog box, default NULL uses "Open"
bMultiSelection=Input flag specifiying to use multi-selection Open (default true) or Multi-Open (false) dialog box

Return values:
Returns the path and filename of all selected files or an empty string if Cancel button
in dialog box is clicked. Also returns the number of files selected.

Example:
        int iNumFiles;
        StringArray saFilePaths;
        iNumFiles = GetMultiOpenBox(saFilePaths); // or
        iNumFiles = GetMultiOpenBox( saFilePaths, "[Old version (*.ORG)] *.ORG" ); // or
        iNumFiles = GetMultiOpenBox( saFilePaths, "*.OPJ"); // or
        iNumFiles = GetMultiOpenBox( saFilePaths, "*.ocw Workspace", GetAppPath() + "OriginC\\" ); // or
        iNumFiles = GetMultiOpenBox( saFilePaths, "*.ocw Workspace", GetAppPath() + "OriginC\\", "Origin" ); // or
        iNumFiles = GetMultiOpenBox( saFilePaths, "*.ocw Workspace", "C:\\Program Files\\", "Origin", "Open Workspace", false );

Summary:
Sample data:
Header file: sys_utils.h
See also:


GetOpenBox

Function: GetOpenBox
Prototype:
string GetOpenBox( StringArray &saFiletypes, LPCSTR lpcszPath = NULL, LPCSTR lpcszFilename = NULL,LPCSTR lpcszDialogName = NULL )
Remarks: Open an FDLog Open dialog box passing the file types to list in an array of strings.
Parameters:
saFiletypes=Vector containing file types to list in the dialog box, each element
of vector must follow syntax of LabTalk FDLog.TypeN$ object property
lpcszPath=Initial path when dialog opens, default NULL uses FDLog tracking
lpcszFileName=Initial filename when dialog opens, default NULL uses an empty string
lpcszDialogName=Title of the dialog box, default NULL uses "Open"

Return values:
Returns the path and filename of a selecetd file or an empty string if Cancel button
in dialog box is clicked.

Example:
        string strPath;
        StringArray saFiletypes;
        saFiletypes.SetSize( 3 );
        saFiletypes[0]="[Project (*.OPJ)] *.OPJ";
        saFiletypes[1]="[Old version (*.ORG)] *.ORG";
        saFiletypes[2]="[Worksheets (*.OGW)] *.OGW";
        strPath = GetOpenBox( saFiletypes ); // or
        //strPath = GetOpenBox( saFiletypes, "C:\\Program Files\\" ); // or
        //strPath = GetOpenBox( saFiletypes, "C:\\Program Files\\", "Origin" ); // or
        //strPath = GetOpenBox( saFiletypes, "C:\\Program Files\\", "Origin", "OpenOPJ" );
        if( strPath.IsEmpty() )
            out_str( "User has cancelled the Open dialog box." );
        else
            printf( "The file chosen is %s\n.", strPath );

Summary:
Sample data:
Header file: sys_utils.h
See also:
Function: GetOpenBox
Prototype:
string GetOpenBox( FDLogUseGroup nFDLogUseGroup, LPCSTR lpcszPath = NULL, LPCSTR lpcszFilename = NULL,LPCSTR lpcszDialogName = NULL )
Remarks: An FDLog.UseGroup version of GetOpenBox that uses an enumerated FDLog.UseGroup code to indicate the set of file types to list. See sys_utils.h or the Origin.ini file for a list of the enumerated FDLOG.UseGroup codes.
Parameters:
nFDLogUseGroup=A LabTalk FDLog.UseGroup code as enumerated in sys_utils.h and in
the Origin.ini file
lpcszPath=Initial path when dialog opens, default NULL uses FDLog tracking
lpcszFileName=Initial filename when dialog opens, default NULL uses an empty string
lpcszDialogName=Title of the dialog box, default NULL uses "Open"

Return values:
Returns the path and filename of a selected file or an empty string if Cancel button
in dialog box is clicked.

Example:
        string strPath;
        strPath = GetOpenBox( FDLOG_ORIGIN ); // or
        //strPath = GetOpenBox( FDLOG_EXCEL, "C:\\Program Files\\" ); // or
        //strPath = GetOpenBox( FDLOG_ASCII, "C:\\Program Files\\", "Origin" ); // or
        //strPath = GetOpenBox( FDLOG_SCRIPT, "C:\\Program Files\\", "Origin", "OpenOGS" );
        if( strPath.IsEmpty() )
            out_str( "User has cancelled the Open dialog box." );
        else
            printf( "The file chosen is %s\n.", strPath );

Summary:
Sample data:
Header file: sys_utils.h
See also:
Function: GetOpenBox
Prototype:
string GetOpenBox( LPCSTR lpcszFileType = "*.* All Files", LPCSTR lpcszPath = NULL, LPCSTR lpcszFilename = NULL,LPCSTR lpcszDialogName = NULL )
Remarks: An easier to use version of GetOpenBox that works for a single file type.
Parameters:
lpcszFileType="*.ext description", or "[decription (*.ext)] *.ext", or just "*.ext"
lpcszPath=Initial path when dialog opens, default NULL uses FDLog tracking
lpcszFileName=Initial filename when dialog opens, default NULL uses an empty string
lpcszDialogName=Title of the dialog box, default NULL uses "Open"

Return values:
Returns the path and filename of a selecetd file or an empty string if Cancel button
in dialog box is clicked.

Example:
        string strPath;
        strPath = GetOpenBox(); // or
        //strPath = GetOpenBox( "[Old version (*.ORG)] *.ORG" ); // or
        //strPath = GetOpenBox( "*.OPJ"); // or
        //strPath = GetOpenBox( "*.ocw Workspace", GetAppPath() + "OriginC\\" ); // or
        //strPath = GetOpenBox( "*.ocw Workspace", GetAppPath() + "OriginC\\", "Origin" ); // or
        //strPath = GetOpenBox( "*.ocw Workspace", "C:\\Program Files\\", "Origin", "Open Workspace" );
        if( strPath.IsEmpty() )
            out_str( "User has cancelled the Open dialog box." );
        else
            printf( "The file chosen is %s\n.", strPath );

Summary:
Sample data:
Header file: sys_utils.h
See also:


GetSaveAsBox

Function: GetSaveAsBox
Prototype:
string GetSaveAsBox( LPCSTR lpcszFileType = "*.* All Files", LPCSTR lpcszPath = NULL, LPCSTR lpcszFilename = NULL,LPCSTR lpcszDialogName = NULL )
Remarks: An easier to use version of GetSaveAsBox that works for a single file type.
Parameters:
lpcszFileType="*.ext description", or "[decription (*.ext)] *.ext", or just "*.ext"
lpcszPath=Initial path when dialog opens, default NULL uses FDLog tracking
lpcszFileName=Initial filename when dialog opens, default NULL uses an empty string
lpcszDialogName=Title of the dialog box, default NULL uses "SaveAs"

Return values:
Returns the path and filename of a selecetd file or an empty string if Cancel button
in dialog box is clicked.

Example:
        string strPath;
        strPath = GetSaveAsBox(); // or
        //strPath = GetSaveAsBox( "[Old version (*.ORG)] *.ORG" ); // or
        //strPath = GetSaveAsBox( "*.OPJ"); // or
        //strPath = GetSaveAsBox( "*.ocw Workspace", GetAppPath() + "OriginC\\" ); // or
        //strPath = GetSaveAsBox( "*.ocw Workspace", GetAppPath() + "OriginC\\", "Origin" ); // or
        //strPath = GetSaveAsBox( "*.ocw Workspace", "C:\\Program Files\\", "Origin", "SaveAs Workspace" );
        if( strPath.IsEmpty() )
            out_str( "User has cancelled the SaveAs dialog box." );
        else
            printf( "The file chosen is %s\n.", strPath );

Summary:
Sample data:
Header file: sys_utils.h
See also:
Function: GetSaveAsBox
Prototype:
string GetSaveAsBox( StringArray &saFiletypes, LPCSTR lpcszPath = NULL, LPCSTR lpcszFilename = NULL,LPCSTR lpcszDialogName = NULL )
Remarks: Open an FDLog SaveAs dialog box passing the file types to list in an array of strings.
Parameters:
saFiletypes=Vector containing file types to list in the dialog box, each element
of vector must follow syntax of LabTalk FDLog.TypeN$ object property
lpcszPath=Initial path when dialog opens, default NULL uses FDLog tracking
lpcszFileName=Initial filename when dialog opens, default NULL uses an empty string
lpcszDialogName=Title of the dialog box, default NULL uses "SaveAs"

Return values:
Returns the path and filename of a selecetd file or an empty string if Cancel button
in dialog box is clicked.

Example:
        string strPath;
        StringArray saFiletypes;
        saFiletypes.SetSize( 3 );
        saFiletypes[0]="[Project (*.OPJ)] *.OPJ";
        saFiletypes[1]="[Old version (*.ORG)] *.ORG";
        saFiletypes[2]="[Worksheets (*.OGW)] *.OGW";
        strPath = GetSaveAsBox( saFiletypes ); // or
        //strPath = GetSaveAsBox( saFiletypes, "C:\\Program Files\\" ); // or
        //strPath = GetSaveAsBox( saFiletypes, "C:\\Program Files\\", "Origin" ); // or
        //strPath = GetSaveAsBox( saFiletypes, "C:\\Program Files\\", "Origin", "SaveAsOPJ" );
        if( strPath.IsEmpty() )
            out_str( "User has cancelled the SaveAs dialog box." );
        else
            printf( "The file chosen is %s\n.", strPath );

Summary:
Sample data:
Header file: sys_utils.h
See also:
Function: GetSaveAsBox
Prototype:
string GetSaveAsBox( FDLogUseGroup nFDLogUseGroup, LPCSTR lpcszPath = NULL, LPCSTR lpcszFilename = NULL,LPCSTR lpcszDialogName = NULL )
Remarks: An FDLog.UseGroup version of GetSaveAsBox that uses an enumerated FDLog.UseGroup code to indicate the set of file types to list. See sys_utils.h or the Origin.ini file for a list of the enumerated FDLOG.UseGroup codes.
Parameters:
nFDLogUseGroup=A LabTalk FDLog.UseGroup code as enumerated in sys_utils.h and in
the Origin.ini file
lpcszPath=Initial path when dialog opens, default NULL uses FDLog tracking
lpcszFileName=Initial filename when dialog opens, default NULL uses an empty string
lpcszDialogName=Title of the dialog box, default NULL uses "SaveAs"

Return values:
Returns the path and filename of a selected file or an empty string if Cancel button
in dialog box is clicked.

Example:
        string strPath;
        strPath = GetSaveAsBox( FDLOG_ORIGIN ); // or
        //strPath = GetSaveAsBox( FDLOG_EXCEL, "C:\\Program Files\\" ); // or
        //strPath = GetSaveAsBox( FDLOG_ASCII, "C:\\Program Files\\", "Origin" ); // or
        //strPath = GetSaveAsBox( FDLOG_SCRIPT, "C:\\Program Files\\", "Origin", "SaveAsOGS" );
        if( strPath.IsEmpty() )
            out_str( "User has cancelled the SaveAs dialog box." );
        else
            printf( "The file chosen is %s\n.", strPath );

Summary:
Sample data:
Header file: sys_utils.h
See also:


InputBox

Function: InputBox
Prototype:
string InputBox(LPCSTR lpcszMsg, DWORD dwOption = 0)
Remarks: Opens a simple input box for entering a string.
Parameters:
lpcszMsg = Pointer to a string containing a message used to prompt the user.
dwOption = not used (must be 0)

Return values:
the string which has been input

Example:
        void	run_InputBox()
        {
            string		strInput = InputBox("Please enter your name");

            printf("You entered: %s\n", strInput);

        }

Summary:
Sample data:
Header file: utilities.h
See also:


OptionalMessage

Function: OptionalMessage
Prototype:
int OptionalMessage(LPCSTR lpcszMessage, int iBtnOpts, LPCSTR lpcszAuxStr = NULL)
Remarks: Display message box.
Parameters:
lpcszMessage = Keyword for the text of the message to display.
iBtnOpts = Message box style; can be one of: OM_RETURN_NOT_PRESENT, OM_RETURN_YNC_CANCEL, OM_RETURN_OK, OM_RETURN_CANCEL, OM_RETURN_YES, OM_RETURN_NO
lpcszAuxStr = Optional string - reserved.

Return values:
User choice; can be one of: MB_OK, MB_OKCANCEL, MB_YESNO, MB_YESNOCANCEL.

Example:
        BOOL bDelete = FALSE;
          if ( OM_RETURN_OK == OptionalMessage( "DestroyOperationWithSource", MB_YESNO ) )
            bDelete = TRUE;

Summary:
Sample data:
Header file: utilities.h
See also:


SetDataDisplayText

Function: SetDataDisplayText
Prototype:
BOOL SetDataDisplayText(LPCTSTR lpcszText)
Remarks: Set the text in the Data Display control. The Data Display is usually used for display Screen Reader coordinates. This function will also show the Data Display control if it is not already shown
Parameters:
lpcszText = text string to set, use NULL to close the Data Display if not docked.

Return values:
void

Example:
        // test hide;// to hide the Data Display control
        // test "what ever";// to put text into Data Display control
        void	test(string str)
        {
            if(str.CompareNoCase("hide")==0)
                SetDataDisplayText(NULL);
            else
                SetDataDisplayText(str);
        }

Summary:
Sample data:
Header file: utilities.h
See also:


nag_free

Function: nag_free
Prototype:
void nag_free(void * pvoid)
Remarks: Free memory allocated by NAG functions.
Parameters:

Return values:

Example:

Summary: Free memory allocated by NAG functions.
Sample data:
Header file: OC_nag.h
See also:


nag_fft_real

Function: nag_fft_real
Prototype:
int nag_fft_real(int n,double x[])
Remarks: calculates the discrete Fourier transforms of a sequence of n real data values.
Parameters:
n
  the number of data values.
x[]
  Input: contained in x[j], for j = 0, 1, . . . , n - 1.  Output: the discrete Fourier transform stored in Hermitian form.

Return values:
The function returns NAG error code or 0 if no error.
137: At least one of the prime factors of n is greater than 19.
138: n has more than 20 prime factors.
12:  On entry, n must not be less than or equal to 1: n = _value_.
successfully call of the nag_fft_real function.

Example:
    This piece of code reads in a sequence of real data values from a worksheet column, and
    prints their discrete Fourier transform (as computed by nag fft real), after expanding
    it from Hermitian form into a full complex sequence.
    Assume "Data1" Worksheet has 3 columns, the first column contain 7 data, and we want to
    put result complex form real part in the second column and imag part in the third column.

    int n = 7, j, success, n2, nj;
    //Attach two Datasets to these 2 columns
    Dataset xx("data1",0);
    Dataset aa("data1",1);
    Dataset bb("data1",2);
    //Because Dataset cannot be the parameter of function, but vector can be.
    vector x = xx, a = aa, b = bb;
    success = nag_fft_real(n, x);

    if(success == 0)
    {
        a[0] = x[0];
        b[0] = 0.0;
        n2 = (n-1)/2;
        for (j = 1; j<=n2; j++)
        {
            nj = n - j;
            a[j] = x[j];
            a[nj] = x[j];
            b[j] = x[nj];
            b[nj] = -x[nj];
        }
        if (n % 2==0)
        {
            a[n2+1] = x[n2+1];
            b[n2+1] = 0.0;
        }
    }
    //write the result to worksheet.
    aa = a;
    bb = b;

    This program reads in a sequence of real data values, and prints their discrete
    Fourier transform (as computed by nag fft real), after expanding it from
    Hermitian form into a full complex sequence.  It then performs an inverse
    transform using nag conjugate hermitian (c06gbc) and nag fft hermitian (c06ebc),
    and prints the sequence so obtained alongside the original data values.

void test_nag_fft_real()
{

    int j, n = 7, n2, nj;
    double a[20], b[20], xx[20];
    double x[20] = {0.34907, 0.54890, 0.74776, 0.94459, 1.13850, 1.32850, 1.51370};
    int success;

    for (j = 0; j<n; j++)
        xx[j] = x[j];

    success = nag_fft_real(n, x);
    if(success == 0)
    {
        a[0] = x[0];
        b[0] = 0.0;
        n2 = (n-1)/2;
        for (j = 1; j<=n2; j++)
        {
            nj = n - j;
            a[j] = x[j];
            a[nj] = x[j];
            b[j] = x[nj];
            b[nj] = -x[nj];
        }
        if (n % 2==0)
        {
            a[n2+1] = x[n2+1];
            b[n2+1] = 0.0;
        }
        printf("\nComponents of discrete Fourier transform\n");
        printf("\n Real Imag \n\n");
        for (j = 0; j<n; j++)
            printf("%3ld %10.5f %10.5f\n", j, a[j], b[j]);

        nag_conjugate_hermitian(n, x);
        nag_fft_hermitian(n, x);
        printf("\nOriginal sequence as restored by inverse transform\n");
        printf("\n Original Restored\n\n");
        for (j = 0; j<n; j++)
            printf("%3ld %10.5f %10.5f\n", j, xx[j], x[j]);
    }
    else
    printf("Function c06eac has some problems.");
}

    The output is following:

    Components of discrete Fourier transform

              Real 		 Imag

    0 		 2.48361 	 0.00000
    1 		-0.26599 	 0.53090
    2 		-0.25768 	 0.20298
    3 		-0.25636 	 0.05806
    4 		-0.25636 	-0.05806
    5 		-0.25768 	-0.20298
    6 		-0.26599 	-0.53090

    Original sequence as restored by inverse transform

            Original 		Restored

    0 		0.34907 		0.34907
    1 		0.54890 		0.54890
    2 		0.74776 		0.74776
    3 		0.94459 		0.94459
    4 		1.13850 		1.13850
    5 		1.32850 		1.32850
    6 		1.51370 		1.51370

Summary: Given a sequence of n real data values xj, for j = 0, 1, . . . , n - 1, this function calculates their discrete Fourier transform.
Sample data:
Header file: OCN_c06.h
See also:


nag_fft_hermitian

Function: nag_fft_hermitian
Prototype:
int nag_fft_hermitian(int n,double x[])
Remarks: calculates the discrete Fourier transforms of a Hermitian sequence of n.
Parameters:
n
  the number of data values.
x[]
  Input:the number of data values.  Output: the components of the discrete Fourier transforms.

Return values:
The function returns NAG error code or 0 if no error.
137: At least one of the prime factors of n is greater than 19.
138: n has more than 20 prime factors.
12:  On entry, n must not be less than or equal to 1: n = _value_.
successfully call of the function nag_fft_hermitian function.

Example:
    Assume "Data1" Worksheet has 2 columns, the first column contain 7 data.  This piece of code reads
    in a sequence of first column data values and we want to put the result which is the discrete
    Fourier transforms of a Hermitian sequence of nin the second column.

    int n = 7, success;
    //Attach two Datasets to these 2 columns
    Dataset xx("data1",0);
    Dataset aa("data1",1);
    //Because Dataset cannot be the parameter of function, but vector can be.
    vector x = xx;
    success = nag_fft_hermitian(n, x);
    //put the result, the discrete Fourier transforms to "data1" second column.
    if(success == 0)
        aa = x;

    This program reads in a sequence of real data values which is assumed to be a Hermitian sequence of
    complex data values stored in Hermitian form. The input sequence is expanded into a full complex
    sequence and printed alongside the original sequence. The discrete Fourier transform (as computed
    by nag_fft_hermitian) is printed out.  The program then performs an inverse transform using
    nag_fft_real (c06eac) and nag_conjugate_hermitian (c06gbc), and prints the sequence so obtained
    alongside the original data values.

void test_nag_fft_hermitian()
{
    int j, n, n2, nj;
    double u[20], v[20], xx[20];
    double x[20] = {0.34907, 0.54890, 0.74776, 0.94459, 1.13850, 1.32850, 1.51370};
    int success;
    n  = 7;

    for (j = 0; j<n; j++)
        xx[j] = x[j];

    u[0] = x[0];
    v[0] = 0.0;
    n2 = (n-1)/2;
    for (j = 1; j<=n2; j++)
    {
        nj = n - j;
        u[j] = x[j];
        u[nj] = x[j];
        v[j] = x[nj];
        v[nj] = -x[nj];
    }
    if (n % 2==0)
    {
        u[n2+1] = x[n2+1];
        v[n2+1] = 0.0;
    }

    printf("\nOriginal and corresponding complex sequence\n");
    printf("\n Data Real Imag \n\n");
    for (j = 0; j<n; j++)
        printf("%3ld %10.5f %10.5f %10.5f\n", j, x[j], u[j], v[j]);

    success = nag_fft_hermitian(n, x);

    if(success == 0)
    {
        printf("\nComponents of discrete Fourier transform\n\n");
        for (j = 0; j<n; j++)
            printf("%3ld %10.5f\n", j, x[j]);

        nag_fft_real(n, x);

        nag_conjugate_hermitian(n, x);

        printf("\nOriginal sequence as restored by inverse transform\n");
        printf("\n Original Restored\n\n");
        for (j = 0; j<n; j++)
            printf("%3ld %10.5f %10.5f\n", j, xx[j], x[j]);
    }
    else
        printf("function c06ebc has some problem\n");
}

    The output is following:

    Original and corresponding complex sequence

        Data 		Real 		 Imag

    0 	0.34907 	0.34907 	 0.00000
    1 	0.54890 	0.54890 	 1.51370
    2 	0.74776 	0.74776 	 1.32850
    3 	0.94459 	0.94459  	 1.13850
    4 	1.13850	 	0.94459 	-1.13850
    5 	1.32850 	0.74776 	-1.32850
    6 	1.51370 	0.54890 	-1.51370

    Components of discrete Fourier transform

    0	 1.82616
    1 	 1.86862
    2 	-0.01750
    3 	 0.50200
    4 	-0.59873
    5 	-0.03144
    6 	-2.62557

    Original sequence as restored by inverse transform

        Original 	Restored

    0 	0.34907 	0.34907
    1 	0.54890 	0.54890
    2 	0.74776 	0.74776
    3 	0.94459 	0.94459
    4 	1.13850 	1.13850
    5 	1.32850 	1.32850
    6 	1.51370 	1.51370

Summary: Given a Hermitian sequence of n complex data values z[j] (i.e., a sequence such that z0 is real and z(n-j) is the complex conjugate of z[j], for j = 1, 2, . . . , (n - 1), this function calculates their discrete Fourier transform.
Sample data:
Header file: OCN_c06.h
See also:


nag_fft_complex

Function: nag_fft_complex
Prototype:
int nag_fft_complex(int n,double x[],double y[])
Remarks: calculates the discrete Fourier transforms of a sequence of n complex data values.
Parameters:
n
  the number of data values
x[]
  Input:contained in x[j] , the real part of z[j], for j = 0, 1, . . ., n . 1.  Output: the real parts a[k] of the components of the discrete Fourier transform. a[k] is contained in x[k], for k = 0, 1, . . ., n . 1.
y[]
  Input: contain y[j] , the imaginary part of z[j], for j = 0, 1, . . . , n . 1.  Output: the imaginary parts b[k] of the components of the discrete Fourier transform. b[k] is contained in y[k], for k = 0, 1, . . ., n . 1.

Return values:
The function returns NAG error code or 0 if no error.
137: At least one of the prime factors of n is greater than 19.
138: n has more than 20 prime factors.
successfully call of the nag_fft_complex function.

Example:
    Assume "Data1" Worksheet has 4 columns, the first two columns contain 7 data each.  The first
    column is the real part of the original complex data and second column is the imag part of
    original complex data.  This piece of code reads in a sequence of these 7 complex data values
    and put the result which is the discrete Fourier transforms of the original complex data values
    to the third and fourth column.  The third column is the real part and the fourth column is the
    imag part.

    int n = 7, success;
    //Attach two Datasets to these 2 columns
    Dataset xx("data1",0);
    Dataset yy("data1",1);
    Dataset aa("data1",2);
    Dataset bb("data1",3);
    //Because Dataset cannot be the parameter of function, but vector can be.
    vector x = xx, y = yy;
    success = nag_fft_complex(n, x, y);
    //put the result back to worksheet "data1", the third column and the fourth column.
    aa = x;
    bb = y;

    This program reads in a sequence of complex data values and prints their discrete
    Fourier transform.  It then performs an inverse transform using nag_conjugate_complex (c06gcc)
    and nag fft complex, and prints the sequence so obtained alongside the original data values.

void test_nag_fft_complex()
{
    #define NMAX 20
    int j, n ;
    int success;
    double xx[20], yy[20];
    double x[20] = {0.34907, 0.54890, 0.74776, 0.94459, 1.13850, 1.32850, 1.51370};
    double y[20] = {-0.37168, -0.35669, -0.31175, -0.23702, -0.13274, 0.00074, 0.16298};
     n = 7;

    for (j = 0; j<n; ++j)
    {
        xx[j] = x[j];
        yy[j] = y[j];
    }

    success = nag_fft_complex(n, x, y);

    printf("\nComponents of discrete Fourier transforms\n\n");
    printf(" Real Imag\n\n");
    for (j = 0; j<n; ++j)
        printf("%3ld %10.5f %10.5f\n", j, x[j], y[j]);

    nag_conjugate_complex(n, y);

    nag_fft_complex(n, x, y);

    nag_conjugate_complex(n, y);

    printf("\nOriginal sequence as restored byinverse transform\n");
    printf("\n Original Restored\n");
    printf(" Real Imag Real Imag\n\n");
    for (j = 0; j<n; ++j)
        printf("%3ld %10.5f %10.5f %10.5f %10.5f\n", j, xx[j], yy[j], x[j], y[j]);
}

    The output is following:

    Components of discrete Fourier transform

         Real 			 Imag

    0 	 2.48361 		-0.47100
    1 	-0.55180 	 	 0.49684
    2 	-0.36711 		 0.09756
    3 	-0.28767 		-0.05865
    4 	-0.22506 		-0.17477
    5 	-0.14825 		-0.30840
    6 	 0.01983 		-0.56496

    Original sequence as restored byinverse transform

              Original 				  Restored
        Real 		  Imag 		  Real 		  Imag

    0 	0.34907 	-0.37168 	0.34907 	-0.37168
    1 	0.54890 	-0.35669 	0.54890 	-0.35669
    2 	0.74776 	-0.31175 	0.74776 	-0.31175
    3 	0.94459 	-0.23702 	0.94459 	-0.23702
    4 	1.13850 	-0.13274 	1.13850  	-0.13274
    5 	1.32850 	 0.00074 	1.32850 	 0.00074
    6 	1.51370 	 0.16298 	1.51370 	 0.16298

Summary: Given a sequence of n complex data values z[j], for j = 0, 1, . . . , n . 1, this function calculates their discrete Fourier transform.
Sample data:
Header file: OCN_c06.h
See also:


nag_convolution_real

Function: nag_convolution_real
Prototype:
int nag_convolution_real(Nag_VectorOp operation,int n,double x[],double y[])
Remarks: calculates the circular convolution or correlation of two real vectors of period n.
Parameters:
operation
  the computation to be performed.
n
  the number of values.
x[]
  Input:the elements of one period of the vector x. Output:the corresponding elements of the discrete convolution or correlation
y[]
  Input:the elements of one period of the vector y. Output:the discrete Fourier transform of the convolution

Return values:
The function returns NAG error code or 0 if no error.
137: At least one of the prime factors of n is greater than 19.
138: n has more than 20 prime factors.
12:  On entry, n must not be less than or equal to 1: n = _value_.
70:  On entry, parameter operation has an illegal value.
successfully call of the nag_convolution_real function.

Example:
    Assume "Data1" Worksheet has 4 columns, the first two columns contain 9 data each.  This piece
    of code calculates the circular convolution or correlation of two real vectors of period 9 and
    put the result the circular convolution to the third column and correlation to the fourth column.

    int n = 9;
    //Attach four Datasets to these 4 columns
    Dataset dxa("data1",0);
    Dataset dya("data1",1);
    Dataset dxb("data1",2);
    Dataset dyb("data1",3);
    //Dataset cannot be the parameter of function, but vector can be.
    vector xa = dxa, ya = dya, xb = dxa, yb = dya;

    nag_convolution_real(NAG_Convolution, n, xa, ya);
    nag_convolution_real(Nag_Correlation, n, xb, yb);

    //put the result Convolution to the worksheet "data1" third column and Correlation
    //to the fourth column.
    dxb = xa;
    dyb = xb;

    This program reads in the elements of one period of two real vectors x and y and
    prints their discrete convolution and correlation (as computed by nag_convolution_real).
    In realistic computations the number of data values would be much larger.

void test_nag_convolution_real()
{
    int j, n;
    double xb[64], yb[64];
    double xa[64] = {1.0, 1.0, 1.0, 1.0, 1.0, 0.0, 0.0, 0.0, 0.0};
    double ya[64] = {0.5, 0.5, 0.5, 0.5, 0.0, 0.0, 0.0, 0.0, 0.0};
    n = 9;

    for (j = 0; j<n; ++j)
    {
        xb[j]= xa[j];
        yb[j]= ya[j];
    }

    nag_convolution_real(Nag_Convolution, n, xa, ya);

    nag_convolution_real(Nag_Correlation, n, xb, yb);

    printf("\n Convolution Correlation\n\n");
    for (j = 0; j<n; ++j)
        printf("%5ld %13.5f %13.5f\n", j, xa[j], xb[j]);
}

    The output is following:

         Convolution 	Correlation

    0 	0.50000 		2.00000
    1 	1.00000 		1.50000
    2 	1.50000 		1.00000
    3 	2.00000 		0.50000
    4 	2.00000 		0.00000
    5 	1.50000 		0.50000
    6 	1.00000 		1.00000
    7 	0.50000 		1.50000
    8 	0.00000 		2.00000

Summary: calculates the circular convolution or correlation of two real vectors of period n.
Sample data:
Header file: OCN_c06.h
See also:


nag_fft_multiple_real

Function: nag_fft_multiple_real
Prototype:
int nag_fft_multiple_real(int m,int n,double x[],const double trig[])
Remarks: computes the discrete Fourier transforms of m sequences, and each contains n real data values.
Parameters:
m
  the number of sequences to be transformed.
n
  the number of real values in each sequence.
x[]
  Input:the m data sequences must be stored in x consecutively.  Output: the m discrete Fourier transforms in Hermitian form, stored consecutively, overwrite the corresponding original sequences.
trig[]
  trigonometric coefficients are returned by a call of nag_fft_init_trig (c06gzc).

Return values:
The function returns NAG error code or 0 if no error.
11:  On entry, m must not be less than 1: m = _value_.  On entry, n must not be less than 1: n = _value_.
139: Value of n and trig array are incompatible or trig array is not initialized.
73:  Memory allocation failed.
successfully call of the nag_fft_multiple_real function.

Example:
    Assume "Data1" Worksheet has 2 columns, the first column contain 18 data. This piece of code
    computes the discrete Fourier transforms of 3 sequences and each contains 6 data values.  The
    result will be put in the second column (Discrete Fourier transforms in Hermitian format).

    double trig[40];
    int m = 3, n = 6;
    //Attach two Datasets to these 2 columns
    Dataset xx("data1",0);
    Dataset yy("data1",1);
    //Dataset cannot be the parameter of function, but vector can be.
    vector x = xx;
    nag_fft_init_trig(n, trig);
    nag_fft_multiple_real(m, n, x, trig);
    //put the result to worksheet "data1" the second column.
    yy = x;

    This program reads in sequences of real data values and prints their discrete Fourier
    transforms (as computed by nag_fft_multiple real). The Fourier transforms are expanded
    into full complex form using nag_multiple_hermitian to complex (c06gsc) and printed. Inverse
    transforms are then calculated by calling nag_multiple _conjugate_hermitian (c06gqc) followed by
    nag_fft_multiple_hermitian (c06fqc) showing that the original sequences are restored.

void test_nag_fft_multiple_real()
{
    #define MMAX 5
    #define NMAX 20
    double trig[40];
    int i, j, m, n;
    double u[100], v[100];
    double x[100] = {0.3854, 0.6772, 0.1138, 0.6751, 0.6362, 0.1424,
                     0.5417, 0.2983, 0.1181, 0.7255, 0.8638, 0.8723,
                     0.9172, 0.0644, 0.6037, 0.6430, 0.0428, 0.4815};
    m =3;
    n =6;

    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if((i % 6 )== 5 && (i != n-1 ))
                 printf("\n " );
        }
        printf("\n");
    }

    nag_fft_init_trig(n, trig);

    nag_fft_multiple_real(m, n, x, trig);
    printf("\nDiscrete Fourier transforms in Hermitian format\n\n");

    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\n");
    }

    nag_multiple_hermitian_to_complex(m, n, x, u, v);
    printf("\nFourier transforms in full complex form\n\n");
    for (j = 0; j<m; ++j)
    {
        printf("Real");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", u[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\nImag");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", v[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\n\n");
    }

    nag_multiple_conjugate_hermitian(m, n, x);
    nag_fft_multiple_hermitian(m, n, x, trig);
    printf ("\nOriginal data as restored by inverse transform\n\n");
    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if(i % 6 == 5 &&  i!= n-1 )
                 printf("\n " );
        }
        printf("\n");
    }
}

    The output is following:

    m = 3 n = 6

    Original data values

            0.3854 	  0.6772 	 0.1138 	 0.6751 	 0.6362 	 0.1424
            0.5417 	  0.2983 	 0.1181 	 0.7255 	 0.8638 	 0.8723
            0.9172 	  0.0644 	 0.6037 	 0.6430 	 0.0428 	 0.4815

    Discrete Fourier transforms in Hermitian format

            1.0737 	 -0.1041 	 0.1126 	-0.1467 	-0.3738 	-0.0044
            1.3961 	 -0.0365 	 0.0780 	-0.1521 	-0.0607 	 0.4666
            1.1237 	  0.0914 	 0.3936 	 0.1530 	 0.3458 	-0.0508

    Fourier transforms in full complex form

    Real 	1.0737 	 -0.1041 	 0.1126 	-0.1467 	 0.1126 	-0.1041
    Imag 	0.0000 	 -0.0044 	-0.3738 	 0.0000 	 0.3738  	 0.0044

    Real 	1.3961 	 -0.0365 	 0.0780 	-0.1521 	 0.0780 	-0.0365
    Imag 	0.0000 	  0.4666 	-0.0607 	 0.0000 	 0.0607 	-0.4666

    Real 	1.1237 	  0.0914 	 0.3936 	 0.1530 	 0.3936 	 0.0914
    Imag 	0.0000 	 -0.0508 	 0.3458 	 0.0000  	-0.3458 	 0.0508

    Original data as restored by inverse transform

            0.3854 	  0.6772 	 0.1138 	 0.6751 	 0.6362 	 0.1424
            0.5417 	  0.2983 	 0.1181 	 0.7255 	 0.8638 	 0.8723
            0.9172 	  0.0644 	 0.6037 	 0.6430 	 0.0428 	 0.4815

Summary: Given m sequences of n real data values x[p][j], for j = 0, 1, . . . , n - 1; p = 1, 2, . . .,m, this function simultaneously calculates the Fourier transforms of all the sequences.
Sample data:
Header file: OCN_c06.h
See also:


nag_fft_multiple_hermitian

Function: nag_fft_multiple_hermitian
Prototype:
int nag_fft_multiple_hermitian(int m,int n,double x[],const double trig[])
Remarks: computes the discrete Fourier transforms of m Hermitian sequences, each containing n complex data values.
Parameters:
m
  the number of sequences to be transformed
n
  the number of data values in each sequence
x[]
  Input: the m Hermitian sequences must be stored consecutively in x in Hermitian form.  Output: the components of the m discrete Fourier transforms, are stored consecutively.
trig[]
  trigonometric coefficients are returned by a call of nag_fft_init_trig (c06gzc).

Return values:
The function returns NAG error code or 0 if no error.
11:  On entry, m must not be less than 1: m = _value_.  On entry, n must not be less than 1: n = _value_.
139: Value of n and trig array are incompatible or trig array is not initialized.
73:  Memory allocation failed.
successfully call of the nag_fft_multiple_hermitian function.

Example:
    Assume "Data1" Worksheet has 2 columns, the first column contain 18 data. This piece of code
    computes the discrete Fourier transforms of 3 sequences and each contains 6 data values.  The
    result will be put in the second column (Discrete Fourier transforms in Hermitian format).

    double trig[40], u[40], v[40];
    int m = 3, n = 6;
    //Attach two Datasets to these 2 columns
    Dataset xx("data1",0);
    Dataset yy("data1",1);
    //Dataset cannot be the parameter of function, but vector can be.
    vector x = xx;
    //expand the sequences into full complex form.
    nag_multiple_hermitian_to_complex(m, n, x, u, v);
    nag_fft_init_trig(n, trig);
    nag_fft_multiple_hermitian(m, n, x, trig);
    //put the result to worksheet "data1" the second column.
    yy = x;

    This program reads in sequences of real data values which are assumed to be Hermitian sequences
    of complex data stored in Hermitian form. The sequences are expanded into full complex form
    using nag_multiple_hermitian_to_complex (c06gsc) and printed. The discrete Fourier transforms
    are then computed (using nag_fft_multiple_hermitian) and printed out. Inverse transforms are then
    calculated by calling nag_fft_multiple_real (c06fpc) followed by nag_multiple_conjugate_hermitian
    (c06gqc) showing that the original sequences are restored.

void test_nag_fft_multiple_hermitian()
{
    #define MMAX 5
    #define NMAX 20
    double trig[40];
    int i, j, m, n;
    double u[100], v[100];
    double x[100] = {0.3854, 0.6772, 0.1138, 0.6751, 0.6362, 0.1424,
                     0.5417, 0.2983, 0.1181, 0.7255, 0.8638, 0.8723,
                     0.9172, 0.0644, 0.6037, 0.6430, 0.0428, 0.4815};
    m = 3;
    n = 6;

    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if((i % 6 )== 5 && (i != n-1 ))
                 printf("\n " );
        }
        printf("\n");
    }
    nag_multiple_hermitian_to_complex(m, n, x, u, v);
    printf("\nOriginal data written in full complex form\n\n");
    for (j = 0; j<m; ++j)
    {
        printf("Real");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", u[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\nImag");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", v[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\n\n");
    }

    nag_fft_init_trig(n, trig);
    nag_fft_multiple_hermitian(m, n, x, trig);
    printf ("\nDiscrete Fourier transforms (real values)\n\n");
    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if(i % 6 == 5 &&  i!= n-1 )
                 printf("\n " );
         }
        printf("\n");
    }

    nag_fft_multiple_real(m, n, x, trig);
    nag_multiple_conjugate_hermitian(m, n, x);
    printf ("\nOriginal data as restored by inverse transform\n\n");
    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if(i % 6 == 5 &&  i!= n-1 )
                 printf("\n " );
        }
        printf("\n");
    }
}

    The output is following:

    m = 3 n = 6

    Original data values

            0.3854 		0.6772 		0.1138 		0.6751 		0.6362 	 	 0.1424
            0.5417 		0.2983 		0.1181 		0.7255 		0.8638 	 	 0.8723
            0.9172 		0.0644 		0.6037 		0.6430 		0.0428 	 	 0.4815

    Original data written in full complex form

    Real 	0.3854 		0.6772 		0.1138 		0.6751		0.1138 	 	 0.6772
    Imag 	0.0000 		0.1424 		0.6362 		0.0000	   -0.6362  	-0.1424
    Real 	0.5417 		0.2983 		0.1181 		0.7255		0.1181 	 	 0.2983
    Imag 	0.0000 		0.8723 		0.8638 		0.0000	   -0.8638 		-0.8723
    Real 	0.9172 		0.0644 		0.6037 		0.6430		0.6037 	 	 0.0644
    Imag 	0.0000 		0.4815 		0.0428 		0.0000	   -0.0428 		-0.4815

    Discrete Fourier transforms (real values)

            1.0788 		0.6623 	   -0.2391 	   -0.5783 	  	0.4592 		-0.4388
            0.8573 		1.2261 		0.3533 	   -0.2222 	 	0.3413 		-1.2291
            1.1825 		0.2625 		0.6744 		0.5523  	0.0540 		-0.4790

    Original data as restored by inverse transform

            0.3854 		0.6772 		0.1138 		0.6751 		0.6362 		 0.1424
            0.5417 		0.2983 		0.1181 		0.7255 		0.8638 		 0.8723
            0.9172 		0.0644 		0.6037 		0.6430 		0.0428 		 0.4815

Summary: computes the discrete Fourier transforms of m Hermitian sequences, each contains n complex data values.
Sample data:
Header file: OCN_c06.h
See also:


nag_fft_multiple_complex

Function: nag_fft_multiple_complex
Prototype:
int nag_fft_multiple_complex(int m,int n,double x[],double y[],const double trig[])
Remarks: computes the discrete Fourier transforms of m sequences, each containing n complex data values.
Parameters:
m
  the number of sequences to be transformed.
n
  the number of data values in each sequence.
x[]
  Input: the real parts of the complex data.  Output: x is overwritten by the real part of the complex transforms.
y[]
  Input: the imaginary parts of the complex data. Output: y is overwritten by the imaginary part of the complex transforms.
trig[]
  trigonometric coefficients are returned by a call of nag_fft_init_trig (c06gzc).

Return values:
The function returns NAG error code or 0 if no error.
11:  On entry, m must not be less than 1: m = _value_.  On entry, n must not be less than 1: n = _value_.
139: Value of n and trig array are incompatible or trig array is not initialized.
73:  Memory allocation failed.
successfully call of the nag_fft_multiple_complex function.

Example:
    Assume "Data1" Worksheet has 4 columns, the first two columns contain 18 data each.  This piece
    of code computes the discrete Fourier transforms of 3 sequences, each containing 6 complex data
    values. and put the result to the third column (real part) and the fourth column (imag part).

    double trig[40];
    int m = 3, n = 6;
    //Attach four Datasets to these 4 columns
    Dataset xx("data1",0);
    Dataset yy("data1",1);
    Dataset dx("data1",2);
    Dataset dy("data1",3);
    //Dataset cannot be the parameter of function, but vector can be.
    vector x = xx, y = yy;
    nag_fft_init_trig(n, trig);
    nag_fft_multiple_complex(m, n, x, y, trig);
    //Put the result to worksheet "data1" the third and fourth column.
    dx = x;
    dy = y;

    This program reads in sequences of complex data values and prints their discrete Fourier
    transforms (as computed by nag_fft_multiple_complex). Inverse transforms are then calculated
    using nag_conjugate_complex (c06gcc) and nag_fft_multiple_complex and printed out, showing that
    the original sequences are restored.

void test_nag_fft_multiple_complex()
{
    #define MMAX 5
    #define NMAX 20
    double trig[40];
    int i, j, m, n;
    double x[100] = {0.3854, 0.6772, 0.1138, 0.6751, 0.6362, 0.1424,
                      0.9172, 0.0644, 0.6037, 0.6430, 0.0428, 0.4815,
                      0.1156, 0.0685, 0.2060, 0.8630, 0.6967, 0.2792};

    double y[100] = {0.5417, 0.2983, 0.1181, 0.7255, 0.8638, 0.8723,
                     0.9089, 0.3118, 0.3465, 0.6198, 0.2668, 0.1614,
                     0.6214, 0.8681, 0.7060, 0.8652, 0.9190, 0.3355};
    m = 3;
    n = 6;

    printf("\nOriginal data values\n\n");
    for (j = 0; j<m; ++j)
    {
        printf("Real");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\nImag");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", y[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\n\n");
    }

    nag_fft_init_trig(n, trig);

    nag_fft_multiple_complex(m, n, x, y, trig);
    printf("\nDiscrete Fourier transforms\n\n");
    for (j = 0; j<m; ++j)
    {
        printf("Real");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\nImag");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", y[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\n\n");
    }

    nag_conjugate_complex(m*n, y);
    nag_fft_multiple_complex(m, n, x, y, trig);
    nag_conjugate_complex(m*n, y );

    printf ("\nOriginal data as restored by inverse transform\n\n");
    for (j = 0; j<m; ++j)
    {
        printf("Real");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\nImag");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", y[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\n\n");
    }
}

    The output is following:

    m = 3 n = 6

    Original data values

    Real 	0.3854 	 0.6772 	0.1138 	 0.6751 	0.6362 	 0.1424
    Imag 	0.5417 	 0.2983 	0.1181 	 0.7255 	0.8638 	 0.8723

    Real 	0.9172 	 0.0644 	0.6037   0.6430 	0.0428 	 0.4815
    Imag 	0.9089 	 0.3118 	0.3465 	 0.6198 	0.2668 	 0.1614

    Real 	0.1156 	 0.0685 	0.2060 	 0.8630 	0.6967 	 0.2792
    Imag 	0.6214 	 0.8681 	0.7060 	 0.8652 	0.9190 	 0.3355

    Discrete Fourier transforms

    Real 	1.0737 	-0.5706 	0.1733 	-0.1467 	0.0518 	 0.3625
    Imag 	1.3961 	-0.0409    -0.2958 	-0.1521 	0.4517 	-0.0321

    Real 	1.1237 	 0.1728 	0.4185 	 0.1530 	0.3686 	 0.0101
    Imag 	1.0677 	 0.0386 	0.7481 	 0.1752 	0.0565 	 0.1403

    Real 	0.9100 	-0.3054 	0.4079 	-0.0785    -0.1193 	-0.5314
    Imag 	1.7617 	 0.0624    -0.0695 	 0.0725 	0.1285 	-0.4335

    Original data as restored by inverse transform

    Real 	0.3854 	 0.6772 	0.1138 	 0.6751 	0.6362 	 0.1424
    Imag 	0.5417 	 0.2983 	0.1181 	 0.7255 	0.8638 	 0.8723

    Real 	0.9172 	 0.0644 	0.6037 	 0.6430 	0.0428 	 0.4815
    Imag 	0.9089 	 0.3118 	0.3465 	 0.6198 	0.2668 	 0.1614

    Real 	0.1156 	 0.0685 	0.2060 	 0.8630 	0.6967 	 0.2792
    Imag 	0.6214 	 0.8681 	0.7060 	 0.8652 	0.9190 	 0.3355

Summary: computes the discrete Fourier transforms of m sequences, each containing n complex data values.
Sample data:
Header file: OCN_c06.h
See also:


nag_fft_2d_complex

Function: nag_fft_2d_complex
Prototype:
int nag_fft_2d_complex(int m,int n,double x[],double y[],const double trigm[],const double trign[])
Remarks: computes the two-dimensional discrete Fourier transform of a bivariate sequence of complex data values
Parameters:
m
  the number of rows of the bivariate data sequence.
n
  : the number of columns of the bivariate data sequence.
x[]
  Input: the real parts of the complex data.  Output: the real part of the corresponding elements of the computed transform.
y[]
  Input: the imaginary parts of the complex data.  Output: the imaginary part of the corresponding elements of the computed transform.
trigm[]
  trigonometric coefficients are returned by calls of nag_fft_init_trig (c06gzc).
trign[]
  trigonometric coefficients are returned by calls of nag_fft_init_trig (c06gzc).

Return values:
The function returns NAG error code or 0 if no error.
11:  On entry, m must not be less than 1: m = _value_.  On entry, n must not be less than 1: n = _value_.
139: Value of n and trign array are incompatible or trign array is not initialized.  Value of m and trigm array are incompatible or trigm array is not initialized.
73:  Memory allocation failed.
successfully call of the nag_fft_2d_complex function.

Example:
    Assume "Data1" Worksheet has 4 columns, the first two columns contain 15 data each.  This piece
    of code computes the two-dimensional discrete Fourier transform of a bivariate sequence of complex
    data values. and put the result to the third column (real part) and the fourth column (imag part).

    int m = 3, n = 5;
    double trigm[5], trign[5];
    //Attach four Datasets to these 4 columns
    Dataset xx("data1",0);
    Dataset yy("data1",1);
    Dataset dx("data1",2);
    Dataset dy("data1",3);
    //Dataset cannot be the parameter of function, but vector can be.
    vector x = xx, y = yy;
    nag_fft_init_trig(m, trigm);
    nag_fft_init_trig(n, trign);
    nag_fft_2d_complex(m, n, x, y, trigm, trign);
    //Put the result to worksheet "data1" the third and fourth column.
    dx = x;
    dy = y;

    This program reads in a bivariate sequence of complex data values and prints the two-dimensional
    Fourier transform. It then performs an inverse transform and prints the sequence so obtained,
    which may be compared to the original data values.

void test_nag_ftt_2d_complex()
{
    int i, j, m, n;
    double trigm[12], trign[12];
    double x[36] = {1.000, 0.999, 0.987, 0.936, 0.802,
                    0.994, 0.989, 0.963, 0.891, 0.731,
                    0.903, 0.885, 0.823, 0.694, 0.467};
    double y[36] = {0.000, -0.040, -0.159, -0.352, -0.597,
                    -0.111, -0.151, -0.268, -0.454, -0.682,
                     -0.430, -0.466, -0.568, -0.720, -0.884};
    m = 3;
    n = 5;

    printf("\nOriginal data values\n\n");
    for (j = 0; j<m; ++j)
    {
        printf("Real");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\nImag");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", y[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\n\n");
    }

    nag_fft_init_trig(m, trigm);
    nag_fft_init_trig(n, trign);
    nag_fft_2d_complex(m, n, x, y, trigm, trign);

    printf("\nComponents of discrete Fourier transforms\n\n");
    for (j = 0; j<m; ++j)
    {
        printf("Real");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\nImag");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", y[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\n\n");
    }

    nag_conjugate_complex(m*n, y);
    nag_fft_2d_complex(m, n, x, y,trigm, trign);
    nag_conjugate_complex(m*n, y);

    printf ("\nOriginal data as restored by inverse transform\n\n");
    for (j = 0; j<m; ++j)
    {
        printf("Real");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\nImag");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", y[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\n\n");
    }
}

    The output is following:

    m = 3 n = 5

    Original data values

    Real 	1.0000 	 0.9990   	0.9870 	 0.9360 	0.8020
    Imag 	0.0000 	-0.0400    -0.1590 	-0.3520    -0.5970

    Real 	0.9940 	 0.9890 	0.9630 	 0.8910 	0.7310
    Imag   -0.1110 	-0.1510    -0.2680 	-0.4540    -0.6820

    Real 	0.9030 	 0.8850 	0.8230 	 0.6940 	0.4670
    Imag   -0.4300 	-0.4660    -0.5680 	-0.7200    -0.8840

    Components of discrete Fourier transforms

    Real 	3.3731 	 0.4814 	0.2507 	 0.0543    -0.4194
    Imag   -1.5187 	-0.0907 	0.1776 	 0.3188 	0.4145

    Real 	0.4565 	 0.0549 	0.0093 	-0.0217    -0.0759
    Imag 	0.1368 	 0.0317 	0.0389 	 0.0356 	0.0045

    Real   -0.1705 	-0.0375    -0.0423 	-0.0377    -0.0022
    Imag 	0.4927 	 0.0584 	0.0082  -0.0255    -0.0829

    Original data as restored by inverse transform

    Real 	1.0000 	 0.9990 	0.9870 	 0.9360 	0.8020
    Imag 	0.0000 	-0.0400    -0.1590 	-0.3520    -0.5970

    Real 	0.9940 	 0.9890 	0.9630 	 0.8910 	0.7310
    Imag   -0.1110 	-0.1510    -0.2680 	-0.4540    -0.6820

    Real 	0.9030 	 0.8850 	0.8230 	 0.6940 	0.4670
    Imag   -0.4300 	-0.4660    -0.5680 	-0.7200    -0.8840

Summary: computes the two-dimensional discrete Fourier transform of a bivariate sequence of complex data values.
Sample data:
Header file: OCN_c06.h
See also:


nag_conjugate_hermitian

Function: nag_conjugate_hermitian
Prototype:
int nag_conjugate_hermitian(int n,double x[])
Remarks: forms the complex conjugate of a Hermitian sequence of n data values.
Parameters:
n
  the number of data values.
x[]
  Input: the Hermitian sequence in Hermitian form.  Output: the imaginary parts y[j] are negated. The real parts x[j] are not referenced.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, n must not be less than 1: n = _value_.
successfully call of the nag_conjugate_hermitian function.

Example:
    Assume "Data1" Worksheet has 3 columns, the first column contain 7 data.  This piece of code forms
    the complex conjugate of a Hermitian sequence of 7 data values. and put the result to the second
    column (real part) and the third column (imag part).

    int j, n = 7, n2, nj;
    //Attach three Datasets to these 3 columns
    Dataset xx("data1",0);
    Dataset aa("data1",1);
    Dataset bb("data1",2);
    //Dataset cannot be the parameter of function, but vector can be.
    vector x = xx, a = aa, b = bb;
    nag_fft_real(n, x);
    nag_conjugate_hermitian(n, x);
    a[0] = x[0];
    b[0] = 0.0;
    n2 = (n-1)/2;
    for (j = 1; j<=n2; j++)
    {
        nj = n - j;
        a[j] = x[j];
        a[nj] = x[j];
        b[j] = x[nj];
        b[nj] = -x[nj];
    }
    if (n % 2==0)
    {
        a[n2+1] = x[n2+1];
        b[n2+1] = 0.0;
    }
    //Put the result to the Worksheet "data1" the second and third column.
    aa = a;
    bb = b;

    This program reads in a sequence of real data values,cal ls nag fft real (c06eac) followed by
    nag_conjugate_hermitian to compute their inverse discrete Fourier transform, and prints this after
    expanding it from Hermitian form into a full complex sequence.

void test_nag_conjugate_hermitian()
{
    #define NMAX 20

    int j, n, n2, nj;
    double a[20], b[20];
    double x[20] = {0.34907, 0.54890, 0.74776, 0.94459,
                    1.13850, 1.32850, 1.51370};
    n = 7;

    nag_fft_real(n, x);

    nag_conjugate_hermitian(n, x);
    a[0] = x[0];
    b[0] = 0.0;
    n2 = (n-1)/2;
    for (j = 1; j<=n2; j++)
    {
        nj = n - j;
        a[j] = x[j];
        a[nj] = x[j];
        b[j] = x[nj];
        b[nj] = -x[nj];
    }
    if (n % 2==0)
    {
        a[n2+1] = x[n2+1];
        b[n2+1] = 0.0;
    }

    printf("\nComponents of inverse discrete Fourier transform\n");
    printf("\n Real Imag \n\n");
    for (j = 0; j<n; j++)
        printf("%3ld %10.5f %10.5f\n", j, a[j], b[j]);
}

    The output is following:

    Components of inverse discrete Fourier transform

             Real 		 Imag

    0 		 2.48361 	 0.00000
    1 		-0.26599 	-0.53090
    2 		-0.25768 	-0.20298
    3 		-0.25636 	-0.05806
    4 		-0.25636 	 0.05806
    5 		-0.25768 	 0.20298
    6 		-0.26599 	 0.53090

Summary: forms the complex conjugate of a Hermitian sequence of n data values.
Sample data:
Header file: OCN_c06.h
See also:


nag_conjugate_complex

Function: nag_conjugate_complex
Prototype:
int nag_conjugate_complex(int n,double y[])
Remarks: forms the complex conjugate of a sequence of n data values.
Parameters:
n
  the number of data values.
y[]
  Input:the imaginary part of the  data values.  Output: these values are negated.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, n must not be less than 1: n = _value_.
successfully call of the nag_conjugate_complex function.

Example:
    Assume "Data1" Worksheet has 4 columns, the first two columns contain 7 data each.
    This piece of code forms the complex conjugate of a sequence of 7 data values. and
    put the result to the third column (real part) and the fourth column (imag part).

    int j, n = 7;
    //Attach four Datasets to these 4 columns
    Dataset xx("data1",0);
    Dataset yy("data1",1);
    Dataset dx("data1",2);
    Dataset dy("data1",3);
    //Dataset cannot be the parameter of function, but vector can be.
    vector x = xx;
    nag_conjugate_complex(n, y);
    nag_fft_complex(n, x, y);
    nag_conjugate_complex(n, y);
    //Put the result to the Worksheet "data1" the third and fourth column.
    dx = x;
    dy = y;

    This program reads in a sequence of complex data values and prints their inverse discrete Fourier
    transform as computed by calling nag_conjugate_complex, followed by nag_fft_complex (c06ecc) and
    nag_conjugate_complex again.

void test_nag_conjugate_complex()
{
    #define NMAX 20
    int j, n ;
    double x[20] = {0.34907, 0.54890, 0.74776, 0.94459,
                    1.13850, 1.32850, 1.51370};
    double y[20] = {-0.37168, -0.35669, -0.31175, -0.23702,
                    -0.13274, 0.00074, 0.16298};
    n = 7;

    nag_conjugate_complex(n, y);

    nag_fft_complex(n, x, y);

    nag_conjugate_complex(n, y);
    printf("\nComponents of inverse discrete Fourier transform\n");
    printf("\n Real Imag\n\n");
    for (j = 0; j<n; ++j)
        printf("%3ld %10.5f %10.5f\n", j, x[j], y[j]);
}

    The output is following:

    Components of inverse discrete Fourier transform

             Real 		 Imag
    0 		 2.48361 	-0.47100
    1 		 0.01983 	-0.56496
    2 		-0.14825 	-0.30840
    3 		-0.22506 	-0.17477
    4 		-0.28767 	-0.05865
    5 		-0.36711 	 0.09756
    6 		-0.55180 	 0.49684

Summary: forms the complex conjugate of a sequence of n data values.
Sample data:
Header file: OCN_c06.h
See also:


nag_multiple_conjugate_hermitian

Function: nag_multiple_conjugate_hermitian
Prototype:
int nag_multiple_conjugate_hermitian(int m,int n,double x[])
Remarks: forms the complex conjugates of m Hermitian sequences, each containing n data values.
Parameters:
m
  the number of Hermitian sequences to be conjugated.
n
  the number of data values in each Hermitian sequence.
x[]
  Input:the m data sequences must be stored in x consecutively.  Output:the imaginary parts are negated.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, m must not be less than 1: m = _value_.  On entry, n must not be less than 1: n = _value_.
successfully call of the nag_multiple_conjugate_hermitian function.

Example:
    Assume "Data1" Worksheet has 4 columns, the first column contains 18 data.  This piece of
    code forms the complex conjugate of 3 Hermitian sequences, each containing 6 data values.
    The result was put to the second column (Conjugated data values) the third column (real part)
    and the fourth column (imag part).

    int m = 3, n = 6;
    //Attach four Datasets to these 4 columns
    Dataset xx("data1",0);
    Dataset yy("data1",1);
    Dataset uu("data1",2);
    Dataset vv("data1",3);
    //Dataset cannot be the parameter of function, but vector can be.
    vector x = xx, u = uu, v = vv;
    //Original data written in full complex form, u is real part, v is imag part.
    nag_multiple_hermitian_to_complex(m, n, x, u, v);
    nag_multiple_conjugate_hermitian(m, n, x);
    //Put the Conjugated data values to Worksheet "data1" the second column.
    yy = x;
    nag_multiple_hermitian_to_complex(m, n, x, u, v);
    //Put the Conjugated data written in full complex form to the third and fourth column.
    uu = u;
    vv = v;

    This program reads in sequences of real data values which are assumed to be Hermitian sequences
    of complex data stored in Hermitian form. The sequences are expanded into full complex form
    using nag_multiple_hermitian_to_complex (c06gsc) and printed out. The sequences are then conjugated
    (using nag_multiple_conjugate_hermitian) and the conjugated sequences are expanded into complex
    form using nag_multiple_hermitian_to_complex (c06gsc) and printed out.

void test_nag_multiple_conjugate_hermitian()
{
    int i, j, m, n;
    double u[100], v[100];
    double x[100] = {0.3854, 0.6772, 0.1138, 0.6751, 0.6362, 0.1424,
                     0.5417, 0.2983, 0.1181, 0.7255, 0.8638, 0.8723,
                     0.9172, 0.0644, 0.6037, 0.6430, 0.0428, 0.4815};
    m = 3;
    n =6;
    printf("\n\nm = %2ld n = %2ld\n", m, n);

    printf("\nOriginal data values\n\n");
    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if((i % 6 )== 5 && (i != n-1 ))
                 printf("\n " );
        }
        printf("\n");
    }

    nag_multiple_hermitian_to_complex(m, n, x, u, v);
    printf("\nOriginal data written in full complex form\n\n");
    for (j = 0; j<m; ++j)
    {
        printf("Real");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", u[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }

        printf("\nImag");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", v[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\n\n");
    }

    nag_multiple_conjugate_hermitian(m, n, x);
    printf("\nConjugated data values\n\n");
    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if((i % 6 )== 5 && (i != n-1 ))
                 printf("\n " );
        }
        printf("\n");
    }

    nag_multiple_hermitian_to_complex(m, n, x, u, v);

    printf("\nConjugated data written in full complex form\n\n");
    for (j = 0; j<m; ++j)
    {
        printf("Real");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", u[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\nImag");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", v[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\n\n");
    }
}

    The output is following:

    m = 3 n = 6

    Original data values

    0.3854 0.6772 0.1138 0.6751 0.6362 0.1424
    0.5417 0.2983 0.1181 0.7255 0.8638 0.8723
    0.9172 0.0644 0.6037 0.6430 0.0428 0.4815

    Original data written in full complex form

    Real 	0.3854 	  0.6772 	0.1138 	  0.6751 	 0.1138 	 0.6772
    Imag 	0.0000 	  0.1424 	0.6362 	  0.0000 	-0.6362 	-0.1424

    Real 	0.5417 	  0.2983 	0.1181 	  0.7255 	 0.1181 	 0.2983
    Imag 	0.0000 	  0.8723 	0.8638 	  0.0000 	-0.8638 	-0.8723

    Real 	0.9172 	  0.0644 	0.6037 	  0.6430 	 0.6037 	 0.0644
    Imag 	0.0000 	  0.4815 	0.0428 	  0.0000 	-0.0428 	-0.4815

    Conjugated data values

            0.3854 	  0.6772    0.1138    0.6751 	-0.6362 	-0.1424
            0.5417 	  0.2983    0.1181    0.7255 	-0.8638 	-0.8723
            0.9172    0.0644    0.6037    0.6430 	-0.0428 	-0.4815

    Conjugated data written in full complex form

    Real 	0.3854 	  0.6772 	0.1138 	  0.6751 	 0.1138 	 0.6772
    Imag 	0.0000 	 -0.1424   -0.6362    0.0000 	 0.6362 	 0.1424

    Real 	0.5417 	  0.2983 	0.1181    0.7255     0.1181 	 0.2983
    Imag 	0.0000 	 -0.8723   -0.8638 	  0.0000 	 0.8638 	 0.8723

    Real 	0.9172 	  0.0644 	0.6037 	  0.6430 	 0.6037  	 0.0644
    Imag 	0.0000 	 -0.4815   -0.0428 	  0.0000 	 0.0428 	 0.4815

Summary: forms the complex conjugates of m Hermitian sequences, each containing n data values.
Sample data:
Header file: OCN_c06.h
See also:


nag_multiple_hermitian_to_complex

Function: nag_multiple_hermitian_to_complex
Prototype:
int nag_multiple_hermitian_to_complex(int m,int n,const double x[],double u[],double v[])
Remarks: takes m Hermitian sequences, each containing n data values, and forms the real and imaginary parts of the m corresponding complex sequences.
Parameters:
m
  the number of Hermitian sequences to be converted into complex form.
n
  the number of data values, in each sequence.
x[]
  the data sequences must be stored in x consecutively.
u[]
  the real part of the m sequences of length n are stored consecutively in u.
v[]
  the imaginary part of the m sequences of length n are stored consecutively v.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, m must not be less than 1: m = _value_.  On entry, n must not be less than 1: n = _value_.
successfully call of the nag_multiple_hermitian_to_complex function.

Example:
    Assume "Data1" Worksheet has 3 columns, the first column contains 18 data.  This piece of
    code forms the complex conjugate of 3 Hermitian sequences, each containing 6 data values.
    The result was put to the second column (real part) and the third column (imag part).

    int m = 3, n = 6;
    //Attach 3 Datasets to these 3 columns
    Dataset xx("data1",0);
    Dataset uu("data1",1);
    Dataset vv("data1",2);
    //Dataset cannot be the parameter of function, but vector can be.
    vector x = xx, u = uu, v = vv;
    // Convert Hermitian form to full complex
    nag_multiple_hermitian_to_complex(m, n, x, u, v);
    //Put the Conjugated data written in full complex form to the third and fourth column.
    uu = u;
    vv = v;

    This program reads in sequences of real data values which are assumed to be Hermitian
    sequences of complex data stored in Hermitian form. The sequences are then expanded
    into full complex form using_nag_multiple_hermitian_to_complex and printed.

void test_nag_multiple_hermitian_to_complex()
{
    #define MMAX 5
    #define NMAX 20

    int i, j, m, n;
    double u[100], v[100];
    double x[100] = {0.3854, 0.6772, 0.1138, 0.6751, 0.6362, 0.1424,
                     0.5417, 0.2983, 0.1181, 0.7255, 0.8638, 0.8723,
                     0.9172, 0.0644, 0.6037, 0.6430, 0.0428, 0.4815};
    m = 3;
    n = 6;

    printf("\nOriginal data values\n\n");
    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if((i % 6 )== 5 && (i != n-1 ))
                 printf("\n " );
         }
        printf("\n");
    }

    // Convert Hermitian form to full complex

    nag_multiple_hermitian_to_complex(m, n, x, u, v);
    printf("\nOriginal data written in full complex form\n\n");
    for (j = 0; j<m; ++j)
    {
        printf("Real");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", u[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\nImag");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", v[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\n\n");
    }
}

    The output is following:

    m = 3 n = 6

    Original data values

            0.3854 	  0.6772 	0.1138 	  0.6751 	0.6362 	  0.1424
            0.5417 	  0.2983 	0.1181 	  0.7255 	0.8638 	  0.8723
            0.9172 	  0.0644 	0.6037 	  0.6430 	0.0428 	  0.4815

    Original data written in full complex form

    Real 	0.3854 	  0.6772 	0.1138 	  0.6751  	0.1138 	  0.6772
    Imag 	0.0000 	  0.1424 	0.6362 	  0.0000   -0.6362 	 -0.1424

    Real 	0.5417 	  0.2983 	0.1181 	  0.7255 	0.1181 	  0.2983
    Imag 	0.0000 	  0.8723 	0.8638 	  0.0000   -0.8638   -0.8723

    Real 	0.9172 	  0.0644 	0.6037 	  0.6430 	0.6037 	  0.0644
    Imag 	0.0000 	  0.4815 	0.0428 	  0.0000   -0.0428 	 -0.4815

Summary: takes m Hermitian sequences, each containing n data values, and forms the real and imaginary parts of the m corresponding complex sequences.
Sample data:
Header file: OCN_c06.h
See also:


nag_fft_init_trig

Function: nag_fft_init_trig
Prototype:
int nag_fft_init_trig(int n,double trig[])
Remarks: calculates the trigonometric coefficients required for the computation of discrete Fourier transforms.
Parameters:
n
  the value  in the Fourier transform function being called.
trig[]
  the trigonometric coefficients.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, n must not be less than 1: n = _value_.
successfully call of the nag_fft_init_trig function.

Example:
    Assume "Data1" Worksheet has 2 columns, the first column contains 18 data.  This piece of
    code calculates the trigonometric coefficients required for the computation of discrete
    Fourier transforms. The result was put to the second column.

    double trig[40];
    int m = 3, n = 6;
    //Attach 2 Datasets to these 2 columns
    Dataset xx("data1",0);
    Dataset dx("data1",1);
    x = xx;
    nag_fft_init_trig(n, trig);
    nag_fft_multiple_real(m, n, x, trig);
    //Put the result to the second column.
    dx = x;

    The program reads in 3 real data sequences and prints their discrete Fourier transforms in Hermitian
    format as calculated by nag_fft_multiple_real (c06fpc). A call is made to nag_fft_init_trig to initialise
    the array trig prior to calling nag_fft_multiple_real (c06fpc). The transforms are then printed out
    in full complex form after a call to nag_multiple_hermitian_to_complex (c06gsc).

void test_nag_fft_init_trig()
{

    double trig[40];
    int i, j, m, n;
    double u[100], v[100];
    double x[100] = {0.3854, 0.6772, 0.1138, 0.6751, 0.6362, 0.1424,
                     0.5417, 0.2983, 0.1181, 0.7255, 0.8638, 0.8723,
                     0.9172, 0.0644, 0.6037, 0.6430, 0.0428, 0.4815};
    m = 3;
    n = 6;

    printf("\nOriginal data values\n\n");
    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if((i % 6 )== 5 && (i != n-1 ))
                 printf("\n " );
        }
        printf("\n");
    }
    nag_fft_init_trig(n, trig);
    nag_fft_multiple_real(m, n, x, trig);
    printf("\nDiscrete Fourier transforms in Hermitian format\n\n");
    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if((i % 6 )== 5 && (i != n-1 ))
                 printf("\n " );
        }
        printf("\n");
    }

    nag_multiple_hermitian_to_complex(m, n, x, u, v);
    printf("\nFourier transforms in full complex form\n\n");
    for (j = 0; j<m; ++j)
    {
        printf("Real");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", u[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\nImag");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", v[j*n + i]);
             if(i % 6 == 5 && i != n-1 )
                 printf("\n " );
        }
        printf("\n\n");
    }
}

    The output is following:

    m = 3 n = 6

    Original data values

            0.3854 	  0.6772 	0.1138    0.6751 	0.6362    0.1424
            0.5417    0.2983 	0.1181    0.7255 	0.8638    0.8723
            0.9172    0.0644 	0.6037    0.6430 	0.0428    0.4815

    Discrete Fourier transforms in Hermitian format

            1.0737 	 -0.1041  	0.1126   -0.1467   -0.3738 	 -0.0044
            1.3961   -0.0365 	0.0780   -0.1521   -0.0607 	  0.4666
            1.1237    0.0914 	0.3936 	  0.1530 	0.3458   -0.0508

    Fourier transforms in full complex form

    Real 	1.0737   -0.1041 	0.1126 	 -0.1467 	0.1126   -0.1041
    Imag 	0.0000   -0.0044   -0.3738    0.0000 	0.3738    0.0044

    Real 	1.3961   -0.0365 	0.0780 	 -0.1521 	0.0780   -0.0365
    Imag 	0.0000    0.4666   -0.0607    0.0000 	0.0607   -0.4666

    Real 	1.1237    0.0914 	0.3936    0.1530 	0.3936    0.0914
    Imag 	0.0000   -0.0508 	0.3458    0.0000   -0.3458    0.0508

Summary: calculates the trigonometric coefficients required for the computation of discrete Fourier transforms.
Sample data:
Header file: OCN_c06.h
See also:


nag_fft_multiple_sine

Function: nag_fft_multiple_sine
Prototype:
int nag_fft_multiple_sine(int m,int n,double x[],const double trig[])
Remarks: computes the discrete Fourier sine transforms of m sequences of n real data values.
Parameters:
m
  the number of sequences to be transformed.
n
  one more than the number of real values in each sequence, i.e. the number of values in each sequence is n - 1.
x[]
  Input: the m data sequences stored in x consecutively.  Output: the m Fourier sine transforms stored consecutively, overwrite the corresponding original sequence.
trig[]
  the trigonometric coefficients are returned by a call of nag fft init trig (c06gzc).

Return values:
The function returns NAG error code or 0 if no error.
11:  On entry, m must not be less than 1: m = _value_.  On entry, n must not be less than 1: n = _value_.
139: Value of n and trig array are incompatible or trig array is not initialized.
73:  Memory allocation failed.
successfully call of the nag_fft_multiple_sine function.

Example:
    Assume "Data1" Worksheet has 2 columns, the first column contains 18 data.  This piece of
    code computes the discrete Fourier sine transforms of 3 sequences of 6 real data values.
    The result was put to the second column.

    double trig[40];
    int m = 3, n = 6;
    //Attach 2 Datasets to these 2 columns
    Dataset xx("data1",0);
    Dataset dx("data1",1);
    x = xx;
    nag_fft_init_trig(n, trig);
    nag_fft_multiple_sine(m, n, x, trig);
    //Put the result to the second column.
    dx = x;

    This program reads in sequences of real data values and prints their Fourier sine
    transforms (as computed by nag_fft_multiple_sine). It then calls nag_fft_multiple_sine
    again and prints the results which may be compared with the original sequence.

void test_nag_fft_multiple_sine()
{

    double trig[40];
    int i, j, m, n, row_len;
    double x[100] = {0.6772, 0.1138, 0.6751, 0.6362, 0.1424,
                     0.2983, 0.1181, 0.7255, 0.8638, 0.8723,
                     0.0644, 0.6037, 0.6430, 0.0428, 0.4815};
    m = 3;
    n = 6;
    row_len = n - 1;

    printf("\nOriginal data values\n\n");
    for (i = 0; i<m; ++i)
    {
        printf(" ");
        for (j = 0; j<row_len; ++j)
        {
            printf("%10.4f", x[(i)*row_len + (j)]);
             if((j % 7 )== 6 && (j != row_len-1 ))
                 printf("\n " );
        }
        printf("\n");
    }

    nag_fft_init_trig(n, trig);
    nag_fft_multiple_sine(m, n, x, trig);
    printf("\nDiscrete Fourier sine transforms\n\n");
    for (i = 0; i<m; ++i)
    {
        printf(" ");
        for (j = 0; j<row_len; ++j)
        {
            printf("%10.4f", x[(i)*row_len + (j)]);
             if((j % 7 )== 6 && (j != row_len-1 ))
                 printf("\n " );
        }
        printf("\n");
    }

    nag_fft_multiple_sine(m, n, x, trig);
    printf("\nOriginal data as restored by inverse transform\n\n");
    for (i = 0; i<m; ++i)
    {
        printf(" ");
        for (j = 0; j<row_len; ++j)
        {
            printf("%10.4f", x[(i)*row_len + (j)]);
             if((j % 7 )== 6 && (j != row_len-1 ))
                 printf("\n " );
        }
        printf("\n");
    }
}

    The output is following:

    Original data values

    0.6772    0.1138 	0.6751    0.6362 	0.1424
    0.2983    0.1181 	0.7255    0.8638 	0.8723
    0.0644    0.6037 	0.6430    0.0428 	0.4815

    Discrete Fourier sine transforms

    1.0014    0.0062 	0.0834    0.5286 	0.2514
    1.2477   -0.6599 	0.2570    0.0858 	0.2658
    0.8521    0.0719   -0.0561   -0.4890 	0.2056

    Original data as restored by inverse transform

    0.6772    0.1138 	0.6751    0.6362 	0.1424
    0.2983    0.1181 	0.7255    0.8638 	0.8723
    0.0644    0.6037 	0.6430    0.0428 	0.4815

Summary: computes the discrete Fourier sine transforms of m sequences of real data values.
Sample data:
Header file: OCN_c06.h
See also:


nag_fft_multiple_cosine

Function: nag_fft_multiple_cosine
Prototype:
int nag_fft_multiple_cosine(int m,int n,double x[],const double trig[])
Remarks: computes the discrete Fourier cosine transforms of m sequences of n real data values.
Parameters:
m
  the number of sequences to be transformed.
n
  one less than the number of real values in each sequence, i.e., the number of values in each sequence is n + 1.
x[]
  Input:the m data sequences stored in x.  Output:the m Fourier cosine transforms stored consecutively, overwrite the corresponding original sequence.
trig[]
  the trigonometric coefficients as returned by a call of nag_fft_init_trig (c06gzc).

Return values:
The function returns NAG error code or 0 if no error.
11:  On entry, m must not be less than 1: m = _value_.  On entry, n must not be less than 1: n = _value_.
139: Value of n and trig array are incompatible or trig array is not initialized.
73:  Memory allocation failed.
successfully call of the nag_fft_multiple_cosine function.

Example:
    Assume "Data1" Worksheet has 2 columns, the first column contains 18 data.  This piece of
    code computes the discrete Fourier cosine transforms of 3 sequences of 6 real data values.
    The result was put to the second column.

    double trig[40];
    int m = 3, n = 6;
    //Attach 2 Datasets to these 2 columns
    Dataset xx("data1",0);
    Dataset dx("data1",1);
    x = xx;
    nag_fft_init_trig(n, trig);
    nag_fft_multiple_cosine(m, n, x, trig);
    //Put the result to the second column.
    dx = x;

    This program reads in sequences of real data values and prints their Fourier cosine
    transforms (as computed by nag_fft_multiple_cosine). It then calls nag_fft_multiple_cosine
    again and prints the results which may be compared with the original sequence.

void test_nag_fft_multiple_cosine()
{
    double trig[40];
    int i, j, m, n, row_len;
    double x[105] = {0.3854, 0.6772, 0.1138, 0.6751, 0.6362, 0.1424,0.9562,
                     0.5417, 0.2983, 0.1181, 0.7255, 0.8638, 0.8723,0.4936,
                     0.9172, 0.0644, 0.6037, 0.6430, 0.0428, 0.4815,0.2057};
    m = 3;
    n = 6;
    row_len = n + 1;

    printf("\nOriginal data values\n\n");
    for (i = 0; i<m; ++i)
    {
        printf(" ");
        for (j = 0; j<row_len; ++j)
        {
            printf("%10.4f", x[(i)*row_len + (j)]);
             if((j % 7 )== 6 && (j != row_len-1 ))
                 printf("\n " );
         }
        printf("\n");
    }

    nag_fft_init_trig(n, trig);
    nag_fft_multiple_cosine(m, n, x, trig);
    printf("\nDiscrete Fourier cosine transforms\n\n");
    for (i = 0; i<m; ++i)
    {
        printf(" ");
        for (j = 0; j<row_len; ++j)
        {
            printf("%10.4f", x[(i)*row_len + (j)]);
             if((j % 7 )== 6 && (j != row_len-1 ))
                 printf("\n " );
        }
        printf("\n");
    }

    nag_fft_multiple_cosine(m, n, x, trig);
    printf("\nOriginal data as restored by inverse transform\n\n");
    for (i = 0; i<m; ++i)
    {
        printf(" ");
        for (j = 0; j<row_len; ++j)
        {
            printf("%10.4f", x[(i)*row_len + (j)]);
             if((j % 7 )== 6 && (j != row_len-1 ))
                 printf("\n " );
        }
        printf("\n");
    }
}

    The output is following:

    Original data values

    0.3854    0.6772 	0.1138    0.6751 	0.6362    0.1424 	0.9562
    0.5417    0.2983 	0.1181    0.7255 	0.8638    0.8723 	0.4936
    0.9172    0.0644 	0.6037    0.6430 	0.0428    0.4815 	0.2057

    Discrete Fourier cosine transforms

    1.6833   -0.0482 	0.0176    0.1368 	0.3240   -0.5830   -0.0427
    1.9605   -0.4884   -0.0655    0.4444 	0.0964    0.0856   -0.2289
    1.3838    0.1588   -0.0761 	 -0.1184 	0.3512    0.5759  	0.0110

    Original data as restored by inverse transform

    0.3854    0.6772 	0.1138    0.6751 	0.6362    0.1424 	0.9562
    0.5417    0.2983 	0.1181    0.7255 	0.8638    0.8723 	0.4936
    0.9172    0.0644 	0.6037    0.6430 	0.0428    0.4815 	0.2057

Summary: computes the discrete Fourier cosine transforms of m sequences of real data values.
Sample data:
Header file: OCN_c06.h
See also:


nag_fft_multiple_qtr_sine

Function: nag_fft_multiple_qtr_sine
Prototype:
int nag_fft_multiple_qtr_sine(Nag_TransformDirection direct,int m,int n,double x[],const double trig[])
Remarks: computes the discrete quarter-wave Fourier sine transforms of m sequences of real data values.
Parameters:
direct
  determine which direction transform to be computed.
m
  the number of sequences to be transformed.
n
  the number of real values in each sequence,
x[]
  Input:the m data sequences stored in x consecutively.  Output:the m quarter-wave sine transforms stored consecutively.
trig[]
  the trigonometric coefficients as returned by a call of nag_fft_init_trig (c06gzc).

Return values:
The function returns NAG error code or 0 if no error.
11:  On entry, m must not be less than 1: m = _value_.  On entry, n must not be less than 1: n = _value_.
139: Value of n and trig array are incompatible or trig array is not initialized.
70:  On entry, parameter direct has an illegal value.
successfully call of the nag_fft_multiple_qtr_sine function.

Example:
    Assume "Data1" Worksheet has 2 columns, the first column contains 18 data.  This piece of
    code computes the discrete quarter-wave Fourier sine transforms of 3 sequences of 6 real data values.
    The result was put to the second column.

    double trig[40];
    int m = 3, n = 6;
    //Attach 2 Datasets to these 2 columns
    Dataset xx("data1",0);
    Dataset dx("data1",1);
    x = xx;
    nag_fft_init_trig(n, trig);
    nag_fft_multiple_qtr_sine(Nag_ForwardTransform, m, n, x, trig);
    //Put the result to the second column.
    dx = x;

    This program reads in sequences of real data values and prints their quarter-wave sine
    transforms as computed by nag_fft_multiple_qtr_sine with direct = Nag_ForwardTransform.
    It then calls nag_fft_multiple_qtr_sine again with direct = Nag BackwardTransform
    and prints the results which may be compared with the original data.

void test_nag_fft_multiple_qtr_sine()
{
    double trig[40];
    int i, j, m, n;
    double x[100] = {0.3854, 0.6772, 0.1138, 0.6751, 0.6362, 0.1424,
                     0.5417, 0.2983, 0.1181, 0.7255, 0.8638, 0.8723,
                     0.9172, 0.0644, 0.6037, 0.6430, 0.0428, 0.4815};
    m = 3;
    n = 6;

    printf("\nOriginal data values\n\n");
    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if((i % 7 )== 6 && (i != n-1 ))
                 printf("\n " );
        }
        printf("\n");
    }
    nag_fft_init_trig(n, trig);

    nag_fft_multiple_qtr_sine(Nag_ForwardTransform, m, n, x, trig);
    printf("\nDiscrete quarter-wave Fourier sine transforms\n\n");

    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if((i % 7 )== 6 && (i != n-1 ))
                 printf("\n " );
        }
        printf("\n");
    }

    nag_fft_multiple_qtr_sine(Nag_BackwardTransform, m, n, x, trig);
    printf("\nOriginal data as restored by inverse transform\n\n");
    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if((i % 7 )== 6 && (i != n-1 ))
                 printf("\n " );
        }
        printf("\n");
    }
}

    The output is the following:

    Original data values

    0.3854    0.6772 	0.1138    0.6751 	0.6362 	  0.1424
    0.5417    0.2983 	0.1181    0.7255 	0.8638    0.8723
    0.9172    0.0644 	0.6037    0.6430 	0.0428    0.4815

    Discrete quarter-wave Fourier sine transforms

    0.7304    0.2078 	0.1150    0.2577   -0.2869 	 -0.0815
    0.9274   -0.1152 	0.2532    0.2883   -0.0026   -0.0635
    0.6268    0.3547 	0.0760    0.3078 	0.4987   -0.0507

    Original data as restored by inverse transform

    0.3854    0.6772 	0.1138    0.6751 	0.6362    0.1424
    0.5417    0.2983 	0.1181    0.7255 	0.8638    0.8723
    0.9172    0.0644 	0.6037    0.6430 	0.0428    0.4815

Summary: computes the discrete quarter-wave Fourier sine transforms of m sequences of real data values.
Sample data:
Header file: OCN_c06.h
See also:


nag_fft_multiple_qtr_cosine

Function: nag_fft_multiple_qtr_cosine
Prototype:
int nag_fft_multiple_qtr_cosine(Nag_TransformDirection direct,int m,int n,double x[],const double trig[])
Remarks: computes the discrete quarter-wave Fourier cosine transforms of m sequences of real data values.
Parameters:
direct
  determine which direction transform to be computed
m
  the number of sequences to be transformed.
n
  the number of real values in each sequence.
x[]
  Input: the m data sequences stored in x consecutively.  Output: the m quarter-wave cosine transforms stored consecutively overwrite the corresponding original sequence.
trig[]
  the trigonometric coefficients as returned by by a call of nag_fft_init_trig (c06gzc).

Return values:
The function returns NAG error code or 0 if no error.
11:  On entry, m must not be less than 1: m = _value_.  On entry, n must not be less than 1: n = _value_.
139: Value of n and trig array are incompatible or trig array is not initialized.
70:  On entry, parameter direct has an illegal value.
successfully call of the nag_fft_multiple_qtr_cosine function.

Example:
    Assume "Data1" Worksheet has 2 columns, the first column contains 18 data.  This piece of
    code computes the discrete quarter-wave Fourier cosine transforms of 3 sequences of 6 real data values.
    The result was put to the second column.

    double trig[40];
    int m = 3, n = 6;
    //Attach 2 Datasets to these 2 columns
    Dataset xx("data1",0);
    Dataset dx("data1",1);
    x = xx;
    nag_fft_init_trig(n, trig);
    nag_fft_multiple_qtr_cosine(Nag_ForwardTransform, m, n, x, trig);
    //Put the result to the second column.
    dx = x;

    This program reads in sequences of real data values and prints their quarter-wave cosine
    transforms as computed by nag_fft_multiple_qtr_cosine with direct = Nag_ForwardTransform.
    It then calls nag_fft_multiple_qtr_cosine again with direct = Nag_BackwardTransform and
    prints the results which may be compared with the original data.

void test_nag_fft_multiple_qtr_cosine()
{

    double trig[40];
    int i, j, m, n;
    double x[100] = {0.3854, 0.6772, 0.1138, 0.6751, 0.6362, 0.1424,
                     0.5417, 0.2983, 0.1181, 0.7255, 0.8638, 0.8723,
                     0.9172, 0.0644, 0.6037, 0.6430, 0.0428, 0.4815};
    m =3;
    n =6;

    printf("\nOriginal data values\n\n");
    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if((i % 7 )== 6 && (i != n-1 ))
                 printf("\n " );
        }
        printf("\n");
    }

    nag_fft_init_trig(n, trig);
    nag_fft_multiple_qtr_cosine(Nag_ForwardTransform, m, n, x, trig);
    printf("\nDiscrete quarter-wave Fourier cosine transforms\n\n");
    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if((i % 7 )== 6 && (i != n-1 ))
                 printf("\n " );
         }
        printf("\n");
    }

    nag_fft_multiple_qtr_cosine(Nag_BackwardTransform, m, n, x, trig);
    printf("\nOriginal data as restored by inverse transform\n\n");
    for (j = 0; j<m; ++j)
    {
        printf(" ");
        for (i = 0; i<n; ++i)
        {
            printf("%10.4f", x[j*n + i]);
             if((i % 7 )== 6 && (i != n-1 ))
                 printf("\n " );
         }
        printf("\n");
    }
}

    The output is following:

    Original data values

    0.3854    0.6772 	0.1138    0.6751 	0.6362    0.1424
    0.5417    0.2983 	0.1181    0.7255 	0.8638    0.8723
    0.9172    0.0644 	0.6037    0.6430 	0.0428    0.4815

    Discrete quarter-wave Fourier cosine transforms

    0.7257   -0.2216 	0.1011    0.2355   -0.1406   -0.2282
    0.7479   -0.6172 	0.4112    0.0791 	0.1331   -0.0906
    0.6713   -0.1363   -0.0064   -0.0285 	0.4758    0.1475

    Original data as restored by inverse transform

    0.3854    0.6772 	0.1138    0.6751 	0.6362    0.1424
    0.5417    0.2983 	0.1181    0.7255 	0.8638    0.8723
    0.9172    0.0644 	0.6037    0.6430 	0.0428    0.4815

Summary: computes the discrete quarter-wave Fourier cosine transforms of m sequences of real data values.
Sample data:
Header file: OCN_c06.h
See also:


nag_1d_spline_interpolant

Function: nag_1d_spline_interpolant
Prototype:
int nag_1d_spline_interpolant(int m,double x[],double y[],Nag_Spline *spline)
Remarks: determines a cubic spline interpolant to a given set of data.
Parameters:
m
  the number of data points.
x[]
  the ith data value of the independent variable x, for i = 1, 2, . . .,m.
y[]
  the ith data value of the dependent variable y, for i = 1, 2, . . .,m.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, m must not be less than 4: m = _value_.
63: The sequence x is not strictly increasing: x[_value_] = _value_, x[_value_] = _value_.
73: Memory allocation failed.
successful call of the nag_1d_spline_interpolant function.

Example:
    Assume "Data1" Worksheet has 2 columns, the first column contain 5 data
    and we want to put result in the second column.

    int m = 5, i, j;
    Nag_Spline spline;
    //Attach two Datasets to these 2 columns
    Dataset xx("data1",0);
    xx.SetSize(m);
    Dataset yy("data1",1);
    yy.SetSize(m);
    //Because Dataset cannot be the parameter of function, but vector can be.
    vector x = xx, y = yy;
    for (i=0; i<m; ++i)
        y[i] = exp(x[i]);
    nag_1d_spline_interpolant(m, x, y, &spline);
    //put the result back to the worksheet.
    yy = y;

    The following example program sets up data from 7 values of the exponential
    function in the interval 0 to 1. nag 1d spline interpolant is then called
    to compute a spline interpolant to these data.  The spline is evaluated
    by nag 1d spline evaluate (e02bbc), at the data points and at points halfway
    between each adjacent pair of data points, and the spline values and
    the values of ex are printed out.

void test_nag_1d_spline_interpolant()
{
    int MMAX = 7;
    double x[] = {0.0, 0.2, 0.4, 0.6, 0.75, 0.9, 1.0};
    int i, j;
    double y[7], fit, xarg;
    Nag_Spline spline;
    int m = MMAX;

    for (i=0; i<m; ++i)
        y[i] = exp(x[i]);
    nag_1d_spline_interpolant(m, x, y, &spline);
    printf("\n Number of distinct knots = %ld\n\n", m-2);
    printf(" Distinct knots located at \n\n");
    for (j=3; j<m+1; j++)
    {
        printf("%7.4f",spline.lamda[j]);
        if((j-3)%5==4 || j==m )
            printf("\n");
    }

    printf("\n\n J B-spline coeff c\n\n");
    for (j=0; j<m; ++j)
        printf(" %ld %13.4f\n",j+1,spline.c[j]);
    printf("\n J Abscissa Ordinate Spline\n\n");

    for (j=0; j<m; ++j)
    {
        nag_1d_spline_evaluate(x[j], &fit, &spline);
        printf(" %ld %13.4f %13.4f %13.4f\n",j+1,x[j],y[j],fit);
        if (j < m-1)
        {
            xarg = (x[j] + x[j+1]) * 0.5;
            nag_1d_spline_evaluate(xarg, &fit, &spline);
            printf(" %15.4f %27.4f\n",xarg,fit);
        }
    }
    nag_free(spline.lamda);
    nag_free(spline.c);

}

    The output is as follows:

     Number of distinct knots = 5

     Distinct knots located at

      0.0000 0.4000 0.6000 0.7500 1.0000

     J B-spline coeff c

     1        1.0000
     2        1.1336
     3        1.3726
     4        1.7827
     5        2.1744
     6        2.4918
     7        2.7183

     J Abscissa Ordinate Spline

     1        0.0000        1.0000        1.0000
              0.1000                      1.1052
     2        0.2000        1.2214        1.2214
              0.3000                      1.3498
     3        0.4000        1.4918        1.4918
              0.5000                      1.6487
     4        0.6000        1.8221        1.8221
                 0.6750                      1.9640
     5        0.7500        2.1170        2.1170
              0.8250                      2.2819
     6        0.9000        2.4596        2.4596
                  0.9500                      2.5857
     7        1.0000        2.7183        2.7183

Summary:
Sample data:
Header file: OCN_e01.h
See also:


nag_monotonic_interpolant

Function: nag_monotonic_interpolant
Prototype:
int nag_monotonic_interpolant(int n,double x[],double f[],double d[])
Remarks: computes a monotonicity-preserving piecewise cubic Hermite interpolant to a set of data points.
Parameters:
n
  the number of data points.
x[]
  the rth value of the independent variable (abscissa), for r = 0, 1 . . . , n - 1.
f[]
  the rth value of the dependent variable (ordinate), for r = 0, 1, . . . , n - 1.
d[]
  d[r] contains the derivative at x[r].

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 2: n = _value_.
236: On entry, x[r - 1] = x[r] for r = _value_: x[r - 1], x[r] = _values_.  The values of x[r], for r = 0, 1, . . . , n - 1, are not in strictly increasing order.
successful call of the nag_monotonic_interpolant function.

Example:
    Assume "Data1" Worksheet has 5 columns, the first 2 columns contain 9 data in each column
    and we want to put result in the third, fourth and fifth column.

    int i, m=11, n = 9, r;
    //Attach four Datasets to these 5 columns
    Dataset dx("data1",0);
    dx.SetSize(n);
    Dataset df("data1",1);
    df.SetSize(n);
    Dataset dd("data1",2);
    dd.SetSize(m);
    Dataset dpf("data1",3);
    dpf.SetSize(m);
    Dataset dpx("data1",4);
    dpx.SetSize(m);

    //vector can be a parameter, but Dataset cannot.
    vector x = dx, f = df, d = dd, pf = dpf, px = dpx;
    if(0 == nag_monotonic_interpolant(n, x, f, d))
    {
        double step = (x[n-1] - x[0]) / (1.0*(m-1));
        for (i = 0; i < m; i++)
        {
            if(x[0]+ i*step > x[n-1])
                px[i] =x[n-1];
            else
                px[i] = x[0]+ i*step;
        }
        nag_monotonic_evaluate(n, x, f, d, m, px, pf);
        //write the result back to the worksheet.
        dd = d;
        dpf = pf;
        dpx = px;
    }
    else
        printf("there is some problem with the function of nag_monotonic_interpolant");

    This example program reads in a set of data points, calls nag
    monotonic interpolant to compute a piecewise monotonic interpolant,
    and then calls nag monotonic evaluate (e01bfc) to evaluate the
    interpolant at equally spaced points.

void test_nag_monotonic_interpolant()
{

    int i, m, n, r;
    double step, d[50], pf[50], px[50];

    n = 9;
    double x[50] = {7.99, 8.09, 8.19, 8.70, 9.20, 10.00, 12.00, 15.00, 20.00};
    double f[50] = {0.00000E+0, 0.27643E-4, 0.43750E-1, 0.16918E+0, 0.46943E+0,
                    0.94374E+0, 0.99864E+0, 0.99992E+0, 0.99999E+0};

    if(0 == nag_monotonic_interpolant(n, x, f, d))
    {
        m = 11;
        step = (x[n-1] - x[0]) / (1.0*(m-1));
        for (i = 0; i < m; i++)
        {
            if(x[0]+ i*step > x[n-1])
                px[i] =x[n-1];
            else
                px[i] = x[0]+ i*step;
        }
        nag_monotonic_evaluate(n, x, f, d, m, px, pf);
    printf("                    Interpolated\n");
    printf("      Abscissa      Value\n");
        for (i = 0; i < m; i++)
            printf("%13.4f%13.4f\n", px[i], pf[i]);
    }
    else
        printf("there is some problem with the function of nag_monotonic_interpolant");
}

    The output is as follows:

                    Interpolated
    Abscissa 		Value

     7.9900 		0.0000
     9.1910 		0.4640
    10.3920 		0.9645
    11.5930 		0.9965
    12.7940 		0.9992
    13.9950 		0.9998
    15.1960 		0.9999
    16.3970 		1.0000
    17.5980 		1.0000
    18.7990 		1.0000
    20.0000 		1.0000

Summary:
Sample data:
Header file: OCN_e01.h
See also:


nag_monotonic_evaluate

Function: nag_monotonic_evaluate
Prototype:
int nag_monotonic_evaluate(int n,double x[],double f[],double d[],int m,double px[],double pf[])
Remarks: evaluates a piecewise cubic Hermite interpolant at a set of points.
Parameters:
d[]
  Input: n, x, f and d must be unchanged from the previous call of nag monotonic interpolant (e01bec).
m
  the number of points at which the interpolant is to be evaluated.
px[]
  Input: the m values of x at which the interpolant is to be evaluated.
pf[]
  Output: pf[i] contains the value of the interpolant evaluated at the point px[i], for i = 0, 1 . . .,m - 1.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 2: n = _value_.  On entry, m must not be less than 1: m = _value_.
236: On entry, x[r - 1] = x[r] for r = _value_: x[r - 1], x[r] = _values_.  The values of x[r], for r = 0, 1, . . . , n - 1, are not in strictly increasing order.
237: Warning - some points in array PX lie outside the range x[0]. . .x[n - 1]. Values at these points are unreliable as they have been computed by extrapolation.
successful call of the nag_monotonic_evaluate function.

Example:
    Assume "Data1" Worksheet has 5 columns, the first 3 columns contain 9 data in each column
    and we want to put result in the fourth and fifth column.

    int i, m = 11, n = 9, r;
    //Attach four Datasets to these 5 columns
    Dataset dx("data1",0);
    dx.SetSize(n);
    Dataset df("data1",1);
    df.SetSize(n);
    Dataset dd("data1",2);
    dd.SetSize(n);
    Dataset dpf("data1",3);
    dpf.SetSize(m);
    Dataset dpx("data1",4);
    dpx.SetSize(m);
    //vector can be a parameter, but Dataset cannot.
    vector x = dx, f = df, d = dd, pf = dpf, px = dpx;
    double step = (x[n-1] - x[0]) / (1.0*(m-1));
    for (i = 0; i < m; i++)
    {
        if(x[0]+ i*step > x[n-1])
            px[i] =x[n-1];
        else
            px[i] = x[0]+ i*step;
    }
    nag_monotonic_evaluate(n, x, f, d, m, px, pf);
    //put the result back to worksheet.
    dpf = pf;
    dpx = px;

    This example program reads in values of n, x, f, d and m, and
    then calls nag monotonic evaluate to evaluate the interpolant
    at equally spaced points.

void test_nag_monotonic_evaluate()
{

    int i, m, n, r;
    double step, pf[50], px[50];

    n = 9;
    m = 11;

    double x[50] = {7.99, 8.09, 8.19, 8.70, 9.20, 10.00, 12.00, 15.00, 20.00};
    double f[50] = {0.00000E+0, 0.27643E-4, 0.43750E-1, 0.16918E+0, 0.46943E+0,
                    0.94374E+0, 0.99864E+0, 0.99992E+0, 0.99999E+0};
    double d[50] = {0.00000E+0, 5.52510E-4, 0.33587E+0, 0.34944E+0, 0.59696E+0,
                    6.03260E-2, 8.98335E-4, 2.93954E-5, 0.00000E+0};

    step = (x[n-1] - x[0]) / (1.0*(m-1));
    for (i = 0; i < m; i++)
    {
        if(x[0]+ i*step > x[n-1])
            px[i] =x[n-1];
        else
            px[i] = x[0]+ i*step;
    }
    nag_monotonic_evaluate(n, x, f, d, m, px, pf);
    printf("                    Interpolated\n");
    printf("      Abscissa      Value\n");
    for (i = 0; i < m; i++)
        printf("%13.4f%13.4f\n", px[i], pf[i]);
}

    The output is as follows:

                 Interpolated
   Abscissa      Value
    7.9900       0.0000
    9.1910       0.4640
   10.3920       0.9645
   11.5930       0.9965
   12.7940       0.9992
   13.9950       0.9998
   15.1960       0.9999
   16.3970       1.0000
   17.5980       1.0000
   18.7990       1.0000
   20.0000       1.0000

Summary:
Sample data:
Header file: OCN_e01.h
See also:


nag_monotonic_deriv

Function: nag_monotonic_deriv
Prototype:
int nag_monotonic_deriv(int n,double x[],double f[],double d[],int m,double px[],double pf[],double pd[])
Remarks: evaluates a piecewise cubic Hermite interpolant and its first derivative at a set of points.
Parameters:
d[]
  Input: n, x, f and d must be unchanged from the previous call of nag monotonic interpolant (e01bec).
m
  the number of points at which the interpolant is to be evaluated.
px[]
  Input: the m values of x at which the interpolant is to be evaluated.
pf[]
  Output: pf[i] contains the value of the interpolant evaluated at the point px[i], for i = 0, 1, . . .,m - 1.
pd[]
  Output: pd[i] contains the .rst derivative of the interpolant evaluated at the point px[i], for i = 0, 1, . . .,m - 1.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 2: n = _value_.  On entry, m must not be less than 1: m = _value_.
236: On entry, x[r - 1] = x[r] for r = _value_: x[r - 1 ] =_value_, x[r] = _value_.  The values of x[r], for r = 0, 1, . . . , n - 1a re not in strictly increasing order.
successful call of the nag_monotonic_deriv function.

Example:
    Assume "Data1" Worksheet has 6 columns and 10 rows, the first 3 columns contain 5 data in each column
    and we want to put result in the fourth to sixth column.

    int i, m = 7, n = 5, r;
    double step;
    //Attach six Datasets to these 6 columns
    Dataset dx("data1",0);
    dx.SetSize(n);
    Dataset df("data1",1);
    df.SetSize(n);
    Dataset dd("data1",2);
    dd.SetSize(n);
    Dataset dpf("data1",3);
    dpf.SetSize(m);
    Dataset dpx("data1",4);
    dpx.SetSize(m);
    Dataset dpd("data1",5);
    dpd.SetSize(m);
    //vector can be a parameter, but Dataset cannot.
    vector x = dx, f = df, d = dd, pf = dpf, px = dpx, pd = dpd;
    step = (x[n-1]-x[0]) / (double)(m-1);
    for (i = 0; i < m; i++)
    {
        if(x[0]+ i*step > x[n-1])
            px[i] =x[n-1];
        else
            px[i] = x[0]+ i*step;
    }
    nag_monotonic_deriv(n, x, f, d, m, px, pf, pd);
    //Put the results to the Worksheet.
    dpf = pf;
    dpx = px;
    dpd = pd;

    This example program reads in values of n, x, f and d and calls
    nag monotonic deriv to compute the values of the interpolant and
    its derivative at equally spaced points.

void test_nag_monotonic_deriv()
{

    int i, m, n, r;
    double pd[21], pf[21], px[21], step;
    n = 9;
    m = 11;

    double x[50] = {7.99, 8.09, 8.19, 8.70, 9.20, 10.00, 12.00, 15.00, 20.00};
    double f[50] = {0.00000E+0, 0.27643E-4, 0.43750E-1, 0.16918E+0, 0.46943E+0,
                    0.94374E+0, 0.99864E+0, 0.99992E+0, 0.99999E+0};
    double d[50] = {0.00000E+0, 5.52510E-4, 0.33587E+0, 0.34944E+0, 0.59696E+0,
                    6.03260E-2, 8.98335E-4, 2.93954E-5, 0.00000E+0};

    step = (x[n-1]-x[0]) / (double)(m-1);
    for (i = 0; i < m; i++)
    {
        if(x[0]+ i*step > x[n-1])
            px[i] =x[n-1];
        else
            px[i] = x[0]+ i*step;
    }
    nag_monotonic_deriv(n, x, f, d, m, px, pf, pd);
    printf("                      Interpolated  Interpolated\n");
    printf("        Abscissa         Value       Derivative\n");
    for (i=0; i<m; i++)
        printf("%15.4f %15.4f %15.3e\n",px[i],pf[i],pd[i]);
}

    The output is as follows:

                  Interpolated  Interpolated
    Abscissa         Value       Derivative
     7.9900          0.0000      0.000e+000
     9.1910          0.4640      6.060e-001
    10.3920          0.9645      4.569e-002
    11.5930          0.9965      9.917e-003
    12.7940          0.9992      6.249e-004
    13.9950          0.9998      2.708e-004
    15.1960          0.9999      2.809e-005
    16.3970          1.0000      2.034e-005
    17.5980          1.0000      1.308e-005
    18.7990          1.0000      6.297e-006
    20.0000          1.0000      -3.388e-021

Summary:
Sample data:
Header file: OCN_e01.h
See also:


nag_monotonic_intg

Function: nag_monotonic_intg
Prototype:
int nag_monotonic_intg(int n,double x[],double f[],double d[],double a,double b,double *integral)
Remarks: evaluates the definite integral of a piecewise cubic Hermite interpolant over the interval [a, b].
Parameters:
d[]
  Input: n, x, f and d must be unchanged from the previous call of nag monotonic interpolant (e01bec).
b
  Input: the interval [a, b] over which integration is to be performed.
integral
  Output: the value of the definite integral of the interpolant over the interval [a, b].

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 2: n = _value_.
236: On entry, x[r - 1] = x[r] for r = _value_: x[r - 1] = _value_, x[r] = _value_.  The values of x[r], for r = 0, 1, . . . , n - 1 are not in strictly increasing order.
237: On entry, limits a, b must not be outside interval [x[0], x[n - 1]], a = _value_, b = _value_, x[0] = _value_, x[_value_] = _value_. Extrapolation was performed to compute the integral.  The value returned is therefore unreliable.
successful call of the nag_monotonic_intg function.

Example:
    Assume "Data1" Worksheet has 3 columns and 9 rows, and contain 9 data in each column.
    "Data2" Worksheet has 3 columns and 4 rows, the first two columns contain 4 data in
    each column.  This piece of code reads in values of "Data1", and then reads in pair
    of "Data2" first two columns, and evaluates the definite integral of the intepolant
    over the interval [a, b].

    int n = 9, nn = 4;
    //Attach six Datasets to these 6 columns
    Dataset dx("data1",0);
    dx.SetSize(n);
    Dataset df("data1",1);
    df.SetSize(n);
    Dataset dd("data1",2);
    dd.SetSize(n);
    Dataset da("data2",0);
    da.SetSize(nn);
    Dataset db("data2",1);
    db.SetSize(nn);
    Dataset dintegral("data2",2);
    dintegral.SetSize(nn);
    //vector can be a parameter, but Dataset cannot.
    vector x = dx, f = df, d = dd, a = da, b = db, integral = dintegral;
    for(int i = 0; i < nn; i++)
    {
        nag_monotonic_intg(n, x, f, d, a[i], b[i], &integral[i]);
    }
    //put the result to the "data2" third column.
    dintegral = integral;

    This example program reads in values of n, x, f and d. It then reads
    in pairs of values for a and b, and evaluates the definite integral
    of the interpolant over the interval [a, b] until end-of-file is reached.

void test_nag_monotonic_intg()
{
    double integral;
    int n, r;

    n = 9;
    double x[50] = {7.99, 8.09, 8.19, 8.70, 9.20, 10.00, 12.00, 15.00, 20.00};
    double f[50] = {0.00000E+0, 0.27643E-4, 0.43750E-1, 0.16918E+0, 0.46943E+0,
                    0.94374E+0, 0.99864E+0, 0.99992E+0, 0.99999E+0};
    double d[50] = {0.00000E+0, 5.52510E-4, 0.33587E+0, 0.34944E+0, 0.59696E+0,
                    6.03260E-2, 8.98335E-4, 2.93954E-5, 0.00000E+0};

    double a[4] = {7.99, 10.0, 12.0, 15.0};
    double b[4] = {20.0, 12.0, 10.0, 15.0};
    printf("					    Integral\n");
    printf("	a 		  b 		    over (a,b)\n");
    for(int i = 0; i < 4; i++)
    {
        nag_monotonic_intg(n, x, f, d, a[i], b[i], &integral);
        printf("%13.4f %13.4f %13.4f\n",a[i],b[i],integral);
    }
}

    The output is as follows:

                            Integral
    a 		  b	 		    over (a,b)
     7.9900   20.0000       10.7648
    10.0000   12.0000        1.9622
    12.0000   10.0000       -1.9622
    15.0000   15.0000        0.0000

Summary:
Sample data:
Header file: OCN_e01.h
See also:


nag_2d_spline_interpolant

Function: nag_2d_spline_interpolant
Prototype:
int nag_2d_spline_interpolant(int mx,int my,double x[],double y[],double f[],Nag_2dSpline *spline)
Remarks: computes a bicubic spline interpolating surface through a set of data values, given on a rectangular grid in the x-y plane.
Parameters:
my
  Input: mx and my must specify mx and my respectively, the number of points along the x and y axis that define the rectangular grid.
y[]
  Input: x[q-1] and y[r-1] must contain xq, for q = 1, 2, . . .,mx, and yr, for r = 1, 2, . . .,my, respectively.
f[]
  Input: f[my × (q - 1) + r - 1] must contain fq,r, for q = 1, 2, . . .,mx; r = 1, 2, . . .,my.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, mx must not be less than 4: mx = _value_.  On entry, my must not be less than 4: my = _value_.
63: The sequence x is not strictly increasing: x[_value_] = _value_, x[_value_] = _value_.  The sequence y is not strictly increasing: y[_value_] = _value_, y[_value_] = _value_.
73: Memory allocation failed.
243: An intermediate set of linear equations is singular, the data is too ill-conditioned to compute B-spline coefficients.
successful call of the nag_2d_spline_interpolant function.

Example:
    Assume we have a Worksheet "data1" which has three columns and 20
    rows.  The first column shows the x axis value, and there are 5 data
    in this column.  The second column shows the y axis value, and there
    are 4 data in this column.  The third column contains 20 data.  This
    piece of code computes a bicubic spline interpolating surface through
    a set of data values.

    int mx = 5, my = 4;
    Nag_2dSpline spline;
    //Attach three Datasets to these 3 columns
    Dataset dx("data1",0);
    dx.SetSize(mx);
    Dataset dy("data1",1);
    dy.SetSize(my);
    Dataset df("data1",2);
    df.SetSize(20);
    //vector can be a parameter, but Dataset cannot.
    vector x = dx, y = dy, f = df;
    nag_2d_spline_interpolant(mx, my, x, y, f, &spline);

       This program reads in values of mx, xq for q = 1, 2, . . .,mx, my
    and yr for r = 1, 2, . . .,my, followed by values of the
    ordinates fq,r defined at the grid points (xq, yr). It then calls
    nag 2d spline interpolant to compute a bicubic spline interpolant
    of the data values, and prints the values of the knots and
    B-spline coefficients. Finally it evaluates the spline at a
    small sample of points on a rectangular grid.

void test_nag_2d_spline_interpolant()
{
    int i, j, mx, my, npx, npy;
    double fg[400], tx[20], ty[20];
    double xhi, yhi, xlo, ylo, step;
    Nag_2dSpline spline;

    mx = 7;
    my = 6;
    double x[20] = {1.0, 1.10, 1.30, 1.50, 1.60, 1.80, 2.00};

    double y[20] = {0.00, 0.10, 0.40, 0.70, 0.90, 1.00};

    double f[400] = {1.00, 1.10, 1.40, 1.70, 1.90, 2.00, 1.21, 1.31, 1.61, 1.91,
                     2.11, 2.21, 1.69, 1.79, 2.09, 2.39, 2.59, 2.69, 2.25, 2.35,
                     2.65, 2.95, 3.15, 3.25, 2.56, 2.66, 2.96, 3.26, 3.46, 3.56,
                     3.24, 3.34, 3.64, 3.94, 4.14, 4.24, 4.00, 4.10, 4.40, 4.70,
                     4.90, 5.00};

    nag_2d_spline_interpolant(mx, my, x, y, f, &spline);

    printf("Distinct knots in x direction located at\n");
    for (j=3; j<spline.nx-3; j++)
    {
        printf("%12.4f",spline.lamda[j]);
        if((j-3)%5==4 || j==spline.nx - 4)
            printf("\n");
    }

    printf("\nDistinct knots in y direction located at\n");
    for (j=3; j<spline.ny-3; j++)
    {
        printf("%12.4f",spline.mu[j]);
        if((j-3)%5==4 || j==spline.ny-4)
            printf("\n");
    }

    printf("\nThe B-Spline coefficients:\n");
    for (i=0; i<mx; i++)
    {
        for (j=0; j<my; j++)
            printf("%9.4f",spline.c[my*i+j]);
        printf("\n");
    }

    npx = 6;
    npy = 6;
    xlo = 1.0;
    ylo = 0.0;
    xhi = 2.0;
    yhi = 1.0;

    step = (xhi-xlo)/(1.0*(npx-1));
    printf("\nSpline evaluated on a regular mesh (x across, y down): \n ");

    for (i=0; i<npx; i++)
    {
        if(xlo + i * step > xhi)
            tx[i] = xhi;
        else
            tx[i] = xlo + i * step;
        printf(" %5.2f ",tx[i]);
    }

    step = (yhi-ylo)/(npy-1);
    for (i=0; i<npy; i++)
    {
        if(ylo + i * step > yhi)
            ty[i] = yhi;
        else
            ty[i] = ylo + i * step;
    }
    nag_2d_spline_eval_rect(npx, npy, tx, ty, fg, &spline);

    printf("\n");
    for (j=0; j<npy; j++)
    {
        printf("%5.2f",ty[j]);
        for (i=0; i<npx; i++)
            printf("%8.3f ",fg[npy*i+j]);
        printf("\n");
    }
    nag_free(spline.lamda);
    nag_free(spline.mu);
    nag_free(spline.c);

}

    The output is as follows:

    Distinct knots in x direction located at
      1.0000      1.3000      1.5000      1.6000      2.0000

    Distinct knots in y direction located at
      0.0000      0.4000      0.7000      1.0000

    The B-Spline coefficients:
       1.0000   1.1333   1.3667   1.7000   1.9000   2.0000
       1.2000   1.3333   1.5667   1.9000   2.1000   2.2000
       1.5833   1.7167   1.9500   2.2833   2.4833   2.5833
       2.1433   2.2767   2.5100   2.8433   3.0433   3.1433
       2.8667   3.0000   3.2333   3.5667   3.7667   3.8667
       3.4667   3.6000   3.8333   4.1667   4.3667   4.4667
       4.0000   4.1333   4.3667   4.7000   4.9000   5.0000

    Spline evaluated on a regular mesh (x across, y down):
       1.00   1.20   1.40   1.60   1.80   2.00
     0.00   1.000    1.440    1.960    2.560    3.240    4.000
     0.20   1.200    1.640    2.160    2.760    3.440    4.200
     0.40   1.400    1.840    2.360    2.960    3.640    4.400
     0.60   1.600    2.040    2.560    3.160    3.840    4.600
     0.80   1.800    2.240    2.760    3.360    4.040    4.800
     1.00   2.000    2.440    2.960    3.560    4.240    5.000

Summary:
Sample data:
Header file: OCN_e01.h
See also:


nag_2d_scat_interpolant

Function: nag_2d_scat_interpolant
Prototype:
int nag_2d_scat_interpolant(Nag_2d_Scat_Method method,int m,double x[],double y[],double f[],Nag_Scat_Struct *comm,Nag_E01_Opt *optional)
Remarks: generates a two-dimensional surface interpolating a set of scattered data points, using either the method of Renka and Cline or a modification of Shepard's method.
Parameters:
m
  the number of data points, m.
x[]
  Input: the co-ordinates of the rth data point, for r = 1, 2, . . .,m. The data points are accepted in any order, but see Section 6.
y[]
  Input: the co-ordinates of the rth data point, for r = 1, 2, . . .,m. The data points are accepted in any order, but see Section 6.
f[]
  Input: the co-ordinates of the rth data point, for r = 1, 2, . . .,m. The data points are accepted in any order, but see Section 6.
comm
  Pointer to a communication structure of type Nag Scat Struct. For method = Nag RC, this structure contains the computed triangulation and the estimated partial derivatives at the nodes. For method = Nag Shep, this structure contains the coefficients of the constructed nodal functions.  This structure must be passed unchanged to the interpolant evaluating function nag 2d scat eval (e01sbc).
optional
  Pointer to structure of type Nag E01 Opt, which may be used only if method = Nag Shep.

Return values:
This function returns NAG error code, 0 if no error.
70: On entry, parameter method had an illegal value.
11: On entry, m must not be less than 3: m = _value_.
73: Memory allocation failed.
245: On entry, all the (x,y) pairs are collinear. Consider specifying method = Nag Shep or usinga one-dimensional interpolating function nag 1d spline interpolant (e01bac).
246: On entry, each data pair is not unique since data points (x[_value_],y[_value_]) and (x[_value_],y[_value_]) are identical and equal to (_value_,_value_).
247: On entry, either or both of optional.nq and optional.nw are invalid, optional.nq = _value_ and optional.nw = _value_. optional.nq and optional.nw must satisfy the following constraints: 0 < optional.nw = optional.nq.
248: On entry, either or both of optional.rnq and optional.rnw are invalid, optional.rnq = _value_ and optional.rnw = _value_. optional.rnq and optional.rnw must satisfy the following constraints: 0.0 < optional.rnw = optional.rnq.
249: The minimum number of data points _value_ that lie within the radius optional.rnq of any node is small enough to indicate that the interpolant may be unsatisfactory in regions where the data points are sparse. Current values of other relevant parameters (available as members of the structure optional, if this has been defined) are rnq = _value_, rnw = _value_, nq = _value_, nw = _value_.
successful call of the nag_2d_scat_interpolant function.

Example:
    Assume we have Worksheet "data1" which has 9 columns and 30 rows.
    The first three columns contain 30 data in each column.  This example
    shows user to use nag_2d_scat_interpolant(e01sac), nag_2d_scat_eval(e01sbc),
    and nag_ad_scat_free(e01szc).  The result will be put the in the rest
    six columns of "data1".

    int i, isel, j, m = 30, n = 0, nx = 7, ny = 6;
    double xhi = 21.0, xlo = 3.0, yhi = 17.0, ylo = 2.0;
    Nag_Scat_Struct comm;
    Nag_2d_Scat_Method method;
    Nag_E01_Opt optional;
    //Attach nine Datasets to these 9 columns
    Dataset dx("data1",0);
    dx.SetSize(m);
    Dataset dy("data1",1);
    dy.SetSize(m);
    Dataset df("data1",2);
    df.SetSize(m);
    Dataset dpx("data1",3);
    dpx.SetSize(100);
    Dataset dpy("data1",4);
    dpy.SetSize(100);
    Dataset dpf("data1",5);
    dpf.SetSize(100);
    Dataset dmpx("data1",6);
    dmpx.SetSize(100);
    Dataset dmpy("data1",7);
    dmpy.SetSize(100);
    Dataset dmpf("data1",8);
    dmpf.SetSize(100);
    //vector can be a parameter, but Dataset cannot.
    vector x = dx, y = dy, f = df, px = dpx, py = dpy, pf = dpf;

    for (isel=1; isel<=2; ++isel)
    {
        if (isel==1)
            method = Nag_RC;
        else if (isel==2)
            method = Nag_Shep;

        if (method==Nag_RC)
            nag_2d_scat_interpolant(method, m, x, y, f, &comm, NULL);
        if (method==Nag_Shep)
        {
            optional.nq = 24;
            optional.nw = 12;
            optional.rnq = -1.0;
            nag_2d_scat_interpolant(method, m, x, y, f, &comm, &optional);
            printf("   optional.rnw =%8.2f optional.rnq =%8.2f\n\n",	optional.rnw, optional.rnq);
            printf("   minimum number of data points that lie within radius 	optional.rnq =%3ld\n", optional.minnq);
        }
        for (j=0; j<ny; ++j)
        {
            for (i=0; i<nx; ++i)
            {
                px[i+nx*j] = (1.0 * (nx-i-1) / (nx-1)) * xlo + (1.0*i / (nx-1)) * xhi;
                py[i+nx*j] = (1.0 * (ny-j-1) / (ny-1)) * ylo +	(1.0* j / (ny-1)) * yhi;
                ++n;
            }
        }

        if (method == Nag_RC)
        {
            nag_2d_scat_eval(&comm, n, px, py, pf);
            //put the result to "data1" the fourth column to the sixth column.
            dpx = px;
            dpy = py;
            dpf = pf;
        }
        if (method == Nag_Shep)
        {
            nag_2d_scat_eval(&comm, n, px, py, pf);
            //put the result to "data1" the seventh column to ninth column.
            dmpx = px;
            dmpy = py;
            dmpf = pf;
        }

        nag_2d_scat_free(&comm);
    }

    This program reads in a set of 30 data points and calls
    nag 2d scat interpolant to construct an interpolating surface.
    It then calls nag 2d scat eval (e01sbc) to evaluate the
    interpolant at a sample of points on a rectangular grid.
    The two methods described in Section 3 are used in the
    construction of the interpolating surface and the subsequent
    evaluation of the interpolant.  Note that this example is not
    typical of a realistic problem: the number of data points would
    normally be larger, and the interpolant would need to be evaluated
    on a finer grid to obtain an accurate plot, say.

void test_nag_2d_scat_interpolant()
{

    int i, isel, j, m, n, nx, ny;
    double xhi, xlo, yhi, ylo;
    double pf[100], px[100], py[100];
    Nag_Scat_Struct comm;
    Nag_2d_Scat_Method method;
    Nag_E01_Opt optional;

    nx = 7;
    ny = 6;
    xlo = 3.0;
    ylo = 2.0;
    xhi = 21.0;
    yhi = 17.0;
    m = 30;
    double x[100] = {11.16, 12.85, 19.85, 19.72, 15.91, 0.00, 20.87, 3.45, 14.26, 17.43,
                     22.80, 7.58, 25.00, 0.00, 9.66, 5.22, 17.25, 25.00, 12.13, 22.23,
                     11.52, 15.20, 7.54, 17.32, 2.14, 0.51, 22.69, 5.47, 21.67, 3.31};

      double y[100] = {1.24, 3.06, 10.72, 1.39, 7.74, 20.00, 20.00, 12.78, 17.87, 3.46,
                       12.39, 1.98, 11.87, 0.00, 20.00, 14.66, 19.57, 3.87, 10.79, 6.21,
                       8.53, 0.00, 10.69, 13.78, 15.03, 8.37, 19.63, 17.13, 14.36, 0.33};

    double f[100] = {22.15, 22.11, 7.97, 16.83, 15.30, 34.60, 5.74, 41.24, 10.74, 18.60,
                     5.47, 29.87, 4.40, 58.20, 4.73, 40.36, 6.43, 8.74, 13.71, 10.25,
                     15.74, 21.60, 19.31, 12.11, 53.10, 49.43, 3.25, 28.63, 5.52, 44.08};

    for (isel=1; isel<=2; ++isel)
    {
        if (isel==1)
            method = Nag_RC;
        else if (isel==2)
            method = Nag_Shep;

        if (method==Nag_RC)
            nag_2d_scat_interpolant(method, m, x, y, f, &comm, NULL);

        if (method==Nag_Shep)
        {

            optional.nq = 24;
            optional.nw = 12;
            optional.rnq = -1.0;
            nag_2d_scat_interpolant(method, m, x, y, f, &comm, &optional);
            printf("   optional.rnw =%8.2f optional.rnq =%8.2f\n\n",	optional.rnw, optional.rnq);
            printf("   minimum number of data points that lie within radius 	optional.rnq =%3ld\n", optional.minnq);
        }

        n = 0;

        for (j=0; j<ny; ++j)
        {
            for (i=0; i<nx; ++i)
            {
                px[i+nx*j] = (1.0 * (nx-i-1) / (nx-1)) * xlo + (1.0*i / (nx-1)) * xhi;
                py[i+nx*j] = (1.0 * (ny-j-1) / (ny-1)) * ylo +	(1.0* j / (ny-1)) * yhi;
                ++n;
            }
        }

        if (method == Nag_RC)
            nag_2d_scat_eval(&comm, n, px, py, pf);
        if (method == Nag_Shep)
            nag_2d_scat_eval(&comm, n, px, py, pf);

        printf("\n   px\n");
        for (i = 0; i < nx; i++)
            printf("%8.2f", px[i]);
        printf("\n   py       pf\n");
        for (i = ny-1; i >= 0; --i)
        {
            printf("%8.2f ", py[nx * i]);
            for (j = 0; j < nx; j++)
                printf("%8.2f", pf[nx * i + j]);
            printf("\n");
        }
        nag_2d_scat_free(&comm);
    }
}

    The output is as follows:

    px
        3.00    6.00    9.00   12.00   15.00   18.00   21.00
       py       pf
      17.00    41.25   27.62   18.03   12.29   11.68    9.09    5.37
      14.00    47.61   36.66   22.87   14.02   13.44   11.20    6.46
      11.00    38.55   25.25   16.72   13.83   13.08   10.71    6.88
       8.00    37.90   23.97   16.79   16.43   15.46   13.02    9.30
    5.00    40.49   29.26   22.51   20.72   19.30   16.72   12.87
    2.00    43.52   33.91   26.59   22.23   21.15   18.67   14.88
    optional.rnw =    9.49 optional.rnq =   13.42

    minimum number of data points that lie within radius 	optional.rnq =  7

    px
     3.00    6.00    9.00   12.00   15.00   18.00   21.00
    py       pf
    17.00    40.23   27.72   21.23   14.59   12.00    9.43    5.46
    14.00    46.96   37.37   23.74   14.67   13.25   11.29    6.26
    11.00    39.42   25.42   16.32   13.78   12.60   10.39    7.03
     8.00    37.50   22.36   18.57   15.63   15.55   13.05    9.69
     5.00    41.25   31.76   24.74   21.17   18.93   16.83   12.65
     2.00    44.58   34.35   26.47   22.27   20.98   18.69   15.06

Summary:
Sample data:
Header file: OCN_e01.h
See also:


nag_2d_scat_eval

Function: nag_2d_scat_eval
Prototype:
int nag_2d_scat_eval(Nag_Scat_Struct *comm,int n,double px[],double py[],double pf[])
Remarks: evaluates at given points the two-dimensional interpolant function computed by nag 2d scat interpolant (e01sac).
Parameters:
comm
  Pointer to a communication structure of type Nag Scat Struct which must be unchanged from the previous call of nag 2d scat interpolant (e01sac).
n
  the number of points at which the evaluation of the interpolant is required.
py[]
  Input: the x- and y-coordinates of the kth point (pxk, pyk),fo r k = 1, 2, . . . ,n,at which the interpolant is to be evaluated.
pf[]
  Output: the values of the interpolant evaluated at the points (pxk, pyk),fo r k = 1, 2, . . . ,n.

Return values:
This function returns NAG error code, 0 if no error.
178: The setup function nag 2d scat interpolant (e01sac) has not been called.
179: The call to setup function nag 2d scat interpolant (e01sac) produced an error.
81: The structure _value_ has been corrupted since the previous call to _value_.
11: On entry, n must not be less than 1: n = _value_.
251: The evaluation point (_value_, _value_) of (px, py) lies outside the triangulation boundary.  The returned value, _value_,of pf was computed by extrapolation.
252: On entry,the interpolant cannot be evaluted because the evaluation point (px, py) of (_value_, _value_) is outside the support region of the input data points defined by optional.rnw= _value_ as set in nag 2d scat interpolant (e01sac).
successful call of the nag_2d_scat_eval function.

Example:

    See the example program for nag 2d scat interpolant (e01sac).

Summary:
Sample data:
Header file: OCN_e01.h
See also:


nag_2d_scat_free

Function: nag_2d_scat_free
Prototype:
void nag_2d_scat_free(Nag_Scat_Struct *comm)
Remarks: frees the memory allocated by NAG function nag 2d scat interpolant (e01sac) to the communication structure comm of type Nag Scat Struct.
Parameters:
comm
  Input: the communication structure that was used in the call to nag 2d scat interpolant (e01sac).  Output: pointers which pointed to NAG allocated memory will have been freed and set to NULL.

Return values:
This function returns NAG error code, 0 if no error.
successful call of the nag_2d_scat_free function.

Example:

    See nag 2d scat interpolant (e01sac) for an example of hown ag 2d scat free is used.

Summary:
Sample data:
Header file: OCN_e01.h
See also:


nag_1d_cheb_fit

Function: nag_1d_cheb_fit
Prototype:
int nag_1d_cheb_fit(int m,int kplus,int tda,const double x[],const double y[],const double w[],double a[],double s[])
Remarks: computes weighted least-squares polynomial approximations to an arbitrary set of data points.
Parameters:
m
  the number m of data points.
kplus
  k + 1, where k is the maximum degree required
tda
  the second dimension of the array a.
x[]
  the values xr of the independent variable
y[]
  the values yr of the dependent variable.
w[]
  the set of weights, wr, for r = 1, 2, . . .,m.
a[]
  the coefficients of in the approximating polynomial of degree i
s[]
  the root mean square residual si, for i = 0, 1, . . . , k

Return values:
This function returns NAG error code, 0 if no error.
successfully call of the nag_1d_cheb_fit function.

Example:
    Assume we have "Data1" Worksheet and "Matrix1" Matrix.  "Data1" Worksheet has 4 columns, the first
    3 columns contain 4 data in each column and we want to put result in the fourth column and at
    "Matrix1" matrix.

    int tdim = 10, m = 4;
    //Attach four Datasets to these 4 columns
    Dataset xx("data1",0);
    Dataset yy("data1",1);
    Dataset ww("data1",2);
    Dataset ss("data1",3);
    xx.SetSize(m);
    yy.SetSize(m);
    ww.SetSize(m);
    ss.SetSize(m);
    //Because Dataset cannot be the parameter of function, but vector can be.
    vector x = xx;
    vector y = yy;
    vector w = ww;
    vector s = ss;
    //So you need 4 vectors for this function.
    //Because matrix can be the parameter of function, but Matrix cannot.
    matrix a;
    a.SetSize(20, 20);		//use a as a parameter of a function.

    //Call function here, x, y, w, s are four vectors, and a is a matrix.
    int success = nag_1d_cheb_fit(m, 4, tdim, x, y, w, a, s);

    //After call the function, let the fourth dataset eqauls to the fourth vector by using
    ss = s;
    //After get result, let a Matrix equals to matrix by using
    Matrix aa("Matrix1");
    aa = a;

    Determine weighted least-squares polynomial approximations of degrees 0, 1, 2 and 3 to
    a set of 11 prescribed data points.

void test_nag_1d_cheb_fit()
{
    double d1;
    double xarg;
    matrix a;
    a.SetSize(50, 50);
    double s[200], xcapr;
    double x[200] = {1.00, 2.10, 3.10, 3.90, 4.90, 5.80, 6.50, 7.10, 7.80, 8.40, 9.00};
    double y[200] = {10.40, 7.90, 4.70, 2.50, 1.20, 2.20, 5.10, 9.20, 16.10, 24.50, 35.30};
    double w[200] = {1.00, 1.00, 1.00, 1.00, 1.00, 0.80, 0.80, 0.70, 0.50, 0.30, 0.20};
    double x1, ak[50], xm, fit;
    int i, j, k, m, r;
    int iwght = 2;
    int tdim = 50;
    int success;

    printf("e02adc Example Program Results \n");
    m = 11;
    k = 3;

    printf("the input data are as following:\n");
    printf("m = 11, k = 2, iwght = 3\n");
    printf("x:\n");
    for(i = 0; i < m; i++)
    {
        printf("%3.2f  ",x[i]);
        if((i + 1) % 5 == 0)
            printf("\n");
    }
    printf("\ny:\n");
    for(i = 0; i < m; i++)
    {
        printf("%3.2f  ",y[i]);
        if((i + 1) % 5 == 0)
            printf("\n");
    }
    printf("\nw:\n");
    for(i = 0; i < m; i++)
    {
        printf("%3.2f  ",w[i]);
        if((i + 1) % 5 == 0)
            printf("\n");
    }

    success = nag_1d_cheb_fit(m, 4, tdim, x, y, w, a, s);

    if( success == 0)
    {
        for (i = 0; i <= k; ++i)
        {
            printf("\n");
            printf(" %s%4ld%s%12.2e\n","Degree",i," R.M.S. residual =",s[i]);
            printf("\n J Chebyshev coeff A(J) \n");
            for (j = 0; j < i+1; ++j)
                printf(" %3ld%15.4f\n",j+1,a[i][j]);
        }
        for (j = 0; j < k+1; ++j)
            ak[j] = a[k][j];
        x1 = x[0];
        xm = x[m-1];
        printf("\n %s%4ld\n","Polynomial approximation and residuals for degree",k);
        printf("\n R Abscissa Weight Ordinate Polynomial Residual\n");
        for (r = 1; r <= m; ++r)
        {
            xcapr = (x[r-1] - x1 - (xm - x[r-1])) / (xm - x1);
            nag_1d_cheb_eval(k+1, ak, xcapr, &fit);
            d1 = fit - y[r-1];
            printf(" %3ld%11.4f%11.4f%11.4f%11.4f%11.2e\n",r,x[r-1],w[r-1],y[r-1],fit,d1);
            if (r < m)
            {
                xarg = (x[r-1] + x[r]) * 0.5;
                xcapr = (xarg - x1 - (xm - xarg)) / (xm - x1);
                success = nag_1d_cheb_eval(k+1, ak, xcapr, &fit);
                if( success == 0)
                    printf(" %11.4f %11.4f\n",xarg,fit);
                else
                {
                    printf("there is some problem with the function");
                    break;
                }
            }
        }
    }
    else
        printf("there is some problem with this function");
}

    The output is following:

    Degree 0 R.M.S. residual = 4.07e+00
    J Chebyshev coeff A(J)
    1 		12.1740

    Degree 1 R.M.S. residual = 4.28e+00
    J 	Chebyshev coeff A(J)
    1 		12.2954
    2 	 	 0.2740

    Degree 2 R.M.S. residual = 1.69e+00
    J 	Chebyshev coeff A(J)
    1 		20.7345
    2 	 	 6.2016
    3 	 	 8.1876

    Degree 3 R.M.S. residual = 6.82e-02
    J 	Chebyshev coeff A(J)
    1 		24.1429
    2 	 	 9.4065
    3 		10.8400
    4 	 	 3.0589

    Polynomial approximation and residuals for degree 3

    R 	Abscissa 	Weight 	Ordinate 	Polynomial 		Residual

    1 	1.0000 		1.0000 	10.4000 	10.4461 		 4.61e-02
        1.5500 							9.3106
    2 	2.1000 		1.0000 	7.9000 		7.7977 			-1.02e-01
        2.6000 							6.2555
    3 	3.1000 		1.0000 	4.7000 		4.7025 			 2.52e-03
        3.5000 							3.5488
    4 	3.9000 		1.0000 	2.5000 		2.5533 			 5.33e-02
        4.4000 							1.6435
    5 	4.9000 		1.0000 	1.2000 		1.2390 			 3.90e-02
        5.3500 							1.4257
    6 	5.8000 		0.8000 	2.2000 		2.2425 			 4.25e-02
        6.1500 							3.3803
    7 	6.5000 		0.8000 	5.1000 		5.0116 			-8.84e-02
        6.8000 							6.8400
    8 	7.1000 		0.7000 	9.2000 		9.0982 			-1.02e-01
        7.4500 							12.3171
    9 	7.8000 		0.5000 	16.1000 	16.2123 		 1.12e-01
        8.1000 							20.1266
    10 	8.4000 		0.3000 	24.5000 	24.6048 		 1.05e-01
         8.7000 							29.6779
    11 	9.0000 		0.2000 	35.3000 	35.3769 		 7.69e-02

Summary: least squares curve fit with polynomials and arbitrary data points
Sample data:
Header file: OCN_e02.h
See also:


nag_1d_cheb_eval

Function: nag_1d_cheb_eval
Prototype:
int nag_1d_cheb_eval(int nplus1,const double a[],double xcap,double *p)
Remarks: evaluates a polynomial from its Chebyshev-series representation
Parameters:
nplus1
  the number n + 1 of terms in the series
a[]
  the value of the ith coe.cient in the series, for i = 1, 2, . . ., n+1.
xcap
  the argument at which the polynomial is to be evaluated.
p
  the value of the polynomial.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, nplus1 must not be less than 1: nplus1 = _value_.
271: On entry, abs(xcap) > 1.0 + 4 _, w here _ is the machine precision.  In this case the value of p is set arbitrarily to zero.
successfully call of the nag_1d_cheb_eval function.

Example:
    Assume "Data1" Worksheet has three columns, the first column contains 5 data,
    and we want to put result in the second and third column.

    int i, m = 11, n = 4, r, success;
    //Attach three Datasets to these 3 columns
    Dataset aa("data1",0);
    Dataset dxcap("data1",1);
    Dataset pp("data1",2);
    aa.SetSize(n+1);
    dxcap.SetSize(m);
    pp.SetSize(m);
    //Because Dataset cannot be the parameter of function, but vector can be.
    vector a = aa;
    vector xcap = dxcap;
    vector p = pp;
    for(r = 0; r < m; r++)
    {
        xcap[r] = 1.0 * (2*r - m + 1 ) / (1.0* (m - 1)) ;
        success = nag_1d_cheb_eval(5, a , xcap[r], &p[r]);
    }
    //put the result to Worksheet columns.
    dxcap = xcap;
    pp = p;

    Evaluate at 11 equally-spaced points in the interval -1 = ¯x = 1 the polynomial of degree 4 with
    Chebyshev coe.cients, 2.0, 0.5, 0.25, 0.125, 0.0625.

void test_nag_1d_cheb_eval()
{
    double xcap;
    double a[200] = {2.0000, 0.5000, 0.2500, 0.1250, 0.0625};
    double p;
    int i, m = 11, n = 4;
    int r;
    int success;
    printf("e02aec Example Program Results \n");

    printf("the input data:\n");
    printf("m = 11, n = 4 ");
    printf("\na:\n");
    for(r = 0; r < 5; r++)
        printf("%10.4f",a[r]);

    printf("\n R Argument Value of polynomial \n");
    for(r = 0; r < m; r++)
    {
        xcap = 1.0 * (2*r - m + 1 ) / (1.0* (m - 1)) ;
        success = nag_1d_cheb_eval(5, a , xcap, &p);
        if(success == 0)
            printf(" %3ld%14.4f %35.4f\n",r,xcap,p);
        else
        {
            printf("there is some problem with the function");
            break;
        }
    }
}

    The output is following:

    R 	Argument 	Value of polynomial

    1 	-1.0000 	0.6875
    2 	-0.8000 	0.6613
    3 	-0.6000 	0.6943
    4 	-0.4000 	0.7433
    5 	-0.2000 	0.7843
    6 	 0.0000 	0.8125
    7 	 0.2000 	0.8423
    8 	 0.4000 	0.9073
    9 	 0.6000 	1.0603
    10 	 0.8000 	1.3733
    11 	 1.0000 	1.9375

Summary: evaluation of polynomials in one variable
Sample data:
Header file: OCN_e02.h
See also:


nag_1d_cheb_interp_fit

Function: nag_1d_cheb_interp_fit
Prototype:
int nag_1d_cheb_interp_fit(int nplus1,const double f[],double a[])
Remarks: computes the coeffcients of a polynomial, in its Chebyshev series form, which interpolates (passes exactly through) data at a special set of points. Least-squares polynomial approximations can also be obtained.
Parameters:
nplus1
  the number n + 1 of data points (one greater than the degree n of the interpolating polynomial.
a[]
  the coefficient a[j] in the interpolating polynomial,for j = 1,2,.., n + 1.

Return values:
This function returns NAG error code, 0 if no error
11: On entry, nplus1 must not be less than 2: nplus1 = _value_.
successfully call of the nag_1d_cheb_interp_fit function.

Example:
    Assume "Data1" Worksheet has two columns, the first column contains 11 data,
    and we want to put result in the second column.

    int n = 10, success;
    //Attach two Datasets to these 2 columns
    Dataset ff("data1",0);
    Dataset dan("data1",1);

    ff.SetSize(n+1);
    dan.SetSize(n+1);

    //Because Dataset cannot be the parameter of function, but vector can be.
    vector f = ff;
    vector an = dan;

    success = nag_1d_cheb_interp_fit(n+1, f, an);

    //Put the result back to the Worksheet "data1" second column.
    dan = an;

    Determine the Chebyshev coeffcients of the polynomial which interpolates
    the data ¯xr, fr, for r = 1, 2, . . . , 11, where ¯xr = cos((r - 1)p/10)
    and fr = e¯xr . Evaluate, for comparison with the values of fr, the
    resulting Chebyshev series at ¯xr, for r = 1, 2, . . . , 11.  The example
    program supplied is written in a general form that will enable polynomial
    interpolations of arbitrary data at the cosine points cos((r - 1)p/n),
    for r = 1, 2, . . . , n + 1 to be obtained for any n (= nplus1-1). Note
    that nag 1d cheb eval (e02aec) is used to evaluate the interpolating
    polynomial. The program is self-starting in that any number of data sets
    can be supplied.

void test_nag_1d_cheb_interp_fit()
{
    #define NMAX 199
    #define NP1MAX NMAX+1
    double d1;
    double xcap[NP1MAX];
    double f[NP1MAX] = {2.7182, 2.5884, 2.2456, 1.7999, 1.3620, 1.0000,
    0.7341, 0.5555, 0.4452, 0.3863, 0.3678};
    double piby2n, pi1, an[NP1MAX], fit;
    int i, j, n = 10;
    int r,success;

    pi1 = 3.1415926;
    piby2n = pi1 * 0.5 / n;

    for (r = 0; r < n+1; ++r)
    {
        i = r;
        if (2*i <= n)
        {
            d1 = sin(piby2n * i);
            xcap[i] = 1.0 - d1 * d1 * 2.0;
        }
        else if (2*i > n * 3)
        {
            d1 = sin(piby2n * (n - i));
            xcap[i] = d1 * d1 * 2.0 - 1.0;
        }
        else
        {
            xcap[i] = sin(piby2n * (n - 2*i));
        }
    }

    success = nag_1d_cheb_interp_fit(n+1, f, an);

    printf("\n Chebyshev \n");
    printf(" J coefficient A(J) \n");
    for (j = 0; j < n+1; ++j)
        printf(" %3ld%14.7f\n",j+1,an[j]);
    printf("\n R Abscissa Ordinate Fit \n");
    for (r = 0; r < n+1; ++r)
    {
        success =nag_1d_cheb_eval(n+1, an, xcap[r], &fit);
        printf(" %3ld%11.4f%11.4f%11.4f\n",r+1,xcap[r],f[r],fit);
    }
}

    The output is following:

            Chebyshev
    J 		coefficient A(J)

    1 		 2.5320000
    2 		 1.1303095
    3 		 0.2714893
    4 		 0.0443462
    5 	 	 0.0055004
    6 		 0.0005400
    7 		 0.0000307
    8 		-0.0000006
    9 		-0.0000004
    10 		 0.0000049
    11 		-0.0000200

    R 	Abscissa 		Ordinate 	Fit

    1 	 1.0000 		2.7182 		2.7182
    2 	 0.9511 		2.5884 		2.5884
    3 	 0.8090 		2.2456 		2.2456
    4 	 0.5878 		1.7999 		1.7999
    5 	 0.3090 		1.3620 		1.3620
    6 	 0.0000 		1.0000 		1.0000
    7 	-0.3090 		0.7341 		0.7341
    8 	-0.5878 		0.5555 		0.5555
    9 	-0.8090 		0.4452 		0.4452
    10 	-0.9511 		0.3863 		0.3863
    11 	-1.0000 		0.3678 		0.3678

Summary: Least-squares curve fit with polynomials,selected data points
Sample data:
Header file: OCN_e02.h
See also:


nag_1d_spline_fit_knots

Function: nag_1d_spline_fit_knots
Prototype:
int nag_1d_spline_fit_knots(int m,const double x[],const double y[],const double weights[],double *ss,Nag_Spline *spline)
Remarks: computes a weighted least-squares approximation to an arbitrary set of data points by a cubic spline with knots prescribed by the user. Cubic spline interpolation can also be carried out. Return NAG error, 0 if no error.
Parameters:
m
  the number m of data points.
x[]
  the values xr of the independent variable (abscissa), for r = 1, 2,...,m.
y[]
  the values yr of the of the dependent variable (ordinate), for r = 1, 2,...,m.
weights[]
  the values wr of the weights, for r = 1, 2, . .,m.
ss
  the residual sum of squares
spline
  pointer to structure of type Nag_Spline.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, spline.n must not be less than 8: spline.n = _value_.
73: Memory allocation failed.
239: On entry, user-specified knots must be interior to the data interval, spline.lamda[4] must be greater than x[0] and spline.lamda[spline.n-5] must be less than x[m-1]: spline.lamda[4] = _value_, x[0] = _value_, spline.lamda[_value_] = _value_, x[_value_] = _value_.
62: The sequence spline.lamda is not increasing: spline.lamda[_value_] = _value_, spline.lamda[_value_] = _value_.  This condition on spline.lamda applies to user-speci.ed knots in the interval spline.lamda[4], spline.lamda[spline.n-5].  The sequence x is not increasing: x[_value_] = _value_, x[_value_] = _value_.
240: On entry, the weights are not strictly positive: weights[_value_] = _value_.
244: Too many knots for the number of distinct abscissae, mdist: spline.n = _value_, mdist = _value_.  These must satisfy the constraint spline.n = mdist + 4.
241: The conditions speci.ed by Schoenberg and Whitney fail.  The conditions speci.ed by Schoenberg andWhitney (1953) fail to hold for at least one subset of the distinct data abscissae. That is, there is no subset of spline.n-4 strictly increasing values, x[r0], x[r1],. . . ,x[rspline.n-5], among the abscissae such that x[r0] < spline.lamda[0] < x[r4], x[r1] < spline.lamda[1] < x[r5], . . . x[rspline.n-9] < spline.lamda[spline.n-9] < x[rspline.n-5].  This means that there is no unique solution: there are regions containing too many knots compared with the number of data points.
successfully call of the nag_1d_spline_fit_knots function.

Example:
    Assume "Data1" Worksheet has three columns, every column has 14 data.  After call the function,
    we get the residual sum of squares and the result of a Nag_Spline structure variable.

    //Attach three Datasets to these 3 columns

    int m=14;
    Dataset xx("data1",0);
    Dataset yy("data1",1);
    Dataset dweights("data1",2);

    xx.SetSize(m);
    yy.SetSize(m);
    dweights.SetSize(m);

    double ss;
    Nag_Spline spline;
    vector x, y, weights;
    x = xx;
    y = yy;
    weights = dweights;
    BOOL success = nag_1d_spline_fit_knots(m, x, y, weights, &ss, &spline);

    Determine a weighted least-squares cubic spline approximation with five intervals (four interior knots)
    to a set of 14 given data points. Tabulate the data and the corresponding values of the approximating
    spline, together with the residual errors, and also the values of the approximating spline at points
    half-way between each pair of adjacent data points.

void test_nag_1d_spline_fit_knots()
{
    int ncap, ncap7, j, m, r, wght;
    double weights[200] = {0.20, 0.20, 0.30, 0.70, 0.90, 1.00, 1.00, 1.00, 0.80, 0.50, 0.70, 1.00, 1.00, 1.00};;
    double xarg, ss, fit;
    double fg[12];
    double x[200] = {0.20, 0.47, 0.74, 1.09, 1.60, 1.90, 2.60, 3.10, 4.00, 5.15, 6.17, 8.00, 10.00, 12.00};
    double y[200] = {0.00, 2.00, 4.00, 6.00, 8.00, 8.62, 9.10, 8.90, 8.15, 7.00, 6.00, 4.54, 3.39, 2.56};
    Nag_Spline spline;
    int success;
    m = 14;
    ncap = 5;
    wght = 2;
    ncap7 = ncap+7;
    spline.n = ncap7;

    fg[4] = 1.50;
    fg[5] = 2.60;
    fg[6] = 4.00;
    fg[7] = 8.00;
    spline.lamda = fg;

    printf("spline = %d\n", spline.n);
    ASSERT(spline.n == 12);

    int nSize=sizeof(Nag_Spline);

     success = nag_1d_spline_fit_knots(m, x, y, weights, &ss, &spline);

    printf("\nNumber of distinct knots = %ld\n\n", ncap+1);
    printf("Distinct knots located at \n\n");
    for (j=3; j<ncap+4; j++)
    {
        printf("%8.4f",spline.lamda[j]);
        if((j-3)%6==5 || j==ncap+3)
            printf("\n");
    }
    printf("\n\n J B-spline coeff c\n\n");
    for (j=0; j<ncap+3; ++j)
    printf(" %ld %13.4f\n",j+1,spline.c[j]);
    printf("\nResidual sum of squares = ");
    printf("%9.2e\n\n",ss);
    printf("Cubic spline approximation and residuals\n");
    printf(" r Abscissa Weight Ordinate	Spline Residual\n\n");
    for (r=0; r<m; ++r)
    {
        nag_1d_spline_evaluate(x[r], &fit, &spline);
        printf("%3ld %11.4f %11.4f %11.4f %11.4f %10.1e\n",r+1,x[r],weights[r],y[r],fit,fit-y[r]);
        if (r<m-1)
        {
            xarg = (x[r] + x[r+1]) * 0.5;
            nag_1d_spline_evaluate(xarg, &fit, &spline);
            printf(" %14.4f %35.4f\n",xarg,fit);
        }
    }
    nag_free(spline.c);

}

    The output is following:
    spline = 12

    Number of distinct knots = 6

    Distinct knots located at

    0.2000 1.5000 2.6000 4.0000 8.0000 12.0000

    J 	B-spline coeff c

    1 	-0.0465
    2 	 3.6150
    3 	 8.5724
    4 	 9.4261
    5 	 7.2716
    6 	 4.1207
    7  	 3.0822
    8 	 2.5597

    Residual sum of squares = 1.78e-03

    Cubic spline approximation and residuals

    r 	Abscissa 	Weight 		Ordinate 	Spline 		Residual

    1 	0.2000 		0.2000 		0.0000 		-0.0465 	-4.7e-02
        0.3350 								 1.0622
    2 	0.4700 		0.2000 		2.0000 		 2.1057 	 1.1e-01
        0.6050 								 3.0817
    3 	0.7400 		0.3000 		4.0000 		 3.9880 	-1.2e-02
        0.9150 								 5.0558
    4 	1.0900 		0.7000 		6.0000 		 5.9983 	-1.7e-03
        1.3450 								 7.1376
    5 	1.6000 		0.9000 		8.0000 		 7.9872 	-1.3e-02
        1.7500 								 8.3544
    6 	1.9000 		1.0000 		8.6200 		 8.6348 	 1.5e-02
        2.2500 								 9.0076
    7 	2.6000 		1.0000 		9.1000 		 9.0896 	-1.0e-02
        2.8500 								 9.0353
    8 	3.1000 		1.0000 		8.9000 		 8.9125 	 1.2e-02
        3.5500 								 8.5660
    9 	4.0000 		0.8000 		8.1500 		 8.1321 	-1.8e-02
        4.5750 								 7.5592
    10 	5.1500 		0.5000 		7.0000 		 6.9925 	-7.5e-03
        5.6600 								 6.5010
    11 	6.1700 		0.7000 		6.0000 		 6.0255 	 2.6e-02
        7.0850 								 5.2292
    12  8.0000 		1.0000 		4.5400 		 4.5315 	-8.5e-03
        9.0000 								 3.9045
    13 10.0000 		1.0000 		3.3900 		 3.3928 	 2.8e-03
       11.0000 								 2.9574
    14 12.0000 		1.0000 		2.5600 		 2.5597 	-3.5e-04

Summary: Least-squares curve fit with cubic splines e02bac
Sample data:
Header file: OCN_e02.h
See also:


nag_1d_spline_evaluate

Function: nag_1d_spline_evaluate
Prototype:
int nag_1d_spline_evaluate(double x,double *s,Nag_Spline *spline)
Remarks: evaluates a cubic spline from its B-spline representation.
Parameters:
x
  the argument x at which the cubic spline is to be evaluated.
s
  the value of the spline, s(x).
spline
  Pointer to structure of type Nag_Spline.

Return values:
This function returns NAG error, 0 if no error.
11: On entry, spline.n must not be less than 8: spline.n = _value_.
238: On entry, x must satisfy spline.lamda[3] = x = spline.lamda[spline.n-4]: spline.lamda[3] = _value_, x = _value_, spline.lamda[_value_] = _value_.  In this case s is set arbitrarily to zero.
successfully call of the nag_1d_spline_evaluate function.

Example:
    Evaluate at 9 equally-spaced points in the interval [1.0, 9.0] the cubic spline with
    (augmented) knots 1.0, 1.0, 1.0, 1.0, 3.0, 6.0, 8.0, 9.0, 9.0, 9.0, 9.0 and normalised
    cubic B-spline coefficients 1.0, 2.0, 4.0, 7.0, 6.0, 4.0, 3.0.

void test_nag_1d_spline_evaluate()
{
    double a, b,ncap7;
    int m =9;
    int ncap = 4;
    int r;
    double lamda[11] = {1.00, 1.00, 1.00, 1.00, 3.00, 6.00, 8.00, 9.00, 9.00, 9.00, 9.00};
    double c[11] = {1.00, 2.00, 4.00, 7.00, 6.00, 4.00, 3.00};
    double s;
    double x;
    int i, j;
    Nag_Spline spline;
    ncap7 = ncap +7;
    spline.n = ncap7;
    spline.lamda = lamda;
    spline.c = c;

    a = spline.lamda[3];
    printf("a = %f\n",a);
    b = spline.lamda[ncap+3];
    printf("b = %f\n",b);
    printf("Augmented set of knots stored in spline.lamda:\n");
    for(j = 0; j < ncap7-1; j++)
        printf("%10.4f",lamda[j]);
    printf("\nB-spline coefficients stored in spline.c\n\n");
    for(j = 0; j< ncap+3; j++)
        printf("%10.4f",c[j]);
    printf("\n x Value of cubic spline\n\n");
    for (r=1; r<=m; ++r)
    {
        x = 1.0*((m-r) * a + (r-1) * b) /(m-1);
        s= 0;
         nag_1d_spline_evaluate(x, &s, &spline);
        printf("%10.4f%15.4f\n",x,s);
    }
}

    The output is following:

    Augmented set of knots stored in spline.lamda:

    1.0000 	1.0000 	1.0000 	1.0000 	3.0000 	6.0000
    8.0000 	9.0000 	9.0000 	9.0000 	9.0000

    B-spline coefficients stored in spline.c:
    1.0000 	2.0000 	4.0000 	7.0000 	6.0000 	4.0000
    3.0000

    x 			Value of cubic spline
    1.0000 		1.0000
    2.0000 		2.3779
    3.0000 		3.6229
    4.0000 		4.8327
    5.0000 		5.8273
    6.0000 		6.3571
    7.0000 		6.1905
    8.0000 		5.1667
    9.0000 		3.0000

Summary: Evaluation of cubic splines.
Sample data:
Header file: OCN_e02.h
See also:


nag_1d_spline_deriv

Function: nag_1d_spline_deriv
Prototype:
int nag_1d_spline_deriv(Nag_DerivType derivs,double x,double s[],Nag_Spline *spline)
Remarks: evaluates a cubic spline and its first three derivatives from its B-spline representation.
Parameters:
x
  the argument x at which the cubic spline and its derivatives are to be evaluated.
s[]
  the value of the jth derivative of the spline at the argument x, for j = 0, 1, 2, 3.
spline
  Pointer to structure of type Nag_Spline

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, spline.n must not be less than 8: spline.n = _value_.
70: On entry, parameter derivs had an illegal value.
238: On entry, x must satisfy spline.lamda[3] = x = spline.lamda[spline.n-4]: spline.lamda[3] = _value_, x = _value_, spline.lamda[_value_] = _value_.
269: On entry, the cubic spline range is invalid: spline.lamda[3] = _value_ while spline.lamda[spline.n-4] = _value_.  These must satisfy spline.lamda[3] < spline.lamda[spline.n-4].
successfully call of the nag_1d_spline_deriv function.

Example:
    Compute, at the 7 arguments x = 0, 1, 2 , 3, 4, 5, 6, the left- and right-hand
    values and first 3 derivatives of the cubic spline defined over the interval
    0 <= x <= 6 having the 6 interior knots x = 1, 3, 3, 3, 4, 4, the 8 additional
    knots 0, 0, 0, 0, 6, 6, 6, 6, and the 10 B-spline coe.cients 10, 12, 13, 15,
    22, 26, 24, 18, 14, 12.  The input data items (using the notation of Section 4)
    comprise the following values in the order indicated:

    ¯n 								m
    spline.lamda[j], 				for j = 0, 1, . . . , ¯n + 6
    spline.c[j], 					for j = 0, 1, . . . , ¯n + 2
    x 								m values of x

    The example program is written in a general form that will enable the values
    and derivatives of a cubic spline having an arbitrary number of knots to be
    evaluated at a set of arbitrary points. Any number of data sets may be supplied.

void test_nag_1d_spline_deriv()
{
    int i, j, l, m, ncap, ncap7;
    double s[4];
    double lamd[14] = {0.0, 0.0, 0.0, 0.0, 1.0, 3.0, 3.0, 3.0, 4.0, 4.0, 6.0, 6.0, 6.0, 6.0};
    double c1[14] = {10.0, 12.0, 13.0, 15.0, 22.0, 26.0, 24.0, 18.0, 14.0, 12.0};
    double x[7] = {0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0};
    Nag_Spline spline;
    Nag_DerivType derivs;

    printf("e02bcc Example Program Results\n");
    ncap = 7;
    m = 7;
    ncap7 = ncap+7;
       spline.n = ncap7;
    spline.lamda = lamd;
    spline.c = c1;

    for( i = 0; i < 11; i++)
        printf("%f	",spline.lamda[i]);

    printf(" x Spline 1st deriv 2nd deriv 3rd deriv");
    for (i= 0; i< m; i++)
    {
        derivs = Nag_LeftDerivs;
        for (j=1; j<=2; j++)
        {
             nag_1d_spline_deriv(derivs, x[i], s, &spline);

             if(derivs ==Nag_LeftDerivs)
            {
                printf("\n\n%11.4f Left",x[i]);
                for (l=0; l<4; l++)
                    printf("%11.4f",s[l]);
            }
            else
            {
                printf("\n%11.4f Right",x[i]);
                for (l=0; l<4; l++)
                    printf("%11.4f",s[l]);
            }
            derivs = Nag_RightDerivs;
        }
    }
}

    The output is following:

    x 				Spline 		1st deriv 	2nd deriv 	3rd deriv

    0.0000 	Left 	10.0000 	6.0000 		-10.0000 	10.6667
    0.0000 	Right 	10.0000 	6.0000 		-10.0000 	10.6667

    1.0000 	Left 	12.7778 	1.3333 		  0.6667 	10.6667
    1.0000 	Right 	12.7778 	1.3333 		  0.6667 	 3.9167

    2.0000 	Left 	15.0972 	3.9583 	 	  4.5833 	 3.9167
    2.0000 	Right 	15.0972 	3.9583 		  4.5833 	 3.9167

    3.0000 	Left 	22.0000 	10.5000 	  8.5000 	 3.9167
    3.0000 	Right 	22.0000 	12.0000 	-36.0000 	36.0000

    4.0000 	Left 	22.0000 	-6.0000  	  0.0000 	36.0000
    4.0000 	Right 	22.0000 	-6.0000 	  0.0000 	 1.5000

    5.0000 	Left 	16.2500 	-5.2500 	  1.5000 	 1.5000
    5.0000 	Right 	16.2500 	-5.2500 	  1.5000	 1.5000

    6.0000 	Left 	12.0000 	-3.0000 	  3.0000	 1.5000
    6.0000 	Right 	12.0000 	-3.0000 	  3.0000	 1.5000

Summary: Evaluation of fitted cubic spline, function and derivatives
Sample data:
Header file: OCN_e02.h
See also:


nag_1d_spline_intg

Function: nag_1d_spline_intg
Prototype:
int nag_1d_spline_intg(Nag_Spline *spline,double *integral)
Remarks: computes the definite integral of a cubic spline from its B-spline representation.
Parameters:
spline
  pointer to structure of type Nag_Spline
integral
  the value of the definite integral of s(x) between the limits x = a and x = b,

Return values:
The function returns NAG error, 0 if no error.
11: On entry, spline.n must not be less than 8: spline.n = _value_.
253: On entry, the knots must satisfy the following constraints: spline.lamda[spline.n-4] > spline.lamda[3], spline.lamda[j] = spline.lamda[j - 1], for j = 1, 2, . . . ,spline.n-1, with equality in the cases j = 1, 2, 3,spline.n-3,spline.n-2 and spline.n-1.
successfully call of the nag_1d_spline_intg function.

Example:
    Determine the definite integral over the interval [0,6] of a cubic spline having 6 interior
    knots at the positions lamda= 1, 3, 3, 3, 4, 4, the 8 additional knots 0, 0, 0, 0, 6, 6, 6, 6,
    and the 10 B-spline coefficients 10, 12, 13, 15, 22, 26, 24, 18, 14, 12.

void test_nag_1d_spline_intg()
{
    int j;
    double integral;
    Nag_Spline spline;
    spline.n = 14;
    double lamda[] = {0.0, 0.0, 0.0, 0.0, 1.0, 3.0, 3.0, 3.0,4.0, 4.0, 6.0, 6.0, 6.0, 6.0};
    double c[] = {10.0, 12.0, 13.0, 15.0, 22.0, 26.0, 24.0, 18.0,14.0, 12.0, 0, 0, 0}
    spline.c = c;
    spline.lamda = lamda;

    nag_1d_spline_intg(&spline, &integral);

    printf("Definite integral = %11.3e\n",integral);
}

    The output is following:

Definite integral = 1.000e+02

Summary: Evaluation of fitted cubic spline, definite integral
Sample data:
Header file: OCN_e02.h
See also:


nag_1d_spline_fit

Function: nag_1d_spline_fit
Prototype:
int nag_1d_spline_fit(Nag_Start start,int m,const double x[],const double y[],const double weights[],double s,int nest,double *fp,Nag_Comm *warmstartinf,Nag_Spline *spline)
Remarks: computes a cubic spline approximation to an arbitrary set of data points.
Parameters:
start
  start must be set to Nag Cold or Nag Warm.
m
  the number of data points
x[]
  the value x[r] of the independent variable (abscissa) x, for r = 1, 2, . . .,m.
y[]
  the value y[r] of the dependent variable (ordinate) y, for r = 1, 2, . . .,m.
weights[]
  the value w[r] of the weights,for r = 1, 2, . . .,m.
s
  the smoothing factor
nest
  an over-estimate for the number, n, of knots required.
fp
  the sum of the squared weighted residuals of the computed spline approximation
warmstartinf
  Pointer to structure of type Nag_Comm
spline
  Pointer to structure of type Nag_Spline

Return values:
The function returns NAG error, 0 if no error.
70: On entry, parameter start had an illegal value.
11: On entry, m must not be less than 4: m = _value_.  On entry, nest must not be less than 8: nest = _value_.
5: On entry, s must not be less than 0.0: s = _value_.
240: On entry, the weights are not strictly positive: weights[_value_] = _value_.
63: The sequence x is not strictly increasing: x[_value_] = _value_ x[_value_] = _value_.
268: On entry, nest = _value_, s = _value_, m = _value_.  Constraint: nest = m + 4 when s = 0.0.
73: Memory allocation failed.
266: Start has been set to Nag Warm at the .rst call of this function. It must be set to Nag Cold at the FIrst call.
264: The number of knots needed is greater than nest, nest = _value_. If nest is already large, say nest > m/2, this may indicate that possibly s is too small: s = _value_.
254: The iterative process has failed to converge. Possibly s is too small: s = _value_.  If the function fails with an error exit of NE SPLINE COEFF CONV or NE NUM KNOTS ID GT, a spline approximation is returned, but it fails to satisfy the .tting criterion (see (2) and (3) in Section 3) - perhaps by only a small amount, however.
successfully call of the nag_1d_spline_fit function.

Example:
    This example program reads in a set of data values, followed by a set of values of S. For each value
    of S it calls nag_1d_spline_fit to compute a spline approximation, and prints the values of the knots
    and the B-spline coefficients ci.

void test_nag_1d_spline_fit()
{
    int NEST = 54;
    int m = 15, r, j;
    double weights[50] = {1.00, 2.00, 1.50, 1.00, 3.00, 1.00, 0.50, 1.00, 2.00, 2.50, 1.00, 3.00, 1.00, 2.00, 1.00};
    double x[50] = {0.0000E+00, 5.0000E-01, 1.0000E+00, 1.5000E+00, 2.0000E+00, 2.5000E+00, 3.0000E+00, 4.0000E+00,
    4.5000E+00, 5.0000E+00, 5.5000E+00, 6.0000E+00, 7.0000E+00, 7.5000E+00, 8.0000E+00};
    double y[50] = {-1.1000E+00, -3.7200E-01, 4.3100E-01, 1.6900E+00, 2.1100E+00, 3.1000E+00, 4.2300E+00, 4.3500E+00,
    4.8100E+00, 4.6100E+00, 4.7900E+00, 5.2300E+00, 6.3500E+00, 7.1900E+00, 7.9700E+00};
    double s[3] = {1.0, 0.5, 0.1};
    double fp, sp[99], txr;
    Nag_Start start;
    Nag_Comm warmstartinf;
    Nag_Spline spline;

    start = Nag_Cold;

    for(int i = 0; i < 3; i ++)
    {
        nag_1d_spline_fit(start, m, x, y, weights, s[i], NEST, &fp, &warmstartinf, &spline);

        for (r=0; r<m; r++)
            nag_1d_spline_evaluate(x[r], &sp[r*2], &spline);
        for (r=0; r<m-1; r++)
        {
            txr = (x[r] + x[r+1]) / 2;
            nag_1d_spline_evaluate(txr, &sp[r*2], &spline);
        }

        printf("\nCalling with smoothing factor s = %12.3e\n",s);
        printf("\nNumber of distinct knots = %ld\n\n", spline.n-6);
        printf("Distinct knots located at \n\n");
        for (j=3; j<spline.n-3; j++)
        {
            printf("%8.4f",spline.lamda[j]);
            if((j-3)%6==5 || j==spline.n-4)
                printf("\n");
        }
        printf("\n\n J B-spline coeff c\n\n");
        for (j=0; j<spline.n-4; ++j)
            printf(" %3ld %13.4f\n",j+1,spline.c[j]);
        printf("\nWeighted sum of squared residuals fp = %12.3e\n",fp);
        if (fp == 0.0)
            printf("The spline is an interpolating spline\n");
        if (spline.n == 8)
            printf("The spline is the weighted least-squares cubic	polynomial\n");
        start = Nag_Warm;
    }
    nag_free(spline.c);
    nag_free(spline.lamda);
    nag_free(warmstartinf.nag_w);
    nag_free(warmstartinf.nag_iw);

}

    The output is following:

    Calling with smoothing factor s = 1.000e+00

    Number of distinct knots = 3

    Distinct knots located at

    0.0000 4.0000 8.0000

    J 	B-spline coeff c

    1 	-1.3201
    2 	 1.3542
    3 	 5.5510
    4 	 4.7031
    5 	 8.2277

    Weighted sum of squared residuals fp = 1.000e+00

    Calling with smoothing factor s = 5.000e-01

    Number of distinct knots = 7

    Distinct knots located at

    0.0000 1.0000 2.0000 4.0000 5.0000 6.0000	8.0000

    J 	B-spline coeff c

    1 	-1.1072
    2 	-0.6571
    3 	 0.4350
    4 	 2.8061
    5 	 4.6824
    6 	 4.6416
    7 	 5.1976
    8 	 6.9008
    9 	 7.9979

    Weighted sum of squared residuals fp = 5.001e-01

    Calling with smoothing factor s = 1.000e-01

    Number of distinct knots = 10

    Distinct knots located at

    0.0000 1.0000 1.5000 2.0000 3.0000 4.0000	4.5000 5.0000 6.0000 8.0000

    J 	B-spline coeff c
    1 	-1.0900
    2 	-0.6422
    3 	 0.0369
    4 	 1.6353
    5 	 2.1274
    6 	 4.5526
    7 	 4.2225
    8 	 4.9108
    9 	 4.4159
    10 	 5.4794
    11 	 6.8308
    12   7.9935

    Weighted sum of squared residuals fp = 1.000e-01

Summary: Least-squares cubic spline curve fit, automatic knot placement, one variable
Sample data:
Header file: OCN_e02.h
See also:


nag_2d_spline_fit_grid

Function: nag_2d_spline_fit_grid
Prototype:
int nag_2d_spline_fit_grid(Nag_Start start,int mx,const double x[],int my,const double y[],const double f[],double s,int nxest,int nyest,double *fp,Nag_Comm *warmstartinf,Nag_2dSpline *spline)
Remarks: computes a bicubic spline approximation to a set of data values, given on a rectangular grid in the x-y plane.
Parameters:
start
  start must be set to Nag Cold or Nag Warm.
mx
  the number of grid points along the x axis
x[]
  the x co-ordinate of the qth grid point along the x axis, for q = 1, 2, . . .,mx.
my
  the number of grid points along the y axis.
y[]
  the y co-ordinate of the rth grid point along the y axis, for r = 1, 2, . . .,my.
f[]
  contain the data value fq,r, for q = 1, 2, . . .,mx and r = 1, 2, . . .,my.
s
  the smoothing factor
nyest
  an upper bound for the number of knots nx and ny required in the x and y directions respectively.
fp
  the sum of squared residuals of the computed spline approximation
warmstartinf
  Pointer to structure of type Nag_Comm
spline
  Pointer to structure of type Nag_2dSpline

Return values:
This function returns NAG error code, 0 if no error.
70: On entry, parameter start had an illegal value.
11: On entry, mx must not be less than 4: mx = _value_.  On entry, my must not be less than 4: my = _value_.  On entry, nxest must not be less than 8: nxest = _value_.  On entry, nyest must not be less than 8: nyest = _value_.
5: On entry, s must not be less than 0.0: s = _value_.
268: On entry, s = _value_, nxest = _value_, mx = _value_. Constraint: nxest = mx+4 when s = 0.0.  On entry, s = _value_, nyest = _value_, my = _value_. Constraint: nyest = mx+4 when s = 0.0.
73: Memory allocation failed.
266: start has been set to Nag Warm at the .rst call of this function. It must be set to Nag Cold at the .rst call.
63: The sequence x is not strictly increasing: x[_value_] = _value_, x[_value_] = _value_.  The sequence y is not strictly increasing: y[_value_] = _value_, y[_value_] = _value_.
261: The number of knots required is greater than allowed by nxest or nyest, nxest = _value_, nyest = _value_. Possibly s is too small, especially if nxest, nyest > mx/2, my/2. s = _value_, mx = _value_, my = _value_.
254: The iterative process has failed to converge. Possibly s is too small: s = _value_.  If the function fails with an error exit of NE NUM KNOTS 2D GT RECT or NE SPLINE COEFF CONV, then a spline approximation is returned, but it fails to satisfy the .tting criterion (see (2) and (3) in Section 3) - perhaps by only a small amount, however.
successfully call of the nag_2d_spline_fit_grid function.

Example:

    This example program reads in values of mx, my, xq, for q = 1, 2, . . . ,mx,
    and yr, for r = 1, 2, . . .,my, followed by values of the ordinates fq,
    r defined at the grid points (xq, yr). It then calls nag 2d spline fit
    grid to compute a bicubic spline approximation for one specified value of s,
    and prints the values of the computed knots and B-spline coefficients.
    Finally it evaluates the spline at a small sample of points on a rectangular grid.

void test_nag_2d_spline_fit_grid()
{
    int NXEST = 15;
    int NYEST = 13;
    int mx = 11, my = 9, nx, ny, npx, npy, i, j;
    double fg[49], px[7], py[7];
    double xhi, yhi, xlo, ylo, delta, s, fp;
    Nag_Start start;
    Nag_2dSpline spline;
    Nag_Comm warmstartinf;
    double x[] ={0.0000E+00, 5.0000E-01, 1.0000E+00, 1.5000E+00, 2.0000E+00,2.5000E+00,
             3.0000E+00, 3.5000E+00, 4.0000E+00, 4.5000E+00,5.0000E+00};
    double y[] ={0.0000E+00, 5.0000E-01, 1.0000E+00, 1.5000E+00, 2.0000E+00,2.5000E+00,
                 3.0000E+00, 3.5000E+00, 4.0000E+00}
    double f[] ={1.0000E+00, 8.8758E-01, 5.4030E-01, 7.0737E-02, -4.1515E-01,
            -8.0114E-01, -9.7999E-01, -9.3446E-01, -6.5664E-01, 1.5000E+00,
            1.3564E+00, 8.2045E-01, 1.0611E-01, -6.2422E-01, -1.2317E+00,
            -1.4850E+00, -1.3047E+00, -9.8547E-01, 2.0600E+00, 1.7552E+00,
            1.0806E+00, 1.5147E-01, -8.3229E-01, -1.6023E+00, -1.9700E+00,
            -1.8729E+00, -1.4073E+00, 2.5700E+00, 2.1240E+00, 1.3508E+00,
            1.7684E-01, -1.0404E+00, -2.0029E+00, -2.4750E+00, -2.3511E+00,
            -1.6741E+00, 3.0000E+00, 2.6427E+00, 1.6309E+00, 2.1221E-01,
            -1.2484E+00, -2.2034E+00, -2.9700E+00, -2.8094E+00, -1.9809E+00,
            3.5000E+00, 3.1715E+00, 1.8611E+00, 2.4458E-01, -1.4565E+00,
            -2.8640E+00, -3.2650E+00, -3.2776E+00, -2.2878E+00, 4.0400E+00,
            3.5103E+00, 2.0612E+00, 2.8595E-01, -1.6946E+00, -3.2046E+00,
            -3.9600E+00, -3.7958E+00, -2.6146E+00, 4.5000E+00, 3.9391E+00,
            2.4314E+00, 3.1632E-01, -1.8627E+00, -3.6351E+00, -4.4550E+00,
            -4.2141E+00, -2.9314E+00, 5.0400E+00, 4.3879E+00, 2.7515E+00,
            3.5369E-01, -2.0707E+00, -4.0057E+00, -4.9700E+00, -4.6823E+00,
            -3.2382E+00, 5.5050E+00, 4.8367E+00, 2.9717E+00, 3.8505E-01,
            -2.2888E+00, -4.4033E+00, -5.4450E+00, -5.1405E+00, -3.5950E+00,
            6.0000E+00, 5.2755E+00, 3.2418E+00, 4.2442E-01, -2.4769E+00,
            -4.8169E+00, -5.9300E+00, -5.6387E+00, -3.9319E+00}

    start = Nag_Cold;
    s = 0.1;

    nag_2d_spline_fit_grid(start, mx, x, my, y, f, s, NXEST, NYEST,
                        &fp, &warmstartinf, &spline);
    nx = spline.nx;
    ny = spline.ny;
    printf("\nCalling with smoothing factor s = %11.4e:	spline.nx = %2ld, spline.ny = %2ld.\n\n",s,nx,ny);
    printf("Distinct knots in x direction located at\n");
    for (j=3; j<spline.nx-3; j++)
    {
        printf("%12.4f",spline.lamda[j]);
        if((j-3)%5==4 || j==spline.nx-4)
            printf("\N");
    }

    printf("\nDistinct knots in y direction located at\n");
    for (j=3; j<spline.ny-3; j++)
    {
        printf("%12.4f",spline.mu[j]);
        if((j-3)%5==4 || j==spline.ny-4)
            printf("\n");
    }
    printf("\nThe B-spline coefficients:\n\n");
    for (i=0; i<ny-4; i++)
    {
        for (j=0; j<nx-4; j++)
            printf("%9.4f",spline.c[i+j*(ny-4)]);
        printf("\n");
    }
    printf("\nSum of squared residuals fp = %11.4e\n",fp);
    if (fp==0.0)
        printf("\nThe spline is an interpolating spline\n");
    if (nx==8 && ny==8)
        printf("\nThe spline is the least-squares bi-cubic polynomial\n");

    npx = 6;
    xlo = 0.0;
    xhi = 5.0;
    npy = 5;
    ylo = 0.0;
    yhi = 4.0;
    delta = (xhi-xlo) / (npx-1);
    for (i=0; i<npx; i++)
    {
        if(xlo+i*delta > xhi)
            px[i] = xhi;
        else
            px[i] =	xlo+i*delta;
    }
    for (i=0; i<npy; i++)
    {
        if(ylo+i*delta > yhi)
            py[i] = yhi;
        else
            py[i] =	ylo+i*delta;
    }
    nag_2d_spline_eval_rect(npx, npy, px, py, fg, &spline);
    printf("\nValues of computed spline:\n");
    printf("\n x");
    for (i=0; i<npx; i++)
        printf("%7.2f ",px[i]);
    printf("\n y\n");
    for (i=npy-1; i>=0; i--)
    {
        printf("%7.2f ",py[i]);
        for (j=0; j<npx; ++j)
            printf("%8.2f ",fg[npy*j+i]);
        printf("\n");
    }
    nag_free(spline.mu);
    nag_free(spline.c);
    nag_free(spline.lamda);
    nag_free(warmstartinf.nag_w);
    nag_free(warmstartinf.nag_iw);
}

    The output is following:

    Calling with smoothing factor s = 1.0000e-01: spline.nx = 10, spline.ny = 13.

    Distinct knots in x direction located at

    0.0000 1.5000 2.5000 5.0000

    Distinct knots in y direction located at

    0.0000 1.0000 2.0000 2.5000 3.0000	3.5000 4.0000

    The B-spline coefficients:

     0.9918  1.5381  2.3913  3.9845  5.2138  5.9965
     1.0546  1.5270  2.2441  4.2217  5.0860  6.0821
     0.6098  0.9557  1.5587  2.3458  3.3860  3.7716
    -0.2915 -0.4199 -0.7399 -1.1763 -1.5527 -1.7775
    -0.8476 -1.3296 -1.8521 -3.3468 -4.3628 -5.0085
    -1.0168 -1.5952 -2.4022 -3.9390 -5.4680 -6.1656
    -0.9529 -1.3381 -2.2844 -3.9559 -5.0032 -5.8709
    -0.7711 -1.0914 -1.8488 -3.2549 -3.9444 -4.7297
    -0.6476 -1.0373 -1.5936 -2.5887 -3.3485 -3.9330

    Sum of squared residuals fp = 1.0004e-01

    Values of computed spline:

    x 	0.00 1.00 2.00 3.00 4.00 5.00

    y
    4.00 -0.65 -1.36 -1.99 -2.61 -3.25 -3.93
    3.00 -0.98 -1.97 -2.91 -3.91 -4.97 -5.92
    2.00 -0.42 -0.83 -1.24 -1.66 -2.08 -2.48
    1.00  0.54  1.09  1.61  2.14  2.71  3.24
    0.00  0.99  2.04  3.03  4.01  5.02  6.00

Summary: Least-squares bicubic spline fit with automatic knot placement, two variables (rectangular grid).
Sample data:
Header file: OCN_e02.h
See also:


nag_2d_spline_fit_scat

Function: nag_2d_spline_fit_scat
Prototype:
int nag_2d_spline_fit_scat(Nag_Start start,int m,const double x[],const double y[],const double f[],const double weights[],double s,int nxest,int nyest,double *fp,int *rank,double *warmstartinf,Nag_2dSpline *spline)
Remarks: computes a bicubic spline approximation to a set of scattered data.
Parameters:

Return values:
This function returns NAG error code, 0 if no error.
70: On entry, parameter start had an illegal value.
11: On entry, nxest must not be less than 8: nxest = _value_.  On entry, nyest must not be less than 8: nyest = _value_.
5: On entry, s must not be less than or equal to 0.0: s = _value_.
270: On entry, the number of data points with non-zero weights = _value_. Constraint: the number of non-zero weights = 16.
73: Memory allocation failed.
266: start has been set to Nag Warm at the .rst call of this function. It must be set to Nag Cold at the .rst call.
260: On entry, all the values in the array x must not be equal.  On entry, all the values in the array y must not be equal.
262: The number of knots required is greater than allowed by nxest or nyest, nxest = _value_, nyest = _value_. Possibly s is too small, especially if nxest, nyest > 5 + ãm. s = _value_, m = _value_.
263: No more knots can be added because the number of B-spline coe.cients already exceeds m.  Either m or s is probably too small: m = _value_, s = _value_.
265: No more knots added; the additional knot would coincide with an old one. Possibly an inaccurate data point has too large a weight, or s is too small. s = _value_.
254: The iterative process has failed to converge. Possibly s is too small: s = _value_.  If the function fails with an error exit of NE NUM KNOTS 2D GT SCAT, NE NUM COEFF GT, NE NO ADDITIONAL KNOTS or NE SPLINE COEFF CONV, then a spline approximation is returned, but it fails to satisfy the setting criterion (see (2) and (3) in Section 3) - perhaps by only a small amount, however.
successfully call of the  nag_1d_cheb_fit function.

Example:
    This example program reads in a value of m, followed by a set of m data
    points (xr, yr, fr) and their weights wr. It then calls nag 2d spline fit scat
    to compute a bicubic spline approximation for one specified value of S,
    and prints the values of the computed knots and B-spline coefficients. Finally
    it evaluates the spline at a small sample of points on a rectangular grid.

void test_nag_2d_spline_fit_scat()
{
    double  weights[30], fg[49],px[7], py[7];
    int i, j, m, rank, nx, ny, npx, npy, nxest, nyest;
    double s, delta, fp, xhi, yhi, xlo, ylo;
    Nag_Start start;
    Nag_2dSpline spline;
    double warmstartinf;
    double x[] ={11.16,12.85,19.85,19.72,15.91,0.00,20.87,3.45,14.26,17.43,22.80,
            7.58,25.00,0.00,9.66,5.22,17.25,25.00,12.13,22.23,11.52,15.20,7.54,
            17.32,2.14,0.51,22.69,5.47,21.67,3.31}
    double y[] ={1.24,3.06,10.72,1.39,7.74,20.00,20.00,12.78,17.87,3.46,12.39,1.98,
            11.87,0.00,20.00,14.66,19.57,3.87,10.79,6.21,8.53,0.00,10.69,13.78,
            15.03,8.37,19.63,17.13,14.36,0.33};
    double f[] ={22.15,22.11,7.97,16.83,15.30, 34.60,5.74,41.24,10.74,18.60,5.47,
            29.87, 4.40,58.20,4.73,40.36, 6.43,8.74, 13.71,10.25, 15.74,21.60,
            19.31,12.11,53.10,49.43,3.25,28.63,5.52,44.08};

    nxest = 14;
    nyest = 14;
    for(i = 0; i < 30; i++)
        weights[i] = 1.00;
    m = 30;
    start = Nag_Cold;
    s = 10.0;

    nag_2d_spline_fit_scat(start, m, x, y, f, weights, s, nxest, nyest,
                            &fp,&rank, &warmstartinf, &spline);

    nx= spline.nx;
    ny = spline.ny;
    printf("\nCalling with smoothing factor s = %11.4e, nx= %1ld,ny = %1ld\n",s,nx,ny);
    printf("rank deficiency = %1ld\n\n",(nx-4)*(ny-4)-rank);
    printf("Distinct knots in xdirection located at\n");
    for (j=3; j < spline.nx-3; j++)
    {
        printf("%12.4f",spline.lamda[j]);
        if((j-3)%5==4 || j==spline.nx-4)
            printf("\n");
    }
    printf("\nDistinct knots in y direction located at\n");
    for (j=3; j < spline.ny-3; j++)
    {
        printf("%12.4f",spline.mu[j]);
        if((j-3)%5==4 || j==spline.ny-4)
            printf("\n");
    }
    printf("\nThe B-spline coefficients:\n\n");
    for (i=0; i <ny-4; i++)
    {
        for (j=0; j < nx-4; j++)
            printf("%9.2f",spline.c[i+j*(ny-4)]);
        printf("\n");
    }
    printf("\n Sum of squared residuals fp = %11.4e\n",fp);
    if (nx==8 && ny==8)
        printf("The spline is the least-squares bi-cubic polynomial\n");

    npx = 7;
    xlo = 3.0;
    xhi = 21.0;

    npy = 6;
    ylo = 2.0;
    yhi = 17.0;
    delta = (xhi-xlo)/(npx-1);
    for (i=0; i<npx; i++)
    {
        if(xlo+i*delta > xhi)
            px[i] = xhi;
        else
            px[i] =	xlo+i*delta;
    }
    for (i=0; i<npy; i++)
    {
        if(ylo+i*delta > yhi)
            py[i] = yhi;
        else
            py[i] =	ylo+i*delta;
    }
    nag_2d_spline_eval_rect(npx, npy, px, py, fg, &spline);

    printf("\nValues of computed spline:\n\n");
    printf(" x");
    for (i=0; i< npx;  i++)
        printf("%8.2f ",px[i]);
    printf("\n y\n");
    for (i=npy-1; i>=0; i--)
    {
        printf("%8.2f ",py[i]);
        for (j=0; j < npx; ++j)
            printf("%8.2f ",fg[npy*j+i]);
        printf("\n");
    }
    nag_free(spline.lamda);
    nag_free(spline.c);
    nag_free(spline.mu);
}

    The output is following:

    Calling with smoothing factor s = 1.0000e+01, nx= 10, ny = 9 rank deficiency = 0

    Distinct knots in xdirection located at

    0.0000 9.7575 18.2582 25.0000

    Distinct knots in y direction located at

    0.0000 9.0008 20.0000

    The B-spline coefficients:

    58.16  46.31  6.01  32.00  5.86 -23.78
    63.78  46.74 33.37  18.30 14.36  15.95
    40.84 -33.79  5.17  13.10 -4.13  19.37
    75.44 111.92  6.94  17.33  7.09 -13.24
    34.61 -42.61 25.20  -1.96 10.37  -9.09

    Sum of squared residuals fp = 1.0002e+01

    Values of computed spline:

    x	3.00 6.00 9.00 12.00 15.00 18.00 21.00

    y

    17.00 40.74 28.62 19.84 14.29 11.21 9.46 7.09
    14.00 48.34 33.97 21.56 14.71 12.32 10.82 7.15
    11.00 37.26 24.46 17.21 14.14 13.02 11.23 7.29
    8.00 30.25 19.66 16.90 16.28 15.21 12.71 8.99
    5.00 36.64 26.75 23.07 21.13 18.97 15.90 11.98
    2.00 45.04 33.70 26.25 22.88 21.62 19.39 13.40

Summary:
Sample data:
Header file: OCN_e02.h
See also:


nag_2d_spline_eval

Function: nag_2d_spline_eval
Prototype:
int nag_2d_spline_eval(int m ,const double x[],const double y[],double ff[],Nag_2dSpline *spline)
Remarks: calculates values of a bicubic spline from its B-spline representation.
Parameters:
m
  the number of points at which values of the spline are required
y[]
  These are the coordinates of the points at which values of the spline are required
ff[]
  contains the value of the spline at the point (xr, yr),
spline
  Pointer to structure of type Nag_2dSpline

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, m must not be less than 1: m = _value_.  On entry, spline.nx must not be less than 8: spline.nx = _value_.  On entry, spline.ny must not be less than 8: spline.ny = _value_.
73: Memory allocation failed.
255: On entry, the end knots must satisfy _value_, _value_ = _value_, _value_ = _value_.
62: The sequence spline.lamda is not increasing: spline.lamda [_value_] = _value_, spline.lamda [_value_] = _value_. The sequence spline.mu is not increasing: spline.mu[_value_] = _value_, spline.mu[_value_] = _value_.
257: On entry, point (x[_value_] = _value_, y[_value_] = _value_) lies outside the rectangle bounded by spline.lamda[3] = _value_, spline.lamda[_value_] = _value_, spline.mu[3] = _value_, spline.mu[_value_] = _value_.
successfully call of the nag_2d_spline_eval.

Example:
    This program reads in knot sets spline.lamda[0],. . . ,spline.lamda[spline.nx-1]
    and spline.mu[0],. . . ,spline.mu[spline.ny and a set of bicubic spline coefficients cij.
    Following these are a value for m and the co-ordinates (xr, yr), for r = 1, 2, . . .,m,
    at which the spline is to be evaluated.

void test_nag_2d_spline_eval()
{
    int i, m = 7;
    double x[20] = {1.0, 1.1, 1.5, 1.6, 1.9, 1.9, 2.0};
    double y[20] = {0.0, 0.1, 0.7, 0.4, 0.3, 0.8, 1.0};
    double ff[20];
    Nag_2dSpline spline;
    double lamda[] = {1.0,1.0,1.0,1.0,1.3,1.5,1.6,2.0,2.0,2.0,2.0};
    double mu[] = {0.0,0.0, 0.0, 0.0, 0.4, 0.7, 1.0, 1.0, 1.0, 1.0};
    double c[] ={1.0000, 1.1333, 1.3667, 1.7000, 1.9000, 2.0000,
        1.2000, 1.3333, 1.5667, 1.9000, 2.1000, 2.2000,
        1.5833, 1.7167, 1.9500, 2.2833, 2.4833, 2.5833,
        2.1433, 2.2767, 2.5100, 2.8433, 3.0433, 3.1433,
        2.8667, 3.0000, 3.2333, 3.5667, 3.7667, 3.8667,
        3.4667, 3.6000, 3.8333, 4.1667, 4.3667, 4.4667,
        4.0000, 4.1333, 4.3667, 4.7000, 4.9000, 5.0000};

    spline.nx = 11;
    spline.ny = 10;
    spline.c = c;
    spline.lamda =lamda;
    spline.mu = mu;

    nag_2d_spline_eval(m, x, y, ff, &spline);

    printf(" i x[i] y[i] ff[i]\n");
    for (i=0; i<m; i++)
        printf("%7ld %11.3f%11.3f%11.3f\n",i,x[i],y[i],ff[i]);
}

    The output is following:

    i 	x[i] 	y[i] 	ff[i]

    0 	1.000 	0.000 	1.000
    1 	1.100 	0.100 	1.310
    2 	1.500 	0.700 	2.950
    3 	1.600 	0.400 	2.960
    4 	1.900 	0.300 	3.910
    5 	1.900 	0.800 	4.410
    6 	2.000 	1.000 	5.000

Summary: Evaluation of bicubic spline, at a set of points
Sample data:
Header file: OCN_e02.h
See also:


nag_2d_spline_eval_rect

Function: nag_2d_spline_eval_rect
Prototype:
int nag_2d_spline_eval_rect(int mx,int my,const double x[],const double y[],double ff[],Nag_2dSpline *spline)
Remarks: calculates values of a bicubic spline from its B-spline representation. The spline is evaluated at all points on a rectangular grid.
Parameters:
my
  the number of points along the x and y axes that define the rectangular grid.
y[]
  These are the x and y co-ordinates that define the rectangular grid of points at which values of the spline are required
ff[]
  contains the value of the spline at the point (xq, yr),
spline
  Pointer to structure of type Nag_2dSpline

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, mx must not be less than 1: mx = _value.  On entry, my must not be less than 1: my = _value.  On entry, spline.nx must not be less than 8: spline.nx = _value.  On entry, spline.ny must not be less than 8: spline.ny = _value.
73: Memory allocation failed.
255: On entry, the end knots must satisfy _value	, _value	 = _value	, _value	 = _value	.
62: The sequence spline.lamda is not increasing: spline.lamda[_value	] = _value	, spline.lamda [_value	] = _value	.  The sequence spline.mu is not increasing: spline.mu[_value	] = _value	, spline.mu[_value	] = _value	.
256: On entry, the end knots and coordinates must satisfy spline.lamda[3] = x[0] and x[mx]-1] = spline.lamda[spline.nx-4]. spline.lamda[3] = _value	, x[0] = _value	, x[_value	] = _value	, spline.lamda[_value	] = _value	.  On entry, the end knots and coordinates must satisfy spline.mu[3] = y[0] and y[my-1] = spline.mu[spline.ny-4]. spline.mu[3] = _value	, y[0] = _value	, y[_value	] = _value	, spline.mu[_value	] = _value	.
63: The sequence x is not strictly increasing: x[_value	] = _value	, x[_value	] = _value	.  The sequence y is not strictly increasing: y[_value	] = _value	, y[_value	] = _value	.
successfully call of the nag_2d_spline_eval_rect function.

Example:
    This program reads in knot sets spline.lamda[0],. . . ,spline.lamda[spline.nx-1]
    and spline.mu[0],. . ., spline.mu[spline.ny-1], and a set of bicubic spline
    coefficients cij . Following these are values for mx and the x co-ordinates x[q],
    for q = 1, 2, . . .,mx, and values for my and the y co-ordinates y[r],
    for r = 1, 2, . . .,my, defining the grid of points on which the spline
    is to be evaluated.

void test_nag_2d_spline_eval_rect()
{
    int i, j, mx = 7, my = 6;
    double x[20] = {1.0, 1.1, 1.3, 1.4, 1.5, 1.7, 2.0};
    double y[20] = {0.0, 0.2, 0.4, 0.6, 0.8, 1.0};
    double ff[400];
    Nag_2dSpline spline;
    double lamda[] = {1.0,1.0,1.0,1.0,1.3,1.5,1.6,2.0,2.0,2.0,2.0};
    double mu[] = {0.0,0.0, 0.0, 0.0, 0.4, 0.7, 1.0, 1.0, 1.0, 1.0};
    double c[] ={1.0000, 1.1333, 1.3667, 1.7000, 1.9000, 2.0000,
                 1.2000, 1.3333, 1.5667, 1.9000, 2.1000, 2.2000,
                 1.5833, 1.7167, 1.9500, 2.2833, 2.4833, 2.5833,
                 2.1433, 2.2767, 2.5100, 2.8433, 3.0433, 3.1433,
                 2.8667, 3.0000, 3.2333, 3.5667, 3.7667, 3.8667,
                 3.4667, 3.6000, 3.8333, 4.1667, 4.3667, 4.4667,
                 4.0000, 4.1333, 4.3667, 4.7000, 4.9000, 5.0000};

    spline.nx = 11;
    spline.ny = 10;
    spline.c = c;
    spline.lamda =lamda;
    spline.mu = mu;

    nag_2d_spline_eval_rect(mx, my, x, y, ff, &spline);

    printf("Spline evaluated on x-y grid (x across, y down):\n   ");
    for(i=0; i<mx; i++)
        printf(" %8.3f ",x[i]);
    printf("\n");
    for (j=0; j<my; j++)
    {
        printf("%2.1f",y[j]);
        for (i=0; i<mx; i++)
        {
            printf(" %8.3f ", ff[my*i+j]);
            if(i%7==6 || i==mx-1)
                printf("\n");
        }
    }
}

    The output is following:

    Spline evaluated on x-y grid (x across, y down):

            1.0 	1.1 	1.3 	1.4 	1.5 	1.7 	2.0
    0.0 	1.000 	1.210 	1.690 	1.960 	2.250 	2.890 	4.000
    0.2 	1.200 	1.410 	1.890 	2.160 	2.450 	3.090 	4.200
    0.4 	1.400 	1.610 	2.090 	2.360 	2.650 	3.290 	4.400
    0.6 	1.600 	1.810 	2.290 	2.560 	2.850 	3.490 	4.600
    0.8 	1.800 	2.010 	2.490 	2.760 	3.050 	3.690 	4.800
    1.0 	2.000 	2.210 	2.690 	2.960 	3.250 	3.890 	5.000

Summary: Evaluation of bicubic spline, at a mesh of points
Sample data:
Header file: OCN_e02.h
See also:


nag_complex_cholesky

Function: nag_complex_cholesky
Prototype:
int nag_complex_cholesky(int n,complex a[],int tda,double p[])
Remarks: computes a Cholesky factorization of a complex positive-definite Hermitian matrix.
Parameters:
n
  the order of the matrix A.
a[]
  Input:the lower triangle of the n by n positive-definite Hermitian matrix A. The elements of the array above the diagonal need not be set.  Output: the off-diagonal elements of the upper triangular matrix U. The lower triangle of A is unchanged.
tda
  the second dimension of the array a as declared in the function from which nag complex cholesky is called.
p[]
  the reciprocals of the real diagonal elements of U.

Return values:
This function returns NAG error code, 0 if no error.
370: Matrix diagonal element a [_value_][_value_] has non-zero imaginary part.
358: The matrix is not positive-de.nite, possibly due to rounding errors.
11: On entry, n must not be less than 1: n = _value_.
17: On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.
successfully call of the nag_complex_cholesky function.

Example:
    This example computes the Cholesky factorization of the well-conditioned positive-definite Hermitian matrix
    .
    ..
    15 1 - 2i 2 -4 + 3i
    1 + 2i 20 -2 + i 3 - 3i
    2 -2 - i 18 -1 + 2i
    -4 - 3i 3 + 3i -1 - 2i 26
    .
    ..
    .

void test_nag_complex_cholesky()
{
    int i, j, n;
    matrix<complex> a;
    a.SetSize(8,8);
    double p[8];

    printf("f01bnc Example Program Results\n");
    a[0][0] = 15.0+0.0i;
    a[1][0] = 1.0+2.0i;
    a[1][1] = 20.0+0.0i;
    a[2][0] = 2.0+0.0i;
    a[2][1] = -2.0-1.0i;
    a[2][2] = 18.0+0.0i;
    a[3][0] = -4.0-3.0i;
    a[3][1] = 3.0+3.0i;
    a[3][2] = -1.0-2.0i;
    a[3][3] = 26.0+0.0i;
    n = 4;
    nag_complex_cholesky(n,a,8,p);
    complex gh;
    printf("\n Upper triangle of Complex matrix U by rows\n");
    for (i=0; i<n; ++i)
    {
        printf("\n");
        printf("   (%7.4f,%9.4f)\n", 1.0/p[i], 0.0);
        for (j=i+1; j<n; ++j)
        {
            gh = a[i][j];
            printf("   (%7.4f,%9.4f)\n",gh.m_re, gh.m_im);
        }
    }

}

    The output is following:

    Upper triangle of Complex matrix U by rows

    ( 3.8730, 0.0000)
    ( 0.2582, -0.5164)
    ( 0.5164, 0.0000)
    (-1.0328, 0.7746)
    ( 4.4347, 0.0000)
    (-0.4811, 0.1654)
    ( 0.8268, -0.6013)
    ( 4.1803, 0.0000)
    ( 0.0073, 0.3463)
    ( 4.8133, 0.0000)

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_cholesky_skyline

Function: nag_real_cholesky_skyline
Prototype:
int nag_real_cholesky_skyline(int n,double a[],int lal,int row[],double al[],double d[])
Remarks: computes the Cholesky factorization of a real symmetric positive-de.nite variable-bandwidth matrix.
Parameters:
n
  the order of the matrix A.
a[]
  the elements within the envelope of the lower triangle of the positive-de.nite symmetric matrix A, taken in row by row order.
lal
  the smaller of the dimensions of the arrays a and al as declared in the function from which nag real cholesky skyline is called.
row[]
  contain the width of row i of the matrix A.
al[]
  : the elements within the envelope of the lower triangular matrix L, taken in row by row order.
d[]
  the diagonal elements of the diagonal matrix D. Note that the determinant of A is equal to the product of these diagonal elements.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 1: n = _value_.  On entry, row[_value_] must not be less than 1: row[_value_] = _value_.
13: On entry, row[_value_] = _value_ while i = _value_.  These parameters must satisfy row[i] = i + 1.
17: On entry, lal = _value_while row[0]+ . . .+row[n-1] = _value_. These parameters must satisfy lal = row[0]+ . . .+row[n - 1].
359: The matrix is not positive-de.nite, possibly due to rounding errors. The factorization has been completed but may be very inaccurate.
358: The matrix is not positive-de.nite, possibly due to rounding errors.
successfully call of the nag_real_cholesky_skyline function.

Example:
    To obtain the Cholesky factorization of the symmetric matrix, whose lower triangle is
    .
    ......
    1
    2 5
    0 3 13
    0 0 0 16
    5 14 18 8 55
    0 0 0 24 17 77
    .
    ......
    .
    For this matrix, the elements of row must be set to 1, 2, 2, 1, 5, 3, and the elements
    within the envelope must be supplied in row order as 1, 2, 5, 3, 13, 16, 5, 14, 18, 8,
    55, 24, 17, 77.

void test_nag_real_cholesky_skyline()
{

    int i, k, k1, k2, lal, n;
    double a[] = {1.0, 2.0, 5.0, 3.0, 13.0, 16.0, 5.0, 14.0,
                  18.0, 8.0, 55.0, 24.0, 17.0, 77.0};
    double al[36], d[8];
    n = 6;
    int row[] = {1, 2, 2, 1, 5, 3, 0, 0};
    k2 =14;
    lal = k2;

    int success = nag_real_cholesky_skyline(n, a, lal, row, al, d);
    printf("\n");
    if(success == 0)
    {
        printf(" i d[i] Rowi of unit lower triangle\n\n");
        k2 = 0;
        for (i=0; i<n; ++i)
        {
            k1 = k2;
            k2 = k2+row[i];
            printf(" %3ld%8.3f", i, d[i]);
            for (k=k1; k<k2; k++)
                printf("%8.3f", al[k]);
            printf("\n");
        }
    }
    else
    printf("there is some problem with the function call");

}

    The output is following:

    i 	 d[i] 	Rowi of unit lower triangle

    0 	 1.000 	1.000
    1 	 1.000 	2.000  1.000
    2 	 4.000 	3.000  1.000
    3 	16.000 	1.000
    4 	 1.000 	5.000  4.000  1.500  0.500  1.000
    5 	16.000 	1.500  5.000  1.000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_qr

Function: nag_real_qr
Prototype:
int nag_real_qr(int m,int n,double a[],int tda,double zeta[])
Remarks: finds the QR factorization of the real m by n matrix A, where m = n.
Parameters:
m
  the number of rows of A.
n
  the number of columns of A.
a[]
  Input: the leading m by n part of the array a must contain the matrix to be factorized.  Output: the n by n upper triangular part of a will contain the upper triangular matrix R and the m by n strictly lower triangular part of a will contain details of the factorization as described in Section 3.
tda
  the second dimension of the array a as declared in the function from which nag real qr is called.
zeta[]
  contains the scalar zeta_k for the kth transformation.

Return values:
This function returns NAG error code, 0 if no error.
17: On entry, m = _value_ while n = _value_. These parameters must satisfy m = n.  On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.
11: On entry, n must not be less than 0: n = _value_.
successfully call of the nag_real_qr function.

Example:
    To obtain the QR factorization of the 5 by 3 matrix
    A =
    .
    ....
    2.0 2.5 2.5
    2.0 2.5 2.5
    1.6 -0.4 2.8
    2.0 -0.5 0.5
    1.2 -0.3 -2.9

void test_nag_real_qr()
{
    double zeta[10];
    matrix a;
    a.SetSize(20,10);
    int i, j, m, n;
    m = 5;
    n = 3;
    a[0][0] = 2.0;
    a[0][1] = 2.5;
    a[0][2] = 2.5;
    a[1][0] = 2.0;
    a[1][1] = 2.5;
    a[1][2] = 2.5;
    a[2][0] = 1.6;
    a[2][1] = -0.4;
    a[2][2] = 2.8;
    a[3][0] = 2.0;
    a[3][1] = -0.5;
    a[3][2] = 0.5;
    a[4][0] = 1.2;
    a[4][1] = -0.3;
    a[4][2] = -2.9;

    nag_real_qr(m, n, a, 10, zeta);
    printf("QR factorization of A\n\n");
    printf("Vector zeta\n");
    for (i = 0; i < n; ++i)
        printf(" %8.4f", zeta[i]);
    printf("\n\n");
    printf("Matrix A after factorization (upper triangular part is R)\n");
    for (i = 0; i < m; ++i)
    {
        for (j = 0; j < n; ++j)
            printf(" %8.4f", a[i][j]);
        printf("\n");
    }
}

    The output is following:

    QR factorization of A

    Vector zeta

    1.2247 1.1547 1.2649

    Matrix A after factorization (upper triangular part is R)

    -4.0000 	-2.0000 	-3.0000
     0.4082 	-3.0000 	-2.0000
     0.3266 	-0.4619 	-4.0000
     0.4082 	-0.5774 	 0.0000
     0.2449 	-0.3464 	-0.6325

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_apply_q

Function: nag_real_apply_q
Prototype:
int nag_real_apply_q(MatrixTranspose trans,Nag_WhereElements wheret,int m,int n,double a[],int tda,double zeta[],int ncolb,double b[],int tdb)
Remarks: performs one of the transformations B := QB or B := QT B, where B is an m by ncolb real matrix and Q is an m by m orthogonal matrix, given as the product of Householder transformation matrices.
Parameters:
m
  the number of rows of A.
n
  the number of columns of A.
a[]
  contain details of the matrix Q.
tda
  the second dimension of the array a as declared in the function from which nag real apply q is called.
zeta[]
  contain the elements of zeta.
ncolb
  the number of columns of B.
b[]
  Input: the leading m by ncolb part of the array b must contain the matrix to be transformed.  Output: b is overwritten by the transformed matrix.
tdb
  the second dimension of the array b as declared in the function from which nag real apply q is called.

Return values:
This function returns NAG error code, 0 if no error.
70: On entry, parameter trans had an illegal value.  On entry, parameter wheret had an illegal value.
17: On entry, m = _value_ while n = _value_. These parameters must satisfy m = n.  On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.  On entry, tdb = _value_ while ncolb = _value_. These parameters must satisfy tdb = ncolb.
11: On entry, n must not be less than 0: n = _value_.  On entry, ncolb must not be less than 0: ncolb = _value_.
73: Memory allocation failed.
successfully call of the nag_real_apply_q function.

Example:
    To obtain the matrix QTB for the matrix B given by
    B =
    .
    ....
    1.1 0 0 .00
    0.90 0.00
    0.60 1.32
    0.00 1.10
    -0.80 -0.26
    .
    ....
    following the QR factorization of the 5 by 3 matrix A given by
    A =
    .
    ....
    2.0 2.5 2.5
    2.0 2.5 2.5
    1.6 -0.4 2.8
    2.0 -0.5 0.5
    1.2 -0.3 -2.9
    .

void test_nag_real_apply_q()
{
    double zeta[10];
    matrix a, b;
    a.SetSize(20,10);
    b.SetSize(20,5);
    int i, j, m, n, ncolb;
    m = 5;
    n = 3;
    a[0][0] =2.0;
    a[0][1] =2.5;
    a[0][2] =2.5;
    a[1][0] =2.0;
    a[1][1] =2.5;
    a[1][2] =2.5;
    a[2][0] =1.6;
    a[2][1] =-0.4;
    a[2][2] =2.8;
    a[3][0] =2.0;
    a[3][1] =-0.5;
    a[3][2] =0.5;
    a[4][0] =1.2;
    a[4][1] =-0.3;
    a[4][2] =-2.9;

    b[0][0] =1.1;
    b[0][1] =0.0;

    b[1][0] =0.9;
    b[1][1] =0.0;

    b[2][0] =0.6;
    b[2][1] =1.32;

    b[3][0] =0.0;
    b[3][1] =1.1;

    b[4][0] =-0.8;
    b[4][1] =-0.26;
    ncolb = 2;
    nag_real_qr(m, n, a, 10, zeta);
    nag_real_apply_q(Transpose, Nag_ElementsSeparate, m, n, a, 10, zeta,
                    ncolb, b, 5);
    printf("Matrix Q'*B\n");
    for (i = 0; i < m; ++i)
    {
        for (j = 0; j < ncolb; ++j)
            printf(" %8.4f", b[i][j]);
        printf("\n");
    }
}

    The output is following:

    Matrix Q'*B

    -1.0000 	-1.0000
    -1.0000 	 1.0000
    -1.0000 	-1.0000
    -0.1000 	 0.1000
    -0.1000	 	-0.1000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_form_q

Function: nag_real_form_q
Prototype:
int nag_real_form_q(Nag_WhereElements wheret,int m,int n,int ncolq,double a[],int tda,double zeta[])
Remarks: returns the .rst ncolq columns of the real m by m orthogonal matrix Q, where Q is given as the product of Householder transformation matrices.
Parameters:
m
  the number of rows of A.
n
  the number of columns of A.
ncolq
  the required number of columns of Q.
a[]
  Input: the required number of columns of Q.  When ncolq = 0 then an immediate return is effected.  Output: the first ncolq columns of the array a are overwritten by the first ncolq columns of the m by m orthogonal matrix Q.
tda
  the second dimension of the array a as declared in the function from which nag real form q is called.
zeta[]
  contain the elements of zeta.

Return values:
This function returns NAG error code, 0 if no error.
70: On entry, parameter wheret had an illegal value.
17: On entry, m = _value_ while n = _value_. These parameters must satisfy m = n.  On entry, tda = _value_ while max(n,ncolq) = _value_. These parameters must satisfy tda = max(n,ncolq).
19: On entry, ncolq = _value_ while m = _value_. These parameters must satisfy ncolq = m.
11: On entry, n must not be less than 0: n = _value_.  On entry, ncolq must not be less than 0: ncolq = _value_.
73: Memory allocation failed.
successfully call of the nag_real_form_q function.

Example:
    To obtain the 5 by 5 orthogonal matrix Q following the QR factorization
    of the 5 by 3 matrix A given by
    A =
    .
    ....
    2.0 2.5 2.5
    2.0 2.5 2.5
    1.6 -0.4 2.8
    2.0 -0.5 0.5
    1.2 -0.3 -2.9
    .
    ....

void test_nag_real_form_q()
{
    double zeta[10];
    matrix a, q;
    a.SetSize(20,10);
    q.SetSize(20,20);
    int i, j, m, n, ncolq;
    m = 5;
    n = 3;
    a[0][0] =2.0;
    a[0][1] =2.5;
    a[0][2] =2.5;
    a[1][0] =2.0;
    a[1][1] =2.5;
    a[1][2] =2.5;
    a[2][0] =1.6;
    a[2][1] =-0.4;
    a[2][2] =2.8;
    a[3][0] =2.0;
    a[3][1] =-0.5;
    a[3][2] =0.5;
    a[4][0] =1.2;
    a[4][1] =-0.3;
    a[4][2] =-2.9;

    nag_real_qr(m, n, a, 10, zeta);

    for (j = 0; j < n; ++j)
        for (i = 0; i < m; ++i)
            q[i][j] = a[i][j];
    ncolq = m;
    nag_real_form_q(Nag_ElementsSeparate, m, n, ncolq, q, 20,
                    zeta);
    printf("Matrix Q\n");
    for (i = 0; i < m; ++i)
    {
        for (j = 0; j < ncolq; ++j)
            printf(" %8.4f", q[i][j]);
        printf("\n");
    }
}

    The output is following:

    Matrix Q

    -0.5000 -0.5000  0.0000 -0.5000 -0.5000
    -0.5000 -0.5000  0.0000  0.5000  0.5000
    -0.4000  0.4000 -0.6000 -0.4000  0.4000
    -0.5000  0.5000  0.0000  0.5000 -0.5000
    -0.3000  0.3000  0.8000 -0.3000  0.3000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_complex_qr

Function: nag_complex_qr
Prototype:
int nag_complex_qr(int m,int n,complex a[],int tda,complex theta[])
Remarks: finds the QR factorization of the complex m by n matrix A, where m = n.
Parameters:
m
  the number of rows of A.
n
  the number of columns of A.
a[]
  Input: the leading m by n part of the array a must contain the matrix to be factorized.  Output: the n by n upper triangular part of a will contain the upper triangular matrix R, with the imaginary parts of the diagonal elements set to zero, and the m by n strictly lower triangular part of a will contain details of the factorization as described above.
tda
  the second dimension of the array a as declared in the function from which nag complex qr is called.
theta[]
  the scalar theta_k for the kth transformation.

Return values:
This function returns NAG error code, 0 if no error.
17: On entry, m = _value_ while n = _value_. These parameters must satisfy m = n.  On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.
11: On entry, n must not be less than 0: n = _value_.
successfully call of the nag_complex_qr function.

Example:
    To obtain the QR factorization of the 5 by 3 matrix
    A =
    .
    ....
    0.5i -0.5 + 1.5i -1.0+ 1.0i
    0.4 + 0.3i 0.9 + 1.3i 0.2+ 1.4i
    0.4 -0.4 + 0.4i 1.8
    0.3 - 0.4i 0.1 + 0.7i 0.0
    - 0.3i 0.3 + 0.3i 2.4i
    .
    ....

void test_nag_complex_qr()
{
    int i, j, m, n;

    matrix<complex> theta;
    theta.SetSize(1,10);					 //{0.0-0.3i,0.3+0.3i,0.0+2.4i}};
    matrix<complex> a;
    a.SetSize(20,10);
    a[0][0] = 0.0+0.5i;
    a[0][1] = -0.5+1.5i;
    a[0][2] = -1.0+1.0i;

    a[1][0] = 0.4+0.3i;
    a[1][1] = 0.9+1.3i;
    a[1][2] = 0.2+1.4i;

    a[2][0] = 0.4+0.0i;
    a[2][1] = -0.4+0.4i;
    a[2][2] = 1.8+0.0i;

    a[3][0] = 0.3-0.4i;
    a[3][1] = 0.1+0.7i;
    a[3][2] = 0.0+0.0i;

    a[4][0] = 0.0-0.3i;
    a[4][1] = 0.3+0.3i;
    a[4][2] = 0.0+2.4i;
    m = 5;
    n = 3;
    printf("A=\n");
    for (i=0; i<m; ++i)
    {
        for (j=0; j<n; ++j)
        {
            complex temp = a[i][j];

            printf(" (%7.4f,%8.4f)", temp.m_re, temp.m_im);
            if(j%3==2 || j==n-1)
                printf("\n");
        }
    }
    nag_complex_qr(m, n, a, 10, theta);
    printf("QR factorization of A\n");
    printf("Vector THETA\n");
    for (i=0; i<n; ++i)
    {
        complex temp = theta[0][i];
        printf(" (%7.4f,%8.4f)", temp.m_re, temp.m_im);
        if(i%3==2 || i==n-1)
            printf("\n");
    }
    printf("\nMatrix A after factorization (upper triangular part is R)\n");
    for (i=0; i<m; ++i)
    {
        for (j=0; j<n; ++j)
        {
            complex temp = a[i][j];

            printf(" (%7.4f,%8.4f)", temp.m_re, temp.m_im);
            if(j%3==2 || j==n-1)
                printf("\n");
        }
    }
}

    The output is following:
    A=
     ( 0.0000,  0.5000) (-0.5000,  1.5000) (-1.0000,  1.0000)
     ( 0.4000,  0.3000) ( 0.9000,  1.3000) ( 0.2000,  1.4000)
     ( 0.4000,  0.0000) (-0.4000,  0.4000) ( 1.8000,  0.0000)
     ( 0.3000, -0.4000) ( 0.1000,  0.7000) ( 0.0000,  0.0000)
     ( 0.0000, -0.3000) ( 0.3000,  0.3000) ( 0.0000,  2.4000)

    QR factorization of A
    Vector THETA

    ( 1.0000, 0.5000) ( 1.0954, -0.3333) ( 1.2649, 0.0000)

    Matrix A after factorization (upper triangular part is R)

    ( 1.0000, 0.0000) 	( 1.0000, 1.0000)  ( 1.0000, 1.0000)
    (-0.2000, -0.4000)  (-2.0000, 0.0000)  (-1.0000, -1.0000)
    (-0.3200, -0.1600)  (-0.3505, 0.2629)  (-3.0000, 0.0000)
    (-0.4000, 0.2000)   ( 0.0000, 0.5477)  ( 0.0000, 0.0000)
    (-0.1200, 0.2400)   ( 0.1972, 0.2629)  ( 0.0000, 0.6325)

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_complex_apply_q

Function: nag_complex_apply_q
Prototype:
int nag_complex_apply_q(MatrixTranspose trans,Nag_WhereElements wheret,int m,int n,complex a[],int tda,complex theta[],int ncolb,complex b[],int tdb)
Remarks: ) performs one of the transformations B := QB or B := QHB, where B is an m by ncolb complex matrix and Q is an m by m unitary matrix, given as the product of Householder transformation matrices.
Parameters:
m
  the number of rows of A.
n
  the number of columns of A.
a[]
  the leading m by n strictly lower triangular part of the array a must contain details of the matrix Q.
tda
  the second dimension of the array a as declared in the function from which nag complex apply q is called.
theta[]
  contain the elements of theta.
ncolb
  Input: ncolb, the number of columns of B. When ncolb = 0 then an immediate return is effected.
b[]
  Input: the leading m by ncolb part of the array b must contain the matrix to be transformed.  Output: b is overwritten by the transformed matrix.
tdb
  the second dimension of the array b as declared in the function from which nag complex apply q is called.

Return values:
This function returns NAG error code, 0 if no error.
70: On entry, parameter trans had an illegal value.  On entry, parameter wheret had an illegal value.
17: On entry, m = _value_ while n = _value_. These parameters must satisfy m = n.  On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.  On entry, tdb = _value_while ncolb = _value_. These parameters must satisfy tdb = ncolb.
11: On entry, n must not be less than 0: n = _value_.  On entry, ncolb must not be less than 0: ncolb = _value_.
73: Memory allocation failed.
successfully call of the nag_complex_apply_q function.

Example:
    To obtain the matrix QHB for the matrix B given by
    B =
    .
    ....
    -0.55 + 1.05i 0.45 + 1.05i
    0.49 + 0.93i 1.09 + 0.13i
    0.56 - 0.16i 0.64 + 0.16i
    0.39 + 0.23i -0.39 - 0.23i
    1.1 3 +0.83i -1.1 3 +0.77i
    .
    ....
    following the QR factorization of the 5 by 3 matrix A given by
    A =
    .
    ....
    0.5i -0.5 + 1.5i -1.0+ 1.0i
    0.4 + 0.3i 0.9 + 1.3i 0.2+ 1.4i
    0.4 -0.4 + 0.4i 1.8
    0.3 - 0.4i 0.1 + 0.7i 0.0
    -0.3i 0.3 + 0.3i 2.4i
    .
    ....

void test_nag_complex_apply_q()
{

    int i,j,m, n,ncolb;
    matrix<complex> a, b, theta;
    a.SetSize(20,10);
    b.SetSize(20,5);
    theta.SetSize(1,10);

    m = 5;
    n = 3;

    a[0][0] = 0.0+0.5i;
    a[0][1] = -0.5+1.5i;
    a[0][2] = -1.0+1.0i;

    a[1][0] = 0.4+0.3i;
    a[1][1] = 0.9+1.3i;
    a[1][2] = 0.2+1.4i;

    a[2][0] = 0.4+0.0i;
    a[2][1] = -0.4+0.4i;
    a[2][2] = 1.8+0.0i;

    a[3][0] = 0.3-0.4i;
    a[3][1] = 0.1+0.7i;
    a[3][2] = 0.0+0.0i;

    a[4][0] = 0.0-0.3i;
    a[4][1] = 0.3+0.3i;
    a[4][2] = 0.0+2.4i;
    ncolb = 2;
    b[0][0] =-0.55 +1.05i;
    b[0][1] =0.45+1.05i;

    b[1][0] = 0.49 + 0.93i;
    b[1][1] = 1.09+0.13i;

    b[2][0] =0.56 - 0.16i;
    b[2][1] = 0.64+0.16i;

    b[3][0] =0.39+0.23i;
    b[3][1] = -0.39-0.23i;

    b[4][0] =1.13+0.83i;
    b[4][1] = -1.13+0.77i;

    nag_complex_qr(m,n, a, 10, theta);

    nag_complex_apply_q(ConjugateTranspose, Nag_ElementsSeparate, m,n,a, 10,
                        theta, ncolb, b, 5);

    printf("\nMatrix conjg( Q' )*B\n");
    for (i=0; i<m; ++i)
    {
        for (j=0; j<ncolb; ++j)
        {
            complex temp = b[i][j];
            printf(" (%7.4f,%8.4f)", temp.m_re,temp.m_im);
            if(j%2==1 || j==n-1)
                printf("\n");

        }
    }

}

    The output is following:

    Matrix conjg( Q' )*B

    ( 1.0000,1.0000) 	( 1.0000, -1.0000)
    (-1.0000,0.0000) 	(-1.0000,0.0000)
    (-1.0000,1.0000) 	(-1.0000, -1.0000)
    (-0.0600,-0.0200) 	(-0.0400, 0.1200)
    ( 0.0400,0.1200) 	(-0.0600,0.0200)

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_complex_form_q

Function: nag_complex_form_q
Prototype:
int nag_complex_form_q(Nag_WhereElements wheret,int m,int n,int ncolq,complex a[],int tda,complex theta[])
Remarks: returns the .rst ncolq columns of the m by m unitary matrix Q, where Q is given as the product of Householder transformation matrices.
Parameters:
m
  the number of rows of A.
n
  the number of columns of A.
ncolq
  the required number of columns of Q.
a[]
  Input: the leading m by n strictly lower triangular part of the array a must contain details of the matrix Q.  Output: the .rst ncolq columns of the array a are overwritten by the first ncolq columns of the m by m unitary matrix Q. When n = 0 then the .rst ncolq columns of a are overwritten by the .rst ncolq columns of the unit matrix.
tda
  the second dimension of the array a as declared in the function from which nag complex form q is called.
theta[]
  contain the elements of theta.

Return values:
This function returns NAG error code, 0 if no error.
70: On entry, parameter wheret had an illegal value.
17: On entry, m = _value_ while n = _value_. These parameters must satisfy m = n.  On entry, tda = _value_ while max(n,ncolq) = _value_. These parameters must satisfy tda = n.
11: On entry, n must not be less than 0: n = _value_.  On entry, ncolq must not be less than 0: ncolq = _value_.
19: On entry, ncolq = _value_ while m = _value_. These parameters must satisfy ncolq = m.
73: Memory allocation failed.
successfully call of the nag_complex_form_q function.

Example:
    To obtain the 5 by 5 unitary matrix Q following the QR factorization
    of the 5 by 3 matrix A given by
    A =
    .
    ....
    0.5i -0.5 + 1.5i -1.0+ 1.4i
    0.4 + 0.3i 0.9 + 1.3i 0.2+ 1.4i
    0.4 -0.4 + 0.4i 1.8
    0.3 - 0.4i 0.1 + 0.7i 0.0
    -0.3i 0.3 + 0.3i 2.4i
    .
    ....

void test_nag_complex_form_q()
{
    int i, j, m, n, ncolq;
    matrix<complex>a, q, theta;
    a.SetSize(20,10);
    q.SetSize(20,20);
    theta.SetSize(1,10);
    m = 5;
    n = 3;
    a[0][0] = 0.0+0.5i;
    a[0][1] = -0.5+1.5i;
    a[0][2] = -1.0+1.0i;

    a[1][0] = 0.4+0.3i;
    a[1][1] = 0.9+1.3i;
    a[1][2] = 0.2+1.4i;

    a[2][0] = 0.4+0.0i;
    a[2][1] = -0.4+0.4i;
    a[2][2] = 1.8+0.0i;

    a[3][0] = 0.3-0.4i;
    a[3][1] = 0.1+0.7i;
    a[3][2] = 0.0+0.0i;

    a[4][0] = 0.0-0.3i;
    a[4][1] = 0.3+0.3i;
    a[4][2] = 0.0+2.4i;

    nag_complex_qr(m, n, a, 10, theta);

    for (j=0; j<n; ++j)
        for (i=0; i<m; ++i)
            q[i][j] = a[i][j];

    ncolq = m;
    nag_complex_form_q(Nag_ElementsSeparate, m, n, ncolq, q, 20,theta);

    printf("\nMatrix Q\n");
    for (i=0; i<m; ++i)
    {
        for (j=0; j<ncolq; ++j)
        {
            complex temp = q[i][j];
            printf(" (%5.2f,%5.2f)", temp.m_re, temp.m_im);
            if(j%5==4 || j==ncolq-1)
                printf("\n");
        }
    }
}

    The output is following:

    Matrix Q

    ( 0.00, 0.50) ( 0.00,-0.50) ( 0.00, 0.00) ( 0.50, 0.00) ( 0.40, 0.30)
    ( 0.40, 0.30) (-0.40,-0.30) ( 0.00, 0.00) (-0.30, 0.40) (-0.48, 0.14)
    ( 0.40, 0.00) ( 0.40, 0.00) (-0.60, 0.00) (-0.24,-0.32) ( 0.00, 0.40)
    ( 0.30,-0.40) ( 0.30,-0.40) ( 0.00, 0.00) ( 0.50, 0.00) (-0.40,-0.30)
    ( 0.00,-0.30) ( 0.00,-0.30) ( 0.00,-0.80) (-0.24, 0.18) ( 0.30, 0.00)

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_symm_eigenvalues

Function: nag_real_symm_eigenvalues
Prototype:
int nag_real_symm_eigenvalues(int n,double a[],int tda,double r[])
Remarks: calculates all the eigenvalues of a real symmetric matrix.
Parameters:
n
  the order of the matrix A.
a[]
  Input: the lower triangle of the n by n symmetric matrix A. The elements of the array above the diagonal need not be set.  Output: the elements of A below the diagonal are overwritten, and the rest of the array is unchanged.
tda
  the second dimension of the array a as declared in the function from which nag real symm eigenvalues is called.
r[]
  the eigenvalues in ascending order.

Return values:
This function returns NAG error code, 0 if no error.
362: More than _value_ iterations are required to isolate all the eigenvalues.
11: On entry, n must not be less than 1: n = _value_.
17: On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.
73: Memory allocation failed.
successfully call of the nag_real_symm_eigenvalues function.

Example:
    To calculate all the eigenvalues of the real symmetric matrix
    .
    ..
    0.5 0.0 2.3 -2.6
    0.0 0.5 -1.4 -0.7
    2.3 -1.4 0.5 0.0
    -2.6 -0.7 0.0 0.5
    .
    ..
    .

void test_nag_real_symm_eigenvalues()
{
    int i, j, n;
    matrix a;
    a.SetSize(8,8);
    double r[8];

    n = 4;
    a[0][0] = 0.5;
    a[0][1] = 0.0;
    a[0][2] = 2.3;
    a[0][3] = -2.6;

    a[1][0] = 0.0;
    a[1][1] = 0.5;
    a[1][2] = -1.4;
    a[1][3] = -0.7;

    a[2][0] = 2.3;
    a[2][1] = -1.4;
    a[2][2] = 0.5;
    a[2][3] = 0.0;

    a[3][0] = -2.6;
    a[3][1] = -0.7;
    a[3][2] = 0.0;
    a[3][3] = 0.5;

    nag_real_symm_eigenvalues(n, a, 8, r);
    printf("Eigenvalues\n");
    for (i=0; i<n; i++)
    {
        printf("%9.4f",r[i]);
        if(i%8==7 || i==n-1)
            printf("\n");
    }
}

    The output is following:

    Eigenvalues

    -3.0000 -1.0000 2.0000 4.0000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_symm_eigensystem

Function: nag_real_symm_eigensystem
Prototype:
int nag_real_symm_eigensystem(int n,double a[],int tda,double r[],double v[],int tdv)
Remarks: calculates all the eigenvalues and eigenvectors of a real symmetric matrix.
Parameters:
n
  the order of the matrix A.
a[]
  the lower triangle of the n by n symmetric matrix A. The elements of the array above the diagonal need not be set.
tda
  the second dimension of the array a as declared in the function from which nag real symm eigensystem is called.
r[]
  the eigenvalues in ascending order.
v[]
  the normalised eigenvectors, stored by columns; the ith column corresponds to the ith eigenvalue. The eigenvectors are normalised so that the sum of squares of the elements is equal to 1.
tdv
  the second dimension of the array v as declared in the function from which nag real symm eigensystem is called.

Return values:
This function returns NAG error code, 0 if no error.
362: More than _value_ iterations are required to isolate all the eigenvalues.
11: On entry, n must not be less than 1: n = _value_.
17: On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.  On entry, tdv = _value_ while n = _value_. These parameters must satisfy tdv = n.
73: Memory allocation failed.
successfully call of the  nag_real_symm_eigensystem function.

Example:
    To calculate all the eigenvalues and eigenvectors of the real symmetric matrix
    .
    ..
    0.5 0.0 2.3 -2.6
    0.0 0.5 -1.4 -0.7
    2.3 -1.4 0.5 0.0
    -2.6 -0.7 0.0 0.5
    .
    ..
    .

void test_nag_real_symm_eigensystem()
{

    int i, j, n;
    matrix a, v;
    a.SetSize(8,8);
    double  r[8];
    v.SetSize(8,8);

    n = 4;
    a[0][0] = 0.5;
    a[0][1] = 0.0;
    a[0][2] = 2.3;
    a[0][3] = -2.6;

    a[1][0] = 0.0;
    a[1][1] = 0.5;
    a[1][2] = -1.4;
    a[1][3] = -0.7;

    a[2][0] = 2.3;
    a[2][1] = -1.4;
    a[2][2] = 0.5;
    a[2][3] = 0.0;

    a[3][0] = -2.6;
    a[3][1] = -0.7;
    a[3][2] = 0.0;
    a[3][3] = 0.5;

    nag_real_symm_eigensystem(n, a, 8, r, v, 8);
    printf("Eigenvalues\n");
    for (i=0; i<n; i++)
    {
        printf("%9.4f", r[i]);
        if(i%8==7 || i==n-1)
            printf("\n");
    }

    printf("Eigenvectors\n");
    for ( i=0; i<n; i++)
        for (j=0; j<n; j++)
        {
            printf("%9.4f", v[i][j]);
            if(j%8==7 || j==n-1)
                printf("\n");
        }

}

    The output is following:

    Eigenvalues

    -3.0000 -1.0000 2.0000 4.0000

    Eigenvectors

     0.7000   0.1000   0.1000  -0.7000
    -0.1000   0.7000   0.7000   0.1000
    -0.5000   0.5000  -0.5000  -0.5000
     0.5000   0.5000  -0.5000   0.5000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_symm_general_eigenvalues

Function: nag_real_symm_general_eigenvalues
Prototype:
int nag_real_symm_general_eigenvalues(int n,double a[],int tda,double b[],int tdb,double r[])
Remarks: calculates all the eigenvalues of Ax = lamdaBx, where A is a real symmetric matrix and B is a real symmetric positive-definite matrix.
Parameters:
n
  the order of the matrices A and B.
a[]
  Input: the upper triangle of the n by n symmetric matrix A. The elements of the array below the diagonal need not be set.  Output: the lower triangle of the array is overwritten. The rest of the array is unchanged.
tda
  the second dimension of the array a as declared in the function from which nag real symm general eigenvalues is called.
b[]
  Input: the upper triangle of the n by n symmetric positive-de.nite matrix B. The elements of the array below the diagonal need not be set.  Output: the elements below the diagonal are overwritten. The rest of the array is unchanged.
tdb
  the second dimension of the array b as declared in the function from which nag real symm general eigenvalues is called.
r[]
  the eigenvalues in ascending order.

Return values:
This function returns NAG error code, 0 if no error.
358: The matrix B is not positive-de.nite, possibly due to rounding errors.
362: More than _value_ iterations are required to isolate all the eigenvalues.
11: On entry, n must not be less than 1: n = _value_.
17: On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.  On entry, tdb = _value_ while n = _value_. These parameters must satisfy tdb = n.
73: Memory allocation failed.
successfully call of the nag_real_symm_general_eigenvalues function.

Example:
    To calculate all the eigenvalues of the general symmetric
    eigenproblem Ax = lamdaBx where A is the symmetric matrix
    .
    ..
    0.5 1.5 6.6 4.8
    1.5 6.5 16.2 8.6
    6.6 16.2 37.6 9.8
    4.8 8.6 9.8 -17.1
    .
    ..
    and B is the symmetric positive-de.nite matrix
    .
    ..
    1 3 4 1
    3 13 16 11
    4 16 24 18
    1 11 18 27
    .
    ..
    .

void test_nag_real_symm_general_eigenvalues()
{
    int i, j, n;
    matrix a, b;
    a.SetSize(8,8);
    b.SetSize(8,8);
    double r[8];
    n = 4;
    a[0][0] = 0.5;
    a[0][1] = 1.5;
    a[0][2] = 6.6;
    a[0][3] = 4.8;

    a[1][0] = 1.5;
    a[1][1] = 6.5;
    a[1][2] = 16.2;
    a[1][3] = 8.6;

    a[2][0] = 6.6;
    a[2][1] = 16.2;
    a[2][2] = 37.6;
    a[2][3] = 9.8;

    a[3][0] = 4.8;
    a[3][1] = 8.6;
    a[3][2] = 9.8;
    a[3][3] = -17.1;

    b[0][0] = 1.0;
    b[0][1] = 3.0;
    b[0][2] = 4.0;
    b[0][3] = 1.0;

    b[1][0] = 3.0;
    b[1][1] = 13.0;
    b[1][2] = 16.0;
    b[1][3] = 11.0;

    b[2][0] = 4.0;
    b[2][1] = 16.0;
    b[2][2] = 24.0;
    b[2][3] = 18.0;

    b[3][0] = 1.0;
    b[3][1] = 11.0;
    b[3][2] = 18.0;
    b[3][3] = 27.0;

    nag_real_symm_general_eigenvalues(n, a, 8, b, 8, r);
    printf("Eigenvalues\n");
    for (i=0; i<n; i++)
    {
        printf("%9.4f",r[i]);
        if(i%8==7 || i==n-1)
            printf("\n");
    }
}

    The output is following:

    Eigenvalues

    -3.0000 -1.0000 2.0000 4.0000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_symm_general_eigensystem

Function: nag_real_symm_general_eigensystem
Prototype:
int nag_real_symm_general_eigensystem(int n,double a[],int tda,double b[],int tdb,double r[],double v[],int tdv)
Remarks: calculates all the eigenvalues and eigenvectors of Ax = lamdaBx, where A is a real symmetric matrix and B is a real symmetric positive-definite matrix.
Parameters:
n
  the order of the matrices A and B.
a[]
  Input: the upper triangle of the n by n symmetric matrix A. The elements of the array below the diagonal need not be set.  Output: the lower triangle of the array is overwritten. The rest of the array is unchanged.
tda
  the second dimension of the array a as declared in the function from which nag real symm general eigensystem is called.
b[]
  Input: the upper triangle of the n by n symmetric positive-de.nite matrix B. The elements of the array below the diagonal need not be set.  Output: the elements below the diagonal are overwritten. The rest of the array is unchanged.
tdb
  the second dimension of the array b as declared in the function from which nag real symm general eigensystem is called.
r[]
  the eigenvalues in ascending order.
v[]
  the normalised eigenvectors, stored by columns; the ith column corresponds to the ith eigenvalue. The eigenvectors x are normalised so that xTBx = 1.
tdv
  the second dimension of the array v as declared in the function from which nag real symm general eigensystem is called.

Return values:
This function returns NAG error code, 0 if no error.
358:  The matrix B is not positive-de.nite, possibly due to rounding errors.
362: More than _value_ iterations are required to isolate all the eigenvalues.
11: On entry, n must not be less than 1: n = _value_.
17: On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.  On entry, tdb = _value_ while n = _value_. These parameters must satisfy tdb = n.  On entry, tdv = _value_ while n = _value_. These parameters must satisfy tdv = n.
73: Memory allocation failed.
successfully call of the nag_real_symm_general_eigensystem function.

Example:
    To calculate all the eigenvalues and eigenvectors of the general
    symmetric eigenproblem Ax = lamdaBx where A is the symmetric matrix
    .
    ..
    0.5 1.5 6.6 4.8
    1.5 6.5 16.2 8.6
    6.6 16.2 37.6 9.8
    4.8 8.6 9.8 -17.1
    .
    ..
    and B is the symmetric positive-de.nite matrix
    .
    ..
    1 3 4 1
    3 13 16 11
    4 16 24 18
    1 11 18 27
    .
    ..
    .

void test_nag_real_symm_general_eigensystem()
{
    int i, j, n;
    matrix a, b, v;
    a.SetSize(8,8);
    b.SetSize(8,8);
    v.SetSize(8,8);
    double  r[8];
    n = 4;
    a[0][0] = 0.5;
    a[0][1] = 1.5;
    a[0][2] = 6.6;
    a[0][3] = 4.8;

    a[1][0] = 1.5;
    a[1][1] = 6.5;
    a[1][2] = 16.2;
    a[1][3] = 8.6;

    a[2][0] = 6.6;
    a[2][1] = 16.2;
    a[2][2] = 37.6;
    a[2][3] = 9.8;

    a[3][0] = 4.8;
    a[3][1] = 8.6;
    a[3][2] = 9.8;
    a[3][3] = -17.1;

    b[0][0] = 1.0;
    b[0][1] = 3.0;
    b[0][2] = 4.0;
    b[0][3] = 1.0;

    b[1][0] = 3.0;
    b[1][1] = 13.0;
    b[1][2] = 16.0;
    b[1][3] = 11.0;

    b[2][0] = 4.0;
    b[2][1] = 16.0;
    b[2][2] = 24.0;
    b[2][3] = 18.0;

    b[3][0] = 1.0;
    b[3][1] = 11.0;
    b[3][2] = 18.0;
    b[3][3] = 27.0;
    nag_real_symm_general_eigensystem(n, a, 8, b, 8, r, v, 8);
    printf("Eigenvalues\n");
    for (i=0; i<n; i++)
    {
        printf("%9.4f",r[i]);
        if(i%8==7 || i==n-1)
            printf("\n");
    }
    printf("Eigenvectors\n");
    for (i=0; i<n; i++)
    {
        for (j=0; j<n; j++)
        {
            printf("%9.4f",v[i][j]);
            if(j%8==7 || j==n-1)
                printf("\n");
        }
    }
}

    The output is following:

    Eigenvalues

    -3.0000 -1.0000 2.0000 4.0000

    Eigenvectors

    -4.3500 -2.0500 -3.9500  2.6500
     0.0500  0.1500  0.8500  0.0500
     1.0000  0.5000  0.5000 -1.0000
    -0.5000 -0.5000 -0.5000  0.5000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_eigenvalues

Function: nag_real_eigenvalues
Prototype:
int nag_real_eigenvalues(int n,double a[],int tda,complex r[],int iter[])
Remarks: calculates all the eigenvalues of a real unsymmetric matrix.
Parameters:
n
  the order of the matrix A.
a[]
  Input: the n by n matrix A.  Output: the array is overwritten.
tda
  the second dimension of the array a as declared in the function from which nag real eigenvalues is called.
r[]
  the eigenvalues.
iter[]
  contains the number of iterations used to find the ith eigenvalue. If iter[i - 1] is negative, the ith eigenvalue is the second of a pair found simultaneously.

Return values:
This function returns NAG error code, 0 if no error.
362: More than _value_ iterations are required to isolate all the eigenvalues.
11: On entry, n must not be less than 1: n = _value_.
17: On entry, tda = _value_ while n = value. These parameters must satisfy tda = n.
73: Memory allocation failed.
successfully call of the nag_real_eigenvalues function.

Example:

    To calculate all the eigenvalues of the real matrix.
    .
    ..
    1.5 0.1 4.5 -1.5
    -22.5 3.5 12.5 -2.5
    -2.5 0.3 4.5 -2.5
    -2.5 0.1 4.5 2.5
    .
    ..
    .

void test_nag_real_eigenvalues()
{
    int i, j, n;
    matrix a;
    a.SetSize(4,4);
    matrix<complex> r;
    r.SetSize(1,4);
    int iter[4];
    n = 4;
    a[0][0] = 1.5;
    a[0][1] = 0.1;
    a[0][2] = 4.5;
    a[0][3] = -1.5;

    a[1][0] = -22.5;
    a[1][1] = 3.5;
    a[1][2] = 12.5;
    a[1][3] = -2.5;

    a[2][0] = -2.5;
    a[2][1] = 0.3;
    a[2][2] = 4.5;
    a[2][3] = -2.5;

    a[3][0] = -2.5;
    a[3][1] = 0.1;
    a[3][2] = 4.5;
    a[3][3] = 2.5;
    nag_real_eigenvalues(n, a, 4, r, iter);
    printf("Eigenvalues\n");
    for (i=0; i<n; i++)
    {
        complex temp =  r[0][i];
        printf("( %7.3f , %7.3f ) \n", temp.m_re, temp.m_im);
    }
}

    The output is following:

    Eigenvalues

    ( 3.000 ,  4.000 )
    ( 3.000 , -4.000 )
    ( 4.000 ,  0.000 )
    ( 2.000 ,  0.000 )

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_eigensystem

Function: nag_real_eigensystem
Prototype:
int nag_real_eigensystem(int n,double a[],int tda,complex r[],complex v[],int tdv,int iter[])
Remarks: calculates all the eigenvalues and eigenvectors of a real unsymmetric matrix.
Parameters:
n
  the order of the matrix A.
a[]
  Input: the n by n matrix A.  Output: the array is overwritten.
tda
  the second dimension of the array a as declared in the function from which nag real eigensystem is called.
r[]
  the eigenvalues.
v[]
  the eigenvectors, stored by columns. The ith column corresponds to the ith eigenvalue. The eigenvectors are normalised so that the sum of the squares of the moduli of the elements is equal to 1an d the element of largest modulus is real. This ensures that real eigenvalues have real eigenvectors.
tdv
  the second dimension of the array v as declared in the function from which nag real eigensystem is called.
iter[]
  contains the number of iterations used to find the ith eigenvalue. If iter[i - 1] is negative, the ith eigenvalue is the second of a pair found simultaneously.

Return values:
This function returns NAG error code, 0 if no error.
362: More than _value_ iterations are required to isolate all the eigenvalues.
11: On entry, n must not be less than 1: n = _value_.
17: On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.  On entry, tdv = _value_ while n = _value_. These parameters must satisfy tdv = n.
73: Memory allocation failed.
successfully call of the nag_real_eigensystem function.

Example:
    To calculate all the eigenvalues and eigenvectors of the real matrix.
    .
    ..
    1.5 0.1 4.5 -1.5
    -22.5 3.5 1 2 .5 -2.5
    -2.5 0.3 4.5 -2.5
    -2.5 0.1 4.5 2.5
    .
    ..
    .

void test_nag_real_eigensystem()
{

    int i, j, n;
    matrix a;
    a.SetSize(4,4);
    matrix<complex>r, v;
    r.SetSize(1,4);
    v.SetSize(4,4);
    int iter[4];

    a[0][0] = 1.5;
    a[0][1] = 0.1;
    a[0][2] = 4.5;
    a[0][3] = -1.5;

    a[1][0] = -22.5;
    a[1][1] = 3.5;
    a[1][2] = 12.5;
    a[1][3] = -2.5;

    a[2][0] = -2.5;
    a[2][1] = 0.3;
    a[2][2] = 4.5;
    a[2][3] = -2.5;

    a[3][0] = -2.5;
    a[3][1] = 0.1;
    a[3][2] = 4.5;
    a[3][3] = 2.5;
    n = 4;
    nag_real_eigensystem(n, a, 4, r, v, 4, iter);
    printf("Eigenvalues\n");
    for (i=0; i<n; i++)
    {
        complex temp = r[0][i];
        printf("(%7.3f, %7.3f) \n", temp.m_re, temp.m_im);

    }
    printf("\nEigenvectors\n");
    for (i=0; i<n; i++)
        for (j=0; j<n; j++)
        {
            complex temp = v[i][j];
            printf("(%7.3f, %7.3f)", temp.m_re, temp.m_im);
            if(j%4==3 || j==n-1)
                printf("\n");
        }

}

    The output is following:

    Eigenvalues

    ( 3.000,  4.000)
    ( 3.000, -4.000)
    ( 4.000,  0.000)
    ( 2.000,  0.000)

    Eigenvectors

    ( 0.113, -0.151) ( 0.113, 0.151) ( -0.033, 0.000) ( 0.063, 0.000)
    ( 0.945,  0.000) ( 0.945, 0.000) (  0.988, 0.000) ( 0.996, 0.000)
    ( 0.189,  0.000) ( 0.189, 0.000) (  0.011, 0.000) ( 0.006, 0.000)
    ( 0.113, -0.151) ( 0.113, 0.151) (  0.154, 0.000) ( 0.063, 0.000)

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_hermitian_eigenvalues

Function: nag_hermitian_eigenvalues
Prototype:
int nag_hermitian_eigenvalues(int n,complex a[],int tda,double r[])
Remarks: calculates all the eigenvalues of a complex Hermitian matrix.
Parameters:
n
  the order of the matrix A.
a[]
  Input: the elements of the lower triangle of the n by n complex Hermitian matrix A. Elements of the array above the diagonal need not be set.  Output: the array is overwritten.
tda
  the last dimension of the array a as declared in the function from which nag hermitian eigenvalues is called.
r[]
  the eigenvalues in ascending order.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 1: n = _value_.
17: On entry tda = _value_ while n = _value_. These parameters must satisfy tda = n.
73: Memory allocation failed.
362: More than _value_ iterations are required to isolate all the eigenvalues.
successfully call of the nag_hermitian_eigenvalues function.

Example:
    To calculate all the eigenvalues of the complex Hermitian matrix:
    .
    ..
    0.50 0.00 1.84 + 1.38i 2.08 - 1.56i
    0.00 0.50 1.1 2 +0.84i -0.56 + 0.42i
    1.84 - 1.38i 1.12 - 0.84i 0.50 0.00
    2.08 + 1.56i -0.56 - 0.42i 0.00 0.50
    .
    ..
    .

void test_nag_hermitian_eigenvalues()
{
    int i, j, n;
    matrix<complex>a;
    a.SetSize(4,4);
    double r[4];
    n = 4;

    a[0][0] = 0.50 + 0.00i;
    a[0][1] =  0.00 + 0.00i;
    a[0][2] = 1.84 + 1.38i;
    a[0][3] = 2.08 - 1.56i;

    a[1][0] = 0.00 + 0.00i;
    a[1][1] = 0.50 + 0.00i;
    a[1][2] = 1.12 + 0.84i;
    a[1][3] = -0.56 + 0.42i;

    a[2][0] = 1.84 - 1.38i;
    a[2][1] = 1.12 - 0.84i;
    a[2][2] = 0.50 + 0.00i;
    a[2][3] = 0.00 + 0.00i;

    a[3][0] = 2.08 + 1.56i;
    a[3][1] = -0.56 - 0.42i;
    a[3][2] = 0.00 + 0.00i;
    a[3][3] = 0.50 + 0.00i;

    nag_hermitian_eigenvalues(n, a, 4, r);
    printf("Eigenvalues\n");
    for (i=0; i<n; i++)
        printf("%9.4f", r[i]);
    printf("\n");
}

    The output is following:

    Eigenvalues

    -3.0000 -1.0000 2.0000 4.0000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_hermitian_eigensystem

Function: nag_hermitian_eigensystem
Prototype:
int nag_hermitian_eigensystem(int n,complex a[],int tda,double r[],complex v[],int tdv)
Remarks: calculates all the eigenvalues and eigenvectors of a complex Hermitian matrix.
Parameters:
n
  the order of the matrix A.
a[]
  the elements of the lower triangle of the n by n complex Hermitian matrix A. Elements of the array above the diagonal need not be set.
tda
  the last dimension of the array a as declared in the function from which nag hermitian eigensystem is called.
r[]
  the eigenvalues in ascending order.
v[]
  the eigenvectors, stored by columns. The ith column corresponds to the ith eigenvector. The eigenvectors are normalised so that the sum of the squares of the moduli of the elements is equal to 1an d the element of largest modulus is real.
tdv
  the last dimension of the array v as declared in the function from which nag hermitian eigensystem is called.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 1: n = _value_.
17: On entry tda = _value_ while n = _value_. These parameters must satisfy tda = n.  On entry tdv = _value_ while n = _value_. These parameters must satisfy tdv = n.
73: Memory allocation failed.
successfully call of the nag_hermitian_eigensystem function.

Example:
    To calculate the eigenvalues and eigenvectors of the complex Hermitian matrix:
    .
    ..
    0.50 0.00 1.84 + 1.38i 2.08 - 1.56i
    0.00 0.50 1.1 2 +0.84i -0.56 + 0.42i
    1.84 - 1.38i 1.12 - 0.84i 0.50 0.00
    2.08 + 1.56i -0.56 - 0.42i 0.00 0.50
    .
    ..
    .

void test_nag_hermitian_eigensystem()
{
    int i, j, n;
    matrix<complex> a, v;
    a.SetSize(4,4);
    v.SetSize(4,4);
    double r[4];
    n = 4;

    a[0][0] = 0.50 + 0.00i;
    a[0][1] =  0.00 + 0.00i;
    a[0][2] = 1.84 + 1.38i;
    a[0][3] = 2.08 - 1.56i;

    a[1][0] = 0.00 + 0.00i;
    a[1][1] = 0.50 + 0.00i;
    a[1][2] = 1.12 + 0.84i;
    a[1][3] = -0.56 + 0.42i;

    a[2][0] = 1.84 - 1.38i;
    a[2][1] = 1.12 - 0.84i;
    a[2][2] = 0.50 + 0.00i;
    a[2][3] = 0.00 + 0.00i;

    a[3][0] = 2.08 + 1.56i;
    a[3][1] = -0.56 - 0.42i;
    a[3][2] = 0.00 + 0.00i;
    a[3][3] = 0.50 + 0.00i;
    nag_hermitian_eigensystem(n, a, 4, r, v, 4);
    printf("Eigenvalues\n");
    for (i=0; i<n; i++)
        printf("%9.4f", r[i]);
    printf("\nEigenvectors\n");
    for (i=0; i<n; i++)
        for (j=0; j<n; j++)
        {
            complex temp = v[i][j];
            printf("(%7.3f %7.3f )",temp.m_re, temp.m_im);
            if(j%4==3 || j==n-1)
                printf("\n");
        }
}

    The output is following:

    Eigenvalues

    -3.0000 -1.0000 2.0000 4.0000

    Eigenvectors

    (  0.700  0.000 ) ( -0.100 0.000 ) ( -0.100  0.000 ) ( 0.700  0.000 )
    (  0.100  0.000 ) (  0.700 0.000 ) (  0.700  0.000 ) ( 0.100  0.000 )
    ( -0.400  0.300 ) ( -0.400 0.300 ) (  0.400 -0.300 ) ( 0.400 -0.300 )
    ( -0.400 -0.300 ) (  0.400 0.300 ) ( -0.400 -0.300 ) ( 0.400  0.300 )

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_general_eigensystem

Function: nag_real_general_eigensystem
Prototype:
int nag_real_general_eigensystem(int n,double a[],int tda,double b[],int tdb,double tol,complex alfa[],double beta[],bool wantv,double v[],int tdv,int iter[])
Remarks: calculates all the eigenvalues and, if required, all the eigenvectors of the generalized eigenproblem Ax = lamdaBx where A and B are real, square matrices, using the QZ algorithm.
Parameters:
n
  the order of the matrices A and B.
a[]
  Input: the n by n matrix A.  Output: the array is overwritten.
tda
  the second dimension of the array a as declared in the function from which nag real general eigensystem is called.
b[]
  Input: the n by n matrix B.  Output: the array is overwritten.
tdb
  the second dimension of the array b as declared in the function from which nag real general eigensystem is called.
tol
  the tolerance used to determine negligible elements. If tol > 0.0, an element will be considered negligible if it is less than tol times the norm of its matrix. If tol = 0.0, machine precision is used in place of tol. A value of tol greater than machine precision may result in faster execution but less accurate results.
alfa[]
  Output: alpha_j, for j = 1, 2, . . . , n.
beta[]
  Output: beta_j, for j = 1, 2, . . . , n.
wantv
  wantv must be set to TRUE if the eigenvectors are required. If wantv is set to FALSE then the array v is not referenced.
v[]
  Output: if wantv = TRUE, then (i) if the jth eigenvalue is real, the jth column of v contains its eigenvector; (ii) if the jth and (j + 1)th eigenvalues form a complex pair, the jth and (j + 1)th columns of v contain the real and imaginary parts of the eigenvector associated with the first eigenvalue of the pair. The conjugate of this vector is the eigenvector for the conjugate eigenvalue.  Each eigenvector is normalised so that the component of largest modulus is real and the sum of squares of the moduli equal one.  If wantv = FALSE, v is not referenced and may be set to the null pointer
tdv
  the second dimension of the array v as declared in the function from which nag real general eigensystem is called.
iter[]
  contains the number of iterations needed to obtain the jth eigenvalue.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 1: n = _value_.
17: On entry tda = _value_ while n = _value_. These parameters must satisfy tda = n.  On entry tdb = _value_ while n = _value_. These parameters must satisfy tdb = n.  On entry tdv = _value_ while n = _value_. These parameters must satisfy tdv = n.
374: More than n × 30 iterations are required to determine all the diagonal 1 by 1 or 2 by 2 blocks of the quasi-triangular form in the second step of the QZ algorithm. This failure occurs at the ith eigenvalue, i = _value_. aj and ßj are correct for j = i+1, i+2, . . ., n but v does not contain any correct eigenvectors.  The value of i will be returned in member errnum of the NAG error structure provided NAGERR DEFAULT is not used as the error parameter.
successfully call of the nag_real_general_eigensystem function.

Example:
    To find all the eigenvalues and eigenvectors of Ax = ?Bx where
    A =
    .
    ..
    3.9 4.3 4.3 4.4
    12.5 21.5 21.5 26.0
    -34.5 -47.5 -43.5 -46.0
    -0.5 7.5 3.5 6.0
    .
    ..
    and
    B =
    .
    ..
    1 1 1 1
    2 3 3 3
    -3 -5 -4 -4
    1 4 3 4
    .
    ..
    .

void test_nag_real_general_eigensystem()
{
    int i, j, k, n, ip, iter[8];
    matrix<complex> alfa;
    alfa.SetSize(1,8);
    double beta[8], eps1;
    matrix a, b, z;
    a.SetSize(8,8);
    b.SetSize(8,8);
    z.SetSize(8,8);
    BOOL matz;
    n = 4;

    a[0][0] = 3.9;
    a[0][1] = 12.5;
    a[0][2] = -34.5;
    a[0][3] = -0.5;

    a[1][0] = 4.3;
    a[1][1] = 21.5;
    a[1][2] = -47.5;
    a[1][3] = 7.5;

    a[2][0] = 4.3;
    a[2][1] = 21.5;
    a[2][2] = -43.5;
    a[2][3] = 3.5;

    a[3][0] = 4.4;
    a[3][1] = 26.0;
    a[3][2] = -46.0;
    a[3][3] = 6.0;

    b[0][0] = 1.0;
    b[0][1] = 2.0;
    b[0][2] = -3.0;
    b[0][3] = 1.0;

    b[1][0] = 1.0;
    b[1][1] = 3.0;
    b[1][2] = -5.0;
    b[1][3] = 4.0;

    b[2][0] = 1.0;
    b[2][1] = 3.0;
    b[2][2] = -4.0;
    b[2][3] = 3.0;

    b[3][0] = 1.0;
    b[3][1] = 3.0;
    b[3][2] = -4.0;
    b[3][3] = 4.0;

    matz = TRUE;
    eps1 = 1e-8;
    nag_real_general_eigensystem(n, a, 8, b, 8, eps1, alfa, beta, matz, z, 8, iter);
    ip = 0;
    for (i=0; i<n; ++i)
    {
        complex tmp = alfa[0][i];
        printf("Eigensolution %4ld\n",i+1);
        printf("alfa[%ld].re %7.3f",i,tmp.m_re);
        printf(" alfa[%ld].im %7.3f",i,tmp.m_im);
        printf(" beta[%ld] %7.3f\n",i,beta[i]);
        if (beta[i] == 0.0)
            printf("lambda is infinite");
        else if (tmp.m_im == 0.0)
        {
            printf("lambda %7.3f\n",tmp.m_re/beta[i]);
            printf("Eigenvector\n");
            for (j=0; j<n; ++j)
                printf("%7.3f\n", z[j][i]);
        }
        else
        {
            complex temp = alfa[0][i];
            printf("lambda %7.3f %7.3f\n",temp.m_re/beta[i], temp.m_im/beta[i] );
            printf("Eigenvector\n");
            k = pow(-1, ip+2);
            for (j=0; j<n; ++j)
            {
                printf("%7.3f",z[j][i-ip]);
                printf("%7.3f\n",k*z[j][i-ip+1]);
            }
            ip = 1-ip;
        }
    }
    printf("Number of iterations (machine-dependent)\n");
    for (i=0; i<n; ++i)
        printf("%2ld",iter[i]);
    printf("\n");
}

    The output is following:

    Eigensolution 1

    alfa[0].re 3.801 alfa[0].im 0.000 beta[0] 1.900

    lambda 2.000

    Eigenvector

    0.996
    0.006
    0.063
    0.063

    Eigensolution 2

    alfa[1].re 1.563 alfa[1].im 2.084 beta[1] 0.521

    lambda 3.000 4.000

    Eigenvector

    0.945 0.000
    0.189 0.000
    0.113 -0.151
    0.113 -0.151

    Eigensolution 3

    alfa[2].re 3.030 alfa[2].im -4.040 beta[2] 1.010

    lambda 3.000 -4.000

    Eigenvector

    0.945 0.000
    0.189 0.000
    0.113 0.151
    0.113 0.151

    Eigensolution 4

    alfa[3].re 4.000 alfa[3].im 0.000 beta[3] 1.000

    lambda 4.000

    Eigenvector

    0.988
    0.011
    -0.033
    0.154

    Number of iterations (machine-dependent)
    0 0 5 0

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_eigensystem_sel

Function: nag_real_eigensystem_sel
Prototype:
int nag_real_eigensystem_sel(Nag_Select_Eigenvalues crit,int n,double a[],int tda,double wl,double wu,int mest,int *m,complex w[],complex v[],int tdv)
Remarks: computes selected eigenvalues and eigenvectors of a real general matrix.
Parameters:
n
  the order of the matrix A.
a[]
  Input: the n by n general matrix A.  Output: a contains the Hessenberg form of the balanced input matrix A_
tda
  the last dimension of the array a as declared in the calling program.
wl
  the lower bound on the criterion for the selected eigenvalues.
wu
  the upper bound on the criterion for the selected eigenvalues.
mest
  an upper bound on m, the number of eigenvalues and eigenvectors selected. No eigenvectors are computed if mest < m.
m
  the number of eigenvalues actually selected
w[]
  the first m elements of w hold the values of the selected eigenvalues; elements from the index m to n-1 contain the other eigenvalues. Complex conjugate pairs of eigenvalues are stored in consecutive elements of the array, with the eigenvalue having the positive imaginary part first.
v[]
  the selected eigenvectors, with the ith column holding the eigenvector associated with the eigenvalue lamda.
tdv
  the second dimension of the array v as declared in the calling program.

Return values:
This function returns NAG error code, 0 if no error.
70: On entry, parameter crit had an illegal value.
11: On entry, n must not be less than 0: n = _value_.  On entry, mest must not be less than 1: mest = _value_.
91: On entry, tda = _value_ while n = _value_.  Constraint: tda = max(1,n).  On entry, tdv = _value_ while mest = _value_.  Constraint: tdv = max(1,mest).
24: On entry, wu = _value_ while wl = _value_.  These parameters must satisfy wu > wl.
378: The QR algorithm failed to compute all the eigenvalues. No eigenvectors have been computed.
379: There are more than mest eigenvalues in the speci.ed range. The actual number of eigenvalues in the range is returned in m. No eigenvectors have been computed.  Rerun with the second dimension of v = mest = m.
successfully call of the nag_real_eigensystem_sel function.

Example:
    To compute those eigenvalues of the matrix A whose moduli lie in
    the range [0.2,0.5], and their corresponding eigenvectors, where
    A =
    .
    ..
    0.35 0.45 -0.14 -0.17
    0.09 0.07 -0.54 0.35
    -0.44 -0.33 -0.03 0.17
    0.25 -0.32 -0.13 0.11
    .

void test_nag_real_eigensystem_sel()
{
    matrix a;
    a.SetSize(8,8);
    double wl, wu;
    int i, j, m, n;
    int mest = 3;

    matrix<complex>w, v;
    w.SetSize(1,8);
    v.SetSize(8,3);
    n = 4;
    wl = 0.2;
    wu = 0.5;
    a[0][0] =0.35;
    a[0][1] =0.45;
    a[0][2] =-0.14;
    a[0][3] = -0.17;

    a[1][0] =0.09;
    a[1][1] =0.07;
    a[1][2] = -0.54;
    a[1][3] =0.35;

    a[2][0] =-0.44;
    a[2][1] =-0.33;
    a[2][2] =-0.03;
    a[2][3] =0.17;

    a[3][0] =0.25;
    a[3][1] =-0.32;
    a[3][2] =-0.13;
    a[3][3] =0.11;

    nag_real_eigensystem_sel(Nag_Select_Modulus, n, a, 8, wl, wu, mest, &m, w,v, 3);
    printf("\n\nEigenvalues\n");
    for (i = 0; i < m; ++i)
    {
        complex temp;
        temp = w[0][i];
        printf("(%7.4f, %7.4f) ", temp.m_re, temp.m_im);
    }
    printf("\n");
    printf(" Eigenvectors\n ");
    for (i = 1; i <= m; i++)
    {
        printf("%15ld", i);
        if(i%m == 0 )
            printf("\n");
    }
    for (i = 0; i < n; i++)
    {
        printf("%ld ", i + 1);
        for (j = 0; j < m; j++)
        {
            complex temp;
            temp = v[i][j];
            printf("(%8.4f, %8.4f)", temp.m_re, temp.m_im);
            if((j + 1) % m == 0)
                printf("\n");
        }
    }
}

    The output is following:

    Eigenvalues

    (-0.0994, 0.4008) (-0.0994, -0.4008)

    Eigenvectors

            1 					2

    1 ( -0.1933,  0.2546) ( -0.1933, -0.2546)
    2 (  0.2519, -0.5224) (  0.2519,  0.5224)
    3 (  0.0972, -0.3084) (  0.0972,  0.3084)
    4 (  0.6760,  0.0000) (  0.6760,  0.0000)

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_complex_eigensystem_sel

Function: nag_complex_eigensystem_sel
Prototype:
int nag_complex_eigensystem_sel(Nag_Select_Eigenvalues crit,int n,complex a[],int tda,double wl,double wu,int mest,int *m,complex w[],complex v[],int tdv)
Remarks: computes selected eigenvalues and eigenvectors of a complex general matrix.
Parameters:
n
  the order of the matrix A.
a[]
  Input: the n by n general matrix A.  Output: a contains the Hessenberg form of the balanced input matrix A
tda
  the last dimension of the array a as declared in the calling program.
wl
  the lower bound on the criterion for the selected eigenvalues.
wu
  the upper bound on the criterion for the selected eigenvalues.
mest
  an upper bound on m, the number of eigenvalues and eigenvectors selected. No eigenvectors are computed if mest < m.
m
  the number of eigenvalues actually selected.
w[]
  the first m elements of w hold the selected eigenvalues; elements from the index m to n-1 contain the other eigenvalues.
v[]
  the selected eigenvectors, with the ith column holding the eigenvector associated with the eigenvalue lamda.
tdv
  the second dimension of the array v as declared in the calling program.

Return values:
This function returns NAG error code, 0 if no error.
70: On entry, parameter crit had an illegal value.
11: On entry, n must not be less than 0: n = _value_.  On entry, mest must not be less than 1: mest = _value_.
91: On entry, tda = _value_ while n = _value_. Constraint: tda = max (1,n).
24: On entry, wu = _value_ while wl = _value_.  These parameters must satisfy wu > wl.
17: On entry, tdv = _value_ while mest = _value_.  These parameters must satisfy tdv = mest.
378: The QR algorithm failed to compute all the eigenvalues. No eigenvectors have been computed.
379: There are more than mest eigenvalues in the speci.ed range. The actual number of eigenvalues in the range is returned in m. No eigenvectors have been computed.  Rerun with the second dimension of v = mest = m.
380: Inverse iteration failed to compute all the specified eigenvectors. If an eigenvector failed to converge, the corresponding column of v is set to zero.
successfully call of the nag_complex_eigensystem_sel function.

Example:
    To compute those eigenvalues of the matrix A whose moduli lie
    in the range [-5.5,+5.5], and their corresponding eigenvectors, where
    A =
    .
    ..
    -3.97 - 5.04i -4.11 + 3.70i -0.34 + 1.01i 1.29 - 0.86i
    0.34 - 1.50i 1.52 - 0.43i 1.88 - 5.38i 3.36 + 0.65i
    3.31 - 3.85i 2.50 + 3.45i 0.88 - 1.08i 0.64 - 1.48i
    -1.10 + 0.82i 1.81 - 1.59i 3.25 + 1.33i 1.57 - 3.44i
    .
    ..

void test_nag_complex_eigensystem_sel()
{
    double wl,wu;
    int mest = 3;
    int i,j,m, n;
    matrix<complex> a, v, w;
    a.SetSize(8,8);
    v.SetSize(8,3);
    w.SetSize(1,8);
    n = 4;
    wl = -5.5;
    wu = 5.5;

    a[0][0] = -3.97 - 5.04i;
    a[0][1] = -4.11 + 3.70i;
    a[0][2] = -0.34 + 1.01i;
    a[0][3] = 1.29 - 0.86i;

    a[1][0] = 0.34 - 1.50i;
    a[1][1] = 1.52 - 0.43i;
    a[1][2] = 1.88 - 5.38i;
    a[1][3] = 3.36 + 0.65i;

    a[2][0] = 3.31 - 3.85i;
    a[2][1] = 2.50 + 3.45i;
    a[2][2] = 0.88 - 1.08i;
    a[2][3] = 0.64 - 1.48i;

    a[3][0] = -1.10 + 0.82i;
    a[3][1] = 1.81 - 1.59i;
    a[3][2] = 3.25 + 1.33i;
    a[3][3] = 1.57 - 3.44i;

    nag_complex_eigensystem_sel(Nag_Select_Modulus, n, a, 8, wl, wu, mest, &m, w, v,3);
    printf("\n\nEigenvalues\n\n");
    for (i = 0; i < m; ++i)
    {
        complex temp = w[0][i];
        printf("(%7.4f,%7.4f)\t", temp.m_re, temp.m_im);
        if((i+1)%2 == 0)
            printf("\n");
    }
    printf("\nEigenvectors\n");
    for (i=1; i<=m; i++)
    {
        printf("%15ld",i);
        if(i%m == 0)
            printf("\n");
    }
    for (i = 0; i < n; i++)
    {
        printf("% ld ",i + 1);
        for (j = 0; j < m; j++)
        {
            complex temp = v[i][j];
            printf("(%8.4f,%8.4f)", temp.m_re, temp.m_im);
            if((j + 1)%m == 0)
                printf("\n");
        }
    }
}

    The output is following:

    Eigenvalues

    (-5.0000,2.0060) ( 3.0023, -3.9998)

    Eigenvectors

                1 			2

    1 ( -0.3865, 0.1732) ( -0.0356, -0.1782)
    2 ( -0.3539, 0.4529) (  0.1264,  0.2666)
    3 (  0.6124, 0.0000) (  0.0129, -0.2966)
    4 ( -0.0859,-0.3284) (  0.8898,  0.0000)

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_svd

Function: nag_real_svd
Prototype:
int nag_real_svd(int m,int n,double a[],int tda,int ncolb,double b[],int tdb,bool wantq,double q[],int tdq,double sv[],bool wantp,double pt[],int tdpt,int *iter,double e[],int *failinfo)
Remarks: returns all, or part, of the singular value decomposition of a general real matrix.
Parameters:
m
  the number of rows, m, of the matrix A.
n
  the number of columns, n, of the matrix A.
a[]
  Input: the leading m by n part of the array a must contain the matrix A whose singular value decomposition is required.  Output: if m = n and wantq = TRUE, then the leading m by n part of a will contain the first n columns of the orthogonal matrix Q.  If m < n and wantp = TRUE, then the leading m by n part of a will contain the .rst m rows of the orthogonal matrix PT .  If m = n and wantq = FALSE and wantp = TRUE, then the leading n by n part of a will contain the first n rows of the orthogonal matrix PT .  Otherwise the contents of the leading m by n part of a are indeterminate.
tda
  the second dimension of the array a as declared in the function from which nag real svd is called.
ncolb
  the number of columns of the matrix B. When ncolb = 0 the array b is not referenced.
b[]
  Input: if ncolb > 0, the leading m by ncolb part of the array b must contain the matrix to be transformed. If ncolb = 0 the array b is not referenced and may be set to the null pointer, i.e., (double *)0.  Output: b is overwritten by the m by ncolb matrix QTB.
tdb
  the second dimension of the array b as declared in the function from which nag real svd is called.
wantq
  wantq must be TRUE, if the left-hand singular vectors are required. If wantq = FALSE, then the array q is not referenced.
q[]
  if m < n and wantq = TRUE, the leading m by m part of the array q will contain the orthogonal matrix Q. Otherwise the array q is not referenced and may be set to the null pointer, i.e., (double *)0.
tdq
  the second dimension of the array q as declared in the function from which nag real svd is called.
sv[]
  the min(m,n) diagonal elements of the matrix S.
wantp
  wantp must be TRUE if the right-hand singular vectors are required. If wantp = FALSE, then the array pt is not referenced.
pt[]
  if m = n and wantq and wantp are TRUE, the leading n by n part of the array pt will contain the orthogonal matrix PT . Otherwise the array pt is not referenced and may be set to the null pointer, i.e., (double *)0.
tdpt
  the second dimension of the array pt as declared in the function from which nag real svd is called.
iter
  the total number of iterations taken by the QR algorithm.
e[]
  if the error NE QR NOT CONV occurs the array e contains the super diagonal elements of matrix E in the factorisation of A according to A = QEPT . See Section 5 for further details.
failinfo
  if the error NE QR NOT CONV occurs failinfo contains the number of singular values which may not have been found correctly. See Section 5 for details.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, m must not be less than 0: m = _value_.  On entry, n must not be less than 0: n = _value_.  On entry, ncolb must not be less than 0: ncolb = _value_.
17: On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n. On entry, tdb = _value_ while ncolb = _value_. These parameters must satisfy tdb = ncolb.
363: On entry, tdq = _value_ while m = _value_. Whenwantq is TRUE and m < n then relationship tdq = m must be satis.ed.
364: On entry, tdpt = _value_ while n = _value_. When wantq and wantp are TRUE and m = n then relationship tdpt = n must be satis.ed.
366: The QR algorithm has failed to converge in _value_ iterations. Singular values 1,2,. . .,failinfo may not have been found correctly and the remaining singular values may not be the smallest.  The matrix A will nevertheless have been factorized as A = QEPT , where the leading min(m, n) by min(m, n) part of E is a bidiagonal matrix with sv[0], sv[1], . . ., sv[min(m,n-1)] as the diagonal elements and e[0], e[1], . . ., e[min(m,n-2)] as the superdiagonal elements.  This failure is not likely to occur.
73: Memory allocation failed.
successfully call of the nag_real_svd function.

Example:
    To find the singular value decomposition of the 5 by 3 matrix
    A =
    .
    ....
    2.0 2.5 2.5
    2.0 2.5 2.5
    1.6 -0.4 2.8
    2.0 -0.5 0.5
    1.2 -0.3 -2.9
    .
    ....
    together with the vector QT b for the vector
    b =
    .
    ....
    1.1
    0.9
    0.6
    0.0
    -0.8
    .
    ....
    .

void test_nag_real_svd()
{
    int tda = 10;
    int tdpt = 10;
    matrix a;
    double b[20],e[9];
    a.SetSize(20,10);

    matrix pt;
    pt.SetSize(10,10);
    double sv[10], dummy[1];
    int i, j, m, n, iter, failinfo;
    BOOL wantp, wantq;
    m = 5;
    n = 3;
    a[0][0] = 2.0;
    a[0][1] = 2.5;
    a[0][2] = 2.5;

    a[1][0] = 2.0;
    a[1][1] = 2.5;
    a[1][2] = 2.5;

    a[2][0] = 1.6;
    a[2][1] = -0.4;
    a[2][2] = 2.8;

    a[3][0] = 2.0;
    a[3][1] = -0.5;
    a[3][2] = 0.5;

    a[4][0] = 1.2;
    a[4][1] = -0.3;
    a[4][2] = -2.9;

    b[0] = 1.1;
    b[1] = 0.9;
    b[2] = 0.6;
    b[3] = 0.0;
    b[4] = -0.8;

    wantq = TRUE;
    wantp = TRUE;
    nag_real_svd(m, n, a, tda, 1, b, 1, wantq, dummy, 1, sv, wantp, pt, tdpt, &iter, e, &failinfo);

    printf("Singular value decomposition of A\n\n");
    printf("Singular values\n");
    for (i = 0; i < n; ++i)
        printf(" %8.4f", sv[i]);
    printf("\n\n");
    printf("Left-hand singular vectors, by column\n");
    for (i = 0; i < m; ++i)
    {
        for (j = 0; j < n; ++j)
            printf(" %8.4f", a[i][j]);
        printf("\n");
    }
    printf("\n");
    printf("Right-hand singular vectors, by column\n");
    for (i = 0; i < n; ++i)
    {
        for (j = 0; j < n; ++j)
            printf(" %8.4f", pt[j][i]);
        printf("\n");
    }
    printf("\n");
    printf("Vector Q'*B\n");
    for (i = 0; i < m; ++i)
        printf(" %8.4f", b[i]);
    printf("\n\n");
}

    The output is following:

    Example 2
    Singular value decomposition of A

    Singular values
    6.5616   3.0000   2.4384

    Left-hand singular vectors, by column
       0.6011  -0.1961  -0.3165
       0.6011  -0.1961  -0.3165
       0.4166   0.1569   0.6941
       0.1688  -0.3922   0.5636
      -0.2742  -0.8629   0.0139

    Right-hand singular vectors, by column
       0.4694  -0.7845   0.4054
       0.4324  -0.1961  -0.8801
       0.7699   0.5883   0.2471

    Vector Q'*B
       1.6716   0.3922  -0.2276  -0.1000  -0.1000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_complex_svd

Function: nag_complex_svd
Prototype:
int nag_complex_svd(int m,int n,complex a[],int tda,int ncolb,complex b[],int tdb,bool wantq,complex q[],int tdq,double sv[],bool wantp,complex ph[],int tdph,int *iter,double e[],int *failinfo)
Remarks: returns all, or part, of the singular value decomposition of a general complex matrix.
Parameters:
m
  the number of rows, m, of the matrix A.
n
  the number of columns, n, of the matrix A.
a[]
  Input: the leading m by n part of the array a must contain the matrix A whose singular value decomposition is required.  Output: if m = n and wantq = TRUE, then the leading m by n part of a will contain the first n columns of the unitary matrix Q.  If m < n and wantp = TRUE, then the leading m by n part of a will contain the .rst m rows of the unitary matrix PH.  If m = n and wantq = FALSE and wantp = TRUE, then the leading n by n part of a will contain the .rst n rows of the unitary matrix PH.  Otherwise the contents of the leading m by n part of a are indeterminate.
tda
  the second dimension of the array a as declared in the function from which nag complex svd is called.
ncolb
  the number of columns of the matrix B. When ncolb = 0 the array b is not referenced.
b[]
  Input: if ncolb > 0, the leading m by ncolb part of the array b must contain the matrix to be transformed. If ncolb = 0 the array b is not referenced and may be set to the null pointer, i.e., (Complex *)0.  Output: b is overwritten by the m by ncolb matrix QHB.
tdb
  the second dimension of the array b as declared in the function from which nag complex svd is called.
wantq
  Input: wantq must be TRUE if the left-hand singular vectors are required. If wantq = FALSE then the array q is not referenced.
q[]
  Output: if m < n and wantq = TRUE, the leading m by m part of the array q will contain the unitary matrix Q. Otherwise the array q is not referenced and may be set to the null pointer, i.e., (Complex *)0.
tdq
  the second dimension of the array q as declared in the function from which nag complex svd is called.
sv[]
  the min(m,n) diagonal elements of the matrix S.
wantp
  wantp must be TRUE if the right-hand singular vectors are required. If wantp = FALSE then the array ph is not referenced
ph[]
  if m = n and wantq and wantp are TRUE, the leading n by n part of the array ph will contain the unitary matrix PH. Otherwise the array ph is not referenced and may be set to the null pointer, i.e., (Complex *)0.
tdph
  the second dimension of the array ph as declared in the function from which nag complex svd is called.
iter
  the total number of iterations taken by the QR algorithm.
e[]
  if the error NE QR NOT CONV occurs the array e contains the super-diagonal elements of matrix E in the factorisation of A according to A = QEPH. See Section 5 for further details.
failinfo
  if the error NE QR NOT CONV occurs failinfo contains the number of singular values which may not have been found correctly. See Section 5 for details.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, m must not be less than 0: m = _value_.  On entry, n must not be less than 0: n = _value_.  On entry, ncolb must not be less than 0: ncolb = _value_.
17: On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.  On entry, tdb = _value_ while ncolb = _value_. These parameters must satisfy tdb = ncolb.
363: On entry, tdq = _value_ while m = _value_. Whenwantq is TRUE and m < n then relationship tdq = m must be satis.ed.
364: On entry, tdph = _value_ while n = _value_. When wantq and wantp are TRUE and m = n then relationship tdph = n must be satis.ed.
366: The QR algorithm has failed to converge in _value_ iterations. Singular values 1, 2, . . . ,fail info may not have been found correctly and the remaining singular values may not be the smallest.  The matrix A will nevertheless have been factorized as A = QEPT , where the leading min(m, n) by min(m, n) part of E is a bidiagonal matrix with sv[0], sv[1], . . ., sv[min(m,n-1)] as the diagonal elements and e[0], e[1], . . ., e[min(m,n-2)] as the super-diagonal elements.  This failure is not likely to occur.
73: Memory allocation failed.
successfully call of the nag_complex_svd function.

Example:
    To find the singular value decomposition of the 5 by 3 matrix
    A =
    .
    ....
    0.5i -0.5 + 1.5i -1.0+ 1.0i
    0.4 + 0.3i 0.9 + 1.3i 0.2+ 1.4i
    0.4 -0.4 + 0.4i 1.8
    0.3 - 0.4i 0.1 + 0.7i 0.0
    -0.3i 0.3 + 0.3i 2.4i
    .
    ....
    together with the vector QHb for the vector
    b =
    .
    ....
    -0.55 + 1.05i
    0.49 + 0.93i
    0.56 - 0.16i
    0.39 + 0.23i
    1.13 + 0.83i
    .
    ....
    .

void test_nag_complex_svd()
{
    int tda = 10;
    int tdph = 10;
    matrix<complex>a, b, ph, dummy;
    a.SetSize(20,10);
    b.SetSize(1,20);
    ph.SetSize(10,10);
    dummy.SetSize(1,1);
    double e[9], sv[10];
    int i, j, m, n, iter, failinfo;
    BOOL wantp, wantq;
    m = 5;
    n = 3;

    a[0][0] =0.00 + 0.50i;
    a[0][1] = -0.50 + 1.50i;
    a[0][2] = -1.00 + 1.00i;

    a[1][0] =0.40 + 0.30i;
    a[1][1] = 0.90 + 1.30i;
    a[1][2] = 0.20 + 1.40i;

    a[2][0] =0.40 + 0.00i;
    a[2][1] = -0.40 + 0.40i;
    a[2][2] = 1.80 + 0.00i;

    a[3][0] =0.30 - 0.40i;
    a[3][1] = 0.10 + 0.70i;
    a[3][2] = 0.00 + 0.00i;

    a[4][0] = 0.00 - 0.30i;
    a[4][1] = 0.30 + 0.30i;
    a[4][2] = 0.00 + 2.40i;

    b[0][0] = -0.55 + 1.05i;
    b[0][1] = 0.49 + 0.93i;
    b[0][2] = 0.56 - 0.16i;
    b[0][3] = 0.39 + 0.23i;
    b[0][4] = 1.13 + 0.83i;

    wantq = TRUE;
    wantp = TRUE;
    nag_complex_svd(m, n, a, tda, 1, b, 1, wantq, dummy, 1, sv, wantp, ph, tdph, &iter, e, &failinfo);
    printf("Singular value decomposition of A\n\nSingular values\n");
    for (i=0; i<n; ++i)
    {
        printf("%9.4f", sv[i]);
        if(i%5==4 || i==n-1)
            printf("\n");
    }
    printf("\nLeft-hand singular vectors, by column\n");
    for (i=0; i<m; ++i)
        for (j=0; j<n; ++j)
        {
            complex temp = a[i][j];
            printf("(%7.4f %7.4f)  ", temp.m_re, temp.m_im);
            if(j%3==2 || j==n-1)
                printf("\n")
        }

    printf("\nRight-hand singular vectors, by column\n");
    for (i=0; i<n; ++i)
        for (j=0; j<n; ++j)
        {
            complex temp = ph[i][j];
            printf("(%7.4f %7.4f)  ", temp.m_re, temp.m_im);
            if(j%3==2 || j==n-1)
                printf("\n");
        }

    printf("\nVector conjg(Q')*B\n");
    for (i=0; i<m; ++i)
    {
        complex temp = b[0][i];
        printf("(%7.4f %7.4f)  ", temp.m_re, temp.m_im);
        if(i%3==2 || i==m-1)
            printf("\n");
    }
}

    The output is following:

    Example 2
    Singular value decomposition of A

    Singular values
          3.9263   2.0000   0.7641

    Left-hand singular vectors, by column
    (-0.0757 -0.5079)  (-0.2831 -0.2831)  (-0.2251  0.1594)
    (-0.4517 -0.2441)  (-0.3963  0.0566)  (-0.0075  0.2757)
    (-0.2366  0.2669)  (-0.1359 -0.6341)  ( 0.2983 -0.2082)
    (-0.0561 -0.0513)  (-0.3284 -0.0340)  ( 0.1670 -0.5978)
    (-0.4820 -0.3277)  ( 0.3737  0.1019)  (-0.0976 -0.5664)

    Right-hand singular vectors, by column
    (-0.1275  0.0000)  (-0.3899 -0.2046)  (-0.5289 -0.7142)
    (-0.2265  0.0000)  (-0.3397 -0.7926)  ( 0.0000  0.4529)
    ( 0.9656  0.0000)  (-0.1311 -0.2129)  (-0.0698  0.0119)

    Vector conjg(Q')*B
    (-1.9656 -0.7935)  ( 0.1132 -0.3397)  ( 0.0915  0.6086)
    (-0.0600 -0.0200)  ( 0.0400  0.1200)

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_cholesky

Function: nag_real_cholesky
Prototype:
int nag_real_cholesky(int n,double a[],int tda,double p[],double *detf,int *dete)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OCN_f.h
See also:
Function: nag_real_cholesky
Prototype:
int nag_real_cholesky(int n,double a[],int tda,double p[],double *detf,int *dete)
Remarks: computes a Cholesky factorization of a real symmetric positive-definite matrix, and evaluates the determinant.
Parameters:
n
  the order of the matrix A.
a[]
  Input: the upper triangle of the n by n positive-de.nite symmetric matrix A. The elements of the array below the diagonal need not be set.  Output: the sub-diagonal elements of the lower triangular matrix L. The upper triangle of A is unchanged.
tda
  the second dimension of the array a as declared in the function from which nag real cholesky is called.
p[]
  the reciprocals of the diagonal elements of L.
dete
  the determinant of A is given by detf × 2.0dete. It is given in this form to avoid overflow or underflow.

Return values:
This function returns NAG error code, 0 if no error.
358: The matrix is not positive-de.nite, possibly due to rounding errors. The factorization could not be completed. detf and dete are set to zero.
11: On entry, n must not be less than 1: n = _value_.
17: On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.
successfully call of the nag_real_cholesky function.

Example:
    To compute a Cholesky factorization and calculate the determinant of the
    real symmetric positive-definite matrix
    .
    ..
    6 7 6 5
    7 11 8 7
    6 8 11 9
    5 7 9 11
    .
    ..
    .

void test_nag_real_cholesky()
{
    double detf, determ;
    matrix a;
    a.SetSize(8,8);
    double p[8];
    int i, dete, j, n;
    n = 4;
    a[0][0] = 6;
    a[0][1] = 7;
    a[0][2] = 6;
    a[0][3] = 5;

    a[1][0] = 7;
    a[1][1] = 11;
    a[1][2] = 8;
    a[1][3] = 7;

    a[2][0] = 6;
    a[2][1] = 8;
    a[2][2] = 11;
    a[2][3] = 9;

    a[3][0] = 5;
    a[3][1] = 7;
    a[3][2] = 9;
    a[3][3] = 11;
    nag_real_cholesky(n, a, 8, p, &detf, &dete);
    printf("Array A after factorization\n");
    for (i=0; i<n; i++)
        for (j=0; j<n; j++)
        {
            printf("%9.4f", a[i][j]);
            if(j%8==7 || j==n-1)
                printf("\n");
        }
    printf("\nArray p\n");
    for (i=0; i<n; i++)
    {
        printf("%9.4f", p[i]);
        if(i%8==7 || i==n-1)
            printf("\n");
    }
    printf("\ndetf = %9.4f dete = %2ld\n\n", detf, dete);
    determ = detf*pow(2.0,1.0*dete);
    printf("Value of determinant = %9.4f\n", determ);

}

    The output is following:

    Array A after factorization

    6.0000  7.0000  6.0000  5.0000
    2.8577 11.0000  8.0000  7.0000
    2.4495  0.5941 11.0000  9.0000
    2.0412  0.6931  1.6645 11.0000

    Array p

    0.4082 0.5941 0.4639 0.5283

    detf = 0.0691 dete = 12

    Value of determinant = 283.0000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_lu

Function: nag_real_lu
Prototype:
int nag_real_lu(int n,double a[],int tda,int pivot[],double *detf,int *dete)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OCN_f.h
See also:
Function: nag_real_lu
Prototype:
int nag_real_lu(int n,double a[],int tda,int pivot[],double *detf,int *dete)
Remarks: computes an LU factorization of a real matrix, with partial pivoting, and evaluates the determinant.
Parameters:
n
  the order of the matrix A.
a[]
  Input: the n by n matrix A.  Output: A is overwritten by the lower triangular matrix L and the o.-diagonal elements of the upper triangular matrix U. The unit diagonal elements of U are not stored.
tda
  the second dimension of the array a as declared in the function from which nag real lu is called.
pivot[]
  pivot[i - 1] gives the row index of the ith pivot.
dete
  the determinant of A is given by detf × 2.0dete. It is given in this form to avoid overflow or underflow.

Return values:
This function returns NAG error code, 0 if no error.
357: The matrix A is singular, possibly due to rounding errors. The factorization could not be completed. detf and dete are set to zero.
11: On entry, n must not be less than 1: n = _value_.
17: O n entry, tda = _value_ while n = _value_. The parameters must satisfy tda = n.
73: Memory allocation failed.
successfully call of the nag_real_lu function.

Example:
    To compute the LU factorization with partial pivoting, and
    calculate the determinant, of the real matrix
    .
    .
    33 16 72
   -24 -10 -57
   -8 -4 -17
    .
    ..

void test_nag_real_lu()
{
    double detf, two=2.0;
    int i, dete, j, n;
    matrix a;
    a.SetSize(8,8);
    int pivot[8];

    n = 3;
    a[0][0] = 33;
    a[0][1] = 16;
    a[0][2] = 72;

    a[1][0] = -24;
    a[1][1] = -10;
    a[1][2] = -57;

    a[2][0] = -8;
    a[2][1] = -4;
    a[2][2] = -17;

    nag_real_lu(n,a,8,pivot,&detf, &dete);

    printf("Array A after factorization\n");
    for (i=0; i<n; i++)
        for (j=0; j<n; j++)
        {
            printf("%9.4f",a[i][j]);
            if(j%8==7 || j==n-1)
                printf("\n");
        }
    printf("\nArray P\n");
    for (i=0; i<n; i++)
    {
        printf("%3ld",pivot[i]);
        if(i%8==7 || i==n-1)
            printf("\n");
    }
    printf("\ndetf = %9.4f dete = %2ld\n", detf, dete);
    detf = detf * pow(two, 1.0*dete);
    printf("\nValue of determinant = %9.4f\n", detf);
}

    The output is following:

    Array A after factorization

     -8.0000  0.5000  2.1250
    -24.0000  2.0000 -3.0000
     33.0000 -0.5000  0.3750

    Array P

    3 2 3

    detf = 0.3750 dete = 4

    Value of determinant = 6.0000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_complex_lu

Function: nag_complex_lu
Prototype:
int nag_complex_lu(int n,complex a[],int tda,int pivot[],complex *detf,int *dete)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OCN_f.h
See also:
Function: nag_complex_lu
Prototype:
int nag_complex_lu(int n,complex a[],int tda,int pivot[],complex *detf,int *dete)
Remarks: computes an LU factorization of a complex matrix, with partial pivoting, and evaluates the determinant.
Parameters:
n
  the order of the matrix A.
a[]
  Input: the n by n matrix A.  Output: A is overwritten by the lower triangular matrix L and the o.-diagonal elements of the upper triangular matrix U. The unit diagonal elements of U are not stored.
tda
  the second dimension of the array a as declared in the function from which nag complex lu is called.
pivot[]
  pivot[i - 1] gives the row index of the ith pivot.
dete
  the determinant of A is given by (det.re + idet.im) × 2.0dete. It is given in this form to avoid overflow and underflow.

Return values:
This function returns NAG error code, 0 if no error.
357: The matrix A is singular, possibly due to rounding errors. The factorization could not be completed. detf and dete are set to zero.
11: On entry, n must not be less than 1: n = _value_.
17: On entry, tda = _value_ while n = _value_. The parameters must satisfy tda = n.
73: Memory allocation failed.
successfully call of the nag_complex_lu function.

Example:
    To compute an LU factorization, with partial pivoting, and
    calculate the determinant, of the complex matrix
    .
    .
    2 1+2i 2 + 10i
    1 + i 1 + 3i -5+ 14i
    1 + i 5i -7+ 20i
    .
    ..

void test_nag_complex_lu()
{

    int pivot[5];
    matrix<complex> a;
    a.SetSize(5,5);
    complex det;
    int i, j, n, dete;
    n = 3;
    a[0][0] = 2.0 + 0.0i;
    a[0][1] = 1.0 + 2.0i;
    a[0][2] = 2.0 + 10.0i;

    a[1][0] = 1.0 + 1.0i;
    a[1][1] = 1.0 + 3.0i;
    a[1][2] = -5.0 +14.0i;

    a[2][0] = 1.0 + 1.0i;
    a[2][1] = 0.0 + 5.0i;
    a[2][2] = -7.0 + 20.0i;

    nag_complex_lu(n, a, 5, pivot, &det, &dete);

    printf("Array a after factorization\n");
    for (i=0; i<n; i++)
    {
        for (j=0; j<n; j++)
        {
            complex temp  =  a[i][j];
            printf("(%7.3f, %7.3f) ", temp.m_re, temp.m_im);
        }
        printf("\n");
    }
    printf("\nArray pivot\n");
    for (i=0; i<n; i++)
        printf("%5ld",pivot[i]);
    printf("\n\ndet.re = %7.4f, det.im = %7.4f, dete = %2ld.\n",det.m_re, det.m_im, dete);
     //the determinent given in this form to avoid overflow and underflow
     det.m_re=det.m_re * pow(2,dete);
    det.m_im=det.m_im * pow(2,dete);

    printf("\nValue of determinant = (%7.4f, %7.4f)\n", det.m_re, det.m_im);

}

    The output is following:

    Array a after factorization

    ( 2.000, 0.000) ( 0.500, 1.000) ( 1.000, 5.000)
    ( 1.000, 1.000) ( 0.500, 3.500) ( 3.800, 1.400)
    ( 1.000, 1.000) ( 1.500, 1.500) ( -4.600, 0.200)

    Array pivot

    1 3 3

    det.re = 0.0234, det.im = 0.1250, dete = 8.
    Value of determinant = ( 6.0000, 32.0000)

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_complex_lin_eqn_mult_rhs

Function: nag_complex_lin_eqn_mult_rhs
Prototype:
int nag_complex_lin_eqn_mult_rhs(int n,int nrhs,complex a[],int tda,complex b[],int tdb,complex x[],int tdx)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OCN_f.h
See also:
Function: nag_complex_lin_eqn_mult_rhs
Prototype:
int nag_complex_lin_eqn_mult_rhs(int n,int nrhs,complex a[],int tda,complex b[],int tdb,complex x[],int tdx)
Remarks: calculates the solution of a set of complex linear equations with multiple right-hand sides.
Parameters:
n
  the order of the matrix A.
nrhs
  the number of right-hand sides.
a[]
  Input: the n by n matrix A.  Output: A is overwritten by the lower triangular matrix L and the o.-diagonal elements of the upper triangular matrix U. The unit diagonal elements of U are not stored.
tda
  the last dimension of the array a as declared in the function from which nag complex lin eqn mult rhs is called.
b[]
  the n by r right-hand side matrix B.
tdb
  the last dimension of the array b as declared in the function from which nag complex lin eqn mult rhs is called.
x[]
  the n by r solution matrix X.
tdx
  the last dimension of the array x as declared in the function from which nag complex lin eqn mult rhs is called.

Return values:
This function returns NAG error code, 0 if no error.
357: The matrix A is singular, possibly due to rounding errors.
11: On entry, n must not be less than 1: n = _value_.  On entry, nrhs must not be less than 1: nrhs = _value_.
17: On entry, tda = _value_ while n = _value_. The parameters must satisfy tda = n.  On entry, tdb = _value_ while nrhs = _value_. These parameters must satisfy tdb = nrhs.  On entry, tdx = _value_ while nphs = _value_. These parameters must satisfy tdx = nrhs.
73: Memory allocation failed.
successfully call of the nag_complex_lin_eqn_mult_rhs function.

Example:
    To solve the set of linear equations AX = B where
    A = .
    .
    1     1+2i    2+ 10i
    1 + i 3i     -5+ 14i
    1 + i 5i     -8+ 20i
    .
    .
    and
    B = .
    .
    1
    0
    0
    .
    ..

void test_nag_complex_lin_eqn_mult_rhs()
{
    matrix<complex> a, b, x;
    a.SetSize(5,5);
    b.SetSize(5,1);
    x.SetSize(5,1);
    int i, j, n, l = 1;

    n = 3;
    a[0][0] = 1.0 + 0.0i;
    a[0][1] = 1.0 + 2.0i;
    a[0][2] = 2.0 +10.0i;

    a[1][0] = 1.0 + 1.0i;
    a[1][1] = 0.0 + 3.0i;
    a[1][2] = -5.0 +14.0i;

    a[2][0] = 1.0 + 1.0i;
    a[2][1] = 0.0 + 5.0i;
    a[2][2] = -8.0 + 20.0i;

    b[0][0] = 1.0 + 0.0i;
    b[1][0] = 0.0 + 0.0i;
    b[2][0] = 0.0 + 0.0i;

    nag_complex_lin_eqn_mult_rhs(n, 1, a, 5, b, 1, x, 1);

    printf("Solution\n");
    for (i=0; i<n; i++)
    {
        complex temp = x[i][0];
        printf("(%7.4f, %7.4f)\n", temp.m_re, temp.m_im);
    }
}

The output is following:

Solution
(10.0000, 1.0000)
( 9.0000, -3.0000)
(-2.0000, 2.0000)

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_cholesky_solve_mult_rhs

Function: nag_real_cholesky_solve_mult_rhs
Prototype:
int nag_real_cholesky_solve_mult_rhs(int n,int nrhs,double a[],int tda,double p[],double b[],int tdb,double x[],int tdx)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OCN_f.h
See also:
Function: nag_real_cholesky_solve_mult_rhs
Prototype:
int nag_real_cholesky_solve_mult_rhs(int n,int nrhs,double a[],int tda,double p[],double b[],int tdb,double x[],int tdx)
Remarks: calculates the approximate solution of a set of real symmetric positive-definite linear equations with multiple right-hand sides, AX = B, where A has been factorized by nag real cholesky (f03aec).
Parameters:
n
  the order of the matrix A.
nrhs
  the number of right-hand sides.
a[]
  the upper triangle of the n by n positive-de.nite symmetric matrix A, and the subdiagonal elements of its Cholesky factor L, as returned by nag real cholesky (f03aec).
tda
  : the second dimension of the array a as declared in the function from which nag real cholesky solve mult rhs is called.
p[]
  the reciprocals of the diagonal elements of L, as returned by nag real cholesky (f03aec).
b[]
  the n by r right-hand side matrix B.
tdb
  the second dimension of the array b as declared in the function from which nag real cholesky solve mult rhs is called.
x[]
  the n by r solution matrix X.
tdx
  the second dimension of the array x as declared in the function from which nag real cholesky solve mult rhs is called.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 1: n = _value_.  On entry, nrhs must not be less than 1: nrhs = _value_.
17: On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.  On entry, tdb = _value_while nrhs = _value_. These parameters must satisfy tdb = nrhs.  On entry, tdx = _value_while nrhs = _value_. These parameters must satisfy tdx = nrhs.
successfully call of the nag_real_cholesky_solve_mult_rhs function.

Example:
    To solve the set of linear equations AX = B where
    A =
    .
    ..
    5 7 6 5
    7 10 8 7
    6 8 10 9
    5 7 9 10
    .
    ..
    and
    B =
    .
    ..
    23
    32
    33
    31
    .
    ..
    .

void test_nag_real_cholesky_solve_mult_rhs()
{
    double d1;
    int i, id, j, n;
    matrix a, b, x;
    a.SetSize(8,8);
    b.SetSize(8,1);
    double  p[8];
    x.SetSize(8,1);
    n = 4;
    a[0][0] = 5;
    a[0][1] = 7;
    a[0][2] = 6;
    a[0][3] = 5;

    a[1][0] = 7;
    a[1][1] = 10;
    a[1][2] = 8;
    a[1][3] = 7;

    a[2][0] = 6;
    a[2][1] = 8;
    a[2][2] = 10;
    a[2][3] = 9;

    a[3][0] = 5;
    a[3][1] = 7;
    a[3][2] = 9;
    a[3][3] = 10;

    b[0][0] = 23;
    b[1][0] = 32;
    b[2][0] = 33;
    b[3][0] = 31;

    nag_real_cholesky(n, a, 8, p, &d1, &id);
    nag_real_cholesky_solve_mult_rhs(n, 1, a, 8, p, b, 1, x, 1);

    printf("\n Solution\n");
    for (i=0; i<n; ++i)
    {
        for (j=0; j <1 ; ++j)
            printf("%9.4f", x[i][j]);
        printf("\n");
    }
}

The output is following:

Solution
1.0000
1.0000
1.0000
1.0000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_lu_solve_mult_rhs

Function: nag_real_lu_solve_mult_rhs
Prototype:
int nag_real_lu_solve_mult_rhs(int n,int nrhs,double a[],int tda,int pivot[],double b[],int tdb)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OCN_f.h
See also:
Function: nag_real_lu_solve_mult_rhs
Prototype:
int nag_real_lu_solve_mult_rhs(int n,int nrhs,double a[],int tda,int pivot[],double b[],int tdb)
Remarks: calculates the approximate solution of a set of real linear equations with multiple right-hand sides, AX = B, where A has been factorized by nag real lu (f03afc).
Parameters:
n
  the order of the matrix A.
nrhs
  the number of right-hand sides.
a[]
  details of the LU factorization, as returned by nag real lu (f03afc).
tda
  the second dimension of the array a as declared in the function from which nag real lu solve mult rhs is called.
pivot[]
  details of the row interchanges as returned by nag real lu (f03afc).
b[]
  Input: the n by r right-hand side matrix B.  Output: B is overwritten by the solution matrix X.
tdb
  the second dimension of the array b as declared in the function from which nag real lu solve mult rhs is called.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 1: n = _value_.  On entry, nrhs must not be less than 1: nrhs = _value_.
17: On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.  On entry, tdb = _value_ while nrhs = _value_. These parameters must satisfy tdb = nrhs.
successfully call of the nag_real_lu_solve_mult_rhs function.

Example:
    To solve the set of linear equations AX = B where
    A = .
    .
     33 16 72
    -24 -10 -57
    -8 -4 -17
    .
    .
    and
    B = .
    .
    -359
     281
      85
     .
    ..

void test_nag_real_lu_solve_mult_rhs()
{
    int TDB =  3;
    int NMAX = 8;
    int TDA = 8;
    double detf;
    int i, dete, j, n, nrhs = 1;
    matrix a, b;
    a.SetSize(NMAX,TDA);
    b.SetSize(NMAX, TDB);
    int pivot[8];

    n = 3;
    a[0][0] = 33;
    a[0][1] = 16;
    a[0][2] = 72;

    a[1][0] = -24;
    a[1][1] = -10;
    a[1][2] = -57;

    a[2][0] = -8;
    a[2][1] = -4;
    a[2][2] = -17;

    b[0][0] = -359;
    b[1][0] = 281;
    b[2][0] = 85;

    nag_real_lu(n, a, TDA, pivot, &detf,&dete);

    nag_real_lu_solve_mult_rhs(n, nrhs, a, TDA, pivot, b, TDB);

    printf("Solution\n");
    for (i=0; i<n; i++)
        for (j=0; j<nrhs; j++)
            printf("%9.4f\n",b[i][j]);
}

    The output is following:

    Solution
    1.0000
    -2.0000
    -5.0000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_complex_lu_solve_mult_rhs

Function: nag_complex_lu_solve_mult_rhs
Prototype:
int nag_complex_lu_solve_mult_rhs(int n,int nrhs,complex a[],int tda,int pivot[],complex b[],int tdb)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OCN_f.h
See also:
Function: nag_complex_lu_solve_mult_rhs
Prototype:
int nag_complex_lu_solve_mult_rhs(int n,int nrhs,complex a[],int tda,int pivot[],complex b[],int tdb)
Remarks: calculates the approximate solution of a set of complex linear equations with multiple right-hand sides AX = B, where A has been factorized by nag complex lu (f03ahc).
Parameters:
n
  the order of the matrix A.
nrhs
  the number of right-hand sides.
a[]
  details of the LU factorization, as returned by nag complex lu (f03ahc).
tda
  the second dimension of the array a as declared in the function from which nag complex lu solve mult rhs is called.
pivot[]
  details of the row interchanges as returned by nag complex lu (f03ahc).
b[]
  Input: the n by r right-hand side matrix B.  Output: B is overwritten by the solution matrix X.
tdb
  the second dimension of the array b as declared in the function from which nag complex lu solve mult rhs is called.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 1: n = _value_.  On entry, nrhs must not be less than 1: nrhs = _value_.
17: On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.  On entry, tdb = _value_ while nrhs = _value_. These parameters must satisfy tdb = nrhs.
successfully call of the  nag_complex_lu_solve_mult_rhs function.

Example:
    To solve the set of linear equations AX = B where
    A = .
    .
    1 1+2i 2+ 10i
    1 + i 3i -5+ 14i
    1 + i 5i -8+ 20i
    .
    .
    and
    B = .
    .
    1
    0
    0
    .
    ..

void test_nag_complex_lu_solve_mult_rhs()
{
    int NMAX = 5;
    int TDA =  NMAX;
    int TDB  = NMAX;

    complex det;
    matrix<complex>a, b;
    a.SetSize(NMAX,TDA);
    b.SetSize(NMAX,TDB);
    int i, j, n, dete, nrhs = 1;
    int pivot[5];

    n = 3;
    a[0][0] = 1.0 + 0.0i;
    a[0][1] = 1.0 + 2.0i;
    a[0][2] = 2.0 +10.0i;

    a[1][0] = 1.0 + 1.0i;
    a[1][1] = 0.0 + 3.0i;
    a[1][2] = -5.0 + 14.0i;

    a[2][0] = 1.0 + 1.0i;
    a[2][1] = 0.0 + 5.0i;
    a[2][2] = -8.0 + 20.0i;

    b[0][0] = 1.0 + 0.0i;
    b[1][0] = 0.0 + 0.0i;
    b[2][0] = 0.0 + 0.0i;

    nag_complex_lu(n, a, TDA, pivot, &det, &dete);

    nag_complex_lu_solve_mult_rhs(n, nrhs, a, TDA, pivot, b, TDB);
    printf("Solution\n");
    for (i=0; i<n; i++)
    {
        for (j=0; j<nrhs; j++)
        {
            complex temp = b[i][j];
            printf("(%7.3f, %7.3f) ", temp.m_re, temp.m_im);
        }
        printf("\n");
    }

}

    The output is following:

    Solution
    ( 10.000, 1.000)
    ( 9.000, -3.000)
    ( -2.000, 2.000)

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_lin_eqn

Function: nag_real_lin_eqn
Prototype:
int nag_real_lin_eqn(int n,double a[],int tda,double b[],double x[])
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OCN_f.h
See also:
Function: nag_real_lin_eqn
Prototype:
int nag_real_lin_eqn(int n,double a[],int tda,double b[],double x[])
Remarks: calculates the approximate solution of a set of real linear equations with a single right-hand side, using an LU factorization with partial pivoting.
Parameters:
n
  the order of the matrix A.
a[]
  Input: the n by n matrix A.  Output: A is overwritten by the lower triangular matrix L and the o.-diagonal elements of the upper triangular matrix U. The unit diagonal elements of U are not stored.
tda
  the second dimension of the array a as declared in the function from which nag real lin eqn is called.
b[]
  the right-hand side vector b.
x[]
  the solution vector x.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 1: n = _value_.
17: On entry, tda = _value_ while n = _value_. These parameters must satisfy tda = n.
357: The matrix A is singular, possibly due to rounding errors.
73: Memory allocation failed.
successfully call of the nag_real_lin_eqn function.

Example:
    To solve the set of linear equations Ax = b where
    A = .
    .
     33 16 72
    -24 -10 -57
    -8 -4 -17
    .
    .
    and
    B = .
    .
    -359
     281
      85
     .
     ..

void test_nag_real_lin_eqn()
{
    int NMAX = 8;
    int TDA = NMAX;

    matrix a;
    a.SetSize(NMAX,TDA);
    double  b[8], x[8];
    int i, j, n;
    n = 3;
    a[0][0] = 33;
    a[0][1] = 16;
    a[0][2] = 72;

    a[1][0] = -24;
    a[1][1] = -10;
    a[1][2] = -57;

    a[2][0] = -8;
    a[2][1] = -4;
    a[2][2] = -17;

    b[0] = -359;
    b[1] = 281;
    b[2] = 85;

    nag_real_lin_eqn(n, a, TDA, b, x);
    printf("Solution\n");
    for (i=0; i<n; i++)
        printf("%9.4f\n",x[i]);

}

    The output is following:

    Solution
    1.0000
    -2.0000
    -5.0000

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_hermitian_lin_eqn_mult_rhs

Function: nag_hermitian_lin_eqn_mult_rhs
Prototype:
int nag_hermitian_lin_eqn_mult_rhs(int n,int nrhs,complex a[],int tda,double p[],complex b[],int tdb,complex x[],int tdx)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OCN_f.h
See also:
Function: nag_hermitian_lin_eqn_mult_rhs
Prototype:
int nag_hermitian_lin_eqn_mult_rhs(int n,int nrhs,complex a[],int tda,double p[],complex b[],int tdb,complex x[],int tdx)
Remarks: calculates the approximate solution of a set of complex Hermitian positive-definite linear equations with multiple right-hand sides, AX = B, where A has been factorized by nag complex cholesky (f01bnc).
Parameters:
n
  the order of the matrix A.
nrhs
  the number of right-hand sides.
a[]
  the o.-diagonal elements of the upper triangular matrix U as returned by nag complex cholesky (f01bnc). The lower triangle of the array is not used.
tda
  the second dimension of the array a as declared in the function from which nag hermitian lin eqn mult rhs is called.
p[]
  the reciprocals of the diagonal elements of U, as returned by nag complex cholesky (f01bnc).
b[]
  the n by r right-hand side matrix B.
tdb
  the second dimension of the array b as declared in the function from which nag hermitian lin eqn mult rhs is called.
x[]
  the n by r solution matrix X.
tdx
  the second dimension of the array x as declared in the function from which nag hermitian lin eqn mult rhs is called.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, nrhs must not be less than 1: nrhs = _value_.  On entry, n must not be less than 1: n = _value_.
17: On entry, tda = _value_ while n = _value_. These paremters must satisfy tda = n.  On entry, tdb = _value_ while nrhs = _value_. These parameters must satisfy tdb = nrhs.  On entry, tdx = _value_ while nrhs = _value_. These parameters must satisfy tdx = nrhs.
successfully call of the nag_hermitian_lin_eqn_mult_rhs function.

Example:
    To solve the set of linear equations AX = B where A is the
    positive-definite Hermitian matrix:
    .
    ..
    15 1 - 2i 2 -4 + 3i
    1 + 2i 20 -2 + i 3 - 3i
    2 -2 - i 18 -1 + 2i
    -4 - 3i 3 + 3i -1 - 2i 26
    .
    ..
    and B is the single column vector:
    .
    ..
    25 + 34i
    21 + 19i
    12 - 21i
    21 - 27i
    .
    ..
    .

void test_nag_hermitian_lin_eqn_mult_rhs()
{
    int NMAX =  8;
    int TDA =  NMAX;
    int TDB =  2;
    int TDX = 2;
    int i, j, n;
    matrix<complex> a, b, x;
    a.SetSize(NMAX,TDA);
    b.SetSize(NMAX,TDB);
    x.SetSize(NMAX,TDX);
    double p[8];
    int nrhs = 1;

    n = 4;
    a[0][0] = 15.0 + 0.0i;

    a[1][0] = 1.0 + 2.0i;
    a[1][1]	= 20.0 + 0.0i;

    a[2][0] = 2.0 + 0.0i;
    a[2][1] = -2.0 -1.0i;
    a[2][2] = 18.0 + 0.0i;

    a[3][0] = -4.0 - 3.0i;
    a[3][1] = 3.0 + 3.0i;
    a[3][2] = -1.0 - 2.0i;
    a[3][3] = 26.0 + 0.0i;

    b[0][0] = 25.0 + 34.0i;
    b[1][0] = 21.0 + 19.0i;
    b[2][0] = 12.0 - 21.0i;
    b[3][0] = 21.0 - 27.0i;

    nag_complex_cholesky(n, a, TDA, p);

    nag_hermitian_lin_eqn_mult_rhs(n, nrhs, a, TDA, p, b, TDB, x, TDX);

    printf("\nSolution\n\n");
    for (i=0; i<n; ++i)
    {
        for (j=0; j<nrhs; ++j)
        {
            complex temp = x[i][j];
             printf(" (%7.4f,%7.4f)", temp.m_re, temp.m_im);
         }
        printf("\n");
    }

}

    The output is following:

    Solution
    ( 1.4917, 2.1788)
    ( 1.1629, 0.7698)
    ( 0.5506,-1.3977)
    ( 0.8691,-0.7655)

Summary:
Sample data:
Header file: OCN_f.h
See also:


nag_real_cholesky_skyline_solve

Function: nag_real_cholesky_skyline_solve
Prototype:
int nag_real_cholesky_skyline_solve(Nag_SolveSystem selct,int n,int nrhs,double al[],int lal,double d[],int row[],double b[],int tdb,double x[],int tdx)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OCN_f.h
See also:
Function: nag_real_cholesky_skyline_solve
Prototype:
int nag_real_cholesky_skyline_solve(Nag_SolveSystem selct,int n,int nrhs,double al[],int lal,double d[],int row[],double b[],int tdb,double x[],int tdx)
Remarks: computes the approximate solution of a system of real linear equations with multiple right-hand sides, AX = B, where A is a symmetric positive-definite variable-bandwidth matrix, which has previously been factorized by nag real cholesky skyline (f01mcc). Related systems may also be solved.
Parameters:
n
  the order of the matrix L.
nrhs
  the number of right-hand sides.
al[]
  the elements within the envelope of the lower triangular matrix L, taken in row by row order, as returned by nag real cholesky skyline (f01mcc). The unit diagonal elements of L must be stored explicitly.
lal
  the dimension of the array al as declared in the function from which nag real cholesky skyline solve is called.
d[]
  the diagonal elements of the diagonal matrix D. d is not referenced if selct = Nag LLTX, Nag LX or Nag LTX
row[]
  row[i] must contain the width of row i of L, i.e., the number of elements between the first (left-most) non-zero element and the element on the diagonal, inclusive.
b[]
  the n by r right-hand side matrix B.
tdb
  the second dimension of the array b as declared in the function from which nag real cholesky skyline solve is called.
x[]
  the n by r solution matrix X.
tdx
  the second dimension of the array x as declared in the function from which nag real cholesky skyline solve is called.

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 1: n = _value_.  On entry, row[_value_] must not be less than 1: row[_value_] = _value_.  On entry, nrhs must not be less than 1: nrhs = _value_.
19: On entry, row[i] = _value_ while i = _value_. These parameters must satisfy row[i] = i + 1 .
17: On entry, lal = _value_ while row[0] + . . .+row[n - 1 ] =_value_. These parameters must satisfy lal = row[0] + . . .+row[n - 1].  On entry, tdb = _value_ while nrhs = _value_. These parameters must satisfy tdb = nrhs.  On entry, tdx = _value_ while nrhs = _value_. These parameters must satisfy tdx = nrhs.
70: On entry, parameter selct had an illegal value.
370: The diagonal matrix D is singular as it has at least one zero element. The .rst zero element has been located in the array d[_value_]
371: The lower triangular matrix L has at least one diagonal element which is not equal to unity.  The first non-unit element has been located in the array al[_value_]
successfully call of the nag_real_cholesky_skyline_solve function.

Example:
    To solve the system of equations AX = B, where
    A =
    .
    ......
    1 2 0 0 5 0
    2 5 3 0 1 40
    0 3 1 3 01 8 0
    0 0 0 1 68 24
    5 14 18 8 55 17
    0 0 0 24 1 77
    .
    ......
    and
    B =
    .
    ......
    6 -10
    15 -21
    11 -3
    0 24
    51 -39
    46 67
    .
    ......
    .
    Here A is symmetric and positive-definite and must first
    be factorized by nag real cholesky skyline

void test_nag_real_cholesky_skyline_solve()
{
    int NMAX = 6;
    int NRHSMAX  = 2;
    int TDB  = NRHSMAX;
    int TDX =  NRHSMAX;
    int LALMAX  = 14;

    int i, nrhs, k, k1, k2, lal, n;
    matrix b, x;
    b.SetSize(NMAX,TDB);
    x.SetSize(NMAX, TDX);
    double a[14] = {1.0, 2.0, 5.0, 3.0, 13.0, 16.0, 5.0, 14.0, 18.0, 8.0, 55.0, 24.0, 17.0, 77.0};
    double al[14], d[6];
    int row[6] = {1, 2, 2, 1, 5, 3};
    Nag_SolveSystem select;
    n = 6;
    k2 = 0;
    nrhs = 2;
    lal = 14;

    b[0][0] = 6.0;
    b[0][1] = -10.0;

    b[1][0] = 15.0;
    b[1][1] = -21.0;

    b[2][0] = 11.0;
    b[2][1] = -3.0;

    b[3][0] = 0.0;
    b[3][1] = 24.0;

    b[4][0] = 51.0;
    b[4][1] = -39.0;

    b[5][0] = 46.0;
    b[5][1] = 67.0;

    nag_real_cholesky_skyline(n, a, lal, row, al, d);
    select = Nag_LDLTX;
    nag_real_cholesky_skyline_solve(select, n, nrhs, al, lal, d, row, b, TDB, x, TDX);
    printf("\n Solution\n");
    for (i=0; i<n; ++i)
    {
        for (k=0; k<nrhs; ++k)
            printf("%9.3f",x[i][k]);
        printf("\n");
    }
}

The output is following:

Solution
   -3.000    4.000
    2.000   -2.000
   -1.000    3.000
   -2.000    1.000
    1.000   -2.000
    1.000    1.000

Summary:
Sample data:
Header file: OCN_f.h
See also:


dgemv

Function: dgemv
Prototype:
void dgemv(MatrixTranspose trans,int m,int n,double alpha,const double a[],int tda,const double x[],int incx,double beta,double y[],int incy)
Remarks: computes a matrix-vector product for general matrix.
Parameters:
trans=NoTranspose, return (alpha*Ax+beta*y) in array y[];
trans=Transpose, return (alpha*transpose(A)*x+beta*y) in array y[];
trans=ConjugateTranspose, return (alpha*ConjugateTranspose(A)*x+beta*y) in array y[].
m
  the number of rows of A
n
  the number of columns of A
a[]
  a general m by n matrix
tda
  the last demension of A
x[]
  vector x
incx
  the spacing which the elements of the vector x occur
y[]
  Input: vector y; Output: alpha*trans(A)*x + beta*y
incy
  the spacing which the elements of the vector y occur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a general matrix
        1  2  3  4
        5  6  7  8
        9 10 11 12
       13 14 15 16

    and a vector
       17
       18
       19
       20.

void test_f06pac()      //test for function dgemv(f06pac)
{
    int nRows=4;
    int nCols=4;

    matrix<double> mat_input={{1,2,3,4},{5,6,7,8},{9,10,11,12},{13,14,15,16}};

    vector<double> vec_input={17,18,19,20};

    vector<double> vec_output(nRows);
    vec_output=0;

    dgemv(NoTranspose,nRows,nCols,1,mat_input,nCols,vec_input,1,1,vec_output,1);

    printf("Compute a matrix-vector product for general real matrix M*V:\n");

    printf("M=\n");                     //output mat_input
    for(int i=0;i<nRows;i++)
    {
       printf("       ");
       for(int j=0;j<nCols;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
    }

    printf("\n");                       //output vec_input
    printf("V=\n");
    for(i=0;i<nRows;i++)
    {
      printf("       ");
      printf("%f\n",vec_input[i]);
    }

    printf("\n");                       //output vec_output
    printf("Result vector=\n");
    for(i=0;i<nRows;i++)
    {
      printf("       ");
      printf("%f\n",vec_output[i]);
    }
}

    The output is following:

Compute a matrix-vector product for general real matrix M*V:
M=
       1.000000    2.000000    3.000000    4.000000
       5.000000    6.000000    7.000000    8.000000
       9.000000    10.000000    11.000000    12.000000
       13.000000    14.000000    15.000000    16.000000

V=
       17.000000
       18.000000
       19.000000
       20.000000

Result vector=
       190.000000
       486.000000
       782.000000
       1078.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dgbmv

Function: dgbmv
Prototype:
void dgbmv(MatrixTranspose trans,int m,int n,int kl,int ku,double alpha,const double a[],int tda,const double x[],int incx,double beta,double y[],int incy)
Remarks: Compute a matrix-vector product for real general band matrix
Parameters:
trans=NoTranspose, return (alpha*Ax+beta*y) in array y[];
trans=Transpose, return (alpha*transpose(A)*x+beta*y) in array y[];
trans=ConjugateTranspose, return (alpha*ConjugateTranspose(A)*x+beta*y) in array y[].
m
  the number of rows of A
n
  the number of columns of A
kl
  specify the subdiagonals of the matrix A
ku
  specify the superdiagonals of the matrix A
a[]
  the real m by n matrix A which stored in band storage
tda
  the last dimension of A
x[]
  vector x
incx
  the spacing which the elements of the vector x occur
y[]
  Input: vector y; Output: alpha*trans(A)*x+beta*y
incy
  the spacing which the elements of vector y occur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a real matrix
       1.000000    2.000000    3.000000    0.000000
       4.000000    5.000000    6.000000    7.000000
       0.000000    8.000000    9.000000    10.000000
    which in band storage and a real vector
       11
       12
       13
       14

void test_f06pbc()              //test for function dgbmv(f06pbc)
{
   int nRows=3;
   int nCols=4;

   matrix<double> mat_input={{1,2,3,0},
                             {4,5,6,7},
                             {0,8,9,10}};

   matrix<double> mat_input_band={{0,1,2,3},
                                  {4,5,6,7},
                                  {8,9,10,0}};
   int kupper=2;
   int klower=1;

   vector<double> vec_input={11,12,13,14};

   vector<double> vec_output(nRows);
   vec_output=0;

   dgbmv(NoTranspose,nRows,nCols,klower,kupper,1,mat_input_band,nCols,vec_input,1,1,vec_output,1);

   printf("Compute a matrix-vector product for real band matrix M*V:\n");

   printf("M=\n");                     //output mat_input
   for(int i=0;i<nRows;i++)
   {
       printf("       ");
       for(int j=0;j<nCols;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
   }

   printf("\n");                       //output vec_input
   printf("V=\n");
   for(i=0;i<nCols;i++)
   {
      printf("       ");
      printf("%f\n",vec_input[i]);
   }

   printf("\n");                       //output vec_output
   printf("Result vector=\n");
   for(i=0;i<nRows;i++)
   {
      printf("       ");
      printf("%f\n",vec_output[i]);
   }
}

  The output is following:
Compute a matrix-vector product for real band matrix M*V:
M=
       1.000000    2.000000    3.000000    0.000000
       4.000000    5.000000    6.000000    7.000000
       0.000000    8.000000    9.000000    10.000000

V=
       11.000000
       12.000000
       13.000000
       14.000000

Result vector=
       74.000000
       280.000000
       353.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dsymv

Function: dsymv
Prototype:
void dsymv(MatrixTriangle uplo,int n,double alpha,const double a[],int tda,const double x[],int incx,double beta,double y[],int incy)
Remarks: Compute a matrix-vector product for real symmetric matrix
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of symmetric matrix A
a[]
  the real symmetric matrix of order n
tda
  the last dimension of A
x[]
  vector x
incx
  the spacing which the elements of vector x occur
y[]
  Input: vector y; Output: alpha*Ax+beta*y

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a real symmetric matrix
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       2.000000    7.000000    9.000000    10.000000
       4.000000    8.000000    10.000000    11.000000

    and a real vector
       12.000000
       13.000000
       14.000000
       15.000000

void test_f06pcc()         //test for function dsymv(f06pcc)
{
    int nColRow=4;

    matrix<double> mat_input={{1,2,3,4},
                              {2,6,7,8},
                              {2,7,9,10},
                              {4,8,10,11}};

    vector<double> vec_input={12,13,14,15};

    vector<double> vec_output(nColRow);
    vec_output=0;

    dsymv(UpperTriangle,nColRow,1,mat_input,nColRow,vec_input,1,1,vec_output,1);

    printf("Compute a matrix-vector product for real symmetric matrix M*V:\n");

    printf("M=\n");                     //output mat_input
    for(int i=0;i<nColRow;i++)
    {
       printf("       ");
       for(int j=0;j<nColRow;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
    }

    printf("\n");                       //output vec_input
    printf("V=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_input[i]);
    }

    printf("\n");                       //output vec_output
    printf("Result vector=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_output[i]);
    }
}

   The output is as following:
Compute a matrix-vector product for real symmetric matrix M*V:
M=
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       2.000000    7.000000    9.000000    10.000000
       4.000000    8.000000    10.000000    11.000000

V=
       12.000000
       13.000000
       14.000000
       15.000000

Result vector=
       140.000000
       320.000000
       403.000000
       457.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dsbmv

Function: dsbmv
Prototype:
void dsbmv(MatrixTriangle uplo,int n,int k,double alpha,const double a[],int tda,const double x[],int incx,double beta,double y[],int incy)
Remarks: Compute a matrix-vector product for symmetric band matrix
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of symmetric band matrix A
k
  the subdiagonals (superdiagonals) of A
a[]
  the symmetric band matrix A
tda
  the last dimension of A
x[]
  vector x
incx
  the spacing which the elements of vector x occur
y[]
  Input: vector y; Output: alpha*Ax+beta*y
incy
  the spacing which the elements of vector y occur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a symmetric band matrix
       1.000000    2.000000    3.000000    0.000000
       2.000000    5.000000    6.000000    7.000000
       3.000000    6.000000    9.000000    10.000000
       0.000000    7.000000    10.000000   11.000000

    and a real vector
       11.000000
       12.000000
       13.000000
       14.000000

void test_f06pdc()              //test for function dsbmv(f06pdc)
{
   int nRowCol=4;

   matrix<double> mat_input={{1,2,3,0},
                             {2,5,6,7},
                             {3,6,9,10},
                             {0,7,10,11}};
   int k_nzero=2;
   matrix<double> mat_input_band={{1,2,3},
                                  {5,6,7},
                                  {9,10,0},
                                  {11,0,0}};

   vector<double> vec_input={11,12,13,14};

   vector<double> vec_output(nRowCol);
   vec_output=0;

   dsbmv(UpperTriangle,nRowCol,k_nzero,1,mat_input_band,k_nzero+1,vec_input,1,1,vec_output,1);

   printf("Compute a matrix-vector product for real symmetric band matrix M*V:\n");

   printf("M=\n");                     //output mat_input
   for(int i=0;i<nRowCol;i++)
   {
       printf("       ");
       for(int j=0;j<nRowCol;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
   }

   printf("\n");                       //output vec_input
   printf("V=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("%f\n",vec_input[i]);
   }

   printf("\n");                       //output vec_output
   printf("Result vector=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("%f\n",vec_output[i]);
   }
}

   The output is as following:
Compute a matrix-vector product for real symmetric band matrix M*V:
M=
       1.000000    2.000000    3.000000    0.000000
       2.000000    5.000000    6.000000    7.000000
       3.000000    6.000000    9.000000    10.000000
       0.000000    7.000000    10.000000    11.000000

V=
       11.000000
       12.000000
       13.000000
       14.000000

Result vector=
       74.000000
       258.000000
       362.000000
       368.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dspmv

Function: dspmv
Prototype:
void dspmv(MatrixTriangle uplo,int n,double alpha,const double ap[],const double x[],int incx,double beta,double y[],int incy)
Remarks: Compute a matrix-vector product for real symmetric packed matrix
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of the real symmetric packed matrix A
ap[]
  the real symmetric matrix A in packed storage
x[]
  vetor x
incx
  the spacing which the elements of vector x occur
y[]
  Input: vector y; Output: alpha*Ax+beta*y
incy
  the spacing which the elements of vector y occur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a real symmetric packed matrix
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       2.000000    7.000000    9.000000    10.000000
       4.000000    8.000000    10.000000    11.000000

    and a real vector
       12.000000
       13.000000
       14.000000
       15.000000

void test_f06pec()         //test for function dspmv(f06pec)
{
    int nColRow=4;

    matrix<double> mat_input_pack={1,2,3,4,
                                     6,7,8,
                                       9,10,
                                         11};

    matrix<double> mat_input={{1,2,3,4},
                              {2,6,7,8},
                              {2,7,9,10},
                              {4,8,10,11}};

    vector<double> vec_input={12,13,14,15};

    vector<double> vec_output(nColRow);
    vec_output=0;

    dspmv(UpperTriangle,nColRow,1,mat_input_pack,vec_input,1,1,vec_output,1);

    printf("Compute a matrix-vector product for real symmetric packed matrix M*V:\n");

    printf("M=\n");                     //output mat_input
    for(int i=0;i<nColRow;i++)
    {
       printf("       ");
       for(int j=0;j<nColRow;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
    }

    printf("\n");                       //output vec_input
    printf("V=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_input[i]);
    }

    printf("\n");                       //output vec_output
    printf("Result vector=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_output[i]);
    }
}

   The output is as following:
Compute a matrix-vector product for real symmetric packed matrix M*V:
M=
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       2.000000    7.000000    9.000000    10.000000
       4.000000    8.000000    10.000000    11.000000

V=
       12.000000
       13.000000
       14.000000
       15.000000

Result vector=
       140.000000
       320.000000
       403.000000
       457.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dtrmv

Function: dtrmv
Prototype:
void dtrmv(MatrixTriangle uplo,MatrixTranspose trans,MatrixUnitTriangular diag,int n,const double a[],int tda,double x[],int incx)
Remarks: Compute a matrix-vector product for real triangular matrix
Parameters:
trans=NoTranspose, return A*x in array x[];
trans=Transpose, return transpose(A)*x in array x[];
trans=ConjugateTranspose, return ConjugateTranspose(A)*x in array x[].
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
diag specify whether or not the matrix is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
n
  the order of the real triangular matrix A
a[]
  order n real triangular matrix A
tda
  the last dimension of A
x[]
  Input: the vector x; Output: the product of A and x
incx
  the spacing which the elements of x occur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a real triangular matrix
       1.000000    2.000000    3.000000    4.000000
       0.000000    6.000000    7.000000    8.000000
       0.000000    0.000000    9.000000    10.000000
       0.000000    0.000000    0.000000    11.000000

    and a real vector
       12.000000
       13.000000
       14.000000
       15.000000

void test_f06pfc()         //test for function dtrmv(f06pfc)
{
    int nColRow=4;

    matrix<double> mat_input={{1,2,3,4},
                              {0,6,7,8},
                              {0,0,9,10},
                              {0,0,0,11}};

    vector<double> vec_input={12,13,14,15};

    vector<double> vec_output;
    vec_output=vec_input;

    dtrmv(UpperTriangle,NoTranspose,NotUnitTriangular,nColRow,
            mat_input,nColRow,vec_output,1);

    printf("Compute a matrix-vector product for real triangular matrix M*V:\n");

    printf("M=\n");                     //output mat_input
    for(int i=0;i<nColRow;i++)
    {
       printf("       ");
       for(int j=0;j<nColRow;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
    }

    printf("\n");                       //output vec_input
    printf("V=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_input[i]);
    }

    printf("\n");                       //output vec_output
    printf("Result vector=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_output[i]);
    }
}

   The output is as following:
Compute a matrix-vector product for real triangular matrix M*V:
M=
       1.000000    2.000000    3.000000    4.000000
       0.000000    6.000000    7.000000    8.000000
       0.000000    0.000000    9.000000    10.000000
       0.000000    0.000000    0.000000    11.000000

V=
       12.000000
       13.000000
       14.000000
       15.000000

Result vector=
       140.000000
       296.000000
       276.000000
       165.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dtbmv

Function: dtbmv
Prototype:
void dtbmv(MatrixTriangle uplo,MatrixTranspose trans,MatrixUnitTriangular diag,int n,int k,const double a[],int tda,double x[],int incx)
Remarks: Compute a matrix-vector product for real triangular band matrix
Parameters:
trans=NoTranspose, return A*x in array x[];
trans=Transpose, return transpose(A)*x in array x[];
trans=ConjugateTranspose, return ConjugateTranspose(A)*x in array x[].
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
diag specify whether or not the matrix is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
n
  the order of A
k
  the subdiagonals(superdiagonals) of A
a[]
  the real triangular band matrix A
tda
  the last dimension of A
x[]
  Input: the vector x; Output: the product of A and x
incx
  the spacing which the elements of vector x occur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a real triangular band matrix
       1.000000    2.000000    3.000000    0.000000
       0.000000    5.000000    6.000000    7.000000
       0.000000    0.000000    9.000000    10.000000
       0.000000    0.000000    0.000000    11.000000

    and a real vector
       11.000000
       12.000000
       13.000000
       14.000000

void test_f06pgc()              //test for function dtbmv(f06pgc)
{
   int nRowCol=4;

   matrix<double> mat_input={{1,2,3,0},
                             {0,5,6,7},
                             {0,0,9,10},
                             {0,0,0,11}};
   int k_nzero=2;
   matrix<double> mat_input_band={{1,2,3},
                                  {5,6,7},
                                  {9,10,0},
                                  {11,0,0}};

   vector<double> vec_input={11,12,13,14};

   vector<double> vec_output(nRowCol);
   vec_output=vec_input;

   dtbmv(UpperTriangle,NoTranspose,NotUnitTriangular,nRowCol,k_nzero,
            mat_input_band,k_nzero+1,vec_output,1);

   printf("Compute a matrix-vector product for real tringular band matrix M*V:\n");

   printf("M=\n");                     //output mat_input
   for(int i=0;i<nRowCol;i++)
   {
       printf("       ");
       for(int j=0;j<nRowCol;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
   }

   printf("\n");                       //output vec_input
   printf("V=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("%f\n",vec_input[i]);
   }

   printf("\n");                       //output vec_output
   printf("Result vector=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("%f\n",vec_output[i]);
   }
}

   The output is as following:
Compute a matrix-vector product for real tringular band matrix M*V:
M=
       1.000000    2.000000    3.000000    0.000000
       0.000000    5.000000    6.000000    7.000000
       0.000000    0.000000    9.000000    10.000000
       0.000000    0.000000    0.000000    11.000000

V=
       11.000000
       12.000000
       13.000000
       14.000000

Result vector=
       74.000000
       236.000000
       257.000000
       154.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dtpmv

Function: dtpmv
Prototype:
void dtpmv(MatrixTriangle uplo,MatrixTranspose trans,MatrixUnitTriangular diag,int n,const double ap[],double x[],int incx)
Remarks: Compute a matrix-vector product for real triangular packed matrix
Parameters:
trans=NoTranspose, return A*x in array x[];
trans=Transpose, return transpose(A)*x in array x[];
trans=ConjugateTranspose, return ConjugateTranspose(A)*x in array x[].
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
diag specify whether or not the matrix is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
n
  the order of A
ap[]
  the real triangular packed matrix A
x[]
  Input: the vector x; Output: the product of A and x
incx
  the spacing which the elements of x occur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a real triangular packed matrix
       1.000000    2.000000    3.000000    4.000000
       0.000000    6.000000    7.000000    8.000000
       0.000000    0.000000    9.000000    10.000000
       0.000000    0.000000    0.000000    11.000000

    and a real vector
       12.000000
       13.000000
       14.000000
       15.000000

void test_f06phc()         //test for function dtpmv(f06phc)
{
    int nColRow=4;

    matrix<double> mat_input_pack={1,2,3,4,
                                     6,7,8,
                                       9,10,
                                         11};

    matrix<double> mat_input={{1,2,3,4},
                              {0,6,7,8},
                              {0,0,9,10},
                              {0,0,0,11}};

    vector<double> vec_input={12,13,14,15};

    vector<double> vec_output(nColRow);
    vec_output=vec_input;

    dtpmv(UpperTriangle,NoTranspose,NotUnitTriangular,nColRow,
             mat_input_pack,vec_output,1);

    printf("Compute a matrix-vector product for real tringular packed matrix M*V:\n");

    printf("M=\n");                     //output mat_input
    for(int i=0;i<nColRow;i++)
    {
       printf("       ");
       for(int j=0;j<nColRow;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
    }

    printf("\n");                       //output vec_input
    printf("V=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_input[i]);
    }

    printf("\n");                       //output vec_output
    printf("Result vector=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_output[i]);
    }
}

   The output is as following:
Compute a matrix-vector product for real tringular packed matrix M*V:
M=
       1.000000    2.000000    3.000000    4.000000
       0.000000    6.000000    7.000000    8.000000
       0.000000    0.000000    9.000000    10.000000
       0.000000    0.000000    0.000000    11.000000

V=
       12.000000
       13.000000
       14.000000
       15.000000

Result vector=
       140.000000
       296.000000
       276.000000
       165.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dtrsv

Function: dtrsv
Prototype:
void dtrsv(MatrixTriangle uplo,MatrixTranspose trans,MatrixUnitTriangular diag,int n,const double a[],int tda,double x[],int incx)
Remarks: Solve a system of equations for real triangular coefficient matrix
Parameters:
trans=NoTranspose, solve the equations A*x=b;
trans=Transpose, solve the equations Transpose(A)*x=b;
trans=ConjugateTranspose, solve the equations ConjugateTranspose(A)*x=b.
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
diag specify whether or not the matrix is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
n
  the order of A
a[]
  the order n real triangular coefficient matrix
tda
  the last dimension of A
x[]
  Input: the vector b; Output: the solution of the equations, vector x
incx
  the spacing which the elements of vecter x occur

Return values:
Return: NULL

Example:
    This example solve a system of equations Ax=b, where matrix A is
       1.000000    2.000000    3.000000    4.000000
       0.000000    6.000000    7.000000    8.000000
       0.000000    0.000000    9.000000    10.000000
       0.000000    0.000000    0.000000    11.000000

    and the vector b is
       12.000000
       13.000000
       14.000000
       15.000000

void test_f06pjc()         //test for function dtrsv(f06pjc)
{
    int nColRow=4;

    matrix<double> mat_input={{1,2,3,4},
                              {0,6,7,8},
                              {0,0,9,10},
                              {0,0,0,11}};

    vector<double> vec_input={12,13,14,15};

    vector<double> vec_output;
    vec_output=vec_input;

    dtrsv(UpperTriangle,NoTranspose,NotUnitTriangular,nColRow,
            mat_input,nColRow,vec_output,1);

    printf("Solve a system of equations for real triangular matrix M*X=B:\n");

    printf("M=\n");                     //output mat_inputM
    for(int i=0;i<nColRow;i++)
    {
       printf("       ");
       for(int j=0;j<nColRow;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
    }

    printf("\n");                       //output vec_inputB
    printf("B=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_input[i]);
    }

    printf("\n");                       //output vec_outputX
    printf("Result vector=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_output[i]);
    }
}

   The output is as following:
Solve a system of equations for real triangular matrix M*X=B:
M=
       1.000000    2.000000    3.000000    4.000000
       0.000000    6.000000    7.000000    8.000000
       0.000000    0.000000    9.000000    10.000000
       0.000000    0.000000    0.000000    11.000000

B=
       12.000000
       13.000000
       14.000000
       15.000000

Result vector=
       5.821549
       0.301347
       0.040404
       1.363636

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dtbsv

Function: dtbsv
Prototype:
void dtbsv(MatrixTriangle uplo,MatrixTranspose trans,MatrixUnitTriangular diag,int n,int k,const double a[],int tda,double x[],int incx)
Remarks: Solve a system of equations for real triangular band coefficient matrix
Parameters:
trans=NoTranspose, solve the equations A*x=b;
trans=Transpose, solve the equations Transpose(A)*x=b;
trans=ConjugateTranspose, solve the equations ConjugateTranspose(A)*x=b.
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
diag specify whether or not the matrix is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
n
  the oder of A
k
  the subdiagonals(superdiagonals) of A
a[]
  the real triangular band coefficient matrix A
tda
  the last dimension of A
x[]
  Input: the vector b; Output: the solution of the equations, vector x
incx
  the spacing which the elements of vector x occur

Return values:
Return: NULL

Example:
    This example solve a system of equations Ax=b, where matrix A is
       1.000000    2.000000    0.000000    0.000000
       0.000000    1.000000    2.000000    0.000000
       0.000000    0.000000    1.000000    2.000000
       0.000000    0.000000    0.000000    1.000000

    and the vector b is
       2.000000
       2.000000
       2.000000
       2.000000

void test_f06pkc()              //test for function dtbsv(f06pkc)
{
   int nRowCol=4;

   matrix<double> mat_input={{1,2,0,0},
                             {0,1,2,0},
                             {0,0,1,2},
                             {0,0,0,1}};
   int k_nzero=1;
   matrix<double> mat_input_band={{1,2},
                                 {1,2},
                                 {1,2},
                                 {1,0}};

   vector<double> vec_input={2,2,2,2};

   vector<double> vec_output(nRowCol);
   vec_output=vec_input;

   dtbsv(UpperTriangle,NoTranspose,NotUnitTriangular,nRowCol,k_nzero,
            mat_input_band,k_nzero+1,vec_output,1);

   printf("Solve a system of equations for real triangular band matrix M*X=B:\n");

   printf("M=\n");                     //output mat_inputM
   for(int i=0;i<nRowCol;i++)
   {
       printf("       ");
       for(int j=0;j<nRowCol;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
   }

   printf("\n");                       //output vec_inputB
   printf("B=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("%f\n",vec_input[i]);
   }

   printf("\n");                       //output vec_outputX
   printf("Result vector=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("%f\n",vec_output[i]);
   }

}

   The output is as following:
Solve a system of equations for real triangular band matrix M*X=B:
M=
       1.000000    2.000000    0.000000    0.000000
       0.000000    1.000000    2.000000    0.000000
       0.000000    0.000000    1.000000    2.000000
       0.000000    0.000000    0.000000    1.000000

B=
       2.000000
       2.000000
       2.000000
       2.000000

Result vector=
       -10.000000
       6.000000
       -2.000000
       2.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dtpsv

Function: dtpsv
Prototype:
void dtpsv(MatrixTriangle uplo,MatrixTranspose trans,MatrixUnitTriangular diag,int n,const double ap[],double x[],int incx)
Remarks: Solve a system of equations for real triangular packed coefficient matrix
Parameters:
trans=NoTranspose, solve the equations A*x=b;
trans=Transpose, solve the equations Transpose(A)*x=b;
trans=ConjugateTranspose, solve the equations ConjugateTranspose(A)*x=b.
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
diag specify whether or not the matrix is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
n
  the order of A
ap[]
  the real triangular packed coefficient matrix A
x[]
  Input: the vector b; Output: the solutions of the equations, vector x
incx
  the spacing which the elements of vector x occur

Return values:
Return: NULL

Example:
    This example solve a system of equations Ax=b, where matrix A is
       1.000000    2.000000    3.000000    4.000000
       0.000000    6.000000    7.000000    8.000000
       0.000000    0.000000    9.000000    10.000000
       0.000000    0.000000    0.000000    11.000000

    and the vector b is
       12.000000
       13.000000
       14.000000
       15.000000

void test_f06plc()         //test for function dtpsv(f06plc)
{
    int nColRow=4;

    matrix<double> mat_input={{1,2,3,4},
                              {0,6,7,8},
                              {0,0,9,10},
                              {0,0,0,11}};

   matrix<double> mat_input_pack={1,2,3,4,
                                    6,7,8,
                                     9,10,
                                       11};

    vector<double> vec_input={12,13,14,15};

    vector<double> vec_output;
    vec_output=vec_input;

    dtpsv(UpperTriangle,NoTranspose,NotUnitTriangular,nColRow,
            mat_input_pack,vec_output,1);

    printf("Solve a system of equations for real packed triangular matrix M*X=B:\n");

    printf("M=\n");                     //output mat_inputM
    for(int i=0;i<nColRow;i++)
    {
       printf("       ");
       for(int j=0;j<nColRow;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
    }

    printf("\n");                       //output vec_inputB
    printf("B=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_input[i]);
    }

    printf("\n");                       //output vec_outputX
    printf("Result vector=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_output[i]);
    }
}

   The output is as following:
Solve a system of equations for real packed triangular matrix M*X=B:
M=
       1.000000    2.000000    3.000000    4.000000
       0.000000    6.000000    7.000000    8.000000
       0.000000    0.000000    9.000000    10.000000
       0.000000    0.000000    0.000000    11.000000

B=
       12.000000
       13.000000
       14.000000
       15.000000

Result vector=
       5.821549
       0.301347
       0.040404
       1.363636

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dger

Function: dger
Prototype:
void dger(int m,int n,double alpha,const double x[],int incx,const double y[],int incy,double a[],int tda)
Remarks: Perform a rank-one update for real general matrix:A=alpha*x*transpose(y)+A
Parameters:
m
  the number of rows of A
n
  the number of column of A
x[]
  the vector x
incx
  the spacing which the elements of x occur
y[]
  the vector y
incy
  the spacing which the elements of y occur
a[]
  Input: the real general matrix A; Output: the matrix A after rank-one update
tda
  the last dimension of A

Return values:
Return: NULL

Example:
    This example perform a rank-one update for A, where matrix A is
       1.000000    2.000000    3.000000    4.000000
       5.000000    6.000000    7.000000    8.000000
       9.000000    10.000000    11.000000    12.000000
       13.000000    14.000000    15.000000    16.000000

    and the vector x is
       17.000000
       18.000000
       19.000000
       20.000000

    vector y is
       1.000000
       2.000000
       3.000000
       4.000000

void test_f06pmc()      //test for function dger(f06pmc)
{
    int nRows=4;
    int nCols=4;

    matrix<double> mat_input={{1,2,3,4},
                              {5,6,7,8},
                              {9,10,11,12},
                              {13,14,15,16}};

    vector<double> vec_x={17,18,19,20};
    vector<double> vec_y={1,2,3,4};

    matrix<double> mat_output;
    mat_output=mat_input;

    int i,j;

    dger(nRows,nCols,1,vec_x,1,vec_y,1,mat_output,nRows);

    printf("Perform a rank-one update for real general matrix:A=A+X*transpose(Y)\n");

    printf("A=\n");                     //output mat_inputA
    for(i=0;i<nRows;i++)
    {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
    }

    printf("\n");                       //output vec_inputX
    printf("X=\n");
    for(i=0;i<nRows;i++)
    {
      printf("       ");
      printf("%f\n",vec_x[i]);
    }

    printf("\n");                       //output vec_inputY
    printf("Y=\n");
    for(i=0;i<nCols;i++)
    {
      printf("       ");
      printf("%f\n",vec_y[i]);
    }

    printf("Result matrix A=\n");       //output mat_outputA
    for(i=0;i<nRows;i++)
    {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("%f    ",mat_output[i][j]);
       printf("\n");
    }
}

   The output is as following:
Perform a rank-one update for real general matrix:A=A+X*transpose(Y)
A=
       1.000000    2.000000    3.000000    4.000000
       5.000000    6.000000    7.000000    8.000000
       9.000000    10.000000    11.000000    12.000000
       13.000000    14.000000    15.000000    16.000000

X=
       17.000000
       18.000000
       19.000000
       20.000000

Y=
       1.000000
       2.000000
       3.000000
       4.000000
Result matrix A=
       18.000000    36.000000    54.000000    72.000000
       23.000000    42.000000    61.000000    80.000000
       28.000000    48.000000    68.000000    88.000000
       33.000000    54.000000    75.000000    96.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dsyr

Function: dsyr
Prototype:
void dsyr(MatrixTriangle uplo,int n,double alpha,const double x[],int incx,double a[],int tda)
Remarks: Perform a rank-one update for real symmetric matrix:A=alpha*x*Transpose(x)+A
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of A
x[]
  vector x
incx
  the spacing which the elements of x occur
a[]
  Input: the real symmetric matrix A; Output: matrix A after update
tda
  the last dimension of A

Return values:
Return: NULL

Example:
    This example perform a rank-one update for A, where matrix A is
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       3.000000    7.000000    11.000000    12.000000
       4.000000    8.000000    12.000000    16.000000

    and the vector x is
       1.000000
       1.000000
       1.000000
       1.000000

void test_f06ppc()      //test for function dsyr(f06ppc)
{
    int nColRows=4;

    matrix<double> mat_input={{1,2,3,4},
                              {2,6,7,8},
                              {3,7,11,12},
                              {4,8,12,16}};

    vector<double> vec_x={1,1,1,1};

    matrix<double> mat_output;
    mat_output=mat_input;

    int i,j;

    dsyr(UpperTriangle,nColRows,1,vec_x,1,mat_output,nColRows);

    for(i=0;i<nColRows;i++)
        for(j=0;j<i;j++)
            mat_output[i][j]=mat_output[j][i];

    printf("Perform a rank-one update for real symmetric matrix:A=A+X*transpose(X)\n");

    printf("A=\n");                     //output mat_inputA
    for(i=0;i<nColRows;i++)
    {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
    }

    printf("\n");                       //output vec_inputX
    printf("X=\n");
    for(i=0;i<nColRows;i++)
    {
      printf("       ");
      printf("%f\n",vec_x[i]);
    }

    printf("Result matrix A=\n");       //output mat_outputA
    for(i=0;i<nColRows;i++)
    {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("%f    ",mat_output[i][j]);
       printf("\n");
    }
}

   The output is as following:
Perform a rank-one update for real symmetric matrix:A=A+X*transpose(X)
A=
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       3.000000    7.000000    11.000000    12.000000
       4.000000    8.000000    12.000000    16.000000

X=
       1.000000
       1.000000
       1.000000
       1.000000
Result matrix A=
       2.000000    3.000000    4.000000    5.000000
       3.000000    7.000000    8.000000    9.000000
       4.000000    8.000000    12.000000    13.000000
       5.000000    9.000000    13.000000    17.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dspr

Function: dspr
Prototype:
void dspr(MatrixTriangle uplo,int n,double alpha,const double x[],int incx,double ap[])
Remarks: Perform a rank-one update for real symmetric packed matrix:A=alpha*x*Transpose(x)+A
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of A
x[]
  the vector x
incx
  the spacing which the elements of x occur
ap[]
  Input: the real symmetrix packed matrix A; Output: matrix A after update

Return values:
Return: NULL

Example:
    This example perform a rank-one update for A, where matrix A is
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       2.000000    7.000000    9.000000    10.000000
       4.000000    8.000000    10.000000    11.000000

    and the vector x is
       12.000000
       13.000000
       14.000000
       15.000000

void test_f06pqc()         //test for function dspr(f06pqc)
{
    int nColRow=4;

    matrix<double> mat_input_pack={1,2,3,4,
                                     6,7,8,
                                       9,10,
                                         11};

    matrix<double> mat_input={{1,2,3,4},
                              {2,6,7,8},
                              {2,7,9,10},
                              {4,8,10,11}};

    vector<double> vec_input={12,13,14,15};

    matrix<double> mat_output_pack(mat_input_pack);
    matrix<double> mat_output(nColRow,nColRow);

    dspr(UpperTriangle,nColRow,1,vec_input,1,mat_output_pack);

    int i,j;
    int k=0;
    for(i=0;i<nColRow;i++)
        for(j=i;j<nColRow;j++)
            mat_output[i][j]=mat_output_pack[0][k++];

    for(i=0;i<nColRow;i++)
        for(j=0;j<i;j++)
            mat_output[i][j]=mat_output[j][i];

    printf("Perform a rank-one update for real symmetric packed matrix:A=A+X*transpose(X)\n");

    printf("A=\n");                     //output mat_input
    for(i=0;i<nColRow;i++)
    {
       printf("       ");
       for(j=0;j<nColRow;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
    }

    printf("\n");                       //output vec_input
    printf("X=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_input[i]);
    }

    printf("\n");                       //output mat_output
    printf("Result matrix A=\n");
    for(i=0;i<nColRow;i++)
    {
        for(j=0;j<nColRow;j++)
        {
            printf("       ");
            printf("%f",mat_output[i][j]);
        }
        printf("\n");
    }
}

   The output is as following:
Perform a rank-one update for real symmetric packed matrix:A=A+X*transpose(X)
A=
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       2.000000    7.000000    9.000000    10.000000
       4.000000    8.000000    10.000000    11.000000

X=
       12.000000
       13.000000
       14.000000
       15.000000

Result matrix A=
       145.000000       158.000000       171.000000       184.000000
       158.000000       175.000000       189.000000       203.000000
       171.000000       189.000000       205.000000       220.000000
       184.000000       203.000000       220.000000       236.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dsyr2

Function: dsyr2
Prototype:
void dsyr2(MatrixTriangle uplo,int n,double alpha,const double x[],int incx,const double y[],int incy,double a[],int tda)
Remarks: Perform a rank-two update for real symmetric matrix:A=alpha*x*Transpose(y)+alpha*y*Transpose(x)+A
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of A
x[]
  the vector x
incx
  the spacing which the elements of x occur
y[]
  the vector y
incy
  the spacing which the elements of y occur
a[]
  Input: the real symmetric matrix A; Output: matrix A after update
tda
  the last dimension of A

Return values:
Return: NULL

Example:
    This example perform a rank-two update for A, where matrix A is
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       3.000000    7.000000    11.000000    12.000000
       4.000000    8.000000    12.000000    16.000000

    and the vector x is
       1.000000
       1.000000
       1.000000
       1.000000

    and the vector y is
       2.000000
       2.000000
       2.000000
       2.000000

void test_f06prc()      //test for function dsyr2(f06prc)
{
    int nColRows=4;

    matrix<double> mat_input={{1,2,3,4},
                              {2,6,7,8},
                              {3,7,11,12},
                              {4,8,12,16}};

    vector<double> vec_x={1,1,1,1};
    vector<double> vec_y={2,2,2,2};

    matrix<double> mat_output;
    mat_output=mat_input;

    int i,j;

    dsyr2(UpperTriangle,nColRows,1,vec_x,1,vec_y,1,mat_output,nColRows);

    for(i=0;i<nColRows;i++)
        for(j=0;j<i;j++)
            mat_output[i][j]=mat_output[j][i];

    printf("Perform a rank-two update for real symmetric matrix:A=A+X*transpose(Y)+Y*transpose(X)\n");

    printf("A=\n");                     //output mat_inputA
    for(i=0;i<nColRows;i++)
    {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
    }

    printf("\n");                       //output vec_inputX
    printf("X=\n");
    for(i=0;i<nColRows;i++)
    {
      printf("       ");
      printf("%f\n",vec_x[i]);
    }

    printf("\n");                       //output vec_inputY
    printf("Y=\n");
    for(i=0;i<nColRows;i++)
    {
      printf("       ");
      printf("%f\n",vec_y[i]);
    }

    printf("Result matrix A=\n");       //output mat_outputA
    for(i=0;i<nColRows;i++)
    {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("%f    ",mat_output[i][j]);
       printf("\n");
    }
}

   The output is as following:
Perform a rank-two update for real symmetric matrix:A=A+X*transpose(Y)+Y*transpose(X)
A=
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       3.000000    7.000000    11.000000    12.000000
       4.000000    8.000000    12.000000    16.000000

X=
       1.000000
       1.000000
       1.000000
       1.000000

Y=
       2.000000
       2.000000
       2.000000
       2.000000
Result matrix A=
       5.000000    6.000000    7.000000    8.000000
       6.000000    10.000000    11.000000    12.000000
       7.000000    11.000000    15.000000    16.000000
       8.000000    12.000000    16.000000    20.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dspr2

Function: dspr2
Prototype:
void dspr2(MatrixTriangle uplo,int n,double alpha,const double x[],int incx,const double y[],int incy,double ap[])
Remarks: Perform a rank-two update for real symmetric packed matrix:A=alpha*x*Transpose(y)+alpha*y*Transpose(x)+A
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of A
x[]
  the vector x
incx
  the spacing which the elements of x occur
y[]
  the vector y
incy
  the spacing which the elements of y occur
ap[]
  Input: the real symmetric packed matrix A; Output: matrix A after update

Return values:
Return: NULL

Example:
    This example perform a rank-two update for A, where matrix A is
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       2.000000    7.000000    9.000000    10.000000
       4.000000    8.000000    10.000000    11.000000

    and the vector x is
       12.000000
       13.000000
       14.000000
       15.000000

    and the vector y is
       1.000000
       1.000000
       1.000000
       1.000000

void test_f06psc()         //test for function dspr2(f06psc)
{
    int nColRow=4;

    matrix<double> mat_input_pack={1,2,3,4,
                                     6,7,8,
                                       9,10,
                                         11};

    matrix<double> mat_input={{1,2,3,4},
                              {2,6,7,8},
                              {2,7,9,10},
                              {4,8,10,11}};

    vector<double> vec_x={12,13,14,15};
    vector<double> vec_y={1,1,1,1};

    matrix<double> mat_output_pack(mat_input_pack);
    matrix<double> mat_output(nColRow,nColRow);

    dspr2(UpperTriangle,nColRow,1,vec_x,1,vec_y,1,mat_output_pack);

    int i,j;
    int k=0;
    for(i=0;i<nColRow;i++)
        for(j=i;j<nColRow;j++)
            mat_output[i][j]=mat_output_pack[0][k++];

    for(i=0;i<nColRow;i++)
        for(j=0;j<i;j++)
            mat_output[i][j]=mat_output[j][i];

    printf("Perform a rank-two update for real symmetric packed matrix:A=A+X*transpose(Y)+Y*transpose(X)\n");

    printf("A=\n");                     //output mat_input
    for(i=0;i<nColRow;i++)
    {
       printf("       ");
       for(j=0;j<nColRow;j++)
          printf("%f    ",mat_input[i][j]);
       printf("\n");
    }

    printf("\n");                       //output vec_X
    printf("X=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_x[i]);
    }

    printf("\n");                       //output vec_Y
    printf("Y=\n");
    for(i=0;i<nColRow;i++)
    {
      printf("       ");
      printf("%f\n",vec_y[i]);
    }

    printf("\n");                       //output mat_output
    printf("Result matrix A=\n");
    for(i=0;i<nColRow;i++)
    {
        for(j=0;j<nColRow;j++)
        {
            printf("       ");
            printf("%f",mat_output[i][j]);
        }
        printf("\n");
    }
}

   The output is as following:
Perform a rank-two update for real symmetric packed matrix:A=A+X*transpose(Y)+Y*transpose(X)
A=
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       2.000000    7.000000    9.000000    10.000000
       4.000000    8.000000    10.000000    11.000000

X=
       12.000000
       13.000000
       14.000000
       15.000000

Y=
       1.000000
       1.000000
       1.000000
       1.000000

Result matrix A=
       25.000000       27.000000       29.000000       31.000000
       27.000000       32.000000       34.000000       36.000000
       29.000000       34.000000       37.000000       39.000000
       31.000000       36.000000       39.000000       41.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zgemv

Function: zgemv
Prototype:
void zgemv(MatrixTranspose trans,int m,int n,complex alpha,const complex a[],int tda,const complex x[],int incx,complex beta,complex y[],int incy)
Remarks: Compute a matrix-vector product for complex general matrix
Parameters:
trans=NoTranspose, return (alpha*Ax+beta*y) in array y[];
trans=Transpose, return (alpha*transpose(A)*x+beta*y) in array y[];
trans=ConjugateTranspose, return (alpha*ConjugateTranspose(A)*x+beta*y) in array y[].
m
  the number of rows of A
n
  the number of columns of A
a[]
  the m by n complex matrix A
tda
  the last dimension of A
x[]
  the vector x
incx
  the spacing which the elements of the vector x occur
y[]
  Input: the vecor y; Output: alpha*trans(A)*x+beta*y
incy
  the spacing which the elements of the vector y occur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a general complex matrix
        1+2i,8+3i,2+3i,3+4i
        2+1i,3+1i,5+2i,4+4i
        1+3i,2+1i,2+3i,5+4i
        1+4i,2+3i,6+1i,2+4i

    and a vector
       2+2i
       1+1i
       3+2i
       2+4i.

void test_f06sac()    //test for function zgemv(f06sac)
{
   int nRows=4;
   int nCols=4;

   matrix<complex>  mat_input={{1+2i,8+3i,2+3i,3+4i},
                               {2+1i,3+1i,5+2i,4+4i},
                               {1+3i,2+1i,2+3i,5+4i},
                               {1+4i,2+3i,6+1i,2+4i}};

   vector<complex>  vec_input={2+2i,1+1i,3+2i,2+4i};

   vector<complex>  vec_output(nRows);
   vec_output=0;

   zgemv(NoTranspose,nRows,nCols,1,mat_input,nCols,vec_input,1,1,vec_output,1);

   printf("Compute a matrix-vector product for general complex matrix M*V:\n");

   printf("M=\n");                     //output mat_input
   for(int i=0;i<nRows;i++)
   {
       printf("       ");
       for(int j=0;j<nCols;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_input
   printf("V=\n");
   for(i=0;i<nRows;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_input[i].m_re,vec_input[i].m_im);
   }

   printf("\n");                       //output vec_output
   printf("Result vector=\n");
   for(i=0;i<nRows;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_output[i].m_re,vec_output[i].m_im);
   }
}

    The output is following:

Compute a matrix-vector product for general complex matrix M*V:
M=
       (1.000000,2.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (2.000000,1.000000i)    (3.000000,1.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (1.000000,3.000000i)    (2.000000,1.000000i)    (2.000000,3.000000i)    (5.000000,4.000000i)
       (1.000000,4.000000i)    (2.000000,3.000000i)    (6.000000,1.000000i)    (2.000000,4.000000i)

V=
       (2.000000,2.000000i)
       (1.000000,1.000000i)
       (3.000000,2.000000i)
       (2.000000,4.000000i)

Result vector=
       (-7.000000,50.000000i)
       (7.000000,50.000000i)
       (-9.000000,52.000000i)
       (-3.000000,46.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zgbmv

Function: zgbmv
Prototype:
void zgbmv(MatrixTranspose trans,int m,int n,int kl,int ku,complex alpha,const complex a[],int tda,const complex x[],int incx,complex beta,complex y[],int incy)
Remarks: Compute a matrix-vector product for complex general band matrix
Parameters:
trans=NoTranspose, return (alpha*Ax+beta*y) in array y[];
trans=Transpose, return (alpha*transpose(A)*x+beta*y) in array y[];
trans=ConjugateTranspose, return (alpha*ConjugateTranspose(A)*x+beta*y) in array y[].
m
  the number of rows of A
n
  the number of columns of A
kl
  the subdiagonals of matrix A
ku
  the superdiagonals of matrix A
a[]
  the m by n general complex matrix A
tda
  the last dimension of A
x[]
  complex vector x
incx
  the spacing which the elements of the vector x occur
y[]
  Input:complex vector y; Output: alpha*trans(A)*x+beta*y
incy
  the spacing which the elements of the vector y occur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a complex general matrix
       (1.000000,1.200000i)    (2.000000,2.100000i)    (3.000000,1.000000i)    (0.000000,0.000000i)
       (4.000000,2.600000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (7.000000,4.100000i)
       (0.000000,0.000000i)    (8.000000,1.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
    which is stored in band storage and a complex vector
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

void test_f06sbc()     //test for function zgbmv(f06sbc)
{
   int nRows=3;
   int nCols=4;

   matrix<complex> mat_input={{1+1.2i,2+2.1i,3+1.0i,0},
                             {4+2.6i,5+1.2i,6+2.6i,7+4.1i},
                             {0,8+1i,9,10+2i}};
   int kupper=2;
   int klower=1;
   matrix<complex> mat_input_band={{0,1+1.2i,2+2.1i,3+1.0i},
                                  {4+2.6i,5+1.2i,6+2.6i,7+4.1i},
                                  {8+1i,9,10+2i,0}};

   vector<complex> vec_input={11+2i,12,13+2i,14+1.8i};

   vector<complex> vec_output(nRows);
   vec_output=0;

   zgbmv(NoTranspose,nRows,nCols,klower,kupper,1,mat_input_band,nCols,vec_input,1,1,vec_output,1);

   printf("Compute a matrix-vector product for complex band matrix M*V:\n");

   printf("M=\n");                     //output mat_input
   for(int i=0;i<nRows;i++)
   {
       printf("       ");
       for(int j=0;j<nCols;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_input
   printf("V=\n");
   for(i=0;i<nCols;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_input[i].m_re,vec_input[i].m_im);
   }

   printf("\n");                       //output vec_output
   printf("Result vector=\n");
   for(i=0;i<nRows;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_output[i].m_re,vec_output[i].m_im);
   }
}

   The output is as following:
Compute a matrix-vector product for complex band matrix M*V:
M=
       (1.000000,1.200000i)    (2.000000,2.100000i)    (3.000000,1.000000i)    (0.000000,0.000000i)
       (4.000000,2.600000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (7.000000,4.100000i)
       (0.000000,0.000000i)    (8.000000,1.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)

V=
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

Result vector=
       (69.600000,59.400000i)
       (262.220000,166.800000i)
       (349.400000,76.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zhemv

Function: zhemv
Prototype:
void zhemv(MatrixTriangle uplo,int n,complex alpha,const complex a[],int tda,const complex x[],int incx,complex beta,complex y[],int incy)
Remarks: Compute a matrix-vector product for complex Hermitian matrix
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of complex Hermitian matrix A
a[]
  order n complex Hermitian matrix A
tda
  the last dimension of A
x[]
  complex vector
incx
  the spacing which the elements of the vector x occur
y[]
  Input: complex vector y; Output: alpha*Ax+beta*y
incy
  the spacing which the elements of the vector y occuur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a complex Hermitian matrix
       (1.000000,0.000000i)    (2.000000,2.100000i)    (3.000000,1.000000i)    (4.000000,1.300000i)
       (2.000000,-2.100000i)   (5.000000,0.000000i)    (6.000000,2.600000i)    (7.000000,4.100000i)
       (3.000000,-1.000000i)   (6.000000,-2.600000i)   (9.000000,0.000000i)    (10.000000,2.000000i)
       (4.000000,-1.300000i)   (7.000000,-4.100000i)   (10.000000,-2.000000i)  (11.000000,0.000000i)

    and a complex vector
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

void test_f06scc()      //test for function zhemv(f06scc)
{
   int nRowCol=4;

   matrix<complex> mat_input={{1,2+2.1i,3+1.0i,4+1.3i},
                             {2-2.1i,5,6+2.6i,7+4.1i},
                             {3-1.0i,6-2.6i,9,10+2i},
                             {4-1.3i,7-4.1i,10-2i,11}};

   vector<complex> vec_input={11+2i,12,13+2i,14+1.8i};

   vector<complex> vec_output(nRowCol);
   vec_output=0;

   zhemv(UpperTriangle,nRowCol,1,mat_input,nRowCol,vec_input,1,1,vec_output,1);

   printf("Compute a matrix-vector product for complex Hermitian matrix M*V:\n");

   printf("M=\n");                     //output mat_input
   for(int i=0;i<nRowCol;i++)
   {
       printf("       ");
       for(int j=0;j<nRowCol;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_input
   printf("V=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_input[i].m_re,vec_input[i].m_im);
   }

   printf("\n");                       //output vec_output
   printf("Result vector=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_output[i].m_re,vec_output[i].m_im);
   }
}

   The output is as following:
Compute a matrix-vector product for complex Hermitian matrix M*V:
M=
       (1.000000,0.000000i)    (2.000000,2.100000i)    (3.000000,1.000000i)    (4.000000,1.300000i)
       (2.000000,-2.100000i)    (5.000000,0.000000i)    (6.000000,2.600000i)    (7.000000,4.100000i)
       (3.000000,-1.000000i)    (6.000000,-2.600000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (4.000000,-1.300000i)    (7.000000,-4.100000i)    (10.000000,-2.000000i)    (11.000000,0.000000i)

V=
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

Result vector=
       (125.660000,71.600000i)
       (249.620000,96.700000i)
       (360.400000,27.800000i)
       (418.600000,-41.700000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zhbmv

Function: zhbmv
Prototype:
void zhbmv(MatrixTriangle uplo,int n,int k,complex alpha,const complex a[],int tda,const complex x[],int incx,complex beta,complex y[],int incy)
Remarks: Compute a matrix-vector product for complex Hermitian band matrix
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of Hermitian band matrix A
k
  the subdiagonals (superdiagonals) of A
a[]
  the complex Hermitian band matrix A
tda
  the last dimension of A
x[]
  vector x
incx
  the spacing which the elements of vector x occur
y[]
  Input: vector y; Output: alpha*Ax+beta*y
incy
  the spacing which the elements of vector y occur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a complex Hermitian band matrix
       (1.000000,0.000000i)    (2.000000,2.100000i)    (0.000000,0.000000i)    (0.000000,0.000000i)
       (2.000000,-2.100000i)    (5.000000,0.000000i)    (6.000000,2.600000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (6.000000,-2.600000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (10.000000,-2.000000i)    (11.000000,0.000000i)

    and a complex vector
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

void test_f06sdc()      //test for function zhbmv(f06sdc)
{
   int nRowCol=4;

   matrix<complex> mat_input={{1,2+2.1i,0,0},
                             {2-2.1i,5,6+2.6i,0},
                             {0,6-2.6i,9,10+2i},
                             {0,0,10-2i,11}};

   int k_nzero=1;
   matrix<complex> mat_input_band={{1,2+2.1i},
                                   {5,6+2.6i},
                                   {9,10+2i},
                                   {11,0}};

   vector<complex> vec_input={11+2i,12,13+2i,14+1.8i};

   vector<complex> vec_output(nRowCol);
   vec_output=0;

   zhbmv(UpperTriangle,nRowCol,k_nzero,1,mat_input_band,k_nzero+1,vec_input,1,1,vec_output,1);

   printf("Compute a matrix-vector product for complex Hermitian band matrix M*V:\n");

   printf("M=\n");                     //output mat_input
   for(int i=0;i<nRowCol;i++)
   {
       printf("       ");
       for(int j=0;j<nRowCol;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_input
   printf("V=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_input[i].m_re,vec_input[i].m_im);
   }

   printf("\n");                       //output vec_output
   printf("Result vector=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_output[i].m_re,vec_output[i].m_im);
   }
}

   The output is as following:
Compute a matrix-vector product for complex Hermitian band matrix M*V:
M=
       (1.000000,0.000000i)    (2.000000,2.100000i)    (0.000000,0.000000i)    (0.000000,0.000000i)
       (2.000000,-2.100000i)    (5.000000,0.000000i)    (6.000000,2.600000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (6.000000,-2.600000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (10.000000,-2.000000i)    (11.000000,0.000000i)

V=
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

Result vector=
       (35.000000,27.200000i)
       (159.000000,26.700000i)
       (325.400000,32.800000i)
       (288.000000,13.800000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zhpmv

Function: zhpmv
Prototype:
void zhpmv(MatrixTriangle uplo,int n,complex alpha,const complex ap[],const complex x[],int incx,complex beta,complex y[],int incy)
Remarks: Compute a matrix-vector product for complex Hermitian packed matrix
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of the complex Hermitian matrix A
ap[]
  order n complex Hermitian matrix A in packed storage
x[]
  vector x
incx
  the spacing which the elements of vector x occur
y[]
  Input: vector y; Output: alpha*Ax+beta*y
incy
  the spacing which the elements of vector y occur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a complex Hermitian packed matrix
       (1.000000,0.000000i)     (2.000000,2.100000i)    (3.000000,1.000000i)    (4.000000,1.300000i)
       (2.000000,-2.100000i)    (5.000000,0.000000i)    (6.000000,2.600000i)    (7.000000,4.100000i)
       (3.000000,-1.000000i)    (6.000000,-2.600000i)   (9.000000,0.000000i)    (10.000000,2.000000i)
       (4.000000,-1.300000i)    (7.000000,-4.100000i)   (10.000000,-2.000000i)  (11.000000,0.000000i)

    and a complex vector
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

void test_f06sec()      //test for function zhpmv(f06sec)
{
   int nRowCol=4;

   matrix<complex> mat_input={{1,2+2.1i,3+1.0i,4+1.3i},
                             {2-2.1i,5,6+2.6i,7+4.1i},
                             {3-1.0i,6-2.6i,9,10+2i},
                             {4-1.3i,7-4.1i,10-2i,11}};

   matrix<complex> mat_input_pack={1,2+2.1i,3+1.0i,4+1.3i,
                                          5,6+2.6i,7+4.1i,
                                                       9,10+2i,
                                                         11};

   vector<complex> vec_input={11+2i,12,13+2i,14+1.8i};

   vector<complex> vec_output(nRowCol);
   vec_output=0;

   zhpmv(UpperTriangle,nRowCol,1,mat_input_pack,vec_input,1,1,vec_output,1);

   printf("Compute a matrix-vector product for complex packed Hermitian matrix M*V:\n");

   printf("M=\n");                     //output mat_input
   for(int i=0;i<nRowCol;i++)
   {
       printf("       ");
       for(int j=0;j<nRowCol;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_input
   printf("V=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_input[i].m_re,vec_input[i].m_im);
   }

   printf("\n");                       //output vec_output
   printf("Result vector=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_output[i].m_re,vec_output[i].m_im);
   }
}

   The output is as following:
Compute a matrix-vector product for complex packed Hermitian matrix M*V:
M=
       (1.000000,0.000000i)    (2.000000,2.100000i)    (3.000000,1.000000i)    (4.000000,1.300000i)
       (2.000000,-2.100000i)    (5.000000,0.000000i)    (6.000000,2.600000i)    (7.000000,4.100000i)
       (3.000000,-1.000000i)    (6.000000,-2.600000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (4.000000,-1.300000i)    (7.000000,-4.100000i)    (10.000000,-2.000000i)    (11.000000,0.000000i)

V=
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

Result vector=
       (125.660000,71.600000i)
       (249.620000,96.700000i)
       (360.400000,27.800000i)
       (418.600000,-41.700000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


ztrmv

Function: ztrmv
Prototype:
void ztrmv(MatrixTriangle uplo,MatrixTranspose trans,MatrixUnitTriangular diag,int n,const complex a[],int tda,complex x[],int incx)
Remarks: Compute a matrix-vector product for complex triangular matrix
Parameters:
trans=NoTranspose, return A*x in array x[];
trans=Transpose, return transpose(A)*x in array x[];
trans=ConjugateTranspose, return ConjugateTranspose(A)*x in array x[].
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
diag specify whether or not the matrix is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
n
  the order of the complex triangular matrix A
a[]
  order n complex triangular matrix A
tda
  the last dimension of A
x[]
  Input: the complex vector x; Output: the product of A and x
incx
  the spacing which the elemnets of x occur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a complex triangular matrix
       (1.000000,1.200000i)    (2.000000,2.100000i)    (4.000000,0.500000i)    (1.000000,0.000000i)
       (0.000000,0.000000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (2.000000,1.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (11.000000,4.000000i)

    and a complex vector
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

void test_f06sfc()      //test for function ztrmv(f06sfc)
{
   int nRowCol=4;

   matrix<complex> mat_input={{1+1.2i,2+2.1i,4+0.5i,1},
                              {0,5+1.2i,6+2.6i,2+1i},
                               {0,0,9,10+2i},
                               {0,0,0,11+4i}};

   int k_nzero=1;

   vector<complex> vec_input={11+2i,12,13+2i,14+1.8i};

   vector<complex> vec_output(nRowCol);
   vec_output=vec_input;

   ztrmv(UpperTriangle,NoTranspose,NotUnitTriangular,nRowCol,
            mat_input,nRowCol,vec_output,1);

   printf("Compute a matrix-vector product for complex Hermitian band matrix M*V:\n");

   printf("M=\n");                     //output mat_input
   for(int i=0;i<nRowCol;i++)
   {
       printf("       ");
       for(int j=0;j<nRowCol;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_input
   printf("V=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_input[i].m_re,vec_input[i].m_im);
   }

   printf("\n");                       //output vec_output
   printf("Result vector=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_output[i].m_re,vec_output[i].m_im);
   }
}

   The output is as following:
Compute a matrix-vector product for complex Hermitian band matrix M*V:
M=
       (1.000000,1.200000i)    (2.000000,2.100000i)    (4.000000,0.500000i)    (1.000000,0.000000i)
       (0.000000,0.000000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (2.000000,1.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (11.000000,4.000000i)

V=
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

Result vector=
       (97.600000,56.700000i)
       (159.000000,77.800000i)
       (253.400000,64.000000i)
       (146.800000,75.800000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


ztbmv

Function: ztbmv
Prototype:
void ztbmv(MatrixTriangle uplo,MatrixTranspose trans,MatrixUnitTriangular diag,int n,int k,const complex a[],int tda,complex x[],int incx)
Remarks: Compute a matrix-vector product for complex triangular band matrix
Parameters:
trans=NoTranspose, return A*x in array x[];
trans=Transpose, return transpose(A)*x in array x[];
trans=ConjugateTranspose, return ConjugateTranspose(A)*x in array x[].
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
diag specify whether or not the matrix is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a complex triangular band matrix
       (1.000000,1.200000i)    (2.000000,2.100000i)    (0.000000,0.000000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (11.000000,4.000000i)

    and a complex vector
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

void test_f06sgc()      //test for function ztbmv(f06sgc)
{
   int nRowCol=4;

   matrix<complex> mat_input={{1+1.2i,2+2.1i,0,0},
                             {0,5+1.2i,6+2.6i,0},
                             {0,0,9,10+2i},
                             {0,0,0,11+4i}};

   int k_nzero=1;
   matrix<complex> mat_input_band={{1+1.2i,2+2.1i},
                             {5+1.2i,6+2.6i},
                             {9,10+2i},
                             {11+4i,0}};

   vector<complex> vec_input={11+2i,12,13+2i,14+1.8i};

   vector<complex> vec_output(nRowCol);
   vec_output=vec_input;

   ztbmv(UpperTriangle,NoTranspose,NotUnitTriangular,nRowCol,k_nzero,
             mat_input_band,k_nzero+1,vec_output,1);

   printf("Compute a matrix-vector product for complex triangular band matrix M*V:\n");

   printf("M=\n");                     //output mat_input
   for(int i=0;i<nRowCol;i++)
   {
       printf("       ");
       for(int j=0;j<nRowCol;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_input
   printf("V=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_input[i].m_re,vec_input[i].m_im);
   }

   printf("\n");                       //output vec_output
   printf("Result vector=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_output[i].m_re,vec_output[i].m_im);
   }
}

   The output is as following:
Compute a matrix-vector product for complex triangular band matrix M*V:
M=
       (1.000000,1.200000i)    (2.000000,2.100000i)    (0.000000,0.000000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (11.000000,4.000000i)

V=
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

Result vector=
       (32.600000,40.400000i)
       (132.800000,60.200000i)
       (253.400000,64.000000i)
       (146.800000,75.800000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


ztpmv

Function: ztpmv
Prototype:
void ztpmv(MatrixTriangle uplo,MatrixTranspose trans,MatrixUnitTriangular diag,int n,const complex ap[],complex x[],int incx)
Remarks: Compute a matrix-vector product for complex triangular packed matrix
Parameters:
trans=NoTranspose, return A*x in array x[];
trans=Transpose, return transpose(A)*x in array x[];
trans=ConjugateTranspose, return ConjugateTranspose(A)*x in array x[].
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
diag specify whether or not the matrix is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
n
  the order of A
ap[]
  the complex triangular packed matrix A
x[]
  Input: the vector x; Output: the product of A and x
incx
  the spacing which the elements of x occur

Return values:
Return: NULL

Example:
    This example computes the matrix-vector product for a complex triangular packed matrix
       (1.000000,1.200000i)    (2.000000,2.100000i)    (0.000000,0.000000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (11.000000,4.000000i)

    and a complex vector
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

void test_f06shc()         //test for function ztpmv(f06shc)
{
    int nRowCol=4;

    matrix<complex> mat_input_pack={1+1.2i,2+2.1i,0,0,
                                      5+1.2i,6+2.6i,0,
                                              9,10+2i,
                                                11+4i};

    matrix<complex> mat_input={{1+1.2i,2+2.1i,0,0},
                               {0,5+1.2i,6+2.6i,0},
                               {0,0,9,10+2i},
                               {0,0,0,11+4i}};

    vector<complex> vec_input={11+2i,12,13+2i,14+1.8i};

    vector<complex> vec_output(nRowCol);
    vec_output=vec_input;

    ztpmv(UpperTriangle,NoTranspose,NotUnitTriangular,nRowCol,
             mat_input_pack,vec_output,1);

    printf("Compute a matrix-vector product for complex tringular packed matrix M*V:\n");

    printf("M=\n");                     //output mat_input
   for(int i=0;i<nRowCol;i++)
   {
       printf("       ");
       for(int j=0;j<nRowCol;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_input
   printf("V=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_input[i].m_re,vec_input[i].m_im);
   }

   printf("\n");                       //output vec_output
   printf("Result vector=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_output[i].m_re,vec_output[i].m_im);
   }
}

   The output is as following:
Compute a matrix-vector product for complex tringular packed matrix M*V:
M=
       (1.000000,1.200000i)    (2.000000,2.100000i)    (0.000000,0.000000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (11.000000,4.000000i)

V=
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

Result vector=
       (32.600000,40.400000i)
       (132.800000,60.200000i)
       (253.400000,64.000000i)
       (146.800000,75.800000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


ztrsv

Function: ztrsv
Prototype:
void ztrsv(MatrixTriangle uplo,MatrixTranspose trans,MatrixUnitTriangular diag,int n,const complex a[],int tda,complex x[],int incx)
Remarks: Solve a system of equations for complex triangular coefficient matrix
Parameters:
trans=NoTranspose, solve the equations A*x=b;
trans=Transpose, solve the equations Transpose(A)*x=b;
trans=ConjugateTranspose, solve the equations ConjugateTranspose(A)*x=b.
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
diag specify whether or not the matrix is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
n
  the order of A
a[]
  the order n complex triangular coefficient matrix A
tda
  the last dimension of A
x[]
  Input: the vctor b; Output: the solution of the equations, vector x
incx
  the spacing which the elements of vector x occur

Return values:
Return: NULL

Example:
    This example solve a system of equations Ax=b, where matrix A is
       (1.000000,1.200000i)    (2.000000,2.100000i)    (4.000000,0.500000i)    (1.000000,0.000000i)
       (0.000000,0.000000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (2.000000,1.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (11.000000,4.000000i)

    and the vector b is
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

void test_f06sjc()      //test for function ztrsv(f06sjc)
{
   int nRowCol=4;

   matrix<complex> mat_input={{1+1.2i,2+2.1i,4+0.5i,1},
                              {0,5+1.2i,6+2.6i,2+1i},
                               {0,0,9,10+2i},
                               {0,0,0,11+4i}};

   vector<complex> vec_input={11+2i,12,13+2i,14+1.8i};

   vector<complex> vec_output(nRowCol);
   vec_output=vec_input;

   ztrsv(UpperTriangle,NoTranspose,NotUnitTriangular,nRowCol,
            mat_input,nRowCol,vec_output,1);

   printf("Solve a system of equations for complex triangular matrix M*X=B:\n");

   printf("M=\n");                     //output mat_inputM
   for(int i=0;i<nRowCol;i++)
   {
       printf("       ");
       for(int j=0;j<nRowCol;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_inputB
   printf("B=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_input[i].m_re,vec_input[i].m_im);
   }

   printf("\n");                       //output vec_outputX
   printf("Result vector=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_output[i].m_re,vec_output[i].m_im);
   }
}

   The output is as following:
Solve a system of equations for complex triangular matrix M*X=B:
M=
       (1.000000,1.200000i)    (2.000000,2.100000i)    (4.000000,0.500000i)    (1.000000,0.000000i)
       (0.000000,0.000000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (2.000000,1.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (11.000000,4.000000i)

B=
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

Result vector=
       (1.498443,-2.397366i)
       (1.702533,-0.884189i)
       (0.078345,0.254339i)
       (1.176642,-0.264234i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


ztbsv

Function: ztbsv
Prototype:
void ztbsv(MatrixTriangle uplo,MatrixTranspose trans,MatrixUnitTriangular diag,int n,int k,const complex a[],int tda,complex x[],int incx)
Remarks: Solve a system of equations for complex triangular band coefficient matrix
Parameters:
trans=NoTranspose, solve the equations A*x=b;
trans=Transpose, solve the equations Transpose(A)*x=b;
trans=ConjugateTranspose, solve the equations ConjugateTranspose(A)*x=b.
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
diag specify whether or not the matrix is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
n
  the order of A
k
  the subdiagonals(superdiagonals) of A
a[]
  the complex triangular band coefficient matrix A
tda
  the last dimension of A
x[]
  Input: the vector b; Output: the solution of the equations, vector x
incx
  the spacing which the elements of vector x occur

Return values:
Return: NULL

Example:
    This example solve a system of equations Ax=b, where matrix A is
       (1.000000,1.200000i)    (2.000000,2.100000i)    (0.000000,0.000000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (11.000000,4.000000i)

    and the vector b is
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

void test_f06skc()      //test for function ztbsv(f06skc)
{
   int nRowCol=4;

   matrix<complex> mat_input={{1+1.2i,2+2.1i,0,0},
                              {0,5+1.2i,6+2.6i,0},
                               {0,0,9,10+2i},
                               {0,0,0,11+4i}};

   vector<complex> vec_input={11+2i,12,13+2i,14+1.8i};

   int k_nonzero=1;
   matrix<complex> mat_input_band={{1+1.2i,2+2.1i},
                                   {5+1.2i,6+2.6i},
                                   {9,10+2i},
                                   {11+4i,0}};

   vector<complex> vec_output(nRowCol);
   vec_output=vec_input;

   ztbsv(UpperTriangle,NoTranspose,NotUnitTriangular,nRowCol,k_nonzero,
            mat_input_band,k_nonzero+1,vec_output,1);

   printf("Solve a system of equations for complex triangular band matrix M*X=B:\n");

   printf("M=\n");                     //output mat_inputM
   for(int i=0;i<nRowCol;i++)
   {
       printf("       ");
       for(int j=0;j<nRowCol;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_inputB
   printf("B=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_input[i].m_re,vec_input[i].m_im);
   }

   printf("\n");                       //output vec_outputX
   printf("Result vector=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_output[i].m_re,vec_output[i].m_im);
   }
}

   The output is as following:
Solve a system of equations for complex triangular band matrix M*X=B:
M=
       (1.000000,1.200000i)    (2.000000,2.100000i)    (0.000000,0.000000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (0.000000,0.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (11.000000,4.000000i)

B=
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

Result vector=
       (1.474731,-2.685431i)
       (2.226943,-0.880413i)
       (0.078345,0.254339i)
       (1.176642,-0.264234i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


ztpsv

Function: ztpsv
Prototype:
void ztpsv(MatrixTriangle uplo,MatrixTranspose trans,MatrixUnitTriangular diag,int n,const complex ap[],complex x[],int incx)
Remarks: Solve a system of equations for complex triangular packed coefficient matrix
Parameters:
trans=NoTranspose, solve the equations A*x=b;
trans=Transpose, solve the equations Transpose(A)*x=b;
trans=ConjugateTranspose, solve the equations ConjugateTranspose(A)*x=b.
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
diag specify whether or not the matrix is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
n
  the order of A
ap[]
  the complex triangular packed coefficient matrix A
x[]
  Input: the vector b; Output: the solution of the equations, vector x
incx
  the spacing which the elements of vector x occur

Return values:
Return: NULL

Example:
    This example solve a system of equations Ax=b, where matrix A is
       (1.000000,1.200000i)    (2.000000,2.100000i)    (4.000000,0.500000i)    (1.000000,0.000000i)
       (0.000000,0.000000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (2.000000,1.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (11.000000,4.000000i)

    and the vector b is
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

void test_f06slc()      //test for function ztpsv(f06slc)
{
   int nRowCol=4;

   matrix<complex> mat_input={{1+1.2i,2+2.1i,4+0.5i,1},
                              {0,5+1.2i,6+2.6i,2+1i},
                               {0,0,9,10+2i},
                               {0,0,0,11+4i}};

  matrix<complex> mat_input_pack={1+1.2i,2+2.1i,4+0.5i,1,
                                      5+1.2i,6+2.6i,2+1i,
                                                 9,10+2i,
                                                   11+4i};

   vector<complex> vec_input={11+2i,12,13+2i,14+1.8i};

   vector<complex> vec_output(nRowCol);
   vec_output=vec_input;

   ztpsv(UpperTriangle,NoTranspose,NotUnitTriangular,nRowCol,
            mat_input_pack,vec_output,1);

   printf("Solve a system of equations for complex packed triangular matrix M*X=B:\n");

   printf("M=\n");                     //output mat_inputM
   for(int i=0;i<nRowCol;i++)
   {
       printf("       ");
       for(int j=0;j<nRowCol;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_inputB
   printf("B=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_input[i].m_re,vec_input[i].m_im);
   }

   printf("\n");                       //output vec_outputX
   printf("Result vector=\n");
   for(i=0;i<nRowCol;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_output[i].m_re,vec_output[i].m_im);
   }
}

   The output is as following:
Solve a system of equations for complex packed triangular matrix M*X=B:
M=
       (1.000000,1.200000i)    (2.000000,2.100000i)    (4.000000,0.500000i)    (1.000000,0.000000i)
       (0.000000,0.000000i)    (5.000000,1.200000i)    (6.000000,2.600000i)    (2.000000,1.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (9.000000,0.000000i)    (10.000000,2.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (11.000000,4.000000i)

B=
       (11.000000,2.000000i)
       (12.000000,0.000000i)
       (13.000000,2.000000i)
       (14.000000,1.800000i)

Result vector=
       (1.498443,-2.397366i)
       (1.702533,-0.884189i)
       (0.078345,0.254339i)
       (1.176642,-0.264234i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zgeru

Function: zgeru
Prototype:
void zgeru(int m,int n,complex alpha,const complex x[],int incx,const complex y[],int incy,complex a[],int tda)
Remarks: Perform a rank-one update for complex general matrix:A=alpha*x*transpose(y)+A
Parameters:
m
  the number of rows of A
n
  the number of columns of A
x[]
  the vecor x
incx
  the spacing which the elements of x occur
y[]
  vector y
incy
  the spacing which the elements of y occur
a[]
  Input: the complex general matrix A; Output: matrix A after update
tda
  the last dimension of A

Return values:
Return: NULL

Example:
    This example perform a rank-one update for A, where matrix A is
       (1.000000,2.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (2.000000,1.000000i)    (3.000000,1.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (1.000000,3.000000i)    (2.000000,1.000000i)    (2.000000,3.000000i)    (5.000000,4.000000i)
       (1.000000,4.000000i)    (2.000000,3.000000i)    (6.000000,1.000000i)    (2.000000,4.000000i)

    and the vector x is
       (2.000000,2.000000i)
       (1.000000,1.000000i)
       (3.000000,2.000000i)
       (2.000000,4.000000i)

    vector y is
       (1.000000,2.000000i)
       (3.000000,0.400000i)
       (1.000000,0.200000i)
       (4.000000,2.100000i)

void test_f06smc()    //test for function zgeru(f06smc)
{
   int nRows=4;
   int nCols=4;

   matrix<complex>  mat_input={{1+2i,8+3i,2+3i,3+4i},
                               {2+1i,3+1i,5+2i,4+4i},
                               {1+3i,2+1i,2+3i,5+4i},
                               {1+4i,2+3i,6+1i,2+4i}};

   vector<complex>  vec_x={2+2i,1+1i,3+2i,2+4i};
   vector<complex>  vec_y={1+2i,3+0.4i,1+0.2i,4+2.1i};

   matrix<complex>  mat_output();
   mat_output=mat_input;

   int i,j;

   zgeru(nRows,nCols,1,vec_x,1,vec_y,1,mat_output,nRows);

   printf("Perform a rank-one update for complex general matrix:A=A+X*transpose(Y)\n");

   printf("A=\n");                     //output mat_inputA
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_inputX
   printf("X=\n");
   for(i=0;i<nRows;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_x[i].m_re,vec_x[i].m_im);
   }

   printf("\n");                       //output vec_outputY
   printf("Y=\n");
   for(i=0;i<nCols;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_y[i].m_re,vec_y[i].m_im);
   }

   printf("Result matrix A=\n");                     //output mat_inputA
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("(%f,%fi)    ",mat_output[i][j].m_re,mat_output[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Perform a rank-one update for complex general matrix:A=A+X*transpose(Y)
A=
       (1.000000,2.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (2.000000,1.000000i)    (3.000000,1.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (1.000000,3.000000i)    (2.000000,1.000000i)    (2.000000,3.000000i)    (5.000000,4.000000i)
       (1.000000,4.000000i)    (2.000000,3.000000i)    (6.000000,1.000000i)    (2.000000,4.000000i)

X=
       (2.000000,2.000000i)
       (1.000000,1.000000i)
       (3.000000,2.000000i)
       (2.000000,4.000000i)

Y=
       (1.000000,2.000000i)
       (3.000000,0.400000i)
       (1.000000,0.200000i)
       (4.000000,2.100000i)
Result matrix A=
       (-1.000000,8.000000i)    (13.200000,9.800000i)    (3.600000,5.400000i)    (6.800000,16.200000i)
       (1.000000,4.000000i)    (5.600000,4.400000i)    (5.800000,3.200000i)    (5.900000,10.100000i)
       (0.000000,11.000000i)    (10.200000,8.200000i)    (4.600000,5.600000i)    (12.800000,18.300000i)
       (-5.000000,12.000000i)    (6.400000,15.800000i)    (7.200000,5.400000i)    (1.600000,24.200000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zgerc

Function: zgerc
Prototype:
void zgerc(int m,int n,complex alpha,const complex x[],int incx,const complex y[],int incy,complex a[],int tda)
Remarks: Perform a rank-one update for complex general matrix:A=alpha*x*ConjugateTranspose(y)+A
Parameters:
m
  the number of rows of A
n
  the number of columns of A
x[]
  the vector x
incx
  the spacing which the elements of x occur
y[]
  the vector y
incy
  the spacing which the elements of y occur
a[]
  the complex general matrix A
tda
  the last dimension of A

Return values:
Return: NULL

Example:
    This example perform a rank-one update for A, where matrix A is
       (1.000000,2.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (2.000000,1.000000i)    (3.000000,1.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (1.000000,3.000000i)    (2.000000,1.000000i)    (2.000000,3.000000i)    (5.000000,4.000000i)
       (1.000000,4.000000i)    (2.000000,3.000000i)    (6.000000,1.000000i)    (2.000000,4.000000i)

    and the vector x is
       (2.000000,2.000000i)
       (1.000000,1.000000i)
       (3.000000,2.000000i)
       (2.000000,4.000000i)

    vector y is
       (1.000000,2.000000i)
       (3.000000,0.400000i)
       (1.000000,0.200000i)
       (4.000000,2.100000i)

void test_f06snc()    //test for function zgerc(f06snc)
{
   int nRows=4;
   int nCols=4;

   matrix<complex>  mat_input={{1+2i,8+3i,2+3i,3+4i},
                               {2+1i,3+1i,5+2i,4+4i},
                               {1+3i,2+1i,2+3i,5+4i},
                               {1+4i,2+3i,6+1i,2+4i}};

   vector<complex>  vec_x={2+2i,1+1i,3+2i,2+4i};
   vector<complex>  vec_y={1+2i,3+0.4i,1+0.2i,4+2.1i};

   matrix<complex>  mat_output();
   mat_output=mat_input;

   int i,j;

   zgerc(nRows,nCols,1,vec_x,1,vec_y,1,mat_output,nRows);

   printf("Perform a rank-one update for complex general matrix:A=A+X*transpose(Y)\n");

   printf("A=\n");                     //output mat_inputA
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_inputX
   printf("X=\n");
   for(i=0;i<nRows;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_x[i].m_re,vec_x[i].m_im);
   }

   printf("\n");                       //output vec_outputY
   printf("Y=\n");
   for(i=0;i<nCols;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_y[i].m_re,vec_y[i].m_im);
   }

   printf("Result matrix A=\n");                     //output mat_inputA
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("(%f,%fi)    ",mat_output[i][j].m_re,mat_output[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Perform a rank-one update for complex general matrix:A=A+X*transpose(Y)
A=
       (1.000000,2.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (2.000000,1.000000i)    (3.000000,1.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (1.000000,3.000000i)    (2.000000,1.000000i)    (2.000000,3.000000i)    (5.000000,4.000000i)
       (1.000000,4.000000i)    (2.000000,3.000000i)    (6.000000,1.000000i)    (2.000000,4.000000i)

X=
       (2.000000,2.000000i)
       (1.000000,1.000000i)
       (3.000000,2.000000i)
       (2.000000,4.000000i)

Y=
       (1.000000,2.000000i)
       (3.000000,0.400000i)
       (1.000000,0.200000i)
       (4.000000,2.100000i)
Result matrix A=
       (7.000000,0.000000i)    (14.800000,8.200000i)    (4.400000,4.600000i)    (15.200000,7.800000i)
       (5.000000,0.000000i)    (6.400000,3.600000i)    (6.200000,2.800000i)    (10.100000,5.900000i)
       (8.000000,-1.000000i)    (11.800000,5.800000i)    (5.400000,4.400000i)    (21.200000,5.700000i)
       (11.000000,4.000000i)    (9.600000,14.200000i)    (8.800000,4.600000i)    (18.400000,15.800000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zher

Function: zher
Prototype:
void zher(MatrixTriangle uplo,int n,double alpha,const complex x[],int incx,complex a[],int tda)
Remarks: Perform a rank-one update for complex Hermitian matrix:A=alpha*x*ConjugateTranspose(x)+A
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of A
x[]
  the vector x
incx
  the spacing which the elements of x occur
a[]
  Input: the complex Hermitian matrix A; Output: matrix A after update
tda
  the last dimension of A

Return values:
Return: NULL

Example:
    This example perform a rank-one update for A, where matrix A is
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,-3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (8.000000,-3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,-4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)

    and the vector x is
       (2.000000,2.000000i)
       (1.000000,1.000000i)
       (3.000000,2.000000i)
       (2.000000,4.000000i)

void test_f06spc()    //test for function zher(f06spc)
{
   int nColRows=4;

   matrix<complex>  mat_input={{1,8+3i,2+3i,3+4i},
                               {8-3i,3,5+2i,4+4i},
                               {8-3i,5-2i,2,5+4i},
                               {3-4i,4-4i,5-4i,2}};

   vector<complex>  vec_x={2+2i,1+1i,3+2i,2+4i};

   matrix<complex>  mat_output();
   mat_output=mat_input;

   int i,j;

   zher(UpperTriangle,nColRows,1,vec_x,1,mat_output,nColRows);

   for(i=0;i<nColRows;i++)
        for(j=0;j<i;j++)
        {
            mat_output[i][j].m_re=mat_output[j][i].m_re;
            mat_output[i][j].m_im=-mat_output[j][i].m_im;
        }

   printf("Perform a rank-one update for complex Hermitian matrix:A=A+X*transpose(X)\n");

   printf("A=\n");                     //output mat_inputA
   for(i=0;i<nColRows;i++)
   {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_inputX
   printf("X=\n");
   for(i=0;i<nColRows;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_x[i].m_re,vec_x[i].m_im);
   }

   printf("Result matrix A=\n");                     //output mat_outputA
   for(i=0;i<nColRows;i++)
   {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("(%f,%fi)    ",mat_output[i][j].m_re,mat_output[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Perform a rank-one update for complex Hermitian matrix:A=A+X*transpose(X)
A=
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,-3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (8.000000,-3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,-4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)

X=
       (2.000000,2.000000i)
       (1.000000,1.000000i)
       (3.000000,2.000000i)
       (2.000000,4.000000i)
Result matrix A=
       (9.000000,0.000000i)    (12.000000,3.000000i)    (12.000000,5.000000i)    (15.000000,0.000000i)
       (12.000000,-3.000000i)    (5.000000,0.000000i)    (10.000000,3.000000i)    (10.000000,2.000000i)
       (12.000000,-5.000000i)    (10.000000,-3.000000i)    (15.000000,0.000000i)    (19.000000,-4.000000i)
       (15.000000,0.000000i)    (10.000000,-2.000000i)    (19.000000,4.000000i)    (22.000000,0.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zhpr

Function: zhpr
Prototype:
void zhpr(MatrixTriangle uplo,int n,double alpha,const complex x[],int incx,complex ap[])
Remarks: Perform a rank-one update for complex Hermitian packed matrix:A=alpha*x*ConjugateTranspose(x)+A
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of A
x[]
  the vector x
incx
  the spacing which the elements of x occur
ap[]
  Input: the complex Hermitian matrix A; Output: matrix A after update

Return values:
Return: NULL

Example:
    This example perform a rank-one update for A, where matrix A is
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,-3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (8.000000,-3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,-4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)

    and the vector x is
       (2.000000,2.000000i)
       (1.000000,1.000000i)
       (3.000000,2.000000i)
       (2.000000,4.000000i)

void test_f06sqc()    //test for function zhpr(f06sqc)
{
   int nColRows=4;

   matrix<complex>  mat_input_pack={1,8+3i,2+3i,3+4i,3,5+2i,4+4i,2,5+4i,2};

   matrix<complex>  mat_input={{1,8+3i,2+3i,3+4i},
                               {8-3i,3,5+2i,4+4i},
                               {8-3i,5-2i,2,5+4i},
                               {3-4i,4-4i,5-4i,2}};

   vector<complex>  vec_x={2+2i,1+1i,3+2i,2+4i};

   matrix<complex>  mat_output_pack(mat_input_pack);

   int i,j;

   zhpr(UpperTriangle,nColRows,1,vec_x,1,mat_output_pack);

   int k=0;
   matrix<complex> mat_output(nColRows,nColRows);
   for(i=0;i<nColRows;i++)
       for(j=i;j<nColRows;j++)
       {
           mat_output[i][j].m_re=mat_output_pack[0][k].m_re;
           mat_output[i][j].m_im=mat_output_pack[0][k++].m_im;
       }

   for(i=0;i<nColRows;i++)
       for(j=0;j<i;j++)
       {
           mat_output[i][j].m_re=mat_output[j][i].m_re;
           mat_output[i][j].m_im=-mat_output[j][i].m_im;
       }

   printf("Perform a rank-one update for complex Hermitian packed matrix:A=A+X*transpose(X)\n");

   printf("A=\n");                     //output mat_inputA
   for(i=0;i<nColRows;i++)
   {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_inputX
   printf("X=\n");
   for(i=0;i<nColRows;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_x[i].m_re,vec_x[i].m_im);
   }

   printf("Result matrix A=\n");                     //output mat_outputA
   for(i=0;i<nColRows;i++)
   {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("(%f,%fi)    ",mat_output[i][j].m_re,mat_output[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Perform a rank-one update for complex Hermitian packed matrix:A=A+X*transpose(X)
A=
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,-3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (8.000000,-3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,-4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)

X=
       (2.000000,2.000000i)
       (1.000000,1.000000i)
       (3.000000,2.000000i)
       (2.000000,4.000000i)
Result matrix A=
       (9.000000,0.000000i)    (12.000000,3.000000i)    (12.000000,5.000000i)    (15.000000,0.000000i)
       (12.000000,-3.000000i)    (5.000000,0.000000i)    (10.000000,3.000000i)    (10.000000,2.000000i)
       (12.000000,-5.000000i)    (10.000000,-3.000000i)    (15.000000,0.000000i)    (19.000000,-4.000000i)
       (15.000000,0.000000i)    (10.000000,-2.000000i)    (19.000000,4.000000i)    (22.000000,0.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zher2

Function: zher2
Prototype:
void zher2(MatrixTriangle uplo,int n,complex alpha,const complex x[],int incx,const complex y[],int incy,complex a[],int tda)
Remarks: Perform a rank-two update for complex Hermitian matrix:A=alpha*x*ConjugateTranspose(y)+alpha*y*ConjugateTranspose(x)+A
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of A
x[]
  the vector x
incx
  the spacing which the elements of x occur
y[]
  the vector y
incy
  the spacing which the elements of y occur
a[]
  Input: the complex Hermitian matrix A; Output: matrix A after update
tda
  the last dimension of A

Return values:
Return: NULL

Example:
    This example perform a rank-two update for A, where matrix A is
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,-3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (8.000000,-3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,-4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)

    and the vector x is
       (2.000000,2.000000i)
       (1.000000,1.000000i)
       (3.000000,2.000000i)
       (2.000000,4.000000i)

    and the vector y is
       (1.000000,1.000000i)
       (2.000000,2.000000i)
       (3.000000,1.000000i)
       (4.000000,1.000000i)

void test_f06src()    //test for function zher2(f06src)
{
   int nColRows=4;

   matrix<complex>  mat_input={{1,8+3i,2+3i,3+4i},
                               {8-3i,3,5+2i,4+4i},
                               {8-3i,5-2i,2,5+4i},
                               {3-4i,4-4i,5-4i,2}};

   vector<complex>  vec_x={2+2i,1+1i,3+2i,2+4i};
   vector<complex>  vec_y={1+1i,2+2i,3+1i,4+1i};

   matrix<complex>  mat_output();
   mat_output=mat_input;

   int i,j;

   zher2(UpperTriangle,nColRows,1,vec_x,1,vec_y,1,mat_output,nColRows);

   for(i=0;i<nColRows;i++)
        for(j=0;j<i;j++)
        {
            mat_output[i][j].m_re=mat_output[j][i].m_re;
            mat_output[i][j].m_im=-mat_output[j][i].m_im;
        }

   printf("Perform a rank-two update for complex Hermitian matrix:A=A+X*transpose(Y)+Y*transpose(X)\n");

   printf("A=\n");                     //output mat_inputA
   for(i=0;i<nColRows;i++)
   {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_inputX
   printf("X=\n");
   for(i=0;i<nColRows;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_x[i].m_re,vec_x[i].m_im);
   }

   printf("\n");                       //output vec_inputY
   printf("Y=\n");
   for(i=0;i<nColRows;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_y[i].m_re,vec_y[i].m_im);
   }

   printf("Result matrix A=\n");                     //output mat_outputA
   for(i=0;i<nColRows;i++)
   {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("(%f,%fi)    ",mat_output[i][j].m_re,mat_output[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Perform a rank-two update for complex Hermitian matrix:A=A+X*transpose(Y)+Y*transpose(X)
A=
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,-3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (8.000000,-3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,-4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)

X=
       (2.000000,2.000000i)
       (1.000000,1.000000i)
       (3.000000,2.000000i)
       (2.000000,4.000000i)

Y=
       (1.000000,1.000000i)
       (2.000000,2.000000i)
       (3.000000,1.000000i)
       (4.000000,1.000000i)
Result matrix A=
       (9.000000,0.000000i)    (18.000000,3.000000i)    (15.000000,8.000000i)    (19.000000,8.000000i)
       (18.000000,-3.000000i)    (11.000000,0.000000i)    (19.000000,6.000000i)    (21.000000,3.000000i)
       (15.000000,-8.000000i)    (19.000000,-6.000000i)    (24.000000,0.000000i)    (29.000000,-1.000000i)
       (19.000000,-8.000000i)    (21.000000,-3.000000i)    (29.000000,1.000000i)    (26.000000,0.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zhpr2

Function: zhpr2
Prototype:
void zhpr2(MatrixTriangle uplo,int n,complex alpha,const complex x[],int incx,const complex y[],int incy,complex ap[])
Remarks: Perform a rank-two update for complex Hermitian packed matrix:A=alpha*x*ConjugateTranspose(y)+conjugate(alpha)*y*ConjugateTranspose(x)+A
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle is being reference.
n
  the order of A
x[]
  the vector x
incx
  the spacing which the elements of x occur
y[]
  the vector y
incy
  the spacing which the elements of y occur
ap[]
  Input: the complex Hermitian matrix A; Output: matrix A after update

Return values:
Return: NULL

Example:
    This example perform a rank-two update for A, where matrix A is
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,-3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (8.000000,-3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,-4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)

    and the vector x is
       (2.000000,2.000000i)
       (1.000000,1.000000i)
       (3.000000,2.000000i)
       (2.000000,4.000000i)

    and the vector y is
       (4.000000,1.000000i)
       (2.000000,1.000000i)
       (1.000000,1.000000i)
       (1.000000,1.000000i)

void test_f06ssc()    //test for function zhpr2(f06ssc)
{
   int nColRows=4;

   matrix<complex>  mat_input_pack={1,8+3i,2+3i,3+4i,3,5+2i,4+4i,2,5+4i,2};

   matrix<complex>  mat_input={{1,8+3i,2+3i,3+4i},
                               {8-3i,3,5+2i,4+4i},
                               {8-3i,5-2i,2,5+4i},
                               {3-4i,4-4i,5-4i,2}};

   vector<complex>  vec_x={2+2i,1+1i,3+2i,2+4i};
   vector<complex>  vec_y={4+1i,2+1i,1+1i,1+1i};

   matrix<complex>  mat_output_pack(mat_input_pack);

   int i,j;

   zhpr2(UpperTriangle,nColRows,1,vec_x,1,vec_y,1,mat_output_pack);

   int k=0;
   matrix<complex> mat_output(nColRows,nColRows);
   for(i=0;i<nColRows;i++)
       for(j=i;j<nColRows;j++)
       {
           mat_output[i][j].m_re=mat_output_pack[0][k].m_re;
           mat_output[i][j].m_im=mat_output_pack[0][k++].m_im;
       }

   for(i=0;i<nColRows;i++)
       for(j=0;j<i;j++)
       {
           mat_output[i][j].m_re=mat_output[j][i].m_re;
           mat_output[i][j].m_im=-mat_output[j][i].m_im;
       }

   printf("Perform a rank-one update for complex Hermitian packed matrix:A=A+X*transpose(Y)+Y*transpose(X)\n");

   printf("A=\n");                     //output mat_inputA
   for(i=0;i<nColRows;i++)
   {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("(%f,%fi)    ",mat_input[i][j].m_re,mat_input[i][j].m_im);
       printf("\n");
   }

   printf("\n");                       //output vec_inputX
   printf("X=\n");
   for(i=0;i<nColRows;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_x[i].m_re,vec_x[i].m_im);
   }

   printf("\n");                       //output vec_inputY
   printf("Y=\n");
   for(i=0;i<nColRows;i++)
   {
      printf("       ");
      printf("(%f,%fi)\n",vec_y[i].m_re,vec_y[i].m_im);
   }

   printf("Result matrix A=\n");                     //output mat_outputA
   for(i=0;i<nColRows;i++)
   {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("(%f,%fi)    ",mat_output[i][j].m_re,mat_output[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Perform a rank-one update for complex Hermitian packed matrix:A=A+X*transpose(Y)+Y*transpose(X)
A=
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,-3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (8.000000,-3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,-4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)

X=
       (2.000000,2.000000i)
       (1.000000,1.000000i)
       (3.000000,2.000000i)
       (2.000000,4.000000i)

Y=
       (4.000000,1.000000i)
       (2.000000,1.000000i)
       (1.000000,1.000000i)
       (1.000000,1.000000i)
Result matrix A=
       (21.000000,0.000000i)    (19.000000,2.000000i)    (20.000000,-2.000000i)    (19.000000,-10.000000i)
       (19.000000,-2.000000i)    (9.000000,0.000000i)    (15.000000,1.000000i)    (14.000000,-2.000000i)
       (20.000000,2.000000i)    (15.000000,-1.000000i)    (12.000000,0.000000i)    (16.000000,1.000000i)
       (19.000000,10.000000i)    (14.000000,2.000000i)    (16.000000,-1.000000i)    (14.000000,0.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dgemm

Function: dgemm
Prototype:
void dgemm(MatrixTranspose transa,MatrixTranspose transb,int m,int n,int k,double alpha,const double a[],int tda,const double b[],int tdb,double beta,double c[],int tdc)
Remarks: Compute a matrix-matrix product for two real rectangular matrices
Parameters:
m
  the number of rows of C
n
  the number of columns of C
k
  the number of columns(rows) of A which is equal to the number of rows(columns) of B
a[]
  the m by k real general matrix A(with transa=Notranspose) or the k by m matrix A (with transa=Transpose)
tda
  the last dimension of A
b[]
  the k by n real general matrix B(with transb=Notranspose) or the n by k matrix B(with transb=Transpose)
tdb
  the last dimension of B
c[]
  Input: the m by n matrix C; Output: C=beta*C+alpha*transa(A)*transb(B)
tdc
  the last dimension of C

Return values:
Return: NULL

Example:
    This example computes the product of A and B, where matrix A is
       1.000000    2.000000    3.000000    4.000000
       5.000000    6.000000    7.000000    8.000000
       9.000000    10.000000    11.000000    12.000000
       13.000000    14.000000    15.000000    16.000000

    and matrix B is
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000

void test_f06yac()      //test for function dgemm(f06yac)
{
    int nCols_b=4;
    int nColRows=4;
    int nRows_a=4;

    matrix<double> mat_a={{1,2,3,4},{5,6,7,8},{9,10,11,12},{13,14,15,16}};
    matrix<double> mat_b={{1,1,1,1},{1,1,1,1},{1,1,1,1},{1,1,1,1}};
    matrix<double> mat_c(nRows_a,nCols_b);
    mat_c=0;

    dgemm(NoTranspose,NoTranspose,nRows_a,nCols_b,nColRows,1,
                mat_a,nColRows,mat_b,nCols_b,1,mat_c,nCols_b);

    printf("Compute a matrix-matrix product for general real matrix C=A*B:\n");

    int i,j;
    printf("A=\n");                     //output mat_a
    for(i=0;i<nRows_a;i++)
    {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("%f    ",mat_a[i][j]);
       printf("\n");
    }

    printf("\nB=\n");                       //output mat_b
    for(i=0;i<nColRows;i++)
    {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("%f    ",mat_b[i][j]);
       printf("\n");
    }

    printf("\nC=\n");                       //output mat_c
    for(i=0;i<nRows_a;i++)
    {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("%f    ",mat_c[i][j]);
       printf("\n");
    }
}

   The output is as following:
Compute a matrix-matrix product for general real matrix C=A*B:
A=
       1.000000    2.000000    3.000000    4.000000
       5.000000    6.000000    7.000000    8.000000
       9.000000    10.000000    11.000000    12.000000
       13.000000    14.000000    15.000000    16.000000

B=
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000

C=
       10.000000    10.000000    10.000000    10.000000
       26.000000    26.000000    26.000000    26.000000
       42.000000    42.000000    42.000000    42.000000
       58.000000    58.000000    58.000000    58.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dsymm

Function: dsymm
Prototype:
void dsymm(OperationSide side,MatrixTriangle uplo,int m,int n,double alpha,const double a[],int tda,const double b[],int tdb,double beta,double c[],int tdc)
Remarks: Compute a matrix-matrix product for one real symmetric rectangular matrix A and one real general matrix B
Parameters:
side=Leftside: compute A*B
side=Rightside: compute B*A
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle of A is being reference.
m
  the number of rows of C
n
  the number of columns of C
a[]
  the order m symmetric matrix A(with side=Leftside) or the order n symmetric matrix A (with side=Rightside)
tda
  the last dimension of A
b[]
  the m by n matrix B(with side=Leftside) or the n by m matrix B(with side=Rightside)
tdb
  the last dimension of B
c[]
  Input: the m by n matrix C; Output: the product of A and B
tdc
  the last dimension of C

Return values:
Return: NULL

Example:
    This example computes the product of A and B, where the symmetric matrix A is
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       3.000000    7.000000    11.000000    12.000000
       4.000000    8.000000    12.000000    16.000000

    and the general matrix B is
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000

void test_f06ycc()      //test for function dsymm(f06ycc)
{
    int nCols_b=4;
    int nColRows_sy=4;

    matrix<double> mat_sy={{1,2,3,4},{2,6,7,8},{3,7,11,12},{4,8,12,16}};
    matrix<double> mat_g={{1,1,1,1},{1,1,1,1},{1,1,1,1},{1,1,1,1}};
    matrix<double> mat_c(nColRows_sy,nCols_b);
    mat_c=0;

    dsymm(LeftSide,UpperTriangle,nColRows_sy,nCols_b,1,
                mat_sy,nColRows_sy,mat_g,nCols_b,1,mat_c,nCols_b);

    printf("Compute a matrix-matrix product for a symmetric real matrix A and a general real matrix B, C=A*B:\n");

    int i,j;
    printf("A=\n");                     //output symmetric real matrix mat_sy
    for(i=0;i<nColRows_sy;i++)
    {
       printf("       ");
       for(j=0;j<nColRows_sy;j++)
          printf("%f    ",mat_sy[i][j]);
       printf("\n");
    }

    printf("\nB=\n");                       //output general real mat_g
    for(i=0;i<nColRows_sy;i++)
    {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("%f    ",mat_g[i][j]);
       printf("\n");
    }

    printf("\nC=\n");                       //output mat_c
    for(i=0;i<nColRows_sy;i++)
    {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("%f    ",mat_c[i][j]);
       printf("\n");
    }
}

   The output is as following:
Compute a matrix-matrix product for a symmetric real matrix A and a general real matrix B, C=A*B:
A=
       1.000000    2.000000    3.000000    4.000000
       2.000000    6.000000    7.000000    8.000000
       3.000000    7.000000    11.000000    12.000000
       4.000000    8.000000    12.000000    16.000000

B=
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000

C=
       10.000000    10.000000    10.000000    10.000000
       23.000000    23.000000    23.000000    23.000000
       33.000000    33.000000    33.000000    33.000000
       40.000000    40.000000    40.000000    40.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dtrmm

Function: dtrmm
Prototype:
void dtrmm(MatrixTriangle side,MatrixTriangle uplo,MatrixTranspose transa,MatrixUnitTriangular diag,int m,int n,double alpha,const double a[],int tda,double b[],int tdb)
Remarks: Compute a matrix-matrix product for one real triangular matrix A and one real general matrix B
Parameters:
side=Leftside: compute transa(A)*B
side=Rightside: compute B*transa(A)
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle of A is being reference.
diag specify whether or not the matrix A is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
m
  the number of rows of B
n
  the number of columns of B
a[]
  the real triangular matrix A of m by m(with side=Leftside) or n by n(with side=Rightside)
tda
  the last dimension of A
b[]
  Input: the m by n general real matrix B; Output: alpha*AB
tdb
  the last dimension of B

Return values:
Return: NULL

Example:
    This example computes the product of A and B, where the real triangular matrix A is
       1.000000    2.000000    3.000000    4.000000
       0.000000    6.000000    7.000000    8.000000
       0.000000    0.000000    11.000000    12.000000
       0.000000    0.000000    0.000000    16.000000

    and the general real matrix B is
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000

void test_f06yfc()      //test for function dtrmm(f06yfc)
{
    int nCols_g=4;
    int nColRows_tr=4;

    matrix<double> mat_tr={{1,2,3,4},{0,6,7,8},{0,0,11,12},{0,0,0,16}};
    matrix<double> mat_g={{1,1,1,1},{1,1,1,1},{1,1,1,1},{1,1,1,1}};
    matrix<double> mat_c(nColRows_tr,nCols_g);
    mat_c=mat_g;

    dtrmm(LeftSide,UpperTriangle,NoTranspose,NotUnitTriangular,nColRows_tr,nCols_g,1,
                mat_tr,nColRows_tr,mat_c,nCols_g);

    printf("Compute a matrix-matrix product for a triangular real matrix A and a general real matrix B, C=A*B:\n");

    int i,j;
    printf("A=\n");                     //output triangular real matrix mat_tr
    for(i=0;i<nColRows_tr;i++)
    {
       printf("       ");
       for(j=0;j<nColRows_tr;j++)
          printf("%f    ",mat_tr[i][j]);
       printf("\n");
    }

    printf("\n");
    printf("B=\n");                //output general real mat_g
    for(i=0;i<nColRows_tr;i++)
    {
       printf("       ");
       for(j=0;j<nCols_g;j++)
          printf("%f    ",mat_g[i][j]);
       printf("\n");
    }

    printf("\n");
    printf("C=\n");                    //output mat_c
    for(i=0;i<nColRows_tr;i++)
    {
       printf("       ");
       for(j=0;j<nCols_g;j++)
          printf("%f    ",mat_c[i][j]);
       printf("\n");
    }
}

   The output is as following:
Compute a matrix-matrix product for a triangular real matrix A and a general real matrix B, C=A*B:
A=
       1.000000    2.000000    3.000000    4.000000
       0.000000    6.000000    7.000000    8.000000
       0.000000    0.000000    11.000000    12.000000
       0.000000    0.000000    0.000000    16.000000

B=
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000

C=
       10.000000    10.000000    10.000000    10.000000
       21.000000    21.000000    21.000000    21.000000
       23.000000    23.000000    23.000000    23.000000
       16.000000    16.000000    16.000000    16.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dsyrk

Function: dsyrk
Prototype:
void dsyrk(MatrixTriangle uplo,MatrixTranspose trans,int n,int k,double alpha,const double a[],int tda,double beta,double c[],int tdc)
Remarks: Perform a rank-k update of a real symmetric matrix
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle of C is being reference.
trans=Notranspose: return alpha*A*transpose(A)+beta*C in array C;
trans=Transpose or ConjugateTranspose: return alpha*transpose(A)*A+beta*C in array C;
n
  the order of C
k
  the number of rows(with tran=Transpose) or columns(tran=Notranspose) of A
a[]
  the matrix A
tda
  the last dimension of A
c[]
  Input: the order n real symmetric matrix C; Output: matrix C after update
tdc
  the last dimension of C

Return values:
Return: NULL

Example:
    This example perform a rank-k update of a real symmetric matrix C.

void test_f06ypc()      //test for function dsyrk(f06ypc)
{
    int nCols=4;
    int nRows=4;

    matrix<double> mat_a={{1,2,3,4},{2,3,4,5},{3,7,11,12},{4,8,12,16}};
    matrix<double> mat_c(nRows,nRows);
    mat_c=0;

    dsyrk(UpperTriangle,NoTranspose,nRows,nCols,1,
                mat_a,nCols,1,mat_c,nRows);

    int i,j;
    for(i=0;i<nRows;i++)
        for(j=0;j<i;j++)
            mat_c[i][j]=mat_c[j][i];

    printf("Perform a rank-k update of a real symmtric matrix C=A*transpose(A)+C:\n");

    printf("A=\n");                     //output general real matrix mat_sy
    for(i=0;i<nCols;i++)
    {
       printf("       ");
       for(j=0;j<nRows;j++)
          printf("%f    ",mat_a[i][j]);
       printf("\n");
    }

    printf("\n");
    printf("C=\n");                       //output real symmtric matrix mat_c
    for(i=0;i<nRows;i++)
    {
       printf("       ");
       for(j=0;j<nRows;j++)
          printf("%f    ",mat_c[i][j]);
       printf("\n");
    }
}

   The output is as following:
Perform a rank-k update of a real symmtric matrix C=A*transpose(A)+C:
A=
       1.000000    2.000000    3.000000    4.000000
       2.000000    3.000000    4.000000    5.000000
       3.000000    7.000000    11.000000    12.000000
       4.000000    8.000000    12.000000    16.000000

C=
       30.000000    40.000000    98.000000    120.000000
       40.000000    54.000000    131.000000    160.000000
       98.000000    131.000000    323.000000    392.000000
       120.000000    160.000000    392.000000    480.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


dsyr2k

Function: dsyr2k
Prototype:
void dsyr2k(MatrixTriangle uplo,MatrixTranspose trans,int n,int k,double alpha,const double a[],int tda,const double b[],int tdb,double beta,double c[],int tdc)
Remarks: Perform a rank-2k update of a real symmetric matrix
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle of C is being reference.
trans=Notranspose: both A and B are n by k, return alpha*A*transpose(B)+alpha*B*transpose(A)+beta*C in array C;
trans=Transpose or ConjugateTranspose: both A and B are k by n, return alpha*transpose(A)*B+alpha*transpose(B)*A+beta*C in array C;
n
  the order of C
a[]
  the general matrix A
tda
  the last dimesion of A
b[]
  the general matrix B
tdb
  the last dimension of B
c[]
  Input: the order n real symmetric matrix C; Output: matrix C after update
tdc
  the last dimension of C

Return values:
Return: NULL

Example:
    This example perform a rank-2k update of a real symmtric matrix C

void test_f06yrc()      //test for function dsyr2k(f06yrc)
{
    int nCols=4;
    int nRows=4;
    int nColRows=4;

    matrix<double> mat_a={{1,2,3,4},{2,2,8,4},{3,7,11,12},{4,8,12,16}};
    matrix<double> mat_b={{1,1,1,1},{1,1,1,1},{1,1,1,1},{1,1,1,1}};
    matrix<double> mat_c(nRows,nRows);
    mat_c=0;

    dsyr2k(UpperTriangle,NoTranspose,nRows,nCols,1,
                mat_a,nCols,mat_b,nCols,1,mat_c,nRows);

    int i,j;
    for(i=0;i<nRows;i++)
        for(j=0;j<i;j++)
            mat_c[i][j]=mat_c[j][i];

    printf("Perform a rank-2k update of a real symmetric matrix C=C+A*transpose(B)+B*transpose(A):\n");

    printf("A=\n");                     //output general real matrix A
    for(i=0;i<nRows;i++)
    {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("%f    ",mat_a[i][j]);
       printf("\n");
    }

    printf("B=\n");                       //output general real matrix B
    for(i=0;i<nRows;i++)
    {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("%f    ",mat_b[i][j]);
       printf("\n");
    }

    printf("C=\n");                       //output symmetric matrix C
    for(i=0;i<nRows;i++)
    {
       printf("       ");
       for(j=0;j<nRows;j++)
          printf("%f    ",mat_c[i][j]);
       printf("\n");
    }
}

   The output is as following:
Perform a rank-2k update of a real symmetric matrix C=C+A*transpose(B)+B*transpose(A):
A=
       1.000000    2.000000    3.000000    4.000000
       2.000000    2.000000    8.000000    4.000000
       3.000000    7.000000    11.000000    12.000000
       4.000000    8.000000    12.000000    16.000000
B=
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
       1.000000    1.000000    1.000000    1.000000
C=
       20.000000    26.000000    43.000000    50.000000
       26.000000    32.000000    49.000000    56.000000
       43.000000    49.000000    66.000000    73.000000
       50.000000    56.000000    73.000000    80.000000

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zgemm

Function: zgemm
Prototype:
void zgemm(MatrixTranspose transa,MatrixTranspose transb,int m,int n,int k,complex alpha,const complex a[],int tda,const complex b[],int tdb,complex beta,complex c[],int tdc)
Remarks: Compute a matrix-matrix product for two complex rectangular matrices
Parameters:
m
  the number of rows of C
n
  the number of columns of C
k
  the number of columns(rows) of A, which is equal to the number of rows(columns) of B
a[]
  the m by k complex matrix A(with transa=Notranspose) or k by m complex matrix A(with transa=Transpose or ConjugateTranspose)
tda
  the last dimension of A
b[]
  the k by n complex matrix B(with transb=Notranspose) or n by k complex matrix B (with transb=Transpose or ConjugateTranspose)
tdb
  the last dimension of B
c[]
  Input: the m by n complex matrix C; Output: C=beta*C+alpha*transa(A)*transb(B)
tdc
  the last dimension of C

Return values:
Return: NULL

Example:
    This example computes the product of A and B, where matrix A is
       (1.000000,2.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (2.000000,1.000000i)    (3.000000,1.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (1.000000,3.000000i)    (2.000000,1.000000i)    (2.000000,3.000000i)    (5.000000,4.000000i)
       (1.000000,4.000000i)    (2.000000,3.000000i)    (6.000000,1.000000i)    (2.000000,4.000000i)

    and matrix B is
       (1.000000,2.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)

void test_f06zac()    //test for function zgemm(f06zac)
{
   int nRows_a=4;
   int nCols_b=4;
   int nColRows=4;

   matrix<complex>  mat_a={{1+2i,8+3i,2+3i,3+4i},
                           {2+1i,3+1i,5+2i,4+4i},
                           {1+3i,2+1i,2+3i,5+4i},
                           {1+4i,2+3i,6+1i,2+4i}};

   matrix<complex> mat_b={{1+2i,1,1,1},{1,1,1,1},{1,1,1,1},{1,1,1,1}};

   matrix<complex> mat_c(nRows_a,nColRows);
   mat_c=0;

   zgemm(NoTranspose,NoTranspose,nRows_a,nCols_b,nColRows,1,
                mat_a,nColRows,mat_b,nCols_b,1,mat_c,nCols_b);

   printf("Compute a matrix-matrix product for general complex matrix C=A*B:\n");

   int i,j;

   printf("A=\n");                     //output mat_a
   for(i=0;i<nRows_a;i++)
   {
       printf("       ");
       for(j=0;j<nColRows;j++)
          printf("(%f,%fi)    ",mat_a[i][j].m_re,mat_a[i][j].m_im);
       printf("\n");
   }

   printf("B=\n");                     //output mat_b
   for(i=0;i<nColRows;i++)
   {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("(%f,%fi)    ",mat_b[i][j].m_re,mat_b[i][j].m_im);
       printf("\n");
   }

   printf("C=\n");                     //output mat_c
   for(i=0;i<nRows_a;i++)
   {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("(%f,%fi)    ",mat_c[i][j].m_re,mat_c[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Compute a matrix-matrix product for general complex matrix C=A*B:
A=
       (1.000000,2.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (2.000000,1.000000i)    (3.000000,1.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (1.000000,3.000000i)    (2.000000,1.000000i)    (2.000000,3.000000i)    (5.000000,4.000000i)
       (1.000000,4.000000i)    (2.000000,3.000000i)    (6.000000,1.000000i)    (2.000000,4.000000i)
B=
       (1.000000,2.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
C=
       (10.000000,14.000000i)    (14.000000,12.000000i)    (14.000000,12.000000i)    (14.000000,12.000000i)
       (12.000000,12.000000i)    (14.000000,8.000000i)    (14.000000,8.000000i)    (14.000000,8.000000i)
       (4.000000,13.000000i)    (10.000000,11.000000i)    (10.000000,11.000000i)    (10.000000,11.000000i)
       (3.000000,14.000000i)    (11.000000,12.000000i)    (11.000000,12.000000i)    (11.000000,12.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zhemm

Function: zhemm
Prototype:
void zhemm(OperationSide side,MatrixTriangle uplo,int m,int n,complex alpha,const complex a[],int tda,const complex b[],int tdb,complex beta,complex c[],int tdc)
Remarks: Compute a matrix-matrix product for one complex Hermitian matrix A and one complex general matrix B
Parameters:
side=Leftside: compute A*B
side=Rightside: compute B*A
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle of A is being reference.
m
  the number of rows of C
n
  the number of column of C
a[]
  the complex Hermitian matrix A of m by m (with side=Leftside) or n by n (with side=Rightside)
tda
  the last dimension of A
b[]
  the complex matrix B of m by n (with side=Leftside) or n by m (with side=Rightside)
tdb
  the last dimension of B
c[]
  Input: the m by n matrix; Output: C=beta*C+alpha*AB
tdc
  the last dimension of C

Return values:
Return: NULL

Example:
    This example computes the product of A and B, where the complex Hermitian matrix A is
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,-3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (2.000000,-3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,-4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)

    and the general complex matrix B is
       (1.000000,2.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)

void test_f06zcc()    //test for function zhemm(f06zcc)
{
   int nColRows_h=4;
   int nCols_b=4;

   matrix<complex>  mat_h={{1,8+3i,2+3i,3+4i},
                           {8-3i,3,5+2i,4+4i},
                           {2-3i,5-2i,2,5+4i},
                           {3-4i,4-4i,5-4i,2}};

   matrix<complex> mat_b={{1+2i,1,1,1},{1,1,1,1},{1,1,1,1},{1,1,1,1}};

   matrix<complex> mat_c(nColRows_h,nCols_b);
   mat_c=0;

   zhemm(LeftSide,UpperTriangle,nColRows_h,nCols_b,1,
                mat_h,nColRows_h,mat_b,nCols_b,1,mat_c,nCols_b);

   printf("Compute a matrix-matrix product for a complex Hermitian matrix H and a general complex matrix B, C=H*B:\n");

   int i,j;

   printf("H=\n");                     //output complex Hermitian matrix mat_h
   for(i=0;i<nColRows_h;i++)
   {
       printf("       ");
       for(j=0;j<nColRows_h;j++)
          printf("(%f,%fi)    ",mat_h[i][j].m_re,mat_h[i][j].m_im);
       printf("\n");
   }

   printf("B=\n");                     //output general complex matrix mat_b
   for(i=0;i<nColRows_h;i++)
   {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("(%f,%fi)    ",mat_b[i][j].m_re,mat_b[i][j].m_im);
       printf("\n");
   }

   printf("C=\n");                     //output mat_c
   for(i=0;i<nColRows_h;i++)
   {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("(%f,%fi)    ",mat_c[i][j].m_re,mat_c[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Compute a matrix-matrix product for a complex Hermitian matrix H and a general complex matrix B, C=H*B:
H=
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,-3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (2.000000,-3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,-4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)
B=
       (1.000000,2.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
C=
       (14.000000,12.000000i)    (14.000000,10.000000i)    (14.000000,10.000000i)    (14.000000,10.000000i)
       (26.000000,19.000000i)    (20.000000,3.000000i)    (20.000000,3.000000i)    (20.000000,3.000000i)
       (20.000000,3.000000i)    (14.000000,-1.000000i)    (14.000000,-1.000000i)    (14.000000,-1.000000i)
       (22.000000,-6.000000i)    (14.000000,-12.000000i)    (14.000000,-12.000000i)    (14.000000,-12.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


ztrmm

Function: ztrmm
Prototype:
void ztrmm(MatrixTriangle side,MatrixTriangle uplo,MatrixTranspose transa,MatrixUnitTriangular diag,int m,int n,complex alpha,const complex a[],int tda,complex b[],int tdb)
Remarks: Compute a matrix-matrix product for one complex triangular matrix A and one complex general matrix B
Parameters:
side=Leftside: compute transa(A)*B
side=Rightside: compute B*transa(A)
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle of A is being reference.
diag specify whether or not the matrix A is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
m
  the number of rows of B
n
  the number of columns of B
a[]
  the complex triangular matrix A of m by m(with side=Leftside) or n by n(with side= Rightside)
tda
  the last dimension of A
b[]
  Input: the m by n complex general matrix B; Output: alpha*AB
tdb
  the last dimension of B

Return values:
Return: NULL

Example:
    This example computes the product of T and B, where the complex triangular matrix T is
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (0.000000,0.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (2.000000,0.000000i)

    and the general complex matrix B is
       (1.000000,2.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)

void test_f06zfc()    //test for function ztrmm(f06zfc)
{
   int nColRows_tr=4;
   int nCols_b=4;

   matrix<complex>  mat_tr={{1,8+3i,2+3i,3+4i},
                           {0,3,5+2i,4+4i},
                           {0,0,2,5+4i},
                           {0,0,0,2}};

   matrix<complex> mat_b={{1+2i,1,1,1},{1,1,1,1},{1,1,1,1},{1,1,1,1}};

   matrix<complex> mat_c(nColRows_tr,nCols_b);
   mat_c=mat_b;

   ztrmm(LeftSide,UpperTriangle,NoTranspose,NotUnitTriangular,nColRows_tr,nCols_b,1,
                mat_tr,nColRows_tr,mat_c,nCols_b);

   printf("Compute a matrix-matrix product for a complex triangular matrix H and a general complex matrix B, C=T*B:\n");

   int i,j;

   printf("T=\n");                     //output complex triangular matrix mat_tr
   for(i=0;i<nColRows_tr;i++)
   {
       printf("       ");
       for(j=0;j<nColRows_tr;j++)
          printf("(%f,%fi)    ",mat_tr[i][j].m_re,mat_tr[i][j].m_im);
       printf("\n");
   }

   printf("B=\n");                     //output general complex matrix mat_b
   for(i=0;i<nColRows_tr;i++)
   {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("(%f,%fi)    ",mat_b[i][j].m_re,mat_b[i][j].m_im);
       printf("\n");
   }

   printf("C=\n");                     //output mat_c
   for(i=0;i<nColRows_tr;i++)
   {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("(%f,%fi)    ",mat_c[i][j].m_re,mat_c[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Compute a matrix-matrix product for a complex triangular matrix H and a general complex matrix B, C=T*B:
T=
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (0.000000,0.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (2.000000,0.000000i)
B=
       (1.000000,2.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
C=
       (14.000000,12.000000i)    (14.000000,10.000000i)    (14.000000,10.000000i)    (14.000000,10.000000i)
       (12.000000,6.000000i)    (12.000000,6.000000i)    (12.000000,6.000000i)    (12.000000,6.000000i)
       (7.000000,4.000000i)    (7.000000,4.000000i)    (7.000000,4.000000i)    (7.000000,4.000000i)
       (2.000000,0.000000i)    (2.000000,0.000000i)    (2.000000,0.000000i)    (2.000000,0.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


ztrsm

Function: ztrsm
Prototype:
void ztrsm(MatrixTriangle side,MatrixTriangle uplo,MatrixTranspose transa,MatrixUnitTriangular diag,int m,int n,complex alpha,const complex a[],int tda,complex b[],int tdb)
Remarks: Solve a system of equations with multiple right-hand sides for real triangular coefficient matrix
Parameters:
side=Leftside: solve the equations trans(A)*X=alpha*B
side=Rightside: solve the equations X*trans(A)=alpha*B
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle of A is being reference.
diag specify whether or not the matrix A is unit triangular. if diag=UnitTriangular, the diagonal elements are not referenced.
m
  the number of rows of B
n
  the number of columns of B
a[]
  the coefficient matrix A of m by m(with side=Leftside) or n by n (with side=Rightside)
tda
  the last dimension of A
b[]
  Input: the m by n right-hand side matrix B; Output:the solvtion of the equations
tdb
  the last dimension of B

Return values:
Return: NULL

Example:
    This example solve a system of equations with multiple fight-hand sides, where the coefficient matrix T is
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (0.000000,0.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (2.000000,0.000000i)

    and the multiple right-hand sides matrix B is
       (1.000000,2.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (2.000000,3.000000i)    (3.000000,2.000000i)    (4.000000,0.000000i)
       (2.000000,-2.000000i)    (3.000000,5.000000i)    (4.000000,0.000000i)    (5.000000,0.000000i)
       (3.000000,-1.000000i)    (4.000000,2.000000i)    (5.000000,-3.000000i)    (6.000000,4.000000i)

void test_f06zjc()    //test for function ztrsm(f06zjc)
{
   int nColRows_tr=4;
   int nCols_b=4;

   matrix<complex>  mat_tr={{1,8+3i,2+3i,3+4i},
                           {0,3,5+2i,4+4i},
                           {0,0,2,5+4i},
                           {0,0,0,2}};

   matrix<complex> mat_b={{1+2i,1,1,1},{1,2+3i,3+2i,4},{2-2i,3+5i,4,5},{3-1i,4+2i,5-3i,6+4i}};

   matrix<complex> mat_c(nColRows_tr,nCols_b);
   mat_c=mat_b;

   ztrsm(LeftSide,UpperTriangle,NoTranspose,NotUnitTriangular,nColRows_tr,nCols_b,1,
                mat_tr,nColRows_tr,mat_c,nCols_b);

   printf("Solve a systrm of equations with multiple right-hand sides, T*X=B:\n");

   int i,j;

   printf("T=\n");                     //output complex triangular matrix mat_tr
   for(i=0;i<nColRows_tr;i++)
   {
       printf("       ");
       for(j=0;j<nColRows_tr;j++)
          printf("(%f,%fi)    ",mat_tr[i][j].m_re,mat_tr[i][j].m_im);
       printf("\n");
   }

   printf("B=\n");                     //output right-hand complex matrix mat_b
   for(i=0;i<nColRows_tr;i++)
   {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("(%f,%fi)    ",mat_b[i][j].m_re,mat_b[i][j].m_im);
       printf("\n");
   }

   printf("X=\n");                     //output mat_c
   for(i=0;i<nColRows_tr;i++)
   {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("(%f,%fi)    ",mat_c[i][j].m_re,mat_c[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Solve a systrm of equations with multiple right-hand sides, T*X=B:
T=
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (0.000000,0.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (0.000000,0.000000i)    (0.000000,0.000000i)    (0.000000,0.000000i)    (2.000000,0.000000i)
B=
       (1.000000,2.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (2.000000,3.000000i)    (3.000000,2.000000i)    (4.000000,0.000000i)
       (2.000000,-2.000000i)    (3.000000,5.000000i)    (4.000000,0.000000i)    (5.000000,0.000000i)
       (3.000000,-1.000000i)    (4.000000,2.000000i)    (5.000000,-3.000000i)    (6.000000,4.000000i)
X=
       (-5.666667,-38.000000i)    (10.666667,-33.333333i)    (-38.333333,-52.000000i)    (51.333333,-74.666667i)
       (2.083333,5.750000i)    (-0.833333,4.666667i)    (6.916667,6.250000i)    (-5.666667,12.333333i)
       (-3.750000,-2.750000i)    (-1.500000,-4.000000i)    (-7.250000,-1.250000i)    (-1.000000,-11.000000i)
       (1.500000,-0.500000i)    (2.000000,1.000000i)    (2.500000,-1.500000i)    (3.000000,2.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zherk

Function: zherk
Prototype:
void zherk(MatrixTriangle uplo,MatrixTranspose trans,int n,int k,double alpha,const complex a[],int tda,double beta,complex c[],int tdc)
Remarks: Perform a rank-k update of a complex Hermitian matrix
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle of C is being reference.
trans=Notranspose: return alpha*A*transpose(A)+beta*C in array C;
trans=ConjugateTranspose: return alpha*ConjugateTranspose(A)*A+beta*C in array C;
n
  the order of C
k
  the number of rows(with trans=Transpose/ConjugateTranspose) or columns(trans=Notranspose) of A
a[]
  the matrix A
tda
  the last dimension of A
c[]
  Input: the Hermitian matrix C; Output: the matrix C after update
tdc
  the last dimension of A

Return values:
Return: NULL

Example:
    This example perform a rank-k update of a complex Hermitian matrix C

void test_f06zpc()    //test for function zherk(f06zpc)
{
   int nRows=4;
   int nCols=4;

   matrix<complex>  mat_a={{1,8+3i,2+3i,3+4i},
                           {8-3i,3,5+2i,4+4i},
                           {2-3i,5-2i,2,5+4i},
                           {3-4i,4-4i,5-4i,2}};

   matrix<complex> mat_c(nRows,nRows);
   mat_c=0;

   zherk(UpperTriangle,NoTranspose,nRows,nCols,1,
                mat_a,nCols,1,mat_c,nRows);

   int i,j;
   for(i=0;i<nRows;i++)
        for(j=0;j<i;j++)
        {
            mat_c[i][j].m_re=mat_c[j][i].m_re;
            mat_c[i][j].m_im=-mat_c[j][i].m_im;
        }

   printf("Perform a rank-k update of a complex Hermitian matrix C=H*conj(H)+C:\n");

   printf("H=\n");                     //output complex  matrix mat_h
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("(%f,%fi)    ",mat_a[i][j].m_re,mat_a[i][j].m_im);
       printf("\n");
   }

   printf("C=\n");                     //output complex Hermitian matrix  mat_c
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nRows;j++)
          printf("(%f,%fi)    ",mat_c[i][j].m_re,mat_c[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Perform a rank-k update of a complex Hermitian matrix C=H*conj(H)+C:
H=
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,-3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (2.000000,-3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,-4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)
C=
       (112.000000,0.000000i)    (76.000000,27.000000i)    (71.000000,48.000000i)    (27.000000,79.000000i)
       (76.000000,-27.000000i)    (143.000000,0.000000i)    (86.000000,32.000000i)    (73.000000,73.000000i)
       (71.000000,-48.000000i)    (86.000000,-32.000000i)    (87.000000,0.000000i)    (66.000000,27.000000i)
       (27.000000,-79.000000i)    (73.000000,-73.000000i)    (66.000000,-27.000000i)    (102.000000,0.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zher2k

Function: zher2k
Prototype:
void zher2k(MatrixTriangle uplo,MatrixTranspose trans,int n,int k,complex alpha,const complex a[],int tda,const complex b[],int tdb,double beta,complex c[],int tdc)
Remarks: Perform a rank-2k update of a complex Hermitian matrix
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle of C is being reference.
trans=Notranspose: both A and B are n by k, return alpha*A*ConjugateTranspose(B)+ConjugateTranspose(alpha)*B*ConjugateTranspose(A)+beta*C in array C;
trans=ConjugateTranspose: both A and B are k by n, return alpha*ConjugateTranspose(A)*B+ConjugateTranspose(alpha)*ConjugateTranspose(B)*A+beta*C in array C;
n
  the order of C
a[]
  the complex general matrix A
tda
  the last dimension of A
b[]
  the complex general matrix B
tdb
  the last dimension of B
c[]
  Input: the order n complex Hermitian matrix C; Output: matrix C after update
tdc
  the last dimension of C

Return values:
Return: NULL

Example:
    This example perform a rank-2k update of complex Hermitian matrix C

void test_f06zrc()    //test for function zher2k(f06zrc)
{
   int nCols=4;
   int nRows=4;

   matrix<complex>  mat_a={{1,8+3i,2+3i,3+4i},
                           {8-3i,3,5+2i,4+4i},
                           {2-3i,5-2i,2,5+4i},
                           {3-4i,4-4i,5-4i,2}};

   matrix<complex> mat_b={{1+2i,1,1,1},{1,1-4i,1,1},{1,1+1i,1,1},{1-4i,1,1,1}};

   matrix<complex> mat_c(nRows,nRows);
   mat_c=0;

   zher2k(UpperTriangle,NoTranspose,nRows,nCols,1,
                mat_a,nCols,mat_b,nCols,1,mat_c,nRows);

   printf("Perform a rank-2k update of a complex Hermitian matrix C=C+A*transpose(B)+B*transpose(A):\n");

   int i,j;
   for(i=0;i<nRows;i++)
        for(j=0;j<i;j++)
        {
            mat_c[i][j].m_re=mat_c[j][i].m_re;
            mat_c[i][j].m_im=-mat_c[j][i].m_im;
        }

   printf("A=\n");                     //output general complex matrix mat_a
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("(%f,%fi)    ",mat_a[i][j].m_re,mat_a[i][j].m_im);
       printf("\n");
   }

   printf("B=\n");                     //output general complex matrix mat_b
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("(%f,%fi)    ",mat_b[i][j].m_re,mat_b[i][j].m_im);
       printf("\n");
   }

   printf("C=\n");                     //output complex Hermitian matrix mat_c
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nRows;j++)
          printf("(%f,%fi)    ",mat_c[i][j].m_re,mat_c[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Perform a rank-2k update of a complex Hermitian matrix C=C+A*transpose(B)+B*transpose(A):
A=
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,-3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (2.000000,-3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,-4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)
B=
       (1.000000,2.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,-4.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,1.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,-4.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
C=
       (28.000000,0.000000i)    (16.000000,55.000000i)    (25.000000,7.000000i)    (20.000000,32.000000i)
       (16.000000,-55.000000i)    (40.000000,0.000000i)    (42.000000,-19.000000i)    (62.000000,31.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zsymm

Function: zsymm
Prototype:
void zsymm(OperationSide side,MatrixTriangle uplo,int m,int n,complex alpha,const complex a[],int tda,const complex b[],int tdb,complex beta,complex c[],int tdc)
Remarks: Compute a matrix-matrix product for one complex symmetric matrix and one somplex rectangular matrix
Parameters:
side=Leftside: compute A*B
side=Rightside: compute B*A
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle of A is being reference.
m
  the number of rows of C
n
  the number of columns of C
a[]
  the real symmetric matrix A of n by n(side=Rightside) or m by m(side=Leftside)
tda
  the last dimension of A
b[]
  the real matrix B of m by n(side=Leftside) or n by m (side=Rightside)
tdb
  the last dimension of B
c[]
  Input: the m by n matrix; Output: alpha*AB+beta*C
tdc
  the last dimension of C

Return values:
Return: NULL

Example:
    This example computes a matrix-matrix product for A and B, where the complex symmetric matrix A is
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (2.000000,3.000000i)    (5.000000,2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,4.000000i)    (4.000000,4.000000i)    (5.000000,4.000000i)    (2.000000,0.000000i)

    and the matrix B is
       (1.000000,2.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)

void test_f06ztc()    //test for function zsymm(f06ztc)
{
   int nColRows_sy=4;
   int nCols_b=4;

   matrix<complex>  mat_sy={{1,8+3i,2+3i,3+4i},
                           {8+3i,3,5+2i,4+4i},
                           {2+3i,5+2i,2,5+4i},
                           {3+4i,4+4i,5+4i,2}};

   matrix<complex> mat_b={{1+2i,1,1,1},{1,1,1,1},{1,1,1,1},{1,1,1,1}};

   matrix<complex> mat_c(nColRows_sy,nCols_b);
   mat_c=0;

   zsymm(LeftSide,UpperTriangle,nColRows_sy,nCols_b,1,
                mat_sy,nColRows_sy,mat_b,nCols_b,1,mat_c,nCols_b);

   printf("Compute a matrix-matrix product for a complex symmetric matrix A and a general complex matrix B, C=A*B:\n");

   int i,j;

   printf("A=\n");                     //output complex symmetric matrix mat_h
   for(i=0;i<nColRows_sy;i++)
   {
       printf("       ");
       for(j=0;j<nColRows_sy;j++)
          printf("(%f,%fi)    ",mat_sy[i][j].m_re,mat_sy[i][j].m_im);
       printf("\n");
   }

   printf("B=\n");                     //output general complex matrix mat_b
   for(i=0;i<nColRows_sy;i++)
   {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("(%f,%fi)    ",mat_b[i][j].m_re,mat_b[i][j].m_im);
       printf("\n");
   }

   printf("C=\n");                     //output mat_c
   for(i=0;i<nColRows_sy;i++)
   {
       printf("       ");
       for(j=0;j<nCols_b;j++)
          printf("(%f,%fi)    ",mat_c[i][j].m_re,mat_c[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Compute a matrix-matrix product for a complex symmetric matrix A and a general complex matrix B, C=A*B:
A=
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (2.000000,3.000000i)    (5.000000,2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,4.000000i)    (4.000000,4.000000i)    (5.000000,4.000000i)    (2.000000,0.000000i)
B=
       (1.000000,2.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
C=
       (14.000000,12.000000i)    (14.000000,10.000000i)    (14.000000,10.000000i)    (14.000000,10.000000i)
       (14.000000,25.000000i)    (20.000000,9.000000i)    (20.000000,9.000000i)    (20.000000,9.000000i)
       (8.000000,13.000000i)    (14.000000,9.000000i)    (14.000000,9.000000i)    (14.000000,9.000000i)
       (6.000000,18.000000i)    (14.000000,12.000000i)    (14.000000,12.000000i)    (14.000000,12.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zsyrk

Function: zsyrk
Prototype:
void zsyrk(MatrixTriangle uplo,MatrixTranspose trans,int n,int k,complex alpha,const complex a[],int tda,complex beta,complex c[],int tdc)
Remarks: Perform a rank-k update of a complex symmetric matrix
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle of C is being reference.
trans=Notranspose: both A and B are n by k, return alpha*A*Transpose(A)+beta*C in array C;
trans=Transpose: both A and B are k by n, return alpha*Transpose(A)*A+beta*C in array C;
n
  the order of C
a[]
  the complex matrix of n by k(trans=Notranspose) or k by n(trans=Transpose)
tda
  the last dimension of A
c[]
  Input: the complex symmetric matrix C; Output: matrix C after update
tdc
  the last dimension of C

Return values:
Return: NULL

Example:
    This example perform a rank-k update of a complex sysmetric matrix C

void test_f06zuc()    //test for function zsyrk(f06zuc)
{
   int nRows=4;
   int nCols=4;

   matrix<complex>  mat_a={{1,8+3i,2+3i,3+4i},
                           {8+3i,3,5+2i,4+4i},
                           {2+3i,5-2i,2,5+4i},
                           {3+4i,4-4i,5-4i,2}};

   matrix<complex> mat_c(nRows,nRows);
   mat_c=0;

   zsyrk(UpperTriangle,NoTranspose,nRows,nCols,1,
                mat_a,nCols,1,mat_c,nRows);

   printf("Perform a rank-k update of a complex symmetric matrix C=A*conj(A)+C:\n");

   int i,j;
   for(i=0;i<nRows;i++)
        for(j=0;j<i;j++)
        {
            mat_c[i][j].m_re=mat_c[j][i].m_re;
            mat_c[i][j].m_im=mat_c[j][i].m_im;
        }

   printf("A=\n");                     //output complex  matrix mat_h
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("(%f,%fi)    ",mat_a[i][j].m_re,mat_a[i][j].m_im);
       printf("\n");
   }

   printf("C=\n");                     //output complex Hermitian matrix  mat_c
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nRows;j++)
          printf("(%f,%fi)    ",mat_c[i][j].m_re,mat_c[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Perform a rank-k update of a complex symmetric matrix C=A*conj(A)+C:
A=
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (2.000000,3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)
C=
       (44.000000,84.000000i)    (32.000000,59.000000i)    (51.000000,40.000000i)    (75.000000,-1.000000i)
       (32.000000,59.000000i)    (85.000000,100.000000i)    (36.000000,64.000000i)    (65.000000,27.000000i)
       (51.000000,40.000000i)    (36.000000,64.000000i)    (29.000000,32.000000i)    (26.000000,-11.000000i)
       (75.000000,-1.000000i)    (65.000000,27.000000i)    (26.000000,-11.000000i)    (6.000000,-48.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


zsyr2k

Function: zsyr2k
Prototype:
void zsyr2k(MatrixTriangle uplo,MatrixTranspose trans,int n,int k,complex alpha,const complex a[],int tda,const complex b[],int tdb,complex beta,complex c[],int tdc)
Remarks: Perform a rank-2k update of a complex symmetric matrix
Parameters:
uplo specify whether the upper (uplo=UpperTriangle) or lower (uplo=LowerTriangle) triangle of C is being reference.
trans=Notranspose: both A and B are n by k, return alpha*A*transpose(B)+alpha*B*transpose(A)+beta*C in array C;
trans=Transpose: both A and B are k by n, return alpha*transpose(A)*B+alpha*transpose(B)*A+beta*C in array C;
n
  the order of C
a[]
  the general matrix A
tda
  the last dimension of A
b[]
  the general matrix B
tdb
  the last dimension of B
c[]
  Input: the complex symmetric matrix C; Output: matrix C after update
tdc
  the last dimension of C

Return values:
Return: NULL

Example:
    This example perform a rank-2k update of a complex sysmetric matrix C

void test_f06zwc()    //test for function zsyr2k(f06zwc)
{
   int nCols=4;
   int nRows=4;

   matrix<complex>  mat_a={{1,8+3i,2+3i,3+4i},
                           {8-3i,3,5+2i,4+4i},
                           {2-3i,5-2i,2,5+4i},
                           {3-4i,4-4i,5-4i,2}};

   matrix<complex> mat_b={{1+2i,1,1,1},{1,1-4i,1,1},{1,1+1i,1,1},{1-4i,1,1,1}};

   matrix<complex> mat_c(nRows,nRows);
   mat_c=0;

   zsyr2k(UpperTriangle,NoTranspose,nRows,nCols,1,
                mat_a,nCols,mat_b,nCols,1,mat_c,nRows);

   printf("Perform a rank-2k update of a complex sysmmetric matrix C=C+A*transpose(B)+B*transpose(A):\n");

   int i,j;
   for(i=0;i<nRows;i++)
        for(j=0;j<i;j++)
        {
            mat_c[i][j].m_re=mat_c[j][i].m_re;
            mat_c[i][j].m_im=mat_c[j][i].m_im;
        }

   printf("A=\n");                     //output general complex matrix mat_a
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("(%f,%fi)    ",mat_a[i][j].m_re,mat_a[i][j].m_im);
       printf("\n");
   }

   printf("B=\n");                     //output general complex matrix mat_b
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nCols;j++)
          printf("(%f,%fi)    ",mat_b[i][j].m_re,mat_b[i][j].m_im);
       printf("\n");
   }

   printf("C=\n");                     //output complex symmetric matrix mat_c
   for(i=0;i<nRows;i++)
   {
       printf("       ");
       for(j=0;j<nRows;j++)
          printf("(%f,%fi)    ",mat_c[i][j].m_re,mat_c[i][j].m_im);
       printf("\n");
   }
}

   The output is as following:
Perform a rank-2k update of a complex sysmmetric matrix C=C+A*transpose(B)+B*transpose(A):
A=
       (1.000000,0.000000i)    (8.000000,3.000000i)    (2.000000,3.000000i)    (3.000000,4.000000i)
       (8.000000,-3.000000i)    (3.000000,0.000000i)    (5.000000,2.000000i)    (4.000000,4.000000i)
       (2.000000,-3.000000i)    (5.000000,-2.000000i)    (2.000000,0.000000i)    (5.000000,4.000000i)
       (3.000000,-4.000000i)    (4.000000,-4.000000i)    (5.000000,-4.000000i)    (2.000000,0.000000i)
B=
       (1.000000,2.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,-4.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,0.000000i)    (1.000000,1.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
       (1.000000,-4.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)    (1.000000,0.000000i)
C=
       (28.000000,24.000000i)    (52.000000,-3.000000i)    (31.000000,21.000000i)    (36.000000,0.000000i)
       (52.000000,-3.000000i)    (40.000000,-18.000000i)    (26.000000,-15.000000i)    (6.000000,-57.000000i)
       (31.000000,21.000000i)    (26.000000,-15.000000i)    (32.000000,8.000000i)    (20.000000,-17.000000i)
       (36.000000,0.000000i)    (6.000000,-57.000000i)    (20.000000,-17.000000i)    (-4.000000,-48.000000i)

Summary:
Sample data:
Header file: OCN_f06.h
See also:


nag_summary_stats_1var

Function: nag_summary_stats_1var
Prototype:
int nag_summary_stats_1var(int n,const double x[],const double wt[],int* nvalid,double *xmean,double *xsd,double *xskew = NULL,double *xkurt = NULL,double *xmin = NULL,double *xmax = NULL,double *wsum = NULL)
Remarks: calculates the mean, standard deviation, coefficients of skewness and kurtosis, and the maximum and minimum values of a set of ungrouped data. Weighting may be used.
Parameters:
n
  the number of observations
x[]
  the sample of observations, x[i]. i = 0,1,2 ..., n
wt[]
  the weight, can be NULL is not specified
nvalid
  the number of valid observations, (n) minus number of missing values
wsum
  the sum of weights, equals (n) if no weight is specified

Return values:
The function returns NAG error code or 0 if no error.
NE_INT_ARG_LE(12):	On entry, n must not be less than or equal to 0: n =value.
NE_CASES_ONE(401): The number of valid cases is one. In this case,standard deviation and coeficients of skewness and of kurtosis cannot be calculated.
NE_CASES_ZERO(400): The number of valid cases is zero.
NE_REAL_ARG_LT(5): On entry, wt [value] must not be less than 0.0: wt [value ]=value
success is 0.
successfully call of the nag_summary_stats_1var function.

Example:
    Read a set of data with 10 unweighted data values from worksheet "Data1",
    calculates the mean, standard deviation, coeffieients of skewness and kurtosis,
    and the maximum and minimum values.

    double xsd,xskew, xkurt, wsum, xmean, xmax, xmin;
    double * wt;
    int sucess, weight, nvalid = 10;
    wt = NULL;
    Dataset xx("data1",0);
    //Dataset cannot be used as a parameter, but vector can.
    vector x = xx;
    sucess = nag_summary_stats_1var(nvalid, x, wt, &nvalid, &xmean, &xsd, &xskew,
            &xkurt, &xmin, &xmax, &wsum);

    In the example, there is one set of data with 24 unweighted data values.

void  test_nag_summary_stats_1var()
{
    double xsd,xskew, xkurt, wsum, xmean, xmax, xmin;
    double * wt;
    int sucess,i, weight, j, nvalid = 24;
    double x[24] = {193.0, 215.0, 112.0, 161.0, 92.0, 140.0, 38.0, 33.3, 279.0,
                    249.0, 473.0, 339.0, 60.0, 130.0, 20.0, 50.0, 257.0, 284.0,
                    447.0, 52.0, 67.0, 61.0, 150.0, 2220.0};
    wt = NULL;

    sucess = nag_summary_stats_1var(nvalid, x, wt, &nvalid, &xmean, &xsd, &xskew,
            &xkurt, &xmin, &xmax, &wsum);

       printf("Number of cases is %d\n", nvalid);
       printf("And there is no weight\n");
       printf("The input is following : x=\n");

       for(i=0; i<24; i++)
    {
        printf("%10.1f", x[i]);
        if((i+1)%10 == 0)
        printf("\n");
    }

    printf("\nsucess is%d\n", sucess);
    if(sucess == 0)
    {
        printf("\nsucessfully call of the nag_summary_stats_1var function\n");
        printf("the output is following:\n");
        printf("No of valid cases         %10d\n", nvalid);
        printf("mean                      %10.1f\n", xmean);
        printf("std devn                  %10.1f\n", xsd);
        printf("Skewness                  %10.1f\n", xskew);
        printf("Kurtosis                  %10.1f\n", xkurt);
        printf("Minimun                   %10.1f\n", xmin);
        printf("Maximum                   %10.1f\n", xmax);
        printf("Sum of weights            %10.1f\n", wsum);
    }
    else
    {
        printf(" \n There are some problems.");
    }
}

    The output is following:

    No. of valid cases                24
    mean                           255.1
    std devn                       437.4
    Skewness                         3.9
    Kurtosis                        14.7
    Minimun                         20.0
    Maximum                       2220.0
    Sum of weights                  24.0

Summary: Mean, standard deviation, skewness, kurtosis etc, one variable, from raw data.
Sample data:
Header file: OCN_g01.h
See also:


nag_frequency_table

Function: nag_frequency_table
Prototype:
int nag_frequency_table(int n,const double x[],int num_class,Nag_ClassBoundary class_val,double cint[],int ifreq[],double *xmin,double *xmax)
Remarks: constructs a frequency distribution of a variable, according to either user-supplied, or routine-calculated class boundary values.
Parameters:
n
  the number of observations
x[]
  the sample of observations, x[i]. i = 0,1,2,...,n
num_class
  the number of classes desired in the frequency distribution
xmin
  the smallest value in the sample
xmax
  the largest value in the sample

Return values:
The function returns NAG error code or 0 if no error.
NE_INT_ARG_LT(11):	On entry, num_class must not be less than 2: num_class = <value>.  On entry, n must not be less than 1: n  =  <value>.
NE_BAD_PARAM(70): On entry, parameter class had an ellegal value.
NE_NOT_STRICTLY_INCREASING(63):	The sequence cint is not strictly increasing: cint[<value>] = <value>, cint[<value>] = <value>.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function.  Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
success is 0
sucessfully call of the  function nag_frequency_table

Example:
    Assume we have two worksheets, "Data1"'s datatype is double, "Data2"'s datatype
    is integer.  We have two columns in "Data1", the first column contains 70 data,
    and we have to put the result to the second column of "Data1" and first column
    of "Data2".

    double  xmax, xmin;
    int success, num_class = 7, iclass = 0, n = 70;
    Nag_ClassBoundary iclass_enum;
    iclass_enum = Nag_ClassBoundaryComp;
    Dataset aa("data1",0);
    aa.SetSize(n);
    Dataset cc("data1",1);
    cc.SetSize( 7 );
    Dataset difreq("data2",0);
    difreq.SetSize( 7 );
    vector a = aa, c = cc;
    vector<int> ifreq = difreq;
    success = nag_frequency_table(n, a, num_class, iclass_enum, c, ifreq, &xmin, &xmax );
    //write the result back to the worksheets.
    difreq = ifreq;
    cc = c;

    In this example, there are 70 observations.

void  test_nag_frequency_table()
{
    double  xmax, xmin;
    double c[7];
    int sucess, i, num_class = 7, iclass = 0, ifreq[7], n = 70;
    Nag_ClassBoundary iclass_enum;
    double a[70] = {22.3, 21.6, 22.6, 22.4, 22.4, 22.4, 22.1, 21.9, 23.1, 23.4,
                    23.4, 22.6,	22.5, 22.5, 22.1, 22.6, 22.3, 22.4, 21.8, 22.3,
                    22.1, 23.6, 20.8, 22.2,	23.1, 21.1, 21.7, 21.4, 21.6, 22.5,
                    21.2, 22.6, 22.2, 22.2, 21.4, 21.7, 23.2, 23.1, 22.3, 22.3,
                    21.1, 21.4, 21.5, 21.8, 22.8, 21.4, 20.7, 21.6, 23.2, 23.6,
                    22.7, 21.7, 23.0, 21.9, 22.6, 22.1, 22.2, 23.4, 21.5, 23.0,
                    22.8, 21.4, 23.2, 21.8, 21.2, 22.0, 22.4, 22.8, 23.2, 23.6};

    iclass_enum = Nag_ClassBoundaryComp;

    sucess = nag_frequency_table(n, a, num_class, iclass_enum, c, ifreq, &xmin, &xmax );

       printf("Number of cases is %d\n", n);
       printf("Number of calsses, including extreme classes %d\n", num_class);
       printf("routine -supplied class boundary\n\n\n");

       printf("the data are as following\n");

       for(i=0; i<70; i++)
    {
        printf("%10.1f", a[i]);
        if((i+1)%10 == 0)
        printf("\n");
    }

    printf("\nsucess is%d\n", sucess);

    if(sucess == 0)
    {
        printf("\nsucessfully call of the  function nag_frequency_table\n");
        printf("the output is following:\n");
        printf("***     Frequency distribution   ***\n");
        printf("        class             frequency\n");
        printf("up to           %5.2f             %d\n", c[0],ifreq[0]);
        for (i = 2; i<(num_class - 1); i++)
            printf("%5.2f  to   %5.2f             %d\n",c[i-2], c[i-1], ifreq[i-1]);
        printf("%5.2f        and over             %d\n", c[num_class - 2],ifreq[num_class-1]);
        printf("Total frequency  = 70 \n" );
        printf("Minimun                   %10.1f\n", xmin);
        printf("Maximum                   %10.1f\n", xmax);

    }
    else
    {
        printf(" \n There are some problems.");
    }

}

The output is following:

***     Frequency distribution   ***
        class             frequency
up to       20.70   	       0
20.70  to   21.28       	   6
21.28  to   21.86             16
21.86  to   22.44             21
22.44  to   23.02             14
23.60  and over		           0
Total frequency  = 70
Minimum                   20.7
Maximum                   23.6

Summary: Frequency table from raw data
Sample data:
Header file: OCN_g01.h
See also:


nag_5pt_summary_stats

Function: nag_5pt_summary_stats
Prototype:
int nag_5pt_summary_stats(int n,double x[],double res[])
Remarks: calculates a five-point summary for a single sample.
Parameters:
n
  the number of observations
x[]
  the sample of observations, x[i]. i = 0,1,2,...,n

Return values:
The function returns NAG error code or 0 if no error.
NE_INT_ARG_LT(11): On entry, n must not be less than 5: n = _value_.
NE_ALLOC_FAIL(73): Memory allocation failed.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function. Check the function call and array sizes.
If the function call is correct, please consult NAG for assistance.
successfully call of the nag_5pt_summary_stats function.

Example:

void test_nag_5pt_summary_stats()
{
    double res[5];
    int i, sucess, n=12;
    double x[12] = {12.0, 9.0, 2.0, 5.0, 6.0, 8.0, 2.0, 7.0, 3.0, 1.0, 11.0, 10.0};

    printf("\n the number of data is 12 and as following\n");
    for( i=0; i<12; i++)
        printf("%5.1f  ", x[i]);

    sucess = nag_5pt_summary_stats(n, x, res);
    if(sucess == 0)
    {
        printf("\nThe function has been sucessfully called\n");
        printf("the results are the following\n");
        printf("Maximum			 %8.4f\n", res[4]);
        printf("Upper hinge 	 %8.4f\n", res[3]);
        printf("Median			 %8.4f\n", res[2]);
        printf("Lower hinge		 %8.4f\n", res[1]);
        printf("Minimum			 %8.4f\n", res[0]);
    }
    else
        printf("The call is unsucessful.");
}

    The output is following:

    Maximum			  12.0000
    Upper hinge 	   9.5000
    Median			   6.5000
    Lower hinge		   2.5000
    Minimum			   1.0000

Summary: Five-point summary (median, hinges and extremes)
Sample data:
Header file: OCN_g01.h
See also:


nag_binomial_dist

Function: nag_binomial_dist
Prototype:
int nag_binomial_dist(int n,double p,int k,double *plek,double *pgtk,double *peqk)
Remarks: returns the lower tail, upper tail and point probabilities associated with a Binomial distribution.
Parameters:
n
  the parameter n of the binomial distribution
p
  the parameter p of the binomial distribution
k
  the integer k which defines the required probabilities
plek
  the lower tail probability
pgtk
  the upper tail probability
peqk
  the point probability

Return values:
The function returns NAG error code or 0 if no error.
NE_2_INT_ARG_GT(19): On entry, k = _value_ while n = _value_. These parameters must satisfy k = n.
NE_ARG_TOO_LARGE(410): On entry, n is too large to be represented exactly as a double precision number.
NE_INT_ARG_LE(12):	On entry, p must not be less than or equal to 0.0: p = _value_.
NE_REAL_ARG_GE(8): On entry, p must not be greater than or equal to 1.0: p = _value_.
NE_VARIANCE_TOO_LARGE(411): On entry, the variance (= np(1 - p)) exceeds 106.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function. Check the function call and array sizes.
If the function call is correct, please consult NAG for assistance.
successfully call of the nag_binomial_dist

Example:

void test_nag_binomial_dist()
{
    double plek, peqk, pgtk;
    int sucess, i;
    double p[4] = {0.5, 0.440, 0.750, 0.330};
    int n[4] = {4, 19, 100, 2000};
    int k[4] = {2, 13, 67, 700};

    printf("    n        p    k       plek        pgtk          peqk\n");
    for(i=0; i<4; i++)
    {
        sucess = nag_binomial_dist(n[i], p[i], k[i], &plek,	&pgtk, &peqk);
        if(sucess == 0)
            printf("%4d     %4.3f  %3d    %6.5f     %6.5f       %6.5f \n",n[i], p[i], k[i], plek, pgtk, peqk);
        else
            break;
    }
    if(sucess != 0)
        printf(" the function is not sucessfully called");
}

    The output is following:

        n        p    k       plek        pgtk          peqk
       4     0.500    2    0.68750     0.31250       0.37500
      19     0.440   13    0.99138     0.00862       0.01939
     100     0.750   67    0.04460     0.95540       0.01700
    2000     0.330  700    0.97251     0.02749       0.00312

Summary: Binomial distribution function
Sample data:
Header file: OCN_g01.h
See also:


nag_poisson_dist

Function: nag_poisson_dist
Prototype:
int nag_poisson_dist(double rlamda,int k,double *plek,double *pgtk,double *peqk)
Remarks: returns the lower tail, upper tail and point probabilities associated with a Poisson distribution.
Parameters:
rlamda
  the parameter lambda of the poisson distribution
k
  the integer k which defines the required probabilities
plek
  the lower tail probability
pgtk
  the upper tail probability
peqk
  the point probability

Return values:
The function returns NAG error code or 0 if no error.
NE_INT_ARG_LT(11): On entry, k must not be less than 0: k = _value_.
NE_REAL_ARG_LE(6): On entry, rlamda must not be less than or equal to 0.0: rlamda = _value_.
NE_REAL_ARG_GT(7): On entry, rlamda must not be greater than 106: rlamda = _value_.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function. Check the function call and array sizes.
If the function call is correct, please consult NAG for assistance.
successfully call of the nag_poisson_dist function

Example:

void test_nag_poisson_dist()
{
    double plek, peqk, pgtk;
    int sucess, i;
    int k[4] = {3, 12, 25, 175};
    double rlamda[4] = {0.75, 9.20, 34.00, 175.00};

    printf("  rlamda      k        plek        pgtk          peqk\n");
    for(i=0; i<4; i++)
    {
        sucess = nag_poisson_dist(rlamda[i], k[i], &plek, &pgtk, &peqk);
        if(sucess == 0)
            printf("%6.3f     %4d     %6.5f     %6.5f       %6.5f \n",rlamda[i], k[i], plek, pgtk, peqk);
        else
            break;
    }
    if(sucess != 0)
        printf(" the function is not sucessfully called");
}

    The output is following:

      rlamda      k        plek        pgtk          peqk
     0.750        3     0.99271     0.00729       0.03321
     9.200       12     0.86074     0.13926       0.07755
    34.000       25     0.06736     0.93264       0.02140
    175.000      175     0.52009     0.47991       0.03014

Summary: Poisson distribution function
Sample data:
Header file: OCN_g01.h
See also:


nag_hypergeom_dist

Function: nag_hypergeom_dist
Prototype:
int nag_hypergeom_dist(int n,int l,int m,int k,double *plek,double *pgtk,double *peqk)
Remarks: returns the lower tail, upper tail and point probabilities associated with a hypergeometric distribution.
Parameters:
n
  the parameter n of hypergeometric distribution
l
  the parameter l of hypergeometric distribution
m
  the parameter m of hypergeometric distribution
k
  the integer k which defines the required probabilities
plek
  the lower tail probability
pgtk
  the upper tail probability
peqk
  the point probability

Return values:
The function returns NAG error code or 0 if no error.
NE_INT_ARG_LT(11): On entry, n, l, k, m must not be less than 0: n, l, k, m = _value_.
NE_2_INT_ARG_GT(19): On entry, l = _value_ while n = _value_. These parameters must satisfy l = n.
On entry, m = _value_ while n = _value_. These parameters must satisfy m = n.
On entry, k = _value_ while l = _value_. These parameters must satisfy k = l.
On entry, k = _value_ while m = _value_. These parameters must satisfy k = m.
NE_4_INT_ARG_CONS(30): On entry, k = _value_, l = _value_, m = _value_, n = _value_. These parameters must satisfy k = l + m - n.
NE_REAL_ARG_LT(5): On entry, n is too large to be represented exactly as a double precision number.
NE_VARIANCE_TOO_LARGE(411): On entry, the variance = lm(n - l)(n - m)/[(n^2)(n - 1)] exceeds 10^6.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function. Check the function call and array sizes.
If the function call is correct, please consult NAG for assistance.
successfully call of the nag_hypergeom_dist function

Example:

void test_nag_hypergeom_dist()
{
    double plek, peqk, pgtk;
    int sucess, i;
    int n[4] = {10, 40, 155, 1000};
    int l[4] = {2, 10, 35, 444};
    int m[4] = {5, 3, 122, 500};
    int k[4] = {1, 2, 22, 220};

    printf(" the input data and results\n");
    printf("   n        l        m       k       plek         pgtk        peqk\n");
    for(i=0; i<4; i++)
    {
        sucess = nag_hypergeom_dist(n[i], l[i], m[i], k[i], &plek, &pgtk, &peqk);
        if(sucess == 0)
            printf("%4d     %4d     %4d    %4d    %6.5f      %6.5f     %6.5f \n",n[i], l[i], m[i], k[i], plek, pgtk, peqk);
        else
            break;
    }
    if(sucess != 0)
        printf(" the function is not sucessfully called");

}

    The ouput is following:

       n        l        m       k       plek         pgtk        peqk
      10        2        5       1    0.77778      0.22222     0.55556
      40       10        3       2    0.98785      0.01215     0.13664
     155       35      122      22    0.01101      0.98899     0.00779
    1000      444      500     220    0.42429      0.57571     0.04913

Summary: Hypergeometric distribution function
Sample data:
Header file: OCN_g01.h
See also:


nag_deviates_normal_dist

Function: nag_deviates_normal_dist
Prototype:
double nag_deviates_normal_dist(double p,NagError* fail=NULL)
Remarks: returns the deviate, xp, associated with the given lower tail probability, p, of the standardized Normal distribution. Example The deviates corresponding to several lower tail probabilities from the standard Normal distribution are calculated and printed. void test_nag_deviates_normal_dist() { double x; int i; double p[5] = {0.950, 0.500, 0.995, 0.750, 0.001}; printf(" the input data and results\n"); printf("prob. Deviate\n"); for(i=0; i<5; i++) { x = nag_deviates_normal_dist(p[i]); printf("%6.5f %6.5f\n",p[i], x); } } The output is following: prob. Deviate 0.95000 1.64485 0.50000 0.00000 0.99500 2.57583 0.75000 0.67449 0.00100 -3.09023
Parameters:
p
  the probablity, p, from the standardised Normal distribution
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_REAL_ARG_LE(6): On entry, p must not be less than or equal to 0.0: p = _value_.
NE_REAL_ARG_GE(8): On entry, p must not be greater than or equal to 1.0: p = _value_.
successfully call of the nag_deviates_normal_dist function.

Example:

Summary: Deviate of Normal distribution function
Sample data:
Header file: OCN_g01.h
See also:


nag_shapiro_wilk_test

Function: nag_shapiro_wilk_test
Prototype:
int nag_shapiro_wilk_test(int n,const double x[],Boolean calc_wts,double a[],double* w,double* pw)
Remarks: calculates Shapiro and Wilk’s W statistic and its significance level for testing Normality.
Parameters:
n
  the sample size, 3 <= n <= 2000
x[]
  the ordered sample values
calc_wts
  calculate weight or not
a[]
  weight
w
  the value of the statistics, W
pw
  the significance level of W

Return values:
The function returns NAG error code or 0 if no error.
NE_INT_ARG_LT(11): On entry, n must not be less than 3: n = _value_.
NE_REAL_ARG_GT(7):  On entry, n must not be greater than 2000: n = _value_.
NE_NON_MONOTONIC(83): On entry, the sequence in array x is non-monotonic. First anomaly detected at x[_value_] = _value_.
NE_ALL_ELEMENTS_EQUAL(260): On entry, all the values in the array x must not be equal.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function. Check the function call and array sizes.
If the function call is correct, please consult NAG for assistance.
successfully call of the nag_shapiro_wilk_test function.

Example:
    A program to test the following 2 samples (each of size 20) for Normality.

void test_nag_shapiro_wilk_test()
{
    double x[20];
    double w, swap, minvalue, pw;
    int i, j, k, sucess;
    int min;
    Boolean  calwts;
    double a[20] = {0.11, 7.87, 4.61, 10.14, 7.95, 3.14, 0.46, 4.43, 0.21, 4.75,
                    0.71, 1.52, 3.24, 0.93, 0.42, 4.97, 9.53, 4.55, 0.47, 6.66};
    double b[20] = {1.36, 1.14, 2.92, 2.55, 1.46, 1.06, 5.27, -1.11, 3.48, 1.10,
                    0.88, -0.51, 1.46, 0.52, 6.20, 1.69, 0.08, 3.67, 2.81, 3.49};

    // Sort the list.
    test_sort(20,a);
    printf("the input data \n");
    printf("the first set\n");
    for (i = 0; i < 20; i++)
    {
        printf("%3.2f  ",a[i]);
        if( (i+1) % 10 == 0)
            printf("\n");
    }

    printf("the results as following \n");

    calwts= true;
    sucess = nag_shapiro_wilk_test(20, a, calwts, x, &w, &pw);
    if(sucess == 0)
    {
        printf("value of W statistic = %5.4f\n",w);
        printf("Significance level is  %5.4f\n",pw);

    }
    else
    {
        printf("the function call  is not sucessful");
    }

    // Sort the list.
    test_sort(20,b);
    printf("\n\n\nthe input data \n");
    printf("the second set\n");
    for (i = 0; i < 20; i++)
    {
        printf("%3.2f  ",b[i]);
        if( (i+1) % 10 == 0)
            printf("\n");
    }

    printf("the results as following \n");

    calwts= false;
    sucess = nag_shapiro_wilk_test(20, b, calwts, x, &w, &pw);
    if(sucess == 0)
    {
        printf("value of W statistic = %5.4f\n",w);
        printf("Significance level is  %5.4f\n",pw);

    }
    else
    {
        printf("the function call  is not sucessful");
    }
    for(i = 0; i<20; i++)
        printf("%4.2f\n",a[i]);

}

//This function is used to sort a list.
void test_sort(int n, double a[])
{
    int i, j;
    int min;
    double swap, minvalue;

    for(i = 0; i < n; i++)
    {
        min = i;
        minvalue=a[i];
        for(j = i+1; j < n; j++)
        {
            if(minvalue > a[j])
            {
                minvalue = a[j];
                min = j;
            }
        }

        if(min != i)
        {
            swap = a[i];
            a[i] = a[min];
            a[min] = swap;
        }
    }
}

    The output is following:

    For sample number 1, value of W statistic = 0.8992
    Significance level is 0.0408
    For sample number 2, value of W statistic = 0.9583
    Significance level is 0.5171

Summary: Shapiro and Wilk's W test for Normality
Sample data:
Header file: OCN_g01.h
See also:


nag_ranks_and_scores

Function: nag_ranks_and_scores
Prototype:
int nag_ranks_and_scores(Nag_Scores scores,Nag_Ties ties,int n,const double x[],double r[])
Remarks: computes the ranks, Normal scores, an approximation to the Normal scores or the exponential scores as requested by the user.
Parameters:
n
  the number of observations
x[]
  the sample of observations, x[i]. i = 0,1,2,...,n
r[]
  output scores

Return values:
The function returns NAG error code or 0 if no error.
NE_INT_ARG_LT(11): On entry, n must not be less than 1: n = _value_.
NE_BAD_PARAM(70): On entry, parameter scores has an illegal value.  On entry, parameter ties has an illegal value.
NE_ALLOC_FAIL(73): Memory allocation failed.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_ranks_and_scores function

Example:

void test_nag_ranks_and_scores()
{
    int i;
    double aa[5] = {2, 0, 2, 2, 0};
    double bb[5];

    nag_ranks_and_scores(Nag_SavageScores,Nag_AverageTies, 5, aa, bb);
    printf("the input data\n");
    for( i = 0; i < 5; i++)
        printf("%4.0f   ",aa[i]);
    printf("\n\nthe results as following\n");
    for(i = 0;i < 5;i++)
        printf("%5.4f   \n",bb[i]);
}

    The output is following:

    1.4500
    0.3250
    1.4500
    1.4500
    0.3250

Summary: Ranks, Normal scores, approximate Normal scores or exponential (Savage) scores
Sample data:
Header file: OCN_g01.h
See also:


nag_prob_normal

Function: nag_prob_normal
Prototype:
double nag_prob_normal(Nag_TailProbability tail,double x,NagError* fail=NULL)
Remarks: returns a one or two tail probability for the standard distribution
Parameters:
x
  the value of the standard Normal variate
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_BAD_PARAM(70): On entry, parameter tail has an illegal value.
successfully call of the nag_prob_normal function

Example:
    Four values of tail and x are inputed and the probabilities are calculated and printed.

void test_nag_prob_normal()
{
    double prob, x;
    int i;
    Nag_TailProbability tail;
    char tail_char;

    tail_char = 'L';
    tail = Nag_LowerTail;
    x = 1.96;
    prob = nag_prob_normal(tail, x);
    printf("	Tail     X       Probability\n");
    printf("	 %c     %3.2f      %5.4f\n",tail_char,x,prob);

    tail_char = 'U';
    tail = Nag_UpperTail;
    prob = nag_prob_normal(tail, x);
    printf("	 %c     %3.2f      %5.4f\n",tail_char,x,prob);
    tail_char = 'C';
    tail = Nag_TwoTailConfid;
    prob = nag_prob_normal(tail, x);
    printf("	 %c     %3.2f      %5.4f\n",tail_char,x,prob);
    tail_char = 'S';
    tail = Nag_TwoTailSignif;
    prob = nag_prob_normal(tail, x);
    printf("	 %c     %3.2f      %5.4f\n",tail_char,x,prob);
}

    The output is following:

    Tail     X       Probability
     L     1.96      0.9750
     U     1.96      0.0250
     C     1.96      0.9500
     S     1.96      0.0500

Summary: Probabilities for the standard Normal distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_prob_students_t

Function: nag_prob_students_t
Prototype:
double nag_prob_students_t(Nag_TailProbability tail,double t,double df,NagError* fail=NULL)
Remarks: returns the lower tail,upper tail or two-tail probability for the Student’s t-distribution with real degrees of freedom.
Parameters:
t
  the value of the Student ’s t variate
df
  the degree of freedom
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_BAD_PARAM(70): On entry, parameter tail has an illegal value.
NE_REAL_ARG_LT(5):  On entry, df must not be less than 1.0: df = _value_.
successfully call of the nag_prob_students_t function

Example:
    Values from, and degrees of freedom for Student's t-distributions are read
    along with the required tail. The probabilities are calculated and printed
    until the end of data is reached.

void test_nag_prob_students_t()
{
    double prob;
    int i;
    Nag_TailProbability tail[4] = {Nag_LowerTail, Nag_UpperTail, Nag_TwoTailSignif, Nag_TwoTailConfid};
    double t[4] = {0.85, 0.85, 0.85, 0.85};
    double df[4] = {20.0, 20.0, 20.0, 20.0};

    printf("	t     df	  prob		tail\n");

    for( i = 0; i < 4; i++)
    {
        prob = nag_prob_students_t(tail[i], t[i], df[i]);
        if ( i == 0)
        printf("  %4.3f   %5.3f   %5.4f     Nag_LowerTail  \n",t[i], df[i], prob);
        if ( i == 1)
        printf("  %4.3f   %5.3f   %5.4f     Nag_UpperTail  \n",t[i], df[i], prob);
        if ( i == 2)
        printf("  %4.3f   %5.3f   %5.4f     Nag_TwoTailSignif  \n",t[i], df[i], prob);
        if ( i == 3)
        printf("  %4.3f   %5.3f   %5.4f     Nag_TwoTailConfid  \n",t[i], df[i], prob);
    }
}

    The ouput results are following:

        t     df	  	prob		tail
      0.850   20.000   	0.7973     Nag_LowerTail
      0.850   20.000   	0.2027     Nag_UpperTail
      0.850   20.000   	0.4054     Nag_TwoTailSignif
      0.850   20.000   	0.5946     Nag_TwoTailConfid

Summary: Probabilities for Student's t-distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_prob_chi_sq

Function: nag_prob_chi_sq
Prototype:
double nag_prob_chi_sq(Nag_TailProbability tail,double x,double df,NagError* fail=NULL)
Remarks: returns the lower or upper tail probability for the ÷ 2 distribution with real degrees of freedom.
Parameters:
x
  the value of the x^2 variate
df
  the degree of freedom
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_BAD_PARAM(70): On entry, parameter tail has an illegal value.
NE_REAL_ARG_LT(5):  On entry, x must not be less than 0.0: x = _value_.
NE_REAL_ARG_LE(6):  On entry, df must not be less than or equal to 0.0: df = _value_.
NE_ALG_NOT_CONV(405): The series used to calculate the gamma probabilities has failed to converge.  The result returned should represent an approximation to the solution.
successfully call of the nag_prob_chi_sq function

Example:
    Values from various Chi-square distributions are read, the lower-tail probabilities
    are calculated, and all these values are printed out, until the end of data is reached.

void test_nag_prob_chi_sq()
{
    double prob;
    int i;
    double df[3] = {20.0, 7.5, 45.0};
    double x[3] = {8.26, 6.2, 55.76};

    printf("the input data and results as following\n");
    printf("    x       df       prob\n");
    for( i = 0; i < 3; i++)
    {
        prob = nag_prob_chi_sq(Nag_LowerTail, x[i], df[i]);
        printf("  %5.3f    %5.3f      %5.4f\n", x[i], df[i], prob);
    }
}

    The output is following:

        x       df       prob

      8.260    20.000      0.0100
      6.200    7.500       0.4279
      55.760   45.000      0.8694

Summary: Probabilities for chi^2 distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_prob_f_dist

Function: nag_prob_f_dist
Prototype:
double nag_prob_f_dist(Nag_TailProbability tail,double f,double df1,double df2,NagError* fail=NULL)
Remarks: returns the probability for the lower or upper tail of the F or variance-ratio distribution with real degrees of freedom.
Parameters:
f
  the value of the F variate
df1
  the degree of freedom of the numerator variance, v1
df2
  the degree of freedom of the denominator variance, v2
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_BAD_PARAM(70): On entry, parameter tail has an illegal value.
NE_REAL_ARG_LT(5):  On entry, f must not be less than 0.0: f = _value_.
NE_REAL_ARG_LE(6):  On entry, df1 must not be less than or equal to 0.0: df1 = _value_.  On entry, df2 must not be less than or equal to 0.0: df2 = _value_.
successfully call of the nag_prob_f_dist function

Example:
    Values from, and degrees of freedom for F-distributions are read, the lower-tail
    probabilities are computed, and all these values are printed, until the end of data is reached.

void test_nag_prob_f_dist()
{
    double prob;
    int i;
    double df1[3] = {1.5, 1.0, 20.25};
    double df2[3] = {25.5, 1.0, 1.0};
    double f[3] = {5.5, 39.9, 2.5};

    printf(" the input data and results are the following:\n");
    printf("  f      df1     df2    prob\n");
    for(i = 0; i < 3; i++)
    {
        prob = nag_prob_f_dist(Nag_LowerTail, f[i], df1[i], df2[i]);
        printf("%4.3f  %4.3f    %5.3f  %5.4f\n",f[i], df1[i], df2[i], prob);
    }
}

    The ouput is following:

      f      df1     df2    prob

    5.500  1.500    25.500  0.9837
    39.900  1.000    1.000  0.9000
    2.500  20.250    1.000  0.5342

Summary: Probabilities for F-distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_prob_beta_dist

Function: nag_prob_beta_dist
Prototype:
int nag_prob_beta_dist(double x,double a,double b,double tol,double *p,double *q,double *pdf)
Remarks: computes the upper an lower tail probabilities and the probability density function of the beta distribution with parameters a and b.
Parameters:
x
  the value of the beta variate
a
  the first parameter required by the beta distribution
b
  the second parameter required by the beta distribution
tol
  the required accuracy of the solution
p
  the lower tail probability
q
  the upper tail probability
pdf
  the probability density function

Return values:
The function returns NAG error code or 0 if no error.
NE_REAL_ARG_LT(5): On entry, x must not be less than 0.0: x = _value_.
NE_REAL_ARG_GT(7): On entry, x must not be greater than 1.0: x = _value_.  On entry, a must not be greater than 106: a = _value_.  On entry, b must not be greater than 106: b = _value_.
NE_REAL_ARG_LE(6): On entry, a must not be less than or equal to 0.  0: a = _value_.  On entry, b must not be less than or equal to 0.0: b = _value_.
NE_RES_NOT_ACC(404): The requested accuracy has not been achieved. Use a larger value of tol.  The values returned for p and q should be reasonable approximations.
NE_PROBAB_CLOSE_TO_TAIL(409): The probability is too close to 0.0 or 1.0.  The result returned is either 0 or 1 as appropriate. This should be a good approximation to
the required solution.
successfully call of the nag_prob_beta_dist function

Example:
    Values for several beta distributions are read, and the probabilities
    calculated and printed, until the end of data is reached.

void test_nag_prob_beta_dist()
{
    double p, pdf, q;
    int i, sucess;
    double a[3] = {1.0, 1.5, 2.0};
    double b[3] = {2.0, 1.5, 1.0};
    double x[3] = {0.25, 0.75, 0.50};
    double tol[3] = {1.9, 0.0001, 1.01};

    printf("the input data and results\n");
    printf(" x			a			b			p			q			pdf\n");
    for(i = 0; i < 3; i++)
    {
        sucess = nag_prob_beta_dist( x[i], a[i], b[i],tol[i], &p, &q, &pdf);
        if( sucess == 0)
            printf("%5.4f  %9.4e		 %9.4e        %9.4e        %9.4e       %9.4e \n",x[i], a[i], b[i],
                    p, q, pdf);
        else
            break;
    }
    if(sucess != 0)
        printf("the function call is not sucessfully");
}

    The output is following:

     x				a			b						p			q					pdf
    0.2500  1.0000e+000		 2.0000e+000        4.3750e-001        5.6250e-001       1.5000e+000
    0.7500  1.5000e+000		 1.5000e+000        8.0450e-001        1.9550e-001       1.1027e+000
    0.5000  2.0000e+000		 1.0000e+000        2.5000e-001        7.5000e-001       1.0000e+000

Summary: Upper and lower tail probabilities and probability density function for the beta distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_gamma_dist

Function: nag_gamma_dist
Prototype:
double nag_gamma_dist(Nag_TailProbability tail,double g,double a,double b,NagError* fail=NULL)
Remarks: returns the lower or upper tail probability of the gamma distribution, with parameters alpha and beta.
Parameters:
g
  the value of the gamma variate
a
  the parameter alpha of the gamma distribution
b
  the parameter beta of the gamme distribution
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_BAD_PARAM(70): On entry, parameter tail has an illegal value.
NE_REAL_ARG_LT(5):  On entry, g must not be less than 0.0: g = _value_.
NE_REAL_ARG_LE(6):  On entry, a must not be less than or equal to 0.0: a = _value_.  On entry, b must not be less than or equal to 0.0: b = _value_.
NE_ALG_NOT_CONV(405): The algorithm has failed to converge in _value_ iterations.  The probability returned should be a reasonable approximation to the solution.
successfully call of the nag_gamma_dist function

Example:
    The following example reads in values for several gamma distributions, computes
    and prints the lower probabilities for each case, until the end of data is reached.

void test_nag_gamma_dist()
{
    double p;
    int i;
    double g[4] = {15.50, 0.50, 10.0, 5.0};
    double a[4] = {4.0, 4.0, 1.0, 2.0};
    double b[4] = {2.0, 1.0, 2.0, 2.0};

    printf("the input data and results are following\n");
    printf("Gamma deviate      Alpha     Beta      Lower tail prob.\n");
    for(i = 0; i < 4; i++)
    {
        p =  nag_gamma_dist(Nag_LowerTail, g[i], a[i], b[i]);
        printf("  %4.2f            %3.2f     %3.2f         %5.4f\n",g[i],a[i],b[i],p);
    }
}

    The output is following:

    Gamma deviate      Alpha     Beta      Lower tail prob.
      15.50            4.00     2.00         0.9499
      0.50             4.00     1.00         0.0018
      10.00            1.00     2.00         0.9933
      5.00             2.00     2.00         0.7127

Summary: Probabilities for the gamma distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_deviates_normal

Function: nag_deviates_normal
Prototype:
double nag_deviates_normal(Nag_TailProbability tail,double p,NagError* fail=NULL)
Remarks: returns the deviate associated with the given probability of the standard Normal distribution.
Parameters:
p
  the probability from the standard Normal distribution
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_BAD_PARAM(70): On entry, parameter tail has an illegal value.
NE_REAL_ARG_LE(6):  On entry, p must not be less than or equal to 0.0: p = 	value.
NE_REAL_ARG_GE(8):  On entry, p must not be greater than or equal to 1.0: p = 	value.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_deviates_normal function

Example:
    Four values of tail and x are input and the probabilities calculated and printed.

void test_nag_deviates_normal()
{

    double p, dev;
    int i;
    Nag_TailProbability tail;
    char tail_char;

    tail_char = 'L';
    tail = Nag_LowerTail;
    p = 0.975;
    dev = nag_deviates_normal(tail, p);
    printf("	Tail     Probability        Deviate\n");
    printf("	 %c     %4.3f      %5.4f\n",tail_char, p, dev);

    tail_char = 'U';
    tail = Nag_UpperTail;
    p = 0.025;
    dev = nag_deviates_normal(tail, p);
    printf("	 %c     %4.3f      %5.4f\n",tail_char, p, dev);

    tail_char = 'C';
    tail = Nag_TwoTailConfid;
    p = 0.95;
    dev = nag_deviates_normal(tail, p);
    printf("	 %c     %4.3f      %5.4f\n",tail_char, p, dev);
    tail_char = 'S';
    tail = Nag_TwoTailSignif;
    p = 0.05;
    dev = nag_deviates_normal(tail, p);
    printf("	 %c     %4.3f      %5.4f\n",tail_char, p, dev);

}

    The output is following:

    Tail     Probability        Deviate
     L       0.975              1.9600
     U       0.025              1.9600
     C       0.950              1.9600
     S       0.050              1.9600

Summary: Deviates for the Normal distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_deviates_students_t

Function: nag_deviates_students_t
Prototype:
double nag_deviates_students_t(Nag_TailProbability tail,double p,double df,NagError* fail=NULL)
Remarks: returns the deviate associated with the given tail probability of Student’s t-distribution with real degrees of freedom.
Parameters:
p
  the probability from the standard Normal distribution
df
  the degree of freedom
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_BAD_PARAM(70): On entry, parameter tail had an illegal value.
NE_REAL_ARG_LE(6):  On entry, p must not be less than or equal to 0.0: p = _value_.
NE_REAL_ARG_GE(8):  On entry, p must not be greater than or equal to 1.0: p = _value_.
NE_INT_ARG_LT(11): On entry, df must not be less than 1.0: df = _value_.
NE_SOL_CLOSE_TO_ZERO(406): The solution is too close to zero to be determined accurately.  This error will only occur when df = 1.0. The returned value of zero will be a good approximation in terms of absolute value but will have a poor relative precision.
NE_ALG_NOT_CONV(405): The solution has failed to converge.  However, the result should be a reasonable approximation.
successfully call of the nag_deviates_students_t function

Example:
    Lower tail probabilities are read for several t-distributions, and the
    corresponding deviates calculated and printed, until the end of data is reached.

void test_nag_deviates_students_t()
{
    double t;
    int i;
    double p[4] = {0.01, 0.85, 0.01, 0.99};
    double df[4] = {7.5, 20.0, 20.0, 45.0};
    Nag_TailProbability tail[4] = {Nag_LowerTail, Nag_UpperTail, Nag_TwoTailSignif, Nag_TwoTailConfid};

    printf("	p       df	   tail		  t\n");

    for( i = 0; i < 4; i++)
    {
        if(i != 1)
        {

            t = nag_deviates_students_t(tail[i], p[i], df[i]);
            if ( i == 0)
                printf("  %4.3f   %5.3f  Nag_LowerTail      %5.4f\n",p[i], df[i], t);
            if ( i == 1)
                printf("  %4.3f   %5.3f  Nag_UpperTail      %5.4f\n",p[i], df[i], t);
            if ( i == 2)
                printf("  %4.3f   %5.3f  Nag_TwoTailSignif  %5.4f\n",p[i], df[i], t);
            if ( i == 3)
                printf("  %4.3f   %5.3f  Nag_TwoTailConfid  %5.4f\n",p[i], df[i], t);
        }
    }
}

    The output is following:

        p 			df 			tail 				t

    0.010       7.500       Nag_LowerTail           -2.9431
    0.010       20.000      Nag_TwoTailSignif       2.8453
    0.990       45.000      Nag_TwoTailConfid       2.6896

Summary: Deviates for Student's t-distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_deviates_chi_sq

Function: nag_deviates_chi_sq
Prototype:
double nag_deviates_chi_sq(double p,double df,NagError* fail=NULL)
Remarks: the deviate associated with the given lower tail probability of the distribution with real degrees of freedom.
Parameters:
p
  the probability p from the distribution
df
  the degree of freedom
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
On any of the error conditions listed below except NE_ALG_NOT_CONV(405) nag_deviates_chi_sq returns 0.0.
NE_REAL_ARG_LT(5): On entry, p must not be less than 0.0: p = _value_.
NE_REAL_ARG_GE(8): On entry, p must not be greater than or equal to 1.0: p = _value_.
NE_REAL_ARG_LE(6): On entry, df must not be less than or equal to 0.0: df = _value_.
NE_PROBAB_CLOSE_TO_TAIL(409): The probability is too close to 0.0 or 1.0.
NE_ALG_NOT_CONV(405): The algorithm has failed to converge in _value_ iterations.  The result should be a reasonable approximation.
NE_GAM_NOT_CONV(403): The series used to calculate the gamma probabilities has failed to converge.  This is an unlikely error exit.
successfully call of the nag_deviates_chi_sq function

Example:
    Lower tail probabilities are read for several Chi-square distributions, and
    the corresponding deviates calculated and printed, until the end of data is reached.

void test_nag_deviates_chi_sq()
{
    double x;
    int i;
    double p[3] = {0.01, 0.4279, 0.8694};
    double df[3] = {20.0, 7.5, 45.0};

    printf("the input data and results are following\n");
    printf("p		df		    x\n");
    for(i = 0; i < 3; i++)
    {
        x = nag_deviates_chi_sq(p[i], df[i]);
        printf("%5.4f     %5.3f		   %5.3f\n",p[i], df[i], x);
    }

}

    The output is following:

        p 			df 			x

        0.0100 		20.000 		8.260
        0.4279 		7.500 		6.200
        0.8694 		45.000 		55.759

Summary: Deviates for the chi^2 distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_deviates_f_dist

Function: nag_deviates_f_dist
Prototype:
double nag_deviates_f_dist(double p,double df1,double df2,NagError* fail=NULL)
Remarks: the deviate associated with the given lower tail probability of the F or variance-ratio distribution with real degrees of freedom.
Parameters:
p
  the probability from the standard Normal distribution
df1
  the degree of freedom of the numerator variance, v1
df2
  the degree of freedom of the denominator variance, v2
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
On any of the error conditions listed below except NAG_SOL_NOT_CONV(407) nag deviates f dist returns 0.0.
NE_REAL_ARG_LT(5): On entry, p must not be less than 0.0: p = _value_.
NE_REAL_ARG_GE(8): On entry, p must not be greater than or equal to 1.0: p = _value_.
NE_REAL_ARG_LE(6): On entry, df1 must not be less than or equal to 0.0: df1 = _value_.  On entry, df2 must not be less than or equal to 0.0: df2 = _value_.
NE_SOL_NOT_CONV(407): The solution has failed to converge.  However, the result should be a reasonable approximation.  Alternatively, nag deviates f dist can be used with a suitable setting of the parameter tol.
NE_PROBAB_CLOSE_TO_TAIL(409): The probability is too close to 0.0 or 1.0.  The value of fp cannot be computed. This will only occur when the large sample approximations are used.
successfully call of the nag_deviates_f_dist function

Example:
    Lower tail probabilities are read for several F-distributions, and the
    corresponding deviates calculated and printed, until the end of data is reached.

void test_nag_deviates_f_dist()
{
    double f;
    int i;
    double df1[3] = {10.0, 1.0, 20.25};
    double df2[3] = {25.5, 1.0, 1.0};
    double p[3] = {0.9837,0.9000, 0.5342};

    printf(" the input data and results are the following:\n");
    printf("  p      df1     df2     f\n");
    for(i = 0; i < 3; i++)
    {
        f = nag_deviates_f_dist(p[i], df1[i], df2[i]);
        printf("%4.3f   %4.3f       %5.3f      %5.4f\n",p[i], df1[i], df2[i], f);
    }
}

    The output is following:

      p      df1     	df2     	f

    0.984  	10.000    	25.500  	2.8366
    0.900  	1.000  	  	1.000  		39.8657
    0.534  	20.250    	1.000  		2.5004

Summary: Deviates for the F-distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_deviates_beta

Function: nag_deviates_beta
Prototype:
double nag_deviates_beta(double p,double a,double b,double tol=5e-6,NagError* fail=NULL)
Remarks: the deviate associated with the given lower tail probability of the beta distribution.
Parameters:
p
  the probability from the standard Normal distribution
a
  the first parameter of the beta distribution
b
  the second parameter of the beta distribution
tol
  the required accuracy of the solution
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
On any of the error conditions listed below except NE_RES_NOT_ACC(404) and NE_SOL_NOT_CONV(403) nag deviates beta returns 0.0.
NE_REAL_ARG_LT(5): On entry, p must not be less than 0.0: p = _value_.
NE_REAL_ARG_GT(7): On entry, p must not be greater than 1.0: p = _value_.  On entry, a must not be greater than 106: a = _value_.  On entry, b must not be greater than 106: b = _value_.
NE_REAL_ARG_LE(6): On entry, a must not be less than or equal to 0.0: a = _value_.  On entry, b must not be less than or equal to 0.0: b = _value_.
NE_RES_NOT_ACC(404): The requested accuracy has not been achieved. Use a larger value of tol.  There is doubt concerning the accuracy of the computed result. 100 iterations of the Newton-Raphson method have been performed without satisfying the accuracy criterion (see Section 6.1). The result should be a reasonable approximation of the solution.
NE_GAM_NOT_CONV(403): The solution has failed to converge.  However, the result should be a reasonable approximation.  Requested accuracy not achieved when calculating beta probability. The user should try setting tol larger.
successfully call of the nag_deviates_beta function

Example:
    Lower tail probabilities are read for several beta distributions, and the
    corresponding deviates calculated and printed, until the end of data is reached.

void test_nag_deviates_beta()
{
    double x;
    int i;
    double a[3] = {1.0, 1.5, 20.0};
    double b[3] = {2.0, 1.5, 10.0};
    double p[3] = {0.5, 0.99, 0.25};
    double tol[3] = {0.0, 0.0, 0.0};

    printf("the input data and results\n");
    printf(" probability   A	        	 B	       deviate\n");
    for(i = 0; i < 3; i++)
    {
       x= nag_deviates_beta(p[i], a[i], b[i], tol[i]);
       printf("%5.4f      %5.4f		 %4.3f        %5.4f\n",p[i], a[i], b[i], x);
    }
}

    The output is following:

    probability   A	        	 B	       deviate
    0.5000      1.0000		 2.000        0.2929
    0.9900      1.5000		 1.500        0.9672
    0.2500      20.0000		 10.000        0.6105

Summary: Deviates for the beta distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_deviates_gamma_dist

Function: nag_deviates_gamma_dist
Prototype:
double nag_deviates_gamma_dist(double p,double a,double b,double tol=5e-6,NagError* fail=NULL)
Remarks: the deviate associated with the given lower tail probability of the gamma distribution.
Parameters:
p
  the probability from the required gamma distribution
a
  the shape parameter of the gamma distribution
b
  the scale parameter of the gamma distribution
tol
  the required accuracy of the solution
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
On any of the error conditions listed below except NE_ALG_NOT_CONV(405) nag_deviates_gamma_dist returns 0.0.
NE_REAL_ARG_LT(5): On entry, p must not be less than 0.0: p = _value_.
NE_REAL_ARG_GE(8): On entry, p must not be greater than or equal to 1.0: p = _value_.
NE_REAL_ARG_LE(6): On entry, a must not be less than or equal to 0.0: a = _value_.  On entry, b must not be less than or equal to 0.0: b = _value_.
NE_REAL_ARG_GT(7): On entry, a must not be greater than 106: a = _value_.
NE_PROBAB_CLOSE_TO_TAIL(409): The probability is too close to 0.0 for given a result to be calculated.
NE_ALG_NOT_CONV(405): The algorithm has failed to converge in 100 iterations.  A larger value of tol should be tried. The result may be a reasonable approximation.
NE_GAM_NOT_CONV(403): The series used to calculate the gamma probabilities has failed to converge.  This is an unlikely error exit.
successfully call of the nag_deviates_gamma_dist function

Example:
    Lower tail probabilities are read for several gamma distributions, and the
    corresponding deviates calculated and printed, until the end of data is reached.

void test_nag_deviates_gamma_dist()
{
    double g;
    int i;
    double p[3] = {0.10, 0.4279, 0.8694};
    double a[3] = {1.0, 7.5, 45.0};
    double b[3] = {20.0, 0.1, 10.0};

    printf("the input data and results are following\n");
    printf("p      a     b      g.\n");
    for(i = 0; i < 3; i++)
    {
        g =  nag_deviates_gamma_dist(p[i], a[i], b[i], 0.0);
        printf("%4.3f      %5.4f    %5.3f      %5.3f\n",p[i], a[i], b[i], g);
    }
}

    The output is following:

    p      		a     		b      		g
    0.100      1.0000    20.000      2.107
    0.428      7.5000    0.100       0.670
    0.869      45.0000   10.000      525.979

Summary: Deviates for the gamma distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_prob_non_central_students_t

Function: nag_prob_non_central_students_t
Prototype:
double nag_prob_non_central_students_t(double t,double df,double delta,double tol=5e-6,int max_iter=100,NagError* fail=NULL)
Remarks: returns the lower tail probability for the non-central Student's t-distribution.
Parameters:
t
  the deviate from the Student's t-distribution, t
df
  the degree of freedom
delta
  the non-centrality of the distribution
tol
  the absolute accuracy required by the user
max_iter
  the maximum number of terms used in each of the summations
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_REAL_ARG_LT(5):  On entry, df must not be less than 1.0: df = <value>.
NE_INT_ARG_LT(11): On entry, max_iter must not be less than 1: max_iter = <value>.
NE_SERIES(415): One of the series has failed to converge with df = <value>.  Reconsider the requested tolerance and/or the maximum number of iterations.
NE_PROBABILITY(416): The probability is too small to calculate accurately.
NE_INTERNAL_ERROR(74):  An internal error has ocurred in this function.  Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_prob_non_central_students_t function.

Example:

void test_nag_prob_non_central_students_t()
{
    double prob;
    int i;
    double delta[3] = {2.0, 1.0, 0.0};
    double df[3] = {20.0, 7.5, 45.0};
    double t[3] = {-1.528, -0.188, 1.138};

    printf("the input data and the results are as following\n");
    printf("	t 	df	delta	   prob\n");
    for(i = 0; i < 3; i++)
    {
        prob = nag_prob_non_central_students_t(t[i], df[i], delta[i]);
        printf("%8.3f%8.3f%8.3f%8.4f%\n", t[i],df[i],delta[i],prob);
    }
}

    The output is following:(with default tol and max_iter)

        t 	df	delta	   prob
      -1.528  20.000   2.000  0.0003
      -0.188   7.500   1.000  0.1189
       1.138  45.000   0.000  0.8694

Summary: Computes probabilities for the non-central Student's t-distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_prob_non_central_chi_sq

Function: nag_prob_non_central_chi_sq
Prototype:
double nag_prob_non_central_chi_sq(double x,double df,double lambda,double tol=5e-6,int max_iter = 100,NagError *fail=NULL)
Remarks: returns the lower tail probability for the non-central chi-square distribution.
Parameters:
x
  the deviate from the chi-square distribution
df
  the degree of freedom
lambda
  the non-centrality parameter
tol
  the required accuracy of the solution
max_iter
  the maximum number of iterations to be performed
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_REAL_ARG_LT(5):  One entry, df must not be less than 0: df = <value>.  One entry, lambda must not be less than 0: lambda = <value>.  On entry, x must not be less than 0: x = <value>.
NE_2_REAL_ARG_CONS(31): On entry, df = <value> while lambda = <value>.  These parameters must satisfy lambda > 0 if df = 0.
NE_INT_ARG_LT(11): On entry, max_iter must not be less than 1: max_iter = <value>
NE_POISSON_WEIGHT(417): The initial value of the Poisson weight used in the summation of (1) was too small to be calculated.  The computed probability is likely to be zero.
NE_CONV(420): The solution has failed to converge in <value> iterations, consider increasing max_iter or tol.
NE_TERM_LARGE(418): The value of a term required in (2) is too large to be evaluated accurately.  The most likely cause of this error is that both x and lambda are too large.
NE_CHI_PROB(419): The calculations for the central chi-square probability has failed to converge.  A larger value of tol should be used.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function.  Check the function call and array sized.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_prob_non_central_chi_sq function

Example:

void test_nag_prob_non_central_chi_sq()
{
    double prob;
    int i;
    double x[3] = {8.26, 6.20, 55.76};
    double df[3] = {20.0, 7.5, 45.0};
    double lamda[3] = {3.5, 2.0, 1.0};

    printf("the input data and corresponding results are as following\n");
    printf("   x       df	  lambda prob\n");
    for(i = 0; i < 3; i++)
    {
        prob = nag_prob_non_central_chi_sq(x[i], df[i],lamda[i],5e-6,50);
        printf("%8.3f%8.3f%8.3f%8.4f\n",x[i], df[i], lamda[i], prob);
    }
}

    The output is following: (with default tol and max_iter)

    x		df	lambda	prob
    8.260	20.000	3.500	0.0032
    6.200	7.500	2.000	0.2699
    55.760	45.000	1.000	0.8443

Summary: Computes probabilities for the non-central chi^2 distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_prob_non_central_f_dist

Function: nag_prob_non_central_f_dist
Prototype:
double nag_prob_non_central_f_dist(double f,double df1,double df2,double lambda,double tol=5e-6,int max_iter = 500,NagError *fail=NULL)
Remarks: returns the lower tail probability for the non-central F-distribution
Parameters:
f
  the deviate from the F-distribution, F
df1
  the degree of freedom of the numerator variance, v1
df2
  the degree of freedom of the denominator variance, v2
lambda
  the non-centrality parameter
tol
  the required accuracy of the solution
max_iter
  the maximum number of iterations to be performed
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_REAL_ARG_CONS(9): On entry, df1 = <value>.  This parameter must satisfy 0 < df1 <= 1e6.  On entry, lambda = <value>.  This parameter must satisfy 0 <= lambda <= -2 * log(X02AMC).
NE_REAL_ARG_LE(6): On entry, df2 must not be less than or equal to 0: df2 = <value>.  On entry, f must not be less than or equal to 0: f = <value>.
NE_INT_ARG_LT(11): On entry, max_iter must not be less than 1: max_iter = <value>.
NE_CONV(420): The solution has failed to converge in <value> iterations, consider increasing max_iter or tol.
NE_PROB_F(421): The required probability cannot be computed accurately.  This may happen if the result would be very close to zero or one.  Alternatively the values of df1 and f may be too large.  In the later case, the user could try using a normal approximation, see Abramowitz and Stegun (1972).
NE_PROB_F_INIT(422): The required accuracy was not achieved when calculating the initial value of the central F or Chi-square probability.  The user should try a larger value of tol.  If the Ch-square approximation is being used then nag_prob_non_central_f_dist returns zero.  Otherwise, the value returned should be an approximation to the correct value.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function.  Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_prob_non_central_f_dist function

Example:

void test_nag_prob_non_central_f_dist()
{
    double prob;
    int i;
    double lambda[3] = {3.0, 2.0, 0};
    double df1[3] = {1.5, 1.0, 20.25};
    double f[3] = {5.5, 39.9, 2.5};
    double df2[3] = {25.5, 1.0, 1.0};

    printf("the input data and the results are as following\n");
    printf("	f 	d1f	 df2  lambda   prob\n");
    for(i = 0; i < 3; i++)
    {
        prob = nag_prob_non_central_f_dist(f[i], df1[i], df2[i], lambda[i], 5e-6, 50);
        printf("%8.3f%8.3f%8.3f%8.3f%8.4f%\n", f[i], df1[i], df2[i], lambda[i], prob);
    }
}

    The output is following: (with default tol and max_iter)

    f		df1		df2		lambda	prob
    5.500	1.5		25.5	3.000	0.8214
    39.90	1.0		1.0		2.000	0.8160
    2.500	20.25	1.0		0.000	0.5342

Summary: Computes probabilities for the non-central F-distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_prob_non_central_beta_dist

Function: nag_prob_non_central_beta_dist
Prototype:
double nag_prob_non_central_beta_dist(const double x,double a,double b,double lambda,double tol=5e-6,int max_iter=100,NagError* fail=NULL)
Remarks: the probability associated with the lower tail of the non-central beta distribution.
Parameters:
x
  the deviate from the beta distribution, for which the probability is to be found
a
  the first of the required beta distribution
b
  the second parameter of the beta distribution
lambda
  the non-centrality parameter of the beta distribution
tol
  the required accuracy of the solution
max_iter
  the maximum number of terms used in each of the summations
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_REAL_ARG_CONS(9):  On entry, x = <value>.  This parameter must satisfy 0 < x <= 1.  On entry, a = <value>.  This parameter must satisfy 0 < a <= 1e6.  On entry, b = <value>.  This parameter must satisfy 0 < b < 1e6.  On entry, lambda = <value>.  This parameter must satisfy 0 <= lambda <= -2 * log(X02AMC).
NE_INT_ARG_LT(11): On entry, max_iter must not be less than 1: max_iter = <value>.
NE_CONV(420):  The solution has failed to converge in <value> iterations, consider increasing max_iter or tol.
NE_PROB_LIMIT(423): The probability is too close to 0 or 1 for the algorithm to be able to calculate the required probability. nag_prob_non_central_beta_dist will return 0 or 1 as appropriate.  This should be a reasonable approximation.
NE_PROB_B_INIT(424):  The required accuracy was not achieved when calculating the initial value of the beta distribution.  The user should try a larger value of tol.  The returned value will be an approximation to the correct value.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function.  Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_prob_non_central_beta_dist function

Example:

void test_nag_prob_non_central_beta_dist()
{
    double prob;
    int i;
    double a[3] = {1.0, 1.5,2.0};
    double b[3] = {2.0, 1.5, 1.0};
    double x[3] = {0.25, 0.75, 0.50};
    double lambda[3] = {1.0, 0.5, 0.0};

    printf("the input data and the results are as following\n");
    printf("	x 	a	 b      lambda   prob\n");
    for(i = 0; i < 3; i++)
    {
        prob = nag_prob_non_central_beta_dist(x[i], a[i], b[i], lambda[i], 5e-6, 50);
        printf("%8.3f%8.3f%8.3f%8.3f%8.4f%\n",x[i], a[i], b[i], lambda[i], prob);
    }
}

    The output is following:

        x 	a	 b      lambda   prob
       0.250   1.000   2.000   1.000  0.3168
       0.750   1.500   1.500   0.500  0.7705
       0.500   2.000   1.000   0.000  0.2500

Summary: Computes probabilities for the non-central beta distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_bivariate_normal_dist

Function: nag_bivariate_normal_dist
Prototype:
double nag_bivariate_normal_dist(double x,double y,double rho,NagError* fail=NULL)
Remarks: the lower tail probability for the bivariate Normal distribution.
Parameters:
x
  the first arguement for which the bivariate Normal distribution funtion is to be evaluated
y
  the second arguement for which the bivariate Normal distribution funtion is to be evaluated
rho
  the correlation coefficent
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_REAL_ARG_LT(5): On entry, rho must not be less than -1.0: rho = _value_.
NE_REAL_ARG_GT(7): On entry, rho must not be greater than 1.0: rho = _value_.
successfully call of the nag_bivariate_normal_dist function

Example:
    Values of x and y for a bivariate Normal distribution are read along
    with the value of rho. The lower tail probabilities are computed.

void test_nag_bivariate_normal_dist()
{
    double prob;
    int i;
    double x[4] = {1.7, 0.0, 3.3,9.1};
    double y[4] = {23.1, 0.0, 11.1, 9.1};
    double rho[4] = {0.0, 0.1, 0.54, 0.17};

    printf("the input data and the results are as following\n");
    printf("	x 	y	 rho      prob\n");
    for(i = 0; i < 4; i++)
    {
        prob = nag_bivariate_normal_dist(x[i],	y[i], rho[i]);
        printf("%8.3f%8.3f%8.3f%8.4f\n",x[i],	y[i], rho[i], prob);
    }
}

    The output is following:

    x 		y	 	rho      prob
   1.700  23.100   0.000  	0.9554
   0.000   0.000   0.100  	0.2659
   3.300  11.100   0.540  	0.9995
   9.100   9.100   0.170  	1.0000

Summary: Probability for the bivariate Normal distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_multi_normal

Function: nag_multi_normal
Prototype:
double nag_multi_normal(Nag_TailProbability tail,int n,const double a[],const double b[],const double mean[],const double sigma[],int tdsig,double tol=5e-6,int maxpts = 100,NagError* fail=NULL)
Remarks: the upper tail, lower tail or central probability associated with multivariate Normal distribution of up to ten dimensions.
Parameters:
n
  the number of dimensions
a[]
  the lower bounds
b[]
  the upper bounds
mean[]
  the mean vector of the multivariate Normal distribution
sigma[]
  the variance/covariance matrix of the multivariate Normal distribution
tdsig
  the second dimension
tol
  the required accuracy of the solution
maxpts
  the maximum number of sub-intervals or the integrand evaluations
fail
  NAG error structure

Return values:
The function returns missing value (NANUM) if error occurs, 0 if no error.
NE_INT_ARG_CONS(15): On entry, n = <value>.  This parameter must satisfy 1 <= n <= 10.  On entry, maxpts = <value>.  This parameter must satisfy maxpts >= 4*n, if n >= 3.
NE_2_INT_ARG_LT(17): On entry, tdsig = <value> while n = <value>.  These parameters must satisfy tdsig >=n.
NE_REAL_ARG_CONS(9): On entry, tol = <value>.  This parameter must satisfy tol > 0, if n > 1.
NE_2_REAL_ARRAYS_CONS(60): On entry, a[<value>] = <value> while b[<value>] = <value>.  Constraint: if tail = Nag_Central, a[i] < b[i], for i = 0, 1, . . . , n - 1.
NE_BAD_PARAM(70): On entry, parameter tail had an illlegal value.
NE_ALLOC_FAIL(73): Memory allocation failed.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function.  Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
NE_POS_DEF(562): The matrix sigma is not positive definitely.
NE_ACC(561): The requested accuracy cannot be achieved.  Try increasing tol.  The returned result is an approximation to the required result.
NE_ROUND_OFF(563): Round_off error prevents the requested accuracy from being achieved.  Try increasing tol.  The returned result is an approximation to the required result.  This result will only occur if n = 3.
successfully call of the nag_multi_normal function

Example:

void test_nag_multi_normal()
{
    double prob;
    int i;
    Nag_TailProbability  tail_enum;
    double a[4] = {-2.0, -2.0, -2.0, -2.0};
    double b[4] = {2.0, 2.0, 2.0, 2.0};
    double sigma[16] = {1.0, 0.9, 0.9, 0.9, 0.9, 1.0, 0.9, 0.9,
                        0.9, 0.9, 1.0, 0.9, 0.9, 0.9, 0.9, 1.0};
    double mean[4] = {0.0, 0.0, 0.0, 0.0};

    tail_enum = Nag_Central;

    printf("for the inputs and corresponding results are as following\n");
    printf("mean has the value:\n");
    for(i = 0; i < 4; i++)
        printf("%2.1f    ",mean[i]);
    printf("\na has the value:\n");
    for(i = 0; i < 4; i++)
        printf("%2.1f    ",a[i]);

    printf("\nb has the value:\n");
    for(i = 0; i < 4; i++)
        printf("%2.1f    ",b[i]);

    printf("\nsigma has the value:\n");
    for(i = 0; i < 16; i++)
    {
        printf("%2.1f    ", sigma[i]);
        if((i + 1) % 4 ==0)
            printf("\n");
    }

    prob = nag_multi_normal(tail_enum, 4, a, b, mean, sigma, 4, 0.0001, 2000);
    printf("multiivariate Normal probability = %5.4f\n",prob);
}

    The output is following:

    multiivariate Normal probability = 0.9142

Summary: Computes probabilities for the multivariate Normal distribution
Sample data:
Header file: OCN_g01.h
See also:


nag_ken_spe_corr_coeff

Function: nag_ken_spe_corr_coeff
Prototype:
int nag_ken_spe_corr_coeff(int n,int m,double x[],int tdx,int svar[],int sobs[],double corr[],int tdc)
Remarks: calculates Kendall and Spearman rank correlation coefficients.
Parameters:
n
  the number of observations
m
  the number of variables
x[]
  the variable of each observation contained the ith observation on the jth variable
tdx
  the second dimension of the array x.
svar[]
  indicates which variables are to be included.
sobs[]
  indicates which observations are to be included.
corr[]
  return Spearman and Kendall rank correlation.
tdc
  the second dimension of the array corr as declared in the function  from which nag_ken_spe_corr_coe. is called.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, n must not be less than 2: n = _value_.  On entry, m must not be less than 2: m = _value_.
17: On entry tdx = _value_ while m = _value_. These parameters must satisfy tdx = m.  On entry tdc = _value_ while m = _value_. These parameters must satisfy tdc = m.
53: Value _value_ given to svar[_value_] not valid. Correct range for elements of svar is svar[i] = 0.  Value _value_ given to sobs[_value_] not valid. Correct range for elements of sobs is sobs[i] = 0.
450: Too fewobserv ations have been selected. On entry, sobs must contain at least 2 positive elements.
451: No variables have been selected. On entry, svar must contain at least 1 positive element.
73: Memory allocation failed.
74: An initial error has occured in this function. Check the function call and any array sizes.
successful call of the nag_ken_spe_corr_coe function

Example:
    Assume we have two Matrix, "Matrix1" and "Matrix2", they are all 20X20.
    "Matrix1" first three columns and first 7 rows contains totally 21 data.
    We will put the result to "Matrix2".

    int m = 3, n = 7, tdx = 20, tdc = 20;
    matrix x, corr;
    corr.SetSize(20,20);
    int *svarptr;
    int *sobsptr;
    int success;
    int svar[20] = {1, 1, 1};
    svarptr = svar;
    int sobs[20] = {1, 1, 1, 1, 1, 1, 1};
    sobsptr = sobs;
    Matrix xx("Matrix1");
    x = xx;
    success = nag_ken_spe_corr_coeff(n, m, x, tdx, svarptr, sobsptr, corr, tdc);
    //put the result to the Matrix2.
    Matrix mcorr("Matrix2");
    mcorr = corr;

    A program to calculate the Kendall and Spearman rank correlation coefficients from a set of data.
    The data consists of 7 observations for each of 3 variables, and there is no weight.

void test_nag_ken_spe_corr_coeff()
{
    int i, j, m, n, tdx, tdc;
    matrix x, corr;
    x.SetSize(20,20);
    corr.SetSize(20,20);
    int *svarptr;
    int *sobsptr;
    int success;
    char s, w;
    tdx = 20;
    tdc = 20;
    m = 3;
    n = 7;
    x[0][0] = 1.0;
    x[0][1] = 2.0;
    x[0][2] = 4.0;

    x[1][0] = 7.0;
    x[1][1] = 7.0;
    x[1][2] = 3.0;

    x[2][0] = 2.0;
    x[2][1] = 3.0;
    x[2][2] = 4.0;

    x[3][0] = 4.0;
    x[3][1] = 4.0;
    x[3][2] = 5.0;

    x[4][0] = 5.0;
    x[4][1] = 6.0;
    x[4][2] = 7.0;

    x[5][0] = 3.0;
    x[5][1] = 1.0;
    x[5][2] = 3.0;

    x[6][0] = 6.0;
    x[6][1] = 5.0;
    x[6][2] = 5.0;

    int svar[20] = {1, 1, 1};
    svarptr = svar;
    int sobs[20] = {1, 1, 1, 1, 1, 1, 1};
    sobsptr = sobs;

    printf("The input data are as follows\n");
    printf("m = 3, n = 7, and all variables and observations are included\n");
    printf("x\n");
    for(i = 0; i < 7; i++)
    {
        for(j = 0; j < 3; j++)
            printf("%2.1f, ",x[i][j]);
        printf("\n");
    }
    success = nag_ken_spe_corr_coeff(n, m, x, tdx, svarptr, sobsptr, corr, tdc);

    if(success == 0)
    {
        printf("\nCorrelation coefficients:\n\n");
        for (i=0; i<m; i++)
        {
            for (j=0; j<m; j++)
                printf("%8.5f ", corr[i][j]);
            printf("\n");
        }
    }

    else
    {
        printf("The function g02brc has some problem\n");
    }
}

    The output is as follows:

    The input data are as follows
    m = 3, n = 7, and all variables and observations are included
     x
    1.0, 2.0, 4.0,
    7.0, 7.0, 3.0,
    2.0, 3.0, 4.0,
    4.0, 4.0, 5.0,
    5.0, 6.0, 7.0,
    3.0, 1.0, 3.0,
    6.0, 5.0, 5.0,

    Correlation coefficients:

     1.00000  0.85714  0.12849
     0.71429  1.00000  0.33040
     0.10287  0.41148  1.00000

Summary: Spearman and Kendall rank correlation coefficients.
Sample data:
Header file: OCN_g02.h
See also:


nag_corr_cov

Function: nag_corr_cov
Prototype:
int nag_corr_cov(int n,int m,double x[],int tdx,int sx[],double wt[],double *sw,double wmean[],double std[],double r[],int tdr,double v[],int tdv)
Remarks: calculates the Pearson product-moment correlation coefficients and the variance-covariance matrix for a set of data. Weights may be used.
Parameters:
n
  number of observervations
m
  number of variables
x[]
  the variable of each observation contained the ith observation on the jth variable
tdx
  the second dimension of the array x.
sx[]
  indicates which p variables to include in the analysis
wt[]
  the (optional) frequency weighting for each observation.
sw
  the sum of weights
wmean[]
  the sample means
std[]
  the standard deviations
r[]
  the matrix of Pearson product-moment correlation coefficients.
tdr
  the second dimension of the array r.
v[]
  the variance-covariance matrix.
tdv
  the second dimension of the array v.

Return values:
The function returns NAG error code or 0 if no error.
12: On entry, n must be greater than 1: n = _value_.
11: On entry, m must not be less than 1: m = _value_.
17: On entry, tdx = _value_ while m = _value_.  These parameters must satisfy tdx = m.  On entry, tdr = _value_ while m = _value_.  The parameters must satisfy tdr = m.  On entry, tdv = _value_ while m = _value_.  These parameters must satisfy tdv = m.
399: On entry, at least one of the weights is negative.
444: On entry, at least one element of sx is negative.
445: On entry, no element of sx is positive.
442: On entry, the sum of weights is less than 1.0.
443: A variable has zero variance.  At least one variable has zero variance. In this case v and std are as calculated, but r will contain zero for any correlation involving a variable with zero variance.
73: Memory allocation failed.
successful call of the nag_corr_cov function

Example:
    A program to calculate the means, standard deviations, variance-covariance matrix and a matrix
    of Pearson product-moment correlation coefficients for a set of 3 observations of 3 variables.

void test_nag_corr_cov()
{

    matrix r, v;
    r.SetSize(5,5);
    v.SetSize(5,5);
    double  *wtptr;
    double sw, wmean[5], std[5];
    int i, j, n, m;
    char w;
    int tdx, tdr, tdv;
    int test;
    int success;

    tdx = 5;
    tdr = 5;
    tdv = 5;
    test = 0;
    m = 3;
    n = 3;
    w = 'w';
    double wt[5] = {9.1231, 3.7011, 4.5230};

    matrix x = 	{ {0.9310, 0.0900, 0.8870,0,0}, {0.0009, 0.0099, 0.0999,0,0},
                {0.1300, 1.3070, 0.3700,0,0}, {0, 0, 0, 0, 0} , {0, 0, 0, 0, 0} };

    if (w == 'w')
        wtptr = wt;
    else
        wtptr = NULL;
    success = nag_corr_cov(n, m, x, tdx, NULL, wtptr, &sw, wmean, std, r, tdr, v, tdv);
    if(success == 0)
    {
        if (wtptr)
            printf("\nCase %ld --- Using weights\n", ++test);
        else
            printf("\nCase %ld --- Not using weights\n", ++test);
        printf ("\nInput data\t\t  weight\n");
        for(i=0; i<n; i++)
            printf("%6.1f%6.1f%6.1f%6.1f\n",x[i][0],x[i][1],x[i][2],wt[i]);
        printf("\n");
        printf("Sample means\n");
        for(i=0; i<m; i++)
            printf("%6.1f\n",wmean[i]);
        printf("\nStandard deviation\n");
        for(i=0; i<m; i++)
            printf("%6.1f\n",std[i]);
        printf("\nCorrelation matrix\n");
        for(i=0; i<m; i++)
        {
            for(j=0; j<m; j++)
                printf(" %7.4f ",r[i][j]);
            printf("\n");
        }
        printf("\nVariance matrix\n");
        for(i=0; i<m; i++)
        {

            for(j=0; j<m; j++)
                printf(" %7.3f ",v[i][j]);
            printf("\n");
        }
        printf("\nSum of weights %6.1f\n", sw);
        ASSERT( is_equal( round(sw,1), 17.3 ) );

    }
    else
    {
        printf("There is some problem with function nag_corr_cov\n");
    }
}

        The output is as follows:

Case 0 --- Using weights

Input data		  weight
   0.9   0.1   0.9   9.1
   0.0   0.0   0.1   3.7
   0.1   1.3   0.4   4.5

Sample means
   0.5
   0.4
   0.6

Standard deviation
   0.4
   0.6
   0.3

Correlation matrix
  1.0000  -0.4932   0.9839
 -0.4932   1.0000  -0.3298
  0.9839  -0.3298   1.0000

Variance matrix
   0.197   -0.123    0.149
  -0.123    0.316   -0.063
   0.149   -0.063    0.117

Sum of weights   17.3

Summary: sum of weights, sample means, standard deviation, Pearson correlation coefficients variance-covariance matrix.
Sample data:
Header file: OCN_g02.h
See also:


nag_partial_corr

Function: nag_partial_corr
Prototype:
int nag_partial_corr(int m,int ny,int nx,int sz[],double r[],int tdr,double p[],int tdp)
Remarks: computes a partial correlation/variance-vovariance matrix from a correlation or variance-covariance matrix computed by nag_corr-cov.
Parameters:
m
  the number of variables in the variance-covariance/correlation matrix given in r.
ny
  the number of Y variables for which partial correlation coefficents are to be computed.
nx
  the number of X variables which are to be considered as fixed.
sz[]
  indicates which variables belong to set X and Y
r[]
  the variance-covariance or correlation matrix for the m variables as given by nag_corr_cov
tdr
  the second dimension of the array r.
p[]
  p contains the strict upper triangular part of the ny by ny partial correlation matrix and the lower triangle of the ny by ny partial variance-covariance matrix.
tdp
  the second dimension of the array p.

Return values:
The function returns NAG error or 0 if no error.
11: On entry, m must not be less than 3: m = <value>.  On entry, ny must not be less than 2: ny = <value>.  On entry, nx must not be less than 1; nx = <value>.
29: On entry, ny = <value>, nx = <value> and m = <value>.  These parameters must satisfy ny + nx <= m.
17: On entry, tdr = <value> while m = <value>.  These parameters must satisfy tdr >= m.  On entry, tdp = <value> while ny = <value>.  These parameters must satisfy tdp >= ny.
466: On entry, ny = <value> and there are not exactly ny values of isz < 0.  Number of values of isz < 0 = <value>.
467: On entry, nx = <value> and there are not exactly nx values of isz < 0.
73: Memory allocation failed.
74: An internal error has occurred in this function.  Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
498: On entry, either the variance-covariance matrix or the correlation matrix is not of full rank.  Try removing some of the x variables by setting the appropriate elements of isz to zero.
499: Either a diagonal element of the partial variance-covariance matrix is zero and/or a computed partial correlation coefficient is greater than one.  Both indicate that the matrix input in r was not positive-definite.
successful call of the nag_partial_corr function.

Example:
    Data, given by Osborn (1979), on the number of deaths, smoke (mg/m^3) and sulphur
    dioxide (parts/million) during an intense period of fog is input.  The correlations
    are  computed using nag_corr_cov (g02bxc) and the partial correlation between deaths
    and smoke given sulphur dioxide is computed using nag_partial_corr.

void test_nag_partial_corr()
{
    double r[9];
    double std[3];
    double v[9];
    double xbar[3];
    double sw;
    int success;
    int j, k, i, m, n, nx, ny;
    n = 15;
    m =3;

    double x[45] = {112, 0.30, 0.09, 140, 0.49, 0.16, 143, 0.61, 0.22,
                    120, 0.49, 0.14, 196, 2.64, 0.75, 294, 3.45, 0.86,
                    513 4.46, 1.34, 518, 4.46, 1.34, 430, 1.22, 0.47,
                    274, 1.22, 0.47, 255, 0.32, 0.22, 236, 0.29, 0.23,
                    256, 0.50, 0.26, 222, 0.32, 0.16, 213, 0.32, 0.16};
    nx = 1;
    ny = 2;
    int sz[3] = {-1, -1, 1};

    printf("The input data are as follows\n");
    printf("n = 15, n = 3, nx = 1, ny = 2\n");
    printf("x\n");
    for(i = 0; i < 45; i++)
    {
        printf("%3.2f, ",x[i]);
        if((i + 1) % 3 == 0)
            printf("\n");
    }
    printf("\nsz\n");
    for(i = 0; i < 3; i++)
        printf("%d, ", sz[i]);

    printf("\n");
    printf("\nThe results are as follows\n");
    success = nag_corr_cov(n, m, x, m, NULL, NULL, &sw, xbar, std, r, m, v, m);
    if(success == 0)
    {
        printf("\nCorreelation matrix\n\n");
        for(i = 0; i < m; i++)
        {
                for(j = 0; j < m; j++)
                    if(i > j)
                        printf("            ");
                    else
                        printf("%7.4f     ",r[i * m + j]);
                printf("\n");
        }

        success =  nag_partial_corr(m, ny, nx, sz, v, m, r, m);
        if(success == 0)
        {
            printf("\n");
            printf("\nPartial Correlation matrix\n\n");
            for(i = 0; i < ny; i++)
            {
                for(j = 0; j < ny; j++)
                {
                    if(i > j)
                        printf("          ");
                    else if( i == j)
                        printf("%7.4f   ",1.0);
                    else
                        printf("%7.4f     ",r[i * m + j]);
                }
                printf("\n");
            }
        }
        else
        {
            printf("The function call of  nag_partial_corr has some problem\n");
        }
    }
    else
    {
        printf("The function nag_corr_cov has some problem\n");
    }
}

    The output is as follows:

    The input data are as follows
    n = 15, n = 3, nx = 1, ny = 2
    x
    112.00, 0.30, 0.09,
    140.00, 0.49, 0.16,
    143.00, 0.61, 0.22,
    120.00, 0.49, 0.14,
    196.00, 2.64, 0.75,
    294.00, 3.45, 0.86,
    5134.46, 1.34, 518.00,
    4.46, 1.34, 430.00,
    1.22, 0.47, 274.00,
    1.22, 0.47, 255.00,
    0.32, 0.22, 236.00,
    0.29, 0.23, 256.00,
    0.50, 0.26, 222.00,
    0.32, 0.16, 213.00,
    0.32, 0.16, 0.00,

    sz
    -1, -1, 1,

    The results are as follows

    Correelation matrix

     1.0000      0.1943      0.5257
                 1.0000     -0.1255
                             1.0000

    Partial Correlation matrix

     1.0000    0.3084
               1.0000

Summary: Partial correlation/variance-covariance matrix
Sample data:
Header file: OCN_g02.h
See also:


nag_simple_linear_regression

Function: nag_simple_linear_regression
Prototype:
int nag_simple_linear_regression(Nag_SumSquare mean,int n,double x[],double y[],double wt[],double *a,double *b,double *a_serr,double *b_serr,double *rsq,double *rss,double *df)
Remarks: performs a simple linear regression with or without a constant term. The data is optionally weighted.
Parameters:
n
  the number of observations
x[]
  the x observation
y[]
  the y observation
wt[]
  an (optional) weight is specified to be used in the weighted regression.
a
  the regression constant a
b
  the regression coefficient b
a_serr
  the standard error of the regression constant a.
b_serr
  the standard error of the regression coefficient b.
rsq
  the coefficient of determination
rss
  the sum of squares of the residuals about the regression.
df
  the degrees of freedom associated with the residual sum of squares.

Return values:
The function returns NAG error code or 0 if no error.
70: On entry, parameter mean had an illegal value.
11: On entry, n must not be less than 1: n = _value_ if mean = Nag AboutZero.  On entry, n must not be less than 2: n = _value_ if mean = Nag AboutMean.
399: On entry, at least one of the weights is negative.
446: On entry, wt must contain at least 1 positive element if mean = Nag AboutZero or at least 2p ositive elements if mean = Nag AboutMean.
452: On entry, all elements of x and/or y are equal.
447: On entry, the sum of elements of wt must be greater than 1.0 if mean = Nag AboutZero or greater than 2.0 if mean = Nag AboutMean.
426: On entry, the degrees of freedom for the residual are zero, i.e., the designated number of parameters = the effective number of observations.
448: Residual sum of squares is zero, i.e., a perfect .t was obtained.
successful call of the function nag_simple_linear_regression function.

Example:
    A program to calculate regression constants, a-hat and b-hat, the standard error of the regression
    constants, 	the regression coefficient of determination and the degrees of freedom about the regression.

void test_nag_simple_linear_regression()
{

    Nag_SumSquare mean;
    char m, w;
    int i, n;
    double a, b, err_a, err_b, rsq, rss, df;
    double *wtptr;
    int success;
    m = 'm';
    w = 'w';
    n = 8;
    double x[10] = {1.0, 0.0, 4.0, 7.5, 2.5, 0.0, 10.0, 5.0};
    double y[10] = {20.0, 15.5, 28.3, 45.0, 24.5, 10.0, 99.0, 31.2};
    double wt[10] = {1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0};

     printf("The input data are as follows\n");
     printf("n = 8, mean = Nag_AboutMean, wtptr =wt\n");
     printf("\nx\n");
     for(i = 0; i < 8; i++)
         printf("%2.1f, ",x[i]);
     printf("\ny\n");
     for(i = 0; i < 8; i++)
         printf("%3.1f, ",y[i]);
     printf("\nwt\n");
     for(i = 0; i < 8; i++)
         printf("%2.1f, ",wt[i]);
     printf("\n");
    if (m == 'M' || m == 'm')
        mean = Nag_AboutMean;
    else
        mean = Nag_AboutZero;
    if (w == 'W' || w == 'w')
    {
        wtptr = wt;
    }
    success =	nag_simple_linear_regression(mean, n, x, y, wtptr, &a, &b, &err_a, &err_b,
                                        &rsq, &rss, &df);
    if(success == 0)
    {
        if (mean == Nag_AboutMean)
        {
            printf("\nRegression constant a = %6.4f\n", a);
            printf("Standard error of the regression constant a = %6.4f\n",err_a);
        }
        printf("Regression coefficient b = %6.4f\n", b);
        printf("Standard error of the regression coefficient b = %6.4f\n", err_b);
        printf("The regression coefficient of determination = %6.4f\n", rsq);
        printf("The sum of squares of the residuals about the regression = %6.4f\n", rss);
        printf("Number of degrees of freedom about the regression = %6.4f\n",df);
    }
    else
    {
        printf("The function nag_simple_linear_regression does not work\n");
    }
}

    The output is as follows:

    The input data are as follows
    n = 8, mean = Nag_AboutMean, wtptr =wt

    x
    1.0, 0.0, 4.0, 7.5, 2.5, 0.0, 10.0, 5.0,
    y
    20.0, 15.5, 28.3, 45.0, 24.5, 10.0, 99.0, 31.2,
    wt
    1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,

    Regression constant a = 7.5982
    Standard error of the regression constant a = 6.6858
    Regression coefficient b = 7.0905
    Standard error of the regression coefficient b = 1.3224
    The regression coefficient of determination = 0.8273
    The sum of squares of the residuals about the regression = 965.2454
    Number of degrees of freedom about the regression = 6.0000

Summary: Regression const., SE of regression const., regression coefficient of determination sum of square, degree of freedom
Sample data:
Header file: OCN_g02.h
See also:


nag_regress_confid_interval

Function: nag_regress_confid_interval
Prototype:
int nag_regress_confid_interval(Nag_SumSquare mean,int n,double x[],double y[],double wt[],double clm,double clp,double yhat[],double yml[],double ymu[],double yl[],double yu[],double h[],double res[],double *rms)
Remarks: performs a simple linear regression with or without a constant term. The data is optionally weighted, and confidence intervals are calculated for the predicted and average values of y at a given x.
Parameters:
n
  the number of observations
x[]
  observations on the independent variable X (all the values X must not be identical)
y[]
  observations on the dependent variable, Y
wt[]
  an (optional) weight is specified to be used in the weighted regression.
clm
  the conffidence level for the confidence intervals for the mean.
clp
  the conffidence level for the prediction intervals.
yhat[]
  the fitted values
yml[]
  contains the lower limit of the confidence interval for the regression line.
ymu[]
  contains the upper limit of the confidence interval for the regression line.
yl[]
  contains the lower limit of the confidence interval for the individual y value.
yu[]
  contains the upper limit of the confidence interval for the individual y value
h[]
  the leverage of each observation on the regression.
res[]
  the residuals of the regression.
rms
  the residual mean square about the regression.

Return values:
The function returns NAG error or 0 if no error.
70: On entry, parameter mean had an illegal value.
11: On entry, n must not be less than 1: n = _value_ if mean = Nag AboutZero.  On entry, n must not be less than 2: n = _value_ if mean = Nag AboutMean.
8: On entry, clm must not be greater than or equal to 1.0: clm = _value_.  On entry, clp must not be greater than or equal to 1.0: clp = _value_.
6: On entry, clm must not be less than or equal to 0.0: clm = _value_.  On entry, clp must not be less than or equal to 0.0: clp = _value_.
399: On entry, at least one of the weights is negative.
446: On entry, wt must contain at least 1 positive element if mean = Nag AboutZero or at least 2 positive elements if mean = Nag AboutMean.
453: On entry, all elements of x are equal.
447: On entry, the sum of elements of wt must be greater than 1.0 if mean = Nag AboutZero and 2.0 if mean = Nag AboutMean.
449: Residual mean sum of squares is zero, i.e., a perfect .t was obtained.
successful call of the function nag_regress_confid_interval function.

Example:
     A program to calculate the fitted value of y and the upper and lower limits of the
     confidence interval for the regression line as well as the individual y values.

void test_nag_regress_confid_interval()
{

    Nag_SumSquare mean;
    int n;
    double clm, clp;
    double yhat[10], yml[10], ymu[10], yl[10], yu[10], h[10],
    res[10], rms;
    int i, success;
    char m, w;
    n = 9;
    clm = 0.95;
    clp = 0.95;
    m = 'm';
    w = 'w';
    double x[10] = {1.0, 2.0, 4.0, 2.0, 2.0, 3.0, 7.0, 4.0, 2.0};
    double y[10] = {4.0, 4.0, 5.1, 4.0, 6.0, 5.2, 9.1, 2.0, 4.1};
    double wt[10] = {1.0, 2.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0};

     printf("The input data are as follows\n");
     printf("n = 9, clp = 0.95, clm = 0.95, mean = Nag_AboutMean\n");
     printf("\nx\n");
     for(i = 0; i < 9; i++)
         printf("%2.1f, ",x[i]);
     printf("\ny\n");
     for(i = 0; i < 9; i++)
         printf("%3.1f, ",y[i]);
     printf("\nwt\n");
     for(i = 0; i < 9; i++)
         printf("%2.1f, ",wt[i]);
    if (m == 'm' || m == 'M')
    mean = Nag_AboutMean;
    else if (m == 'z'|| m == 'Z')
    mean = Nag_AboutZero;

    success = nag_regress_confid_interval(mean, n, x, y, wt, clm, clp,
                                         yhat, yml, ymu, yl, yu, h, res,&rms);

    if(success == 0)
    {
        printf("\nThe results are as follows\n");
        printf ("\ni       yhat[i]    yml[i]     ymu[i]     yl[i]      yu[i] \n\n");
        for (i=0; i < n; ++i)
        {
            printf("%ld %10.2f %10.2f", i, yhat[i], yml[i]);
            printf(" %10.2f %10.2f %10.2f\n",ymu[i], yl[i], yu[i]);
        }
    }

    else
    {
        printf("\nThe function nag_regress_confid_interval has some problem\n");
    }
}

    The output is as follows:

    The input data are as follows
    n = 9, clp = 0.95, clm = 0.95, mean = Nag_AboutMean

    x
    1.0, 2.0, 4.0, 2.0, 2.0, 3.0, 7.0, 4.0, 2.0,
    y
    4.0, 4.0, 5.1, 4.0, 6.0, 5.2, 9.1, 2.0, 4.1,
    wt
    1.0, 2.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
    The results are as follows

    i       yhat[i]    yml[i]     ymu[i]     yl[i]      yu[i]

    0       3.47       1.76       5.18      -0.46       7.40
    1       4.14       2.87       5.42       0.38       7.90
    2       5.49       4.15       6.84       1.71       9.27
    3       4.14       2.87       5.42       0.38       7.90
    4       4.14       2.87       5.42       0.38       7.90
    5       4.82       3.70       5.94       1.11       8.53
    6       7.52       4.51      10.53       2.87      12.16
    7       5.49       4.15       6.84       1.71       9.27
    8       4.14       2.87       5.42       0.38       7.90

Summary: Confidence Interval for the regression line and for the individual y value.
Sample data:
Header file: OCN_g02.h
See also:


nag_regsn_mult_linear

Function: nag_regsn_mult_linear
Prototype:
int nag_regsn_mult_linear(Nag_IncludeMean mean,int n,double x[],int tdx,int m,int sx[],int ip,double y[],double wt[],double *rss,double *df,double b[],double se[],double cov[],double res[],double h[],double q[],int tdq,Boolean *svd,int *rank,double p[],double tol,double com_ar[])
Remarks: performs a general multiple linear regression when the independent variables may be linearly dependent. Parameter estimates, standard errors, residuals and influence statistics are computed. nag_regsn_mult_linear may be used to perform a weighted regression.
Parameters:
n
  the number of observations
x[]
  the variable for which ith observation for the jth potential indepent variable.
tdx
  the second dimension of the array x.
m
  the total number of independent variables in the data set.
sx[]
  indicates which of the potential independent variables are to be included in the model.
ip
  the number p of independent variables in the model, including the mean or intercept if present.
y[]
  the observations on the dependent variable.
wt[]
  an (optional) weight is specified to be used in the weighted regression.
rss
  the residual sum of squares for the regression.
df
  the degree of freedom associated with the residual sum of squares.
b[]
  return the least-squares estimates of the parameters of the regression model.
se[]
  return the standard errors of the ip parameter estimates given in b.
cov[]
  return the variance-covariance matrix of estimated parameters in b.
res[]
  return the (weighted) residuals.
h[]
  return the diagonal elements of H.
q[]
  return the results of the QR decomposition.
tdq
  the second dimension of the array q.
svd
  return TRUE if a singular value decomposition has been performed, otherwise FALSE
rank
  return the rank of the independent variables.
p[]
  details of the QR decomposition and SVD if used.
tol
  the value of tol is used to decide what is the rank of the independent variables.
com_ar[]
  return information which is needed by nag_regsn_mult_linear_newyvar_if svd = TRUE.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, n must not be less than 2: n = _value_.  On entry, m must not be less than 1: m = _value_.  On entry, ip must not be less than 1: ip = _value_.  On entry, sx[_value_] must not be less than 0: sx[_value_] = _value_.
17: On entry, tdx = _value_ while m = _value_. These parameters must satisfy tdx = m.  On entry, tdq = _value_ while ip+1 = _value_. These parameters must satisfy tdq = ip+1.  On entry, n = _value_ while ip = _value_. These parameters must satisfy n = ip.
5: On entry, tol must not be less than 0.0: tol = _value_.  On entry, wt[_value_] must not be less than 0.0: wt[_value_] = _value_.
70: On entry, parameter mean had an illegal value.
425: Either a value of sx is < 0, or ip is incompatible with mean and sx, or ip > the effective number of observations.
427: The singular value decomposition has failed to converge.
426: The degrees of freedom for the residuals are zero, i.e., the designated number of parameters = the effective number of observations.  In this case the parameter estimates will be returned along with the diagonal elements of H, but neither standard errors nor the variance-covariance matrix will be calculated.
73: Memory allocation failed.
successful call of the nag_regsn_mult_linear function

Example:
    Data from an experiment with four treatments and three observations per treatment
    are read in.  The treatments are represented by dummy (0-1) variables. An
    unweighted model is fitted with a mean included in the model.

void test_nag_regsn_mult_linear()
{

    double rss, tol;
    int i, ip, rank, j, m, n;
    double df;
    Boolean svd;
    char weight, meanc;
    Nag_IncludeMean mean;
    double b[20];
    double cov[210], h[20], p[440];
    double res[20], se[20];
    double com_ar[495];
      double wt[20];
    matrix q;
    q.SetSize(20, 21);
    double *wtptr;
    n = 12;
    m = 4;
    mean = Nag_MeanInclude;
    wtptr =NULL;
    matrix x = 	{
                {1.0, 0.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 0.0, 1.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 1.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 1.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 0.0, 1.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 1.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 0.0, 1.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {1.0, 0.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 1.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {1.0, 0.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 1.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 1.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
                {0.0, 0.0, 0.0, 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}
                };

    double y[20] = {33.63, 39.62, 38.18, 41.46, 38.02, 35.83,
            35.99, 36.58, 42.92, 37.80, 40.43, 37.89};

    int sx[20] = {1, 1, 1, 1};

    printf("The  input data are as follows\n");
    printf("n = 12, m = 4, tol = 0.000001e0\n");
    printf("x\n");
    for(i = 0; i < n; i++)
    {
        for(j = 0; j < m; j++)
            printf("%2.1f, ",x[i][j]);
            printf("\n");
    }
    printf("\ny\n");
    for(i = 0; i < n; i ++)
    {
        printf("%5.3f, ", y[i]);
        if((i + 1) % 7 == 0)
            printf("\n");
    }

    ip = 0;
    if (mean==Nag_MeanInclude)
        ip += 1;
    for (i=0; i<m; i++)
        if (sx[i]>0) ip += 1;
    tol = 0.00001e0;
    nag_regsn_mult_linear(mean, n, x, 20, m, sx, ip, y,
        wtptr, &rss, &df, b, se, cov, res, h, q, 21, &svd, &rank, p, tol, com_ar);
    if (svd)
    {	printf("\nModel not of full rank, rank = %4ld\n", rank);
        ASSERT( rank == 4 );
    }
    printf("Residual sum of squares = %12.4e\n", rss);
    ASSERT( is_equal( round( rss, 3 ), 22.227 ) );
    printf("Degrees of freedom = %3.1f\n\n", df);
    ASSERT( is_equal( round( df, 1 ), 8.0 ) );
    printf("Variable       Parameter           Estimate Standard error\n\n");
    for (j=0; j<ip; j++)
        printf("%6ld%20.4e%20.4e\n", j+1, b[j], se[j]);

    printf("\n");
    printf("Obs            Residuals           h\n\n");
    for (i=0; i<n; i++)
        printf("%6ld%20.4e%20.4e\n", i+1, res[i], h[i]);
}

    The output is as follows:

    The  input data are as follows
    n = 12, m = 4, tol = 0.000001e0
    x
    1.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 0.0, 1.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    0.0, 0.0, 0.0, 1.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 0.0, 1.0,
    1.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    1.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    0.0, 1.0, 0.0, 0.0,

    y
    33.630, 39.620, 38.180, 41.460, 38.020, 35.830, 35.990,
    36.580, 42.920, 37.800, 40.430, 37.890,
    Model not of full rank, rank =    4
    Residual sum of squares =  2.2227e+001
    Degrees of freedom = 8.0

    Variable       Parameter           Estimate Standard error

          1         3.0557e+001         3.8494e-001
         2         5.4467e+000         8.3896e-001
         3         6.7433e+000         8.3896e-001
         4         1.1047e+001         8.3896e-001
         5         7.3200e+000         8.3896e-001

    Obs            Residuals           h

         1        -2.3733e+000         3.3333e-001
          2         1.7433e+000         3.3333e-001
         3         8.8000e-001         3.3333e-001
         4        -1.4333e-001         3.3333e-001
         5         1.4333e-001         3.3333e-001
         6        -1.4700e+000         3.3333e-001
         7        -1.8867e+000         3.3333e-001
         8         5.7667e-001         3.3333e-001
         9         1.3167e+000         3.3333e-001
           10         1.7967e+000         3.3333e-001
        11        -1.1733e+000         3.3333e-001
        12         5.9000e-001         3.3333e-001

Summary: Parameter estimates, standard errors, residuals ...
Sample data:
Header file: OCN_g02.h
See also:


nag_regsn_mult_linear_addrem_obs

Function: nag_regsn_mult_linear_addrem_obs
Prototype:
int nag_regsn_mult_linear_addrem_obs(Nag_UpdateObserv update,Nag_IncludeMean mean,int m,int sx[],double q[],int tdq,int ip,double x[],int nr,int tdx,int ix,double y,double *wt,double *rss)
Remarks: adds or deletes an observation from a general regression model fitted by nag_regsn_mult_linear.
Parameters:
m
  the total number of independent variables in the data set.
sx[]
  indicates which of the potential independent variables are to be included in the model.
q[]
  array q taken from output by_nag_regsn_mult_linear
tdq
  the last dimension of the array q.
ip
  the number of linear terms in general linear regression model (including mean if there is one).
x[]
  the ip values for the dependent variables of the observation to be added or deleted.
nr
  the number of rows of the notional two dimensional array x.
tdx
  the trailing dimension of the notional two dimensional array x.
ix
  the row of the two dimensional array x that contains the values for the dependent variables of the observation to be added or deleted.
y
  the value of the dependent variable for the observation to be added or deleted.
wt
  an (optional) weight for a new observation.
rss
  the value of the residual sums of squares for the original set of observations.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, ip must not be less than 1: ip = _value_.  On entry, m must not be less than 1: m = _value_.  On entry, ix must not be less than 1: ix = _value_.  On entry, nr must not be less than 1: nr = _value_.
17: On entry tdq = _value_ while ip + 1 = _value_. These parameters must satisfy tdq = ip + 1.  On entry tdx = _value_ while m = _value_. These parameters must satisfy tdx = m.
19: On entry ix = _value_ while nr = _value_. These parameters must satisfy ix = nr.
5: On entry, wt must not be less than 0.0: wt = _value_.  On entry, rss must not be less than 0.0: rss = _value_.
70: On entry, update had an illegal value.  On entry, mean had an illegal value.
437: On entry, for mean = Nag MeanInclude, number of non-zero values of sx must be equal to ip - 1: number of non-zero values of sx = _value_, ip - 1 = _value_.  On entry, for mean = Nag MeanZero, number of non-zero values of sx must be equal to ip: number of non-zero values of sx = _value_, ip = _value_.
429: The rss could not be updated because the input rss was less than the calculated decrease in rss when the new observation was deleted.
428: The R matrix could not be updated: to, either, delete non-existent observation, or, add an observation to R matrix with zero diagonal element.
73: Memory allocation failed.
successful call of the int nag_regsn_mult_linear_addrem_obs function.

Example:
    A data set consisting of 12 observations with four independent variables is read in
    and a general linear regression model fitted by nag_regsn_mult_linear (g02dac) and
    parameter estimates printed. The last observation is then dropped and the parameter
    estimates recalculated, using nag_regsn_mult_linear_upd model (g02ddc), and printed.

void test_nag_regsn_mult_linear_addrem_obs()
{

    double rss, tol;
    int i, ip, rank, j, m, n;
    double df;
    Boolean svd;
    char meanc, weight;
    Nag_IncludeMean mean;
    Nag_UpdateObserv update;
    double b[5];
    double cov[15];
    double h[12];
    double  p[35];
    double  res[12], se[5];
    double com_ar[45], wt[12];
    matrix q;
    q.SetSize(12,6);
    double *wtptr;
    int success;
    n = 12;
    m = 4;
    weight = 'u';
    meanc = 'z';

    if (meanc=='m')
        mean = Nag_MeanInclude;
    else
        mean = Nag_MeanZero;
    if (weight=='w')
        wtptr = wt;
    else
        wtptr = NULL;

    matrix xm = {{1.0, 0.0, 0.0, 0.0, 0}, {0.0, 0.0, 0.0, 1.0, 0},
                 {0.0, 1.0, 0.0, 0.0, 0}, {0.0, 0.0, 1.0, 0.0, 0},
                 {0.0, 0.0, 0.0, 1.0, 0}, {0.0, 1.0, 0.0, 0.0, 0},
                 {0.0, 0.0, 0.0, 1.0, 0}, {1.0, 0.0, 0.0, 0.0, 0},
                 {0.0, 0.0, 1.0, 0.0, 0}, {1.0, 0.0, 0.0, 0.0, 0},
                 {0.0, 0.0, 1.0, 0.0, 0}, {1.0, 1.0, 1.0, 1.0, 0}};
    double y[12] = {33.63, 39.62, 38.18, 41.46, 38.02, 35.83,
                    35.99, 36.58, 42.92, 37.80, 40.43, 37.89};

    int sx[5] =	{1, 1, 1, 1, 4};

    ip = 4;

    tol = 0.00001e0;

    success = nag_regsn_mult_linear(mean, n, xm, 5, m, sx, ip, y, wtptr, &rss,
                                    &df, b, se, cov, res, h, q, 6, &svd, &rank,
                                    p, tol, com_ar);

    if(success ==0)
    {
        printf("Results from g02dac\n\n");
        if (svd)
            printf("Model not of full rank\n");
        printf("Residual sum of squares = %12.4e\n", rss);
        printf("Degrees of freedom = %3.1f\n\n", df);
        printf("Variable       Parameter           Estimate Standard error\n\n");
        for (j=0; j<ip; j++)
            printf("%6ld%20.4e%20.4e\n", j+1, b[j], se[j]);
        printf("\n");
        update = Nag_ObservDel;
        success = nag_regsn_mult_linear_addrem_obs(update, mean, m, sx, q, 6, ip,
                                                    xm, 12, 5, 12, y[11], wtptr, &rss);
            printf("Results from dropping an observation using g02dcc\n");
            n = n - 1;
            nag_regsn_mult_linear_upd_model(n, ip, q, 6, &rss, &df, b, se, cov,
            &svd, &rank, p, tol);
            printf("Residual sum of squares = %12.4e\n", rss);
            printf("Degrees of freedom = %3.1f\n\n", df);
            printf("Variable       Parameter           Estimate Standard error\n\n");
            for (j=0; j<ip; j++)
                printf("%6ld%20.4e%20.4e\n", j+1, b[j], se[j]);
    }
    else
    {
        printf("There is some problem with the function nag_regsn_mult_linear\n");
    }

}

    The output is as follows:

    Results from g02dac

    Residual sum of squares =  5.2748e+003
    Degrees of freedom = 8.0

    Variable       Parameter           Estimate Standard error

         1         2.0724e+001         1.3801e+001
         2         1.4085e+001         1.6240e+001
         3         2.6324e+001         1.3801e+001
         4         2.2597e+001         1.3801e+001

    Results from dropping an observation using g02dcc
    Residual sum of squares =  2.1705e+001
    Degrees of freedom = 7.0

    Variable       Parameter           Estimate Standard error

         1         3.6003e+001         1.0166e+000
         2         3.7005e+001         1.2451e+000
         3         4.1603e+001         1.0166e+000
         4         3.7877e+001         1.0166e+000

Summary: Regression coefficients, standard errors and variance-covariance matrix.
Sample data:
Header file: OCN_g02.h
See also:


nag_regsn_mult_linear_upd_model

Function: nag_regsn_mult_linear_upd_model
Prototype:
int nag_regsn_mult_linear_upd_model(int n,int ip,double q[],int tdq,double *rss,double *df,double b[],double se[],double cov[],Boolean *svd,int *rank,double p[],double tol)
Remarks: calculates the regression parameters for a general linear regression model. It is intended to be called after nag_regsn_mult_linear_addrem_obs, nag_regsn_mult_linear_add_var or nag_regsn_mult_linear_delete_var.
Parameters:
n
  the number of observations
ip
  the number of terms in the regression model
q[]
  array q is taken from output by nag_regsn_mult_linear_addrem_obs, nag_regsn_mult_linear_add_var or nag_regsn_mult_linear_delete_var.
tdq
  the last dimension of the array q as declared in the function from which nag_regsn_mult_linear_upd_model is called.
rss
  the residual sum of squares.
df
  the degree of freedom associated with the residual sum of squares.
b[]
  the parameter estimates.
se[]
  the standard error of the parameter estimates.
cov[]
  the estimate variance-covariance matrix of parameter extimates.
svd
  TRUE if a singular value decomposition has been performed, otherwise FALSE.
rank
  the rank of the independent variables.
p[]
  contains details of the singular value decomposition if used.
tol
  the value of tol is used to decide if the independent variables are of full rank.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, n must not be less than 1: n = _value_.  On entry, ip must not be less than 1: ip = _value_.
17: On entry tdq = _value_ while ip + 1 = _value_. These parameters must satisfy tdq = ip + 1.  On entry, n = _value_ while ip = _value_. These parameters must satisfy n = ip.
430: The degrees of freedom for error are less than or equal to 0. In this case the estimates, ˆ ß, are returned but not the standard errors or covariances.
427: The singular value decomposition has failed to converge.  See nag_real_svd (f02wec). This is an unlikely error exit.
5: On entry, tol must not be less than 0.0: tol = _value_.
73: Memory allocation failed.
successful call of the function int nag_regsn_mult_linear_upd_model function.

Example:
    A data set consisting of 12 observations and four independent variables is input and
    a regression model fitted by calls to nag_regsn_mult_linear_add_var (g02dec).  The
    parameters are then calculated by nag_regsn_mult_linear_upd_model and the results printed.

void test_nag_regsn_mult_linear_upd_model()
{

    double rss, tol;
    int i, ip, rank, j, m, n;
    double df;
    Boolean svd;
    char weight;
    double cov[15];
    double p[35];

    double b[5];
    matrix q;
    q.SetSize(12, 6);
    int success;
     double se[5], wt[12],  xe[12];
    double *wtptr;
    n = 12;
    m = 4;
    weight = 'u';
    if (weight=='w')
    wtptr = wt;
    else
    wtptr = NULL;

    matrix x = {{1.0, 0.0, 0.0, 0.0, 0}, {0.0, 0.0, 0.0, 1.0, 0},
                {0.0, 1.0, 0.0, 0.0, 0}, {0.0, 0.0, 1.0, 0.0, 0},
                {0.0, 0.0, 0.0, 1.0, 0}, {0.0, 1.0, 0.0, 0.0, 0},
                {0.0, 0.0, 0.0, 1.0, 0}, {1.0, 0.0, 0.0, 0.0, 0},
                {0.0, 0.0, 1.0, 0.0, 0}, {1.0, 0.0, 0.0, 0.0, 0},
                {0.0, 0.0, 1.0, 0.0, 0}, {0.0, 1.0, 0.0, 0.0, 0}};
    q[0][0] = 33.63;
    q[1][0] = 39.62;
    q[2][0] = 38.18;
    q[3][0] = 41.46;
    q[4][0] = 38.02;
    q[5][0] = 35.83;
    q[6][0] = 35.99;
    q[7][0] = 36.58;
    q[8][0] = 42.92;
    q[9][0] = 37.80;
    q[10][0] = 40.43;
    q[11][0] = 37.89;

    printf("\nThe input data are as follows\n");
    printf("n = 12, m = 4, wtptr = NULL, tol = 0.000001e0, tdq = 6\n");
    printf("x\n");
    for(i = 0; i < 12; i ++)
    {
        for(j = 0; j < 3; j++)
            printf("%2.1f, ",x[i][j]);
        printf("\n");
    }
    printf("q[i][0]\n");
    for(i = 0; i < 12; i++)
        printf("%4.2f, ", q[i][0]);

    printf("\n\nThe results are follows\n\n");

    tol = 0.000001e0;
    ip = 0;
    for (j=0; j<m; ++j)
    {
        for (i=0; i<n; i++)
        xe[i] = x[i][j];
        success = nag_regsn_mult_linear_add_var(n, ip, q, 6, p, wtptr, xe, &rss, tol);
        if( success == 0)
                ip += 1;
        else if (success ==NE_NVAR_NOT_IND)
            printf(" *New variable not added *\n");
        else
            printf("This function has some problem\n");

    }
    rss = 0.0;
    success = nag_regsn_mult_linear_upd_model(n, ip, q, 6, &rss, &df, b, se, cov, &svd,
                    &rank, p, tol);
    if(success  == 0)
    {
        printf("\n");
        if (svd)
            printf("Model not of full rank\n\n");
        printf("Residual sum of squares = %12.4e\n", rss);
        printf("Degrees of freedom = %3.1f\n\n", df);

        printf("Variable       Parameter           Estimate Standard error\n\n");
        for (j=0; j<ip; j++)
            printf("%6ld%20.4e%20.4e\n", j+1, b[j], se[j]);
        printf("\n");
    }
    else
        printf("\nThe function of g02ddc has some problem\n");

}

    The output is as follows:

    The input data are as follows
    n = 12, m = 4, wtptr = NULL, tol = 0.000001e0, tdq = 6
    x
    1.0, 0.0, 0.0,
    0.0, 0.0, 0.0,
    0.0, 1.0, 0.0,
    0.0, 0.0, 1.0,
    0.0, 0.0, 0.0,
    0.0, 1.0, 0.0,
    0.0, 0.0, 0.0,
    1.0, 0.0, 0.0,
    0.0, 0.0, 1.0,
    1.0, 0.0, 0.0,
    0.0, 0.0, 1.0,
    0.0, 1.0, 0.0,
    q[i][0]
    33.63, 39.62, 38.18, 41.46, 38.02, 35.83, 35.99, 36.58, 42.92, 37.80, 40.43, 37.89,

    The results are follows

    Residual sum of squares =  2.2227e+001
    Degrees of freedom = 8.0

    Variable       Parameter           Estimate Standard error

         1         3.6003e+001         9.6235e-001
         2         3.7300e+001         9.6235e-001
         3         4.1603e+001         9.6235e-001
         4         3.7877e+001         9.6235e-001

Summary: Regression coefficients, standard errors and variance-covariance matrix.
Sample data:
Header file: OCN_g02.h
See also:


nag_regsn_mult_linear_add_var

Function: nag_regsn_mult_linear_add_var
Prototype:
int nag_regsn_mult_linear_add_var(int n,int ip,double q[],int tdq,double p[],double wt[],double x[],double *rss,double tol)
Remarks: adds a new independent variable to a general linear regression model.
Parameters:
n
  the number of observations
ip
  the number of independent variables already in the model
q[]
  the results of the QR decomposition for the model with p + 1 parameters.
tdq
  the last dimension of the array q.
p[]
  contains further details of the QR decomposition used.
wt[]
  an (optional) weighted is specified to be used in the weighted regression.
x[]
  the new independent variable
rss
  the residual sum of squares for the new fitted model
tol
  the value of tol is used to decide if the new independent variable is linearly related to independent variables already included in the model.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, n must not be less than 1: n = _value_.  On entry, ip must not be less than 0: ip = _value_.
20: On entry ip = _value_ while n = _value_. These parameters must satisfy ip < n.
17: On entry tdq = _value_ while ip+2 = _value_. These parameters must satisfy tdq = ip+2.
5: On entry, wt[_value_] must not be less than 0.0: wt[_value_] = _value_.
6: On entry, tol must not be less than or equal to 0.0: tol = _value_.
431: The new independent variable is a linear combination of existing variables. The (ip+1)th column of q is, therefore, null.
successful call of the int nag_regsn_mult_linear_add_var function.

Example:
    A data set consisting of 12 observations is read in. The four independent variables are stored in
    the array x while the dependent variable is read into the first column of q. If the character variable
    meanc indicates that a mean should be included in the model, a variable taking the value 1.0 for
    all observations is set up and fitted. Subsequently, one variable at a time is selected to enter the
    model as indicated by the input value of indx. After the variable has been added the parameter
    estimates are calculated by nag_regsn_mult_linear_upd_model (g02ddc) and the results printed.

void test_nag_regsn_mult_linear_add_var()
{

    double rss, rsst, tol;
    int i, ip, rank, j, m, n;
    double df;
    Boolean svd;
    char meanc, weight;
    Nag_IncludeMean mean;
    double b[5];
    double cov[15];
    double p[35];
    double se[5], wt[12];
    matrix y;
    y.SetSize(12, 5);
    double xe[12];
    double *wtptr;
    int success;

    n = 12;
    m = 4;
    weight = 'u';
    meanc = 'm';
    mean = Nag_MeanInclude;
    wtptr = NULL;

    matrix x = 	{{1.0, 1.4, 0.0, 0.0, 0}, {1.5, 2.2, 0.0, 0.0, 0},
                 {2.0, 4.5, 0.0, 0.0, 0}, {2.5, 6.1, 0.0, 0.0, 0},
                 {3.0, 7.1, 0.0, 0.0, 0}, {3.5, 7.7, 0.0, 0.0, 0},
                 {4.0, 8.3, 1.0, 4.0, 0}, {4.5, 8.6, 1.0, 4.5, 0},
                 {5.0, 8.8, 1.0, 5.0, 0}, {5.5, 9.0, 1.0, 5.5, 0},
                 {6.0, 9.3, 1.0, 6.0, 0}, {6.5, 9.2, 1.0, 6.5, 0}};

    matrix q = 	{{4.32, 0, 0, 0, 0, 0}, {5.21, 0, 0, 0, 0, 0},
                 {6.49, 0, 0, 0, 0, 0}, {7.10, 0, 0, 0, 0, 0},
                 {7.94, 0, 0, 0, 0, 0}, {8.53, 0, 0, 0, 0, 0},
                 {8.84, 0, 0, 0, 0, 0}, {9.02, 0, 0, 0, 0, 0},
                 {9.27, 0, 0, 0, 0, 0}, {9.43, 0, 0, 0, 0, 0},
                 {9.68, 0, 0, 0, 0, 0}, {9.83, 0, 0, 0, 0, 0}};

    int index[5] = {1, 3, 4, 2, 0};

    printf("The input data are as follows:\n");
    printf("\nm = 4, n = 12, wtptr = NULL,tol = 0.0000001e0");
    printf("ip = 0, mean = Nag_MeanInclude \n");
    printf("x\n");
    for(i = 0; i < 12; i++)
    {
         for( j = 0; j < 4; j++)
             printf("%2.1f, ",x[i][j]);
         printf("\n");
    }
    printf("\nq[i][0]\n");
    for(i = 0; i < 12; i++)
        printf("%3.2f, ",q[i][0]);

    tol = 0.000001e0;
    ip = 0;
    if(mean == Nag_MeanInclude)
    {
        for (i = 0; i<n; ++i)
            xe[i] = 1.0;
        nag_regsn_mult_linear_add_var(n, ip, q, 6, p, wtptr, xe, &rss,
        tol);
        ip = 1;
    }
    printf("\nxe\n");
    for(i = 0; i < n; i++)
        printf("%2.1f, ",xe[i]);
    printf("\nThe results are as follows\n");
    for(i = 0; i < 5; i++)
    {
        if(index[i] > 0)
        {
            for (j=0; j<n; j++)
                xe[j] = x[j][index[i]-1];
            success = nag_regsn_mult_linear_add_var(n, ip, q, 6, p, wtptr, xe, &rss,tol);
            if(success == 0)
            {
                ip += 1;
                printf("Variable %4ld added\n", index[i]);
                rsst = 0.0;
                nag_regsn_mult_linear_upd_model(n, ip, q, 6, &rsst, &df, b, se,
                cov, &svd, &rank, p, tol);
                if (svd)
                    printf("Model not of full rank\n\n");
                printf("Residual sum of squares = %13.4e\n", rsst);
                printf("Degrees of freedom = %3.1f\n\n", df);
                printf("Variable       Parameter           Estimate Standard error\n\n");
                for (j=0; j<ip; j++)
                    printf("%6ld%20.4e%20.4e\n", j+1, b[j], se[j]);
                printf("\n");
            }
            else if(success == NE_NVAR_NOT_IND)
                printf(" * Newvariable not added *\n");
            else
                printf("This function has some problem\n");
        }
    }
}

    The output is as follows:

    The input data are as follows:

    m = 4, n = 12, wtptr = NULL,tol = 0.0000001e0ip = 0, mean = Nag_MeanInclude
    x
    1.0, 1.4, 0.0, 0.0,
    1.5, 2.2, 0.0, 0.0,
    2.0, 4.5, 0.0, 0.0,
    2.5, 6.1, 0.0, 0.0,
    3.0, 7.1, 0.0, 0.0,
    3.5, 7.7, 0.0, 0.0,
    4.0, 8.3, 1.0, 4.0,
    4.5, 8.6, 1.0, 4.5,
    5.0, 8.8, 1.0, 5.0,
    5.5, 9.0, 1.0, 5.5,
    6.0, 9.3, 1.0, 6.0,
    6.5, 9.2, 1.0, 6.5,

    q[i][0]
    4.32, 5.21, 6.49, 7.10, 7.94, 8.53, 8.84, 9.02, 9.27, 9.43, 9.68, 9.83,
    xe
    1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
    The results are as follows
    Variable    1 added
    Residual sum of squares =   4.0164e+000
    Degrees of freedom = 10.0

    Variable       Parameter           Estimate Standard error

          1         4.4100e+000         4.3756e-001
         2         9.4979e-001         1.0599e-001

    Variable    3 added
    Residual sum of squares =   3.8872e+000
    Degrees of freedom = 9.0

    Variable       Parameter           Estimate Standard error

         1         4.2236e+000         5.6734e-001
         2         1.0554e+000         2.2217e-001
         3        -4.1962e-001         7.6695e-001

    Variable    4 added
    Residual sum of squares =   1.8702e-001
    Degrees of freedom = 8.0

    Variable       Parameter           Estimate Standard error

         1         2.7605e+000         1.7592e-001
          2         1.7057e+000         7.3100e-002
         3         4.4575e+000         4.2676e-001
         4        -1.3006e+000         1.0338e-001

    Variable    2 added
    Residual sum of squares =   8.4066e-002
    Degrees of freedom = 7.0

    Variable       Parameter           Estimate Standard error

         1         3.1440e+000         1.8181e-001
         2         9.0748e-001         2.7761e-001
         3         2.0790e+000         8.6804e-001
         4        -6.1589e-001         2.4530e-001
         5         2.9224e-001         9.9810e-002

Summary: Residual sum of squares.
Sample data:
Header file: OCN_g02.h
See also:


nag_regsn_mult_linear_delete_var

Function: nag_regsn_mult_linear_delete_var
Prototype:
int nag_regsn_mult_linear_delete_var(int ip,double q[],int tdq,int indx,double *rss)
Remarks: deletes an independent variable from a general linear regression model.
Parameters:
ip
  the number of independent variables already in the model
q[]
  the results of the QR decomposition as returned by the other nag regsn mult linear functions.
tdq
  the last dimension of the array q.
indx
  indicates which independent variable is to be deleted from the model.
rss
  the residual sum of squares for the full regression.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, ip must not be less than 1: ip = _value_.  On entry, indx must not be less than 1: indx = _value_.
17: On entry tdq = _value_ while ip+1 = _value_. These parameters must satisfy tdq = ip+1.
19: On entry indx = _value_ while ip = _value_. These parameters must satisfy indx = ip.
5: On entry, rss must not be less than 0.0: rss = _value_.
441: On entry, a diagonal element, _value_, of R is zero.
73 Memory allocation failed.
successful call of the nag_regsn_mult_linear_delete_var function.

Example:
    A data set consisting of 12 observations on four independent variables and one dependent
    variable is read in. The full model, including a mean term, is fitted using
    nag_regsn_mult_linear (g02dac). The value of indx is read in and that variable dropped from
    the regression. The parameter estimates are calculated by nag_regsn_mult_linear_upd_model (g02ddc)
    and printed. This process is repeated until indx is 0.

void test_nag_regsn_mult_linear_delete_var()
{
    double rss, tol;
    int i, indx, ip, rank, j, m, n;
    double df;
    Boolean svd;
    char meanc, weight;
    Nag_IncludeMean mean;
    double b[5];
    double cov[15], h[12], p[35];
    matrix q;
    q.SetSize(12,6);
    double res[12], se[5], com_ar[45],wt[12];
    double *wtptr;
    int sx[5];
    n = 12;
    m = 4;
    weight = 'u';
    meanc = 'm';
    mean = Nag_MeanInclude;
    wtptr = NULL;

    matrix x = {{1.0, 1.4, 0.0, 0.0, 0}, {1.5, 2.2, 0.0, 0.0, 0},
                {2.0, 4.5, 0.0, 0.0, 0}, {2.5, 6.1, 0.0, 0.0, 0},
                {3.0, 7.1, 0.0, 0.0, 0}, {3.5, 7.7, 0.0, 0.0, 0},
                {4.0, 8.3, 1.0, 4.0, 0}, {4.5, 8.6, 1.0, 4.5, 0},
                {5.0, 8.8, 1.0, 5.0, 0}, {5.5, 9.0, 1.0, 5.5, 0},
                {6.0, 9.3, 1.0, 6.0, 0}, {6.5, 9.2, 1.0, 6.5, 0}};

    double y[12] = {4.32, 5.21, 6.49, 7.10, 7.94, 8.53,
                    8.84, 9.02, 9.27, 9.43, 9.68, 9.83};

    int index[3] = {2, 4, 0};

    printf("The input data are as follows:\n");
    printf("\nm = 4, n = 12, wtptr = NULL,tol = 0.0000001e0");
    printf("ip = 0, mean = Nag_MeanInclude \n");
    printf("x\n");
    for(i = 0; i < 12; i++)
    {
         for( j = 0; j < 4; j++)
             printf("%2.1f, ",x[i][j]);
         printf("\n");
    }
    printf("\ny\n");
    for(i = 0; i < 12; i++)
        printf("%3.2f, ",y[i]);
    printf("\nindex\n");
    for(i = 0; i < 3; i++)
        printf("%d, ",index[i]);
    for (i=0; i<m; ++i)
        sx[i] = 1;
    printf("\nsx\n");
    for(i = 0; i < m; i++)
        printf("%d, ",sx[i]);
    printf("\nThe results are as follows\n");

    ip = m;
    if (mean==Nag_MeanInclude)
        ip += 1;
    printf("\nip = %d\n",ip);
    tol = 0.00001e0;
    nag_regsn_mult_linear(mean, n, x, 5, m, sx, ip, y, wtptr, &rss,
                            &df, b, se, cov, res, h, q, 6, &svd, &rank, p, tol, com_ar);
    printf("Results from full model\n");
    if(svd)
        printf("Model not of full rank\n\n");
    printf("Residual sum of squares = %13.4e\n", rss);
    printf("Degrees of freedom = %3.1f\n\n", df);

    for(i = 0; i < 3; i++)
    {
        if (index[i] != 0)
        {
            nag_regsn_mult_linear_delete_var(ip, q, 6, index[i], &rss);
            ip = ip - 1;
            if (ip == 0)
                printf("No terms left in model\n");
            else
            {
                printf("Variable %4ld dropped\n", index[i]);
                nag_regsn_mult_linear_upd_model(n, ip, q, 6, &rss, &df, b, se,cov, &svd, &rank, p, tol);
                printf("Residual sum of squares = %13.4e\n", rss);
                printf("Degrees of freedom = %3.1f\n\n", df);
                printf("Parameter       Estimate Standard error\n\n");
                for (j=0; j<ip; j++)
                    printf("%12.4e%15.4e\n", b[j], se[j]);
            }
        }
    }
}

    The output is as follows:

    The input data are as follows:

    m = 4, n = 12, wtptr = NULL,tol = 0.0000001e0ip = 0, mean = Nag_MeanInclude
    x
    1.0, 1.4, 0.0, 0.0,
    1.5, 2.2, 0.0, 0.0,
    2.0, 4.5, 0.0, 0.0,
    2.5, 6.1, 0.0, 0.0,
    3.0, 7.1, 0.0, 0.0,
    3.5, 7.7, 0.0, 0.0,
    4.0, 8.3, 1.0, 4.0,
    4.5, 8.6, 1.0, 4.5,
    5.0, 8.8, 1.0, 5.0,
    5.5, 9.0, 1.0, 5.5,
    6.0, 9.3, 1.0, 6.0,
    6.5, 9.2, 1.0, 6.5,

    y
    4.32, 5.21, 6.49, 7.10, 7.94, 8.53, 8.84, 9.02, 9.27, 9.43, 9.68, 9.83,
    index
    2, 4, 0,
    sx
    1, 1, 1, 1,
    The results are as follows

    ip = 5
    Results from full model
    Residual sum of squares =   8.4066e-002
    Degrees of freedom = 7.0

    Variable    2 dropped
    Residual sum of squares =   2.1239e-001
    Degrees of freedom = 8.0

    Parameter       Estimate Standard error

     3.6372e+000    1.5083e-001
      6.1264e-001    2.8007e-002
    -6.0154e-001    4.2335e-001
      1.6709e-001    7.8656e-002
    Variable    4 dropped
    Residual sum of squares =   3.3220e-001
    Degrees of freedom = 9.0

    Parameter       Estimate Standard error

      3.5974e+000    1.7647e-001
      6.2088e-001    3.2706e-002
      2.4247e-001    1.7235e-001

Summary: Residual Sum of Square.
Sample data:
Header file: OCN_g02.h
See also:


nag_regsn_mult_linear_newyvar

Function: nag_regsn_mult_linear_newyvar
Prototype:
int nag_regsn_mult_linear_newyvar(int n,double wt[],double *rss,int ip,int rank,double cov[],double q[],int tdq,Boolean svd,double p[],double y[],double b[],double se[],double res[],double com_ar[])
Remarks: calculates the estimates of the parameters of a general linear regression model for a new dependent variable after a call to nag_regsn_mult_linea.
Parameters:
n
  the number of observations
wt[]
  an optional weight is specified to be used in the weighted regression.
rss
  the residual sum of squares for the original dependent variable.
ip
  the number p of independent variables in the model.
rank
  the rank of the independent variables as given by (g02dac)
cov[]
  the estimate variance-covariance matrix of the parameter estimates as given by (g02dac)
q[]
  the results of the QR decomposition as returned by (g02dac)
tdq
  the second dimension of the array q.
svd
  indicates if a singular value decomposition was used by (g02dac).
p[]
  details of the QR decomposition and SVD, if used, as returned in array p by (g02dac).
y[]
  the new dependent variable.
b[]
  contain the least-squares estimates of the parameters of the regression model.
se[]
  contain the standard errors of the ip parameter estimates given in b.
res[]
  the residuals for the new regression model.
com_ar[]
  if svd = TRUE, com_ar must be unaltered from the previous call to (g02dac).

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, ip must not be less than 1: ip = _value_.
12: On entry, rank must not be less than or equal to 0: rank = _value_.
17: On entry, tdq = _value_ while ip + 1 = _value_. These parameters must satisfy tdq = ip + 1.  On entry, n = _value_ while ip = _value_. These parameters must satisfy n = ip.
6: On entry, rss must not be less than or equal to 0.0: rss = _value_.
5: On entry, wt[_value_] must not be less than 0.0: wt[_value_] = _value_.
434: On entry, the Boolean variable, svd, is FALSE and rank must be equal to ip: rank = _value_, ip = _value_.
435: On entry, the Boolean variable, svd, is TRUE and rank must not be greater than ip: rank = _value_, ip = _value_.
successful call of the nag_regsn_mult_linear_newyvar function.

Example:
    A data set consisting of 12 observations with four independent variables and two dependent variables
    is read in. A model with all four independent variables is fitted to the first dependent variable by
    nag_regsn_mult_linear (g02dac) and the results printed. The model is then fitted to the second
    dependent variable by nag_regsn_mult_linear_newyvar and those results printed.

void test_nag_regsn_mult_linear_newyvar()
{
    double rss, tol;
    int i, ip, rank, j, m, n;
    double df;
    Boolean svd;
    Nag_IncludeMean mean;
    char weight, meanc;
    double b[5], cov[15], h[12],p[35];
    matrix q;
    q.SetSize(12,6);
    double res[12], se[5], com_ar[45], wt[12];
    double *wtptr;
    n = 12;
    m = 4;
    weight = 'u';
    meanc = 'm';
    if (meanc=='m')
        mean = Nag_MeanInclude;
    else
        mean = Nag_MeanZero;

    wtptr = NULL;

    matrix xm = {{1.0, 0.0, 0.0, 0.0, 0}, {0.0, 0.0, 0.0, 1.0, 0},
                 {0.0, 1.0, 0.0, 0.0, 0}, {0.0, 0.0, 1.0, 0.0, 0},
                 {0.0, 0.0, 0.0, 1.0, 0}, {0.0, 1.0, 0.0, 0.0, 0},
                 {0.0, 0.0, 0.0, 1.0, 0}, {1.0, 0.0, 0.0, 0.0, 0},
                 {0.0, 0.0, 1.0, 0.0, 0}, {1.0, 0.0, 0.0, 0.0, 0},
                 {0.0, 0.0, 1.0, 0.0, 0}, {0.0, 1.0, 0.0, 0.0, 0}};

    double y[12] = {33.63, 39.62, 38.18, 41.46, 38.02, 35.83,
                    35.99, 36.58, 42.92, 37.80, 40.43, 37.89};

    int sx[5] =	{1, 1, 1, 1};

    double newy[12] = {63.0, 69.0, 68.0, 71.0, 68.0, 65.0,
                       65.0, 66.0, 72.0, 67.0, 70.0, 67.0};

    ip = 5;
    for (j=0; j<m; j++)
    tol = 0.00001e0;
    printf("The input data are as follows:\n");
    printf("\nm = 4, n = 12, wtptr = NULL,tol = 0.0000001e0");
    printf("ip = 0, mean = Nag_MeanInclude, ip =5\n");
    printf("x\n");
    for(i = 0; i < 12; i++)
    {
         for( j = 0; j < 4; j++)
             printf("%2.1f, ",xm[i][j]);
         printf("\n");
    }
    printf("\ny\n");
    for(i = 0; i < 12; i++)
        printf("%3.2f, ",y[i]);
    printf("\nnewy\n");
    for(i = 0; i < 12; i++)
        printf("%3.2f, ",newy[i]);

    printf("\nsx\n");
    for(i = 0; i < m; i++)
        printf("%d, ",sx[i]);
    printf("\nThe results are as follows\n");

    nag_regsn_mult_linear(mean, n, xm, 5, m, sx, ip,	y, wtptr, &rss, &df,
                        b, se, cov, res, h, q, 6, &svd, &rank, p, tol, com_ar);
    printf("Results from g02dac\n\n");
    if(svd)
        printf("Model not of full rank\n\n");
    printf("Residual sum of squares = %12.4e\n", rss);
    printf("Degrees of freedom = %3.1f\n\n", df);

    printf("Variable       Parameter          Estimate Standard error\n\n");
    for (j=0; j<ip; j++)
        printf("%6ld%20.4e%20.4e\n", j+1, b[j], se[j]);
    printf("\n");

    nag_regsn_mult_linear_newyvar(n, wtptr, &rss, ip, rank, cov, q, 6, svd, p,
            newy, b, se, res, com_ar);
    printf("\n");
    printf("Results for second y-variable using g02dgc\n\n");
    printf("Residual sum of squares = %12.4e\n", rss);
    printf("Degrees of freedom = %3.1f\n\n", df);

    printf("Variable       Parameter          Estimate Standard error\n\n");
    for (j=0; j<ip; j++)
        printf("%6ld%20.4e%20.4e\n", j+1, b[j], se[j]);
    printf("\n");
}

    The output is as follows:

    The input data are as follows:

    m = 4, n = 12, wtptr = NULL,tol = 0.0000001e0ip = 0, mean = Nag_MeanInclude, ip =5
    x
    1.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 0.0, 1.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    0.0, 0.0, 0.0, 1.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 0.0, 1.0,
    1.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    1.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    0.0, 1.0, 0.0, 0.0,

    y
    33.63, 39.62, 38.18, 41.46, 38.02, 35.83, 35.99, 36.58, 42.92, 37.80, 40.43, 37.89,
    newy
    63.00, 69.00, 68.00, 71.00, 68.00, 65.00, 65.00, 66.00, 72.00, 67.00, 70.00, 67.00,
    sx
    1, 1, 1, 1,
    The results are as follows
    Results from g02dac

    Model not of full rank

    Residual sum of squares =  2.2227e+001
    Degrees of freedom = 8.0

    Variable       Parameter          Estimate Standard error

         1         3.0557e+001         3.8494e-001
         2         5.4467e+000         8.3896e-001
         3         6.7433e+000         8.3896e-001
         4         1.1047e+001         8.3896e-001
         5         7.3200e+000         8.3896e-001

    Results for second y-variable using g02dgc

    Residual sum of squares =  2.4000e+001
    Degrees of freedom = 8.0

    Variable       Parameter          Estimate Standard error

         1         5.4067e+001         4.0000e-001
          2         1.1267e+001         8.7178e-001
          3         1.2600e+001         8.7178e-001
         4         1.6933e+001         8.7178e-001
         5         1.3267e+001         8.7178e-001

Summary: Estimates of parameters, Standard errors of parameter estimates.
Sample data:
Header file: OCN_g02.h
See also:


nag_regsn_mult_linear_est_func

Function: nag_regsn_mult_linear_est_func
Prototype:
int nag_regsn_mult_linear_est_func(int ip,int rank,double b[],double cov[],double p[],double f[],Boolean *est,double *stat,double *sestat,double *t,double tol)
Remarks: gives the estimate of an estimable function along with its standard error.
Parameters:
ip
  the number of terms in the linear model.
rank
  the rank of the independent variables.
b[]
  the ip values of the estimates of the parameters of the model.
cov[]
  the upper triangular part of the variance-covariance matrix of the ip parameter estimates given in b.
p[]
  p as returned by (g02dac) or (g02ddc).
f[]
  the linear function to be estimated.
est
  indicates if the function was estimable.
stat
  if est = TRUE, stat contains the estimate of the function.
sestat
  if est = TRUE, sestat contains the standard error of the estimate of the function.
t
  if est = TRUE, t contains the t-statistic for the test of the function being equal to zero.
tol
  the tolerance value used in the check for estimability.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, ip must not be less than 1: ip = _value_.  On entry, rank must not be less than 1: rank = _value_.
19: On entry ip = _value_ while rank = _value_. These parameters must satisfy rank = ip.
440: On entry, rank = ip. In this case, the boolean variable est is returned as TRUE and all statistics are calculated.
439: se(F) = 0.0 probably due to rounding error or due to incorrectly specified inputs cov and f.
73: Memory allocation failed.
successful call of the nag_regsn_mult_linear_est_func function.

Example:
    Data from an experiment with four treatments and three observations per treatment
    are read in.  This example uses three different linear regression functions.
    Depend on what you want, you can assign each coefficient for each function.

void test_nag_regsn_mult_linear_est_func()
{

    double rss, sestat, stat, t, tol;
    int i, ip, rank, j, m, n, nestern;
    double df;
    Boolean est, svd;
    Nag_IncludeMean mean;
    char meanc, weight;
    double b[5], cov[15], f[5], h[12], p[35];
    matrix q;
    q.SetSize(12,6);
    double  res[12], se[5], com_ar[45], wt[12];
    double *wtptr;
    int success;

    n = 12;
    m = 4;
    weight = 'u';
    meanc = 'm';

    if (meanc=='m')
        mean = Nag_MeanInclude;
    else
        mean = Nag_MeanZero;
    if (weight=='w')
        wtptr = wt;
    else

    wtptr = NULL;
    matrix x = {{1.0, 0.0, 0.0, 0.0, 0}, {0.0, 0.0, 0.0, 1.0, 0},
                {0.0, 1.0, 0.0, 0.0, 0}, {0.0, 0.0, 1.0, 0.0, 0},
                {0.0, 0.0, 0.0, 1.0, 0}, {0.0, 1.0, 0.0, 0.0, 0},
                {0.0, 0.0, 0.0, 1.0, 0}, {1.0, 0.0, 0.0, 0.0, 0},
                {0.0, 0.0, 1.0, 0.0, 0}, {1.0, 0.0, 0.0, 0.0, 0},
                {0.0, 0.0, 1.0, 0.0, 0}, {0.0, 1.0, 0.0, 0.0, 0}};

    double y[12] = {33.63, 39.62, 38.18, 41.46, 38.02, 35.83,
                    35.99, 36.58, 42.92, 37.80, 40.43, 37.89};

    int sx[5] =	{1, 1, 1, 1};

    ip = 5;
    tol = 0.00001e0;
    nag_regsn_mult_linear(mean, n, x, 5, m, sx, ip, y, wtptr, &rss, &df, b, se, cov,
                        res, h, q, 6, &svd, &rank, p, tol, com_ar);
    printf("\n");
    printf("Estimates from g02dac\n\n");
    printf("Residual sum of squares = %12.4e\n", rss);
    printf("Degrees of freedom = %3.1f\n\n", df);

    printf("Variable       Parameter          Estimate Standard error\n\n");
    for (j=0; j<ip; j++)
        printf("%6ld%20.4e%20.4e\n", j+1, b[j], se[j]);
    printf("\n");
    nestern = 3;
    matrix fl = {{1.0, 1.0, 0.0, 0.0, 0.0}, {0.0, 1.0,-1.0, 0.0, 0.0},
                 {0.0, 1.0, 0.0, 0.0, 0.0}};

    for (i = 0; i < nestern; ++i)
    {
        for(j = 0; j < 5; j++)
            f[j] = fl[i][j];
        success = nag_regsn_mult_linear_est_func(ip, rank, b, cov, p, f, &est, &stat, &sestat, &t, tol);
        if (success == 0 || success == NE_RANK_EQ_IP)
        {
            printf("\n");
            printf("Function %ld\n\n", i+1);
            for (j=0; j<ip; ++j)
                printf("%8.2f%c", f[j], (j%5==4 || j==ip-1) ? '\n' : ' ');
            printf("\n");
        if(est)
            printf(" stat = %10.4f se = %10.4f t = %10.4f\n", stat, sestat, t);
        else
            printf("Function not estimable\n");
        }
    }
}

    The output is as follows:

    Estimates from g02dac

    Residual sum of squares =  2.2227e+001
    Degrees of freedom = 8.0

    Variable       Parameter          Estimate Standard error

         1         3.0557e+001         3.8494e-001
         2         5.4467e+000         8.3896e-001
         3         6.7433e+000         8.3896e-001
         4         1.1047e+001         8.3896e-001
         5         7.3200e+000         8.3896e-001

    Function 1

        1.00    1.00    0.00    0.00    0.00
      stat =    36.0033 se =     0.9623 t =    37.4119

    Function 2

         0.00    1.00   -1.00    0.00    0.00
       stat =    -1.2967 se =     1.3610 t =    -0.9528

    Function 3

        0.00    1.00    0.00    0.00    0.00
    Function not estimable

Summary: Estimate of an estimable function along with its standard error.
Sample data:
Header file: OCN_g02.h
See also:


nag_regsn_mult_linear_tran_model

Function: nag_regsn_mult_linear_tran_model
Prototype:
int nag_regsn_mult_linear_tran_model(int ip,int iconst,double p[],double c[],int tdc,double b[],double rss,double df,double se[],double cov[])
Remarks: calculates the estimates of the parameters of a general linear regression model for given constraints from the singular value decomposition results.
Parameters:
ip
  the number of terms in the linear model.
iconst
  the number of constraints to be imposed on the parameters.
p[]
  p as returned by (g02dac) and (g02ddc).
c[]
  the iconst constraints stored by column.
tdc
  the last dimension of the array c.
b[]
  Input: the parameter estimates computed by using the singular value decomposition.  Output: the parameter estimates of the parameters with the constraints imposed.
rss
  the residual sum of squares as returned by (g02dac) or (g02ddc).
df
  the degrees of freedom associated with the residual sum of squares as returned by (g02dac) or (g02ddc).
se[]
  the standard error of the parameter estimates in b.
cov[]
  the upper triangular part of the variance-covariance matrix of the ip parameter estimates given in b.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, ip must not be less than 1: ip = _value_.
12: On entry, iconst must not be less than or equal to 0: iconst = _value_.
20: On entry, iconst = _value_ while ip = _value_. These parameters must satisfy iconst < ip.
17: On entry, tdc = _value_ while iconst = _value_. These parameters must satisfy tdc = iconst.
6: On entry, rss must not be less than or equal to 0.0: rss = _value_.  On entry, df must not be less than or equal to 0.0: df = _value_.
438: matrix c does not give a model of full rank.
73: Memory allocation failed.
successful call of the nag_regsn_mult_linear_tran_model function.

Example:
    Data from an experiment with four treatments and three observations per treatment are read in. A
    model, including the mean term, is fitted by nag_regsn_mult_linear (g02dac) and the results printed.
    The constraint that the sum of treatment effects is zero is then read in and the parameter estimates
    with this constraint imposed are computed by nag_regsn_mult_linear_tran_model and printed.

void test_nag_regsn_mult_linear_tran_model()
{

    double rss, tol;
    int i, iconst, ip, rank, j, m, n;
    double df;
    Boolean svd;
    Nag_IncludeMean mean;
    char weight, meanc;
    double b[5];
    matrix c;
    c.SetSize(5,5);
    double cov[15], h[12],p[35];
    matrix q;
    q.SetSize(12,6);
    double res[12], se[5],	com_ar[120], wt[12];
    double *wtptr;
    n = 12;
    m = 4;
    weight = 'u';
    meanc = 'm';
    if (meanc=='m')
        mean = Nag_MeanInclude;
    else
        mean = Nag_MeanZero;
    wtptr = NULL;

    matrix x =  {{1.0, 0.0, 0.0, 0.0, 0}, {0.0, 0.0, 0.0, 1.0, 0},
                 {0.0, 1.0, 0.0, 0.0, 0}, {0.0, 0.0, 1.0, 0.0, 0},
                 {0.0, 0.0, 0.0, 1.0, 0}, {0.0, 1.0, 0.0, 0.0, 0},
                 {0.0, 0.0, 0.0, 1.0, 0}, {1.0, 0.0, 0.0, 0.0, 0},
                 {0.0, 0.0, 1.0, 0.0, 0}, {1.0, 0.0, 0.0, 0.0, 0},
                 {0.0, 0.0, 1.0, 0.0, 0}, {0.0, 1.0, 0.0, 0.0, 0}};

    double y[12] = {33.63, 39.62, 38.18, 41.46, 38.02, 35.83,
                    35.99, 36.58, 42.92, 37.80, 40.43, 37.89};
    int sx[5] = {1, 1, 1, 1};

    double temp[5] = {0.0, 1.0, 1.0, 1.0, 1.0};

    ip = 5;
    tol = 0.00001e0;
    printf("The input data are as follows:\n");
    printf("\nm = 4, n = 12, wtptr = NULL,tol = 0.0000001e0");
    printf("ip = 5, mean = Nag_MeanInclude, ip =5\n");
    printf("x\n");
    for(i = 0; i < 12; i++)
    {
         for( j = 0; j < 4; j++)
             printf("%2.1f, ",x[i][j]);
         printf("\n");
    }
    printf("\ny\n");
    for(i = 0; i < 12; i++)
        printf("%3.2f, ",y[i]);
    printf("\nsx\n");
    for(i = 0; i < m; i++)
        printf("%d, ",sx[i]);
    printf("\nThe results are as follows\n");
    nag_regsn_mult_linear(mean, n, x, 5, m, sx, ip, y, wtptr, &rss, &df, b, se, cov,
            res, h, q, 6, &svd, &rank, p, tol, com_ar);
    printf("Estimates from g02dac\n\n");
    printf("Residual sum of squares = %13.4e\n", rss);
    printf("Degrees of freedom = %3.1f\n\n", df);

    printf("Variable       Parameter           Estimate Standard error\n\n");
    for (j=0; j<ip; j++)
        printf("%6ld%20.4e%20.4e\n", j+1, b[j], se[j]);
    printf("\n");

    iconst = ip - rank;
    for (i=0; i<ip; ++i)
        for (j=0; j<iconst; ++j)
        c[i][j] = temp[i * iconst  + j];
    nag_regsn_mult_linear_tran_model(ip, iconst, p, c, 5, b, rss, df, se, cov);

    printf("\n");
    printf("Estimates from g02dkc using constraints\n\n");
    printf("Variable       Parameter           Estimate Standard error\n\n");
    for (j=0; j<ip; j++)
        printf("%6ld%20.4e%20.4e\n", j+1, b[j], se[j]);
    printf("\n");
}

    The output is as follows:

    The input data are as follows:

    m = 4, n = 12, wtptr = NULL,tol = 0.0000001e0ip = 5, mean = Nag_MeanInclude, ip =5
    x
    1.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 0.0, 1.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    0.0, 0.0, 0.0, 1.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 0.0, 1.0,
    1.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    1.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    0.0, 1.0, 0.0, 0.0,

    y
    33.63, 39.62, 38.18, 41.46, 38.02, 35.83, 35.99, 36.58, 42.92, 37.80, 40.43, 37.89,
    sx
    1, 1, 1, 1,
    The results are as follows
    Estimates from g02dac

    Residual sum of squares =   2.2227e+001
    Degrees of freedom = 8.0

    Variable       Parameter           Estimate Standard error

         1         3.0557e+001         3.8494e-001
         2         5.4467e+000         8.3896e-001
         3         6.7433e+000         8.3896e-001
         4         1.1047e+001         8.3896e-001
         5         7.3200e+000         8.3896e-001

    Estimates from g02dkc using constraints

    Variable       Parameter           Estimate Standard error

         1         3.8196e+001         4.8117e-001
         2        -2.1925e+000         8.3342e-001
         3        -8.9583e-001         8.3342e-001
         4         3.4075e+000         8.3342e-001
         5        -3.1917e-001         8.3342e-001

Summary: Parameter estimates, Variance-covariance matrix, Residual sum of squares...
Sample data:
Header file: OCN_g02.h
See also:


nag_regsn_std_resid_influence

Function: nag_regsn_std_resid_influence
Prototype:
int nag_regsn_std_resid_influence(int n,int ip,int nres,double res[],double h[],double rms,double sres[])
Remarks: calculates two types of standardised residuals and two measures of influence for a linear regression.
Parameters:
n
  number of observations included in the regression.
ip
  the number of linear parameters estimated in the regression model.
nres
  the number of residuals.
res[]
  the residuals.
h[]
  the diagonal elements of H, h(i), corresponding to the residuals in res.
rms
  the estimate of s2 based on all n observations, s2, i.e., the residual mean square.
sres[]
  the standardised residuals and influence statistics.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, ip must not be less than 1: ip = _value_.  On entry, nres must not be less than 1: nres = _value_.
18: On entry, n = _value_ while ip + 1 = _value_. These parameters must satisfy n > ip + 1.
17: On entry, nres = _value_ while n = _value_. These parameters must satisfy nres = n.
6: On entry, rms must not be less than or equal to 0.0: rms = _value_.  On entry, h[_value_] must not be less than or equal to 0.0: h[_value_] = _value_.
8: On entry, h[_value_] must not be greater than or equal to 1.0: h[_value_] = _value_.
433: On entry, the value of a residual is too large for the given value of rms: res[_value_] = _value_, rms = _value_.
successful call of the nag_regsn_std_resid_influence function.

Example:
    A set of 24 residuals and h(i) values from an 11 parameter model fitted to the cloud
    seeding data considered in Cook and Weisberg (1982) are input and the standardised
    residuals etc calculated and printed for the first 10 observations.

void test_nag_regsn_std_resid_influence()
{

    double rms;
    int i, ip, j, n, nres;
    matrix sres;
    sres.SetSize(24,4);
    n = 24;
    ip = 11;
    nres = 10;
    rms = 0.5798;

    double res[24] = { 	0.2660,-0.1387,-0.2971, 0.5926,-0.4013, 0.1396,
                       -1.3173, 1.1226, 0.0321,-0.7111, 0.3439,-0.4379,
                           0.0633,-0.0936, 0.9968, 0.0209,-0.4056, 0.1396,
                          0.0327, 0.2970,-0.2277, 0.5180, 0.5301,-1.0650};

    double h[24] = {	0.5519, 0.9746, 0.6256, 0.3144, 0.4106, 0.6268,
                        0.5479, 0.2325, 0.4115, 0.3577, 0.3342, 0.1673,
                        0.3874, 0.1705, 0.3466, 0.3743, 0.7527, 0.9069,
                        0.2610, 0.6256, 0.2485, 0.3072, 0.5848, 0.4794};

    printf("The input data are as follows:\n");
    printf("n = 24, ip = 11, nres = 10,	rms = 0.5798,\n");
    printf("res\n");
    for(i = 0; i < n; i ++)
    {
        printf("%5.4f, ",res[i]);
        if(( i + 1) % 6 == 0)
            printf("\n");
    }

    printf("\nh\n");
    for(i = 0; i < n; i ++)
    {
        printf("%5.4f, ",h[i]);
        if(( i + 1) % 6 == 0)
            printf("\n");
    }
    printf("\nThe results are as follows:\n");

    nag_regsn_std_resid_influence(n, ip, nres, res, h, rms, sres);
    printf("\n");
    printf("Internally Externally\n");
    printf("Obs.       studentized   studentized   Cook's D     Atkinson's T\n");
    printf(" \t\t\t\t\t\t   residuals    residuals\n\n");
    for (i=0; i<nres; i++)
    {
        printf("%2ld", i+1);
        for (j=0; j<4; j++)
        printf("%14.3f", sres[i][j]);
        printf("\n");
    }
}

    The output is as follows:

    The input data are as follows:
    n = 24, ip = 11, nres = 10,	rms = 0.5798,
    res
    0.2660, -0.1387, -0.2971, 0.5926, -0.4013, 0.1396,
    -1.3173, 1.1226, 0.0321, -0.7111, 0.3439, -0.4379,
    0.0633, -0.0936, 0.9968, 0.0209, -0.4056, 0.1396,
    0.0327, 0.2970, -0.2277, 0.5180, 0.5301, -1.0650,

    h
    0.5519, 0.9746, 0.6256, 0.3144, 0.4106, 0.6268,
    0.5479, 0.2325, 0.4115, 0.3577, 0.3342, 0.1673,
    0.3874, 0.1705, 0.3466, 0.3743, 0.7527, 0.9069,
    0.2610, 0.6256, 0.2485, 0.3072, 0.5848, 0.4794,

    The results are as follows:

    Internally Externally
    Obs.       studentized   studentized   Cook's D     Atkinson's T
                                               residuals    residuals

       1         0.522         0.507         0.030         0.611
      2        -1.143        -1.158         4.557        -7.797
     3        -0.638        -0.622         0.062        -0.875
     4         0.940         0.935         0.037         0.689
     5        -0.686        -0.672         0.030        -0.610
     6         0.300         0.289         0.014         0.408
     7        -2.573        -3.529         0.729        -4.223
     8         1.683         1.828         0.078         1.094
     9         0.055         0.053         0.000         0.048
    10        -1.165        -1.183         0.069        -0.960

Summary: Internal studentized statistic, External studentized statistic, Cook's D residual, Atkinson's T residual.
Sample data:
Header file: OCN_g02.h
See also:


nag_glm_normal

Function: nag_glm_normal
Prototype:
int nag_glm_normal(Nag_Link link,Nag_IncludeMean mean,int n,double x[],int tdx,int m,int sx[],int ip,double y[],double wt[],double offset[],double *scale,double ex_power,double *rss,double *df,double b[],int *rank,double se[],double cov[],double v[],int tdv,double tol,int max_iter,int print_iter,const char *outfile,double eps)
Remarks: fits a generalized linear model with normal errors.
Parameters:
n
  the number of observations.
x[]
  contain the ith observation for the jth independent variable.
tdx
  the second dimension of the array x.
m
  the total number of independent variables.
sx[]
  indicates which independent variables are to be included in the model.
ip
  the number p of independent variables in the model, including the mean or intercept if present.
y[]
  observations on the dependent variable.
wt[]
  an (optional) weight is specified to be used with the model.
offset[]
  an optional offset is specified.
scale
  indicates the scale parameter for the model.
ex_power
  if link = Nag Expo then ex power must contain the power a of the exponential.
rss
  the residual sum of squares for the fitted model.
df
  the degrees of freedom associated with the residual sum of squares for the fitted model.
b[]
  the estimates of the parameters of the generalized linear model.
rank
  the rank of the independent variables.
se[]
  the standard errors of the linear parameters.
cov[]
  the estimate variance-covariance of estimate parameters.
v[]
  auxiliary information on the fitted model.
tdv
  the second dimension of the array v.
tol
  indicates the accuracy required for the fit of the model.
max_iter
  the maximum number of iterations for the iterative weighted least-squares.
print_iter
  indicates if the printing of information on the iterations is required which printing is produced.
outfile
  a null terminated character string giving the name of the file to which results should be printed.
eps
  the value of eps is used to decide if the independent variables are of full rank

Return values:
The function returns NAG error code or 0 if no error.
70: On entry, parameter link had an illegal value.  On entry, parameter mean had an illegal value.
11: On entry, n must not be less than 2: n = _value	.  On entry, m must not be less than 1: m = _value	.  On entry, ip must not be less than 1: ip = _value	.  On entry, max_iter must not be less than 0: max_iter = _value	.  On entry, sx[_value	] must not be less than 0: sx[_value	] = _value	.
5: On entry, scale must not be less than 0.0: scale = _value	.  On entry, tol must not be less than 0.0: tol = _value	.  On entry, eps must not be less than 0.0: eps = _value	.  On entry, wt[_value	] must not be less than 0.0: wt[_value	] = _value	.
17: On entry, tdx = _value	while m = _value	. These parameters must satisfy tdx = m.  On entry, tdv = _value	while ip = _value	. These parameters must satisfy tdv = ip+6.
37: On entry, ex power = 0.0 , link = Nag Expo.  These parameters must satisfy link == Nag Expo && ex power _= 0.0.
457: Parameter ip is incompatible with parameters mean and sx.
458: Parameter ip is greater than the effective number of observations.
459: A fitted value is at a boundary. This will only occur with link = Nag Expo, Nag Log or Nag Reci. This may occur if there are small values of y and the model is not suitable for the data. The model should be reformulated with, perhaps, some observations dropped.
427: The singular value decomposition has failed to converge.
463: The iterative weighted least-squares has failed to converge in max_iter = _value	 iterations.  The value of max_iter could be increased but it may be advantageous to examine the convergence using the print iter option. This may indicate that the convergence is slow because the solution is at a boundary in which case it may be better to reformulate the model.
464: The rank of the model has changed during the weighted least-squares iterations. The estimate for ß returned may be reasonable, but the user should check how the deviance has changed during iterations.
465: The degrees of freedom for error are 0. A saturated model has been fitted.
78: Cannot open file _string for appending.
79: Cannot close file _string	.
73: Memory allocation failed.
successful call of the nag_glm_normal function.

Example:
    The model: [y = ß1 + ß2x + epsilon] for a sample of 5 observations.

void test_nag_glm_normal()
{
    char linkc, meanc, weightc;
    Nag_Link link;
    Nag_IncludeMean mean;
    int i, j, m, n, ip;
    int max_iter, print_iter, rank;
    double ex_power, scale, tol, eps, rss, df;
    int sx[2];
    double b[2];
    matrix v;
    v.SetSize(5,8);
    double wt[5];
    matrix x;
    x.SetSize(5,2);

    double y[5], se[2], cov[3];
    double *wtptr;
    double *offsetptr;
    offsetptr = NULL;
    int success;
    linkc = 'r';
    meanc = 'm';
    weightc = 'n';
    n = 5;
    m = 1;
    print_iter = 0;
    scale = 0.0;

    set_enum(linkc, &link, meanc, &mean);

    wtptr = NULL;
    x[0][0] = 1.0;
    y[0] = 25.0;
    x[1][0] = 2.0;
    y[1] = 10.0;
    x[2][0] = 3.0;
    y[2] = 6.0;
    x[3][0] = 4.0;
    y[3] = 4.0;
    x[4][0] = 5.0;
    y[4] = 3.0;

    sx[0] = 1;
    ip = 0;
    for (j=0; j<m; j++)
        if (sx[j]>0) ip += 1;
    if (mean == Nag_MeanInclude)
        ip += 1;
    if (link == Nag_Expo)
        printf("there is some problemtttttttt");
    else
        ex_power = 0.0;
    printf("ipip = %d",ip);
    max_iter = 10;
    tol = 5e-5;
    eps = 1e-6;
    String str = "c:\\c\\test.txt";
    success = nag_glm_normal(link, mean, n, x, 2, m, sx, ip, y, wtptr,
                                offsetptr, &scale, ex_power, &rss, &df, b, &rank,se, cov,
                                    v, 8, tol, max_iter,	print_iter, str, eps);

    if (success == NE_NOERROR || success == NE_LSQ_ITER_NOT_CONV || success == NE_RANK_CHANGED || success == NE_ZERO_DOF_ERROR)
    {
        printf("\nResidual sum of squares = %12.4e\n", rss);
        printf("Degrees of freedom = %3.1f\n\n", df);
        printf("       Estimate    Standard error\n\n");
        for (i=0; i<ip; i++)
            printf("%14.4f%14.4f\n", b[i], se[i]);
        printf("\n");
        printf("   y     fitted value     Residual    Leverage\n\n");
        for (i = 0; i < n; ++i)
        {

            printf("%7.1f%10.2f%12.4f%10.3f\n", y[i], v[i][1], v[i][4], v[i][5]);
        }

    }
    else
    {
        printf("there are some problem");
    }
}

int set_enum(char linkc, Nag_Link *link, char meanc, Nag_IncludeMean *mean)
{
    if(linkc == 'E' ||linkc =='e')
        *link = Nag_Expo;
    else if(linkc == 'I' ||linkc =='i')
        *link = Nag_Iden;
    else if(linkc == 'L' ||linkc =='l')
        *link = Nag_Log;
    else if(linkc == 'S' ||linkc =='s')
        *link = Nag_Sqrt;
    else if(linkc == 'R' ||linkc =='r')
        *link = Nag_Reci;
    else
        return 1;
    if(meanc == 'M'|| meanc == 'm')
        *mean = Nag_MeanInclude;
    else if(meanc == 'Z' || meanc == 'z')
        *mean = Nag_MeanZero;
    else
        return 1;
        return 0;
}

    The output is as follows:

    ip = 2
    Residual sum of squares =  3.8717e-001
    Degrees of freedom = 3.0

    Estimate       Standard error

    -0.0239        0.0028
     0.0638        0.0026

    y    fitted value   Residual   Leverage

    25.0     25.04     -0.0387     0.995
    10.0      9.64      0.3613     0.458
      6.0      5.97      0.0320     0.268
      4.0      4.32     -0.3221     0.167
      3.0      3.39     -0.3878     0.112

Summary: Linear Model with Normal Errors, Residual, Leverage.
Sample data:
Header file: OCN_g02.h
See also:


nag_glm_binomial

Function: nag_glm_binomial
Prototype:
int nag_glm_binomial(Nag_Link link,Nag_IncludeMean mean,int n,double x[],int tdx,int m,int sx[],int ip,double y[],double binom_t[],double wt[],double offset[],double *dev,double *df,double b[],int *rank,double se[],double cov[],double v[],int tdv,double tol,int max_iter,int print_iter,const char *outfile,double eps)
Remarks: fits a generalized linear model with binomial errors.
Parameters:
mean
  indicates if a mean term is to be included.
n
  the number of observations
x[]
  contain the ith observation for the jth independent variable.
tdx
  the second dimension of the array x.
m
  the total number of independent variables.
sx[]
  indicates which independent variables are to be included in the model.
ip
  the number p of independent variables in the model, including the mean or intercept if present.
y[]
  observations on the dependent variable.
binom_t[]
  the binomial denominator
wt[]
  an (optional) weight is specified to be used with the model.
offset[]
  if an offset is required then offset must contain the values of the offset.
dev
  the deviance for the fitted model.
df
  the degrees of freedom associated with the deviance for the fitted model.
b[]
  the coefficient of the variable contained in column j of x.
rank
  the rank of the independent variables.
se[]
  the standard errors of the linear parameters.
cov[]
  the estimate variance-covariance matrix of parameter estimates.
v[]
  auxiliary information on the fitted model.
tdv
  the second dimension of the array v.
tol
  indicates the accuracy required for the fit of the model.
max_iter
  the maximum number of iterations for the iterative weighted least-squares.
print_iter
  indicates if the printing of information on the iterations is required.
outfile
  a null terminated character string giving the name of the file to which results should be printed.
eps
  the value of eps is used to decide if the independent variables are of full rank.

Return values:
The function returns NAG error code or 0 if no error.
70:	On entry parameter link had an illegal value. On entry parameter mean had an illegal value.
11:	On entry, n must not be less than 2: n = _value_.  On entry, m must not be less than 1: m = _value_.  On entry, ip must not be less than 1: ip = _value_.  On entry, max_iter must not be less than 0: max_iter = _value_.  On entry, sx[_value_] must not be less than 0: sx[_value_] = _value_.
5: On entry, tol must not be less than 0.0: tol = _value_.  On entry, eps must not be less than 0.0: eps = _value_.  On entry, wt[_value_] must not be less than 0.0: wt[_value_] = _value_.  On entry, binom t[_value_] must not be less than 0.0: binom t[_value_] = _value_.  On entry, y[_value_] must not be less than 0.0: y[_value_] = _value_.
17: On entry tdx = _value_ while m = _value_. These parameters must satisfy tdx = m.  On entry tdv = _value_ while ip = _value_. These parameters must satisfy tdv = ip+6.
25: On entry y[_value_] = _value_ while binom t[_value_] = _value_. These parameters must satisfy y[_value_] = binom t[_value_] .
457: Parameter ip is incompatible with parameters mean and sx.
458: Parameter ip is greater than the effective number of observations.
460: A fitted value is at a boundary i.e., 0.0 or 1.0. This may occur if there are y values of 0.0 or binom t and the model is too complex for the data. The model should be reformulated with, perhaps, some observations dropped.
73: Memory allocation failed.
427: The singular value decomposition has failed to converge.
463: The iterative weighted least-squares has failed to converge in max_iter = _value_ iterations.  The value of max_iter could be increased but it may be advantageous to examine the convergence using the print iter option. This may indicate that the convergence is slow because the solution is at a boundary in which case it may be better to reformulate the model.
464: The rank of the model has changed during the weighted least-squares iterations. The estimate for ß returned may be reasonable, but the user should check how the deviance has changed during iterations.
465: The degrees of freedom for error are 0. A saturated model has been fitted.
78: Cannot open file _string_ for appending.
79: Cannot close file _string_.
successful call of the nag_glm_binomial function.

Example:
    A linear trend (x = -1, 0, 1) is fitted to data relating the incidence of carriers of
    Streptococcus pyogenes to size of tonsils. The data is described in Cox (1983).

void test_nag_glm_binomial()
{
    out_str("You must create a Text.txt file under C:\C\ folder first.");
    out_str("Otherwise, it will say this function nag_glm_binomial has some problem");
    char linkc, meanc, weightc;
    Nag_Link link;
    Nag_IncludeMean mean;
    int i, j, m, n, nvar;
    double beta[2];
    matrix v;
    v.SetSize(3,8);
    double wt[3];
    double *wtptr;
    double *offsetptr;
    int max_iter, print_iter;
    double tol, eps;
    int rank;
    double df, dev;
    double se[2], cov[3];
    String str;
    int success;
    linkc = 'g';
    meanc = 'm';
    weightc = 'n';
    offsetptr = NULL;
    n = 3;
    m = 1;
    print_iter = 0;
    wtptr = NULL;

    link = Nag_Logistic;
    mean = Nag_MeanInclude;
    matrix x =  {
                {1.0, 0},
                {0.0, 0},
                {-1.0, 0}
                }
    double y[3] = {19.0, 29.0, 24.0};
    double binom[3] = {516.0, 560.0, 293.0};
    int ivar[2] = {1, 0};

    nvar = 0;
    for (i=0; i<m; i++)
        if (ivar[i]>0)
             nvar = nvar + 1;
    if (mean == Nag_MeanInclude)
        nvar =nvar + 1;
    max_iter = 10;
    tol = 5e-5;
    eps = 1e-6;
    str = "c:\\c\\c";
    success = nag_glm_binomial(link, mean, n, x, 2, m, ivar, nvar, y, binom, wtptr,
                                offsetptr, &dev, &df, beta, &rank, se, cov, v, 8, tol, max_iter,
                                print_iter, str, eps);
    if(success == NE_NOERROR || success == NE_SVD_NOT_CONV ||
        success == NE_LSQ_ITER_NOT_CONV ||
        success == NE_RANK_CHANGED || success == NE_ZERO_DOF_ERROR)
    {
        printf("\nDeviance = %12.4e\n", dev);
        printf("Degrees of freedom = %3.1f\n\n", df);

        printf("Estimate       Standard error\n\n");
        for (i=0; i<nvar; i++)
            printf("%7.4f%14.4f\n", beta[i], se[i]);

        printf("\n");
        printf("binom   y   fitted value    Residual  Leverage\n\n");
        for (i = 0; i < n; ++i)
            printf("%5.1f%7.1f%10.2f%12.4f%10.3f\n", binom[i], y[i],v[i][1], v[i][4], v[i][5]);
    }
    else
        printf("This function nag_glm_binomial has some problem\n");
}

    The output is as follows:

    You must create a Text.txt file under C:\C\ folder first.
    Otherwise, it will say this function nag_glm_binomial has some problem

    Deviance =  7.3539e-002
    Degrees of freedom = 1.0

    Estimate       Standard error

    -2.8682        0.1217
    -0.4264        0.1598

    binom   y   fitted value    Residual  Leverage

    516.0   19.0     18.45      0.1296     0.769
    560.0   29.0     30.10     -0.2070     0.422
    293.0   24.0     23.45      0.1178     0.809

Summary: Binomial, Residual, Leverage...
Sample data:
Header file: OCN_g02.h
See also:


nag_glm_poisson

Function: nag_glm_poisson
Prototype:
int nag_glm_poisson(Nag_Link link,Nag_IncludeMean mean,int n,double x[],int tdx,int m,int sx[],int ip,double y[],double wt[],double offset[],double ex_power,double *dev,double *df,double b[],int *rank,double se[],double cov[],double v[],int tdv,double tol,int max_iter,int print_iter,const char *outfile,double eps)
Remarks: fits a generalized linear model with Poisson errors.
Parameters:
mean
  indicates if a mean term is to be included.
n
  the number of observations
x[]
  contain the ith observation for the jth independent variable.
tdx
  the second dimension of the array x.
m
  the total number of independent variables.
sx[]
  indicates which independent variables are to be included in the model.
ip
  the number p of independent variables in the model, including the mean or intercept if present.
y[]
  observations on the dependent variable.
wt[]
  an (optional) weight is specified to be used with the model.
offset[]
  if an offset is required then offset must contain the values of the offset.
ex_power
  if link = Nag Expo then ex power must contain the power a of the exponential.
dev
  the deviance for the fitted model.
df
  the degrees of freedom associated with the deviance for the fitted model.
b[]
  the estimates of the parameters of the generalized linear model.
rank
  the rank of the independent variables.
se[]
  the standard errors of the linear parameters.
cov[]
  the estimate variance-covariance of parameter estimates.
v[]
  auxiliary information on the fitted model.
tdv
  the second dimension of the array v.
tol
  indicates the accuracy required for the fit of the model.
max_iter
  the maximum number of iterations for the iterative weighted least-squares.
print_iter
  indicates if the printing of information on the iterations is required.
outfile
  a null terminated character string giving the name of the file to which results should be printed.
eps
  the value of eps is used to decide if the independent variables are of full rank.

Return values:
The function returns NAG error code or 0 if no error.
70: On entry, parameter link had an illegal value.  On entry, parameter mean had an illegal value.
11: On entry, n must not be less than 2: n = _value_.  On entry, m must not be less than 1: m = _value_.  On entry, ip must not be less than 1: ip = _value_.  On entry, sx[_value_] must not be less than 0: sx[_value_] = _value_.  On entry, max_iter must not be less than 0: max_iter = _value_.
17: On entry, tdx = _value	 while m = _value_. These parameters must satisfy tdx = m.  On entry, tdv = _value_ while ip = _value_. These parameters must satisfy tdv = ip+6.
5: On entry, tol must not be less than 0.0: tol = _value_.  On entry, eps must not be less than 0.0: eps = _value_.  On entry, wt[_value_] must not be less than 0.0: wt[_value_] = _value_.  On entry, y[_value_] must not be less than 0.0: y[_value_] = _value_.
37: On entry ex power = 0.0, link = Nag Expo. These parameters must satisfy link == Nag Expo && ex power _= 0.0.
73: Memory allocation failed.
457: Parameter ip is incompatible with mean and sx.
458: Parameter ip is greater than the effective number of observations.
427: The singular value decomposition has failed to converge.
461: A fitted value is at a boundary, i.e., ˆµ = 0.0. This may occur if there are y values of 0.0 and the model is too complex for the data. The model should be reformulated with, perhaps, some observations dropped.
463: The iterative weighted least-squares has failed to converge in max_iter = _value_ iterations.  The value of max_iter could be increased but it may be advantageous to examine the convergence using the print iter option. This may indicate that the convergence is slow because the solution is at a boundary in which case it may be better to reformulate the model.
464: The ranko f the model has changed during the weighted least-squares iterations. The estimate for ß returned may be reasonable, but the user should checkho w the deviance has changed during iterations.
465: The degrees of freedom for error are 0. A saturated model has been fitted.
78: Cannot open file _string for appending.
79: Cannot close file _string	.
successful call of the nag_glm_poisson function.

Example:
    A 3 by 5 contingency table given by Plackett (1974) is analysed by fitting terms
    for rows and columns. The table is:

    141		67		114		79		39
    131 	66 		143 	72 		35
    36 		14 		38 		28 		16

void test_nag_glm_poisson()
{

    char linkc, meanc, weightc;
    Nag_Link link;
    Nag_IncludeMean mean;
    int i, j, m, n, ip;
    double ex_power, scale;
    int  sx[9];
    double b[9];
    matrix v;
    v.SetSize(15,15);
    double wt[15];
    matrix x;
    x.SetSize(15,9);
    double y[15];
    double *wtptr;
    double  *offsetptr;
    int max_iter;
    int print_iter;
    double eps;
    double tol;
    double df;
    double dev;
    int rank;
    double se[9], cov[45];
    int success;
    offsetptr = NULL;
    linkc = 'l';
    meanc = 'm';
    weightc = 'n';
    n = 15;
    m = 8;
    print_iter = 0;

    set_enum(linkc, &link, meanc, &mean);

    wtptr = NULL;

    x[0][0] = 1.0;
    x[0][1] = 0.0;
    x[0][2] = 0.0;
    x[0][3] = 1.0;
    x[0][4] = 0.0;
    x[0][5] = 0.0;
    x[0][6] = 0.0;
    x[0][7] = 0.0;
    y[0] = 141.0;

    x[1][0] = 1.0;
    x[1][1] = 0;
    x[1][2] = 0;
    x[1][3] = 0;
    x[1][4] = 1;
    x[1][5] = 0;
    x[1][6] = 0;
    x[1][7] = 0;
    y[1] = 67;

    x[2][0] = 1;
    x[2][1] = 0;
    x[2][2] = 0;
    x[2][3] = 0;
    x[2][4] = 0;
    x[2][5] = 1;
    x[2][6] = 0;
    x[2][7] = 0;
    y[2] = 114;

    x[3][0] = 1;
    x[3][1] = 0;
    x[3][2] = 0;
    x[3][3] = 0;
    x[3][4] = 0;
    x[3][5] = 0;
    x[3][6] = 1;;
    x[3][7] = 0;
    y[3] = 79;

    x[4][0] = 1.0;
    x[4][1] = 0;
    x[4][2] = 0;
    x[4][3] = 0;
    x[4][4] = 0;
    x[4][5] = 0;
    x[4][6] = 0;
    x[4][7] = 1;
    y[4] =  39;

    x[5][0] = 0;
    x[5][1] = 1;
    x[5][2] = 0;
    x[5][3] = 1;
    x[5][4] = 0;
    x[5][5] = 0;
    x[5][6] = 0;
    x[5][7] = 0;
    y[5] =131;

    x[6][0] = 0;
    x[6][1] = 1;
    x[6][2] = 0;
    x[6][3] = 0;
    x[6][4] = 1;
    x[0][5] = 0;
    x[6][6] = 0;
    x[6][7] = 0;
    y[6] = 66;

    x[7][0] = 0;
    x[7][1] = 1;
    x[7][2] = 0;
    x[7][3] = 0;
    x[7][4] = 0;
    x[7][5] = 1;
    x[7][6] = 0;
    x[7][7] = 0;
    y[7] = 143;

    x[8][0] = 0;
    x[8][1] = 1;
    x[8][2] = 0;
    x[8][3] = 0;
    x[8][4] = 0;
    x[8][5] = 0;
    x[8][6] = 1;
    x[8][7] = 0;
    y[8] = 72;

    x[9][0] = 0;
    x[9][1] = 1;
    x[9][2] = 0;
    x[9][3] = 0;
    x[9][4] = 0;
    x[9][5] = 0;
    x[9][6] = 0;
    x[9][7] = 1;
    y[9] = 35;

    x[10][0] = 0;
    x[10][1] = 0;
    x[10][2] = 1;
    x[10][3] = 1;
    x[10][4] = 0;
    x[10][5] = 0;
    x[10][6] = 0;
    x[10][7] = 0;
    y[10] = 36;

    x[11][0] = 0;
    x[11][1] = 0;
    x[11][2] = 1;
    x[11][3] = 0;
    x[11][4] = 1;
    x[11][5] = 0;
    x[11][6] = 0;
    x[11][7] = 0;
    y[11] = 14;

    x[12][0] = 0;
    x[12][1] = 0;
    x[12][2] = 1;
    x[12][3] = 0;
    x[12][4] = 0;
    x[12][5] = 1;
    x[12][6] = 0;
    x[12][7] = 0;
    y[12] =38;

    x[13][0] = 0;
    x[13][1] = 0;
    x[13][2] = 1;
    x[13][3] = 0;
    x[13][4] = 0;
    x[13][5] = 0;
    x[13][6] = 1;
    x[13][7] = 0;
    y[13] = 28;

    x[14][0] = 0;
    x[14][1] = 0;
    x[14][2] = 1;
    x[14][3] = 0;
    x[14][4] = 0;
    x[14][5] = 0;
    x[14][6] = 0;
    x[14][7] = 1;
    y[14] =16;

    for (j=0; j<m; j++)
        sx[j] = 1;
    ip = 0;
    for (j=0; j<m; j++)
        if (sx[j]>0) ip =ip + 1;
    if (mean == Nag_MeanInclude)
        ip = ip + 1;

    ex_power = 0.0;
    max_iter = 10;
    tol = 5e-5;
    eps = 1e-6;
    success = nag_glm_poisson(link, mean, n, x, 9, m,sx, ip, y,
    wtptr, offsetptr, ex_power, &dev, &df, b, &rank, se, cov,
    v, 15, tol, max_iter, print_iter, "c:\\c\\tre.txt", eps);
    if (success == NE_NOERROR || success == NE_LSQ_ITER_NOT_CONV ||
    success == NE_RANK_CHANGED || success == NE_ZERO_DOF_ERROR)
    {
        printf("\nDeviance = %12.4e\n", dev);
        printf("Degrees of freedom = %3.1f\n\n", df);
        printf(" Estimate Standard error\n\n");
        for (i=0; i<ip; i++)
            printf("%14.4f%14.4f\n", b[i], se[i]);
        printf("\n");
        printf("   y    fitted value   Residual   Leverage\n\n");
        for (i = 0; i < n; ++i)
            printf("%7.1f%10.2f%12.4f%10.3f\n", y[i], v[i][1], v[i][4],	v[i][5]);

    }
    else
        printf("the function is OK");
}

int set_enum(char linkc, Nag_Link *link, char meanc, Nag_IncludeMean *mean)
{
    if(linkc == 'E' ||linkc =='e')
        *link = Nag_Expo;
    else if(linkc == 'I' ||linkc =='i')
        *link = Nag_Iden;
    else if(linkc == 'L' ||linkc =='l')
        *link = Nag_Log;
    else if(linkc == 'S' ||linkc =='s')
        *link = Nag_Sqrt;
    else if(linkc == 'R' ||linkc =='r')
        *link = Nag_Reci;
    else
        return 1;
    if(meanc == 'M'|| meanc == 'm')
        *mean = Nag_MeanInclude;
    else if(meanc == 'Z' || meanc == 'z')
        *mean = Nag_MeanZero;
    else
        return 1;
        return 0;
}

    The output is as follows:

    Deviance =  9.0379e+000
    Degrees of freedom = 8.0

    Estimate Standard error

            2.5977        0.0258
            1.2619        0.0438
            1.2777        0.0436
            0.0580        0.0668
            1.0307        0.0551
            0.2910        0.0732
            0.9876        0.0559
            0.4880        0.0675
              -0.1996        0.0904

    y    fitted value    Residual   Leverage

    141.0    132.99      0.6875     0.604
      67.0     63.47      0.4386     0.514
    114.0    127.38     -1.2072     0.596
      79.0     77.29      0.1936     0.532
      39.0     38.86      0.0222     0.482
    131.0    135.11     -0.3553     0.608
      66.0     64.48      0.1881     0.520
    143.0    129.41      1.1749     0.601
      72.0     78.52     -0.7465     0.537
      35.0     39.48     -0.7271     0.488
      36.0     39.90     -0.6276     0.393
      14.0     19.04     -1.2131     0.255
      38.0     38.21     -0.0346     0.382
      28.0     23.19      0.9675     0.282
      16.0     11.66      1.2028     0.206

Summary: Poisson, Parameter Estimates, Standard Error, Residual, Leverage...
Sample data:
Header file: OCN_g02.h
See also:


nag_glm_gamma

Function: nag_glm_gamma
Prototype:
int nag_glm_gamma(Nag_Link link,Nag_IncludeMean mean,int n,double x[],int tdx,int m,int sx[],int ip,double y[],double wt[],double offset[],double *scale,double ex_power,double *dev,double *df,double b[],int *rank,double se[],double cov[],double v[],int tdv,double tol,int max_iter,int print_iter,const char *outfile,double eps)
Remarks: fits a generalized linear model with gamma errors.
Parameters:
n
  the number of observations.
x[]
  contain the ith observation for the jth independent variable.
tdx
  the second dimension of the array x.
m
  the total number of independent variables.
sx[]
  indicates which independent variables are to be included in the model.
ip
  the number p of independent variables in the model, including the mean or intercept if present.
y[]
  observations on the dependent variable.
wt[]
  an (optional) weight is specified to be used with the model.
offset[]
  if an offset is required then offset must contain the values of the offset
scale
  the scale parameter for the gamma model.
ex_power
  if link = Nag Expo then ex power must contain the power a of the exponential.
dev
  the deviance for the fitted model.
df
  the degrees of freedom associated with the deviance for the fitted model.
b[]
  the estimates of the parameters of the generalized linear model.
rank
  the rank of the independent variables.
se[]
  the standard errors of the linear parameters.
cov[]
  the variance-covariance matrix of the parameter estimates.
v[]
  auxiliary information on the fitted model.
tdv
  the second dimension of the array v.
tol
  indicates the accuracy required for the fit of the model.
max_iter
  the maximum number of iterations for the iterative weighted least-squares.
print_iter
  indicates if the printing of information on the iterations is required.
outfile
  a null terminated character string giving the name of the file to which results should be printed.
eps
  the value of eps is used to decide if the independent variables are of full rank.

Return values:
The function returns NAG error code or 0 if no error.
70: On entry, parameter link had an illegal value.  On entry, parameter mean had an illegal value.
11: On entry, n must not be less than 2: n = _value_.  On entry, m must not be less than 1: m = _value_.  On entry, ip must not be less than 1: ip = _value_.  On entry, sx[_value_] must not be less than 0: sx[_value_] = _value_.  On entry, max_iter must not be less than 0: max_iter = _value_.
17: On entry, tdx = _value_ while m = _value_. These parameters must satisfy tdx = m.  On entry, tdv = _value_ while ip = _value_. These parameters must satisfy tdv = ip+6.
5: On entry, scale must not be less than 0.0: scale = _value_.  On entry, tol must not be less than 0.0: tol = _value_.  On entry, eps must not be less than 0.0: eps = _value_.  On entry, wt[_value_] must not be less than 0.0: wt[_value_] = _value_.  On entry, y[_value_] must not be less than 0.0: y[_value_] = _value_.
37: On entry ex power = 0.0 , link = Nag Expo.  These parameters must satisfy link == Nag Expo && ex power _= 0.0.
73: Memory allocation failed.
457: ip is incompatible with mean and sx.
458: ip is greater than the effective number of observations.
427: The singular value decomposition has failed to converge.
462: A fitted value is at a boundary, i.e., ˆµ = 0.0. This may occur if there are small values of y and the model is not suitable for the data. The model should be reformulated with, perhaps, some observations dropped.
463: The iterative weighted least-squares has failed to converge in max_iter = _value_ iterations.  The value of max_iter could be increased but it may be advantageous to examine the convergence using the print iter option. This may indicate that the convergence is slow because the solution is at a boundary in which case it may be better to reformulate the model.
464: The rank of the model has changed during the weighted least-squares iterations. The estimate for ß returned may be reasonable, but the user should check how the deviance has changed during iterations.
465: The degrees of freedom for error are 0. A saturated model has been fitted.
78:Cannot open file _string	 for appending.
79: Cannot close file _string	.
successful call of the nag_glm_gamma function.

Example:
    A set of 10 observations from two groups are input and a model for the two groups is fitted.

void test_nag_glm_gamma()
{

    char linkc, meanc, weightc;
    Nag_Link link;
    Nag_IncludeMean mean;
    int i, j, m, n, ip;
    double ex_power, scale;
    int sx[2];
    double b[2];
    matrix v;
    v.SetSize(10,8);
    double wt[10];
    double *wtptr;
    double *offsetptr;
    int max_iter;
    int print_iter;
    double eps;
    double tol;
    double df;
    double dev;
    int rank;
    double se[2], cov[3];
    int success;
    offsetptr = NULL;
    linkc = 'r';
    meanc = 'm';
    weightc = 'u';
    n = 10;
    m = 1;
    print_iter = 0;
    scale = 0.0;
    set_enum(linkc, &link, meanc, &mean);

    wtptr = NULL;

    matrix x =  {{1.0, 0.0}, {1.0, 0.0}, {1.0, 0.0},
                 {1.0, 0.0}, {1.0, 0.0}, {0.0, 0.0},
                 {0.0, 0.0}, {0.0, 0.0}, {0.0, 0.0},
                 {0.0, 0.0}};

    double y[10] = {1.0, 0.3, 10.5, 9.7, 10.9,
                    0.62, 0.12, 0.09, 0.50, 2.14};

    for (j=0; j<m; j++)
        sx[j] = 1;

    ip = 0;
    for (j=0; j<m; j++)
        if (sx[j]>0) ip = ip + 1;
    if (mean == Nag_MeanInclude)
        ip = ip + 1;
    ex_power = 0.0;
    max_iter = 10;
    tol = 5e-5;
    eps = 1e-6;
    success = nag_glm_gamma(link, mean, n, x, 2, m, sx, ip, y,	wtptr, offsetptr, &scale, ex_power, &dev, &df, b, &rank,
    se, cov, v, 8, tol, max_iter, print_iter, "c:\\c\\test.txt", eps);
    if (success == NE_NOERROR || success == NE_LSQ_ITER_NOT_CONV ||
    success == NE_RANK_CHANGED || success == NE_ZERO_DOF_ERROR)
    {
        printf("\nDeviance = %12.4e\n", dev);
        printf("Degrees of freedom = %3.1f\n\n", df);
        printf("     Estimate     Standard error\n\n");
        for (i=0; i<ip; i++)
            printf("%14.4f%14.4f\n", b[i], se[i]);
        printf("\n");

        printf("y    fitted value   Residual   Leverage\n\n");
        for (i = 0; i < n; ++i)
            printf("%4.1f%10.2f%12.4f%10.3f\n", y[i], v[i][1], v[i][4], v[i][5]);
    }
    else
    printf("This function has some problem\n");
}

int set_enum(char linkc, Nag_Link *link, char meanc, Nag_IncludeMean *mean)
{
    if(linkc == 'E' ||linkc =='e')
        *link = Nag_Expo;
    else if(linkc == 'I' ||linkc =='i')
        *link = Nag_Iden;
    else if(linkc == 'L' ||linkc =='l')
        *link = Nag_Log;
    else if(linkc == 'S' ||linkc =='s')
        *link = Nag_Sqrt;
    else if(linkc == 'R' ||linkc =='r')
        *link = Nag_Reci;
    else
        return 1;
    if(meanc == 'M'|| meanc == 'm')
        *mean = Nag_MeanInclude;
    else if(meanc == 'Z' || meanc == 'z')
        *mean = Nag_MeanZero;
    else
        return 1;
        return 0;
}

    The output is as follows:

    Deviance =  3.5034e+001
    Degrees of freedom = 8.0

    Estimate	   Standard error

     1.4408        0.6678
    -1.2865        0.6717

    y    fitted value   Residual   Leverage

      1.0      6.48     -1.3909     0.200
      0.3      6.48     -1.9228     0.200
    10.5      6.48      0.5236     0.200
      9.7      6.48      0.4318     0.200
    10.9      6.48      0.5678     0.200
      0.6      0.69     -0.1107     0.200
      0.1      0.69     -1.3287     0.200
      0.1      0.69     -1.4815     0.200
      0.5      0.69     -0.3106     0.200
      2.1      0.69      1.3665     0.200

Summary: Gamma, Parameter Estimates, Standard Error, Residual, Leverage...
Sample data:
Header file: OCN_g02.h
See also:


nag_glm_tran_model

Function: nag_glm_tran_model
Prototype:
int nag_glm_tran_model(int ip,int nclin,double v[],int tdv,double c[],int tdc,double b[],double scale,double se[],double cov[])
Remarks: calculates the estimates of the parameters of a generalized linear model for given constraints from the singular value decomposition results.
Parameters:
ip
  the number of terms in the linear model.
nclin
  the number of constraints to be imposed on the parameters.
v[]
  v as returned by (g02gac), (g02gbc), (g02gcc) or (g02gdc).
tdv
  the second dimension of the array v
c[]
  the nclin constraints stored by column.
tdc
  the last dimension of the array c.
b[]
  Input: the parameter estimates computed by using the singular value decomposition.

  Output: the parameter estimates of the parameters with the constraints imposed.
scale
  the estimate of the scale parameter.
se[]
  the standard error of the parameter estimates in b.
cov[]
  the estimate variance-covariance of the parameter estimates.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, ip must not be less than 1: ip = _value_.
12: On entry, nclin must not be less than or equal to 0: nclin = _value_.
20: On entry, nclin = _value_ while ip = _value_. These parameters must satisfy nclin < ip.
17: On entry, tdv = _value_ while ip = _value_. These parameters must satisfy tdv = ip+6.  On entry, tdc = _value_ while nclin = _value_. These parameters must satisfy tdc = nclin.
6: On entry, scale must not be less than or equal to 0.0: scale = _value_.
438: matrix c does not give a model of full rank.
73: Memory allocation failed.
successful call of the nag_glm_tran_model function.

Example:
    A loglinear model is fitted to a 3 by 5 contingency table by nag_glm_poisson (g02gcc).
    The model consists of terms for rows and columns. The table is:

    141   67 	114 	79 	  	39
    131   66 	143 	72 		35
     36   14 	 38 	28 		16

void test_nag_glm_tran_model()
{

    int i, nclin, ip, j, m, n;
    double ex_power;
    int sx[9];
    double b[9];
    matrix c;
    c.SetSize(15,9);
    double cov[45], se[9];
    matrix v;
    v.SetSize(15,15);
    double *wtptr;
    int max_iter;
    int print_iter;
    double eps;
    double tol;
    double df;
    double dev;
    int rank;
    int success;

    n = 15;
    m = 8;
    print_iter = 0;
    wtptr = NULL;

    double y[15] = {141.0, 67, 114, 79, 39, 131, 66,
                    143, 72, 35, 36, 14, 38, 28, 16};

    matrix x =  {{1, 0, 0, 1, 0, 0, 0, 0, 0}, {1, 0, 0, 0, 1, 0, 0, 0, 0},
                 {1, 0, 0, 0, 0, 1, 0, 0, 0}, {1, 0, 0, 0, 0, 0, 1, 0, 0},
                 {1, 0, 0, 0, 0, 0, 0, 1, 0}, {0, 1, 0, 1, 0, 0, 0, 0, 0},
                 {0, 1, 0, 0, 1, 0, 0, 0, 0}, {0, 1, 0, 0, 0, 1, 0, 0, 0},
                 {0, 1, 0, 0, 0, 0, 1, 0, 0}, {0, 1, 0, 0, 0, 0, 0, 1, 0},
                  {0, 0, 1, 1, 0, 0, 0, 0, 0}, {0, 0, 1, 0, 1, 0, 0, 0, 0},
                 {0, 0, 1, 0, 0, 1, 0, 0, 0}, {0, 0, 1, 0, 0, 0, 1, 0, 0},
                 {0, 0, 1, 0, 0, 0, 0, 1, 0}};

    double c1[18] = { 0.0, 0.0, 1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 0.0,
                    1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 1.0 };

    for (j=0; j<m; j++)
        sx[j]= 1;
    ip = 9;

    max_iter = 10;
    tol = 5e-5;
    eps = 1e-6;
    ex_power = 0.0;
    success = nag_glm_poisson(Nag_Log, Nag_MeanInclude, n, x, 9, m, sx, ip, y, wtptr, NULL, ex_power, &dev,
                    &df, b, &rank, se, cov,	v, 15, tol, max_iter, print_iter, "c:\\c\\test.txt", eps);
    if (success == NE_NOERROR || success == NE_LSQ_ITER_NOT_CONV ||
        success == NE_RANK_CHANGED || success == NE_ZERO_DOF_ERROR)
    {
        printf("\nDeviance = %12.4e\n", dev);
        printf("Degrees of freedom = %3.1f\n\n", df);
        nclin = ip - rank;

        for (i=0; i<ip; ++i)
            for (j=0; j<nclin; ++j)
                c[i][j] = c1[i * nclin + j];
        success = nag_glm_tran_model(ip, nclin, v, 15, c, 9, b, 1.0e0, se, cov);
        if (success == NE_NOERROR)
        {
            printf("Estimate        Standard error\n\n");
            for (i=0; i<ip; i++)
                printf(" %7.4f%14.4f\n", b[i], se[i]);
            printf("\n");
        }
        else
            printf("some problem here\n");
    }
    else
        printf("some problem here\n");
}

    The output is as follows:

    Deviance =  9.0379e+000
    Degrees of freedom = 8.0

    Estimate        Standard error

        3.9831        0.0396
        0.3961        0.0458
        0.4118        0.0457
      -0.8079        0.0622
        0.5112        0.0562
      -0.2285        0.0727
        0.4680        0.0569
      -0.0316        0.0675
      -0.7191        0.0887

Summary: Constraint, Estimate, Standard Error.
Sample data:
Header file: OCN_g02.h
See also:


nag_glm_est_func

Function: nag_glm_est_func
Prototype:
int nag_glm_est_func(int ip,int rank,double b[],double cov[],double v[],int tdv,double f[],Boolean *est,double *stat,double *sestat,double *z,double tol)
Remarks: gives the estimate of an estimable function along with its standard error from the results from fitting a generalized linear model.
Parameters:
ip
  the number of terms in the linear model.
rank
  the rank of the independent variables.
b[]
  the ip values of the estimates of the parameters of the model.
cov[]
  the estimate variance-covariance of the parameter estimates.
v[]
  v as returned by (g02gac), (g02gbc), (g02gcc) or (g02gdc).
tdv
  the second dimension of the array v.
f[]
  the linear function to be estimated.
est
  indicates if the function was estimable.
stat
  if est = TRUE, stat contains the estimate of the function.
sestat
  if est = TRUE, sestat contains the standard error of the estimate of the function.
z
  if est = TRUE, z contains the z statistic for the test of the function being equal to zero.
tol
  tol is the tolerance value used in the check for estimability.

Return values:
The function return NAG error code or 0 if no error.
11: On entry, ip must not be less than 1: ip = _value_.  On entry, rank must not be less than 1: rank = _value_.
19: On entry, ip = _value_ while rank = _value_. These parameters must satisfy rank = ip.
17: On entry, tdv = _value_ while ip = _value_. These parameters must satisfy tdv = ip+6.
440: On entry, rank = ip. In this case, the boolean variable est is returned as TRUE and all statistics are calculated.
439: sestat, the standard error of the estimate of the function, se(F) = 0.0; probably due to rounding error or due to incorrectly specified input values of cov and f.
73: Memory allocation failed.
successful call of the nag_glm_est_func function.

Example:
    A loglinear model is fitted to a 3 by 5 contingency table by (g02gcc). The model consists of
    terms for rows and columns. The table is:

    141   67 	114 	79 	  	39
    131   66 	143 	72 		35
     36   14 	 38 	28 		16

    The number of functions to be tested is read in, then the linear functions themselves are
    read in and tested with nag_glm_est_func. The results of nag_glm_est_func are printed.

void  test_nag_glm_est_func()
{
    Boolean est;
    int i, ip, j, m, n, nestfn, tdx, tdv;
    double ex_power;
    double sestat, stat, z;
    int sx[9];
    double b[9], f[9];
    matrix v;
    v.SetSize(15,15);
    double  wt[15];
    double *wtptr;
    int max_iter;
    int print_iter;
    double eps;
    double tol;
    double df;
    double dev;
    int rank;
    double cov[45], se[9];
    int success;
    n = 15;
    m = 8;
    print_iter = 0;

    double y[15] = {141.0, 67, 114, 79, 39, 131, 66, 143, 72, 35, 36, 14, 38, 28, 16};

    matrix x =  {{1, 0, 0, 1, 0, 0, 0, 0, 0}, {1, 0, 0, 0, 1, 0, 0, 0, 0},
                 {1, 0, 0, 0, 0, 1, 0, 0, 0}, {1, 0, 0, 0, 0, 0, 1, 0, 0},
                 {1, 0, 0, 0, 0, 0, 0, 1, 0}, {0, 1, 0, 1, 0, 0, 0, 0, 0},
                 {0, 1, 0, 0, 1, 0, 0, 0, 0}, {0, 1, 0, 0, 0, 1, 0, 0, 0},
                 {0, 1, 0, 0, 0, 0, 1, 0, 0}, {0, 1, 0, 0, 0, 0, 0, 1, 0},
                 {0, 0, 1, 1, 0, 0, 0, 0, 0}, {0, 0, 1, 0, 1, 0, 0, 0, 0},
                  {0, 0, 1, 0, 0, 1, 0, 0, 0}, {0, 0, 1, 0, 0, 0, 1, 0, 0},
                 {0, 0, 1, 0, 0, 0, 0, 1, 0}};

    matrix fl = {{1, 1, 0, 0, 1, 0, 0, 0, 0}, {0, 1,-1, 0, 0, 0, 0, 0, 0},
                 {0, 1, 0, 0, 0, 0, 0, 0, 0}};

    wtptr = NULL;
    for (j=0; j<m; j++)
        sx[j]=1;
    ip = 9;
    max_iter = 10;
    tol = 5e-5;
    eps = 1e-6;
    ex_power = 0.0;
    success = nag_glm_poisson(Nag_Log, Nag_MeanInclude, n, x, 9,
                    m, sx, ip, y, wtptr, NULL, ex_power, &dev, &df, b, &rank, se, cov,
                    v, 15, tol, max_iter, print_iter, "c:\\c\\test.txt", eps);

    if (success == NE_NOERROR || success == NE_LSQ_ITER_NOT_CONV ||
            success == NE_RANK_CHANGED || success == NE_ZERO_DOF_ERROR)
    {
            printf("\nDeviance = %12.4e\n", dev);
            printf("Degrees of freedom = %3.1f\n\n", df);
            printf("Estimate       Standard error\n\n");
            for (i=0; i<ip; i++)
                printf("%7.4f%14.4f\n", b[i], se[i]);

            printf("\n");
            nestfn = 3;
            for(i = 0; i < 3; i++)
            {
                for(j = 0; j < 9; j++)
                    f[j] = fl[i][j];

                success = nag_glm_est_func(ip, rank, b, cov, v, 15, f, &est, &stat, &sestat, &z, tol);
                if (success == NE_NOERROR || success == NE_RANK_EQ_IP)
                {
                    printf("\n");
                    printf("Function %ld\n\n", i+1);
                    for (j=0; j<ip; ++j)
                    printf("%8.2f%c", f[j], (j%5==4 || j==ip-1) ? '\n' : ' ');
                    printf("\n");
                    if (est)
                        printf("stat = %10.4f\nsestat = %10.4f\nz = %10.4f\n", stat, sestat, z);
                    else
                    printf("Function not estimable\n");
                }
            }
    }
    else
    {
        printf("This function has some problem\n");
    }
}

    The output is as follows:

    Deviance =  9.0379e+000
    Degrees of freedom = 8.0

    Estimate       Standard error

      2.5977        0.0258
      1.2619        0.0438
      1.2777        0.0436
      0.0580        0.0668
      1.0307        0.0551
      0.2910        0.0732
      0.9876        0.0559
      0.4880        0.0675
    -0.1996        0.0904

    Function 1

        1.00    1.00    0.00    0.00    1.00    0.00    0.00    0.00    0.00
    stat =     4.8903
    sestat =     0.0674
    z =    72.5934

    Function 2

        0.00    1.00   -1.00    0.00    0.00    0.00    0.00    0.00    0.00
    stat =    -0.0158
    sestat =     0.0672
    z =    -0.2350

    Function 3

        0.00    1.00    0.00    0.00    0.00    0.00    0.00    0.00    0.00
    Function not estimable

Summary: Estimable Function, Parameter Estimates, Standard Errors...
Sample data:
Header file: OCN_g02.h
See also:


nag_robust_m_regsn_estim

Function: nag_robust_m_regsn_estim
Prototype:
int nag_robust_m_regsn_estim(Nag_RegType regtype,Nag_PsiFun psifun,Nag_SigmaEst sigma_est,Nag_CovMatrixEst covmat_est,int n,int m,double x[],int tdx,double y[],double cpsi,double hpsi[],double cucv,double dchi,double theta[],double *sigma,double c[],int tdc,double rs[],double wt[],double tol,int max_iter,int print_iter,const char *outfile,double info[])
Remarks: performs bounded influence regression (M-estimates). Several standard methods are available.
Parameters:
n
  the number of observations.
m
  the number m, of independent variables.
x[]
  the values of the X matrix, i.e., the independent variables.
tdx
  the second dimension of the array x.
y[]
  the data values of the dependent variable.
cpsi
  if psifun = Nag HuberFun, cpsi must specify the parameter, c, of Huber's psi function.
hpsi[]
  if psifun = Nag_HampelFun then hpsi[0], hpsi[1] and hpsi[2] must specify the parameters h1, h2, and h3, of Hampel's piecewise linear psi function.
cucv
  if regtype = Nag_MallowsReg then cucv must specify the value of the constant, c, of the function u for Maronna's proposed weights. If regtype = Nag_SchweppeReg then cucv must specify the value of the function u for the Krasker-Welsch weights.
dchi
  the constant, d, of the Chi function.
theta[]
  starting values of the parameter vector theta. These maybe obtained from least-squares regression.
sigma
  a starting value for the estimation of sigma.
c[]
  the diagonal elements of c contain the estimated asymptotic standard errors of the estimates of theta,
tdc
  the second dimension of the array c.
rs[]
  contains the residuals from the model evaluated at final value of theta.
wt[]
  contains the vector of weights.
tol
  the relative precision for the calculation of A.
max_iter
  the maximum number of iterations that should be used in the calculation of A.
print_iter
  the amount of information that is printed on each iteration.
outfile
  a null terminated character string giving the name of the .le to which results should be printed.
info[]
  elements of info contain the values of parameters, rank, and number of iterations.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, n must not be less than 2: n =_value_.  On entry, m must not be less than 1: m =_value_.
20: On entry, m =_value_ while n =_value_. These parameters must satisfy m < n.
17: On entry, tdx =_value_ while m =_value_. These parameters must satisfy tdx = m.  On entry, tdc =_value_ while m =_value_. These parameters must satisfy tdc = m.
70: On entry, parameter regtype had an illegal value.  On entry, parameter psifun had an illegal value.  On entry, parameter sigma est had an illegal value.  On entry, parameter covmat est had an illegal value.
12: On entry, max_iter must not be less than or equal to 0: max_iter =_value_.
6: On entry, sigma must not be less than or equal to 0.0: sigma =_value_.  On entry, tol must not be less than or equal to 0.0: tol = value_.
473: On entry, psifun = Nag HuberFun and cpsi =_value_. For this value of psifun, cpsi must be > 0.0.
475: On entry, regtype = Nag MallowsReg, cucv =_value_ and m =_value_. For this value of regtype, cucv must be >= m.
476: On entry, regtype = Nag_SchweppeReg, cucv =_value_ and m =_value_. For this value of regtype, cucv must be >= m^(1/2).
474: On entry, psifun _= Nag Lsq, sigma est = Nag SigmaChi and dchi =_value_. For these values of psifun and sigma est, dchi must be > 0.0.
477: On entry, psifun = Nag HampelFun and hpsi[0] =_value_, hpsi[1] =_value_ and hpsi[2] =_value_. For this value of psifun, the elements of hpsi must satisfyt he condition 0.0 = hpsi[0] = hpsi[1] = hpsi[2] and hpsi[2] > 0.0.
478: The number of iterations required to calculate the weights exceeds max_iter.  This is only applicable if regtype _= Nag_HuberReg.
479: The number of iterations required to calculate ß1 exceeds max_iter.  This is onlya pplicable if regtype = Nag MallowsReg and sigma est = Nag SigmaRes.
480: The number of iterations required to calculate theta and sigma exceeds max_iter. In this case, info[2] = max_iter on exit.
481: The iterations to solve the weighted least-squares equations failed to converge.
482: The weighted least-squares equations are not of full rank.
483: Failure to invert matrix while calculating covariance.  If regtype = Nag HuberReg, then (XTX) is almost singular.  If regtype _= Nag HuberReg, then S1 is singular or almost singular. This maybe due to too many diagonal elements of the matrix being zero, see Section 6.
484: In calculating the correlation factor for the asymptotic variance-covariance matrix, the factor for covariance matrix = 0.  For this error, see Section 6. In this case c is returned as inv(t(X)*X).  (This is only applicable if regtype = Nag HuberReg).
485: The estimated variance for an element of ? = 0. In this case the diagonal element of c will contain the negative variance and the above diagonal elements in the row and the column corresponding to the element will be returned as zero.  This error maybe caused byrounding errors or too many of the diagonal elements of p being zero. See Section 6.
486: n = value_, rank of x =_value_. The degrees of freedom for error, n - (rank of x) must be > 0.0.
487: The estimated value of s was 0.0 during an iteration.
78: Cannot open file string_ for appending.
79: Cannot close file string_.
73: Memory allocation failed.
successful call of the nag_robust_m_regsn_estim function.

Example:
    The number of observations and the number of x variables are read in followed byt he data. The
    option parameters are then read in (in this case giving: Schweppe type regression with Hampel's
    Psi function and Huber's Chi function and then using the 'replace expected byo bserved' option in
    calculating the covariances). Finally a set of values for the constants are read in.  After a
    call to nag_robust_m_regsn_estim, theta-hat, its standard error and sigma-hat are printed. In addition the
    weight and residual for each observation is printed.

void test_nag_robust_m_regsn_estim()
{
    char regtypec, psifunc, sigestc, covmat_estc;
    Nag_RegType regtype;
    Nag_PsiFun psifun;
    Nag_SigmaEst sigma_est;
    Nag_CovMatrixEst covmat_est;
    int i, j, m, n;
    double sigma;
    matrix c;
    c.SetSize(3,3);
    double theta[3];
    double cpsi;
    double hpsi[3];
    double cucv;
    double dchi;
    double rs[8];
    double wt[8];
    double tol;
    int max_iter;
    int print_iter;
    double info[4];
    int success;
    String str;
    m = 3;
    n = 8;

    matrix x = 	{{1, -1, -1}, {1, -1, 1}, {1, 1, -1},
                 {1, 1, 1}, {1, -2, 0}, {1, 0, -2},
                 {1, 2, 0}, {1, 0, 2}};

    double y[8] = {2.1, 3.6, 4.5, 6.1, 1.3, 1.9, 6.7, 5.5};

    regtypec = 'S';
    psifunc = 'P';
    sigestc = 'X';

    set_enum1(regtypec, ®type, psifunc, &psifun, sigestc, &sigma_est);

    if (regtype != Nag_HuberReg)
    {
        covmat_estc = 'R';
        cucv = 3.0;
    }
    if (covmat_estc == 'A')
        covmat_est = Nag_CovMatAve;
    else
        covmat_est = Nag_CovMatObs;
    if (psifun != Nag_Lsq)
    {
        if (psifun == Nag_HuberFun)
            cpsi = 1.5;
        else
            cpsi = 1.5;
        if (psifun == Nag_HampelFun)
        {
            hpsi[0] = 1.5;
            hpsi[1] = 3.0;
            hpsi[2] = 4.5;
        }
        if (sigma_est == Nag_SigmaChi)
            dchi= 1.5;
    }

    printf("dchi =%f \n", dchi);

    tol = 5e-5;
    max_iter = 50;
    print_iter = 1;
    sigma = 1.0e0;
    for (i = 0; i < m; ++i)
        theta[i] = 0.0e0;
    str = "c:\\c\\teax.txt";

    success = nag_robust_m_regsn_estim(regtype, psifun, sigma_est, covmat_est, n, m, x,
                                        3, y, cpsi, hpsi, cucv, dchi, theta, &sigma, c, 3, rs,
                                        wt, tol, max_iter, print_iter, str, info);

    if(success == 0)
    {
    }
    else
    {
        printf("THE PRINTF");
    }

    if((success == NE_NOERROR) || (success == NE_THETA_ITER_EXCEEDED) ||
    (success== NE_LSQ_FAIL_CONV) || (success == NE_MAT_SINGULAR) ||
    (success == NE_WT_LSQ_NOT_FULL_RANK) ||
    (success == NE_REG_MAT_SINGULAR) ||
    (success == NE_COV_MAT_FACTOR_ZERO) ||
    (success == NE_VAR_THETA_LEQ_ZERO) ||
    (success == NE_VAR_THETA_LEQ_ZERO) ||
    (success == NE_ERR_DOF_LEQ_ZERO) ||
    (success == NE_ESTIM_SIGMA_ZERO))
    {
        if (success != NE_NOERROR)
        {

            printf(" Some of the following results may be unreliable\n");
        }
        printf("Sigma = %10.4f\n\n", sigma);
        printf("Theta         Standard errors\n\n");
        for (j = 0; j < m; ++j)
            printf("%6.4f %13.4f\n", theta[j], c[j][j]);

        printf("\nWeights       Residuals\n\n");
        for (i = 0; i < n; ++i)
            printf("%6.4f %13.4f\n", wt[i], rs[i]);
    }
}

int set_enum1(char regtypec, Nag_RegType *regtype, char psifunc, Nag_PsiFun *psifun,
             char sigestc, Nag_SigmaEst *sigma_est)
{
    if(regtypec == 'h'||regtypec == 'H')
        *regtype = Nag_HuberReg;
    else if(regtypec == 'M'||regtypec == 'm')
        *regtype = Nag_MallowsReg;
    else if(regtypec == 'S'||regtypec == 's')
        *regtype = Nag_SchweppeReg;
    else
        return 1;

    if(psifunc == 'L' || psifunc =='l')
        *psifun = Nag_Lsq;
    else if(psifunc == 'H' || psifunc =='h')
        *psifun = Nag_HuberFun;

    else if(psifunc == 'p' || psifunc =='P')
        *psifun = Nag_HampelFun;
    else if(psifunc == 'A' || psifunc =='a')
        *psifun = Nag_AndrewFun;
    else if(psifunc == 'T' || psifunc =='t')
        *psifun = Nag_TukeyFun;
    else
        return 1;

    if(sigestc == 'R' || sigestc == 'r')
        *sigma_est = Nag_SigmaRes;
    else if(sigestc == 'C' || sigestc == 'c')
        *sigma_est = Nag_SigmaConst;
    else if(sigestc == 'X' || sigestc == 'x')
        *sigma_est = Nag_SigmaChi;
    else
        return 1;
    return 0;

}

    The output is as follows:

    dchi =1.500000
    Sigma =     0.2026

    Theta         Standard errors

    4.0423        0.0384
    1.3083        0.0272
    0.7519        0.0311

    Weights       Residuals

    0.5783        0.1179
    0.5783        0.1141
    0.5783       -0.0987
    0.5783       -0.0026
    0.4603       -0.1256
    0.4603       -0.6385
    0.4603        0.0410
    0.4603       -0.0462

Summary: Sigma, Theta, Weight, Standard Error....
Sample data:
Header file: OCN_g02.h
See also:


nag_robust_corr_estim

Function: nag_robust_corr_estim
Prototype:
int nag_robust_corr_estim(int n,int m,double x[],int tdx,double eps,double cov[],double theta[],int max_iter,int print_iter,const char *outfile,double tol,int *iter)
Remarks: computes a robust estimate of the covariance matrix for an expected fraction of gross errors.
Parameters:
n
  the number of observations.
m
  the number of independent variables
x[]
  must contain the ith observation for the jth variable.
tdx
  the second dimension of the array x.
eps
  the expected fraction of gross errors expected in the sample.
cov[]
  the covariance matrix.
theta[]
  the robust estimate of the location parameters.
max_iter
  the maximum number of iterations that will be used during the calculation of the covariance matrix.
print_iter
  indicates if the printing of information on the iterations is required.
outfile
  a null terminated character string giving the name of the file to which results should be printed.
tol
  the relative precision for the final estimates of the covariance matrix.
iter
  the number of iterations performed.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, n must not be less than 2: n = _value_.  On entry, m must not be less than 1: m = _value_.
19: On entry, m = _value_ while n = _value_. These parameters must satisfy m = n.
17: On entry, tdx = _value_ while m = _value_	. These parameters must satisfy tdx = m.
12: On entry, max_iter must not be less than or equal to 0: max_iter = _value_.
5: On entry, eps must not be less than 0.0: eps = _value_.
8: On entry, eps must be not be greater than or equal to 1.0: eps = _value_.
6: On entry, tol must not be less than or equal to 0.0: tol = _value_.
497: On entry, column _value_ of array x has constant value.
3: Too many iterations(_value_).  The iterative procedure to find the co-variance matrix C, has failed to converge in max_iter iterations.
490: The iterative procedure to find C has become unstable. This may happen if the value of eps is too large.
78: Cannot open file _string	 for appending.
79: Cannot close file _string	.
73: Memory allocation failed.
successful call of the nag_robust_corr_estim function.

Example:
    A sample of 10ob servations on three variables is read in and the robust estimate of the covariance
    matrix is computed assuming 10% gross errors are to be expected and file c;\c\test.txt exists.

void test_nag_robust_corr_estim()
{
    int i, j, k, m, n;
    int ifail;
    matrix x;
    x.SetSize(20,10);
    double theta[10];
    int tdx=10;
    int max_iter, l1, l2;
    int print_iter;
    double eps, cov[15];
    int iter;
    double tol;
    x[0][0] = 3.4;
    x[0][1] =  6.9 ;
    x[0][2] = 12.2;
    x[1][0] = 6.4 ;
    x[1][1] = 2.5;
    x[1][2] = 15.1;
    x[2][0] = 4.9;
    x[2][1] = 5.5;
    x[2][2] = 14.2;
    x[3][0] = 7.3;
    x[3][1] = 1.9;
    x[3][2] = 18.2;
    x[4][0] = 8.8;
    x[4][1] = 3.6;
    x[4][2] = 11.7;
    x[5][0] = 8.4;
    x[5][1] =  1.3;
    x[5][2] =  17.9;

    x[6][0] = 5.3;
    x[6][1] = 3.1;
    x[6][2] = 15.0;
    x[7][0] = 2.7;
    x[7][1] = 8.1;
    x[7][2] = 7.7;
    x[8][0] = 6.1;
    x[8][1] = 3.0;
    x[8][2] = 21.9;
    x[9][0] = 5.3;
    x[9][1] = 2.2;
    x[9][2] = 13.9;

    n = 10;
    m = 3;
    eps = 0.1;
    max_iter = 100;
    tol = 5e-5;
    print_iter = 1;
    printf("The input data are as follows\n");
    printf("\nn = 10, m = 3, eps = 0.1, max_iter = 100, tol = 5e-5, print_iter = 1\n");
    printf("\nthe ouput file name = c:\\c\\test.txt\n");
    String	strFile = "c:\\c\\test.txt";
    nag_robust_corr_estim(n, m, x, tdx, eps, cov, theta, max_iter, print_iter,
                            strFile, tol, &iter);
    printf("\n\ng02hkc required %ld iterations to converge\n\n", iter);
    printf("Covariance matrix\n");
    l2 = 0;
    for (j = 1; j <= m; ++j)
    {
        l1 = l2 + 1;
        l2 += j;
        for (k = l1; k <= l2; ++k)
        {
            printf("%6.3f\t", cov[k - 1]);
        }
        printf("\n");
    }
    printf("\n\ntheta\n");
    for (j = 1; j <= m; ++j)
    {
        printf("%6.3f\n", theta[j - 1]);
    }

}

  The output is as follows

    The input data are as follows

    n = 10, m = 3, eps = 0.1, max_iter = 100, tol = 5e-5, print_iter = 1

    the ouput file name = c:\c\test.txt

    g02hkc required 23 iterations to converge

    Covariance matrix
      3.461
     -3.681	   5.348
      4.682	  -6.645	14.439

    theta
     5.818
     3.681
    15.037

Summary: Robust Covariance matrix, Robust Parameter Estimates.
Sample data:
Header file: OCN_g02.h
See also:


nag_mv_prin_comp

Function: nag_mv_prin_comp
Prototype:
int nag_mv_prin_comp(Nag_PrinCompMat pcmatrix,Nag_PrinCompScores scores,int n,int m,double x[],int tdx,int isx[],double s[],double w[],int nvar,double e[],int tde,double p[],int tdp,double v[],int tdv)
Remarks: performs a principal component analysis on a data matrix; both the principal component loadings and the principal component scores are returned.
Parameters:
n
  the number of observations
m
  the number of variables in the data matrix
x[]
  contain the ith observation for the jth variable, for i = 1, 2, . . ., n; j = 1, 2, . . .,m.
tdx
  the last dimension of the array x.
isx[]
  indicates whether or not the jth variable is to be included in the analysis.
s[]
  the standardizations to be used, if any.
w[]
  contain the weights to be used in the principal component analysis.
nvar
  the number of variables in the principal component analysis.
e[]
  the statistics of the principal component analysis.
tde
  the last dimension of the array e.
p[]
  the first nvar columns of p contain the principal component loadings. The jth column of p contains the nvar coefficients for the jth principal component.
tdp
  the last dimension of the array p
v[]
  the first nvar columns of v contain the principal component scores. The jth column of v contains the n scores for the jth principal component.
tdv
  the last dimension of the array v.

Return values:
The function returns NAG error code or 0 if no error.
70:  On entry, parameter pcmatrix had an illegal value.  On entry, parameter scores had an illegal value.
11:  On entry, m must not be less than 1: m = _value_.  On entry, n must not be less than 2: n = _value_.  On entry, nvar must not be less than 1: nvar = _value_.  On entry, tde must not be less than 6: tde = _value_.
17:  On entry, tdx = _value_ while m = _value_. These parameters must satisfy tdx = m.  On entry, tdv = _value_ while nvar = _value_. These parameters must satisfy tdv = nvar.  On entry, tdp = _value_ while nvar = _value_. These parameters must satisfy tdp = nvar.
19:  On entry, nvar = _value_ while m = _value_. These parameters must satisfy nvar = m.
20:  On entry, nvar = _value_ while n = _value_. These parameters must satisfy nvar < n.
500: On entry, wt[_value_] = _value_.  Constraint: when referenced, all elements of wt must be non-negative.
501: The number of variables, nvar in the analysis = _value_, while the number of variables included in the analysis via array isx = _value_.  Constraint: these two numbers must be the same.
504: On entry, the standardisation element s[_value_] = _value_, while the variable to be included isx[_value_] = _value_.  Constraint: when a variable is to included, the standardisation element must be positive.
503: With weighted data, the e.ective number of observations given by the sum of weights = _value_, while the number of variables included in the analysis, nvar = _value_.  Constraint: effective number of observations > nvar + 1.
427: The singular value decomposition has failed to converge.  This is an unlikely error exit.
505: All eigenvalues/singular values are zero.  This will be caused by all the variables being constant.
73:  Memory allocation failed.
74:  An internal error has occurred in this function.  Check the function call and array sizes. If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_prin_comp function.

Example:
    Assume we have four Matrix, "Matrix1"'s size is 10X3 and stores 30 number; "Matrix2"'s
    size is 3X6; "Matrix3"'s size is 3X3, and "Matrix4"'s size is 12X3.  We will store the
    value to "Matrix2", "Matrix3" and "Matrix4".

    matrix p;
    p.SetSize(3,3);
    double s[3];
    matrix e;
    e.SetSize(3,6);
    matrix v;
    v.SetSize(12,3);
    double wt[12];
    double *wtptr;
    wtptr = NULL;
    int isx[3] = {1, 1, 1};
    int nvar = 3;
    int tdx = 3;
    int tde = 6;
    int tdp = 3;
    int tdv = 3;
    int i, j, m = 3, n = 10;
    Nag_PrinCompMat pcmatrix;
    Nag_PrinCompScores scores;
    Matrix xx("Matrix1");
    matrix x = xx;
    char weight, mat, std;
    mat = 'V';
    std = 'E';
    weight = 'U';

    if (mat == 'C')
        pcmatrix = Nag_MatCorrelation;
    else if (mat == 'S')
        pcmatrix = Nag_MatStandardised;
    else if (mat == 'U')
        pcmatrix = Nag_MatSumSq;
    else
        pcmatrix = Nag_MatVarCovar;
    if (std == 'S')
        scores = Nag_ScoresStand;
    else if (std == 'U')
        scores = Nag_ScoresNotStand;
    else if (std == 'Z')
        scores = Nag_ScoresUnitVar;
    else
        scores = Nag_ScoresEigenval;

    nag_mv_prin_comp(pcmatrix, scores, n, m, x, tdx, isx, s, wtptr, nvar,
                e, tde, p, tdp, v, tdv);
    //put the result to the matrix.
    //first column is Eigenvalues, second column is Percentage variation,
    //third column is Cumulative variation, fourth column is Chisp,
    //fifth column is DF and sixth column is Sig.
    Matrix ee("Matrix2");
    ee = e;
    Matrix pp("Matrix3");		//Eigenvalues
    pp = p;
    Matrix vv("Matrix4");		//Principal component scores
    vv = v;
    A data set is taken from Cooley and Lohnes (1971), it consists of ten observations on
    three variables.  The unweighted principal components based on the variance-covariance
    matrix are computed and unstandardised principal component scores requested.

void test_nag_mv_prin_comp()
{
    matrix p;
    p.SetSize(3,3);
    double s[3];
    matrix e;
    e.SetSize(3,6);
    matrix v;
    v.SetSize(12,3);
    matrix x = {{7.0, 4.0, 3.0}, {4.0, 1.0, 8.0}, {6.0, 3.0, 5.0},
    {8.0, 6.0, 1.0}, {8.0, 5.0, 7.0}, {7.0, 2.0, 9.0}, {5.0, 3.0, 3.0},
    {9.0, 5.0, 8.0}, {7.0, 4.0, 5.0}, {8.0, 2.0, 2.0}};
    double wt[12];
    double *wtptr;
    int isx[3];
    int nvar = 3;
    int tdx = 3;
    int tde = 6;
    int tdp = 3;
    int tdv = 3;
    int i, j, m = 3, n = 10;
    Nag_PrinCompMat pcmatrix;
    Nag_PrinCompScores scores;
    char weight, mat, std;

     for(i = 0; i < 3; i++)
         isx[i] = 1;

    mat = 'V';
    std = 'E';
    weight = 'U';

    if (mat == 'C')
        pcmatrix = Nag_MatCorrelation;
    else if (mat == 'S')
        pcmatrix = Nag_MatStandardised;
    else if (mat == 'U')
        pcmatrix = Nag_MatSumSq;
    else
        pcmatrix = Nag_MatVarCovar;
    if (std == 'S')
        scores = Nag_ScoresStand;
    else if (std == 'U')
        scores = Nag_ScoresNotStand;
    else if (std == 'Z')
        scores = Nag_ScoresUnitVar;
    else
        scores = Nag_ScoresEigenval;

    wtptr = NULL;

    nag_mv_prin_comp(pcmatrix, scores, n, m, x, tdx, isx, s, wtptr, nvar,
                    e, tde, p, tdp, v, tdv);

    printf("Eigenvalues  Percentage   Cumulative   Chisq   DF   Sig\n");
    printf("              variation   variation\n\n");

    for (i = 0; i < nvar; ++i)
    {
        for (j = 0; j < 6; ++j)
            printf("%11.4f",e[i][j]);
        printf("\n");
    }
    printf("\nEigenvalues\n\n");
    for (i = 0; i < nvar; ++i)
    {
        for (j = 0; j < nvar; ++j)
            printf("%9.4f",p[i][j]);
        printf("\n");
    }
    printf("\nPrincipal component scores \n\n");
    for (i = 0; i < n; ++i)
    {
        printf("%2ld", i+1);
        for (j = 0; j < nvar; ++j)
            printf("%9.3f", v[i][j]);
        printf("\n");
    }
}

    The output is following:

    Eigenvalues		Percentage 		Cumulative 		Chisq 		DF 			Sig
                    variation 		variation
    8.2739 			0.6515 			0.6515 			8.6127 		5.0000 		0.1255
    3.6761 			0.2895 			0.9410 			4.1183 		2.0000 		0.1276
    0.7499 			0.0590 			1.0000 			0.0000 		0.0000 		0.0000

    Eigenvalues

     0.1376 	0.6990   0.7017
     0.2505 	0.6609 	-0.7075
    -0.9583 	0.2731 	-0.0842

    Principal component scores

    1 	 2.151 	 -0.173 	-0.107
    2 	-3.804   -2.887 	-0.510
    3 	-0.153   -0.987 	-0.269
    4 	 4.707 	  1.302 	-0.652
    5 	-1.294 	  2.279 	-0.449
    6 	-4.099 	  0.144 	 0.803
    7 	 1.626 	 -2.232 	-0.803
    8 	-2.114 	  3.251 	 0.168
    9 	 0.235 	  0.373 	-0.275
    10 	 2.746 	 -1.069 	 2.094

Summary: Eigenvalues, Percentage Variation, Cumulative Variation, Principal Component Scores......
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_canon_var

Function: nag_mv_canon_var
Prototype:
int nag_mv_canon_var(Nag_Weightstype weights,int n,int m,double x[],int tdx,int isx[],int nx,int ing[],int ng,double *wtptr,int nig[],double cvm[],int tdcvm,double e[],int tde,int *ncv,double cvx[],int tdcvx,double tol,int *irankx)
Remarks: performs a canonical variate (canonical descrimination) analysis.
Parameters:
weights
  indicates the type of weights to be used in the analysis.
n
  the number of observations.
m
  the total number of variables.
x[]
  contain the ith observation for the jth variable, for i = 1, 2, . . ., n; j = 1, 2, . . .,m.
tdx
  the last dimension of the array x.
isx[]
  indicates whether or not the jth variable is to be included in the analysis.
nx
  the number of variables in the analysis.
ing[]
  indicates which group the ith observation is in, for i = 1, 2, . . ., n.
ng
  The number of groups.
wtptr
  if weight = Nag Weightsfreq or Nag Weightsvar then the elements of wt must contain the weights to be used in the analysis.
nig[]
  the number of observations in group j, for j = 1, 2, . . . , ng.
cvm[]
  the mean of the jth canonical variate for the ith group, for i = 1, 2, . . . , ng; j = 1, 2, . . . , l;
tdcvm
  the last dimension of the array cvm.
e[]
  the statistics of the canonical variate analysis.
tde
  the last dimension of the array e.
ncv
  the number of canonical variates.
cvx[]
  the canonical variate loadings.
tdcvx
  the last dimension of the array cvx.
tol
  the value of tol is used to decide if the variables are of full rank.
irankx
  the rank of the dependent variables.

Return values:
The function returns NAG error code or 0 if no error.
70: On entry, parameter weight had an illegal value.
11: On entry, nx must not be less than 1: nx = _value_.  On entry, ng must not be less than 2: ng = _value_.  On entry, tde must not be less than 6: tde = _value_.
5:  On entry, tol must not be less than 0.0: tol = _value_.
17: On entry, m = _value_ while nx = _value_.  These parameters must satisfy m = nx.  On entry, tdx = _value_ while m = _value_.  These parameters must satisfy tdx = m.  On entry, tdcvx = _value_ while ng = _value_.  These parameters must satisfy tdcvx = ng-1.  On entry, tdcvm = _value_ while nx = _value_.  These parameters must satisfy tdcvm = nx.
29: On entry, n = _value_, nx = _value_ and ng = _value_.  These parameters must satisfy n = nx + ng.
112: On entry, ing[_value_] = _value_, ng = _value_.  Constraint: 1 = ing[i - 1] = ng, i = 1, 2, . . ., n.
510: The wt array argument must not be NULL when the weight argument indicates weights.
500: On entry, wt[_value_] = _value_.  Constraint: When referenced, all elements of wt must be non-negative.
501: The number of variables, nx in the analysis = _value_, while number of variables included in the analysis via array isx = _value_.  Constraint: these two numbers must be the same.
427: The singular value decomposition has failed to converge.  This is an unlikely error exit.
506: A canonical correlation is equal to one.  This will happen if the variables provide an exact indication as to which group every observation is allocated.
507: Either the e.ective number of groups is less than two or the e.ective number of groups plus the number of variables, nx is greater than the the e.ective number of observations.
508: The rank of the variables is zero.  This will happen if all the variables are constants.
73: Memory allocation failed.
74: An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_canon_var function.

Example:
    A sample of nine observations, each consisting of three variables plus group indicator, is read in.
    There are three groups. An unweighted canonical variate analysis is performed.

void test_nag_mv_canon_var()
{

    matrix e;
    e.SetSize(3,6);
    matrix x = {{13.3, 10.6, 21.2}, {13.6, 10.2, 21.0}, {14.2, 10.7, 21.1},
    {13.4, 9.4, 21.0}, {13.2, 9.6, 20.1}, {13.9, 10.4, 19.8}, {12.9, 10.0, 20.5},
    {12.2, 9.9, 20.7}, {13.9, 11.0, 19.1}};
    double wt[9];
    matrix cvm;
    cvm.SetSize(3,3);
    double tol;
    matrix cvx;
    cvx.SetSize(3,3);
    int i, j, m = 3, n = 9;
    int ng = 3;
    int nx = 3;
    int nig[3], ncv;
    int ing[9] = {1, 2, 3, 1, 2, 3, 1, 2, 3};
    int irx, isx[6];
    int tdx = 3;
    int tdc = 3;
    int tde = 6;
    char wtchar = 'U';
    Nag_Weightstype weight;

    weight = Nag_NoWeights;

    for (j = 0; j < m; ++j)
        isx[j] = 1;
    tol = 1e-6;

    nag_mv_canon_var(weight, n, m, x, tdx, isx, nx, ing, ng, wt, nig,
                    cvm, tdc, e, tde, &ncv, cvx, tdc, tol, &irx);

    printf("%s%2ld\n\n","Rank of x = ",irx);
    printf("      Canonical   Eigenvalues Percentage  ChiSQ       DF          SIG\n");
    printf("      Correlations            Variation\n");
    for (i = 0; i < ncv; ++i)
    {
        for (j = 0; j < 6; ++j)
            printf("%12.4f",e[i][j]);
            printf("\n");
    }
    printf("\nCanonical Coefficients for X\n");
    for (i = 0; i < nx; ++i)
    {
        for (j = 0; j < ncv; ++j)
            printf("%9.4f",cvx[i][j]);
        printf("\n");
    }
    printf("\nCanonical variate means\n");
    for (i = 0; i < ng; ++i)
    {
        for (j = 0; j < ncv; ++j)
            printf("%9.4f",cvm[i][j]);
        printf("\n");
    }
}

    The output is following:

    Rank of x = 3
    Canonical 		Eigenvalues 	Percentage 		CHISQ 		DF 			SIG
    Correlations 					Variation
    0.8826 			3.5238 			0.9795 			7.9032 		6.0000 		0.2453
    0.2623 			0.0739 			0.0205 			0.3564 		2.0000 		0.8368

    Canonical Coefficients for X
    -1.7070 	0.7277
    -1.3481 	0.3138
     0.9327 	1.2199

    Canonical variate means
     0.9841 	0.2797
     1.1805 	-0.2632
    -2.1646 	-0.0164

Summary: Canonical Coeffiecients, Canonical Correlation, Eigenvalues, Canonical Variate Means....
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_canon_corr

Function: nag_mv_canon_corr
Prototype:
int nag_mv_canon_corr(int n,int m,double z[],int tdz,int isz[],int nx,int ny,double wt[],double e[],int tde,int *ncv,double cvx[],int tdcvx,double cvy[],int tdcvy,double tol)
Remarks: performs canonical correlation analysis upon input data matrices.
Parameters:
n
  the number of observations.
m
  the total number of variables.
z[]
  contain the ith observation for the jth variable, for i = 1, 2, . . ., n; j = 1, 2, . . .,m.
tdz
  the last dimension of the array z.
isz[]
  indicates whether or not the jth variable is to be included in the analysis and to which set of variables it belongs.
nx
  the number of x variables in the analysis.
ny
  the number of y variables in the analysis.
wt[]
  the weights to be used in the analysis.
e[]
  the statistics of the canonical variate analysis.
tde
  the last dimension of the array e.
ncv
  the number of canonical correlations.
cvx[]
  the canonical variate loadings for the x variables.
tdcvx
  the last dimension of the array cvx.
cvy[]
  the canonical variate loadings for the y variables.
tdcvy
  the last dimension of the array cvy.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, nx must not be less than 1: nx = _value_.  On entry, ny must not be less than 1: ny = _value_.  On entry, tde must not be less than 6: tde = _value_.
5: On entry, tol must not be less than 0.0: tol = _value_.
17: On entry, tdz = _value_ while m = _value_.  These parameters must satisfy tdz = m.
29: On entry, m = _value_, nx = _value_ and ny = _value_.  These parameters must satisfy m = nx + ny.  On entry, n = _value_, nx = _value_ and ny = _value_.  These parameters must satisfy n > nx + ny.  On entry, tdcvx = _value_, nx = _value_ and ny = _value_.  These parameters must satisfy tdcvx = min(nx,ny).  On entry, tdcvy = _value_, nx = _value_ and ny = _value_.  These parameters must satisfy tdcvy = min(nx,ny).
500: On entry, wt[_value_] = _value_.  Constraint: When referenced, all elements of wt must be non-negative.
501: The number of variables, nx in the analysis = _value_, while the number of x variables included in the analysis via array isz = _value_.  Constraint: these two numbers must be the same.  The number of variables, ny in the analysis = _value_, while the number of y variables included in the analysis via array isz = _value_.  Constraint: these two numbers must be the same.
503: With weighted data, the e.ective number of observations given by the sum of weights = _value_, while number of variables included in the analysis, nx + ny = _value_.  Constraint: E.ective number of observations = nx + ny + 1.
427: The singular value decomposition has failed to converge.  This is an unlikely error exit.
506: A canonical correlation is equal to one.  This will happen if the x and y variables are perfectly correlated.
509: The rank of the x matrix or the rank of the y matrix is zero.  This will happen if all the x and y variables are constants.
73: Memory allocation failed.
74: An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_canon_corr function.

Example:
    A sample of nine observations with two variables in each set is read in. The second and third
    variables are x variables while the first and last are y variables. Canonical variate analysis is performed.

void test_nag_mv_canon_corr()
{

    matrix e, cvx, cvy;
    e.SetSize(2,6);
    cvx.SetSize(2,2);
    cvy.SetSize(2,2);
    matrix z = {{80.0, 58.4, 14.0, 21.0}, {75.0, 59.2, 15.0, 27.0}, {78.0, 60.3, 15.0, 27.0},
    {75.0, 57.4, 13.0, 22.0}, {79.0, 59.5, 14.0, 26.0}, {78.0, 58.1, 14.5, 26.0},
    {75.0, 58.0, 12.5, 23.0}, {64.0, 55.5, 11.0, 22.0}, {80.0, 59.2, 12.5, 22.0}};
    double wt[9];
    double tol;
    double *wtptr;
    int i, j, m = 4, n = 9;
    int ix = 2, iy = 2;
    int nx, ny;
    int ncv;
    int isz[4] = {-1, 1, 1, -1};
    int tdz= 4;
    int tde=6;
    int tdc=2;
    char weight = 'U';

    wtptr = NULL;
    tol = 1e-6;
    nx = ix;
    ny= iy;

    nag_mv_canon_corr(n, m, z, tdz, isz, nx, ny, wtptr, e, tde, &ncv, cvx, tdc, cvy, tdc, tol);

    printf("\n%s%2ld%s%2ld\n\n","Rank of x = ",nx," Rank of y= ",ny);
    printf(" Canonical Eigenvalues Percentage Chisq DF Sig\n");
    printf(" correlations          variation\n");
    for (i = 0; i < ncv; ++i)
    {
        for (j = 0; j < 6; ++j)
            printf("%12.4f",e[i][j]);
        printf("\n");
    }
    printf("\nCanonical coefficients for x\n");
    for (i = 0; i < ix; ++i)
    {
        for (j = 0; j < ncv; ++j)
            printf("%9.4f",cvx[i][j]);
        printf("\n");
    }
    printf("\nCanonical coefficients for y\n");
    for (i = 0; i < iy ;++i)
    {
        for (j = 0; j < ncv; ++j)
            printf("%9.4f",cvy[i][j]);
        printf("\n");
    }
}

    The output is following:

    Rank of x = 2 Rank of y= 2
    Canonical 		Eigenvalues 	Percentage 	Chisq 		DF 			Sig
    correlations 					variation

    0.9570 			10.8916 		0.9863 		14.3914 	4.0000 		0.0061
    0.3624 		 	 0.1512 		0.0137 		 0.7744 	1.0000 		0.3789

    Canonical coefficients for x
    -0.4261 		 1.0337
    -0.3444 		-1.1136

    Canonical coefficients for y
    -0.1415 		 0.1504
    -0.2384 		-0.3424

Summary: Canonical coefficients, Eigenvalues, Percentage variation, Canonical coefficients...
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_orthomax

Function: nag_mv_orthomax
Prototype:
int nag_mv_orthomax(Nag_RotationLoading stand,double g,int nvar,int k,double fl[],int tdf,double flr[],double r[],int tdr,double acc,int maxit,int *iter)
Remarks: computes orthogonal rotations for a matrix of loadings using a generalized orthomax criterion.
Parameters:
g
  the criterion constant.
nvar
  The number of original variables.
k
  The number of derived variates or factors.
fl[]
  the matrix of loadings.
tdf
  the last dimension of the arrays fl and flr.
flr[]
  the rotated matrix of loadings.
r[]
  the matrix of rotations.
tdr
  the last dimension of the array r.
acc
  indicates the accuracy required.
maxit
  the maximum number of iterations.
iter
  the number of iterations performed.

Return values:
The function returns NAG error code or 0 if no error.
70: On entry, parameter stand had an illegal value.
11: On entry, k must not be less than 2: k = _value_.
12: On entry, maxit must not be less than or equal to 0 : maxit = _value_.
5:  On entry, g must not be less than 0.0: g = _value_.  On entry, acc must not be less than 0.0: acc = _value_.
17: On entry, nvar = _value_ while k = _value_.  These parameters must satisfy nvar = k.  On entry, tdf = _value_ while k = _value_.  These parameters must satisfy tdf = k.  On entry, tdr = _value_ while k = _value_.  These parameters must satisfy tdr = k.
427: The singular value decomposition has failed to converge.  This is an unlikely error exit.
511: The algorithm to .nd R has failed to reach the required accuracy in the given number of iterations, _value_. Try increasing acc or increasing maxit. The returned solution should be a reasonable approximation.
73: Memory allocation failed.
74: An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_orthomax function.

Example:
    The example is taken from page 75 of Lawley and Maxwell (1971). The results from a
    factor analysis of ten variables using three factors are input and rotated using
    varimax rotations without standardising rows.

void test_nag_mv_orthomax()
{

    double g = 1.0;
    matrix r, flr;
    r.SetSize(3,3);
    flr.SetSize(10,3);
    matrix fl = {{0.788, -0.152, -0.352}, {0.874, 0.381, 0.041}, {0.814, -0.043, -0.213},
    {0.798, -0.170, -0.204}, {0.641, 0.070, -0.042}, {0.755, -0.298, 0.067}, {0.782, -0.221, 0.028},
    {0.767, -0.091, 0.358}, {0.733, -0.384, 0.229}, {0.771, -0.101, 0.071}};
    double acc = 0.00001;
    int iter, nvar;
    int i, j, k;
    int maxit = 20;
    int tdf = 3;
    int tdr = 3;
    char char_stand;
    Nag_RotationLoading stand;

    nvar = 10;
    k = 3;
    char_stand = 'U';

    if (char_stand == 'S')
        stand = Nag_RoLoadStand;
    else
        stand = Nag_RoLoadNotStand;

    nag_mv_orthomax(stand, g, nvar, k, fl, tdf, flr, r, tdr, acc, maxit, &iter);

    printf("\n Rotated factor loadings\n\n");
    for (i = 0; i < nvar; ++i)
    {
        for (j = 0; j < k ;++j)
            printf(" %8.3f",flr[i][j]);
        printf("\n");
    }
    printf("\n Rotation matrix\n\n");
    for (i = 0; i < k ;++i)
    {
        for (j = 0; j < k ;++j)
            printf(" %8.3f",r[i][j]);
        printf("\n");
    }
}

    The output is following:

    Rotated factor loadings

    0.329 	-0.289 	-0.759
    0.849 	-0.273 	-0.340
    0.450 	-0.327 	-0.633
    0.345 	-0.397 	-0.657
    0.453 	-0.276 	-0.370
    0.263 	-0.615 	-0.464
    0.332 	-0.561 	-0.485
    0.472 	-0.684 	-0.183
    0.209 	-0.754 	-0.354
    0.423 	-0.514 	-0.409

    Rotation matrix

    0.633 	-0.534 	-0.560
    0.758 	 0.573 	 0.311
    0.155 	-0.622 	 0.768

Summary: Rotation factor loading, Rotation matrix.
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_procustes

Function: nag_mv_procustes
Prototype:
int nag_mv_procustes(Nag_TransNorm stand,Nag_RotationScale pscale,int n,int m,double x[],int tdx,double y[],int tdy,double yhat[],double r[],int tdr,double *alpha,double *rss,double res[])
Remarks: computes Procrustes rotations in which an orthogonal rotation is found so that a transformed matrix best matches a target matrix.
Parameters:
n
  the number of points.
m
  the number of dimensions.
x[]
  the matrix to be rotated.
tdx
  the last dimension of the array x.
y[]
  the target matrix.
tdy
  the last dimension of the arrays y.
yhat[]
  the fitted matrix
r[]
  the matrix of rotations.
tdr
  the last dimension of the array r.
alpha
  if pscale = Nag LsqScale the scaling factor, a; otherwise alpha is not set
rss
  the residual sum of squares.
res[]
  the residuals.

Return values:
The function returns NAG error code or 0 if no error.
70: On entry, parameter stand had an illegal value.  On entry, parameter pscale had an illegal value.
11: On entry, n must not be less than 1: n = _value_.  On entry, m must not be less than 1: m = _value_.
17: On entry, tdx = _value_ while m = _value_.  These parameters must satisfy tdx = m.  On entry, tdy = _value_ while m = _value_.  These parameters must satisfy tdy = m.  On entry, tdr = _value_ while m = _value_.  These parameters must satisfy tdr = m.
19: On entry, m = _value_ while n = _value_.  These parameters must satisfy m = n.
427: The singular value decomposition has failed to converge.  This is an unlikely error exit.
512: On entry, either x or y contains only zero-points (possibly after translation) when normalization is to be applied.
513: The fitted matrix Y-hat, contains only zero-points when least-squares scaling is applied.
73: Memory allocation failed.
74: An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_orthomax function.

Example:
    Three points representing the vertices of a triangle in two dimensions are input.
    The points are translated and rotated to match the triangle given by (0,0),(1,0),(0,2)
    and scaling is applied after rotation.

void test_nag_mv_procustes()
{
    matrix r, yhat;
    r.SetSize(2,2);
    yhat.SetSize(3,2);
    matrix x = {{0.63, 0.58}, {1.36, 0.39}, {1.01, 1.76}};
    matrix y = {{0.0, 0.0}, {1.0, 0.0}, {0.0, 2.0}};
    double res[3];
    double alpha;
    double rss;
    int i, j, m = 2, n = 3;
    int tdx = 2;
    int tdr = 2;
    int tdy = 2;
    char char_scale;
    char char_stand;
    Nag_TransNorm stand;
    Nag_RotationScale scale;

    char_stand = 'C';
    char_scale = 'S';

    if (char_stand == 'N')
        stand = Nag_NoTransNorm;

    else if (char_stand == 'Z')
        stand = Nag_Orig;

    else if (char_stand == 'C')
        stand = Nag_OrigCentroid;

    else if (char_stand == 'U')
        stand = Nag_Norm;

    else if (char_stand == 'S')
        stand = Nag_OrigNorm;

    else if (char_stand == 'M')
        stand = Nag_OrigNormCentroid;

    if (char_scale == 'S')
        scale = Nag_LsqScale;

    else if (char_scale == 'U')
        scale = Nag_NotLsqScale;

    nag_mv_procustes(stand, scale, n, m, x, tdx, y, tdy, yhat, r, tdr, &alpha, &rss, res);

    printf("\n Rotation matrix\n\n");
    for (i = 0; i < m; ++i)
    {
        for (j = 0; j < m; ++j)
            printf(" %7.3f ",r[i][j]);
        printf("\n");
    }
    if (char_scale == 'S' || char_scale == 's')
        printf("\n%s%10.3f\n"," Scale factor = ",alpha);

    printf("\n Target matrix \n\n");
    for (i = 0; i < n; ++i)
    {
        for (j = 0; j < m; ++j)
            printf(" %7.3f ",y[i][j]);
        printf("\n");
    }
    printf("\n Fitted matrix\n\n");
    for (i = 0; i < n; ++i)
    {
        for (j = 0; j < m; ++j)
            printf(" %7.3f ",yhat[i][j]);
        printf("\n");
    }
    printf("\n%s%10.3f\n","RSS = ",rss);
}

    The output is following:

    Rotation matrix
     0.967 		0.254
    -0.254 		0.967

    Scale factor = 1.556

    Target matrix
    0.000 	0.000
    1.000 	0.000
    0.000 	2.000

    Fitted matrix
    -0.093 		0.024
     1.080 		0.026
     0.013 		1.950

    RSS = 0.019

Summary: Rotation matrix, Target matrix, Fitted matrix, RSS, Scale factor.
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_discrim

Function: nag_mv_discrim
Prototype:
int nag_mv_discrim(int n,int m,double x[],int tdx,int isx[],int nvar,int ing[],int ng,double *wtptr,int nig[],double gmean[],int tdg,double det[],double gc[],double *stat,double *df,double *sig)
Remarks: computes a test statistic for the equality of within-group covariance matrices and also computes matrices for use in discriminant analysis.
Parameters:
n
  the number of observations.
m
  the number of variables in the data array x.
x[]
  contain the kth observation for the lth variable, for k = 1, 2, . . ., n; l = 1, 2, . . ., m .
tdx
  the last dimension of the array x.
isx[]
  indicates whether or not the lth variable in x is to be included in the variance-covariance matrices.
nvar
  the number of variables in the variance-covariance matrices.
ing[]
  indicates to which group the kth observation belongs, for k = 1, 2, . . ., n.
ng
  the number of groups.
wtptr
  the weights to be used in the analysis and the effective number of observations for a group is the sum of the weights of the observations in that group.
nig[]
  the number of observations in the jth group, for j = 1, 2, . . . , ng
gmean[]
  the jth row of gmean contains the means of the p selected variables for the jth group, for j = 1, 2, . . . , ng.
tdg
  the last dimension of the array gmean.
det[]
  the logarithm of the determinants of the within-group variance-covariance matrices.
gc[]
  the first p(p+1)/2 elements of gc contain R and the remaining ng blocks of p(p+1)/2 elements contain the Rj matrices.
stat
  the likelihood-ratio test statistic, G.
df
  the degrees of freedom for the distribution of G.
sig
  the significance level for G.

Return values:
The function returns NAG error code or 0 if no error.
11:  On entry, n must not be less than 1: n = _value_.  On entry, nvar must not be less than 1: nvar = _value_.  On entry, ng must not be less than 2: ng = _value_.
17:  On entry, m = _value_ while nvar = _value_.  These parameters must satisfy m = nvar.  On entry, tdx = _value_ while m = _value_.  These parameters must satisfy tdx = m.  On entry, tdg = _value_ while nvar = _value_.  These parameters must satisfy tdg = nvar.
112: On entry, ing[_value_] = _value_, ng = _value_.  Constraint: 1 = ing[i - 1] = ng, i = 1, 2, . . ., n.
500: On entry, wt[_value_] = _value_. Constraint: when referenced, all elements of wt must be non-negative.
501: The number of variables, nvar in the analysis = _value_, while number of variables included in the analysis via array isx = _value_.  Constraint: these two numbers must be the same.
515: On entry, group _value_ has _value_ e.ective observations.  Constraint: in each group the e.ective number of observations must be = 1.
516: On entry, group _value_ has _value_ members, while nvar = _value_.  Constraint: number of members in each group = nvar
520: The variables in group _value_ are not of full rank.
519: The variables are not of full rank.
73:  Memory allocation failed.
74:  An internal error has occurred in this function.  Check the function call and array sizes. If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_discrim function.

Example:
    The data, taken from Aitchison and Dunsmore (1975), is concerned with the diagnosis
    of three 'types' of Cushing's syndrome. The variables are the logarithms of the
    urinary excretion rates (mg/24hr) of two steroid metabolites. Observations for a
    total of 21 patients are input and the statistics computed by nag mv discrim (g03dac).
    The printed results show that there is evidence that the within-group variance-covariance
    matrices are not equal.

void test_nag_mv_discrim()
{
    double stat;
    double det[3], gc[12];
    matrix gmean;
    gmean.SetSize(3,2);
    matrix x = {{1.1314, 2.4596}, {1.0986, 0.2624}, {0.6419, -2.3026}, {1.3350, -3.2189},
    {1.4110, 0.0953}, {0.6419, -0.9163}, {2.1163, 0.0000}, {1.3350, -1.6094}, {1.3610, -0.5108},
    {2.0541, 0.1823}, {2.2083, -0.5108}, {2.7344, 1.2809}, {2.0412, 0.4700}, {1.8718, -0.9163},
    {1.7405, -0.9163}, {2.6101, 0.4700}, {2.3224, 1.8563}, {2.2192, 2.0669}, {2.2618, 1.1314},
    {3.9853, 0.9163}, {2.7600, 2.0281}};
    double wt[21];
    double df;
    double *wtptr = NULL;
    double sig;
    int nvar = 2;
    int i, j, m = 2, n = 21;
    int isx[2], nig[3];
    int ing[21] = {1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3};
    int ng = 3;
    int tdgmean = 2;
    int tdx = 2;
    char weight = 'U';

    for (j = 0; j < m; ++j)
        isx[j] = 1;

    nag_mv_discrim(n, m, x, tdx, isx, nvar, ing, ng, wtptr, nig, gmean, tdgmean, det, gc,
                &stat, &df, &sig);

    printf("\nGroup means\n\n");
    for (i = 0; i < ng; ++i)
    {
        for (j = 0; j < nvar; ++j)
            printf("%10.4f",gmean[i][j]);
        printf("\n");
    }
    printf("\nLOG of determinants\n\n");
    for (j = 0; j < ng; ++j)
        printf("%10.4f",det[j]);
    printf("\n\n%s%7.4f\n","stat = ",stat);
    printf("%s%7.4f\n"," df = ",df);
    printf("%s%7.4f\n"," sig = ",sig);
}

    The output is following:

    Group means

    1.0433   -0.6034
    2.0073   -0.2060
    2.7097    1.5998

    LOG of determinants

           -0.8273   -3.0460   -2.2877

    stat = 19.2410
     df =  6.0000
     sig =  0.0038

Summary:
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_discrim_mahaldist

Function: nag_mv_discrim_mahaldist
Prototype:
int nag_mv_discrim_mahaldist(Nag_GroupCovars equal,Nag_MahalDist mode,int nvar,int ng,double gmean[],int tdg,double gc[],int nobs,int m,int isx[],double x[],int tdx,double d[],int tdd)
Remarks: computes Mahalanobis squared distances for groups or pooled variance-covariance matrices. It is intended for use after nag mv discrim (g03dac).
Parameters:
nvar
  the number of variables, p, in the variance-covariance matrices as specified to nag mv discrim (g03dac).
ng
  the number of groups.
gmean[]
  the jth row of gmean contains the means of the p selected variables for the jth group, for j = 1, 2, . . . , ng.
tdg
  the last dimension of the array gmean.
gc[]
  the first p(p + 1)/2 elements of gc should contain the upper triangular matrix R and the next ng blocks of p(p+1)/2 elements should contain the upper triangular matrices Rj.
nobs
  if mode = Nag SamplePoints the number of sample points in x for which distances are to be calculated.
m
  if mode = Nag SamplePoints the number of variables in the data array x.
isx[]
  if mode = Nag SamplePoints, isx[l-1] indicates if the lth variable in x is to be included in the distance calculations.
x[]
  contain the kth sample value for the lth variable for k = 1, 2, . . . ,nobs; l = 1, 2, . . . ,m.
tdx
  the last dimension of the array x.
d[]
  the squared distances.
tdd
  the last dimension of the array dd.

Return values:
The function returns NAG error code or 0 if no error.
70: On entry, parameter equal had an illegal value.  On entry, parameter mode had an illegal value.
11: On entry, nvar must not be less than 1: nvar = _value_.  On entry, ng must not be less than 2: ng = _value_.
17: On entry, tdg = _value_ while nvar = _value_.  These parameters must satisfy tdg = nvar.  On entry, tdd = _value_ while ng = _value_.  These parameters must satisfy tdd = ng.
108: On entry, nobs = _value_ while mode = Nag SamplePoints.  These parameters must satisfy nobs = 1 w hen mode = Nag SamplePoints.
109: On entry, m = _value_ while nvar = _value_ and mode = Nag SamplePoints.  These parameters must satisfy m = nvar when mode = Nag SamplePoints.  On entry, tdx = _value_ while m = _value_ and mode = Nag SamplePoints.  These parameters must satisfy tdx = max(1,m) w hen mode = Nag SamplePoints.
502: The number of variables, nvar in the analysis = _value_, while number of variables included in the analysis via array isx = _value_.  Constraint: These two numbers must be the same when mode = Nag SamplePoints.
517: A diagonal element of R is zero when equal = Nag EqualCovar.
518: A diagonal element of R is zero for some j, w hen equal = Nag NotEqualCovar.
73: Memory allocation failed.
74: An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_discrim_mahaldist function.

Example:
    The data, taken from Aitchison and Dunsmore (1975), are concerned with
    the diagnosis of three 'types' of Cushing's syndrome. The variables are
    the logarithms of the urinary excretion rates (mg/24hr) of two steroid
    metabolites. Observations for a total of 21 patients are input and the
    group means and R matrices are computed by nag mv discrim (g03dac). A
    further six observations of unknown type are input, and the distances
    from the group means of the 21 patients of known type are computed under
    the assumption that the within-group variance-covariance matrices are
    not equal. These results are printed and indicate that the .rst four
    are close to one of the groups while observations 5 and 6 are some
    distance from any group.

void test_nag_mv_discrim_mahaldist()
{
    matrix d, gmean;
    d.SetSize(21,3);
    gmean.SetSize(3,2);
    matrix x = {{1.1314, 2.4596}, {1.0986, 0.2624}, {0.6419, -2.3026}, {1.3350, -3.2189},
    {1.4110, 0.0953}, {0.6419, -0.9163}, {2.1163, 0.0000}, {1.3350, -1.6094}, {1.3610, -0.5108},
    {2.0541, 0.1823}, {2.2083, -0.5108}, {2.7344, 1.2809}, {2.0412, 0.4700}, {1.8718, -0.9163},
    {1.7405, -0.9163}, {2.6101, 0.4700}, {2.3224, 1.8563}, {2.2192, 2.0669}, {2.2618, 1.1314},
    {3.9853, 0.9163}, {2.7600, 2.0281}};
    double det[3], gc[12];
    double	wt[21];
    double stat;
    double df;
    double sig;
    double *wtptr;
    int nobs, nvar;
    int isx[2], nig[3];
    int ing[21] = {1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3};
    int i, j, m = 2, n = 21;
    int ng = 3;
    int tdd = 3;
    int tdgmean = 2;
    int tdx = 2;
    char char_equal;
    char weight = 'U';
    Nag_GroupCovars equal;

    wtptr = NULL;
    nvar = 2;

    for (j = 0; j < m; ++j)
        isx[j] = 1;

    nag_mv_discrim(n, m, x, tdx, isx, nvar, ing, ng, wtptr, nig, gmean, tdgmean, det, gc,
                &stat, &df, &sig);

    nobs = 6;
    char_equal = 'U';

    x[0][0] = 1.6292;
    x[0][1] = -0.9163;

    x[1][0] = 2.5572;
    x[1][1] = 1.6094;

    x[2][0] = 2.5649;
    x[2][1] = -0.2231;

    x[3][0] = 0.9555;
    x[3][1] = -2.3026;

    x[4][0] = 3.4012;
    x[4][1] = -2.3026;

    x[5][0] = 3.0204;
    x[5][1] = -0.2231;

    if(char_equal == 'E')
        equal = Nag_EqualCovar;
    else if (char_equal == 'U')
        equal = Nag_NotEqualCovar;

    nag_mv_discrim_mahaldist(equal, Nag_SamplePoints, nvar, ng, gmean, tdgmean, gc,
                            nobs, m, isx, x, tdx, d, tdd);

    printf("\n Obs Distances\n\n");
    for (i = 0; i < nobs; ++i)
    {
        printf(" %3ld",i+1);
        for (j = 0; j < ng; ++j)
            printf("%10.3f",d[i][j]);
        printf("\n");
    }
}

    The Output is following:

    Obs Distances

   1     3.339     0.752    50.928
   2    20.777     5.656     0.060
   3    21.363     4.841    19.498
   4     0.718     6.280   124.732
   5    55.000    88.860    71.785
   6    36.170    15.785    15.749

Summary:
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_discrim_group

Function: nag_mv_discrim_group
Prototype:
int nag_mv_discrim_group(Nag_DiscrimMethod type,Nag_GroupCovars equal,Nag_PriorProbability priors,int nvar,int ng,int nig[],double gmean[],int tdg,double gc[],double det[],int nobs,int m,int isx[],double x[],int tdx,double prior[],double p[],int tdp,int iag[],Boolean atiq,double ati[])
Remarks: allocates observations to groups according to selected rules. It is intended for use after nag mv discrim (g03dac). Example The data, taken from Aitchison and Dunsmore (1975), are concerned with the diagnosis of three 'types' of Cushing's syndrome. The variables are the logarithms of the urinary excretion rates (mg/24hr) of two steroid metabolites. Observations for a total of 21 patients are input and the group means and R matrices are computed by nag mv discrim (g03dac). A further six observations of unknown type are input and allocations made using the predictive approach and under the assumption that the within-group covariance matrices are not equal. The posterior probabilities of group membership, q[j], and the atypicality index are printed along with the allocated group. The atypicality index shows that observations 5 and 6 do not seem to be typical of the three types present in the initial 21 observations. void test_nag_mv_discrim_group() { double stat; matrix ati, gmean, p; ati.SetSize(21,3); gmean.SetSize(3,2); p.SetSize(21,3); matrix x = {{1.1314, 2.4596}, {1.0986, 0.2624}, {0.6419, -2.3026}, {1.3350, -3.2189}, {1.4110, 0.0953}, {0.6419, -0.9163}, {2.1163, 0.0000}, {1.3350, -1.6094}, {1.3610, -0.5108}, {2.0541, 0.1823}, {2.2083, -0.5108}, {2.7344, 1.2809}, {2.0412, 0.4700}, {1.8718, -0.9163}, {1.7405, -0.9163}, {2.6101, 0.4700}, {2.3224, 1.8563}, {2.2192, 2.0669}, {2.2618, 1.1314}, {3.9853, 0.9163}, {2.7600, 2.0281}}; double det[3], gc[12]; double prior[3], wt[21]; double df; double sig; double *wtptr = NULL; int nobs, nvar; int i, j, m, n; int iag[21], isx[2], nig[3]; int ing[21] = {1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3}; int ng = 3; int tdgmean = 2; int tdp = 3; int tdx = 2; Boolean atiq = true; char char_type; char char_equal; char weight = 'U'; Nag_DiscrimMethod type; Nag_GroupCovars equal; n = 21; m = 2; nvar = 2; for (j = 0; j < m; ++j) isx[j] = 1; nag_mv_discrim(n, m, x, tdx, isx, nvar, ing, ng, wtptr, nig, gmean, tdgmean, det, gc, &stat, &df, &sig); nobs = 6; char_equal ='U'; char_type = 'P'; x[0][0] = 1.6292; x[0][1] = -0.9163; x[1][0] = 2.5572; x[1][1] = 1.6094; x[2][0] = 2.5649; x[2][1] = -0.2231; x[3][0] = 0.9555; x[3][1] = -2.3026; x[4][0] = 3.4012; x[4][1] = -2.3026; x[5][0] = 3.0204; x[5][1] = -0.2231; if (char_type == 'E') type = Nag_DiscrimEstimate; if(char_type == 'P') type = Nag_DiscrimPredict; if(char_equal == 'E') equal = Nag_EqualCovar; if (char_equal == 'U') equal = Nag_NotEqualCovar; nag_mv_discrim_group(type, equal, Nag_EqualPrior, nvar, ng, nig, gmean, tdgmean, gc, det, nobs, m, isx, x, tdx, prior, p, tdp, iag, atiq, ati); printf("\n"); printf(" Obs Posterior Allocated "); printf(" Atypicality "); printf("\n"); printf(" probabilities to group index "); printf("\n"); printf("\n"); for (i = 0; i < nobs; ++i) { printf(" %6ld ",i+1); for (j = 0; j < ng; ++j) printf("%6.3f",p[i][j]); printf(" %6ld ",iag[i]); for (j = 0; j < ng; ++j) printf("%6.3f",ati[i][j]); printf("\n"); } } The output is following: Obs Posterior Allocated Atypicality probabilities to group index 1 0.094 0.905 0.002 2 0.596 0.254 0.975 2 0.005 0.168 0.827 3 0.952 0.836 0.018 3 0.019 0.920 0.062 2 0.954 0.797 0.912 4 0.697 0.303 0.000 1 0.207 0.860 0.993 5 0.317 0.013 0.670 3 0.991 1.000 0.984 6 0.032 0.366 0.601 3 0.981 0.978 0.887
Parameters:
nvar
  the number of variables, p, in the variance-covariance matrices as specified to nag mv discrim (g03dac).
ng
  the number of groups.
nig[]
  the number of observations in each group training set.
gmean[]
  the jth row of gmean contains the means of the p variables for the jth group, for j = 1, 2,.., nj.
tdg
  the last dimension of the array gmean.
gc[]
  the first p(p + 1)/2 elements of gc should contain the upper triangular matrix R and the next ng blocks of p(p + 1)/2 elements should contain the upper triangular matrices Rj .
det[]
  if equal = Nag NotEqualCovar the logarithms of the determinants of the within-group variance-covariance matrices as returned by nag mv discrim (g03dac).
nobs
  the number of observations in x which are to be allocated.
m
  the number of variables in the data array x.
isx[]
  indicates if the lth variable in x is to be included in the distance calculations.
x[]
  contain the kth observation for the lth variable, for k = 1, 2, . . . ,nobs; l = 1, 2, . . . ,m.
tdx
  the last dimension of the array x.
prior[]
  if priors = Nag UserPrior, the prior probabilities for the ng groups.
p[]
  contains the posterior probability p[k][j] for allocating the kth observation to the jth group, for k = 1, 2, . . . ,nobs; j = 1, 2, . . ., ng.
tdp
  the last dimension of the array p and ati.
iag[]
  the groups to which the observations have been allocated.
atiq
  atiq must be TRUE if atypicality indices are required. .
ati[]
  the atypicality index for the kth observation with respect to the jth group,

  for k = 1, 2, . . . ,nobs; j = 1, 2, . . ., ng if atiq is TRUE,

Return values:
The function returns NAG error code or 0 if no error.
70:  On entry, parameter type had an illegal value.  On entry, parameter equal had an illegal value.  On entry, parameter priors had an illegal value.
11:  On entry, nvar must not be less than 1: nvar = _value_.  On entry, ng must not be less than 2: ng = _value_.  On entry, nobs must not be less than 1: nobs = _value_.
17:  On entry, m = _value_ while nvar = _value_.  These parameters must satisfy m = nvar.  On entry, tdx = _value_ while m = _value_.  These parameters must satisfy tdx = m.  On entry, tdp = _value_ while ng = _value_.  These parameters must satisfy tdp = ng.  On entry, tdg = _value_ while nvar = _value_.  These parameters must satisfy tdg = nvar.
501: The number of variables, nvar in the analysis = _value_, while number of variables included in the analysis via array isx = _value_.  Constraint: these two numbers must be the same.
111: On entry, nig[_value_] = _value_.  Constraint: nig[i - 1] > 0, i = 1, 2, . . . ,ng when equal = Nag EqualCovar.
112: On entry, nig[_value_] = _value_, nvar = _value_.  Constraint: nig[i - 1] > nvar, i = 1, 2, . . . ,ng when equal = Nag NotEqualCovar.
115: On entry, prior[_value_] = _value_.  Constraint: prior[j - 1] > 0, j=1,2,. . . ,ng when priors = Nag UserPrior.
522: On entry,summation of prior[j - 1] = _value_.  Constraint: summation of prior[j - 1] must be within 10 × machine precision of 1 when priors = Nag UserPrior.
521: On entry, summation of nig[j - 1] = _value_, ng = _value_, nvar = _value_.  Constraint: summation of nig[j - 1] > ng + nvar when equal = Nag EqualCovar.
517: A diagonal element of R is zero when equal = Nag EqualCovar.
518: A diagonal element of R is zero for some j, when equal = Nag NotEqualCovar
73:  Memory allocation failed.
74:  An internal error has occurred in this function.  Check the function call and array sizes. If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_discrim_group function.

Example:

Summary:
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_distance_mat

Function: nag_mv_distance_mat
Prototype:
int nag_mv_distance_mat(Nag_MatUpdate update,Nag_DistanceType dist,Nag_VarScaleType scale,int n,int m,double x[],int tdx,int isx[],double s[],double d[])
Remarks: computes a distance (dissimilarity) matrix.
Parameters:
n
  the number of observations.
m
  the total number of variables in array x.
x[]
  the value of the jth variable for the ith object, for i = 1, 2, . . . , n; j = 1, 2, . . . ,m.
tdx
  the last dimension of the array x.
isx[]
  indicates whether or not the jth variable in x is to be included in the distance computations.
s[]
  Input:if scale = Nag VarScaleUser and isx[j - 1] > 0 then s[j - 1] must contain the scaling for variable j, for j = 1, 2, . . . ,m.  Output:if scale = Nag VarScaleStd and isx[j - 1] > 0 then s[j - 1] contains the standard deviation of the variable in the jth column of x.
d[]
  Input:if update = Nag MatUp then d must contain the strictly lower triangle of the distance matrix D to be updated.  Output:the strictly lower triangle of the distance matrix D.

Return values:
The function returns NAG error code or 0 if no error.
70: On entry, parameter dist had an illegal value.  On entry, parameter update had an illegal value.  On entry, parameter scale had an illegal value.
11: On entry, n must not be less than 2: n = _value_.
12: On entry, m must not be less than or equal to 0: m = _value_.
17: On entry, tdx = _value_ while m = _value_.  These parameters must satisfy tdx = m.
111: On entry, isx[_value_] = _value_.  Constraint: isx[i - 1] > 0, for at least one i, i = 1, 2, . . . ,m.
115: On entry, d[_value_] = _value_.  Constraint: d[i - 1] = 0, i = 1, 2, . . . ,n*(n-1)/2 when update = Nag MatUp.  On entry, s[_value_] = _value_.  Constraint: s[j - 1] > 0, j = 1, 2, . . . ,m when scale = Nag VarScaleUser and isx[j - 1] > 0.
523: On entry, scale = Nag VarScaleRange or scale = Nag VarScaleStd, and x[i - 1][j - 1] = x[i][j - 1], for i = 1, 2, . . . , n - 1, for some j with isx[i - 1] > 0.
74: An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_distance_mat function.

Example:
    A data matrix of five observations and three variables is read in
    and a distance matrix is calculated from variables 2 and 3 using
    squared Euclidean distance with no scaling. This matrix is then printed.

void test_nag_mv_distance_mat()
{
    double d[45], s[10];
    matrix x;
    x.SetSize(10,10);
    int isx[10];
    int i, j, m, n;
    int tdx = 10;
    char char_scale;
    char char_update;
    char char_dist;
    Nag_MatUpdate update;
    Nag_DistanceType dist;
    Nag_VarScaleType scale;

    n = 5;
    m = 3;
    char_update = 'I';
    char_dist = 'S';
    char_scale = 'U';

    x[0][0] = 1.0;
    x[0][1] = 1.0;
    x[0][2] = 1.0;

    x[1][0] = 2.0;
    x[1][1] = 1.0;
    x[1][2] = 2.0;

    x[2][0] = 3.0;
    x[2][1] = 6.0;
    x[2][2] = 3.0;

    x[3][0] = 4.0;
    x[3][1] = 8.0;
    x[3][2] = 2.0;

    x[4][0] = 5.0;
    x[4][1] = 8.0;
    x[4][2] = 0.0;

    for (i = 0; i < m; ++i)
        isx[i] = 1;
    isx[0] = 0;
    for (i = 0; i < m; ++i)
        s[i] = 1.0;

    if (char_update == 'U')
        update = Nag_MatUp;
    if (char_update == 'I')
        update = Nag_NoMatUp;
    if (char_dist == 'A')
        dist = Nag_DistAbs;
    if (char_dist == 'E')
        dist = Nag_DistEuclid;
    if (char_dist == 'S')
        dist = Nag_DistSquared;
    if (char_scale == 'S')
        scale = Nag_VarScaleStd;
    if (char_scale == 'R')
        scale = Nag_VarScaleRange;
    if (char_scale == 'G')
        scale = Nag_VarScaleUser;
    if (char_scale == 'U')
        scale = Nag_NoVarScale;

    nag_mv_distance_mat(update, dist, scale, n, m, x, tdx, isx, s, d);

    printf("\n");
    printf(" Distance matrix ");
    printf("\n");
    printf("\n");
    printf(" %s\n","      1	   2    3	 4");
    printf("\n");
    for (i = 2; i <= n; ++i)
    {
        printf("%2ld ",i);
        for (j=(i-1)*(i-2)/2+1; j<=i*(i - 1)/2; ++j)
            printf("%5.2f ",d[j-1]);
        printf("\n");
    }
}

    The output is following:

    Distance matrix

      1 	   2 	  3 	 4

 2  1.00
 3 29.00 26.00
 4 50.00 49.00  5.00
 5 50.00 53.00 13.00  4.00

Summary:
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_hierar_cluster_analysis

Function: nag_mv_hierar_cluster_analysis
Prototype:
int nag_mv_hierar_cluster_analysis(Nag_ClusterMethod method,int n,double d[],int ilc[],int iuc[],double cd[],int iord[],double dord[])
Remarks: performs hierarchical cluster analysis.
Parameters:
n
  the number of objects.
d[]
  the strictly lower triangle of the distance matrix.
ilc[]
  contains the number, j, of the cluster merged with cluster k (see iuc), j < k, at step l for l = 1, 2, . n - 1.
iuc[]
  contains the number, k, of the cluster merged with cluster j, j < k, at step l for l = 1, 2, . . . , n - 1.
cd[]
  the distance djk, between clusters j and k, j < k, merged at step l for l = 1, 2, . . . , n - 1.
iord[]
  the objects in dendrogram order.
dord[]
  the clustering distances corresponding to the order in iord.

Return values:
The function returns NAG error code or 0 if no error.
70:  On entry, parameter method had an illegal value.
11:  On entry, n must not be less than 2: n = _value_.
115: On entry, d[_value_] = _value_.  Constraint: d[i - 1] = 0.0, i = 1, 2, . . . , n * (n - 1)/2.
524: A true dendrogram cannot be formed because the distances at which clusters have merged are not increasing for all steps, i.e., cd[i - 1] < cd[i - 2] for some i = 2, 3, . . . , n - 1.  This can occur for the Nag Centroid and Nag Median methods.
73:  Memory allocation failed.
74:  An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_hierar_cluster_analysis function.

Example:
    Data consisting of three variables on five objects are read in. Euclidean squared
    distances based on two variables are computed using nag mv distance mat (g03eac),
    the objects are clustered using nag mv hierar cluster analysis and the dendrogram
    computed using nag mv dendrogram (g03ehc).  The dendrogram is then printed.

void test_nag_mv_hierar_cluster_analysis()
{
    double cd[9], d[45], dord[10], s[10];
    matrix x;
    x.SetSize(10,10);
    double dmin_, dstep, ydist;
    int ilc[9], iord[10], isx[10], iuc[9];
    int nsym;
    int i, j;
    int m = 3, n = 5;
    int int_method;
    int tdx = 10;
    char name[10] = "ABCDE";
    char char_dist;
    char **c= NULL;
    char char_scale;
    char char_update;

    Nag_ClusterMethod method;
    Nag_MatUpdate update;
    Nag_DistanceType dist;
    Nag_VarScaleType scale;

    int_method = 5;

    if (int_method == 1)
        method = Nag_SingleLink;
    else if (int_method == 2)
        method = Nag_CompleteLink;
    else if (int_method == 3)
        method = Nag_GroupAverage;
    else if (int_method == 4)
        method = Nag_Centroid;
    else if (int_method == 5)
        method = Nag_Median;
    else
        method = Nag_MinVariance;

    char_update = 'I';

    if (char_update == 'U')
        update = Nag_MatUp;
    else
        update = Nag_NoMatUp;
    char_dist = 'S';
    if (char_dist == 'A')
        dist = Nag_DistAbs;
    else if (char_dist == 'E')
        dist = Nag_DistEuclid;
    else
        dist = Nag_DistSquared;

    char_scale = 'U';

    if (char_scale == 'S')
        scale = Nag_VarScaleStd;
    else if (char_scale == 'R')
        scale = Nag_VarScaleRange;
    else if(char_scale == 'G')
        scale = Nag_VarScaleUser;
    else
        scale = Nag_NoVarScale;

    x[0][0] = 1;
    x[0][1] = 5.0;
    x[0][2] = 2.0;

    x[1][0] = 2;
    x[1][1] = 1.0;
    x[1][2] = 1.0;

    x[2][0] = 3;
    x[2][1] = 4.0;
    x[2][2] = 3.0;

    x[3][0] = 4;
    x[3][1] = 1.0;
    x[3][2] = 2.0;

    x[4][0] = 5;
    x[4][1] = 5.0;
    x[4][2] = 0.0;

    for (i = 0; i < m; ++i)
        isx[i] = 1;
    isx[0] = 0;
    for (i = 0; i < m; ++i)
        s[i] = 1.0;

    nag_mv_distance_mat(update, dist, scale, n, m, x, tdx, isx, s, d);

    nag_mv_hierar_cluster_analysis(method, n, d, ilc, iuc, cd, iord, dord);

    printf("\n Distance Clusters Joined\n\n");
    for (i = 1; i <= n-1; ++i)
        printf("%10.3f %3c%3c\n",cd[i-1], name[ilc[i-1]-1], name[iuc[i-1]-1]);

    nsym = 20;
    dmin_ = 0.0;
    dstep = cd[n - 2] / (1.0 * nsym);

    nag_mv_dendrogram(Nag_DendSouth, n, dord, dmin_, dstep, nsym, &c);

    printf("\n");
    printf("Dendrogram ");
    printf("\n");
    printf("\n");
    ydist = cd[n - 2];
    for (i = 0; i < nsym; ++i)
    {
        if ((i+1) % 3 == 1)
        {
            printf("%10.3f%6s",ydist,"");
            printf("%s",c[i]);
            printf("\n");
        }
        else
        {
            printf("%16s%s","", c[i]);
            printf("\n");
        }
        ydist -= dstep;
    }
    printf("\n");
    printf("%14s","");
    for (i = 0; i < n; ++i)
        printf("%3c",name[iord[i]-1]);
    printf("\n");
    nag_mv_dend_free(&c);
}

    The output is as following:
 Distance Clusters Joined

     1.000   B  D
     2.000   A  C
     6.500   A  E
    14.125   A  B

Dendrogram

    14.125            -------
                      I     I
                      I     I
    12.006            I     I
                      I     I
                      I     I
     9.887            I     I
                      I     I
                      I     I
     7.769            I     I
                   ---*     I
                   I  I     I
     5.650         I  I     I
                   I  I     I
                   I  I     I
     3.531         I  I     I
                   I  I     I
                ---*  I     I
     1.412      I  I  I  ---*
                I  I  I  I  I

                A  C  E  B  D

Summary:
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_kmeans_cluster_analysis

Function: nag_mv_kmeans_cluster_analysis
Prototype:
int nag_mv_kmeans_cluster_analysis(int n,int m,double x[],int tdx,int isx[],int nvar,int k,double cmeans[],int tdc,double *wtptr,int inc[],int nic[],double css[],double csw[],int maxit)
Remarks: performs K-means cluster analysis.
Parameters:
n
  the number of observations.
m
  the number of variables in the array x.
x[]
  the value of jth variable for the ith object for i = 1, 2, . . ., n; j = 1, 2, . . . ,m.
tdx
  the last dimension of the array x.
isx[]
  indicates whether or not the jth variable is to be included in the analysis.
nvar
  the number of variables included in the sum of squares calculations.
k
  the number of clusters.
cmeans[]
  Input: contain the value of the jth variable for the ith initial cluster centre, for i = 1, 2, . . .,K; j = 1, 2, . . . , p.  Output: contains the value of the jth variable for the ith computed cluster centre, for i = 1, 2, . . .,K; j = 1, 2, . . . , p.
tdc
  the last dimension of the array cmeans.
wtptr
  contain the weights to be used in the analysis.
inc[]
  the cluster to which the ith object has been allocated, for i = 1, 2, . . . , n.
nic[]
  the number of objects in the ith cluster, for i = 1, 2, . . .,K. css[k]
css[]
  the within-cluster (weighted) sum of squares of the ith cluster, for i = 1, 2, . . .,K.
csw[]
  s the within-cluster sum of weights of the ith cluster, for i = 1, 2, . . .,K.
maxit
  the maximum number of iterations allowed in the analysis.

Return values:
The function returns NAG error code or 0 if no error.
11: On entry, n must not be less than 2: n = _value_.  On entry, k must not be less than 2: k = _value_.  On entry, nvar must not be less than 1: nvar = _value_.
12: On entry, maxit must not be less than or equal to 0: maxit = _value_.
17: On entry, m = _value_ while nvar = _value_.  These parameters must satisfy m = nvar.  On entry, tdx = _value_ while m = _value_.  These parameters must satisfy tdx = m.  On entry, tdc = _value_ while nvar = _value_.  These parameters must satisfy tdc = nvar.
501: The number of variables, nvar in the analysis = _value_, while number of variables included in the analysis via array isx = _value_.  Constraint: these two numbers must be the same.
500: On entry, wt[_value_] = _value_.  Constraint: When referenced, all elements of wt must be non-negative.
525: At least two elements of wt must be greater than zero.
526: At least one cluster is empty after the initial assignment.  Try a di.erent set of initial cluster centres in cmeans and also consider decreasing the value of k. The empty clusters may be found by examining the values in nic.
3: Too many iterations (_value_).  Convergence has not been achieved within the maximum number of iterations given by maxit.  Try increasing maxit and, if possible, use the returned values in cmeans as the initial cluster centres.
73: Memory allocation failed.
74: An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_kmeans_cluster_analysis function.

Example:
    The data consists of observations of .ve variables on twenty soils
    (Kendall and Stuart (1976)). The data is read in, the K-means
    clustering performed and the results printed.

void test_nag_mv_kmeans_cluster_analysis()
{
    double css[3], csw[3], wt[20];
    double *wtptr;
    int nvar, i, j, k;
    int m, n;
    int inc[20], isx[5], nic[5];
    int maxit;
    int tdc = 5;
    int tdx = 5;
    char weight;
    matrix x = {{77.3, 13.0, 9.7, 1.5, 6.4}, {82.5, 10.0, 7.5, 1.5, 6.5}, {66.9, 20.6, 12.5, 2.3, 7.0},
    {47.2, 33.8, 19.0, 2.8, 5.8}, {65.3, 20.5, 14.2, 1.9, 6.9}, {83.3, 10.0, 6.7, 2.2, 7.0},
    {81.6, 12.7, 5.7, 2.9, 6.7}, {47.8, 36.5, 15.7, 2.3, 7.2}, {48.6, 37.1, 14.3, 2.1, 7.2},
    {61.6, 25.5, 12.9, 1.9, 7.3}, {58.6, 26.5, 14.9, 2.4, 6.7}, {69.3, 22.3, 8.4, 4.0, 7.0},
    {61.8, 30.8, 7.4, 2.7, 6.4}, {67.7, 25.3, 7.0, 4.8, 7.3}, {57.2, 31.2, 11.6, 2.4, 6.5},
    {67.2, 22.7, 10.1, 3.3, 6.2}, {59.2, 31.2, 9.6, 2.4, 6.0}, {80.2, 13.2, 6.6, 2.0, 5.8},
    {82.2, 11.1, 6.7, 2.2, 7.2}, {69.7, 20.7, 9.6, 3.1, 5.9}};
    matrix cmeans = {{82.5, 10.0, 7.5, 1.5, 6.5}, {47.8, 36.5, 15.7, 2.3, 7.2}, {67.2, 22.7, 10.1, 3.3, 6.2}};

    weight = 'U';
    n = 20;
    m = 5;
    nvar = 5;
    k = 3;
    maxit = 10;

    for (j = 0; j < m; ++j)
        isx[j] = 1;

    nag_mv_kmeans_cluster_analysis(n, m, x, tdx, isx, nvar, k, cmeans, tdc, wtptr,
                                inc, nic, css, csw, maxit);

    printf("\nThe cluster each point belongs to\n");
    for (i = 0; i < n; ++i)
    {
        printf(" %6ld",inc[i]);
        if((i + 1) % 10 == 0)
            printf("\n");
    }

    printf("\n\nThe number of points in each cluster\n");
    for (i = 0; i < k; ++i)
        printf(" %6ld",nic[i]);
    printf("\n\nThe within-cluster sum of weights of each cluster\n");
    for (i = 0; i < k; ++i)
        printf(" %9.2f",csw[i]);
    printf("\n\nThe within-cluster sum of squares of each cluster\n\n");
    for (i = 0; i < k; ++i)
        printf(" %13.4f",css[i]);
    printf("\n\nThe final cluster centres\n");
    printf(" 1 2 3 4 5\n");
    for (i = 0; i < k; ++i)
    {
        printf(" %5ld ",i+1);
        for (j = 0; j < nvar; ++j)
            printf("%8.4f",cmeans[i][j]);
        printf("\n");
    }
}

    The output is following:

    The cluster each point belongs to
      1      1      3      2      3      1      1      2      2      3
      3      3      3      3      3      3      3      1      1      3

    The number of points in each cluster
      6      3     11

    The within-cluster sum of weights of each cluster
      6.00      3.00     11.00

    The within-cluster sum of squares of each cluster

      46.5717       20.3800      468.8964

    The final cluster centres
             1 		2 		3 		4 		5
     1  81.1833 11.6667  7.1500  2.0500  6.6000
     2  47.8667 35.8000 16.3333  2.4000  6.7333
     3  64.0455 25.2091 10.7455  2.8364  6.6545

Summary:
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_dendrogram

Function: nag_mv_dendrogram
Prototype:
int nag_mv_dendrogram(Nag_DendOrient orient,int n,double dord[],double dmin_,double dstep,int nsym,char ***c)
Remarks: produces a dendrogramfrom the results of nag mv hierar cluster analysis.
Parameters:
n
  the number of objects in the cluster analysis.
dord[]
  contains the distances, in dendrogram order, at which clustering takes place.
dmin_
  the clustering distance at which the dendrogram begins.
dstep
  the distance represented by one symbol of the dendrogram.
nsym
  the number of character positions used in the dendrogram. Hence the clustering distance at which the dendrogram terminates is given by dmin + nsym × dstep.
c
  a pointer to an array of character pointers, containing consecutive lines of the dendrogram.

Return values:
The function returns NAG error code or 0 if no error.
70: On entry, parameter orient had an illegal value.
11: On entry, n must not be less than 2: n = _value_.  On entry, nsym must not be less than 1: nsym = _value_.
5:  On entry, dmin must not be less than 0.0: dmin = _value_.
6:  On entry, dstep must not be less than or equal to 0.0: dstep = _value_.
527: On entry, n = _value_, dord[_value_] = _value_.  Constraint: dord[n-1] = dord[i - 1], i = 1, 2, . . . ,n-1.
74: An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_dendrogram function.

Example:
    Data consisting of three variables on five objects are read in. Euclidean squared
    distances are computed using nag mv distance mat (g03eac) and median clustering
    performed by nag mv hierar cluster analysis (g03ecc). nag mv dendrogram (g03ehc)
    is used to produce a dendrogram with orientation east and a dendrogram with
    orientation south. The two dendrograms are printed.  Note the use of
    nag mv dend free (g03xzc)to free the memory allocated internally to the
    character array pointed to by c.

void test_nag_mv_dendrogram()
{
    double cd[9], d[45], dord[10], s[10];
    matrix x;
    x.SetSize(10,10);
    double dmin_;
    double dstep;
    int ilc[9], iord[10], isx[10], iuc[9];
    int  nsym;
    int i, j;
    int m = 3, n = 5;
    int int_method;
    int tdx;
    char char_dist;
    char char_scale;
    char char_update;
    char **c = NULL;
    Nag_ClusterMethod method;
    Nag_MatUpdate update;
    Nag_DistanceType dist;
    Nag_VarScaleType scale;
    tdx = 10;

    x[0][0] = 1.0;
    x[0][1] = 1.0;
    x[0][2] = 1.0;

    x[1][0] = 2.0;
    x[1][1] = 1.0;
    x[1][2] = 2.0;

    x[2][0] = 3.0;
    x[2][1] = 6.0;
    x[2][2] = 3.0;

    x[3][0] = 4.0;
    x[3][1] = 8.0;
    x[3][2] = 2.0;

    x[4][0] = 5.0;
    x[4][1] = 8.0;
    x[4][2] = 0.0;

    for (i = 0; i < m; ++i)
        isx[i] = 1;
    isx[0] = 0;
    for (i = 0; i < m; ++i)
        s[i] = 1;

    int_method = 5;
    if (int_method == 1)
        method = Nag_SingleLink;
    else if (int_method == 2)
        method = Nag_CompleteLink;
    else if (int_method == 3)
        method = Nag_GroupAverage;
    else if (int_method == 4)
        method = Nag_Centroid;
    else if (int_method == 5)
        method = Nag_Median;
    else
        method = Nag_MinVariance;

    char_update = 'I';
    char_dist = 'S';
    char_scale = 'U';

    if (char_update == 'U')
        update = Nag_MatUp;
    else
        update = Nag_NoMatUp;
    if (char_dist == 'A')
        dist = Nag_DistAbs;
    else if (char_dist == 'E')
        dist = Nag_DistEuclid;
    else
        dist = Nag_DistSquared;

    if (char_scale == 'S')
        scale = Nag_VarScaleStd;
    else if (char_scale == 'R')
        scale = Nag_VarScaleRange;
    else if (char_scale == 'G')
        scale = Nag_VarScaleUser;
    else
        scale = Nag_NoVarScale;

    dmin_ = 0.0;
    dstep = 1.1;
    nsym = 40;

    nag_mv_distance_mat(update, dist, scale, n, m, x, tdx, isx, s, d);

    nag_mv_hierar_cluster_analysis(method, n, d, ilc, iuc, cd, iord, dord);

    nag_mv_dendrogram(Nag_DendEast, n, dord, dmin_, dstep, nsym, &c);

    printf("\nDendrogram, Orientation East\n\n");
    for (i=0; i< n; i++)
         printf("%s\n", c[i]);
    dmin_ = 0.0;
    dstep = 1.0;
    nsym = 40;
    nag_mv_dend_free(&c);
    nag_mv_dendrogram(Nag_DendSouth, n, dord, dmin_, dstep, nsym, &c);
    printf("\n\n Dendrogram, Orientation South\n\n");
    for (i=0; i< nsym; i++)
    {
        printf("%s\n", c[i]);
    }
    nag_mv_dend_free(&c);
}

    The output is as following:
Dendrogram, Orientation East

        ...............................(
       (                         .......
       (                        (    ...
       (........................(...(...

 Dendrogram, Orientation South

   ----------
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I        I
   I  ------*
   I  I     I
   I  I     I
   I  I     I
   I  I  ---*
   I  I  I  I
   I  I  I  I
---*  I  I  I
I  I  I  I  I

Summary:
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_cluster_indicator

Function: nag_mv_cluster_indicator
Prototype:
int nag_mv_cluster_indicator(int n,double cd[],int iord[],double dord[],int *k,double *dlevel,int ic[])
Remarks: computes a cluster indicator variable from the results of nag mv hierar cluster analysis (g03ecc).
Parameters:
n
  the number of objects.
cd[]
  the clustering distances in increasing order as returned by nag mv hierar cluster analysis (g03ecc).
iord[]
  the objects in the dendrogram order as returned by nag mv hierar cluster analysis
dord[]
  the clustering distances corresponding to the order in iord.
k
  Input: indicates if a speci.ed number of clusters is required.  Output: the number of clusters produced, k.
dlevel
  Input: if k = 0, then dlevel must contain the distance at which clusters are produced.  Output: the distance at which the required number of clusters are found if k > 0.

Return values:
The functions returns NAG error code, 0 if no error.
11: On entry, n must not be less than 2: n = _value_.
19: On entry, k = _value_ while n = _value_.  These parameters must satisfy k = n.
118: On entry, dlevel = _value_, k = _value_.  Constraint: k = 0 and dlevel > 0.0.
62: The sequence cd is not increasing: cd[_value_] = _value_, cd[_value_] = _value_.
122: On entry, dlevel = _value_, cd[_value_] = _value_.  Trivial solution returned.
120: On exit, k = 1 .  Trivial solution returned.
121: On exit, k = _value_, n = _value_.  Trivial solution returned.
116: Arrays cd and dord are not compatible.
528: The precise number of clusters requested is not possible because of tied clustering distances. The actual number of clusters produced is _value_.
74: An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_cluster_indicator function.

Example:
    Data consisting of three variables on five objects are input. Euclidean
    squared distances are computed using nag mv distance mat (g03eac) and
    median clustering performed using nag mv hierar cluster analysis (g03ecc).
    A dendrogram is produced by nag mv dendrogram (g03ehc) and printed.
    nag mv cluster indicator finds two clusters and the results are printed.

void test_nag_mv_cluster_indicator()
{
    double cd[9], d[45], dord[10], s[10];
    matrix x;
    x.SetSize(10, 10);
    double dmin_;
    double dstep, ydist;
    double dlevel;
    int ic[10], ilc[9], iord[10], isx[10],iuc[9];
    int nsym;
    int i, j, k;
    int m = 3, n = 5;
    int int_method;
    int tdx = 10;
    char **c = NULL;
    char name[10] = "ABCDE";
    char char_dist;
    char char_scale;
    char char_update;
    Nag_ClusterMethod method;
    Nag_MatUpdate update;
    Nag_DistanceType dist;
    Nag_VarScaleType scale;

    int_method = 5;
    if (int_method == 1)
        method = Nag_SingleLink;
    else if (int_method == 2)
        method = Nag_CompleteLink;
    else if (int_method == 3)
        method = Nag_GroupAverage;
    else if (int_method == 4)
        method = Nag_Centroid;
    else if (int_method == 5)
        method = Nag_Median;
    else
        method = Nag_MinVariance;
    char_update = 'I';
    if (char_update == 'U')
        update = Nag_MatUp;
    else
        update = Nag_NoMatUp;

    char_dist = 'S';
    if (char_dist == 'A')
        dist = Nag_DistAbs;
    else if (char_dist == 'E')
        dist = Nag_DistEuclid;
    else
        dist = Nag_DistSquared;
    char_scale = 'U';
    if (char_scale == 'S')
        scale = Nag_VarScaleStd;
    else if (char_scale == 'R')
        scale = Nag_VarScaleRange;
    else if (char_scale == 'G')
        scale = Nag_VarScaleUser;
    else
        scale = Nag_NoVarScale;

    x[0][0] = 1;
    x[0][1] = 5.0;
    x[0][2] = 2.0;

    x[1][0] = 2;
    x[1][1] = 1.0;
    x[1][2] = 1.0;

    x[2][0] = 3;
    x[2][1] = 4.0;
    x[2][2] = 3.0;

    x[3][0] = 4;
    x[3][1] = 1.0;
    x[3][2] = 2.0;

    x[4][0] = 5;
    x[4][1] = 5.0;
    x[4][2] = 0.0;

    for (i = 0; i < m; ++i)
        isx[i] = 1;
    isx[0] = 0;
    for (i = 0; i < m; ++i)
        s[i] = 1.0;

    k = 2;
    dlevel = 0.0;
    nag_mv_distance_mat(update, dist, scale, n, m, x, tdx, isx, s, d);

    nag_mv_hierar_cluster_analysis(method, n, d, ilc, iuc, cd, iord, dord);

    printf("\nDistance Clusters Joined\n\n");
    for (i = 0; i < n-1; ++i)
    {
        printf("%10.3f ",cd[i]);
        printf("%3c",name[ilc[i]-1]);
        printf("%3c",name[iuc[i]-1]);
        printf("\n");
    }

    nsym = 20;
    dmin_ = 0.0;
    dstep = cd[n - 2] / (1.0* nsym);
    nag_mv_dendrogram(Nag_DendSouth, n, dord, dmin_, dstep, nsym, &c);
    printf("\n");

    printf("Dendrogram ");
    printf("\n");
    printf("\n");
    ydist = cd[n - 2];
    for (i = 0; i < nsym; ++i)
    {
        if ((i+1) % 3 == 1)
        {
            printf("%10.3f%6s",ydist,"");
            printf("%s",c[i]);
            printf("\n");
        }
        else
        {
            printf("%16s%s","", c[i]);
            printf("\n");
        }
        ydist -= dstep;
    }
    printf("\n");
    printf("%14s","");
    for (i = 0; i < n; ++i)
    {
        printf("%3c",name[iord[i]-1]);
        printf("");
    }
    printf("\n");

    nag_mv_cluster_indicator(n, cd, iord, dord, &k, &dlevel, ic);

    printf("\n%s%2i%s\n\n","Allocation to ",k," clusters");
    printf("Object Cluster\n\n");
    for (i = 0; i < n; ++i)
    {
        printf("%5s%c%5s","",name[i],"");
        printf("%ld ",ic[i]);
        printf("\n");
    }
}

    The output is as following:
Distance Clusters Joined

     1.000   B  D
     2.000   A  C
     6.500   A  E
    14.125   A  B

Dendrogram

    14.125            -------
                      I     I
                      I     I
    12.006            I     I
                      I     I
                      I     I
     9.887            I     I
                      I     I
                      I     I
     7.769            I     I
                   ---*     I
                   I  I     I
     5.650         I  I     I
                   I  I     I
                   I  I     I
     3.531         I  I     I
                   I  I     I
                ---*  I     I
     1.412      I  I  I  ---*
                I  I  I  I  I

                A  C  E  B  D

Allocation to  2 clusters

Object Cluster

     A     1
     B     2
     C     1
     D     2
     E     1

Summary:
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_prin_coord_analysis

Function: nag_mv_prin_coord_analysis
Prototype:
int nag_mv_prin_coord_analysis(Nag_Eigenvalues roots,int n,double d[],int ndim,double x[],int tdx,double eval[])
Remarks: performs a principal coordinate analysis also known as classical metric scaling.
Parameters:
n
  the number of objects in the distance matrix.
d[]
  the lower triangle of the distance matrix D stored packed by rows.
ndim
  the number of dimensions used to represent the data.
x[]
  the ith row contains k coordinates for the ith point, i = 1, 2, . . . , n.
tdx
  the last dimension of the array x.
eval[]
  if roots = Nag AllEigVals, eval contains the n scaled eigenvalues of the matrix E.  If roots = Nag LargeEigVals, eval contains the largest k scaled eigenvalues of the matrix E.

Return values:
The function returns NAG error code or 0 if no error.
70:  On entry, parameter roots had an illegal value.
11:  On entry, ndim must not be less than 1: ndim = _value_.
18:  On entry, n = _value_ while ndim = _value_.  These parameters must satisfy n > ndim.
17:  On entry, tdx = _value_ while ndim = _value_.  These parameters must satisfy tdx = ndim.
115: On entry, d[_value_] = _value_.  Constraint: d[i - 1] = 0.0, i = 1, 2, . . . , n * (n - 1)/2.
529: There are fewer than ndim eigenvalues greater than zero.  Try a smaller number of dimensions (ndim) or use non-metric scaling (nag mv ordinal multidimscale (g03fcc)).
530: The computation of eigenvalues or eigenvectors has failed.
73:  Memory allocation failed.
74:  An internal error has occurred in this function. Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
successfully call of the  nag_mv_prin_coord_analysis function.

Example:
    The data, given by Krzanowski (1990), are dissimilarities between water
    vole populations in Europe.  The first two principal co-ordinates are
    computed by nag mv prin coord analysis.

void test_nag_mv_prin_coord_analysis()
{
    double e[14];
    matrix x;
    x.SetSize(14, 14);
    int ndim;
    int tdx=14;
    int i, j, n;
    int nn;
    char char_roots;
    Nag_Eigenvalues roots;
    double d[91] = {0.099, 0.033, 0.022, 0.183, 0.114, 0.042, 0.148, 0.224, 0.059, 0.068,
    0.198, 0.039, 0.053, 0.085, 0.051, 0.462, 0.266, 0.322, 0.435, 0.268, 0.025, 0.628,
    0.442, 0.444, 0.406, 0.240, 0.129, 0.014, 0.113, 0.070, 0.046, 0.047, 0.034, 0.002,
    0.106, 0.129, 0.173, 0.119, 0.162, 0.331, 0.177, 0.039, 0.089, 0.237, 0.071, 0.434,
    0.419, 0.339, 0.505, 0.469, 0.390, 0.315, 0.349, 0.151, 0.430, 0.762, 0.633, 0.781,
    0.700, 0.758, 0.625, 0.469, 0.618, 0.440, 0.538, 0.607, 0.530, 0.389, 0.482, 0.579,
    0.597, 0.498, 0.374, 0.562, 0.247, 0.383, 0.387, 0.084, 0.586, 0.435, 0.550, 0.530,
    0.552, 0.509, 0.369, 0.471, 0.234, 0.346, 0.456, 0.090, 0.038};

    n = 14;
    ndim = 2;
    char_roots = 'L';
    nn = n * (n - 1) / 2;

    if (char_roots == 'L')
        roots = Nag_LargeEigVals;
    else
        roots = Nag_AllEigVals;
    nag_mv_prin_coord_analysis(roots, n, d, ndim, x, tdx, e);
    printf("\nScaled Eigenvalues\n\n");
    if (char_roots == 'L')
    {
        for (i = 0; i < ndim; ++i)
            printf("%10.4f",e[i]);
    }
    else
    {
        for (i = 0; i < n; ++i)
            printf("%10.4f",e[i]);
        printf("\n");
    }
    printf("\nCo-ordinates\n\n");
    for (i = 0; i < n; ++i)
    {
        for (j = 0; j < ndim; ++j)
            printf("%10.4f",x[i][j]);
        printf("\n");
    }
}

    The output is as following:
Scaled Eigenvalues

    0.7871    0.2808
Co-ordinates

    0.2408    0.2337
    0.1137    0.1168
    0.2394    0.0760
    0.2129    0.0605
    0.2495   -0.0693
    0.1487   -0.0778
   -0.0514   -0.1623
    0.0115   -0.3446
   -0.0039    0.0059
    0.0386   -0.0089
   -0.0421   -0.0566
   -0.5158    0.0291
   -0.3180    0.1501
   -0.3238    0.0475

Summary:
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_dend_free

Function: nag_mv_dend_free
Prototype:
int nag_mv_dend_free(char ***c)
Remarks: frees Nag allocated memory for the dendrogram array in nag mv dendrogram (g03ehc).
Parameters:
c
  Input: a pointer to an array of character pointers to which memory has been allocated internally by nag mv dendrogram (g03ehc).  Output: The memory allocated to each of the pointers in the pointer array is freed and the pointers are set to NULL.

Return values:
The function returns NAG error code or 0 if no error.

Example:
        For an example of the use of nag mv dend free, please refer
        to the example program for nag mv dendrogram (g03ehc).

Summary:
Sample data:
Header file: OCN_g03.h
See also:


nag_mv_z_scores

Function: nag_mv_z_scores
Prototype:
int nag_mv_z_scores(int n,int m,double x[],int tdx,int nvar,int isx[],double s[],double e[],double z[],int tdz)
Remarks: produces standardized values (z-scores) for a data matrix.
Parameters:
n
  the number of observations in the data matrix.
m
  the number of variables in the data array x.
x[]
  contain the ith sample point for the jth variable x[i][j] , for i = 1, 2,. , n, j = 1, 2,  . ,m.
tdx
  the last dimension of the array x.
nvar
  the number of variables to be standardised.
isx[]
  indicates whether or not the observations on the jth variable are included in the matrix of standardized values.
s[]
  the scaling (standard deviation), sj, for the jth variable.
e[]
  the location shift (mean), µj, for the jth variable.
z[]
  the matrix of standardized values (z-scores).
tdz
  the last dimension of the array z

Return values:
The function returns NAG error code or 0 if no error.
11:  On entry, n must not be less than 1: n = _value_.  On entry, nvar must not be less than 1: nvar = _value_.
17:  On entry, m = _value_ while nvar = _value_.  These parameters must satisfy m = nvar.  On entry, tdx = _value_ while m = _value_.  These parameters must satisfy tdx = m.  On entry, tdz = _value_ while nvar = _value_.  These parameters must satisfy tdz = nvar.
501: The number of variables, nvar in the analysis = _value_, while number of variables included in the analysis via array isx = _value_.  Constraint: these two numbers must be the same.
123: On entry, isx[_value_] = _value_, s[_value_] = _value_.  Constraint: if isx[j - 1] =0 then s[j - 1] > 0.0, j=1,2,. . .,m.
74:  An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_mv_z_scores function.

Example:
    A 4 by 3 data matrix is input along with location and scaling values.
    The first and third columns are scaled and the results printed.

void test_nag_mv_z_scores()
{
    double e[3] = {14.75, 0.0, 1050.0}, s[3] = {2.50, 0.0, 420.0};
    matrix z;
    z.SetSize(4,3);
    matrix x = {{15.0, 0.0, 1500.0}, {12.0, 1.0, 1000.0}, {18.0, 2.0, 1200.0}, {14.0, 3.0, 500.0}};
    int nvar = 2;
    int isx[3];
    int i, j, m = 3, n = 4;
    int tdx = 3;
    int tdz = 3;

    for (j = 0; j < m; ++j)
        isx[j] = 1;
    isx[1] = 0;

    nag_mv_z_scores(n, m, x, tdx, nvar, isx, s, e, z, tdz);

    printf("\nStandardized Values\n\n");
    for (i = 0; i < n; ++i)
    {
        for (j = 0; j < nvar; ++j)
            printf("%8.3f",z[i][j]);
        printf("\n");
    }
}

    The output is following:

    Standardized Values

     0.100   1.071
      -1.100  -0.119
       1.300   0.357
    -0.300  -1.310

Summary:
Sample data:
Header file: OCN_g03.h
See also:


nag_anova_random

Function: nag_anova_random
Prototype:
int nag_anova_random(int n,const double y[],Nag_Blocks blocks,int iblock,int nt,int it[],double *gmean,double bmean[],double tmean[],double table[],double c[],int tdc,int irep[],double r[],double ef[],double tol,int irdf)
Remarks: computes the analysis of variance and treatment means and standard errors for a randomized block or completely randomized design
Parameters:
n
  the number of observations n
y[]
  the observations in the order as described by blocks and nt
iblock
  indicates the number of blocks
nt
  indicates the number of treatments
it[]
  indicates the treatments used
gmean
  the grand mean
bmean[]
  if blocks = Nag SerialBlocks or Nag ParallelBlocks, bmean contains the mean for the jth block
tmean[]
  contains the mean of the treatments
table[]
  the analysis of variance table
c[]
  the variance/covariance matrix of the treatment effects
tdc
  the second dimension of the array c
irep[]
  the treatment replications
r[]
  the residuals
ef[]
  the canonical efficiency factors
tol
  the tolerance value used to check for zero eigenvalues of the matrix.
irdf
  an adjustment to the degrees of freedom for the residual and total

Return values:
The function returns NAG error code, 0 if no error.
NE_BAD_PARAM(70): On entry, parameter blocks has illegal value.
NE_INT_ARG_LT(11): On entry, n must not be less than 2: n = _value_.  On entry, nt must not be less than 1: nt = _value_.  On entry, irdf must not be less than 0: irdf = _value_.
NE_REAL_ARG_LT(5): On entry, tol must not be less than 0.0: tol = _value_.
NE_INT(90): On entry, iblock = _value_.  Constraint: iblock = 2when blocks = Nag NoBlocks.  On entry, nt = _value_.  Constraint: nt = 2when blocks = Nag NoBlocks.
NE_2_INT_ARG_LT(17): On entry, tdc = _value_ while nt = _value_.  These parameters must satisfy tdc = nt.
NE_INT_2(91): On entry, n = _value_, iblock = _value_.  Constraint: when iblock = 2, n must be a multiple of iblock.
NE_INTARR(111): On entry, it[_value_] = _value_.  Constraint: 1 = it[i - 1] = nt, for i = 1, 2, . . . ,n.
NE_IT_ARRAY(533): No value of it[j - 1] = j for some j = 1, 2, . . . ,nt.
NE_ARRAY_CONSTANT(534): On entry, the elements of the array y are constant.
NE_G04BB_STDERR(535): A computed standard error is zero due to rounding errors.  This is an unlikely error exit.
NE_G04BB_DESIGN(537): The design is disconnected; the standard errors may not be valid. The design may be nested.
NE_G04BB_TREAT(538): The treatments are totally confounded with blocks, so the treatment sum of squares and degrees of freedom are zero. The analysis of variance table is not computed, except for block and total sums of squares and degrees of freedom.
NE_G04BB_CONV(536): The eigenvalue computation has failed to converge.  This is an unlikely error exit.
NE_G04BB_RES_DF(539): The residual degrees of freedom or the residual sum of squares are zero, columns 3, 4 and 5 of the analysis of variance table will not be computed and the matrix of standard errors and covariances, C, will not be scaled by s or the square of s.
NE_ALLOC_FAIL(73): Memory allocation failed.
successfully call of the nag_anova_random function.

Example:
    Assume "Data1" Worksheet contains 7 columns and 36 rows and it is double type, "Data2" Worksheet
    contains 2 columns and 36 rows and it is integer type. The first column contains 30 data in every
    worksheet. The result will write in rest columns.

    int n = 30, nt = 6, iblock = 10, tdc = 6, irdf = 0;
    double tol = 5e-6;
    double gmean;
    //Attach 7 Datasets to 7 columns of "Data1".
    Dataset dy("data1",0);
    Dataset dbmean("data1",1);
    Dataset dtmean("data1",2);
    Dataset dtable("data1",3);
    Dataset dc("data1",4);
    Dataset dr("data1",5);
    Dataset def("data1",6);
    //Attach 2 Datasets to 2 columns of "Data2".
    Dataset dit("data2",0);
    Dataset direp("data2",1);

    dy.SetSize(30);
    dbmean.SetSize(10);
    dtmean.SetSize(6);
    dtable.SetSize(20);
    dc.SetSize(36);
    dit.SetSize(30);
    dr.SetSize(30);
    def.SetSize(6);
    direp.SetSize(6);

    vector y = dy, bmean = dbmean, tmean = dtmean, table = dtable, c = dc, r = dr, ef = def;
    vector<int> it=dit, irep=direp;
    BOOL sucess = nag_anova_random(	n, y, Nag_SerialBlocks, iblock, nt, it, &gmean, bmean, tmean,
                                    table,  c, tdc, irep, r, ef, tol, irdf );
    //put the result to the Worksheet "data1" and Worksheet "data2".
    dbmean = bmean;
    dtmean = tmean;
    dtable = table;
    dc = c;
    dr = r;
    def = ef;
    dit = it;
    direp = irep;

    The data, given by John and Quenouille (1977), is for a balanced incomplete block design with
    10 blocks and 6 treatments and with 3 plots per block. The observations are the degree of pain
    experienced and the treatments are penicillin of different potency.

void test_nag_anova_random()
{

    double tmean[6];
    double table[20];
    double ef[6], r[30];
    double gmean;
    double tol = 5e-6;
    double bmean[10];
    double c[36];
    int irep[6];
    int irdf = 0;
    int i, j;
    int tdc = 6;
    int sucess;
    int n = 30, nt = 6, iblock = 10;
    double y[30] = {1.00, 5.00, 4.00, 5.00, 10.00, 6.00, 2.00, 9.00, 3.00, 4.00,
    8.00, 6.00, 2.00, 4.00, 7.00, 6.00, 7.00, 5.00, 5.00, 7.00, 2.00, 7.00,
    2.00, 4.00, 8.00, 4.00, 2.00, 10.00, 8.00, 7.00};
    int it[30] = {1, 2, 3, 1, 2, 4, 1, 3, 5, 1, 4, 6, 1, 5, 6, 2, 3, 6, 2, 4, 5,
    2, 5, 6, 3, 4, 5, 3, 4, 6};

    printf("the input data is following\n");
    printf("n = 30, nt = 6, iblock = 10\n");
    printf("y:  \n");
    for( i = 0; i < 30; i++)
    {
        printf("%f ",y[i]);
        if((i + 1) % 10 == 0)
        printf("\n");
    }
    printf("\nit:\n");
    for(i = 0; i < 30; i++)
    {
        printf("%d ",it[i]);
        if((i + 1) % 10 == 0)
        printf("\n");
    }

    sucess = nag_anova_random(n, y, Nag_SerialBlocks, iblock, nt, it, &gmean, bmean, tmean,
                                table,  c, tdc, irep, r, ef, tol, irdf);

    if(sucess == 0)
    {
        printf("the function is called sucessfully\n\n\n");
        printf("the results are the following:\n\n");
        printf("ANOVA table\n");
        printf(" Source       df       SS  	    MS     F         Prob\n");
        printf("Blocks     ");
        for(i = 0; i < 5; i++)
        {
            printf("%10.4f",table[i]);
        }
        printf("\nTreatments ");
        for(i = 5; i < 10; i++)
        {
            printf("%10.4f",table[i]);
        }

        printf("\nResidual   ");
        for(i = 11; i < 14; i++)
        {
            printf("%10.4f",table[i]);
        }

        printf("\nTotal      ");
        for(i = 15; i < 17; i++)
        {
            printf("%10.4f",table[i]);
        }

        printf("\n\nEfficency Fators     \n");
        for(i = 0; i < 6; i++)
            printf("%10.5f",ef[i]);
        printf("\n\nGrand Mean%10.5f\n",gmean);
        printf("\nTreatment Means\n");
        for(i = 0; i < 6; i++)
            printf("%10.5f", tmean[i]);
        printf("\nthe standard erros of difference between means\n");
        for( i = 1; i < 6; i++)
        {
            for( j = 0; j < i; j++)
                printf("%10.5f",c[i*6+j]);
            printf("\n");
        }

    }
    else
        printf("the function has not been called successfully");
}

    The output is following:

the input data is following
n = 30, nt = 6, iblock = 10
y:
1.000000 5.000000 4.000000 5.000000 10.000000 6.000000 2.000000 9.000000 3.000000 4.000000
8.000000 6.000000 2.000000 4.000000 7.000000 6.000000 7.000000 5.000000 5.000000 7.000000
2.000000 7.000000 2.000000 4.000000 8.000000 4.000000 2.000000 10.000000 8.000000 7.000000

it:
1 2 3 1 2 4 1 3 5 1
4 6 1 5 6 2 3 6 2 4
5 2 5 6 3 4 5 3 4 6
the function is called sucessfully

the results are the following:

ANOVA table
 Source       df       SS  	    MS     F         Prob
Blocks         9.0000   60.0000    6.6667    4.7872    0.0039
Treatments     5.0000  101.7778   20.3556   14.6170    0.0000
Residual      20.8889    1.3926    0.0000
Total         29.0000  182.6667

Efficency Fators
   0.00000   0.80000   0.80000   0.80000   0.80000   0.80000

Grand Mean   5.33333

Treatment Means
   2.50000   7.25000   8.08333   5.91667   2.91667   5.33333
the standard erros of difference between means
   0.83444
   0.83444   0.83444
   0.83444   0.83444   0.83444
   0.83444   0.83444   0.83444   0.83444
   0.83444   0.83444   0.83444   0.83444   0.83444

Summary: General block design or completely randomized design.
Sample data:
Header file: OCN_g04.h
See also:


nag_anova_row_col

Function: nag_anova_row_col
Prototype:
int nag_anova_row_col(int nrep,int nrow,int ncol,const double y[],int nt,const int it[],double * gmean,double tmean[],double table[],double c[],int tdc,int irep[],double rpmean[],double rmean[],double cmean[],double r[],double ef[],double tol,int irdf)
Remarks: computes the analysis of variance for a general row and column design together with the treatment means and standard error
Parameters:
nrep
  the number of replicates.
nrow
  the number of rows per replicate.
ncol
  the number of columns per replicate.
y[]
  the observation of the k column of the jth row of the ith replicate.
nt
  the number of treatments
it[]
  indicate which of the nt treatments unit i received, i = 1, 2, 3, ...., n.
gmean
  the grand mean.
tmean[]
  contains the (adjusted) mean for the lth treatment, l = 1, 2, 3, ..., nt.
table[]
  the analysis of variance table
c[]
  the variance/covariance matrix of the treatment effects.
tdc
  the second dimension of c.
irep[]
  the treatment replications.
rpmean[]
  contains the mean for the ith replicate, i = 1, 2, ..., b.
rmean[]
  contains the mean for the jth row, j= 1, 2, ..., r.
cmean[]
  contains the mean for the kth column, k = 1, 2, ..., c.
r[]
  contains the residuals
ef[]
  the canonical efficiancy factor
tol
  the tolerance value used to check for zero eigenvalue of the matrix Omega.
irdf
  an adjustment to  the degrees of freedom for the residual and total.

Return values:
The function returns NAG error code, 0 if no error.
NE_INT_ARG_LT(11):  On entry, nrep must not be less than 1: nrep = <value>.  On entry, nrow must not be less than 2: nrow = <value>.  On entry, ncol must not be less than 2: ncol = <value>.  On entry, nt must not be less than 1: nt = <value>.  On entry, irdf must not be less than 0: irdf = <value>.
NE_2_INT_ARG_LT(17):  On entry, tdc = <value> while nt = <value>.  These parameters must satisfy tdc >= nt.
NE_REAL_ARG_LT(5):   On entry, tol must not be less than 0: tol = <value>.
NE_ARRAY_CONS(58):  The contents of array it are not valid.  Constraint: if nt >= 2, 1 <= it[i] <= nt, i = 0, 1, 2, ..., nrep*nrow*ncol.  Constraint: some value of it = j for all j = 1, 2, ..., nt.
NE_ALLOC_FAIL(73):  Memory allocation failed.
NE_ARRAY_CONSTANT(534): On entry, the elements of the array y are constant.
NE_G04BC_ST_ERR(543): A computed standard error is zero due to rounding errors, or the eigenvalue computation failed to converge.  Both are unlikely errors.
NE_G04BC_REPS(544): The treatments are totally confounded with replicates, rows and columns, so the treatment sum of squares and degrees of freedom are zero.  The analysis of variance table is not computed, except for replicate, row, column, total sum of squares and degrees of freedom.
NE_G04BC_RESD(545): The residual degrees of freedom or the residual sum of squares are zero, columns 3, 4, and 5 of the analysis of variance table will not be computed and the matrix of standard errors and covariances, c, will not be scaled.
NE_G04BC_DISCON(546): The design is disconnected, the standard errors may not be valid.  The design may have a nested structure.
NE_INTERNAL_ERROR(74):  An internal error has occurred in this function.  Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully calll of the nag_anova_row_col function.

Example:
    The data for a 5 x 5 Latin square is inputted and the ANOVA and treatment means are computed and printed.

void test_nag_anova_row_col()
{
    double c[25], c_b20 = 1e-5, cmean[5], ef[5], r[25], gmean;
    double	rmean[5], rpmean[1], tmean[5], table[30];
    int irep[5], c_0 = 0, i, j;
    int nrep = 1, nt = 5, nrow = 5, ncol = 5;
    int sucess;
    double y[25] = {6.67, 7.15, 8.29, 8.95, 9.62, 5.40, 4.77, 5.40, 7.54, 6.93,
    7.32, 8.53, 8.50, 9.99, 9.68, 4.92, 5.00, 7.29, 7.85, 7.08, 4.88, 6.16,
    7.83, 5.38, 8.51};
    int it[25] = {5, 4, 1, 3, 2, 2, 5, 4, 1, 3, 3, 2, 5, 4, 1, 1, 3, 2, 5, 4, 4,
    1, 3, 2, 5};

    sucess = nag_anova_row_col(nrep, nrow, ncol, y, nt, it, &gmean, tmean, table, c,
                             nt, irep, rpmean, rmean, cmean, r, ef, c_b20, c_0);

    if(sucess == 0)
    {
        printf("\nthe input data are following\n");
        printf("nrep = 1, nt = 5, nrow = 5 , ncol = 5\n");
        printf("y:\n");
        for(i = 0; i < 25; i++)
        {
            printf("%3.2f   ",y[i]);
            if((i + 1) % 5 == 0)
                printf("\n");
        }

        printf("it:\n");
        for(i = 0; i < 25; i++)
        {
            printf("%d   ",it[i]);
            if((i + 1) % 5 == 0)
                printf("\n");
        }

        printf("\n\n\n");
        printf("ANOVA TABLE\n");

        printf("Rows       ");
        for(i = 5; i < 10; i++)
        {
            if(i == 5)
                printf("%3.0f   ", table[i]);
            else
                printf("%6.4f   ", table[i]);
        }

        printf("\nCloumns    ");
        for(i = 10; i < 15; i++)
        {
            if(i == 10)
                printf("%3.0f  ", table[i]);
            else
                printf("%6.4f  ", table[i]);
        }

        printf("\nTreatments ");
        for(i = 15; i <20; i++)
        {
            if(i == 15)
                printf("%3.0f  ", table[i]);
            else
                printf("%6.4f  ", table[i]);
        }

        printf("\nResidual   ");
        for(i = 20; i <23; i++)
        {
            if(i == 20)
                printf("%3.0f  ", table[i]);
            else
                printf("%6.4f  ", table[i]);
        }

        printf("\nTotal      ");
        for(i = 25; i < 27; i++)
        {
            if(i == 25)
                printf("%3.0f  ", table[i]);
            else
                printf("%6.4f  ", table[i]);
        }

        printf("\nTreatment means\n");
        for(i = 0; i < 5; i++)
            printf("%10.4f", tmean[i]);

        printf("\n\nS.E. of difference  (orthogonal design) = %10.4f\n", c[5]);
    }
    else
        printf("the function is not sucessfully called");
}

    The output is following:

the input data are following
nrep = 1, nt = 5, nrow = 5 , ncol = 5
y:
6.67   7.15   8.29   8.95   9.62
5.40   4.77   5.40   7.54   6.93
7.32   8.53   8.50   9.99   9.68
4.92   5.00   7.29   7.85   7.08
4.88   6.16   7.83   5.38   8.51
it:
5   4   1   3   2
2   5   4   1   3
3   2   5   4   1
1   3   2   5   4
4   1   3   2   5

ANOVA TABLE
Rows         4   29.4231   7.3558   9.0266   0.0013
Cloumns      4  22.9950  5.7487  7.0545  0.0037
Treatments   4  0.5423  0.1356  0.1664  0.9514
Residual    12  9.7788  0.8149
Total       24  62.7392
Treatment means
    7.3180    7.2440    7.2060    6.9000    7.2600

S.E. of difference  (orthogonal design) =     0.5709

Summary: Analysis of variance, general row and column design, treatment means and standard errors.
Sample data:
Header file: OCN_g04.h
See also:


nag_anova_factorial

Function: nag_anova_factorial
Prototype:
int nag_anova_factorial(int n,const double y[],int nfac,int lfac[],int nblock,int inter,int irdf,int *mterm,double **table,double **tmean,int *maxt,double **e,int **imean,double **semean,double **bmean,double r[])
Remarks: computes an analysis of variance table and treatment means for a complete factorial design.
Parameters:
n
  the number of observations
y[]
  the observations in standard order
nfac
  the number of factors
lfac[]
  the number of levels for the ith factor
nblock
  the number of blocks
inter
  the maximum number of factors in an interaction term, inter=0 or 1 if no interaction terms are computed.
irdf
  the adjustment to the residual and total degrees of freedom
mterm
  the number of terms in the analysis of variance table
table
  the table of analysis of variance.
tmean
  contains the treatment means.
maxt
  the number of treatment means that have been computed.
e
  contains the estimated effects in the same order as for the means in tmean.
imean
  indicates the position of the e.ect means in tmean.
semean
  the standard error of the di.erence between means corresponding to the ith treatment effect in the ANOVA table.
bmean
  bmean[0] contains the grand mean, bmean[1] up to bmean[nblock] contain the block means.
r[]
  the residuals

Return values:
The function returns NAG error code, 0 if no error.
NE_INT_ARG_LT(11):  On entry, n must not be less than 4: n = _value_.  On entry, nfac must not be less than 1: nfac = _value_.  On entry, nblock must not be less than 0: nblock = _value_.  On entry, inter must not be less than 0: inter = _value_.  On entry, irdf must not be less than 0: irdf = _value_.
NE_2_INT_ARG_GT(19):  On entry, inter = _value_ while nfac = _value_.  These parameters must satisfy inter = nfac.
NE_INTARR(111): On entry, lfac[_value_] = _value_.  Constraint: lfac[i - 1] = 2 for i = 1, 2, . . . ,nfac.
NE_INT_2(91):  On entry, nblock = _value_, n = _value_.  Constraint: n must be a multiple of nblock, when nblock > 1.
NE_PLOT_TREAT(541): The number of plots per block is not a multiple of the number of treatment combinations.
NE_ARRAY_CONSTANT(534): On entry, the elements of the array y are constant.
NE_G04CA_RES_DF(542): There are no degrees of freedom for the residual or the residual sum of squares is zero. In either case the standard errors and F-statistics cannot be computed.
NE_ALLOC_FAIL(73):  Memory allocation failed.
successfully call of the nag_anova_factorial function.

Example:
        These are the program data:
        The data, given by John and Quenouille (1977), is for the yield of turnips (54 observation) for a
        factorial experiment with two factors, the amount of phosphate with 6 levels and the amount of
        liming with 3 levels.  The design was replicated in 3 blocks.

        void test_nag_anova_factorial()
        {
            double r[54];
            double *bmean;
            double *e;
            double *semean;
            double *table;
            double *tmean;
            int c__27 = 27;
            int lfac[2] = {6, 3};
            int *imean;
            int mterm = 6;
            int nfac, irdf;
            int i, j, k, l, n;
            int num;
            int inter, nblock;
            int itotal, ntreat;
            n = 54;
            nblock = 3;
            nfac = 2;
            inter = 2;
            double y[54] = {274, 361, 253, 325, 317, 339, 326, 402, 336, 379, 345, 361,
            352, 334, 318, 339, 393, 358, 350, 340, 203, 397, 356, 298, 382, 376, 355,
            418, 387, 379, 432, 339, 293, 322, 417, 342, 82, 297, 133, 306, 352, 361,
            220, 333, 270, 388, 379, 274, 336, 307, 266, 389, 333, 353};

            irdf = 0;
            nag_anova_factorial(n, y, nfac, lfac, nblock, inter, irdf, &mterm, &table, &tmean,
                &c__27, &e, &imean, &semean, &bmean, r);

            itotal = mterm;
            printf("\n ANOVA table\n\n");
            printf(" Source     df      SS      MS      F     	Prob\n\n");
            k = 0;
            if (nblock > 1)
            {
                ++k;
                printf("%s"," Blocks ");
                for (j = 1; j <= 5; ++j)
                printf("%10.2f  ",table[((1)-1) * ( 5) + ((j)-1)]);
                printf("\n");
            }
            ntreat = mterm - 2 - k;
            for (i = 1; i <= ntreat; ++i)
            {
                printf("%s%2i  "," Effect ",i);
                for (j = 1; j <= 5; ++j)
                printf("%10.2f ",table[((k+i)-1) * ( 5) + ((j)-1)]);
                printf("\n");
            }
            printf("%s "," Residual ");
            for (j = 1; j <= 3; ++j)
                printf("%10.2f  ",table[((mterm -1)-1) * ( 5) + ((j)-1)]);
            printf("\n");
            printf("%s "," Total ");
            for (j = 1; j <= 2; ++j)
                printf("%10.2f  ",table[((mterm)-1) * ( 5) + ((j)-1)]);

            printf("\n");
            printf("\n");
            printf(" Treatment Means and Standard Errors ");
            printf("\n");
            printf("\n");
            k = 0;
            for (i = 0; i < ntreat; ++i)
            {
                l = imean[i];
                printf("%s%2i"," Effect ",i+1);
                printf("\n");
                printf("\n");
                num=1;
                for (j = k; j < l; ++j)
                {
                    printf("%10.2f ",tmean[j]);
                    if(num % 8 == 0)
                        printf("\n");
                    num++;
                }
                printf("\n");
                printf("\n%s%10.2f\n\n"," SE of difference in means = ",semean[i]);
                k = l;
            }

            nag_anova_factorial_free(&table, &tmean, &e, &imean, &semean, &bmean);
        }

        The output is following:

        ANOVA TABLE
        Source             df           SS         MS         F        Prob

        Blocks           2.0000    30118.7778     15059.3889  7.6848   0.0018
        Effect0          5.00      73008.17       14601.63    7.45     0.00
        Effect1          2.00      21596.33       10798.17    5.51     0.01
        Effect2          10.00     31191.67       3119.17     1.59     0.15
        Residual         34.0000   66627.8889     1959.6438
        total            53.0000   222542.8333

        Treatment Means and Standard Errors

        Effect 1
            254.78,   339.00,   333.33,   367.78,   330.78,   360.67

        SE of difference inm means =      20.87

        Effect 2
            334.28,	  353.78,   305.11

        SE of difference inm means =      14.76

        Effect 3
            235.33,   332.67,   196.33,   342.67,   341.67,   332.67,   309.33,   370.33,
            320.33,   395.00,   370.33,   338.00,   373.33,   326.67,   292.33,   350.00,
            381.00,   351.00

        SE of difference in means =      36.14

Summary: Complete factorial design
Sample data:
Header file: OCN_g04.h
See also:


nag_anova_factorial_free

Function: nag_anova_factorial_free
Prototype:
void nag_anova_factorial_free(double **table,double **tmean,double **e,int **imean,double **semean,double **bmean)
Remarks: frees Nag allocated memory to some parameters in nag anova factorial
Parameters:
Input:pointers to which memory has been allocated internally in nag anova factorial(g04cac).
Output:The memory allocated to each of the pointers is freed and the pointers are set to NULL.

Return values:
None

Example:
        These are the program data:
        The data, given by John and Quenouille (1977), is for the yield of turnips (54 observation) for a
        factorial experiment with two factors, the amount of phosphate with 6 levels and the amount of
        liming with 3 levels.  The design was replicated in 3 blocks.

        void test_nag_anova_factorial()
        {
            double r[54];
            double *bmean;
            double *e;
            double *semean;
            double *table;
            double *tmean;
            int c__27 = 27;
            int lfac[2] = {6, 3};
            int *imean;
            int mterm = 6;
            int nfac, irdf;
            int i, j, k, l, n;
            int num;
            int inter, nblock;
            int itotal, ntreat;
            n = 54;
            nblock = 3;
            nfac = 2;
            inter = 2;
            double y[54] = {274, 361, 253, 325, 317, 339, 326, 402, 336, 379, 345, 361,
            352, 334, 318, 339, 393, 358, 350, 340, 203, 397, 356, 298, 382, 376, 355,
            418, 387, 379, 432, 339, 293, 322, 417, 342, 82, 297, 133, 306, 352, 361,
            220, 333, 270, 388, 379, 274, 336, 307, 266, 389, 333, 353};

            irdf = 0;
            nag_anova_factorial(n, y, nfac, lfac, nblock, inter, irdf, &mterm, &table, &tmean,
                &c__27, &e, &imean, &semean, &bmean, r);

            itotal = mterm;
            printf("\n ANOVA table\n\n");
            printf(" Source     df      SS      MS      F     	Prob\n\n");
            k = 0;
            if (nblock > 1)
            {
                ++k;
                printf("%s"," Blocks ");
                for (j = 1; j <= 5; ++j)
                printf("%10.2f  ",table[((1)-1) * ( 5) + ((j)-1)]);
                printf("\n");
            }
            ntreat = mterm - 2 - k;
            for (i = 1; i <= ntreat; ++i)
            {
                printf("%s%2i  "," Effect ",i);
                for (j = 1; j <= 5; ++j)
                printf("%10.2f ",table[((k+i)-1) * ( 5) + ((j)-1)]);
                printf("\n");
            }
            printf("%s "," Residual ");
            for (j = 1; j <= 3; ++j)
                printf("%10.2f  ",table[((mterm -1)-1) * ( 5) + ((j)-1)]);
            printf("\n");
            printf("%s "," Total ");
            for (j = 1; j <= 2; ++j)
                printf("%10.2f  ",table[((mterm)-1) * ( 5) + ((j)-1)]);

            printf("\n");
            printf("\n");
            printf(" Treatment Means and Standard Errors ");
            printf("\n");
            printf("\n");
            k = 0;
            for (i = 0; i < ntreat; ++i)
            {
                l = imean[i];
                printf("%s%2i"," Effect ",i+1);
                printf("\n");
                printf("\n");
                num=1;
                for (j = k; j < l; ++j)
                {
                    printf("%10.2f ",tmean[j]);
                    if(num % 8 == 0)
                        printf("\n");
                    num++;
                }
                printf("\n");
                printf("\n%s%10.2f\n\n"," SE of difference in means = ",semean[i]);
                k = l;
            }

            nag_anova_factorial_free(&table, &tmean, &e, &imean, &semean, &bmean);
        }

        The output is following:

        ANOVA TABLE
        Source             df           SS         MS         F        Prob

        Blocks           2.0000    30118.7778     15059.3889  7.6848   0.0018
        Effect0          5.00      73008.17       14601.63    7.45     0.00
        Effect1          2.00      21596.33       10798.17    5.51     0.01
        Effect2          10.00     31191.67       3119.17     1.59     0.15
        Residual         34.0000   66627.8889     1959.6438
        total            53.0000   222542.8333

        Treatment Means and Standard Errors

        Effect 1
            254.78,   339.00,   333.33,   367.78,   330.78,   360.67

        SE of difference inm means =      20.87

        Effect 2
            334.28,	  353.78,   305.11

        SE of difference inm means =      14.76

        Effect 3
            235.33,   332.67,   196.33,   342.67,   341.67,   332.67,   309.33,   370.33,
            320.33,   395.00,   370.33,   338.00,   373.33,   326.67,   292.33,   350.00,
            381.00,   351.00

        SE of difference in means =      36.14

Summary:
Sample data:
Header file: OCN_g04.h
See also:


nag_anova_confid_interval

Function: nag_anova_confid_interval
Prototype:
int nag_anova_confid_interval(Nag_IntervalType type,int nt,const double tmean[],double rdf,const double c[],int ldc,double clevel,double cil[],double ciu[],int isig[])
Remarks: Computes confidence intervals for differences between means computed by nag_anova_random (g04bbc) or nag_anova_row_col (g04bcc).
Parameters:
nt
  the number of treatment means
tmean[]
  the treatment means
rdf
  the residual degrees of freedom
c[]
  the standard errors of the differences between the means
ldc
  the second dimension of the array c
clevel
  the confidence level for the computed intervals
cil[]
  lower limit to the confidence interval
ciu[]
  upper limit to the confidence interval
isig[]
  difference between the ith and jth means in tmean is significant.

Return values:
The function returns NAG error code, 0 if no error.
NE_INT_ARG_LT(11): On entry, nt must not be less than 2: nt = <value>.
NE_2_INT_ARG_LT(17): On entry, tdc = <value> while nt = <value>.
NE_REAL_ARG_LT(5):  On entry, rdf must not be less than 1: rdf = <value>.
NE_REAL(96): On entry, clevel <value>.  Constrant 0 < clevel < 1.
NE_BAD_PARAM(70): On entry, parameter type has an illegal value.
NE_ALLOC_FAIL(73): Memory allocation failed.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function.  Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
NE_STUDENTIZED_STAT(549): There has been a failure in the computation of the studentized range statistic.  Try using a smaller value of clevel.
successfully call of the nag_anova_confid_interval function.

Example:
    In the example taken from Winer (1970) a completely randomised design with unequal treatment replication
    is analysed using nag_anova_random (g04bbc) and the confidence intervals are computed by
    nag_anova_confid_interval using the Tukey-Kramer method.  There are 26 observations and 4 treatments.

void test_nag_anova_confid_interval()
{
    double bmean[1], tol = 5e-6;
    double irdf = 0;
    int nbolck = 1;
    double c[16];
    double cil[6];
    double ciu[6];
    double clevel = 0.95;
    double ef[4];
    double gmean;
    double r[26];
    double rdf;
    matrix table;
    table.SetSize(4,5);
    double tmean[4];
    int i, ij;
    int irep[4];
    int isig[6];
    int success;
    int j, n, nblock, nt;
    Nag_IntervalType type_enum;
    n = 26;
    nt = 4;
    type_enum = Nag_TukeyInterval;
    double y[26] = {3, 2, 4, 3, 1, 5, 7, 8, 4, 10, 6, 3, 2, 1, 2, 4, 2, 3,
    1, 10, 12, 8, 5, 12, 10, 9};
    int it[26] = {1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 3, 3 ,3, 3, 3, 3, 3, 3, 4,
    4, 4, 4, 4, 4, 4};

    success =nag_anova_random(n, y, Nag_NoBlocks, nblock, nt, it, &gmean, bmean, tmean,
                                table,  c, nt, irep, r, ef, tol, irdf);

    printf("the input data and results as folowing\n\n");
    printf("input data:\n");
    printf("n = %d,  nt = %d  clevel = %4.2f type_enum = Nag_TurkeyInterval\n",n, nt, clevel);
    printf("\ny:\n");
    for(i = 0; i < 26; i ++)
      {
          printf("%2.0f,",y[i]);
          if( (i + 1) % 13 == 0)
          {
              printf("\n");
          }
      }

    printf("\nit:\n");
    for(i = 0; i < 26; i ++)
      {
          printf("%d, ",it[i]);
          if( (i + 1) % 13 == 0)
          {
              printf("\n");
          }
      }

    if(success ==0)
    {
        printf("the results:\n");
        printf("\nANOVA TABLE");
        printf("\n\n  Source       df    SS         MS       F      Prob\n");
        printf("Treatments   ");
        for(j = 0; j < 5; j++)
        {
            if( j == 0)
            printf("%3.0f", table[1][j]);
            else if(j == 1 || j == 2)
            printf("%10.1f", table[1][j]);
            else if(j == 3)
            printf("%10.3f", table[1][j]);
            else
            printf("%9.4f", table[1][j]);
        }

        printf("\nResidual    ");
        for(j = 0; j < 3; j++)
        {  	if( j == 0)
            printf(" %3.0f", table[2][j]);
            if(j == 1 || j == 2)
            printf("%10.1f", table[2][j]);
        }

        printf("\nTotal   ");
        for(j = 0; j < 2; j++)
        {  	if( j == 0)
            printf("     %3.0f", table[3][j]);
            if(j == 1 || j == 2)
            printf("%10.1f", table[3][j]);
        }

        printf("\nTreat means  ");
        for(i = 0; i < nt; i ++)
          {
              printf("%6.3f  ",tmean[i]);
              if( (i + 1) % 8 == 0)
              {
                  printf("\n");
              }
          }

        printf("\nSimiltanous Confidence Intervals\n");
        rdf  = table[2][0];
        success = nag_anova_confid_interval(type_enum, nt, tmean, rdf, c, nt, clevel, cil, ciu, isig);
        if(success ==0)
        {
            ij = 0;
            for(i = 1; i <= nt; i++)
            {
                for(j = 1; j <= i-1; j++)
                {
                    ++ij;
                    printf("%2ld%2ld %10.3f  %10.3f", i, j, cil[ij - 1], ciu[ij - 1]);
                    if(isig[ij - 1] == 1)
                    printf("    *");
                    if(isig[ij - 1] == 2)
                    printf("\0");
                    if(isig[ij - 1] == 0)
                    printf("  ");
                    printf("\n");
                }
            }
        }
        else
        printf("there is some problem with function nag_anova_random");
    }
    else
    printf("there is some problem with the function of nag_anova_random");
}

    The output is following:
the input data and results as folowing

input data:
n = 26,  nt = 4  clevel = 0.95 type_enum = Nag_TurkeyInterval

y:
 3, 2, 4, 3, 1, 5, 7, 8, 4,10, 6, 3, 2,
 1, 2, 4, 2, 3, 1,10,12, 8, 5,12,10, 9,

it:
1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 3, 3,
3, 3, 3, 3, 3, 3, 4, 4, 4, 4, 4, 4, 4,
the results:

ANOVA TABLE

  Source       df    SS         MS       F      Prob
Treatments     3     239.9      80.0    24.029   0.0000
Residual      22      73.2       3.3
Total         25     313.1
Treat means   3.000   7.000   2.250   9.429
Similtanous Confidence Intervals
 2 1      0.933       7.067    *
 3 1     -3.486       1.986
 3 2     -7.638      -1.862    *
 4 1      3.610       9.247    *
 4 2     -0.538       5.395
 4 3      4.557       9.800    *

Summary: Computes confidence intervals for differences between means computed
Sample data:
Header file: OCN_g04.h
See also:


nag_dummy_vars

Function: nag_dummy_vars
Prototype:
int nag_dummy_vars(Nag_DummyType type,int n,int levels,const int ifact[],double x[],int tdx,const double v[],double rep[])
Remarks: Computes orthogonal polynomials or dummy variables for factor/classification variable.
Parameters:
n
  the number of observations for which the dummy variables are to be computed.
levels
  the number of levels of the factor.
ifact[]
  the n values of the factor.
x[]
  the n by k matrix of dummy variables
tdx
  the second dimension of the array x
v[]
  If type equal Nag_Poly, the k distinct values of the underlying variable for which

  the orthogonal polynomial is to be computed.  If type not equal Nag_Poly, v is not reference.
rep[]
  contains the number of replications for each level

Return values:
The function returns NAG error code, 0 if no error.
NE_INT_ARG_LT(11): On entry, levels must not be les than 2: levels = <value>.
NE_2_INT_ARG_LT(17): On entry, n = <value> while levels = <value>.  These parameters must satisfy n >= levels.  On entry, tdx = <value> while levels = <value>.  These parameters must satisfy tdx >= levels.  On entry, tdx = <value> while levels - 1 = <value>.  These parameters must satisfy tdx >= levels - 1.
NE_BAD_PARAM(70): On entry, parameter type has an illegal value.
NE_ALLOC_FAIL(73): Memory allocation failed.
NE_ARRAY_CONS(58): The contents of array v are not valid.  Constraint: all values of v must be distinct.
NE_INT_ARRAY_CONS(103): On entry, factor{0] = <value>.  Constraint: 1 <= factor[0] <= levels.
NE_G04EA_LEVELS(547): All levels are not represented in array factor.
NE_G04EA_ORTHO_POLY(548): An orthogonal polynomial has all values zero.  This will be due to some values of v being close together.  This can only occur if type = Nag_Poly.
NE_INTERNAL_ERROR(74): An internal error has occurred in this function.  Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_dummy_vars function.

Example:
    Data are read in from an experiment with four treatments and three observations per
    treatment with the treatment coded as a factor, nag_dummy_vars is used to compute the
    required dummy variables and the model is then fitted by nag_regsn_mult_linear (g02dac).

void test_nag_dummy_vars()
{
    double b[5], cov[15], p[35], h[12], q[72], rep[4], res[12];
    double df, rss, tol;
    double se[5], v[1], com_ar[45], wt[12], x[48];
    double *wtptr;
    int i, j, ip, irank, levels, m, n, tdq, tdx;
    int isx[4];
    Boolean  svd;
    Nag_DummyType dum_type;
    Nag_IncludeMean  mean_enum;
    int success, success1;
    int ifact[12] = {1, 4, 2, 3, 4, 2, 4, 1, 3, 1, 3, 2};
    double y[12] = {33.63, 39.62, 38.18, 41.46, 38.02, 35.83, 35.99, 36.58, 42.92,
    37.80, 40.43, 37.89};

    n = 12;
    levels = 4;
    dum_type = Nag_AllLevels;
    mean_enum = Nag_MeanInclude;
    tdx = levels;
    wtptr = NULL;

    printf("the input data are as following\n");
    printf("n = 12,	levels = 4,	dum_type = Nag_AllLevels,\nmean_enum = Nag_MeanInclude");
    printf(",tdx = levels, wtptr = NULL, tol = 1e-5, ip = 5, m = 4, tdx =4 \n");
    printf("ifact:\n");
    for(i = 0; i < n; i ++)
    {
        printf("%5.2f,  ",ifact[i]);
        if((i + 1) % 6 == 0)
            printf("\n");
    }

    printf("y:\n");
    for(i = 0; i < n; i ++)
    {
        printf("%5.2f,  ",y[i]);
        if((i + 1) % 6 == 0)
            printf("\n");
    }

    success = nag_dummy_vars(dum_type, n, levels, ifact, x, tdx, v, rep);

    if(success == 0)
    {
        m = tdx;
        ip = m;
        if(mean_enum == Nag_MeanInclude)
            ip++;
        for(j = 0; j < m ; j++)
            isx[j] = 1;
        tol = 1e-5;
        tdq = 6;
        success1 = nag_regsn_mult_linear(mean_enum, n, x, tdx, m, isx, ip, y, wtptr, &rss, &df, b,
                                        se, cov, res, h, q, tdq, &svd, &irank, p, tol, com_ar);

        if(success1 ==0)
        {
            if(svd)
                printf("Model not full of rank, rank = %4ld\n\n ", irank);
            printf("Residual sum of squares = %12.4e\n", rss);
            printf("Degrees of freedom = %3.1f\n\n", df);
            printf("Variable Parameter estimate Standard error\n\n");
            for (j=0; j<ip; j++)
                printf("%6ld%20.4e%20.4e\n", j+1, b[j], se[j]);
            printf("\n");
        }
        else
            printf("what the hell  is the pronblem with nag_regsn_mult_linear");
    }
    else
        printf("what the hell  is the pronblem with the fuction");

}

    The output is following:

the input data are as following
n = 12,	levels = 4,	dum_type = Nag_AllLevels,
mean_enum = Nag_MeanInclude,tdx = levels, wtptr = NULL, tol = 1e-5, ip = 5, m = 4, tdx =4
ifact:
 0.00,   0.00,   0.00,   0.00,   0.00,   0.00,
 0.00,   0.00,   0.00,   0.00,   0.00,   0.00,
y:
33.63,  39.62,  38.18,  41.46,  38.02,  35.83,
35.99,  36.58,  42.92,  37.80,  40.43,  37.89,
Model not full of rank, rank =    4

 Residual sum of squares =  2.2227e+001
Degrees of freedom = 8.0

Variable Parameter estimate Standard error

     1         3.0557e+001         3.8494e-001
     2         5.4467e+000         8.3896e-001
     3         6.7433e+000         8.3896e-001
     4         1.1047e+001         8.3896e-001
     5         7.3200e+000         8.3896e-001

Summary: Computes orthogonal polynomials or dummy variables for factor/classification variable.
Sample data:
Header file: OCN_g04.h
See also:


nag_sign_test

Function: nag_sign_test
Prototype:
int nag_sign_test(int n,const double x[],const double y[],int *s,double *p,int *non_tied)
Remarks: Performs the Sign test on two related samples of size n.
Parameters:
n
  Size of each sample, n>=1.
x[]
  Sample1 dataset, x[i-1] and y[i-1] must be set to ith pair of data values.
y[]
  Sample2 dataset, x[i-1] and y[i-1] must be set to ith pair of data values.
s
  The returned Sign test statistic, S.
p
  The returned lower tail probability, p, corresponding to S.
non_tied
  The returned number of non-tied pairs.

Return values:
This function returns NAG error code, 0 if no error.
successfully call of the nag_sign_test function.

Example:

void test_nag_sign_test()
{
    double p;
    double x[] = {4, 4, 5, 5, 3, 2, 5, 3, 1, 5, 5, 5, 4, 5, 5, 5, 5};
    int i, s, n, non_tied;
    n= 17;
    double y[] ={2,3,3, 3,3,3,3,3,2,3,2,2,5,2,5,3,1};

    printf("\nSign Test\n\n");
    printf("Data values\n\n");
    for(i =0; i < n; i++)
        printf("%3.0f",x[i]);
    printf("\n");
    for(i =0; i < n; i++)
        printf("%3.0f",y[i]);
    printf("\n");
    nag_sign_test(n, x, y, &s, &p, &non_tied);
    printf("Test statistic    %5ld\n",s);
    printf("Observations      %5ld\n",non_tied);
    printf("Lower tail prob   %5.3f\n",p);
}

The output is following:

Sign Test

Data values

  4  4  5  5  3  2  5  3  1  5  5  5  4  5  5  5  5
  2  3  3  3  3  3  3  3  2  3  2  2  5  2  5  3  1
Test statistic        3
Observations         14
Lower tail prob   0.029

Summary: Sign test on two paired samples.
Sample data:
Header file: OCN_g08.h
See also:


nag_median_test

Function: nag_median_test
Prototype:
int nag_median_test(int n1,const double x[],int n2,const double y[],int *above,int *below,double *p)
Remarks: Performs the Median test on two independent samples of possibly unequal size.
Parameters:
n1
  The size of the first sample, n1>=1.
x[]
  The data values of the first sample.
n2
  The size of the second sample, n2>=1.
y[]
  The data values of the second sample.
above
  The returned number of scores in the first sample which lie above the pooled median.
below
  The returned number of scores in the first sample which lie below the pooled median.
p
  The returned tail probability, p, corresponding to the observed dichotomy of the two samples.

Return values:
The function returns NAG error code, 0 if no error.

Example:

void test_nag_median_test()
{
    double p;
    int i, above, below, n1, n2;
    n1 = 16;
    n2 = 23;
    double x[] = {13, 6, 12, 7, 12, 7, 10, 7, 10, 7, 10, 7, 10, 8, 9, 8}
    double y[] = {17, 6, 16, 8, 15, 8, 15, 10, 15, 10, 14, 10, 14, 11, 14, 11,
                    13, 12, 13, 12, 13, 12, 12}
    printf("\nMedian test\n\n");
    printf("Data values\n\n");
    printf("   Group1   ");
    for(i = 0; i < n1; i++)
    {
        printf("%4.0f",x[i]);
        if((i+1) % 8 == 0)
            printf("\n            ");
    }

    printf("\n   Group2   ");
    for(i = 0; i < n2; i++)
    {
        printf("%4.0f",y[i]);
        if((i+1) % 8 == 0)
            printf("\n            ");
    }
    nag_median_test(n1, x, n2, y, &above, &below, &p);
    printf("\n");
    printf("%6ld  scores below madian in group 1\n",above);
    printf("%6ld  scores below madian in group 2\n",below);
    printf("\n		Significance   %8.5f\n", p);
}

The output is following:

Median test

Data values

   Group1     13   6  12   7  12   7  10   7
              10   7  10   7  10   8   9   8

   Group2     17   6  16   8  15   8  15  10
              15  10  14  10  14  11  14  11
              13  12  13  12  13  12  12
    13  scores below madian in group 1
     6  scores below madian in group 2

        Significance    0.00088

Summary: Median test on two samples of unequal size.
Sample data:
Header file: OCN_g08.h
See also:


nag_friedman_test

Function: nag_friedman_test
Prototype:
int nag_friedman_test(int k,int n,const double x[],int tdx,double *fr,double *p)
Remarks: Performs the Friedman two-way analysis of variance by ranks on k related samples of size n.
Parameters:
k
  The number of samples, k>1.
n
  The size of each sample, n>=1.
x[]
  Two dimension array (x[k,tdx]) of all data points where x[i-1][j-1] is the jth observation in sample i.
tdx
  The first dimension of x as declared in the function from which nag_friedman_test is called.
fr
  The returned value of the Friedman test statistic, FR.
p
  The returned approximate significance, p, of the Friedman test statistic.

Return values:
NAG error code, 0 if no error.

Example:

void test_nag_friedman_test()
{
    double fr, sig;
    int i, ix, j, k, n;
    n = 18;
    k =3;
    ix =k;
    double x[] = {1, 2, 1, 1, 3, 2, 3, 1, 3, 3, 2, 2, 3, 2, 2.5, 3, 3, 2,
                  3, 3, 3, 2, 1, 3, 2, 3, 1, 1, 3, 3, 2, 3, 2.5, 2, 2, 3,
                  2, 1, 2, 3, 2, 1, 1, 2, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1};
    printf("\nData values\n");
    printf("\n	Group   Group    Group\n");
    printf("\n 	1      2       3\n");
    for(j = 0; j < 18; j++)
    {
        for( i =0; i < 3; i++)
            printf("%7.1f", x[i * 18 + j]);
        printf("\n");
    }

    nag_friedman_test(k, n, x, n, &fr, &sig);
    printf("\n");
    printf("Test statistics       %6.3f\n", fr);
    printf("Degrees of freedom    %6ld\n", k-1);
    printf("Significance          %6.3f\n ", sig);
}

The output is following:

    Data values

    Group   Group    Group

     1      2       3
    1.0    3.0    2.0
    2.0    3.0    1.0
    1.0    3.0    2.0
    1.0    2.0    3.0
    3.0    1.0    2.0
    2.0    3.0    1.0
    3.0    2.0    1.0
    1.0    3.0    2.0
    3.0    1.0    2.0
    3.0    1.0    2.0
    2.0    3.0    1.0
    2.0    3.0    1.0
    3.0    2.0    1.0
    2.0    3.0    1.0
    2.5    2.5    1.0
    3.0    2.0    1.0
    3.0    2.0    1.0
    2.0    3.0    1.0

Test statistics        8.583
Degrees of freedom         2
Significance           0.014

Summary: Friedman two-way analysis of variance on k matched samples.
Sample data:
Header file: OCN_g08.h
See also:


nag_kruskal_wallis_test

Function: nag_kruskal_wallis_test
Prototype:
int nag_kruskal_wallis_test(int k,const int l[],const double x[],int lx,double *h,double *p)
Remarks: Performs the Kruskal-Wallis one-way analysis of variance by ranks on k independent samples of possibly unequal sizes.
Parameters:
k
  The number of samples, k>=2.
l[]
  l[i-1] contains the number of observations in sample i.
x[]
  Contains the observations in k groups each having l[i-1] scores (e.g. The first l[0] elements contain the scores in the first group, etc.)
lx
  The total number of observations, N.
h
  The returned value of the Kruskal-Wallis statistic, H.
p
  The returned approximate significance, p, of the Kruskal-Wallis test statistic.

Return values:
This function returns NAG error code, 0 if no error.
successfully call of the nag_kruskal_wallis_test function.

Example:

void test_nag_kruskal_wallis_test()
{
    double h, p;
    int count, i, ii, k, lx, nhi, ni, nlo;
    k =5;
    int l[] = { 5, 8, 6, 8, 8};
    printf("\n");
    printf("Kruskal_wallis test");
    printf("\n");
    printf("Data values \n\n");
    printf("  Group    Observations\n");

    lx = 0;
    for(i =0; i < 5; i++)
        lx +=l[i];
    double x[] = {23, 27, 26, 19, 30, 29, 25, 33, 36, 32,
                  28, 30, 31, 38, 31, 28, 35, 33, 36, 30,
                  27, 28, 22, 33, 34, 34, 32, 31, 33, 31,
                  28, 30, 24, 29, 30};
    nlo = 1;
    for(i = 0; i < k; i++)
    {
        ni = l[i];
        nhi = nlo + ni - 1;
        printf("%5ld     ", i);
        count = 1;
        for( ii = nlo; ii <= nhi; ii++)
        {
            printf("%4.0f",x[ii -1]);
            if(count % 10 == 0)
                printf("\n");
        }
        nlo +=ni;
        printf("\n");
    }

    nag_kruskal_wallis_test(k, l, x, lx, &h, &p);
    printf("\n");
    printf("\n");
    printf("Test statistics       %6.3f\n",h);
    printf("Degrees of freedom    %6ld\n", k-1);
    printf("Significance          %6.3f\n ",p);
}

The output is following:
Data values

  Group    Observations
    0       23  27  26  19  30
    1       29  25  33  36  32  28  30  31
    2       38  31  28  35  33  36
    3       30  27  28  22  33  34  34  32
    4       31  33  31  28  30  24  29  30

Test statistics       10.537
Degrees of freedom         4
Significance           0.032

Summary: Kruskal-Wallis one-way analysis of variance on k samples of unequal size.
Sample data:
Header file: OCN_g08.h
See also:


nag_wilcoxon_test

Function: nag_wilcoxon_test
Prototype:
int nag_wilcoxon_test(int n,const double x[],double median,Nag_TailProbability tail,Nag_IncSignZeros zeros,double *rs,double *rsnor,double *p,int *nz1)
Remarks: Performs the Wilcoxon one-sample (matched pairs) signed rank test.
Parameters:
n
  The size of the sample, n>=1.
x[]
  The sample observations.
median
  The median test value.
tail
  Indicates choice of tail probability and hence the alternative hypothesis.
zeros
  Indicates whether or not to include cases where di=0.0 when ranking di's.
rs
  The returned Wilcoxon rank sum statistic, W, being the sum of the positive ranks.
rsnor
  The returned approximate Normal test statistic, z.
p
  The returned tail probability, p, as specified by the parameter tail.
nz1
  The returned number of non-zero di's.

Return values:
This function returns NAG error code, 0 if no error.

Example:

void test_nag_wilcoxon_test()
{
    double median, p, w, z;
    int i, n, non_zero;
    double data[8];
    n = 8;
    double x[] = {82, 69, 73, 43, 58, 56, 76, 65};
    double y[] = {63, 42, 74, 37, 51, 43, 80, 62};
    printf("\n\n");
    printf("Wilcoxon one sample signed ranks test");
    printf("\n");
    printf("Data Values \n");
    for(i = 0; i < n; i++)
        printf("%5.1f", x[i]);
    printf("\n");
    for(i = 0; i < n; i++)
        printf("%5.1f", y[i]);
    printf("\n");
    for(i = 0; i < n; i++)
        data[i] = x[i] -y[i];
    median = 0.0;
    nag_wilcoxon_test(n, data, median, Nag_TwoTail, Nag_IncSignZerosN, &w, &z, &p, &non_zero);
    printf("\n");
    printf("Test statistics              =%8.4f\n",w);
    printf("Normalized  test statistics  =%8.4f\n", z);
    printf("Degree of freedom            =%8ld\n",non_zero);
    printf("Two tail probability         =%8.4f\n", p);
}

The output is following:

Wilcoxon one sample signed ranks test
Data Values
 82.0 69.0 73.0 43.0 58.0 56.0 76.0 65.0
 63.0 42.0 74.0 37.0 51.0 43.0 80.0 62.0

Test statistics              = 32.0000
Normalized  test statistics  =  1.8904
Degree of freedom            =       8
Two tail probability         =  0.0547

Summary: Performs the Wilcoxon one-sample (matched pairs) signed rank test.
Sample data:
Header file: OCN_g08.h
See also:


nag_mann_whitney

Function: nag_mann_whitney
Prototype:
int nag_mann_whitney(int n1,const double x[],int n2,const double y[],Nag_TailProbability tail,Nag_CompProb exact,double *u,double *z,double *p)
Remarks: Performs the Mann-Whitney U test on two independent samples of possibly unequal size and calculates the exact probability for the Mann-Whitney rank sum test statistic for the case where there are either ties or no ties in the samples pooled together.
Parameters:
n1
  The number of non-tied pairs, n1>=1.
x[]
  The first vector of observations.
n2
  The size of the second sample, n2>=1.
y[]
  The second vector of observations.
tail
  Indicates choice of tail probability and hence the alternative hypothesis.
exact
  Indicates if exact probability is to be computed
u
  The returned Mann-Whitney rank sum statistic, U.
z
  The returned approximate Normal test statistic, z.
p
  The returned exact tail probability, p, as specified by the parameter tail.

Return values:
This function returns NAG error code, 0 if no error.

Example:

void test_nag_mann_whitney()
{
    double p, u, z;
    int i , n1, n2;
    n1 = 16;
    n2 = 23;
    printf("Sample size of group 1 = %5ld\n", n1);
    printf("Sample size of group 2 = %5ld\n", n2);
    double x[] ={13.0, 6.0, 12.0, 7.0, 12.0, 7.0, 10.0, 7.0,
                10.0, 7.0, 16.0, 7.0, 10.0, 8.0, 9.0, 8.0};
    printf("Mann-Whitney U test\n");
    printf("Data values\n");
    printf("	Group 1	");
    for(i = 0; i < n1; i++)
    {
        printf("%5.1f",x[i]);
        if((i + 1) % 8 == 0)
            printf("\n");
    }

    double y[] ={17.0, 6.0, 10.0, 8.0, 15.0, 8.0, 15.0, 10.0, 15.0, 10.0, 14.0, 10.0,
                14.0, 11.0, 14.0, 11.0, 13.0, 12.0, 13.0, 12.0,13.0,12.0, 12.0};
    printf("\n	Group 2	");
    for(i = 0; i < n2; i++)
    {
        printf("%5.1f",y[i]);
        if((i + 1) % 8 == 0)
            printf("\n");
    }
    nag_mann_whitney(n1, x, n2, y, Nag_LowerTail, Nag_CompProbApprox, &u, &z, &p);
    printf("\n\n");
    printf("Test statistics              =%8.4f\n", u);
    printf("Normal statistics 		 =%8.4f\n", z);
    printf("Approximate tail probability =%8.4f\n", p);
    nag_mann_whitney(n1, x, n2, y, Nag_LowerTail, Nag_CompProbExact, &u, &z, &p);
    printf("Exact tail probability       =%8.4f\n",p);
}

The output is following:

Sample size of group 1 =    16
Sample size of group 2 =    23
Mann-Whitney U test
Data values
    Group 1	 13.0  6.0 12.0  7.0 12.0  7.0 10.0  7.0
 10.0  7.0 16.0  7.0 10.0  8.0  9.0  8.0

    Group 2	 17.0  6.0 10.0  8.0 15.0  8.0 15.0 10.0
 15.0 10.0 14.0 10.0 14.0 11.0 14.0 11.0
 13.0 12.0 13.0 12.0 13.0 12.0 12.0

Test statistics              = 86.0000
Normal statistics 		 = -2.8039
Approximate tail probability =  0.0025
Exact tail probability       =  0.0020

Summary: Performs the Mann-Whitney U test on two independent samples.
Sample data:
Header file: OCN_g08.h
See also:


nag_1_sample_ks_test

Function: nag_1_sample_ks_test
Prototype:
int nag_1_sample_ks_test(int n,const double x[],Nag_Distributions dist,double par[],Nag_ParaEstimates estima,Nag_TestStatistics dtype,double *d,double *z,double *p)
Remarks: Performs the one-sample Kolmogorov-Smirnov test for standard distributions.
Parameters:
n
  The number of observations in the sample, n >= 3.
x[]
  The sample observations x1, x2,...,xN.
dist
  The NAG distribution.
par[]
  Contains the known values of the parameter(s) of the null distribution.
estima
  Specifies whether the values of the parameter(s) are known or estimated from data.
dtype
  The test statistic to be calculated...i.e. the choice of alternative hypothesis.
d
  The Kolmogorov-Smirnov test statistic.
z
  A standardized value, Z, of the test statistic, D, without correction for continuity.
p
  The probability, P, associated with the observerd value of D.

Return values:
This function returns NAG error code, 0 if no error.

Example:

void test_nag_1_sample_ks_test()
{
    double d, p, z;
    int i, n, np, ntype;
    Nag_TestStatistics ntype_enum;
    n = 30;

    double x[] ={0.01, 0.30, 0.20, 0.90, 1.20, 0.09, 1.30, 0.18, 0.90, 0.48,
                 1.98, 0.03, 0.50, 0.70, 0.07, 0.60, 0.95, 1.00, 0.31, 1.45,
                 1.04, 1.25, 0.15, 0.75, 0.85, 0.22, 1.56, 0.81, 0.57, 0.55};

    np =2;
    double par[] ={0.0, 2.0};
    ntype = 1;
    ntype_enum = Nag_TestStatisticsDAbs;

    nag_1_sample_ks_test(n, x, Nag_Uniform, par, Nag_ParaSupplied, ntype_enum, &d, &z, &p);
    printf("Test against uniform distribution on(0, 2)\n");
    printf("Test statistics  D    	= %8.4f\n", d);
    printf("Z statistic    			= %8.4f\n", z);
    printf("Tail probability		= %8.4f\n", p);

    np = 2;
    par[0] = 0.0;
    par[1] = 1.0;
    ntype = 1;
    ntype_enum = Nag_TestStatisticsDAbs;
    nag_1_sample_ks_test(n, x, Nag_Normal, par, Nag_ParaEstimated, ntype_enum, &d, &z, &p);
    printf("Test  against Normal distribution with parameters estimated from the data\n");
    printf("\n");
    printf("Mean = %6.4f	and varaince = %6.4f\n",par[0],par[1]);
    printf("Test statistics  D    	= %8.4f\n", d);
    printf("Z statistic    			= %8.4f\n", z);
    printf("Tail probability		= %8.4f\n", p);

}

The output is following:

Test against uniform distribution on(0, 2)
Test statistics  D    	=   0.2800
Z statistic    			=   1.5336
Tail probability		=   0.0143
Test  against Normal distribution with parameters estimated from the data

Mean = 0.6967	and varaince = 0.2564
Test statistics  D    	=   0.1108
Z statistic    			=   0.6068
Tail probability		=   0.8925

Summary: Performs the one-sample Kolmogorov-Smirnov test for standard distributions.
Sample data:
Header file: OCN_g08.h
See also:


nag_2_sample_ks_test

Function: nag_2_sample_ks_test
Prototype:
int nag_2_sample_ks_test(int n1,const double x[],int n2,const double y[],Nag_TestStatistics ntype,double *d,double *z,double *p)
Remarks: Performs the two-sample Kolmogorov-Smirnov distribution test.
Parameters:
n1
  The number of observations in the first sample, n1>=1.
x[]
  The observations from the first sample.
n2
  The number of observations in the second sample, n2>=1.
y[]
  The observations from the second sample.
ntype
  The statistic to be computed or the choice of alternative hypothesis.
d
  The  returned Kolmogorov-Smirnov test statistic according to the value of ntype.
z
  The returned standardized value, Z, of the test statistic, D, without correction for continuity.
p
  The returned tail probability, P, associated with the observerd value of D.

Return values:
This function returns NAG error code, 0 if no error.

Example:

void test_nag_2_sample_ks_test()
{
    double d, enda, endb, p, z;
    int init, i, m, n, ntype;
    Nag_TestStatistics ntype_enum;
    double x[100], y[50];
    n = 100;
    m = 50;
    init = 0;
    enda = 0.0;
    endb = 2.0;
    for(i = 0; i < n; i++)
        x[i] = enda +(endb -enda) * ran(init);
    enda = 0.25;
    endb = 2.25;
    for(i = 0; i < m; i++)
        y[i] = enda + (endb - enda) * ran(init);

    ntype = 1;
    ntype_enum = Nag_TestStatisticsDAbs;
    nag_2_sample_ks_test(n, x, m, y, ntype_enum, &d, &z, &p);
    printf("Test statistics  D    	= %8.4f\n", d);
    printf("Z statistic    			= %8.4f\n", z);
    printf("Tail probability		= %8.4f\n", p);
}

Summary: Performs the two-sample Kolmogorov-Smirnov distribution test.
Sample data:
Header file: OCN_g08.h
See also:


nag_chi_sq_goodness_of_fit_test

Function: nag_chi_sq_goodness_of_fit_test
Prototype:
int nag_chi_sq_goodness_of_fit_test(int k2,const int ifreq[],const double cint[],Nag_Distributions dist,const double par[],int iparam,const double prob[],double *chisq,double *p,int *ndf,double eval[],double chisqi[])
Remarks: Performs the chi^2 goodness of fit test, for standard continuous distributions and for data with a chosen number of class intervals.
Parameters:
k2
  The number of clsses, k2, into which the data is divided.
ifreq[]
  ifreq[i-1] specifies the frequency of the ith class.
cint[]
  cint[i-1] specifies the upper boundary value for the ith class, cint[i]=0..
dist
  The NAG distribution.
par[]
  par[] specifies the parameters of the distribution being tested.
iparam
  The number of estimated parameters of the distribution.
prob[]
  If the user is supplying the probability distribution then prob[i-1] contains the probability that X lies in the ith class.
chisq
  The returned test statistic, chi^2, for the chi^2 goodness of fit test.
p
  The returned upper tail probability from the chi^2 distribution.
ndf
  Returns the degrees of freedom associated with test.
eval[]
  eval[i-1] contains the returned expected frequency for the ith class.
chisqi[]
  chisqi[i-1] contains the returned contribution from the ith class to the test statistic.

Return values:
This function returns NAG error code, 0 if no error.

Example:

void test_nag_chi_sq_goodness_of_fit_test()
{
    double chisq, p, xmax, xmin;
    int i, iclass, init, n, nclass, ndf, npest;
    double x[100], cint[4], par[2] = {0.0, 1.0};
    int ifreq[5];
    double chisqi[5], eval[5], prob[5];
    Nag_Distributions cdist_enum;
    Nag_ClassBoundary class_enum;

    n = 100;
    nclass = 5;
    cdist_enum = Nag_Uniform;

    npest = 0;
    init = 0;
    for( i =0; i < n; i++)
        x[i] = 	ran(init);		//generate random variable from 0 to 1.
    iclass = 1;
    cint[0] = par[0] + (par[1] -par[0])/nclass;
    for(i = 1; i < nclass -1; i++)
        cint[i] = cint[i - 1] +(par[1] - par[0])/nclass;

    class_enum = Nag_ClassBoundaryUser;
    nag_frequency_table(n, x, nclass, class_enum, cint, ifreq, &xmin, &xmax);
    nag_chi_sq_goodness_of_fit_test(nclass, ifreq, cint, cdist_enum, par, npest, prob, &chisq, &p, &ndf, eval, chisqi);
    printf("\n");
    printf("Chi-squared test statistic			=%10.4f\n",chisq);
    printf("Degrees of freedom.					=%5ld\n", ndf);
    printf("Significance level					=%10.4f\n", p);
    printf("\n");
    printf("The contributions to the test statistic are :");
    for(i = 0; i < nclass; i++)
        printf("%10.4f\n", chisqi[i]);

}

Summary: Performs the chi^2 goodness of fit test, for standard continuous distributions.
Sample data:
Header file: OCN_g08.h
See also:


nag_runs_test

Function: nag_runs_test
Prototype:
int nag_runs_test(int n,const double x[],int maxr,int *nruns,double *chi,double *df,double *prob)
Remarks: Performs the runs up or runs down test on a sequence of observations.
Parameters:
n
  The length of the current sequence of observations, n>=3.
x[]
  The sequence of observations.
maxr
  The length of the longest run for which tabulation is desired, r. That is, all runs with length greater than or equal to r are counted together.
nruns
  The returned number of runs actually found.
chi
  The returned approximate chi^2 test statistic.
df
  The returned number of degrees of freedom of the chi^2 statistic.
prob
  The returned upper tail probability corresponding to the chi^2 test statistic (i.e. significance level).

Return values:
This function returns NAG error code, 0 if no error.

Example:

void test_nag_runs_test()
{
    double chi, df, p;
    int i, init, max_run, n, nruns;
    n = 10000;
    double x[10000];
    init =0;

    for(i = 0; i < n; i++)
        x[i] = 	ran(init);		//generate random variable from 0 to 1.
    max_run = 6;
    nag_runs_test(n, x, max_run, &nruns, &chi, &df, &p);
    printf("\n");
    printf("Total number of runs found =%10ld\n" , nruns);
    printf("chisq = %10.4f\n",chi);
    printf("df    = %10,4f\n",df);
    printf("Prob  = %10.4f\n", p);
}

Summary: Performs the runs up or runs down test for randomness.
Sample data:
Header file: OCN_g08.h
See also:


nag_pairs_test

Function: nag_pairs_test
Prototype:
int nag_pairs_test(int n,const double x[],int msize,int lag,double *chi,double *df,double *p)
Remarks: Performs the pairs (serial) test for randomness on a sequence of observations in the interval [0,1].
Parameters:
n
  The number of observations, n>=2.
x[]
  The sequence of observations in the interval [0,1].
msize
  The size of the matrix of counts, m>=2.
lag
  The lag, l, to be used in choosing pairs.
chi
  The returned chi^2 test statistic for testing the null hypothesis of randomness.
df
  The returned degrees of freedom for the chi^2 test statistic.
p
  The returned upper tail probability associated with the chi^2 test statistic (i.e. significance level).

Return values:
This function returns NAG error code, 0 if no error.

Example:

void test_nag_pairs_test()
{
    double chi, df, p;
    int i, max_count, n, init, lag;
    init = 0;
    n = 10000;
    double x[10000];
    for(i = 0; i < n; i++)
        x[i] = 	ran(init);		//generate random variable from 0 to 1.
    max_count = 10;
    lag =1;
    nag_pairs_test(n, x, max_count, lag, &chi, &df, &p);
    printf("\n\n");
    printf("CHISQ	= %10.4f\n",chi);
    printf("DF		= %8.2f\n", df);
    printf("Probabitlity =%10.4f",p);
}

Summary: Performs the pairs (serial) test for randomness.
Sample data:
Header file: OCN_g08.h
See also:


nag_triplets_test

Function: nag_triplets_test
Prototype:
int nag_triplets_test(int n,const double x[],int msize,double *chi,double *df,double *p)
Remarks: Performs the triplets test for randomness on a sequence of observations from the interval [0,1]..
Parameters:
n
  The number of observations, n>=3.
x[]
  The sequence of observations in the interval [0,1].
msize
  The size of the matrix of counts, m>=2.
chi
  The returned chi^2 test statistic for testing the null hypothesis of randomness.
df
  The returned degrees of freedom for the chi^2 test statistic.
p
  The returned upper tail probability associated with the chi^2 test statistic (i.e. significance level).

Return values:
This function returns NAG error code, 0 if no error.

Example:

void test_nag_triplets_test()
{
    double chi, df, p;
    int i, init, max_count, n;
    n = 10000;
    double x[10000];
    for(i = 0; i < n; i++)
        x[i] = 	ran(init);		//generate random variable from 0 to 1.
    max_count = 5;
    nag_triplets_test(n, x, max_count, &chi, &df, &p);
    printf("\n");
    printf("CHISQ	= %10.4f\n",chi);
    printf("DF		= %8.2f\n", df);
    printf("Prob	=%10.4f",p);
}

Summary: Performs the triplets test for randomness.
Sample data:
Header file: OCN_g08.h
See also:


nag_gaps_test

Function: nag_gaps_test
Prototype:
int nag_gaps_test(int n,const double x[],int m,int k,double rl,double ru,double til,double *chi,double *df,double *prob)
Remarks: Performs the gaps test for randomness
Parameters:
n
  The length of the current sequence of observations, n>=1.
x[]
  The sequence of observations.
m
  The maximum number of gaps to be sought. If m<=0 then there is no limit placed on the number of gaps that are found.
k
  The length of the longest gap for which tabulation is desired.
rl
  The lower limit of the interval to be used to define the gaps (rlru
  The upper limit of the interval to be used to define the gaps (ru>rl and ru-rltil
  The total lengeth of the interval which contains all possible numbers that may arise in the sequence (til>0 and ru-rlchi
  The returned chi^2 test statistic for testing the null hypothesis of randomness.
df
  The returned degrees of freedom for the chi^2 test statistic.
prob
  The returned upper tail probability associated with the chi^2 test statistic (i.e. significance level).

Return values:
This function returns NAG error code, 0 if no error.

Example:

void test_nag_gaps_test()
{
    int i, init, max_gap, n, num_gaps;
    double chi, df, lower, length, p, upper;
    init = 0;
    n = 5000;
    double x[5000];
    for(i = 0; i < n; i++)
        x[i] = 	ran(init);		//generate random variable from 0 to 1.
    num_gaps = 0;
    max_gap = 10;
    length = 1.0;
    lower = 0.4;
    upper = 0.6;
    nag_gaps_test(n, x, num_gaps, max_gap, lower, upper, length, &chi, &df, &p);
    printf("\n");
    printf("CHISQ	= %10.4f\n",chi);
    printf("DF		= %8.2f\n", df);
    printf("Prob	=%10.4f",p);
}

Summary: Performs the gaps test for randomness.
Sample data:
Header file: OCN_g08.h
See also:


nag_chi_sq_2_way_table

Function: nag_chi_sq_2_way_table
Prototype:
int nag_chi_sq_2_way_table(int nrow,int ncol,const int nobst[],int tdt,double expt[],double chist[],double *prob,double *chi,double *g,double *df)
Remarks: computes Chi-square statistics for a two-way contingency table. For a 2×2 table with a small number of observations exact probabilities are computed.
Parameters:
nrow
  the number of rows in the contingency table.
ncol
  the number of columns in the contingency table.
nobst[]
  the contingency table.
tdt
  the last dimension of the arrays nobst.
expt[]
  the table of expected values.
chist[]
  the table of Chi-square contributions.
prob
  contains the two-tail significance level for Fisher's exact test, otherwise prob contains the significance level from the Pearson ?2 statistic.
chi
  the Pearson Chi-square statistic.
g
  the likelihood ratio test statistic.
df
  the degrees of freedom for the statistics

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, nrow must not be less than 2: nrow = _value_ On entry, ncol must not be less than 2: ncol = _value_
17: On entry tdt=_value_ while ncol = _value_. These parameters must satisfy tdt = ncol
596: On entry nobst[_value_][_value_]=_value_. All elements of this array must be = 0.
597: On entry all elements of the array nobst are 0. At least one element of this array must be > 0.
598: On entry a 2*2 table has a row or column with both elements zero i.e., the table is degenerate.
599: At least one cell has expected frequency = 0.5. The chi-square approximation may be poor.
74: An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_chi_sq_2_way_table function.

Example:
    Assume we have a matrix "Matrix1"'s size is 3X3 and the data type is integer.
    We have put 9 data in Matrix1.  We need get the Probability, Pearson Chi-square
    statistic, Likelihood ratio test statistic and Degrees of freedom.

    double prob, chi, g, df;
    Matrix <int> mnobst("Matrix1");
    matrix <int> nobst;
    nobst.SetSize(3, 3);
    nobst = mnobst;
    matrix expt, chist;
    expt.SetSize(3, 3);
    chist.SetSize(3, 3);
    int ncol = 3, nrow = 3, tda = 3;

    nag_chi_sq_2_way_table(nrow, ncol, nobst, tda, expt,chist, &prob, &chi, &g, &df);
    printf("Probability = %6.4f\n", prob);
    printf("Pearson Chi-square statistic = %8.3f\n", chi);
    printf("Likelihood ratio test statistic = %8.3f\n", g);
    printf("Degrees of freedom = %4.0f\n", df);

    The data below, taken from Everitt (1977), is from 141 patients with brain tumours.
    The row classification variable is the site of the tumour: frontal lobes, temporal
    lobes and other cerebral areas. The column classification variable is the type of
    tumour: benign, malignant and other cerebral tumours.

void test_nag_chi_sq_2_way_table()
{
    double prob;
    matrix expt;
    expt.SetSize(3,3);
    double g;
    matrix chist;
    chist.SetSize(3,3);
    double df, chi;
    int ncol;
    int nrow;
    int nobst1[9];
    matrix<int> nobst = {{23, 9, 6}, {21, 4, 3}, {34, 24, 17}};;
    nobst.SetSize(3,3);
    int tda = 3;

    nrow = 3;
    ncol = 3;

    nag_chi_sq_2_way_table(nrow, ncol, nobst, tda, expt,chist, &prob, &chi, &g, &df);
    printf("Probability = %6.4f\n", prob);
    printf("Pearson Chi-square statistic = %8.3f\n", chi);
    printf("Likelihood ratio test statistic = %8.3f\n", g);
    printf("Degrees of freedom = %4.0f\n", df);

}

The output is following:

    Probability = 0.0975
    Pearson Chi-square statistic = 7.844
    Likelihood ratio test statistic = 8.096
    Degrees of freedom = 4

Summary: computes Chi-square statistics for a two-way contingency table. For a 2×2 table with a small number of observations exact probabilities are computed.
Sample data:
Header file: OCN_g11.h
See also:


nag_tabulate_stats

Function: nag_tabulate_stats
Prototype:
int nag_tabulate_stats(Nag_TableStats stat,Nag_TableUpdate update,Nag_Weightstype weight,int n,int nfac,const int sf[],const int lfac[],const int factor[],int tdf,const double y[],const double wt[],double table[],int maxt,int *ncells,int *ndim,int idim[],int count[],double comm_ar[])
Remarks: computes a table from a set of classification factors using a selected statistics
Parameters:
stat
  indicates which statistic is to be computed for the table cells
update
  indicates if an existing table is to be updated by further observation.
weight
  indicates if weights are to be used
n
  the number of observations
nfac
  the number of classifying factor
sf[]
  indicates which factor in factor are to be used in the tabulation
lfac[]
  the number of levels of the classifying factors in factor
factor[]
  the nfac coded classification factors for the n observation;
tdf
  the second dimension of the array factor
y[]
  the variable to be tabulated
wt[]
  the weights
table[]
  the computed table
maxt
  the maximum size of the table
ncells
  the number of cells
ndim
  the number of factors
idim[]
  the number of levels
count[]
  a table containing the number of observations
comm_ar[]
  the sum of the weights contributing to each cells

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 2: n = <value>.  On entry, nfac must not be less than 1: nfac = <value>.
17: On entry, tdf = <value> while nfac = <value>.  These parameters must satisfy tdf >= nfac.
70: On entry, parameter stat had an illegal value.  On entry, parameter weight had an illegal value.  On entry, parameter update had an illegal value.
510: The wt array argument must not be NULL when the weight argument indicates weights.
57: On entry, wt[<value>] = <value>.  Constraint: if weight = Nag_Weights or Nag_Weightsvar, wt[i]>=0.
104: On entr, sf[<value>] = <value> while lfac[0] = <value>.  Constraint: if sf[i] > 0, lfac[i] >= 2 for i = 0, 1 , 2, .., nfac.
105: On entry, factor[<value>][<value>] = <value>.  Constraint: factor{i}{j} >= 1 for i = 0, 1, .., n-1; j = 0, 1, ..., nfac - 1.
107: On entry, factor[<value>][<value>] = <value> while lfac[0] = <value>.  Constraint: factor[i][j] <= lfac[j] for i = 0, 1, .., n - 1; j = 0, 1, .., nfac - 1.
600: The maximum size of the table to be computed, maxt is too small.
601: stat Nag_TableStatsVar and the divisor for the variance <= 0.
602: update = Nag_TableUpdateU and at least one of ncells, table, comm_ar or count have been changed since previous call to nag_tabulate_stats.
73: Memory allocation failed.
74: An internal error has occurred in this function.  Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_tabulate_stats function.

Example:
    The data, given by John and Quenouille (1977), is for  a 3 by 6 factorial
    experiment in 3 blocks of 18 units.  The data is input in the order:
    blocks, factor with 3 levels, factor with 6 levels, yield.  The 3 by 6
    table of treatment means for yield over blocks is computed and printed.

void test_nag_tabulate_stats()
{
    char stat[2], weight[2];
    double comm_ar[36];
    double wt[54];
    double table[18];
    int items, i;
    int count[18];
    int	idim[3];
    int isf[3] = {0, 1, 1};
    int j, k, tdf;
    int lfac[3] = {3, 3, 6};
    int ltmax, maxt, n, ncells, ncol, ndim, nfac;
    int nrow;
    Nag_TableStats  stat_enum;
    Nag_Weightstype weight_enum;

    n = 54;
    nfac =3;
    ltmax = 18;
    maxt = ltmax;
    printf("the input data are as following\n");
    printf("n = 54, nfac = 3, ltmax = 18, maxt = ltmax,tdf  = 3,maxt = ltmax,\n");
    printf("stat_enum = Nag_TableStatsAv,weight_enum = Nag_NoWeights;\n");

    int factor[162] = {1, 1, 1, 1, 2, 1, 1, 3, 1, 1, 1, 2, 1, 2, 2, 1, 3, 2, 1, 1,
    3, 1, 2, 3, 1, 3, 3, 1, 1, 4, 1, 2, 4, 1, 3, 4, 1, 1, 5, 1, 2, 5, 1, 3, 5,
    1, 1, 6, 1, 2, 6, 1, 3, 6, 2, 1, 1, 2, 2, 1, 2, 3, 1, 2, 1, 2, 2, 2, 2, 2,
    3, 2, 2, 1, 3, 2, 2, 3, 2, 3, 3, 2, 1, 4, 2, 2, 4, 2, 3, 4, 2, 1, 5, 2, 2,
    5, 2, 3, 5, 2, 1, 6, 2, 2, 6, 2, 3, 6, 3, 1, 1, 3, 2, 1, 3, 3, 1, 3, 1, 2,
    3, 2, 2, 3, 3, 2, 3, 1, 3, 3, 2, 3, 3, 3, 3, 3, 1, 4, 3, 2, 4, 3, 3, 4, 3,
    1, 5, 3, 2, 5, 3, 3, 5, 3, 1, 6, 3, 2, 6, 3, 3, 6};

    printf("\nfactor:\n");
    for(i = 0; i < 162; i++)
    {
        printf("%d, ",factor[i]);
        if((i + 1) % 8 == 0)
            printf("\n");
    }

    double y[54] = {274, 361, 253, 325, 317, 339, 326, 402, 336, 379,
    345, 361, 352, 334, 318, 339, 393, 358, 350, 340, 203, 397, 356, 298, 382,
    376, 355, 418, 387, 379, 432, 339, 293, 322, 417, 342, 82, 297, 133, 306,
    352, 361, 220, 333, 270, 388, 379, 274, 336, 307, 266, 389, 333, 353};

    printf("\ny:\n");
    for(i = 0; i < 54; i++)
    {
        printf("%3.0f, ",y[i]);
        if((i + 1) % 9 == 0)
            printf("\n");
    }

    printf("\nlfac:\n");
    for(i = 0; i < 3; i++)
    {
        printf("%d, ",lfac[i]);

    }
    printf("\nisf:\n");
    for(i = 0; i < 3; i++)
    {
        printf("%d, ",isf[i]);

    }

    printf("\nthe results are as following:\n");
    tdf  = 3;
    maxt = ltmax;
    stat_enum = Nag_TableStatsAv;
    weight_enum = Nag_NoWeights;

    nag_tabulate_stats(stat_enum, Nag_TableUpdateI, weight_enum, n, nfac, isf, lfac, factor, tdf,
                        y, wt, table, maxt, &ncells, &ndim, idim, count, comm_ar);

    printf("\n");
    printf("Table\n");
    printf("\n");
    ncol = idim[ndim -1];
    nrow = ncells /ncol;
    k = 1;
    items = 0;
    for(i = 1; i <= nrow; i++)
    {
            for(j = k, items = 1; j <= k + ncol -1; ++j, items++)
        {
            printf("%8.2f(%2ld)",table[j - 1],count[j - 1]);
            if(items % 6 == 0)
                printf("\n");
        }
        k = k + ncol;
    }
}

    The output is following:
    235.33(3)	342.67(3)	309.33(3)	395.00(3)	373.33(3)	350.00(3)
    332.67(3)	341.67(3)	370.33(3)	370.33(3)	326.67(3)	381.00(3)
    196.33(3)	332.67(3)	320.33(3)	338.00(3)	292.33(3)	351.00(3)

Summary: computes a table from a set of classification factors using a selected statistics.
Sample data:
Header file: OCN_g11.h
See also:


nag_tabulate_percentile

Function: nag_tabulate_percentile
Prototype:
int nag_tabulate_percentile(Nag_TabulateVar type,int n,int nfac,const int sf[],const int lfac[],const int factor[],int tdf,double percnt,const double y[],const double wt[],double table[],int maxt,int *ncells,int *ndim,int idim[],int count[])
Remarks: computes a table from a set of calssification factors using a given percentile or quantile, for example the median
Parameters:
type
  indicates whether the variable to be tabulated is discrete or continous
n
  the number of observation
nfac
  the number of classifying factors
sf[]
  indicates which factor in factor is to be used in the tabulation
lfac[]
  the number of levels of the classifying factors in factor
factor[]
  the nfac coded classification factors for the n observation;
tdf
  the second dimension of the array factor
percnt
  the percentile to be tabulated
y[]
  the variable to be tabulated
wt[]
  the weights
table[]
  the computed table
maxt
  the maximum size of the table to be computed
ncells
  the number of cells in the table
ndim
  the number of factors
idim[]
  the number of levels
count[]
  the number of observations

Return values:
This function returns NAG error code, 0 if no error.
11: On entry, n must not be less than 2: n= <value>.  On entry, nfac must not be less than 1: nfac = <value>.
17: On entry, tdf = <value> while nfac = <value>.  These parameters must satisfy tdf >= nfac.
96: On entry, percnt = <value>.  Constraint: 0 < percnt < 100.
70: On entry, parameter type had an illegal value.
57: On entry, wt[<value>] = <value>.  Constraint: wt[i] >= 0, for i = , 1, .., n - 1.
104: On entry, sf[<value>] = <value> while lfac{<value>] = <value>.  Constraint: if sf[i] > 0, lfac[i] >= 2, for i = 0, 1, ..., nfac - 1.
105: On entry, factor[<value>][<value>] = <value>.  Constraint: factor[i][j] >= 1, for i = 0, 1, .. , n - 1; j = 0, 1, ..., nfac - 1.
107: On entry, factor[<value>][<value>] = <value> while lfac{<value>] = <value>.  Constraint: factor[i][j] <= lfac[j], for i = 0, 1, .. , n - 1; j = 0, 1, ..., nfac - 1.
600: The maximum size of the table to be computed, maxt is too small.
603:  At least one cell is empty.
73: Memory allocation failed.
74: An internal error has occurred in this function.  Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_tabulate_percentile

Example:
    The data, given by John and Quenouille (1977) are for a 3 by 6 factorial
    experiment in 3 blocks of 18 units.  The data is input in the order:
    blocks, factor with 3 levels, factor with 6 levels, yield, and the 3 by 6
    table of treatment medians for yield over blocks is computed and printed.

void test_nag_tabulate_percentile()
{
    char stat[2], weight[2];
    double percnt;
    double wt[54];
    double *wtptr;
    double table[18];
    int ifail;
    int items, i;
    int count[18];
    int	idim[3];
    int sf[3] = {0, 1, 1};
    int j, k, tdf;
    int lfac[3] = {3, 3, 6};
    int ltmax, maxt, n, ncells, ncol, ndim, nfac;
    int nrow;
    Nag_TabulateVar type_enum;

    n = 54;
    nfac = 3;
    percnt =50.0;
    ltmax = 18;
    maxt = ltmax;
    printf("the input are as folowing\n");
    printf("n = 54;nfac = 3 ;percnt =50.0;ltmax = 18;maxt = ltmax;\n");
    printf("tdf  = nfac;ifail = 0;wtptr = NULL;	type_enum = Nag_TabulateVarCont;\n");

    int factor[162] = {1, 1, 1, 1, 2, 1, 1, 3, 1, 1, 1, 2, 1, 2, 2, 1, 3, 2, 1, 1,
    3, 1, 2, 3, 1, 3, 3, 1, 1, 4, 1, 2, 4, 1, 3, 4, 1, 1, 5, 1, 2, 5, 1, 3, 5,
    1, 1, 6, 1, 2, 6, 1, 3, 6, 2, 1, 1, 2, 2, 1, 2, 3, 1, 2, 1, 2, 2, 2, 2, 2,
    3, 2, 2, 1, 3, 2, 2, 3, 2, 3, 3, 2, 1, 4, 2, 2, 4, 2, 3, 4, 2, 1, 5, 2, 2,
    5, 2, 3, 5, 2, 1, 6, 2, 2, 6, 2, 3, 6, 3, 1, 1, 3, 2, 1, 3, 3, 1, 3, 1, 2,
    3, 2, 2, 3, 3, 2, 3, 1, 3, 3, 2, 3, 3, 3, 3, 3, 1, 4, 3, 2, 4, 3, 3, 4, 3,
    1, 5, 3, 2, 5, 3, 3, 5, 3, 1, 6, 3, 2, 6, 3, 3, 6};

    printf("\nfactor:\n");
    for(i = 0; i < 162; i++)
    {
        printf("%d, ",factor[i]);
        if((i + 1) % 8 == 0)
            printf("\n");
    }

    double y[54] = {274, 361, 253, 325, 317, 339, 326, 402, 336, 379,
    345, 361, 352, 334, 318, 339, 393, 358, 350, 340, 203, 397, 356, 298, 382,
    376, 355, 418, 387, 379, 432, 339, 293, 322, 417, 342, 82, 297, 133, 306,
    352, 361, 220, 333, 270, 388, 379, 274, 336, 307, 266, 389, 333, 353};

    printf("\ny:\n");
    for(i = 0; i < 54; i++)
    {
        printf("%3.0f, ",y[i]);
        if((i + 1) % 9 == 0)
            printf("\n");
    }

    printf("\nlfac:\n");
    for(i = 0; i < 3; i++)
    {
        printf("%d, ",lfac[i]);

    }
    printf("\nsf:\n");
    for(i = 0; i < 3; i++)
    {
        printf("%d, ",sf[i]);

    }

    printf("\nthe results are as following:\n");

    tdf  = nfac;
    ifail = 0;
    wtptr = NULL;
    type_enum = Nag_TabulateVarCont;
    nag_tabulate_percentile(type_enum, n, nfac, sf, lfac, factor, tdf, percnt,
                        y, wtptr, table, maxt, &ncells, &ndim, idim, count);

    printf("\n");
    printf("Table for the %4.0fth percentile\n",percnt);
    printf("\n");
//	printf("ndim = %d",ndim-1);
    ncol = idim[ndim -1];
    nrow = ncells /ncol;
    k = 1;
    for(i = 1; i <= nrow; i++)
    {
            for(j = k, items = 1; j <= k + ncol -1; ++j, items++)
        {
            printf("%8.2f(%2ld)",table[j - 1],count[j - 1]);
            if(items % 6 == 0)
                printf("\n");
        }
        k = k + ncol;
    }
}

    The output is following:

    Table for 50th percentile

    226.00(3)	320.25(3)	299.50(3)	385.75(3)	348.00(3)	334.75(3)
    329.25(3)	343.25(3)	365.25(3)	370.50(3)	327.25(3)	378.00(3)
    185.50(3)	328.75(3)	319.50(3)	339.25(3)	286.25(3)	350.25(3)

Summary:
Sample data:
Header file: OCN_g11.h
See also:


nag_prod_limit_surviv_fn

Function: nag_prod_limit_surviv_fn
Prototype:
int nag_prod_limit_surviv_fn(int n,const double t[],const int ic[],const int freq[],int *nd,double tp[],double p[],double psig[])
Remarks: computes the Kaplan-Meier,(or product-limit),estimates of survival probabilities for a sample of failure times.
Parameters:
n
  the number of failure and censored times give in t.
t[]
  the failure and censored times;these need not be ordered.
ic[]
  contains the censoring code of the ith observation.
freq[]
  indicates whether frequencies are provided for each failure and censored time point.
nd
  the number of distinct failure times.
tp[]
  contains the ith ordered distinct failure time.
p[]
  contains the Kaplan-Meier estimate of the survival probability.
psig[]
  contains an estimate of the standard deviation.

Return values:
This function returns NAG error code, 0 if no error.
11:  On entry, n must not be less than 2: n=_value_.
604: On entry, ic[_value_]=_value_. The censor code for an observation must be either 0 or 1.
605: On entry, freq[_value_]=_value_. The value of frequency for an observation must be = 0.
73:  Memory allocation failed.
74:  An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_prod_limit_surviv_fn function.

Example:
    Assume we have "Data1" Worksheet which has 4 columns and 10 rows.
    The first column contain 10 data, and we will put the result,
    the time in the second column, survival probability in the third
    column, and standard deviation in fourth column.  We also have
    "Data2" Worksheet which has 2 columns and 10 rows, these two columns
    contain 10 data in each column.

    int n = 10, nd;
    //Attach six Datasets to these 6 columns
    Dataset dt("data1",0);
    Dataset dtp("data1",1);
    Dataset dp("data1",2);
    Dataset dpsig("data1",3);
    Dataset difreq("data2",0);
    Dataset dic("data2",1);

    dt.SetSize(10);
    dtp.SetSize(10);
    dp.SetSize(10);
    dpsig.SetSize(10);
    difreq.SetSize(10);
    dic.SetSize(10);

    //Dataset cannot be the parameter of function, but vector can be.
    vector t = dt, tp = dtp, p = dp, psig = dpsig;
    vector<int> ifreq = difreq, ic = dic;
    nag_prod_limit_surviv_fn(n, t, ic, ifreq, &nd, tp, p, psig);
    //Put the result to worksheet "Data1" the second, third and fourth column.
    dtp = tp;
    dp = p;
    dpsig = psig;

    The remission times for a set of 21 leukemia patients at 18 distinct
    time points are read in and the Kaplan-Meier estimate computed and
    printed. For further details see Gross and Clark (1975), page 242.

void test_nag_prod_limit_surviv_fn()
{
    double psig[18];
    double p[18];
    double t[18] = {6.0, 6.0, 7.0, 9.0, 10.0, 10.0, 11.0, 13.0, 16.0, 17.0,
    19.0, 20.0, 22.0, 23.0, 25.0, 32.0, 34.0, 35.0};
    double tp[18];
    int i, n = 18, nd;
    int ifreq[18] = {1, 3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 1, 1};
    int ic[18] = {1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 1, 0, 0, 1, 1, 1, 1};

    nag_prod_limit_surviv_fn(n, t, ic, ifreq, &nd, tp, p, psig);

    printf("nd = %d \n",nd);
    printf("\n   Time     Survival 	 Standard\n");
    printf(" 	      probability    deviation\n\n");

    for (i = 0; i < nd; ++i)
        printf(" %6.1f%10.3f %10.3f\n", tp[i], p[i], psig[i]);
}

    The output is following:

nd = 7

   Time     Survival 	 Standard
           probability    deviation

    6.0       0.857        0.076
    7.0       0.807        0.087
   10.0       0.753        0.096
   13.0       0.690        0.107
   16.0       0.627        0.114
   22.0       0.538        0.128
   23.0       0.448        0.135

Summary: General block design or completely randomized design.
Sample data:
Header file: OCN_g12.h
See also:


nag_surviv_cox_model

Function: nag_surviv_cox_model
Prototype:
int nag_surviv_cox_model(int n,int m,int ns,const double z[],int tdz,const int sz[],int ip,const double t[],const int ic[],const double omega[],const int isi[],double *dev,double b[],double se[],double sc[],double cov[],double res[],int *nd,double tp[],double sur[],int tdsur,int ndmax,double tol,int max_iter,int iprint,const char *outfile)
Remarks: returns parameter estimates and other statistics that are associated with the Cox proportional hazards model for fixed covariates
Parameters:
n
  the number of data points
m
  the number of covariates
ns
  the number of strata
z[]
  the covariates
tdz
  the second dimension of array z;
sz[]
  indicates which subset of covariates is to be included
ip
  the number of covariates included as indicated by sz
t[]
  the vector of n failure censoring times
ic[]
  the status of the individual at time t given in t
omega[]
  if an offset is set, it contain value \omega[i], otherwise it is NULL;
isi[]
  the stratum indicator
dev
  the deviance
b[]
  initial estimates of the covariate coefficient parameters
se[]
  the asymptotic standard error of the estimate
sc[]
  the value of the score function
cov[]
  the variance-covariance matirx of the parameter estimates
res[]
  the residuals
nd
  the number of distinct failure times
tp[]
  the distinct failure time
sur[]
  the estimated survival function
tdsur
  the second dimension of the array
ndmax
  the first dimension of the array
tol
  the accuracy required for the estimation
max_iter
  the maximun number of iterations
iprint
  indicates if the printing information on the iteration is required
outfile
  the name of the file into which information is to be output.

Return values:
This function returns NAG error code, 0 if no error.
11:  On entry, m must not be less than 1: m = <value>.  On entry, n must not be less than 2: n = <value>.  On entry, ns must not be less than 0: ns = <value>.  On entry, tdsur must not be less than 1: tdsur = <value>.  On entry, max_iter must not be less than 0: max_iter = <value>.
17:  On entry, tdsur = <value> while ns = <value>.  These parameters must satisfy tdsur >= ns.  On entry, tdz = <value> while m = <value>. These parameters must satisfy tdz >= m.
117: On entry, tol = <value>, machine precision (X02AJC) = <value>.  Constraint: tol >= 10 * machine precision.
78:  Cannot open file outfile for appending.
79:  Cannot close file outfile.
103: On entry, sz[<value>] =<value>.  Constrant: sz[<value>] >= 0.  On entry, ic[<value>] = <value>.  Constraint: ic[<value>] = 0 or 1.  On entry, isi[<value>] = <value>.  Constraint: 0 <= isi[<value>] <= ns.
607: On entry, ip = <value> and the number of non zero values of sz = <value>.  Constraint: ip = the number of non-zero values of sz.
608: On entry, the number of values of sz[i] > 0 is <value>, n = <value> and excluded observations with isi[i] = 0 is <value>.  Constraint: the number of values of non-zero sz must be less than n - excluded observations.
609: On entry, ndmax is = <value> while the output value of nd = <value>.  Constraint: ndmax >= nd.
610: The matrix of second partial derivatives is singular.  Try different starting values or include fewer covariates.
611: Overflow has been detected.  Try different starting values.
612: Convergence has not been achieved in max_iter iterations.  The progress towards convergence can be examined by using by setting iprint to >= 1.  Any non _convergence decreasing the deviance maybe due to a linear combination of covariates being monotonic with time.  Full results are returned.
613: In the current iteration 10 step halvings have been performed withour decreasing the deviance from the previous iteration.  Convergence is assumed.
73:  Memory allocation failed.
74:  An internal error has occurred in this function. Check the function call and array sizes.  If the function call is correct, please consult NAG for assistance.
successfully call of the nag_surviv_cox_model function.

Example:
    Assume we have "Data1" Worksheet which is double type and has 4 columns
    and 42 rows.  The first two columns contain 42 data in each column, and we
    will put the result, the time in the third column, survival function in
    the fourth column.  We have "Data2" Worksheet which is integer type and has
    2 columns and 42 rows.  The first column contains 42 data.

    double b[2], cov[3], dev, df;
    double omega[42], res[42], sc[2], se[2];
    double tol = 5e-5,  v[336], y[42], offset[42];
    int i, i_1, ip = 1, ip1, iprint = 0, irank, isi[42], sz[1] = {1};
    int j, m = 1, maxit = 20, n = 42, nd, ndmax = 42, ns = 0, tdsur = 1, tdv = 8;
    double c_b42  = 0;
    int c_0 = 0;
    string filename = "c:\\test.txt";
    ip1 = ip +1;
    i_1 = n;
    //Attach five Datasets to these five columns
    Dataset dt("data1",0);
    Dataset dz("data1",1);
    Dataset dtp("data1",2);
    Dataset dsur("data1",3);
    Dataset dic("data2",0);

    dt.SetSize(42);
    dz.SetSize(42);
    dtp.SetSize(42);
    dsur.SetSize(42);
    //Dataset cannot be the parameter of function, but vector can be.
    vector t = dt, z = dz, tp = dtp, sur = dsur;
    vector<int> ic = dic;

    for(i =0; i < n; i++)
    {
        y[i] = 1.0 -1.0*ic[i];
        v[i+250] = log(t[i]);
        offset[i] = log(t[i]);
    }
    nag_glm_poisson(Nag_Log, Nag_MeanInclude, n, z, m, m, sz, ip1, y, NULL, offset,
                    c_b42, &dev, &df, b, &irank, se, cov, v, tdv, tol, maxit, c_0,
                    filename, c_b42);
    for(i = 0; i < ip; i++)
        b[i] = b[i+1];
    if(irank != ip +1)
        printf("WARNING: covariate not of full rank\n");
    nag_surviv_cox_model(n, m, ns, z, m, sz, ip, t, ic, NULL, isi, &dev, b,
                        se, sc, cov, res, &nd, tp, sur, tdsur, ndmax, tol,
                        maxit, iprint, filename);
    //put the result to Worksheet "data1", the third time is time and fourth column
    //is suvival function.
    dtp = tp;
    dsur = sur;

    The data are the remission times for two groups of leukemia patients(see Gross
    and Clark(1975)p242). A dummy variable indicates which group they come from. An
    initial estimate is computed using the exponential model and then the Cox proportional
    hazard model is fitted and parameter estimates and  the survival function are printed

void test_nag_surviv_cox_model()
{
    double b[2], cov[3], dev, df;
    double omega[42], res[42], sc[2], se[2];
    double sur[42];
    double t[42] = {1, 1, 2, 2, 3, 4, 4, 5, 5, 8, 8, 8, 8, 11, 11, 12, 12,
    15, 17, 22, 23, 6, 6, 6, 7, 10, 13, 16, 22, 23, 6, 9, 10, 11, 17, 19,
    20, 25, 32, 32, 34, 35};
    double z[42] = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1};
    double tol, tp[42], v[336], y[42], offset[42];
    int i, i_1, ip, ip1, iprint = 0, irank, isi[42], sz[1];
    int ic[42] = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1};
    int j, m = 1, maxit = 20, n = 42, nd, ndmax = 42, ns = 0, tdsur = 1, tdv;
    double c_b42  = 0;
    int c_0 = 0;

    //Get the origin folder path.
    char sztemp[100];
    LT_get_str("%Y", sztemp, 100);

    //Define a filename and working path.
    string str1, filename;
    str1 = sztemp;
    filename = str1 + "text.txt";
    printf("%s\n", filename);

    sz[0] =1;
    ip =1;
    ip1 = ip +1;
    tol = 5e-5;
    i_1 = n;
    tdv = 8;
    for(i =0; i < n; i++)
    {
        y[i] = 1.0 -1.0*ic[i];
        v[i+250] = log(t[i]);
        offset[i] = log(t[i]);
    }

    nag_glm_poisson(Nag_Log, Nag_MeanInclude, n, z, m, m, sz, ip1, y, NULL, offset,
                    c_b42, &dev, &df, b, &irank, se, cov, v, tdv, tol, maxit, c_0,
                    filename, c_b42);

    for(i = 0; i < ip; i++)
        b[i] = b[i+1];
    if(irank != ip +1)
        printf("WARNING: covariate not of full rank\n");

    nag_surviv_cox_model(n, m, ns, z, m, sz, ip, t, ic, NULL, isi, &dev, b,
                        se, sc, cov, res, &nd, tp, sur, tdsur, ndmax, tol,
                        maxit, iprint, filename);
    printf("\n");
    printf("Parameter          Estimate");
    printf("       Standard Error");
    printf("\n");
    for(i = 0; i < ip; i++)
        printf("%6ld          %8.4f         %8.4f\n",i + 1, b[i], se[i]);
    printf("\n");
    printf("Deviance = %13.4f\n",dev);
    printf("\n");
    printf("    Time     Survivor Function");
    printf("\n");
    ns = 1;
    for(i = 0; i < nd; i++)
    {
        printf("%10.0f",tp[i]);
        for(j = 0; j < ns; j++)
        {
            printf("      %8.4f",sur[i * tdsur +j]);
            if( (j + 1) % 3 == 0)
                printf("\n");
        }
        printf("\n");
    }
}

    The output is following:

C:\sftest\Gr394\text.txt

Parameter          Estimate       Standard Error
     1           -1.5091           0.4096

Deviance =      172.7592

    Time     Survivor Function
         1        0.9640
         2        0.9264
         3        0.9065
         4        0.8661
         5        0.8235
         6        0.7566
         7        0.7343
         8        0.6506
        10        0.6241
        11        0.5724
        12        0.5135
        13        0.4784
        15        0.4447
        16        0.4078
        17        0.3727
        22        0.2859
        23        0.1908

Summary:
Sample data:
Header file: OCN_g12.h
See also:


nag_tanh

Function: nag_tanh
Prototype:
double nag_tanh(double x)
Remarks: returns a value for the hyperbolic tangent, tanh x.
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
successfully call of the nag_tanh function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_tanh()
{

    double  y;
    double x[] = { -20.0, -5.0,	0.5, 5.0};
    printf(" 	   x       y\n");
    for(int i = 0; i < 4; i++)
    {
        y = nag_tanh(x[i]);
        printf("%12.1f%12.5f\n", x[i], y);
    }

}

    The output if following:

      x 			y

    -20.0 		-1.00000
    -5.0 		-0.99991
     0.5  		 0.46212
     5.0 		 0.99991

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_sinh

Function: nag_sinh
Prototype:
double nag_sinh(double x,NagError* fail = NULL)
Remarks: returns the value of the hyperbolic sine, sinh x.
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
5: On entry, |x| must not be greater than _value_: x = _value_.  The function has been called with an argument too large in absolute magnitude. There is a danger of setting over.ow. The result is the value of sinh at the closest argument for which a valid call could be made.
successfully call of the nag_sinh function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_sinh()
{
    double  y;
    double x[] = {-10.0, -0.5, 0.0, 0.5, 25.0};
    printf("   x		  y\n");
    for(int i = 0; i < 5; i++)
    {
        y = nag_sinh(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    -1.000e+01 	-1.101e+04
    -5.000e-01 	-5.211e-01
     0.000e+00 	 0.000e+00
     5.000e-01 	 5.211e-01
     2.500e+01 	 3.600e+10

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_cosh

Function: nag_cosh
Prototype:
double nag_cosh(double x,NagError* fail = NULL)
Remarks: returns the value of the hyperbolic cosine, cosh x.
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, |x| must not be greater than _value_: x = _value_.  The function has been called with an argument too large in absolute magnitude. There is a danger of over.ow. The result returned is the value of cosh x at the nearest valid argument.
successfully call of the nag_cosh function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_cosh()
{
    double  y;
    double x[] = {-10.0, -0.5, 0.0, 0.5, 25.0};
    printf("   x		  y\n");
    for(int i = 0; i < 5; i++)
    {
        y = nag_cosh(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    -1.000e+01 	1.101e+04
    -5.000e-01 	1.128e+00
     0.000e+00 	1.000e+00
     5.000e-01 	1.128e+00
     2.500e+01 	3.600e+10

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_arctanh

Function: nag_arctanh
Prototype:
double nag_arctanh(double x,NagError* fail = NULL)
Remarks: returns the value of the inverse hyperbolic tangent, arctanh x.
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
8: On entry, |x| must not be greater than or equal to 1.0: x = _value_.  The function has been called with an argument greater than or equal to 1.0in magnitude, for which arctanh is not de.ned. The result is returned as zero.
successfully call of the nag_arctanh function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_arctanh()
{
    double  y;
    double x[] = {-0.5, 0.0, 0.5, -0.9999};
    printf("   x		  y\n");
    for(int i = 0; i < 4; i++)
    {
        y = nag_arctanh(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    -5.000e-01 	-5.493e-01
     0.000e+00 	 0.000e+00
     5.000e-01 	 5.493e-01
    -9.999e-01 	-4.952e+00

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_arcsinh

Function: nag_arcsinh
Prototype:
double nag_arcsinh(double x)
Remarks: returns the value of the inverse hyperbolic sine, arcsinh x.
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
sucessfully call of the nag_arcsinh function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_arcsinh()
{
    double  y;
    double x[] = {-2.0, -0.5, 1.0, 6.0};
    printf("   x		  y\n");
    for(int i = 0; i < 4; i++)
    {
        y = nag_arcsinh(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    -2.000e+00 	-1.444e+00
    -5.000e-01 	-4.812e-01
     1.000e+00 	 8.814e-01
     6.000e+00 	 2.492e+00

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_arccosh

Function: nag_arccosh
Prototype:
double nag_arccosh(double x,NagError* fail = NULL)
Remarks: returns the value of the inverse hyperbolic cosine, arccoshx. The result is in the principal positive branch.
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
5: On entry, x must not be less than 1.0: x = _value_.  arccosh x is not de.ned and the result returned is zero.
successfully call of the nag_arccosh function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_arccosh()
{
    double  y;
    double x[] = {1.00, 2.0, 5.0, 10.0};
    printf("   x		  y\n");
    for(int i = 0; i < 4; i++)
    {
        y = nag_arccosh(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    1.000e+00 	0.000e+00
    2.000e+00 	1.317e+00
    5.000e+00 	2.292e+00
    1.000e+01 	2.993e+00

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_exp_integral

Function: nag_exp_integral
Prototype:
double nag_exp_integral(double x,NagError *fail = NULL)
Remarks: returns the value of the exponential integral E1(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
6: On entry, x must not be less than or equal to 0.0: x = _value_.  The function is not de.ned for this value and the result returned is zero.
successfully call of the nag_exp_integral function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_exp_integral()
{
    double  y;
    double x[] = {2.0, 9.0};
    printf("   x		  y\n");
    for(int i = 0; i < 2; i++)
    {
        y = nag_exp_integral(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    2.000e+00 	4.890e-02
    9.000e+00 	1.245e-05

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_cos_integral

Function: nag_cos_integral
Prototype:
double nag_cos_integral(double x,NagError *fail = NULL)
Remarks: returns the value of the cosine integral Ci(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
6: On entry, x must not be less than or equal to 0.0: x = _value_.  The function is not de.ned for this value and the result returned is zero.
successfully call of the nag_cos_integral function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_cos_integral()
{
    double  y;
    double x[] = {0.2, 0.4, 0.6, 0.8, 1.0};
    printf("   x		  y\n");
    for(int i = 0; i < 5; i++)
    {
        y = nag_cos_integral(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    2.000e-01 	-1.042e+00
    4.000e-01 	-3.788e-01
    6.000e-01 	-2.227e-02
    8.000e-01 	 1.983e-01
    1.000e+00 	 3.374e-01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_sin_integral

Function: nag_sin_integral
Prototype:
double nag_sin_integral(double x)
Remarks: returns the value of the sine integral Si(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
successfully call of the nag_sin_integral function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_sin_integral()
{
    double  y;
    double x[] = {0.0, 0.2, 0.4, 0.6, 0.8, 1.0};
    printf("   x		  y\n");
    for(int i = 0; i < 6; i++)
    {
        y = nag_sin_integral(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    0.000e+00 	0.000e+00
    2.000e-01 	1.996e-01
    4.000e-01 	3.965e-01
    6.000e-01 	5.881e-01
    8.000e-01 	7.721e-01
    1.000e+00 	9.461e-01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_gamma

Function: nag_gamma
Prototype:
double nag_gamma(double x,NagError *fail = NULL)
Remarks: returns the value of the Gamma function G(x).
Parameters:
x
  the argument x of the function.

Return values:
This funtion returns NAG error code, 0 if no error.
7: On entry, x must not be greater than _value_: x = _value_.  The argument is too large, the function returns the approximate value of G(x) at the nearest valid argument.
5: On entry, x must not be less than _value_: x = _value_.  The argument is too large and negative, the function returns zero.
692: On entry, x must be greater than _value_: x = _value_.  The argument is too close to zero, the function returns the approximate value of G(x) at the nearest valid argument.
693: On entry, x must not be e.ectively a negative integer: x = _value_.  The argument is a negative integer, at which values G(x) is in.nite. The function returns a large positive value.
successfully call of the nag_gamma function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_gamma()
{
    double  y;
    double x[] = {1.0, 1.25, 1.5, 1.75, 2.0, 5.0, 10.0, -1.5};
    printf("   x		  y\n");
    for(int i = 0; i < 8; i++)
    {
        y = nag_gamma(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 				y

    1.000e+00 		1.000e+00
    1.250e+00 		9.064e-01
    1.500e+00 		8.862e-01
    1.750e+00 		9.191e-01
    2.000e+00 		1.000e+00
    5.000e+00 		2.400e+01
    1.000e+01 		3.629e+05
    -1.500e+00 		2.363e+00

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_log_gamma

Function: nag_log_gamma
Prototype:
double nag_log_gamma(double x,NagError *fail = NULL)
Remarks: returns a value for the logarithm of the Gamma function, ln G(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
6: On entry, x must not be less than or equal to 0.0: x = _value_.  For zero and negative values the function is undefined, the function returns zero.
7: On entry, x must not be greater than _value_: x = _value_.  x is too large, the function would over.ow, the function returns the value of the function at the largest permissible argument.
successfully call of the nag_log_gamma function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_log_gamma()
{
    double  y;
    double x[] = {1.0, 1.25, 1.5, 1.75, 2.0, 5.0, 10.0, 20.0, 1000.0};
    printf("   x		  y\n");
    for(int i = 0; i < 9; i++)
    {
        y = nag_log_gamma(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    1.000e+00 	 0.000e+00
    1.250e+00 	-9.827e-02
    1.500e+00 	-1.208e-01
    1.750e+00 	-8.440e-02
    2.000e+00 	 0.000e+00
    5.000e+00 	 3.178e+00
    1.000e+01    1.280e+01
    2.000e+01 	 3.934e+01
    1.000e+03 	 5.905e+03

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_real_polygamma

Function: nag_real_polygamma
Prototype:
double nag_real_polygamma(double x,int k,NagError *fail = NULL)
Remarks: returns the value of the kth derivative of the psi function psi(x) for real x and k = 0, 1, ..., 6.
Parameters:
x
  the argument x of the function.
k
  the function psi-k(z) to be evaluated.

Return values:
This function returns NAG error code, 0 if no error.
90: On entry, k = <value>.  Constraint: 0 <= k <= 6.
96: On entry, x = <value>.  Constraint: x must not be 'too close' to a non-positive integer.  That is, |x - nint(x)| >= machine precision x nint(x).
694: The evaluation has been abandoned due to the likelihood of underflow.  The result is returned as zero.
695: The evaluation has been abandoned due to the likelihood of overflow.  The result is returned as zero.
74:  An internal error has occurred in this function.  Check the function call and any array sizes.  If the call is correct the please consult NAG for assistance.
successfully call of the nag_real_polygamma.

Example:
    The example program evaluates \psi(2)(x) at  x = 2.5, and prints the results

void test_nag_real_polygamma()
{
    double y;
    double x[] ={1.0, 0.5, -3.6, 8.0, 2.9, -4.7, -5.4};
    int k[] = {0, 1, 2, 3, 4, 5, 6};
    printf("  x	    k	    (D^K/DX^K)psi(X)\n");
    for( int i = 0; i < 6; i++)
    {
        y = nag_real_polygamma(x[i], k[i]);
        printf("%5.1f %5ld     %12.4e\n", x[i], k[i], y);
    }
}

The output is following:

 X		    K		(D^K/DX^K)psi(X)

 1.0		0		-5.772 e-01
 0.5		1		 4.9348e+00
-3.6		2		-2.2335e+01
 8.0		3		 4.6992e-03
 2.9		4		-1.5897e-01
-4.7		5		 1.6566e+05
-5.4		6		 4.1378e+05

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_complex_polygamma

Function: nag_complex_polygamma
Prototype:
complex nag_complex_polygamma(complex z,int k,NagError *fail = NULL)
Remarks: returns the value of the kth derivative of the psi function psi(z), for complex z and k = 0, 1, ..., 4.
Parameters:
z
  the argument z of the function.
k
  the function psi-k(z) to be evaluated.

Return values:
This function returns NAG error code, 0 if no error.
90: On entry, k = <value>.  Constraint: 0 <= k <= 4.
102: On entry, z = (<value>, <value>).  Constraint: z.re must not be ' too close' to a non-positive integer when z.im = 0.0.  That is, |z.re - nint(z.re)| >= machine precision x |nint(z.re)|
695: The evaluation has been abandoned due to the likelihood of overflow.  The result is returned as zero.
74: An internal error has occurred in the function.  Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
successfully call of the nag_complex_polygamma function.

Example:
    The example program evaluates the psi(trigamma) function at z = -1.5 +2.5i,
    and prints the results.

void test_nag_complex_polygamma()
{
    complex z, z_l;
    double re[5] = {1.2, 0.5, -1.5, 8.0, 2.9};
    double im[5] = {5.0, -0.2, 2.5, 3.3, 7.5};
    int k[5] = {0, 1, 1, 3, 4};
    printf("          z        k          (d^K/DZ^k)psi(z)\n\n");

    for(int i = 0; i < 5; i++)
    {
        z.m_re = re[i];
        z.m_im = im[i];
        z_l = nag_complex_polygamma(z, k[i]);
        printf("(%5.1f, %5.1f) %6ld (%12.4e, %12.4e) \n",z.m_re, z.m_im, k[i], z_l.m_re, z_l.m_im);
    }
}

    The output is following:

    z 					k				(D^K/DZ^K)psi(z)

    ( 1.2,  5.0)		0			( 1.6176e+00,  1.4312e+00)
    ( 0.5, -0.2)		1			( 3.4044e+00,  2.5394e+00)
    (-1.5,  2.5)		2			(-1.9737e-01, -2.4271e-01)
    ( 8.0,  3.3)		3			( 1.1814e-03, -3.4188e-03)
    ( 2.9,  7.5)		4			(-5.0227e-04, -1.4955e-03)

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_incomplete_gamma

Function: nag_incomplete_gamma
Prototype:
int nag_incomplete_gamma(double a,double x,double tol,double *p,double *q)
Remarks: computes values for the incomplete gamma functions P(a, x) and Q(a, x).
Parameters:
a
  the argument a of the functions.
x
  the argument x of the functions.
tol
  the relative accuracy required by the user in the results. If nag incomplete gamma is entered with tol greater than 1.0 or less than machine precision, then the value of machine precision is used instead.
p
  the values of the functions P(a, x) and Q(a, x) respectively.
q
  the values of the functions P(a, x) and Q(a, x) respectively.

Return values:
This function returns NAG error code, 0 if no error.
On error nag incomplete gamma returns with a value of 0.0 for p and q.
6: On entry, a must not be less than or equal to 0.0: a = _value_.
11: On entry, x must not be less than 0.0: x = _value_.
405: The algorithm has failed to converge in _value_ iterations.  Convergence of the Taylor series or Legendre continued fraction has failed within the speci.ed number of iterations. This error is extremely unlikely to occur; if it does, contact NAG.
successfully call of the nag_incomplete_gamma function.

Example:
    The following program reads values of the argument a and x from a file,
    evaluates the function and prints the results.

void test_nag_incomplete_gamma()
{
    double q, tol, p;
    double a[] = {2.0,7.0, 0.5, 20.0, 21.0};
    double x[] = {3.0, 1.0, 99.0, 21.0, 20.0}
    tol = 1e-5;
    printf("       a            x           p           q\n");

    for(int i = 0; i < 5; i++)
    {
        nag_incomplete_gamma(a[i], x[i], tol, &p, &q);
        printf("%12.4f%12.4f%12.4f%12.4f\n", a[i], x[i], p, q);
    }
}

    The output is following:

        a 		x 		p 	 q

     2.0000	 3.0000 0.8009 0.1991
     7.0000	 1.0000 0.0001 0.9999
     0.5000	99.0000 1.0000 0.0000
    20.0000 21.0000 0.6157 0.3843
    21.0000 20.0000 0.4409 0.5591

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_cumul_normal

Function: nag_cumul_normal
Prototype:
double nag_cumul_normal(double x)
Remarks: returns the value of the cumulative Normal distribution function P(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
successfully call of the nag_cumul_normal function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_cumul_normal()
{
    double y;
    double x[] = { -20.0, -1.0, 0.0, 1.0, 2.0, 20.0};

    printf("   x		  y\n");
    for(int i = 0; i < 6; i++)
    {
        y= nag_cumul_normal(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    -2.000e+01 	2.754e-89
    -1.000e+00 	1.587e-01
     0.000e+00 	5.000e-01
     1.000e+00 	8.413e-01
     2.000e+00 	9.772e-01
     2.000e+01 	1.000e+00

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_cumul_normal_complem

Function: nag_cumul_normal_complem
Prototype:
double nag_cumul_normal_complem(double x)
Remarks: returns the value of the complement of the cumulative normal distribution function Q(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
successfully call of the nag_cumul_normal_complem function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_cumul_normal_complem()
{
    double y;
    double x[] = { -20.0, -1.0, 0.0, 1.0, 2.0, 20.0};

    printf("   x		  y\n");
    for(int i = 0; i < 6; i++)
    {
        y= nag_cumul_normal_complem(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }

}

    The output is following:

    x 				y

    -2.000e+01 	1.000e+00
    -1.000e+00 	8.413e-01
     0.000e+00 	5.000e-01
     1.000e+00 	1.587e-01
     2.000e+00 	2.275e-02
     2.000e+01 	2.754e-89

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_erfc

Function: nag_erfc
Prototype:
double nag_erfc(double x)
Remarks: returns the value of the complementary error function, erfc x.
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
successfully call of the nag_erfc function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_erfc()
{
    double  y;
    double x[] = { -10.0, -1.0, 0.0, 1.0, 10.0}
    printf("   x		  y\n");
    for(int i = 0; i < 5; i++)
    {
        y= nag_erfc(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }

}

    The output is following:

    x 					y

    -1.000e+01 		2.000e+00
    -1.000e+00 		1.843e+00
     0.000e+00 		1.000e+00
     1.000e+00 		1.573e-01
     1.000e+01 		2.088e-45

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_erf

Function: nag_erf
Prototype:
double nag_erf(double x)
Remarks: returns the value of the error function, erf x.
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
successfully call of the nag_erf function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_erf()
{
    double y;
    double x[] = {-6.0, -4.5, -1.0, 1.0, 4.5, 6.0};
    printf("   x		  y\n");
    for(int i = 0; i < 6; i++)
    {
        y= nag_erf(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }

}

    The output is following:

        x			 y

    -6.000e+00 	-1.000e+00
    -4.500e+00 	-1.000e+00
    -1.000e+00 	-8.427e-01
     1.000e+00 	 8.427e-01
     4.500e+00 	 1.000e+00
     6.000e+00 	 1.000e+00

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_y0

Function: nag_bessel_y0
Prototype:
double nag_bessel_y0(double x,NagError *fail = NULL)
Remarks: returns the value of the Bessel function Y0(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, x must not be greater than _value_: x = _value_.  x is too large, the function returns the amplitude of the Y0 oscillation, _2/px.
6: On entry, x must not be less than or equal to 0.0: x = _value_.  Y0 is undefined, the function returns zero.
successfully call of the nag_bessel_y0 function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_bessel_y0()
{
    double y;
    double x[] = {0.5, 1.0, 3.0, 6.0, 8.0, 10.0, 1000.0};
    printf("   x		  y\n");
    for(int i = 0; i < 7; i++)
    {
        y= nag_bessel_y0(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 				y
    5.000e-01 		-4.445e-01
    1.000e+00 		 8.826e-02
    3.000e+00 		 3.769e-01
    6.000e+00 		-2.882e-01
    8.000e+00 		 2.235e-01
    1.000e+01 		 5.567e-02
    1.000e+03 		 4.716e-03

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_y1

Function: nag_bessel_y1
Prototype:
double nag_bessel_y1(double x,NagError *fail = NULL)
Remarks: returns the value of the Bessel function Y1(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, x must not be greater than _value_: x = _value_.  x is too large, the function returns the amplitude of the Y1 oscillation, _2/px.
6: On entry, x must not be less than or equal to 0.0: x = _value_.  Y1 is undefined, the function returns zero.
692: On entry, x must be greater than _value_: x = _value_.  x is too close to zero, there is a danger of over.ow, the function returns the value of Y1(x) at the smallest valid argument.
successfully call of the nag_bessel_y1 function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_bessel_y1()
{
    double y;
    double x[] = {0.5, 1.0, 3.0, 6.0, 8.0, 10.0, 1000.0};
    printf("   x		  y\n");
    for(int i = 0; i < 7; i++)
    {
        y= nag_bessel_y1(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

    x 				y

    5.000e-01 	-1.471e+00
    1.000e+00 	-7.812e-01
    3.000e+00 	 3.247e-01
    6.000e+00 	-1.750e-01
    8.000e+00 	-1.581e-01
    1.000e+01 	 2.490e-01
    1.000e+03 	-2.478e-02

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_j0

Function: nag_bessel_j0
Prototype:
double nag_bessel_j0(double x,NagError *fail = NULL)
Remarks: returns the value of the Bessel function J0(x).
Parameters:
x
  the argument x of the function.

Return values:
This function return NAG error code, 0 if no error.
7: On entry, x must not be greater than _value_: x = _value_.  x is too large, the function returns the amplitude of the J0 oscillation, _2/p|x|.
successfully call of the nag_bessel_j0 function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results

void test_nag_bessel_j0()
{
    double y;
    double x[] ={0.0, 0.5, 1.0, 3.0, 6.0, 8.0, 10.0, -1.0, 1000.0}

    printf("   x		  y\n");
    for(int i = 0; i < 9; i++)
    {
        y= nag_bessel_j0(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

    x 					y

    0.000e+00 		1.000e+00
    5.000e-01 		9.385e-01
    1.000e+00 		7.652e-01
    3.000e+00 	   -2.601e-01
    6.000e+00 		1.506e-01
    8.000e+00 		1.717e-01
    1.000e+01 	   -2.459e-01
    -1.000e+00 		7.652e-01
    1.000e+03 		2.479e-02

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_j1

Function: nag_bessel_j1
Prototype:
double nag_bessel_j1(double x,NagError *fail = NULL)
Remarks: returns the value of the Bessel function J1(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, x must not be greater than _value_: x = _value_.  x is too large. The function returns the amplitude of the J1 oscillation, _2/p|x|.
successfully call of the 	nag_bessel_j1.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_bessel_j1()
{
    double y;
    double x[] ={0.0, 0.5, 1.0, 3.0, 6.0, 8.0, 10.0, -1.0, 1000.0}
    printf("   x		  y\n");
    for(int i = 0; i < 9; i++)
    {
        y= nag_bessel_j1(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    0.000e+00 	0.000e+00
    5.000e-01 	2.423e-01
    1.000e+00 	4.401e-01
    3.000e+00 	3.391e-01
    6.000e+00  -2.767e-01
    8.000e+00	2.346e-01
    1.000e+01 	4.347e-02
    -1.000e+00 -4.401e-01
    1.000e+03 	4.728e-03

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_airy_ai

Function: nag_airy_ai
Prototype:
double nag_airy_ai(double x,NagError *fail = NULL)
Remarks: returns a value for the Airy function Ai(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, x must not be greater than _value_: x = _value_.  x is too large and positive. The function returns zero.
5: On entry, x must not be less than _value_: x = _value_.  x is too large and negative. The function returns zero.
successfully call of the nag_airy_bi function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_airy_ai()
{
    double y;
    double x[] ={-10.0, -1.0, 0.0, 1.0, 5.0, 10.0, 20.0};

    printf("   x		  y\n");
    for(int i = 0; i < 7; i++)
    {
        y= nag_airy_ai(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 				y

    -1.000e+01 		4.024e-02
    -1.000e+00 		5.356e-01
     0.000e+00 		3.550e-01
     1.000e+00 		1.353e-01
     5.000e+00 		1.083e-04
     1.000e+01 		1.105e-10
     2.000e+01 	  	1.692e-27

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_airy_bi

Function: nag_airy_bi
Prototype:
double nag_airy_bi(double x,NagError *fail = NULL)
Remarks: returns a value of the Airy function Bi(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, x must not be greater than _value_: x = _value_.  x is too large and positive. The function returns zero.
5: On entry, x must not be less than _value_: x = _value_.  x is too large and negative. The function returns zero.
successfully call of the nag_airy_bi function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_airy_bi()
{
    double y;
    double x[] ={-10.0, -1.0, 0.0, 1.0, 5.0, 10.0, 20.0};

    printf("   x		  y\n");
    for(int i = 0; i < 7; i++)
    {
        y= nag_airy_bi(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    -1.000e+01 	-3.147e-01
    -1.000e+00 	 1.040e-01
     0.000e+00   6.149e-01
     1.000e+00 	 1.207e+00
     5.000e+00 	 6.578e+02
     1.000e+01 	 4.556e+08
     2.000e+01 	 2.104e+25

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_airy_ai_deriv

Function: nag_airy_ai_deriv
Prototype:
double nag_airy_ai_deriv(double x,NagError *fail = NULL)
Remarks: returns a value of the derivative of the Airy function Ai(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, x must not be greater than _value_: x = _value_.  x is too large and positive. The function returns zero.
5: On entry, x must not be less than _value_: x = _value_.  x is too large and negative. The function returns zero.
successfully call of the nag_airy_ai_deriv function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_airy_ai_deriv()
{
    double y;
    double x[] ={-10.0, -1.0, 0.0, 1.0, 5.0, 10.0, 20.0};

    printf("   x		  y\n");
    for(int i = 0; i < 7; i++)
    {
        y= nag_airy_ai_deriv(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    -1.000e+01 	 9.963e-01
    -1.000e+00 	-1.016e-02
     0.000e+00 	-2.588e-01
     1.000e+00 	-1.591e-01
     5.000e+00 	-2.474e-04
     1.000e+01 	-3.521e-10
     2.000e+01 	-7.586e-27

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_airy_bi_deriv

Function: nag_airy_bi_deriv
Prototype:
double nag_airy_bi_deriv(double x,NagError *fail = NULL)
Remarks: returns a value of the derivative of the Airy function Bi(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, x must not be greater than _value_: x = _value_.  x is too large and positive. The function returns zero.
5: On entry, x must not be less than _value_: x = _value_.  x is too large and negative. The function returns zero.
successfully call of the nag_airy_bi_deriv function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_bi_deriv()
{
    double y;
    double x[] ={-10.0, -1.0, 0.0, 1.0, 5.0, 10.0, 20.0};

    printf("   x		  y\n");
    for(int i = 0; i < 7; i++)
    {
        y= nag_airy_bi_deriv(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    -1.000e+01 	1.194e-01
    -1.000e+00 	5.924e-01
     0.000e+00  4.483e-01
     1.000e+00  9.324e-01
     5.000e+00  1.436e+03
     1.000e+01  1.429e+09
     2.000e+01  9.382e+25

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_zeros

Function: nag_bessel_zeros
Prototype:
int nag_bessel_zeros(double a,int n,int mode,double rel,double x[],NagError *fail = NULL)
Remarks: determines the leading N zeros of one of the Bessel functions Ja(x), Ya(x), J'a(x), Y'a(x) for real x and non-nagative a (alpha).
Parameters:
a
  the order alpha of fuction.
n
  the number n of zeros required.
mode
  specifies the form of the function whose zeros are required.
rel
  the relative accuracy to which the zeros are required.
x[]
  the n required zeros of the function specified by mode.

Return values:
This function returns NAG error code, 0 if no error.
90: On entry, n = <value>.  Constraint: n >= 1.  On entry, mode = <value>.  Constraint: 1<= mode <= 4.
96: On entry, a = <value>.  Constraint: 0.0 <= a <= 100000.0.  On entry, rel = <value>.  Constraint: rel > 0.0
74: An internal error has occurred in this function.  Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
successfully call of the nag_bessel_zeros function.

Example:

    to determine the leading five positive zeros of the Bessel function j0(x)

void test_nag_bessel_zeros()
{

    double a = 0.0;
    int n = 5;
    int mode = 1;
    double rel = 1.1e-8;
    double x[100];
    nag_bessel_zeros(a, n, mode, rel, x);
    printf(" a,       n,   mode,      rel\n");
    printf("                     (machine-dependent)\n");
    printf("%4.1f   %3ld %6ld        %9.1e\n\n", a, n, mode, rel);

    if(mode == 1)
        printf("Leading N positive zeros of J\n");
    if(mode == 2)
        printf("Leading N positive zeros of Y \n");
    if(mode == 3)
    {
        if(a == 0)
            printf("Leading N non_negative zeros of J'\n");
        else
            printf("Leading N positive zeros of J'\n");
    }
    if(mode == 4)
        printf("Leading N positive zeros of Y'\n\n");

    for(int i = 0; i <= n - 1; i++)
        printf("x = %12.4e\n", x[i]);
    printf("\n");

}

    The output is following:

    a 		n		mode			rel
                                (machine-dependent)
    0.0		5		1				1.1e-08

    Leading N positive zeros of J

    x = 2.4048 e+00
    x = 5.5201e+00
    x = 8.6537e+00
    x = 1.1792e+01
    x = 1.4931e+01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_k0

Function: nag_bessel_k0
Prototype:
double nag_bessel_k0(double x,NagError *fail = NULL)
Remarks: returns the value of the modified Bessel function K0(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
6: On entry, x must not be less than or equal to 0.0: x = _value_.  K0 is undefined and the function returns zero.
successfully call of the nag_bessel_k0 function.

Example:
    The following program reads values of the argument x from a .le, evaluates the function at each
    value of x and prints the results.

void test_nag_bessel_k0()
{
    double y;
    double x[] ={0.4, 0.6, 1.4, 1.6, 2.5, 3.5, 6.0, 8.0, 10.0, 1000.0};
    printf("   x		  y\n");
    for(int i = 0; i < 10; i++)
    {
        y=nag_bessel_k0(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    4.000e-01 	1.115e+00
    6.000e-01 	7.775e-01
    1.400e+00 	2.437e-01
    1.600e+00 	1.880e-01
    2.500e+00 	6.235e-02
    3.500e+00 	1.960e-02
    6.000e+00 	1.244e-03
    8.000e+00 	1.465e-04
    1.000e+01 	1.778e-05
    1.000e+03 	0.000e+00

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_k1

Function: nag_bessel_k1
Prototype:
double nag_bessel_k1(double x,NagError *fail = NULL)
Remarks: returns the value of the modified Bessel function, K1(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
6: On entry, x must not be less than or equal to 0.0: x = _value_.  K0 is undefined and the function returns zero.
692: On entry, x must be greater than _value_: x = _value_.  x is too small, there is a danger of over.ow and the function returns approximately the largest representable value.
successfully call of the the nag_bessel_k1 function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_bessel_k1()
{
    double y;
    double x[] ={0.4, 0.6, 1.4, 1.6, 2.5, 3.5, 6.0, 8.0, 10.0, 1000.0};
    printf("   x		  y\n");
    for(int i = 0; i < 10; i++)
    {
        y=nag_bessel_k1(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    4.000e-01 	2.184e+00
    6.000e-01 	1.303e+00
    1.400e+00 	3.208e-01
    1.600e+00 	2.406e-01
    2.500e+00 	7.389e-02
    3.500e+00 	2.224e-02
    6.000e+00 	1.344e-03
    8.000e+00 	1.554e-04
    1.000e+01 	1.865e-05
    1.000e+03 	0.000e+00

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_i0

Function: nag_bessel_i0
Prototype:
double nag_bessel_i0(double x,NagError *fail = NULL)
Remarks: returns the value of the modified Bessel function I0(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, |x| must not be greater than _value_: x = _value_.  |x| is too large and the function returns the approximate value of I0(x) at the nearest valid argument.
successfully call of the nag_bessel_i1 function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_bessel_i0()
{
    double y;
    double x[] ={0.0, 0.5, 1.0, 3.0, 6.0, 8.0, 10.0, 15.0, 20.0, -1.0};
    printf("   x		  y\n");
    for(int i = 0; i < 10; i++)
    {
        y=nag_bessel_i0(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    0.000e+00 	1.000e+00
    5.000e-01 	1.063e+00
    1.000e+00 	1.266e+00
    3.000e+00 	4.881e+00
    6.000e+00 	6.723e+01
    8.000e+00 	4.276e+02
    1.000e+01 	2.816e+03
    1.500e+01 	3.396e+05
    2.000e+01 	4.356e+07
    -1.000e+00 	1.266e+00

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_i1

Function: nag_bessel_i1
Prototype:
double nag_bessel_i1(double x,NagError *fail = NULL)
Remarks: returns a value for the modified Bessel function I1(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, |x| must not be greater than _value_: x = _value_.  |x| is too large and the function returns the approximate value of I0(x) at the nearest valid argument.
successfully call of the nag_bessel_i1 function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_bessel_i1()
{
    double y;
    double x[] ={0.0, 0.5, 1.0, 3.0, 6.0, 8.0, 10.0, 15.0, 20.0, -1.0};
    printf("   x		  y\n");
    for(int i = 0; i < 10; i++)
    {
        y=nag_bessel_i1(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    0.000e+00 	0.000e+00
    5.000e-01 	2.579e-01
    1.000e+00 	5.652e-01
    3.000e+00 	3.953e+00
    6.000e+00 	6.134e+01
    8.000e+00 	3.999e+02
    1.000e+01 	2.671e+03
    1.500e+01 	3.281e+05
    2.000e+01 	4.245e+07
    -1.000e+00 -5.652e-01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_k0_scaled

Function: nag_bessel_k0_scaled
Prototype:
double nag_bessel_k0_scaled(double x,NagError *fail = NULL)
Remarks: returns a value of the scaled modified Bessel function exK0(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
6: On entry, x must not be less than or equal to 0.0: x = _value_.  K0 is undefined and the function returns zero.
successfully call of the nag_bessel_k0_scaled function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_bessel_k0_scaled()
{
    double y;
    double x[] ={0.4, 0.6, 1.4, 2.5, 10.0, 1000.0};
    printf("   x		  y\n");
    for(int i = 0; i < 6; i++)
    {
        y=nag_bessel_k0_scaled(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 		y

    4.000e-01 1.663e+00
    6.000e-01 1.417e+00
    1.400e+00 9.881e-01
    2.500e+00 7.595e-01
    1.000e+01 3.916e-01
    1.000e+03 3.963e-02

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_k1_scaled

Function: nag_bessel_k1_scaled
Prototype:
double nag_bessel_k1_scaled(double x,NagError *fail = NULL)
Remarks: returns a value of the scaled modified Bessel function exK1(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
6: On entry, x must not be less than or equal to 0.0: x = _value_.  K1 is undefined and the function returns zero.
692: On entry, x must be greater than _value_ : x = _value_.  The function returns the value of the function at the smallest permitted value of the argument.
successfully call of the nag_bessel_k1_scaled.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_bessel_k1_scaled()
{
    double y;
    double x[] ={0.4, 0.6, 1.4, 2.5, 10.0, 1000.0};
    printf("   x		  y\n");
    for(int i = 0; i < 6; i++)
    {
        y=nag_bessel_k1_scaled(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 		y

    4.000e-01 3.259e+00
    6.000e-01 2.374e+00
    1.400e+00 1.301e+00
    2.500e+00 9.002e-01
    1.000e+01 4.108e-01
    1.000e+03 3.965e-02

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_i0_scaled

Function: nag_bessel_i0_scaled
Prototype:
double nag_bessel_i0_scaled(double x)
Remarks: returns a value of the scaled modified Bessel function e-|x|I0(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
successfully call of the nag_bessel_i0_scaled.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_bessel_i0_scaled()
{
    double y;
    double x[] ={0.0, 0.5, 1.0, 3.0, 6.0, 10.0, 1000.0, -1.0};
    printf("   x		  y\n");
    for(int i = 0; i < 8; i++)
    {
        y=nag_bessel_i0_scaled(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 			y

    0.000e+00 	1.000e+00
    5.000e-01 	6.450e-01
    1.000e+00 	4.658e-01
    3.000e+00 	2.430e-01
    6.000e+00 	1.667e-01
    1.000e+01 	1.278e-01
    1.000e+03 	1.262e-02
    -1.000e+00 	4.658e-01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_i1_scaled

Function: nag_bessel_i1_scaled
Prototype:
double nag_bessel_i1_scaled(double x)
Remarks: returns a value of the scaled modified Bessel function e-|x|I1(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
successfully call of the nag_bessel_i1_scaled function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_bessel_i1_scaled()
{
    double y;
    double x[] ={0.0, 0.5, 1.0, 3.0, 6.0, 10.0, 1000.0, -1.0};
    printf("   x		  y\n");
    for(int i = 0; i < 8; i++)
    {
        y=nag_bessel_i1_scaled(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x			y

    0.000e+00 	1.000e+00
    5.000e-01 	1.564e-01
    1.000e+00 	2.079e-01
    3.000e+00 	1.968e-01
    6.000e+00 	1.521e-01
    1.000e+01 	1.213e-01
    1.000e+03 	1.261e-02
    -1.000e+00 	-2.079e-01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_i_nu_scaled

Function: nag_bessel_i_nu_scaled
Prototype:
double nag_bessel_i_nu_scaled(double x,int nu,NagError *fail = NULL)
Remarks: returns the value of the scaled modified Bessel function (e^-x)I_nu/4(x).
Parameters:
x
  the argument x of the function.
nu
  the argument nu of the function.

Return values:
This function returns NAG error code, 0 if no error.
118: On entry, x = <value>, nu = <value>.  Constraint: x > 0.0 when nu < 0.  On entry, x = <value>, nu = <value>.  Constraint: x >= 0 when nu > 0 .
90: On entry, nu = <value>.  Constraint: 1<= abs(nu) <=3.
695: The evaluation has been abandoned due to the likelihood of overflow.  The result is returned as zero.
696: The evaluation has been completed but some precision has been lost.
697: The evaluation has been abandoned due to total loss of precision.  The result is returned as zero.
698: The evaluation has been abandoned due to failure to satisfy the termination condition.  The result is returned as zero.
74: An internal error has occured in this function.  Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
successfully call of the nag_bessel_i_nu_scaled function.

Example:
    The example program reads values of the arguments x and v from a file,
    evaluates the function and prints the results

void test_nag_bessel_i_nu_scaled()
{
    double x[] = {3.9, 1.4, 8.2, 6.7, 0.5, 2.3};
    int nu[] = {-3, -2, -1, 1, 2, 3};
    printf("   x	   nu	 y\n");
    for(int i = 0; i < 6; i++)
    {
        double y = nag_bessel_i_nu_scaled(x[i], nu[i]);
        printf("%4.1f %6ld %12.4e\n", x[i], nu[i],  y);
    }
}

    The output is following:

    x		nu			y

    3.9		-3		1.9272e-01
    1.4		-2		3.5767e-01
    8.2		-1		1.4103e-01
    6.7		 1		1.5649e-01
    0.5		 2		3.5664e-01
    2.3		 3		2.3748e-01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_k_nu_scaled

Function: nag_bessel_k_nu_scaled
Prototype:
double nag_bessel_k_nu_scaled(double x,int nu,NagError *fail = NULL)
Remarks: returns the value of the scaled modified Bessel function (e^x)K_nu/4(x) for real x > 0.
Parameters:
x
  the argument x of the function.
nu
  the argument nu of the function.

Return values:
This function returns NAG error code, 0 if no error.
96: On entry, nu = <value>.  Constraint: 1 <= abs(nu) <= 3.
90: On entry, nu = <value>.  Constraint: 1<= abs(nu) <=3.
695: The evaluation has been abandoned due to the likelihood of overflow.  The result is returned as zero.
696: The evaluation has been completed but some precision has been lost.
697: The evaluation has been abandoned due to total loss of precision.  The result is returned as zero.
698: The evaluation has been abandoned due to failure to satisfy the termination condition.  The result is returned as zero.
74: An internal error has occured in this function.  Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
successfully call of the nag_bessel_k_nu_scaled function.

Example:
    The example program reads values of the arguments x and v from a file,
    evaluates the function and prints the results.

void test_nag_bessel_k_nu_scaled()
{
    double x[] = {3.9, 1.4, 8.2, 6.7, 0.5, 2.3};
    int nu[] = {-3, -2, -1, 1, 2, 3};
    printf("   x	   nu	 y\n");
    for(int i = 0; i < 6; i++)
    {
        double y = nag_bessel_k_nu_scaled(x[i], nu[i]);
        printf("%4.1f %6ld %12.4e\n", x[i], nu[i],  y);
    }
}

    The output is following:

    x		nu			y

    3.9		-3		6.5781e-01
    1.4		-2		1.0592e+00
    8.2		-1		4.3297e-01
    6.7		 1		4.7791e-01
    0.5		 2		1.7725e+00
    2.3		 3		8.7497e-01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_i_nu

Function: nag_bessel_i_nu
Prototype:
double nag_bessel_i_nu(double x,int nu,NagError *fail = NULL)
Remarks: returns the value of the modified Bessel function I_nu/4(x) for real x > 0.
Parameters:
x
  the argument x of the function.
nu
  the argument nu of the function.

Return values:
This function returns NAG error code, 0 if no error.
118: On entry, x = <value>, nu = <value>.  Constraint: x > 0 when nu < 0.  On entry, x = <value>, nu = <value>.  Constraint: 1 <= abs(nu) <= 3.
90: On entry, nu = <value>.  Constraint: 1<= abs(nu) <=3.
695: The evaluation has been abandoned due to the likelihood of overflow.  The result is returned as zero.
696: The evaluation has been completed but some precision has been lost.
697: The evaluation has been abandoned due to total loss of precision.  The result is returned as zero.
698: The evaluation has been abandoned due to failure to satisfy the termination condition.  The result is returned as zero.
74: An internal error has occured in this function.  Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
successfully call of the nag_bessel_i_nu function.

Example:
    The example program reads values of the arguments x and v from a file,
    evaluats the function and prints the results.

void test_nag_bessel_i_nu()
{
    double x[] = {3.9, 1.4, 8.2, 6.7, 0.5, 2.3};
    int nu[] = {-3, -2, -1, 1, 2, 3};
    printf("   x	   nu	 y\n");
    for(int i = 0; i < 6; i++)
    {
        double y = nag_bessel_i_nu(x[i], nu[i]);
        printf("%4.1f %6ld %12.4e\n", x[i], nu[i],  y);
    }
}

    The output is following:

    x		nu			y

    3.9		-3		9.5207e+00
    1.4		-2		1.4504e+00
    8.2		-1		5.1349e+02
    6.7		 1		1.2714e+02
    0.5		 2		5.8799e-01
    2.3		 3		2.3687e+00

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_k_nu

Function: nag_bessel_k_nu
Prototype:
double nag_bessel_k_nu(double x,int nu,NagError *fail = NULL)
Remarks: returns the value of the modified Bessel function K_nu/4(x) for real x > 0.
Parameters:
x
  the argument x of the function.
nu
  the argument nu of the function.

Return values:
This function returns NAG error code, 0 if no error.
96: On entry, nu = <value>.  Constraint: 1 <= abs(nu) <= 3.
90: On entry, nu = <value>.  Constraint: 1<= abs(nu) <=3.
695: The evaluation has been abandoned due to the likelihood of overflow.  The result is returned as zero.
696: The evaluation has been completed but some precision has been lost.
697: The evaluation has been abandoned due to total loss of precision.  The result is returned as zero.
698: The evaluation has been abandoned due to failure to satisfy the termination condition.  The result is returned as zero.
74: An internal error has occured in this function.  Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
successfully call of the nag_bessel_k_nu function.

Example:
    The example program reads values of the arguments x and v from a file,
    evaluates the function and prints the results.

void test_nag_bessel_k_nu()
{
    double x[] = {3.9, 1.4, 8.2, 6.7, 0.5, 2.3};
    int nu[] = {-3, -2, -1, 1, 2, 3};
    printf("   x	   nu	 y\n");
    for(int i = 0; i < 6; i++)
    {
        double y = nag_bessel_k_nu(x[i], nu[i]);
        printf("%4.1f %6ld %12.4e\n", x[i], nu[i],  y);
    }
}

    The output is following:

    x		nu			y

    3.9		-3		1.3315e-02
    1.4		-2		2.6121e-01
    8.2		-1		1.1892e-04
    6.7		 1		5.8826e-04
    0.5		 2		1.0750e+00
    2.3		 3		8.7724e-02

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_k_alpha

Function: nag_bessel_k_alpha
Prototype:
int nag_bessel_k_alpha(double x,int ia,int ja,int nl,double b[])
Remarks: returns a sequence of values for the modified Bessel functions K_alpha+n(x) for real x > 0, selected values of apha >= 0 and n = 0, 1, 2, ..., N.
Parameters:
x
  the argument x of the function.
ja
  the numerator i and denominator j, respectively, of the order alpha = i/j of the first member in the rquered sequence of function values.  Only the following combinations of pairs of values of i and j are allowed: (ia,ja) = (0,1), (1,2), (1,3), (1,4), (2,3) or (3,4).
nl
  the value of N.  Note that the order of the last member in the required sequence of function values is given by alpha + N.
b[]
  with fail.code = NE_NOERROR or fail.code = NW_SOME_PRECISION_LOSS, the required sequence of function values: b(n) contains K_alpha+n(x) n = 0, 1, ..., N.

Return values:
This function returns NAG error code, 0 if no error.
96: On entry, nu = <value>.  Constraint: 1 <= abs(nu) <= 3.
90: On entry, nl = <value>.  Constraint: 0<= abs(nl) <= 100.
91: On entry, ia = <value>, ja = <value>.  Constraint: ia and ja must constitue a valid pair (ia, ja).
695: The evaluation has been abandoned due to the likelihood of overflow.
696: The evaluation has been completed but some precision has been lost.
697: The evaluation has been abandoned due to total loss of precision.  .
698: The evaluation has been abandoned due to failure to satisfy the termination condition.
74: An internal error has occured in this function.  Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
successfully call of the nag_bessel_k_alpha function.

Example:
    The example program evaluates k0(x), k1(x), k2(x) and k3(x)
    at x = 0.5 and prints the results.

void test_nag_bessel_k_alpha()
{
    double b[101];
    double x = 0.5;
    int ia = 0;
    int ja = 1;
    int nl = 3;
    printf("x = %4.1f ia = %6ld ja = %6ld nl = %6ld\n\n",x, ia, ja, nl);
    int success;
    nag_bessel_k_alpha(x, ia, ja, nl, b);
    if(success == 0)
    {
        printf("Requested values of K_alpha(X)\n\n");
        double alpha = 1.0 * ia / ja;
        printf("	alpha		K_alpha(X)\n");
        for(int i = 0; i <= nl; i++, alpha+=1.0)
            printf("%12.4e %12.4e \n",alpha, b[i]);
    }
    else
        printf("nag_bessel_k_alpha has some problem");
}

    The output is following:

    x		ia		ja		nl

    0.5		0		1		3

    Requested values of K_alpha(x)

    alpha			K_alpha(x)

    0.0000e+00		9.2552e-01
    1.0000e+00		1.6554e+00
    2.0000e+00		7.5502e+00
    3.0000e+00		6.2058e+01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_kalpha_scaled

Function: nag_bessel_kalpha_scaled
Prototype:
int nag_bessel_kalpha_scaled(double x,int ia,int ja,int nl,double b[])
Remarks: eturns a sequence of values for the modified Bessel functions (e^x)K_alpha+n(x) for real x > 0, selected values of apha >= 0 and n = 0, 1, 2, ..., N.
Parameters:
x
  the argument x of the function.
ja
  the numerator i and denominator j, respectively, of the order alpha = i/j of the first member in the rquered sequence of function values.  Only the following combinations of pairs of values of i and j are allowed: (ia,ja) = (0,1), (1,2), (1,3), (1,4), (2,3) or (3,4).
nl
  the value of N.  Note that the order of the last member in the required sequence of function values is given by alpha + N.
b[]
  with fail.code = NE_NOERROR or fail.code = NW_SOME_PRECISION_LOSS, the required sequence of function values: b(n) contains K_alpha+n(x) n = 0, 1, ..., N.

Return values:
This function returns NAG error code, 0 if no error.
96: On entry, nu = <value>.  Constraint: 1 <= abs(nu) <= 3.
90: On entry, nl = <value>.  Constraint: 0<= abs(nl) <= 100.
91: On entry, ia = <value>, ja = <value>.  Constraint: ia and ja must constitue a valid pair (ia, ja).
695: The evaluation has been abandoned due to the likelihood of overflow.
696: The evaluation has been completed but some precision has been lost.
697: The evaluation has been abandoned due to total loss of precision.  .
698: The evaluation has been abandoned due to failure to satisfy the termination condition.
74: An internal error has occured in this function.  Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
successfully call of the nag_bessel_kalpha_scaled function.

Example:
    The example program evaluates e^xk0(x), e^xk1(x),e^xk2(x) and e^xk3(x)
    at x = 0.5 and prints the results.

void test_nag_bessel_kalpha_scaled()
{
    double b[101];
    double x = 0.5;
    int ia = 0;
    int ja = 1;
    int nl = 3;
    printf("x = %4.1f ia = %6ld ja = %6ld nl = %6ld\n\n",x, ia, ja, nl);
    int success;
    success = nag_bessel_kalpha_scaled(x, ia, ja, nl, b);
    if(success == 0)
    {
        printf("Requested values of K_alpha(X)\n\n");
        double alpha = 1.0 * ia / ja;
        printf("	alpha		K_alpha(X)\n");
        for(int i = 0; i <= nl; i++, alpha+=1.0)
            printf("%12.4e %12.4e \n",alpha, b[i]);
    }
    else
        printf("nag_bessel_k_alpha has some problem");
}

The output is following:

    x		ia		ja		nl

    0.5		0		1		3

    Requested values of K_alpha(x)

    alpha			exp(x)K_alpha(x)

    0.0000e+00		1.5241e-01
    1.0000e+00		2.7310e+00
    2.0000e+00		1.2448e+00
    3.0000e+00		1.0232e+01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_i_alpha

Function: nag_bessel_i_alpha
Prototype:
int nag_bessel_i_alpha(double x,double a,int nl,complex *b)
Remarks: returns a sequence of values for the modified Bessel functions I_alpha+n-1(x) or I_alpha-n+1(x) for real x, non-negative alpha < 1 and n = 1, 2, ..., |N| + 1.
Parameters:
x
  the argument x of the functions.
a
  the order alpha of the first member in the required sequence of function values.
nl
  the value of N.
b
  with fail.code = NE_NOERROR or fail.code = NW_SOME_PRECISION_LOSS, the required sequence of function values: b(n) contains I_alpha+n-1(x) if nl >= 1 and I_alpha-n+1(x) otherwise, for n = 0, 1, ..., abs(nl) + 1.

Return values:

Example:
    The example program evalutes j0(x), j1(x), j2(x) and j3(x) at x = 0.5, and prints the results.

**note this function requires the support of the complex array

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_bessel_j_alpha

Function: nag_bessel_j_alpha
Prototype:
int nag_bessel_j_alpha(double x,double a,int nl,complex b[],NagError *fail = NULL)
Remarks: returns a sequence of values for the Bessel functions J_alpha+n-1(x) or J_alpha-n+1(x) for real x, non-negative alpha < 1 and n = 1, 2, .. , abs(N) +1.
Parameters:
x
  the argument x of the function.
a
  the order alpha of the first member in the required sequence of function values.
nl
  the value of N
b[]
  the dimension, dim1, of the array b must be at least abs(nl) + 1.

Return values:
This function returns NAG error code, 0 if no error.
118: On entry, x = <value>, nl = <value>.  Constraint x not equal 0 when nl < 0.
96: On entry, a = <value>.  Constraint 0 <= a < 1.
90: On entry, nl = <value>. Constraint: abs(nl) <= 101.
695: The evaluation has been abandoned due to the likelihood of overflow.
696: The evaluation has been completed but some precision has been lost.
697: The evaluation has been abandoned due to total loss of precision.
698: The evaluation has been abandoned due to failure to satisfy the termination condition.
74: An internal error has occured in this function.  Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
successfully call of the nag_bessel_j_alpha function.

Example:
    The example program evalutes j0(x), j1(x), j2(x) and j3(x) at x = 0.5, and prints the results.

void test_nag_bessel_j_alpha()
{
    double c_1 = 1.0;
    matrix <complex> b;
    b.SetSize(1,101);
    double a;
    double alpha;
    double d_1;
    double x;
    int i, nl;
    a = 0.0;
    x = 0.5;
    nl = 3;
    printf("%4.1f	%4.1f	%6ld\n\n",x, a, nl);
    if(nag_bessel_j_alpha(x, a, nl, b) == 0)
    {
        printf("\n Requested values of I_alpha(x)\n\n");
        alpha = a;
        printf("	alpha				I_alpha(x)\n");
        for(i = 1; i <= fabs(nl) + 1; i++)
        {
            complex cmTemp = b[0][i-1];
            printf("%12.4e	(%12.4e, %12.4e)\n", alpha, cmTemp.m_re, cmTemp.m_im);
            d_1 = 1.0 * nl;
            if(d_1 > 0)
                alpha = fabs(c_1) + alpha;
            else
                alpha  =  -fabs(c_1) + alpha;
        }
    }
    else
        printf("there is some problem with the fuction");
}

    The output is following:

    x		a		nl
    0.5		0.0		3

    Requested values of J_alpha(x)

        alpha					J_alpha(x)

        0.0000e+00		(9.3847e-01, 0.0000e+00)
        1.0000e+00		(2.4227e-01, 0.0000e+00)
        2.0000e+00		(3.0604e-02, 0.0000e+00)
        3.0000e+00		(2.5637e-03, 0.0000e+00)

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_kelvin_ber

Function: nag_kelvin_ber
Prototype:
double nag_kelvin_ber(double x,NagError *fail = NULL)
Remarks: returns a value for the Kelvin function berx.
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, |x| must not be greater than _value_: x = _value_.  |x| is too large for an accurate result to be returned and the function returns zero.
successfully call of the nag_kelvin_ber function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_kelvin_ber()
{
    double y;
    double x[] ={0.1, 1.0, 2.5, 5.0, 10.0, 15.0, -1.0};
    printf("   x		  y\n");
    for(int i = 0; i < 7; i++)
    {
        y = nag_kelvin_ber(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x 				y
    1.000e-01 		1.000e+00
    1.000e+00 		9.844e-01
    2.500e+00 		4.000e-01
    5.000e+00 	   -6.230e+00
    1.000e+01 		1.388e+02
    1.500e+01 	   -2.967e+03
    -1.000e+00 		9.844e-01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_kelvin_bei

Function: nag_kelvin_bei
Prototype:
double nag_kelvin_bei(double x,NagError *fail = NULL)
Remarks: returns a value for the Kelvin function bei x.
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, |x| must not be greater than _value_: x = _value_.  |x| is too large for an accurate result to be returned and the function returns zero.
successfully call of the nag_kelvin_bei function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.
void test_nag_kelvin_bei()
{
    double y;
    double x[] ={0.1, 1.0, 2.5, 5.0, 10.0, 15.0, -1.0};
    printf("   x		  y\n");
    for(int i = 0; i < 7; i++)
    {
        y = nag_kelvin_bei(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

    x 				y

    1.000e-01 	2.500e-03
    1.000e+00 	2.496e-01
    2.500e+00 	1.457e+00
    5.000e+00	1.160e-01
    1.000e+01 	5.637e+01
    1.500e+01 	-2.953e+03
    -1.000e+00 	2.496e-01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_kelvin_ker

Function: nag_kelvin_ker
Prototype:
double nag_kelvin_ker(double x,NagError *fail = NULL)
Remarks: returns a value for the Kelvin function ker x.
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, x must not be greater than _value_: x = _value_.  x is too large, the result under.ows and the function returns zero.
12: On entry, x must not be less than or equal to 0.0: x = _value_.  The function is undefined and returns zero.
successfully call of the nag_kelvin_ker function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_kelvin_ker()
{
    double y;
    double x[] ={0.1, 1.0, 2.5, 5.0, 10.0, 15.0};
    printf("   x		  y\n");
    for(int i = 0; i < 6; i++)
    {
        y = nag_kelvin_ker(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

    x			 y

    1.000e-01	 2.420e+00
    1.000e+00	 2.867e-01
    2.500e+00	-6.969e-02
    5.000e+00	-1.151e-02
    1.000e+01	 1.295e-04
    1.500e+01	-1.514e-08

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_kelvin_kei

Function: nag_kelvin_kei
Prototype:
double nag_kelvin_kei(double x,NagError *fail = NULL)
Remarks: returns a value for the Kelvin function kei x.
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
7: On entry, x must not be greater than _value_: x = _value_.  x is too large, and the result under.ows and the function returns zero.
11: On entry, x must not be less than 0.0: x = _value_.  The function is undefined and returns zero.
successfully call of the nag_kelvin_kei function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_kelvin_kei()
{
    double y;
    double x[] ={0.1, 1.0, 2.5, 5.0, 10.0, 15.0};
    printf("   x		  y\n");
    for(int i = 0; i < 6; i++)
    {
        y = nag_kelvin_kei(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

    x			 	y

    0.000e+00	 -7.854e-01
    1.000e-01	 -7.769e-01
    1.000e+00	 -4.950e-01
    2.500e+00	 -1.107e-01
    5.000e+00	  1.119e-02
    1.000e+01	 -3.075e-04
    1.500e+01	  7.963e-06

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_fresnel_s

Function: nag_fresnel_s
Prototype:
double nag_fresnel_s(double x)
Remarks: returns a value for the Fresnel Integral S(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
successfully call of the nag_fresnel_s function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_fresnel_s()
{
    double y;
    double x[] ={0.1, 1.0, 2.5, 5.0, 10.0, 15.0};
    printf("   x		  y\n");
    for(int i = 0; i < 6; i++)
    {
        y = nag_fresnel_s(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

        x			 y

     1.000e-001  5.236e-004
     1.000e+000  4.383e-001
     2.500e+000  6.192e-001
     5.000e+000  4.992e-001
     1.000e+001  4.682e-001
     1.500e+001  5.000e-001

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_fresnel_c

Function: nag_fresnel_c
Prototype:
double nag_fresnel_c(double x)
Remarks: returns a value for the Fresnel Integral C(x).
Parameters:
x
  the argument x of the function.

Return values:
This function returns NAG error code, 0 if no error.
successfully call of the nag_fresnel_c function.

Example:
    The following program reads values of the argument x from a file,
    evaluates the function at each value of x and prints the results.

void test_nag_fresnel_c()
{
    double  y;
    double x[] ={0.0, 0.5, 1.0, 2.0, 4.0, 5.0, 6.0, 8.0, 10.0, -1.0, 1000.0};

    printf("   x		  y\n");
    for(int i = 0; i < 11; i++)
    {
        y = nag_fresnel_c(x[i]);
        printf("%12.3e%12.3e\n", x[i], y);
    }
}

    The output is following:

         x 			y

     0.000e+00 	  0.000e+00
     5.000e-01	  4.923e-01
     1.000e+00	  7.799e-01
     2.000e+00	  4.883e-01
     4.000e+00	  4.984e-01
     5.000e+00	  5.636e-01
     6.000e+00	  4.995e-01
     8.000e+00	  4.998e-01
     1.000e+01 	  4.999e-01
    -1.000e+00 	 -7.799e-01
     1.000e+03 	  5.000e-01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_elliptic_integral_rc

Function: nag_elliptic_integral_rc
Prototype:
double nag_elliptic_integral_rc(double x,double y,NagError *fail = NULL)
Remarks: returns a value of an elementary integral, which occurs as a degenerate case of an elliptic integral of the first kind.
Parameters:
x
  the argument x of the function.
y
  the argument y of the function.

Return values:
This function returns NAG error code, 0 if no error.
5: On entry, x must not be less than 0.0: x = _value_.  The function is undefined.
10: On entry, y must not be equal to 0.0: y = _value_.  The function is undefined and returns zero.
successfully call of the nag_elliptic_integral_rc function.

Example:
    This example program simply generates a small set of non-extreme arguments
    which are used with the function to produce the table of low accuracy results.

void test_nag_elliptic_integral_rc()
{
    double rc, x, y;
    int ix;
    printf(" x y s21bac \n");
    for (ix=1; ix<=3; ix++)
    {
        x = ix*0.5;
        y = 1.0;
        rc = nag_elliptic_integral_rc(x, y);
        printf("%7.2f%7.2f%12.4f\n", x, y, rc);
    }
}

    The output is following:

    x 	   	  y 	s21bac

    0.50 	1.00 	1.1107
    1.00 	1.00	1.0000
    1.50 	1.00 	0.9312

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_elliptic_integral_rf

Function: nag_elliptic_integral_rf
Prototype:
double nag_elliptic_integral_rf(double x,double y,double z,NagError *fail = NULL)
Remarks: returns a value of the symmetrised elliptic integral of the first kind.
Parameters:
x
  the argument x of the function.
y
  the argument y of the function.
z
  the argument z of the function.

Return values:
This function returns NAG error code, 0 if no error.
5: On entry, x must not be less than 0.0: x = _value_.  On entry, y must not be less than 0.0: y = _value_.  On entry, z must not be less than 0.0: z = _value_. The function is undefined.
10: On entry, _parameters_ must not be equal to 0.0: _parameters_ = _value_.  On entry,t wo or more of x, y and z are zero; the function is undefined and the function returns zero.
successfully call of the nag_elliptic_integral_rf function.

Example:
    This example program simply generates a small set of non-extreme arguments
    which are used with the function to produce the table of low accuracy results

void test_nag_elliptic_integral_rf()
{
    double rf, x, y, z;
    int ix;
    printf(" x y z s21bbc\n");
    for (ix=1; ix<=3; ix++)
    {
        x = ix*0.5;
        y = (ix+1)*0.5;
        z = (ix+2)*0.5;
        rf = nag_elliptic_integral_rf(x, y, z);
        printf("%7.2f%7.2f%7.2f%12.4f\n", x, y, z, rf);
    }
}

    The output is following:

    x 		y 		z 		s21bbc

    0.50 	1.00 	1.50 	1.0281
    1.00 	1.50 	2.00 	0.8260
    1.50 	2.00 	2.50 	0.7116

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_elliptic_integral_rd

Function: nag_elliptic_integral_rd
Prototype:
double nag_elliptic_integral_rd(double x,double y,double z,NagError *fail = NULL)
Remarks: returns a value of the symmetrised elliptic integral of the second kind.
Parameters:
x
  the argument x of the function.
y
  the argument y of the function.
z
  the argument z of the function.

Return values:
This function returns NAG error code, 0 if no error.
5: On entry, x must not be less than 0.0: x = _value_.  On entry, y must not be less than 0.0: y = _value_.  The function is undefined. On entry, _parameters_ must not be less than _value_: _parameters_ = _value_.  On entry, either z is too close to zero or both x and y are too close to zero: there is a danger of setting overflow.
10: On entry, x+y must not be equal to 0.0: x+y = _value_.  Both x and y are zero and the function is undefined.
6: On entry, z must not be less than or equal to 0.0: z = _value_.  The function is undefined.
8: On entry, x must not be greater than or equal to _value_: x = _value_.  On entry, y must not be greater than or equal to _value_: y = _value_.  On entry, z must not be greater than or equal to _value_: z = _value_.  There is a danger of setting under.ow and the function returns zero.
successfully call of the nag_elliptic_integral_rd function.

Example:
    This example program simply generates a small set of non-extreme arguments
    which are used with the function to produce the table of low accuracy results.

void test_nag_elliptic_integral_rd()
{
    double rd, x, y, z;
    int ix, iy;
    printf (" x y z s21bcc \n");
    for ( ix=1; ix<=3; ix++)
    {
        x = ix*0.5;
        for (iy=ix; iy<=3; iy++)
        {
            y = iy*0.5;
            z = 1.0;
            rd = nag_elliptic_integral_rd(x, y, z);
            printf (" %7.2f%7.2f%7.2f%12.4f\n", x, y, z, rd);
        }
    }
}

    The output is following:

    x 		y 		z 		s21bcc

    0.50 	0.50 	1.00 	1.4787
    0.50 	1.00 	1.00 	1.2108
    0.50 	1.50 	1.00 	1.0611
    1.00 	1.00 	1.00 	1.0000
    1.00 	1.50 	1.00 	0.8805
    1.50 	1.50 	1.00 	0.7775

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_elliptic_integral_rj

Function: nag_elliptic_integral_rj
Prototype:
double nag_elliptic_integral_rj(double x,double y,double z,double r,NagError *fail = NULL)
Remarks: returns a value of the symmetrised elliptic integral of the third kind.
Parameters:
x
  the argument x of the function.
y
  the argument y of the function.
z
  the argument z of the function.
r
  the argument rho of the function.

Return values:
This function returns NAG error code, 0 if no error.
5: On entry, x must not be less than 0.0: x = _value_.  On entry, y must not be less than 0.0: y = _value_.  On entry, z must not be less than 0.0: z = _value_.  The function is undefined.  On entry, _parameters_ must not be less than _value_: _parameters_ = _value_.  On entry, either r is too close to zero, or any two of x, y and z are too close to zero; there is a danger of setting overflow.
10: On entry, _parameters_ must not be equal to 0.0: _parameters_ = _value_.  At least two of x, y and z are zero and the function is undefined.  On entry, r must not be equal to 0.0: r = _value_.  The function is undefined.
7: On entry, x must not be greater than _value_: x = _value_.  On entry, y must not be greater than _value_: y = _value_.  On entry, z must not be greater than _value_: z = _value_.  On entry, |r| must not be greater than _value_: |r| = _value_.
successfully call of the nag_elliptic_integral_rj function.

Example:
    This example program simply generates a small set of non-extreme arguments
    which are used with the function to produce the table of low accuracy results.

void test_nag_elliptic_integral_rj()
{
    double r, rj, x, y, z;
    int ix, iy, iz;
    printf(" x y z r s21bdc \n");
    for (ix = 1; ix <= 3; ix++)
    {
        x = ix*0.5;
        for ( iy=ix; iy<=3; iy++)
        {
            y = iy*0.5;
            for ( iz=iy; iz<=3; iz++)
            {
                z = iz*0.5;
                r = 2.0;
                rj = nag_elliptic_integral_rj(x, y, z, r);
                printf (" %7.2f%7.2f%7.2f%7.2f%12.4f\n", x, y, z, r, rj);
            }
        }
    }
}

    The output is following:

    x 		y 		z 		r 		s21bdc

    0.50 	0.50 	0.50 	2.00 	1.1184
    0.50 	0.50 	1.00 	2.00 	0.9221
    0.50 	0.50 	1.50 	2.00 	0.8115
    0.50 	1.00 	1.00 	2.00 	0.7671
    0.50 	1.00 	1.50 	2.00 	0.6784
    0.50 	1.50 	1.50 	2.00 	0.6017
    1.00 	1.00 	1.00 	2.00 	0.6438
    1.00 	1.00 	1.50 	2.00 	0.5722
    1.00 	1.50 	1.50 	2.00 	0.5101
    1.50 	1.50 	1.50 	2.00 	0.4561

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_jacobian_elliptic

Function: nag_jacobian_elliptic
Prototype:
int nag_jacobian_elliptic(complex z,double ak2,complex *sn,complex *cn,complex *dn)
Remarks: evaluates the Jacobian elliptic functions snz, cnz, and dnz for a complex argument z.
Parameters:
z
  the argument z of the function.
ak2
  the value of k^2.
sn
  the value of the functions snz.
cn
  the value of the functions cnz.
dn
  the value of the functions dnz.

Return values:
This function returns NAG error code, 0 if no error.
96: On entry, ak2 = <value>.  Constraint: 0 <= ak2 <= 1
102: On entry, z = (<value>, <value>).  Constraint: abs(z.ro) <= lamda and abs(z.im) <= lamda, where lamda = (1/X02AMC)^(1/2).
74: An internal error has occurred in this function.  Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
successfully call of the nag_jacobian_elliptic function.

Example:
    The program evaluates snz, cnz, and dnz at z = -2.0+3.0i
    when k = 0.5 and prints the results

void test_nag_jacobian_elliptic()
{
    complex cn, dn, sn, z;
    double ak2;

    z = -2.0 + 3.0i;
    ak2 = 0.25;
    nag_jacobian_elliptic(z, ak2, &sn, &cn, &dn);
    printf("		z			ak2\n");
    printf(" (%8.4f,%8.4f)	%10.2f\n\n",z.m_re,z.m_im, ak2);
    printf("	sn				cn				dn\n ");
    printf("(%8.4f, %8.4f)	",sn.m_re, sn.m_im);
    printf("(%8.4f, %8.4f)	",cn.m_re, cn.m_im);
    printf("(%8.4f, %8.4f)	",dn.m_re, dn.m_im);
    printf("\n");
}

    The output is following:

        z							ak2

    (-2.0000, 3.0000)				0.25

        sn						cn				dn

    (-1.5865, 0.2456)	(0.3125, 1.2468)	(-0.6395, -0.1523)

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_jacobian_theta

Function: nag_jacobian_theta
Prototype:
double nag_jacobian_theta(int k,double x,double q,NagError *fail = NULL)
Remarks: returns the value of one of the Jacobian theta functions theta_0(x,q), theta_0(x,q), theta_1(x,q), theta_2(x,q), theta_3(x,q), or theta_0(x,q) for a real argument x and non-negative q <= 1.
Parameters:
k
  the function theta_k(x,q) to be evaluated.  Note that k = 4 is equivalent to k = 0.
x
  the argument x of the function.
q
  the argument q of the function.

Return values:
This function returns NAG error code, 0 if no error.
90: On entry, k = <value>.  Constraint: 0 <= k <= 4.
96: On entry, q = <value>.  Constraint: 0 <= q <= 1.  On entry, x = <value>.  Constraint: (x - 0.5) must not be an integer when q = 1 and k = 1. On entry, x = <value>.  Constraint: x must not be an integer when q = 1 and k = 2.
699: The evaluation has been abandoned because the function value is infinite.
74: An internal error has occurred in this function.  Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
successfully call of the nag_jacobian_theta function.

Example:
    The example program evaluates theta(x,q) at x =0.7
    when q = 0.4, and prints the results.

void test_nag_jacobian_theta()
{
    double q, x, y;
    int k;

    k = 2;
    x = 0.7;
    q = 0.4;
    y  = nag_jacobian_theta(k, x, q);
    printf("%d	%f	%f	%10.4e", k, x, q, y);
}

    The output is following:

    k		x		q			y

    2		0.7		0.4		-6.9289e-01

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_elliptic_integral_f

Function: nag_elliptic_integral_f
Prototype:
complex nag_elliptic_integral_f(complex z,double akp,double a,double b,NagError *fail = NULL)
Remarks: returns the value of the general elliptic integral of the second kind F(z, k',a,b) for a complex argument z.
Parameters:
z
  the argument z of the function.
akp
  the argument k' of the function.
a
  the argument a of the function.
b
  the argument b of the function.

Return values:
This function returns NAG error code, 0 if no error.
102: On entry, z = (<value>,<value>). Constraints: 0 <= zire <= lamda, |z.im| <= lamda, where lamda^6 = 1/X02AMC.
700: The iterative procedure used to evaluate the integral has failed to converge.  The result is returned as zero.
74: An internal error has occurred in this function.  Check the function call and any array sizes.  If the call is correct then please consult NAG for assistance.
successfully call of the nag_elliptic_integral_f function.

Example:
    The example program evaluates the elliptic integral of the first kind
    F1(z,k') given by where z = 1.2 + 3.7i; and k' = 0.5, and prints the results.

void test_nag_elliptic_integral_f()
{
     complex y;
     matrix<complex> z;
     z.SetSize(1,2);
     double a[2], akp[2], b[2];

     z[0][0] = 1.2 + 3.7i;
     z[0][1] = 9.2 - 3.4i;
     akp[0] = 0.5;
     akp[1] = 0.8;
     a[0] = 1.0;
     a[1] = 0.4;

     b[0] = 1.0;
     b[1] = 2.7;
     for(int i = 0; i < 2; i++)
     {
         complex temp = z[0][i];

          y =  nag_elliptic_integral_f(temp, akp[i], a[i], b[i]);

        printf("(%4.1f,	%4.1f)	%7.1f	%7.1f	%7.1f	(%12.4e,	%12.4e)\n",temp.m_re, temp.m_im, akp[i], a[i], b[i], y.m_re, y.m_im);
     }
}

    The output is following:

    z				akp		a		b			y

    (1.2, 3.7)		0.5		1.0		1.0		(1.9713e+00, 5.0538e-01)
    (9.2, -3.4)		0.8		0.4		2.7		(2.5042e+00,-1.1709e-01)

Summary:
Sample data:
Header file: OCN_s.h
See also:


nag_legendre_p

Function: nag_legendre_p
Prototype:
int nag_legendre_p(int mode,double x,int m,int nl,double p[])
Remarks: returns a sequence of values for either the unnormalized or normalized Legendre functions of the first kind P_m_n(x) or _P_m_n(x) for real x of a given order m and degree n = 0, 1, ..., N.
Parameters:
mode
  indicates whether the sequence of function values is to be returned unnormalized or normalized as follows: if mode = 1, then the sequence of function values is returned unnormalized; if mode = 2, then the sequence of function values is returned normalized.
x
  the argument x of the function.
m
  the order m of the function.
nl
  the degree N of the last function required in the sequence.
p[]
  the required sequence of function values as follows: if mode = 1, p(n) contains P_m_n(x), for n = 0, 1, ..., N.  if mode = 2, p(n) contains _P_m_n(x),for n = 0, 1, ..., N.

Return values:
This function returns NAG error code, 0 if no error.
96: On entry, x = <value>.  Constraint: abs(x) <= 1.
90: On entry, mode = <value>.  Constraint: mode = 1 or 2.  On entry, nl = <value>.  Constraint: nl >= 0.  On entry, m = <value>.  Constraint: abs(m) <= 27.
91: On entry, nl = <value>, m = <value>.  Constraint: nl <= 100 when m = 0. On entry, nl = <value>, m = <value>.  Constraint: nl <= 55 - abs(m) when m not equal 0.
successfully call of the nag_legendre_p function.

Example:
    The following program reads the values of the arguments x, m, N, calculates the sequence
    of unnormalized assocaited Legendre function values P and prints out the results.

void test_nag_legendre_p()
{
    int m, n, nl, mode;
    double x;
    double p[101];
    mode = 1;
    x = 0.5;
    m = 2;
    nl = 3;
    nag_legendre_p(mode, x, m, nl, p);
    printf("mode	x	m	nl\n\n");
    printf("%3ld	%5.2f%6ld%6ld\n\n",mode, x, m, nl);
    printf("Unnormalized associated Legendre function values\n");
    printf("\n");
    printf("\n	P(n)\n");
    for(n = 0; n <= nl; n++)
        printf("%2ld %12.4e\n", n, p[n]);
}

    The output is following:

    mode	x		m		nl

    1		0.5		2		3

    Unnormalized associated Legendre function values

    n			P(n)

    0		0.0000e+00
    1		0.0000e+00
    2		2.2500e+00
    3		5.6250e+00

Summary:
Sample data:
Header file: OCN_s.h
See also:


Matlab

Class: Matlab

Description: Matlab class provides communication between Origin and Matlab.

Hierarchy:

Matlab

Sample:

        #include <origin.h>
        #include <externApps.h> // this file is not included in origin.h
        ////////////////////////////////////////////////////////////////////////////////////

        void mltest()
        {
            Matlab matObj;
            if(!matObj)
            {
                out_str("No Matlab found");
                return;
            }

            //defines 3x5 matrix named ma
            string strRet = matObj.Execute("ma=[1 2 3 4 5; 4 5 6 7 8;10.3 4.5 -4.7 -23.2 -6.7]");
            out_str(strRet);// show str from Matlab

            // put matrix into Origin matrix
            MatrixLayer matLayer;
            matLayer.Create();
            Matrix mao(matLayer);

            //Transfer Matlab's matrix (ma) to Origin's mao matrix.
            BOOL bRet = matObj.GetMatrix("ma", &mao);
        }


Attach

Matlab::Attach
Prototype:
PUBLIC  BOOL Attach( BOOL bUseRunningInstance=TRUE, BOOL bSingle = FALSE, BOOL bKeepMatlabRunning = FALSE )
Remarks: Establishes connection to Matlab.
Parameters:
bUseRunningInstance=if TRUE (default) attempt is made to reuse already established connection.
If that is not possible, or if the parameter is FALSE, new connection is made.

Return values:
Returns TRUE if connection is being made, FALSE otherwise.

Example:
            // Assumes	Matlab object successfully created.
            if ( !matObj.Attach() ) return;	//return if connection can not be made
            matObj.Attach(FALSE);			//Establish new connection destroying any previous connection first

Summary:
Sample data:
Header file: ExternApps.h
See also: Detach


Detach

Matlab::Detach
Prototype:
PUBLIC  BOOL Detach()
Remarks: Destroys the connection with Matlab
Parameters:

Return values:
Returns TRUE if connection is being destroyed, FALSE if the operation failed.

Example:
            // Assumes	Matlab object successfully created, and communication established
            matObj.Detach();	//destroys the connection

            matObj.Detach();
            matObj.Attach()		//the same effect as matObj.Attach(FALSE);

Summary:
Sample data:
Header file: ExternApps.h
See also: Attach


Execute

Matlab::Execute
Prototype:
PUBLIC  string Execute(LPCSTR lpcszCommand)
Remarks: Executes command in Matlab workspace
Parameters:
lpcszCommand=Matlab command to execute.

Return values:
Returns the string containing Matlab command window output.
//Comment: ";" at the end of the command suppresses output in Matlab.

Example:
            // Assumes	Matlab object successfully created, i.e. communication established
            string strRet = matObj.Execute("ma=[1 2 3; 4 5 6]");	//defines 2x3 matrix named ma
            string strRet = matObj.Execute("filename");				//runs Matlab's script filename.m if in Matlab's search path

Summary:
Sample data:
Header file: ExternApps.h
See also:
Matlab::Execute
Prototype:
PUBLIC  BOOL Execute(LPCSTR lpcszCommand, string &strReturn)
Remarks: Executes command in Matlab workspace
Parameters:
lpcszCommand=Matlab command to execute.
strRet=string to receive Matlab output,
or OriginC output "??? FAILED TO EXECUTE MAtlab" if execution failed

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Assumes	Matlab object successfully created, i.e. communication established
            string strRet;
            BOOL bRet = matObj.Execute("ma=[1 2 3; 4 5 6]", strRet);	//defines 2x3 matrix named ma
            out_str(strRet);

Summary:
Sample data:
Header file: ExternApps.h
See also:


GetMatrix

Matlab::GetMatrix
Prototype:
PUBLIC  BOOL GetMatrix(LPCSTR lpcszMatrixName, Matrix *pmmReal, Matrix *pmmImag = NULL, LPCSTR lpcszMatLabWorkspace = NULL)
Remarks: Transfer Matlab matrix to Origin Matrix. OriginC matrix not currently supported.
Parameters:
lpcszMatrixName=The name of the Matlab matrix source
pmmReal=Origin matrix as destination for the data
pmmImag=To receive complex matrix from Matlab, define Origin matrices for real and imaginary parts. Currently not implemented -
leave without this optional argument, or set NULL to access the fourth parameter
lpcszMatLabWorkspace=default value "base" defines lpcszMatrixName in default Matlab workspace. The use of "global" for global Matlab workspace is not currently supported

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Assumes	Matlab object successfully created, i.e. communication established
            //			Matrix1 exists in Origin
            Matrix mReal("Matrix1");
            BOOL bRet = matObj.GetMatrix("mat", &mReal);				//Transfer mat Matlab's matrix to mReal.

Summary:
Sample data:
Header file: ExternApps.h
See also: PutMatrix


GetString

Matlab::GetString
Prototype:
PUBLIC  string GetString( LPCSTR lpcszStringName, LPCSTR lpcszMatLabWorkspace = NULL )
Remarks: Transfer Matlab character array to Origin string.
Parameters:
lpcszStringName=The name of the Matlab character array source
lpcszMatLabWorkspace=default value "base" defines lpcszMatrixName in default Matlab workspace. The use of "global" for global Matlab workspace is not currently supported

Return values:
Returns Matlab's character array as a string.

Example:
            // Assumes	Matlab object successfully created, i.e. communication established
            string strMcharname;
            strMcharname = matObj.GetString( "mcharname", "base" );

Summary:
Sample data:
Header file: ExternApps.h
See also: PutString


Matlab

Matlab::Matlab
Prototype:
PUBLIC  Matlab( BOOL bAttach = TRUE, BOOL bSingle = FALSE, BOOL bKeepMatlabRunning = FALSE )
Remarks: Constructor for Matlab class. It will connect to Matlab if called with default argument(TRUE).
Parameters:

Return values:

Example:
            //Assumes Matlab version R12 or greater is installed on client's computer (DCOM not tested)
            Matlab matObj; 					// Use constructor to create Origin C Matlab object
            if (!matObj) return FALSE;		//return FALSE if communication is not established
            Matlab matObj0(FALSE);			//Use to create Origin C Matlab object without connecting to Matlab.
            matObj0.Attach();				//To actually connect to Matlab, Attach() have to be called.

Summary: Constructor for Matlab class.
Sample data:
Header file: ExternApps.h
See also: Attach


MinimizeCommandWindow

Matlab::MinimizeCommandWindow
Prototype:
PUBLIC  void MinimizeCommandWindow()
Remarks: Minimizes Matlab command window.
Parameters:

Return values:

Example:
            // Assumes	Matlab object successfully created, i.e. communication established
            matObj.MinimizeCommandWindow();

Summary:
Sample data:
Header file: ExternApps.h
See also: MaximizeCommandWindow


PutMatrix

Matlab::PutMatrix
Prototype:
PUBLIC  BOOL PutMatrix(LPCSTR lpcszMatrixName, Matrix *pmmReal, Matrix *pmmImag = NULL, LPCSTR lpcszMatLabWorkspace = NULL)
Remarks: Transfer Origin Matrix to Matlab matrix. OriginC matrix not currently supported. Complex matrices not currently supported
Parameters:
lpcszMatrixName=The name of the Matlab matrix to receive the data
pmmReal=Origin matrix is the source of the data
pmmImag=To create complex matrix in Matlab, define Origin matrices for real and imaginary parts
lpcszMatLabWorkspace=default value "base" defines lpcszMatrixName in default Matlab workspace. The use of "global" for global Matlab workspace is not currently supported

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Assumes	Matlab object successfully created, i.e. communication established
            //			Matrix1 with sample data exists in Origin
            Matrix mReal("Matrix1");
            BOOL bRet = matObj.PutMatrix("mat", &mReal);				//Transfer mReal data to mat Matlab's matrix. mat will be created if it didn't exist before
            if (bRet)
                string strRet = matObj.Execute("mat");				//strRet will contain display of mat

Summary:
Sample data:
Header file: ExternApps.h
See also: GetMatrix


PutString

Matlab::PutString
Prototype:
PUBLIC  BOOL PutString( LPCSTR lpcszStringName, LPCSTR lpcszString, LPCSTR lpcszMatLabWorkspace = NULL )
Remarks: Transfer Origin string to Matlab character array.
Parameters:
lpcszStringName=The name of the Matlab character array source
lpcszMatLabWorkspace=default value "base" defines lpcszMatrixName in default Matlab workspace. The use of "global" for global Matlab workspace is not currently supported

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Assumes	Matlab object successfully created, i.e. communication established
            matObj.PutString( "mcharname", "OC::Matlab Origin Text", "base" );

Summary:
Sample data:
Header file: ExternApps.h
See also: GetString


CategoricalData

Class: CategoricalData

Description: An Origin C CategoricalData data set is a dynamically allocated and sized array of integers that is tied to an internal Origin data set of type Text. A CategoricalData data set maps the text values in the data to categories referenced by an index (1 based offset). The text value to index map is stored in the CategoricalMap data member. Origin currently supports Ordinal maps in which items are sorted (ordered) alphanumerically. If a non-Text worksheet column in Origin is attached to it will be converted to type Text. When non-Text columns are converted to Text only displayed digits are converted thus precision may be lost if all digits are not displayed in the worksheet. When non-Text columns contain numeric data attaching a CategoricalData data set prompts with a novice dialog box asking the user whether or not to proceed. If the user selects "No" (do not proceed) the conversion to text does not occur and the resulting CategoricalData object is invalid. The CategoricalData class is derived from the Dataset, vector, and vectorbase classes from which it inherits methods and properties.

Hierarchy:

vectorbase
 vector
 Dataset
 CategoricalData

Sample:

        // Worksheet column Data1_A must exist prior to execution
        StringArray vMyCatMap;
        CategoricalData cdMyCatData("Data1_A");
        CategoricalMap cmMyCatMap;
        cmMyCatMap = cdMyCatData.Map;
        vMyCatMap = (StringArray) cmMyCatMap; // Requires explicit cast


Attach

CategoricalData::Attach
Prototype:
PUBLIC  BOOL Attach(LPCSTR lpcszDatasetName, UINT wType)
Remarks: Attach a CategoricalData object to an internal Origin data set by name.
Parameters:
lpcszDatasetName=Input name of internal Origin data set
wType=Input type of CategoricalMap (only CMT_ORDINAL is supported)

Return values:

Example:
            // Worksheet column Data1_A must exist and contain the sample data
            StringArray vMyCatMap;
            CategoricalData cdMyCatData;
            cdMyCatData.Attach("Data1_A",CMT_ORDINAL);
            vMyCatMap = (StringArray) cdMyCatData.Map; // Requires explicit cast

Summary: Attach a CategoricalData object to an internal Origin data set
Sample data: aaa bbb ddd ccc
Header file: vector.h
See also: CategoricalData
CategoricalData::Attach
Prototype:
PUBLIC  BOOL Attach(LPCSTR lpcszWksName, UINT wColumnNumber, UINT wType)
Remarks: Attach a CategoricalData object to an internal Origin data set by worksheet name and column number.
Parameters:
lpcszWksName=Input name of internal Origin worksheet
wColumnNumber=Input column number in worksheet
wType=Input type of CategoricalMap (only CMT_ORDINAL is supported)

Return values:

Example:
            // Worksheet column Data1_A must exist and contain the sample data
            StringArray vMyCatMap;
            CategoricalData cdMyCatData;
            cdMyCatData.Attach("Data1",0,CMT_ORDINAL);
            vMyCatMap = (StringArray) cdMyCatData.Map; // Requires explicit cast

Summary: Attach a CategoricalData object to an internal Origin data set by worksheet name and column number.
Sample data: aaa bbb ddd ccc
Header file: vector.h
See also: Attach


CategoricalData

CategoricalData::CategoricalData
Prototype:
PUBLIC  CategoricalData(LPCSTR lpcszWksName, UINT wColumnNumber, UINT wType)
Remarks: Constructor to create a CategoricalData object and attach it to an internal Origin data set by worksheet name and column number.
Parameters:
lpcszWksName=Input name of internal Origin worksheet
wColumnNumber=Input column number in worksheet
wType=Input type of CategoricalMap (only CMT_ORDINAL is supported)

Return values:

Example:
            // Worksheet column Data1_A must exist and contain the sample data
            StringArray vMyCatMap;
            CategoricalData cdMyCatData("Data1",0,CMT_ORDINAL);
            vMyCatMap = (StringArray) cdMyCatData.Map; // Requires explicit cast

Summary: Constructor to create a CategoricalData object by worksheet name and column number.
Sample data: aaa bbb ddd ccc
Header file: vector.h
See also: Attach
CategoricalData::CategoricalData
Prototype:
PUBLIC  CategoricalData()
Remarks: Default constructor to create a CategoricalData object.
Parameters:

Return values:

Example:
            // Worksheet column Data1_A must exist and contain the sample data
            StringArray vMyCatMap;
            CategoricalData cdMyCatData;
            cdMyCatData.Attach("Data1_A",CMT_ORDINAL);
            vMyCatMap = (StringArray) cdMyCatData.Map; // Requires explicit cast

Summary: Default constructor to create a CategoricalData object.
Sample data: aaa bbb ddd ccc
Header file: vector.h
See also: Attach
CategoricalData::CategoricalData
Prototype:
PUBLIC  CategoricalData(LPCSTR lpcszDatasetName, UINT wType = CMT_ORDINAL)
Remarks: Constructor to create a CategoricalData object and attach it to an internal Origin data set by name.
Parameters:
lpcszDatasetName=Input name of internal Origin data set
wType=Input type of CategoricalMap (only default CMT_ORDINAL is supported)

Return values:

Example:
            // Worksheet column Data1_A must exist and contain the sample data
            StringArray vMyCatMap;
            CategoricalData cdMyCatData("Data1_A");
            vMyCatMap = (StringArray) cdMyCatData.Map; // Requires explicit cast

Summary: Constructor to create a CategoricalData object by data set name.
Sample data: aaa bbb ddd ccc
Header file: vector.h
See also: Attach


Group

CategoricalData::Group
Prototype:
PUBLIC  int Group( vector& vIn, matrix& mOut, vector<int>& vColumnSize )
Remarks: Sort an input vector into columns in a matrix by this CategoricalData data set. Each value in the input vector is sorted into the column of the matrix having the 1 based column number equal to its paired index value in this CategoricalData data set. The input vector and this CategoricalData data set must have the same number of elements. The matrix will be dynamically sized having the same number of columns as there are unique index values in the CategoricalData data set and having as many rows as are necessary to hold the largest group of sorted values. An Output vector gives the number of grouped values in each column. This method is currently implemented only for input vectors having an underlying base type of double.
Parameters:
vIn=The input data to be sorted into groups by this CategoricalData set
mOut=The output matrix sorted into groups
vColumnSize=Vector containing the number of data points in each group (column of the matrix)

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            // Assumes worksheet Data1 and matrix Matrix1 exist in Origin
            // Data1_A and Data1_B should have following data
            // Data1_A = {Tic, Tic, Tac, Toe, Tic, Toe, Tac}
            // Data1_B = {1,2,3,4,5,6,7};
            CategoricalData cdMyData("Data1_A");
            Dataset dsIn("Data1_B");
            Matrix mOut("Matrix1");
            vector<int> vCounts;
            int ii;
            StringArray vMyMap;
            cdMyData.Group( dsIn, mOut, vCounts );
            vMyMap = (StringArray) cdMyData.Map;
            for( ii = 0; ii < vCounts.GetSize(); ii++ )
                printf("Column %d ('%s' group) has %d values\n", ii+1, vMyMap[ii], vCounts[ii] );

Summary: Sort an input vector into columns in a matrix by this CategoricalData set.
Sample data:
Header file: vector.h
See also:


CategoricalMap

Class: CategoricalMap

Description: An Origin C CategoricalMap is a dynamically allocated and sized array of text values that is not tied to an internal Origin data set. A CategoricalMap contains a set of unique and alpha-numerically sorted text values which are typically referenced by the elements of an associated object of type CategoricalData. The CategoricalMap class contains additional class methods and is not derived from the vector<string> class so an object of type CategoricalMap is not technically equivalent to an object of type vector<string> but the data elements of each are functionally equivalent and the types can be explicitly cast.

Hierarchy:

CategoricalMap

Sample:

        // Worksheet column Data1_A must exist prior to execution
        StringArray vMyCatMap;
        CategoricalData cdMyCatData("Data1_A");
        CategoricalMap cmMyCatMap;
        cmMyCatMap = cdMyCatData.Map;
        vMyCatMap = (StringArray) cmMyCatMap; // Requires explicit cast


ArrangeAZ

CategoricalMap::ArrangeAZ
Prototype:
PUBLIC  void ArrangeAZ()
Remarks: Sort this CategoricalMap in ascending order.
Parameters:

Return values:

Example:
            // Worksheet column Data1_A must exist and contain data prior to execution
            StringArray vMyCatMap;
            CategoricalData cdMyCatData("Data1_A");
            vMyCatMap = (StringArray) cdMyCatData.Map; // CategoricalMap is sorted in ascending order by default
            cdMyCatData.Map.ArrangeZA();               // Sort CategoricalMap in descending order
            vMyCatMap = (StringArray) cdMyCatData.Map;
            cdMyCatData.Map.ArrangeAZ();               // Sort CategoricalMap in ascending order
            vMyCatMap = (StringArray) cdMyCatData.Map;

Summary: Sort this CategoricalMap in ascending order.
Sample data:
Header file: vector.h
See also: ArrangeZA


ArrangeZA

CategoricalMap::ArrangeZA
Prototype:
PUBLIC  void ArrangeZA()
Remarks: Sort this CategoricalMap in descending order.
Parameters:

Return values:

Example:
            // Worksheet column Data1_A must exist and contain data prior to execution
            StringArray vMyCatMap;
            CategoricalData cdMyCatData("Data1_A");
            vMyCatMap = (StringArray) cdMyCatData.Map; // CategoricalMap is sorted in ascending order by default
            cdMyCatData.Map.ArrangeZA();               // Sort CategoricalMap in descending order
            vMyCatMap = (StringArray) cdMyCatData.Map;
            cdMyCatData.Map.ArrangeAZ();               // Sort CategoricalMap in ascending order
            vMyCatMap = (StringArray) cdMyCatData.Map;

Summary: Sort this CategoricalMap in descending order.
Sample data:
Header file: vector.h
See also: ArrangeAZ


CategoricalMap

CategoricalMap::CategoricalMap
Prototype:
PUBLIC  CategoricalMap()
Remarks: Default constructor to create an Origin C CategoricalMap object.
Parameters:

Return values:

Example:
            // Worksheet column Data1_A must exist prior to execution
            StringArray vMyCatMap;
            CategoricalData cdMyCatData("Data1_A");
            CategoricalMap cmMyCatMap;
            cmMyCatMap = cdMyCatData.Map;
            vMyCatMap = (StringArray) cmMyCatMap; // Requires explicit cast

Summary:
Sample data:
Header file: vector.h
See also: CategoricalData
CategoricalMap::CategoricalMap
Prototype:
PUBLIC  CategoricalMap(CategoricalMap& cmMap)
Remarks: Copy constructor to create a CategoricalMap from another CategoricalMap.
Parameters:
cmMap=CategoricalMap object that is copied

Return values:

Example:
            // Worksheet column Data1_A must exist prior to execution
            StringArray vMyCatMap;
            CategoricalData cdMyCatData("Data1_A");
            CategoricalMap cmMyCatMap(cdMyCatData.Map);
            vMyCatMap = (StringArray) cmMyCatMap; // Requires explicit cast

Summary:
Sample data:
Header file: vector.h
See also: CategoricalData


GetMapType

CategoricalMap::GetMapType
Prototype:
PUBLIC  int GetMapType()
Remarks: Get the CategoricalMap type. Origin currently supports Ordinal maps in which items are sorted (ordered) alphanumerically.
Parameters:

Return values:
The CategoricalMap type code (current possible value CMT_ORDINAL=2).

Example:
            // Worksheet column Data1_A must exist prior to execution
            int iMapType;
            CategoricalData cdMyCatData("Data1_A");
            iMapType = cdMyCatData.Map.GetMapType();

Summary:
Sample data:
Header file: vector.h
See also:


LookUp

CategoricalMap::LookUp
Prototype:
PUBLIC  int LookUp(LPCSTR lpcszCategory)
Remarks: Look up a category (text value) in this CategoricalMap and return its index (1 based offset). If the CategoricalMap has an associated CategoricalData data set then all text data values in the CategoricalData data set equal to the specified category are mapped to the category's index value. For the sample data below the text value "ddd" is mapped to the index 5.
Parameters:
lpcszCategory=Input category to look up

Return values:
Returns the index (1 based offset) of the category in this CategoricalMap if the category is
found and returns -1 if it is not found.

Example:
            // Worksheet column Data1_A must exist and contain Sample Data
            StringArray vMyCatMap;
            CategoricalData cdMyCatData("Data1_A");
            vMyCatMap = (StringArray) cdMyCatData.Map;
            int index = cdMyCatData.Map.LookUp("ddd");
            string strVal = cdMyCatData.Map.ReverseLookUp(5);

Summary: Look up a category in this CategoricalMap and return its index.
Sample data: aaa bbb ddd ccc qqq 777 aaa ddd
Header file: vector.h
See also: ReverseLookUp


ReverseLookUp

CategoricalMap::ReverseLookUp
Prototype:
PUBLIC  string ReverseLookUp(int iVal)
Remarks: Reverse look up an index (1 based offset) in this CategoricalMap and return its category (or text value). If the CategoricalMap has an associated CategoricalData data set the mapped index values in the CategoricalData data set refer to the text values in this CategoricalMap. For the sample data below the index 5 refers to the text value "ddd".
Parameters:
iVal=Input index value to reverse look up

Return values:
Returns the category or text value in this CategoricalMap referred to by the index if found
and returns an empty string if it is not found.

Example:
            // Worksheet column Data1_A must exist and contain Sample Data
            StringArray vMyCatMap;
            CategoricalData cdMyCatData("Data1_A");
            vMyCatMap = (StringArray) cdMyCatData.Map;
            int index = cdMyCatData.Map.LookUp("ddd");
            string strVal = cdMyCatData.Map.ReverseLookUp(5);

Summary: Reverse look up an index in this CategoricalMap and return its category.
Sample data: aaa bbb ddd ccc qqq 777 aaa ddd
Header file: vector.h
See also: LookUp


complex

Class: complex

Description: The Origin C complex class implements a complex number data type containing both a Real and an Imaginary component.

Hierarchy:

complex

Sample:

        complex cc(4.5, 7.8);
        out_double("Real part = ", cc.m_re);
        out_double("Imaginary part = ", cc.m_im);
        cc  = cc.Conjugate();
        out_double("Real part = ", cc.m_re);
        out_double("Imaginary part = ", cc.m_im);


complex

complex::complex
Prototype:
PUBLIC  complex(complex cc)
Remarks: constructor which constructs a complex value from another complex value.
Parameters:
cc = the source comples value

Return values:

Example:
        void	run_complex()
        {
            complex		cc(1.2, 3.4);
            complex		c(cc);

            // Display the value:
            out_complex("value = ", c);
        }

Summary:
Sample data:
Header file: complex.h
See also:
complex::complex
Prototype:
PUBLIC  complex()
Remarks: default constructor which constructs a complex value with both the real and the imaginary part being zero.
Parameters:
None

Return values:

Example:
        void	run_complex()
        {
            complex		c;

            // Display the value:
            out_complex("value = ", c);
        }

Summary:
Sample data:
Header file: complex.h
See also:
complex::complex
Prototype:
PUBLIC  complex(double dReal)
Remarks: constructor which constructs a complex value with from the real argument such that the real part becomes the value of the argument and the imaginary part is zero.
Parameters:
dReal = the real part

Return values:

Example:
        void	run_complex()
        {
            complex		c(7.89);

            // Display the value:
            out_complex("value = ", c);
        }

Summary:
Sample data:
Header file: complex.h
See also:
complex::complex
Prototype:
PUBLIC  complex(double dReal, double dImaginary)
Remarks: constructor which constructs a complex value from the real and imaginary values.
Parameters:
dReal = the real part
dImaginary = the imaginary part

Return values:

Example:
        void	run_complex()
        {
            complex		c(3.45, 6.78);

            // Display the value:
            out_complex("value = ", c);
        }

Summary:
Sample data:
Header file: complex.h
See also:


Conjugate

complex::Conjugate
Prototype:
PUBLIC  complex Conjugate()
Remarks: it returns the complex conjugate of the value
Parameters:
None.

Return values:
The complex conjugate

Example:
        void	run_complex_Conjugate()
        {
            complex		cc(1.2, 3.4);
            complex		cconj = cc.Conjugate();

            // Display the values:
            out_complex("original value = ", cc);
            out_complex("conjugate value = ", cconj);
        }

Summary:
Sample data:
Header file: complex.h
See also:


GetAmplitude

complex::GetAmplitude
Prototype:
PUBLIC  double GetAmplitude()
Remarks: returns the amplitude(modulus) of the complex value.
Parameters:
None.

Return values:
The amplitude

Example:
        void	run_complex_GetAmplitude()
        {
            complex		cc(1., -1.);

            // Display the amplitude:
            out_double("amplitude = ", cc.GetAmplitude());	// shoulde be 1.4142 (=sqrt(2))
        }

Summary:
Sample data:
Header file: complex.h
See also:


GetPhase

complex::GetPhase
Prototype:
PUBLIC  double GetPhase()
Remarks: returns the phase in radians, of the complex value.
Parameters:
None.

Return values:
The phase

Example:
        void	run_complex_GetPhase()
        {
            complex		cc(1., -1.);

            // Display the phase:
            out_double("phase = ", cc.GetPhase());	// shoulde be -0.7854 (=-PI/4)
        }

Summary:
Sample data:
Header file: complex.h
See also:


Curve

Class: Curve

Description: An Origin C Curve is comprised of a Y Dataset and typically (but not necessarily) an associated X Dataset. For example, a data set plotted against row numbers will not have an associated X data set. An Origin C Curve object can easily be plotted using methods of the GraphLayer class. The Curve class is derived from the curvebase, and vectorbase classes from which it inherits methods and properties.

Hierarchy:

vectorbase
 curvebase
 Curve

Sample:

        // Assumes Data1_A and Data1_B exist and contain data
        Dataset ds1("Data1_A"), ds2("Data1_B");
        Curve crvCopy( ds1, ds2 );
        crvCopy.Sort(); // Does not effect ds1, ds2


Attach

Curve::Attach
Prototype:
PUBLIC  BOOL Attach(Worksheet & wks, int nColY)
Remarks: Attach an Origin C Curve object to internal Origin X and Y datasets. The Y data set is specified by the column number in an Origin C worksheet object. The Y data set's internally associated X data set is automatically used for the X data set. Otherwise, row numbers are used for the X data set. Operations on the Curve object do affect the associated Origin X and Y worksheet columns (data sets).
Parameters:
wks=Origin C Dataset object attached to an internal Origin worksheet
nColY=0 based offset or column number of Y column (data set)

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Assumes Data1_A and Data1_B exist and contain data
            Worksheet wks("Data1");
            Curve crv; // Data1 worksheet and columns 1 (X) and 2 (Y)
            crv.Attach( wks, 1 ); // Data1 worksheet and column 2 (Y)
            crv.Sort(); // Does affect columns 1 and 2 in wks

Summary:
Sample data:
Header file: curve.h
See also:
Curve::Attach
Prototype:
PUBLIC  BOOL Attach(LPCSTR lpcszWksName, int nCol)
Remarks: Attach an Origin C Dataset object to an Origin worksheet column. Origin worksheet name and column number are passed as arguments. Please note Origin C column numbers are 0 based offsets while internal Origin column numbers are 1 based offsets. Origin C Dataset objects must be attached to internal Origin data sets either by constructor or by the Attach method.
Parameters:
lpcszWksName=Name of worksheet in which column resides
nCol=Origin C column number to attach to (nCol=1 attaches to second column in worksheet)

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Worksheet columns Data1_A and Data1_B must exist prior to execution
            Dataset	ds1;               // Create unattached Dataset object
            if(ds1.Attach("Data1",0))  // Attach Dataset object to first column in Data1 worksheet
            {
                ds1.SetSize(10);
                for(int ii = 0; ii < 10; ii++)
                    ds1[ii] = ii;
            }
            if(ds1.Attach("Data1",1)) // Attaching to different dataset detaches from previous dataset
            {                         //   and attaches to new one
                ds1.SetSize(10);
                for(int ii = 0; ii < 10; ii++)
                    ds1[ii] = -ii;
            }

Summary: Attach a Dataset object a worksheet column identified by worksheet name and column number.
Sample data:
Header file: curve.h
See also: Dataset Detach
Curve::Attach
Prototype:
PUBLIC  BOOL Attach(Column & col)
Remarks: Attach an Origin C Dataset object to an Origin worksheet column identified by an Origin C Column object. Origin C Dataset objects must be attached to internal Origin data sets either by constructor or by the Attach method.
Parameters:
col=Origin C column object attached to an Origin worksheet column

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Worksheet columns Data1_A and Data1_B must exist prior to execution
            Column colB("Data1",1); // Create an Origin C Column object attached to the second column
                                    //   in the Origin worksheet Data1
            Dataset	ds1;            // Create unattached Dataset object
            ds1.Attach(colB);       // Attach Dataset object to first column in Data1 worksheet

Summary: Attach a Dataset object to a worksheet column identified by a Column object.
Sample data:
Header file: curve.h
See also: Column Dataset Detach
Curve::Attach
Prototype:
PUBLIC  BOOL Attach(LPCSTR lpcszYData)
Remarks: Attach an Origin C Curve object to an internal Origin Y data set and its associated X data set. The Y data set is specified by name and, if it exists, the Y data set's internally associated X data set is automatically used for the X data set. Otherwise, row numbers are used for the X data set. Operations on the Curve object do effect the X and/or the specified Y data set(s).
Parameters:
lpcszYData=Name of Y Dataset

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Assumes Data1_B exists and contains data
            Curve crv;               // Declare Curve object
            crv.Attach( "Data1_B" ); // Attach to Y data set by name
            crv.Sort();              // Does effect Data1_B

Summary: Attach an Origin C Curve object to an internal Origin Y data set and its associated X data set.
Sample data:
Header file: curve.h
See also: Curve Detach
Curve::Attach
Prototype:
PUBLIC  BOOL Attach(LPCSTR lpcszXData, LPCSTR lpcszYData)
Remarks: Attach an Origin C Curve object to internal Origin X and Y data sets. Both the X and Y data sets are specified by name. Operations on the Curve object do effect the specified X and Y data sets.
Parameters:
lpcszXData=Name of X Dataset
lpcszYData=Name of Y Dataset

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Assumes Data1_A and Data1_B exist and contain data
            Curve crv;                          // Declare Curve object
            crv.Attach( "Data1_A", "Data1_B" ); // Attach Curve object to X and Y data sets by name
            crv.Sort();                         // Does effect data sets Data1_A and Data1_B

Summary: Attach an Origin C Curve object to internal Origin X and Y data sets.
Sample data:
Header file: curve.h
See also: Curve Detach
Curve::Attach
Prototype:
PUBLIC  BOOL Attach(Worksheet & wks, int nColX, int nColY)
Remarks: Attach an Origin C Curve object to internal Origin X and Y datasets. The X and Y data sets are specified by column number in an Origin C worksheet object. Operations on the Curve object do affect the associated Origin X and Y worksheet columns (data sets).
Parameters:
wks=Origin C Dataset object attached to an internal Origin worksheet
nColX=0 based offset or column number of X column (data set)
nColY=0 based offset or column number of Y column (data set)

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Assumes Data1_A and Data1_B exist and contain data
            Worksheet wks("Data1");
            Curve crv; // Data1 worksheet and columns 1 (X) and 2 (Y)
            crv.Attach( wks, 0, 1 ); // Data1 worksheet and columns 1 (X) and 2 (Y)
            crv.Sort(); // Does affect columns 1 and 2 in wks

Summary:
Sample data:
Header file: curve.h
See also:


Create

Curve::Create
Prototype:
PUBLIC  BOOL Create(int Size, UINT Option = 0)
Remarks: Create a temporary (or permanent) Origin data set and attach the Dataset object to it. If Option=1 is specified and data set is not destroyed by calling the Dataset::Destroy method the data set will remain in Origin after the Origin C function completes execution.
Parameters:
Size=Size of the data set
Option=0 (default) causes temporary Origin data set to be automatically deleted when program control exits scope
of Dataset object, Option=1 causes data set to not be deleted unless user calls Dataset::Destroy method

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            int ii;
            {
                LT_execute("list s;");
                Dataset	ds0;
                ds0.Create(3);         // Size=3 & Option=0 by default (create and attach to temporary data set)
                for(ii = 0; ii < 3; ii++)
                    ds0[ii] = ii;
                LT_execute("list s;"); // Note new ds0 TEMP_ data set
            }
            LT_execute("list s;");     // Out of ds0's scope, note new ds0 TEMP_ data set is destroyed

            Dataset	ds1;
            ds1.Create(3,1);           // Size=3 & Option=1 (create and attach to a second data set that is not temporary)
            for(ii = 0; ii < 3; ii++)
                ds1[ii] = ii;
            LT_execute("list s;");     // Note new ds1 TEMP_ data set
            ds1.Destroy();             // Destroy ds1 TEMP_ data set (comment out this line and TEMP_ data set does not get deleted)
            LT_execute("list s;");     // Note new ds1 TEMP_ data set is destroyed (or not if above line is commented out)

Summary: Create an internal Origin data set (may or may not be temporary).
Sample data:
Header file: curve.h
See also: Destroy Detach Dataset Attach


Curve

Curve::Curve
Prototype:
PUBLIC  Curve(Worksheet & wks, int nColX, int nColY)
Remarks: Constructor for Curve class. The X and Y data sets are specified by column number in an Origin C worksheet object. Operations on the Curve object do effect the associated Origin X and Y worksheet columns (data sets).
Parameters:
wks=Origin C Dataset object attached to an internal Origin worksheet
nColX=0 based offset or column number of X column (data set)
nColY=0 based offset or column number of Y column (data set)

Return values:

Example:
            // Assumes Data1_A and Data1_B exist and contain data
            Worksheet wks("Data1");
            Curve crv( wks, 0, 1 ); // Data1 worksheet and columns 1 (X) and 2 (Y)
            crv.Sort(); // Does effect columns 1 and 2 in wks

Summary: Construct a Curve from a Worksheet and X and Y column numbers.
Sample data:
Header file: curve.h
See also: Attach Detach
Curve::Curve
Prototype:
PUBLIC  Curve(Worksheet & wks, int nColY)
Remarks: Constructor for Curve class. The Y data set is specified by column number in an Origin C worksheet object and, if it exists, the Y column's internally associated X column is automatically used for the X column. Otherwise, row numbers are used for the X data set. Operations on the Curve object do effect the X and/or the specified Y column(s).
Parameters:
wks=Origin C Dataset object attached to an internal Origin worksheet
nColY=0 based offset or column number of Y column (data set)

Return values:

Example:
            // Assumes Data1_B exists and contains data
            Worksheet wks("Data1");
            Curve crv( wks, 1 ); // Data1 worksheet and column 2 (Y)
            crv.Sort(); // Does effect column 2 in wks

Summary: Construct a Curve from a Worksheet, a Y column number, and an associated X column.
Sample data:
Header file: curve.h
See also: Attach Detach
Curve::Curve
Prototype:
PUBLIC  Curve(curvebase &cv, int &nNumMissingInCopy, int &nSrcOffset, DWORD dwOptions = 0, int nLower = -1, int nUpper = -1)
Remarks: It creates a temporary curve object from the supplied source.
Parameters:
cv = [in] source curve
nNumMissingInCopy=(output) number of missing values in the created curve.
nSrcOffset = index in source curve that the result curve's 1st point is copied from
dwOptions=a combination of values from the enumeration:
enum {
CURVECOPY_SCAN_OVER_MISSING_FROM_LEFT	= 0x00000001,   // if on, it will scan from the left (see the parameter nLower) until it finds the first nonmissing value
CURVECOPY_SCAN_OVER_MISSING_FROM_RIGHT	= 0x00000002,   // if on, it will scan back from the right (see the parameter nUpper) until it finds the first nonmissing value
CURVECOPY_SKIP_MISSING_INSIDE			= 0x00000004,   // if on, it will not copy any missing values found in the middle
CURVECOPY_REPLACE_MISSING_INSIDE		= 0x00000008,   // if on, any missing values in the middle will be replaced with the average of neighboring points (not used if the bit CURVECOPY_SKIP_MISSING_INSIDE  is on)
};
nLower=lower index to start from or -1 to start from the lower bound.
nUpper=upper index to end at, or -1 to end at the upper bound.

Return values:

Example:

Summary:
Sample data:
Header file: curve.h
See also:
Curve::Curve
Prototype:
PUBLIC  Curve(LPCSTR lpcszYData)
Remarks: Constructor for Curve class. The Y data set is specified by name and, if it exists, the Y data set's internally associated X data set is automatically used for the X data set. Otherwise, row numbers are used for the X data set. Operations on the Curve object do effect the X and/or the specified Y data set(s).
Parameters:
lpcszYData=Name of Y Dataset

Return values:

Example:
            // Assumes Data1_B exists and contains data
            Curve crv( "Data1_B" );
            crv.Sort(); // Does effect Data1_B

Summary: Construct a Curve from a Y data set name and an associated X data set.
Sample data:
Header file: curve.h
See also: Attach Detach
Curve::Curve
Prototype:
PUBLIC  Curve(LPCSTR lpcszXData, LPCSTR lpcszYData)
Remarks: Constructor for Curve class. Both the X and Y data sets are specified by name. Operations on the Curve object do effect the specified X and Y data sets.
Parameters:
lpcszXData=Name of X Dataset
lpcszYData=Name of Y Dataset

Return values:

Example:
            // Assumes Data1_A and Data1_B exist and contain data
            Curve crv( "Data1_A", "Data1_B" ); // Attach Origin C Curve object to internal Origin data sets
            crv.Sort(); // Does effect Data1_A and Data1_B

Summary: Construct a Curve from X and Y data set names.
Sample data:
Header file: curve.h
See also: Attach Detach
Curve::Curve
Prototype:
PUBLIC  Curve(Dataset dsX, Dataset dsY)
Remarks: Constructor for Curve class. Both the X and Y data sets are specified by Origin C Dataset objects which are attached to internal Origin data sets. Operations on the Curve object do not effect the associated Origin X and Y data sets.
Parameters:
dsX=Origin C Dataset object attached to internal Origin X data set
dsY=Origin C Dataset object attached to internal Origin Y data set

Return values:

Example:
            // Assumes Data1_A and Data1_B exist and contain data
            Dataset ds1("Data1_A"), ds2("Data1_B");
            Curve crv( ds1, ds2 );
            crv.Sort(); // Does not effect ds1, ds2

Summary: Construct a Curve from X and Y Datasets.
Sample data:
Header file: curve.h
See also: Attach Detach
Curve::Curve
Prototype:
PUBLIC  Curve(DataPlot& dp)
Remarks: Constructor for Curve class. The X and Y data sets are specified by an Origin C DataPlot object. Operations on the Curve object do effect the associated data plot and underlying data sets in Origin.
Parameters:
DataPlot=Origin C DataPlot object attached to an internal Origin data plot

Return values:

Example:
            // Assumes Graph1 window with one or more data plots is active in Origin
            GraphLayer	gl = Project.ActiveLayer(); // Get active layer in project file
            if(gl)                                  // If valid graph layer...
            {
                DataPlot dp = gl.DataPlots(0);      // Get first data plot in graph layer
                if(dp)                              // If valid DataPlot...
                {
                    Curve crv(dp);                  // Get Curve from DataPlot
                    crv.Sort();                     // Does effect DataPlot
                }
            }

Summary: Construct a Curve from a DataPlot
Sample data:
Header file: curve.h
See also: Attach Detach
Curve::Curve
Prototype:
PUBLIC  Curve()
Remarks: Default constructor for Curve class.
Parameters:

Return values:

Example:
            // Assumes Data1_A and Data1_B exist and contain data
            Curve crv; // Use default constructor to create unattached Origin C Curve object
            crv.Attach( "Data1_A", "Data1_B" ); // Attach Origin C Curve object to internal Origin data sets
            crv.Sort(); // Does effect Data1_A and Data1_B

Summary: Default constructor for Curve class.
Sample data:
Header file: curve.h
See also: Attach Detach
Curve::Curve
Prototype:
PUBLIC  Curve(Curve crvOriginal)
Remarks: Copy constructor for Curve class. The original Y data set is copied into a new Curve object and is then associated with a copy of the original X data set. The Datasets of the original Curve object are not effected by operations on the copy Curve.
Parameters:
crvOriginal=Curve object which is copied

Return values:

Example:
            // Assumes Data1_A and Data1_B exist and contain data
            Dataset ds1("Data1_A"), ds2("Data1_B");
            Curve crv1( ds1, ds2 );
            Curve crv2( crv1 );
            crv2.Sort(); // Does not effect ds1, ds2

Summary: Copy constructor for Curve class.
Sample data:
Header file: curve.h
See also: Attach Detach


Destroy

Curve::Destroy
Prototype:
PUBLIC  void Destroy()
Remarks: Delete (destroy) an Origin data set created using the Dataset::Create method. For data sets not created by the Dataset::Create method the Destroy method functions identically to the Dataset::Detach method.
Parameters:

Return values:

Example:
            // Worksheet column Data1_A must exist prior to execution
            int ii;
            Dataset	ds1;
            ds1.Create(3,1);           // Create data set with Size=3 & Option=1 (not a temporary data set)
            for(ii = 0; ii < 3; ii++)
                ds1[ii] = ii;
            LT_execute("list s;");     // Note new ds1 TEMP_ data set
            ds1.Destroy();             // Destroy ds1 TEMP_ data set
            LT_execute("list s;");     // Note new ds1 TEMP_ data set is destroyed

            Dataset	ds2("Data1_A");    // Construct and attach to pre-existing Origin data set
            ds2.Destroy();             // Detaches ds2 from Data1_A but does not delete pre-existing data set from Origin
            LT_execute("list s;");     // Note ds2 is an Invalid Object but Data1_A still exists

Summary: Detach the Origin C Dataset object and Destroy (delete) the internal Origin data set.
Sample data:
Header file: curve.h
See also: Detach Attach Create


Detach

Curve::Detach
Prototype:
PUBLIC  BOOL Detach()
Remarks: Detach an Origin C Curve object from internal Origin data sets. The Curve object can only be attached to one pair of internal Origin data sets at a time but it may be sequentially detached and re-attached as many times as desired.
Parameters:

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Assumes Data1_A, Data1_B, Data2_A, and Data2_B exist and contain data
            Curve crv( "Data1_A", "Data1_B" );  // Declare Curve object and attach to X and Y data sets
            crv.Sort();
            crv.Detach();                       // Detach Curve Object from X and Y data sets
            crv.Attach( "Data2_A", "Data2_B" ); // Re-Attach Curve object to different X and Y data sets
            crv.Sort();

Summary: Detach an Origin C Curve object from internal Origin data sets.
Sample data:
Header file: curve.h
See also: Attach Curve


curvebase

Class: curvebase

Description: The Origin C curvebase class is an abstract base class used for polymorphic handling of Curve related template class types. Consequently, Origin C objects of type curvebase can not be constructed. Derived classes, such as Curve, inherit curvebase class methods and should be used instead. The curvebase class is derived from vectorbase class from which it inherits methods and properties.

Hierarchy:

vectorbase
 curvebase

Sample:

        // Assumes Data1_A and Data1_B exist and contain data
        Dataset ds1("Data1_A"), ds2("Data1_B");
        Curve crvCopy( ds1, ds2 );
        crvCopy.Sort(); // Does not effect ds1, ds2


Append

curvebase::Append
Prototype:
Private  BOOL Append(vector& v, int iMode = REDRAW_NONE)
Remarks: Append data from a vector or Dataset object to this Origin C Dataset object and update the Origin data set from this Origin C Dataset object.
Parameters:
v=vector or Dataset to append
iMode=Dataset update mode, allowed values are
REDRAW_NONE				do update
REDRAW_REALTIME			graph realtime drawing, only the new added data will be drawn
REDRAW_REALTIME_WKS		similar to REDRAW_REALTIME_SCOPE, but redraw the entire worksheet
REDRAW_REFRESH			do a simple refresh of the data
REDRAW_REALTIME_SCOPE	this is used to do realtime drawing for the entire range of data. To see effect in plots, must set dataplots to animate mode

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            // Assume Data1 worksheet and with A(X) vs. B(Y) plotted in graph window
            // Can test by typing "rt_add 10" into Script window with the graph active
            void rt_add(int npts)
            {
                static int nn = 1;

                Worksheet wks("data1");
                Dataset aa(wks,0);
                Dataset bb(wks,1);

                vector a(npts);
                vector b(npts);

                for(int ii = 0; ii < npts; ii++)
                {
                    a[ii] = nn++;
                    b[ii] = rnd();
                }

                aa.Append(a, REDRAW_REALTIME);
                bb.Append(b, REDRAW_REALTIME);
                return;
            }

Summary: Append data from a vector or Dataset object to this Origin C Dataset object.
Sample data:
Header file: curve.h
See also: Append Update


AttachX

curvebase::AttachX
Prototype:
Private  BOOL AttachX(Dataset& dsX, BOOL SetXRangeToYRange = TRUE)
Remarks: Attach an Origin C Dataset object to the X data set associated with this Curve object (if there is one) and optionally set the upper and lower bounds of the X data set to the upper and lower bounds of the Curve object's Y data set.
Parameters:
dsX=A Dataset object which is attached to the X data set of this Curve object (if any)
SetXRangeToYRange=TRUE (default) sets the upper and lower bounds of the X data set to the upper
and lower bounds of the Curve object's Y data set. This setting is temporary and may be over-
ridden when using multiple Curve objects linked to the same X data set.

Return values:
Returns TRUE if the Curve object has an associated X data set and the attachment is successful and FALSE
if there is no X data set or the attachment fails.

Example:
            // Assumes Data1_A(X) and Data2_B(Y) exist with the following data:
            // Data1_B={1,2,3,4,5,6,7}
            // Data1_A={1,2,3,4,5,6,7,-10,10};
            Curve crv("Data1_B");
            Dataset dsX;
            BOOL bRet = crv.AttachX(dsX);
            double xMin = min( dsX );
            double xMax = max( dsX );
            printf( "Due to upper bound restriction of Y Dataset the Minimum X in dsX is %g not -10\n", xMin );
            printf( "Due to upper bound restriction of Y Dataset the Maximum X in dsX is %g not 10\n", xMax );

Summary: Attach an Origin C Dataset object to the X data set associated with this Curve object.
Sample data:
Header file: curve.h
See also: Attach Attach Detach


CopyData

curvebase::CopyData
Prototype:
Private  bool CopyData(vector& vx, vector& vy, vector& yWeight = NULL, vector& xWeight = NULL)
Remarks:
Parameters:

Return values:

Example:
            void run_CopyData()
            {
                // Assumes Data1_A(X) and Data1_B(Y) with the following data:
                // Data1_B={1,2,3,4,5,6,7,8,9,10}
                // Data1_A={1,2,3,4,5,6,7,8,9,10};
                Curve crv("Data1_A", "Data1_B");
                vector vDatax;
                vector vDatay;
                bool bOK = crv.CopyData(vDatax, vDatay);
                out_int("bOK = ", bOK);
            }

Summary:
Sample data:
Header file: curve.h
See also:


CopyX

curvebase::CopyX
Prototype:
Private  bool CopyX(curvebase &cbSource)
Remarks: It copies x values from cbSource.
Parameters:
cbSource=the source curve

Return values:
TRUE for success, otherwise FALSE.

Example:
            // The example assumes that the worksheet "Data1" exists with four columns
            // A, B, C, D, and some values in them.
            Curve	crvData("data1_a", "data1_b");
            Curve	crvBaseline("data1_c", "data1_d");

            BOOL	bOK = crvBaseline.CopyX(crvData);
            out_int("OK = ", bOK);

Summary:
Sample data:
Header file: curve.h
See also:


GetName

curvebase::GetName
Prototype:
Private  BOOL GetName(string& strName)
Remarks: Get the name of an internal Origin data set.
Parameters:
strName=Returned name of an internal Origin data set

Return values:
Returns TRUE on successful exit and FALSE on failure. Also returns the name of an internal Origin data set.

Example:
            // Worksheet column Data1_A must exist prior to execution
            string strName;
            Dataset	dsA("Data1_A");
            dsA.GetName(strName);
            out_str("Data set name is " + strName);

Summary: Get the name of an internal Origin data set.
Sample data:
Header file: curve.h
See also:
curvebase::GetName
Prototype:
Private  string GetName()
Remarks: Get the name of an internal Origin data set.
Parameters:

Return values:
Returns the name of an internal Origin data set.

Example:
            // Worksheet column Data1_A must exist prior to execution
            string strName;
            Dataset dsA("Data1_A");
            strName = dsA.GetName();
            out_str("Data set name is " + strName);

Summary: Get the name of an internal Origin data set.
Sample data:
Header file: curve.h
See also:


GetRectPoints

curvebase::GetRectPoints
Prototype:
Private  int GetRectPoints( fpoint& fptTopLeft, fpoint& fptBottomRight, vector<double>& vX, vector<double>& vY, vector<int>& vIndex )
Remarks: Find all the points in a Curve which fall on or within a specified rectangle. The rectangle is specified by its top-left and bottom-right corners.
Parameters:
fptTopLeft=Input fpoint identifying the top-left corner of the rectangle
fptBottomRight=Input fpoint identifying the bottom-right corner of the rectangle
vX=Output vector containing the X coordinates of all points in the rectangele, paired with vY and vIndex
vY=Output vector containing the Y coordinates of all points in the rectangele, paired with vX and vIndex
vIndex=Output vector containing the row index (0 based) into the Curve's X and Y data sets, paired with vX and vY

Return values:
Returns the number of data points found within the rectangle (0,1,2,3...) on success and returns a
negative integer on failure. Also returns the coordinates and index of all points within the rectangle.

Example:
            // Assumes Data1_A(X) and Data1_B(Y) exist with the following data:
            // Data1_B={1,2,3,4,5,6,7,8,9,10}
            // Data1_A={1,2,3,4,5,6,7,8,9,10};
            Dataset ds1("Data1_A"), ds2("Data1_B");
            Curve crv(ds1, ds2);
            fpoint fptTL(3,8);
            fpoint fptBR(7,2);
            vector<double> vX, vY;
            vector<int> vIndex;
            int num = crv.GetRectPoints( fptTL, fptBR, vX, vY, vIndex );

Summary: Find all the points in a Curve which fall on or within a specified rectangle.
Sample data:
Header file: curve.h
See also:


GetSourceRange

curvebase::GetSourceRange
Prototype:
Private  bool GetSourceRange(int &nLower, int &nUpper)
Remarks:
Parameters:

Return values:

Example:
             void run_GetSourceRange()
            {
                // Assumes Data1_A(X) and Data1_B(Y) exist with the following data:
                // Data1_B={1,2,3,4,5,6,7,8,9,10}
                // Data1_A={1,2,3,4,5,6,7,8,9,10};
                Curve crv("Data1_B");
                int nLow, nUp;
                crv.SetLowerBound(1);
                crv.SetUpperBound(8);
                bool bOK = crv.GetSourceRange(nLow, nUp);
                out_int("bOK = ", bOK);
            }

Summary:
Sample data:
Header file: curve.h
See also:


HasX

curvebase::HasX
Prototype:
Private  BOOL HasX(string& strXdatasetName = NULL)
Remarks: Checks whether or not this Curve object has an associated X data set.
Parameters:
strXdatasetName = optional string to receive the X dataset name

Return values:
Returns TRUE if this Curve object has an associated X data set.

Example:
            // Assumes Data1_B exists and contains data
            Curve crv("Data1_B");
            BOOL bHasX = crv.HasX();

Summary: Checks whether or not this Curve object has an associated X data set.
Sample data:
Header file: curve.h
See also: Attach Curve


IsValid

curvebase::IsValid
Prototype:
Private  BOOL IsValid()
Remarks: Checks the validity of an Origin C Dataset object. Dataset objects are valid when they are successfully attached to an internal Origin data set.
Parameters:

Return values:
Returns TRUE if Dataset object is valid and FALSE if not.

Example:
            // Worksheet column Data1_A must exist prior to execution
            Dataset dsA;                          // Dataset is not yet attached and is not valid
            if(dsA.IsValid())
                out_str("Dataset is valid!");
            else
                out_str("Dataset is not valid!");
            dsA.Attach("Data1_A");                // Dataset is now attached and is valid
            if(dsA.IsValid())
                out_str("Dataset is valid!");
            else
                out_str("Dataset is not valid!");

Summary: Checks the validity of an Origin C Dataset object.
Sample data:
Header file: curve.h
See also: Attach Detach


SetLowerBound

curvebase::SetLowerBound
Prototype:
Private  BOOL SetLowerBound(int nLower)
Remarks: Set the lower display index of the Dataset range. Index values are 0 based offsets. SetLowerBound is supported only for Datasets (not vectors) while GetLowerBound is supported for all vectorbase derived objects. This allows for creation of more general purpose functions that can take vectorbase objects as arguments in place of Dataset objects. Essentially, the lower bound can be read but not written for vectors. SetLowerIndex is a synonym for SetLowerBound.
Parameters:
nLower=New lower display index of the Dataset

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            // Worksheet column Data1_A must exist prior to execution
            Dataset	dsA("Data1_A");
            dsA.SetSize(10);
            for(int ii = 0; ii < 10; ii++)
                dsA[ii] = ii;

            dsA.SetLowerBound(2);
            dsA.SetUpperBound(7);
            BasicStats bsStatVal;
            Data_sum(&dsA, &bsStatVal);
            ASSERT( bsStatVal.min == 2 );
            ASSERT( bsStatVal.max == 7 );

            dsA.SetLowerBound(0);
            dsA.SetUpperBound(9);
            Data_sum(&dsA, &bsStatVal);
            ASSERT( bsStatVal.min == 0 );
            ASSERT( bsStatVal.max == 9 );

Summary: Set the lower display index of the Dataset.
Sample data:
Header file: curve.h
See also: GetLowerBound GetSize SetSize GetUpperBound SetUpperBound


SetUpperBound

curvebase::SetUpperBound
Prototype:
Private  BOOL SetUpperBound(int nUpper)
Remarks: Set the upper display index of the Dataset range. Index values are 0 based offsets so use SetUpperBound(-1) to dispaly no rows. SetUpperBound is supported only for Datasets (not vectors) while GetUpperBound is supported for all vectorbase derived objects. This allows for creation of more general purpose functions that can take vectorbase objects as arguments in place of Dataset objects. Essentially, the upper bound can be read but not written for vectors. SetUpperIndex is a synonym for SetUpperBound.
Parameters:
nUpper=New upper display index of the Dataset

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            // Worksheet column Data1_A must exist prior to execution
            Dataset	dsA("Data1_A");
            dsA.SetSize(10);
            for(int ii = 0; ii < 10; ii++)
                dsA[ii] = ii;

            dsA.SetLowerBound(2);
            dsA.SetUpperBound(7);
            BasicStats bsStatVal;
            Data_sum(&dsA, &bsStatVal);
            ASSERT( bsStatVal.min == 2 );
            ASSERT( bsStatVal.max == 7 );

            dsA.SetLowerBound(0);
            dsA.SetUpperBound(9);
            Data_sum(&dsA, &bsStatVal);
            ASSERT( bsStatVal.min == 0 );
            ASSERT( bsStatVal.max == 9 );

Summary: Set the upper display index of the Dataset.
Sample data:
Header file: curve.h
See also: GetUpperBound GetSize SetSize GetLowerBound SetLowerBound


Sort

curvebase::Sort
Prototype:
Private  BOOL Sort(DWORD dwFlags = 0)
Remarks: Use a Curve object to sort a Y data set according to an X data set. This function does nothing if is there is no X data set associated with the Y data set. Please note that constructor of curve that takes two Dataset is just making a copy of the Datasets, they are not attched to the curve. So even you made some changes to the curve, it will not affect the original Dataset. Due to this reason, the curve sort will ONLY work on the X Dataset, So if one want to make sort on Y Dataset, he may need to construct a curve with X and Y dataset swapped first.
Parameters:
dwFlags=Sort options. Default 0 sorts in ascending order and places missing values at the end. See
the NS_DESCENDING and NS_MISSING_AS_SMALLEST macro definitions in system header file data.h

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Assumes Data1_A and Data1_B exist and contain data
            Curve crv("Data1_A","Data1_B");
            crv.Sort(NS_DESCENDING | NS_MISSING_AS_SMALLEST);

Summary: Use a Curve object to sort a Y data set according to an X data set.
Sample data:
Header file: curve.h
See also: Data_sort


TrimLeft

curvebase::TrimLeft
Prototype:
Private  int TrimLeft(BOOL bShiftLeft = FALSE)
Remarks: TrimLeft removes elements having the value NANUM from the left end or beginning of the Dataset by advancing the lower index to the first valid numeric value. If bShiftLeft is TRUE cells containing NANUM are deleted from the Dataset and a lower index value of 0 is returned shifting numeric values left to the beginning of the Dataset. When bShiftLeft is TRUE TrimLeft of Curve objects causes both X and Y Datasets to be trimmed.
Parameters:
bShiftLeft=TRUE will delete cells on the left of (before) the first valid numeric value, FASLE will cause the lower bound
or index to be adjusted upward but no cells are deleted.

Return values:
Returns -1 on error, 0 on success, and N > 0 for number of cells deleted.

Example:
            // Worksheet columns Data1_A and data1_B must exist prior to execution
            Dataset	dsA("Data1",0);
            dsA.TrimLeft(TRUE);
            Curve crvAxBy("Data1_A","Data1_B");
            crvAxBy.TrimLeft(TRUE);
            LT_execute("doc -uw");

Summary: TrimLeft removes elements having the value NANUM from the left end of a Dataset.
Sample data:
Header file: curve.h
See also: TrimRight GetLowerBound vector


TrimRight

curvebase::TrimRight
Prototype:
Private  int TrimRight(BOOL bDelExtra = FALSE)
Remarks: TrimRight removes elements having the value NANUM from the right end or bottom of the Dataset by retarding the upper index to the last valid numeric value. If bDelExtra is set to TRUE cells containing NANUM are deleted from the Dataset. When bDelExtra is TRUE TrimRight of Curve objects causes both X and Y Datasets to be trimmed.
Parameters:
bDelExtra=TRUE will delete cells on the right of (after) the last valid numeric value, FASLE will cause the upper bound
or index to be adjusted downward but no cells are deleted.

Return values:
Returns -1 on error, 0 on success, and N > 0 for number of cells deleted.

Example:
            // Worksheet columns Data1_A and data1_B must exist prior to execution
            Dataset	dsA("Data1",0);
            dsA.TrimRight(TRUE);
            Curve crvAxBy("Data1_A","Data1_B");
            crvAxBy.TrimRight(TRUE);
            LT_execute("doc -uw");

Summary: TrimRight removes elements having the value NANUM from the right end of a Dataset.
Sample data:
Header file: curve.h
See also: TrimLeft GetUpperBound GetSize vector


Update

curvebase::Update
Prototype:
Private  void Update(BOOL bFromOrigin, int mode = -1)
Remarks: Update an Origin C Dataset object from an Origin data set or update an Origin data set from an Origin C Dataset object. The number of elements and memory allocated are primarily affected by this method.
Parameters:
bFromOrigin=TRUE updates the Origin C Dataset object from the Origin data set, FALSE updates the Origin dataset
from an Origin C Dataset object.
mode=Dataset update mode, used only if bFromOrigin=FALSE. Supported values are
mode=Dataset update mode, allowed values are
REDRAW_NONE				do update
REDRAW_REALTIME_WKS		similar to REDRAW_REALTIME_SCOPE, but redraw the entire worksheet
REDRAW_REFRESH			do a simple refresh of the data
REDRAW_REALTIME_SCOPE	this is used to do realtime drawing for the entire range of data. To see effect in plots, must set dataplots to animate mode

Return values:

Example:
            // Worksheet column Data1_A must exist prior to execution
            void test_update_OC_when_Origin_changed()
            {
                Dataset	dsA("Data1_A");
                dsA.SetSize(10);
                dsA=1;
                LT_execute("set Data1_A -e 20;Data1_A=2;"); // Note Dataset size is not updated but Dataset values change in Local Variables windows of Debug mode
                dsA.Update(TRUE); // Note Dataset dsA size is now updated in Local Variables windows of Debug mode
                ASSERT(dsA.GetSize()==20);
            }

            // Assumes Data1 worksheet with column B
            // This example shows how to update Origin from inside Origin C program before it returns
            void test_update_Origin_when_OC_data_changed()
            {
                Dataset aa("Data1_b");
                // in case column is empty
                if(aa.GetSize()<1)
                {
                    aa.SetSize(10);
                    aa=0;
                }

                aa[0]+= 1;
                aa.Update(FALSE, REDRAW_REFRESH);
                MessageBox(GetWindow(),"Data1_b increment 1, click OK to increment again");
                aa[0]+=1;
            }

            // Demonstrate the usage of REDRAW_REALTIME_SCOPE and REDRAW_REALTIME_WKS
            // Assumes:
            //    1) Data1_A is filled with row numbers
            //    2) Data1_A(X) vs. B(Y) is plotted as line plot
            //    3) The line plot is set to animate mode so that the effect is fully visualized
            //       (set plot active and then execute LabTalk script command "set %C -an 1")

            void test_realtime_update_Origin_fromOC(int imax = 20)
            {
                Dataset aa("Data1_b");
                int	nMaxRows = 10;
                if(aa.GetSize()<nMaxRows)
                {
                    aa.SetSize(nMaxRows);
                    aa=0;
                }

                int ic = 0;//current cell

                for(int ii = 0; ii < imax; ii++)
                {
                    for(int jj = 0; jj < nMaxRows; jj++)
                        aa[jj] = 1;

                    aa[ic++] = 2;
                    if(ic >= nMaxRows)
                        ic = 0;
                    //aa.Update(FALSE, REDRAW_REALTIME_WKS);
                    aa.Update(FALSE, REDRAW_REALTIME_SCOPE);
                    LT_execute("sec -w 0.1;");// hard wait
                }
            }

Summary: Update an Origin C Dataset object from an Origin data set or vice-versa.
Sample data:
Header file: curve.h
See also: Append


Dataset

Class: Dataset

Description: An Origin C Dataset is a dynamically allocated and sized array that is tied to an internal Origin data set. The internal Origin data set can either be displayed or not displayed in an Origin worksheet column. Dataset is a template class with a default type of double but a Dataset of any basic data type (including char, byte, short, word, int, and uint but not string) can be constructed using the syntax Dataset<type>. OVector can be used as a synonym for Dataset. The Dataset class is derived from the vector and vectorbase classes from which it inherits methods and properties.

Hierarchy:

vectorbase
 vector
 Dataset

Sample:

        // Worksheet column Data1_B must exist prior to execution
        Dataset dsB;           // Create Origin C Dataset object not attached to an Origin data set
        dsB.Attach("Data1_B"); // Attach Origin C Dataset object dsB to Origin data set Data1_B
        dsB.SetSize(5);
        dsB = 100;


Append

Dataset::Append
Prototype:
PUBLIC  BOOL Append(vector& v, int iMode = REDRAW_NONE)
Remarks: Append data from a vector or Dataset object to this Origin C Dataset object and update the Origin data set from this Origin C Dataset object.
Parameters:
v=vector or Dataset to append
iMode=Dataset update mode, allowed values are
REDRAW_NONE				do update
REDRAW_REALTIME			graph realtime drawing, only the new added data will be drawn
REDRAW_REALTIME_WKS		similar to REDRAW_REALTIME_SCOPE, but redraw the entire worksheet
REDRAW_REFRESH			do a simple refresh of the data
REDRAW_REALTIME_SCOPE	this is used to do realtime drawing for the entire range of data. To see effect in plots, must set dataplots to animate mode

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            // Assume Data1 worksheet and with A(X) vs. B(Y) plotted in graph window
            // Can test by typing "rt_add 10" into Script window with the graph active
            void rt_add(int npts)
            {
                static int nn = 1;

                Worksheet wks("data1");

                Dataset aa(wks,0);
                Dataset bb(wks,1);

                vector a(npts);
                vector b(npts);

                for(int ii = 0; ii < npts; ii++)
                {
                    a[ii] = nn++;
                    b[ii] = rnd();
                }

                aa.Append(a, REDRAW_REALTIME);
                bb.Append(b, REDRAW_REALTIME);
                return;
            }

Summary: Append data from a vector or Dataset object to this Origin C Dataset object.
Sample data:
Header file: vector.h
See also: Append Update


Attach

Dataset::Attach
Prototype:
PUBLIC  BOOL Attach(Column & col)
Remarks: Attach an Origin C Dataset object to an Origin worksheet column identified by an Origin C Column object. Origin C Dataset objects must be attached to internal Origin data sets either by constructor or by the Attach method.
Parameters:
col=Origin C column object attached to an Origin worksheet column

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Worksheet columns Data1_A and Data1_B must exist prior to execution
            Column colB("Data1",1); // Create an Origin C Column object attached to the second column
                                    //   in the Origin worksheet Data1
            Dataset	ds1;            // Create unattached Dataset object
            ds1.Attach(colB);       // Attach Dataset object to first column in Data1 worksheet

Summary: Attach a Dataset object to a worksheet column identified by a Column object.
Sample data:
Header file: vector.h
See also: Column Dataset Detach
Dataset::Attach
Prototype:
PUBLIC  BOOL Attach(LPCSTR lpcszDatasetName)
Remarks: Attach an Origin C Dataset object to an internal Origin data set whose name is passed as an argument. Origin C Dataset objects must be attached to internal Origin data sets either by constructor or by the Attach method.
Parameters:
lpcszDatasetName=Name of Origin data set to attach to

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Worksheet columns Data1_A and Data1_B must exist prior to execution
            Dataset	ds1;               // Create unattached Dataset object
            if(ds1.Attach("Data1_A"))  // Attach Dataset object to Origin data set Data1_A
            {
                ds1.SetSize(10);
                for(int ii = 0; ii < 10; ii++)
                    ds1[ii] = ii;
            }
            if(ds1.Attach("Data1_B")) // Attaching to different dataset detaches from previous dataset
            {                         //   and attaches to new one
                ds1.SetSize(10);
                for(int ii = 0; ii < 10; ii++)
                ds1[ii] = -ii;
            }

Summary: Attach Dataset object to an Origin data set identified by name.
Sample data:
Header file: vector.h
See also: Dataset Detach
Dataset::Attach
Prototype:
PUBLIC  BOOL Attach(LPCSTR lpcszWksName, int nCol)
Remarks: Attach an Origin C Dataset object to an Origin worksheet column. Origin worksheet name and column number are passed as arguments. Please note Origin C column numbers are 0 based offsets while internal Origin column numbers are 1 based offsets. Origin C Dataset objects must be attached to internal Origin data sets either by constructor or by the Attach method.
Parameters:
lpcszWksName=Name of worksheet in which column resides
nCol=Origin C column number to attach to (nCol=1 attaches to second column in worksheet)

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Worksheet columns Data1_A and Data1_B must exist prior to execution
            Dataset	ds1;               // Create unattached Dataset object
            if(ds1.Attach("Data1",0))  // Attach Dataset object to first column in Data1 worksheet
            {
                ds1.SetSize(10);
                for(int ii = 0; ii < 10; ii++)
                    ds1[ii] = ii;
            }
            if(ds1.Attach("Data1",1)) // Attaching to different dataset detaches from previous dataset
            {                         //   and attaches to new one
                ds1.SetSize(10);
                for(int ii = 0; ii < 10; ii++)
                    ds1[ii] = -ii;
            }

Summary: Attach a Dataset object a worksheet column identified by worksheet name and column number.
Sample data:
Header file: vector.h
See also: Dataset Detach
Dataset::Attach
Prototype:
PUBLIC  BOOL Attach(Worksheet &wks, int nCol)
Remarks: Attach an Origin C Dataset object to an Origin worksheet column. An Origin C Worksheet object and column number are passed as arguments. Please note Origin C column numbers are 0 based offsets while internal Origin column numbers are 1 based offsets. Origin C Dataset objects must be attached to internal Origin data sets either by constructor or by the Attach method.
Parameters:
wks=Origin C worksheet object attached to an Origin worksheet
nCol=Origin C column number to attach to (nCol=1 attaches to second column in worksheet)

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Worksheet columns Data1_A and Data1_B must exist prior to execution
            Worksheet wksW("Data1");  // Create Origin C Worksheet object and attach to Origin Data1 worksheet
            Dataset	ds1;              // Create unattached Dataset object
            ds1.Attach(wksW,0);       // Attach Dataset object to first column in Data1 worksheet
            ds1.Attach(wksW,1);       // Attaching to different data set detaches from previous data set
                                      //   and attaches to new one

Summary: Attach a Dataset object to a worksheet column identified by Worksheet object and column number.
Sample data:
Header file: vector.h
See also: Worksheet Dataset Detach


Create

Dataset::Create
Prototype:
PUBLIC  BOOL Create(int Size, UINT Option = 0)
Remarks: Create a temporary (or permanent) Origin data set and attach the Dataset object to it. If Option=1 is specified and data set is not destroyed by calling the Dataset::Destroy method the data set will remain in Origin after the Origin C function completes execution.
Parameters:
Size=Size of the data set
Option=0 (default) causes temporary Origin data set to be automatically deleted when program control exits scope
of Dataset object, Option=1 causes data set to not be deleted unless user calls Dataset::Destroy method

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            int ii;
            {
                LT_execute("list s;");
                Dataset	ds0;
                ds0.Create(3);         // Size=3 & Option=0 by default (create and attach to temporary data set)
                for(ii = 0; ii < 3; ii++)
                    ds0[ii] = ii;
                LT_execute("list s;"); // Note new ds0 TEMP_ data set
            }
            LT_execute("list s;");     // Out of ds0's scope, note new ds0 TEMP_ data set is destroyed

            Dataset	ds1;
            ds1.Create(3,1);           // Size=3 & Option=1 (create and attach to a second data set that is not temporary)
            for(ii = 0; ii < 3; ii++)
                ds1[ii] = ii;
            LT_execute("list s;");     // Note new ds1 TEMP_ data set
            ds1.Destroy();             // Destroy ds1 TEMP_ data set (comment out this line and TEMP_ data set does not get deleted)
            LT_execute("list s;");     // Note new ds1 TEMP_ data set is destroyed (or not if above line is commented out)

Summary: Create an internal Origin data set (may or may not be temporary).
Sample data:
Header file: vector.h
See also: Destroy Detach Dataset Attach


Dataset

Dataset::Dataset
Prototype:
PUBLIC  Dataset(LPCSTR lpcszWksName, int nCol)
Remarks: Constructor to create an Origin C Dataset object and attach it to an Origin worksheet column. Origin worksheet name and column number in worksheet are passed as arguments. Please note Origin C column numbers are 0 based offsets while internal Origin column numbers are 1 based offsets.
Parameters:
lpcszWksName=Name of worksheet in which column resides
nCol=Origin C column number to attach to (nCol=1 attaches to second column in worksheet)

Return values:

Example:
            // Worksheet columns Data1_A and Data1_B must exist prior to execution
            Dataset dsB("Data1",1); // Create an Origin C Dataset object attached to an Origin data set
                                    //   contained in column 2 of Origin worksheet Data1
            dsB.SetSize(5);
            dsB = 3;

Summary: Constructor to create a Dataset from worksheet name and column number.
Sample data:
Header file: vector.h
See also: Attach Detach
Dataset::Dataset
Prototype:
PUBLIC  Dataset(Worksheet &wks, int nCol)
Remarks: Constructor to create an Origin C Dataset object and attach it to an Origin worksheet column. An Origin C worksheet object and worksheet column number are passed as arguments. Please note Origin C column numbers are 0 based offsets while internal Origin column numbers are 1 based offsets.
Parameters:
wks=Origin C worksheet object attached to an Origin worksheet
nCol=Origin C column number to attach to (nCol=1 attaches to second column in Origin worksheet)

Return values:

Example:
            // Worksheet columns Data1_A and Data1_B must exist prior to execution
            Worksheet wksW("Data1"); // Create an Origin C Worksheet object attached to the Origin worksheet Data1
            Dataset dsB(wksW,1);     // Create an Origin C Dataset object attached to an Origin data set
                                     //   contained in column 2 of the Origin worksheet Data1
            dsB.SetSize(5);
            dsB = 4;

Summary: Constructor to create a Dataset from worksheet object and column number.
Sample data:
Header file: vector.h
See also: Worksheet Attach Detach
Dataset::Dataset
Prototype:
PUBLIC  Dataset(Column & col)
Remarks: Constructor to create an Origin C Dataset object from an Origin C Column object.
Parameters:
col=Origin C column object attached to an Origin worksheet column

Return values:

Example:
            // Worksheet columns Data1_A and Data1_B must exist prior to execution
            Column colB("Data1",1); // Create an Origin C Column object attached to the second column
                                       //   in the Origin worksheet Data1
            Dataset dsB(colB);      // Create an Origin C Dataset object attached to the data set
                                       //   contained in column 2 of the Origin worksheet Data1
            dsB.SetSize(5);
            dsB = 5;

Summary: Constructor to create a Dataset from a Column object.
Sample data:
Header file: vector.h
See also: Column Attach Detach
Dataset::Dataset
Prototype:
PUBLIC  Dataset(Dataset dsOriginal)
Remarks: Dataset copy constructor accepts an Origin C Dataset object as an argument and generates a temporary Dataset which is an exact copy (same size and values as original) of the Dataset. The temporary Dataset is destroyed when program control exits the scope of the temporary Dataset.
Parameters:
dsOriginal=Origin C Dataset object to copy

Return values:

Example:
            void Test()
            {
                Worksheet wks("Data1");
                Dataset dsA(wks,0);

                int nSize = 3;
                dsA.SetSize(nSize);
                for(int ii=0; ii<nSize; ii++)
                {
                    dsA[ii] = ii;
                }

                Dataset dsB(dsA); // Generates a temporary dataset of size 3 having values 1,2,3
            }

Summary: Copy constructor for Dataset class.
Sample data:
Header file: vector.h
See also:
Dataset::Dataset
Prototype:
PUBLIC  Dataset()
Remarks: Default constructor to create an Origin C Dataset object that is not attached to an internal Origin data set. The Origin C Dataset object can be attached to an internal Origin data set at a later time.
Parameters:

Return values:

Example:
            // Worksheet column Data1_B must exist prior to execution
            Dataset dsB;           // Create Origin C Dataset object not attached to an Origin data set
            dsB.Attach("Data1_B"); // Attach Origin C Dataset object dsB to Origin data set Data1_B
            dsB.SetSize(5);
            dsB = 1;

Summary: Default constructor for Dataset class.
Sample data:
Header file: vector.h
See also: Attach Detach
Dataset::Dataset
Prototype:
PUBLIC  Dataset(LPCSTR lpcszDatasetName)
Remarks: Constructor to create an Origin C Dataset object and attach it to an internal Origin data set whose name is passed as an argument.
Parameters:
lpcszDatasetName=Name of internal Origin data set to which Origin C object is attached

Return values:

Example:
            // Worksheet column Data1_B must exist prior to execution
            Dataset dsB("Data1_B"); // Create an Origin C Dataset object attached to an Origin data set
            dsB.SetSize(5);
            dsB = 2;

Summary: Constructor to create a Dataset from data set name.
Sample data:
Header file: vector.h
See also: Attach Detach


Destroy

Dataset::Destroy
Prototype:
PUBLIC  void Destroy()
Remarks: Delete (destroy) an Origin data set created using the Dataset::Create method. For data sets not created by the Dataset::Create method the Destroy method functions identically to the Dataset::Detach method.
Parameters:

Return values:

Example:
            // Worksheet column Data1_A must exist prior to execution
            int ii;
            Dataset	ds1;
            ds1.Create(3,1);           // Create data set with Size=3 & Option=1 (not a temporary data set)
            for(ii = 0; ii < 3; ii++)
                ds1[ii] = ii;
            LT_execute("list s;");     // Note new ds1 TEMP_ data set
            ds1.Destroy();             // Destroy ds1 TEMP_ data set
            LT_execute("list s;");     // Note new ds1 TEMP_ data set is destroyed

            Dataset	ds2("Data1_A");    // Construct and attach to pre-existing Origin data set
            ds2.Destroy();             // Detaches ds2 from Data1_A but does not delete pre-existing data set from Origin
            LT_execute("list s;");     // Note ds2 is an Invalid Object but Data1_A still exists

Summary: Detach the Origin C Dataset object and Destroy (delete) the internal Origin data set.
Sample data:
Header file: vector.h
See also: Detach Attach Create


Detach

Dataset::Detach
Prototype:
PUBLIC  BOOL Detach()
Remarks: Detach an Origin C Dataset object from an internal Origin data set. The Dataset object can only be attached to one internal Origin data set at a time but it may be sequentially detached and re-attached as many times as desired.
Parameters:

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            // Worksheet columns Data1_A and Data1_ B must exist prior to execution
            Dataset	dsD("Data1_A");    // Attach to Origin data set Data1_A
            vector vV(dsD);            // Copy Data1_A data set to vector
            dsD.Detach();              // Explicitly Detach dsD from Data1_A
            dsD.Attach("Data1_B");     // Now Attach dsD to Data1_B
            dsD = vV;                  // Copy vector to data set Data1_B
            dsD.Detach();              // Detach dsD from Data1_B

Summary: Detach the Dataset object from an internal Origin data set.
Sample data:
Header file: vector.h
See also: Destroy Attach Create


GetName

Dataset::GetName
Prototype:
PUBLIC  BOOL GetName(string& strName)
Remarks: Get the name of an internal Origin data set.
Parameters:
strName=Returned name of an internal Origin data set

Return values:
Returns TRUE on successful exit and FALSE on failure. Also returns the name of an internal Origin data set.

Example:
            // Worksheet column Data1_A must exist prior to execution
            string strName;
            Dataset	dsA("Data1_A");
            dsA.GetName(strName);
            out_str("Data set name is " + strName);

Summary: Get the name of an internal Origin data set.
Sample data:
Header file: vector.h
See also:
Dataset::GetName
Prototype:
PUBLIC  string GetName()
Remarks: Get the name of an internal Origin data set.
Parameters:

Return values:
Returns the name of an internal Origin data set.

Example:
            // Worksheet column Data1_A must exist prior to execution
            string strName;
            Dataset dsA("Data1_A");
            strName = dsA.GetName();
            out_str("Data set name is " + strName);

Summary: Get the name of an internal Origin data set.
Sample data:
Header file: vector.h
See also:


GetStringArray

Dataset::GetStringArray
Prototype:
PUBLIC  BOOL GetStringArray(vector<string>& as, int nRow1=0, int nRow2=-1)
Remarks: Get the contents (from row nRow1 to nRow2) of a Text Dataset and copy the elements into a StringArray.
Parameters:
as=Output StringArray
nRow1=Input starting row number, default 0
nRow2=Input ending row number, default -1 means to upper bound of Dataset

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            // This test function assumes a Data1 worksheet with columns A, B, and C
            // Column A should have some number of text entries
            StringArray sa1, sa2, sa3;
            BOOL bRet;
            Dataset ds1("Data1_A");
            Dataset ds2("Data1_B");
            Dataset ds3("Data1_C");
            bRet = ds1.GetStringArray(sa1, 2, 5);
            bRet = ds1.GetStringArray(sa2);
            bRet = ds2.PutStringArray(sa1, 3);
            bRet = ds3.PutStringArray(sa2);

Summary: Copy the contents of a Text Dataset into a StringArray.
Sample data:
Header file: vector.h
See also: PutStringArray


GetText

Dataset::GetText
Prototype:
PUBLIC  BOOL GetText(int nRow, string& strTextVal)
Remarks: Get the text value of a cell in an Origin data set. The Origin data set must be of type Text & Numeric.
Parameters:
nRow=Row number (O based offset) of an Origin data set whose text value is returned
strTextVal=Returned text value

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            string strTextVal;
            // Worksheet columns Data1_A and Data1_B must exist prior to execution and must have a column type of Text & Numeric
            LT_execute("Data1_A[1]$=Row 0;");   // Use LabTalk to initialize text values
            LT_execute("Data1_A[2]$=Row 1;");   // LabTalk row numbers use 1 based offset
            LT_execute("Data1_A[3]$=Row 2;");

            Dataset dsTextA("Data1_A");
            dsTextA.SetSize(3);
            Dataset dsTextB("Data1_B");
            dsTextB.SetSize(3);
            for(int ii = 0; ii < 3; ii++)       // Origin C row numbers use 0 based offset
            {
                dsTextA.GetText(ii,strTextVal); // Get text value in column A
                dsTextB.SetText(ii,strTextVal); // Set text value in column B
            }

Summary: Get the text value of a cell in an Origin data set of type Text & Numeric.
Sample data:
Header file: vector.h
See also: SetText GetCell SetCell Cell TCell


IsValid

Dataset::IsValid
Prototype:
PUBLIC  BOOL IsValid()
Remarks: Checks the validity of an Origin C Dataset object. Dataset objects are valid when they are successfully attached to an internal Origin data set.
Parameters:

Return values:
Returns TRUE if Dataset object is valid and FALSE if not.

Example:
            // Worksheet column Data1_A must exist prior to execution
            Dataset dsA;                          // Dataset is not yet attached and is not valid
            if(dsA.IsValid())
                out_str("Dataset is valid!");
            else
                out_str("Dataset is not valid!");
            dsA.Attach("Data1_A");                // Dataset is now attached and is valid
            if(dsA.IsValid())
                out_str("Dataset is valid!");
            else
                out_str("Dataset is not valid!");

Summary: Checks the validity of an Origin C Dataset object.
Sample data:
Header file: vector.h
See also: Attach Detach


PutStringArray

Dataset::PutStringArray
Prototype:
PUBLIC  BOOL PutStringArray(vector<string>& as, int nRow1=0)
Remarks: Put (copy) the contents of a StringArray to a Text Dataset starting in row nRow1 of the destination Dataset.
Parameters:
as=Input StringArray to copy
nRow1=Input starting row number of destination Dataset

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            // This test function assumes a Data1 worksheet with columns A, B, and C
            // Column A should have some number of text entries
            StringArray sa1, sa2, sa3;
            BOOL bRet;
            Dataset ds1("Data1_A");
            Dataset ds2("Data1_B");
            Dataset ds3("Data1_C");
            bRet = ds1.GetStringArray(sa1, 2, 5);
            bRet = ds1.GetStringArray(sa2);
            bRet = ds2.PutStringArray(sa2, 3);
            bRet = ds3.PutStringArray(sa2);

Summary: Put (copy) the contents of a StringArray to a Text Dataset.
Sample data:
Header file: vector.h
See also: GetStringArray


SetLowerBound

Dataset::SetLowerBound
Prototype:
PUBLIC  BOOL SetLowerBound(int nLower)
Remarks: Set the lower display index of the Dataset range. Index values are 0 based offsets. SetLowerBound is supported only for Datasets (not vectors) while GetLowerBound is supported for all vectorbase derived objects. This allows for creation of more general purpose functions that can take vectorbase objects as arguments in place of Dataset objects. Essentially, the lower bound can be read but not written for vectors. SetLowerIndex is a synonym for SetLowerBound.
Parameters:
nLower=New lower display index of the Dataset

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            // Worksheet column Data1_A must exist prior to execution
            Dataset	dsA("Data1_A");
            dsA.SetSize(10);
            for(int ii = 0; ii < 10; ii++)
                dsA[ii] = ii;

            dsA.SetLowerBound(2);
            dsA.SetUpperBound(7);
            BasicStats bsStatVal;
            Data_sum(&dsA, &bsStatVal);
            ASSERT( bsStatVal.min == 2 );
            ASSERT( bsStatVal.max == 7 );

            dsA.SetLowerBound(0);
            dsA.SetUpperBound(9);
            Data_sum(&dsA, &bsStatVal);
            ASSERT( bsStatVal.min == 0 );
            ASSERT( bsStatVal.max == 9 );

Summary: Set the lower display index of the Dataset.
Sample data:
Header file: vector.h
See also: GetLowerBound GetSize SetSize GetUpperBound SetUpperBound


SetText

Dataset::SetText
Prototype:
PUBLIC  BOOL SetText(int nRow, LPCSTR lpcszTextValue)
Remarks: Set the text value of a cell in an Origin data set. The Origin data set must be of type Text & Numeric.
Parameters:
nRow=Row number (O based offset) of an Origin data set whose text value is to be set
lpcszTextValue=Text value to set

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            string strTextVal;
            // Worksheet column Data1_A must exist prior to execution and must have a column type of Text & Numeric
            Dataset dsTextA("Data1_A");         // Attach to data set
            dsTextA.SetSize(3);
            for(int ii = 0; ii < 3; ii++)       // For rows 0 to 2...
            {
                strTextVal.Format("Row %d",ii); // Format text value
                dsTextA.SetText(ii,strTextVal); // Set text value of row ii
            }

Summary: Set the text value of a cell in an Origin data set of type Text & Numeric.
Sample data:
Header file: vector.h
See also: GetText SetCell GetCell Cell TCell


SetUpperBound

Dataset::SetUpperBound
Prototype:
PUBLIC  BOOL SetUpperBound(int nUpper)
Remarks: Set the upper display index of the Dataset range. Index values are 0 based offsets so use SetUpperBound(-1) to dispaly no rows. SetUpperBound is supported only for Datasets (not vectors) while GetUpperBound is supported for all vectorbase derived objects. This allows for creation of more general purpose functions that can take vectorbase objects as arguments in place of Dataset objects. Essentially, the upper bound can be read but not written for vectors. SetUpperIndex is a synonym for SetUpperBound.
Parameters:
nUpper=New upper display index of the Dataset

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            // Worksheet column Data1_A must exist prior to execution
            Dataset	dsA("Data1_A");
            dsA.SetSize(10);
            for(int ii = 0; ii < 10; ii++)
                dsA[ii] = ii;

            dsA.SetLowerBound(2);
            dsA.SetUpperBound(7);
            BasicStats bsStatVal;
            Data_sum(&dsA, &bsStatVal);
            ASSERT( bsStatVal.min == 2 );
            ASSERT( bsStatVal.max == 7 );

            dsA.SetLowerBound(0);
            dsA.SetUpperBound(9);
            Data_sum(&dsA, &bsStatVal);
            ASSERT( bsStatVal.min == 0 );
            ASSERT( bsStatVal.max == 9 );

Summary: Set the upper display index of the Dataset.
Sample data:
Header file: vector.h
See also: GetUpperBound GetSize SetSize GetLowerBound SetLowerBound


TrimLeft

Dataset::TrimLeft
Prototype:
PUBLIC  int TrimLeft(BOOL bShiftLeft = FALSE)
Remarks: TrimLeft removes elements having the value NANUM from the left end or beginning of the Dataset by advancing the lower index to the first valid numeric value. If bShiftLeft is TRUE cells containing NANUM are deleted from the Dataset and a lower index value of 0 is returned shifting numeric values left to the beginning of the Dataset. When bShiftLeft is TRUE TrimLeft of Curve objects causes both X and Y Datasets to be trimmed.
Parameters:
bShiftLeft=TRUE will delete cells on the left of (before) the first valid numeric value, FASLE will cause the lower bound
or index to be adjusted upward but no cells are deleted.

Return values:
Returns -1 on error, 0 on success, and N > 0 for number of cells deleted.

Example:
            // Worksheet columns Data1_A and data1_B must exist prior to execution
            Dataset	dsA("Data1",0);
            dsA.TrimLeft(TRUE);
            Curve crvAxBy("Data1_A","Data1_B");
            crvAxBy.TrimLeft(TRUE);
            LT_execute("doc -uw");

Summary: TrimLeft removes elements having the value NANUM from the left end of a Dataset.
Sample data:
Header file: vector.h
See also: TrimRight GetLowerBound vector


TrimRight

Dataset::TrimRight
Prototype:
PUBLIC  int TrimRight(BOOL bDelExtra = FALSE)
Remarks: TrimRight removes elements having the value NANUM from the right end or bottom of the Dataset by retarding the upper index to the last valid numeric value. If bDelExtra is set to TRUE cells containing NANUM are deleted from the Dataset. When bDelExtra is TRUE TrimRight of Curve objects causes both X and Y Datasets to be trimmed.
Parameters:
bDelExtra=TRUE will delete cells on the right of (after) the last valid numeric value, FASLE will cause the upper bound
or index to be adjusted downward but no cells are deleted.

Return values:
Returns -1 on error, 0 on success, and N > 0 for number of cells deleted.

Example:
            // Worksheet columns Data1_A and data1_B must exist prior to execution
            Dataset	dsA("Data1",0);
            dsA.TrimRight(TRUE);
            Curve crvAxBy("Data1_A","Data1_B");
            crvAxBy.TrimRight(TRUE);
            LT_execute("doc -uw");

Summary: TrimRight removes elements having the value NANUM from the right end of a Dataset.
Sample data:
Header file: vector.h
See also: TrimLeft GetUpperBound GetSize vector


Update

Dataset::Update
Prototype:
PUBLIC  void Update(BOOL bFromOrigin, int mode = -1)
Remarks: Update an Origin C Dataset object from an Origin data set or update an Origin data set from an Origin C Dataset object. The number of elements and memory allocated are primarily affected by this method.
Parameters:
bFromOrigin=TRUE updates the Origin C Dataset object from the Origin data set, FALSE updates the Origin dataset
from an Origin C Dataset object.
mode=Dataset update mode, used only if bFromOrigin=FALSE. Supported values are
mode=Dataset update mode, allowed values are
REDRAW_NONE				do update
REDRAW_REALTIME_WKS		similar to REDRAW_REALTIME_SCOPE, but redraw the entire worksheet
REDRAW_REFRESH			do a simple refresh of the data
REDRAW_REALTIME_SCOPE	this is used to do realtime drawing for the entire range of data. To see effect in plots, must set dataplots to animate mode

Return values:

Example:
            // Worksheet column Data1_A must exist prior to execution
            void test_update_OC_when_Origin_changed()
            {
                Dataset	dsA("Data1_A");
                dsA.SetSize(10);
                dsA=1;
                LT_execute("set Data1_A -e 20;Data1_A=2;"); // Note Dataset size is not updated but Dataset values change in Local Variables windows of Debug mode
                dsA.Update(TRUE); // Note Dataset dsA size is now updated in Local Variables windows of Debug mode
                ASSERT(dsA.GetSize()==20);
            }

            // Assumes Data1 worksheet with column B
            // This example shows how to update Origin from inside Origin C program before it returns
            void test_update_Origin_when_OC_data_changed()
            {
                Dataset aa("Data1_b");
                // in case column is empty
                if(aa.GetSize()<1)
                {
                    aa.SetSize(10);
                    aa=0;
                }

                aa[0]+= 1;
                aa.Update(FALSE, REDRAW_REFRESH);
                MessageBox(GetWindow(),"Data1_b increment 1, click OK to increment again");
                aa[0]+=1;
            }

            // Demonstrate the usage of REDRAW_REALTIME_SCOPE and REDRAW_REALTIME_WKS
            // Assumes:
            //    1) Data1_A is filled with row numbers
            //    2) Data1_A(X) vs. B(Y) is plotted as line plot
            //    3) The line plot is set to animate mode so that the effect is fully visualized
            //       (set plot active and then execute LabTalk script command "set %C -an 1")

            void test_realtime_update_Origin_fromOC(int imax = 20)
            {
                Dataset aa("Data1_b");
                int	nMaxRows = 10;
                if(aa.GetSize()<nMaxRows)
                {
                    aa.SetSize(nMaxRows);
                    aa=0;
                }

                int ic = 0;//current cell

                for(int ii = 0; ii < imax; ii++)
                {
                    for(int jj = 0; jj < nMaxRows; jj++)
                        aa[jj] = 1;

                    aa[ic++] = 2;
                    if(ic >= nMaxRows)
                        ic = 0;
                    //aa.Update(FALSE, REDRAW_REALTIME_WKS);
                    aa.Update(FALSE, REDRAW_REALTIME_SCOPE);
                    LT_execute("sec -w 0.1;");// hard wait
                }
            }

Summary: Update an Origin C Dataset object from an Origin data set or vice-versa.
Sample data:
Header file: vector.h
See also: Append


Matrix

Class: Matrix

Description: An Origin C Matrix (upper case M) is a dynamically allocated and sized two dimensional array that is tied to an internal Origin matrix window. Matrix is a template class with a default type of double but a Matrix of any basic data type (including char, byte, short, word, int, and uint but not string) can be constructed using the syntax Matrix<type>. The Origin C Matrix class is used to access the data in an internal Origin matrix while the Origin C MatrixObject class is used for style related control of the matrix. Thus, the MatrixObject class has the same relationship with the Matrix class as the Column class has with the Dataset class. That is, an internal Origin matrix object (accessed by the MatrixObject class) holds a matrix data set (accessed by the Matrix class) just as a worksheet column (accessed by the Column class) holds a data set (accessed by the Dataset class). The data values displayed in the cells of an Origin matrix (referenced by a Matrix object) are typically referred to as Z values whose associated X values are linearly mapped to the columns of the matrix and whose associated Y values are linearly mapped to the rows of the matrix. The Matrix class is derived from the matrix and matrixbase classes from which it inherits methods and properties.

Hierarchy:

matrixbase
 matrix
 Matrix

Sample:

        // Assumes Matrix1 exists in Origin
        double dMean;
        Matrix matA;             // Declare OC Matrix object
        matA.Attach("Matrix1");  // Attach OC object to internal Origin matrix
        dMean = matA.GetMean();  // Use matrixbase::GetMean function
        printf("Mean of Matrix1: %g\n", dMean ); // Print out mean


Attach

Matrix::Attach
Prototype:
PUBLIC  BOOL Attach(LPCSTR lpcszMatrixName)
Remarks: Attach a Matrix object to an internal Origin matrix by name.
Parameters:
lpcszMatrixName=Input name of matrix in Origin to attach to

Return values:
Returns TRUE if attachment is successful and FALSE if unsuccessful.

Example:
            // Assumes Matrix1 exists in Origin
            double dMean;
            Matrix matA;             // Declare OC Matrix object
            matA.Attach("Matrix1");  // Attach OC object to internal Origin matrix
            dMean = matA.GetMean();  // Use matrixbase::GetMean function
            printf("Mean of Matrix1: %g\n", dMean ); // Print out mean

Summary: Attach matrix object to internal Origin matrix
Sample data:
Header file: MatrixData.h
See also: Detach IsValid Matrix
Matrix::Attach
Prototype:
PUBLIC  BOOL Attach(MatrixLayer& mlMatLayer)
Remarks: Attach a Matrix object to an internal Origin matrix by a MatrixLayer object.
Parameters:
mlMatLayer=Input MatrixLayer object

Return values:
Returns TRUE if attachment is successful and FALSE if unsuccessful.

Example:
            // Assumes Matrix1 is active window in Origin
            double dMean;
            Matrix matA;                              // Declare OC Matrix object
            MatrixLayer ml;                           // Declare OC MatrixLayer object
            ml = (MatrixLayer) Project.ActiveLayer(); // Get active MatrixLayer from OC Project object
            matA.Attach(ml);                          // Attach OC object to Matrix1
            dMean = matA.GetMean();                   // Use matrixbase::GetMean function
            printf("Mean of Matrix1: %g\n", dMean );    // Print out mean

Summary: Attach a Matrix object to an internal Origin matrix by a MatrixLayer object.
Sample data:
Header file: MatrixData.h
See also: Detach IsValid Matrix


Detach

Matrix::Detach
Prototype:
PUBLIC  BOOL Detach()
Remarks: Detach a Matrix object from an internal Origin matrix.
Parameters:

Return values:
Returns TRUE if detachment is successful and FALSE if unsuccessful.

Example:
            // Assumes Matrix1 and Matrix2 exist in Origin
            double dMean;
            Matrix matA;             // Declare OC Matrix object
            matA.Attach("Matrix1");  // Attach OC object to internal Origin matrix Matrix1
            dMean = matA.GetMean();  // Use matrixbase::GetMean function
            printf("Mean of Matrix1: %g\n", dMean ); // Print out mean
            matA.Detach();           // Detach OC Object from internal Origin matrix
            matA.Attach("Matrix2");  // Attach OC object to internal Origin matrix Matrix2
            dMean = matA.GetMean();  // Use matrixbase::GetMean function
            printf("Mean of Matrix2: %g\n", dMean ); // Print out mean

Summary: Detach a Matrix object from an internal Origin matrix.
Sample data:
Header file: MatrixData.h
See also: Attach IsValid Matrix


GetCellValue

Matrix::GetCellValue
Prototype:
PUBLIC  double GetCellValue(double x, double y)
Remarks: Get the value of the cell nearest the specified X and Y coordinates.
Parameters:
x=The input x coordinate
y=The input y coordinate

Return values:
Returns the value of the cell nearest the specified X and Y coordinates.

Example:
            // To setup function assumptions:
            // 1. Click the New Project button on the Standard toolbar in Origin.
            // 2. Click the New Matrix button on the Standard toolbar in Origin.
            // 3. Select the Matrix:Set Values menu item, set Cell(i,j) = x+y, click OK.
            // 4. Run function below.
            double dValue;
            Matrix mat("Matrix1");
            dValue = mat.GetCellValue(2.0,2.0);
            printf("dValue = %g\n",dValue);

Summary: Get the value of the cell nearest the specified X and Y coordinates.
Sample data:
Header file: MatrixData.h
See also: SetCellValue


GetInterpolatedValue

Matrix::GetInterpolatedValue
Prototype:
PUBLIC  double GetInterpolatedValue(double dX, double dY, int nMethod = INTERPOLATE_NEAREST, int* pnError = NULL)
Remarks: Get an interpolated Z value from an internal Origin matrix using the specified interpolation method and interpolating in two dimensions for the specified x and y coordinates.
Parameters:
dX=The X coordinate value
dY=The Y coordinate value
nMethod=Determines interpolation method. An enumerated value from the system header file OC_const.h including the values INTERPOLATE_NEAREST,
INTERPOLATE_BILINEAR, INTERPOLATE_BICUBIC, INTERPOLATE_2DSPLINE, and INTERPOLATE_VERTICINTERPOL
pnError=A pointer to an error code

Return values:
Returns the interpolated Z value on success or NANUM and an error code on failure.
Possible values for *pnError include:
-1=Complex matrix not supported
-5=Interpolate method does not exist
-6=dX or dY value is out of range
-7=ONAG DLL can not be loaded
-8=The matrix must be at least 2*2 for bilinear method
-9=The matrix must be at least 3*3 for bicubic method
-10=The matrix must be at least 4*4 for 2D spline method
73=Memory allocation failed
243=Data is too ill conditioned to compute the B spline

Example:
            // Assumes Matrix1 with Data exists in Origin
            Matrix matTemp("Matrix1");
            double x = 5.5;
            double y = 4.5;
            double z;
            int nError;
            z = matTemp.GetInterpolatedValue(x, y, INTERPOLATE_BILINEAR, &nError );

Summary: Get an interpolated Z value from an internal Origin matrix.
Sample data:
Header file: MatrixData.h
See also: ImageLinesProfile


GetName

Matrix::GetName
Prototype:
PUBLIC  string GetName()
Remarks: Get the name of the internal Origin matrix attached to this Origin C Matrix object.
Parameters:

Return values:
Returns the name of an internal Origin Matrix.

Example:
            MatrixLayer ml = Project.ActiveLayer();
            if(ml)
            {
                Matrix mat1(ml);
                printf("Matrix %s:[%d x %d]\n",mat1.GetName(), mat1.GetNumRows(), mat1.GetNumCols());
            }
            else
                out_str("No active matrix");

Summary: Get the name of an internal Origin Matrix.
Sample data:
Header file: MatrixData.h
See also:


GetXMax

Matrix::GetXMax
Prototype:
PUBLIC  double GetXMax() const
Remarks: In addition to the values displayed in the cells of an internal Origin matrix (nominally Z values), Origin matrices map X coordinate values to the columns and Y coordinate values to the rows of the matrix. The GetXMax function gets the X coordinate associated with the right most column of the matrix.
Parameters:

Return values:
Returns the X coordinate associated with the right most column of the matrix.

Example:
            // Assumes Matrix1 exists in Origin
            double dXMax;
            Matrix matA("Matrix1");   // Declare OC Matrix object and attach it to Matrix1
            dXMax = matA.GetXMax();   // Use GetXMax to get X coordinate of right most column
            printf("X Coordinate of right most column: %g\n", dXMax); // Print out coordinate

Summary: Get the X coordinate associated with the right most column of the matrix.
Sample data:
Header file: MatrixData.h
See also: GetXMin GetYMin GetYMax SetXMin SetYMin SetXMax SetYMax GetXValue GetYValue


GetXMin

Matrix::GetXMin
Prototype:
PUBLIC  double GetXMin() const
Remarks: In addition to the values displayed in the cells of an internal Origin matrix (nominally Z values), Origin matrices map X coordinate values to the columns and Y coordinate values to the rows of the matrix. The GetXMin function gets the X coordinate associated with the left most column of the matrix.
Parameters:

Return values:
Returns the X coordinate associated with the left most column of the matrix.

Example:
            // Assumes Matrix1 exists in Origin
            double dXMin;
            Matrix matA("Matrix1");   // Declare OC Matrix object and attach it to Matrix1
            dXMin = matA.GetXMin();   // Use GetXMin to get X coordinate of left most column
            printf("X Coordinate of left most column: %g\n", dXMin); // Print out coordinate

Summary: Get the X coordinate associated with the leftmost column of the matrix.
Sample data:
Header file: MatrixData.h
See also: GetXMax GetYMin GetYMax SetXMin SetYMin SetXMax SetYMax GetXValue GetYValue


GetXValue

Matrix::GetXValue
Prototype:
PUBLIC  double GetXValue(int iColumn)
Remarks: In addition to the values displayed in the cells of an internal Origin matrix (nominally Z values), Origin matrices map X coordinate values to the columns and Y coordinate values to the rows of the matrix. The GetXValue function gets the X coordinate associated with the specified column of the matrix. An error will result if the matrix coordinate map or column number is not valid.
Parameters:
iColumn=Input column number (0 based offset)

Return values:
Returns the X coordinate value of the specified column on success and NANUM on failure.

Example:
            // Assumes Matrix1 exists in Origin and has at least 20 columns
            double dXValue;
            Matrix matA("Matrix1");       // Declare OC Matrix object and attach it to Matrix1
            dXValue = matA.GetXValue(21); // Use GetXValue to get X coordinate of 20th column
            printf("X Coordinate of 22th column: %g\n", dXValue); // Print out coordinate

Summary: Get the X coordinate associated with the specified column of the matrix.
Sample data:
Header file: MatrixData.h
See also: GetYValue GetXMin GetXMax GetYMin GetYMax SetXMin SetXMax SetYMin SetYMax


GetYMax

Matrix::GetYMax
Prototype:
PUBLIC  double GetYMax() const
Remarks: In addition to the values displayed in the cells of an internal Origin matrix (nominally Z values), Origin matrices map X coordinate values to the columns and Y coordinate values to the rows of the matrix. The GetYMax function gets the Y coordinate associated with the last row of the matrix.
Parameters:

Return values:
Returns the Y coordinate associated with the last row of the matrix.

Example:
            // Assumes Matrix1 exists in Origin
            double dYMax;
            Matrix matA("Matrix1");   // Declare OC Matrix object and attach it to Matrix1
            dYMax = matA.GetYMax();   // Use GetYMax to get Y coordinate of last row
            printf("Y Coordinate of last row: %g\n", dYMax); // Print out coordinate

Summary: Get the Y coordinate associated with the last row of the matrix.
Sample data:
Header file: MatrixData.h
See also: GetXMin GetXMax GetYMin SetXMin SetYMin SetXMax SetYMax GetXValue GetYValue


GetYMin

Matrix::GetYMin
Prototype:
PUBLIC  double GetYMin() const
Remarks: In addition to the values displayed in the cells of an internal Origin matrix (nominally Z values), Origin matrices map X coordinate values to the columns and Y coordinate values to the rows of the matrix. The GetYMin function gets the Y coordinate associated with the first row of the matrix.
Parameters:

Return values:
Returns the Y coordinate associated with the first row of the matrix.

Example:
            // Assumes Matrix1 exists in Origin
            double dYMin;
            Matrix matA("Matrix1");   // Declare OC Matrix object and attach it to Matrix1
            dYMin = matA.GetYMin();   // Use GetYMin to get Y coordinate of first row
            printf("Y Coordinate of first row: %g\n", dYMin); // Print out coordinate

Summary: Get the Y coordinate associated with the first row of the matrix.
Sample data:
Header file: MatrixData.h
See also: GetXMin GetXMax GetYMax SetXMin SetYMin SetXMax SetYMax GetXValue GetYValue


GetYValue

Matrix::GetYValue
Prototype:
PUBLIC  double GetYValue(int iRow)
Remarks: In addition to the values displayed in the cells of an internal Origin matrix (nominally Z values), Origin matrices map X coordinate values to the columns and Y coordinate values to the rows of the matrix. The GetYValue function gets the Y coordinate associated with the specified row of the matrix. An error will result if the matrix coordinate map or row number is not valid.
Parameters:
iRow=Input row number (0 based offset)

Return values:
Returns the Y coordinate value of the specified row on success and NANUM on failure.

Example:
            // Assumes Matrix1 exists in Origin and has at least 20 rows
            double dYValue;
            Matrix matA("Matrix1");       // Declare OC Matrix object and attach it to Matrix1
            dYValue = matA.GetYValue(21); // Use GetYValue to get Y coordinate of 20th row
            printf("Y Coordinate of 22th row: %g\n", dYValue); // Print out coordinate

Summary: Get the Y coordinate associated with the specified row of the matrix.
Sample data:
Header file: MatrixData.h
See also: GetXValue GetXMin GetXMax GetYMin GetYMax SetXMin SetXMax SetYMin SetYMax


GetZRange

Matrix::GetZRange
Prototype:
PUBLIC  BOOL GetZRange(double& z1, double& z2)
Remarks: Get the dynamic range (Z1, Z2) that is used in data to image conversion.
Parameters:
z1=Lower bound of the matrix data to be mapped in converting to an image, all data below z1 are treated as z1
z2=Upper bound of the matrix data to be mapped in converting to an image, all data above z2 are treated as z2

Return values:
Returns FALSE if z range is not available and returns TRUE if Z range is available.

Example:
            // Assumes Matrix1 exists in Origin
            Matrix mat1("Matrix1");
            double v1, v2;
            //we will reduce the dynamic range to half of the original
            if(mat1.GetZRange(v1, v2))
            {
                double range = v2-v1;
                mat1.SetZRange(v1+range/4, v2-range/4);
            }

Summary: Get the dynamic range (Z1, Z2) that is used in the data to image conversion.
Sample data:
Header file: MatrixData.h
See also: SetZRangeUpdate SetZRange


ImageLinesProfile

Matrix::ImageLinesProfile
Prototype:
PUBLIC  int ImageLinesProfile(vector<fpoint>& vPathVertices, vector<fpoint>& vCalPoints, vectorbase & vIntensity,int iPointNumber = -1, int iMethod = INTERPOLATE_NEAREST)
Remarks:
Parameters:

Return values:

Example:

Summary: Get intensity values over the course of a user defined path through this Matrix.
Sample data:
Header file: MatrixData.h
See also:


IsValid

Matrix::IsValid
Prototype:
PUBLIC  BOOL IsValid()
Remarks: Checks the validity of this Matrix. Matrix objects not attached to an internal Origin matrix object are not valid.
Parameters:

Return values:
Returns TRUE if this Matrix is valid and FALSE if this Matrix is not valid.

Example:
            // Assumes Matrix1 exists in Origin
            Matrix mat;
            mat.Attach("Matrix1");
            if(mat.IsValid())
                out_str("After attaching mat object is valid!");
            else
                out_str("After attaching mat object is not valid!");
            mat.Detach();
            if(mat.IsValid())
                out_str("After detaching mat object is valid!");
            else
                out_str("After detaching mat object is not valid!");

Summary: Checks the validity of this Matrix.
Sample data:
Header file: MatrixData.h
See also: Attach Detach Matrix


Matrix

Matrix::Matrix
Prototype:
PUBLIC  Matrix()
Remarks: Default constructor for Matrix class.
Parameters:

Return values:

Example:
            // Assumes Matrix1 exists in Origin
            double dMean;
            Matrix matA;             // Declare OC Matrix object
            matA.Attach("Matrix1");  // Attach OC object to internal Origin matrix
            dMean = matA.GetMean();  // Use matrixbase::GetMean function
            printf("Mean of Matrix1: %g\n", dMean ); // Print out mean

Summary: Default constructor for Matrix class.
Sample data:
Header file: MatrixData.h
See also: Attach Detach IsValid
Matrix::Matrix
Prototype:
PUBLIC  Matrix(LPCSTR lpcszMatrixName)
Remarks: Constructor for Matrix class that attaches to an internal Origin matrix by name.
Parameters:
lpcszMatrixName=Input name of matrix in Origin to attach to

Return values:

Example:
            // Assumes Matrix1 exists in Origin
            double dMean;
            Matrix matA("Matrix1");  // Declare OC Matrix object and attach it to Matrix1
            dMean = matA.GetMean();  // Use matrixbase::GetMean function
            printf("Mean of Matrix1: %g\n", dMean ); // Print out mean

Summary: Constructor for Matrix class that attaches to an internal Origin matrix by name.
Sample data:
Header file: MatrixData.h
See also: Attach Detach IsValid
Matrix::Matrix
Prototype:
PUBLIC  Matrix(MatrixLayer& mlMatLayer)
Remarks: Constructor for Matrix class that attaches to an internal Origin matrix by a MatrixLayer object.
Parameters:
mlMatLayer=Input MatrixLayer object

Return values:

Example:
            // Assumes Matrix1 is active window in Origin
            double dMean;
            MatrixLayer ml;                           // Declare OC MatrixLayer object
            ml = (MatrixLayer) Project.ActiveLayer(); // Get active MatrixLayer from OC Project object
            Matrix matA(ml);                          // Declare OC Matrix object and attach it to Matrix1
            dMean = matA.GetMean();                   // Use matrixbase::GetMean function
            printf("Mean of Matrix1: %g\n", dMean );    // Print out mean

Summary: Constructor for Matrix class that attaches to an internal Origin matrix by a MatrixLayer object.
Sample data:
Header file: MatrixData.h
See also: Attach Detach IsValid


SetCellValue

Matrix::SetCellValue
Prototype:
PUBLIC  BOOL SetCellValue(double x, double y, double dValue)
Remarks: Set the value of the cell nearest the specified X and Y coordinates.
Parameters:
x=The input x coordinate
y=The input y coordinate
dValue=The new cell value

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // To setup assumptions of function:
            // 1. Click the New Project button on the Standard toolbar in Origin.
            // 2. Click the New Matrix button on the Standard toolbar in Origin.
            // 3. Run function below.
            Matrix mat("Matrix1");
            mat.SetCellValue(2.0,2.0,-999); // Note Cell(5,5)==-999

Summary: Set the value of the cell nearest the specified X and Y coordinates.
Sample data:
Header file: MatrixData.h
See also: GetCellValue


SetXMax

Matrix::SetXMax
Prototype:
PUBLIC  BOOL SetXMax(double dXMax)
Remarks: In addition to the values displayed in the cells of an internal Origin matrix (nominally Z values), Origin matrices map X coordinate values to the columns and Y coordinate values to the rows of the matrix. The SetXMax function sets the X coordinate associated with the right most column of the matrix.
Parameters:
dXMax=Input X coordinate of right most column

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 exists in Origin
            double dXMax;
            Matrix matA("Matrix1");    // Declare OC Matrix object and attach it to Matrix1
            dXMax = matA.GetXMax();    // Use GetXMax to get X coordinate of right most column
            printf("X Coordinate of right most column: %g\n", dXMax); // Print out coordinate
            matA.SetXMax( dXMax*10 );  // Use SetXMax to set new X coordinate of right most column
            dXMax = matA.GetXMax();    // Use GetXMax to get new X coordinate of right most column
            printf("New X Coordinate of right most column: %g\n", dXMax); // Print out coordinate

Summary: Set the X coordinate associated with the right most column of the matrix.
Sample data:
Header file: MatrixData.h
See also: SetXMin SetYMin SetYMax GetXMin GetXMax GetYMin GetYMax GetXValue GetYValue


SetXMin

Matrix::SetXMin
Prototype:
PUBLIC  BOOL SetXMin(double dXMin)
Remarks: In addition to the values displayed in the cells of an internal Origin matrix (nominally Z values), Origin matrices map X coordinate values to the columns and Y coordinate values to the rows of the matrix. The SetXMin function sets the X coordinate associated with the left most column of the matrix.
Parameters:
dXMin=Input X coordinate of left most column

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 exists in Origin
            double dXMin;
            Matrix matA("Matrix1");    // Declare OC Matrix object and attach it to Matrix1
            dXMin = matA.GetXMin();    // Use GetXMin to get X coordinate of left most column
            printf("X Coordinate of left most column: %g\n", dXMin); // Print out coordinate
            matA.SetXMin( dXMin*10 );  // Use SetXMin to set new X coordinate of left most column
            dXMin = matA.GetXMin();    // Use GetXMin to get new X coordinate of left most column
            printf("New X Coordinate of left most column: %g\n", dXMin); // Print out coordinate

Summary: Set the X coordinate associated with the left most column of the matrix.
Sample data:
Header file: MatrixData.h
See also: SetYMin SetXMax SetYMax GetXMin GetXMax GetYMin GetYMax GetXValue GetYValue


SetYMax

Matrix::SetYMax
Prototype:
PUBLIC  BOOL SetYMax(double dYMax)
Remarks: In addition to the values displayed in the cells of an internal Origin matrix (nominally Z values), Origin matrices map X coordinate values to the columns and Y coordinate values to the rows of the matrix. The SetYMax function sets the Y coordinate associated with the last row of the matrix.
Parameters:
dYMax=Input Y coordinate of last row

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 exists in Origin
            double dYMax;
            Matrix matA("Matrix1");    // Declare OC Matrix object and attach it to Matrix1
            dYMax = matA.GetYMax();    // Use GetYMax to get Y coordinate of last row
            printf("Y Coordinate of last row: %g\n", dYMax); // Print out coordinate
            matA.SetYMax( dYMax*10 );  // Use SetYMax to set new Y coordinate of last row
            dYMax = matA.GetYMax();    // Use GetYMax to get new Y coordinate of last row
            printf("New Y Coordinate of last row: %g\n", dYMax); // Print out coordinate

Summary: Set the Y coordinate associated with the last row of the matrix.
Sample data:
Header file: MatrixData.h
See also: SetXMin SetYMin SetXMax GetXMin GetXMax GetYMin GetYMax GetXValue GetYValue


SetYMin

Matrix::SetYMin
Prototype:
PUBLIC  BOOL SetYMin(double dYMin)
Remarks: In addition to the values displayed in the cells of an internal Origin matrix (nominally Z values), Origin matrices map X coordinate values to the columns and Y coordinate values to the rows of the matrix. The SetYMin function sets the Y coordinate associated with the first row of the matrix.
Parameters:
dYMin=Input Y coordinate of first row

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 exists in Origin
            double dYMin;
            Matrix matA("Matrix1");    // Declare OC Matrix object and attach it to Matrix1
            dYMin = matA.GetYMin();    // Use GetYMin to get Y coordinate of first row
            printf("Y Coordinate of first row: %g\n", dYMin); // Print out coordinate
            matA.SetYMin( dYMin*10 );  // Use SetYMin to set new Y coordinate of first row
            dYMin = matA.GetYMin();    // Use GetYMin to get new Y coordinate of first row
            printf("New Y Coordinate of first row: %g\n", dYMin); // Print out coordinate

Summary: Set the Y coordinate associated with the first row of the matrix.
Sample data:
Header file: MatrixData.h
See also: SetXMin SetXMax SetYMax GetXMin GetXMax GetYMin GetYMax GetXValue GetYValue


SetZRange

Matrix::SetZRange
Prototype:
PUBLIC  BOOL SetZRange(double z1, double z2, BOOL bRound=FALSE)
Remarks: Set the dynamic range of this Matrix (Z1, Z2) that is used in data to image conversion. This method calls SetZRangeUpdate(FALSE) as there is no need to recalculate the Z range from the Matrix data when explicitly setting it.
Parameters:
z1=Lower bound of the matrix data to be mapped in converting to an image, all data below z1 are treated as z1
z2=Upper bound of the matrix data to be mapped in converting to an image, all data above z2 are treated as z2
bRound=TRUE to use 256 to round the z1 z2 values, FALSE (default) will use values as they are without rounding

Return values:
Returns FALSE if z1 and z2 are not valid for setting the dynamic range otherwise returns TRUE.

Example:
            // Assumes Matrix1 exists in Origin
            Matrix mat1("Matrix1");
            double v1, v2;
            // We will reduce the dynamic range to half of the original
            if( mat1.GetZRange(v1, v2) )
            {
                double range = v2 - v1;
                mat1.SetZRange(v1+range/4, v2-range/4);
            }

Summary: Set the dynamic range of this Matrix (Z1, Z2) that is used in data to image conversion.
Sample data:
Header file: MatrixData.h
See also: SetZRangeUpdate GetZRange


SetZRangeUpdate

Matrix::SetZRangeUpdate
Prototype:
PUBLIC  void SetZRangeUpdate(BOOL bSet = TRUE)
Remarks: Enable (default) or disable the automatic dynamic range (Z range) update when Matrix data is changed. Each Matrix keeps track of the range of the data in the Matrix. Whenever data in the Matrix is changed the internal cache of the dynamic range should be recalculated. Since this recalculation needs to scan the entire matrix the operation can be time consuming. There are some situations when the Origin C programmer can determine that the data range in the matrix will not be changed after an operation on the matrix and thus there is no need to do the rescanning.
Parameters:
bSet = TRUE (default) performs update when class deconstructor is called, FALSE will disable update

Return values:

Example:
            // Assumes Matrix1 exists in Origin
            Matrix mat1("Matrix1");
            mat1.SetZRangeUpdate(FALSE); // Turn off automatic Z range scanning
            mat1.Transpose();

Summary: Enable or disable the automatic dynamic range (Z) update when Matrix data is changed.
Sample data:
Header file: MatrixData.h
See also: SetZRange GetZRange


Update

Matrix::Update
Prototype:
PUBLIC  void Update(BOOL bFromOrigin, int mode = REDRAW_REFRESH)
Remarks: Update an Origin C Matrix object when the matrix data in Origin is changed or update the matrix in Origin before exiting from the current program scope.
Parameters:
bFromOrigin=TRUE updates an Origin C Matrix object from an Origin matrix, FALSE updates an Origin matrix
from an Origin C Matrix object
mode=Matrix update mode, used only if bFromOrigin=FALSE. Supported values (enumerated in OC_const.h) are
REDRAW_NONE				Perform update
REDRAW_REFRESH			Perform a simple refresh of the data
REDRAW_REALTIME_SCOPE	Perform real time drawing for the entire range of data.
To see effect in plots, must set dataplots to animate mode.

Return values:

Example:
            // Both Examples assume Matrix1 window is active in Origin
            // Update Origin C Matrix object from Origin when matrix dimension is changed
            // Also works if data is changed in Origin
            Matrix mat1("Matrix1");
            mat1.SetSize(10,10);
            ASSERT(mat1.GetNumCols()==10);
            LT_execute("Matrix -ps DIM 20 20"); // Origin (via LabTalk) has changed the matrix dimensions
            ASSERT(mat1.GetNumCols()==10);
            mat1.Update(TRUE);                  // Update from Origin
            ASSERT(mat1.GetNumCols()==20);

            // This example shows how to update Origin from inside Origin C program before returning
            Matrix mat1("Matrix1");
            mat1 = -999;
            MessageBox(GetWindow(),"OC mat1 object set to -999 but Origin Matrix1 not yet updated, click OK update");
            mat1.Update(FALSE);
            MessageBox(GetWindow(),"Origin Matrix1 has now been updated from OC mat1 object, click OK to set to 0 and update on return");
            mat1 = 0;

Summary: Update an Origin C Matrix object from an Origin matrix or vice-versa.
Sample data:
Header file: MatrixData.h
See also: Update


matrix

Class: matrix

Description: An Origin C matrix (lower case m) is a dynamically allocated and sized two dimensional array that is not tied to an internal Origin matrix allowing a greater degree of flexibility. matrix is a template class with a default type of double but a matrix of any basic data type (including char, byte, short, word, int, and uint but not string) can be constructed using the syntax matrix<type>. The matrix class is derived from the matrixbase class from which it inherits methods and properties.

Hierarchy:

matrixbase
 matrix

Sample:

        int ii, jj;
        matrix<int> mInts = {{1,2,3},{4,5,6},{7,8,9}};
        printf("mInts:\n");
        for(ii = 0; ii < mInts.GetNumRows(); ii++)
        {
            for(jj = 0; jj < mInts.GetNumCols(); jj++)
                printf("%d\t",mInts[ii][jj]);
            printf("\n");
        }

        matrix mDoublesByDefault = {{1.1,2.2,3.3},{4.4,5.5,6.6},{7.7,8.8,9.9}};
        printf("mDoublesByDefault:\n");
        for(ii = 0; ii < mDoublesByDefault.GetNumRows(); ii++)
        {
            for(jj = 0; jj < mDoublesByDefault.GetNumCols(); jj++)
                printf("%g\t",mDoublesByDefault[ii][jj]);
            printf("\n");
        }


GetSourceDim

matrix::GetSourceDim
Prototype:
PUBLIC  bool GetSourceDim(int &nRows, int &nCols)
Remarks: It returns the dimensions of the source Matrix used by the constructor matrix(MatrixObject &mo, BOOL bWriteback = FALSE) if bWriteback is TRUE. See that constructor and the accompanying example for more details.
Parameters:
nRows=it receives the number of rows of the source.
nCols=it receives the number of columns of the source.

Return values:
TRUE if bWriteback was TRUE when calling the constructor, otherwise FALSE.

Example:

Summary:
Sample data:
Header file: MatrixData.h
See also:


matrix

matrix::matrix
Prototype:
PUBLIC  matrix(UINT nNumRows, UINT nNumCols)
Remarks: Constructor for matrix class that constructs a matrix having a specific size.
Parameters:
nNumRows=Number of rows in constructed matrix
nNumCols=Number of columns in constructed matrix

Return values:

Example:
            int ii, jj;
            matrix mA(4,5); // Construct an empty 4 x 5 matrix

            printf("mA:\n");
            for(ii = 0; ii < mA.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mA.GetNumCols(); jj++)
                {
                    mA[ii][jj] = ii + jj;
                    printf("%g\t",mA[ii][jj]);
                }
                printf("\n");
            }

Summary: Constructor for matrix class that constructs a matrix having a specific size.
Sample data:
Header file: MatrixData.h
See also:
matrix::matrix
Prototype:
PUBLIC  matrix(MatrixObject &mo, BOOL bWriteback = FALSE)
Remarks: Initialize the matrix by copying the data from the source Matrix associated with the MatrixObject mo. If bWriteback, on exiting the scope in which the matrix object was declared, if writes back the values into the source Matrix. The originla size of the source matrix can be retrieved using the method GetSourceDim().
Parameters:
mo=the source Matrix object
bWriteback=if TRUE, it will write back the new values into the source on exiting the scope.

Return values:

Example:
            // Have a matrix with the name "Matrix1" in the project, with some values.
            // After the function executes, the matrix will contain new values set inside
            // the nested for-loops.
            void	test_matrixobj_writeback()
            {
                MatrixObject		mo("Matrix1", 0);

                matrix				m(mo, TRUE);

                int					nRows, nCols;
                if (m.GetSourceDim(nRows, nCols))
                    printf("rows = %d\tcols=%d\n", nRows, nCols);

                // Change the size and set new values:
                m.SetSize(7, 9);
                for (int row = 0; row < m.GetNumRows(); row++)
                {
                    for (int col = 0; col < m.GetNumCols(); col++)
                    {
                        m[row][col] = (row + 1) * (col + 1);
                    }
                }

            }

Summary:
Sample data:
Header file: MatrixData.h
See also:
matrix::matrix
Prototype:
PUBLIC  matrix()
Remarks: Default constructor for matrix class.
Parameters:

Return values:

Example:
            int ii, jj;
            matrix<int> mInts = {{1,2,3},{4,5,6},{7,8,9}};
            printf("mInts:\n");
            for(ii = 0; ii < mInts.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mInts.GetNumCols(); jj++)
                    printf("%d\t",mInts[ii][jj]);
                printf("\n");
            }

            matrix mDoublesByDefault = {{1.1,2.2,3.3},{4.4,5.5,6.6},{7.7,8.8,9.9}};
            printf("mDoublesByDefault:\n");
            for(ii = 0; ii < mDoublesByDefault.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mDoublesByDefault.GetNumCols(); jj++)
                    printf("%g\t",mDoublesByDefault[ii][jj]);
                printf("\n");
            }

Summary: Default constructor for matrix class.
Sample data:
Header file: MatrixData.h
See also:
matrix::matrix
Prototype:
PUBLIC  matrix(matrixbase & mbOriginal)
Remarks: Copy constructor for matrix class.
Parameters:
mbOriginal=Matrix that is copied

Return values:

Example:
            int ii, jj;
            matrix mA = {{1,2,3},{4,5,6},{7,8,9}};
            printf("mA:\n");
            for(ii = 0; ii < mA.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mA.GetNumCols(); jj++)
                    printf("%g\t",mA[ii][jj]);
                printf("\n");
            }

            matrix mB( mA );
            printf("mB Copy of mA:\n");
            for(ii = 0; ii < mB.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mB.GetNumCols(); jj++)
                    printf("%g\t",mB[ii][jj]);
                printf("\n");
            }

Summary: Copy constructor for matrix class.
Sample data:
Header file: MatrixData.h
See also:
matrix::matrix
Prototype:
PUBLIC  matrix(Dataset dsDataset)
Remarks: Constructor for matrix class that constructs a matrix object from a Dataset object.
Parameters:
dsDataset=Dataset object from which a matrix object is created

Return values:

Example:
            // Assumes Data1_A data set with 9 elements exists in Origin
            int ii, jj;
            Dataset dsA("Data1_A");
            matrix mA( dsA ); // Construct a matrix from Data1_A
            mA.SetSize(3,3);
            printf("mA:\n");
            for(ii = 0; ii < mA.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mA.GetNumCols(); jj++)
                    printf("%g\t",mA[ii][jj]);
                printf("\n");
            }

Summary: Constructor for matrix class that constructs a matrix object from a Dataset object.
Sample data:
Header file: MatrixData.h
See also:


matrixbase

Class: matrixbase

Description: The Origin C matrixbase class is an abstract base class used for polymorphic handling of the matrix and Matrix template class types. Origin C objects of type matrixbase can not be constructed. Derived classes such as matrix and Matrix inherit matrixbase class methods and should be used instead.

Hierarchy:

matrixbase

Sample:


AllNonZero

matrixbase::AllNonZero
Prototype:
PUBLIC  int AllNonZero(vector<BOOL> & vAllNonZero, int nDim = 1, double dTol = DEFAULT_TOLERANCE)
Remarks: Indicates whether or not an entire row or column of this matrix is comprised of all non-zero elements. For matrices having an underlying base type of double or complex a specified tolerance is used to determine whether or not each element is zero.
Parameters:
vAllNonZero=The result vector
nDim=The AllNonZero test can occur row wise (relative to the first dimension when nDim=1) or
column wise (relative to the second dimension when nDim=2)
dTol=The tolerance used to decide whether or not an element is zero (if abs(element) < dTol
then the element is considered to be zero)

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj;

            matrix mA = {{0,2,3},{0,0,6},{7,8,9}};
            vector<BOOL> vRowIsAllNonZeros;

            mA.AllNonZero(vRowIsAllNonZeros);

            printf("mA:\t\tAll non-zero\n");
            for(ii = 0; ii < mA.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mA.GetNumCols(); jj++)
                    printf("%g\t",mA[ii][jj]);
                printf("%d\n",vRowIsAllNonZeros[ii]);
            }

Summary: Indicates whether or not an entire row or column of this matrix is comprised of all non-zero elements.
Sample data:
Header file: MatrixData.h
See also: AnyNonZero


AnyNonZero

matrixbase::AnyNonZero
Prototype:
PUBLIC  int AnyNonZero(vector<BOOL> & vAnyNonZero, int nDim = 1, double dTol = DEFAULT_TOLERANCE)
Remarks: Indicates whether or not each row or column of this matrix contains any (one or more) non-zero elements. For matrices having an underlying base type of double or complex the machine based precision is used to determine whether or not any element is zero.
Parameters:
vAnyNonZero=The result vector
nDim=The AnyNonZero test can occur row wise (relative to the first dimension when nDim=1) or
column wise (relative to the second dimension when nDim=2)
dTol=The tolerance used to decide whether or not an element is zero (if abs(element) < dTol
then the element is considered to be zero)

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj;

            matrix mA = {{0,2,0},{0,0,6},{0,8,0}};
            vector<BOOL> vColumnHasAnyNonZeros;

            mA.AnyNonZero(vColumnHasAnyNonZeros,2);

            printf("mA:\n");
            for(ii = 0; ii < mA.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mA.GetNumCols(); jj++)
                    printf("%g\t",mA[ii][jj]);
                printf("\n");
            }

            printf("Any non-zero:\n");
            for(ii = 0; ii < mA.GetNumCols(); ii++)
                printf("%d\t",vColumnHasAnyNonZeros[ii]);
            printf("\n");

Summary: Indicates whether or not each row or column of this matrix contains any non-zero elements.
Sample data:
Header file: MatrixData.h
See also: AllNonZero


ApplyFilter

matrixbase::ApplyFilter
Prototype:
PUBLIC  BOOL ApplyFilter(matrix &mfilter, int nPaddingOption = 0, BOOL bNormalize = TRUE)
Remarks: Takes an N x N filter (or mask) matrix and places it centered over each pixel in this image (or matrix). For each cell in the filter/mask it computes the product of the filter/mask element with the overlayed cell of the original image (matrix), sums all of the products, normalizes to the weight of the filter/mask (if specified to do so), and then replaces the pixel in the original image with the weighted average.
Parameters:
matfilter=An N x N filter/mask matrix used by Applyfilter
nPaddingOption=Pads the area outside the borders in one of the following ways
nPaddingOption=0 -- pads with zeroes
nPaddingOption=1 -- pads with values from adjacent cells
bNormalize=Normalize replacement value with weight of mask/filter if TRUE

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            matrix mfilter(3,3);
            mfilter = 1;       // mfilter
            mfilter[0][0] = 0; // 0 1 0
            mfilter[2][0] = 0; // 1 1 1
            mfilter[0][2] = 0; // 0 1 0
            mfilter[2][2] = 0;
            ASSERT( mat[2][1] == 1 ); // Before filter
            // Use mfilter as mask/filter for Matrix1 padding outside borders with adjacent cells and weighting to mfilter
            mat.ApplyFilter(mfilter,1);
            ASSERT( mat[2][1] == 1.8 ); // After filter: (0*0+1*2+0*0+1*2+1*1+1*2+0*0+1*2+0*0)/(0+1+0+1+1+1+0+1+0)=9/5=1.8

Summary: Apply filter.
Sample data: // Matrix1 is 5 x 5 with following data 0 0 0 0 0 0 2 0 0 0 2 1 2 0 0 0 2 0 0 0 0 0 0 0 0 // Matrix1 after running Example program 0 0.8 0 0 0 1.2 0.6 0.8 0 0 0.8 1.8 0.6 0.4 0 1.2 0.6 0.8 0 0 0 0.8 0 0 0
Header file: MatrixData.h
See also: MedianFilter


CastToDouble

matrixbase::CastToDouble
Prototype:
PUBLIC  int CastToDouble(matrix & mDouble)
Remarks: Copy this matrix and cast the underlying base type to double.
Parameters:
mDouble=The result matrix having an underlying base type of double

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj;
            matrix<int> mInts = {{1,2,3},{4,5,6},{7,8,9}};
            mInts *= 1.1;

            printf("Intergers:\n");
            for(ii = 0; ii < mInts.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mInts.GetNumCols(); jj++)
                    printf("%d\t",mInts[ii][jj]);
                printf("\n");
            }

            matrix<double> mDoubles;
            mInts.CastToDouble(mDoubles);
            mDoubles *= 1.1;

            printf("Doubles:\n");
            for(ii = 0; ii < mDoubles.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mDoubles.GetNumCols(); jj++)
                    printf("%g\t",mDoubles[ii][jj]);
                printf("\n");
            }

Summary: Copy this matrix casting the underlying base type to double.
Sample data:
Header file: MatrixData.h
See also: MakeComplex CastToInteger


CastToInteger

matrixbase::CastToInteger
Prototype:
PUBLIC  int CastToInteger(matrix<int> & mInteger)
Remarks: Round this matrix placing the results in a matrix having an underlying base type of int. The input matrix must have an underlying base type of float or double or a run time error is generated.
Parameters:
mInteger=The result matrix having an underlying base type of int

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj;

            matrix<double> mDoubles = {{1.1,2.2,3.3},{4.4,5.5,6.6},{7.7,8.8,9.9}};
            printf("Doubles:\n");
            for(ii = 0; ii < mDoubles.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mDoubles.GetNumCols(); jj++)
                    printf("%g\t",mDoubles[ii][jj]);
                printf("\n");
            }

            matrix<int> mInts;
            mDoubles.CastToInteger(mInts);

            printf("Intergers:\n");
            for(ii = 0; ii < mInts.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mInts.GetNumCols(); jj++)
                    printf("%d\t",mInts[ii][jj]);
                printf("\n");
            }

Summary: Round this matrix placing the results in a matrix having an underlying base type of int.
Sample data:
Header file: MatrixData.h
See also: MakeComplex CastToDouble


Ceil

matrixbase::Ceil
Prototype:
PUBLIC  int Ceil(matrixbase & mbCeil)
Remarks: Round each cell of this matrix to the nearest integer greater than the current cell value (toward positive infinity). .
Parameters:
mbCeil=Output matrix containing the results

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj,	nRows, nCols;
            matrix mResult;
            matrix mSource = {{1.001,2.009,-3.99999,4.0005,-5.999},
                              {-6.2000,7.345,8.9999,-9.0001,10.0001}};

            printf("The source data:\n");
            nCols = mSource.GetNumCols();
            nRows = mSource.GetNumRows();
            for( ii = 0; ii < nRows; ii++)
            {
                for(jj = 0; jj < nCols; jj++)
                    printf("%g\t",mSource[ii][jj]);
                printf("\n");
            }

            mSource.Ceil(mResult);

            printf("After Ceil function:\n");
            for( ii = 0; ii < nRows; ii++)
            {
                for(jj = 0; jj < nCols; jj++)
                    printf("%g\t",mResult[ii][jj]);
                printf("\n");
            }

Summary: Round each cell of this matrix to the nearest integer greater than the current cell value (toward positive infinity).
Sample data:
Header file: MatrixData.h
See also: Floor Fix Round


Concatenate

matrixbase::Concatenate
Prototype:
PUBLIC  int Concatenate(int nDim, matrixbase & mSource, matrixbase & mResult )
Remarks: Concatenate a matrix to this matrix placing the results in a third matrix. Matrices can be concatenated row wise or column wise. All three matrices must have the same underlying base type or a runtime error will be generated.
Parameters:
nDim=Specifies whether the matrices are concatenated row wise (nDim=1) or column wise (nDim=2)
mSource=Source matrix that is concatenated to this matrix
mResult=The matrix resulting from the concatenation

Return values:
Returns 0 on success or one of the following error codes on failure.
-1=nDim is not 1 or 2
-2=The source matrices do not have the same number of columns (when concatenating row wise)
or rows (when concatenating column wise)

Example:
            int ii, jj, nCols, nRows;
            matrix mSource1 = { {1,2,3}, {4,5,6}, {7,8,9} };
            matrix mSource2 = { {10,11,12}, {12,14,15} };
            matrix mSource3 = { {1,2}, {1,2}, {1,2} };
            matrix mResult;

            mSource1.Concatenate( 1, mSource2, mResult );

            nCols = mResult.GetNumCols();
            nRows = mResult.GetNumRows();
            for(ii = 0; ii < nRows; ii++)
            {
                for(jj = 0; jj < nCols; jj++)
                    printf("%g\t", mResult[ii][jj]);
                printf("\n");
            }
            printf("\n\n");

            mSource1.Concatenate( 2, mSource3, mResult);

            nCols = mResult.GetNumCols();
            nRows = mResult.GetNumRows();
            for(ii = 0; ii < nRows; ii++)
            {
                for(jj = 0; jj < nCols; jj++)
                    printf("%g\t", mResult[ii][jj]);
                printf("\n");
            }

Summary: Concatenate a matrix to this matrix placing the results in a third matrix.
Sample data:
Header file: MatrixData.h
See also:


Conjugate

matrixbase::Conjugate
Prototype:
PUBLIC  int Conjugate()
Remarks: Replace this matrix with the Conjugate of this matrix. A runtime error occurs if the underlying base type of this matrix is not double or Complex.
Parameters:

Return values:
Returns 0 on success and -1 on failure which occurs if the matrix is empty.

Example:
            matrix<complex> mA(2,2);
            mA[0][0] = 1+2i; mA[0][1] = 3;
            mA[1][0] = 4-1i; mA[1][1] = -2+2i;
            mA.Conjugate();
            for(int ii = 0; ii < 2; ii++)
            {
                for(int jj = 0; jj < 2; jj++)
                    printf("%g + %gi, ",mA[ii][jj].m_re, mA[ii][jj].m_im);
                printf("\n");

            }

Summary: Replace this matrix with the Conjugate of this matrix.
Sample data:
Header file: MatrixData.h
See also: GetReal GetImaginary GetPhase GetAmplitude Cross Inverse MakeComplex


CopyFromWks

matrixbase::CopyFromWks
Prototype:
PUBLIC  BOOL CopyFromWks(Worksheet & wksSource, int c1 = 0, int c2 = -1, int r1 = 0, int r2 = -1)
Remarks: Copies a specified range from a worksheet to a matrix dynamically resizing the matrix as needed.
Parameters:
wksSource=Source worksheet from which data is copied
c1=Begining column index, default is 0 (0 based offset)
c2=Ending column index, (inclusive) default -1 is GetNumCols -1 (0 based offset)
r1=Begining row index, default is 0 (0 based offset)
r2=Ending row index, (inclusive) default -1 is GetNumRows -1 (0 based offset)

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            // Assumes Data1 worksheet and Matrix1 matrix exist in Origin
            Worksheet wks("Data1");
            Matrix mat1("Matrix1");
            BOOL bRet = TRUE;
            if(mat1 && wks)
                bRet = mat1.CopyFromWks(wks); //Copies the whole wks to m1

Summary: Copies a specified range from a worksheet to a matrix.
Sample data:
Header file: MatrixData.h
See also:


Cross

matrixbase::Cross
Prototype:
PUBLIC  int Cross(matrixbase & mbSource, int nDim = 1)
Remarks: Cross product of this matrix and the source matrix along the dimension identified by iDim. The iDim dimension of both matrices must be three and the underlying base type of the source matrix must be less than or equal to the underlying base type of this matrix.
Parameters:
mbSource=The source matrix
nDim=Cross product can occur row wise (relative to the first dimension when nDim=1) or column wise (relative
to the second dimension when nDim=2)

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj;
            matrix mA = {{1,2,3},{4,5,6}};
            matrix<int> mB = {{1,1,1},{1,1,1}} ;

            mA.Cross(mB,1);
            printf("mA x mB:\n");
            for(ii = 0; ii < mA.GetNumRows();  ii++)
            {
                for(jj = 0; jj < mA.GetNumCols(); jj++)
                    printf("%g\t",mA[ii][jj]);
                printf("\n");
            }

Summary:
Sample data:
Header file: MatrixData.h
See also: DotMultiply DotDivide DotPower


CumulativeProduct

matrixbase::CumulativeProduct
Prototype:
PUBLIC  int CumulativeProduct(matrixbase & mbProduct, int nDim = 1)
Remarks: Compute the cumulative product of this matrix. The underlying base type of this matrix must be less than or equal to the underlying base type of the result matrix. Currently only the double and complex types are supported for the result matrix.
Parameters:
mbProduct=The result matrix containing the cumulative product
nDim=The CumulativeProduct function can operate row wise (relative to the first dimension when nDim=1) or
column wise (relative to the second dimension when nDim=2)

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj;

            matrix mA = {{1,2,3},{4,5,6},{7,8,9}}, mB;

            printf("mA:\n");
            for(ii = 0; ii < mA.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mA.GetNumCols(); jj++)
                    printf("%g\t",mA[ii][jj]);
                printf("\n");
            }

            mA.CumulativeProduct(mB);

            printf("mB = Cumulative product of mA:\n");
            for(ii = 0; ii < mB.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mB.GetNumCols(); jj++)
                    printf("%g\t",mB[ii][jj]);
                printf("\n");
            }

Summary:
Sample data:
Header file: MatrixData.h
See also: CumulativeSum


CumulativeSum

matrixbase::CumulativeSum
Prototype:
PUBLIC  int CumulativeSum(matrixbase & mbSum, int nDim = 1)
Remarks: Compute the cumulative sum of this matrix. The underlying base type of this matrix must be less than or equal to the underlying base type of the result matrix. Currently only the double and complex types are supported for the result matrix.
Parameters:
mbSum=The result matrix containing the cumulative sum
nDim=The CumulativeSum function can operate row wise (relative to the first dimension when nDim=1) or
column wise (relative to the second dimension when nDim=2)

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj;

            matrix mA = {{1,2,3},{4,5,6},{7,8,9}}, mB;

            printf("mA:\n");
            for(ii = 0; ii < mA.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mA.GetNumCols(); jj++)
                    printf("%g\t",mA[ii][jj]);
                printf("\n");
            }

            mA.CumulativeSum(mB);

            printf("mB = Cumulative sum of mA:\n");
            for(ii = 0; ii < mB.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mB.GetNumCols(); jj++)
                    printf("%g\t",mB[ii][jj]);
                printf("\n");
            }

Summary:
Sample data:
Header file: MatrixData.h
See also: CumulativeProduct


Difference

matrixbase::Difference
Prototype:
PUBLIC  int Difference(matrixbase & mbDifference, int nOrder = 1, int nDim = 1)
Remarks: Compute the N-th order row wise or column wise difference of the elements in this matrix. The difference matrix is computed by replacing the current element with the current element minus the previous element along the dimension specified by nDim. The N-th order difference approximates the N-th order derivative. If nOrder is greater than or equal to the size of the dimension identified by nDim than an empty matrix is returned. The underlying base type of this matrix and the result matrix must be the same.
Parameters:
mbDifference=The result matrix containing the difference
nOrder=The order of difference to compute, default is 1
nDim=The Difference function can operate row wise (relative to the first dimension when nDim=1) or
column wise (relative to the second dimension when nDim=2), default is 1 or row wise

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj;
            matrix mSource = {{8,2,5,4,2},{1,7,11,9,3}};

            printf("The source matrix:\n");
            for(ii = 0; ii < mSource.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mSource.GetNumCols(); jj++)
                    printf("%g\t",mSource[ii][jj]);
                printf("\n");
            }

            matrix mResult;
            mSource.Difference(mResult);

            printf("The result matrix:\n");
            for(ii = 0; ii < mResult.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mResult.GetNumCols(); jj++)
                    printf("%g\t",mResult[ii][jj]);
                printf("\n");
            }

Summary: Compute the N-th order row wise or column wise difference of the elements in this matrix.
Sample data:
Header file: MatrixData.h
See also:


DotDivide

matrixbase::DotDivide
Prototype:
PUBLIC  BOOL DotDivide(matrixbase &mb)
Remarks: Divide this matrix by another matrix on an element by element basis placing the result in this matrix. The underlying base type of the matrix passed as an argument must be "less than or equal" to the underlying base type of this matrix. The matrices must have the same size.
Parameters:
mb=The input divisor matrix which is divided into this matrix

Return values:
Returns TRUE on success and FALSE on Failure.

Example:
            matrix<double> m2(2,2) = {{15,12},{9,6}}, m1(2,2) = {{5,4},{3,2}};
            m2.DotDivide( m1 );
            printf( "m2[0][0]=%g\tm2[0][1]=%g\n", m2[0][0], m2[0][1] );
            printf( "m2[1][0]=%g\tm2[1][1]=%g\n", m2[1][0], m2[1][1] );

Summary: Divide this matrix by another matrix.
Sample data:
Header file: MatrixData.h
See also: DotMultiply DotPower Cross


DotMultiply

matrixbase::DotMultiply
Prototype:
PUBLIC  BOOL DotMultiply(matrixbase &mb)
Remarks: Multiply two matrices element by element placing the result in this matrix. The underlying base type of the matrix passed as an argument must be "less than or equal" to the underlying base type of this matrix. The matrices must have the same size.
Parameters:
mb=Input matrix which is multiplied with this matrix.

Return values:
Returns TRUE on success and FALSE on Failure.

Example:
            matrix<double> m1(2,2) = {{0,1},{2,3}}, m2(2,2) = {{4,5},{6,7}};
            m2.DotMultiply( m1 );
            printf( "m2[0][0]=%g\tm2[0][1]=%g\n", m2[0][0], m2[0][1] );
            printf( "m2[1][0]=%g\tm2[1][1]=%g\n", m2[1][0], m2[1][1] );

Summary: Multiply two matrices element by element.
Sample data:
Header file: MatrixData.h
See also: DotDivide DotPower Cross


DotPower

matrixbase::DotPower
Prototype:
PUBLIC  BOOL DotPower(matrixbase &mb)
Remarks: Raise this matrix to the power of another matrix on an element by element basis placing the result in this matrix. The underlying base type of the matrix passed as an argument must be "less than or equal" to the underlying base type of this matrix. The matrices must have the same size.
Parameters:
mb=Input matrix to which this matrix is raised (the exponents)

Return values:
Returns TRUE on success and FALSE on Failure.

Example:
            matrix<double> m2(2,2) = {{16,32},{2,3}}, m1(2,2) = {{0.5,0.6},{3,2}};
            m2.DotPower( m1 );
            printf( "m2[0][0]=%g\tm2[0][1]=%g\n", m2[0][0], m2[0][1] );
            printf( "m2[1][0]=%g\tm2[1][1]=%g\n", m2[1][0], m2[1][1] );

Summary: Raise this matrix to the power of another matrix.
Sample data:
Header file: MatrixData.h
See also: DotDivide DotMultiply Cross


FFTShift

matrixbase::FFTShift
Prototype:
PUBLIC  int FFTShift(matrixbase & mbShifted, int nDim = -1)
Remarks: Shift this matrix placing the result in the matrix passed as an argument. Shifts can occur row wise or relative to the first dimension (nDim=1), column wise or relative to the second dimension (nDim=2), or relative to both or the first dimension and then the second dimension (nDim=-1 default). The result matrix and this matrix can be the same (i.e. m1.FFTShift(m1);).
Parameters:
mbShifted=The output matrix in which the shifted matrix is returned
nDim=Shifts can occur row wise (relative to the first dimension when nDim=1), column wise (relative
to the second dimension when nDim=2), or relative to both or the first dimension and then the second
dimension (when nDim=-1 default)

Return values:
Returns 0 on success and a non-zero error code on failure:
-1=nDim is not -1, 1, or 2
-2=Internal casting error

Example:
            matrix mSource = {{1,2,3},{4,5,6},{7,8,9}};
            matrix mShifted;
            int ii, jj;
            printf("Before shifting:\n");
            for(ii = 0; ii < mSource.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mSource.GetNumCols(); jj++)
                    printf("%g\t",mSource[ii][jj]);
                printf("\n");
            }

            mSource.FFTShift(mShifted);
            printf("After shifting for FFT:\n");
            for(ii = 0; ii < mShifted.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mShifted.GetNumCols(); jj++)
                    printf("%g\t",mShifted[ii][jj]);
                printf("\n");
            }

            mSource.FFTShift(mShifted, 1);
            printf("After shifting relative to first dimension:\n");
            for(ii = 0; ii < mShifted.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mShifted.GetNumCols(); jj++)
                    printf("%g\t",mShifted[ii][jj]);
                printf("\n");
            }

            mSource.FFTShift(mShifted, 2);
            printf("After shifting relative to second dimension:\n");
            for(ii = 0; ii < mShifted.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mShifted.GetNumCols(); jj++)
                    printf("%g\t",mShifted[ii][jj]);
                printf("\n");
            }

Summary: Shift this matrix placing the result in the matrix passed as an argument.
Sample data:
Header file: MatrixData.h
See also: IFFTShift


Fix

matrixbase::Fix
Prototype:
PUBLIC  int Fix(matrixbase & mbFix)
Remarks: Round each cell of this matrix to the nearest integer (toward zero). .
Parameters:
mbFix=Output matrix containing the results

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj,	nRows, nCols;
            matrix mResult;
            matrix mSource = {{1.001,2.009,-3.99999,4.0005,-5.999},
                              {-6.2000,7.345,8.9999,-9.0001,10.0001}};

            printf("The source data:\n");
            nCols = mSource.GetNumCols();
            nRows = mSource.GetNumRows();
            for( ii = 0; ii < nRows; ii++)
            {
                for(jj = 0; jj < nCols; jj++)
                    printf("%g\t",mSource[ii][jj]);
                printf("\n");
            }

            mSource.Fix(mResult);

            printf("After Fix function:\n");
            for( ii = 0; ii < nRows; ii++)
            {
                for(jj = 0; jj < nCols; jj++)
                    printf("%g\t",mResult[ii][jj]);
                printf("\n");
            }

Summary: Round each cell of this matrix to the nearest integer (toward zero).
Sample data:
Header file: MatrixData.h
See also: Floor Round Ceil


FlipHorizontal

matrixbase::FlipHorizontal
Prototype:
PUBLIC  BOOL FlipHorizontal()
Remarks: Horizontally flips this matrixbase derived object about a vertical axis through the center of the matrix. For the example below, the first column will contain all 5's and the last column will contain all 1's after the flip.
Parameters:

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            mat.FlipHorizontal();

Summary: Horizontally flips this matrixbase derived object.
Sample data: // Matrix1 is 5 x 5 with following data 1 2 3 4 5 1 2 3 4 5 1 2 3 4 5 1 2 3 4 5 1 2 3 4 5
Header file: MatrixData.h
See also: FlipVertical Rotate Reorder Transpose


FlipVertical

matrixbase::FlipVertical
Prototype:
PUBLIC  BOOL FlipVertical()
Remarks: Vertically flips this matrixbase derived object about a horizontal axis through the center of the matrix. For the example below, the first row will contain all 5's and the last row will contain all 1's after the flip.
Parameters:

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            mat.FlipVertical();

Summary: Vertically flips this matrixbase derived object.
Sample data: // Matrix1 is 5 x 5 with following data 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 5 5 5 5 5
Header file: MatrixData.h
See also: FlipHorizontal Rotate Reorder Transpose


Floor

matrixbase::Floor
Prototype:
PUBLIC  int Floor(matrixbase & mbFloor)
Remarks: Round each cell of this matrix to the nearest integer less than the current cell value (toward minus infinity). .
Parameters:
mbFloor=Output matrix containing the results

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj,	nRows, nCols;
            matrix mResult;
            matrix mSource = {{1.001,2.009,-3.99999,4.0005,-5.999},
                              {-6.2000,7.345,8.9999,-9.0001,10.0001}};

            printf("The source data:\n");
            nCols = mSource.GetNumCols();
            nRows = mSource.GetNumRows();
            for( ii = 0; ii < nRows; ii++)
            {
                for(jj = 0; jj < nCols; jj++)
                printf("%g\t",mSource[ii][jj]);
                printf("\n");
            }

            mSource.Floor(mResult);

            printf("After Floor function:\n");
            for( ii = 0; ii < nRows; ii++)
            {
                for(jj = 0; jj < nCols; jj++)
                printf("%g\t",mResult[ii][jj]);
                printf("\n");
            }

Summary: Round each cell of this matrix to the nearest integer less than the current cell value (toward minus infinity).
Sample data:
Header file: MatrixData.h
See also: Fix Round Ceil


GetAmplitude

matrixbase::GetAmplitude
Prototype:
PUBLIC  BOOL GetAmplitude( matrix& mAmplitude )
Remarks: Get the amplitude(modulus) of the Complex matrix. Causes a runtime error if the underlying base type of the matrix is not Complex.
Parameters:
mAmplitude=Output matrix containing amplitude(modulus) matrix for this Complex matrix

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            matrix<complex> mComplex = { 1+2i, 3+4i };
            matrix mAmplitude1, mAmplitude2, mReal = { 1, 3 };
            mComplex.GetAmplitude( mAmplitude1 );
            printf( "mAmplitude1[0][0]=%g\nmAmplitude1[0][1]=%g", mAmplitude1[0][0], mAmplitude1[0][1] );
            mReal.GetAmplitude( mAmplitude2 ); // Causes runtime error

Summary: Get the amplitude(modulus) of the Complex matrix.
Sample data:
Header file: MatrixData.h
See also: GetReal GetImaginary GetPhase Conjugate Cross Inverse MakeComplex


GetAsVector

matrixbase::GetAsVector
Prototype:
PUBLIC  BOOL GetAsVector(vectorbase &vb, BOOL bByRow = TRUE)
Remarks: Get the values of an entire matrix and assign them to a vector. If the matrix and vector do not have the number of elements then the vector is dynamically resized.
Parameters:
vb=Vector used to get the matrix values
bByRow=Use Row order if TRUE otherwise use Column order

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            vector v1;
            mat.GetAsVector( v1, 4); // v1 = {0,1,2,3,4,1,2,3,4,5,2,3,4,5,6,3,4,5,6,7,4,5,6,7,8}

Summary: Get the values of an entire matrix and assign them to a vector.
Sample data: // Matrix1 is 5 x 5 with following data 0 1 2 3 4 1 2 3 4 5 2 3 4 5 6 3 4 5 6 7 4 5 6 7 8
Header file: MatrixData.h
See also: SetByVector GetRow SetRow GetColumn SetColumn


GetColumn

matrixbase::GetColumn
Prototype:
PUBLIC  BOOL GetColumn(vectorbase &vb, UINT wIndexCol)
Remarks: Get the values of a matrix column and assign them to a vector. The column is specified by a 0 based column index. If the matrix column and vector do not have the same size then the vector is dynamically resized.
Parameters:
vb=Vector used to get the matrix column values
nIndexCol=Specifies the 0 based offset or column index of the column in the matrix

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            vector v1;
            mat.GetColumn( v1, 2); // v1 = {2,3,4,5,6}

Summary: Get the values of a matrix column and assign them to a vector.
Sample data: // Matrix1 is 5 x 5 with following data 0 1 2 3 4 1 2 3 4 5 2 3 4 5 6 3 4 5 6 7 4 5 6 7 8
Header file: MatrixData.h
See also: SetColumn GetRow SetRow GetAsVector SetByVector


GetDiagonal

matrixbase::GetDiagonal
Prototype:
PUBLIC  int GetDiagonal(vectorbase & vbDiagonal, int nNthDiagonal = 0)
Remarks: Get the diagonal or N-th diagonal of this matrix and place the result in a vector. The result vector and this matrix must have the same underlying base type or a run time error will be generated.
Parameters:
vbDiagonal=The result vector containing the (N-th) diagonal
nNthDiagonal=The number specifying the N-th diagonal, default 0 is the main diagonal, > 0 is above
the main diagonal, and < 0 is below the main diagonal.

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj;

            matrix mSource = {{1,2,3},{4,5,6},{7,8,9}};
            printf("Source:\n");
            for(ii = 0; ii < mSource.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mSource.GetNumCols(); jj++)
                    printf("%g\t",mSource[ii][jj]);
                printf("\n");
            }

            vector vResult;
            mSource.GetDiagonal(vResult);
            printf("Diagonal:\n");
            for(ii = 0; ii < vResult.GetSize(); ii++)
                printf("%g\t",vResult[ii]);
            printf("\n");

            mSource.GetDiagonal(vResult,-1);
            printf("-1th Diagonal:\n");
            for(ii = 0; ii < vResult.GetSize(); ii++)
                printf("%g\t",vResult[ii]);
            printf("\n");

Summary: Get the diagonal or N-th diagonal of this matrix.
Sample data:
Header file: MatrixData.h
See also: SetDiagonal GetLowerTriangular GetUpperTriangular MakeIdentity


GetImaginary

matrixbase::GetImaginary
Prototype:
PUBLIC  BOOL GetImaginary( matrix &mImag )
Remarks: Get the Imaginary part of a Complex matrix. Causes a runtime error if the underlying base type of the matrix is not Complex.
Parameters:
mImag=Output matrix containing the Imaginary part of this Complex matrix

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            matrix<complex> mComplex = { 1+2i, 3+4i };
            matrix mImag1, mImag2;
            mComplex.GetImaginary( mImag1 );      // mImag1 = { 2, 4 };
            printf( "mImag1[0][0]=%g\nmImag1[0][1]=%g", mImag1[0][0], mImag1[0][1] );
            mImag1.GetImaginary( mImag2 );        // Causes runtime error

Summary: Get the Imaginary part of a Complex matrix.
Sample data:
Header file: MatrixData.h
See also: GetReal GetPhase GetAmplitude Conjugate Cross Inverse MakeComplex


GetLowerTriangular

matrixbase::GetLowerTriangular
Prototype:
PUBLIC  int GetLowerTriangular(matrixbase & mbResult, int nNumDiagonal = 0)
Remarks: Get a lower triangular matrix from this matrix. This matrix and the result matrix may be the same.
Parameters:
mbResult=The result matrix containing only the lower part
nNumDiagonal=Default 0 is the main diagonal, > 0 is above the
main diagonal, and < 0 is below the main diagonal.

Return values:
Returns 0 on success and a non-zero error code on failure.
-1=Internal cast error.

Example:
            int ii, jj;

            matrix mSource = {{1,2,3},{4,5,6},{7,8,9}};
            printf("Source:\n");
            for(ii = 0; ii < mSource.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mSource.GetNumCols(); jj++)
                    printf("%g\t",mSource[ii][jj]);
                printf("\n");
            }

            matrix mResult;
            mSource.GetLowerTriangular(mResult);

            printf("Lower Triangular:\n");
            for(ii = 0; ii < mResult.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mResult.GetNumCols(); jj++)
                    printf("%g\t",mResult[ii][jj]);
                printf("\n");
            }

Summary: Get a lower triangular matrix from this matrix.
Sample data:
Header file: MatrixData.h
See also: GetUpperTriangular MakeIdentity SetDiagonal GetDiagonal


GetMax

matrixbase::GetMax
Prototype:
PUBLIC  double GetMax()
Remarks: Get the maximum cell value in the matrix (as a double).
Parameters:

Return values:
Returns the maximum cell value in the matrix (as a double).

Example:
            // Assumes Matrix1 window in Origin
            double dMax;
            Matrix mat("Matrix1");
            dMax = mat.GetMax();

Summary: Returns the maximum cell value in the matrix.
Sample data:
Header file: MatrixData.h
See also: GetMin GetMean GetMedian


GetMean

matrixbase::GetMean
Prototype:
PUBLIC  double GetMean()
Remarks: Get the mean cell value of the matrix (as a double).
Parameters:

Return values:
Returns the mean cell value of the matrix (as a double).

Example:
            // Assumes Matrix1 window in Origin
            double dMean;
            Matrix mat("Matrix1");
            dMean = mat.GetMean();

Summary:
Sample data:
Header file: MatrixData.h
See also: GetMedian GetMin GetMax


GetMedian

matrixbase::GetMedian
Prototype:
PUBLIC  double GetMedian()
Remarks: Get the median cell value of the matrix (as a double). If there are an even number N of cells in the matrix the average of the N/2 and (N+1)/2 sorted cell values is returned.
Parameters:

Return values:
Returns the median cell value of the matrix (as a double).

Example:
            // Assumes Matrix1 window in Origin
            double dMedian;
            Matrix mat("Matrix1");
            dMedian = mat.GetMedian();

Summary:
Sample data:
Header file: MatrixData.h
See also: GetMean GetMin GetMax


GetMin

matrixbase::GetMin
Prototype:
PUBLIC  double GetMin()
Remarks: Get the minimum cell value in the matrix (as a double).
Parameters:

Return values:
Returns the minimum cell value in the matrix (as a double).

Example:
            // Assumes Matrix1 window in Origin
            double dMin;
            Matrix mat("Matrix1");
            dMin = mat.GetMin();

Summary:
Sample data:
Header file: MatrixData.h
See also: GetMax GetMean GetMedian


GetNumCols

matrixbase::GetNumCols
Prototype:
PUBLIC  UINT GetNumCols() const
Remarks: Get the number of columns in any matrixbase derived object (e.g. matrix, Matrix).
Parameters:

Return values:
Returns the number of columns in this matrixbase object.

Example:
            // Assumes Matrix1 window in Origin
            Matrix mat("Matrix1");
            int iNumCols;
            iNumCols = mat.GetNumCols(); // Get number of columns

Summary: Get the number of columns in any matrixbase derived object.
Sample data:
Header file: MatrixData.h
See also: SetSize GetNumRows


GetNumRows

matrixbase::GetNumRows
Prototype:
PUBLIC  UINT GetNumRows() const
Remarks: Get the number of rows in any matrixbase derived object (e.g. matrix, Matrix).
Parameters:

Return values:
Returns the number of rows in this matrixbase object.

Example:
            // Assumes Matrix1 window in Origin
            Matrix mat("Matrix1");
            int iNumRows;
            iNumRows = mat.GetNumRows(); // Get number of rows

Summary: Get the number of rows in any matrixbase derived object.
Sample data:
Header file: MatrixData.h
See also: SetSize GetNumCols


GetPhase

matrixbase::GetPhase
Prototype:
PUBLIC  BOOL GetPhase( matrix& mPhase )
Remarks: Get the phase angle matrix, in radians, of the Complex matrix. Causes a runtime error if the underlying base type of the matrix is not Complex.
Parameters:
mPhase=Output matrix containing the phase angle matrix for this Complex matrix

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            matrix<complex> mComplex = { 1+2i, 3+4i };
            matrix mPhase1, mPhase2, mReal = { 1, 3 };
            mComplex.GetPhase( mPhase1 );
            printf( "mPhase1[0][0]=%g\nmPhase1[0][1]=%g", mPhase1[0][0], mPhase1[0][1] );
            mReal.GetPhase( mPhase2 ); // Causes runtime error

Summary: Get the phase angle matrix, in radians, of the Complex matrix.
Sample data:
Header file: MatrixData.h
See also: GetReal GetImaginary GetAmplitude Conjugate Cross Inverse MakeComplex


GetReal

matrixbase::GetReal
Prototype:
PUBLIC  BOOL GetReal( matrix &mReal )
Remarks: Get the Real part of a Complex matrix. Causes a runtime error if the underlying base type of the matrix is not Complex.
Parameters:
mReal=Output matrix containing the Real part of this Complex matrix

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            matrix<complex> mComplex = { 1+2i, 3+4i };
            matrix mReal1, mReal2;
            mComplex.GetReal( mReal1 );  // mReal1 = { 1, 3 };
            printf( "mReal1[0][0]=%g\nmReal1[0][1]=%g", mReal1[0][0], mReal1[0][1] );
            mReal1.GetReal( mReal2 );    // Causes runtime error

Summary: Get the Real part of a Complex matrix.
Sample data:
Header file: MatrixData.h
See also: GetImaginary GetPhase GetAmplitude Conjugate Cross Inverse MakeComplex


GetRow

matrixbase::GetRow
Prototype:
PUBLIC  BOOL GetRow(vectorbase &vb, UINT wIndexRow)
Remarks: Get the values of a matrix row and assign them to a vector. The row is specified by a 0 based row index. If the matrix row and vector do not have the same size then the vector is dynamically resized.
Parameters:
vb=Vector used to get the matrix row values
nIndexRow=Specifies the 0 based offset or row index of the row in the matrix

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            vector v1;
            mat.GetRow( v1, 4); // v1 = {4,5,6,7,8}

Summary: Get the values of a matrix row and assign them to a vector.
Sample data: // Matrix1 is 5 x 5 with following data 0 1 2 3 4 1 2 3 4 5 2 3 4 5 6 3 4 5 6 7 4 5 6 7 8
Header file: MatrixData.h
See also: SetRow GetColumn SetColumn GetAsVector SetByVector


GetSubMatrix

matrixbase::GetSubMatrix
Prototype:
PUBLIC  BOOL GetSubMatrix( matrixbase& mbTarget, int c1 = 0, int c2 = -1, int r1 = 0, int r2 = -1)
Remarks: Get a subset of this matrix specified by 0 based column and row indices.
Parameters:
mbTarget=Matixbase derived object containing returned matrixbase subset
c1=Begining column index, default is 0 (0 based offset)
c2=Ending column index, (inclusive) default -1 is GetNumCols -1 (0 based offset)
r1=Begining row index, default is 0 (0 based offset)
r2=Ending row index, (inclusive) default -1 is GetNumRows -1 (0 based offset)

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            matrix m1, m2;
            m1.SetSize( 10, 10 );
            m1.GetSubMatrix( m2, 5, -1, 5 ); // Copy lower right quarter of matrix m1 into matrix m2
            ASSERT( m2.GetNumCols()==5 );
            ASSERT( m2.GetNumRows()==5 );

Summary: -1 means to last col/row
Sample data:
Header file: MatrixData.h
See also:


GetUpperTriangular

matrixbase::GetUpperTriangular
Prototype:
PUBLIC  int GetUpperTriangular(matrixbase & mbResult, int nNthDiagonal = 0)
Remarks: Get an upper triangular matrix from this matrix. This matrix and the result matrix may be the same.
Parameters:
mbResult=The result matrix containing only the lower part
nNthDiagonal=The number specifying N-th diagonal, default 0 is the main diagonal, > 0 is above
the main diagonal, and < 0 is below the main diagonal.

Return values:
Returns 0 on success and a non-zero error code on failure.
-1=Internal cast error.

Example:
            int ii, jj;

            matrix mSource = {{1,2,3},{4,5,6},{7,8,9}};
            printf("Source:\n");
            for(ii = 0; ii < mSource.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mSource.GetNumCols(); jj++)
                    printf("%g\t",mSource[ii][jj]);
                printf("\n");
            }

            matrix mResult;
            mSource.GetUpperTriangular(mResult);

            printf("Upper Triangular:\n");
            for(ii = 0; ii < mResult.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mResult.GetNumCols(); jj++)
                    printf("%g\t",mResult[ii][jj]);
                printf("\n");
            }

Summary: Get an upper triangular matrix from this matrix.
Sample data:
Header file: MatrixData.h
See also: GetLowerTriangular MakeIdentity SetDiagonal GetDiagonal


IFFTShift

matrixbase::IFFTShift
Prototype:
PUBLIC  int IFFTShift(matrixbase & mbShifted, int nDim = -1)
Remarks: Inverse FFTShift. Inverse FFTShifts can occur row wise or relative to the first dimension (nDim=1), column wise or relative to the second dimension (nDim=2), or relative to both or the first dimension and then the second dimension (nDim=-1 default). The result matrix and this matrix can be the same (i.e m1.IFFTShift(m1);).
Parameters:
mbShifted=The output matrix in which the un-shifted matrix is returned
nDim=Inverse FFTShifts can occur row wise (relative to the first dimension when nDim=1), column wise (relative
to the second dimension when nDim=2), or relative to both or the first dimension and then the second
dimension (when nDim=-1 default)

Return values:
Returns 0 on success and a non-zero error code on failure:
-1=nDim is not -1, 1, or 2
-2=Internal casting error

Example:
            matrix mSource = {{1,2,3},{4,5,6},{7,8,9}};
            matrix mShifted;
            int ii, jj;
            printf("Before shifting:\n");
            for(ii = 0; ii < mSource.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mSource.GetNumCols(); jj++)
                    printf("%g\t",mSource[ii][jj]);
                printf("\n");
            }

            mSource.FFTShift(mShifted);
            printf("After shifting for FFT:\n");
            for(ii = 0; ii < mShifted.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mShifted.GetNumCols(); jj++)
                    printf("%g\t",mShifted[ii][jj]);
                printf("\n");
            }

            mShifted.IFFTShift(mShifted);
            printf("After un-shifting (IFFTShift) for FFT:\n");
            for(ii = 0; ii < mShifted.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mShifted.GetNumCols(); jj++)
                    printf("%g\t",mShifted[ii][jj]);
                printf("\n");
            }

Summary: Inverse FFTShift.
Sample data:
Header file: MatrixData.h
See also: FFTShift


Inverse

matrixbase::Inverse
Prototype:
PUBLIC  int Inverse()
Remarks: Replace this matrix with the Inverse of this matrix. An error is returned if the underlying base type of the matrix is not double.
Parameters:

Return values:
Returns 0 on success or one of the following error codes on failure:
-1=Matrix is not N x N
-2=Underlying type of matrix is not double
-3=Can not find the function in the Nag DLL
Nag Errors:
11=The column or row size of the matrix is less than 1
73=System failed to allocate memory
357=Matrix is singular (it has no inverse)

Example:
            matrix<double> mA(2,2), mB(2,2), mI(2,2);
            mA[0][0]= 3; mA[0][1]=-2;
            mA[1][0]=-1; mA[1][1]= 1;
            mB = mA;

            mA.Inverse();

            // Show mA x mB = mI = | 1 0 |
            //                     | 0 1 |
            mI[0][0]=mA[0][0]*mB[0][0]+mA[0][1]*mB[1][0];
            mI[0][1]=mA[0][0]*mB[0][1]+mA[0][1]*mB[1][1];
            mI[1][0]=mA[1][0]*mB[0][0]+mA[1][1]*mB[1][0];
            mI[1][1]=mA[1][0]*mB[0][1]+mA[1][1]*mB[1][1];

            printf( "mA\t\tx\t\tmB\t\t=\t\tmI\n" );
            printf( "| %g %g |\t\t\t| %g %g |\t\t\t| %g %g |\n", mA[0][0], mA[0][1], mB[0][0], mB[0][1], mI[0][0], mI[0][1] );
            printf( "| %g %g |\t\t\t| %g %g |\t\t\t| %g %g |\n", mA[1][0], mA[1][1], mB[1][0], mB[1][1], mI[1][0], mI[1][1] );

Summary: Replace this matrix with the Inverse of this matrix.
Sample data:
Header file: MatrixData.h
See also: GetReal GetImaginary GetPhase GetAmplitude Conjugate Cross MakeComplex


MakeComplex

matrixbase::MakeComplex
Prototype:
PUBLIC  int MakeComplex(matrixbase & mbReal, matrixbase & mbImag)
Remarks: Make a Complex matrix from two Real matrices (which must have the same dimensions).
Parameters:
mbReal=The matrix containing the Real part
mbImag=The matrix containing the Imaginary part

Return values:
Returns 0 on success and -1 on failure.

Example:
            matrix mA(2,2), mB(2,2);
            matrix<complex> mC(2,2);

            mA[0][0] = 1;			mB[0][0] = -2;
            mA[0][1] = -3;			mB[0][1] = 1;
            mA[1][0] = 4;			mB[1][0] =2;
            mA[1][1] = 5;			mB[1][1] = -3;

            mC.MakeComplex(mA,mB);

            for(int ii = 0; ii < 2; ii++)
                for(int jj = 0; jj < 2; jj++)
                    printf("%g + %gi\n",mC[ii][jj].m_re,mC[ii][jj].m_im);

Summary: Make a Complex matrix from two Real matrices.
Sample data:
Header file: MatrixData.h
See also: CastToInteger CastToDouble GetReal GetImaginary GetPhase GetAmplitude Conjugate Cross Inverse


MakeIdentity

matrixbase::MakeIdentity
Prototype:
PUBLIC  int MakeIdentity(int mNumRows, int nNumCols = -1)
Remarks: Make this matrix an N x N identity matrix or an M x N rectangular matrix with 1's on the diagonal and zeros elsewhere.
Parameters:
mNumRows=Number of rows in the result matrix
nNumCols=Number of columns of the result matrix (default -1 means mNumRows = nNumCols)

Return values:
Returns 0 on success or an error code on failure:
-1=nNumCols and mNumRows are not positive integers (nNumCols can be -1)

Example:
            int ii, jj,	nRows, nCols;
            matrix mIdentity;

            mIdentity.MakeIdentity(4);
            nCols = mIdentity.GetNumCols();
            nRows = mIdentity.GetNumRows();
            for( ii = 0; ii < nRows; ii++)
            {
                for(jj = 0; jj < nCols; jj++)
                    printf("%g\t",mIdentity[ii][jj]);
                printf("\n");
            }

Summary:
Sample data:
Header file: MatrixData.h
See also: GetLowerTriangular GetUpperTriangular


MedianFilter

matrixbase::MedianFilter
Prototype:
PUBLIC  BOOL MedianFilter(int nWindowSize, int nPaddingOption = 0)
Remarks: MedianFilter examines the N x N pixels centered around each pixel of an image (matrix), finds the median value of the N x N pixels, and then replaces the central pixel with the median value. It is a useful filter to remove spot noise (white spots, black spots) in an image because such noisy pixels have values way off the median value.
Parameters:
nWindowSize=The size of the window (N) for median filter
nPaddingOption=Pads the area outside the borders in one of the following ways
nPaddingOption=0 -- pads with zeroes
nPaddingOption=1 -- pads with values from adjacent cells

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            mat.MedianFilter(3,1); // Use 3 x 3 median filter padding outside borders with adjacent cells
            // Results in all cells of Matrix1 = 2

Summary: Median filter.
Sample data: // Matrix1 is 5 x 5 with following data 2 2 2 2 2 100 2 2 100 2 2 2 2 2 2 2 100 2 2 2 2 2 2 2 2
Header file: MatrixData.h
See also: ApplyFilter


Padding

matrixbase::Padding
Prototype:
PUBLIC  BOOL Padding( matrixbase &mPadding, int nPadSize, int nPaddingOption = 0 )
Remarks: Pad a matrix with 0 or with adjacent cell values.
Parameters:
mPadding=Output matrix with padded cells having same underlying base type of this matrix
nPadSize=Input padding width, must be larger than 0
nPaddingOption=Input padding method, 0 pads with zeroes and 1 pads with adjacent cell values

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 and Matrix2 exist in Origin
            Matrix mat1("Matrix1"), mat2("Matrix2");
            mat1.Padding( mat2, 2, 1 );

Summary: Pad a matrix with 0 or with adjacent cell values.
Sample data:
Header file: MatrixData.h
See also:


RemoveEmptyRows

matrixbase::RemoveEmptyRows
Prototype:
PUBLIC  int RemoveEmptyRows(BOOL bOnlyRemoveEmptyRows = TRUE)
Remarks: Remove any row in the matrix that consists entirely of missing values (i.e. remove empty rows). Optionally remove any row that contains one or more missing values. This function is useful for removing missing values from data and for determining whether or not analysis can logically proceed on data that is paired row wise.
Parameters:
bOnlyRemoveEmptyRows=When TRUE only remove rows consisting entirely of missing values. When FALSE
remove all rows containing one or more missing values

Return values:
Returns -1 * the row number (1 based offset) of the first row that contains a missing value but that
does not consist entirely of missing values (the first row that contains a missing value but that is not
empty) otherwise the number of rows removed is returned.

Example:
            // Assumes Matrix1 window in Origin
            int nRowIndex;
            Matrix mat("Matrix1");
            nRowIndex = mat.RemoveEmptyRows();

Summary:
Sample data:
Header file: MatrixData.h
See also:


Reorder

matrixbase::Reorder
Prototype:
PUBLIC  BOOL Reorder(BOOL bRowOrder = TRUE)
Remarks: Re-order a matrix from Column order to Row order or from Row order to Column order.
Parameters:
bRowOrder=If TRUE re-order to Row order and if FALSE re-order to Column order

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            mat.Reorder();

Summary: Re-order a matrix from Column order to Row order or from Row order to Column order.
Sample data: // Matrix1 is 5 x 3 with following data 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 // Matrix1 after running Example program 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3
Header file: MatrixData.h
See also: FlipHorizontal FlipVertical Rotate Transpose


ReorderRowWise

matrixbase::ReorderRowWise
Prototype:
PUBLIC  BOOL ReorderRowWise(const vector<UINT>& vnIndeces, int nC1 = 0, int nC2 = -1 )
Remarks: rearrange the matrix according to the given indeces
Parameters:
vnIndeces = array or row index to reorder a column
nC1 = 1st Column index to reorder
nC2 = last Column index to reorder, use -1 to indicate the last column in matrix

Return values:

Example:
        vector<UINT> vn = {2,1,0};
        matrix<int> mm1 = {{1,1},{2,2},{3,3}};
        mm1.ReorderRowWise(vn, 0);
        // result mm1 = {{3,3},{2,2},{1,1}};

Summary:
Sample data:
Header file: MatrixData.h
See also:


Replace

matrixbase::Replace
Prototype:
PUBLIC  BOOL Replace( double dThresholdVal, double dReplaceVal = 0, uint wBitwiseOption = 0 )
Remarks: Threshold replace for a matrix.
Parameters:
dThresholdVal=Threshold value to compare to cells in matrix
dReplaceVal=Replacement value to use when decision passes
wBitwiseOption=Combination of the following bits
Bit Value Meaning 	                              Group
0    1    Use Less Than in testing                TEST
1    2    Use Equal in testing                    TEST
2    4    Use Greater Than in testing             TEST
3    8    Use Absolute values in testing          TEST
4    16   Keep original sign when test is TRUE    ACTION
5    32   Set to missing value when test is FALSE ACTION
The following are also defined in the header file \OriginC\system\OC_const.h
MATREPL_TEST_LESSTHAN	= 1,
MATREPL_TEST_EQUAL		= 2,
MATREPL_TEST_GREATER	= 4,
MATREPL_USE_ABSOLUTE_VALUE_IN_TEST	= 8,
MATREPL_KEEP_ORIGINAL_SIGN_WHEN_TEST_RESULT_IS_TRUE		= 16,
MATREPL_SET_TO_MISSING_VALUE_WHEN_TEST_RESULT_IS_FALSE	= 32

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            // Assumes Matrix1 exists in Origin and contains some missing values (NANUM)
            Matrix mat1("Matrix1");
            // Change all missing values (NANUM) in Matrix1 to 0 and all other values to missing values
            mat1.Replace( NANUM, 0, MATREPL_TEST_EQUAL | MATREPL_SET_TO_MISSING_VALUE_WHEN_TEST_RESULT_IS_FALSE );

Summary:
Sample data:
Header file: MatrixData.h
See also:


ReplaceGreaterThan

matrixbase::ReplaceGreaterThan
Prototype:
PUBLIC  BOOL ReplaceGreaterThan(double dThresholdVal, double dReplaceVal)
Remarks: Replace all cell values greater than dThresholdVal with dReplaceVal.
Parameters:
dThresholdVal=Condition or threshold value
dReplaceVal=Replacement value

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            mat.ReplaceGreaterThan(4,0);

Summary: Replace all cell values greater than dThresholdVal with dReplaceVal.
Sample data: // Matrix1 is 5 x 5 with following data 0 1 2 3 4 1 2 3 4 5 2 3 4 5 6 3 4 5 6 7 4 5 6 7 8 // Matrix1 after running Example program 0 1 2 3 4 1 2 3 4 0 2 3 4 0 0 3 4 0 0 0 4 0 0 0 0
Header file: MatrixData.h
See also: Replace ReplaceLessThan


ReplaceLessThan

matrixbase::ReplaceLessThan
Prototype:
PUBLIC  BOOL ReplaceLessThan(double dThresholdVal, double dReplaceVal)
Remarks: Replace all cell values less than dThresholdVal with dReplaceVal.
Parameters:
dThresholdVal=Condition or threshold value
dReplaceVal=Replacement value

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            mat.ReplaceLessThan(4,0);

Summary: Replace all cell values less than dThresholdVal with dReplaceVal.
Sample data: // Matrix1 is 5 x 5 with following data 0 1 2 3 4 1 2 3 4 5 2 3 4 5 6 3 4 5 6 7 4 5 6 7 8 // Matrix1 after running Example program 0 0 0 0 4 0 0 0 4 5 0 0 4 5 6 0 4 5 6 7 4 5 6 7 8
Header file: MatrixData.h
See also: Replace ReplaceGreaterThan


Rotate

matrixbase::Rotate
Prototype:
PUBLIC  BOOL Rotate(int nAngleDegree = 90 )
Remarks: Rotates the matrix counter-clockwize by the specified angle. Angles must be multiples of 90 degrees but can be negative. Rotating a matrix by 90 degrees has the simultaneous effect of making the first row become the last column, the last column becomes the last row in reverse order, the last row becomes the first column, and the first column becomes the first row in reverse order.
Parameters:
nAngleDegree=The rotation angle in degrees, can be negative but must be a multiple
of 90 otherwise the closest multiple is used

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            mat.Rotate(90);

Summary: Rotates the matrix counter-clockwize by the specified angle.
Sample data: // Matrix1 is 5 x 5 with following data 0 1 2 3 4 1 2 3 4 5 2 3 4 5 6 3 4 5 6 7 4 5 6 7 8 // Matrix1 after running Matrix1 after running // Example program once Example program twice 4 5 6 7 8 8 7 6 5 4 3 4 5 6 7 7 6 5 4 3 2 3 4 5 6 6 5 4 3 2 1 2 3 4 5 5 4 3 2 1 0 1 2 3 4 4 3 2 1 0
Header file: MatrixData.h
See also: FlipHorizontal FlipVertical Reorder Transpose


Round

matrixbase::Round
Prototype:
PUBLIC  int Round(matrixbase & mbRound)
Remarks: Round each cell of this matrix to the nearest integer (absolute nearest). .
Parameters:
mbRound=Output matrix containing the results

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj,	nRows, nCols;
            matrix mResult;
            matrix mSource = {{1.001,2.009,-3.99999,4.0005,-5.999},
                              {-6.2000,7.345,8.9999,-9.0001,10.0001}};

            printf("The source data:\n");
            nCols = mSource.GetNumCols();
            nRows = mSource.GetNumRows();
            for( ii = 0; ii < nRows; ii++)
            {
                for(jj = 0; jj < nCols; jj++)
                    printf("%g\t",mSource[ii][jj]);
                printf("\n");
            }

            mSource.Round(mResult);

            printf("After Round function:\n");
            for( ii = 0; ii < nRows; ii++)
            {
                for(jj = 0; jj < nCols; jj++)
                    printf("%g\t",mResult[ii][jj]);
                printf("\n");
            }

Summary: und each cell of this matrix to the nearest integer (absolute nearest).
Sample data:
Header file: MatrixData.h
See also: Floor Fix Ceil


SetByVector

matrixbase::SetByVector
Prototype:
PUBLIC  int SetByVector(vectorbase &vb, BOOL bByRow = TRUE)
Remarks: Set the values of a matrix equal to the values of a vector. If the matrix has more elements than the vector then vector values are assigned until they are exausted and the remaining matrix values are left untouched. If the vector has more elements than the matrix then vector values are assigned to the last element of the matrix and the remaining elements of the vector are ignored.
Parameters:
vb=Vector used to set the matrix values
bByRow=Use Row order if TRUE otherwise use Column order

Return values:
0 if successful and the number of elements in the vector is the same as the number of elements
in the matrix otherwise the number of elements in the matrix minus the number of elements in the
vector is returned.

Example:
            // Assumes 5 x 5 Matrix1 window in Origin
            Matrix mat("Matrix1");
            vector v1 = {0,1,2,3,4,0,1,2,3,4,0,1,2,3,4,0,1,2,3,4,0,1,2,3,4};
            mat.SetByVector( v1, FALSE); // Use Column order
            // Results in Matrix1
            // 0	0	0	0	0
            // 1	1	1	1	1
            // 2	2	2	2	2
            // 3	3	3	3	3
            // 4	4	4	4	4

Summary: Set the values of a matrix equal to the values of a vector.
Sample data:
Header file: MatrixData.h
See also: GetAsVector SetRow GetRow SetColumn GetColumn


SetColumn

matrixbase::SetColumn
Prototype:
PUBLIC  int SetColumn(vectorbase &vb, UINT wIndexCol)
Remarks: Set the values of a matrix column equal to the values of a vector. The column is specified by a 0 based column index. If the matrix column and vector do not have the same size then the maximum number of elements possible are assigned from the vector to the matrix column.
Parameters:
vb=Vector whose values are assigned to the column
nIndexCol=Specifies the 0 based offset or column index of the column in the matrix

Return values:
Returns 0 if successful and the vector size matches the matrix column size,
otherwise returns the size of the matrix column minus the size of the vector.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            vector v = {-99,-99,-99,-99,-99};
            mat.SetColumn( v, 2);

Summary: Set the values of a matrix column equal to the values of a vector.
Sample data: // Matrix1 is 5 x 5 with following data 0 1 2 3 4 1 2 3 4 5 2 3 4 5 6 3 4 5 6 7 4 5 6 7 8 // Matrix1 after running Example program 0 1 -99 3 4 1 2 -99 4 5 2 3 -99 5 6 3 4 -99 6 7 4 5 -99 7 8
Header file: MatrixData.h
See also: GetColumn SetRow GetRow GetAsVector SetByVector


SetDiagonal

matrixbase::SetDiagonal
Prototype:
PUBLIC  int SetDiagonal(vectorbase & vbDiagonal, int nNthDiagonal = 0)
Remarks: Set the diagonal or N-th diagonal of this matrix from a vector and set all other elements to 0. The source vector and this matrix must have the same underlying base type or a run time error will be generated.
Parameters:
vbDiagonal=The source vector containing the (N-th) diagonal
nNthDiagonal=The number specifying the N-th diagonal, default 0 is the main diagonal, > 0 is above
the main diagonal, and < 0 is below the main diagonal.

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, jj;

            matrix mResult = {{1,2,3},{4,5,6},{7,8,9}};
            printf("Result:\n");
            for(ii = 0; ii < mResult.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mResult.GetNumCols(); jj++)
                    printf("%g\t",mResult[ii][jj]);
                printf("\n");
            }

            vector vSource = {1,1};
            mResult.SetDiagonal(vSource,1);
            printf("Result after diagonal is set to 0:\n");
            for(ii = 0; ii < mResult.GetNumRows(); ii++)
            {
                for(jj = 0; jj < mResult.GetNumCols(); jj++)
                    printf("%g\t",mResult[ii][jj]);
                printf("\n");
            }

Summary: Set the diagonal or N-th diagonal of this matrix.
Sample data:
Header file: MatrixData.h
See also: GetDiagonal GetLowerTriangular GetUpperTriangular MakeIdentity


SetRow

matrixbase::SetRow
Prototype:
PUBLIC  int SetRow(vectorbase &vb, UINT wIndexRow)
Remarks: Set the values of a matrix row equal to the values of a vector. The row is specified by a 0 based row index. If the matrix row and vector do not have the same size then the maximum number of elements possible are assigned from the vector to the matrix row.
Parameters:
vb=Vector whose values are assigned to the row
nIndexRow=Specifies the 0 based offset or row index of the row in the matrix

Return values:
Returns 0 if successful and the vector size matches the matrix row size,
otherwise returns the size of the matrix row minus the size of the vector.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            vector v = {-99,-99,-99,-99,-99};
            mat.SetRow( v, 2);

Summary: Set the values of a matrix row equal to the values of a vector.
Sample data: // Matrix1 is 5 x 5 with following data 0 1 2 3 4 1 2 3 4 5 2 3 4 5 6 3 4 5 6 7 4 5 6 7 8 // Matrix1 after running Example program 0 1 2 3 4 1 2 3 4 5 -99 -99 -99 -99 -99 3 4 5 6 7 4 5 6 7 8
Header file: MatrixData.h
See also: GetRow SetColumn GetColumn GetAsVector SetByVector


SetSize

matrixbase::SetSize
Prototype:
PUBLIC  BOOL SetSize(UINT wNumRows, UINT wNumCols)
Remarks: Set the size (number of columns and number of rows) in any matrixbase derived object (e.g. matrix, Matrix).
Parameters:
wNumRows=The number of rows in the newly sized matrix
wNumCols=The number of columns in the newly sized matrix

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            matrix m;
            int iNumRows = 7;
            int iNumCols = 5;
            m.SetSize( iNumRows, iNumCols );      // Set the number of rows and columns in matrix
            ASSERT( m.GetNumRows() == iNumRows);  // Check the number of rows is correct
            ASSERT( m.GetNumCols() == iNumCols ); // Check the number of columns is correct

Summary: Set the size of any matrixbase derived object.
Sample data:
Header file: MatrixData.h
See also: GetNumRows GetNumCols


SetSubMatrix

matrixbase::SetSubMatrix
Prototype:
PUBLIC  BOOL SetSubMatrix(matrixbase& mbSource, int c1 = 0, int r1 = 0)
Remarks: Set a subset of this matrix specified by 0 based column and row indices. The source and target matrices can have different types and different dimensions but the target matrix is never resized even if the source matrix is larger than the target.
Parameters:
mbSource = matixbase oject containing the subset to set
c1 = Begining column index in the target matrix, default is 0 (0 based offset)
r1 = Begining row index in the target matrix, default is 0 (0 based offset)

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
            Matrix mat1("Matrix1");
            Matrix mat2("Matrix2");
            mat2.SetSubMatrix(mat1, 10, 10);

            matrix<double> mtxSrc = { {1.1,2.1}, {3.1,4.2} };
            matrix<int> mtxDest = 	 { {0,0,0,0}, {0,0,0,0}, {0,0,0,0}, {0,0,0,0} };

            mtxDest.SetSubMatrix(mtxSrc, 0, 0);

            ASSERT(mtxDest[0][0] == 1);
            ASSERT(mtxDest[0][1] == 2);
            ASSERT(mtxDest[0][2] == 0);
            ASSERT(mtxDest[0][3] == 0);

            ASSERT(mtxDest[1][0] == 3);
            ASSERT(mtxDest[1][1] == 4);
            ASSERT(mtxDest[1][2] == 0);
            ASSERT(mtxDest[1][3] == 0);

            ASSERT(mtxDest[2][0] == 0);
            ASSERT(mtxDest[2][1] == 0);
            ASSERT(mtxDest[2][2] == 0);
            ASSERT(mtxDest[2][3] == 0);

            ASSERT(mtxDest[3][0] == 0);
            ASSERT(mtxDest[3][1] == 0);
            ASSERT(mtxDest[3][2] == 0);
            ASSERT(mtxDest[3][3] == 0);

Summary:
Sample data:
Header file: MatrixData.h
See also:


Shrink

matrixbase::Shrink
Prototype:
PUBLIC  BOOL Shrink( int nColShrinkFactor, int nRowShrinkFactor )
Remarks: Shrink this matrix by averaging cell values together according to the column and row shrink factors. This is similar to the LabTalk mat.Shrink() method.
Parameters:
dColShrinkFactor=column shrink factor
dRowShrinkFactor=row shrink factor

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
             matrix m1;
             m1.SetSize( 15, 12 );
             m1.Shrink( 3, 5 );
             ASSERT( m1.GetNumCols()==4 );
             ASSERT( m1.GetNumRows()==3 );

Summary:
Sample data:
Header file: MatrixData.h
See also:


Sort

matrixbase::Sort
Prototype:
PUBLIC  void Sort(BOOL bAscending = TRUE)
Remarks: Sort a matrix in row order (across rows from top/left to bottom/right). The matrix 1 5 9 1 2 3 2 6 10 4 5 6 3 7 11 7 8 9 4 8 12 would become the matrix 10 11 12 after sorting. This function does not maintain row wise integrity.
Parameters:
bAscending=Sort in ascending order if TRUE otherwise sort in descending order

Return values:

Example:
            // Assumes Matrix1 window in Origin with unsorted data
            Matrix mat("Matrix1");
            mat.Sort();

Summary:
Sample data:
Header file: MatrixData.h
See also:


SumColumns

matrixbase::SumColumns
Prototype:
PUBLIC  int SumColumns(vectorbase & vbSum)
Remarks: Sum the columns of this matrix placing the result in a vector. The underlying base type of the vector must not be less than the underlying base type of the matrix.
Parameters:
vbSum=Output vector containing the summed columns

Return values:
Returns 0 on success and -1 on failure.

Example:
            matrix<complex> mC = { {1+2i,2+1i,3-5i},
                                   {1+2i,2+2i,7-3i} };
            vector<complex> vC(2);
            mC.SumColumns(vC);
            for(int ii = 0; ii < 3; ii++)
                printf("\t%g+%gi",vC[ii].m_re,vC[ii].m_im);

Summary: Sum the columns of this matrix placing the result in a vector.
Sample data:
Header file: MatrixData.h
See also:


Transpose

matrixbase::Transpose
Prototype:
PUBLIC  BOOL Transpose()
Remarks: Transpose a matrix. Rows become columns and columns become rows.
Parameters:

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            // Assumes Matrix1 window in Origin with Sample Data
            Matrix mat("Matrix1");
            mat.Transpose();

Summary: Transpose a matrix.
Sample data: // Matrix1 is 5 x 3 with following data 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 // Matrix1 after running Example program 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3
Header file: MatrixData.h
See also: FlipHorizontal FlipVertical Rotate Transpose


Wrap

matrixbase::Wrap
Prototype:
PUBLIC  BOOL Wrap(int nRowNum=0, int nColNum =0)
Remarks: Wrap around elements.
Parameters:
when the value is 0, no wrap, when value less than zero, do left_wrap, other wise do right_wrap.

Return values:

Example:
            matrix mat = {{1,2,3,4,5}, {6,7,8,9,10}, {11,12,13,14,15}};
            mat.Wrap(0, 2);
            ==> {{3,4,5,1,2}, {8,9,10,6,7}, {13,14,15,11,12}}
            mat.Wrap(2, 0);
            ==> {{11,12,13,14,15}, {1,2,3,4,5}, {6,7,8,9,10}}

Summary:
Sample data:
Header file: MatrixData.h
See also:


PropertyNode

Class: PropertyNode

Description:

Hierarchy:

PropertyNode

Sample:


PropertyNode

PropertyNode::PropertyNode
Prototype:
PUBLIC  PropertyNode()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Tree.h
See also:
PropertyNode::PropertyNode
Prototype:
PUBLIC  PropertyNode(PropertyNode &tn)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Tree.h
See also:


string

Class: string

Description: An Origin C string is a null terminated array of characters similar to objects created using the MFC CString class. The Origin C string class includes many useful methods for manipulating strings (text data). An array of strings has been implmented using the following type definition: typedef vector<string> StringArray;

Hierarchy:

string

Sample:

        string str = "  abcdefg   ";
        str.TrimRight();
        str.TrimLeft();
        ASSERT( str.Compare("abcdefg")==0 );
        ASSERT( str.Compare("ABCDEFG")!=0 );
        ASSERT( str.CompareNoCase("ABCDEFG")==0 );
        str = str.Left(5);
        str = str.Mid(1);
        ASSERT( str.Compare("bcde")==0 );
        ASSERT( str.Find('d')==2 );


Compare

string::Compare
Prototype:
PUBLIC  int Compare( LPCSTR lpsz )
Remarks: This member function performs a case-sensitive comparison of this string object with another string.
Parameters:
lpsz = The other string used for comparison.

Return values:
Zero if the strings are identical, < 0 if this string
object is less than lpsz, or > 0 if this string object
is greater than lpsz.

Example:
            string str1("abc");
            string str2("abd");
            ASSERT(str1.Compare("abb")==1);
            ASSERT(str1.Compare(str2)==-1);
            ASSERT(str1.Compare("abc")==0);

Summary:
Sample data:
Header file: string.h
See also: CompareNoCase


CompareNoCase

string::CompareNoCase
Prototype:
PUBLIC  int CompareNoCase( LPCSTR lpsz )
Remarks: This member function performs a case-insensitive comparison of this string object with another string.
Parameters:
lpsz = The other string used for comparison.

Return values:
Zero if the strings are identical, < 0 if this string
object is less than lpsz, or > 0 if this string object
is greater than lpsz.

Example:
            string str1("abc");
            string str2("ABD");
            ASSERT(str1.CompareNoCase("abb")==1);
            ASSERT(str1.CompareNoCase(str2)==-1);
            ASSERT(str1.CompareNoCase("ABC")==0);

Summary:
Sample data:
Header file: string.h
See also: Compare


Delete

string::Delete
Prototype:
PUBLIC  int Delete( int nIndex, int nCount = 1 )
Remarks: This member function deletes a character or characters from a string starting with the character at nIndex. If nCount is longer than the string, the remainder of the string will be removed.
Parameters:
nIndex = The index of the first character to delete.
nCount = The number of characters to be removed.

Return values:
The length of the changed string.

Example:
            string str("Summer is best");
            str.Delete(6,3);
            ASSERT(0 == str.Compare("Summer best"));
            ASSERT(str.GetLength()==11);

Summary:
Sample data:
Header file: string.h
See also: Insert


Empty

string::Empty
Prototype:
PUBLIC  void Empty( )
Remarks: Makes this string object an empty string (0 length) and frees memory as appropriate.
Parameters:
None.

Return values:
None.

Example:
            string str("abc");
            str.Empty();
            ASSERT(str.GetLength( ) == 0);

Summary:
Sample data:
Header file: string.h
See also: IsEmpty


Find

string::Find
Prototype:
PUBLIC  int Find( LPCSTR lpszSub, int nStart )
Remarks: This overloaded member function searches this string for the match of a substring.
Parameters:
pstr = A pointer to a string to search for.
nStart = The index of the character in the string to begin the
search with.  If nStart equals 0, search starts from the
beginning.  The character at nStart is excluded from the search
if nStart is not equal to 0.

Return values:
Returns the zero-based index of the first character in this string
object that matches the requested substring.  It will return -1 if
the character is not found.

Example:
            string str4("Happy Birthday");
            ASSERT(str4.Find("day",4)==11);

Summary:
Sample data:
Header file: string.h
See also: ReverseFind FindOneOf
string::Find
Prototype:
PUBLIC  int Find( char ch )
Remarks: This overloaded member function searches this string for the first match of a single character.
Parameters:
ch = A single character to search for.

Return values:
Returns the zero-based index of the first character in this string
object that matches the character.  It will return -1 if the character
is not found.

Example:
            string str1("abcdef");
            ASSERT(str1.Find('c')==2);

Summary:
Sample data:
Header file: string.h
See also: ReverseFind FindOneOf
string::Find
Prototype:
PUBLIC  int Find( LPCSTR lpszSub )
Remarks: This overloaded member function searches this string for the first match of a substring.
Parameters:
lpszsub = A substring to search for.

Return values:
Returns the zero-based index of the first character in this string
object that matches the character.  It will return -1 if the character
is not found.

Example:
            string str2("abcdef");
            ASSERT(str2.Find("de") == 3);

Summary:
Sample data:
Header file: string.h
See also: ReverseFind FindOneOf
string::Find
Prototype:
PUBLIC  int Find( char ch, int nStart )
Remarks: This overloaded member function searches this string for the match of a character.
Parameters:
ch = A single character to search for.
nStart = The index of the character in the string to begin the
search with.  If nStart equals 0, search starts from the
beginning.  The character at nStart is excluded from the search
if nStart is not equal to 0.

Return values:
Returns the zero-based index of the first character in this string
object that matches the character.  It will return -1 if the character
is not found.

Example:
            string str3("Hello World");
            ASSERT(str3.Find('o',5)==7);

Summary:
Sample data:
Header file: string.h
See also: ReverseFind FindOneOf


FindOneOf

string::FindOneOf
Prototype:
PUBLIC  int FindOneOf( LPCSTR lpszCharSet )
Remarks: This member function searches this string for the first character that matches any character contained in lpszCharSet.
Parameters:
lpszCharSet = string containing characters for matching.

Return values:
The zero-based index of the first character in this string that is
also in lpszCharSet; -1 if there is no match.

Example:
            string str("abcdef");
            ASSERT(str.FindOneOf("xd")==3); // 'd' is first match

Summary:
Sample data:
Header file: string.h
See also: Find


Format

string::Format
Prototype:
PUBLIC  void Format( LPCSTR lpcszFormat, ... )
Remarks: This member function formats and stores a series of characters and values in the string. Each optional argument (if any) is converted and output according to the corresponding format specification in lpcszFormat. Please note that it is your responsibility to match the data type with the correct formatting specification.
Parameters:
lpcszFormat = A format-control string.

Return values:
none.

Example:
            char sz[10] = "abcdefg";
            int nn = 10;
            double dd = 3.1416;
            string str;
            str.Format("Results = %s, %d, %5.4f", sz, nn, dd);
            ASSERT(0 == str.Compare("Results = abcdefg, 10, 3.1416"));

            // the following usage will generate runtime error due to
            // incorrect data being used
            string str;
            str.Format("x1=%f, x2=%f", 5, 3.4); // 5 is not a double, will generate runtime error
            str.Format("x1=%f, x2=%f", 5.0, 3.4);// this will work correctly

Summary:
Sample data:
Header file: string.h
See also: printf


GetAt

string::GetAt
Prototype:
PUBLIC  char GetAt( int nIndex )
Remarks: This member function returns a single character specified by an index number.
Parameters:
nIndex = Zero-based index of the character in the string
object. The nIndex parameter must be greater than or equal
to 0 and less than the value returned by GetLength.

Return values:
A char containing the character at the specified position in the string.

Example:
            string str( "abcdef" );
            ASSERT( str.GetAt(2) == 'c' );

Summary:
Sample data:
Header file: string.h
See also: SetAt GetLength


GetBuffer

string::GetBuffer
Prototype:
PUBLIC  char* GetBuffer( int nMinBufLength )
Remarks: This method retrieves a pointer to the internal character buffer for the string. If you use the pointer returned by GetBuffer to change the string contents, you must call ReleaseBuffer before using any other string methods.
Parameters:
nMinBufLength = Specifies the minimum size of the character buffer in characters.
This value does not include space for a null terminator.

Return values:
This is an LPTSTR pointer to the character buffer of the null-terminated object.

Example:
            string str = "abcdefg";
            char *p = str.GetBuffer( 20 );
            out_str( p );		//output should be "abcdefg"
            str.ReleaseBuffer();

Summary:
Sample data:
Header file: string.h
See also: ReleaseBuffer


GetBufferSetLength

string::GetBufferSetLength
Prototype:
PUBLIC  char* GetBufferSetLength( int nNewLength )
Remarks: This method retrieves a pointer to the internal character buffer for the string, truncating or growing its length, if necessary, to exactly match the length specified in nNewLength.
Parameters:
nNewLength = Specifies the exact size of the string character buffer in characters.

Return values:
This is an LPTSTR pointer to the character buffer of the null-terminated object.

Example:
            string str;
            char* pstr = str.GetBufferSetLength(3);
             pstr[0] = 'I';
            pstr[1] = 'c';
            pstr[2] = 'e';
            out_str(str);		//output should be "Ice"

Summary:
Sample data:
Header file: string.h
See also:


GetBytes

string::GetBytes
Prototype:
PUBLIC  BOOL GetBytes(vector<byte>& vb)
Remarks: Copy the charactors of this string into a byte vector
Parameters:
vb = [out] vector of bytes to receive the charactors from this string

Return values:
Returns TRUE on success

Example:
            string str = "ABCD";
            vector<byte> vResult;
            str.GetBytes(vResult);
            ASSERT(vResult.GetSize() == 4);

Summary:
Sample data:
Header file: string.h
See also: GetBytes


GetLength

string::GetLength
Prototype:
PUBLIC  int GetLength( )
Remarks: This member function returns the number of bytes (or number of characters in this string object. The count does not include a null terminator.
Parameters:
None.

Return values:
An integer value equal to the length (number of bytes minus
the null character) of this string.

Example:
            string str1( "cow" );
            ASSERT( str1.GetLength() == 3 );

Summary:
Sample data:
Header file: string.h
See also:


GetNumTokens

string::GetNumTokens
Prototype:
PUBLIC  int GetNumTokens( char chDelimiter = 0 )
Remarks: This member function returns the number of tokens in this string where a token is separated by the delimiter specified by chDelimiter. Default is 0 (null constant) so chDelimiter does not have to be specified when any white space (space, tab, newline, etc.) is to be used as the delimiter.
Parameters:
chDelimiter = A character representing the delimiter.

Return values:
The number of tokens in this string.

Example:
            string str1("apples peaches pumpkins");
            string str2("apples,peaches,pumpkins");
            ASSERT(str1.GetNumTokens()==3);
            ASSERT(str2.GetNumTokens(',')==3);

Summary:
Sample data:
Header file: string.h
See also: GetToken GetTokens


GetToken

string::GetToken
Prototype:
PUBLIC  string GetToken( int nToken, char chDelimiter = 0 )
Remarks: This member function returns the nth token where a token is separated by the delimiter specified by chDelimiter. Default is 0 (null constant) so chDelimiter does not have to be specified when any white space (space, tab, newline, etc.) is to be used as the delimiter.
Parameters:
nToken = An integer representing the token to get.
chDelimiter = A character representing the delimiter.

Return values:
The extracted string token.

Example:
            string str1("apples peaches pumpkins");
            string str3("apples,peaches,pumpkins");
            string str2=str1.GetToken(1);
            string str4=str3.GetToken(1,',');
            ASSERT(str2.Compare("peaches")==0);
            ASSERT(str4.Compare("peaches")==0);

Summary:
Sample data:
Header file: string.h
See also: GetNumTokens GetTokens


GetTokens

string::GetTokens
Prototype:
PUBLIC  int GetTokens( StringArray& saTokens, char chDelimiter = 0 )
Remarks: Create a StringArray from this string
Parameters:
saTokens = string array which store the results found.
chDelimiter = A character representing the delimiter.

Return values:
Number of tokens (strings) found

Example:
            StringArray strTokens;
            strTokens.SetSize(3);
            string str = "1@2@3#4#5$6$";
            ASSERT( 3 == str.GetTokens( strTokens, '@') );
            ASSERT( 0 == strTokens[0].Compare("1") );
            ASSERT( 0 == strTokens[1].Compare("2") );
            ASSERT( 0 == strTokens[2].Compare("3#4#5$6$") );

Summary:
Sample data:
Header file: string.h
See also: GetNumTokens GetToken


Insert

string::Insert
Prototype:
PUBLIC  int Insert( int nIndex, char ch )
Remarks: This overloaded member function inserts a single character at the given index within the string. The nIndex parameter identifies the first character that will be moved to make room for the character. If nIndex is zero, the insertion will occur before the entire string. If nIndex is higher than the length of the string, the function will concatenate the string and the character.
Parameters:
nIndex = The index of the character before which the insertion
will take place.
ch = The character to be inserted.

Return values:
The length of the changed string.

Example:
            string str1("love summer");
            str1.Insert(0,'I');
            ASSERT(str1.Compare("Ilove summer")==0);

Summary:
Sample data:
Header file: string.h
See also: Delete
string::Insert
Prototype:
PUBLIC  int Insert( int nIndex, LPCTSTR pstr )
Remarks: This overloaded member function inserts a substring at the given index within the string. The nIndex parameter identifies the first character that will be moved to make room for the substring. If nIndex is zero, the insertion will occur before the entire string. If nIndex is higher than the length of the string, the function will concatenate the string and the substring.
Parameters:
nIndex = The index of the character before which the insertion
will take place.
pstr = A pointer to the substring to be inserted.

Return values:
The length of the changed string.

Example:
            string str1("I summer");
            str1.Insert(2,"love");
            ASSERT(str1.Compare("I lovesummer")==0);

Summary:
Sample data:
Header file: string.h
See also: Delete


IsEmpty

string::IsEmpty
Prototype:
PUBLIC  BOOL IsEmpty( )
Remarks: Tests a string object for the empty condition. Tests whether a string object contains any characters.
Parameters:
None.

Return values:
Nonzero if the string object has 0 length; otherwise 0.

Example:
            string str;
            ASSERT(str.IsEmpty());

Summary:
Sample data:
Header file: string.h
See also: GetLength


IsFile

string::IsFile
Prototype:
PUBLIC  BOOL IsFile( )
Remarks: This member function tests to see if the string is a valid full path file name
Parameters:
None.

Return values:
returns TRUE if the string is a filename that exist

Example:
            string strFile("c:\\Program Files\\Originlab\\origin70.exe");
            ASSERT(strFile.IsFile());

Summary:
Sample data:
Header file: string.h
See also:


IsPath

string::IsPath
Prototype:
PUBLIC  BOOL IsPath( )
Remarks: This member function tests a string object is a valid or invalid path.
Parameters:
None.

Return values:
returns TRUE if the string object is a "path" that exists.

Example:
            string strPath="c:\\Program Files";
            ASSERT(strPath.IsPath());

Summary:
Sample data:
Header file: string.h
See also:


Left

string::Left
Prototype:
PUBLIC  string Left( int nCount )
Remarks: Extracts the leftmost nCount characters from this string object and returns a copy of the extracted substring. If nCount exceeds the string length, then the entire string is extracted.
Parameters:
nCount = The number of characters to extract starting from the
left.

Return values:
A string object containing a copy of the specified range of
characters. Note that the returned string object may be
empty.

Example:
            string str1("abcdef");
            ASSERT ( 0==str1.Left(2).Compare("ab") );

Summary:
Sample data:
Header file: string.h
See also: Right


MakeLower

string::MakeLower
Prototype:
PUBLIC  void MakeLower( )
Remarks: Converts this string object to a lowercase string.
Parameters:
None.

Return values:
None.

Example:
            string str("ABCD");
            str.MakeLower();
            ASSERT(str.Compare("abcd")==0);

Summary:
Sample data:
Header file: string.h
See also: MakeUpper


MakeUpper

string::MakeUpper
Prototype:
PUBLIC  void MakeUpper( )
Remarks: Converts this string object to an uppercase string.
Parameters:
None.

Return values:
None.

Example:
            string str("abcd");
            str.MakeUpper();
            ASSERT(str.Compare("ABCD")==0);

Summary:
Sample data:
Header file: string.h
See also: MakeLower


MakeValidCName

string::MakeValidCName
Prototype:
PUBLIC  void MakeValidCName(char cPrefixIf1stCharNumber=0)
Remarks: Modify a string to be a valid C identifier name. A C Identifier name must begin with a letter and can contain only letters, numbers, and underscore characters.
Parameters:
cPrefixIf1stCharNumber = If not zero and the string begins with a number then this character will be
inserted before the first character.  If the first character of the string is not a digit or if
the specified prefix character is not a letter or underscore then this argument will have no effect.

Return values:
None

Example:
            string str = "23 * this & this";
            printf("Before: %s\n", str);
            str.MakeValidCName('a'); // prefix with 'a', delete all spaces, and delete '*' and '&'
            printf("After: %s\n", str);

Summary:
Sample data:
Header file: string.h
See also:


Match

string::Match
Prototype:
PUBLIC  BOOL Match( LPCSTR strPattern, BOOL bCaseSensitive = FALSE )
Remarks: String pattern matching, any number of wildchars are supported, which can be * or ?.
Parameters:
strPattern = the string will be matched.

Return values:
TRUE if the provided pattern matches the string.

Example:
            string str = "abcdefg";
            ASSERT(str.Match("ab*"));
            ASSERT(str.Match("a*c*f?"));
            ASSERT(str.Match("a*d*"));
            ASSERT(str.Match("?*e*f?"));

Summary:
Sample data:
Header file: string.h
See also:


Mid

string::Mid
Prototype:
PUBLIC  string Mid( int nFirst, int nCount )
Remarks: Extracts a substring of length nCount characters from this string object, starting at position nFirst (zero-based).
Parameters:
nFirst = The zero-based index of the first character in this
string object that is to be included in the extracted
substring.
nCount = The number of characters to extract from this
string object. If this parameter is not supplied, then the
remainder of the string is extracted.

Return values:
Returns a copy of the extracted substring.

Example:
            string str1("I love summer!");
            string str2=str1.Mid(2,4);
            ASSERT(str2.Compare("love")==0);

Summary:
Sample data:
Header file: string.h
See also: Left Right
string::Mid
Prototype:
PUBLIC  string Mid( int nFirst )
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: string.h
See also:


ReleaseBuffer

string::ReleaseBuffer
Prototype:
PUBLIC  void ReleaseBuffer( int nNewLength = -1 )
Remarks: Use ReleaseBuffer to end use of a buffer allocated by GetBuffer.
Parameters:
nNewLength = The new length of the string in characters, not counting a null terminator.
If the string is null-terminated, the -1 default value sets the string size to the
current length of the string.

Return values:
None.

Example:
            string str = "abcdefg";
            char *p = str.GetBuffer( 20 );
            str.ReleaseBuffer();

Summary:
Sample data:
Header file: string.h
See also: GetBuffer


Remove

string::Remove
Prototype:
PUBLIC  int Remove( char ch )
Remarks: This member function removes instances of ch from the string. Comparisons for the character are case-sensitive.
Parameters:
ch = The character to be removed from a string.

Return values:
The count of characters removed from the string.
Zero if the string isn't changed.

Example:
            string str("apple");
            str.Remove('p');
            ASSERT(str.Compare("ale")==0);

Summary:
Sample data:
Header file: string.h
See also: Replace


Replace

string::Replace
Prototype:
PUBLIC  int Replace( char chOld, char chNew )
Remarks: This overloaded member function replaces a character with another. (Comparison is case-sensitive in all cases.)
Parameters:
chOld = The character to be replaced by chNew.
chNew = The character replacing chOld.

Return values:
The number of replaced instances of the character.
Zero if the string isn't changed.

Example:
            string str("A+B+C+");
            ASSERT(str.Replace('+','-')==3);

Summary:
Sample data:
Header file: string.h
See also: Remove
string::Replace
Prototype:
PUBLIC  int Replace( LPCSTR lpszOld, LPCSTR lpszNew )
Remarks: This overloaded member function replaces instances of the substring lpszOld with instances of the string lpszNew.
Parameters:
lpszOld = A pointer to a string containing the characters to
be replaced by lpszNew.
lpszNew = A pointer to a string containing the characters
replacing lpszOld.

Return values:
The number of replaced instances of the character. Zero if
the string isn't changed.

Example:
            string str("Today is Friday");
            ASSERT(str.Replace("Friday","Monday")==1);
            ASSERT(str.Compare("Today is Monday")==0);

Summary:
Sample data:
Header file: string.h
See also: Remove
string::Replace
Prototype:
PUBLIC  int Replace( LPCSTR lpszOneOf, char chNew )
Remarks: This overloaded member function replaces instances of the all characters as specified by lpszOneOf with the character chNew. If the resulted string has repeated occurance of chNew, they are stripped so that only one is left
Parameters:
lpszOneOf = A pointer to a string containing the characters that all are to
be replaced by chNew.
chNew = The character replacing lpszOneOf.

Return values:
The number of replaced instances of the chNew. Zero if no replacement
took place.

Example:
            string str("123  \t456,  789;\n\r1212");
            str.Replace(" \t\n\r,;",',');
            ASSERT(str.Compare("123,456,789,1212")==0);

Summary:
Sample data:
Header file: string.h
See also:


ReverseFind

string::ReverseFind
Prototype:
PUBLIC  int ReverseFind( char ch )
Remarks: This member function searches this string object for the last match of a character.
Parameters:
ch = The character to search for.

Return values:
Returns the index of the last character in this string
object that matches the requested character; -1 if the
character is not found.

Example:
            string str1("abcabc");
            ASSERT(str1.ReverseFind('b') == 4 );

Summary:
Sample data:
Header file: string.h
See also: Find FindOneOf


Right

string::Right
Prototype:
PUBLIC  string Right( int nCount )
Remarks: Extracts the rightmost nCount characters from this string object and returns a copy of the extracted substring. If nCount exceeds the string length, then the entire string is extracted.
Parameters:
nCount = The number of characters to extract starting from the
right.

Return values:
A string object containing a copy of the specified range of
characters. Note that the returned string object may be
empty.

Example:
            string str1("abcdef");
            ASSERT ( 0 == str1.Right(2).Compare("ef") );

Summary:
Sample data:
Header file: string.h
See also: Left


SetAt

string::SetAt
Prototype:
PUBLIC  void SetAt( int nIndex, char ch )
Remarks: This member function overwrites a single character specified by an index number. SetAt will not enlarge the string if the index exceeds the bounds of the existing string.
Parameters:
nIndex = Zero-based index of the character in the string object.
The nIndex parameter must be greater than or equal to 0 and
less than the value returned by GetLength.
ch = The character to insert.

Return values:
None.

Example:
            string str( "abcdef" );
            str.SetAt(2,'z');
            ASSERT(str.Compare("abzdef")==0);

Summary:
Sample data:
Header file: string.h
See also: GetAt


SetBytes

string::SetBytes
Prototype:
PUBLIC  BOOL SetBytes(vector<byte>& vb)
Remarks: Set the content of this string from a vector of bytes
Parameters:
vb = [in] vector of bytes to be put into this string

Return values:
Returns TRUE on success

Example:
            vector<byte> vTemp = {'A','B','C','D'};
            string str ="something to make it longer";
            str.SetBytes(vTemp);
            ASSERT(str.Compatre("ABCD") == 0);

Summary:
Sample data:
Header file: string.h
See also: SetBytes


SpanExcluding

string::SpanExcluding
Prototype:
PUBLIC  string SpanExcluding( LPCSTR lpszCharSet )
Remarks: This member function searches the string for the first occurrence of any character in the specified set lpszCharSet. SpanExcluding extracts and returns all characters preceding the first occurrence of a character from lpszCharSet (in other words, the character from lpszCharSet and all characters following it in the string, are not returned). If no character from lpszCharSet is found in the string, then SpanExcluding returns the entire string.
Parameters:
lpszCharSet = A string interpreted as a set of characters.

Return values:
A substring that contains characters in the string that are
not in lpszCharSet, starting with the first character in the
string and up to but excluding the first character in the
string that is found lpszCharSet). It returns the entire
string if no character in lpszCharSet is found in the string.

Example:
            string str1("Hello World! Goodbye!");
            string str2("Hello World Goodbye");
            string str3=str1.SpanExcluding(".!?");
            string str4=str2.SpanExcluding(".!?");
            ASSERT(str3.Compare("Hello World")==0);
            ASSERT(str4.Compare("Hello World Goodbye")==0);

Summary:
Sample data:
Header file: string.h
See also: SpanIncluding


SpanIncluding

string::SpanIncluding
Prototype:
PUBLIC  string SpanIncluding( LPCSTR lpszCharSet )
Remarks: This member function extracts characters from the string, starting with the first character, that are in the set of characters identified by lpszCharSet. If the first character of the string is not in the character set, then SpanIncluding returns an empty string. Otherwise, it returns a sequence of consecutive characters which are in the set.
Parameters:
lpszCharSet = A string interpreted as a set of characters.

Return values:
A substring that contains characters in the string that are
in lpszCharSet, beginning with the first character in the
string and ending when a character is found in the string
that is not in lpszCharSet. SpanIncluding returns an empty
substring if the first character in the string is not in the
specified set.

Example:
            string str1("cabinet");
            string str2=str1.SpanIncluding("abc");
            ASSERT(str2.Compare("cab")==0);
            string str3=str1.SpanIncluding("xyz");
            ASSERT(str3.IsEmpty());

Summary:
Sample data:
Header file: string.h
See also: SpanExcluding


string

string::string
Prototype:
PUBLIC  string( LPCTSTR lpch, int nLength )
Remarks: Constructs a string object from an array of characters of length nlength, not null-terminated.
Parameters:
lpch = A pointer to an array of characters.
nLength = length of characters.

Return values:
None.

Example:
            char * str="Origin C";
            int nLength=8;
            string str4(str,nLength);
            ASSERT(str4.Compare("Origin C")==0);

Summary:
Sample data:
Header file: string.h
See also:
string::string
Prototype:
PUBLIC  string( _VARIANT var )
Remarks: Constructs a string object from any _VARIANT type variable which holds a string This function is available only for OriginPro versions, or with a special COM enabled license
Parameters:
var = a _VARIANT object

Return values:
None.

Example:
            void test()
            {
               _VARIANT obj;
               string s = "Hello";
               obj = s;
               string str = obj;
            }

Summary:
Sample data:
Header file: string.h
See also:
string::string
Prototype:
PUBLIC  string( )
Remarks: Default constructor, creates a new empty string object
Parameters:
None.

Return values:
None.

Example:
            string str1;  //empty string
            ASSERT(str1.IsEmpty());

Summary:
Sample data:
Header file: string.h
See also:
string::string
Prototype:
PUBLIC  string( LPCSTR lpcszSrc )
Remarks: Constructs a string object from a null-terminated string.
Parameters:
lpcszSrc = A null-terminated string to be copied into this string object.

Return values:
None.

Example:
            string str2("cow");  //create from a string literal
            ASSERT(str2.Compare("cow")==0);

Summary:
Sample data:
Header file: string.h
See also:
string::string
Prototype:
PUBLIC  string( char ch, int nRepeat = 1 )
Remarks: Constructs a string object from a character that is repeated nRepeat times.
Parameters:
ch = A single character to be repeated nRepeat times.
nRepeat = The repeat count for ch.

Return values:
None.

Example:
            string str3('a',6);
            ASSERT(str3.Compare("aaaaaa")==0);

Summary:
Sample data:
Header file: string.h
See also:


TrimLeft

string::TrimLeft
Prototype:
PUBLIC  void TrimLeft( )
Remarks: This member function with no parameters trims leading whitespace characters from the string. It removes newline, space, and tab characters.
Parameters:
None.

Return values:
None.

Example:
            string str="   Hello World";
            str.TrimLeft();
            ASSERT(str.Compare("Hello World")==0);

Summary:
Sample data:
Header file: string.h
See also: Mid Left Right MakeUpper MakeLower Format
string::TrimLeft
Prototype:
PUBLIC  void TrimLeft( char chTarget )
Remarks: Remove a particular character from this string.
Parameters:
chTarget = character to be trimmed.

Return values:
None.

Example:
            string str="Hello World";
            str.TrimLeft('H');
            ASSERT(str.Compare("ello World")==0);

Summary:
Sample data:
Header file: string.h
See also: Mid Left Right MakeUpper MakeLower Format
string::TrimLeft
Prototype:
PUBLIC  void TrimLeft( LPCSTR lpszTargets )
Remarks: Remove a group of characters from this string.
Parameters:
lpszTargets = A pointer to a string containing the target
characters to be trimmed.

Return values:
None.

Example:
            string str="****Hello World";
            str.TrimLeft("****");
            ASSERT(str.Compare("Hello World")==0);

Summary:
Sample data:
Header file: string.h
See also: Mid Left Right MakeUpper MakeLower Format


TrimRight

string::TrimRight
Prototype:
PUBLIC  void TrimRight( )
Remarks: This member function with no parameters trims trailing whitespace characters from the string. It removes trailing newline, space, and tab characters from the string.
Parameters:
None.

Return values:
None.

Example:
            string str="Hello World    ";
            str.TrimRight();
            ASSERT(str.Compare("Hello World")==0);

Summary:
Sample data:
Header file: string.h
See also: Mid Left Right MakeUpper MakeLower Format
string::TrimRight
Prototype:
PUBLIC  void TrimRight( char chTarget )
Remarks: Removes a particular character from the end of a string.
Parameters:
chTarget = character to be trimmed.

Return values:
None.

Example:
            string str="Hello World";
            str.TrimRight('d');
            ASSERT(str.Compare("Hello Worl")==0);

Summary:
Sample data:
Header file: string.h
See also: Mid Left Right MakeUpper MakeLower Format
string::TrimRight
Prototype:
PUBLIC  void TrimRight( LPCSTR lpszTargets )
Remarks: Removes a particular group of character from the end of a string.
Parameters:
lpszTargets = A pointer to a string containing the target
characters to be trimmed.

Return values:
None.

Example:
            string str="Hello World****";
            str.TrimRight("****");
            ASSERT(str.Compare("Hello World")==0);

Summary:
Sample data:
Header file: string.h
See also: Mid Left Right MakeUpper MakeLower Format


Write

string::Write
Prototype:
PUBLIC  void Write( int iDestination )
Remarks: This member function outputs the string.
Parameters:
iDestination = one of enum {WRITE_SCRIPT_WINDOW, WRITE_STATUS_BAR, WRITE_OUTPUT_LOG, WRITE_MESSAGE_BOX, WRITE_COMPILER_OUTPUT};

Return values:
None.

Example:
            string str="Hello World";
            str.Write(WRITE_OUTPUT_LOG);  //Hello World typed out to the Results Log

Summary: 0 = ScriptWindow
Sample data:
Header file: string.h
See also: WriteLine


WriteLine

string::WriteLine
Prototype:
PUBLIC  void WriteLine( int iDestination )
Remarks: This member function outputs the string adding return and newline characters automatically.
Parameters:
iDestination = one of enum {WRITE_SCRIPT_WINDOW, WRITE_STATUS_BAR, WRITE_OUTPUT_LOG, WRITE_MESSAGE_BOX, WRITE_COMPILER_OUTPUT};

Return values:
None.

Example:
            string str="Hello World";
            str.WriteLine(2);  //Hello World typed out to the Results Log cursor is at next line

Summary: will add \r\n automatically
Sample data:
Header file: string.h
See also: Write


Tree

Class: Tree

Description:

Hierarchy:

PropertyNode
 TreeNode
 Tree

Sample:


Load

Tree::Load
Prototype:
PUBLIC  BOOL Load(LPCSTR File, int nType = 0)
Remarks: Gets a tree from an XML file.
Parameters:
File = file name
nType = 0

Return values:
Returns: TRUE if the tree can be created; FALSE otherwise

Example:
            void test()
            {
                Tree myTree;
                myTree.Load("xyz.xml", 0);
            }

Summary:
Sample data:
Header file: Tree.h
See also:


Save

Tree::Save
Prototype:
PUBLIC  BOOL Save(LPCSTR lpcszFile)
Remarks: Saves a tree to an XML file.
Parameters:
File = file name
nType = 0

Return values:
Returns: TRUE if the tree can be created; FALSE otherwise

Example:
        void test()
            {
                Tree myTree(0);
                TreeNode tn1, tn2, tn3;
                tn1 = myTree.AddNode("node1", 1);
                tn2 = tn1.AddTextNode("abc", "node2", 2);
                tn3 = tn2.AddTextNode("efg", "node3", 3);

                myTree.Save("c:\\xyz.xml");
            }

Summary:
Sample data:
Header file: Tree.h
See also:


Tree

Tree::Tree
Prototype:
PUBLIC  Tree(LPCSTR File, int nType = 0)
Remarks: Constructor which initializes a tree from an XML file.
Parameters:
File = file name
nType = 0

Return values:

Example:
Example:
            void test()
            {
                Tree myTree("xyz.xml", 0);
            }

Summary:
Sample data:
Header file: Tree.h
See also:
Tree::Tree
Prototype:
PUBLIC  Tree(int nType = 0)
Remarks: Constructor.
Parameters:
nType = 0

Return values:

Example:
Example:
            void test()
            {
                Tree myTree(0);
            }

Summary:
Sample data:
Header file: Tree.h
See also:


TreeNode

Class: TreeNode

Description:

Hierarchy:

PropertyNode
 TreeNode

Sample:


AddNode

TreeNode::AddNode
Prototype:
PUBLIC  BOOL AddNode(TreeNode &tn, BOOL bDeep = TRUE)
Remarks: Adds a reference to an existing node (in the same tree or another tree).
Parameters:
tn = the new node to be added to the tree
bDeep = TRUE or FALSE;

Return values:
TRUE if the node is successfully added; FALSE otherwise

Example:
            void test()
            {	Tree myTree1;
                TreeNode tn1;
                tn1 = myTree1.AddTextNode("abc", "node1", 1);
                out_tree(myTree1);

                Tree myTree2;
                TreeNode tn2(tn1); // adds a node from myTree1
                bool flag = myTree2.AddNode(tn2, FALSE);
                out_tree(myTree2);
            }

Summary:
Sample data:
Header file: Tree.h
See also:
TreeNode::AddNode
Prototype:
PUBLIC  TreeNode AddNode(LPCSTR Name = NULL, int nChildID = -1)
Remarks: Creates a new node with the specified name & id and returns that node.
Parameters:
name  = the name of the new node to be added to the tree
nChildID = the id of the new node to be added to the tree

Return values:
A new node bearing the name and the id.

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1, tn2, tn3;
                tn1 = myTree.AddNode("node1", 1);
                tn2 = myTree.AddTextNode("abc", "node2", 2);
                tn3 = tn2.AddTextNode("efg", "node3", 3);
            }

Summary: NodeID will not be created if < 0
Sample data:
Header file: Tree.h
See also:


AddNumericNode

TreeNode::AddNumericNode
Prototype:
PUBLIC  TreeNode AddNumericNode(double dVal, LPCSTR Name = NULL, int nChildID = -1)
Remarks: Creates a new node with the specified name,id and the double value and returns that node.
Parameters:
dVal  = double contents of the node
name  = the name of the new node to be added to the tree
nChildID = the id of the new node to be added to the tree; NodeID  will not be created if < 0

Return values:
A new node bearing the name and the id.

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1;
                tn1 = myTree.AddNumericNode(5.432, "node1", 1);
                out_tree(myTree);
            }

Summary:
Sample data:
Header file: Tree.h
See also:
TreeNode::AddNumericNode
Prototype:
PUBLIC  TreeNode AddNumericNode(int nVal, LPCSTR Name = NULL, int nChildID = -1)
Remarks: Creates a new node with the specified name,id and the integer value and returns that node.
Parameters:
nVal  = integer contents of the node
name  = the name of the new node to be added to the tree
nChildID = the id of the new node to be added to the tree; node will not be created if < 0

Return values:
A new node bearing the name and the id.

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1;
                tn1 = myTree.AddNode(5, "node1", 1);
                out_tree(myTree);
            }

Summary:
Sample data:
Header file: Tree.h
See also:


AddTextNode

TreeNode::AddTextNode
Prototype:
PUBLIC  TreeNode AddTextNode(LPCSTR strVal, LPCSTR Name = NULL, int nChildID = -1)
Remarks: Creates a new node with the specified name,id and the string value and returns that node.
Parameters:
strVal  = string contents of the node
name  = the name of the new node to be added to the tree
nChildID = the id of the new node to be added to the tree; node will not be created if < 0

Return values:
A new node bearing the name and the id.

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1;
                tn1 = myTree.AddTextNode("abcd", "node1", 1);
                out_tree(myTree);
            }

Summary:
Sample data:
Header file: Tree.h
See also:


Clone

TreeNode::Clone
Prototype:
PUBLIC  TreeNode Clone(BOOL bDeep = TRUE)
Remarks: Creates a clone of a node i.e., creates an exact copy of a node and its contents. If bDeep is true, copies the whole branch.
Parameters:
bDeep = TRUE or FALSE

Return values:
The cloned node

Example:
            void test()
            {
                Tree myTree1, myTree2;
                TreeNode tn1, tn2, tn3;
                tn2 = myTree2.AddTextNode("abc", "node2", 2);
                tn3 = tn2.AddTextNode("efg", "node3", 3);//tn2 added tn3 as its child

                tn1 = tn2.Clone(TRUE);//TRUE, copies the tn2 as well as its sub-branch
                bool flag = myTree2.AddNode(tn1);
                out_tree(myTree1);
                out_tree(myTree2);
            }

Summary: Clones a Node, if bDeep is true, copies the whole branch
Sample data:
Header file: Tree.h
See also:


GetAttribute

TreeNode::GetAttribute
Prototype:
PUBLIC  BOOL GetAttribute(LPCSTR lpcszAttrName, int &nVal)
Remarks: Gets the integer attribute of a node with the specified name.
Parameters:
lpcszAttrName  = name of the node
nVal  = contains the integer attribute of the node after the function call is finished

Return values:
True if the node is found; FALSE otherwise

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1;
                tn1 = myTree.AddTextNode("abc", "node1", 2);
                int nVal;
                bool flag1 = tn1.SetAttribute("node2", 5); //creates a new attribute named node2 and gives it an
                                                           //integer value 5
                bool flag2 = tn1.GetAttribute("node2", nVal);
                printf("the integer value of the attribute node2 is %d", nVal);
            }

Summary:
Sample data:
Header file: Tree.h
See also:
TreeNode::GetAttribute
Prototype:
PUBLIC  BOOL GetAttribute(LPCSTR lpcszAttrName, double &dVal)
Remarks: Gets the double attribute of a node with the specified name.
Parameters:
lpcszAttrName  = name of the node
nVal  = After the method call, nVal contains the double attribute of the node.

Return values:
True if the node is found; FALSE otherwise

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1;
                tn1 = myTree.AddTextNode("abc", "node1", 2);
                double dVal;
                bool flag1 = tn1.SetAttribute("node2", 5.345);//creating a new attribute named node2 and giving it a
                                                           //double value 5.345
                bool flag2 = tn1.GetAttribute("node2", dVal);
                printf("the double value of the attribute node2 is %d", dVal);
            }

Summary:
Sample data:
Header file: Tree.h
See also:
TreeNode::GetAttribute
Prototype:
PUBLIC  BOOL GetAttribute(LPCSTR lpcszAttrName, string &strVal)
Remarks: Gets the string attribute of a node with the specified name.
Parameters:
lpcszAttrName  = name of the node
strVal  = After the method call, strVal contains the string attribute of the node.

Return values:
True if the node is found; FALSE otherwise

Example:

            #include <Tree.h>
            void test()
            {
                Tree myTree;
                TreeNode tn1;
                tn1 = myTree.AddTextNode("abc", "node1", 2);
                string strVal;
                bool flag1 = tn1.SetAttribute("node2", "xyz");//creating a new attribute named node2 and giving it a
                                                                 //string value "xyz"
                bool flag2 = tn1.GetAttribute("node2", strVal);
                printf("the string value of the attribute node2 is %d", strVal);
            }

Summary:
Sample data:
Header file: Tree.h
See also:


GetNode

TreeNode::GetNode
Prototype:
PUBLIC  TreeNode GetNode(LPCSTR Name)
Remarks: Gets a node from a tree when the name of the node is given.
Parameters:
Name = name of the node

Return values:
The node whose name matches the given name.

Example:
            #include <Tree.h>
            void test()
            {	Tree myTree;
                TreeNode tn1, tn2, tn3;
                tn2 = myTree.AddTextNode("abc", "node2", 2);
                tn3 = tn2.AddTextNode("efg", "node3", 3);//tn2 is adding tn3 as its child
                tn1 = tn2.GetNode("node3");//now tn1 has tn3 as its child
            }

Summary: Find child by name
Sample data:
Header file: Tree.h
See also:


GetNodeCount

TreeNode::GetNodeCount
Prototype:
PUBLIC  int GetNodeCount()
Remarks: Gives the number of nodes in the tree.
Parameters:

Return values:
Returns:
number of nodes in the tree

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1, tn2, tn3;
                tn1 = myTree.AddNumericNode(123, "node1", 1);
                tn2 = myTree.AddTextNode("abc", "node2", 2);
                tn3 = tn2.AddTextNode("abc", "node3", 2);
                printf("number of nodes in myTree = %d", myTree.GetNodeCount());
            }

Summary:
Sample data:
Header file: Tree.h
See also:


IsValid

TreeNode::IsValid
Prototype:
PUBLIC  BOOL IsValid()
Remarks: Checks if a given node is a valid node or not
Parameters:

Return values:
TRUE if the node is valid; FALSE otherwise.

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1;
                tn1 = myTree.AddTextNode("abc", "node1", 2);
                bool flag2 = tn1.IsValid();
            }

Summary:
Sample data:
Header file: Tree.h
See also:


Parent

TreeNode::Parent
Prototype:
PUBLIC  TreeNode Parent()
Remarks: Gets the parent of a node in a tree.
Parameters:

Return values:
Parent node of the child node which calls this method.

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1, tn2, tn3;
                tn2 = myTree.AddTextNode("abc", "node2", 2);
                tn3 = tn2.AddTextNode("efg", "node3", 3);//tn2 is adding tn3 as its child
                tn1 = tn3.Parent();//now tn1 has the parent of tn3
            }

Summary: Find parent -- Null if parent is not an element node
Sample data:
Header file: Tree.h
See also:


Remove

TreeNode::Remove
Prototype:
PUBLIC  BOOL Remove()
Remarks: Removes the node that calls this method.
Parameters:

Return values:
TRUE if the node was removed successfully; FALSE otherwise.

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1;
                tn1 = myTree.AddTextNode("abc", "node1", 2);

                bool flag1 = tn1.Remove();
                printf("the number of nodes in myTree = %d", myTree.GetNodeCount());
            }

Summary:
Sample data:
Header file: Tree.h
See also:


RemoveAttribute

TreeNode::RemoveAttribute
Prototype:
PUBLIC  BOOL RemoveAttribute(LPCSTR lpcszAttrName)
Remarks: Removes the attribute of a node.
Parameters:
lpcszAttrName = name of attribute

Return values:
TRUE if attribute existed and was deleted successfully, FALSE if attribute does not exist.

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1;
                tn1 = myTree.AddTextNode("abc", "node1", 2);
                string strVal;
                bool flag1 = tn1.SetAttribute("node2", "xyz");//creating a new attribute named node2 and giving it a
                                                                 //string value "xyz"
                bool flag2 = tn1.RemoveAttribute("node2");
                bool flag3 = tn1.GetAttribute("node2", strVal);
            }

Summary:
Sample data:
Header file: Tree.h
See also:


RemoveChild

TreeNode::RemoveChild
Prototype:
PUBLIC  BOOL RemoveChild(int nChildID)
Remarks: Removes the node with the specified id.
Parameters:
nChildID = id of the node to be removed

Return values:
TRUE if the node existed and was removed successfully; FALSE otherwise.

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1;

                tn1 = myTree.AddNumericNode(5, "node1", 1);
                printf("number of nodes = %d", myTree.GetNodeCount());

                bool flag = myTree.RemoveChild(1);
                printf("number of nodes = %d", myTree.GetNodeCount());
            }

Summary:
Sample data:
Header file: Tree.h
See also:
TreeNode::RemoveChild
Prototype:
PUBLIC  BOOL RemoveChild(LPCSTR Name)
Remarks: Removes the node with the specified name.
Parameters:
name = name of the node to be removed

Return values:
TRUE if the node existed and was removed successfully; FALSE otherwise.

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1;

                tn1 = myTree.AddNumericNode(5, "node1", 1);
                printf("number of nodes = %d", myTree.GetNodeCount());

                bool flag = myTree.RemoveChild("node1");
                printf("number of nodes = %d", myTree.GetNodeCount());
            }

Summary:
Sample data:
Header file: Tree.h
See also:
TreeNode::RemoveChild
Prototype:
PUBLIC  BOOL RemoveChild(TreeNode &tn)
Remarks: Removes the node specified by the object.
Parameters:
tn = the node object that has to be removed

Return values:
TRUE if the node existed and was removed successfully; FALSE otherwise.

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1;

                tn1 = myTree.AddNumericNode(5, "node1", 1);
                printf("number of nodes = %d", myTree.GetNodeCount());

                bool flag = myTree.RemoveChild(tn1);
                printf("number of nodes = %d", myTree.GetNodeCount());
            }

Summary:
Sample data:
Header file: Tree.h
See also:


RemoveChildrenWithPrefix

TreeNode::RemoveChildrenWithPrefix
Prototype:
PUBLIC  int RemoveChildrenWithPrefix(LPCSTR lpcszPrefix)
Remarks: Removes the node with the specified prefix.
Parameters:
lpcszPrefix = the prefix of name of the node(s).

Return values:
1 if the node existed and was removed successfully; 0 otherwise.

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1, tn2;

                tn1 = myTree.AddNumericNode(5, "node1", 1);
                tn2 = myTree.AddNumericNode(5, "node2", 1);
                printf("number of nodes = %d \n", myTree.GetNodeCount());

                int flag = myTree.RemoveChildrenWithPrefix("no");
                printf("number of nodes = %d \n", myTree.GetNodeCount());//should print 0
            }

Summary:
Sample data:
Header file: Tree.h
See also:


Replace

TreeNode::Replace
Prototype:
PUBLIC  BOOL Replace(TreeNode &tn, BOOL bDeep = TRUE)
Remarks: Replaces a node in the tree.
Parameters:
tn = the new node to be added to the tree
bDeep = TRUE or FALSE;

Return values:
TRUE if the node is successfully replaced; FALSE otherwise

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1, tn2, tn3;
                tn1 = myTree.AddNumericNode(123, "node1", 1);
                tn2 = myTree.AddTextNode("abc", "node2", 2);
                tn3 = tn2.AddTextNode("abc", "node3", 2);
                out_tree(myTree);

                bool flag1 = tn3.Replace(tn1, TRUE);
                if(flag1) printf("node3 successfully replaced \n");
                out_tree(myTree);

            }

Summary:
Sample data:
Header file: Tree.h
See also:


Reset

TreeNode::Reset
Prototype:
PUBLIC  void Reset()
Remarks: Removes all the attributes and the children of a node or a tree.
Parameters:

Return values:

Example:
            void test()
            {
                Tree myTree;
                TreeNode tn1;
                tn1 = myTree.AddTextNode("abc", "node1", 1);
                out_tree(myTree);
                myTree.Reset();
                out_tree(myTree);
            }

Summary:
Sample data:
Header file: Tree.h
See also:


SetAttribute

TreeNode::SetAttribute
Prototype:
PUBLIC  BOOL SetAttribute(LPCSTR lpcszAttrName, int nVal)
Remarks: Sets the integer value of a node.
Parameters:
lpcszAttrName  = name of the node
dVal  = contains the integer value to be set into the node.

Return values:
True if the node is found; FALSE otherwise

Example:

        #include <Tree.h>
        void test()
        {
            Tree myTree;
            TreeNode tn1;
            tn1 = myTree.AddTextNode("abc", "node1", 2);
            int nVal;
            bool flag1 = tn1.SetAttribute("node2", 5); //creating a new attribute named node2 and giving it an
                                                       //integer value 5
            bool flag2 = tn1.GetAttribute("node2", nVal);
            printf("the integer value of the attribute node2 is %d", nVal);
        }

Summary:
Sample data:
Header file: Tree.h
See also:
TreeNode::SetAttribute
Prototype:
PUBLIC  BOOL SetAttribute(LPCSTR lpcszAttrName, double dVal)
Remarks: Sets the double value of a node.
Parameters:
lpcszAttrName  = name of the node
dVal  = contains the double value to be set into the node.

Return values:
True if the node is found; FALSE otherwise

Example:

            #include <Tree.h>
            void test()
            {
                Tree myTree;
                TreeNode tn1;
                tn1 = myTree.AddTextNode("abc", "node2", 2);
                double dVal;
                bool flag1 = tn1.SetAttribute("node2", 5.345);//creating a new attribute named node2 and giving it a
                                                           //double value 5.345
                bool flag2 = tn1.GetAttribute("node2", dVal);
                printf("the double value of the attribute node2 is %d", dVal);
            }

Summary:
Sample data:
Header file: Tree.h
See also:
TreeNode::SetAttribute
Prototype:
PUBLIC  BOOL SetAttribute(LPCSTR lpcszAttrName, LPCSTR strVal)
Remarks: Sets the string attribute of the node.
Parameters:
lpcszAttrName  = name of the node
strVal  = contains the string value to be set into the node.

Return values:
True if the node is found; FALSE otherwise

Example:

            #include <Tree.h>
            void test()
            {
                Tree myTree;
                TreeNode tn1;
                tn1 = myTree.AddTextNode("abc", "node1", 2);
                string strVal;
                bool flag1 = tn1.SetAttribute("node2", "xyz");//creating a new attribute named node2 and giving it a
                                                                 //string value "xyz"
                bool flag2 = tn1.GetAttribute("node2", strVal);
                printf("the string value of the attribute node2 is %d", strVal);
            }

Summary:
Sample data:
Header file: Tree.h
See also:


TreeNode

TreeNode::TreeNode
Prototype:
PUBLIC  TreeNode()
Remarks: Default contructor.
Parameters:

Return values:

Example:
            void test()
            {	Tree myTree;
                TreeNode tn1;
                tn1 = myTree.AddTextNode("abc", "node2", 2);
                out_tree(myTree);
            }

Summary: Default contructor
Sample data:
Header file: Tree.h
See also:
TreeNode::TreeNode
Prototype:
PUBLIC  TreeNode(TreeNode &tn)
Remarks: Contructor.
Parameters:

Return values:

Example:
            void test()
            {	Tree myTree1;
                TreeNode tn1;
                tn1 = myTree1.AddTextNode("abc", "node1", 1);

                Tree myTree2;
                TreeNode tn2(tn1);
                bool flag = myTree2.AddNode(tn2, FALSE);
                out_tree(myTree1);
                out_tree(myTree2);
            }

Summary: Contructor
Sample data:
Header file: Tree.h
See also:


TreeNodeCollection

Class: TreeNodeCollection

Description:

Hierarchy:

Error Occurred While Processing Request

Error Occurred While Processing Request

Error Diagnostic Information

OLEDB Error Code = 245

Syntax error converting the varchar value 'public Collection ' to a column of data type int.

The error occurred while processing an element with a general identifier of (CFQUERY), occupying document position (24:1) to (24:57).

Date/Time: 10/07/03 14:33:36
Browser: Teleport Pro/1.29.1590
Remote Address: 10.10.10.55
HTTP Referer: http://netmeet1/tech/documentation/start_doc_gen.cfm
Query String: query=c%3Bcname%3D1422


TreeNodeCollection

TreeNodeCollection::TreeNodeCollection
Prototype:
PUBLIC  TreeNodeCollection(TreeNode node, LPCSTR lpcsz)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Tree.h
See also:


vector

Class: vector

Description: An Origin C vector is a dynamically allocated and sized array that is not tied to an internal Origin data set allowing a greater degree of flexibility. vector is a template class with a default type of double but a vector of any basic data type (including char, byte, short, word, int, uint, string) can be constructed using the syntax vector<type>. The vector class is derived from the vectorbase class from which it inherits methods and properties.

Hierarchy:

vectorbase
 vector

Sample:

        int imax = 10;
        vector<double> vX(imax);      // vector of doubles having imax elements
        vector vY(imax);              // vector of doubles by default
        vector<int> vI;               // vector of ints

        for(int ii = 0; ii < vX.GetSize(); ii++)
            vX[ii] = rnd();

        vY = 10 * vX;                 // vector arithmetic is supported
        vI = vY;                      // Cast double vector into int vector

        ASSERT(vI.GetSize() == imax); // Check that vectors have same size
        for(ii = 0; ii < vI.GetSize(); ii++) // Output cast elements of vectors
            printf("vI[%d]=%d after cast from %f\n",ii,vI[ii],vY[ii]);


Add

vector::Add
Prototype:
PUBLIC  int Add(_TemplType element)
Remarks: Adds One element at the end of the vector.
Parameters:
element = The element to be added to this vector.

Return values:
The index of the added element.

Example:
        void test()
        {
            vector<string> vsExt = {"OPJ", "TXT"};
            vsExt.Add("SPC");

            for(int ii = 0; ii < vsExt.GetSize(); ii++)
            {
                printf("Extesion(%d) : %s\n", ii, vsExt[ii]);
            }
        }

Summary:
Sample data:
Header file: vector.h
See also:


Find

vector::Find
Prototype:
PUBLIC  int Find(_TemplType element, int nStart = 0, bool bCaseSensitive = false)
Remarks: Find a specified string in an string vector.
Parameters:
lpcsz = the specified string
nStart = start index, defaults to 0.
bCaseSensitive =

Return values:
Return value will be -1 if lpcsz is not found else zero based index of element position

Example:
        void test()
        {
            vector<string> vsExt = {"OPJ", "TXT"};
            ASSERT( -1 == vsExt.Find("SPC") );
        }

Summary:
Sample data:
Header file: vector.h
See also:


InsertAt

vector::InsertAt
Prototype:
PUBLIC  BOOL InsertAt(int nIndex, _TemplType element, int nCount = 1)
Remarks: Inserts one element, or multiple copies of an element at a specified index in an vector. In the process, by incrementing the index, it shifts up the existing element at this index, and it shifts up all the elements above it.
Parameters:
nIndex = A specified index in vector.
element = The element to be added to this vector.
nCount = The number of times this element should be inserted (defaults to 1).

Return values:
Always returns TRUE

Example:
        void test()
        {
            vector<string> vsExt = {"OPJ", "TXT"};
            vsExt.InsertAt(0, "SPC");

            for(int ii = 0; ii < vsExt.GetSize(); ii++)
            {
                printf("Extesion(%d) : %s\n", ii, vsExt[ii]);
            }
        }

Summary:
Sample data:
Header file: vector.h
See also:


RemoveAt

vector::RemoveAt
Prototype:
PUBLIC  BOOL RemoveAt( int nIndex, int nCount = 1 )
Remarks: Removes one or more elements starting at a specified index in an vector. In the process, it shifts down all the elements above the removed element(s). It decrements the upper bound of the vector.
Parameters:
nIndex = A specified index in vector.
nCount = The number of elements to remove (defaults to 1).

Return values:
Always returns TRUE

Example:
        void test()
        {
            vector<string> vsExt = {"OPJ", "TXT", "SPC"};
            vsExt.RemoveAt(0, 2);

            for(int ii = 0; ii < vsExt.GetSize(); ii++)
            {
                printf("Extesion(%d) : %s\n", ii, vsExt[ii]);
            }
        }

Summary:
Sample data:
Header file: vector.h
See also:


SetAtGrow

vector::SetAtGrow
Prototype:
PUBLIC  BOOL SetAtGrow(int nIndex, _TemplType element)
Remarks: Sets the vector element at the specified index.
Parameters:
nIndex = A specified index in vector.
element = The element to be added to this vector.

Return values:
Always returns TRUE

Example:
        void test()
        {
            vector<string> vsExt = {"OPJ", "TXT"};
            vsExt.SetAtGrow(0, "SPC");

            for(int ii = 0; ii < vsExt.GetSize(); ii++)
            {
                printf("Extesion(%d) : %s\n", ii, vsExt[ii]);
            }
        }

Summary:
Sample data:
Header file: vector.h
See also:


vector

vector::vector
Prototype:
PUBLIC  vector(vector &vR, vector &vI)
Remarks: Constructor to create a complex vector from two vectors - one containing the Real parts the other containing the Imaginary parts. The input vectors must have a base type of double and must have the same number of elements.
Parameters:
vR=Input vector of doubles
vI=Input vector of doubles

Return values:
Returns a complex vector having the same size as vR on successful exit and
return an empty complex vector object on failure.

Example:
            vector vR = { 1, 2, 3 };
            vector vI = { 4, 5, 6 };
            vector <complex> vC(vR, vI);

Summary: Complex vector constructor.
Sample data:
Header file: vector.h
See also:
vector::vector
Prototype:
PUBLIC  vector()
Remarks: Default constructor for vector class.
Parameters:

Return values:

Example:
            vector vD;         // vector of doubles
            vector<string> vS; // vector of strings
            vector<int> vI;    // vector of ints

Summary: Default constructor for vector class.
Sample data:
Header file: vector.h
See also:
vector::vector
Prototype:
PUBLIC  vector(UINT nSize)
Remarks: Constructor to create a vector having size nSize.
Parameters:
nSize=Size of declared vector

Return values:

Example:
            vector vD(10);         // vector of 10 doubles
            vector<string> vS(10); // vector of 10 strings
            vector<int> vI(10);    // vector of 10 ints

Summary: Constructor to create a vector having size nSize.
Sample data:
Header file: vector.h
See also:
vector::vector
Prototype:
PUBLIC  vector(Dataset &ds, BOOL bRemoveMissingValues = FALSE)
Remarks: Constructor to create a vector copy of an Origin Dataset. Missing values may or may not be removed.
Parameters:
nSize=Size of declared vector

Return values:

Example:
            Dataset dsB("Data1_B");      // Origin data set Data1_B must exist
            dsB.SetSize(5);              // Set sizeof data set to 5
            dsB[0]=-1;
            dsB[1]=5;
            dsB[2]=NANUM;                // Will be removed
            dsB[3]=NANUM;                // Will be removed
            dsB[4]=23;
            vector vB( dsB, TRUE );      // Copy Dataset dsD to vector vD removing missing values
            ASSERT( vB.GetSize() == 3 ); // Elements dsB[2] and dsB[3] are removed

Summary: Constructor to create a vector copy of an Origin Dataset.
Sample data:
Header file: vector.h
See also: TrimLeft TrimRight


vectorbase

Class: vectorbase

Description: The Origin C vectorbase class is an abstract base class used for polymorphic handling of vector and Dataset related template class types. Consequently, Origin C objects of type vectorbase can not be constructed. Derived classes, such as vector and Dataset, inherit vectorbase class methods and should be used instead.

Hierarchy:

vectorbase

Sample:


Append

vectorbase::Append
Prototype:
PUBLIC  BOOL Append(vectorbase &vv)
Remarks: Append data from a vectorbase derived object to this vectorbase derived object.
Parameters:
vV=vector or Dataset to append

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            vector		vV;             // Initialize variables
            Dataset		dsB("Data1_B"); // Dataset Data1_B must exist in Origin

            dsB.SetSize(10);            // Initialize dataset
            for(int ii = 0; ii < 10; ii++)
            {
                dsB[ii] = 1000 * ii;
            }

            vV.SetSize(5);              // Initalize vector
            for(ii = 0; ii < 5; ii++)
            {
                vV[ii] = 10 * ii;
            }

            dsB.Append(vV);             // Append vector to dataset

Summary: Append data to a vectobase derived object.
Sample data:
Header file: vector.h
See also:
vectorbase::Append
Prototype:
PUBLIC  BOOL Append(_VARIANT& var)
Remarks: Append data from an object of type _VARIANT to a vectorbase derived object. _VARIANT is a universal type that exists in COM to hold various types of data. It is used to set or get the values of properties of COM objects. It can represent individual values of int, double, etc., as well as arrays and other composite types. This function is available only for OriginPro versions, or with a special COM enabled license
Parameters:
var=A COM data object of type _VARIANT

Return values:

Example:

Summary: Append a COM object of type _VARIANT to a vector or Dataset.
Sample data:
Header file: vector.h
See also:


Average

vectorbase::Average
Prototype:
PUBLIC  void Average(vectorbase &vSource, int nLength, int nMethod = RECT_WINDOW)
Remarks: do moving average for vector.
Parameters:
nLength: length of average window length;
nMethod: type of moving average window, now, only support RECT_WINDOW, always set it
as RECT_WINDOW now.

Return values:

Example:
            vector vv1 ={1,3,2,6,4,9,2,5,7};
            vector vv2;
            vv2.Average(vv1,3);
            ==> vv2=
              1.3333  2.0000  3.6667  4.0000  6.3333  5.0000  5.3333  4.6667  4.0000

Summary:
Sample data:
Header file: vector.h
See also:


Conjugate

vectorbase::Conjugate
Prototype:
PUBLIC  int Conjugate()
Remarks: Replace this vector with the Conjugate of this vector. A runtime error occurs if the underlying base type of this vector is not double or Complex.
Parameters:

Return values:
Returns 0 on success and -1 on failure which occurs if the vector is empty.

Example:
            vector<complex> vA(2);
            vA[0] = 1+2i; vA[1] = 3;
            vA.Conjugate();
            for(int ii = 0; ii < 2; ii++)
                    printf("%g + %gi, ",vA[ii].m_re, vA[ii].m_im);
                printf("\n");

Summary: Replace this vector with the Conjugate of this vector.
Sample data:
Header file: vector.h
See also: GetReal GetImaginary GetPhase GetAmplitude MakeComplex


Data

vectorbase::Data
Prototype:
PUBLIC  BOOL Data(double dStartVal, double dEndVal, double dIncVal = 1.0)
Remarks: Generate data values in a vector. This function is similar to the LabTalk function Data(min, max, inc). The vector will be automatically resized and populated with data values such that the first element in the vector will be dStartVal and the last element in the vector will be greater than or equal to dEndVal. If dIncVal is passed in as zero the function will fail. To set all elements in a vector to the same scalar value first set the vector size and then make a scalar assignment using the desired value.
Parameters:
dStartVal=Input value assigned to the first element in the vector
dEndVal=Input value generated for the last element in the vector
dIncVal=Input increment value used to calculate successive values in the vector

Return values:
Returns TRUE on success and FALSE on Failure.

Example:
        vector vData;
        vData.Data(1,10); // Generate 1,2,... 10
        ASSERT(vData.GetSize() == 10);

Summary: Generate data values in a vector.
Sample data:
Header file: vector.h
See also:


Difference

vectorbase::Difference
Prototype:
PUBLIC  BOOL Difference(vectorbase &vecDiff )
Remarks: Get the differences of a vector.
Parameters:
vecDiff will have the differences of target vector,
The length of vecDiff will be n-1 ,n is the length of target vector.

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            vector<int>	vv;
            vv.SetSize(4);
            vv[0] = 23;
            vv[1] = 12;
            vv[2] = 7;
            vv[3] = 28;

            vector<int> vr;
            BOOL bRet = vv.Difference(vr);
            ASSERT(bRet);
            ASSERT(vr[0] == vv[1] - vv[0]);
            ASSERT(vr[1] == vv[2] - vv[1]);
            ASSERT(vr[2] == vv[3] - vv[2]);

Summary:
Sample data:
Header file: vector.h
See also:


FrequencyCount

vectorbase::FrequencyCount
Prototype:
PUBLIC  int FrequencyCount(double dMin, double dMax, double dInc, vector<int>& vCounts, int wIncludeOutliers = FAB_NOT_INCLUDE_OUTLIERS)
Remarks: Compute a frequency count of the elements in a vector binning from dMin to dMax with a bin size of dInc. Values that fall on the lower edge of a bin are included in that bin and values that fall on the upper edge of a bin are included in the next higher bin.
Parameters:
dMin=The minimum value of the range
dMax=The maximum value of the range
dInc=The bin increment
vCounts=The result vector containing frequency counts
wIncludeOutliers=Flag indicating whether or not to include outliers in
first and last bins
0=Don't include outliers (default)
1=Include outliers < dMin in first bin
2=Include outliers >= dMax in last bin
3=Combination of 1 and 2 above

Return values:
Returns 0 on success and a non-zero error code on failure:
1=dInc is zero
2=dInc is greater than (dMax - dMin)

Example:
            // Data1_A (with data between 0 and 1) and Data1_B must exist
            Dataset dsA("Data1_A"), dsB("Data1_B");
            vector  vA(dsA);
            vector<int> vCounts;
            vA.FrequencyCount(0,1,0.05,vCounts);
            dsB = vCounts;

Summary: Compute a frequency count of elements in a vector.
Sample data:
Header file: vector.h
See also:


GetAmplitude

vectorbase::GetAmplitude
Prototype:
PUBLIC  int GetAmplitude( vector & vAmplitude )
Remarks: Get the amplitude(modulus) of the Complex vector. Causes a runtime error if the underlying base type of the vector is not Complex.
Parameters:
vAmplitude=Output vector containing amplitude(modulus) vector for this Complex vector

Return values:
Returns 0 on success and -1 on failure.

Example:
            vector<complex> vComplex = { 1+2i, 3+4i };
            vector vAmplitude1, vAmplitude2, vReal = { 1, 3 };
            vComplex.GetAmplitude( vAmplitude1 );
            printf( "vAmplitude1[0]=%g\nvAmplitude1[1]=%g", vAmplitude1[0], vAmplitude1[1] );
            vReal.GetAmplitude( vAmplitude2 ); // Causes runtime error

Summary: Get the amplitude(modulus) of the Complex vector.
Sample data:
Header file: vector.h
See also: GetReal GetImaginary GetPhase Conjugate MakeComplex


GetAs1DArray

vectorbase::GetAs1DArray
Prototype:
PUBLIC  _VARIANT GetAs1DArray()
Remarks: Assigning a vector or Dataset to a COM object of type _VARIANT generally creates a two dimensional array where the second dimension is 1 (vectors and Datasets are one dimensional so second dimension of _VARIANT is set to 1). This is what Excel expects when assigning a _VARIANT to a "Range" object. However, some COM objects require one dimensional arrays of type _VARIANT. GetAs1DArray returns a one dimensional array from a vector or Dataset. This function is available only for OriginPro versions, or with a special COM enabled license
Parameters:

Return values:
Returns a one dimensional array of type _VARIANT containg a copy of the data in a vector

Example:
            Dataset aa("data1_a");
            Object CW2DGraph = MyDlg.GetItem(IDC_CWGRAPH1).GetActiveXControl();
            CW2DGraph.PlotY(aa.GetAs1DArray());

Summary: Return a copy of a vector or Dataset as a one dimensional array of type _VARIANT.
Sample data:
Header file: vector.h
See also:


GetBytes

vectorbase::GetBytes
Prototype:
PUBLIC  int GetBytes(vector<byte>& vStream)
Remarks: Copy the elements of this vector into an internal buffer.
Parameters:
vStream=Output vector or internal buffer containing bytes copied from this vector

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            vector<int> vTemp = {1,2,3,4,5};
            vector<byte> vResult;
            vTemp.GetBytes(vResult);
            int iSize = vResult.GetSize();
            ASSERT(iSize == 4 * vTemp.GetSize());

Summary: Copy the elements of this vector into an internal buffer.
Sample data:
Header file: vector.h
See also: SetBytes


GetImaginary

vectorbase::GetImaginary
Prototype:
PUBLIC  int GetImaginary( vector & vImag )
Remarks: Get the Imaginary part of a Complex vector. Causes a runtime error if the underlying base type of the vector is not Complex.
Parameters:
vImag=Output vector containing the Imaginary part of this Complex vector

Return values:
Returns 0 on success and -1 on failure.

Example:
            vector<complex> vComplex = { 1+2i, 3+4i };
            vector vImag1, vImag2;
            vComplex.GetImaginary( vImag1 );      // vImag1 = { 2, 4 };
            printf( "vImag1[0]=%g\nmImag1[1]=%g", vImag1[0], vImag1[1] );
            vImag1.GetImaginary( vImag2 );        // Causes runtime error

Summary: Get the Imaginary part of a Complex vector.
Sample data:
Header file: vector.h
See also: GetReal GetPhase GetAmplitude Conjugate MakeComplex


GetInternalDataType

vectorbase::GetInternalDataType
Prototype:
PUBLIC  int GetInternalDataType()
Remarks: Get the internal or underlying base data type of a vectorbase derived object.
Parameters:

Return values:
Returns FSI_DOUBLE, FSI_REAL, FSI_SHORT, FSI_LONG, FSI_CHAR, FSI_TEXT, FSI_MIXED, FSI_BYTE, FSI_USHORT,
FSI_ULONG, or FSI_COMPLEX which are enumerated in OC_const.h.

Example:
            vector vDouble;
            vector<char> vChar;
            vector<int> vInt;
            int nType;
            nType = vDouble.GetInternalDataType(); // Return FSI_DOUBLE
            printf( "nType for double = %d\n", nType );
            nType = vChar.GetInternalDataType(); // Return FSI_CHAR
            printf( "nType for char = %d\n", nType );
            nType = vInt.GetInternalDataType(); // Return FSI_LONG
            printf( "nType for int = %d\n", nType );

Summary: Get the internal or underlying base data type of a vectorbase derived object.
Sample data:
Header file: vector.h
See also:


GetLabTalkVectorValue

vectorbase::GetLabTalkVectorValue
Prototype:
PUBLIC  BOOL GetLabTalkVectorValue(LPCTSTR lpcszLabTalkVector)
Remarks: Assigns a LabTalk vector to an Origin C vector.
Parameters:
lpcszLabTalkVector=Input name of LabTalk vector

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            vector<string> vsColumns;
            if( vsColumns.GetLabTalkVectorValue("wks.cname"))
            {
                for(int ii = 0; ii < vsColumns.GetSize(); ii++)
                {
                    printf("Column (%d) : %s\n", ii, vsColumns[ii]);
                }
            }
            else
                printf("Could not find wks.cname$\n");

Summary: Assigns a LabTalk vector to an Origin C vector.
Sample data:
Header file: vector.h
See also: SetLabTalkVectorValue


GetLowerBound

vectorbase::GetLowerBound
Prototype:
PUBLIC  int GetLowerBound()
Remarks: Get the lower index of the vectorbase range. Index values returned are 0 based offsets. SetLowerBound is supported only for Datasets (not vectors) while GetLowerBound is supported for all vectorbase derived objects. This allows for creation of more general purpose functions that can take vectorbase objects as arguments in place of Dataset objects. Essentially, the lower bound can be read but not written for vectors. If the vectorbase object is not a Dataset then GetLowerBound should always return 0. GetLowerIndex is a synonym for GetLowerBound.
Parameters:

Return values:
The lower display index of the Dataset (0 based offset)

Example:
            // Worksheet column Data1_A must exist prior to execution
            int ii, jj, kk;
            Dataset	dsA("Data1_A");
            double dSumA = 0;
            jj = dsA.GetLowerBound();
            kk = dsA.GetUpperBound();
            for(ii = jj; ii <= kk; ii++)
                dSumA += dsA[ii];
            ASSERT( dsA.GetLowerIndex() == dsA.GetLowerBound() );

Summary: Get the lower index of the Dataset display range.
Sample data:
Header file: vector.h
See also: SetLowerBound GetSize SetSize GetUpperBound SetUpperBound


GetMinMax

vectorbase::GetMinMax
Prototype:
PUBLIC  int GetMinMax(double& min, double& max, uint* pIndexMin = NULL, uint* pIndexMax = NULL)
Remarks: Get min and max values and associated indecies of current vector. For complex, the amplitude will be calculated.
Parameters:

Return values:
The total number of none-missing values in the vector. For complex,
if either of real and imaginary part is missing value, the amplitude will be a missing value.

Example:
            vector<int> vTarget = { 5, 6 ,1, 2, 3, 4 };
            double dbMin, dbMax;
            uint nIndexMin;
            uint nIndexMax;
            uint nCountNonMissingValue = vTarget.GetMinMax(dbMin, dbMax, &nIndexMin, &nIndexMax);
            ASSERT(dbMin == 1.0);
            ASSERT(dbMax == 6.0);
            ASSERT(nIndexMin == 2);
            ASSERT(nIndexMax == 1);
            ASSERT(nCountNonMissingValue == 6);
            // here is another example, which shows how to use this in a worksheet
            void show_wks_min_max(string strWks = "Data1")
            {
                Worksheet wks(strWks);

                foreach(Column cc in wks.Columns)
                {
                    vector vv(cc, 0, cc.GetNumRows()-1); // copy col data into a vector of double
                    double min, max;
                    uint imin, imax;
                    vv.GetMinMax(min, max, &imin, &imax);
                    // show index in LabTalk convention of 1-offset
                    printf("Col(%s): max[%d] = %f, min[%d] = %f\n", cc.GetName(), imax+1, max, imin+1, min);
                }
            }

Summary:
Sample data:
Header file: vector.h
See also: None


GetPhase

vectorbase::GetPhase
Prototype:
PUBLIC  int GetPhase( vector & vPhase )
Remarks: Get the phase angle vector, in radians, of the Complex vector. Causes a runtime error if the underlying base type of the vector is not Complex.
Parameters:
vPhase=Output vector containing the phase angle vector for this Complex vector

Return values:
Returns 0 on success and -1 on failure.

Example:
            vector<complex> vComplex = { 1+2i, 3+4i };
            vector vPhase1, vPhase2, vReal = { 1, 3 };
            vComplex.GetPhase( vPhase1 );
            printf( "vPhase1[0]=%g\nvPhase1[1]=%g", vPhase1[0], vPhase1[1] );
            vReal.GetPhase( vPhase2 ); // Causes runtime error

Summary: Get the phase angle vector, in radians, of the Complex vector.
Sample data:
Header file: vector.h
See also: GetReal GetImaginary GetAmplitude Conjugate MakeComplex


GetReal

vectorbase::GetReal
Prototype:
PUBLIC  int GetReal( vector & vReal )
Remarks: Get the Real part of a Complex vector. Causes a runtime error if the underlying base type of the vector is not Complex.
Parameters:
vReal=Output vector containing the Real part of this Complex vector

Return values:
Returns 0 on success and -1 on failure.

Example:
            vector<complex> vComplex = { 1+2i, 3+4i };
            vector vReal1, vReal2;
            vComplex.GetReal( vReal1 );  // vReal1 = { 1, 3 };

            printf( "vReal1[0]=%g\nvReal1[1]=%g", vReal1[0], vReal1[1] );
            vReal1.GetReal( vReal2 );    // Causes runtime error

Summary: Get the Real part of a Complex vector.
Sample data:
Header file: vector.h
See also: GetImaginary GetPhase GetAmplitude Conjugate MakeComplex


GetSize

vectorbase::GetSize
Prototype:
PUBLIC  UINT GetSize() const
Remarks: Get the size of (number of elements in) a vectorbase derived object.
Parameters:

Return values:
Returns the size of the vectorbase derived object.

Example:
            vector vV;
            vV.SetSize( 99 );
            ASSERT( vV.GetSize() == 99 );

Summary: Get the size of a vectorbase derived object.
Sample data:
Header file: vector.h
See also: GetUpperBound


GetUpperBound

vectorbase::GetUpperBound
Prototype:
PUBLIC  int GetUpperBound()
Remarks: Get the upper index of the vectorbase range. Index values returned are 0 based offsets. SetUpperBound is supported only for Datasets (not vectors) while GetUpperBound is supported for all vectorbase derived objects. This allows for creation of more general purpose functions that can take vectorbase objects as arguments in place of Dataset objects. Essentially, the upper bound can be read but not written for vectors. Please note that GetUpperBound is always GetSize - 1. GetUpperIndex is a synonym for GetUpperBound.
Parameters:

Return values:
The upper display index of the vector (0 based offset)

Example:
            // Worksheet column Data1_A must exist prior to execution
            int ii, jj, kk;
            Dataset	dsA("Data1_A");
            double dSumA = 0;
            jj = dsA.GetLowerBound();
            kk = dsA.GetUpperBound();
            for(ii = jj; ii <= kk; ii++)
                dSumA += dsA[ii];
            ASSERT( dsA.GetUpperIndex() == dsA.GetUpperBound() );

Summary: Get the upper index of the Dataset display range.
Sample data:
Header file: vector.h
See also: SetUpperBound GetSize SetSize GetLowerBound SetLowerBound


MakeComplex

vectorbase::MakeComplex
Prototype:
PUBLIC  int MakeComplex(vectorbase & vbReal, vectorbase & vbImag)
Remarks: Make a Complex vector from two Real vectors (which must have the same dimensions).
Parameters:
vbReal=The vector containing the Real part
vbImag=The vector containing the Imaginary part

Return values:
Returns 0 on success and -1 on failure.

Example:
            vector vA(2), vB(2);
            vector<complex> vC(2);

            vA[0] = 1;			vB[0] = -2;
            vA[1] = -3;			vB[1] = 1;

            vC.MakeComplex(vA,vB);

            for(int ii = 0; ii < 2; ii++)
                    printf("%g + %gi\n",vC[ii].m_re,vC[ii].m_im);

Summary: Make a Complex vector from two Real vectors.
Sample data:
Header file: vector.h
See also: GetReal GetImaginary GetPhase GetAmplitude Conjugate


Normal

vectorbase::Normal
Prototype:
PUBLIC  BOOL Normal(int nSize, int nSeed = 0)
Remarks: fill the vector with pseudorandom values from a normal distribution with zero mean and unit standard deviation. This method is similar to the LabTalk Normal function. If this method is used on an integer vector, then the resulting vecter will be filled with nearest iintegers from the distribution which has typical values betwen -3 and 3
Parameters:
nSize = number of values
nSeed = seed of the random sequence. Using a value of 0 will generate a different seuqence each time this function is called, while using the same seed will generate the same sequence

Return values:
Returns TRUE on success and FALSE on Failure.

Example:
        void run_Normal()
        {
            vector  vv;
            vv.SetSize(20);
            BOOL bRet = vv.Normal(vv.GetSize());
            for(int ii=0; ii<vv.GetSize(); ii++)
            {
                out_double("",vv[ii]);
            }
        }

Summary:
Sample data:
Header file: vector.h
See also:


RemoveAll

vectorbase::RemoveAll
Prototype:
PUBLIC  void RemoveAll()
Remarks: Removes all elements in the vector.
Parameters:

Return values:

Example:
        vector<int> vnData = {1,2,3};
        vnData.RemoveAll();
        ASSERT(0 == vnData.GetSize());

Summary:
Sample data:
Header file: vector.h
See also:


Reorder

vectorbase::Reorder
Prototype:
PUBLIC  BOOL Reorder(const vector<uint>& vnIndeces)
Remarks: Rearrange the vector according to the given indeces
Parameters:
vnIndeces = 0 offset indeces to reorder vector. The indeces must be all unique and include all of the indeces in current vector

Return values:

Example:
            vector<uint> vn = {0,2,1};
            vector<string> vs1 = {"AA", "BB", "CC"};
            vs1.Reorder(vn);
            // result vs1 = AA CC BB

            // the following code sort one vector based on another
            vector<uint> vnIndeces;
            vector<string> vs1 = {"AA", "BB", "CC"};
            vector<double> vdWeight = {0.1, 0.4, 0.2};
            vdWeight.Sort(SORT_ASCENDING, TRUE, vnIndeces);
            vs1.Reorder(vnIndeces);
            // result vs1 = AA CC BB

Summary:
Sample data:
Header file: vector.h
See also:


SetBytes

vectorbase::SetBytes
Prototype:
PUBLIC  int SetBytes(vector<byte>& vStream)
Remarks: Set the elements of this vector from an internal buffer.
Parameters:
vStream=Input vector or internal buffer containing bytes copied to this vector

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            vector<int> vTemp1 = {1,2,3,4,5}, vTemp2;
            vector<byte> vResult;
            vTemp1.GetBytes(vResult);
            int iSize = vResult.GetSize();
            ASSERT(iSize == 4 * vTemp1.GetSize());
            vTemp2.SetSize(vTemp1.GetSize());
            vTemp2.SetBytes(vResult);

Summary: Set the elements of this vector from an internal buffer.
Sample data:
Header file: vector.h
See also: GetBytes


SetLabTalkVectorValue

vectorbase::SetLabTalkVectorValue
Prototype:
PUBLIC  BOOL SetLabTalkVectorValue(LPCTSTR lpcszLabTalkVector)
Remarks: Assigns an Origin C vector to a LabTalk vector.
Parameters:
lpcszLabTalkVector=Input name of LabTalk vector

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            vector<string> vsExt = {"OPJ", "TXT"};
            vector<string> vsExtSave;
            string strExt;

            BOOL bSaved = vsExtSave.GetLabTalkVectorValue("FDlog.Type"); //Save the Current settings

            if(vsExt.SetLabTalkVectorValue("FDlog.Type"))
            {
                for(int ii = 0; ii < vsExt.GetSize(); ii++)
                {
                    strExt = LabTalk.FDlog.Type$(ii+1)$;
                    printf("FDLog Type (%d) : %s\n", ii, strExt);
                }
            }
            else
                printf("Could not find FDlog.Type$\n");
            if(bSaved)
                vsExtSave.SetLabTalkVectorValue("FDlog.Type"); //Restore the older settings

Summary: Assigns an Origin C vector to a LabTalk vector.
Sample data:
Header file: vector.h
See also: GetLabTalkVectorValue


SetSize

vectorbase::SetSize
Prototype:
PUBLIC  BOOL SetSize(UINT nSize, int nGrowBy = -1)
Remarks: Dynamically set the size of (number of elements in) a vectorbase derived object.
Parameters:
nSize=Number of elements in re-sized vectorbase derived object
nGrowBy=Currently not used, users should omit from call to pass default -1

Return values:
Returns TRUE on successful exit and FALSE on error.

Example:
            vector vV;
            vV.SetSize( 361 );
            for( int ii = 0; ii < 361; ii++ )
            {
                vV[ii] = cos(ii*PI/180);
            }

Summary: Set the size of a vectorbase derived object.
Sample data:
Header file: vector.h
See also: SetUpperBound


Sort

vectorbase::Sort
Prototype:
PUBLIC  BOOL Sort(BOOL wOption = SORT_ASCENDING, BOOL bMissingValuesSmall = TRUE)
Remarks: Sort the elements of the vectorbase derived object. Not yet implemented for complex
Parameters:
wOrder = Default value SORT_ASCENDING sorts in ascending order, SORT_DESCENDING sorts in descending order
bMissingAtEnd = when it is FALSE, all missing value will be put in the end, Ignore for string
vnIndeces = Optional array to retrive the original indeces that corresponds to the sorted values
See Also:
Reorder

Return values:

Example:
            vector<string> vV;
            vV.SetSize(5);
            vV[0]="-1";
            vV[1]="5";
            vV[2]="Hello";
            vV[3]="";
            vV[4]="GoodeBye";
            vV.Sort();// sort Text

            // here is a example to show to sort col(a) and put into col(b)
            Worksheet wks("Data1");
            Column colA(wks, 0);
            vector va(colA); // copy data, skip all missing values on both ends
            va.Sort(); // sort numeric
            Dataset dsB(wks, 1);
            dsB = va;

Summary:
Sample data:
Header file: vector.h
See also:
vectorbase::Sort
Prototype:
PUBLIC  BOOL Sort(BOOL wOption = SORT_ASCENDING, BOOL bMissingValuesSmall = TRUE, vector<uint>& vnIndeces = NULL)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: vector.h
See also:


Sum

vectorbase::Sum
Prototype:
PUBLIC  int Sum(int & nSum)
Remarks: Compute a sum of all the elements in this vector. The argument type must be greater than or equal to the underlying base type of the vector.
Parameters:
nSum=Output sum of all the elements in the vector

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii, nSum;
            vector<short> vShort = {1,2,3,4,5};
            printf("vShort:\n");
            for(ii = 0; ii < vShort.GetSize(); ii++)
                printf("%d\t",vShort[ii]);
            printf("\n\n");

            vShort.Sum(nSum);
            printf("Sum of vShort is %d", nSum);

Summary:
Sample data:
Header file: vector.h
See also: Data_sum
vectorbase::Sum
Prototype:
PUBLIC  int Sum(double & dSum)
Remarks: Compute a sum of all the elements in this vector. The argument type must be greater than or equal to the underlying base type of the vector.
Parameters:
dSum=Output sum of all the elements in the vector

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii;
            double dSum;
            vector vDouble = {1.1,2.1,3.1,4.1,5.1};
            printf("vDouble:\n");
            for(ii = 0; ii < vDouble.GetSize(); ii++)
                printf("%g\t",vDouble[ii]);
            printf("\n\n");

            vDouble.Sum(dSum);
            printf("Sum of vDouble is %g", dSum);

Summary:
Sample data:
Header file: vector.h
See also: Data_sum
vectorbase::Sum
Prototype:
PUBLIC  int Sum(complex & cxSum)
Remarks: Compute a sum of all the elements in this vector. The argument type must be greater than or equal to the underlying base type of the vector.
Parameters:
cxSum=Output sum of all the elements in the vector

Return values:
Returns 0 on success and a non-zero error code on failure.

Example:
            int ii;
            complex cxSum;
            vector<complex> vComplex = {1+2i,2-1i,3+4i,4-3i,5+2i};
            printf("vComplex:\n");
            for(ii = 0; ii < vComplex.GetSize(); ii++)
                printf("%g+%gi\t",vComplex[ii].m_re,vComplex[ii].m_im);
            printf("\n\n");

            vComplex.Sum(cxSum);
            printf("Sum of vComplex is %g+%gi", cxSum.m_re, cxSum.m_im);

Summary:
Sample data:
Header file: vector.h
See also: Data_sum


Trim

vectorbase::Trim
Prototype:
PUBLIC  bool Trim()
Remarks: Remove all missing values from the vectorbase derived object and resize acordingly shifting non-missing data values up. Trim of Curve objects causes both X and Y Datasets to be trimmed.
Parameters:

Return values:
Returns true on success and false on failure.

Example:
            Dataset ds("Data1_A"); // Containing missing values
            ds.Trim();

Summary:
Sample data:
Header file: vector.h
See also: TrimLeft TrimRight GetLowerBound vector


TrimLeft

vectorbase::TrimLeft
Prototype:
PUBLIC  int TrimLeft(BOOL bShiftLeft = FALSE)
Remarks: TrimLeft removes elements having the value NANUM from the left end or beginning of the vectorbase derived object by advancing the lower index to the first valid numeric value. If bShiftLeft is TRUE cells containing NANUM are deleted from the vectorbase object and a lower index value of 0 is returned shifting numeric values left. bShiftLeft must be TRUE for vectors or this function will have no effect. When bShiftLeft is TRUE TrimLeft of Curve objects causes both X and Y Datasets to be trimmed.
Parameters:
bShiftLeft=TRUE will delete cells on the left of (before) the first valid numeric value, FASLE will cause the lower bound
or index to be adjusted upward but no cells are deleted.

Return values:
Returns -1 on error, 0 on success, and N > 0 for number of cells deleted.

Example:
            // Worksheet columns Data1_A and data1_B must exist prior to execution
            Dataset	dsA("Data1",0);
            dsA.TrimLeft(TRUE);
            Curve crvAxBy("Data1_A","Data1_B");
            crvAxBy.TrimLeft(TRUE);
            LT_execute("doc -uw");

Summary: TrimLeft removes elements having the value NANUM from the left end of a Dataset.
Sample data:
Header file: vector.h
See also: Trim TrimRight GetLowerBound vector


TrimRight

vectorbase::TrimRight
Prototype:
PUBLIC  int TrimRight(BOOL bDelExtra = FALSE)
Remarks: TrimRight removes elements having the value NANUM from the right end or bottom of vectorbase derived objects by retarding the upper index to the last valid numeric value. If bDelExtra is set to TRUE cells containing NANUM are deleted from the vectorbase object. When bDelExtra is TRUE TrimRight of Curve objects causes both X and Y Datasets to be trimmed.
Parameters:
bDelExtra=TRUE will delete cells on the right of (after) the last valid numeric value, FASLE will cause the upper bound
or index to be adjusted downward but no cells are deleted.

Return values:
Returns -1 on error, 0 on success, and N > 0 for number of cells deleted.

Example:
            // Worksheet columns Data1_A and data1_B must exist prior to execution
            Dataset	dsA("Data1",0);
            dsA.TrimRight(TRUE);
            Curve crvAxBy("Data1_A","Data1_B");
            crvAxBy.TrimRight(TRUE);
            LT_execute("doc -uw");

Summary: TrimRight removes elements having the value NANUM from the right end of a Dataset.
Sample data:
Header file: vector.h
See also: Trim TrimLeft GetUpperBound GetSize vector


Uniform

vectorbase::Uniform
Prototype:
PUBLIC  BOOL Uniform(int nSize, int nSeed = 0)
Remarks: fill the vector with pseudorandom values between 0 and 1 from a uniform distribution. This method is similar to the LabTalk Uniform function. If this method is used on an integer vector, then the resulting vecter will be filled with 0s and 1s.
Parameters:
nSize = number of values
nSeed = seed of the random sequence. Using a value of 0 will generate a different seuqence each time this function is called, while using the same seed will generate the same sequence

Return values:
Returns TRUE on success and FALSE on Failure.

Example:
        void run_Uniform()
        {
            vector  vv;
            vv.SetSize(20);
            BOOL bRet = vv.Uniform(vv.GetSize());
            for(int ii=0; ii<vv.GetSize(); ii++)
            {
                out_double("",vv[ii]);
            }
        }

Summary:
Sample data:
Header file: vector.h
See also:


Wrap

vectorbase::Wrap
Prototype:
PUBLIC  BOOL Wrap(int nNum =0)
Remarks: Wrap around elements.
Parameters:
when the value is 0, no wrap, when value less than zero, do left_wrap, other wise do right_wrap.

Return values:

Example:
            vector vec = {1,2,3,4,5,6,7,8,9};
            vec.Wrap(4);
            ==> vec = {5,6,7,8,9,1,2,3,4}

Summary:
Sample data:
Header file: vector.h
See also:


Axis

Class: Axis

Description: The Axis class is derived from the OriginObject class and provides access to Origin axes. Origin axes are contained by layers on an Origin page.

Hierarchy:

OriginObject
 Axis

Sample:


Axis

Axis::Axis
Prototype:
PUBLIC  Axis()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: graph.h
See also:
Axis::Axis
Prototype:
PUBLIC  Axis(const Axis& axis)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: graph.h
See also:


AxisObjects

Axis::AxisObjects
Prototype:
PUBLIC  AxisObject AxisObjects(int nIndex)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: graph.h
See also:


AxisObject

Class: AxisObject

Description: The AxisObject class is derived from the OriginObject class and provides access to Origin axis ticks, grids and labels. Origin axis objects are contained by axes on an Origin page.

Hierarchy:

OriginObject
 AxisObject

Sample:


AxisObject

AxisObject::AxisObject
Prototype:
PUBLIC  AxisObject()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: graph.h
See also:
AxisObject::AxisObject
Prototype:
PUBLIC  AxisObject(const AxisObject& ao)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: graph.h
See also:


Collection

Class: Collection

Description: The Collection class provides a template for collections of various internal Origin objects such as "Pages" (the collection of all PageBase objects in a project file), etc. The Collection class has an implicit templatized type _TemplType, which is the type of one element of the collection. For example, for the Project class Pages collection (Collection<PageBase> Pages;) the templatized type is PageBase. Each collection usually has a parent class which is the class whose data member is the collection. For example, Collection<PageBase> Pages is a member of the Project class because Project contains all the pages. Therefore, each collection can be attached to one internal object or be unattached. The methods of the Collection class are common for all collections. One of the most useful ways to use a collection is in the foreach loop (see the Example).

Hierarchy:

Collection

Sample:

        // This function demonstrates looping over all the members of a collection
        // using a foreach loop
        // Default constructor creates an unattached Collection object:
        Collection<PageBase> pbColl;

        // Attach to the collection of all the pages in the project:
        pbColl = Project.Pages;

        PageBase pb;

        foreach(pb in pbColl)
        {
            // Display the name of the page:
            out_str(pb.GetName());
        }


Collection

Collection::Collection
Prototype:
PUBLIC  Collection()
Remarks: The default constructor which constructs an uninitialized collection.
Parameters:
None.

Return values:
None.

Example:
        void	run_Collection()
        {
            Collection<PageBase>	pgColl;
        }

Summary:
Sample data:
Header file: Collection.h
See also:


Count

Collection::Count
Prototype:
PUBLIC  UINT Count()
Remarks: Returns the count of all the objects in the collection.
Parameters:
None.

Return values:
the count of objects

Example:
        // The function display the total number of pages in the project.
        void	run_Collection_Count()
        {
            // Default constructor creates an unattached Collection object:
            Collection<PageBase>	pgColl;

            // Attach to the collection of all the pages in the project:
            pgColl = Project.Pages;

            // Get the total count:
            printf("Total count of objects is %d.\n", pgColl.Count());
        }

Summary:
Sample data:
Header file: Collection.h
See also:


Item

Collection::Item
Prototype:
PUBLIC  _TemplType Item(int nIndex)
Remarks: It returns the nIndex'th item of the collection.
Parameters:
nIndex = 0-offset index of the needed item in the collection

Return values:
the item corresponding to the supplied index.

Example:
        void	run_Collection_Item()
        {
            // Default constructor creates an unattached Collection object:
            Collection<PageBase>	pgColl;

            // Attach to the collection of all the pages in the project:
            pgColl = Project.Pages;

            // Get the first page in the collection:
            PageBase				pg = pgColl.Item(0);

            // Display the name of the page:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Collection.h
See also:
Collection::Item
Prototype:
PUBLIC  _TemplType Item(LPCSTR lpcszName)
Remarks: It returns the item with the name lpcszName in the collection.
Parameters:
lpcszName = the name of the desired item.

Return values:
the item corresponding to the supplied name.

Example:
        // For this example to run, make sure that the project contains
        // a window with the name "Data1".
        void	run_Collection_Item()
        {
            // Default constructor creates an unattached Collection object:
            Collection<PageBase>	pgColl;

            // Attach to the collection of all the pages in the project:
            pgColl = Project.Pages;

            // Get the page "Data1" in the collection:
            PageBase				pg = pgColl.Item("Data1");

            // Display the name of the page:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Collection.h
See also:


Column

Class: Column

Description: The Column class provides methods and properties common to Origin worksheet columns. An Origin C Worksheet object has a collection of Column objects each of which in turn holds a Dataset. A Column object is primarily used for style related control of the data in the associated Dataset. An Origin C Column object is a wrapper object that is a reference to an internal Origin column object. Wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The Column class is derived from the DataObject, DataObjectBase, and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 DataObjectBase
 DataObject
 Column

Sample:

        Worksheet wks = Project.ActiveLayer();
        if(!wks)
            return;
        int ii = 1;
        foreach(Column cc in wks.Columns)
        {
            string strLabel;
            if(cc.GetLabel(strLabel) > 0)
                printf("Column(%d) has label = %s\n",ii++, strLabel);
        }


Attach

Column::Attach
Prototype:
PUBLIC  BOOL Attach(LPCSTR lpcszWksName, UINT iColNum)
Remarks: Attach the column object to a Worksheet column by worksheet name
Parameters:
lpcszWksName = name of the worksheet
iColNum 	 = column number in the worksheet at which the column should be attached

Return values:
True for success; false otherwise

Example:
    void test_Column_Attach1()
    {
        Column colMy;
        if (colMy.Attach("Data1", 0))
            out_str("A column is attached to the first column of worksheet Data1.");
        else
            out_str("Attach error!");
    }

Summary:
Sample data:
Header file: wksheet.h
See also:
Column::Attach
Prototype:
PUBLIC  BOOL Attach(Worksheet &wks, UINT iColNum)
Remarks: Attach the column object to a Worksheet column using a worksheet object
Parameters:
wks = worksheet object
iColNum = column number in the worksheet at which the column should be attached.

Return values:
True for success; false otherwise

Example:
    void test_Column_Attach2()
    {
        Worksheet wksMy("Data1");
        Column colMy;
        if (colMy.Attach(wksMy, 0))
            out_str("A column is attached to the first column of worksheet Data1.");
        else
            out_str("Attach error!");
    }

Summary:
Sample data:
Header file: wksheet.h
See also:


Column

Column::Column
Prototype:
PUBLIC  Column(DataObject& colOriginal)
Remarks: Since a Column is a wrapper of the actual internal column inside Origin, you can make copies of this wrapper and both the original and the copy will both be refering to the same internal object.
Parameters:
colOriginal = column object

Return values:
None

Example:
    void test_Column_Column4()
    {
            Column colOriginal("Data1", 0);
            Column colNew(colOriginal);
            string strName;
            if(colMy.IsValid())
            {
                colMy.GetName(strName);
                out_str(strName);
            }
    }

Summary:
Sample data:
Header file: wksheet.h
See also:
Column::Column
Prototype:
PUBLIC  Column()
Remarks: Default constructor for Column class
Parameters:
None

Return values:
None

Example:
    void test_Column_Column1()
    {
            Column colMy;
            string strName;
            colMy.Attach("Data1", 0);
            if(colMy.IsValid())
            {
                colMy.GetName(strName);
                out_str(strName);
            }
    }

Summary:
Sample data:
Header file: wksheet.h
See also:
Column::Column
Prototype:
PUBLIC  Column(LPCTSTR lpcszWksName, UINT iColNum)
Remarks: Constructor that creates an Column object when given a column number in a worksheet.
Parameters:
lpcszWksName = name of the worksheet
iColNum      = column number in the worksheet

Return values:
None

Example:
    void test_Column_Column2()
    {
            Column colMy("Data1", 0);
            string strName;
            if(colMy.IsValid())
            {
                colMy.GetName(strName);
                out_str(strName);
            }
    }

Summary:
Sample data:
Header file: wksheet.h
See also:
Column::Column
Prototype:
PUBLIC  Column(Worksheet &wks, UINT iColNum)
Remarks: Constructor that creates an Column object when given a column number in a worksheet.
Parameters:
wks = worksheet object
iColNum = column number in the worksheet

Return values:
None

Example:
    void test_Column_Column3()
    {
            Worksheet wksMy("Data1");
            Column colMy(wksMy, 0);
            string strName;
            if(colMy.IsValid())
            {
                colMy.GetName(strName);
                out_str(strName);
            }
    }

Summary:
Sample data:
Header file: wksheet.h
See also:


ExecuteFormula

Column::ExecuteFormula
Prototype:
PUBLIC  BOOL ExecuteFormula(int nBegin = -1, int nEnd = -1, BOOL bUndo = TRUE)
Remarks: Triggers the execution of column formula For Origin version 8 or later: If nBegin and nEnd are negative formula is applied to range calculated based on the upper and lower bounds of columns the formula refers to If column formula does not refer to other columns it is applied to all rows in the column
Parameters:
nBegin = begining row index (0 based);
nEnd = end row index (0 based);
bUndo = if this parameter is TRUE method can be undone

Return values:

Example:
        Worksheet wks = Project.ActiveLayer();
        Column colObj(wks, 0);
        colObj.SetFormula("col(B)*2");
        colObj.ExecuteFormula(0, 10);

Summary:
Sample data:
Header file: wksheet.h
See also:


GetDataObject

Column::GetDataObject
Prototype:
PUBLIC  vectorbase& GetDataObject()
Remarks: Get the Dataset associated with a column as a vectorbase class reference for using in functions that expect a vectorbase class. Using vectorbase will allow the same function to be used on any data type
Parameters:

Return values:
a reference to the vectorbase class object for the associated dataset in the column

Example:
        static void show_sum(vectorbase& vtemp)
        {
            if(vtemp.GetSize() < 1)
                return;
            double vv;
            vtemp.Sum(vv);
            printf("sum of vector is %f\n", vv);
        }

        void tt()
        {
                Worksheet wks = Project.ActiveLayer();
                if( wks )
                {
                    int ii = 1;
                    foreach(Column cc in wks.Columns)
                    {
                        printf("Col(%d)'s name is %s\n",ii++, cc.GetName());
                        vectorbase &aa=cc.GetDataObject();
                        show_sum(aa);
                    }
                }
        }

Summary:
Sample data:
Header file: wksheet.h
See also:


GetDigitMode

Column::GetDigitMode
Prototype:
PUBLIC  int GetDigitMode()
Remarks: Gets the display mode used for numbers in a column
Parameters:
None

Return values:
The ColDigitMode for enum {DIGITS_FREE_FORM, DIGITS_DECIMAL, DIGITS_SIGNIFICANT}

Example:
        Worksheet wks("data1");
        int iDigitMode = wks.Columns(0).GetDigitMode();

Summary:
Sample data:
Header file: wksheet.h
See also: SetDigitMode GetDigits SetDigits


GetDigits

Column::GetDigits
Prototype:
PUBLIC  int GetDigits()
Remarks: Get the digit value for numeric display mode
Parameters:
None

Return values:
The Digits value, -1 for error

Example:
        Worksheet wks("data1");
        int iDigits = wks.Columns(0).GetDigits();

Summary:
Sample data:
Header file: wksheet.h
See also: GetDigitMode SetDigitMode SetDigits


GetFormat

Column::GetFormat
Prototype:
PUBLIC  int GetFormat()
Remarks: Get the column format
Parameters:
None

Return values:
The column format, enum {
OKCOLTYPE_NUMERIC,
OKCOLTYPE_TEXT,
OKCOLTYPE_TIME,
OKCOLTYPE_DATE,
OKCOLTYPE_MONTH,
OKCOLTYPE_WEEKDAY,
OKCOLTYPE_TEXT_NUMERIC};

Example:
        Worksheet wks("data1");
        int iFormat = wks.Columns(0).GetFormat();

Summary:
Sample data:
Header file: wksheet.h
See also: SetFormat


GetFormula

Column::GetFormula
Prototype:
PUBLIC  string GetFormula()
Remarks: Get column formula from column
Parameters:

Return values:

Example:
        Worksheet wks = Project.ActiveLayer();
        Column colObj(wks, 0);
        string strFormula = colObj.GetFormula();

Summary:
Sample data:
Header file: wksheet.h
See also:


GetIndex

Column::GetIndex
Prototype:
PUBLIC  int GetIndex()
Remarks: Get the column number, 0 offset.
Parameters:
None

Return values:
column number or -1 if invalid.

Example:
        Worksheet wks("data1");
        int nCol = wks.Columns("B").GetIndex();
        string strNewColName;
        if(nCol >=0)
            wks.InsertCol(nCol+1, "Result", strNewColName);

Summary:
Sample data:
Header file: wksheet.h
See also:


GetInternalData

Column::GetInternalData
Prototype:
PUBLIC  UINT GetInternalData()
Remarks: Get the column internal data types
Parameters:
No arguments

Return values:
the internal type of a column:enum{
FSI_DOUBLE = 0,
FSI_REAL,
FSI_SHORT,
FSI_LONG };

Example:
        Worksheet wks("data1");
        int iInternalData = wks.Columns("0").GetInternalData();

Summary:
Sample data:
Header file: wksheet.h
See also: SetInternalData


GetJustify

Column::GetJustify
Prototype:
PUBLIC  int GetJustify()
Remarks: Get the column justification
Parameters:
None

Return values:
Justification for enum{
COL_JUSTIFY_LEFT = 1,
COL_JUSTIFY_RIGHT,
COL_JUSTIFY_CENTER }

Example:
        Worksheet wks("data1");
        int iJustify = wks.Columns(0).GetJustify();

Summary:
Sample data:
Header file: wksheet.h
See also: SetJustify


GetLabel

Column::GetLabel
Prototype:
PUBLIC  int GetLabel(string &strLabel)
Remarks: Get the column label
Parameters:
strLabel = reference to the string that will receive the label

Return values:
length of the label, 0 if none, -1 if error

Example:
        Worksheet wks("data1");
        string strLabel;
        int i = wks.Columns(0).GetLabel(strLabel);

Summary:
Sample data:
Header file: wksheet.h
See also: SetLabel
Column::GetLabel
Prototype:
PUBLIC  string GetLabel()
Remarks: Get the column label if exist
Parameters:

Return values:

Example:
        Worksheet wks("data1");
        string str = wks.Columns(0).GetLabel();
        if(str.IsEmpty())
            out_str("Column 1 does not have label");

Summary:
Sample data:
Header file: wksheet.h
See also:


GetLastDependentColumnOffset

Column::GetLastDependentColumnOffset
Prototype:
PUBLIC  int GetLastDependentColumnOffset(DWORD dwCntrl)
Remarks: Get the index of the column in the same worksheet that is farthest away from this column and that is dependent on this column. Regarding modifiers: The index returned should be such that, if a column were to be inserted at that location in the worksheet, the distance between any column from the same worksheet that is plotted in some graph and any of its modifier columns used in conjunction with the same dataplot in that graph should not change. This could be rephrased like this: if a column plotted in some graph and all its modifiers associated with the same dataplot are considered as one range, then the index returned 1) should not break any such range in the worksheet, and 2) it should be to the right of the range containing the column through which the method call is made.
Parameters:
dwCntrl is a combination of the following cotrol bits:
typedef enum
{
DOO_LEFT		= 0x10000000,		// left offset
DOO_ERRORBAR	= 0x00010000,		// errorbars
DOO_MODIFIER	= 0x00020000,		// modifiers
DOO_TYPE_MASK	= 0x000F0000,		// type mask
}	DEPENDENTOBJOFFSET;

Return values:
Returns last dependent column offset if success, -1 if error.

Example:
        Worksheet wks = Project.ActiveLayer();
        Column colObj(wks, 0);
        int nOffset = colObj.GetLastDependentColumnOffset(DOO_ERRORBAR);

Summary:
Sample data:
Header file: wksheet.h
See also:


GetName

Column::GetName
Prototype:
PUBLIC  int GetName(string &strName)
Remarks: Get the column name
Parameters:
strName = reference to the string that will receive the name

Return values:
length of the name, 0 if none, -1 if error

Example:
        Worksheet wks("data1");
        string strName;
        int i = wks.Columns(0).GetName(strName);

Summary:
Sample data:
Header file: wksheet.h
See also: SetName
Column::GetName
Prototype:
PUBLIC  string GetName()
Remarks:
Parameters:

Return values:

Example:
    Worksheet wks("data1");
    foreach(Column cc in wks.Columns)
        printf("Column name is %s\n", cc.GetName());

Summary:
Sample data:
Header file: wksheet.h
See also:


GetNumRows

Column::GetNumRows
Prototype:
PUBLIC  int GetNumRows()
Remarks: Get the number of rows in a Column.
Parameters:

Return values:
Returns the number of rows in a Column.

Example:
        Worksheet wks("Data1");
        Column col(wks,0);
        int nRows = col.GetNumRows();

Summary: Get the number of rows in a Column.
Sample data:
Header file: wksheet.h
See also: SetNumRows


GetSubFormat

Column::GetSubFormat
Prototype:
PUBLIC  int GetSubFormat()
Remarks: Get the SubFormat used by a column - the list of available subformats varies for each column type. These are 'Formats' in the Worksheet Column dialog
Parameters:
None

Return values:
The subformat as an integer enumerated from 1

Example:
        Worksheet wks("data1");
        int iSubFormat = wks.Columns(0).GetSubFormat();

Summary:
Sample data:
Header file: wksheet.h
See also: SetSubFormat


GetTextMaxLen

Column::GetTextMaxLen
Prototype:
PUBLIC  int GetTextMaxLen()
Remarks: Get the text width of a column - this is the maximum number of characters that can be stored in a column. The default is 25, the maximum is 256. This is different than the display column width.
Parameters:
None

Return values:
The current Text Width of the column

Example:
        Worksheet wks("data1");
        int iTextMaxLen = wks.Columns(0).GetTextMaxLen();

Summary:
Sample data:
Header file: wksheet.h
See also: SetTextMaxLen


GetType

Column::GetType
Prototype:
PUBLIC  int GetType()
Remarks: Get the type designator of a column (Y, disregard, Y Err, X, Label, Z or X Err)
Parameters:
None

Return values:
The column type enum {OKDATAOBJ_DESIGNATION_Y = 0,
OKDATAOBJ_DESIGNATION_NONE,
OKDATAOBJ_DESIGNATION_ERROR,
OKDATAOBJ_DESIGNATION_X,
OKDATAOBJ_DESIGNATION_L,
OKDATAOBJ_DESIGNATION_Z,
OKDATAOBJ_DESIGNATION_X_ERROR};

Example:
        Worksheet wks("data1");
        int iType = wks.Columns(0).GetType();

Summary:
Sample data:
Header file: wksheet.h
See also:


GetWidth

Column::GetWidth
Prototype:
PUBLIC  int GetWidth()
Remarks: Get the display width of a column in number of characters
Parameters:
None

Return values:
The width in characters (approximate), exact only if the font is fixed width

Example:
        Worksheet wks("data1");
        out_int("col(1) width=", wks.Columns(0).GetWidth());

Summary:
Sample data:
Header file: wksheet.h
See also: SetWidth


IsWriteProtected

Column::IsWriteProtected
Prototype:
PUBLIC  BOOL IsWriteProtected()
Remarks:
Parameters:

Return values:
TRUE if column is write protected. FALSE otherwise
See Also:

Example:

Summary:
Sample data:
Header file: wksheet.h
See also: IsWriteProtected(int nBegin = 0; int nEnd = -1)


SetDigitMode

Column::SetDigitMode
Prototype:
PUBLIC  BOOL SetDigitMode(int iDigitMode)
Remarks: Sets the display mode used for numbers in a column
Parameters:
iDigitMode = The ColDigitMode - enum {
DIGITS_FREE_FORM,
DIGITS_DECIMAL,
DIGITS_SIGNIFICANT
}

Return values:
TRUE, set the digitmode successfully, FALSE, unsuccessful.

Example:
        Worksheet wks("data1");
        BOOL b = wks.Columns(0).SetDigitMode(DIGITS_FREE_FORM);

Summary:
Sample data:
Header file: wksheet.h
See also: GetDigitMode GetDigits SetDigits


SetDigits

Column::SetDigits
Prototype:
PUBLIC  BOOL SetDigits(int iDigits)
Remarks: Set the digit value for the numeric display mode
Parameters:
iDigits = the number of digits

Return values:
TRUE, set the digits successfully, FALSE, unsuccessful.

Example:
        Worksheet wks("data1");
        BOOL b = wks.Columns(0).SetDigits(10);

Summary:
Sample data:
Header file: wksheet.h
See also: GetDigitMode SetDigitMode GetDigits


SetFormat

Column::SetFormat
Prototype:
PUBLIC  BOOL SetFormat(int iFormat)
Remarks: Set the column format
Parameters:
iFormat = the column format,enum {
OKCOLTYPE_NUMERIC,
OKCOLTYPE_TEXT,
OKCOLTYPE_TIME,
OKCOLTYPE_DATE,
OKCOLTYPE_MONTH,
OKCOLTYPE_WEEKDAY,
OKCOLTYPE_TEXT_NUMERIC}

Return values:
TRUE, set the coloumn format successfully, FALSE, unsuccessful.

Example:
        Worksheet wks("data1");
        BOOL b = wks.Columns(0).SetFormat(OKCOLTYPE_NUMERIC);

Summary:
Sample data:
Header file: wksheet.h
See also: GetFormat


SetFormula

Column::SetFormula
Prototype:
PUBLIC  BOOL SetFormula(LPCSTR lpcszFormula)
Remarks: Set the column formula
Parameters:
lpcszFormula = the formula

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        Worksheet wks = Project.ActiveLayer();
        Column colObj(wks, 0);
        colObj.SetFormula("col(B)*2");

Summary:
Sample data:
Header file: wksheet.h
See also:


SetInternalData

Column::SetInternalData
Prototype:
PUBLIC  BOOL SetInternalData(UINT iType)
Remarks: Set the column internal data types (This is a characteristic of numeric column format). If you are not sure the column is in numeric format, call SetFormat first.
Parameters:
iType = the internal type of a column enum{
FSI_DOUBLE = 0,
FSI_REAL,
FSI_SHORT,
FSI_LONG };

Return values:
TRUE, set the column internal type successfully, FALSE, unsuccessful.

Example:
        // this example set all columns in current worksheet to short integers
        Worksheet wks = Project.ActiveLayer();
        if(!wks)
            return;
        foreach(Column col in wks.Columns)
        {
            col.SetFormat(OKCOLTYPE_NUMERIC);
            if(!col.SetInternalData(FSI_SHORT))
                out_str("set short int error");
        }

Summary:
Sample data:
Header file: wksheet.h
See also: GetInternalData


SetJustify

Column::SetJustify
Prototype:
PUBLIC  BOOL SetJustify(int iJustify)
Remarks: Set the column justification
Parameters:
iJustify = enum{
COL_JUSTIFY_LEFT = 1,
COL_JUSTIFY_RIGHT,
COL_JUSTIFY_CENTER }

Return values:
TRUE, set the column justify successfully, FALSE, unsuccessful.

Example:
        Worksheet wks("data1");
        BOOL bResult = wks.Columns(0).SetJustify(COL_JUSTIFY_CENTER);

Summary:
Sample data:
Header file: wksheet.h
See also: GetJustify


SetLabel

Column::SetLabel
Prototype:
PUBLIC  BOOL SetLabel(LPCSTR lpcstrLabel)
Remarks: Set the column label
Parameters:
lpcstrLabel = pointer to a null-terminated string to be used as the
column label

Return values:
TRUE, set the column label successfully. FALSE, unsuccessful.
The error may simply be that Origin modified the name which is now in
strColLabel.
Any more disastrous error should set the string to null.

Example:
        Worksheet wks("data1");
        string strLabel = "Elapsed\n(in sec.)";
        BOOL b = wks.Columns(0).SetLabel(strLabel);

Summary:
Sample data:
Header file: wksheet.h
See also: GetLabel


SetLowerBound

Column::SetLowerBound
Prototype:
PUBLIC  BOOL SetLowerBound( int iR1 )
Remarks: Set the begining row indices for this column.
Parameters:
iR1=Input begining row index (0 based)

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        Worksheet wks = Project.ActiveLayer();
        Column colObj(wks, 0);

        int nR1 = 5;
        colObj.SetLowerBound(nR1);

Summary:
Sample data:
Header file: wksheet.h
See also:


SetName

Column::SetName
Prototype:
PUBLIC  BOOL SetName(LPCSTR lpcstrName)
Remarks: Set the column name
Parameters:
lpcstrName = pointer to a null-terminated string to be used as the column
name

Return values:
TRUE, set the column name successfully, FALSE, unsuccessful.
the error may simply be that Origin modified the name which is now in
strColName any more disastrous error should set the string to null

Example:
        Worksheet wks("data1");
        string strName = "A";
        BOOL b = wks.Columns(0).SetName(strName);

Summary:
Sample data:
Header file: wksheet.h
See also: GetName


SetNumRows

Column::SetNumRows
Prototype:
PUBLIC  BOOL SetNumRows(int nRows)
Remarks: Set the number of rows in a Column.
Parameters:
nRows=Input number of rows to set, nRows must larger than 0.

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
        Worksheet wks("Data1");
        Column col(wks,0);
        col.SetNumRows(50);  // set column size to 50
        Dataset ds(wks,0);   // attach it to dataset ds
        ds.SetSize(20);      // Set data range to 20;
        int ii=ds.GetSize();
        ASSERT( ii == 20);
        ii = col.GetNumRows();
        ASSERT( ii == 50);
        col.SetNumRows(10);  // Set column size to 10, as it is small than data range, so data rang changed here too
        wks.UpdateOrigin();  // update change to worksheet in origin
        ds.Update(TRUE);	 // update Origin C object ds
        ii=ds.GetSize();
        ASSERT(ii==10);

Summary: Set the number of rows in a Column.
Sample data:
Header file: wksheet.h
See also: GetNumRows SetSize


SetSubFormat

Column::SetSubFormat
Prototype:
PUBLIC  BOOL SetSubFormat(int iSubFormat)
Remarks: Set the SubFormat used by a column
Parameters:
iSubFormat = The integer (enumerated from one) of the subformat for the current column
type

Return values:
TRUE, set the column subformat successfully, FALSE, unsuccessful.
an error occurs when a subformat is out of range for example, any value
for a Text column, a value greater than 21 for a Date column

Example:
        Worksheet wks("data1");
        // We will assume the first column is a Date column
        BOOL b = wks.Columns(0).SetSubFormat(13); // The 13th subformat is yyMMdd HH:mm

Summary:
Sample data:
Header file: wksheet.h
See also: GetSubFormat


SetTextMaxLen

Column::SetTextMaxLen
Prototype:
PUBLIC  BOOL SetTextMaxLen(int iTWidth)
Remarks: Set the text width of a column
Parameters:
iTWidth = the text width in characters

Return values:
TRUE, set the column width successfully, FALSE, unsuccessful.

Example:
        Worksheet wks("data1");
        BOOL b = wks.Columns(0).SetTextMaxLen(50);

Summary: Set the text width of the column
Sample data:
Header file: wksheet.h
See also: GetTextMaxLen


SetType

Column::SetType
Prototype:
PUBLIC  BOOL SetType(int iType)
Remarks: Set the type designator of a column (Y, disregard, Y Err, X, Label, Z or X Err)
Parameters:
iType = the column type enum {OKDATAOBJ_DESIGNATION_Y = 0,
OKDATAOBJ_DESIGNATION_NONE,
OKDATAOBJ_DESIGNATION_ERROR,
OKDATAOBJ_DESIGNATION_X,
OKDATAOBJ_DESIGNATION_L,
OKDATAOBJ_DESIGNATION_Z,
OKDATAOBJ_DESIGNATION_X_ERROR};

Return values:
TRUE, set the column type  successfully, FALSE, unsuccessful.

Example:
        Worksheet wks("data1");
        BOOL b = wks.Columns(0).SetType(OKDATAOBJ_DESIGNATION_X);

Summary:
Sample data:
Header file: wksheet.h
See also: GetType


SetUpperBound

Column::SetUpperBound
Prototype:
PUBLIC  BOOL SetUpperBound( int iR2 )
Remarks: Set the ending row indices for this column. Index values are 0 based offsets so use SetUpperBound(-1) to dispaly no rows.
Parameters:
iR2=Input ending row index (0 based)

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        Worksheet wks = Project.ActiveLayer();
        Column colObj(wks, 0);
        int nR2 = 25;
        colObj.SetUpperBound(nR2);

Summary:
Sample data:
Header file: wksheet.h
See also:


SetWidth

Column::SetWidth
Prototype:
PUBLIC  BOOL SetWidth(int iWidth = -1)
Remarks: Set the display column width of a column in number of characters
Parameters:
iWidth = the width in characters (approximate), exact only if the font is fixed width
use -1 to set the width to the largest cell in the column

Return values:
TRUE, set the digitmode successfully, FALSE, unsuccessful.

Example:
        Worksheet wks("data1");
        int iWidth = 3;
        BOOL b = wks.Columns(0).SetWidth(iWidth);
        out_int("col(1) width set to be very small, ", wks.Columns(0).GetWidth());
        MessageBox(NULL, "Wait...");
        wks.Columns(0).SetWidth();
        out_str("col(1) width reset to show all data");

Summary:
Sample data:
Header file: wksheet.h
See also: GetWidth


DataObject

Class: DataObject

Description: The DataObject class is derived from the DataObjectBase class and is the base class of worksheet columns and matrix objects. Origin data objects are contained by layers on an Origin page. For example, columns (data objects) are contained by a worksheet (layer) and are on a worksheet window (page).

Hierarchy:

OriginObject
 DataObjectBase
 DataObject

Sample:


DataObject

DataObject::DataObject
Prototype:
PUBLIC  DataObject()
Remarks: Default constructor for DataObject class.
Parameters:

Return values:

Example:

Summary: Default constructor for DataObject class.
Sample data:
Header file: graph.h
See also:


DataObjectBase

Class: DataObjectBase

Description: The DataObjectBase class provides methods and properties common to all data objects. The Origin C DataObjectBase class is an abstract base class used for polymorphic handling of DataObject and DataPlot related class types. Consequently, Origin C objects of type DataObjectBase can not be constructed. Derived classes such as DataObject, Column, MatrixObject, and DataPlot inherit DataObjectBase class methods and should be used instead.

Hierarchy:

OriginObject
 DataObjectBase

Sample:


GetCategoricalMap

DataObjectBase::GetCategoricalMap
Prototype:
PUBLIC  CategoricalMap GetCategoricalMap()
Remarks: Retrieves categorical map from DataObject
Parameters:

Return values:

Example:
        Column col("Data1", 0);
        if( col )
        {
            CategoricalMap cm = col.GetCategrocalMap();
            if( cm )
            {
                int nCatValue = cm.LookUp("key1");
            }
        }

Summary:
Sample data:
Header file: graph.h
See also:


GetDatasetName

DataObjectBase::GetDatasetName
Prototype:
PUBLIC  string GetDatasetName()
Remarks: A DataObjectBase object is always associated with a dataset inside Origin. Since Dataset is a template class, we use the name as the common mean of connecting to a Dataset
Parameters:

Return values:

Example:
        // list all the dataset names in the current graph layers
        GraphLayer gl = Project.ActiveLayer();
        if(!gl)
            return;
        int index = 1;
        foreach(DataPlot dp in gl.DataPlots)
        {
            printf("%3.0d:%s\n", index++, dp.GetDatasetName());
        }

Summary:
Sample data:
Header file: graph.h
See also:


GetRange

DataObjectBase::GetRange
Prototype:
PUBLIC  BOOL GetRange(int &i1, int &i2)
Remarks: it retrieves the data (display) range for the object
Parameters:
i1 = lower boundary of the range passed by reference to receive the result
i2 = upper boundary of the range passed by reference to receive the result

Return values:
TRUE for success, FALSE for failure.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the graph has at least one data plot.
        void	run_GetRange()
        {
            // Create and attach a graph layer from "Graph1":
            GraphLayer		gl("Graph1");

            // Get the first data plot in the layer:
            DataPlot		dp = gl.DataPlots(0);
            int				i1, i2;

            dp.GetRange(i1, i2);

            printf("Data plot range: i1 = %d   i2 = %d\n", i1, i2);
        }

Summary:
Sample data:
Header file: graph.h
See also:


SetRange

DataObjectBase::SetRange
Prototype:
PUBLIC  BOOL SetRange(int i1 = 0, int i2=-1, BOOL bRepaint=TRUE)
Remarks: It sets the data (display) range for the object. Not that this range can be smaller than the total range of data of the underlying dataset if not all data values are shown. For example, in case of a data plot in a graph, some data points may not have been plotted.
Parameters:
i1 = the lower bound of the desired range, zero offset
i2 = the upper bound of the desired range (-1 to use full dataset range). This is the index immediately after the last data point to be drawn
bRepaint = TRUE to repaint the object after changing the range, FALSE not to repaint.

Return values:
TRUE for success, FALSE for failure.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the graph has at least one data plot and that there are at least ten
        // data points in the plot.
        // After the function executes, the data plot will show
        // only the data points from 5 to 10.
        void	run_SetRange()
        {
            // Create and attach a graph layer from "Graph1":
            GraphLayer		gl("Graph1");

            // Get the first data plot in the layer:
            DataPlot		dp = gl.DataPlots(0);

            // Change the display range of the data plot to
            // show only points from 5 to 10: (1 offset)
            dp.SetRange(4, 10);
        }

Summary: i2=-1 to indicate the full range at the end
Sample data:
Header file: graph.h
See also:


DataPlot

Class: DataPlot

Description: The DataPlot class provides methods and properties common to all Origin data plots. An internal Origin data plot object is used to store the plot characteristics of an Origin data plot. It is contained in a graph layer on a graph page. An Origin C DataPlot object is a wrapper object that is a reference to an internal Origin data plot object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The DataPlot class is derived from the DataObjectBase and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 DataObjectBase
 DataPlot

Sample:

        // Assumes Graph1 window with one or more data plots is active in Origin
        GraphLayer	gl = Project.ActiveLayer(); // Get active layer in project file
        if(gl)                                  // If valid graph layer...
        {
            DataPlot dp = gl.DataPlots(0);      // Get first data plot in graph layer
            dp.SetColor(2);                     // Change color to green
        }


DataPlot

DataPlot::DataPlot
Prototype:
PUBLIC  DataPlot()
Remarks: Default constructor which constructs an uninitialized (unattached) DataPlot. The object cannot be used until it is initialized.
Parameters:
None.

Return values:

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the graph has at least one data plot.
        // The example shows how to initialize an uninitialized DataPlot object.
        void	run_DataPlot_Constructor()
        {
            // Create and attach a graph layer from "Graph1":
            GraphLayer		gl("Graph1");

            // Use default constructor to create an uninitialized DataPlot.
            DataPlot		dp;

            // Now initialize it to be the first DataPlot in the layer:
            dp = gl.DataPlots(0);

            // Displaye a property:
            printf("Data plot range: i2 = %d\n", dp.i2);
        }

Summary:
Sample data:
Header file: graph.h
See also:
DataPlot::DataPlot
Prototype:
PUBLIC  DataPlot(DataPlot &dp)
Remarks: Copy constructor which constructs a DataPlot object from another DataPlot object.
Parameters:
dp = the source DataPlot object.

Return values:

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the graph has at least one data plot.
        void	run_DataPlot_Constructor()
        {
            // Create and attach a graph layer from "Graph1":
            GraphLayer		gl("Graph1");

            // Use copy constructor to create a DataPlot from an existing DataPlot object.
            DataPlot		dp(gl.DataPlots(0));

            // Displaye a property:
            printf("Data plot range: i2 = %d\n", dp.i2);
        }

Summary:
Sample data:
Header file: graph.h
See also:


GetColormap

DataPlot::GetColormap
Prototype:
PUBLIC  BOOL GetColormap(TreeNode& trColormap)
Remarks: Gets the colormap properties of the dataplot (applies to dataplot with colormaps, like contour plot)
Parameters:
trColormap[Out] : A TreeNode object with the Tree structure of GetColormap

Return values:
The BOOL returned is TRUE for success and FALSE for failure.

Example:
        // For this example to run, you need a contour graph
        void test_Get_Colormap(string str)
        {
            GraphPage gp(str);
               GraphLayer glay = gp.Layers();
               DataPlot dp = glay.DataPlots(0);
               vector vZs;
               BOOL bLogScale = FALSE;;
            BOOL bRet = dp.GetColormap(vZs, bLogScale);
            Tree tr;
            BOOL bRetT = dp.GetColormap(tr);
        }
        //The following function shows how to Show/hide contour lines
        //Currently there is no support to  show/hide for the line above
        BOOL HideLines(int nShow)
        {

            GraphPage gp("graph1");
           if(!gp.IsValid() )
               return FALSE;
           // Get graph layer from collection in graph page
           GraphLayer gl = gp.Layers();
           if(!gl.IsValid() )
               return FALSE;
           // Get data plot from collection in graph layer
           DataPlot dp = gl.DataPlots(0);
           if( !dp.IsValid() )
               return FALSE;

           TreeNode tr;
           dp.GetColormap(tr);
           vector<int> vLShow;
           vLShow = tr.Details.ShowLines.nVals;
           vLShow = nShow;
           tr.Details.Remove();
           tr.Details.ShowLines.nVals  =vLShow;
            dp.SetColormap(tr);
            return TRUE;

        }

Summary:
Sample data:
Header file: graph.h
See also:
DataPlot::GetColormap
Prototype:
PUBLIC  BOOL GetColormap(vector<double>& vz, BOOL& bLogScale)
Remarks: Gets the z-levels for of colormap of the dataplot (applies to dataplot with colormaps, like contour plot)
Parameters:
vz[Out]			: A Vector of Doubles giving the Z-level values
bLogScale[Out]	: bLogScale, TRUE means Logarithmic, FALSE for linear

Return values:
The BOOL returned is TRUE for success and FALSE for failure.

Example:
        // For this example to run, you need a contour graph
        void test_Get_Colormap(string str)
        {
            GraphPage gp(str);
               GraphLayer glay = gp.Layers();
               DataPlot dp = glay.DataPlots(0);
               vector vZs;
               BOOL bLogScale = FALSE;;
            BOOL bRet = dp.GetColormap(vZs, bLogScale);
            Tree tr;
            BOOL bRetT = dp.GetColormap(tr);
        }

Summary:
Sample data:
Header file: graph.h
See also:


SetColor

DataPlot::SetColor
Prototype:
PUBLIC  BOOL SetColor(int nColor, BOOL bRepaint = FALSE)
Remarks: set the color of the dataplot (line, symbol).
Parameters:
nColor = the color index in the Origin palette (typically it is 0 - black, 1 - red, etc.)
bRepaint = TRUE to cause graph repaint, FALSE not to repaint.

Return values:

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the graph has at least one scatter data plot.
        void	run_DataPlot_SetColor()
        {
            // Create and attach a graph layer from "Graph1":
            GraphLayer		gl("Graph1");

            // Get the first data plot in the layer:
            DataPlot		dp = gl.DataPlots(0);

            // Set the color to red and repaint:
            dp.SetColor(1, TRUE);
        }

Summary:
Sample data:
Header file: graph.h
See also:


SetColormap

DataPlot::SetColormap
Prototype:
PUBLIC  BOOL SetColormap(TreeNode& trColormap)
Remarks: Sets the colormap properties of the dataplot (applies to dataplot with colormaps, like contour plot) The input TreeNode does not have to contain child nodes for all properties of colormap, only for those intended to be set, the properties for which nodes are no found will remain un-altered unless the alterd properties forces some others to be altered.
Parameters:
trColormap[in] : A TreeNode object with the Tree structure similar to the One obtained from GetColormap

Return values:
The BOOL returned is TRUE for success and FALSE for failure.

Example:
        // For this example to run, you need a contour graph
        void test_Set_Colormap(string str, int nCount = 0)
        {
            GraphPage gp(str);
               GraphLayer glay = gp.Layers();
               DataPlot dp = glay.DataPlots(0);
               vector vZs = {1,5.5,10};
            BOOL bRet;
            if(nCount)
            {
                Tree tr;
                tr.ColorMap.Count.nVal = nCount;
                bRet = dp.SetColormap(tr);

            }
            else
            {
                bRet = dp.SetColormap(vZs, false);
            }

        }

Summary:
Sample data:
Header file: graph.h
See also:
DataPlot::SetColormap
Prototype:
PUBLIC  BOOL SetColormap(const vector<double>& vz, BOOL bLogScale=FALSE)
Remarks: Set the Z levels for the colormap inside the data plot (applies to dataplot with colormaps, like contour plot) The 1st value in vz is the minimum Z value and the last value in vz the maximum, so vz must at least contain 2 values.
Parameters:
vz[in]			: A Vector of Doubles, specifying the the z-level values to be set
bLogScale[im]	: bLogScale, TRUE will set the colormap levels scale to Logarithmic, FALSE for linear

Return values:
The BOOL returned is TRUE for success and FALSE for failure.

Example:
        // For this example to run, you need a contour graph
        void test_Set_Colormap(string str, int nCount = 0)
        {
            GraphPage gp(str);
               GraphLayer glay = gp.Layers();
               DataPlot dp = glay.DataPlots(0);
               vector vZs = {1,5.5,10};
            BOOL bRet;
            if(nCount)
            {
                Tree tr;
                tr.ColorMap.Count.nVal = nCount;
                bRet = dp.SetColormap(tr);

            }
            else
            {
                bRet = dp.SetColormap(vZs, false);
            }

        }

Summary:
Sample data:
Header file: graph.h
See also:


SetColorRGB

DataPlot::SetColorRGB
Prototype:
PUBLIC  BOOL SetColorRGB(BYTE byRed, BYTE byGreen, BYTE byBlue, BOOL bRepaint = FALSE)
Remarks: set the color of the dataplot (line, symbol) by the intensities of red, green, and blue colors
Parameters:
byRed =	the intensity of red
byGreen = the intensity of green
byBlue = the intensity of blue
bRepaint = TRUE to cause graph repaint, FALSE not to repaint.

Return values:

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the graph has at least one scatter data plot.
        void	run_DataPlot_SetColor()
        {
            // Create and attach a graph layer from "Graph1":
            GraphLayer		gl("Graph1");

            // Get the first data plot in the layer:
            DataPlot		dp = gl.DataPlots(0);

            // Set the color to green and repaint:
            dp.SetColorRGB(0x00, 0xFF, 0x00, TRUE);
        }

Summary:
Sample data:
Header file: graph.h
See also:


Datasheet

Class: Datasheet

Description: The Datasheet class provides methods and properties common to Origin worksheet and matrix layers. The Datasheet class is derived from the Layer and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 Layer
 Datasheet

Sample:


Create

Datasheet::Create
Prototype:
PUBLIC  BOOL Create(LPCSTR lpcszTemplate = NULL, int nOption = CREATE_VISIBLE)
Remarks: Create a new worksheet or matrix using the supplied template and attach it to the object.
Parameters:
lpcszTemplate = the template file name, "" or NULL to use a default template.
"0" to create without template
nOption = enum {
CREATE_TEMP = 0,	// it will be destroyed when destroying the object
// (when it exits the scope) and is created invisible
CREATE_VISIBLE_SAME,// visibility is that which is stored in the template
// (does not apply if template not supplied)
CREATE_VISIBLE,
CREATE_HIDDEN,};

Return values:
TRUE for success, otherwise FALSE.

Example:
        Worksheet	wks;
        BOOL		bRet = wks.Create("c:\\mytemplate.otw", CREATE_VISIBLE_SAME);

        Worksheet	newWks;
        if(newWks.Create())
            printf("New wks(%s) is created\n",newWks.GetPage().GetName());

        Worksheet	TempWks;
        if(TempWks.Create(NULL,CREATE_HIDDEN))
            printf("New hidden wks(%s) is created\n",TempWks.GetPage().GetName());

        MatrixLayer mat; // change to MatrixLayer for Matrix
        if(mat.Create(NULL,CREATE_HIDDEN))
            printf("Hidden matrix %s of %d x %d is created\n",
                mat.GetPage().GetName(), mat.GetNumCols(), mat.GetNumRows());

Summary:
Sample data:
Header file: wksheet.h
See also: CreateCopy


Datasheet

Datasheet::Datasheet
Prototype:
PUBLIC  Datasheet()
Remarks: Default constructor.
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: wksheet.h
See also:


GetName

Datasheet::GetName
Prototype:
PUBLIC  BOOL GetName(string &str)
Remarks: Retrieves the name of the worksheet. This function is useful only for Excel workbooks where one workbook can have multiple sheets, each with its own name.
Parameters:

Return values:
The TRUE for succes, FALSE if failed.

Example:
        Page		pg("Book1");
        Layer		lay= pg.Layers();		// gets the active worksheet from Excel
        Worksheet	wks;
        wks = (Worksheet)lay;
        if (wks)
        {
            string	strName;
            wks.GetName(strName);
            out_str(strName);
        }

Summary:
Sample data:
Header file: wksheet.h
See also:


GetNumCols

Datasheet::GetNumCols
Prototype:
PUBLIC  UINT GetNumCols()
Remarks: Get the number of columns in a Datasheet including MatixLayers and Worksheets.
Parameters:

Return values:
Returns the number of columns in the Datasheet including MatixLayers and Worksheets.

Example:
        Worksheet wks("Data1");
        int nCols = wks.GetNumCols();

Summary: Get the number of columns in the Datasheet.
Sample data:
Header file: wksheet.h
See also: GetNumRows SetNumRows


GetNumRows

Datasheet::GetNumRows
Prototype:
PUBLIC  UINT GetNumRows()
Remarks: Get the number of rows in a Datasheet including MatixLayers and Worksheets.
Parameters:

Return values:
Returns the number of rows in the Datasheet including MatixLayers and Worksheets.

Example:
        Worksheet wks("Data1");
        int nRows = wks.GetNumRows();

Summary: Get the number of rows in the Datasheet.
Sample data:
Header file: wksheet.h
See also: GetNumCols SetNumRows


SetNumRows

Datasheet::SetNumRows
Prototype:
PUBLIC  BOOL SetNumRows(uint nRows)
Remarks: Set the number of rows in a Datasheet including MatixLayers and Worksheets.
Parameters:
nRows=Input number of rows to set

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
        MatrixLayer ml("Matrix1");
        ml.SetNumRows(50);

Summary: Set the number of rows in a Datasheet.
Sample data:
Header file: wksheet.h
See also: GetNumRows GetNumCols


Folder

Class: Folder

Description: Project Explorer is a Windows Explorer like user interface inside Origin. It contains a folder/sub-folder structure used to organize and facilitate access to the graph, layout, matrix, note, and worksheet windows of an Origin project file. The Folder class is used to access the methods and properties of Project Explorer and contains collections of all Origin pages and Project Explorer folders. An Origin C Folder object is a wrapper object that is a reference to an internal Origin project explorer object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object.

Hierarchy:

Folder

Sample:

        // List all page names in first level subfolders of root folder
        Folder fld, fldSub;
        fld = Application.RootFolder;
        PageBase pb;

        foreach(fldSub in fld.Subfolders)
        {
            // Display the name of the current subfolder
            printf( "Folder name = %s\n", fldSub.GetName() );
            foreach(pb in fldSub.Pages)
            {
                // Display the name of the page:
                printf( "\tPage name = %s\n", pb.GetName() );
            }
        }


Activate

Folder::Activate
Prototype:
PUBLIC  BOOL Activate()
Remarks: Set the project's current folder.
Parameters:

Return values:

Example:
        Folder fld = Application.ActiveFolder();
        Folder subfld = fld.AddSubfolder("MyFolder");
        subfld.Activate();

Summary:
Sample data:
Header file: folder.h
See also:


AddSubfolder

Folder::AddSubfolder
Prototype:
PUBLIC  Folder AddSubfolder(LPCSTR lpcszSubFolderName)
Remarks: Create a subfolder with the name specified in lpcszSubFolderName.
Parameters:

Return values:

Example:
        Folder fld = Application.RootFolder;
        fld.AddSubfolder("MyFolder");

Summary:
Sample data:
Header file: folder.h
See also:


Attach

Folder::Attach
Prototype:
PUBLIC  Attach(LPCSTR lpcszPathName)
Remarks: Attach the folder object to a folder.
Parameters:

Return values:

Example:
        Folder fld;
        fld.Attach("/");  // attached to root folder

Summary:
Sample data:
Header file: folder.h
See also:


Folder

Folder::Folder
Prototype:
PUBLIC  Folder()
Remarks:
Parameters:

Return values:

Example:
        This example constructs a folder, and adds a subfolder named MyFolder.
        void run_Folder()
        {
            Folder fldRoot;
            fldRoot = Application.RootFolder;
            fldRoot.AddSubfolder("MyFolder");
        }

Summary:
Sample data:
Header file: folder.h
See also:
Folder::Folder
Prototype:
PUBLIC  Folder(Folder &folder)
Remarks: Copy constructor.
Parameters:

Return values:

Example:
        This example illustrates how to copy a constructor. Folder fldRoot and fldRootpp both refer to the root.
        void run_Folder()
        {
            Folder fldRoot;
            fldRoot = Application.RootFolder;
            fldRoot.AddSubfolder("MyFolder1");
            fldRoot.AddSubfolder("MyFolder2");

            Folder fldRootpp(fldRoot);
            fldRootpp.RemoveSubFolder("MyFolder2");
        }

Summary:
Sample data:
Header file: folder.h
See also:
Folder::Folder
Prototype:
PUBLIC  Folder(LPCSTR lpcszPathName)
Remarks: Construct a Folder object by pathname.
Parameters:

Return values:

Example:
        void run_Folder()
        {
            Folder fldRoot("/");
            fldRoot.AddSubfolder("MyFolder");

            Folder fldMyFolder("/MyFolder");
            fldMyFolder.AddSubfolder("MySubFolder");
        }

Summary:
Sample data:
Header file: folder.h
See also:


GetFolder

Folder::GetFolder
Prototype:
PUBLIC  Folder GetFolder(LPCSTR strPathName)
Remarks: Can use relative and absolute way to Get a Folder, the name is no case sensitive.
Parameters:

Return values:

Example:
        "/ttt", use absolute way, the project can be omitted by this way.
        "../ttt", use relative way, it find folder name is "ttt" from current folder's parents' folder.

        void test_Folder_GetFolder()
        {
            Folder fldRoot("/");
            fldRoot.AddSubfolder("MyFolder1");
            Folder fldMyFolder1("/MyFolder1");
            fldRoot.AddSubfolder("MyFolder2");
            Folder fldMyFolder2("/MyFolder2");

            Folder fldCurr = fldRoot.GetFolder("/MyFolder1");
            string strCurrName = fldCurr.GetName();
            printf("The current folder is %s\n", strCurrName);

            fldCurr = fldMyFolder1.GetFolder("../MyFolder2");
            strCurrName = fldCurr.GetName();
            printf("The current folder is %s", strCurrName);
        }

Summary:
Sample data:
Header file: folder.h
See also:


GetName

Folder::GetName
Prototype:
PUBLIC  string GetName()
Remarks: Get the name of the folder.
Parameters:

Return values:

Example:
        void test_Folder_GetName()
        {
            Folder fldRoot("/");
            fldRoot.AddSubfolder("MyFolder");
            Folder fldMyFolder("/MyFolder");

            string strCurrFld = fldMyFolder.GetName();
            printf("The current folder is \"%s\"", strCurrFld);
        }

Summary:
Sample data:
Header file: folder.h
See also:
Folder::GetName
Prototype:
PUBLIC  BOOL GetName(string &strName)
Remarks: Get the name of the folder.
Parameters:

Return values:

Example:
        Folder fld = Application.ActiveFolder();
        string strName;
        if( fld.GetName(strName) )
            printf("Current folder is: %s", strName);

Summary: return FALSE if folder is not valid
Sample data:
Header file: folder.h
See also:


GetParent

Folder::GetParent
Prototype:
PUBLIC  Folder GetParent()
Remarks: Get the folder's parent folder.
Parameters:

Return values:

Example:
        Folder fld = Application.ActiveFolder();
        Folder parentFld = fld.GetParent();
        if( parentFld.IsValid() )
            printf("The parent of Current folder is: %s", parentFld.GetName());

Summary:
Sample data:
Header file: folder.h
See also:


GetPath

Folder::GetPath
Prototype:
PUBLIC  string GetPath()
Remarks: Get the full path of the folder.
Parameters:

Return values:

Example:
        Folder fld = Application.ActiveFolder();
        printf("The path of Current folder is: %s", fld.GetPath());

Summary: Return full path of this folder
Sample data:
Header file: folder.h
See also:


IsRootFolder

Folder::IsRootFolder
Prototype:
PUBLIC  BOOL IsRootFolder()
Remarks: Check if the folder is the root folder.
Parameters:

Return values:

Example:
        Folder fld = Application.RootFolder;
        if( fld.IsRootFolder() )
            printf("Folder is root folder.");

Summary:
Sample data:
Header file: folder.h
See also:


IsValid

Folder::IsValid
Prototype:
PUBLIC  BOOL IsValid()
Remarks: Check if the folder object is valid. Must be used after creating a new folder object.
Parameters:

Return values:

Example:
        void test_Folder_IsValid()
        {
            Folder fldRoot("/");
            fldRoot.AddSubfolder("MyFolder");
            Folder fldMyFolder("/MyFolder");

            if (fldRoot.IsValid())
                printf("The rootfolder is valid.\n");
            if (fldMyFolder.IsValid())
                printf("The subfolder is valid.\n");
        }

Summary:
Sample data:
Header file: folder.h
See also: GetParent


Move

Folder::Move
Prototype:
PUBLIC  BOOL Move(LPCSTR lpcszItemName, LPCSTR lpcszPathName)
Remarks: Move an item from the current folder to another folder whose path name is lpcszPathName.
Parameters:

Return values:

Example:
        // Assume there is a window named "data1" and susbfolders named "sub1" and "sub2" under the root folder.
        Folder root = Application.RootFolder;
        if( !root.Move("data1", "/sub1/") ) // move window "data1" to folder "sub1".
            printf("Can't move this window!");
        if( !root.Move("sub2", "/sub1/") ) // move subfolder "sub2" to folder "sub1".
            printf("Can't move this subfolder!");

Summary:
Sample data:
Header file: folder.h
See also:


Pages

Folder::Pages
Prototype:
PUBLIC  PageBase Pages(int nIndex)
Remarks: Get a page by index. First page has index of zero.
Parameters:

Return values:

Example:
        Folder fld = Application.RootFolder;
        Page pg = fld.Pages(0);
        if(pg.IsValid())
        {
            out_str("The name of the first page is : " + pg.GetName());
        }

Summary:
Sample data:
Header file: folder.h
See also:
Folder::Pages
Prototype:
PUBLIC  PageBase Pages(LPCSTR lpcszName)
Remarks:
Parameters:

Return values:
Get a page by name.

Example:
        Folder fld = Application.RootFolder;
        Page pg = fld.Pages("Data1");

Summary:
Sample data:
Header file: folder.h
See also:


RemoveSubFolder

Folder::RemoveSubFolder
Prototype:
PUBLIC  BOOL RemoveSubFolder(LPCSTR lpcszSubFolderName, BOOL bFolderPrompt = FALSE , BOOL bPagePrompt = FALSE)
Remarks: Remove the subfolder with the name specified in lpcszSubFolderName. If bFolderPrompt or bPagePrompt is TRUE then Origin will prompt the user to verify.
Parameters:

Return values:

Example:
        Folder fld = Application.RootFolder;
        Folder subfld;
        foreach (subfld in fld.Subfolders)
        {
            fld.RemoveSubFolder(subfld.GetName());
        }

Summary:
Sample data:
Header file: folder.h
See also:


Rename

Folder::Rename
Prototype:
PUBLIC  BOOL Rename(LPCSTR strName)
Remarks: Rename the folder. If the new folder name is used by a sibling folder then this function will return FALSE.
Parameters:

Return values:

Example:
        Folder fld = Application.ActiveFolder();
        fld.Rename("Example");
        string strName = fld.GetName();
        printf("Folder renamed to %s\n", strName);

Summary:
Sample data:
Header file: folder.h
See also:


SaveAsProject

Folder::SaveAsProject
Prototype:
PUBLIC  BOOL SaveAsProject(LPCSTR lpcszPath, DWORD dwCntrl = SFC_INCLUDE_SUBFOLDERS)
Remarks: Save folder as project
Parameters:
lpcszPath = specify the path
dwCntrl = additional flags to control the saving
may include one or more of the following bits defined in OC_const.h
SFC_INCLUDE_SUBFOLDERS 		- specifies if subfolders must be saved to project
SFC_INCLUDE_ATTACHED_FILES  - specifies if attached OC files must be saved to project

Return values:
TRUE if successful. FALSE otherwise

Example:
        void Sample_SaveAsProject()
        {
            Folder fldSave = Application.ActiveFolder();
            string strPath = GetAppPath(1) + "OriginC\\abc";
            bool bOK = fldSave.SaveAsProject(strPath);
            out_int("bOK = ", bOK);
        }

Summary:
Sample data:
Header file: folder.h
See also:


Subfolders

Folder::Subfolders
Prototype:
PUBLIC  Folder Subfolders(int nIndex)
Remarks: Get a folder by index. First folder has index of zero.
Parameters:

Return values:

Example:
        Folder fld = Application.RootFolder;
        Folder subfld = fld.Subfolders(0);
        if(subfld.IsValid())
        {
            out_str("The name of the subfolder is : " + subfld.GetName());
        }

Summary:
Sample data:
Header file: folder.h
See also:
Folder::Subfolders
Prototype:
PUBLIC  Folder Subfolders(LPCSTR lpcszName)
Remarks: Get a folder by name.
Parameters:

Return values:

Example:
        Folder fld = Application.RootFolder;
        Folder subfld = fld.Subfolders("MyFolder");

Summary:
Sample data:
Header file: folder.h
See also:


fpoint

Class: fpoint

Description: The fpoint class provides methods and properties common to data points located in a two dimensional or planar space whose (x,y) coordinates are doubles.

Hierarchy:

fpoint

Sample:

        point fpt(1.2, 7.6);
        printf("x = %g   y = %g\n", fpt.x, fpt.y);


fpoint

fpoint::fpoint
Prototype:
PUBLIC  fpoint(double x = 0, double y = 0)
Remarks: constructor which initializes the fpoint object from x and y coordinates
Parameters:
x = (optional) x coordinate
y = (optional) y coordinate

Return values:

Example:
        void	run_fpoint_Constructor()
        {
            fpoint	pt(1.2, 7.6);

            printf("x = %f   y = %f\n", pt.x, pt.y);
        }

Summary:
Sample data:
Header file: graph.h
See also:
fpoint::fpoint
Prototype:
PUBLIC  fpoint(fpoint pp)
Remarks: Copy constructor which initializes the fpoint object from another fpoint object
Parameters:
pp = source fpoint object

Return values:

Example:
        void	run_fpoint_Constructor()
        {
            fpoint	pt(4.4, 7.7);

            // Initialize pt2 from pt:
            fpoint	pt2(pt);

            // Display pt2:
            printf("x = %f   y = %f\n", pt2.x, pt2.y);
        }

Summary:
Sample data:
Header file: graph.h
See also:


fpoint3d

Class: fpoint3d

Description: The fpoint3d class provides methods and properties common to data points located in a three dimensional space whose (x,y,z) coordinates are doubles.

Hierarchy:

fpoint3d

Sample:

        fpoint3d fpt3(2.2, 7.6, 0.5);
        printf("x = %g   y = %g   z = %g\n", fpt3.x, fpt3.y, fpt3.z);


fpoint3d

fpoint3d::fpoint3d
Prototype:
PUBLIC  fpoint3d(double x = 0, double y = 0, double z = 0)
Remarks: constructor which initializes the fpoint3d object from x, y, and z coordinates
Parameters:
x = (optional) x coordinate
y = (optional) y coordinate
z = (optional) z coordinate

Return values:

Example:
        void	run_fpoint3d_Constructor()
        {
            fpoint3d	pt(2.2, 7.6, 0.5);

            printf("x = %f   y = %f   z = %f\n", pt.x, pt.y, pt.z);
        }

Summary:
Sample data:
Header file: graph.h
See also:
fpoint3d::fpoint3d
Prototype:
PUBLIC  fpoint3d(fpoint3d pp)
Remarks: Copy constructor which initializes the fpoint3d object from another fpoint3d object
Parameters:
pp = source fpoint3d object

Return values:

Example:
        void	run_fpoint3d_Constructor()
        {
            fpoint3d	pt(4.4, 5.5, 7.7);

            // Initialize pt2 from pt:
            fpoint3d	pt2(pt);

            // Display pt2:
            printf("x = %f   y = %f   z = %f\n", pt2.x, pt2.y, pt2.z);
        }

Summary:
Sample data:
Header file: graph.h
See also:


GraphLayer

Class: GraphLayer

Description: The GraphLayer class provides methods and properties common to all Origin graph layers. Internal Origin graph pages contain one or more graph layers thus the Origin C GraphPage class contains a collection of one or more GraphLayer objects. Origin graph layers may contain Origin data plots thus the Origin C GraphLayer class contains a collection of DataPlot objects. An Origin C GraphLayer object is a wrapper object that is a reference to an internal Origin graph layer object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The GraphLayer class is derived from the Layer and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 Layer
 GraphLayer

Sample:

        // Assumes Graph1 window with one or more data plots is active in Origin
        GraphLayer	gl = Project.ActiveLayer(); // Get active layer in project file
        if(gl)                                  // If valid graph layer...
        {
            DataPlot dp = gl.DataPlots(0);      // Get first data plot in graph layer
            dp.SetColor(2);                     // Change color to green
        }


AddErrBar

GraphLayer::AddErrBar
Prototype:
PUBLIC  int AddErrBar(Curve& cData, Column &colErrBar)
Remarks: Adds an error bar plot to an existing dataplot.
Parameters:
cData = Data curve to add the error bar to
dsErrBar = the dataset to be used as errorbar
colErrBar = the Data curve to be used as error bar

Return values:
the index of the added error bar dataplot in layer, or -1 if failed.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Also, a workseet with the name "Data1" and with columns "A" and "B" and another column
        // (the third column) must exist with some numeric data in them. The graph
        // window should contain one dataplot (such as scatter plot)
        // which uses the workseet's "B" column as Y-column and "A" column as X-column.
        // After the function executes, the third column of the worksheet will be used
        // for error bars (the graph may need to be refreshed to see the error bars).
        void	run_GraphLayer_AddErrBar()
        {
            GraphLayer		lay("Graph1");

            // a dataplot in the layer that uses Data1_b as Y and Data1_a as X
            Curve			cc("Data1_a", "Data1_b");

            // use the third column in the worksheet "Data1" for error bar:
            Column	colErrBar("Data1", 2);
            int				nPlotIndex = lay.AddErrBar(cc, colErrBar);
            out_int("nPlotIndex = ", nPlotIndex);
        }

Summary:
Sample data:
Header file: graph.h
See also:
GraphLayer::AddErrBar
Prototype:
PUBLIC  int AddErrBar(Curve& cData, Dataset &dsErrBar)
Remarks:
Parameters:

Return values:

Example:
        This example adds an error bar plot to an existing dataplot.
        For this example to run, a graph window with the name "Graph1" must exist in the project.
        Also, a workseet with the name "Data1" and with columns "A" and "B" and "C" must exist
        with some numeric data in them. The graph window should contain one dataplot which uses
        the workseet's "B" column as Y-column and "A" column as X-column. (the graph may need
        to be refreshed to see the error bars).

        void test_GraphLayer_AddErrBar()
        {
            GraphLayer glMyLayer("Graph1");
            Curve crvMyCurve("Data1_a","Data1_b");
            Dataset dsErrBar("Data1_c");
            int iPlotIndex = glMyLayer.AddErrBar(crvMyCurve, dsErrBar);
            if (iPlotIndex==-1)
                printf("ErrBar Plotting Error!");
            else
                printf("Errbar added successfully!");
        }

Summary:
Sample data:
Header file: graph.h
See also:


AddLabelPlot

GraphLayer::AddLabelPlot
Prototype:
PUBLIC  int AddLabelPlot(Curve& cData, Dataset &dsLabel)
Remarks:
Parameters:

Return values:

Example:
        For this example to run, a graph window with the name "Graph1" must exist
        in the project. Also, a workseet with the name "Data1" and with columns "A"
        and "B" and a label column "C" must exist. The graph window should contain
        one dataplot which uses the workseet's "B" column as Y-column and "A" column
        as X-column.

        void test_Graphlayer_AddLabelPlot()
        {
            Worksheet wks("Data1");
            Dataset dsLables("Data1_c");
            if(wks)
            {
                if(!wks.Columns(2).SetType(OKDATAOBJ_DESIGNATION_L))
                    return;
            }
            else
                return;

            GraphLayer glMyLayer("Graph1");
            Curve crvMyCurve("Data1_a", "Data1_b");

            int iPlotIndex = glMyLayer.AddLabelPlot(crvMyCurve, dsLables);
            if (iPlotIndex==-1)
                printf("Lables adding Error!");
            else
                printf("Lables added successfully!");
        }

Summary:
Sample data:
Header file: graph.h
See also:
GraphLayer::AddLabelPlot
Prototype:
PUBLIC  int AddLabelPlot(Curve& cData, Column &colLabel)
Remarks: Adds a label plot to an existing dataplot.
Parameters:
cData = Data curve to add the label plot to
dsLabel = the dataset to be used as labels
colLabel = the Data curve to be used as label column

Return values:

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Also, a workseet with the name "Data1" and with columns "A" and "B" and another label column
        // (the third column) must exist. The graph
        // window should contain one dataplot (such as scatter plot)
        // which uses the workseet's "B" column as Y-column and "A" column as X-column.
        // After the function executes, the third column of the worksheet will be used
        // for labels
        void	run_GraphLayer_AddLabelPlot()
        {
            //we need to first make sure the label column is really a Label column
            Worksheet wks("Data1");
            if(wks)
            {
                if(!wks.Columns(2).SetType(OKDATAOBJ_DESIGNATION_L))
                    return;
            }
            else
                return;

            GraphLayer		lay("Graph1");

            // a dataplot in the layer that uses Data1_b as Y and Data1_a as X
            Curve			cc("Data1_a", "Data1_b");

            // first we plot col(B)
            int				nPlotIndex = lay.AddPlot(cc, IDM_PLOT_SCATTER);
            // use the third column in the worksheet "Data1" for labels:
            Column			colLabels("Data1", 2);
            nPlotIndex = lay.AddLabelPlot(cc, colLabels);
            out_int("nPlotIndex = ", nPlotIndex);

            lay.Rescale();
        }

Summary:
Sample data:
Header file: graph.h
See also:


AddPlot

GraphLayer::AddPlot
Prototype:
PUBLIC  int AddPlot(Curve& cData, int nPlotID = IDM_PLOT_UNKNOWN, int wCntrl = 0)
Remarks: Add one data plot to layer
Parameters:
cData = Data curve to add
nPlotID = the internal Origin plot type id..
wCntrl = (optional) not used

Return values:
0-offset data plot index of the dataplot added or -1 for error

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Also, a workseet with the name "Data1" and with columns "A" and "B" must
        // exist with some numeric data in them.
        void	run_AddPlot()
        {
            // Construct the Curve object specifying the x and y datasets to be used for
            // the dataplot
            Curve		cc("Data1_a", "Data1_b");

            // the graph layer needs to be initialized:
            GraphLayer	lay("Graph1");

            // Add the dataplot to the graph:
            int			nIndex = lay.AddPlot(cc, IDM_PLOT_SCATTER);

            // Display the index of the data plot just added:
            out_int("Dataplot index = ", nIndex);
        }

Summary:
Sample data:
Header file: graph.h
See also:
GraphLayer::AddPlot
Prototype:
PUBLIC  int AddPlot(Worksheet& wks, int nPlotID = IDM_PLOT_UNKNOWN)
Remarks: Add entire worksheet to layer.
Parameters:

Return values:

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Also, a workseet with the name "Data1" must exist with some numeric data.

        void run_AddPlot2()
        {
            GraphLayer gl("Graph1");
            Worksheet wks("Data1");
            gl.AddPlot(wks);
        }

Summary:
Sample data:
Header file: graph.h
See also:


AddXErrBar

GraphLayer::AddXErrBar
Prototype:
PUBLIC  int AddXErrBar(Curve& cData, Column &colXErrBar)
Remarks: Adds an X error bar plot to an existing dataplot.
Parameters:
cData = Data curve to add the X error bar to
dsXErrBar = the dataset to be used as X error bar
colXErrBar = the Data curve to be used as X error bar

Return values:
the index of the the added X error bar dataplot in layer, or -1 if failed.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Also, a workseet with the name "Data1" and with columns "A" and "B" and another column
        // (the third column) must exist with some numeric data in them. The graph
        // window should contain one dataplot (such as scatter plot)
        // which uses the workseet's "B" column as Y-column and "A" column as X-column.
        // After the function executes, the third column of the worksheet will be used
        // for X error bars (the graph may need to be refreshed to see the error bars).
        void	run_GraphLayer_AddXErrBar()
        {
            GraphLayer		lay("Graph1");

            // a dataplot in the layer that uses Data1_b as Y and Data1_a as X
            Curve			cc("Data1_a", "Data1_b");

            // use the third column in the worksheet "Data1" for X error bar:
            Column	colErrBar("Data1", 2);
            int				nPlotIndex = lay.AddXErrBar(cc, colErrBar);
            out_int("nPlotIndex = ", nPlotIndex);
        }

Summary:
Sample data:
Header file: graph.h
See also:
GraphLayer::AddXErrBar
Prototype:
PUBLIC  int AddXErrBar(Curve& cData, Dataset &dsXErrBar)
Remarks:
Parameters:

Return values:

Example:
        For this example to run, a graph window with the name "Graph1" must exist in
        the project. Also, a workseet with the name "Data1" and with columns "A" and
        "B" and "C" must exist with some numeric data in them. The graph window should
        contain one dataplot which uses the workseet's "B" column as Y-column and "A"
        column as X-column. After the function executes, the graph may need to be
        refreshed to see the error bars.

        void test_Graphlayer_AddXErrBar()
        {
            GraphLayer glMyLayer("Graph1");
            Curve crvMyCurve("Data1_a","Data1_b");
            Dataset dsXErrBar("Data1_c");
            int iPlotIndex = glMyLayer.AddXErrBar(crvMyCurve, dsXErrBar);
            if (iPlotIndex==-1)
                printf("X ErrBar Plotting Error!");
            else
                printf("X Errbar added successfully!");
        }

Summary:
Sample data:
Header file: graph.h
See also:


Attach

GraphLayer::Attach
Prototype:
PUBLIC  BOOL Attach(LPCSTR lpcszWinName, int nLayerNum=-1)
Remarks: Attached a layer in an Origin graph window to the object based on the graph name and the layer index.
Parameters:
lpcszWinName = the name of an existing Origin graph window
nLayerNum = (optional) the 0-offset index of the layer in the graph window to attach
or -1 for the active layer.

Return values:
TRUE for success, otherwise FALSE.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the window has at least two layers.
        // Make layer 2 active before running the function.
        void	run_GraphLayer_Attach()
        {
            // Construct a GraphLayer object and attach it to the second layer of "Graph1" window.
            // (note that in the constructor the layer index is 0-offset, so the
            // first layer needs index 0)
            GraphLayer		gl("Graph1", 1);

            // Display the index of the layer in graph page
            // (note that the index returned from the "GetIndex" method
            // is 1-offset, so the first layer will have index 1):
            out_int("Layer index = ", gl.GetIndex());

            // Now attach the first layer:
            gl.Attach("Graph1", 0);

            // Display the index of the layer in graph page.
            // (note that the index returned from the "GetIndex" method
            // is 1-offset, so the first layer will have index 1):
            out_int("Layer index = ", gl.GetIndex());
        }

Summary:
Sample data:
Header file: graph.h
See also:


DataPlots

GraphLayer::DataPlots
Prototype:
PUBLIC  DataPlot DataPlots(int index)
Remarks: Gets an arbitrary DataPlot in layer.
Parameters:
index = 0-offset index of the data plot in layer.

Return values:
the index'th DataPlot.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the graph has at least one data plot and that there are at least ten
        // data points in the plot.
        // After the function executes, the data plot will show
        // only the data points from 5 to 10.
        void	run_DataPlots()
        {
            // Create and attach a graph layer from "Graph1":
            GraphLayer		gl("Graph1");

            // Get the first data plot in the layer:
            DataPlot		dp = gl.DataPlots(0);

            // Change the display range of the data plot to
            // show only points from 5 to 10:
            dp.SetRange(5, 10);
        }

Summary:
Sample data:
Header file: graph.h
See also:
GraphLayer::DataPlots
Prototype:
PUBLIC  DataPlot DataPlots(LPCSTR lpcszName)
Remarks: Gets an arbitrary DataPlot in layer.
Parameters:
lpcszName = the name of the dataset that the desired DataPlot should contain.

Return values:
the DataPlot.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the graph has at least one data plot using
        // the dataset "Data1_b" and that there are at least ten
        // data points in the plot.
        // After the function executes, the data plot will show
        // only the data points from 5 to 10.
        void	run_DataPlots()
        {
            // Create and attach a graph layer from "Graph1":
            GraphLayer		gl("Graph1");

            // Get the data plot in the layer which contains dataset "Data1_b":
            DataPlot		dp = gl.DataPlots("Data1_b");

            // Change the display range of the data plot to
            // show only points from 5 to 10:
            dp.SetRange(5, 10);
        }

Summary:
Sample data:
Header file: graph.h
See also:


GetCoordinateType

GraphLayer::GetCoordinateType
Prototype:
PUBLIC  UINT GetCoordinateType()
Remarks: Gets the layer's coordinate system type.
Parameters:
None.

Return values:
a value from the following enumeration indicating the type:
enum {
FRAME_COOR_CART = 0,			// XY Cartesian coordinate system
FRAME_COOR_POLAR,				// polar
FRAME_COOR_TERNARY,				// ternary
FRAME_COOR_SMITH_CHART			// Smith chart
};

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        void	run_GetCoordinateType()
        {
            // the graph layer needs to be initialized:
            GraphLayer		lay("Graph1");

            if (lay.GetCoordinateType() == FRAME_COOR_CART)
                out_str("The coordinate system is Cartesian");
            else
                out_str("The coordinate system is not Cartesian");
        }

Summary:
Sample data:
Header file: graph.h
See also:


GraphLayer

GraphLayer::GraphLayer
Prototype:
PUBLIC  GraphLayer(LPCSTR lpcszWinName, int nLayerNum=-1)
Remarks: Construct and attach a GraphLayer object based on the name of the graph window and the layer index
Parameters:
lpcszWinName = the name of the graph window (page)
nLayerNum = (optional) 0-offset index of the layer (use -1
for the active layer)

Return values:

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the window has at least two layers.
        // Make layer 2 active before running the function.
        void	run_GraphLayer_Constructor()
        {
            // Construct a GraphLayer object and attach it to the second layer of "Graph1" window.
            // (note that in the constructor the layer index is 0-offset, so the
            // first layer needs index 0)
            GraphLayer		gl("Graph1", 1);

            // Display the index of the layer in graph page
            // (note that the index returned from the "GetIndex" method
            // is 0-offset, so the first layer will have index 0):
            out_int("Layer index = ", gl.GetIndex() + 1);
        }

Summary:
Sample data:
Header file: graph.h
See also:
GraphLayer::GraphLayer
Prototype:
PUBLIC  GraphLayer(Layer & layer)
Remarks: Copy constructor which constructs a GraphLayer object from an existing Layer object. Note that the existing Layer object must also be in a garph page.
Parameters:
layer = the source Layer object

Return values:

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the window has at least two layers.
        // Make layer 2 active before running the function.
        void	run_GraphLayer_Constructor()
        {
            // Construct a GraphLayer object and attach it to the second layer of "Graph1" window.
            // (note that in the constructor the layer index is 0-offset, so the
            // first layer needs index 0)
            GraphLayer		gl("Graph1", 1);

            GraphLayer		gl2(gl);

            // Display the index of the layer in graph page
            // (note that the index returned from the "GetIndex" method
            // is 1-offset, so the first layer will have index 1):
            out_int("Layer index = ", gl2.GetIndex());
        }

Summary:
Sample data:
Header file: graph.h
See also:


GroupPlots

GraphLayer::GroupPlots
Prototype:
PUBLIC  BOOL GroupPlots(int nIndexStart, int nIndexEnd = -1)
Remarks: Groups dataplots in layer.
Parameters:
nIndexStart = the index of the first dataplot to be grouped
nIndexEnd = the index of the last dataplot to be grouped. All the dataplots from nIndexStart
to nIndexEnd are going to be put into the same group (if nIndexEnd is negative,
all the dataplots from nIndexStart to the end are going to be grouped)

Return values:
TRUE for success, otherwise FALSE.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the graph has at least two data plots and they are not grouped.
        // After the function executes, all the dataplots in layer will be grouped in one group.
        void	run_GroupPlots()
        {
            // the graph layer needs to be initialized:
            GraphLayer		lay("Graph1");

            // Group all the plots in the layer into one group.
            lay.GroupPlots(0);
        }

Summary:
Sample data:
Header file: graph.h
See also:


Rescale

GraphLayer::Rescale
Prototype:
PUBLIC  BOOL Rescale()
Remarks: It rescales the graphic layer axes to show all dataplot points that may be outside the current axis ranges.
Parameters:
None.

Return values:
TRUE if OK, otherwise FALSE.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Then manually add some data to the graph and use the Axes dialog to rescale
        // the axes limits so that not all the data is visible. After the function executes,
        // all the data will be visible.
        void	run_GraphLayer_Rescale()
        {
            // the graph layer needs to be initialized:
            GraphLayer		lay("Graph1");

            // Rescale the layer axes if necessary:
            lay.Rescale();
        }

Summary:
Sample data:
Header file: graph.h
See also:


UngroupPlots

GraphLayer::UngroupPlots
Prototype:
PUBLIC  BOOL UngroupPlots(int nIndex = -1)
Remarks: Ungroups dataplots.
Parameters:
nIndex = the index of any dataplot inside the group. If -1, use the first group

Return values:
TRUE for success, otherwise FALSE.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the graph has at least two data plots and that they are grouped.
        // After the function executes, the dataplots in layer will be ungrouped.
        void	run_UngroupPlots()
        {
            // the graph layer needs to be initialized:
            GraphLayer		lay("Graph1");

            // Group all the plots in the layer into one group.
            lay.UngroupPlots();
        }

Summary:
Sample data:
Header file: graph.h
See also:


GraphObject

Class: GraphObject

Description: The GraphObject class provides methods and properties common to all Origin graph objects. Origin graph objects include such things as text annotations, graphic annotations (e.g. rectangles, arrows, line objects, etc.), data plot style holders, and region of interest objects. Origin graph objects are generally contained by layers on an Origin page thus the Origin C GraphLayer class contains a collection of GraphObjects. An Origin C GraphObject is a wrapper object that is a reference to an internal Origin graph object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The GraphObject class is derived from the OriginObject class from which it inherits methods and properties.

Hierarchy:

OriginObject
 GraphObject

Sample:

        // Assumes Graph1 window is active in Origin
        GraphLayer gl = Project.ActiveLayer();  // Get active layer in project file
        if(gl)                                  // If valid graph layer...
        {
            GraphObject	go;                     // Declare GraphObject
            go = gl.GraphObjects("YL"); 		// Attach go to "YL" which is the the left Y-axis title
            out_str(go.Text);
        }


GetName

GraphObject::GetName
Prototype:
PUBLIC  string GetName()
Remarks: The name of the graphic object. The name of each object can be seen by opening the "Label Control" dialog box (using the context menu on the object).
Parameters:
None.

Return values:
the name of the GraphObject.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        void	run_GraphObject_GetName()
        {
            // Create and attach a graph layer from "Graph1":
            GraphLayer		gl("Graph1");
            GraphObject		grobj;

            // Loop over all the graphic objects in the layer and for each of them
            // display its name:
            foreach (grobj in gl.GraphObjects)
            {
                out_str(grobj.GetName());
            }
        }

Summary:
Sample data:
Header file: graph.h
See also:


GetObjectType

GraphObject::GetObjectType
Prototype:
PUBLIC  string GetObjectType()
Remarks: The type of the graphic object as a string.
Parameters:
None.

Return values:
the string representing the type of the graphic object.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        void	run_GraphObject_GetObjectType()
        {
            // Create and attach a graph layer from "Graph1":
            GraphLayer		gl("Graph1");
            GraphObject		grobj;

            // Loop over all the graphic objects in the layer and for each of them
            // display its type as string:
            foreach (grobj in gl.GraphObjects)
            {
                out_str(grobj.GetObjectType());
            }
        }

Summary:
Sample data:
Header file: graph.h
See also:


GraphObject

GraphObject::GraphObject
Prototype:
PUBLIC  GraphObject()
Remarks: Default constructor which creates a GraphObject which is not attached to an internal graphic object. It should be initialized using "GraphObjects" method of the Layer class because all the GraphObject's are conatined in layers.
Parameters:

Return values:

Example:
        For this example to run, a graph window with the name "Graph1" must exist in the project.
        void test_GraphObject()
        {
            GraphLayer glMyLayer("Graph1");
            GraphObject goMyObj = glMyLayer.GraphObjects("Text");
            out_str(goMyObj.Text);
        }

Summary:
Sample data:
Header file: graph.h
See also:
GraphObject::GraphObject
Prototype:
PUBLIC  GraphObject(GraphObject &goOriginal)
Remarks: Copy Constructor: The new GrpahObject object created is attached to the internal graphic object goOriginal was attached to. If goOriginal was invalid (not attached) so will be the new object.
Parameters:

Return values:

Example:
        For this example to run, a graph window with the name "Graph1" must exist in the project.
        void test_GraphObject()
        {
            GraphLayer glMyLayer("Graph1");
            GraphObject goOriginal;
            goOriginal = glMyLayer.GraphObjects("Text");

            GraphObject goNew(goOriginal);
            out_str(goNew.Text);
        }

Summary:
Sample data:
Header file: graph.h
See also:


GraphPage

Class: GraphPage

Description: The GraphPage class provides methods and properties common to all internal Origin graph pages (windows). The Project class contains a collection of GraphPage objects. An Origin C GraphPage object is a wrapper object that is a reference to an internal Origin graph page object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The GraphPage class is derived from the Page, PageBase, and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 PageBase
 Page
 GraphPage

Sample:

        // Assumes Graph1 window exists in Origin
        GraphPage gp;
        GraphLayer gl;
        GraphObject go;

        gp = Project.GraphPages("Graph1");       // Get Graph1 page from GraphPages collection
        if(gp)                                   // If gp IsValid...
        {
            gl = (GraphLayer) gp.Layers(0);      // Get Graph1 Layer from Layers collection
            if(gl)                               // If gl IsValid...
            {
                go = gl.GraphObjects(0);         // Get first GraphObject in Layer
                if(go)                           // If go IsValid...
                {
                    printf("Name of first GraphObject is %s\n", go.GetName() );
                }
            }
        }


AppendLayers

GraphPage::AppendLayers
Prototype:
PUBLIC  BOOL AppendLayers(LPCSTR lpcszName)
Remarks: Append layers from the supplied template to the page.
Parameters:
lpcszName = Template name

Return values:
TRUE for success or FALSE for failure.

Example:
        GraphPage gp;
        gp.Create();
        if( gp.IsValid() )
        {
            printf("%s has %d layers\n", gp.GetName(), gp.Layers.Count());
            gp.AppendLayers("origin");
            printf("Now %s has %d layers\n", gp.GetName(), gp.Layers.Count());
        }

Summary:
Sample data:
Header file: Page.h
See also: LoadTemplate


GraphPage

GraphPage::GraphPage
Prototype:
PUBLIC  GraphPage(LPCTSTR lpcszName)
Remarks: Construct a GraphPage object using the name of an existing page.
Parameters:
lpcszName = The name of an existing page.

Return values:

Example:
        GraphPage gp;
        gp.Create("origin.otm");
        if( gp.IsValid() )
        {
            GraphPage gp2(gp.GetName());
            if( gp2.IsValid() )
                printf("gp and gp2 are both attached to '%s'\n", gp2.GetName());
        }

Summary:
Sample data:
Header file: Page.h
See also: Create
GraphPage::GraphPage
Prototype:
PUBLIC  GraphPage(PageBase &page)
Remarks: Construct a GraphPage object using an existing page object.
Parameters:
page = An existing page object.

Return values:

Example:
        GraphPage gp;
        gp.Create("origin.otm");
        if( gp.IsValid() )
        {
            GraphPage gp2(gp);
            if( gp2.IsValid() )
                printf("gp and gp2 are both attached to '%s'\n", gp2.GetName());
        }

Summary:
Sample data:
Header file: Page.h
See also: Create


Layers

GraphPage::Layers
Prototype:
PUBLIC  GraphLayer Layers(int iIndex = -1)
Remarks: Get a GraphLayer object by index.
Parameters:
iIndex = The index of the layer requested to be accessed.
If -1 then the active layer is returned.

Return values:
If iIndex is valid then the layer to which the index refers is returned otherwise an invalid layer object is returned.

Example:
        // For this example to run, the graph window with the name "Graph1" must exist
        // in the project.
        void	run_Layers()
        {
            GraphPage	gp("Graph1");

            if( gp.IsValid() )
            {
                GraphLayer		gl = gp.Layers(); // Get active layer
                printf("%s has %d layer(s)\n", gp.GetName(), gp.Layers.Count());
            }
        }

Summary:
Sample data:
Header file: Page.h
See also:
GraphPage::Layers
Prototype:
PUBLIC  GraphLayer Layers(LPCSTR lpcszName)
Remarks: Get a GraphLayer object by name.
Parameters:
lpcszName = The name of the layer requested to be accessed.

Return values:
If the name is valid then the layer to which the name refers is returned otherwise an invalid layer object is returned.

Example:
        // For this example to run, the graph window with the name "Graph1" must exist
        // in the project.
        void	run_Layers()
        {
            GraphPage	gp("Graph1");
            string		strLayerName = "ABC";
            GraphLayer	gl = gp.Layers(strLayerName);
            if (gl.IsValid())
                out_str("The layer exists.");
            else
                out_str("The layer does not exist.");
        }

Summary:
Sample data:
Header file: Page.h
See also:


LoadTemplate

GraphPage::LoadTemplate
Prototype:
PUBLIC  BOOL LoadTemplate(LPCSTR lpcszName)
Remarks: Load a template into the page.
Parameters:
lpcszName = Template name

Return values:
TRUE for success or FALSE for failure.

Example:
        GraphPage gp;
        gp.Create();
        if( gp.IsValid() )
        {
            printf("%s has %d layers\n", gp.GetName(), gp.Layers.Count());
            gp.AppendLayers("origin");
            printf("Now %s has %d layers\n", gp.GetName(), gp.Layers.Count());
            gp.LoadTemplate("origin");
            printf("Now %s has %d layers\n", gp.GetName(), gp.Layers.Count());
        }

Summary:
Sample data:
Header file: Page.h
See also: AppendLayers


RemoveTemplatePict

GraphPage::RemoveTemplatePict
Prototype:
PUBLIC  BOOL RemoveTemplatePict()
Remarks: Removes the graph object which is used to store the picture of what the graph created from the template will look like.
Parameters:

Return values:
TRUE for success or FALSE for failure.

Example:
        GraphPage gp;
        gp.Create("origin.otm");
        if( gp.IsValid() )
            gp.RemoveTemplatePict();

Summary:
Sample data:
Header file: Page.h
See also:


GroupPlot

Class: GroupPlot

Description: The GroupPlot class is derived from the OriginObject class and provides access to Origin group plots. Origin GroupPlot objects are contained by layers on an Origin page.

Hierarchy:

OriginObject
 GroupPlot

Sample:


GroupPlot

GroupPlot::GroupPlot
Prototype:
PUBLIC  GroupPlot()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: graph.h
See also:
GroupPlot::GroupPlot
Prototype:
PUBLIC  GroupPlot(const GroupPlot& gp)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: graph.h
See also:


Layer

Class: Layer

Description: The Layer class provides methods and properties common to all internal Origin layers. All Origin pages (windows) except note pages contain one or more layers. Origin objects found "on" a page are generally contained by layers which are themselves contained by the page. Origin layers may contain many different graph objects thus the Layer class contains a collection of all the graph objects in the layer. An Origin C Layer object is a wrapper object that is a reference to an internal Origin layer object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The Layer class is derived from the OriginObject class from which it inherits methods and properties.

Hierarchy:

OriginObject
 Layer

Sample:

        // This example assumes Graph1 with X axis label "XB" is active window/layer in Origin
        Layer lyr;                   // Declare a Layer object named lyr
        lyr = Project.ActiveLayer(); // Attach lyr to active layer in "Graph1"
        GraphObject go ;             // Declare a GraphObject named go
        go = lyr.GraphObjects("XB"); // Attach go to X Axis Label with name "XB"
        if(go.IsValid())             // If graph object exists...
            printf("Name of GraphObject is %s\n", go.GetName()); // Display its name


Detach

Layer::Detach
Prototype:
PUBLIC  void Detach()
Remarks: It detaches the internal Origin layer from this object.
Parameters:
None

Return values:
void

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        void	run_Layer_Detach()
        {
            // Create a Layer object and attach it to the active layer in "Graph1" graph window.
            GraphLayer		lay("Graph1");

            // We can check if the object lay is valid (attached to
            // an internal Origin layer) by calling the method "IsValid)"
            if ( lay.IsValid() )
                out_str("Object is valid");			// it should valid (if "Graph1" exists)
            else
                out_str("Object is not valid");

            // Now detach:
            lay.Detach();

            if ( lay.IsValid() )
                out_str("Object is valid");
            else
                out_str("Object is not valid");	// it should be invalid because we detached it
        }

Summary:
Sample data:
Header file: graph.h
See also:


GetIndex

Layer::GetIndex
Prototype:
PUBLIC  int GetIndex()
Remarks: Get the index of the Layer in the parent page, 0 offset This method returns 1-offset index in Origin 7, and in Origin 7.5 and later, it has been made consistent to return 0-offset index.
Parameters:

Return values:
The index of the specific layer in its parent page

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the window has several layers.
        // Make layer 2 active before running the function.
        void	run_GetIndex()
        {
            // Create a Layer object and attach it to the active layer in "Graph1" graph window.
            GraphLayer		lay("Graph1");

            // Displaye the active index (it should be "2" if the active layer is the second layer):
            out_int("Active layer index is ", lay.GetIndex() + 1); // convert C index to LabTalk index
        }

Summary:
Sample data:
Header file: graph.h
See also:


GetPage

Layer::GetPage
Prototype:
PUBLIC  Page GetPage()
Remarks: It gets the parent Page object (the Page containing this layer).
Parameters:
None

Return values:
the parent Page object

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        void	run_Layer_GetPage()
        {
            // Create a Layer object and attach it to the active layer in "Graph1" graph window.
            GraphLayer		lay("Graph1");

            Page			pg;

            // Get the parent page:
            pg = lay.GetPage();

            printf("The name of the parent page is %s\n", pg.GetName());
        }

Summary:
Sample data:
Header file: graph.h
See also:


GetSystemParam

Layer::GetSystemParam
Prototype:
PUBLIC  DWORD GetSystemParam(int nParamType)
Remarks: Get the layer's internal info
Parameters:
nType = specify the info to obtain

Return values:
a generic value that depends on the request

Example:

Summary:
Sample data:
Header file: graph.h
See also:


GraphObjects

Layer::GraphObjects
Prototype:
PUBLIC  GraphObject GraphObjects(int index)
Remarks: It returns the index'th GraphObject in the layer. GraphObjects are text labels, rectangles, lines, arrows, etc, which can be drawn inside graphs, worksheets, and layouts,
Parameters:
index = GraphObject index

Return values:
the index'th GraphObject in the layer.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        void	run_Layer_GraphObjects()
        {
            // Create a Layer object and attach it to the active layer in "Graph1" graph window.
            GraphLayer		lay("Graph1");

            GraphObject		grobj;

            // Get the first GraphObject in the layer:
            grobj = lay.GraphObjects(0);

            // Make sure that the object is valid:
            if (!grobj.IsValid())
            {
                out_str("No GraphicObject!");
                return;
            }

            // Display its name:
            printf("The name of the first GraphObject in layer is %s\n", grobj.GetName());
        }

Summary:
Sample data:
Header file: graph.h
See also:
Layer::GraphObjects
Prototype:
PUBLIC  GraphObject GraphObjects(LPCSTR lpcszName)
Remarks: It returns the GraphObject with the given name in the layer. GraphObjects are text labels, rectangles, lines, arrows, etc, which can be drawn inside graphs, worksheets, and layouts,
Parameters:
lpcszName = pointer to the string representing the name of the GraphObject

Return values:
the GraphObject with the name lpcszName in the layer.

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Also, in the active layer create a text label with the name "Text". You can change
        // the name of the text label GraphObject using the "Label Control" dialog box (use
        // the context menu on the text label to bring up the dialog).
        void	run_Layer_GraphObjects()
        {
            // Create a Layer object and attach it to the active layer in "Graph1" graph window.
            GraphLayer		lay("Graph1");

            GraphObject		grobj;

            // Get the GraphObject with the name "Text":
            grobj = lay.GraphObjects("Text");

            // Make sure that the object is valid:
            if (!grobj.IsValid())
            {
                out_str("No GraphicObject!");
                return;
            }

            // Display its name:
            printf("The name of the GraphObject is %s\n", grobj.GetName());
        }

Summary:
Sample data:
Header file: graph.h
See also:


Layer

Layer::Layer
Prototype:
PUBLIC  Layer()
Remarks: Default constructor which constructs an unattached Layer object. The member function IsValid() of the base class OriginObject can be used to determine if the object is valid (attached to an internal Origin layer object)
Parameters:
None

Return values:

Example:
        void	run_Layer_constructor()
        {
            Layer	lay;

            if (lay.IsValid())
                out_str("Object is valid");
            else
                out_str("Object is not valid");	// it should be invalid
        }

Summary:
Sample data:
Header file: graph.h
See also:
Layer::Layer
Prototype:
PUBLIC  Layer(Layer & layer)
Remarks: Copy constructor which constructs a Layer object from an existing Layer object. The member function IsValid() of the base class OriginObject can be used to determine if the object is valid (attached to an internal Origin layer object)
Parameters:
layer = the source Layer object

Return values:

Example:
        void	run_Layer_constructor()
        {
            Layer	lay;
            Layer	lay2(lay);

            if (lay2.IsValid())
                out_str("Object is valid");
            else
                out_str("Object is not valid");	// it should be invalid
        }

Summary:
Sample data:
Header file: graph.h
See also:


LT_execute

Layer::LT_execute
Prototype:
PUBLIC  BOOL LT_execute(LPCSTR lpcszstr, int wCntrl = 0)
Remarks: Execute labtalk script with the current layer as the active layer. This command has the combination effect of labtalk's "win -o" and "layer -o"
Parameters:

Return values:

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Make sure that the window has several layers.
        // Make layer 2 active before running the function.
        void	run_Layer_LT_execute()
        {
            GraphPage	page("Graph1");

            // Create a Layer object and attach it to the first layer in "Graph1" graph window.
            GraphLayer		lay = page.Layers(0);

            double			xx = -10.0;

            // we will set X scales in the layer using LabTalk script:
            string			str;
            // Construct the LabTalk script to be executed:
            str.Format("layer.x.from=%f;layer.x.to=%f;", xx, xx + 10.0);

            // Execute the script. After this script executes, the first layer
            // will have the x-axis running from -10 to 0.
            lay.LT_execute(str);
        }

Summary:
Sample data:
Header file: graph.h
See also:


RemoveGraphObject

Layer::RemoveGraphObject
Prototype:
PUBLIC  BOOL RemoveGraphObject(int index)
Remarks: Removes one GraphObject from layer. The object is referred to by index.
Parameters:
index = the GraphObject index

Return values:
TRUE for success, otherwise FALSE

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        void	run_Layer_RemoveGraphObject()
        {
            // Create a Layer object and attach it to the active layer in "Graph1" graph window.
            GraphLayer		lay("Graph1");

            GraphObject		grobj;

            // Get the first GraphObject in the layer:
            grobj = lay.GraphObjects(0);

            // Make sure that the object is valid:
            if (!grobj.IsValid())
            {
                out_str("No GraphicObject!");
                return;
            }

            // Display its name:
            printf("The name of the first GraphObject is %s\n", grobj.GetName());

            // Now remove the first GraphObject:
            lay.RemoveGraphObject(0);

            // Get the new first GraphObject in the layer:
            grobj = lay.GraphObjects(0);

            // Make sure that the object is valid:
            if (!grobj.IsValid())
            {
                out_str("No GraphicObject!");
                return;
            }

            // Display its name:
            printf("The name of the first GraphObject is %s\n", grobj.GetName());
        }

Summary:
Sample data:
Header file: graph.h
See also:
Layer::RemoveGraphObject
Prototype:
PUBLIC  BOOL RemoveGraphObject(LPCSTR lpcszName)
Remarks: Removes one GraphObject from layer. The object is referred to by name (lpcszName).
Parameters:
lpcszName = the GraphObject name

Return values:
TRUE for success, otherwise FALSE

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Also, in the active layer create a text label with the name "Text". You can change
        // the name of the text label GraphObject using the "Label Control" dialog box (use
        // the context menu on the text label to bring up the dialog).
        void	run_Layer_RemoveGraphObject()
        {
            // Create a Layer object and attach it to the active layer in "Graph1" graph window.
            GraphLayer		lay("Graph1");

            GraphObject		grobj;

            // Get the GraphObject named "Text" in the layer:
            grobj = lay.GraphObjects("Text");

            // Make sure that the object is valid:
            if (!grobj.IsValid())
            {
                out_str("No GraphicObject!");
                return;
            }

            // Display its name:
            printf("The name of the GraphObject is %s\n", grobj.GetName());

            // Now remove the GraphObject with the name "Text":
            lay.RemoveGraphObject("Text");

            // Get the the GraphObject named "Text" in the layer again:
            grobj = lay.GraphObjects("Text");

            // Make sure that the object is invalid (because we removed it above):
            if (!grobj.IsValid())
            {
                out_str("No GraphicObject!");
                return;
            }
        }

Summary:
Sample data:
Header file: graph.h
See also:


Layout

Class: Layout

Description: The Layout class provides methods and properties common to all internal Origin layout layers. Origin layout pages contain a layout layer which contains other objects on the layout page. An Origin C Layout object is a wrapper object that is a reference to an internal Origin layout object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The Layout class is derived from the Layer and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 Layer
 Layout

Sample:

        // This example assumes Layout1 window with text object named Text
        // is active window/layer in Origin
        Layout lo;                              // Declare a Layout object
        lo = (Layout) Project.ActiveLayer();    // Attach lo to active Layout (layer); must explicitly cast
        GraphObject go ;                        // Declare a GraphObject
        go = lo.GraphObjects("Text");           // Attach go to text object named Text
        if(go.IsValid())                        // If graph object exists...
            printf("Name of GraphObject is %s\n", go.GetName()); // Display its name


Layout

Layout::Layout
Prototype:
PUBLIC  Layout(LPCSTR layoutname)
Remarks: Constructor which constructs a Layout object given the name of a layout window. The object will be valid if the layout window with the given name exists.
Parameters:
layoutname = the name of a layout window in Origin

Return values:

Example:
        // For this example to run, a layout window with the name "Layout1" must exist in the project.
        void	run_Layout_Constructor()
        {
            Layout	la("Layout1");

            // We can check if the object la is valid (attached to
            // an internal Origin layout) by calling the method "IsValid)"
            if (la.IsValid())
                out_str("Object is valid");		// it should be valid
            else
                out_str("Object is not valid");
        }

Summary:
Sample data:
Header file: graph.h
See also:
Layout::Layout
Prototype:
PUBLIC  Layout(Layer & layer)
Remarks: Copy constructor which constructs a Layout object from an existing Layer object. The member function IsValid() of the base class OriginObject can be used to determine if the object is valid (attached to an internal Origin layout object).
Parameters:
layer = the source Layer object in a layout window

Return values:

Example:
        // For this example to run, a layout window with the name "Layout1" must exist in the project.
        void	run_Layout_Constructor()
        {
            // Create an attach a source Layout object:
            Layout	lay("Layout1");

            Layout	la(lay);

            // We can check if the object la is valid (attached to
            // an internal Origin layout) by calling the method "IsValid)"
            if (la.IsValid())
                out_str("Object is valid");
            else
                out_str("Object is not valid");	// it should be invalid
        }

Summary:
Sample data:
Header file: graph.h
See also:


LayoutPage

Class: LayoutPage

Description: The LayoutPage class provides methods and properties common to all internal Origin layout pages (windows). The Project class contains a collection of LayoutPage objects. An Origin C LayoutPage object is a wrapper object that is a reference to an internal Origin layout page object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The LayoutPage class is derived from the Page, PageBase, and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 PageBase
 Page
 LayoutPage

Sample:

        // Assumes Layout1 window with at least one Graph Object exists in Origin
        LayoutPage lpg;
        Layout lo;
        GraphObject go;

        lpg = Project.LayoutPages("Layout1");       // Get Layout1 page from LayoutPages collection
        if(lpg)                                     // If lpg IsValid...
        {
            lo = (Layout) lpg.Layers(0);            // Get Layout1 Layer from Layers collection
            if(lo)                                  // If lo IsValid...
            {
                go = lo.GraphObjects(0);            // Get first GraphObject in Layout Layer
                if(go)                              // If go IsValid...
                {
                    printf("Name of first GraphObject is %s\n", go.GetName() );
                }
            }
        }


LayoutPage

LayoutPage::LayoutPage
Prototype:
PUBLIC  LayoutPage(LPCTSTR lpcszName)
Remarks: Construct a LayoutPage object using the name of an existing page.
Parameters:
lpcszName = The name of an existing page.

Return values:

Example:
        LayoutPage lp;
        lp.Create("origin.otp");
        if( lp.IsValid() )
        {
            LayoutPage lp2(lp.GetName());
            if( lp2.IsValid() )
                printf("lp and lp2 are both attached to '%s'\n", lp2.GetName());
        }

Summary:
Sample data:
Header file: Page.h
See also: Create
LayoutPage::LayoutPage
Prototype:
PUBLIC  LayoutPage(PageBase &page)
Remarks: Construct a LayoutPage object using an existing LayoutPage object.
Parameters:
page = An existing LayoutPage object.

Return values:

Example:
        LayoutPage lp;
        lp.Create("origin.otp");
        if( lp.IsValid() )
        {
            LayoutPage lp2(lp);
            if( lp2.IsValid() )
                printf("lp and lp2 are both attached to '%s'\n", lp2.GetName());
        }

Summary:
Sample data:
Header file: Page.h
See also: Create


MatrixLayer

Class: MatrixLayer

Description: The MatrixLayer class provides methods and properties common to matrix layers in Origin matrix pages. An Origin matrix contains a number of matrix objects thus the MatrixLayer class contains a collection of all the matrix objects in the matrix layer. An Origin C MatrixLayer object is a wrapper object that is a reference to an internal Origin matrix layer object. Wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The MatrixLayer class is derived from the Datasheet, Layer, and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 Layer
 Datasheet
 MatrixLayer

Sample:

        MatrixLayer ml = Project.ActiveLayer();
        if(ml)
        {
            Matrix mm(ml);// Get the active Matrix from a MatrixLayer
            printf("The active matrix is %d x %d\n",mm.GetNumRows(), mm.GetNumCols());
        }


CreateCopy

MatrixLayer::CreateCopy
Prototype:
PUBLIC  BOOL CreateCopy(MatrixLayer &matlayerSource, int nOption = CREATE_VISIBLE_SAME, DWORD dwCtrl = DCTRL_COPY_DEFAULT)
Remarks: Create a copy of the matrix window matlayerSource and attaches it to the object.
Parameters:
matlayerSource		= the matrix whose copy is made
nOption				= enum {
CREATE_TEMP = 0,		// it will be destroyed when destroying the object (when it exits the scope) and is created invisible
CREATE_VISIBLE_SAME,	// visibility is that of the source matrix
CREATE_VISIBLE,			// create visible
CREATE_HIDDEN,			// create hidden
};
DWORD dwCtrl = enum {
DCTRL_COPY_DATA						= 0x00000001, // copy data from source worksheet
DCTRL_COPY_IN_OPERATIONS			= 0x00000002, // copy operations that have MatrixLayer as output (incoimng operations)
DCTRL_COPY_OUT_OPERATIONS			= 0x00000004, // copy operations that have MatrixLayer as input (outgoing operations)
DCTRL_COPY_DEFAULT = DCTRL_COPY_DATA | DCTRL_COPY_OUT_OPERATIONS,
}

Return values:
TRUE for success; otherwise FALSE.

Example:
        void	matrix_copy()
        {
            MatrixLayer	mat;
            MatrixLayer	matSource("Matrix1");

            int			nOption = CREATE_VISIBLE_SAME;
            BOOL		bRet = mat.CreateCopy(matSource, nOption);

            out_int("bRet = ", bRet);
        }

Summary:
Sample data:
Header file: wksheet.h
See also: Create CreateCopy
MatrixLayer::CreateCopy
Prototype:
PUBLIC  BOOL CreateCopy(MatrixLayer &matlayerSource, int nOption = CREATE_VISIBLE_SAME)
Remarks: Create a copy of the matrix window matlayerSource and attaches it to the object.
Parameters:
matlayerSource		= the matrix whose copy is made
nOption				= enum {
CREATE_TEMP = 0,		// it will be destroyed when destroying the object (when it exits the scope) and is created invisible
CREATE_VISIBLE_SAME,	// visibility is that of the source matrix
CREATE_VISIBLE,			// create visible
CREATE_HIDDEN,			// create hidden
};

Return values:
TRUE for success; otherwise FALSE.

Example:
        void	matrix_copy()
        {
            MatrixLayer	mat;
            MatrixLayer	matSource("Matrix1");

            int			nOption = CREATE_VISIBLE_SAME;
            BOOL		bRet = mat.CreateCopy(matSource, nOption);

            out_int("bRet = ", bRet);
        }

Summary:
Sample data:
Header file: wksheet.h
See also: Create CreateCopy


GetCellWidth

MatrixLayer::GetCellWidth
Prototype:
PUBLIC  uint GetCellWidth()
Remarks: Get the matrix cell width
Parameters:
None.

Return values:
The matrix cell width

Example:
        MatrixLayer mm("Matrix1");
        mm.SetDataDisplay(1,2,3);
        printf("The matrix cell width is %d\n", mm.GetCellWidth());

Summary:
Sample data:
Header file: wksheet.h
See also:


GetInternalData

MatrixLayer::GetInternalData
Prototype:
PUBLIC  UINT GetInternalData()
Remarks: Get matrix internal data type
Parameters:
None.

Return values:
Internal data type of matrix

Example:
        MatrixLayer mm("Matrix1");
        mm.SetInternalData(FSI_BYTE);
        ASSERT( mm.GetInternalData() == FSI_BYTE );

Summary:
Sample data:
Header file: wksheet.h
See also: SetInternalData


HasData

MatrixLayer::HasData
Prototype:
PUBLIC  BOOL HasData()
Remarks: Check if MatrixLayer has data that represent the image one sees in the View Image mode. An image can be loaded into a MatrixLayer and viewed as an image, and the associated matrix data is not constructed until needed, to minimize memory consumption.
Parameters:

Return values:
TRUE if matrix has data, return FALSE if matrix only has image but data not yet created

Example:
        MatrixLayer mm("Matrix1");
        if (mm.HasData())
            printf("Matrix has Data\n");
        else
            printf("Matrix has NO Data\n");

Summary:
Sample data:
Header file: wksheet.h
See also: HasImage


HasImage

MatrixLayer::HasImage
Prototype:
PUBLIC  BOOL HasImage()
Remarks: Check if MatrixLayer has associated image to be used in View Image mode.
Parameters:

Return values:
TRUE if matrix has image

Example:
        MatrixLayer mm("Matrix1");
        if (mm.HasImage())
            printf("Matrix has image\n");
        else
            printf("Matrix has NO image\n");

Summary:
Sample data:
Header file: wksheet.h
See also: HasData


MatrixLayer

MatrixLayer::MatrixLayer
Prototype:
PUBLIC  MatrixLayer(const char* MatrixName)
Remarks: Constructor for the MatrixLayer class
Parameters:
MatrixName = name of the matrix

Return values:
none

Example:
        MatrixLayer mm("Matrix1");

Summary:
Sample data:
Header file: wksheet.h
See also:
MatrixLayer::MatrixLayer
Prototype:
PUBLIC  MatrixLayer(Layer & layer)
Remarks: MatrixLayer is one of the wrapper objects that is a reference to the actual internal Origin object. You can construct a new MatrixLayer from another layer object. The MatrixLayer will become invalid if the layer to construct with is actually not an object of Matrix class in Origin.
Parameters:
Parameters: layer = the worksheet that is currently selected or active

Return values:
Return: void

Example:
        MatrixLayer mlay(Project.ActiveLayer());
        if(!mlay)
        {
            out_str("The active layer is not a matrix, or there is nothing in the project");
        }
        else
            printf("Matrix %s has %d columns\n",mlay.GetPage().GetName(),mlay.GetNumCols());

Summary:
Sample data:
Header file: wksheet.h
See also:


Open

MatrixLayer::Open
Prototype:
PUBLIC  BOOL Open(LPCSTR lpcszFileName, int nOption = CREATE_VISIBLE)
Remarks: Opens a new matrix from the supplied OGM file and attaches it to the object.
Parameters:
lpcszTemplate = the OGM file name
nOption	= enum {
CREATE_TEMP = 0,		// it will be destroyed when destroying the object (when it exits the scope) and is created invisible
CREATE_VISIBLE_SAME,	// visibility is that which is stored in the OGM file
CREATE_VISIBLE,			// create visible
CREATE_HIDDEN,			// create hidden
};

Return values:
TRUE for success; otherwise FALSE.

Example:
        void	matrix_open()
        {
            MatrixLayer	mat;
            string		strOGM = "c:\\c\\vc32\\junk1.ogm";

            int			nOption = CREATE_VISIBLE_SAME;
            BOOL		bRet = mat.Open(strOGM, nOption);

            out_int("bRet = ", bRet);
        }

Summary:
Sample data:
Header file: wksheet.h
See also:


PutSPCBlob

MatrixLayer::PutSPCBlob
Prototype:
PUBLIC  BOOL PutSPCBlob(_VARIANT &varBlob)
Remarks: It puts the data from an SPC blob into the matrix This function is available only for OriginPro versions, or with a special COM enabled license
Parameters:
varBlob = the VARIANT blob containing the data

Return values:
TRUE for success; otherwise FALSE

Example:
        void	blob_to_matrix()
        {
            Object			oSpcIO;
            string			strPathName = "E:\\myfile.spc";

            oSpcIO = CreateObject("GSpcIOLib.GSpcIO");	// the GRAMS object used for importing the SPC file

            oSpcIO.OpenFile(strPathName);

            _VARIANT		varBlob;

            varBlob = oSpcIO.SaveBlob();

            MatrixLayer		mm("Matrix1");
            BOOL			bRet = mm.PutSPCBlob(varBlob);

            out_int("Return value from PutSPCBlob is ", bRet);
        }

Summary:
Sample data:
Header file: wksheet.h
See also:


SetCellWidth

MatrixLayer::SetCellWidth
Prototype:
PUBLIC  BOOL SetCellWidth(uint nCellWidth)
Remarks: Set the matrix cell width
Parameters:
nCellWidth = The width of the cell

Return values:
TRUE for success; otherwise FALSE.

Example:
        MatrixLayer mm("Matrix1");
        mm.SetCellWidth(5);

Summary:
Sample data:
Header file: wksheet.h
See also:


SetInternalData

MatrixLayer::SetInternalData
Prototype:
PUBLIC  BOOL SetInternalData(UINT iType, BOOL bSaveData=TRUE, BOOL bSetViewData = TRUE)
Remarks: Set all matrix objects in layer to FSI_DOUBLE, FSI_BYTE and etc. If matrix is already the correct internal type, this function will do nothing. If the matrix only has image without data, bSaveData set to TRUE will convert the image into data so that HasData will become TRUE after this command.
Parameters:
iType = FSI_* constants defined in oc_const.h
bSaveData = whether to backup the data before type change and attempt to restore afterwords.
Set this to FALSE if you don't need the data in the matrix to make this operation faster.

Return values:

Example:
        MatrixLayer mm("Matrix1");
        mm.SetInternalData(FSI_USHORT);	// make	Matrix1 ushort and keep its data and show as data

Summary:
Sample data:
Header file: wksheet.h
See also: GetInternalData


SetNumCols

MatrixLayer::SetNumCols
Prototype:
PUBLIC  BOOL SetNumCols(uint nCols)
Remarks: Set the number of columns in a MatixLayer.
Parameters:
nCols=Input number of columns to set

Return values:
Returns TRUE on successful exit and FALSE on failure.

Example:
        MatrixLayer ml("Matrix1");
        ml.SetNumCols(50);

Summary: Set the number of columns in a MatixLayer.
Sample data:
Header file: wksheet.h
See also: GetNumRows SetNumRows GetNumCols


SetViewImage

MatrixLayer::SetViewImage
Prototype:
PUBLIC  BOOL SetViewImage(BOOL bSetViewImage = TRUE)
Remarks:
Parameters:
bSetViewImage = TRUE to set matrix as View Image mode, FALSE to set matrix as View Data mode

Return values:
TRUE if success; otherwise FALSE

Example:
        MatrixLayer mm("Matrix1");
        Matrix MM("Matrix1");
        MM.SetSize(32,32);
        MM = 20;
        mm.SetViewImage(TRUE);

Summary:
Sample data:
Header file: wksheet.h
See also:


MatrixObject

Class: MatrixObject

Description: The MatrixObject class provides methods and properties common to internal Origin matrix objects. An Origin C MatrixObject is primarily used for style related control of the data in the internal Origin matrix while the Origin C Matrix class is used to access the data in the matrix. Thus, the MatrixObject class has the same relationship with the Matrix class as the Column class has with the Dataset class. That is, an internal Origin matrix object (accessed by the MatrixObject class) holds a matrix data set (accessed by the Matrix class) just as a worksheet column (accessed by the Column class) holds a data set (accessed by the Dataset class). The data values displayed in the cells of a matrix are typically referred to as Z values whose associated X values are linearly mapped to the columns of the matrix and whose associated Y values are linearly mapped to the rows of the matrix. A MatrixLayer holds a collection of MatrixObjects even though in most cases there is only one MatrixObject per MatrixLayer. An Origin C MatrixObject is a wrapper object that is a reference to an internal Origin matrix object. Wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The MatrixObject class is derived from the DataObject, DataObjectBase, and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 DataObjectBase
 DataObject
 MatrixObject

Sample:

        MatrixLayer ml = Project.ActiveLayer();
        if(ml)
            foreach(MatrixObject mo in ml.MatrixObjects)
                printf( "%s is %d x %d\n", ml.GetPage().GetName(), mo.GetNumRows(), mo.GetNumCols());


GetColumnWidth

MatrixObject::GetColumnWidth
Prototype:
PUBLIC  int GetColumnWidth()
Remarks: Remarks: Gets the width of a matrix column.
Parameters:
NONE

Return values:
width of the column

Example:
            void test_MatrixObject_SetDigits()
            {
                    MatrixObject moMy("Matrix1", 0);
                    printf("the column witdh of Matrix1 is %d", moMy.GetColumnWidth());
            }

Summary:
Sample data:
Header file: wksheet.h
See also:


GetDataObject

MatrixObject::GetDataObject
Prototype:
PUBLIC  matrixbase& GetDataObject()
Remarks: Puts the active Matrix window's data into a matrix data object.
Parameters:

Return values:
Return:
A matrix containing the data of Matrix window.

Example:
           void eg2_matrix()
           {
                 MatrixLayer mlActive = Project.ActiveLayer();
                 if(mlActive == NULL)
                return;

                 matrix<double> ma(mlActive.MatrixObjects(0).GetDataObject());

                 matrix<double> mb;
                 mb = mlActive.MatrixObjects(0).GetDataObject();
            // ...
           }

Summary:
Sample data:
Header file: wksheet.h
See also:


GetDigitMode

MatrixObject::GetDigitMode
Prototype:
PUBLIC  int GetDigitMode()
Remarks: Remarks: Gets the digit mode of the matrix. There are 3 modes: 0 for default decimal digits 1 for decimal digits 2 for significant digits
Parameters:
NONE

Return values:
the integer code representing the format

Example:
            void test_MatrixObject_GetDigitMode()
            {
                    MatrixObject moMy("Matrix1", 0);
                    printf("the data format in the matrix is %d", moMy.GetDigitMode());
            }

Summary:
Sample data:
Header file: wksheet.h
See also:


GetDigits

MatrixObject::GetDigits
Prototype:
PUBLIC  int GetDigits()
Remarks: Remarks: Gets the number of digits of a particular digit mode of the matrix.
Parameters:
NONE

Return values:
the number of digits set in a particular mode

Example:
            void test_MatrixObject_GetDigits()
            {
                    MatrixObject moMy("Matrix1", 0);
                    if (moMy.SetDigitMode(2))
                        out_str("Digit mode is set successfully!");
                    else
                        out_str("Digit mode is not set successfully!");
                    printf("the number of significant digits are %d", moMy.GetDigits());
            }

Summary:
Sample data:
Header file: wksheet.h
See also:


GetFormat

MatrixObject::GetFormat
Prototype:
PUBLIC  int GetFormat()
Remarks: Remarks: Gets the data format of the matrix.
Parameters:

Return values:
the integer code representing the format

Example:
            void test_MatrixObject_GetFormat()
            {
                    MatrixObject moMy("Matrix1", 0);
                    if (moMy.SetFormat(OKCOLTYPE_NUMERIC))
                        out_str("Format setting successfully!");
                    else
                        out_str("Format setting error!");
                    printf("the data format in the matrix is %d", moMy.GetFormat());
            }

Summary:
Sample data:
Header file: wksheet.h
See also:


GetImageMask

MatrixObject::GetImageMask
Prototype:
PUBLIC  BOOL GetImageMask(matrix<byte>& mMask)
Remarks: GetImageMask() will get MatrixObject's image mask. The mask of an Origin image is an one byte DIB image. This method will first set the Origin C matrix data object to have same dimensions as the image mask, then, copy all bytes from the mask image to corresponding locations in Origin C matrix data object. If the return is TRUE, the Origin C matrix data object will have the mask image data.
Parameters:
mMask = An Origin C matrix data object to retrieve image mask. Its type is matrix<byte>.

Return values:
TRUE/FALSE. TRUE indicates the mask has been retrieved successfully. Otherwise, return FALSE

Example:
            MatrixObject mObj("Matrix1", 0);  //assume Matrix1 exists
            matrix<byte> mMask;
            if( mObj.GetImageMask(mMask) )
            {
                printf("The mask is retrieved\n");
                printf("Numder of rows are: %d, Number of Cols are: %d\n", mMask.GetNumRows(), mMask.GetNumCols());

                MatrixObject mObj2("Matrix2", 0);
                mObj2.SetImageMask(mMask);
            }

Summary:
Sample data:
Header file: wksheet.h
See also: SetImageMask


GetIndex

MatrixObject::GetIndex
Prototype:
PUBLIC  int GetIndex()
Remarks: Gets the number of columns in the matrix
Parameters:

Return values:
number of columns in the matrix

Example:
            MatrixLayer mlay = Project.ActiveLayer();
            MatrixObject mobj (mlay, 0);
            printf("the index of the selected matrix is %d", mobj.GetIndex());

Summary:
Sample data:
Header file: wksheet.h
See also:


GetInternalData

MatrixObject::GetInternalData
Prototype:
PUBLIC  int GetInternalData()
Remarks: Get internal data type
Parameters:

Return values:
Internal data type of matrix

Example:
            MatrixLayer mlay = Project.ActiveLayer();
            if(!mlay) return;
            MatrixObject mobj = mlay.MatrixObjects(0);// Most MatrixLayer objects in Origin has only one MatrixObject
            if(mobj.SetInternalData(FSI_BYTE,TRUE,FALSE))
            {
                ASSERT(mobj.GetInternalData() == FSI_BYTE);
            }

Summary:
Sample data:
Header file: wksheet.h
See also: SetInternalData


GetNumCols

MatrixObject::GetNumCols
Prototype:
PUBLIC  int GetNumCols()
Remarks: Gets the number of columns in the matrix.
Parameters:

Return values:
number of columns in the matrix

Example:
        MatrixLayer mlay = Project.ActiveLayer();
        MatrixObject mobj (mlay, 0);
        printf("the number of columns in the selected matrix are %d", mobj.GetNumCols());

Summary:
Sample data:
Header file: wksheet.h
See also:


GetNumRows

MatrixObject::GetNumRows
Prototype:
PUBLIC  int GetNumRows()
Remarks: Gets the number of rows in the matrix.
Parameters:

Return values:
number of rows in the matrix

Example:
            MatrixLayer mlay = Project.ActiveLayer();
            MatrixObject mobj (mlay, 0);
            printf("the number of rows in the selected matrix are %d", mobj.GetNumRows());

Summary:
Sample data:
Header file: wksheet.h
See also:


MatrixObject

MatrixObject::MatrixObject
Prototype:
PUBLIC  MatrixObject(DataObject& OriginalObj)
Remarks: Copy constructor.
Parameters:
OriginalObj = an object of DataObject which is a base class for MatrixObject

Return values:

Example:
            MatrixObject moMy1("matrix1", 0);
            MatrixObject moMy2(moMy1);

Summary: Copy constructor -- refers to the same internal object as colOriginal
Sample data:
Header file: wksheet.h
See also:
MatrixObject::MatrixObject
Prototype:
PUBLIC  MatrixObject()
Remarks: Default constructor.
Parameters:

Return values:
Return:

Example:
        MatrixObject moMy();;

Summary:
Sample data:
Header file: wksheet.h
See also:
MatrixObject::MatrixObject
Prototype:
PUBLIC  MatrixObject(MatrixLayer & mLayer, UINT nObjectIndex)
Remarks: This constructor initializes a user-defined matrix object with one of the objects in the ActiveLayer, if the ActiveLayer is a MatrixLayer.
Parameters:
mLayer = MatrixLayer object which contains one or more matrix objects
nObjectIndex = Index of one of the matrix layers in the MatrixLayer
Presently only zero is supported, as a MatrixLayer can have only one object

Return values:

Example:
        MatrixLayer ml = Project.ActiveLayer();
        MatrixObject moMy(ml, 0);
        if(moMy) out_str("It is a mtarix!");
        else out_str("It is not a mtarix!");

Summary:
Sample data:
Header file: wksheet.h
See also:
MatrixObject::MatrixObject
Prototype:
PUBLIC  MatrixObject(LPCTSTR MatrixName, UINT nObjectIndex)
Remarks: This constructor initializes a user-defined matrix object with one of the objects in the MatrixLayer.
Parameters:
MatrixName = name of the MatrixLayer object
nObjectIndex = Index of one of the matrix objects in the MatrixLayer object.
Presently only zero is supported, as a MatrixLayer can have only one object

Return values:

Example:
        MatrixObject moMy("matrix1", 0);
        if(moMy) out_str("matrix1 exists");
        else out_str("matrix1 doesn't exist!");

Summary:
Sample data:
Header file: wksheet.h
See also:


SetColumnWidth

MatrixObject::SetColumnWidth
Prototype:
PUBLIC  BOOL SetColumnWidth(int nColWidth)
Remarks: Remarks: Sets the width of a matrix column.
Parameters:
nColWidth = user defined width of the column

Return values:
TRUE if successful; FALSE otherwise

Example:
            void test_MatrixObject_SetDigits()
            {
                    MatrixObject moMy("Matrix1", 0);
                    if (moMy.SetColumnWidth(5))
                        out_str("Coluimn width is set successfully!");
                    else
                        out_str("Coluimn width is not set successfully!");
                    printf("the column witdh of Matrix1 is %d", moMy.GetColumnWidth()); //should be 5
            }

Summary:
Sample data:
Header file: wksheet.h
See also:


SetDigitMode

MatrixObject::SetDigitMode
Prototype:
PUBLIC  BOOL SetDigitMode(int nDigitMode)
Remarks: Remarks: Sets the digit mode of the matrix. There are 3 modes: 0 for default decimal digits 1 for decimal digits 2 for significant digits
Parameters:
nDigitMode = 0 for default decimal digits
1 for decimal digits
2 for significant digits

Return values:
TRUE if successful; otherwise false

Example:
            void test_MatrixObject_SetDigitMode()
            {
                    MatrixObject moMy("Matrix1", 0);
                    if (moMy.SetDigitMode(0))
                        out_str("Digit mode is set successfully!");
                    else
                        out_str("Digit mode is not set successfully!");
            }

Summary:
Sample data:
Header file: wksheet.h
See also:


SetDigits

MatrixObject::SetDigits
Prototype:
PUBLIC  BOOL SetDigits(int nDigits)
Remarks: Remarks:Sets the number of digits of a particular digit mode of the matrix.
Parameters:
nDigits = number of digits

Return values:
TRUE if successful; FALSE otherwise

Example:
            void test_MatrixObject_SetDigits()
            {
                    MatrixObject moMy("Matrix1", 0);
                    if (moMy.SetDigitMode(2)) // 2 -> significant digits
                        out_str("Digit mode is set successfully!");
                    else
                        out_str("Digit mode is not set successfully!");
                    moMy.SetDigits(4);
                    printf("the number of significant digits are %d", moMy.GetDigits());
            }

Summary:
Sample data:
Header file: wksheet.h
See also:


SetFormat

MatrixObject::SetFormat
Prototype:
PUBLIC  BOOL SetFormat(int nFormat)
Remarks: Set the Matrix data format. Only OKCOLTYPE_NUMERIC is supported at present time.
Parameters:
iFormat = the column format,enum {
OKCOLTYPE_NUMERIC,
OKCOLTYPE_TEXT,
OKCOLTYPE_TIME,
OKCOLTYPE_DATE,
OKCOLTYPE_MONTH,
OKCOLTYPE_WEEKDAY,
OKCOLTYPE_TEXT_NUMERIC}

Return values:
TRUE, set the Matrix format successfully, FALSE, unsuccessful.

Example:
        void test_MatrixObject_SetFormat()
        {
                MatrixObject moMy("Matrix1", 0);
                if (moMy.SetFormat(OKCOLTYPE_NUMERIC))
                    out_str("Format setting successfully!");
                else
                    out_str("Format setting error!");
        }

Summary: only supports OKCOLTYPE_NUMERIC
Sample data:
Header file: wksheet.h
See also: SetFormat


SetImageMask

MatrixObject::SetImageMask
Prototype:
PUBLIC  BOOL SetImageMask(matrix<byte>& mMask)
Remarks: SetImageMask() method will set MatrixObject's image mask. It creates an one byte DIB from data of the Origin C matrix data object, then, sets that DIB image as image mask for the MatrixObject.
Parameters:
mMask = mMask = An Origin C matrix data object to retrieve image mask. Its type is matrix<byte>.

Return values:
TRUE/FALSE. TRUE indicates the mask has been retrieved successfully. Otherwise, return FALSE

Example:
            MatrixObject mObj("Matrix1", 0);  //assume Matrix1 exists
            matrix<byte> mMask;
            if( mObj.GetImageMask(mMask) )
            {
                printf("The mask is retrieved\n");
                printf("Numder of rows are: %d, Number of Cols are: %d\n", mMask.GetNumRows(), mMask.GetNumCols());

                MatrixObject mObj2("Matrix2", 0);
                mObj2.SetImageMask(mMask);
            }

Summary:
Sample data:
Header file: wksheet.h
See also: GetImageMask


SetInternalData

MatrixObject::SetInternalData
Prototype:
PUBLIC  BOOL SetInternalData(UINT iType, BOOL bSaveData=TRUE, BOOL bSetViewData = TRUE)
Remarks: Set the Matrix internal data types (This is a characteristic of numeric format)
Parameters:
iType = the internal type of a matrix, can be one of the followings
FSI_DOUBLE,
FSI_REAL,
FSI_SHORT,
FSI_LONG,
FSI_CHAR,
FSI_BYTE,
FSI_USHORT,
FSI_ULONG
bSaveData = when changing internal data type, we can keep the original data by converting them to the new type
bSetViewData = TRUE will turn the Matrix into View Data mode after the data type change. FALSE will keep current view mode

Return values:
TRUE, set the Matrix internal type successfully, FALSE, unsuccessful.

Example:
            MatrixLayer mlay = Project.ActiveLayer();
            if(!mlay) return;
            MatrixObject mobj = mlay.MatrixObjects(0);// Most Matrix in Origin has only one MatrixObject
            if(mobj.SetInternalData(FSI_BYTE,TRUE,FALSE))
                out_str("succefully converted into BYTE matrix");

Summary:
Sample data:
Header file: wksheet.h
See also: SetInternalData


MatrixPage

Class: MatrixPage

Description: The MatrixPage class provides methods and properties common to all internal Origin matrix pages (windows). The Project class contains a collection of MatrixPage objects. An Origin C MatrixPage object is a wrapper object that is a reference to an internal Origin matrix page object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The MatrixPage class is derived from the Page, PageBase, and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 PageBase
 Page
 MatrixPage

Sample:

        // Assumes Matrix1 window exists in Origin
        MatrixPage mp;
        MatrixLayer ml;

        mp = Project.MatrixPages("Matrix1");     // Get Matrix1 page from MatrixPages collection
        if(mp)                                   // If mp IsValid...
        {
            ml = (MatrixLayer) mp.Layers(0);     // Get Matrix1 Layer from Layers collection
            if(ml)                               // If ml IsValid...
            {
                MatrixObject mo(ml,0);           // Get first MatrixObject in Layer
                if(mo)                           // If mo IsValid...
                {
                    printf("%s is %d columns x %d rows\n", mp.GetName(), mo.GetNumCols(), mo.GetNumRows() );
                }
            }
        }


MatrixPage

MatrixPage::MatrixPage
Prototype:
PUBLIC  MatrixPage(LPCTSTR lpcszName)
Remarks: Construct a MatrixPage object using the name of an existing page.
Parameters:
lpcszName = The name of an existing page.

Return values:

Example:
        MatrixPage mp;
        mp.Create("origin.otm");
        if( mp.IsValid() )
        {
            MatrixPage mp2(mp.GetName());
            if( mp2.IsValid() )
                printf("mp and mp2 are both attached to '%s'\n", mp2.GetName());
        }

Summary:
Sample data:
Header file: Page.h
See also: Create
MatrixPage::MatrixPage
Prototype:
PUBLIC  MatrixPage(PageBase &page)
Remarks: Construct a MatrixPage object using an existing page object.
Parameters:
page = An existing page object.

Return values:

Example:
        MatrixPage mp;
        mp.Create("origin.otm");
        if( mp.IsValid() )
        {
            MatrixPage mp2(mp);
            if( mp2.IsValid() )
                printf("mp and mp2 are both attached to '%s'\n", mp2.GetName());
        }

Summary:
Sample data:
Header file: Page.h
See also: Create


Note

Class: Note

Description: The Note class provides methods and properties common to all internal Origin Note pages (windows). The Project class contains a collection of Note objects. An Origin C Note object is a wrapper object that is a reference to an internal Origin Note page. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The Note class is derived from the PageBase and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 PageBase
 Note

Sample:

        // Assumes Notes window exists in Origin
        Note no;
        no = Project.Notes("Notes");           // Get Notes page from Notes collection
        if(no)                                 // If no IsValid...
        {
            no.Rename("MyNotes");              // Rename Notes window to MyNotes
        }


Create

Note::Create
Prototype:
PUBLIC  BOOL Create(int nOption = CREATE_VISIBLE, LPCSTR lpcszFilePathName = NULL)
Remarks: Creates either a new empty Notes (page) window, or a new Notes window with the contents of a sepcified text file.
Parameters:
nOption = (optional) creating options. Possible values are:
CREATE_VISIBLE - creates a visible Notes page (window)
CREATE_HIDDEN - creates a hidden Notes page
lpcszFilePathName = (optional) the full pathname of the text file
to load into the new page. If NULL, an empty
page is created.

Return values:
TRUE for success, otherwise FALSE.

Example:
        void	run_this()
        {
            Note		pg;
            // Create a new empty Notes window:
            if (pg.Create())
            {
                printf("The name of the new Notes page is %s\n", pg.GetName());
            }
            else
                out_str("Creating a Notes page failed!");
        }

Summary:
Sample data:
Header file: Page.h
See also:


Note

Note::Note
Prototype:
PUBLIC  Note(LPCTSTR lpcszName)
Remarks: Construct a Note object using the name of an existing page.
Parameters:
lpcszName = The name of an existing page.

Return values:

Example:
        LT_execute("win -n n MyNotes;");
        Note note("MyNotes");
        if( note.IsValid() )
        {
            Note note2(note.GetName());
            if( note2.IsValid() )
                printf("note and note2 are both attached to '%s'\n", note2.GetName());
        }

Summary:
Sample data:
Header file: Page.h
See also: Create
Note::Note
Prototype:
PUBLIC  Note(PageBase &page)
Remarks: Construct a Note object using an existing page object.
Parameters:
page = An existing page object.

Return values:

Example:
        LT_execute("win -n n MyNotes;");
        Note note("MyNotes");
        if( note.IsValid() )
        {
            Note note2(note);
            if( note2.IsValid() )
                printf("note and note2 are both attached to '%s'\n", note2.GetName());
        }

Summary:
Sample data:
Header file: Page.h
See also: Create


OriginObject

Class: OriginObject

Description: The OriginObject class is the base class for all internal Origin objects and provides the methods and properties common to all Origin objects.

Hierarchy:

OriginObject

Sample:

        // If a worksheet is the active window in Origin than wks will be valid
        Worksheet wks;
        wks = (Worksheet) Project.ActiveLayer();
        if(wks.IsValid())
            out_str("Worksheet is Valid!");
        else
            out_str("Worksheet is not Valid!");


ApplyFormat

OriginObject::ApplyFormat
Prototype:
PUBLIC  BOOL ApplyFormat(const TreeNode& trNode, BOOL bRepaint = TRUE)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OrgObj.h
See also:


Destroy

OriginObject::Destroy
Prototype:
PUBLIC  BOOL Destroy()
Remarks: DestroyObject If the Origin object is a layer and it is the only one in the window, then also destroy the window (page).
Parameters:

Return values:
TRUE for success

Example:
        Worksheet wks("Data1");
        ASSERT(wks.IsValid());
        wks.Destroy();
        ASSERT(!wks.IsValid());

Summary:
Sample data:
Header file: OrgObj.h
See also:


GetFormat

OriginObject::GetFormat
Prototype:
PUBLIC  Tree GetFormat(DWORD dwPropertiesFilter = FPB_ALL, DWORD dwObjFilter = FOB_ALL)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OrgObj.h
See also:


GetMemory

OriginObject::GetMemory
Prototype:
PUBLIC  BOOL GetMemory(LPCSTR lpcszName, vector<byte>& vb)
Remarks: get named binary storage into vector of bytes Paramteres lpcszName = storage name, must be valid C identifier vb = vector of bytes to be retrived
Parameters:

Return values:
TRUE if success FALSE if name storage does not exist

Example:
        test_read()
        {
            Page pg = Project.Pages();
            if(!pg)
                return;

            vector<byte> vb;
            if(pg.GetMemory("Test", vb))
            {
                string strContents;
                if(strContents.SetBytes(vb))
                    strContents.Write(WRITE_COMPILER_OUTPUT);
            }
        }

Summary:
Sample data:
Header file: OrgObj.h
See also:


GetParent

OriginObject::GetParent
Prototype:
PUBLIC  void GetParent(OriginObject& obj)
Remarks: Retrieve parent of origin object.
Parameters:
obj = reference to object to which parent will be attached.

Return values:

Example:
        Column col("Data1", 0");
        Worksheet wks;
        col.GetParent(wks); // wks is worksheet to which column belongs.

Summary:
Sample data:
Header file: OrgObj.h
See also:


GetStorage

OriginObject::GetStorage
Prototype:
PUBLIC  storage GetStorage(LPCSTR lpcszName, bool bAdd = FALSE)
Remarks:
Parameters:

Return values:

Example:
            void Run_GetStorage()
            {
                Tree	tr;
                storage st;
                vector<string> vsName;
                Page pg = Project.Pages();

                pg.GetStorageNames(vsName);

                st = pg.GetStorage("system");
                tr = st;
                out_tree(tr);
            }

Summary:
Sample data:
Header file: OrgObj.h
See also:


GetStorageNames

OriginObject::GetStorageNames
Prototype:
PUBLIC  BOOL GetStorageNames(vector<string> &vsNames)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OrgObj.h
See also: GetStorage


GetUID

OriginObject::GetUID
Prototype:
PUBLIC  UINT GetUID(BOOL bCreate = FALSE)
Remarks: Provides internal unique identification number of Origin object
Parameters:
bCreate = create ID if it was not created yet

Return values:
0 if ID for object was not created. Object unique ID otherwise

Example:
        void Run_GetUID()
        {
            Page pg = Project.Pages();
            UINT uID = pg.GetUID(TRUE);
            printf("%u",uID);
        }

Summary:
Sample data:
Header file: OrgObj.h
See also:


IsValid

OriginObject::IsValid
Prototype:
PUBLIC  BOOL IsValid()
Remarks: Checks Validity of the Origin object.
Parameters:

Return values:
FALSE if an Origin Object is not valid, non-zero otherwise.

Example:
            void test(Worksheet& aa)
            {
                if(aa.IsValid())
                    out_str("Worksheet is Valid!");
                else
                    out_str("Worksheet not Valid!");
            }

Summary:
Sample data:
Header file: OrgObj.h
See also:


OriginObject

OriginObject::OriginObject
Prototype:
PUBLIC  OriginObject()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: OrgObj.h
See also:


SetMemory

OriginObject::SetMemory
Prototype:
PUBLIC  BOOL SetMemory(LPCSTR lpcszName, vector<byte>& vb)
Remarks: set/create named binary storage Paramteres lpcszName = storage name, must be valid C identifier vb = vector of bytes to be saved
Parameters:

Return values:
TRUE if success

Example:
        string get_file(LPCSTR lpcszFilename)
        {
            string str;
            stdioFile ff;
            bool bRet = ff.Open(lpcszFilename, file::modeRead);
            if(!bRet)
            {
                out_str("file not found!");
                return str;
            }

            string strTemp;
            while(ff.ReadString(strTemp))
                str += strTemp + "\r\n";

            ff.Close();

            return str;
        }
        test_save()
        {
            Page pg = Project.Pages();
            if(!pg)
                return;

            string strFilename = GetAppPath() + "origin.ini";
            string strFileContent = get_file(strFilename);

            vector<byte> vb;
            if(strFileContent.GetBytes(vb) && pg.SetMemory("Test", vb))
                out_str("Saving origin.ini into page.info done");
        }

Summary:
Sample data:
Header file: OrgObj.h
See also:


Show

OriginObject::Show
Prototype:
PUBLIC  BOOL Show(BOOL bShow = TRUE)
Remarks: Show or hide the Origin object
Parameters:
bShow = optional argument (TRUE to show the object, FALSE - to hide)

Return values:
TRUE for success, otherwise FALSE

Example:
        Page page("Data1");
        page.Show(FALSE);	// hide worksheet page

Summary:
Sample data:
Header file: OrgObj.h
See also:


OriginSettings

Class: OriginSettings

Description: The OriginSettings class provides methods and properties to access different customizable settings of Origin.

Hierarchy:

OriginSettings

Sample:

        // get types of file that can be imported into the active page
        // and bring up "Open File" dialog box
        void test()
        {
            StringArray saTypes;
            PageBase pg = Project.Pages();
            Project.Settings.GetUserTypes(saTypes, pg.GetType());
            string strPath = GetOpenBox(saTypes);
            printf("File name is \"%s\"", strPath);
        }


GetUserTypes

OriginSettings::GetUserTypes
Prototype:
PUBLIC  void GetUserTypes(StringArray& saTypes, int nGroup)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Settings.h
See also:


OriginSettings

OriginSettings::OriginSettings
Prototype:
PUBLIC  OriginSettings()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Settings.h
See also:


Page

Class: Page

Description: The Page class provides methods and properties common to all internal Origin pages that contain one or more layers (all Origin windows except Note windows). The Page class contains a collection of all layers in the page. An Origin C Page object is a wrapper object that is a reference to an internal Origin page object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The Page class is derived from the PageBase and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 PageBase
 Page

Sample:

        // Assumes Origin page with graph (text, arrow, rectangle, etc.) object is active window
        Page pg;
        pg = (Page) Project.Pages(); // Get the project's active page
        if( pg.IsValid() )
        {
            Layer lyr;
            lyr = pg.Layers(0); // Get first layer in page
            if( pg.IsValid() )
            {
                GraphObject go;
                go = lyr.GraphObjects(0); // Get first GraphObject in layer
                printf("Name of GraphObject is %s\n", go.GetName());
            }
        }


Create

Page::Create
Prototype:
PUBLIC  BOOL Create(LPCSTR lpcszTemplate = NULL, int iOption = CREATE_VISIBLE)
Remarks: Create a new page using the supplied template and attach it to the object. The Create method should only be called from derived classes.
Parameters:
lpcszTemplate = The template file name to create the page from.
Pass an empty string or NULL to use the default template.
Pass "0" to create without a template.
iOption = How the window should be created.
Must be one of the following:
CREATE_TEMP = Create invisible and destroy on exit of scope.
CREATE_VISIBLE_SAME = Create with a visibility setting the same as what is stored in the template.
CREATE_VISIBLE = Create visible.
CREATE_HIDDEN = Create the page so it appears hidden in Proejct Explorer.
The following flags can be OR'ed with the above options:
CREATE_NO_REMOVE_TEMPLATEPICT = Do not remove template preview picture (graphic object) on loading.
CREATE_NO_GUI_ACCESS = Do not allow access from Project Explorer (only valid with CREATE_HIDDEN).

Return values:
TRUE for success or FALSE for failure.

Example:
        GraphPage gp;
        if( gp.Create("origin.otp", CREATE_VISIBLE_SAME) )
            printf("Created a graph named %s\n", gp.GetName());
        else
            printf("Failed to create graph page\n");

Summary:
Sample data:
Header file: Page.h
See also: PageBase


Layers

Page::Layers
Prototype:
PUBLIC  Layer Layers(int iIndex = -1)
Remarks: Get a layer object by index.
Parameters:
iIndex = The index of the layer requested to be accessed.
If -1 then the active layer is returned.

Return values:
If iIndex is valid then the layer to which the index refers is returned otherwise an invalid layer object is returned.

Example:
        // For this example to run, a Graph window must be the active window
        // in the project.
        void	run_Layers()
        {
            GraphPage	gp = Project.Pages();

            if( gp)
            {
                GraphLayer		gl = gp.Layers(); // Get active layer
                printf("%s has %d layer(s) with active layer %d\n", gp.GetName(), gp.Layers.Count(), gl.GetIndex() + 1); // show LabTalk index
            }
        }

Summary:
Sample data:
Header file: Page.h
See also:
Page::Layers
Prototype:
PUBLIC  Layer Layers(LPCSTR lpcszName)
Remarks: Get a layer object by name.
Parameters:
lpcszName = The name of the Layer requested to be accessed.

Return values:
If the name is valid then the layer to which the name refers is returned otherwise an invalid layer object is returned.

Example:
        // Assume Book1 is an Excel workbook with a Sheet1
        Page pg("Book1");
        Worksheet wks;
        wks = (Worksheet)pg.Layers("Sheet1");

Summary:
Sample data:
Header file: Page.h
See also:


LT_execute

Page::LT_execute
Prototype:
PUBLIC  BOOL LT_execute(LPCSTR lpcszScript, int wCtrl = 0)
Remarks: Execute a LabTalk script temporarily setting this page as the active page. This command is equivalent to LabTalk's "win -o" command. The original active page is restored after the script completes execution.
Parameters:
lpcszScript = LabTalk script to execute.
wCtrl = This argument is currently ignored.

Return values:
TRUE for success or FALSE for failure.

Example:
        // Output the template name for all the graphs in the project.
        foreach(GraphPage gp in Project.GraphPages)
            gp.LT_execute("win -g; type \"%h uses template %a\";");

Summary:
Sample data:
Header file: Page.h
See also:


Page

Page::Page
Prototype:
PUBLIC  Page()
Remarks: Default constructor for a Page object.
Parameters:

Return values:

Example:
        Page pg;
        pg = (Page) Project.Pages(); // Get the project's active page
        if( pg.IsValid() )
            printf("Active page is of type %d\n", pg.GetType());
        else
            printf("Active page is invalid\n");

Summary:
Sample data:
Header file: Page.h
See also: Create
Page::Page
Prototype:
PUBLIC  Page(LPCSTR lpcszName)
Remarks: Construct a Page object using the name of an existing page.
Parameters:
lpcszName = The name of an existing page.

Return values:

Example:
        void output_page_type(string strName)
        {
            Page pg(strName);
            if( pg.IsValid() )
                printf("Page %s is of type %d\n", strName, pg.GetType());
            else
                printf("Page %s is invalid\n", strName);
        }

        void test_output_page_type()
        {
            MatrixPage mp;
            mp.Create("origin.otm");
            if( mp.IsValid() )
                output_page_type(mp.GetName());
        }

Summary:
Sample data:
Header file: Page.h
See also: Create
Page::Page
Prototype:
PUBLIC  Page(PageBase &page)
Remarks: Construct a Page object using another Page object.
Parameters:
page = An existing Page object.

Return values:

Example:
        void output_page_type(Page &pg)
        {
            Page pgTemp(pg);
            if( pgTemp.IsValid() )
                printf("Page is of type %d\n", pgTemp.GetType());
            else
                printf("Page is invalid\n");
        }

        void test_output_page_type()
        {
            MatrixPage mp;
            mp.Create("origin.otm");
            if( mp.IsValid() )
                output_page_type(mp);
        }

Summary:
Sample data:
Header file: Page.h
See also: Create


Refresh

Page::Refresh
Prototype:
PUBLIC  void Refresh(BOOL bRedraw = FALSE)
Remarks: Refresh the page.
Parameters:
bRedraw = indicate if Origin will need to destroy all the internal drawing cache and recreate the graph.
FALSE will tell the page to simply repaint itself using existing cache.

Return values:

Example:
        Page pg = Project.Pages();
        pg.Refresh(TRUE);// slow refresh, redraw everything from data

Summary:
Sample data:
Header file: Page.h
See also:


PageBase

Class: PageBase

Description: The PageBase class provides methods and properties common to all internal Origin pages (windows). One use of this class is to write functions that accept a PageBase object rather than a page object of specific type. Another use is to attach a PageBase object to an active page whose page type is unknown. These uses facilitate writing general code that can then branch to handle specific page types. The PageBase object can be cast to an object of its page type in order to access methods and properties specific to its class. In general, however, the Origin C PageBase class is intended to be an abstract base class to be used for polymorphic handling of derived page types. Derived classes, such as Note, GraphPage, WorksheetPage, LayoutPage, and MatrixPage inherit PageBase class methods and should be used instead.

Hierarchy:

OriginObject
 PageBase

Sample:

        // Get active window...if not valid...
        PageBase pbActiveWindow;
        string strWindowName;
        int iPageType;

        pbActiveWindow = Project.Pages();
        if( !pbActiveWindow.IsValid() )
            return 1; // Return an error code

        // Get window name and type
        strWindowName = pbActiveWindow.GetName();
        iPageType = pbActiveWindow.GetType();

        // If window is not a worksheet or workbook...
        if( iPageType != EXIST_WKS && iPageType != EXIST_EXTERN_WKS )
            return 1; // Return an error code


Detach

PageBase::Detach
Prototype:
PUBLIC  BOOL Detach()
Remarks: Detach a Page object from a page. This will make the object invalid.
Parameters:

Return values:
TRUE for success or FALSE for failure.

Example:
        GraphPage gp;
        if( gp.Create("origin.otp", CREATE_VISIBLE_SAME) )
        {
            string strName = gp.GetName();
            printf("Created a graph named %s\n", strName);

            if( gp.Detach() )
                printf("Detached %s, IsValid == %d\n", strName, gp.IsValid());
            else
                printf("Failed to detach %s\n", strName);
        }
        else
            printf("Failed to create graph page.\n");

Summary:
Sample data:
Header file: Page.h
See also:


GetFolder

PageBase::GetFolder
Prototype:
PUBLIC  Folder GetFolder()
Remarks: get the folder of the page
Parameters:

Return values:
A valid Folder object if successful, otherwise a NULL object

Example:
        PageBase pbTemp = Project.Pages();
        if(pbTemp)
        {
           Folder fd = pbTemp.GetFolder();
           if(fd)
             printf("%s is at %s\n", pbTemp.GetName(), fd.GetPath());
           else
              printf("Error: %s is not in any folder, impossible!\n", pbTemp.GetName());
        }

Summary:
Sample data:
Header file: Page.h
See also:


GetName

PageBase::GetName
Prototype:
PUBLIC  BOOL GetName(string &strName)
Remarks: Get the name of the page.
Parameters:
strName = The string that will recieve the name of the page.

Return values:
TRUE for success or FALSE for failure.

Example:
        PageBase pb;
        pb = Project.Pages(); // Get the project's active page
        if( pb.IsValid() )
        {
            string strName;
            if( pb.GetName(strName) )
                printf("Active page is named %s\n", strName);
            else
                printf("Failed to get page name\n");
        }
        else
            printf("Active page is not valid\n");

Summary:
Sample data:
Header file: Page.h
See also: Rename
PageBase::GetName
Prototype:
PUBLIC  string GetName()
Remarks: Get the name of the page.
Parameters:

Return values:
The name of the page.

Example:
        PageBase pb;
        pb = Project.Pages(); // Get the project's active page
        if( pb.IsValid() )
            printf("Active page is named %s\n", pb.GetName());
        else
            printf("Active page is not valid\n");

Summary:
Sample data:
Header file: Page.h
See also: Rename


GetPageSystemInfo

PageBase::GetPageSystemInfo
Prototype:
PUBLIC  BOOL GetPageSystemInfo(PageSystemInfo *pInfo)
Remarks: Get the page's creation and last modified time, size, and number of dependents
Parameters:
pInfo=the pointer to a structure to receive the information:
typedef struct tagPageSystemInfo
{
double dCreated;
double dModified;
int nSize;
int nDependents;
} PageSystemInfo;

Return values:
TRUE if succeded, FALSE if failed.

Example:
        PageBase		pg = Project.Pages();
        PageSystemInfo	PgInfo;

        bool	bb = pg.GetPageSystemInfo(&PgInfo);

        double	dCreated = PgInfo.dCreated;
        double	dModified = PgInfo.dModified;
        int		nSize = PgInfo.nSize;
        int		nDependents = PgInfo.nDependents;

Summary:
Sample data:
Header file: Page.h
See also:


GetShow

PageBase::GetShow
Prototype:
PUBLIC  int GetShow()
Remarks: To get the show state of the page
Parameters:

Return values:
One of the values 	PAGE_NORMAL, PAGE_MINIMIZED, PAGE_MAXIMIZED, PAGE_HIDDEN,

Example:
        void all_pages_show_info()
        {

            foreach(PageBase pg in Project.Pages)
            {
                if(pg.GetShow() == PAGE_HIDDEN)
                    printf("%s is hidden\n", pg.GetName());
                else
                    printf("%s Show state is %d\n", pg.GetName(), pg.GetShow());
            }
        }

Summary:
Sample data:
Header file: Page.h
See also:


GetType

PageBase::GetType
Prototype:
PUBLIC  int GetType()
Remarks: Get the page type.
Parameters:

Return values:
A value representing the page type.  See the EXIST constants defined in oc_const.h, they are:
EXIST_WKS       2
EXIST_PLOT      3
EXIST_MATRIX    5
EXIST_LAYOUT	11
EXIST_EXTERN_WKS	12  (Excel workbook)

Example:
        PageBase pbTemp;
        pbTemp = Project.Pages(); // Get the project's active page
        if( pbTemp.IsValid() )
            printf("Active page is of type %d\n", pbTemp.GetType());
        else
            printf("Active page is not valid\n");

Summary: Get the page type.
Sample data:
Header file: Page.h
See also:


PageBase

PageBase::PageBase
Prototype:
PUBLIC  PageBase()
Remarks: Default constructor for a PageBase object.
Parameters:

Return values:

Example:
        PageBase pbTemp;
        pbTemp = Project.Pages(); // Get the project's active page
        if( pbTemp.IsValid() )
            printf("Active page is of type %d\n", pbTemp.GetType());
        else
            printf("Active page is invalid\n");

Summary: Default constructor.
Sample data:
Header file: Page.h
See also:
PageBase::PageBase
Prototype:
PUBLIC  PageBase(LPCSTR lpcszName)
Remarks: Construct a PageBase object using the name of an existing page.
Parameters:
lpcszName = The name of an existing page.

Return values:

Example:
        void output_page_type(string strName)
        {
            PageBase pb(strName);
            if( pb.IsValid() )
                printf("Page %s is of type %d\n", strName, pb.GetType());
            else
                printf("Page %s is invalid\n", strName);
        }

        void test_output_page_type()
        {
            MatrixPage mp;
            mp.Create("origin.otm");
            if( mp.IsValid() )
                output_page_type(mp.GetName());
        }

Summary:
Sample data:
Header file: Page.h
See also:
PageBase::PageBase
Prototype:
PUBLIC  PageBase(PageBase &page)
Remarks: Construct a PageBase object using another PageBase object.
Parameters:
page = An existing PageBase object.

Return values:

Example:
        void output_page_type(PageBase &pb)
        {
            PageBase pbTemp(pb);
            if( pbTemp.IsValid() )
                printf("Page is of type %d\n", pbTemp.GetType());
            else
                printf("Page is invalid\n");
        }

        void test_output_page_type()
        {
            MatrixPage mp;
            mp.Create("origin.otm");
            if( mp.IsValid() )
                output_page_type(mp);
        }

Summary:
Sample data:
Header file: Page.h
See also:


Print

PageBase::Print
Prototype:
PUBLIC  BOOL Print(TreeNode& tn)
Remarks: Print the page.
Parameters:
tn = tree node which stores settings related to printing.

Return values:
TRUE if succeded, FALSE if failed.

Example:
        GraphPage page("Graph1");								// page to print
        Tree tree;
        tree.Printing.PrinterName.strVal = "Canon Bubble-Jet BJC-2000";	// ignore default printer, use Canon instead
        tree.Printing.NumberOfCopies.nVal = 2;							// print 2 copies
        tree.Printing.DPI.nVal = 300;									// resolution 300 dpi
        BOOL bResult = page.Print(tree);

Summary:
Sample data:
Header file: Page.h
See also:


Rename

PageBase::Rename
Prototype:
PUBLIC  int Rename(LPCSTR lpcszNewName, BOOL bAskIfAlreadyUsed = FALSE)
Remarks: Change the name of the page. Please note that this function was changed from its original form BOOL Rename(string strNewName); to this new form in Origin 7 SR4, or Origin 8 Alpha3. The return values were setup such that old codes will still work correctly.
Parameters:
lpcszNewName = Pointer to the string that holds the new name of the page.
bAskIfAlreadyUsed = TRUE will bring up a dialog box to ask for a new name, FALSE will use internal enumeration for the next available name

Return values:
1 = given name is used to rename the page successfully,
0 = another name was used to rename the page, either through user input or through internal enumeration.
-1 = user click Cancel when ask for a different name to rename the page when bAskIfAlreadyUsed is set to TRUE.

Example:
        void	run_this()
        {
            PageBase	pg = Project.Pages(); // Get the active page
            if( pg )
            {
                string		strOldName = pg.GetName();
                string		strNewName = strOldName + "AA";
                if( pg.Rename(strNewName) >=0 )
                    printf("Page renamed from %s to %s\n", strOldName, strNewName);
                else
                    printf("Failed to rename page\n");
            }
            else
                printf("There is no Active page\n");
        }

Summary:
Sample data:
Header file: Page.h
See also: GetName


SetShow

PageBase::SetShow
Prototype:
PUBLIC  int SetShow(int nNewShow = PAGE_ACTIVATE)
Remarks: To open a hidden page, or to show a minimized window This function does the same thing as if double-clicking on the page in the Project explorer window if PAGE_ACTIVATE is used, which is not one of the show state that can be obtained from GetShow.
Parameters:

Return values:
the original show state of the page if successful. Returns -1 if operation failed.

Example:
        Worksheet wksTemp;
        if(wksTemp.Create(NULL, CREATE_HIDDEN))
        {
            // codes till fill wks with data

            // then show it at the end when all is done
            wksTemp.GetPage().Rename("MyNewWks");
            wksTemp.GetPage().SetShow();
        }

Summary:
Sample data:
Header file: Page.h
See also:


point

Class: point

Description: The point class provides methods and properties common to data points located in a two dimensional or planar space whose (x,y) coordinates are integers.

Hierarchy:

point

Sample:

        point pt(4, 7);
        printf("x = %d   y = %d\n", pt.x, pt.y);


point

point::point
Prototype:
PUBLIC  point(int x = 0, int y = 0)
Remarks: constructor which initializes a point object from x and y coordinates
Parameters:
x = (optional) x coordinate
y = (optional) y coordinate

Return values:

Example:
        void	run_point_Constructor()
        {
            point	pt(4, 7);

            printf("x = %d   y = %d\n", pt.x, pt.y);
        }

Summary:
Sample data:
Header file: graph.h
See also:
point::point
Prototype:
PUBLIC  point(point pp)
Remarks: Copy constructor which initializes the point object from another point object
Parameters:
pp = source point object

Return values:

Example:
        void	run_point_Constructor()
        {
            point	pt(4, 7);

            // Initialize pt2 from pt:
            point	pt2(pt);

            // Display pt2:
            printf("x = %d   y = %d\n", pt2.x, pt2.y);
        }

Summary:
Sample data:
Header file: graph.h
See also:


Project

Class: Project

Description: The Project class provides methods and properties to access many of the objects contained in an Origin project file. The Project class includes collections of all different page types and collections of loose data sets (data sets not in a worksheet column) and of all data sets in the Origin Project file. Several methods to get objects active in the Origin project file (such as ActiveCurve, ActiveLayer, and ActiveFolder) and a RootFolder property are also available. An Origin C Project object is a wrapper object that is a reference to an internal Origin project object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Only one project file at a time can be open in Origin consequently all Origin C Project objects refer to the same currently open project file.

Hierarchy:

Project

Sample:

        // try to count the total number layers in all graphs in project
        int nCount = 0;
        foreach(GraphPage gp in Project.GraphPages)
        {
            foreach(GraphLayer gl in gp.Layers)
            {
                nCount++;
            }
        }
        out_int("total number of layers=",nCount);
        out_str("");// another blank line


ActivateFolder

Project::ActivateFolder
Prototype:
PUBLIC  BOOL ActivateFolder(LPCSTR lpszPath)
Remarks: Set the project's active folder. Specified path can be relative or absolute and is not case sensitive.
Parameters:
lpszPath = the path to the folder to be activated. The path can be absolute, in which
case it has to start with the '/' character denoting the root folder, and
each subfolder is separated by a '/' character (example: "/mysub/musubsub")
or it can be relative to the current active folder, in which case the path
must not start with '/' (example: "mysub/mysubsub" where "mysub" is the subdolder
within the current active folder).

Return values:
TRUE for success, otherwise FALSE.
TRUE for success.

Example:
        // For this example to run, create a subfolder named "MySub" in the project's root folder.
        // Make sure that the root folder is active.
        // After the function executes, "MySub" will be the active folder.
        void	run_Project_ActivateFolder()
        {
            string		strPath = "/MySub";

            if (Project.ActivateFolder(strPath))
                out_str("Folder activation succeeded.");
            else
                out_str("Folder activation failed!");
        }

Summary:
Sample data:
Header file: Project.h
See also:


ActiveCurve

Project::ActiveCurve
Prototype:
PUBLIC  Curve ActiveCurve()
Remarks: The Active Curve in the active layer of the active page(window) Dataset, Curve and Matrix are different kinds of objects when compared with other Origin objects. Layers and Pages etc are pure wrapper classes for internal Origin objects so that you can make assignment between them and they will still be referencing the same internal Origin object. For example, both gg1 and gg2 below are the same thing GraphLayer gg1 = Layer("Graph1"); GraphLayer gg2; gg2 = gg1;// having two reference object to the same internal layer in Origin On the other hand, Datasets and Curves and Matrix are wrapper for data objects inside Origin and the assigment between them are interpreted as arithmetic assignments, so Curve cc("data1_a", "data1_c"); Curve dd("data1_a", "data1_d"); dd = cc;// put all values from Y column of cc into Y column of dd Due to this reason, you cannot do things like Curve cc = Project.ActiveCurve(); but rather, you should use Project.ActiveCurve directly or use the "using" notation.
Parameters:
None.

Return values:
the active Curve object

Example:
        // For this example to run, create a graph  with at least one dataplot.
        void	run_Project_ActiveCurve()
        {
            using cc = Project.ActiveCurve();
            if(cc.IsValid())
            {
                Dataset xd;
                printf("Active dataset is %s",cc.GetName());
                if(cc.AttachX(xd, FALSE))
                    printf(", its corresponding X dataset is %s",xd.GetName());

                printf(".\n");
            }
            else
                out_str("There is no active dataset");
        }

Summary:
Sample data:
Header file: Project.h
See also:


ActiveCurveBase

Project::ActiveCurveBase
Prototype:
PUBLIC  curvebase& ActiveCurveBase()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Project.h
See also:


ActiveFolder

Project::ActiveFolder
Prototype:
PUBLIC  Folder ActiveFolder()
Remarks: Gets the active folder in the project.
Parameters:
None.

Return values:
the active Folder object.

Example:
        // For this example to run, create a few folder in the project
        // using Project Explorer. Make one of the new folders active.
        void	run_Project_ActiveFolder()
        {
            // Get the active folder:
            Folder		fld = Project.ActiveFolder();

            // Get the name:
            string		strName = fld.GetName();

            // Display the name:
            out_str(strName);
        }

Summary:
Sample data:
Header file: Project.h
See also:


ActiveLayer

Project::ActiveLayer
Prototype:
PUBLIC  Layer ActiveLayer()
Remarks: It returns the active Layer object. The active Layer object corresponds to the active layer in the active window (graph, worksheet, matrix, or layout).
Parameters:
None.

Return values:
The active Layer object.

Example:
        // For this example to run, create a graph window with one or more dataplots.
        void	run_Project_ActiveLayer()
        {
            GraphLayer	gl = Project.ActiveLayer();
            if(gl)
            {
                printf("The current layer has %d plots\n", gl.DataPlots.Count());
            }
            else
                out_str("There is no active window or it is not a graph window");
        }

Summary:
Sample data:
Header file: Project.h
See also:


ClearModified

Project::ClearModified
Prototype:
PUBLIC  void ClearModified()
Remarks: Mark the active project as not modified. This is usually done before exiting or before loading another project in order to avoid the prompt asking the user to save it.
Parameters:
None.

Return values:
void

Example:
        // For this example to run, create a project, save it, and then modify it
        // (for example by modifying the value in a worksheet cell).
        void	run_Project_ClearModified()
        {
            if (Project.IsModified())
                out_str("Project has been modified");
            else
                out_str("Project has NOT been modified");

            // Now clear the modified flag:
            Project.ClearModified();

            // Now it must be NOT modifed because we cleared it above.
            if (Project.IsModified())
                out_str("Project has been modified");
            else
                out_str("Project has NOT been modified");
        }

Summary:
Sample data:
Header file: Project.h
See also:


CreateNewTheme

Project::CreateNewTheme
Prototype:
PUBLIC  Tree CreateNewTheme()
Remarks: Create new theme.
Parameters:
None.

Return values:
Tree.

Example:

Summary:
Sample data:
Header file: Project.h
See also:


DatasetNames

Project::DatasetNames
Prototype:
PUBLIC  string DatasetNames(int index)
Remarks: Gets the name of Dataset which is index'th element in the list. If index is ;arger than the number of datasets in the project, DatasetNames(int) generates to an execution error.
Parameters:
index = A number smaller than the number of datasets in the project. The datasets are enumerated
by the order in which they appear in the link list and have no special significance.

Return values:
return the name of the dataset.

Example:
        void run_Project_DatasetNames(int index)
        {
            string strName = Project.DatasetNames(index);
            printf("Dataset(%d) Name: %s\n",index, strName);

        }

Summary:
Sample data:
Header file: Project.h
See also:


DeleteOperation

Project::DeleteOperation
Prototype:
PUBLIC  BOOL DeleteOperation(OperationBase* op, BOOL bRemoveFromOperationList = FALSE)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Project.h
See also:


GetCommonColumns

Project::GetCommonColumns
Prototype:
PUBLIC  BOOL GetCommonColumns(const vector<string> &worksheets, vector<string> &columnNames, vector<string> &columnLabels, BOOL bKeepOrder = FALSE)
Remarks: It provides all the columns (by names or prefixes) that are common between the worksheets whose names are supplied. If only one worksheet is supplied, all its columns are returned.
Parameters:
worksheets = [in] the names of all the worksheets to consider. They are in the form WksPageName or WksPageName!WksLayerName
columnNames = [out] the names of all the common columns. There are certain restriction on which columns should be considered "common enough" to be included.
columnLabels = [out] the labels from the 1st worksheet for the corresponding columns
bKeepOrder = TRUE if common columns must follow same order as in the first worksheet, FALSE if the order of columns are not important

Return values:
TRUE if successful, FALSE otherwise

Example:
        void run_GetCommonColumns()
        {
            vector<string>  wksNames = {"Data1","Data2"};
            vector<string>  colNames;
            vector<string>  colLabels;

            BOOL bRet = Project.GetCommonColumns(wksNames, colNames, colLabels, FALSE);
        }

Summary:
Sample data:
Header file: Project.h
See also:


GetDataObject

Project::GetDataObject
Prototype:
PUBLIC  DataObject& GetDataObject(LPCSTR name)
Remarks: Creates a DataObject& from DataObject name
Parameters:
name = name of the DataObject

Return values:
A refernce to  DataObject (A MatrixObject or Column), if invalid name -- the object is invalid

Example:
    void test_Project_GetDataObject()
    {
       foreach (string strDatasetName in Project.DatasetNames)
       {
          DataObject& obj = Project.GetDataObject(strDatasetName);
          if(obj.IsValid())
          {
               printf("Dataset  is  in some wks/matrix\n", strDatasetName);
          }
          else
          {
               printf("Dataset %s is not in any wks/matrix\n", strDatasetName);
          }
       }
    }

Summary:
Sample data:
Header file: Project.h
See also:


GetDatasetInfo

Project::GetDatasetInfo
Prototype:
PUBLIC  DWORD GetDatasetInfo(LPCTSTR lpcszDatasetName, BOOL bNeedFolderInfo = FALSE)
Remarks: Get Dataset information
Parameters:
lpcszDatasetName = name of the Dataset object
bNeedFolderInfo = get folder info, otherwise not

Return values:
return value defined in oc_const.h, can be one of the followings
PGDN_PLOTTABLE = 0x0001,
PGDN_IN_WKS = 0x0002,
PGDN_IN_MATRIX = 0x0004,
PGDN_IS_DATASET = 0x0008,
PGDN_LOOSE = 0x0010,
PGDN_FOLDER = 0x0020,
PGDN_FOLDER_SUB = 0x0040

Example:
    void test_Project_GetDatasetInfo()
    {
        DWORD dwInfo;
        foreach (string strDatasetName in Project.DatasetNames)
        {
            dwInfo = Project.GetDatasetInfo(strDatasetName);
            printf("Info(Dataset %s) = %d\n", strDatasetName, dwInfo);
        }
    }

Summary:
Sample data:
Header file: Project.h
See also:


GetDragDropInfo

Project::GetDragDropInfo
Prototype:
PUBLIC  BOOL GetDragDropInfo(string &strWinName, int &iWinLayer, int &iFileIndex, int &iFileCount, string &strFileName)
Remarks: Get Drag-and-Drop information for the last dropped file..
Parameters:
strWinName = The string that will receive the name of the window that the files were dropped on.  If not dropped on a window then the string will be blank.
iWinLayer = The index of the window's layer that the files were dropped on.
iFileIndex = The index of the dropped file currently being handled.
iFileCount = The number of files that were dropped.
strFileName = The string that will receive the file name of the dropped file.

Return values:

Example:
        void OCTestDragDrop()
        {
            string strWinName, strFileName;
            int iWinLayer, iFileIndex, iFileCount;

            BOOL b = Project.GetDragDropInfo(strWinName, iWinLayer, iFileIndex, iFileCount, strFileName);
            if( b )
            {
                printf("Project.DragDropInfo\n");
                printf("    WinName = %s\n", strWinName);
                printf("    Layer   = %d\n", iWinLayer);
                printf("    Index   = %d\n", iFileIndex);
                printf("    Count   = %d\n", iFileCount);
                printf("    FileName= %s\n", strFileName);
            }
        }

Summary:
Sample data:
Header file: Project.h
See also:


GetFolderWithPage

Project::GetFolderWithPage
Prototype:
PUBLIC  Folder GetFolderWithPage(LPCSTR lpcszWindowName)
Remarks: Find the folder that contains the page with the given name, and return the folder.
Parameters:
lpcszWindowName = the name of the page.

Return values:
the Folder containing the page with the name lpcszWindowName.

Example:
        // For this example to run, create a folder in the project and make
        // sure that the folder contains a graph with the name "Graph1".
        void	run_Project_GetFolderWithPage()
        {
            Folder			fld = Project.GetFolderWithPage("Graph1");

            if (fld.IsValid())	// if the page was found
            {
                // Display the name of the folder containing the page (window) "Graph1".
                out_str(fld.GetName());
            }
            else		// the page was not found
                out_str("The page was not found!");
        }

Summary:
Sample data:
Header file: Project.h
See also:
Project::GetFolderWithPage
Prototype:
PUBLIC  Folder GetFolderWithPage(PageBase &page)
Remarks: Find the folder that contains a given page.
Parameters:
page = the page.

Return values:
the Folder containing the page.

Example:
        // For this example to run, create a folder in the project and make
        // sure that the folder contains a graph with the name "Graph1".
        void	run_Project_GetFolderWithPage()
        {
            Page			pg("Graph1");

            Folder			fld = Project.GetFolderWithPage(pg);

            if (fld.IsValid())	// if the page was found
            {
                // Display the name of the folder containing the page (window) "Graph1".
                out_str(fld.GetName());
            }
            else		// the page was not found
                out_str("The page was not found!");
        }

Summary:
Sample data:
Header file: Project.h
See also:


GetName

Project::GetName
Prototype:
PUBLIC  string GetName()
Remarks: Gets the name of the project.
Parameters:
None.

Return values:
the name of the project.

Example:
        void	run_Project_GetName()
        {
            printf("The name of the project is %s\n", Project.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:


GetObject

Project::GetObject
Prototype:
PUBLIC  OriginObject GetObject(UINT uid)
Remarks: Retrieves Origin object given the object unique ID
Parameters:
uid - ID of object

Return values:
OriginObject if object with unique ID equal to uid passed to function exists

Example:
        void run_GetObject()
        {
            WorksheetPage wks("Data1");
            UINT uID = wks.GetUID(TRUE);

            Page  pg;
            pg = (Page)Project.GetObject(uID);
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:


GetOperationObject

Project::GetOperationObject
Prototype:
PUBLIC  OperationBase & GetOperationObject(UINT uid)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Project.h
See also:


GetPath

Project::GetPath
Prototype:
PUBLIC  string GetPath()
Remarks: Gets the path of the file corresponding to the project. If the project has never been saved before, the path will be empty.
Parameters:
None.

Return values:
the path to the project file.

Example:
        // For this example to run, make sure that you have saved the current project
        // at least once, or that the current project has been loaded from a file.
        void	run_Project_GetPath()
        {
            printf("The path of the project is %s\n", Project.GetPath());
        }

Summary:
Sample data:
Header file: Project.h
See also:


GetProfileData

Project::GetProfileData
Prototype:
PUBLIC  BOOL GetProfileData(vector<string>& vsFuncNames, vector<uint>& vnNumCalls, vector<double>& vdTimes)
Remarks: Get internal profiling info
Parameters:
vsFuncNames = internal mangled function names
vnNumCalls = number of times corresponding function was called
vdTimes = total amount of time in seconds the corresponding function was called

Return values:
FALSE if no profiling info available

Example:

Summary:
Sample data:
Header file: Project.h
See also:


GraphPages

Project::GraphPages
Prototype:
PUBLIC  GraphPage GraphPages(int index)
Remarks: Gets a graph window by index.
Parameters:
index = the 0-offset index of the GraphPage object in project.

Return values:
the index'th GraphPage in project.

Example:
        // For this example to run, create at least one graph window.
        void	run_Project_GraphPages()
        {
            // Get the first GraphPage in project:
            GraphPage	pg = Project.GraphPages(0);

            // Display the page name:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:
Project::GraphPages
Prototype:
PUBLIC  GraphPage GraphPages(LPCSTR name)
Remarks: Gets a GraphPage object by name.
Parameters:
name = pointer to the name of the page.

Return values:
the GraphPage object with the name name.

Example:
        // For this example to run, create a graph with the name "Graph1".
        void	run_Project_GraphPages()
        {
            // Get the page by name:
            GraphPage	pg = Project.GraphPages("Graph1");

            // Display the page name:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:


IsModified

Project::IsModified
Prototype:
PUBLIC  BOOL IsModified()
Remarks: Test if the active project has been modified since the last saving or loading.
Parameters:
None.

Return values:
TRUE if the active project has been modified else FALSE.

Example:
        // For this example to run, create a project, save it, and then modify it
        // (for example by modifying the value in a worksheet cell).
        void	run_Project_IsModified()
        {
            if (Project.IsModified())
                out_str("Project has been modified");
            else
                out_str("Project has NOT been modified");

            // Now save the project:
            Project.Save();

            // Now it must be NOT modifed because we saved it above.
            if (Project.IsModified())
                out_str("Project has been modified");
            else
                out_str("Project has NOT been modified");
        }

Summary:
Sample data:
Header file: Project.h
See also:


IsVisible

Project::IsVisible
Prototype:
PUBLIC  BOOL IsVisible(int nWinID=CWT_PROJECT_EXPLORER)
Remarks: Check a control window to see if it is currently shown. Origin's control windows are those that you can access from the View menu, like Project Explorer, Script Window etc.
Parameters:
nWinID = Control window's ID, can be one of the followings
CWT_PROJECT_EXPLORER,
CWT_SCRIPT_WINDOW,
CWT_CODE_BUILDER,
CWT_RESULTS_LOG,

Return values:

Example:
            BOOL bOK = Project.IsVisible(); // return TRUE if Project Explorer is Open.

Summary:
Sample data:
Header file: Project.h
See also:


LayoutPages

Project::LayoutPages
Prototype:
PUBLIC  LayoutPage LayoutPages(int index)
Remarks: Gets a layout window by index.
Parameters:
index = the 0-offset index of the LayoutPage object in project.

Return values:
the index'th LayoutPage in project.

Example:
        // For this example to run, create at least one layout window.
        void	run_Project_LayoutPages()
        {
            // Get the first LayoutPage in project:
            LayoutPage	pg = Project.LayoutPages(0);

            // Display the page name:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:
Project::LayoutPages
Prototype:
PUBLIC  LayoutPage LayoutPages(LPCSTR name)
Remarks: Gets a LayoutPage object by name.
Parameters:
name = pointer to the name of the page.

Return values:
the LayoutPage object with the name name.

Example:
        // For this example to run, create a layout with the name "Layout1".
        void	run_Project_LayoutPages()
        {
            // Get the page by name:
            LayoutPage	pg = Project.LayoutPages("Layout1");

            // Display the page name:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:


LooseDatasetNames

Project::LooseDatasetNames
Prototype:
PUBLIC  string LooseDatasetNames(int index)
Remarks: Gets the name of Dataset not attached to a worksheet or a matrix, which is index'th element in the list. If index is larger than the number of datasets in the project, DatasetNames(int) generates to an execution error.
Parameters:
index = A number smaller than the number of datasets not attached to a worksheet or a matrix in the project.
The datasets are enumerated by the order in which they appear in the link list and have no special
significance.

Return values:
return the name of the dataset.

Example:
        void run_Project_LooseDatasetNames(int index)
        {
            string strName = Project.LooseDatasetNames(index);
            printf("Dataset(%d) Name: %s\n",index, strName);

        }

Summary:
Sample data:
Header file: Project.h
See also:


MatrixPages

Project::MatrixPages
Prototype:
PUBLIC  MatrixPage MatrixPages(int index)
Remarks: Gets a Matrix window by index.
Parameters:
index = the 0-offset index of the MatrixPage object in project.

Return values:
the index'th MatrixPage in project.

Example:
        // For this example to run, create at least one matrix window.
        void	run_Project_MatrixPages()
        {
            // Get the first MatrixPage in project:
            MatrixPage	pg = Project.MatrixPages(0);

            // Display the page name:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:
Project::MatrixPages
Prototype:
PUBLIC  MatrixPage MatrixPages(LPCSTR name)
Remarks: Gets a MatrixPage object by name.
Parameters:
name = pointer to the name of the page.

Return values:
the MatrixPage object with the name name.

Example:
        // For this example to run, create a matrix with the name "Matrix1".
        void	run_Project_MatrixPages()
        {
            // Get the page by name:
            MatrixPage	pg = Project.MatrixPages("Matrix1");

            // Display the page name:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:


NewOperation

Project::NewOperation
Prototype:
PUBLIC  OperationBase* NewOperation(LPCSTR lpcszClassName, LPCSTR lpcszPath, BOOL bAddToOperationList = TRUE)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Project.h
See also:


Notes

Project::Notes
Prototype:
PUBLIC  Note Notes(int index)
Remarks: Gets a Notes window by index.
Parameters:
index = the 0-offset index of the Note object in project.

Return values:
the index'th Note object in project.

Example:
        // For this example to run, create at least one Notes window.
        void	run_Project_Notes()
        {
            // Get the first Note in project:
            Note	pg = Project.Notes(0);

            // Display the page name:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:
Project::Notes
Prototype:
PUBLIC  Note Notes(LPCSTR name)
Remarks: Gets a Note object by name.
Parameters:
name = pointer to the name of the page.

Return values:
the Note object with the name name.

Example:
        // For this example to run, create a Note window with the name "Notes".
        void	run_Project_Notes()
        {
            // Get the page by name:
            Note	pg = Project.Notes("Notes");

            // Display the page name:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:


Open

Project::Open
Prototype:
PUBLIC  BOOL Open(LPCSTR lpcszFilename = NULL, BOOL bOpenReadOnly = FALSE)
Remarks: Open a new project. Current project will be closed and replace with the new one if successful
Parameters:
lpcszFilename = Origin project name. OPJ extension must be included with full path, if lpcszFilename=NULL, an empty project will be open, so using NULL
has the same effect as creating a new project
bOpenReadOnly = TRUE to open project as ReadOnly. If lpcszFilename is a ReadOnly file, then project will be open as ReadOnly automatically.

Return values:
TRUE for success, this method will check file existence before attempting to open, so will immediately return FALSE if file does not exist

Example:
        // For this example to run, make sure that the variable strPathName inside
        // the function is initialized to the pathname of an existing project file.
        void	run_Project_Open()
        {
            string		strPathName = "c:\\myproject.opj";
            if (Project.Open(strPathName))
                out_str("Project opening succeeded.");
            else
                out_str("Project opening failed!");
        }

Summary:
Sample data:
Header file: Project.h
See also:


Pages

Project::Pages
Prototype:
PUBLIC  PageBase Pages(int index = -1)
Remarks: Gets a PageBase object by index.
Parameters:
index = (optional) the 0-offset index of the PageBase object in project, or
-1 for the active page.

Return values:
the index'th PageBase or the active PageBase.

Example:
        // For this example to run, create at least one window (graph, worksheet, etc.).
        void	run_Project_Pages()
        {
            // Get the first page:
            PageBase	pg = Project.Pages(0);

            // Display the page name:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:
Project::Pages
Prototype:
PUBLIC  PageBase Pages(LPCSTR name)
Remarks: Gets a PageBase object by name.
Parameters:
name = pointer to the name of the page.

Return values:
the PageBase object with the name name.

Example:
        // For this example to run, create a worksheet with the name "Data1".
        void	run_Project_Pages()
        {
            // Get the page by name:
            PageBase	pg = Project.Pages("Data1");

            // Display the page name:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:


Profile

Project::Profile
Prototype:
PUBLIC  BOOL Profile(BOOL bStart, BOOL bResetAll = TRUE)
Remarks: Turn on/off profiling
Parameters:
bStart = set internal flag to enable/disable profiling for functions.
bResetAll = TRUE, to walk all functions to reset profiling info

Return values:
flag value before call.

Example:

Summary:
Sample data:
Header file: Project.h
See also:


Project

Project::Project
Prototype:
PUBLIC  Project()
Remarks: Default constructor. Note that in Origin there can only be one Project open at a time, so it is not necessary to attach a Project object (see the example). The Origin C Project object is attached and valid by default.
Parameters:
None.

Return values:

Example:
        // For this example to run, create several windows in Origin
        // (graphs, worksheets, etc).
        void	run_Project()
        {
            PageBase	pg;

            // Create a Project object
            Project		proj;

            // Loop over all the pages in the project and display their names:
            foreach (pg in proj.Pages)
            {
                out_str(pg.GetName());
            }
        }

        // Since a Project object does not need to be initialized, the same function
        // can be written like this, where "Project" is used as a global object:
        void	run_Project()
        {
            PageBase	pg;

            // Loop over all the pages in the project and display their names:
            foreach (pg in Project.Pages)
            {
                out_str(pg.GetName());
            }
        }

Summary:
Sample data:
Header file: Project.h
See also:


Save

Project::Save
Prototype:
PUBLIC  BOOL Save(LPCSTR lpcszFilename = NULL)
Remarks: Save the active project.
Parameters:
lpcszFilename = The path and name of the file to save to.  If NULL then save to the current path using the project's current name.

Return values:
TRUE for success, otherwise FALSE.

Example:
        void	run_Project_Save()
        {
            string		strPathNameToSave = "c:\\myproj.opj";

            if (Project.Save(strPathNameToSave))
                out_str("Project saving succeeded.");
            else
                out_str("Project saving failed!");
        }

Summary:
Sample data:
Header file: Project.h
See also:


ShowWindow

Project::ShowWindow
Prototype:
PUBLIC  void ShowWindow(int nWinID=CWT_PROJECT_EXPLORER, BOOL bShow=TRUE)
Remarks: Show/Hide the sepcified control window.
Parameters:
nWinID = Control window's ID, can be one of the followings
CWT_PROJECT_EXPLORER,
CWT_SCRIPT_WINDOW,
CWT_CODE_BUILDER,
CWT_RESULTS_LOG,
bShow = TRUE, show the window, otherwise, hide the window.

Return values:

Example:
        // test if Script Window open, hide it if yes
        if(Project.IsVisible(CWT_SCRIPT_WINDOW))
            Project.ShowWindow(CWT_SCRIPT_WINDOW, FALSE);

Summary:
Sample data:
Header file: Project.h
See also:


Undo

Project::Undo
Prototype:
PUBLIC  int Undo()
Remarks: Undo the last block.
Parameters:
None.

Return values:
None.

Example:

Summary:
Sample data:
Header file: Project.h
See also:


UndoBlockBegin

Project::UndoBlockBegin
Prototype:
PUBLIC  void UndoBlockBegin()
Remarks: Begin undo block. After this call any undoable action belongs to the same block. Do not call it directly, use UndoBlock class instead.
Parameters:
None.

Return values:
None.

Example:

Summary:
Sample data:
Header file: Project.h
See also:


UndoBlockEnd

Project::UndoBlockEnd
Prototype:
PUBLIC  void UndoBlockEnd()
Remarks: End undo block. Do not call it directly, use UndoBlock class instead.
Parameters:
None.

Return values:
None.

Example:

Summary:
Sample data:
Header file: Project.h
See also:


UndoBlockId

Project::UndoBlockId
Prototype:
PUBLIC  int UndoBlockId()
Remarks: Gets current undo block identifier (ID).
Parameters:
None.

Return values:
Current undo block ID.

Example:

Summary:
Sample data:
Header file: Project.h
See also:


UpdateDataPlotLimits

Project::UpdateDataPlotLimits
Prototype:
PUBLIC  BOOL UpdateDataPlotLimits(TreeNode& tn)
Remarks: Updates data plot limits.
Parameters:
tn - tree node as input/output

Return values:
TRUE if success, FALSE if failure

Example:

Summary:
Sample data:
Header file: Project.h
See also:


UpdateLayerRescale

Project::UpdateLayerRescale
Prototype:
PUBLIC  BOOL UpdateLayerRescale(TreeNode& tnDP, TreeNode& tnLayer)
Remarks: Updates layer rescale.
Parameters:
tnDP - tree node as input which has dataplots
tnLayer - tree node as input/ouput has layer settings and rescale property

Return values:
TRUE if success, FALSE if failure

Example:

Summary:
Sample data:
Header file: Project.h
See also:


WorksheetPages

Project::WorksheetPages
Prototype:
PUBLIC  WorksheetPage WorksheetPages(int index)
Remarks: Gets a WorksheetPage object by index.
Parameters:
index = the 0-offset index of the WorksheetPage object in project.

Return values:
the index'th WorksheetPage in project.

Example:
        // For this example to run, create at least one worksheet.
        void	run_Project_WorksheetPages()
        {
            // Get the first WorksheetPage:
            WorksheetPage	pg = Project.WorksheetPages(0);

            // Display the page name:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:
Project::WorksheetPages
Prototype:
PUBLIC  WorksheetPage WorksheetPages(LPCSTR name)
Remarks: Gets a WorksheetPage object by name.
Parameters:
name = pointer to the name of the page.

Return values:
the WorksheetPage object with the name name.

Example:
        // For this example to run, create a worksheet with the name "Data1".
        void	run_Project_WorksheetPages()
        {
            // Get the page by name:
            WorksheetPage	pg = Project.WorksheetPages("Data1");

            // Display the page name:
            out_str(pg.GetName());
        }

Summary:
Sample data:
Header file: Project.h
See also:


ROIObject

Class: ROIObject

Description: The ROIObject class provides methods and properties common to all Origin region of interest objects. An Origin region of interest object is used to identify a region of interest in an Origin matrix. An Origin C ROIObject is a wrapper object that is a reference to an internal Origin region of interest object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The ROIObject class is derived from the GraphObject class from which it inherits methods and properties.

Hierarchy:

OriginObject
 GraphObject
 ROIObject

Sample:


ROIObject

ROIObject::ROIObject
Prototype:
PUBLIC  ROIObject()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: graph.h
See also:


Scale

Class: Scale

Description: The Scale class provides methods and properties common to all Origin axis scales. Two scale objects (one X scale and one Y scale) are contained in each graph layer on each graph page. An Origin C Scale object is a wrapper object that is a reference to an internal Origin scale object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The Scale class is derived from the OriginObject class from which it inherits methods and properties.

Hierarchy:

OriginObject
 Scale

Sample:

        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        // Assumes Graph1 window is active.
        GraphLayer	gl = Project.ActiveLayer(); // Get active layer in project file
        if(gl)                                  // If valid graph layer...
        {
            Scale sc(gl.X);                     // Get X scale object from graph layer
            sc.From = 0.01;                     // Assign scale from value
            sc.To = 1000;                       // assign scale to value
            sc.Type = LOG10_SPACE;              // Set axis scale as Log10
            sc.Inc = 1;                         // set axis scale increment to 1
        }


Scale

Scale::Scale
Prototype:
PUBLIC  Scale()
Remarks: Default constructor which constructs an unattached Scale object. The member function IsValid() of the base class OriginObject can be used to determine if the object is valid (attached to an internal Origin axis)
Parameters:
None

Return values:

Example:
        void	run_Scale_Constructor()
        {
            // Create an unattached Scale object
            Scale			s;

            if (!s.IsValid())
            {
                out_str("Invalid Scale object!");	// must be invalid
                return;
            }
        }

Summary:
Sample data:
Header file: graph.h
See also:
Scale::Scale
Prototype:
PUBLIC  Scale(Scale & scale)
Remarks: Copy constructor which constructs a Scale object from another Scale object.
Parameters:
scale = the source scale object

Return values:

Example:
        // For this example to run, a graph window with the name "Graph1" must exist in the project.
        void	run_Scale_Constructor()
        {
            // Create and attach a graph layer from "Graph1":
            GraphLayer		gl("Graph1");

            if (!gl.IsValid())
            {
                out_str("No GraphLayer!");
                return;
            }

            // Intialize a Scale object from the X-axis scale of the GraphLayer
            // (gl.X is the X-axis scale for the layer attched to "gl").
            Scale			s(gl.X);

            // Display the "From" property:
            out_double("From = ", s.From);
        }

Summary:
Sample data:
Header file: graph.h
See also:


Selection

Class: Selection

Description: The Selection class provides methods and properties to access objects in selection

Hierarchy:

Selection

Sample:

        foreach(OriginObject obj in Selection.Objects)
        {
            // .. do something ..
        }


~Selection

Selection::~Selection
Prototype:
PUBLIC  ~Selection()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Selection.h
See also:


Add

Selection::Add
Prototype:
PUBLIC  BOOL Add(OriginObject& obj)
Remarks: Selects object
Parameters:

Return values:
FALSE if OriginObject passed to the function is invalid or can not be selected

Example:
    void AddObjectToSelection(GraphObject& gr)
    {
        if( gr )
            Selection.Add(gr);
    }

Summary:
Sample data:
Header file: Selection.h
See also:


Objects

Selection::Objects
Prototype:
PUBLIC  OriginObject Objects(int nIndex = 0)
Remarks:
Parameters:

Return values:

Example:
            void run_Objects()
            {
                OriginObject OrgObj;
                OrgObj = Selection.Objects(0);

                GraphObject go;
                go = (GraphObject)OrgObj;
                out_str(go.GetName());
            }

Summary:
Sample data:
Header file: Selection.h
See also:


Remove

Selection::Remove
Prototype:
PUBLIC  BOOL Remove(OriginObject& obj)
Remarks: Unselects object
Parameters:

Return values:
FALSE if OriginObject passed to the function is invalid or not selected

Example:
    void RemoveObjectFromSelection(GraphObject& gr)
    {
        if( gr )
            Selection.Remove(gr);
    }

Summary:
Sample data:
Header file: Selection.h
See also:


Reset

Selection::Reset
Prototype:
PUBLIC  void Reset()
Remarks: Deselect all objects
Parameters:

Return values:

Example:
    void ResetSelection()
    {
        Selection.Reset();
    }

Summary:
Sample data:
Header file: Selection.h
See also:


Selection

Selection::Selection
Prototype:
PUBLIC  Selection()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Selection.h
See also:


storage

Class: storage

Description:

Hierarchy:

storage

Sample:


GetSection

storage::GetSection
Prototype:
PUBLIC  BOOL GetSection(LPCSTR lpcszSecName, TreeNode& trNode)
Remarks: Copy a storage section into a treenode
Parameters:
lpcszSecName = name of an existing section,
trNode = a TreeNode to receive the data

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        Page pg = Project.Pages();
        if(pg == NULL)
           return;
        string strStorage = "Test";
        string strSection = "Params";
        Tree trTemp;
        storage st;
        st = pg.GetStorage(strStorage);
        if(st)
        {
            if(st.GetSection(strSection, trTemp))
                out_tree(trTemp);
        }

Summary:
Sample data:
Header file: Storage.h
See also:


GetSectionNames

storage::GetSectionNames
Prototype:
PUBLIC  BOOL GetSectionNames(vector<string> &vsNames)
Remarks:
Parameters:

Return values:

Example:
            void run_GetSectionNames()
            {
                Page pg = Project.Pages();
                if(pg==NULL)
                    return;

                storage st;
                string strStorage = "Test";
                st = pg.GetStorage(strStorage);
                if(st)
                {
                    vector<string> vs;
                    if(st.GetSectionNames(vs))
                    {
                        for(int ii=0;ii<vs.GetSize();ii++)
                            out_str(vs[ii]);
                    }
                }
            }

Summary:
Sample data:
Header file: Storage.h
See also:


IsValid

storage::IsValid
Prototype:
PUBLIC  BOOL IsValid()
Remarks: Checks Validity of the Storage object.
Parameters:

Return values:
FALSE if an Storage Object is not valid, non-zero otherwise.

Example:
            void run_IsValid()
            {
                Page pg = Project.Pages();
                if(pg==NULL)
                    return;

                storage st;
                string strStorage = "Test";
                st = pg.GetStorage(strStorage);
                if(st.IsValid())
                {
                    out_str("OK");
                }
            }

Summary:
Sample data:
Header file: Storage.h
See also:


Read

storage::Read
Prototype:
PUBLIC  bool Read(LPCSTR lpcszFile)
Remarks: Load contents from file into storage class. They can be retrieved by GetTxt method.
Parameters:
lpcszFile = File name

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            void run_Read()
            {
                storage st;
                bool bRet = st.Read("C:\\Test.xml");
            }

Summary:
Sample data:
Header file: Storage.h
See also:


SetSection

storage::SetSection
Prototype:
PUBLIC  BOOL SetSection(LPCSTR lpcszSecName, TreeNode& trNode)
Remarks: Copy a TreeNode branch into a storage section. Section is created if not already present
Parameters:
lpcszSecName = name of an existing section or a new section, must be valid C identifier name
trNode = a TreeNode to set the data

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        Page pg = Project.Pages();
        if(pg == NULL)
           return;

        string strStorage = "Test";
        string strSection = "Params";

        Tree trTemp;
        trTemp.AA.factor.dVal = 1.2345;
        trTemp.AA.title.strVal = "This is a test";
        trTemp.BB.nOrder.nVal = 2;
        trTemp.BB.decay.dVal = 4.32;

        pg.Info.Add(strStorage);
        storage st;
        st = pg.GetStorage(strStorage);
        if(st)
        {
            if(st.SetSection(strSection, trTemp))
                out_str("done");
        }

Summary:
Sample data:
Header file: Storage.h
See also:


storage

storage::storage
Prototype:
PUBLIC  storage()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Storage.h
See also:


Write

storage::Write
Prototype:
PUBLIC  bool Write(LPCSTR lpcszFile)
Remarks: Write contents of a storage class into a file.
Parameters:
lpcszFile = File name

Return values:
Returns TRUE on success and FALSE on failure.

Example:
            void run_Write()
            {
                Page pg = Project.Pages();
                if(pg==NULL)
                    return;

                storage st;
                string strStorage = "Test";
                st = pg.GetStorage(strStorage);

                if(st.IsValid())
                {
                    bool bRet = st.Write("C:\\Test.xml");
                }
            }

Summary:
Sample data:
Header file: Storage.h
See also:


StyleHolder

Class: StyleHolder

Description: The StyleHolder class provides methods and properties common to all data plot style holders. An internal Origin data plot style holder is an object used to store plot type information for a data plot contained in an Origin graph layer. An Origin C StyleHolder is a wrapper object that is a reference to an internal Origin StyleHolder object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The StyleHolder class is derived from the GraphObject and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 GraphObject
 StyleHolder

Sample:

        // Assumes Graph1 is active window in Origin
        GraphLayer gl = Project.ActiveLayer();        // Get active Origin layer
        if(gl)                                        // If layer is valid...
        {
            StyleHolder sh = gl.StyleHolders(0);      // Get first style holder in layer
            out_int("Plot type is ", sh.GetPlotId()); // Get plot id
        }


GetDescription

StyleHolder::GetDescription
Prototype:
PUBLIC  string GetDescription()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: graph.h
See also:


GetPlotDesignations

StyleHolder::GetPlotDesignations
Prototype:
PUBLIC  string GetPlotDesignations(DWORD *pdwFlags = NULL)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: graph.h
See also:


GetPlotId

StyleHolder::GetPlotId
Prototype:
PUBLIC  int GetPlotId(BOOL bBaseID = FALSE)
Remarks: get the Origin internal plot id.
Parameters:
bBaseID = TRUE if we only care about the graph category, such than line,scatter and line symbol plots will all return IDM_PLOT_LINESYMB

Return values:

Example:
        GraphLayer gl = Application.ActiveLayer();
        if(gl)
        {
            StyleHolder sh = gl.StyleHolders(0);
            out_int("plot type is ", sh.GetPlotId());
        }

Summary:
Sample data:
Header file: graph.h
See also:


StyleHolder

StyleHolder::StyleHolder
Prototype:
PUBLIC  StyleHolder()
Remarks:
Parameters:

Return values:

Example:
        // Assumes Graph1 is active window in Origin
        GraphLayer gl = Project.ActiveLayer();        // Get active Origin layer
        if(gl)                                        // If layer is valid...
        {
            StyleHolder sh = gl.StyleHolders(0);      // Get first style holder in layer
            out_int("Plot type is ", sh.GetPlotId()); // Get plot id
        }

Summary:
Sample data:
Header file: graph.h
See also:
StyleHolder::StyleHolder
Prototype:
PUBLIC  StyleHolder(StyleHolder &shOriginal)
Remarks: Copy Constructor: The new StyleHolder object created is attached to the internal graphic object shOriginal was attached to. If shOriginal was invalid (not attached) so will be the new object.
Parameters:

Return values:

Example:
        // Assumes Graph1 exist in Origin
        void test_StyleHolder()
        {
            GraphLayer glMyLayer("Graph1");
            StyleHolder shOriginal;
            shOriginal = glMyLayer.StyleHolders(0);
            StyleHolder shNew(shOriginal);

            if (shNew.IsValid())
            {
                out_str(shNew.GetName());
            }
        }

Summary:
Sample data:
Header file: graph.h
See also:


UndoBlock

Class: UndoBlock

Description: The UndoBlock class provides safe access to project functions UndoBlockBegin() and UndoBlockEnd().

Hierarchy:

UndoBlock

Sample:

        // get format from Graph1 page
        GraphPage pageSrc("Graph1");
        Tree tree;
        tree = pageSrc.GetFormat();
        if( tree )
        {
            // get undo block ID before any changes
            int nIDbefore = Project.UndoBlockId();

            // better to limit scope of undo block
            {
                // start new undo block and save all changes there
                UndoBlock block;

                // apply format to Graph2 page
                GraphPage pageDst1("Graph2");
                BOOL bb = pageDst1.ApplyFormat(tree);

                // apply format to Graph3 page
                GraphPage pageDst2("Graph3");
                bb = pageDst2.ApplyFormat(tree);
            }

            // get undo block ID after all changes
            int nIDafter = Project.UndoBlockId();

            // undo all changes from the added undo block
            Project.Undo();
        }


~UndoBlock

UndoBlock::~UndoBlock
Prototype:
PRIVATE  ~UndoBlock() {Project.UndoBlockEnd()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Project.h
See also:


UndoBlock

UndoBlock::UndoBlock
Prototype:
PRIVATE  UndoBlock() {Project.UndoBlockBegin()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Project.h
See also:


Worksheet

Class: Worksheet

Description: The Worksheet class provides methods and properties common to worksheet layers in Origin worksheet pages. An Origin worksheet may contain a number of worksheet columns thus the Worksheet class contains a collection of all the columns in the worksheet. An Origin C Worksheet object is a wrapper object that is a reference to an internal Origin worksheet object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The Worksheet class is derived from the Datasheet, Layer, and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 Layer
 Datasheet
 Worksheet

Sample:

        Worksheet wks=Project.ActiveLayer();
        if(wks)
        {
            out_int("Num of columns =", wks.GetNumCols());
            while(wks.DeleteCol(0))	 // Remove all columns in worksheet
                ;
            ASSERT(wks.GetNumCols() == 0);
        }
        else
            out_str("No active worksheet.");


AddCol

Worksheet::AddCol
Prototype:
PUBLIC  int AddCol(LPCSTR lpcszColName=NULL)
Remarks: Add a new column to the worksheet and name it if specified.
Parameters:
lpcszColName = Optional, Name of column

Return values:
The index of the newly added column (0 offset)

Example:
        Worksheet wks("data1");
        int colnum = wks.AddCol(); //Add a new column
        colnum = wks.AddCol("Temp"); //Add a new column, called Temp

Summary: Return index of newly added column (0 offset) or -1 if add column fails
Sample data:
Header file: wksheet.h
See also:
Worksheet::AddCol
Prototype:
PUBLIC  int AddCol(LPCSTR lpcszColName, string& strColNameCreated)
Remarks: Add a new column to the worksheet with the given name and store the name in a string. If the given name already exists then increase it.
Parameters:
lpcszColName = desired column name
strColNameCreated = string to store the actual column name on return

Return values:
The index of the newly added column (0 offset)

Example:
        Worksheet wks("Data1");
        string str;
        int nCol = wks.AddCol("Temp",str);
        if(nCol >= 0)
            printf("New Column created, name = %s\n",str);
        else
            out_str("Column creation failed");

Summary:
Sample data:
Header file: wksheet.h
See also:


AppendRows

Worksheet::AppendRows
Prototype:
PUBLIC  BOOL AppendRows(int nRows = 1 )
Remarks: Append rows to the worksheet
Parameters:
nRows = Number of rows to append; 1 by default

Return values:
True = Succesful; otherwise FALSE

Example:
        Worksheet wks("Data1");
        ASSERT(wks.AppendRows(10));

Summary:
Sample data:
Header file: wksheet.h
See also: InsertRow DeleteRow


Attach

Worksheet::Attach
Prototype:
PUBLIC  BOOL Attach(LPCSTR lpcszWksName)
Remarks: Attach to an Origin worksheet
Parameters:
lpcszWksName = The name of an Origin worksheet object

Return values:
TRUE if the worksheet exists; FALSE if the worksheet does not exist

Example:
        Worksheet wks;
        ASSERT(wks.Attach("Data1"));

Summary: Attach worksheet object to a real Origin worksheet
Sample data:
Header file: wksheet.h
See also:


Cell

Worksheet::Cell
Prototype:
PUBLIC  double Cell(int nRow, int nCol)
Remarks: Get the value at the location (nRow, nCol) in the worksheet
Parameters:
nRow = Row number with zero offset
nCol = Column number with zero offset

Return values:
Value at the location (nRow, nCol) in the worksheet

Example:
        Worksheet wks("Data1");
        wks.SetCell(0, 0, 3.14);
        double cellValue = wks.Cell(0, 0);
        printf("Value at (0,0) location is %f\n", cellValue);

Summary:
Sample data:
Header file: wksheet.h
See also: GetCell SetCell TCell


Columns

Worksheet::Columns
Prototype:
PUBLIC  Column Columns(int nCol = -1)
Remarks: Used to call Column member functions directly with a '.' after the function call
Parameters:
nCol = Column number with zero offset (-1 refers to *Active* column)

Return values:
A Column

Example:
        Worksheet wks("Data1");
        ASSERT(wks.Columns(0).IsValid());

Summary: Return a column - can be used to call column members directly with a '.' after function call
Sample data:
Header file: wksheet.h
See also:
Worksheet::Columns
Prototype:
PUBLIC  Column Columns(LPCSTR lpcszName)
Remarks: Used to call Column member functions directly with a '.' after the function call
Parameters:
lpcszName = Column name

Return values:
A Column

Example:
        Worksheet wks("Data1");
        ASSERT(wks.Columns("A").IsValid());

Summary:
Sample data:
Header file: wksheet.h
See also:


CreateCopy

Worksheet::CreateCopy
Prototype:
PUBLIC  BOOL CreateCopy(Worksheet &wksSource, int nOption = CREATE_VISIBLE_SAME, DWORD dwCtrl = DCTRL_COPY_DEFAULT)
Remarks: Create a copy of the worksheet wksSource and attaches it to the object.
Parameters:
wksSource = the worksheet whose copy is made
nOption	= enum {
CREATE_TEMP = 0,		// it will be destroyed when destroying the object (when it exits the scope) and is created invisible
CREATE_VISIBLE_SAME,	// visibility is that of the source worksheet
CREATE_VISIBLE,			// create visible
CREATE_HIDDEN,			// create hidden
};
DWORD dwCtrl = enum {
DCTRL_COPY_DATA						= 0x00000001, // copy data from source worksheet
DCTRL_COPY_IN_OPERATIONS			= 0x00000002, // copy operations that have worksheet as output (incoimng operations)
DCTRL_COPY_OUT_OPERATIONS			= 0x00000004, // copy operations that have worksheet as input (outgoing operations)
DCTRL_COPY_DEFAULT = DCTRL_COPY_DATA | DCTRL_COPY_OUT_OPERATIONS,
}

Return values:
TRUE for success; otherwise FALSE.

Example:
        void	worksheet_copy()
        {
            Worksheet	wks;
            Worksheet	wksSource("Data1");

            int			nOption = CREATE_VISIBLE_SAME;
            BOOL		bRet = wks.CreateCopy(wksSource, nOption);

            out_int("bRet = ", bRet);
        }

Summary:
Sample data:
Header file: wksheet.h
See also: Create
Worksheet::CreateCopy
Prototype:
PUBLIC  BOOL CreateCopy(Worksheet &wksSource, int nOption = CREATE_VISIBLE_SAME)
Remarks: Create a copy of the worksheet wksSource and attaches it to the object.
Parameters:
wksSource = the worksheet whose copy is made
nOption	= enum {
CREATE_TEMP = 0,		// it will be destroyed when destroying the object (when it exits the scope) and is created invisible
CREATE_VISIBLE_SAME,	// visibility is that of the source worksheet
CREATE_VISIBLE,			// create visible
CREATE_HIDDEN,			// create hidden
};

Return values:
TRUE for success; otherwise FALSE.

Example:
        void	worksheet_copy()
        {
            Worksheet	wks;
            Worksheet	wksSource("Data1");

            int			nOption = CREATE_VISIBLE_SAME;
            BOOL		bRet = wks.CreateCopy(wksSource, nOption);

            out_int("bRet = ", bRet);
        }

Summary:
Sample data:
Header file: wksheet.h
See also: Create


DeleteCol

Worksheet::DeleteCol
Prototype:
PUBLIC  BOOL DeleteCol(int nCol)
Remarks: Delete a column in the worksheet
Parameters:
nCol = Column number with zero offset

Return values:
True = Succesful; otherwise FALSE

Example:
        Worksheet wks("Data1");
        ASSERT(wks.DeleteCol(0));

Summary:
Sample data:
Header file: wksheet.h
See also: InsertCol


DeleteRange

Worksheet::DeleteRange
Prototype:
PUBLIC  BOOL DeleteRange(int nRowBegin, int nColBegin, int nRowEnd, int nColEnd, BOOL bInsertNotDelete = false)
Remarks: Delete a range of data in the worksheet
Parameters:
nRowBegin = Beginning row number with zero offset
nColBegin = Beginning column number with zero offset
nRowEnd = Ending row number with zero offset
nColEnd = Ending column number with zero offset
bInserNotDelete = false by default; if TRUE then insert rows

Return values:
TRUE for success; otherwise FALSE

Example:
        Worksheet wks("Data1");
        ASSERT(wks.DeleteRange(1,1,3,2));

Summary:
Sample data:
Header file: wksheet.h
See also: DeleteCol


DeleteRow

Worksheet::DeleteRow
Prototype:
PUBLIC  BOOL DeleteRow(int nPos)
Remarks: Delete a row in the worksheet
Parameters:
nPos = Row number with zero offset

Return values:
TRUE if Succesful; otherwise FALSE

Example:
        Worksheet wks("Data1");
        ASSERT(wks.DeleteRow(10)); //Delete a row from 10th row

Summary:
Sample data:
Header file: wksheet.h
See also: InsertRow AppendRows


ExportASCII

Worksheet::ExportASCII
Prototype:
PUBLIC  int ExportASCII(LPCSTR lpcszFilename, DWORD dwCntrl, char cSeparator = '\t', int nR1 = 0, int nC1 = 0, int nR2 = -1, int nC2 = -1)
Remarks: Export worksheet to a ASCII file
Parameters:
lpcszFilename = a full path file name
dwCntrl = can be the following value(defined in OC_Const.h):
WKS_EXPORT_HEADING	0x0001	// col name
WKS_EXPORT_ALL		0x0002	// ignore c1c2r1r2
WKS_EXPORT_LABELS	0x0004	// col label
WKS_EXPORT_SELECTED 0x0008	// only selected cols
lpcszSeparator = the separator in the data file. The default separator is "\t".
nR1 = first row in the data range to be included with the data file.
nC1 = first column in the data range to be included with the data file.
nR2 = last row in the data range to be included with the data file.
nC2 = last column in the data range to be included with the data file.

Return values:
On error, returns -1, otherwise returns the exported file size.

Example:
    void test_export_ascii()
    {
        Worksheet wks = Project.ActiveLayer();
        if(wks)
        {
            string strFile = GetSaveAsBox("*.dat");
            wks.ExportASCII(strFile, WKS_EXPORT_ALL);
        }
    }

Summary:
Sample data:
Header file: wksheet.h
See also:


FindCol

Worksheet::FindCol
Prototype:
PUBLIC  Column FindCol(LPCSTR lpcszColLabel, int nColBegin = 0, BOOL bCaseSensitive = TRUE, BOOL bFullMatch = TRUE)
Remarks: Find column in worksheet by searching for column label string
Parameters:
lpcszColLabel = string to search for
nColBegin = Column index (0 offset) to start searching
bCaseSensitive = TRUE if case sensitive
bFullMatch = FALSE if only match substring

Return values:

Example:
        void show_wks_labels()
        {
            Worksheet wks("data1");

            BOOL bOK = wks.Columns(0).SetLabel("AA");
            bOK = wks.Columns(1).SetLabel("aa");
            wks.ShowLabels();
            Column col = wks.FindCol("aa");
            string strLabel = col.GetLabel()
        }

Summary:
Sample data:
Header file: wksheet.h
See also:


GetBounds

Worksheet::GetBounds
Prototype:
PUBLIC  BOOL GetBounds( int& iR1, int iC1, int& iR2, int iC2, BOOL bExcludeMissingValues = TRUE)
Remarks: Get the minimum begining and maximum ending row indices for the specified columns in this Worksheet.
Parameters:
iR1=Output minimum begining row index (0 based)
iC1=Input begining column index(0 based)
iR2=Output maximum ending row index (0 based)
iC2=Input ending column index(0 based)
bExcludeMissingValues=TRUE (default) advances iR1 to first row with non-missing value and retards iR2 to last row with with non-missing value.
FALSE will not modify iR1 and iR2

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        void wks_get_bound()
        {
            Worksheet wks = Project.ActiveLayer();
            int nR1, nR2;

            wks.GetBounds(nR1, 0, nR2, -1);
            // need to convert to LabTalk indexing by +1
            printf("%s[%d:%d]\n", wks.GetPage().GetName(), nR1+1, nR2+1);
            // show for each column and check consistency
            foreach(Column cc in wks.Columns)
            {
                Dataset aa(cc);
                printf("Col(%s)[%d:%d]\n",cc.GetName(), aa.GetLowerIndex()+1, aa.GetUpperIndex()+1);
            }
        }

Summary:
Sample data:
Header file: wksheet.h
See also:


GetCell

Worksheet::GetCell
Prototype:
PUBLIC  BOOL GetCell(int nRow, int nCol, string& strText)
Remarks: Get the value at the location (nRow, nCol) in the worksheet as a string
Parameters:
nRow = Row number with zero offset
nCol = Column number with zero offset
strText = string to store the value

Return values:
TRUE for success; otherwise FALSE.

Example:
        Worksheet wks("Data1");
        wks.SetCell(0, 0, 3.14);
        string strText;
        wks.GetCell(0, 0, strText);
        printf("Value at (0,0) location is %s\n", strText);

Summary:
Sample data:
Header file: wksheet.h
See also: Cell SetCell TCell


GetColDesignations

Worksheet::GetColDesignations
Prototype:
PUBLIC  string GetColDesignations()
Remarks: Gets column designations for entire worksheet in form of string Possible values for designations: 'X' - X column 'Y' - Y column 'Z' - Z column 'E' - Y error column 'L' - label column 'M' - X error column 'N' - ignore column
Parameters:

Return values:
column designations for entire worksheet in form of string

Example:
        Worksheet wks("Data1");
        string strDesignations = wks.GetColDesignations();

Summary:
Sample data:
Header file: wksheet.h
See also:
Worksheet::GetColDesignations
Prototype:
PUBLIC  void GetColDesignations(string& strDesignations)
Remarks: /** Gets column designations for entire worksheet in form of string Possible values for designations: 'X' - X column 'Y' - Y column 'Z' - Z column 'E' - Y error column 'L' - label column 'M' - X error column 'N' - ignore column
Parameters:

Return values:
void

Example:
        Worksheet wks("Data1");
        string strDesignations;
        wks.GetColDesignations(strDesignations);

Summary:
Sample data:
Header file: wksheet.h
See also:


GetColFormats

Worksheet::GetColFormats
Prototype:
PUBLIC  string GetColFormats()
Remarks: gets the column formats of all the columns in the worksheet
Parameters:

Return values:
A string containing all the column formats.

Example:
        Worksheet wks("Data1");
        string strFormats;
        strFormats=wks.GetColFormats();
        Example: "99"
        1st column - Text & Numeric (9)
        2nd column - Text & Numeric	(9)

Summary:
Sample data:
Header file: wksheet.h
See also:
Worksheet::GetColFormats
Prototype:
PUBLIC  void GetColFormats(string& strFormats)
Remarks: gets the column formats of all the columns in the worksheet. Same as GetColFormats() except that thi s method takes in a reference to a string as a parameter and returns nothing.
Parameters:

Return values:
void

Example:
        Worksheet wks("Data1");
        string strFormats;
        wks.GetColFormats(strFormats);

Summary:
Sample data:
Header file: wksheet.h
See also:


GetCurve

Worksheet::GetCurve
Prototype:
PUBLIC  curvebase& GetCurve(int nColx, int nColY)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: wksheet.h
See also:
Worksheet::GetCurve
Prototype:
PUBLIC  curvebase& GetCurve(int nColy)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: wksheet.h
See also:


GetRange

Worksheet::GetRange
Prototype:
PUBLIC  BOOL GetRange( int& iR1, int& iR2, int iC1 = 0, int iC2 = -1, BOOL bExcludeMissingValues = TRUE)
Remarks: Get the minimum begining and maximum ending row indices for the specified columns in this Worksheet.
Parameters:
iR1=Output minimum begining row index (0 based)
iR2=Output maximum ending row index (0 based)
iC1=Input begining column index (0 based offset, default 0 is first column)
iC2=Input ending column index (0 based offset, default -1 to indiate last column)
bExcludeMissingValues=TRUE (default) advances iR1 to first row with non-missing value and retards iR2 to last row with with non-missing value.
FALSE will not modify iR1 and iR2

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        void wks_get_range()
        {
            Worksheet wks = Project.ActiveLayer();
            int nR1, nR2;

            wks.GetRange(nR1, nR2);
            // need to convert to LabTalk indexing by +1
            printf("%s[%d:%d]\n", wks.GetPage().GetName(), nR1+1, nR2+1);
            // show for each column and check consistency
            foreach(Column cc in wks.Columns)
            {
                Dataset aa(cc);
                printf("Col(%s)[%d:%d]\n",cc.GetName(), aa.GetLowerIndex()+1, aa.GetUpperIndex()+1);
            }
        }

Summary:
Sample data:
Header file: wksheet.h
See also:


GetSelectedColumns

Worksheet::GetSelectedColumns
Prototype:
PUBLIC  BOOL GetSelectedColumns(vector<int> &v)
Remarks: Retrieves the 0-offset indices of the selected columns in the worksheet.
Parameters:
v = vector of integers which will recieve the 0-offset indices of the selected columns

Return values:
TRUE for success; otherwise FALSE

Example:
        vector<int>		v;
        Worksheet		wks("Data1");

        BOOL			bOK = wks.GetSelectedColumns(v);

Summary:
Sample data:
Header file: wksheet.h
See also:


GetSelectedRange

Worksheet::GetSelectedRange
Prototype:
PUBLIC  int GetSelectedRange(int &r1, int &c1, int &r2, int &c2, string *pstrAddress = NULL)
Remarks: Retrieves the current selection from the worksheet.
Parameters:
r1 = on return it receives the index of the first row in the selection, if any
c1 = on return it receives the index of the first column in the selection, if any
r2 = on return it receives the index of the last row in the selection, if any
c2 = on return it receives the index of the last column in the selection, if any
pstrAddress = optional argument that will on return receive the address of the Excel selection range as string (assuming it is an Excel worksheet)

Return values:
Integer indicating the type of selection. It can be a bitwise combination of one or more of the following:
WKS_SEL_NONE  					// no selection
WKS_SEL_EDIT					// one cell being edited
WKS_SEL_COLUMN					// one or more entire columns selected
WKS_SEL_ROW						// one or more entire rows selected
WKS_SEL_RANGE					// more than one cell selected
WKS_SEL_ONE_COL					// exactly one column selected
WKS_SEL_DISCONTIGUOUS			// discontiguous columns selected
WKS_SEL_ALL						// entire worksheet

Example:
        Worksheet wks("Data1");
        int			 r1, c1,r2, c2;
        string		strAddress;
        int			seltype = wks.GetSelectedRange(r1, c1, r2, c2, &strAddress);

        printf("sel = %d\tr1 = %d\tc1 = %d\tr2 = %d\tc2 = %d\n", seltype, r1, c1, r2, c2);
        out_str(strAddress);

Summary:
Sample data:
Header file: wksheet.h
See also:


ImportASCII

Worksheet::ImportASCII
Prototype:
PUBLIC  int ImportASCII(LPCSTR lpcszFilename, ASCIMP &stAscImp)
Remarks: Import ASCII file into worksheet by using a ASCIMP struct that will define how to import the data
Parameters:
lpcszFilename = a full path ASCII file name
stAscImp = An ASCIMP struct that has been setup with import settings

Return values:
0 if success, otherwise returns error codes

Example:
    void test_ascii_import()
    {
        ASCIMP	ascimp;
        string strFile = GetOpenBox("*.dat");
        if(AscImpReadFileStruct(strFile,&ascimp)==0)
        {
            Worksheet wks;
            wks.Create();
            wks.ImportASCII(strFile, ascimp);
        }
    }

Summary:
Sample data:
Header file: wksheet.h
See also:
Worksheet::ImportASCII
Prototype:
PUBLIC  BOOL ImportASCII(LPCSTR lpcszFilename, BOOL bRenameWks=FALSE, int nMode = ASCIMP_MODE_REPLACE_DATA, BOOL bRenameCols=FALSE)
Remarks: Import ASCII file into worksheet by using automatic procedure
Parameters:
lpcszFilename = a full path ASCII file name
bRenameWks = to rename the worksheet to the file name, might need to be fitted for worksheet naming requirement
nMode = ASCIMP_MODE_REPLACE_DATA, ASCIMP_MODE_APPEND_COLS, ASCIMP_MODE_APPEND_ROWS
bRenameCols = to rename the columns using labels from the file

Return values:
True = succesful; otherwise FALSE

Example:
    void import_to_active_wks()
    {
        Worksheet wks = Project.ActiveLayer();
        if(wks)
        {
            string strFile = GetOpenBox("*.dat");
            wks.ImportASCII(strFile);
        }
    }

Summary:
Sample data:
Header file: wksheet.h
See also:


InsertCol

Worksheet::InsertCol
Prototype:
PUBLIC  BOOL InsertCol(int nPos, LPCSTR lpcszColName, string &strColNameCreated)
Remarks: Insert an empty column in the worksheet with the given name and store the name in a string. If the given name already exists then increment it.
Parameters:
nPos = Column number with zero offset
lpcszColName = string to name inserted column
strColNameCreated = string to store the col name created

Return values:
True for succesful; otherwise FALSE

Example:
        Worksheet wks("Data1");
        string ColName = "NewColoumn";
        string ColNameCreated;
        ASSERT(wks.InsertCol(1, ColName, ColNameCreated)); //Insert an empty column at the 1st column ( 0 offset)
        printf("Column Name created is %s\n", ColNameCreated);

Summary:
Sample data:
Header file: wksheet.h
See also: DeleteCol InsertRow


InsertRow

Worksheet::InsertRow
Prototype:
PUBLIC  BOOL InsertRow(int nPos)
Remarks: Insert an empty row in the worksheet
Parameters:
nPos = Row number with zero offset

Return values:
True = succesful; otherwise FALSE

Example:
        Worksheet wks("Data1");
        ASSERT(wks.InsertRow(10)); //Insert an empty row on 10th row

Summary:
Sample data:
Header file: wksheet.h
See also: DeleteRow AppendRows


Open

Worksheet::Open
Prototype:
PUBLIC  BOOL Open(LPCSTR lpcszFileName, int nOption = CREATE_VISIBLE)
Remarks: Open a new worksheet from the supplied OGW file and attaches it to the object.
Parameters:
lpcszTemplate = the OGW file name
nOption	= enum {
CREATE_TEMP = 0,	// it will be destroyed when destroying the object (when it exits the scope) and is created invisible
CREATE_VISIBLE_SAME,	// visibility is that which is stored in the OGW file
CREATE_VISIBLE,		// create visible
CREATE_HIDDEN,		// create hidden
};

Return values:
TRUE for success; otherwise FALSE.

Example:
        void	worksheet_open()
        {
            Worksheet	wks;
            string		strOGW = "c:\\myfile.ogw";

            int			nOption = CREATE_VISIBLE_SAME;
            BOOL		bRet = wks.Open(strOGW, nOption);

            out_int("bRet = ", bRet);
        }

Summary:
Sample data:
Header file: wksheet.h
See also:


PasteData

Worksheet::PasteData
Prototype:
PUBLIC  BOOL PasteData(LPCTSTR lpcszText,int nRow = -1,int nCol = 0,int nRepaintMode = 0)
Remarks: This member function is similar to paste text from clipboard into the worksheet The data is tab delimited
Parameters:
lpcszText = Tab delimited data values
nRow = Optional row number to begin the paste
nCol = Optional column number to begin the paste
nRepaintMode = Window Refresh mode
lpcszText
  rows of text with tab as list separator and newline of new rows
nRow
  beginning cell's row number, -1 means to append from the first unfilled row of the worksheet
nCol
  beginning cell's column number, -1 if to append from the first unfilled column ( not supported yet)

Return values:
TRUE for success, otherwise FALSE

Example:
        Worksheet wks("Data1");
        string str = "1\t2\t3";
        wks.PasteData(str); // append to end of wks from 1st column

Summary: default will use realtime drawing, can disable repaint, or direct repaint
Sample data:
Header file: wksheet.h
See also:


PutRecordset

Worksheet::PutRecordset
Prototype:
PUBLIC  BOOL PutRecordset(Object &objrs,int nRowBegin = 0,int nNumRows = -1,int nColBegin = 0,int nOptions = LAYWKGETRECORDSET_BY_COLUMN_INDEX)
Remarks: Put the data from a recordset into the worksheet. This function is available only for OriginPro versions, or with a special COM enabled license
Parameters:
objrs or varobjrs	= the recordset
nRowBegin			= the starting row in the worksheet
nNumRows			= total number of records to retrieve,or -1 to retrieve all available.
nColBegin			= it applies only to the options LAYWKGETRECORDSET_BY_COLUMN_INDEX and LAYWKGETRECORDSET_BY_COLUMN_INDEX_WITH_COLUMN_RENAMING
the column in worksheet from which to begin.
nOptions			= enum {
LAYWKGETRECORDSET_BY_COLUMN_INDEX = 0,						// beginning with the starting column nColBegin retrieve all fields (will add columns as necessary)
LAYWKGETRECORDSET_BY_COLUMN_INDEX_WITH_COLUMN_RENAMING,		// same as LAYWKGETRECORDSET_BY_COLUMN_INDEX, except that it will also rename all columns the field names
LAYWKGETRECORDSET_BY_COLUMN_NAME,							// it retrieves only the data from those fields whose names match column names
LAYWKGETRECORDSET_BY_COLUMN_LABEL,							// it retrieves only the data from those fields whose names match column labels
};

Return values:
TRUE for success; otherwise FALSE.

Example:
        void	recordset_to_worksheet()
        {
            Object		ocrs;
            ocrs = CreateObject("ADODB.Recordset");
            ocrs.open("select * from customers", "Provider=SQLOLEDB; Data Source=myServer; Initial Catalog=northwind; User ID=myID; Password=myPassword;");
            Worksheet		wks("Data1");
            // Put the recordset into worksheet:
            BOOL			bRet = wks.PutRecordset(ocrs, 0, -1, 0, LAYWKGETRECORDSET_BY_COLUMN_INDEX_WITH_COLUMN_RENAMING);
            out_int("bRet = ", bRet);
        }

Summary:
Sample data:
Header file: wksheet.h
See also: UpdateRecordset
Worksheet::PutRecordset
Prototype:
PUBLIC  BOOL PutRecordset(_VARIANT &varobjrs,int nRowBegin = 0,int nNumRows = -1,int nColBegin = 0,int nOptions = LAYWKGETRECORDSET_BY_COLUMN_INDEX)
Remarks: Put the data from a recordset into the worksheet. This function is available only for OriginPro versions, or with a special COM enabled license
Parameters:
objrs or varobjrs	= the recordset
nRowBegin			= the starting row in the worksheet
nNumRows			= total number of records to retrieve,or -1 to retrieve all available.
nColBegin			= it applies only to the options LAYWKGETRECORDSET_BY_COLUMN_INDEX and LAYWKGETRECORDSET_BY_COLUMN_INDEX_WITH_COLUMN_RENAMING
the column in worksheet from which to begin.
nOptions			= enum {
LAYWKGETRECORDSET_BY_COLUMN_INDEX = 0,						// beginning with the starting column nColBegin retrieve all fields (will add columns as necessary)
LAYWKGETRECORDSET_BY_COLUMN_INDEX_WITH_COLUMN_RENAMING,		// same as LAYWKGETRECORDSET_BY_COLUMN_INDEX, except that it will also rename all columns the field names
LAYWKGETRECORDSET_BY_COLUMN_NAME,							// it retrieves only the data from those fields whose names match column names
LAYWKGETRECORDSET_BY_COLUMN_LABEL,							// it retrieves only the data from those fields whose names match column labels
};

Return values:
TRUE for success; otherwise FALSE.

Example:
        void	recordset_to_worksheet()
        {
            Object		ocrs;
            ocrs = CreateObject("ADODB.Recordset");
            ocrs.open("select * from customers", "Provider=SQLOLEDB; Data Source=myServer; Initial Catalog=northwind; User ID=myID; Password=myPassword;");
            Worksheet		wks("Data1");
            // Put the recordset into worksheet:
            BOOL			bRet = wks.PutRecordset(ocrs, 0, -1, 0, LAYWKGETRECORDSET_BY_COLUMN_INDEX_WITH_COLUMN_RENAMING);
            out_int("bRet = ", bRet);
        }

Summary:
Sample data:
Header file: wksheet.h
See also: UpdateRecordset


PutSPCBlob

Worksheet::PutSPCBlob
Prototype:
PUBLIC  BOOL PutSPCBlob(_VARIANT &varBlob,int nRow = -1,int nCol = 0,int nRepaintMode = 0)
Remarks: Put the data from an SPC blob into the worksheet. This function is available only for OriginPro versions, or with a special COM enabled license
Parameters:
varBlob = the VARIANT blob containing the data
nRow = Optional row number to begin the import at
nCol = Optional column number to begin the import at
nRepaintMode = Window Refresh mode

Return values:
TRUE for success; otherwise FALSE

Example:
    void	blob_to_wks()
    {
        Object			oSpcIO;
        string			strPathName = "E:\\myfile.spc";
        // the GRAMS object used for importing the SPC file
        oSpcIO = CreateObject("GSpcIOLib.GSpcIO");
        oSpcIO.OpenFile(strPathName);

        _VARIANT		varBlob;
        varBlob = oSpcIO.SaveBlob();
        Worksheet		wks("Data1");
        BOOL			bRet = wks.PutSPCBlob(varBlob);

        out_int("Return value from PutSPCBlob is ", bRet);
    }

Summary:
Sample data:
Header file: wksheet.h
See also:


SetBounds

Worksheet::SetBounds
Prototype:
PUBLIC  BOOL SetBounds( int iR1 = 0, int iC1 = 0, int iR2 = -1, int iC2 = -1 )
Remarks: Set the begining and ending row indices for the specified columns in this Worksheet.
Parameters:
iR1=Input begining row index (0 based)
iC1=Input begining column index (0 based offset, default 0 is first column)
iR2=Input ending row index (0 based)
iC2=Input ending column index (0 based offset, default -1 is last column)

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        // usage
        // wks_set_bound 1 0;// to clear worksheet
        // wks_set_bound 3 200;// show rows from 3 to 200
        void wks_set_bound(int nBegin, int nEnd)
        {
            Worksheet wks = Project.ActiveLayer();
            // convert LabTalk index into C index
            int nR1 = nBegin -1;
            int nR2 = nEnd -1;

            wks.SetBounds(nR1, 0, nR2);
        }

Summary:
Sample data:
Header file: wksheet.h
See also:


SetCell

Worksheet::SetCell
Prototype:
PUBLIC  BOOL SetCell(int nRow, int nCol, LPCSTR lpcszText)
Remarks: Set the value at the location (nRow, nCol) in the worksheet as a string
Parameters:
nRow = Row number with zero offset
nCol = Column number with zero offset
lpcszText = string to be set to location (nRow, nCol)

Return values:
TRUE for success; otherwise FALSE.

Example:
        Worksheet wks("Data1");
        string strText="Monday";
        wks.SetCell(0, 0, strText);
        string cellText;
        wks.GetCell(0, 0, cellText);
        printf("Value at (0,0) location is %s\n", cellText);

Summary:
Sample data:
Header file: wksheet.h
See also: Cell GetCell TCell
Worksheet::SetCell
Prototype:
PUBLIC  BOOL SetCell(int nRow, int nCol, double value)
Remarks: Set the value at the location (nRow, nCol) in the worksheet
Parameters:
nRow = Row number with zero offset
nCol = Column number with zero offset
value = Value to set at the location (nRow, nCol)

Return values:
TRUE for success; otherwise FALSE.

Example:
        Worksheet wks("Data1");
        double value = 1000.05;
        wks.SetCell(0, 0, value);
        double cellValue = wks.Cell(0, 0);
        printf("Value at (0,0) location is %f\n", cellValue);

Summary:
Sample data:
Header file: wksheet.h
See also: Cell GetCell TCell


SetColDesignations

Worksheet::SetColDesignations
Prototype:
PUBLIC  BOOL SetColDesignations(LPCSTR lpcszDesignations, BOOL bRepeat = TRUE)
Remarks: Used to apply designation pattern to entire worksheet
Parameters:
lpcszDesignations - designation pattern
Possible values for designations:
'X' - X column
'Y' - Y column
'Z' - Z column
'E' - Y error column
'L' - label column
'M' - X error column
'N' - ignore column
bRepeat	- repeat pattern. Defines how the pattern is applied
if number of columns in worksheet is larger then length of pattern.
Possible values:
TRUE - repeat entire pattern
FALSE - set designations for the rest of columns to be the last one deifined by pattern

Return values:
TRUE for success. Otherwise FALSE;

Example:
        // the following code will set column designations in worksheet "Data1"		// 1st column - X
        // 2nd column - Y
        // 3rd column - label
        // 4th column - Y
        // 5rd column - label
        // pattern will repeat if worksheet contains more than 5 columns
        Worksheet wks("Data1");
        wks.SetColDesignations("XYLYL");

Summary:
Sample data:
Header file: wksheet.h
See also:


SetColFormats

Worksheet::SetColFormats
Prototype:
PUBLIC  BOOL SetColFormats(LPCSTR lpcszFormats, BOOL bRepeat = TRUE)
Remarks: sets the column formats in the specified worksheet.
Parameters:

Return values:

Example:
        // the following code will set column format in worksheet "Data1"
        // 1st column - Numeric (0)
        // 2nd column - Text	(1)
        // 3rd column - Time	(2)
        // 4th column - Date	(3)
        // 5th column - Text and Numeric (9)
        Worksheet wks("Data1");
        string strFormats="01239";
        wks.SetColFormats(strFormats);

Summary:
Sample data:
Header file: wksheet.h
See also:


SetLowerBound

Worksheet::SetLowerBound
Prototype:
PUBLIC  BOOL SetLowerBound( int iR1, int iC1 = 0, int iC2 = -1 )
Remarks: Set the begining row indices for the specified columns in this Worksheet.
Parameters:
iR1=Input begining row index (0 based)
iC1=Input begining column index (0 based offset, default 0 is first column)
iC2=Input ending column index (0 based offset, default -1 is last column)

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        Worksheet wks = Project.ActiveLayer();

        int nR1 = 5;
        wks.SetLowerBound(nR1);

Summary:
Sample data:
Header file: wksheet.h
See also:


SetRange

Worksheet::SetRange
Prototype:
PUBLIC  BOOL SetRange( int iR1, int iR2, int iC1 = 0, int iC2 = -1 )
Remarks: Set the begining and ending row indices for the specified columns in this Worksheet.
Parameters:
iR1=Input begining row index (0 based)
iR2=Input ending row index (0 based)
iC1=Input begining column index (0 based offset, default 0 is first column)
iC2=Input ending column index (0 based offset, default -1 is last column)

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        // usage
        // wks_set_range 1 0;// to clear worksheet
        // wks_set_range 3 200;// show rows from 3 to 200
        void wks_set_range(int nBegin, int nEnd)
        {
            Worksheet wks = Project.ActiveLayer();
            // convert LabTalk index into C index
            int nR1 = nBegin -1;
            int nR2 = nEnd -1;

            wks.SetRange(nR1, nR2);
        }

Summary:
Sample data:
Header file: wksheet.h
See also:


SetUpperBound

Worksheet::SetUpperBound
Prototype:
PUBLIC  BOOL SetUpperBound( int iR2, int iC1 = 0, int iC2 = -1 )
Remarks: Set the ending row indices for the specified columns in this Worksheet. Index values are 0 based offsets so use SetUpperBound(-1) to dispaly no rows.
Parameters:
iR2=Input ending row index (0 based)
iC1=Input begining column index (0 based offset, default 0 is first column)
iC2=Input ending column index (0 based offset, default -1 is last column)

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        Worksheet wks = Project.ActiveLayer();

        int nR2 = 25;
        wks.SetUpperBound(nR2);

Summary:
Sample data:
Header file: wksheet.h
See also:


ShowLabels

Worksheet::ShowLabels
Prototype:
PUBLIC  void ShowLabels(BOOL bShow = TRUE)
Remarks: Show [Hide] column labels in Origin c
Parameters:
bShow = TRUE (default) shows Column Labels
FALSE will hide Column Labels

Return values:
None.

Example:
        void show_wks_labels()
        {
            Worksheet wks("data1");
            string strLabel = "Elapsed\n(in sec.)";
            BOOL b = wks.Columns(0).SetLabel(strLabel);
            wks.ShowLabels();
        }

Summary:
Sample data:
Header file: wksheet.h
See also: SetLabel GetLabel


TCell

Worksheet::TCell
Prototype:
PUBLIC  string TCell(int nRow, int nCol)
Remarks: Get the value at the location (nRow, nCol) in the worksheet as a string
Parameters:
nRow = Row number with zero offset
nCol = Column number with zero offset

Return values:
string at the location (nRow, nCol) in the worksheet

Example:
        Worksheet wks("Data1");
        string strText="Monday";
        wks.SetCell(0, 0, strText);
        string cellText = wks.TCell(0, 0);
        printf("Value at (0,0) location is %s\n", cellText);

Summary:
Sample data:
Header file: wksheet.h
See also: Cell GetCell SetCell


Type

Worksheet::Type
Prototype:
PUBLIC  BOOL	Type(DWORD dwTarget, LPCTSTR lpcszNotesWindow = NULL, int numCols = 5, int nTab = 0, int nRepeatCol = 0, TreeNode &trRanges = NULL)
Remarks: Dump the contents of the worksheet into the designated target window.
Parameters:
dwTarget = enum {
TYPETARGET_SCRIPT_WINDOW	= 0x00000001UL,		// to the Script window
TYPETARGET_NAMED_WINDOW		= 0x00000002UL,		// to the particular Notes window
TYPETARGET_OUTPUTLOG		= 0x00000004UL,		// to output log
TYPETARGET_SHOW_ERROR		= 0x00000008UL,		// show errors
};
These bits cab be combined.
Note: TYPETARGET_SHOW_ERROR is a constant which should be combined (bitwise "OR-ed") with other constants.
In the case it is combined with TYPETARGET_NAMED_WINDOW, it will report into Script Window (or other output)
when the Notes window with the supplid name does not exist.In other words, it is supposed to make the Type method
"report" method errors (same as type.wks() method of LabTalk works). If TYPETARGET_SHOW_ERROR is supplid alone,
nothing should happen.
lpcszNotesWindow =	the name of the notes window to receive the output
(used only for TYPETARGET_NAMED_WINDOW).
numCols = the number of columns in one block
nTab = tab width (if 0, use worksheet column width as tab width)
nRepeatCol = the 1-offset index of the column which is to appear at
the beginning of every block

Return values:
TRUE for sccess otherwise FALSE.

Example:
        void	worksheet_type()
        {
            Worksheet	wks("Data1");
            BOOL		bRet = wks.Type(TYPETARGET_OUTPUTLOG | TYPETARGET_SHOW_ERROR, NULL, 2, 0, 1);

            out_int("bRet = ", bRet);
        }

Summary:
Sample data:
Header file: wksheet.h
See also:
Worksheet::Type
Prototype:
PUBLIC  BOOL Type(DWORD dwTarget, LPCTSTR lpcszNotesWindow = NULL, int numCols = 5, int nTab = 0, int nRepeatCol = 0)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: wksheet.h
See also:


UpdateOrigin

Worksheet::UpdateOrigin
Prototype:
PUBLIC  BOOL UpdateOrigin()
Remarks: Updates the underlying Origin worksheet from Excel. This method is the equivalent of the combined Layer -s; and set %H -ui; LabTalk commands.
Parameters:

Return values:
Returns TRUE on success and FALSE on failure.

Example:
        Page			pg("Book1");
        Worksheet		wks;
        wks = (Worksheet)pg.Layers("Sheet1");

        BOOL			bOK = wks.UpdateOrigin();

Summary:
Sample data:
Header file: wksheet.h
See also:


UpdateRecordset

Worksheet::UpdateRecordset
Prototype:
PUBLIC  BOOL UpdateRecordset(Object &objrs,int nRowBegin = 0,int nNumRows = -1,int nColBegin = 0,int nNumCols = -1)
Remarks: Put the data from the worksheet into the recordset. The locktype of the recordset must be appropriate for adding data which means that it should not be read-only. This function is available only for OriginPro versions, or with a special COM enabled license
Parameters:
objrs or varobjrs	= the recordset
nRowBegin			= the starting row in the worksheet
nNumRows			= total number of rows to put,or -1 to put all rows.
nColBegin			= the worksheet column from which to start (the first column will be used for the first field, etc.).
nNumCols			= the number of columns to use, beginning with nColBegin, or -1 to use all columns to the right of nColBegin.
If there are less columns than fields, the remaining fields will be set to null.

Return values:
TRUE for success; otherwise FALSE.

Example:
        void	worksheet_recordset()
        {
            Object		ocrs;
            ocrs = CreateObject("ADODB.Recordset");
            ocrs.open("select * from customers", "Provider=SQLOLEDB; Data Source=myServer; Initial Catalog=northwind; User ID=myID; Password=myPassword;");
            Worksheet		wks("Data1");
            // Put changes in worksheet back to the recordset:
            BOOL			bRet = wks.UpdateRecordset(ocrs);
            out_int("bRet = ", bRet);
        }

Summary:
Sample data:
Header file: wksheet.h
See also: PutRecordset
Worksheet::UpdateRecordset
Prototype:
PUBLIC  BOOL UpdateRecordset(_VARIANT &varobjrs,int nRowBegin = 0,int nNumRows = -1,int nColBegin = 0,int nNumCols = -1)
Remarks: Put the data from the worksheet into the recordset. The locktype of the recordset must be appropriate for adding data which means that it should not be read-only. This function is available only for OriginPro versions, or with a special COM enabled license
Parameters:
objrs or varobjrs	= the recordset
nRowBegin			= the starting row in the worksheet
nNumRows			= total number of rows to put,or -1 to put all rows.
nColBegin			= the worksheet column from which to start (the first column will be used for the first field, etc.).
nNumCols			= the number of columns to use, beginning with nColBegin, or -1 to use all columns to the right of nColBegin.
If there are less columns than fields, the remaining fields will be set to null.

Return values:
TRUE for success; otherwise FALSE.

Example:
        void	worksheet_recordset()
        {
            Object		ocrs;

            ocrs = CreateObject("ADODB.Recordset");

            ocrs.open("select * from customers", "Provider=SQLOLEDB; Data Source=myServer; Initial Catalog=northwind; User ID=myID; Password=myPassword;");

            Worksheet		wks("Data1");

            // Put changes in worksheet back to the recordset:
            BOOL			bRet = wks.UpdateRecordset(ocrs);
            out_int("bRet = ", bRet);
        }

Summary:
Sample data:
Header file: wksheet.h
See also: PutRecordset


Worksheet

Worksheet::Worksheet
Prototype:
PUBLIC  Worksheet(LPCTSTR lpcszWksName)
Remarks: Constructor for the Worksheet class that creates a wrapper Worksheet object which is a reference to an internal Origin worksheet object.If the internal origin object is not a worksheet object, then a reference cannot be created.
Parameters:
lpcszWksName = The name of an Origin worksheet object

Return values:

Example:
        Worksheet wks("data1");
        if(!wks)
            out_str("There is no such worksheet");

Summary:
Sample data:
Header file: wksheet.h
See also:
Worksheet::Worksheet
Prototype:
PUBLIC  Worksheet(Layer & layer)
Remarks: Worksheet is one of the wrapper objects that is a reference to the actual internal Origin object. You can construct a new Worksheet object from another layer object. The worksheet will become invalid if the layer to construct with is actually not a worksheet
Parameters:

Return values:

Example:
        Worksheet wks(Project.ActiveLayer());
        if(!wks)
        {
            out_str("The active layer is not a worksheet, or there is nothing in the project");
        }
        else
            printf("Worksheet %s has %d columns\n",wks.GetPage().GetName(),wks.GetNumCols());

        Worksheet wks1 = Project.ActiveLayer();
        Worksheet wks2(wks1);
        if(!wks2)
        {
            out_str("The active layer is not a worksheet, or there is nothing in the project");
        }
        else
            printf("Worksheet %s has %d columns\n",wks2.GetPage().GetName(),wks2.GetNumCols());

Summary:
Sample data:
Header file: wksheet.h
See also:


WorksheetPage

Class: WorksheetPage

Description: The WorksheetPage class provides methods and properties common to all internal Origin worksheet pages (windows). The Project class contains a collection of WorksheetPage objects. An Origin C WorksheetPage object is a wrapper object that is a reference to an internal Origin worksheet page object. Origin C wrapper objects do not actually exist in Origin and merely refer to the internal Origin object. Consequently, multiple Origin C wrapper objects can refer to the same internal Origin object. The WorksheetPage class is derived from the Page, PageBase, and OriginObject classes from which it inherits methods and properties.

Hierarchy:

OriginObject
 PageBase
 Page
 WorksheetPage

Sample:

        // Assumes Data1 window with at least one Column exists in Origin
        WorksheetPage wp;
        Worksheet wks;
        Column col;

        wp = Project.WorksheetPages("Data1");           // Get Data1 page from WorksheetPages collection
        if(wp)                                          // If wp IsValid...
        {
            wks = (Worksheet) wp.Layers(0);             // Get Worksheet from Layers collection
            if(wks)                                     // If wks IsValid...
            {
                col = wks.Columns(0);                   // Get first Column in Worksheet
                if(col)                                 // If col IsValid...
                {
                    Dataset ds(col);				    // Create Dataset object and attach to column
                    if(ds)                              // If ds IsValid...
                    {
                        ds.SetSize(10);                 // Set size of data set
                        for(int ii = 0; ii < 10; ii++ )
                            ds[ii]=2*ii+5;              // Fill data set/column with values
                    }
                }
            }
        }


WorksheetPage

WorksheetPage::WorksheetPage
Prototype:
PUBLIC  WorksheetPage(LPCTSTR lpcszName)
Remarks: Construct a WorksheetPage object using the name of an existing page.
Parameters:
lpcszName = The name of an existing page.

Return values:

Example:
        WorksheetPage wp;
        wp.Create("origin.otw");
        if( wp.IsValid() )
        {
            WorksheetPage wp2(wp.GetName());
            if( wp2.IsValid() )
                printf("wp and wp2 are both attached to '%s'\n", wp2.GetName());
        }

Summary:
Sample data:
Header file: Page.h
See also: Create
WorksheetPage::WorksheetPage
Prototype:
PUBLIC  WorksheetPage(PageBase &page)
Remarks: Construct a WorksheetPage object using the name of an existing page.
Parameters:
page = A reference to an existing page.

Return values:

Example:
        WorksheetPage wp;
        wp.Create("origin.otw");
        if( wp.IsValid() )
        {
            WorksheetPage wp2(wp);
            if( wp2.IsValid() )
                printf("wp and wp2 are both attached to '%s'\n", wp2.GetName());
        }

Summary:
Sample data:
Header file: Page.h
See also: Create


file

Class: file

Description: The Origin C file class provides read/write access to binary files using unbuffered io (immediate disk access) similar to the MFC CFile class. See also the stdioFile class for buffered stream io to text files.

Hierarchy:

file

Sample:

        char szTemp[MAXFULLPATH];
        GetTempPath(MAXFULLPATH, szTemp); // Get temp folder path.
        string strFile = szTemp + "\\test.Dat";
        file ff(strFile, file::modeCreate | file::modeWrite); // Create a new write only file.
        int bb[4] = {1, 2, 3, 4};
        int iSize = sizeof(bb);
        ff.Write(bb,iSize);
        ff.Close();


Close

file::Close
Prototype:
PUBLIC  BOOL Close()
Remarks: Closes the file associated with the indicated file object. The file is then no longer available for reading and writing.
Parameters:

Return values:
A value of FALSE or 0 indicates fail to close file and a value of TRUE or a
non-zero indicates sucessfully closing file.

Example:
            char szTemp[MAXFULLPATH];
            GetTempPath(MAXFULLPATH, szTemp); // Get temp folder path.
            string strFile = szTemp + "\\test.txt";
            file ff;
            if( ff.Open(strFile, file::modeCreate | file::modeWrite) )
            {
                ff.Write(strFile, strFile.GetLength()); // Write the file name into the file.
                ff.Close(); // Close the file when we are done.
            }

Summary: Close the file associated with the indicated file object.
Sample data:
Header file: File.h
See also: Open


file

file::file
Prototype:
PUBLIC  file()
Remarks: The default constructor does not open a file but rather sets m_hFile to file::hFileNull.
Parameters:

Return values:

Example:
            file ff;

Summary: Set the public data member m_hFile to a null value.
Sample data:
Header file: File.h
See also: Open Close
file::file
Prototype:
PUBLIC  file(LPCTSTR lpszFileName, UINT nOpenFlags)
Remarks: Creates a file object and opens the file having the path specified by the parameter lpszFileName. This constructor combines the functions of the default constructor file() and the Open member function. An exception is thrown if an error occurs while opening the file. Depending on the severity of the error, the user should be alerted by an exception handler.
Parameters:
lpszFileName=A string containing an absolute or relative path to the desired file.
nOpenFlags=Specifies the share and access modes of the opened file.  Modes are defined below and can be combined
using the bitwise OR operator "|".  At least one access and one share mode should be specified.
modeRead		Opens the file in read only mode.
modeWrite		Opens the file in write only mode.
modeReadWrite	Opens the file in read and write modes.
shareCompat		Not available...see shareExclusive below.
shareExclusive	Opens the file disallowing read and write access to all other processes. Construction fails
if file is already opened in read or write mode.
shareDenyWrite	Opens the file disallowing write access to all other processes. Construction fails if file
is already opened in write mode.
shareDenyRead	Opens the file disallowing read access to all other processes. Construction fails if file
is already opened in read mode.
shareDenyNone	Opens the file allowing read and write access to all other processes.
modeNoInherit	Opens the file but disallows inheritance by child processes.
modeCreate		Creates a new file of length 0 bytes.  Pre-existing files are truncated to 0 bytes by default.
modeNoTruncate	Used in combination with modeCreate to specify that pre-existing files should not be truncated.
When used together, modeCreate and modeNoTruncate open a specified file if it exists or	create
the specified file if it does not exist.
typeText		Sets text mode for specified file enabling special processing of carriage return-line feed
character combinations.  Used in derived classes only.
typeBinary		Sets binary mode for specified file.  Used in derived classes only.

Return values:

Example:
            char szTemp[MAXFULLPATH];
            GetTempPath(MAXFULLPATH, szTemp); // Get temp folder path.
            string strFile = szTemp + "\\test.txt";
            file ff(strFile, file::modeCreate | file::modeWrite); // Create a new write only file.
            int bb[4] = {1, 2, 3, 4};
            ff.Write(bb, sizeof(bb));
            ff.Close();

Summary: Create a File object and open the file having the specified path.
Sample data:
Header file: File.h
See also: Open Close


Flush

file::Flush
Prototype:
PUBLIC  BOOL Flush()
Remarks: Force data remaining in the file buffer to be written to the file.
Parameters:

Return values:
TRUE for success and FALSE for error.

Example:
            char szTemp[MAXFULLPATH];
            GetTempPath(MAXFULLPATH, szTemp); // Get temp folder path.
            string strFile = szTemp + "\\test.txt";
            file ff;
            if( ff.Open(strFile, file::modeCreate | file::modeWrite) )
            {
                ff.Write(&strFile, strFile.GetLength()); // Write the file name into the file.
                ff.Flush(); // Make sure the file buffer has been written into the file.
                ff.Close();
            }

Summary:
Sample data:
Header file: File.h
See also: Write


GetHandle

file::GetHandle
Prototype:
PUBLIC  UINT GetHandle()
Remarks: Get the handle of current open file.
Parameters:

Return values:
A variable of type UINT. It is file::hFileNull (an operating-system-independent empty file indicator)
if the handle has not been assigned.

Example:
            file ff;
            bool bOK = ff.Open("C:\\test.txt", file::modeCreate | file::modeReadWrite);
            if(!bOK)
            {
                out_str("Failed to open file C:\test.txt");
                return 0;
            }
            UINT hFile = ff.GetHandle();

Summary:
Sample data:
Header file: File.h
See also:


GetLastError

file::GetLastError
Prototype:
PUBLIC  UINT GetLastError()
Remarks: Get the value of the last error that occured. FileError::none = No error occurred. FileError::generic = An unspecified error occurred. FileError::fileNotFound = The file could not be located. FileError::badPath = All or part of the path is invalid. FileError::tooManyOpenFiles = The permitted number of open files was exceeded. FileError::accessDenied = The file could not be accessed. FileError::invalidFile = There was an attempt to use an invalid file handle. FileError::removeCurrentDir = The current working directory cannot be removed. FileError::directoryFull = There are no more directory entries. FileError::badSeek = There was an error trying to set the file pointer. FileError::hardIO = There was a hardware error. FileError::sharingViolation = SHARE.EXE was not loaded, or a shared region was locked. FileError::lockViolation = There was an attempt to lock a region that was already locked. FileError::diskFull = The disk is full. FileError::endOfFile = The end of file was reached.
Parameters:

Return values:

Example:
            This function open/create the file c:\test.txt and get the value of the last error
            if open file fails.
            void run_GetLastError()
            {
                file ff;
                string strFile = "C:\\test.txt";
                string FileErr;
                BOOL bOK;

                bOK = ff.Open(strFile, file::modeCreate | file::modeWrite); //Create a write only file and open it
                if (!bOK)
                {
                    printf("failed to open the file");  //the string should not be output
                    FileErr = ff.GetLastError();
                }
                else
                {
                    ff.Close();
                }
            }

Summary:
Sample data:
Header file: File.h
See also:


GetLength

file::GetLength
Prototype:
PUBLIC  DWORD GetLength()
Remarks: Obtains the current logical length of the file in bytes.
Parameters:

Return values:
The length of the file.

Example:
            string strFile = "c:\\myfile.txt";
            file ff;
            if( ff.Open(strFile, file::modeRead|file::typeBinary) )
            {
                DWORD dwLen = ff.GetLength();
                printf("Length of file %s is %d bytes\n", strFile, dwLen);
                ff.Close();
            }

Summary:
Sample data:
Header file: File.h
See also:


GetPosition

file::GetPosition
Prototype:
PUBLIC  LONG GetPosition()
Remarks: Get the current value of the file pointer which is an offset from the beginning of the file.
Parameters:

Return values:
Returns the current value of the file pointer.

Example:
            char szTemp[MAXFULLPATH];
            GetTempPath(MAXFULLPATH, szTemp); // Get temp folder path.
            string strFile = szTemp + "\\test.txt";
            file ff;
            if( ff.Open(strFile, file::modeCreate | file::modeWrite) )
            {
                int i = 10;
                int ia[4] = {1, 2, 3, 4};
                LONG lPosition;

                ff.Write(&i, sizeof(i));		// Write 1 int (4 bytes) to file.
                lPosition = ff.GetPosition();	// Position now equals 4.
                ff.Write(ia, sizeof(ia));		// Write 4 ints (16 bytes) to file following previous int.
                lPosition = ff.GetPosition();	// Position now equals 20.
                ff.SeekToBegin();				// Set file pointer to start of file.
                lPosition = ff.GetPosition();	// Position now equals 0.
                ff.Close();
            }

Summary:
Sample data:
Header file: File.h
See also: Seek


IsOpen

file::IsOpen
Prototype:
PUBLIC  BOOL IsOpen()
Remarks: Check file object is open or not, when use a method of File object which is not open will lead a runtime error. Use this function before you call the method of File object.
Parameters:

Return values:

Example:
            This function opens/creates the file c:\test.txt.
            void run_IsOpen()
            {
                file ff;
                BOOL bOK;

                string strFile = "C:\\test.txt";

                bOK = ff.Open(strFile, file::modeCreate | file::modeWrite);  //create a new write only file and open it
                if(!bOK)
                    out_str("failed to open the file");
                else
                {
                    if( ff.IsOpen() )
                    {
                        printf("The ff file is open");  //The string should be output
                        ff.Close();  //Close the ff file
                    }
                }
            }

Summary:
Sample data:
Header file: File.h
See also:


Open

file::Open
Prototype:
PUBLIC  BOOL Open(LPCTSTR lpszFileName, UINT nOpenFlags)
Remarks: A safe method of opening a file when failure is a likely outcome. The Open member function should be called after the default File constructor has been invoked. It is a safe method of opening a file because it returns FALSE or 0 on failure instead of throwing an exception. When a file is opened the current pointer position is initialized to 0.
Parameters:
lpszFileName=A string containing an absolute or relative path to the desired file.
nOpenFlags=Specifies the share and access modes of the opened file.  See the default File constructor for
definitions of all supported modes.  Modes can be combined using the bitwise OR operator "|".  At least one access
and one share mode should be specified.

Return values:
Returns FALSE or 0 if the file fails to open and returns TRUE or a non-zero if the file opens successfully.

Example:
            file ff;
            //Get the origin folder path.
            string strOriginPath;
            strOriginPath = GetAppPath() + "OriginC";
            string strFile = strOriginPath + "\\test.txt";
            BOOL bOK = ff.Open(strFile, file::modeCreate | file::modeWrite);		//create a new write only file.
            int bb[4] = {1, 2, 3, 4};
            ff.Write(bb, sizeof(bb));
            ff.Close();
            bOK = ff.Open(strFile, file::modeRead | file::shareDenyWrite);			//open the file created previously and set it to read only file.
            int aa;
            ff.Read(&aa, sizeof(aa));		//aa equals 1 now.
            ff.Close();
            //Get temp folder path.
            char sztemp[MAXFULLPATH];
            DWORD aa = GetTempPath(MAXFULLPATH, sztemp);
            string str1, strFile;
            str1 = sztemp;
            strFile = str1 + "\\test.txt";
            bOK = ff.Open(strFile, file::modeCreate | file::modeReadWrite );
            int bb[4] = {1, 2, 3, 4};
            ff.Write(bb, sizeof(bb));
            int aa;
            ff.Read(&aa, sizeof(aa));		//aa equals 1 now.
            ff.Close();
            //This console program is used to copy files.
            int test()
            {
                char sztemp[MAXFULLPATH];
                DWORD aa = GetTempPath(MAXFULLPATH, sztemp);
                string str1, strFile, strFile2;
                str1 = sztemp;
                strFile = str1 + "\\test.txt";
                strFile2 = str1 + "\\dest.txt";

                   // constructing these file objects doesn't open them
                   file sourceFile;
                   file destFile;

                   // open the source file for reading
                   bool bOK = sourceFile.Open(strFile, file::modeRead | file::shareDenyWrite);
                   if(!bOK)
                   {
                       out_str("failed to open the source file");
                       return 0;
                   }

                   // open the destination file for writing
                   bOK = destFile.Open(strFile2, file::modeWrite | file::shareExclusive | file::modeCreate);
                   if(!bOK)
                   {
                       out_str("failed to open the destination file");
                       return 0;
                   }

                   BYTE buffer[196];
                   DWORD dwRead;

                // Read in 196-byte blocks. Remember how many bytes were actually read, and try to
                // write that many out. This loop ends when there are no more bytes to read.
                  do
                  {
                     dwRead = sourceFile.Read(buffer, 196);
                     destFile.Write(buffer, dwRead);
                  }
                  while (dwRead > 0);

                  // Close both files
                  destFile.Close();
                  sourceFile.Close();

                  return 1;
            }

Summary: Open a file returning FALSE or 0 on failure and TRUE or a non-zero on success.
Sample data:
Header file: File.h
See also: file Close


Read

file::Read
Prototype:
PUBLIC  UINT Read(void *lpBuf, UINT nCount)
Remarks: Read data into a buffer from the file associated with the file object.
Parameters:
lpBuf=A buffer where the data read is stored.
nCount=The number of bytes to read from the file indicated by the file object.

Return values:
Number of bytes read from the file.  May be less than nCount if EOF is reached.

Example:
            //read integer and array of integers.
            file ff;
            bool bOK = ff.Open("c:\\test.dat", file::modeRead);
            if(!bOK)
            {
                out_str("Failed to open file C:\test.txt");
                return 0;
            }
            int aa, intlist[10];
            ff.Read(&aa, sizeof(aa));
            ff.Read(intlist, sizeof(intlist));
            ff.Read(&intlist[0], sizeof(intlist));

            //read double
            double bb;
            ff.Read(&bb, sizeof(bb));

            //read structure
            WIN32_FIND_DATAA cc;
            ff.Read(&cc, sizeof(cc));

            //read char array
            char dd[100];
            ff.Read(dd, sizeof(dd));

            //read vector
            vector<int> kk;
            kk.SetSize(5);
            int size = sizeof(int) * kk.GetSize();
            ff.Read(kk, size);

Summary:
Sample data:
Header file: File.h
See also: Write


ReadFloat

file::ReadFloat
Prototype:
PUBLIC  UINT ReadFloat(void *pDestBuffer, int nDataTypeSize, UINT nItemCount, BOOL bIsLittleEndian = TRUE)
Remarks:
Parameters:

Return values:

Example:

            int test_file_readfloat_writefloat()
            {
                file ff;

                string strFile = "readwritefloat.dat";

                BOOL bOK = ff.Open(strFile, file::modeCreate | file::modeWrite);
                if(!bOK)
                {
                    out_str("Could not open the \\readwritefloat.dat file.");
                    ASSERT(false);
                    return 0;
                }

                vector<float> vecfloat={2,4,6,8};
                vector<double> vecdouble={1,3,5,7};

                ff.WriteFloat(&vecfloat,sizeof(float),vecfloat.GetSize());

                int nposition=ff.GetPosition();
                ASSERT(nposition==16);

                ff.WriteFloat(&vecdouble, sizeof(double), vecdouble.GetSize(), false);

                nposition=ff.GetPosition();
                ASSERT(nposition==48);
                ff.Close();

                bOK = ff.Open(strFile, file::modeRead);
                if(!bOK)
                {
                    out_str("Could not open the \\readwritefloat.dat file.");
                    ASSERT(false);
                    return 0;
                }

                ff.SeekToBegin();

                vector<float> vecf2(4);
                vector<double> vecd2(4);

                ff.ReadFloat(&vecf2,sizeof(float),vecfloat.GetSize());
                ff.ReadFloat(&vecd2,sizeof(double), vecdouble.GetSize(),false);

                for(int i=0;i<4;i++)
                {
                    printf("%f\t%f\n",vecf2[i],vecd2[i]);
                    ASSERT(round(vecfloat[i],8)==round(vecf2[i],8));
                    ASSERT(round(vecdouble[i],8)==round(vecd2[i],8));
                }

                ff.Close();

                return 1;
        }

Summary:
Sample data:
Header file: File.h
See also: ReadInt


ReadInt

file::ReadInt
Prototype:
PUBLIC  UINT ReadInt(void *pDestBuffer, int nDataTypeSize, UINT nItemCount, BOOL bIsLittleEndian = TRUE)
Remarks: It is used to support Little Endian and Big Endian read and write binary data .
Parameters:
nDataTypeSize: Must be size of datatype, for integal, 1, 2 and 4, for float. 4 and 8.
nItemCount: Number of data;
bIsLittleEndian: TRUE, use Little Endian way, FALSE use Big Endian way, default value is TRUE.

Return values:
The number of items read from file.

Example:
           #define INT32_ITEM_COUNT	2
           #define INT16_ITEM_COUNT	4

           // ASCII: A  B  C  D  1  2  3  4
           // HEX  : 41 42 43 44 31 32 33 34
           //

            int  test_read_endian()
            {
                file fil;

                short i16[INT16_ITEM_COUNT];
                long i32[INT32_ITEM_COUNT];

                i16[0] = 0x4241;
                i16[1] = 0x4443;
                i16[2] = 0x3231;
                i16[3] = 0x3433;

                i32[0] = 0x44434241;
                i32[1] = 0x34333231;

                string strFile = "C:\\end.bin";

                if( fil.Open(strFile, file::modeCreate | file::modeWrite ) )
                {
                    int i = fil.WriteInt(i16, sizeof(short), INT16_ITEM_COUNT);
                    ASSERT( INT16_ITEM_COUNT == i);

                    i = fil.WriteInt(i32, sizeof(long), INT32_ITEM_COUNT);
                    ASSERT( INT32_ITEM_COUNT == i);

                    i = fil.WriteInt(i16, sizeof(short), INT16_ITEM_COUNT, FALSE);
                    ASSERT( INT16_ITEM_COUNT == i);

                    i = fil.WriteInt(i32, sizeof(long), INT32_ITEM_COUNT, FALSE);
                    ASSERT( INT32_ITEM_COUNT == i);

                    fil.Close();
                }

                else
                {
                    string strPromptExist = "Before testing, please delete file: " + strFile;
                    MessageBox( NULL, strPromptExist );
                }

                if( fil.Open(strFile, file::modeRead|file::shareDenyWrite) )
                {
                    int i = fil.ReadInt(i16, sizeof(short), INT16_ITEM_COUNT);
                    ASSERT( INT16_ITEM_COUNT == i);
                    ASSERT( i16[0] == 0x4241);
                    ASSERT( i16[1] == 0x4443);
                    ASSERT( i16[2] == 0x3231);
                    ASSERT( i16[3] == 0x3433);

                    fil.SeekToBegin();
                    i = fil.ReadInt(i32, sizeof(long), INT32_ITEM_COUNT);
                    ASSERT( INT32_ITEM_COUNT == i);
                    ASSERT( i32[0] == 0x44434241);
                    ASSERT( i32[1] == 0x34333231);

                    fil.SeekToBegin();
                    i = fil.ReadInt(i16, sizeof(short), INT16_ITEM_COUNT, FALSE);
                    ASSERT( INT16_ITEM_COUNT == i);
                    ASSERT( i16[0] == 0x4142);
                    ASSERT( i16[1] == 0x4344);
                    ASSERT( i16[2] == 0x3132);
                    ASSERT( i16[3] == 0x3334);

                    fil.SeekToBegin();
                    i = fil.ReadInt(i32, sizeof(long), INT32_ITEM_COUNT, FALSE);
                    ASSERT( INT32_ITEM_COUNT == i);
                    ASSERT( i32[0] == 0x41424344);
                    ASSERT( i32[1] == 0x31323334);

                    fil.Close();
                }
                return 1;
            }

Summary:
Sample data:
Header file: File.h
See also:


Seek

file::Seek
Prototype:
PUBLIC  LONG Seek(LONG lOffset, UINT nFrom)
Remarks: Moves the pointer to the current file position as specified. Seek enables random access within a file.
Parameters:
lOffset=Number of bytes to move the file pointer relative to and in the direction indicated by nFrom.
nFrom=Specifies the referenece position and direction to move the pointer to the current file position.
file::begin		Moves the current file position lOffset bytes forward from the beginning of the file.
file::current	Moves the current file position lOffset bytes from the current position in the file.
file::end		Moves the current file position lOffset bytes backward from the end of the file.  The value of
lOffset must be negative otherwise the current file position will be outside the file.

Return values:
If the current file position is valid, seek returns the number of bytes from the beginning of the file
otherwise an exception is thrown.

Example:
            file ff;
            bool bOK = ff.Open("C:\\test.txt", file::modeCreate);
            if(!bOK)
            {
                out_str("Failed to open file C:\test.txt");
                return 0;
            }
            LONG lCurrent = ff.Seek(20, file::begin);	// lCurrent = 20.
            lCurrent = ff.Seek(16, file::current);		// lCurrent = 20 + 16 = 36.
            lCurrent = ff.Seek(-16, file::end);			// lCurrent = length of file - 16.

Summary:
Sample data:
Header file: File.h
See also: GetPosition SeekToBegin SeekToEnd


SeekToBegin

file::SeekToBegin
Prototype:
PUBLIC  void SeekToBegin()
Remarks: Sets the file pointer value to the beginning of the file. This is the same as file::Seek(0, file::begin).
Parameters:

Return values:

Example:
            // Assume strFile is a string containing the name of an exsiting file.
            file ff;
            strFile="C:\\test.dat";
            if( ff.Open(strFile, file::modeRead) )
            {
                LONG lFileSize = ff.SeekToEnd(); // Go to the end of the file.
                ff.SeekToBegin(); // Go to the beginning of the file.
                ff.Close();
            }

Summary:
Sample data:
Header file: File.h
See also: GetPosition Seek SeekToEnd


SeekToEnd

file::SeekToEnd
Prototype:
PUBLIC  LONG SeekToEnd()
Remarks: Sets the file pointer value to the end of the file. This is the same as file::Seek(0, file::end).
Parameters:

Return values:
The number of bytes of the whole file

Example:
            // Assume strFile is a string containing the name of an exsiting file.
            file ff;
            strFile="C:\\test.dat";
            if( ff.Open(strFile, file::modeRead) )
            {
                LONG lFileSize = ff.SeekToEnd();
                ff.Close();
            }

Summary:
Sample data:
Header file: File.h
See also: GetPosition Seek SeekToBegin


Write

file::Write
Prototype:
PUBLIC  UINT Write(void *lpBuf, UINT nCount)
Remarks: Write data from a buffer into the file associated with the file object.
Parameters:
lpBuf=A buffer where the data to be written is stored.
nCount=The number of bytes to write from the buffer to the file indicated by the File object.  Carriage return-line
feed character combinations are counted as one byte.

Return values:
The number of bytes written to the file from the buffer.

Example:
        int test_write()
        {
            file ff;
            bool bOK = ff.Open("C:\\test.txt", file::modeCreate | file::modeReadWrite);
            if(!bOK)
            {
                out_str("Failed to open file C:\test.txt");
                return 0;
            }
            int ia = 10;
            ff.Write(&ia, sizeof(ia));			//write 4 to file.
            int ib[4] = {1, 2, 3, 4};
            ff.Write(ib, sizeof(ib));			//write 1, 2, 3, 4 to file following previous 4.

            //write double
            double da = 123.345;
            ff.Write(&da, sizeof(da));

            //write structure
            WIN32_FIND_DATAA sa;
            memset(&sa, 0, sizeof(WIN32_FIND_DATAA));
            sa.dwFileAttributes = 20000;
            sa.ftCreationTime.dwLowDateTime = 10;
            sa.ftCreationTime.dwHighDateTime = 50;
            sa.ftLastAccessTime.dwLowDateTime = 100000;
            sa.ftLastAccessTime.dwHighDateTime = 500000;
            sa.ftLastWriteTime.dwLowDateTime = 1000;
            sa.ftLastWriteTime.dwHighDateTime = 5000;
            sa.nFileSizeHigh = 9000000;
            sa.nFileSizeLow = 1;
            sa.dwReserved0 = 600;
            sa.dwReserved1 = 98745;
            lstrcpy(sa.cFileName, "C:\\Origin70\\OriginC\\origin.h");
            lstrcpy(sa.cAlternateFileName,"originc.h");
            ff.Write(&sa, sizeof(sa));

            //write char array
            char ca[20] = "This is a string.";
            ff.Write(ca, sizeof(ca));

            //write vector
            vector<int> ik = {1, 2, 3, 4, 5};
            int size = sizeof(int) * ik.GetSize();
            ff.Write(ik, size);

            return 1;
        }

Summary:
Sample data:
Header file: File.h
See also: Read WriteString


WriteFloat

file::WriteFloat
Prototype:
PUBLIC  UINT WriteFloat(void *pSrcBuffer, int nDataTypeSize, UINT nItemCount, BOOL bIsLittleEndian = TRUE)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: File.h
See also: ReadFloat


WriteInt

file::WriteInt
Prototype:
PUBLIC  UINT WriteInt(void *pSrcBuffer, int nDataTypeSize, UINT nItemCount, BOOL bIsLittleEndian = TRUE)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: File.h
See also: ReadInt


INIFile

Class: INIFile

Description: The INIFile class provides methods to access data stored in initialization file

Hierarchy:

INIFile

Sample:


GetFileName

INIFile::GetFileName
Prototype:
PUBLIC  string GetFileName()
Remarks: Gets the name of the INI file.
Parameters:

Return values:
the file name of the INI file in the form of a string.

Example:
                    INIFile ini("Origin.ini");;
                    int nNumLevels = ini.ReadInt("Config", "NumLevels", 0);
                    printf("NumLevels = %d", nNumLevels);
                    out_str(ini.GetFileName());

Summary:
Sample data:
Header file: Settings.h
See also:


GetKeyNames

INIFile::GetKeyNames
Prototype:
PUBLIC  int GetKeyNames(StringArray &saKeys, LPCSTR lpcszSection)
Remarks: Get all the key names in a section into a string array.
Parameters:
saKeys - string array to receive the key names
lpcszSection - pointer to the section name to get the key names from

Return values:
number of key names in the array

Example:
            // This function will output an ini file's section and key names.
            void output_ini(LPCSTR lpcszIniFile)
            {
                string str;
                INIFile ini(lpcszIniFile);
                StringArray saSections, saKeys;
                ini.GetSectionNames(saSections);
                for( int iSection = 0; iSection < saSections.GetSize(); iSection++ )
                {
                    printf("%s\n", saSections[iSection]);
                    ini.GetKeyNames(saKeys, saSections[iSection]);
                    for( int iKey = 0; iKey < saKeys.GetSize(); iKey++ )
                    {
                        str = ini.ReadString(saSections[iSection], saKeys[iKey]);
                        printf("    %s = %s\n", saKeys[iKey], str);
                    }
                }
            }

Summary:
Sample data:
Header file: Settings.h
See also:


GetSectionNames

INIFile::GetSectionNames
Prototype:
PUBLIC  int GetSectionNames(StringArray &saSections)
Remarks: Get all the section names into a string array.
Parameters:
saSections - string array to receive the section names

Return values:
number of section names in the array

Example:
            // This function will output an ini file's section and key names.
            void output_ini(LPCSTR lpcszIniFile)
            {
                string str;
                INIFile ini(lpcszIniFile);
                StringArray saSections, saKeys;
                ini.GetSectionNames(saSections);
                for( int iSection = 0; iSection < saSections.GetSize(); iSection++ )
                {
                    printf("%s\n", saSections[iSection]);
                    ini.GetKeyNames(saKeys, saSections[iSection]);
                    for( int iKey = 0; iKey < saKeys.GetSize(); iKey++ )
                    {
                        str = ini.ReadString(saSections[iSection], saKeys[iKey]);
                        printf("    %s = %s\n", saKeys[iKey], str);
                    }
                }
            }

Summary:
Sample data:
Header file: Settings.h
See also:


INIFile

INIFile::INIFile
Prototype:
PUBLIC  INIFile(LPCSTR lpcszFilename = NULL, BOOL bUseIniPath = TRUE)
Remarks: Constructor to determine what INI file to use
Parameters:
lpcszFilename - File name (can specify full path and file name)
bUseIniPath - Set to TRUE for INI path, false for program path

Return values:

Example:
        // This function will output an ini file's section and key names.
        void output_ini(LPCSTR lpcszIniFile)
        {
            INIFile ini1("Origin.ini", FALSE);
            INIFile ini2("Origin.ini");
            int nNumLevels1 = ini1.ReadInt("Config", "NumLevels", 0);
            int nNumLevels2 = ini2.ReadInt("Config", "NumLevels", 0);
            printf("NumLevels in Program folder ini = %d", nNumLevels1);
            printf("NumLevels in ini folder ini = %d", nNumLevels2);
        }

Summary:
Sample data:
Header file: Settings.h
See also:


ReadInt

INIFile::ReadInt
Prototype:
PUBLIC  int ReadInt(LPCSTR lpcszSection, LPCSTR lpcszKey, int nDefault)
Remarks: Retrieves an integer value from the specified section in an initialization file
Parameters:
lpcszSection - section name
lpcszKey - key name
nDefault - return value if section or key is not found in initialization file

Return values:
integer value specified by section and key from initialization file

Example:
            //gets current value for Initial Origin window state from Origin.ini file
            //see "Config" section og Origin.ini for more details
            void test()
            {
                string strFileName = GetAppPath(1)+ "Origin.ini";
                INIFile ini(strFileName);
                printf("Initial Origin window state is %d", ini.ReadInt("Config", "ShowState", -1));
            }

Summary:
Sample data:
Header file: Settings.h
See also:


ReadString

INIFile::ReadString
Prototype:
PUBLIC  string ReadString(LPCSTR lpcszSection, LPCSTR lpcszKey, LPCSTR lpcszDefault = NULL)
Remarks: Reads the value of a key in a given section into a string.
Parameters:
lpcszSection = section name
lpcszKey = key name
lpcszDefault = NULL

Return values:
the value of a key in a given section in the form of a string

Example:
                    // reads and prints all the key values in all sections
                    string str;
                    INIFile ini("filename.ini");
                    StringArray saSections, saKeys;
                    ini.GetSectionNames(saSections);
                    for( int iSection = 0; iSection < saSections.GetSize(); iSection++ )
                    {
                        printf("%s\n", saSections[iSection]);
                        ini.GetKeyNames(saKeys, saSections[iSection]);
                        for( int iKey = 0; iKey < saKeys.GetSize(); iKey++ )
                        {
                            str = ini.ReadString(saSections[iSection], saKeys[iKey]);
                            printf("    %s = %s\n", saKeys[iKey], str);
                        }
                    }

Summary:
Sample data:
Header file: Settings.h
See also:


SetFileName

INIFile::SetFileName
Prototype:
PUBLIC  void SetFileName(LPCSTR lpcszSection)
Remarks: Sets the file name to the given string.
Parameters:
lpcszSection = new file name

Return values:

Example:

                    INIFile ini("Origin.ini");
                    int nNumLevels = ini.ReadInt("Config", "NumLevels", 0);
                    printf("NumLevels = %d", nNumLevels);

Summary:
Sample data:
Header file: Settings.h
See also:


WriteInt

INIFile::WriteInt
Prototype:
PUBLIC  void WriteInt(LPCSTR lpcszSection, LPCSTR lpcszKey, int nValue)
Remarks: Writes integer value into the specified section of an initialization file
Parameters:
lpcszSection - section name
lpcszKey - key name
nValue - value to be written

Return values:

Example:
            This example writes integer value into the Config section of MyOrigin.ini.
            For this example to run, a file with the name MyOrigin.ini should exist under C:\ folder.
            In addition, MyOrigin.ini should contain a section named Config and a key named ShowState.

            void test_INIFile_WriteInt()
            {
                    int iState = 3;
                    INIFile iniMyF("C:\\MyOrigin.ini");

                    iniMyF.WriteInt("Config", "ShowState", iState);
                    printf("Set initial Origin window state to %d\n", iState);

                    if (iState == iniMyF.ReadInt("Config", "ShowState", -1))
                        printf("Success!\ninitial Origin window state is %d\n",iState);
                    else
                        out_str("Error!");
            }

Summary:
Sample data:
Header file: Settings.h
See also:


WriteString

INIFile::WriteString
Prototype:
PUBLIC  void WriteString(LPCSTR lpcszSection, LPCSTR lpcszKey, LPCSTR lpcszValue)
Remarks: Writes a string value for a given keyname in a given section
Parameters:
lpcszSection = section name
lpcszKey = key name
lpcszValue = the string that needs to be written

Return values:

Example:
                    // writes "***" into all the key values in all sections
                    string str = "***";
                    INIFile ini("EBGIF2.ini");
                    StringArray saSections, saKeys;
                    ini.GetSectionNames(saSections);
                    for( int iSection = 0; iSection < saSections.GetSize(); iSection++ )
                    {
                        printf("%s\n", saSections[iSection]);
                        ini.GetKeyNames(saKeys, saSections[iSection]);
                        for( int iKey = 0; iKey < saKeys.GetSize(); iKey++ )
                        {
                            ini.WriteString(saSections[iSection], saKeys[iKey], str);
                            string str1 = ini.ReadString(saSections[iSection], saKeys[iKey], str);
                            printf("    %s = %s\n", saKeys[iKey], str1);
                        }
                    }

Summary:
Sample data:
Header file: Settings.h
See also:


Registry

Class: Registry

Description:

Hierarchy:

Registry

Sample:


DelKey

Registry::DelKey
Prototype:
PUBLIC  BOOL DelKey(LPCSTR lpSubKey)
Remarks: Deletes a subkey.
Parameters:
lpSubKey = Pointer to a null-terminated string specifying the name of the key to delete. This parameter cannot be NULL.

Return values:
FALSE if the key does not exist or it fails to remove it.

Example:
        Registry myRegAccess(HKEY_CLASSES_ROOT);
        if( myRegAccess.HasKey("a\\b\\c") )
            myRegAccess.DelKey("a\\b\\c");

Summary:
Sample data:
Header file: Settings.h
See also:


DelValue

Registry::DelValue
Prototype:
PUBLIC  BOOL DelValue(LPCSTR lpSubKey, LPCSTR lpValueName = NULL)
Remarks: Removes a named value from the specified registry key.
Parameters:
lpSubKey = Pointer to a null-terminated string specifying the name of the key to delete. This parameter cannot be NULL.
lpValueName = Pointer to a null-terminated string that names the value to remove.
If this parameter is NULL or points to an empty string, the value set by the SetValue function is removed.

Return values:

Example:
        Registry myRegAccess(HKEY_CLASSES_ROOT);
        if( myRegAccess.HasKey("a\\b\\c") )
            myRegAccess.DelValue("a\\b\\c", "MyLabel");

Summary:
Sample data:
Header file: Settings.h
See also:


GetValue

Registry::GetValue
Prototype:
PUBLIC  BOOL GetValue(LPCSTR lpSubKey, LPCSTR lpValueName, DWORD &dwValue)
Remarks: Retrieves the data for a specified value name associated with a subkey.
Parameters:
lpSubKey = Pointer to a null-terminated string containing the name of the subkey to open.
lpValueName = Pointer to a string containing the name of the value to query.
If this parameter is NULL or an empty string, "", the function retrieves
the type and data for the key's unnamed or default value, if any.

Return values:
TRUE if key value pair is in registry, FALSE if not

Example:
        DWORD dwCntrl;
        Registry myRegAccess(HKEY_CLASSES_ROOT);
        if( myRegAccess.HasKey("a\\b\\c") )
            myRegAccess.GetValue("a\\b\\c", "Control", dwCntrl);

Summary:
Sample data:
Header file: Settings.h
See also:
Registry::GetValue
Prototype:
PUBLIC  BOOL GetValue(LPCSTR lpSubKey, LPCSTR lpValueName, string &strValue)
Remarks: Retrieves the data for a specified value name associated with a subkey.
Parameters:
lpSubKey = Pointer to a null-terminated string containing the name of the subkey to open.
lpValueName = Pointer to a string containing the name of the value to query.
If this parameter is NULL or an empty string, "", the function retrieves
the type and data for the key's unnamed or default value, if any.

Return values:
TRUE if key value pair is in registry, FALSE if not

Example:
        string strLabel;
        Registry myRegAccess(HKEY_CLASSES_ROOT);
        if( myRegAccess.HasKey("a\\b\\c") )
            myRegAccess.GetValue("a\\b\\c", "Label", strLabel);

Summary:
Sample data:
Header file: Settings.h
See also:
Registry::GetValue
Prototype:
PUBLIC  BOOL GetValue(LPCSTR lpSubKey, LPCSTR lpValueName, LPBYTE lpData, LPDWORD lpcbData, LPDWORD lpType = NULL)
Remarks: Retrieves the data for a specified value name associated with a subkey.
Parameters:
lpSubKey = Pointer to a null-terminated string containing the name of the subkey to open.
lpValueName = Pointer to a string containing the name of the value to query.
If this parameter is NULL or an empty string, "", the function retrieves
the type and data for the key's unnamed or default value, if any.
lpData = Pointer to a buffer that receives the value’s data. This parameter can be NULL if the data is not required.
lpcbData = Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter.
When the function returns, this variable contains the size of the data copied to lpData.
lpType = Pointer to a variable that receives the type of data associated with the specified value,
The lpType parameter can be NULL if the type is not required.

Return values:

Example:
        char szValue[MY_BUFSIZE];
        DWORD dwBufLen = MY_BUFSIZE;
        string strSubKey = "Classes\\CLSID\\{B0F21977-8AAB-4632-A73D-528B909C5663}\\InProcServer32";

        Registry myRegAccess(HKEY_CLASSES_ROOT);
        if( myRegAccess.HasKey("a\\b\\c") )
            myRegAccess.GetValue("a\\b\\c", strSubKey, (LPBYTE)szValue, &dwBufLen);

Summary:
Sample data:
Header file: Settings.h
See also:


HasKey

Registry::HasKey
Prototype:
PUBLIC  BOOL HasKey(LPCSTR lpSubKey)
Remarks: Has the specified registry key or not.
Parameters:
lpSubKey = Pointer to a null-terminated string containing the name of the subkey to test.

Return values:
TRUE or FALSE.

Example:
        Registry myRegAccess(HKEY_CLASSES_ROOT);
        if( myRegAccess.HasKey("a\\b\\c") )
            return TRUE;

Summary:
Sample data:
Header file: Settings.h
See also:


Registry

Registry::Registry
Prototype:
PUBLIC  Registry(DWORD hParentKey)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: Settings.h
See also:


SetValue

Registry::SetValue
Prototype:
PUBLIC  void SetValue(LPCSTR lpSubKey, LPCSTR lpValueName, LPCSTR lpValue)
Remarks: Sets the data for the default or unnamed value of a specified registry key. The data must be a text string.
Parameters:
lpSubKey = Pointer to a null-terminated string containing the name of the subkey.
If the lpSubKey does not exist, it will be created there
lpValue = Pointer to a null-terminated string containing the data to set for the default value of the specified key.
lpValueName = Pointer to a string containing the name of the value,
If lpszValueName is supplied, the name value pair lpszValueName = lpszValue will be created for the key.
If lpszValueName is NULL, the default value of the lpSubKey will be set to lpszValue.

Return values:

Example:
        string strLabel = "Test";
        Registry myRegAccess(HKEY_CLASSES_ROOT);
        if( myRegAccess.HasKey("a\\b\\c") )
            myRegAccess.SetValue("a\\b\\c", "Label", strLabel);

Summary:
Sample data:
Header file: Settings.h
See also:
Registry::SetValue
Prototype:
PUBLIC  void SetValue(LPCSTR lpSubKey, LPCSTR lpValueName, DWORD dwValue)
Remarks: Sets the data for a specified value name associated with a subkey.
Parameters:
lpSubKey = Pointer to a null-terminated string containing the name of the subkey to open.
lpValueName = Pointer to a string containing the name of the value to set.
dwValue = a unsigned int value

Return values:

Example:
        Registry myRegAccess(HKEY_CLASSES_ROOT);
        if( myRegAccess.HasKey("a\\b\\c") )
            myRegAccess.GetValue("a\\b\\c", "Control", 12345);

Summary:
Sample data:
Header file: Settings.h
See also:
Registry::SetValue
Prototype:
PUBLIC  void SetValue(LPCSTR lpSubKey, LPCSTR lpValueName, LPBYTE lpData, DWORD dwType, DWORD dwcbData)
Remarks: Sets the data for the default or unnamed value of a specified registry key.
Parameters:
lpSubKey = Pointer to a null-terminated string containing the name of the subkey.
If the lpSubKey does not exist, it will be created there
lpValueName = Pointer to a string containing the name of the value,
If lpszValueName is NULL, the default value of the lpSubKey will be set to lpszValue.
lpData = Pointer to a buffer containing the data to be stored with the specified value name.
dwType = Specifies a code indicating the type of data pointed to by the lpData parameter.
dwcbData = Specifies the size of the information pointed to by the lpData parameter, in bytes.

Return values:

Example:

Summary:
Sample data:
Header file: Settings.h
See also:


stdioFile

Class: stdioFile

Description: The Origin C stdioFile class provides read/write access to text and binary files using buffered stream io. However, the stdioFile class does not support stream io to stdin, stdout, and stderr. See also the file class for unbuffered io to binary files. The stdioFile class is derived from the file class from which it inherits methods and properties.

Hierarchy:

file
 stdioFile

Sample:

        // Get the Origin folder path
        string strOriginPath, strFile;
        strOriginPath = GetAppPath() + "OriginC";
        strFile = strOriginPath + "\\test.txt";

        // Create a new standard I/O file.
        stdioFile ff(strFile, file::modeCreate | file::modeReadWrite);

        // Write strings
        string strLine1 = "line 1:";
        string strLine3 = "line 3:";
        ff.WriteString(strLine1);
        ff.WriteString("line 2:");
        ff.WriteString(strLine3);


ReadString

stdioFile::ReadString
Prototype:
PUBLIC  BOOL ReadString(string& str)
Remarks: Read a line from a file into a string. The end of line character is removed. strings in ascii file might be separated by "\r\n", as typical of files fom DOS/Windows or can be just "\n" or just "\r", as typical of unix and MAC files. Both forms are supported by this function. This function will also return TRUE on the last line even if it does not have a "\n" or "\r" termination. In other words, when reaching the end of a file, the function returns FALSE and the resulting string will always be empty. Please note a size limitation of 32762 characters for this function, so longer lines will be broken into multiple lines.
Parameters:
str=A reference to a string object that will contain the string when the function returns.

Return values:
TRUE for success, FALSE for end of file reached, or other error.

Example:
            //the following example will type out any ascii files from the User folder
            void show_file(string strfile = "origin.ini")
            {
                string strFilename = GetAppPath() + strfile;
                stdioFile ff;
                bool bRet = ff.Open(strFilename, file::modeRead);
                if(!bRet)
                {
                    out_str("file not found!");
                    return;
                }

                string strTemp;
                while(ff.ReadString(strTemp))
                    out_str(strTemp);

                ff.Close();
            }

Summary:
Sample data:
Header file: File.h
See also: WriteString


stdioFile

stdioFile::stdioFile
Prototype:
PUBLIC  stdioFile()
Remarks: The default constructor does not open a file but rather sets m_hFile to file::hFileNull.
Parameters:

Return values:

Example:
            stdioFile ff;

Summary:
Sample data:
Header file: File.h
See also:
stdioFile::stdioFile
Prototype:
PUBLIC  stdioFile(LPCTSTR lpszFileName, UINT nOpenFlags)
Remarks: Creates a stdioFile object and opens the file having the path specified by the parameter lpszFileName. This constructor combines the functions of the default constructor stdioFile() and the Open member function. An exception is thrown if an error occurs while opening the file. Depending on the severity of the error, the user should be alerted by an exception handler.
Parameters:
lpszFileName= Specifies a string that is the path to the desired file.
The path can be relative or absolute.
nOpenFlags= Sharing and access mode. Specifies the action to take when the file is opened.

Return values:

Example:
            //Create a new standard I/O file.
            //Get the origin folder path.
            string strOriginPath;
            strOriginPath = GetAppPath() + "OriginC";
            string strFile = strOriginPath + "\\test.txt";
            stdioFile ff(strFile, file::modeCreate | file::modeReadWrite);

Summary:
Sample data:
Header file: File.h
See also:


WriteString

stdioFile::WriteString
Prototype:
PUBLIC  int WriteString(LPCTSTR lpcsz)
Remarks: Write a line to a file. End of line character is appended.
Parameters:
lpcsz = Specifies a pointer to a buffer containing a null-terminated string.

Return values:
the length of lpcsz.

Example:
            //write string.
            string strLine1 = "line 1:";
            string strLine3 = "line 3:";
            stdioFile ff("c:\\test.txt",file::modeCreate | file::modeReadWrite);
            ff.WriteString(strLine1);
            ff.WriteString("line 2:");
            ff.WriteString(strLine3);

Summary:
Sample data:
Header file: File.h
See also: ReadString


DeviceContext

Class: DeviceContext

Description: The DeviceContext class defines a class of device-context objects.

Hierarchy:

DeviceContext

Sample:

        Page pb;
        pb = Project.Pages(); // Get the project's active page
        if( pb.IsValid() )
        {
            Window	myWindow = pb.GetWindow();
            DeviceContext myDC = myWindow.GetDC();
            int nPixels = myDC.GetDeviceCaps(LOGPIXELSX);
        }


~DeviceContext

DeviceContext::~DeviceContext
Prototype:
PUBLIC  ~DeviceContext()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


Attach

DeviceContext::Attach
Prototype:
PUBLIC  BOOL Attach(HDC hDC )
Remarks: Use hDC set internal hDC value.
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


Detach

DeviceContext::Detach
Prototype:
PUBLIC  HDC Detach( )
Remarks: Return internal hDC value of class and set internal hDC to NULL
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


DeviceContext

DeviceContext::DeviceContext
Prototype:
PUBLIC  DeviceContext()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:
DeviceContext::DeviceContext
Prototype:
PUBLIC  DeviceContext(DeviceContext &dc)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


GetDeviceCaps

DeviceContext::GetDeviceCaps
Prototype:
PUBLIC  int GetDeviceCaps(int nIndex) const
Remarks: This method retrieves a wide range of device-specific information about the display device.
Parameters:
nIndex = the type of information to return.

Return values:
The value of the requested capability if the function is successful.

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


GetTextExtent

DeviceContext::GetTextExtent
Prototype:
PUBLIC  SIZE GetTextExtent(LPCTSTR lpszString, int nCount)
Remarks: Computes the width and height of a line of text on the attribute device context using the current font to determine the dimensions.
Parameters:
lpszString = Points to a string of characters.
nCount = Specifies the number of characters in the string.

Return values:
The dimensions of the string (in logical units) in a SIZE structure.

Example:
        void test()
        {
            Window wnd = MyDlg.GetWindow();
            DeviceContext dc = wnd.GetDC();
            SIZE sz[10];
            sz[2] = dc.GetTextExtent("ABC",3);
            out_int("x_width = ", sz[2].cx);
            out_int("y_width = ", sz[2].cy);
        }

Summary:
Sample data:
Header file: mswin.h
See also:
DeviceContext::GetTextExtent
Prototype:
PUBLIC  SIZE GetTextExtent(const string &str)
Remarks: Computes the width and height of a line of text on the attribute device context using the current font to determine the dimensions.
Parameters:
str = A string object.

Return values:
The dimensions of the string (in logical units) in a SIZE structure.

Example:
        void test()
        {
            Window wnd = MyDlg.GetWindow();
            DeviceContext dc = wnd.GetDC();
            SIZE sz[10];
            sz[2] = dc.GetTextExtent("ABC",3);
            out_int("x_width = ", sz[2].cx);
            out_int("y_width = ", sz[2].cy);
        }

Summary:
Sample data:
Header file: mswin.h
See also:


progressBox

Class: progressBox

Description: A progress dialog box is a small dialog box used to indicate that a software is busy processing data. The dialog box contains a progress bar indicating the fraction of processing that has been completed. The progress dialog box is generally used in conjunction with some sort of iterative loop. The progressBox class provides methods and properties needed to open and control progress dialog boxes.

Hierarchy:

progressBox

Sample:

         int imax = 10;
        progressBox aa("This is an example:");
        aa.SetRange(0,imax);
        for(int ii = 0; ii < imax; ii++)
        {
            if(aa.Set(ii))
                printf("Hello, at %d\n", ii);
            else
            {
                out_str("User abort!");
                break;
            }
            LT_execute("sec -p 0.5"); // wasting some time
        }


progressBox

progressBox::progressBox
Prototype:
PUBLIC  progressBox(LPCTSTR lpstrTitle, int nStyle = 0)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: utilities.h
See also:


Set

progressBox::Set
Prototype:
PUBLIC  BOOL Set(int nCurrent)
Remarks: Set the current position of the progress bar. This value is typically within range set by the SetRange method
Parameters:
nCurrent = the current progress bar position

Return values:
TRUE normally, FALSE if user has clicked the Cancel or End button prior to this method was called

Example:
            void run_progressBox()
            {
                    int iMax = 10, iMin = 0;
                    progressBox prgbBox("This is a ProgressBox example:");
                    prgbBox.SetRange(iMin, iMax);
                    for (int ii=iMin; ii<=iMax; ii++)
                    {
                        if(prgbBox.Set(ii))
                            printf("Hi, it is now at %d.\n", ii);
                        else
                        {
                            out_str("User abort!");
                            break;
                        }
                        LT_execute("sec -p 0.5");
                    }
            }

Summary:
Sample data:
Header file: utilities.h
See also:


SetRange

progressBox::SetRange
Prototype:
PUBLIC  BOOL SetRange(int nMin, int nMax)
Remarks: Set the integer range for the progressbox to loop through. If you do not call this method, the default range of 0 to 100 will be used.
Parameters:
nMin = beginning value
nMax = end value

Return values:
TRUE if the range is reasonable, FALSE otherwise.

Example:

Summary:
Sample data:
Header file: utilities.h
See also: Set


waitCursor

Class: waitCursor

Description: A wait cursor is a visual cue (such as an hour glass) used to indicate that a software is busy processing data. The waitCursor class provides methods and properties needed to open and control wait cursors.

Hierarchy:

waitCursor

Sample:

        int imax = 100000;
        waitCursor junk; // just need to declare this, no need to reference to it
        double	aa = 0.5;
        DWORD	dw1 = GetTickCount();
        for(int ii = 0; ii < imax; ii++)
            aa = sin(aa) + ii * aa;
        printf("It took %d ms for %d loop\n",GetTickCount()-dw1,imax);


CheckEsc

waitCursor::CheckEsc
Prototype:
PUBLIC  BOOL CheckEsc()
Remarks: The CheckEsc method allows a program to capture user hitting ESC to abort the current operation
Parameters:

Return values:
TRUE if user has hit the ESC key, FALSE otherwise

Example:
        Worksheet wks = Project.ActiveLayer();
        if(wks==NULL)
            return;

        waitCursor	cur;
        string	str;
        int		nCol = 0;
        for(int ii = 0; ii < 10000 && !cur.CheckEsc();ii++)
        {
            wks.AddCol();
            str.Format("Adding col %d", nCol++);
            SetDataDisplayText(str);
        }
        if(ii < 10000)
            printf("User abort adding columns, only %d columns are added\n", nCol);

Summary:
Sample data:
Header file: utilities.h
See also:


waitCursor

waitCursor::waitCursor
Prototype:
PUBLIC  waitCursor()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: utilities.h
See also:
waitCursor::waitCursor
Prototype:
PUBLIC  waitCursor(int nCursorType)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: utilities.h
See also:


Window

Class: Window

Description: The Window class is the base class for all window classes. This class is similar to the MFC CWnd class

Hierarchy:

Window

Sample:

        // Get "Data1" worksheet window...if not valid...
        WorksheetPage  wksPg("Data1");
        Window winWks = wksPg.GetWindow();
        if(winWks)
        {
            printf("Worksheet window is %s\n", winWks.Text);
        }


Attach

Window::Attach
Prototype:
PUBLIC  BOOL Attach(Window& ctrl)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


CheckRadioButton

Window::CheckRadioButton
Prototype:
PUBLIC  void CheckRadioButton( int nIDFirstButton, int nIDLastButton, int nIDCheckButton )
Remarks: This method selects, adds a check mark to a specified radio button in a group and clears, removes a check mark from all other radio buttons in the group.
Parameters:
nIDFirstButton: Specifies the integer identifier of the first radio button in the group.
nIDLastButton: Specifies the integer identifier of the last radio button in the group.
nIDCheckButton: Specifies the integer identifier of the radio button to be checked.

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


ClientToScreen

Window::ClientToScreen
Prototype:
PUBLIC  void ClientToScreen(RECT * lpRect)
Remarks: Converts the client coordinates of a given point or rectangle on the display to screen coordinates.
Parameters:

Return values:

Example:
            //Please make sure you have a "Data1" worksheet window exist when you run the example
            void run_ClientToScreen()
            {
                WorksheetPage testWks("Data1");
                Window testWin = testWks.GetWindow();
                testWin.ShowWindow(SW_NORMAL);

                RECT rect;
                testWin.GetClientRect(&rect);
                testWin.ClientToScreen(&rect);
                printf("upper-left position on screen, x:%d, y:%d\n", rect.left, rect.top);
                printf("lower-right position on screen: x:%d, y:%d\n", rect.right, rect.bottom);
            }

Summary:
Sample data:
Header file: mswin.h
See also:


GetActiveXControl

Window::GetActiveXControl
Prototype:
PUBLIC  _VARIANT GetActiveXControl()
Remarks: This function provides COM support for ActiveX controls that are placed into Origin windows or Dialog Builder winodws. This function is available only for OriginPro versions, or with a special COM enabled license
Parameters:

Return values:

Example:
        static void UpdateMatrixGraph()
        {
            Matrix myMat("Matrix1");

            if(myMat)
            {
                Object CWKnob1 = MyDlg.GetItem(IDC_CWKNOB1).GetActiveXControl();
                double dNoiseLevel = CWKnob1.Value;

                Object CWSlide1 = MyDlg.GetItem(IDC_CWSLIDE1).GetActiveXControl();
                double vv = CWSlide1.Value;
                double dPeakHalfWidth = 5. / (vv+1.);
                fill_mat_with_values(myMat, 0.2, 0.4, 15.0, dPeakHalfWidth, dNoiseLevel);

                Object CW3DGraph1 = MyDlg.GetItem(IDC_CWGRAPH3D1).GetActiveXControl();
                _VARIANT	var = myMat;
                CW3DGraph1.Plot3DSimpleSurface(var);
            }
        }

Summary:
Sample data:
Header file: mswin.h
See also:


GetCheckedRadioButton

Window::GetCheckedRadioButton
Prototype:
PUBLIC  int GetCheckedRadioButton( int nIDFirstButton, int nIDLastButton )
Remarks: This method retrieves the identifier of the currently checked radio button in the specified group.
Parameters:
nIDFirstButton: Specifies the integer identifier of the first radio button in the group.
nIDLastButton: Specifies the integer identifier of the last radio button in the group.

Return values:
ID of the checked radio button, or zero if none is selected.

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


GetClientRect

Window::GetClientRect
Prototype:
PUBLIC  void GetClientRect(RECT * lpRect)
Remarks: Copies the client coordinates of the CWnd client area into the structure pointed to by lpRect. The client coordinates specify the upper-left and lower-right corners of the client area. Since client coordinates are relative to the upper-left corners of the CWnd client area, the coordinates of the upper-left corner are (0,0).
Parameters:
Points to a RECT structure that will receive the coordinates of the upper-left and lower-right corners of the client area.

Return values:

Example:
            //Please make sure you have a "Data1" worksheet window exist when you run the example
            void test_GetClientRect()
            {
                WorksheetPage testWks("Data1");
                Window testWin = testWks.GetWindow();
                testWin.ShowWindow(SW_NORMAL);

                RECT rect;
                testWin.GetClientRect(&rect);
                printf("upper-left position to client area, x:%d, y:%d\n", rect.left, rect.top);
                printf("lower-right position to client area: x:%d, y:%d\n", rect.right, rect.bottom);
            }

Summary:
Sample data:
Header file: mswin.h
See also:


GetDC

Window::GetDC
Prototype:
PUBLIC  DeviceContext GetDC( )
Remarks: Identifies the device context for the window client area if successful; otherwise, the return value is NULL.
Parameters:

Return values:

Example:
        int get_pixels_per_inch(bool bX = true)
        {
            DeviceContext dc = MyDlg.GetWindow().GetDC();
            return dc.GetDeviceCaps(bX? LOGPIXELSX : LOGPIXELSY);
        }

Summary:
Sample data:
Header file: mswin.h
See also:


GetDlgItem

Window::GetDlgItem
Prototype:
PUBLIC  Window GetDlgItem(int nChildWinID)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


GetParent

Window::GetParent
Prototype:
PUBLIC  Window GetParent()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


GetSafeHwnd

Window::GetSafeHwnd
Prototype:
PUBLIC  HWND GetSafeHwnd()
Remarks: This function returns the window handle
Parameters:

Return values:
Returns the window handle for a window.
Returns NULL if the Window class is not attached to a window.

Example:
            // make active window iconized
            Window winDlg = myDlg.GetWindow();
            MessageBox(winDlg.GetSafeHwnd(), "Hello", "Test", MB_OK);

Summary:
Sample data:
Header file: mswin.h
See also:


GetScrollPos

Window::GetScrollPos
Prototype:
PUBLIC  int GetScrollPos( int nBar ) const
Remarks: Retrieves the current position of the scroll box of a scroll bar. The current position is a relative value that depends on the current scrolling range. For example, if the scrolling range is 50 to 100 and the scroll box is in the middle of the bar, the current position is 75.
Parameters:
nBar = the scroll bar to examine. The parameter can take one of the following values:
SB_HORZ   Retrieves the position of the horizontal scroll bar.
SB_VERT   Retrieves the position of the vertical scroll bar.

Return values:
Specifies the current position of the scroll box in the scroll bar if successful; otherwise 0.

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


GetScrollRange

Window::GetScrollRange
Prototype:
PUBLIC  void GetScrollRange( int nBar, int& nMinPos, int& nMaxPos ) const
Remarks: Copies the current minimum and maximum scroll-bar positions for the given scroll bar to the locations specified by lpMinPos and lpMaxPos. If window does not have a scroll bar, then the GetScrollRange member function copies 0 to lpMinPos and lpMaxPos. The default range for a standard scroll bar is 0 to 100. The default range for a scroll-bar control is empty (both values are 0).
Parameters:
nBar = the scroll bar to examine. The parameter can take one of the following values:
SB_HORZ   Retrieves the position of the horizontal scroll bar.
SB_VERT   Retrieves the position of the vertical scroll bar.
nMinPos = integer variable that is to receive the minimum position.
nMaxPos =  integer variable that is to receive the maximum position.

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


GetWindowRect

Window::GetWindowRect
Prototype:
PUBLIC  void GetWindowRect(RECT * lpRect)
Remarks: Copies the dimensions of the bounding rectangle of the CWnd object to the structure pointed to by lpRect. The dimensions are given in screen coordinates relative to the upper-left corner of the display screen. The dimensions of the caption, border, and scroll bars, if present, are included.
Parameters:
lpRect: Points to a RECT structure that will receive the screen coordinates of the upper-left and lower-right corners.

Return values:

Example:
            //Please make sure you have a "Data1" worksheet window exist when you run the example
            void test_GetWindowRect()
            {
                WorksheetPage testWks("Data1");
                Window testWin = testWks.GetWindow();
                testWin.ShowWindow(SW_NORMAL);

                RECT rect;
                testWin.GetWindowRect(&rect);
                printf("upper-left position, x:%d, y:%d\n", rect.left, rect.top);
                printf("lower-right position: x:%d, y:%d\n", rect.right, rect.bottom);
            }

Summary:
Sample data:
Header file: mswin.h
See also:


IsIconic

Window::IsIconic
Prototype:
PUBLIC  BOOL IsIconic()
Remarks: This function checks if window is minimized.
Parameters:

Return values:
Return TRUE if the window is minimized, otherwise, FALSE..

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


IsZoomed

Window::IsZoomed
Prototype:
PUBLIC  BOOL IsZoomed()
Remarks: This function checks if window is maximized.
Parameters:

Return values:
Return TRUE if the window is maximized, otherwise, FALSE..

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


MoveWindow

Window::MoveWindow
Prototype:
PUBLIC  void MoveWindow(const RECT * lpRect, BOOL bRepaint = TRUE)
Remarks: Changes the position and dimensions.
Parameters:
lpRect:   Points to a RECT structure that specifies the new size and position
bRepaint:   Specifies whether Window is to be repainted.

Return values:

Example:
            //Please make sure you have a "Data1" worksheet window exist when you run the example
            void test_MoveWindow()
            {
                WorksheetPage testWks("Data1");
                Window testWin = testWks.GetWindow();
                testWin.ShowWindow(SW_NORMAL);

                RECT RecNew = {144, 200, 500, 600};;
                testWin.MoveWindow(&RecNew);
            }

Summary:
Sample data:
Header file: mswin.h
See also:


PostMessage

Window::PostMessage
Prototype:
PUBLIC  BOOL PostMessage(uint msg, DWORD wParam = 0, DWORD lParam = 0)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


ScreenToClient

Window::ScreenToClient
Prototype:
PUBLIC  void ScreenToClient(RECT * lpRect)
Remarks:
Parameters:

Return values:

Example:
            //Please make sure you have a "Data1" worksheet window exist when you run the example
            void run_ScreenToClient()
            {
                WorksheetPage testWks("Data1");
                Window testWin = testWks.GetWindow();
                testWin.ShowWindow(SW_NORMAL);

                RECT rect;
                rect.left=100;
                rect.right=200;
                rect.top=200;
                rect.bottom=300;
                testWin.ScreenToClient(&rect);
                printf("upper-left position to client area, x:%d, y:%d\n", rect.left, rect.top);
                printf("lower-right position to client area: x:%d, y:%d\n", rect.right, rect.bottom);
            }

Summary:
Sample data:
Header file: mswin.h
See also:


SendMessage

Window::SendMessage
Prototype:
PUBLIC  UINT SendMessage(uint msg, DWORD wParam = 0, DWORD lParam = 0)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


SetFont

Window::SetFont
Prototype:
PUBLIC  void SetFont(int nFontNumber)
Remarks: Set stock logic font for the control
Parameters:
nFontNumber
the Stock Logic font number, can be one of following,
OEM_FIXED_FONT,
ANSI_FIXED_FONT,
ANSI_VAR_FONT,
SYSTEM_FONT,
DEVICE_DEFAULT_FONT,
SYSTEM_FIXED_FONT.

Return values:
None.

Example:
        RichEdit richEdit = EditBoxes.GetItem(IDC_RICHEDIT1);

        richEdit.SetFont(OEM_FIXED_FONT);

Summary:
Sample data:
Header file: mswin.h
See also:


SetScrollPos

Window::SetScrollPos
Prototype:
PUBLIC  int SetScrollPos( int nBar, int nPos, BOOL bRedraw = TRUE )
Remarks: Sets the current position of a scroll box and, if requested, redraws the scroll bar to reflect the new position of the scroll box. Setting bRedraw to FALSE is useful whenever the scroll bar will be redrawn by a subsequent call to another function.
Parameters:
nBar = the scroll bar to be set. This parameter can be either of the following:
SB_HORZ   Sets the position of the scroll box in the horizontal scroll bar of the window.
SB_VERT   Sets the position of the scroll box in the vertical scroll bar of the window.
nPos = the new position of the scroll box. It must be within the scrolling range.
bRedraw = whether the scroll bar should be repainted to reflect the new scroll-box position.
If this parameter is TRUE, the scroll bar is repainted; if FALSE, the scroll bar is not repainted.

Return values:
The previous position of the scroll box.

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


SetScrollRange

Window::SetScrollRange
Prototype:
PUBLIC  void SetScrollRange( int nBar, int nMinPos, int nMaxPos, BOOL bRedraw = TRUE )
Remarks: Sets the current position of a scroll box and, if requested, redraws the scroll bar to reflect the new position of the scroll box. Setting bRedraw to FALSE is useful whenever the scroll bar will be redrawn by a subsequent call to another function.
Parameters:
nBar = the scroll bar to be set. This parameter can be either of the following:
SB_HORZ   Sets the position of the scroll box in the horizontal scroll bar of the window.
SB_VERT   Sets the position of the scroll box in the vertical scroll bar of the window.
nPos = the new position of the scroll box. It must be within the scrolling range.
bRedraw= whether the scroll bar should be repainted to reflect the new scroll-box position. If this parameter is TRUE, the scroll bar is repainted; if FALSE, the scroll bar is not repainted.

Return values:
The previous position of the scroll box.

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


ShowWindow

Window::ShowWindow
Prototype:
PUBLIC  BOOL ShowWindow(int nCmdShow)
Remarks: This function sets the specified window's show state.
Parameters:
nCmdShow = SW_HIDE, SW_NORMAL, SW_MINIMIZE, SW_MAXIMIZE etc.

Return values:
If the window was previously visible, the return value is TRUE.
If the window was previously hidden, the return value is FALSE.

Example:
            // make "Data1" worksheet window iconized
            WorksheetPage  wksPg("Data1");
            Window winWks = wksPg.GetWindow();
            if(winWks)
                winWks.ShowWindow(SW_MINIMIZE);

Summary:
Sample data:
Header file: mswin.h
See also:


Window

Window::Window
Prototype:
PUBLIC  Window()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:
Window::Window
Prototype:
PUBLIC  Window(HWND hWnd)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:
Window::Window
Prototype:
PUBLIC  Window(Window& ctrl)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: mswin.h
See also:


Origin Programming

Welcome to the Origin Programming Help System


format

string::Format
Prototype:
PUBLIC  void Format( LPCSTR lpcszFormat, ... )
Remarks: This member function formats and stores a series of characters and values in the string. Each optional argument (if any) is converted and output according to the corresponding format specification in lpcszFormat. Please note that it is your responsibility to match the data type with the correct formatting specification.
Parameters:
lpcszFormat = A format-control string.

Return values:
none.

Example:
            char sz[10] = "abcdefg";
            int nn = 10;
            double dd = 3.1416;
            string str;
            str.Format("Results = %s, %d, %5.4f", sz, nn, dd);
            ASSERT(0 == str.Compare("Results = abcdefg, 10, 3.1416"));

            // the following usage will generate runtime error due to
            // incorrect data being used
            string str;
            str.Format("x1=%f, x2=%f", 5, 3.4); // 5 is not a double, will generate runtime error
            str.Format("x1=%f, x2=%f", 5.0, 3.4);// this will work correctly

Summary:
Sample data:
Header file: string.h
See also: printf


EditorManager

Class: EditorManager

Description:

Hierarchy:

EditorManager

Sample:


originc\doc_gen.cfm-query=f;fname=


originc\doc_gen.cfm-query=f;fname=;cname=62


AfterEdit

EditorManager::AfterEdit
Prototype:
PUBLIC  bool AfterEdit(DWORD dwData, int nComboIndex = AFTER_EDIT_USE_CUSTOM_EDITOR, LPCSTR lpcszNewText = NULL)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


CreateEditor

EditorManager::CreateEditor
Prototype:
PUBLIC  DWORD CreateEditor(DWORD dwData, const RECT * lpcRect, HWND hwndOwner, UINT nControlID=100, LPCTSTR lpcszFontName=NULL, int nFontSize=0)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


Delete

EditorManager::Delete
Prototype:
PUBLIC  bool Delete(DWORD dwData)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


DestroyEditor

EditorManager::DestroyEditor
Prototype:
PUBLIC  bool DestroyEditor(DWORD dwData)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


DrawCell

EditorManager::DrawCell
Prototype:
PUBLIC  BOOL DrawCell(DWORD dwData, DWORD hDC, const RECT * lpcRect, BOOL bSelected)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


EditorManager

EditorManager::EditorManager
Prototype:
PUBLIC  EditorManager()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


fitNLSF


GetCellHeightFactor

EditorManager::GetCellHeightFactor
Prototype:
PUBLIC  double GetCellHeightFactor(DWORD dwData)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


GetEditInfo

EditorManager::GetEditInfo
Prototype:
PUBLIC  int GetEditInfo(DWORD dwData, string& strCombo, string& strEditMask)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


GetStorage


GetStrData

EditorManager::GetStrData
Prototype:
PUBLIC  string GetStrData(DWORD dwData)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


GetText

EditorManager::GetText
Prototype:
PUBLIC  string GetText(DWORD dwData, BOOL bTranslate = TRUE)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


initNLSF


IsWriteProtected(int nBegin = 0


MaximizeCommandWindow


New

EditorManager::New
Prototype:
PUBLIC  DWORD New(int nType, int nRow, DWORD nID=0, LPCSTR lpcszAuxString=NULL, DWORD dwParam1=0, DWORD dwParam2=0)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


None


Set


SetSize


SetStrData

EditorManager::SetStrData
Prototype:
PUBLIC  bool SetStrData(DWORD dwData, LPCSTR lpcsz)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


SetText

EditorManager::SetText
Prototype:
PUBLIC  bool SetText(DWORD dwData, LPCSTR lpcsz, int nCvtText = OXVT_UINT)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


StartEdit

EditorManager::StartEdit
Prototype:
PUBLIC  bool StartEdit(DWORD dwData, int nRow)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


SystemTimeToFileTime


ValidateEdit

EditorManager::ValidateEdit
Prototype:
PUBLIC  bool ValidateEdit(DWORD dwData, LPCSTR lpcsz)
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also:


~EditorManager

EditorManager::~EditorManager
Prototype:
PUBLIC  ~EditorManager()
Remarks:
Parameters:

Return values:

Example:

Summary:
Sample data:
Header file: GetNbox.h
See also: