2.1.7.17 RangeName

Description

Add new named range, or update existing named range

Syntax

int RangeName( LPCSTR lpcszName, LPCSTR lpcszRange, int nScope, LPCSTR lpcszComments = NULL )

Parameters

lpcszName

[input] range name, must conform to variable name rule

lpcszRange

[input] a range string to add, NULL to test existance (1=existed, 0=not)

nScope

[input] 0=sheet, 1=book, 2=project

lpcszComments

[input] comment

Return

if succeed return 0, otherwise return negative error code.

Examples

EX1

//name the selected range in active worksheet
void RangeName_ex(string strName)
{
	Worksheet wks;	
	DataRange dr;
	dr.Create();
	
	//get selected data range
	bool bFromFindDlg = false, bCheckLabelRows = true;
	if( GSS_WKS_VALID_SEL > get_sheet_sel(wks, dr, bFromFindDlg, bCheckLabelRows) )
	{
		out_str("no worksheet selection");
		return;
	}
	
	//check whether data range has been named or not
	string strExistName;
	int nOldScope = dr.HasNamedRange(strExistName);
	if(nOldScope >= 0 && strName.CompareNoCase(strExistName) == 0)
	{
		out_str("name no change");
		return;	
	}
	
	string strRange;
	dr.GetRangeString(strRange, NTYPE_SHORT_NAME_ONLY|NTYPE_ALWAYS_SHOW_COLUMN);
	
	int nScope = 1;//book
	nScope |= NRANGE_SUPPORT_LABEL_AREA;
	
	//if data range has been named, update
	if( !strExistName.IsEmpty() ) 
	{
		strRange = strExistName;
		nScope |= NRSCOPE_TO_BACKUP(nOldScope);
		nScope |= NRANGE_UPDATE_EXISTING;
   	}
	
	int nRet = RangeName(strName, strRange, nScope, "it is a test");
	if(nRet != 0)
		out_int("err = ", nRet);
	else
		out_str("done");
}

Remark

See Also

Header to Include

origin.h

Reference