Contents
@Functions »Page @Function Equivalents LciAt...
@Function Registration »Page @Function Registration LciAf...
Cell »Page Cell Functions LciCl...
Events »Page 1-2-3 Events LciEv...
Graphical »Page Toolclass LciTc...
Tool Instance LciTi...
GUI Menus LciMn...
Preset/Validate LciPs..., LciVl...
Tool Messages TOOLMSG_
Lmbcs »Page LMBCS Functions LciLmb...
Load »Page Load Functions LciLd...
Macro Registration »Page Macro Registration LciMc...
Math »Page Math Functions LciMt...
Range »Page Range Functions LciRg...
Return Codes »Page Lci Return Codes LCS_...
Sheet »Page Sheet Functions LciSh...
Utilities »Page Miscellaneous Functions LciUt...
Workfile »Page Workfile Functions LciWf...
Workspace »Page Workspace Functions LciWs...
These functions provide support for the operations performed by almost all of the 1-2-3 @functions. Most 1-2-3 @functions correspond directly to routines described here. In some cases, however, the operation that a 1-2-3 @function performs is covered by a C language feature or C Tools data type.
Function Meaning
LciAtAvg »Page Calculates the average of the values in a range of numbers or numeric formulas.
LciAtChar »Page Retrieves the single-character string that corresponds to a specified LMBCS code or the LMBCS code that corresponds to the first character in a string.
LciAtCount »Page Calculates the number of nonblank cells in a range.
LciAtCTerm »Page Calculates the number of compounding periods it takes for an investment of present value to grow to a future value.
LciAtD360 »Page Calculates the number of days between two date numbers, based on a 360-day year.
LciAtDate »Page Calculates the date number for the specified year, month, and day.
LciAtDateValue »Page Calculates the date number for the specified date.
LciAtDAvg »Page Averages the values in a field of a database table that meet the specified criteria.
LciAtDay »Page Obtains the day of the month (an integer from 1 to 31) from the specified date number.
LciAtDays360 »Page Calculates the number of days between two date numbers, based on a 360-day year, according to the U.S. securities industry.
LciAtDCount »Page Counts the nonblank cells in a field of a database table that meet the specified criteria.
LciAtDDB »Page Calculates the depreciation allowance of an asset for a specified period of time, using the double-declining balance method.
LciAtDGet »Page Retrieves a value or a label in a field of a database table that meets the specified criteria.
LciAtDMax »Page Finds the largest value in a field of a database table that meets the specified criteria.
LciAtDMin »Page Finds the smallest value in a field of a database table that meets the specified criteria.
LciAtDStD »Page Calculates the population standard deviation of the values in a field of a database table that meet the specified criteria.
LciAtDStDS »Page Calculates the sample standard deviation of the values in a field of a database table that meet the specified criteria.
LciAtDSum »Page Calculates the sum of the values in a field of a database table that meet the specified criteria.
LciAtDVar »Page Calculates the population variance of the values in a field of a database table that meet the specified criteria.
LciAtDVarS »Page Calculates the sample variance of the values in a field of a database table that meet the specified criteria.
LciAtExact »Page Tests whether two strings match exactly.
LciAtFind »Page Calculates the position in a target string at which it finds the first occurrence of a search string.
LciAtFV »Page Calculates the future value of an investment, based on a series of equal payments, earning a periodic interest rate, over a specified number of payment periods.
LciAtHLookup »Page Obtains the contents of the cell in a specified row of a horizontal look-up table.
LciAtHour »Page Calculates the hour, a value between 0 (midnight) and 23 (11:00 p.m.), from the specified time number.
LciAtInfo »Page Retrieves system information for the current 1-2-3 session.
LciAtIRR »Page Calculates the expected internal rate of return (profit) for a series of cash flow values generated by an investment.
LciAtLmbcsGroup »Page Returns the current Lmbcs codepage group.
LciAtIsERR »Page Tests the input value for the value ERR.
LciAtIsNA »Page Tests the input value for the value NA.
LciAtIsNumber »Page Tests the specified cell for a numeric value.
LciAtIsRange »Page Determines if the specified range name is defined.
LciAtIsString »Page Tests the specified cell for a label.
LciAtLeft »Page Retrieves the first n characters in a string.
LciAtLower »Page Converts all the letters in the specified string to lowercase.
LciAtMax »Page Obtains the largest value in a range of numbers or numeric formulas.
LciAtMid »Page Retrieves n characters in a string, beginning with the character specified.
LciAtMin »Page Obtains the smallest value in a range of numbers or numeric formulas.
LciAtMinute »Page Obtains the minute from the specified time number.
LciAtMonth »Page Obtains the month in the specified date number.
LciAtNewline »Page Creates a line feed and a carriage return character to move the output down and to the beginning of a line.
LciAtNow »Page Retrieves the value that corresponds to the current date and time.
LciAtNPV »Page Calculates the net present value of a series of future cash flow values discounted at a fixed, periodic interest rate.
LciAtPmt »Page Calculates the amount of the periodic payment needed to pay off a loan, given a specified periodic interest rate and number of payment periods.
LciAtProper »Page Converts the letters in the specified string to proper capitalization. It converts the first letter of each word to uppercase, leaving the remaining letters lowercase.
LciAtPV »Page Calculates the present value of an investment, based on a series of equal payments discounted at a periodic interest rate over a specified number of payment periods.
LciAtRate »Page Returns the periodic interest rate necessary for an investment to grow to a future value over the number of compounding periods specified.
LciAtRepeat »Page Duplicates the specified string.
LciAtReplace »Page Replaces a specified number of characters in a string, beginning at a designated position, with a new string.
LciAtRight »Page Retrieves the last specified number of characters starting at the end of a string.
LciAtRound »Page Rounds the specified value to the specified number of places.
LciAtSecond »Page Obtains the seconds, a value between 0 and 59, from the specified time number.
LciAtSLn »Page Calculates the straight-line depreciation allowance of an asset for one period.
LciAtStD »Page Calculates the population standard deviation in a range of values.
LciAtStDS »Page Calculates the sample standard deviation in a range of values.
LciAtString »Page Converts a number into a string with a specified number of decimal places.
LciAtSum »Page Adds the values in a range of numbers or numeric formulas.
LciAtSYD »Page Calculates the sum-of-the-years-digits depreciation allowance of an asset for a specified period.
LciAtTerm »Page Calculates the number of payment periods in the term of an investment necessary to accumulate a future value, assuming equal payments, when the investment earns a periodic interest rate.
LciAtTime »Page Calculates the time number for the specifed hour, minutes, and seconds.
LciAtTimeValue »Page Calculates the time number for the specified time.
LciAtToday »Page Retrieves the date number that corresponds to the current date.
LciAtUpper »Page Converts all the letters in the specified string to uppercase.
LciAtValue »Page Converts a number entered as a string to its corresponding numeric value.
LciAtVar »Page Calculates the population variance in a range of values.
LciAtVarS »Page Calculates the sample variance in a range of values.
LciAtVDB »Page Calculates the depreciation allowance of an asset for a specified period of time, using the declining-balance method.
LciAtVLookup »Page Obtains the contents of the cell in a specified column of a range.
LciAtYear »Page Obtains the year, a number from 0 (1900) to 199 (2099), inclusive, from the specified date number.
Definition
Calculates the average of the values in a range of numbers or numeric formulas.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtAvg
(LCH_CONTEXT Context,
LCH_RANGE Range,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Range A range object.
lpResult Pointer to an lfloat10 in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
LCS_OUT_OF_BOUNDS »Page
LCS_STR_TOO_LONG »Page
LCS_CONVERSION_ERROR »Page
Example
#include"lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lfloat10 Result;
. . .
Status = LciRgConstructCurr(Construct,&Range);
/* Status check here */
Status = LciAtAvg(Context,Range,&Result);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the single-character string that corresponds to a specified LMBCS code or the LMBCS code that corresponds to the first character in a string.
LciAtChar corresponds to the @CHAR and @CODE functions in 1-2-3, and is useful for entering foreign language characters and mathematical symbols into a worksheet.
If your add-in assigns the result string to a cell and your monitor cannot display the character, 1-2-3 displays a character that resembles the desired character as much as possible. Whether a character prints or not depends on the capabilities of your printer.
Refer to Appendix C in the 1-2-3 Release 4 for Windows ADK Developer's Guide or Appendix A in the 1-2-3 Release 4 for Windows User's Guide for LMBCS code descriptions.
Format
* Integer to string *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtCharLongToStr
(LCH_CONTEXT Context,
lslong CharCode,
lslong BufLen,
lptr(lmbcs) lpResultStr)
* String to integer *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtCharStrToLong
(LCH_CONTEXT Context,
lptr(lmbcs) lpCharStr,
lptr(lslong) lpCharCode)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
CharCode LMBCS code for the desired character.
BufLen The number of bytes available in the buffer pointed to by lpResultStr, including room for a trailing null byte.
lpResultStr Pointer to a lmbcs string in which to return the result.
lpCharStr Pointer to a lmbcs string containing the character(s) for the desired LMBCS code.
lpCharCode Pointer to an lslong in which to return the LMBCS code.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_CONVERSION_ERROR »Page
LCS_OUT_OF_BOUNDS »Page
LCS_STR_TOO_LONG »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lslong CharCode;
lmbcs lpResultStr(LCI_MAX_LMBCS_CHAR_LEN);
lmbcs lpCharStr(LCI_MAX_LMBCS_CHAR_LEN);
. . .
/* Convert LMBCS code 130 to é. */
Status = LciAtCharLongtoStr
(Context,130,
LCI_MAX_LMBCS_CHAR_LEN,
lpResultStr);
/* Status checking here */
/* Convert "A" to LMBCS code 65. */
lstrcpy(lpCharStr,"A");
Status = LciAtCharStrtoLong(Context,lpCharStr,&CharCode);
. . .
Definition
Calculates the number of nonblank cells in a range.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtCount
(LCH_CONTEXT Context,
LCH_RANGE Range,
lptr(lulong) Count)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Range A range object.
Count Pointer to an lulong in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lulong Count;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciAtCount(Context,Range,&Count);
. . .
Status = LciRgDestroy(&Range);
Definition
Calculates the number of compounding periods it takes for an investment of present value to grow to a future value, earning a fixed interest rate per compounding period.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtCTerm
(LCH_CONTEXT Context,
lfloat10 Interest,
lfloat10 FutureVal
lfloat10 PresentVal
lptr(lfloat10) Result)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Interest The fixed interest rate you want to use in the calculation. Interest can be any value greater than -1.0, except 0.0.
FutureVal The future value you want to use in the calculation. The future value is the value to which you want the present value to grow. FutureVal can be any value, but must be a positive value if PresentVal is a positive value or a negative value if PresentVal is a negative value.
PresentVal The present value you want to use in the calculation. The present value is the starting investment value. PresentVal can be any value, but must be a positive value if FutureVal is a positive value or a negative value if FutureVal is a negative value.
Result Pointer to an lfloat10 in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_ERR »Page
LCS_NA »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lfloat10 Result;
. . .
/* How many years to double investment of $10,000
at 10% compounded monthly? */
Status = LciAtCTerm(Context,.1/12,20000,10000,&Result);
. . .
Definition
Calculates the number of days between two date numbers, based on the German standards for a 360-day year. Valid 1-2-3 date numbers are between 1.0 (January 1, 1900) and 73050.0 (December 31. 2099), inclusive. Call LciAtDateValue »Page to get the date number for a specified date string.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtD360
(LCH_CONTEXT Context,
lfloat10 StartDate,
lfloat10 EndDate,
lptr(lulong) Result)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
StartDate Date number that corresponds to the beginning date.
EndDate Date number that corresponds to the ending date.
Result Pointer to an lulong in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_ERR »Page
LCS_NA »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lulong Result;
lulong StartDateNum;
lulong EndDateNum;
lushort Numtype;
lfloat10 StartDate;
lfloat10 EndDate;
. . .
Status = LciAtDateValue(Context,"23-Aug-91",&StartDateNum);
Status = LciAtDateValue(Context,"07-Sep-91",&EndDateNum);
Status = LciMtPushLong(Context,StartDateNum);
Status = LciMtPopFloat10(Context,&StartDate,&Numtype);
Status = LciMtPushLong(Context,EndDateNum);
Status = LciMtPopFloat10(Context,&EndDate,&Numtype);
Status = LciAtD360(Context,StartDate,EndDate,&Result);
. . .
Definition
Calculates the date number for the specified year, month, and day.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDate
(LCH_CONTEXT Context,
lfloat10 Year,
lfloat10 Month,
lfloat10 Day,
lptr(lulong) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Year Number (from 0.0 for 1900 to 199.0 for 2099) that corresponds to the year part of the date.
Month Number (from 1.0 to 12.0) that corresponds to the month part of the date.
Day Number (from 1.0 to 31.0) that corresponds to the day part of the date. The number must be a valid day for month.
lpResult Pointer to an lulong in which to return the result.
Note Even though 1900 was not a leap year, Date assigns a date number to February 29, 1900. This does not invalidate any of your date calculations unless you use dates between January 1, 1900, and March 1, 1900. If you are using dates within that period, subtract 1 from your results.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lulong Result;
. . .
Status = LciAtDate(87,6,1,&Result);
. . .
Definition
Calculates the date number for the specified date.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDateValue
(LCH_CONTEXT Context,
lptr(lmbcs) DateStr,
lptr(lulong) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
DateStr String in one of the following 1-2-3 Date formats: DD-MMM-YY, DD-MMM, MMM-YY, Long Intn'l, or Short Intn'l.
lpResult Pointer to an lulong in which to return the result.
Note Even though 1900 was not a leap year, DateValue assigns a date number to February 29, 1900. This does not invalidate any of your date calculations unless you use dates between January 1, 1900, and March 1, 1900. If you are using dates within that period, subtract 1 from your results.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lulong Result;
lmbcs lpDateStr[ ] = "23-Aug-91";
. . .
Status = LciAtDateValue(Context,lpDateStr,&Result);
. . .
Definition
Averages the values in a field of a database table that meet the specified criteria.
Format
* Field offset *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDAvgByNum
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lushort FieldNum,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
* Field name *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDAvgByName
LCH_CONTEXT Context,
LCH_RANGE InputRange,
lptr(lmbcs) FieldName,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
InputRange Range object that corresponds to the input range (database table).
FieldNum The column number that contains the field in the database whose values you want to average. The first column of the database table is 0, the second is 1, and so on.
CriteriaRange Range object that corresponds to the criteria range (the range that contains the criteria that the values in the field must meet). CriteriaRange must include field names from the input range.You must enter the criteria directly below the appropriate field names.
lpResult Pointer to an lfloat10 in which to return the result.
FieldName Pointer to an lmbcs string that contains the field name in the database table.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Input;
LCH_RANGE Criteria;
LCT_STATUS Status;
lfloat10 Result;
lushort FieldNum;
lmbcs lpFieldName[30];
lmbcs lpInputName[ ] = "INPUT";
lmbcs lpCritName[ ] = "CRITERIA";
. . .
Status = LciRgConstructAddr(Context,lpInputName,&Input);
Status = LciRgConstructAddr(Context,lpCritName,&Criteria);
/* Average values in 2nd column of database table. */
FieldNum = 2;
Status = LciAtDAvgByNum(Context,Input,FieldNum,Criteria,
&Result);
/* Average values by field name. */
lstrcpy(lpfieldname,"EXPENSES");
Status = LciAtDAvgByName(Context,Input,lpFieldName,Criteria,
&Result);
. . .
Status = LciRgDestroy(&Input);
Status = LciRgDestroy(&Criteria);
Definition
Obtains the day of the month (an integer from 1 to 31) from the specified date number.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDay
(LCH_CONTEXT Context,
lfloat10 DateNum,
lptr(lushort) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
DateNum The number between 1.0 (January 1, 1900) and 73050.0 (December 31, 2099) that is the date number from which you want to obtain the day of the month.
lpResult Pointer to an lushort in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lmbcs lpDateStr[ ] = "23-Aug-91";
lulong DateNum;
lfloat10 lfDateNum;
lushort Numtype;
lushort Result;
. . .
Status = LciAtDateValue(Context,lpDateStr,&DateNum);
Status = LciMtPushLong(Context,DateNum);
Status = LciMtPopFloat10(Context,lpDateNum,&Numtype);
Status = LciAtDay(Context,lfDateNum,&Result);
Definition
Calculates the number of days between two date numbers, based on a 360-day year, according to the U.S. securities industry. This uses the algorithm from the Fixed Income Quarterly Report, Vol. 2, Issue 3, published by the Securities Industry Association (120 Broadway, Floor 35, NY,NY 10271). It conforms to the modifications to the 1986 edition of Standard Secirity Calculation Methods. Valid 1-2-3 date numbers are between 1.0 (January 1, 1990) and 73050.0 (December 31, 2099), inclusive. Call LciAtDateValue to get the date number for a specified date string.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDays360
(LCH_CONTEXT Context,
lfloat10 StartDate,
lfloat10 EndDate,
lptr(lulong) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
StartDate Date number that corresponds to the beginning date.
EndDate Date number that corresponds to the ending date.
lpResult Pointer to an lulong in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_ERR »Page
LCS_NA »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lulong Result;
lulong StartDateNum;
lulong EndDateNum;
lushort Numtype;
lfloat10 StartDate;
lfloat10 EndDate;
. . .
Status = LciAtDateValue(Context,"23-Aug-91",&StartDateNum);
Status = LciAtDateValue(Context,"07-Sep-91",&EndDateNum);
Status = LciMtPushLong(Context,StartDateNum);
Status = LciMtPopFloat10(Context,&StartDate,&Numtype);
Status = LciMtPushLong(Context,EndDateNum);
Status = LciMtPopFloat10(Context,&EndDate,&Numtype);
Status = LciAtDays360(Context,StartDate,EndDate,&Result);
Definition
Counts the nonblank cells in a field of a database table that meet the specified criteria.
Format
* Field offset *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDCountByNum
(LCH_CONTEXT Context,
LCH_RANGE InputRange
lushort FieldNum,
LCH_RANGE CriteriaRange,
lptr(lulong) lpResult)
* Field name *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDCountByName
(LCH_CONTEXT Context,
LCH_RANGE InputRange
lptr(lmbcs) FieldName,
LCH_RANGE CriteriaRange
lptr(lulong) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
InputRange Range object that corresponds to the input range (database table).
FieldNum The column number that contains the field in the database whose nonblank cells you want to count. The first column of the database table is 0, the second is 1, and so on.
CriteriaRange Range object that corresponds to the criteria range (the range that contains the criteria that the values in the field must meet). CriteriaRange must include field names from the input range. You must enter the criteria directly below the appropriate field names.
lpResult Pointer to an lulong in which to return the result.
FieldName Pointer to a lmbcs string that contains the field name in the database table.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Input;
LCH_RANGE Criteria;
LCT_STATUS Status;
lulong Result;
lushort FieldNum;
lmbcs lpFieldName[30];
lmbcs lpInputName[ ] = "INPUT";
lmbcs lpCritName[ ] = "CRITERIA";
. . .
Status = LciRgConstructAddr(Context,lpInputName,&Input);
Status = LciRgConstructAddr(Context,lpCritName,&Criteria);
/* Count nonblank cells in 2nd column of table. */
FieldNum = 2;
Status = LciAtDCountByNum(Context,Input,FieldNum,Criteria,
&Result);
/* Count nonblank cells by field name. */
lstrcpy(lpFieldName,"EXPENSES");
Status = LciAtDCountByName(Context,Input,lpFieldName,Criteria,
&Result);
. . .
Status = LciRgDestroy(&Input);
Status = LciRgDestroy(&Criteria);
Definition
Calculates the depreciation allowance of an asset for a specified period of time, using the double-declining balance method.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDDB
(LCH_CONTEXT Context,
lfloat10 Cost,
lfloat10 Salvage,
lfloat10 Life,
lfloat10 Period,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Cost The amount paid for the asset used in the calculation. Cost can be any value greater than or equal to Salvage.
Salvage The estimated value of the asset at the end of its life. Salvage can be any value.
Life The number of periods it takes to depreciate the asset to its salvage value. Life can be any value greater than 2.0.
Period The time period for which you want to find the depreciation allowance. Period can be any value greater than or equal to 1.0.
lpResult Pointer to an lfloat10 in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Note If the salvage value of an asset is relatively low, DDB may not fully depreciate the asset by the end of the estimated useful life. You may want to use VDB, which always fully depreciates the asset within the estimated life.
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lfloat10 Result;
. . .
/* Calculates double-declining balance for equipment purchased
for $10,000 with a useful life of 8 years, and a salvage value
of $1,200. Expense is calculated in 5th year. */
Status = LciAtDDB(Context,l0000,1200,8,5,&Result);
Definition
Retrieves a value or a label in a field of a database table that meets the specified criteria.
Format
* Float, offset *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDGetFloatByNum
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lushort FieldNum,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
* Float, field name *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDGetFloatByName
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lptr(lmbcs) FieldName,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
* String, offset *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDGetStrByNum
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lushort FieldNum,
LCH_RANGE CriteriaRange,
lushort BufLen,
lptr(lmbcs) lpResultStr)
* String, field name *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDGetStrByName
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lptr(lmbcs) FieldName,
LCH_RANGE CriteriaRange,
lushort BufLen,
lptr(lmbcs) lpResultStr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
InputRange Range object that corresponds to the input range (database table).
FieldNum The column number that contains the field in the database in which there is a value you want to retrieve. The first column of the database table is 0, the second is 1, and so on.
CriteriaRange Range object that corresponds to the criteria range (the range that contains the criteria that a value in the field must meet). CriteriaRange must include field names from the input range. You must enter the criteria directly below the appropriate field names.
lpResult Pointer to an lfloat10 in which to return the result.
FieldName Pointer to a lmbcs string that contains the field name in the database table.
BufLen The number of bytes available in the buffer .
lpResultStr Pointer to a lmbcs string in which to return the resulting string.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_OUT_OF_MEMORY »Page
Note If more than one record meets the criteria, DGet returns LCS_ERR.
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Input;
LCH_RANGE Criteria;
LCT_STATUS Status;
lfloat10 Result;
lushort FieldNum = 2;
lmbcs lpFieldName[30];
lmbcs lpInputName[ ] = "INPUT";
lmbcs lpCritName[ ] = "CRITERIA";
lushort BufLen = LCI_MAX_ZERO_STR_LEN;
lmbcs lpResultStr[LCI_MAX_ZERO_STR_LEN];
. . .
Status = LciRgConstructAddr(Context,lpInputName,&Input);
Status = LciRgConstructAddr(Context,lpCritName,&Criteria);
Status = LciAtDGetFloatByNum(Context,Input,FieldNum,Criteria,
&Result);
lstrcpy(lpFieldName,"EXPENSES");
Status = LciAtDGetFloatByName(Context,Input,lpFieldName,Criteria,
&Result);
Status = LciAtDGetStrByNum(Context,Input,FieldNum,Criteria,
BufLen,lpResultStr);
Status = LciAtDGetStrByName(Context,Input,lpFieldName,Criteria,
BufLen,lpResultStr);
. . .
Status = LciRgDestroy(&Input);
Status = LciRgDestroy(&Criteria);
Definition
Finds the largest value in a field of a database table that meets the specified criteria.
Format
* Field offset *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDMaxByNum
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lushort FieldNum,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
* Field name *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDMaxByName
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lptr(lmbcs) FieldName,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
InputRange Range object that corresponds to the input range (database table).
FieldNum The column number that contains the field in the database whose largest value you want to find. The first column of the database table is 0, the second is 1, and so on.
CriteriaRange Range object that corresponds to the criteria range (the range that contains the criteria that a value in the field must meet). CriteriaRange must include field names from the input range. You must enter the criteria directly below the appropriate field names.
lpResult Pointer to an lfloat10 in which to return the result.
FieldName The field name in the database table.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Input;
LCH_RANGE Criteria;
LCT_STATUS Status;
lfloat10 Result;
lushort FieldNum = 2;
lmbcs lpFieldName[30];
lmbcs lpInputName[ ] = "INPUT";
lmbcs lpCritName[ ] = "CRITERIA";
. . .
Status = LciRgConstructAddr(Context,lpInputName,&Input);
Status = LciRgConstructAddr(Context,lpCritName,&Criteria);
/* Find largest value in 2nd column. */
Status = LciAtDMaxByNum(Context,Input,FieldNum,Criteria,&Result);
/* Find largest value in EXPENSES field. */
lstrcpy(lpFieldName,"EXPENSES");
Status = LciAtDMaxByName(Context,Input,lpFieldName,Criteria,
&Result);
. . .
Status = LciRgDestroy(&Input);
Status = LciRgDestroy(&Criteria);
Definition
Finds the smallest value in a field of a database table that meets the specified criteria.
Format
* Field offset *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDMinByNum
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lushort FieldNum,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
* Field name *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDMinByName
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lptr(lmbcs) FieldName,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
InputRange Range object that corresponds to the input range (database table).
FieldNum The column number that contains the field in the database whose smallest value you want to find. The first column of the database table is 0, the second is 1, and so on.
CriteriaRange Range object that corresponds to the criteria range (the range that contains the criteria that a value in the field must meet). CriteriaRange must include field names from the input range. You must enter the criteria directly below the appropriate field names.
lpResult Pointer to an lfloat10 in which to return the result.
FieldName The field name in the database table.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Input;
LCH_RANGE Criteria;
LCT_STATUS Status;
lfloat10 Result;
lushort FieldNum = 2;
lmbcs lpFieldName[30];
lmbcs lpInputName[ ] = "INPUT";
lmbcs lpCritName[ ] = "CRITERIA";
. . .
Status = LciRgConstructAddr(Context,lpInputName,&Input);
Status = LciRgConstructAddr(Context,lpCritName,&Criteria);
/* Find smallest value in 2nd column. */
Status = LciAtDMinByNum(Context,Input,FieldNum,Criteria,&Result);
/* Find smallest value in EXPENSES field. */
lstrcpy(lpFieldName,"EXPENSES");
Status = LciAtDMinByName(Context,Input,lpFieldName,Criteria,
&Result);
. . .
Status = LciRgDestroy(&Input);
Status = LciRgDestroy(&Criteria);
Definition
Calculates the population standard deviation of the values in a field of a database table that meet the specified criteria.
Format
* Field offset *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDStDByNum
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lushort FieldNum,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
* Field name *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDStDByName
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lptr(lmbcs) FieldName,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
InputRange Range object that corresponds to the input range (database table).
FieldNum The column number that contains the field in the database in which there are values whose standard deviation you want to calculate. The first column of the database table is 0, the second is 1, and so on.
CriteriaRange Range object that corresponds to the criteria range (the range that contains the criteria that the values in the field must meet). CriteriaRange must include field names from the input range. You must enter the criteria directly below the appropriate field names.
lpResult Pointer to an lfloat10 in which to return the result.
FieldName Pointer to a lmbcs string that contains the field name in the database table.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Input;
LCH_RANGE Criteria;
LCT_STATUS Status;
lfloat10 Result;
lushort FieldNum = 2;
lmbcs lpFieldName[30];
lmbcs lpInputName[ ] = "INPUT";
lmbcs lpCritName[ ] = "CRITERIA";
. . .
Status = LciRgConstructAddr(Context,lpInputName,&Input);
Status = LciRgConstructAddr(Context,lpCritName,&Criteria);
/* Find population standard deviation in 2nd column. */
Status = LciAtDStDByNum(Context,Input,FieldNum,Criteria,&Result);
/* Find population standard deviation in COUNTRIES field. */
lstrcpy(lpFieldName,"COUNTRIES");
Status = LciAtDStDByName(Context,Input,lpFieldName,Criteria,
&Result);
. . .
Status = LciRgDestroy(&Input);
Status = LciRgDestroy(&Criteria);
Definition
Calculates the sample standard deviation of the values in a field of a database table that meet the specified criteria.
Format
* Field offset *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDStDSByNum
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lushort FieldNum,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
* Field name *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDStDSByName
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lptr(lmbcs) FieldName,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
InputRange Range object that corresponds to the input range (database table).
FieldNum The column number that contains the field in the database in which there are sample values whose standard deviation you want to calculate. The first column of the database table is 0, the second is 1, and so on.
CriteriaRange Range object that corresponds to the criteria range (the range that contains the criteria that a sample value in the field must meet). CriteriaRange must include field names from the input range. You must enter the criteria directly below the appropriate field names.
lpResult Pointer to an lfloat10 in which to return the result.
FieldName Pointer to a lmbcs string that contains the field name in the database table.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Input;
LCH_RANGE Criteria;
LCT_STATUS Status;
lfloat10 Result;
lushort FieldNum = 2;
lmbcs lpFieldName[30];
lmbcs lpInputName[ ] = "INPUT";
lmbcs lpCritName[ ] = "CRITERIA";
. . .
Status = LciRgConstructAddr(Context,lpInputName,&Input);
Status = LciRgConstructAddr(Context,lpCritName,&Criteria);
/* Find sample standard deviation in 2nd column. */
Status = LciAtDStdDSByNum(Context,Input,FieldNum,Criteria,
&Result);
/* Find sample standard deviation in COUNTRIES field. */
lstrcpy(lpFieldName,"COUNTRIES");
Status = LciAtDStdSByName(Context,Input,lpFieldName,Criteria,
&Result);
. . .
Status = LciRgDestroy(&Input);
Status = LciRgDestroy(&Criteria);
Definition
Calculates the sum of the values in a field of a database table that meet the specified criteria.
Format
* Field offset *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDSumByNum
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lushort FieldNum,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
* Field name *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDSumByName
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lptr(lmbcs) FieldName,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
InputRange Range object that corresponds to the input range (database table).
FieldNum The column number that contains the field in the database the sum of whose values you want to calculate. The first column of the database table is 0, the second is 1, and so on.
CriteriaRange Range object that corresponds to the criteria range (the range that contains the criteria that the values in the field must meet). CriteriaRange must include field names from the input range. You must enter the criteria directly below the appropriate field names.
lpResult Pointer to an lfloat10 in which to return the result.
FieldName Pointer to a lmbcs string that contains the field name in the database table.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Input;
LCH_RANGE Criteria;
LCT_STATUS Status;
lfloat10 Result;
lushort FieldNum = 2;
lmbcs lpFieldName[30];
lmbcs lpInputName[ ] = "INPUT";
lmbcs lpCritName[ ] = "CRITERIA";
. . .
Status = LciRgConstructAddr(Context,lpInputName,&Input);
Status = LciRgConstructAddr(Context,lpCritName,&Criteria);
/* Find sum of values in 2nd column. */
Status = LciAtDSumByNum(Context,Input,FieldNum,Criteria,&Result);
/* Find sum of values in QUANTITIES field. */
lstrcpy(lpFieldName,"QUANTITIES");
Status = LciAtDSumByName(Context,Input,lpFieldName,Criteria,
&Result);
. . .
Status = LciRgDestroy(&Input);
Status = LciRgDestroy(&Criteria);
Definition
Calculates the population variance of the values in a field of a database table that meet the specified criteria.
Format
* Field offset *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDVarByNum
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lushort FieldNum,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
* Field name *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDVarByName
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lptr(lmbcs) FieldName,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
InputRange Range object that corresponds to the input range (database table).
FieldNum The column number that contains the field in the database the variance of whose values you want to calculate. The first column of the database table is 0, the second is 1, and so on.
CriteriaRange Range object that corresponds to the criteria range (the range that contains the criteria that the values in the field must meet). CriteriaRange must include field names from the input range. You must enter the criteria directly below the appropriate field names.
lpResult Pointer to an lfloat10 in which to return the result.
FieldName Pointer to a lmbcs string that contains the field name in the database table.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Input;
LCH_RANGE Criteria;
LCT_STATUS Status;
lfloat10 Result;
lushort FieldNum = 2;
lmbcs lpFieldName[30];
lmbcs lpInputName[ ] = "INPUT";
lmbcs lpCritName[ ] = "CRITERIA";
. . .
Status = LciRgConstructAddr(Context,lpInputName,&Input);
Status = LciRgConstructAddr(Context,lpCritName,&Criteria);
/* Find population variance in 2nd column. */
Status = LciAtDVarByNum(Context,Input,FieldNum,Criteria,&Result);
/* Find population variance in COUNTRIES field. */
lstrcpy(lpFieldName,"COUNTRIES");
Status = LciAtDVarByName(Context,Input,lpFieldName,Criteria,
&Result);
. . .
Status = LciRgDestroy(&Input);
Status = LciRgDestroy(&Criteria);
Definition
Calculates the sample variance of the values in a field of a database table that meet the specified criteria.
Format
* Field offset *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDVarSByNum
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lushort FieldNum,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
* Field name *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtDVarSByName
(LCH_CONTEXT Context,
LCH_RANGE InputRange,
lptr(lmbcs) FieldName,
LCH_RANGE CriteriaRange,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
InputRange Range object that corresponds to the input range (database table).
FieldNum The column number that contains the field in the database the variance of whose sample values you want to calculate. The first column of the database table is 0, the second is 1, and so on.
CriteriaRange Range object that corresponds to the criteria range (the range that contains the criteria that a sample value in the field must meet). CriteriaRange must include field names from the input range. You must enter the criteria directly below the appropriate field names.
lpResult Pointer to an lfloat10 in which to return the result.
FieldName Pointer to a lmbcs string that contains field name in the database table.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Input;
LCH_RANGE Criteria;
LCT_STATUS Status;
lfloat10 Result;
lushort FieldNum = 2;
lmbcs lpFieldName[30];
lmbcs lpInputName[ ] = "INPUT";
lmbcs lpCritName[ ] = "CRITERIA";
. . .
Status = LciRgConstructAddr(Context,lpInputName,&Input);
Status = LciRgConstructAddr(Context,lpCritName,&Criteria);
/* Find sample variance in 2nd column. */
Status = LciAtDVarSByNum(Context,Input,FieldNum,Criteria,&Result);
/* Find sample variance in COUNTRIES field. */
lstrcpy(lpFieldName,"COUNTRIES");
Status = LciAtDVarSByName(Context,Input,lpFieldName,Criteria,
&Result);
. . .
Status = LciRgDestroy(&Input);
Status = LciRgDestroy(&Criteria);
Definition
Tests whether two strings match exactly. Exact provides a more precise alternative to the equal operator (=) in a string formula because it distinguishes between uppercase and lowercase letters, between letters with and without accent marks, and between strings that do or do not contain leading or trailing spaces. If the boolean result is LTRUE, the two strings match exactly; if the result is LFALSE, they do not.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtExact
(LCH_CONTEXT Context,
lptr(lmbcs) lpString1,
lptr(lmbcs) lpString2,
lptr(lbool) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpString1 The first string you want to test.
lpString2 The second string you want to test.
lpResult Pointer to an lbool in which to return the boolean result.
Note lpString1 and lpString2 must not exceed LCI_MAX_CELL_LEN in length (including the null-terminating byte).
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STR_TOO_LONG »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcicell.h"
. . .
LCH_CELL CurrentCell;
LCH_CELL MatchCell;
LCT_STATUS Status;
lmbcs lpString1[LCI_MAX_CELL_LEN];
lmbcs lpString2[LCI_MAX_CELL_LEN];
lbool ExactResult;
lushort ContentsType;
. . .
/* Compare the current cell with the home cell in the current
workfile. */
Status = LciClConstructCurr(Context,&CurrentCell);
Status = LciClConstructCoords(Context,
LCI_CURRENT_WORKFILE,
LCI_CURRENT_SHEET,1,1,&MatchCell);
/* Get string from match cell. */
Status = LciClGetContentsString(MatchCell,LCI_MAX_CELL_LEN,
lpstring1);
/* Make sure current cell is a string. */
Status = LciClGetContentsType(CurrentCell,&ContentsType);
if (ContentsType != LCI_CONTENTS_TYPE_LABEL)
return (Status);
Status = LciClGetContentsString(CurrentCell,LCI_MAX_CELL_LEN,
lpstring2);
Status = LciAtExact(Context,lpString1,lpString2,&ExactResult);
. . .
Status = LciClDestroy(CurrentCell);
Status = LciClDestroy(MatchCell);
Definition
Calculates the position in a target string at which it finds the first occurrence of a search string. Find begins searching the target string at the designated position.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtFind
(LCH_CONTEXT Context,
lptr(lmbcs) SearchStr,
lptr(lmbcs) TargetStr,
lushort Start,
lptr(lushort) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
SearchStr Pointer to a lmbcs string that contains the string you want to search for in TargetStr.
TargetStr Pointer to a lmbcs string that contains the string to search.
Start The first character in TargetStr at which you want to begin the search. This is a zero-based number. Start should not be greater than LCI_MAX_CELL_LEN-2.
lpResult Pointer to an lushort in which to return the result.
Note SearchStr and TargetStr should not exceed LCI_MAX_CELL_LEN in length (including the null-terminating byte).
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STR_TOO_LONG »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Note Find is case sensitive. For instance, if you want to find the "we" in "Wesley", you must specify the search string as "We".
Find returns LCS_ERR if it does not find SearchStr. It also returns LCS_ERR if the Start value is greater than LCI_MAX_CELL_LEN-2.
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcicell.h"
. . .
LCH_CELL CurrentCell;
LCH_CELL TargetCell;
LCT_STATUS Status;
lmbcs lpSearchStr[LCI_MAX_CELL_LEN]; /* Include null terminator. */
lmbcs lpTargetStr[LCI_MAX_CELL_LEN]; /* Include null terminator. */
lushort Start;
lushort Result;
lushort ContentsType;
. . .
Status = LciClConstructCurr(Context,&CurrentCell);
Status = LciClConstructCoords(Context,
LCI_CURRENT_WORKFILE,
LCI_CURRENT_SHEET,
1,1,&TargetCell);
/* Get Search String from current cell. */
Status = LciClGetContentsString(CurrentCell,LCI_MAX_CELL_LEN,
lpSearchStr);
/* Make sure target cell containsa string. */
Status = LciGetContentsType(TargetCell,&ContentsType);
if (ContentsType != LCI_CONTENTS_TYPE_LABEL)
return (Status);
Status = LciClGetContentsString(TargetCell,LCI_MAX_CELL_LEN,
lpTargetStr);
Start = 2;
Status = LciAtFind(Context,lpSearchStr,lpTargetStr,Start,&Result);
. . .
Status = LciClDestroy(CurrentCell);
Status = LciClDestroy(TargetCell);
Definition
Calculates the future value of an investment, based on a series of equal payments earning a periodic interest rate over a specified number of payment periods.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtFV
(LCH_CONTEXT Context,
lfloat10 Payment,
lfloat10 Interest,
lfloat10 Term,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Payment Periodic payment.
Interest Periodic interest rate.
Term Number of periods.
lpResult Pointer to an lfloat10 in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Note FV assumes that your calculations use an investment that is an ordinary annuity (a payment at the end of a term). If you want to calculate the future value of an annuity due (a payment at the beginning of a term), use the following formula: FV(Payment, Interest, Term) (1 + Interest).
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lfloat10 Result;
. . .
/* Calculate future value of depositing $2,000
per year for the next 20 years at an interest rate
of 7.5% compounded annually. */
Status = LciAtFV(Context,2000,.075,20,&Result);
Definition
Retrieves the contents of the cell in a specified row of a horizontal look-up table. The function compares a specified value (a number or a string) to each cell in the top row of a range. When it locates the value in the top row, it moves down that column by a specified number of rows to the cell from which it retrieves the contents.
You can also use HLookup to locate a label in the first row of a specified range.
Format
* Float lookup, float lpResult *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtHLookupNumToNum
(LCH_CONTEXT Context,
lfloat10 LookupVal,
LCH_RANGE Range,
lushort RowOffset,
lptr(lfloat10) lpResult)
* Float lookup, string lpResult *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtHLookupNumToStr
(LCH_CONTEXT Context,
lfloat10 LookupStr,
LCH_RANGE Range,
lushort RowOffset,
lushort BufLen,
lptr(lmbcs) lpResultStr)
* String lookup, float Result *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtHLookupStrToNum
(LCH_CONTEXT Context,
lptr(lmbcs) LookupStr,
LCH_RANGE Range,
lushort RowOffset,
lptr(lfloat10) lpResult)
* String lookup, string Result *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtHLookupStrToStr
(LCH_CONTEXT Context,
lptr(lmbcs) LookupStr,
LCH_RANGE Range,
lushort RowOffset,
lushort BufLen,
lptr(lmbcs) lpResultStr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
LookupStr A pointer to a lmbcs string that is used to locate the desired column in the specified range.
LookupVal Value used to locate the desired column in the specified range.
Range Range object that contains the top row of the look-up table.
RowOffset Offset from the top row in the column that contains LookupVal.
BufLen The maximum length of the string expected to be retrieved from a string look-up.
lpResult A pointer to an lfloat10 to contain the result of a float look-up.
lpResultStr A pointer to a lmbcs string to contain the result of a string look-up.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_OUT_OF_MEMORY »Page
Note A float LookupVal can be any value greater than or equal to the first value in the top row of range. If LookupVal is smaller than the first value in the top row of range, or if LookupStr does not correspond to any label in the first row, LciAtHLookup returns LCS_ERR. If LookupVal is larger than the last value in the top row of range, LciAtHLookup stops at the last cell in the row and returns the contents of the cell RowOffset rows down that column.
LCS_ERR is also returned if the look-up string length is greater than LCI_MAX_CELL_LEN-1.
Example
#include "windows.h
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
#include "lcirange"
. . .
LCH_RANGE LookupRange;
LCT_STATUS Status;
lfloat10 LookupVal;
lmbcs lpLookupStr[LCI_MAX_CELL_LEN];
lfloat10 Result;
lmbcs lpResultStr[LCI_MAX_CELL_LEN];
lushort Numtype;
lushort RowOffset;
lmbcs lpRangeAddr[LCI_MAX_ADDR_LEN];
. . .
Status = LciMtPushlong(Context,1991);
Status = LciMtPopFloat10(Context,&LookupVal,&Numtype);
lstrcpy(lpLookupStr,"JANUARY");
lstrcpy(lpRangeAddr,"B1..E1");
RowOffset = 10;
Status = LciRgConstructAddr(Context,lpRangeAddr,&LookupRange);
Status = LciAtHLookupNumToNum(Context,LookupVal,LookupRange,
RowOffset,&Result);
Status = LciAtHLookupNumToStr(Context,LookupVal,LookupRange,
RowOffset,
LCI_MAX_CELL_LEN,lpResultStr);
Status = LciAtHLookupStrToNum(Context,lpLookupStr,LookupRange,
RowOffset,&Result);
Status = LciAtHLookupStrToStr(Context,lpLookupStr,LookupRange,
RowOffset,
LCI_MAX_CELL_LEN,lpResultStr);
. . .
Status = LciRgDestroy(&LookupRange);
Definition
Calculates the hour, a value between 0 (midnight) and 23 (11:00 p.m.), from the specified time number.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtHour
(LCH_CONTEXT Context,
lfloat10 Time,
lptr(lushort) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Time Time number (a value between .000000 (midnight) and .999988 (11:59:59 p.m.), inclusive).
lpResult Pointer to an lushort in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lushort Result;
. . .
/* Find hour for 11:59:59. */
Status = LciAtHour(Context,.999988,&Result);
Definition
Retrieves system information for the current 1-2-3 session.
Format
* Float *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtInfoNum
(LCH_CONTEXT Context,
lushort InfoType,
lptr(lfloat10) lpResult)
* String *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtInfoStr
(LCH_CONTEXT Context,
lushort InfoType,
lushort BufLen,
lptr(lmbcs) lpResultStr)
The InfoType argument specifies the system information. It can have one of
the following values:
Constant Meaning
LCI_FLOAT_INFO_MEMAVAIL Float value that is the current amount of available memory
LCI_FLOAT_INFO_MODE Float value that is the current mode, which can have one of the following values:
0 WAIT
1 READY
2 LABEL
3 MENU
4 VALUE
5 POINT
6 EDIT
7 ERROR
8 FIND
9 FILES
10 HELP
11 STAT
13 NAMES
99 all others (for example, user defined with {INDICATE}
LCI_FLOAT_INFO_NUMFILE Float value that is the current number of active files
LCI_FLOAT_INFO_OSRETURNCODE Float value that is the value returned by the most recent System command or {SYSTEM} advanced macro command
LCI_FLOAT_INFO_TOTMEM Float value that is the total memory available (both the amount currently available and the amount already being used)
LCI_FLOAT_INFO_DBRETURNCODE Most recent error code returned by a DataLens driver
LCI_FLOAT_INFO_DBRECORDCOUNT Number of records extracted, modified, inserted from the last query in the worksheet or in an external database
LCI_STR_INFO_DIRECTORY String value that is the current directory
LCI_STR_INFO_ORIGIN String value that is the first location of the cell pointer (as a cell address) during a 1-2-3 session
LCI_STR_INFO_OSVERSION String value that is the current operating system version
LCI_STR_INFO_RECALC String value that corresponds to the current recalculation mode: either "automatic" or "manual"
LCI_STR_INFO_RELEASE String value that is the release number of the 12-3 product being used. The release number consists of three parts: major release number, upgrade level, and revision number
LCI_STR_INFO_DBDRIVERMESSAGE Most recent DataLens driver message
LCI_STR_INFO_WINDOW_SPLIT String value that indicates the normal, vertical, horizontal, or perspective Status of the window
LCI_STR_INFO_SYSTEM String value that is the name of the operating system
LCI_STR_INFO_SELECTION String value that is the current selection
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
InfoType Value that specifies the system information you want (you must use the float values with LciAtInfoNum).
lpResult Pointer to an lfloat10 in which to return the result.
BufLen The number of bytes available in the buffer pointed to by lpResultStr, including room for a trailing null byte.
lpResultStr Pointer to a lmbcs string in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_INVALID_TYPE »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lfloat10 Result;
lmbcs lpResultStr[50];
. . .
Status = LciAtInfoNum(Context,LCI_FLOAT_INFO_MODE,&Result);
Status = LciAtInfoStr(Context,LCI_STR_INFO_SELECTION,lpResultStr);
Definition
Calculates the expected internal rate of return (profit) for a series of cash flow values generated by an investment. The internal rate of return is the percentage rate at which the present value of an expected series of cash flows is equal to the present value of the initial investment.
IRR calculates the internal rate of return based on cash flows received at regular, equal intervals.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtIRR
(LCH_CONTEXT Context,
lfloat10 Guess,
LCH_RANGE Range,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Guess Your estimate of the internal rate of return. In most cases this should be a value between 0.0 (0% profit) and 1.0 (100% profit).
Range A range object that contains the cash flows upon which you want to base your result.
lpResult Pointer to an lfloat10 in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Note If IRR cannot approximate lpResult to within 0.0000001 after 30 calculations, it returns LCS_ERR. If your guesses continue to return LCS_ERR, use NPV to determine a better estimate.
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
#include "lcirange"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lfloat8 Guess;
lushort Numtype;
lfloat10 Guess2;
lfloat10 Result;
. . .
Status = LciRgConstructAddr(Context,"IRR",&Range);
Guess = .5;
Status = LciMtPushFloat8(Context,Guess);
Status = LciMtPushFloat10(Context,&Guess2,&NumType);
Status = LciAtIRR(Context,Guess2,Range,&Result);
. . .
Status = LciRgDestroy(&Range);
Definition
Returns the current Lmbcs codepage group.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtLmbcsGroup
(LCH_CONTEXT Context,
lptr(lslong) lpGroupcode)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpGroupcode pointer to a long returns the Lmbcs codepage group
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
....
LCH_STATUS Status;
long lpGroupCode;
....
Status = LciAtLmcbsGroup(Context,&lpGroupCode);
Definition
Tests the input value for the value ERR. If the boolean result is LTRUE, the value in the cell is ERR. If the result is LFALSE, the value in the cell is not ERR.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtIsERR
(LCH_CONTEXT Context,
LCH_CELL Cell,
lptr(lbool) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Cell A cell object.
lpResult Pointer to an lbool in which to return the boolean result.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lbool Result;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciAtIsERR(Context,Cell,&Result);
. . .
Status = LciClDestroy(&Cell);
Definition
Tests the input value for the value NA. If the boolean result is LTRUE, the value in the cell is NA. If the result is LFALSE, the value in the cell is not NA.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtIsNA
(LCH_CONTEXT Context,
LCH_CELL Cell,
lptr(lbool) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Cell A cell object.
lpResult Pointer to an lbool in which to return the boolean result.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lbool Result;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciAtIsNA(Context,Cell,&Result);
. . .
Status = LciClDestroy(&Cell);
Definition
Tests the specified cell for a numeric value. If the boolean result is LTRUE, the cell contains a numeric value, NA, ERR, or is blank. If the result is LFALSE, the cell contains a string.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtIsNumber
(LCH_CONTEXT Context,
LCH_CELL Cell,
lptr(lbool) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Cell A cell object.
lpResult Pointer to an lbool in which to return the boolean result.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lbool Result;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciAtIsNumber(Context,Cell,&Result);
. . .
Status = LciClDestroy(&Cell);
Definition
Determines if the specified range name is defined. If the boolean result is LTRUE, the range name is defined. If the result is LFALSE, the range name is not defined.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtIsRange
(LCH_CONTEXT Context,
lptr(lmbcs) RangeName,
lptr(lbool) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
RangeName The range name you want to check.
lpResult Pointer to an lbool in which to return the boolean result.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lbool Result;
. . .
Status = LciAtIsRange(Context,"EXPENSES",&Result);
Definition
Tests the specified cell for a label. If the boolean result is LTRUE, the cell contains a label. If the result is LFALSE, the cell contains a number, NA, ERR, or is blank.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtIsString
(LCH_CONTEXT Context,
LCH_CELL Cell,
lptr(lbool) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Cell A cell object.
lpResult Pointer to an lbool in which to return the boolean result.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lbool Result;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciAtIsString(Context,Cell,&Result);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the specified number of characters in a string.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtLeft
(LCH_CONTEXT Context,
lptr(lmbcs) SourceStr,
lushort CharCount,
lushort BufLen,
lptr(lmbcs) lpResultStr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
SourceStr The string from which to retrieve CharCount characters. SourceStr can be a literal string, a reference to a cell that contains a label, or a formula that evaluates to a string. The length of SourceString must not exceed LCI_MAX_CELL_LEN (including the null-terminating byte).
CharCount Number of characters you want to obtain (any positive integer or 0).
BufLen The number of bytes available in the buffer pointed to by lpResultStr, including room for the null-terminating byte.
lpResultStr Pointer to a lmbcs string in which to return the result string. If CharCount is 0, the result is an empty string. If CharCount is larger than the length of SourceStr, LciAtLeft returns the entire source string.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_OUT_OF_MEMORY »Page
Notes
LciAtLeft counts punctuation and spaces as characters.
LCS_ERR is also returned if CharCount is too big (LCI_MAX_CELL_LEN-1).
LCS_STR_TOO_LONG is returned if the result string is truncated.
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort PaneNum;
lushort BufLen;
lushort ColWidth,CharCount;
lmbcs lpString[LCI_MAX_CELL_LEN];
lmbcs lpResult[LCI_MAX_CELL_LEN];
lushort ContentsType;
. . .
PaneNum = LCI_CURRENT_PANE;
BufLen = LCI_MAX_CELL_LEN;
/* Use column width or current cell to determine
character count. */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetColWidth(Cell,PaneNum,&ColWidth);
CharCount = ColWidth;
Status = LciClGetContentsType(Cell,&ContentsType);
if (ContentsType != LCI_CONTENTS_TYPE_LABEL)
return (LCS_INVALID_CELL);
Status = LciClGetContentsStr(Cell,BufLen,lpString);
Status = LciAtLeft(Context,lpString,CharCount,BufLen,lpResult)
. . .
Status = LciClDestroy(&Cell);
Definition
Converts all the letters in the specified string to lowercase.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtLower
(LCH_CONTEXT Context,
lptr(lmbcs) SourceStr,
lushort BufLen,
lptr(lmbcs) lpResultStr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
SourceStr Pointer to the string you want to convert. The length of SourceStr should not exceed LCI_MAX_CELL_LEN, including the null-terminating byte.
BufLen The number of bytes available in the buffer pointed to by lpResultStr, including room for a trailing null byte.
lpResultStr Pointer to a lmbcs string in which to return the result string. lpResultStr is a null string if the status returned is anything other than LCS_SUCCESS.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_OUT_OF_MEMORY »Page
Note LCS_STR_TOO_LONG us returned if SourceStr is longer than LCI_MAX_CELL_LEN or if BufLen is not big enough for lpResultStr. In the latter case, lpResultStr is truncated.
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort BufLen = LCI_MAX_CELL_LEN;
lmbcs lpString[LCI_MAX_CELL_LEN];
lmbcs lpResult[LCI_MAX_CELL_LEN];
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,BufLen,lpString);
Status = LciAtLower(Context,lpString,BufLen,lpResult)
. . .
Status = LciClDestroy(&Cell);
Definition
Obtains the largest value in a range of numbers or numeric formulas.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtMax
(LCH_CONTEXT Context,
LCH_RANGE Range,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Range A range object.
lpResult Pointer to an lfloat10 in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lfloat10 Result;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciAtMax(Context,Range,&Result);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves a specified number of characters in a string, beginning with the character at a specified position.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtMid
(LCH_CONTEXT Context,
lptr(lmbcs) SourceStr,
lushort Start,
lushort CharCount,
lushort BufLen,
lptr(lmbcs) lpResultStr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
SourceStr Pointer to the string (LCI_MAX_CELL_LEN bytes or less) from which you want to extract characters. It can be a literal string, a reference to a cell that contains a label, or a formula that evaluates to a string.
Start Any positive integer or 0 that indicates where you want to begin obtaining characters in SourceStr. Numbering starts at 0 for the first character in the string, 1 for the second, and so on.
CharCount Number of characters you want to obtain (any positive integer or 0).
BufLen The number of bytes available in the buffer pointed to by lpResultStr, including room for a trailing null byte.
lpResultStr Pointer to a lmbcs string in which to return the result string.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_OUT_OF_MEMORY »Page
Notes
LciAtMid counts punctuation and spaces as characters.
If CharCount is 0, or Start is greater than the length of the string, lpResult is an empty string.
Use a large number for CharCount if you do not know the length of SourceStr. LciAtMid will retrieve SourceStr from Start to its end.
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lmbcs lpString = "This is the string";
lushort Start = 2;
lushort CharCount = 5;
lushort BufLen = 30;
lmbcs lpResult[30];
. . .
Status = LciAtMid(Context, lpString, Start, CharCount,
BufLen, lpResult);
Definition
Obtains the smallest value in a range of numbers or numeric formulas.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtMin
(LCH_CONTEXT Context,
LCH_RANGE Range,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Range A range object.
lpResult Pointer to an lfloat10 in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lfloat10 Result;
. . .
Status = LciRgConstructAddr(Context,"EXPENSES",&Range);
Status = LciAtMin(Context,Range,&Result);
. . .
Status = LciRgDestroy(&Range);
Definition
Obtains the minute from the specified time number.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtMinute
(LCH_CONTEXT Context,
lfloat10 Time,
lptr(lushort) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Time Time number (a number between .000000 (midnight) and .999988 (11:59:59 p.m.)).
lpResult Pointer to an lushort in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lfloat10 Time;
lushort Result;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Cell contains a time value */
Status = LciClGetContentsNum(Cell,&Time);
Status = LciAtMinute(Context,Time,&Result);
. . .
Status = LciClDestroy(&Cell);
Definition
Obtains the month in the specified date number.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtMonth
(LCH_CONTEXT Context,
lfloat10 Date,
lptr(lushort) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Date Date number (the number between 1.0 (January 1, 1900) and 73050.0 (December 31, 2099), inclusive).
lpResult Pointer to an lushort in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lushort Numtype;
lfloat10 Date;
lushort Result;
. . .
/* Obtain month for 4/2/55. */
Status = LciMtPushLong(Context,20181);
Status = LciMtPopFloat10(Context,&Date,&Numtype);
Status = LciAtMonth(Context,Date,&Result);
Definition
Creates a line feed and a carriage return character to move the output down and to the beginning of a line. It is used in conjunction with display and printer outputs.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtNewline
(LCH_CONTEXT Context,
lushort BufLen,
lptr(lmbcs) lpResultStr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
BufLen The number of bytes available in the buffer pointed to by lpResultStr, including room for a trailing null byte.
lpResultStr Pointer to a lmbcs string in which to return the result string, consisting of a carriage return (ASCII 010) followed by a newline (ASCII 013) followed by a null character (0).
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Note LCS_STR_TOO_LONG is returned if BufLen is less than LCI_MAX_NEWLINE_LEN.
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lushort BufLen = LCI_MAX_NEWLINE_LEN;
lmbcs lpResult[LCI_MAX_NEWLINE_LEN];
. . .
Status = LciAtNewline(Context,BufLen,lpResult)
Definition
Retrieves the value that corresponds to the current date and time. This includes both a date number (the integer part of the returned value) and a time number (the decimal part of the returned value). LciAtNow differs from LciAtToday »Page function in that LciAtToday retrieves only a date number.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtNow
(LCH_CONTEXT Context,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpResult Pointer to an lfloat10 in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lfloat10 Result;
. . .
Status = LciAtNow(Context,&Result);
Definition
Calculates the net present value of a series of future cash flow values discounted at a fixed, periodic interest rate.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtNPV
(LCH_CONTEXT Context,
lfloat10 Interest,
LCH_RANGE Range,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Interest The fixed interest rate applied to the cash flow values. Interest can be any value greater than -1.0.
Range A range object that contains the cash flow values.
lpResult Pointer to an lfloat10 in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Note LciAtNPV assumes that the cash flows occur at equal time intervals, that the first cash outflow occurs at the end of the first period, and that subsequent cash outflows occur at the end of subsequent periods.
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lfloat10 Result;
. . .
Status = LciRgConstructAddr(Context,"C1..C10",&Range);
Status = LciAtNPV(Context,.07,Range,&Result);
. . .
Status = LciRgDestroy(&Range);
Definition
Calculates the amount of the periodic payment needed to pay off a loan, given a specified periodic interest rate and number of payment periods. It assumes your calculations are for payments you make at the end of each payment period (an ordinary annuity).
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtPmt
(LCH_CONTEXT Context,
lfloat10 Principal,
lfloat10 Interest,
lfloat10 Term,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Principal Principal amount of loan; can be any value.
Interest The periodic interest rate applied to the loan. Interest can be any value greater than -1.0. Enter Interest in the same unit of time as Term. For instance, if you are calculating a monthly payment, enter the interest and term in monthly increments.
Term The number of payment periods for the loan. Term can be any value except 0.
lpResult Pointer to an lfloat10 in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lfloat10 Result;
. . .
Status = LciAtPmt(Context,50000,.1,30,&Result);
Definition
Converts the letters in the specified string to proper capitalization. It converts the first letter of each word to uppercase, leaving the remaining letters lowercase.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtProper
(LCH_CONTEXT Context,
lptr(lmbcs) SourceStr,
lushort BufLen,
lptr(lmbcs) lpResultStr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
SourceStr The string (where length is LCI_MAX_CELL_LEN or less) you want to convert.
BufLen The number of bytes available in the buffer pointed to by lpResultStr, including room for a trailing null byte.
lpResultStr Pointer to an lfloat10 in which to return the result string.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_OUT_OF_MEMORY »Page
Notes
If status is not LCS_SUCCESS, the string returned is null.
LCS_STR_TOO_LONG is returned if SourceStr is greater than LCI_MAX_CELL_LEN or if BufLen is smaller than lpResultstr. In the latter case, lpResultstr is truncated.
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lmbcs lpSource[LCI_MAX_CELL_LEN];
lmbcs lpResult[LCI_MAX_CELL_LEN];
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,LCI_MAX_CELL_LEN,lpSource);
Status = LciAtProper(Context,lpSource,LCI_MAX_CELL_LEN,lpResult)
. . .
Status = LciClDestroy(&Cell);
Definition
Calculates the present value of an investment based on a series of equal payments discounted at a periodic interest rate over a specified number of payment periods.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtPV
(LCH_CONTEXT Context,
lfloat10 Payment,
lfloat10 Interest,
lfloat10 Term,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Payment The amount of each payment made toward the investment. Payment can be any value.
Interest The periodic interest rate applied to the investment. Interest can be any value greater than -1.0.
Term The number of payment periods. Term can be any value.
lpResult Pointer to an lfloat10 in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Note LciAtPV assumes that your calculations use an investment that is an ordinary annuity (a payment at the end of a term). If you want to calculate the present value of an annuity due (a payment at the beginning of a term), use the following formula: PV(Payment, Interest, Term)/(1+Interest).
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lfloat10 Result;
. . .
Status = LciAtPV(Context,50000,.08,20,&Result);
Definition
Returns the periodic interest rate necessary for an investment to grow to a future value over the number of compounding periods specified.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtRate
(LCH_CONTEXT Context,
lfloat10 FutureVal,
lfloat10 PresentVal,
lfloat10 Term,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
FutureVal Future value of the investment; can be any value.
PresentVal Present value of the investment; can be any value except 0.0
Term The number of compounding periods for the investment; can be any value except 0.0.
lpResult Pointer to an lfloat10 in which to return the result.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lfloat10 Result;
. . .
Status = LciAtRate(Context,18000,10000,60,&Result);
Definition
Duplicates a string a specified number of times. LciAtRepeat retrieves strings that have a length up to the maximum integer represented by an lushort. If the length of the result string is larger than the maximum integer, the function truncates the result.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtRepeat
(LCH_CONTEXT Context,
lptr(lmbcs) SourceStr,
lushort DupCount,
lushort BufLen,
lptr(lmbcs) lpResultStr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
SourceStr Pointer to the string (where length is LCI_MAX-CELL_LEN bytes or less) you want to duplicate.
DupCount The number of times you want to duplicate SourceStr.
BufLen The number of bytes available in the buffer pointed to by lpResultStr, including room for a trailing null byte.
lpResultStr Pointer to a lmbcs string in which to return the result string.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_OUT_OF_MEMORY »Page
Note LCS_STR_TOO_LONG is returned if BufLen is too small; however, using Repeat is different from using the repeating label prefix \ (backslash). The repeating label prefix repeats a label only as many times as will fill the current cell. Repeat duplicates SourceStr as many times as you specify with DupCount, up to the maximum integer represented by an lushort; it is not limited to the current column width.
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lmbcs lpSource[ ] = "duplicate this";
lushort DupCount = 100;
lushort BufLen = 20000;
lmbcs lpResult[20000];
. . .
Status = LciAtRepeat(Context,lpSource,DupCount,BufLen,lpResult)
Definition
Replaces a specified number of characters in a string, beginning at a specified position, with a new string.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtReplace
(LCH_CONTEXT Context,
lptr(lmbcs) SourceStr,
lushort Start,
lushort CharCount,
lptr(lmbcs) NewStr,
lushort BufLen,