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,
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 or less) in which you want to replace characters. SourceStr 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 replacing characters in SourceStr. Numbering starts at 0.
CharCount Number of characters (positive integer or 0) you want to replace.
NewStr Pointer to the lmbcs string you want to use to replace the original characters.
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 LciAtReplace counts punctuation and spaces as characters. If you use LciAtReplace to append or insert strings, be sure to include the necessary spaces.
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lmbcs lpString[ ] = "My dog is black";
lmbcs lpNew[ ] = "brown";
lmbcs lpResult[LCI_MAX_CELL_LEN];
. . .
/* Replace "black" with "brown" in the string "My dog is black" */
Status = LciAtReplace(Context,lpString,10,StrLen(lpNew),
lpNew,LCI_MAX_CELL_LEN,lpResult)
Definition
Retrieves the specified number of characters starting at the end of a string.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtRight
(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 Pointer to the string (LCI_MAX_CELL_LEN) whose last CharCount characters you want to retrieve. SourceStr can be a literal string, a reference to a cell that contains a label, or a formula that evaluates to a string.
CharCount Number of characters you want to retrieve (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
Note LciAtRight counts punctuation and spaces as characters. If CharCount is 0, lpResultStr is an empty string. If CharCount is larger than the length of SourceStr, LciAtRight returns the entire SourceStr string.
Example
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
/* Return the string "black" from the string "My dog is black". */
. . .
LCT_STATUS Status;
lmbcs lpString[LCI_MAX_CELL_LEN] = "My dog is black";
lmbcs lpResult[LCI_MAX_CELL_LEN];
. . .
Status = LciAtRight(Context,lpString,5,LCI_MAX_CELL_LEN,lpResult);
Definition
Rounds the specified value to the specified number of places.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtRound
(LCH_CONTEXT Context,
lfloat10 Num,
lushort Places,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Num Value you want to round.
Places The value between -100 and 100, inclusive, that is the number of places to which you want to round Num. If Places is positive, Round rounds Num to the specified number of places to the right of the decimal point. For instance, if Places is 2, Round rounds Num to the nearest hundredth. If Places is negative, Round rounds Num to the positive Places power of 10. For instance, if Places is -2, Round rounds Num to the nearest hundred. If Places is 0, Round rounds Num to the nearest integer.
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 When you round a value using LciAtRound, your add-in uses the rounded value in calculations. If you want to display values with a specific number of places, but you want 1-2-3 to calculate those values to their full precision, use LciClSetFormat or LciRgSetFormat to set the cell format to FIXED (LCI_FORMAT_FIXED).
Example
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
/* Round 2.346 to 2.35. */
LCT_STATUS Status;
lfloat8 Num = 2.346;
lfloat10 Number,Rounded;
lushort Numtype;
. . .
Status = LciMtPushFloat8(Context,Num);
Status = LciMtPopFloat10(Context,&Number,&NumType);
Status = LciAtRound(Context,Number,2,&Rounded);
Definition
Obtains the seconds, a value between 0 and 59, from the specified time number.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtSecond
(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 (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
/* Get the seconds for 11:59:59 PM. */
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat8 Num = .999988;
lfloat10 Number;
lushort Seconds;
. . .
Status = LciMtPushFloat8(Context,Num);
Status = LciMtPopFloat10(Context,&Number,&NumType);
Status = LciAtSecond(Context,Number,&Seconds);
Definition
Calculates the straight-line depreciation allowance of an asset for one period.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtSLn
(LCH_CONTEXT Context,
lfloat10 Cost,
lfloat10 Salvage,
lfloat10 Life,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Cost Cost of the asset; can be any value.
Salvage The estimated value of the asset at the end of its life; can be any value.
Life The number of periods it takes to depreciate the asset to its salvage value; 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
/* Calculate straight-line depreciation for an item that
cost $1000 (over 60 months) that will be worth $100 after
60 months. */
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat8 Cost8 = 1000;
lfloat8 Salvage8 = 100;
lfloat8 Life8 = 60;
lfloat10 Cost;
lfloat10 Salvage;
lfloat10 Life;
lfloat10 SLineDep;
lushort NumType;
. . .
Status = LciMtPushFloat8(Context,Cost8);
Status = LciMtPopFloat10(Context,&Cost,&NumType);
Status = LciMtPushFloat8(Context,Salvage8);
Status = LciMtPopFloat10(Context,&Salvage,&NumType);
Status = LciMtPushFloat8(Context,Life8);
Status = LciMtPopFloat10(Context,&Life,&NumType);
. . .
Status = LciAtSLn(Context,Cost,Salvage,Life,&SLineDep);
Definition
Calculates the population standard deviation in a range of values. Standard deviation is a measure of the extent to which individual values in a range vary from the mean (average) of all values in the range. The lower the standard deviation, the less individual values vary from the mean, and the more reliable the mean. A standard deviation of 0 indicates that all values in the range are equal.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtStD
(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 that contains the values you want in order to calculate the population standard deviation.
lprResult 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
/* Calculate the standard deviation of the numbers in
A:A1..A:A100. */
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
LCH_RANGE Range;
lfloat10 StdDevPop;
. . .
if (LciRgConstructAddr(Context,"A:A1..A:A100",Range) ==
LCS_SUCCESS {
Status = LciAtStD(Context,Range,&StdDevPop);
. . .
Status = LciRgDestroy(&Range);
}
Definition
Calculates the sample standard deviation in a range of values. Standard deviation is a measure of the extent to which individual values in a range vary from the mean (average) of all values in the range. The lower the standard deviation, the less individual values vary from the mean, and the more reliable the mean. A standard deviation of 0 indicates that all values in the range are equal.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtStDS
(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 that contains the values for which you want to calculate the sample standard deviation.
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
/* Calculate the standard deviation of the number sample in
A:A1..A:A100. */
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lfloat10 StdDevSmp;
. . .
if (LciRgConstructAddr(Context,"A:A1..A:A100",&Range) ==
LCS_SUCCESS {
Status = LciAtStDS(Context,Rg,&StdDevSmp);
. . .
Status = LciRgDestroy(&Range);
}
Definition
Converts a number into a string with a specified number of decimal places.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtString
(LCH_CONTEXT Context,
lfloat10 Num,
lushort Places,
lushort BufLen,
lptr(lmbcs) lpResultStr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Num Value you want to convert.
Places Number of decimal places you want to appear in the string. Places is an integer between 0 and 15, inclusive.
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 LciAtString ignores any formatting characters in Num. For instance, if cell A10 contains the formatted value $100.45, LciAtString converts the value to "100.45".
Example
/* Convert the number 1.2345 to the string "1.23" */
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat8 Num8 = 1.2345;
lfloat10 Num;
lmbcs lpString[LCI_MAX_CELL_LEN];
lushort NumType;
. . .
Status = LciMtPushFloat8(Context,Num8);
Status = LciMtPopFloat10(Context,&Num,&NumType);
Status = LciAtString(Context,Num,2,LCI_MAX_CELL_LEN,lpString);
Definition
Adds the values in a range of numbers or numeric formulas.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtSum
(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 that contains the values you want to sum.
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
/* Sum the numbers in A:A1..A:A100. */
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lfloat10 Sum;
. . .
if (LciRgConstructAddr(Context,"A:A1..A:A100",&Range) ==
LCS_SUCCESS {
Status = LciAtSum(Context,Range,&Sum);
. . .
Status = LciRgDestroy(&Range);
}
Definition
Calculates the sum-of-the-years-digits depreciation allowance of an asset for a specified period.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtSYD
(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 Cost of the asset; can be any value.
Salvage The value of the asset at the end of its life; can be any value.
Life The number of periods (typically years) it takes to depreciate the asset to its salvage value; can be any value greater than or equal to 1.0.
Period The time period for which you want to find the depreciation allowance; 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
Example
/* Calculate sum-of-the-years depreciation for an item that
cost $1000 (over 60 months) that will be worth $100 after
60 months at period 30. */
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat8 Cost8 = 1000;
lfloat8 Salvage8 = 100;
lfloat8 Life8 = 60;
lfloat8 Period8 = 30;
lfloat10 Cost;
lfloat10 Salvage;
lfloat10 Life;
lfloat10 Period;
lfloat10 Dep;
lushort NumType;
. . .
Status = LciMtPushFloat8(Context,Cost8);
Status = LciMtPopFloat10(Context,&Cost,&NumType);
Status = LciMtPushFloat8(Context,Salvage8);
Status = LciMtPopFloat10(Context,&Salvage,&NumType);
Status = LciMtPushFloat8(Context,Life8);
Status = LciMtPopFloat10(Context,&Life,&NumType);
Status = LciMtPushFloat8(Context,Period8);
Status = LciMtPopFloat10(Context,&Period8,&NumType);
Status = LciAtSYD(Context,Cost,Salvage,Life,Period,&Dep);
Definition
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.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtTerm
(LCH_CONTEXT Context,
lfloat10 Payment,
lfloat10 Interest,
lfloat10 FutureVal,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Payment The value of the equal contributions to the investment used in the calculation; can be any value except 0.0.
Interest The periodic interest rate applied to the investment; can be any value greater than -1.0.
FutureVal The future value (the amount you want to accumulate) of the investment. FutureVal can be any value. If you use a negative value for FutureVal, you can calculate the term necessary to pay back a loan.
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 LciAtTerm assumes you are using an ordinary annuity (payment at the end of a term). To calculate the term of an annuity due (payment at the beginning of a term), use the following formula: Term(Payment,Interest,FutureVal)/(1+Interest).
Example
/* Calculate the number of months needed for a future value
of $100,000 with a $10 monthly payment and a monthly
rate of 2%. */
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat8 Payment8 = 10;
lfloat8 Interest8 = 1.02;
lfloat8 Future8 = 100000;
lfloat10 Periods,Payment,Interest,Future;
lushort NumType;
. . .
Status = LciMtPushFloat8(Context,Payment8);
Status = LciMtPopFloat10(Context,&Payment,&NumType);
Status = LciMtPushFloat8(Context,Interest8);
Status = LciMtPopFloat10(Context,&Interest,&NumType);
Status = LciMtPushFloat8(Context,Future8);
Status = LciMtPopFloat10(Context,&Future,&NumType);
Status = LciAtTerm(Context,Payment,Interest,Future,&Periods);
Definition
Calculates the time number for the specifed hour, minutes, and seconds.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtTime
(LCH_CONTEXT Context,
lfloat10 Hour,
lfloat10 Minute,
lfloat10 Second,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Hour Number (from 0.0 (midnight) to 23.0 (11:00 p.m.)) that corresponds to the hour.
Minute Number (from 0.0 to 59.0) that corresponds to the minutes.
Second Number (from 0.0 to 59.0) that corresponds to the seconds.
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
/* Get the time number for 2:43:20 PM. */
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Hour,Minute,Second,Time;
lushort NumType;
. . .
Status = LciMtPushFloat8(Context,14);
Status = LciMtPopFloat10(Context,&Hour,&NumType);
Status = LciMtPushFloat8(Context,43);
Status = LciMtPopFloat10(Context,&Minute,&NumType);
Status = LciMtPushFloat8(Context,20);
Status = LciMtPopFloat10(Context,&Second,&NumType);
Status = LciAtTime(Context,Hour,Minute,Second,&Time);
Definition
Calculates the time number for the specified time.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtTimeValue
(LCH_CONTEXT Context,
lptr(lmbcs) Time,
lptr(lfloat10) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Time String in one of the 1-2-3 time formats: HH:MM:SS (AMPM), HH:MM (AMPM), Long Intn'l (24 hour), Short Intn'l (24 hour).
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
/* Get the time value string for 2:43:20 PM. */
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lfloat10 Time;
lushort NumType;
. . .
Status = LciAtTimeValue(Context,&Time,"14:43:20");
Definition
Retrieves the date number that corresponds to the current date. LciAtToday differs from the LciAtNow »Page function in that LciAtNow retrieves both a date number and a time number.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtToday
(LCH_CONTEXT Context,
lptr(lulong) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpResult Pointer to an lulong 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
/* Get the day number for today's date. */
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lulong Day;
. . .
Status = LciAtToday(Context,&Day);
Definition
Converts all the letters in the specified string to uppercase.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtUpper
(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 (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 null-terminating 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
Example
/* Change "upper" to "UPPER". /
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lmbcs lpLower[ ] = "upper";
lmbcs lpOutStr[LCI_MAX_CELL_LEN];
. . .
Status = LciAtUpper(Context,lpLower,LCI_MAX_CELL_LEN,lpOutStr);
Definition
Converts a number entered as a string to its corresponding numeric value.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtValue
(LCH_CONTEXT Context,
lptr(lmbcs) SourceStr,
lptr(lfloat10) lpResult)
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 or less) you want to convert. The string must contain only numbers or numeric symbols. It can appear as a standard number (456.7), a number in scientific notation (4.567E2), a mixed number (45 78), or a formatted number ($45.75).
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 SourceStr contains spaces that separate symbols from the numbers (such as $ 45.75), or SourceStr contains non-numeric characters, LciAtValue returns LCS_ERR. If SourceStr is empty, LciAtValue returns 0.0.
Example
/* Convert "1.234" to the number 1.234. */
#include "lcicomn.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lfloat10 Num;
. . .
Status = LciAtValue(Context,"1.234",&Num);
Definition
Calculates the population variance in a range of values. Variance is a measure of the extent to which individual values in a range vary from the mean (average) of all the values in the range. The lower the variance, the less individual values vary from the mean, and the more reliable the mean. A variance of 0 indicates that all values in the range are equal.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtVar
(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
/* Calculate the variance of the numbers in A:A1..A:A100. */
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lfloat10 VarPop;
.. . .
if (LciRgConstructAddr(Context,"A:A1..A:A100",&Range) ==
LCS_SUCCESS {
Status = LciAtVar(Context,Range,&VarPop);
. . .
Status = LciRgDestroy(&Range);
}
Definition
Calculates the sample variance in a range of values. Variance is a measure of the extent to which individual values in a range vary from the mean (average) of all the values in the range. The lower the variance, the less individual values vary from the mean, and the more reliable the mean. A variance of 0 indicates that all values in the range are equal.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtVarS
(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
/* Calculate the variance of the number sample in A:A1..A:A100. */
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lfloat10 VarSmp;
. . .
if (LciRgConstructAddr(Context,"A:A1..A:A100",&Range) ==
LCS_SUCCESS) {
Status = LciAtVarS(Context,Range,&VarSmp);
. . .
Status = LciRgDestroy(&Range);
}
Definition
Calculates the depreciation allowance of an asset for a specified period of time, using the declining-balance method. One version of this function, LciAtVDB, uses the double-declining balance method. Another version, LciAtVDBDepr, includes a depreciation factor argument that allows the percentage of straight-line depreciation to vary so that you can calculate a depreciation other than double-declining balance. Yet another version, LciAtVDBDeprType, includes an argument that allows you to switch the depreciation method to straight-line when the straight-line calculation is greater than the declining-balance calculation.
Format
* Double-declining balance method *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtVDB
(LCH_CONTEXT Context,
lfloat10 Cost,
lfloat10 Salvage,
lfloat10 Life,
lfloat10 Start,
lfloat10 End,
lptr(lfloat10) lpResult)
* Specify depreciation percentage *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtVDBDepr
(LCH_CONTEXT Context,
lfloat10 Cost,
lfloat10 Salvage,
lfloat10 Life,
lfloat10 Start,
lfloat10 End,
lfloat10 Depreciation,
lptr(lfloat10) lpResult)
* Specify depreciation percentage and method *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtVDBDeprType
(LCH_CONTEXT Context,
lfloat10 Cost,
lfloat10 Salvage,
lfloat10 Life,
lfloat10 Start,
lfloat10 End,
lfloat10 Depreciation,
lushort VDBType,
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; can be any value greater than Salvage.
Salvage The value of the asset at the end of its life; can be any value.
Life The number of periods it will take to depreciate the asset to its salvage value; can be any value greater than 0.0.
Start The point in the asset life when you want to begin calculating depreciation. Start can be any value greater than or equal to 0.0, but cannot be greater than Life.
End The point in the asset life when you want to stop calculating depreciation. End can be any value greater than Start. Start and End correspond to the asset's life relative to the fiscal period.
lpResult Pointer to an lfloat10 in which to return the result.
Depreciation The percentage of straight-line depreciation you want to use as the depreciation rate. Depreciation can be any value greater than or equal to 0.0.
VDBType Value that specifies the depreciation method you want to use. The VDBType argument specifies the depreciation method. It can have one of the following values:
Constant Meaning
LCI_VDB_SWITCH_TO_SLINE Switches to straight-line depreciation when the straight-line calculation is greater than the declining-balance calculation.
LCI_VDB_NO_SWITCH_TO_SLINE Does not switch to straight-line depreciation.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Notes If you use LciAtVDB, lpResult will be the same as if you had used DDB (described above) because LciAtVDB uses 200% as a default depreciation value, which is double-declining balance depreciation.
The double-declining balance method (so named because the depreciation rate is 200% of the straight-line rate) accelerates the rate of depreciation, so that more depreciation expense occurs (and can be written off) in earlier periods than in later ones. However, when an asset has a small salvage value, declining-balance depreciation is usually less than straight-line depreciation in the last periods of the asset's life.
Example
/* Calculate the first year depreciation allowance for a
$10,000 investment that will be worth $600 in 10 years,
assuming tax laws limit you to 150% depreciation of the
declining balance and that you made the investment in the
middle of the first quarter. Enable switch to straight line. */
. . .
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat8 Cost8 = 10000;
lfloat8 Salvage8 = 600;
lfloat8 Life8 = 10;
lfloat8 DepFact8 = 1.5;
lfloat10 Cost;
lfloat10 Salvage;
lfloat10 Life;
lfloat10 Period;
lfloat8 DepFact;
lfloat10 Dep;
lushort Numtype;
. . .
Status = LciMtPushFloat8(Context,Cost8);
Status = LciMtPopFloat10(Context,&Cost,&NumType);
Status = LciMtPushFloat8(Context,Salvage8);
Status = LciMtPopFloat10(Context,&Salvage,&NumType);
Status = LciMtPushFloat8(Context,Life8);
Status = LciMtPopFloat10(Context,&Life,&NumType);
Status = LciMtPushFloat8(Context,DepFact8);
Status = LciMtPopFloat10(Context,&DepFact,&NumType);
Status = LciMtPushZero(Context);
Status = LciMtPopFloat10(Context,&Period,&NumType);
Status = LciAtVDBDeprType(Context,Cost,Salvage,Life,Period,
DepFact,&Dep);
Definition
Retrieves the contents of the cell in a specified column of a vertical look-up table. The function compares a specified value (a number or a string) to each cell in the first column of a range. When it locates the value in the first column, it moves across that row by a specified number of columns to the cell from which it retrieves the contents.
You can also use LciAtVLookup to locate a label in the first column of a specified range.
Format
* Float lookup, float Result *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtVLookupNumToNum
(LCH_CONTEXT Context,
lfloat10 LookupVal,
LCH_RANGE Range,
lushort ColOffset,
lptr(lfloat10) lpResult)
* Float lookup, string Result *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtVLookupNumToStr
(LCH_CONTEXT Context,
lfloat10 LookupVal,
LCH_RANGE Range,
lushort ColOffset,
lushort BufLen,
lptr(lmbcs) lpResultStr)
* String lookup, float Result *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtVLookupStrToNum
(LCH_CONTEXT Context,
lptr(lmbcs) LookupVal,
LCH_RANGE Range,
lushort ColOffset,
lptr(lfloat10) lpResult)
* String lookup, string Result *
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtVLookupStrToStr
(LCH_CONTEXT Context,
lptr(lmbcs) LookupVal,
LCH_RANGE Range,
lushort ColOffset,
lushort BufLen,
lptr(lmbcs) lpResultStr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
LookupVal Number the function locates in the first column of the range.
Range Range object on which LciAtVLookup works.
ColOffset The number of columns across from LookupVal the function goes to locate the cell whose contents you want to obtain.
lpResult Pointer to an lfloat10 in which the float result is to be stored.
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_INVALID_RANGE »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_OUT_OF_MEMORY »Page
Example
/* Do various look-ups using columns of strings and numbers. */
#include "lcicomn.h"
#include "lciatfnc.h"
#include "lcimath.h"
#include "lcirange.h"
. . .
LCT_STATUS Status;
LCH_RANGE StrRg,NumRg;
lfloat10 Num,FoundNum;
lushort NumType;
. . .
/* Create a string of number look-up ranges. */
if (LciRgConstructAddr(Context,"A:A1..A:A100",&NumRg) !=
LCS_SUCCESS)
Return;
if (LciRgConstructAddr(Context,"A:A1..A:A100",&StrRg) !=
LCS_SUCCESS)
Return;
/*Find a number one column right in a row based on a column
look-up for 0. */
Status = LciMtPushZero(Context);
Status = LciMtPopFloat10(Context,&Num,&NumType);
Status = LciAtVLookupNumToNum(Context,Num,NumRg,&FoundNum);
/*Find a string two column right in a row based on a column
look-up for 0. */
Status = LciMtPushZero(Context);
Status = LciMtPopFloat10(Context,&Num,&NumType);
Status = LciAtVLookupNumToStr(Context,Num,NumRg,
LCI_MAX_CELL_LEN,FoundStr);
/* Find a number one column right in a row based on a
column look-up for "A". */
Status = LciAtVLookUpStrToNum(Context,"A",StrRg,&FoundNum);
/* Find a string two columns right in a row based on a
column look-up for "A". */
Status = LciAtVLookupStrToStr(Context,"A",StrRg,
LCI_MAX_CELL_LEN,FoundStr);
. . .
Status = LciRgDestroy(StrRg);
Status = LciRgDestroy(NumRg);
Definition
Obtains the year, a number from 0 (1900) to 199 (2099), inclusive, from the specified date number.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAtYear
(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 (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;
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 = LciAtYear(Context,lfDateNum,&Result);
You use the Cell functions to represent 1-2-3 worksheet cells in your add-in. A data object that has type Cell refers to a specific 1-2-3 cell.
Function Meaning
LciClConstructAddr »Page Cell constructor specified by an address string.
LciClConstructCoords »Page Cell constructor specified by filename and coordinates.
LciClConstructCurr »Page Cell constructor corresponding to the current cell pointer location.
LciClCopy »Page Copy command for a single-cell range.
LciClDestroy »Page Releases a cell object.
LciClErase »Page Erases the contents of a cell.
LciClFormatRow »Page Retrieves a string that is a concatenation of the strings 1-2-3 displays in a row of cells.
LciClGetAddr »Page Retrieves the fully qualified address string of a cell.
LciClGetBoldFlag »Page Retrieves the status of the bold attribute for a cell.
LciClGetBorderColor »Page Gets the current border colors.
LciClGetBorders »Page Retrieves the current linetypes for the cell.
LciClGetCol »Page Retrieves the current one-based column number of a cell.
LciClGetColor »Page Retrieves the current color used in the cell.
LciClGetColorNegFlag »Page Retrieves a value that indicates if 1-2-3 displays a negative cell value in color.
LciClGetColWidth »Page Retrieves the width of the column that contains the specified cell.
LciClGetContentsNum »Page Retrieves the contents of a cell as a number.
LciClGetContentsStr »Page Retrieves the literal contents of a cell (always in string format).
LciClGetContentsType »Page Retrieves the type of the literal contents of a cell (number, label, formula, blank, @ERR, or @NA).
LciClGetContext »Page Retrieves the context handle that corresponds to the cell object.
LciClGetCoords »Page Retrieves the sheet, column, and row numbers of a cell.
LciClGetFileName »Page Retrieves the fully qualified pathname of the workfile that contains a specified cell.
LciClGetFont »Page Retrieves the current font size and typeface for the cell entry.
LciClGetFont2 »Page Retrieves the font of the cell contained in LCH_CELL, returns the name, height in points, alignment, attributes, font family, charset and type of underlining to use.
LciClGetFormat »Page Retrieves the format and precision of the cell value.
LciClGetItalicFlag »Page Retrieves a value that indicates if 1-2-3 displays the cell entry in italic font.
LciClGetLabelType »Page Retrieves the format used to display labels in a cell.
LciClGetParenFlag »Page Retrieves a value that indicates if 1-2-3 displays a negative value in parentheses.
LciClGetPattern »Page Retrieves the current shading attribute.
LciClGetProtectFlag »Page Retrieves the current protection status of a cell.
LciClGetRow »Page Retrieves the current one-based row number of a cell.
LciClGetRowHeight »Page Retrieves the current row height (in points).
LciClGetShadowFlag »Page Retrieves a value that indicates if the current cell has a drop shadow.
LciClGetSheet »Page Retrieves the current one-based sheet number of a cell.
LciClGetUnderline »Page Retrieves a value that indicates whether or not the cell is underlined.
LciClGetValidFlag »Page Retrieves a value that indicates whether or not the cell is still valid.
LciClGetValNum »Page Retrieves the cell value as a number if it is a number.
LciClGetValStr »Page Retrieves the current cell value if the value is not a number.
LciClGetValType »Page Retrieves the type of the current value in a specified cell.
LciClMove »Page Transfers the contents and format of one cell to another cell.
LciClNextSheet »Page Changes specified cell's sheet coordinate to the next sheet in the specified workfile.
LciClPrevSheet »Page Changes specified cell's sheet coordinate to the previous sheet in the specified workfile.
LciClRunMacro »Page Executes the macro stored in the specified cell.
LciClSetBoldFlag »Page Bolds or removes bold from the cell.
LciClSetBorderColor »Page Sets the current font attribute for a cell.
LciClSetBorders »Page Sets the borders for the cell.
LciClSetCol »Page Sets the one-based column number of a cell.
LciClSetColor »Page Sets the color used in the cell.
LciClSetColorNegFlag »Page Sets whether 1-2-3 displays a negative cell value in a contrasting color.
LciClSetColWidth »Page Sets the width of the column that contains the specified cell.
LciClSetContentsNum »Page Sets the contents of a cell to a number.
LciClSetContentsStr »Page Sets the contents of a cell as a literal string.
LciClSetCoords »Page Sets the sheet, column, and row numbers of a cell.
LciClSetFileName »Page Sets the pathname of the file that contains the specified cell.
LciClSetFont »Page Sets the font size and typeface for the cell.
LciClSetFont2 »Page Sets the current font attribute for a cell.
LciClSetFormat »Page Sets the format and precision by which the cell value is displayed.
LciClSetItalicFlag »Page Italicizes or removes italics from the cell.
LciClSetLabelType »Page Sets the format used to display labels in a cell.
LciClSetParenFlag »Page Determines if 1-2-3 displays a negative value in parentheses.
LciClSetPattern »Page Sets the current shading attribute.
LciClSetProtectFlag »Page Sets protection on or off for a cell.
LciClSetRow »Page Sets the one-based row number of a cell.
LciClSetRowHeight »Page Sets the current row height (in points).
LciClSetShadowFlag »Page Sets whether or not the specified cell has a drop shadow.
LciClSetSheet »Page Sets the one-based sheet number of a cell.
LciClSetUnderline »Page Underlines (or removes underline from) the cell.
LcxClGetAttributeFlags »Page Returns the attributes of a cell as a structured bitmap for 1-2-3 for Windows, Release 1.0.
LcxClGetAttributeFlags2 »Page Returns the attributes of a cell as a structured bitmap for 1-2-3 Release 4.0 for Windows.
LcxClSetAttributeFlags »Page Sets the attributes of a cell as a structured bitmap for 1-2-3 Release for Windows, Release 1.0.
LcxClSetAttributeFlags2 »Page Sets the attributes of a cell as a structured bitmap for 1-2-3 Release 4.0 for Windows.
Definition
Constructs a cell object handle using an address string.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClConstructAddr
(LCH_CONTEXT Context,
lptr(lmbcs) lpCellAddr,
lptr(LCH_CELL) lpCellhandle)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpCellAddr Pointer to a lmbcs string that contains the address string of a cell, for example <<MYFILE>>D:B5.
lpCellhandle A pointer to storage in which to return the cell object handle.
Returns
LCS_SUCCESS »Page
LCS_INVALID_ADDRESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
/* Construct a cell at C3 in the current sheet and workfile. */
Status = LciClConstructAddr(Context, "C3",&Cell);
. . .
Status = LciClDestroy(&Cell);
Definition
Constructs a cell object specified by a workfile name, sheet, row, and column number.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClConstructCoords
(LCH_CONTEXT Context,
lptr(lmbcs) lpWorkfileName,
lushort SheetNum,
lushort ColumnNum,
lushort RowNum,
lptr(LCH_CELL) lpCell)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpWorkfileName A pointer to a lmbcs string that contains the name of an open workfile. It can also be LCI_UNTITLED_WORKFILE to specify the no-name workfile or LCI_CURRENT_WORKFILE to specify the current workfile.
SheetNum A one-based number specifying a worksheet within the workfile. It can be LCI_CURRENT_SHEET to specify the current sheet.
ColNum, One-based number specifying a column within the worksheet.
RowNum One-based number specifying a row within the worksheet.
lpCell A pointer to storage to which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_INVALID_COL »Page
LCS_INVALID_ROW »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_FILENAME »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
/* Construct a cell in the untitled workfile at C:G2. */
Status = LciClConstructCoords(Context,LCI_UNTITLED_WORKFILE,
3,7,2,&Cell);
. . .
Status = LciClDestroy(&Cell);
Definition
Construct a cell object corresponding to the current location of the cell pointer.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClConstructCurr
(LCH_CONTEXT Context,
lptr(LCH_CELL) lpCell)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpCell A pointer to storage in which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
. . .
Status = LciClDestroy(&Cell);
Definition
Copies the contents and all attributes except borders and shadow from one cell to another.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClCopy
(LCH_CELL CellFrom,
LCH_CELL CellTo)
Arguments
CellFrom The handle of a cell object from which to copy.
CellTo The handle of a cell object to which to copy.
Returns
LCS_SUCCESS »Page
LCS_INVALID_FROM_CELL »Page
LCS_INVALID_TO_CELL »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
...
LCH_CELL SourceCell;
LCH_CELL TargetCell;
LCT_STATUS Status;
...
/* SOURCE= Current file, current sheet at C2 */
Status = LciClConstructCoords
(Context, LCI_CURRENT_WORKFILE, LCI_CURRENT_SHEET,
3, 2, &SourceCell);
Status = LciClConstructCurr(Context, &TargetCell);
Status = LciClCopy(SourceCell, TargetCell);
...
Status = LciClDestroy(&SourceCell);
Status = LciClDestroy(&TargetCell);
Definition
Releases a cell object handle and frees all associated memory.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClDestroy
(lptr(LCH_CELL) lpCell)
Argument
lpCell A pointer to a cell object handle, which this call sets to NULL.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the contents of a cell to blank. It does not, in any way, affect the object instance.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClErase
(LCH_CELL Cell)
Argument
Cell The handle of an existing cell object.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClErase(Cell);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves a string that consists of a concatenation of the strings 1-2-3 displays in a row of cells. The string will contain the data exactly as it would appear to the spreadsheet user.
Note This function is based on the use of a fixed pitch font to determine the width of the strings.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClFormatRow
(LCH_CELL Cell,
lushort ColCount,
lushort PaneNum,
lushort BufLen,
lptr(lmbcs) lpResult)
Arguments
Cell The handle of a cell object in the desired row.
ColCount The number of columns to include in the formatted row string, starting with the specified cell.
PaneNum The one-based number of a pane within each window, or LCI_CURRENT_PANE to specify the current pane. One (1) refers to the top, left, or only pane.
BufLen The number of bytes available in the buffer pointed to by lpResult, including room for a null-terminating byte (maximum of LCI_MAX_FMTROW_LEN).
lpResult A pointer to a lmbcs string in which to return the resulting concatenated row string.
Returns
LCS_SUCCESS »Page
LCS_HIDDEN_COL »Page
LCS_INVALID_CELL »Page
LCS_INVALID_NUM »Page
LCS_INVALID_PANE »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lmbcs str[LCI_MAX_FMTROW_LEN];
. . .
/* Get the string displayed from the current
cell for 3 columns. */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClFormatRow(Cell,3,LCI_CURRENT_PANE,
LCI_MAX_FMTROW_LEN,str);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the fully qualified address string of a cell in a form that can be passed to LciClConstructAddr »Page , that is, an address of the form "<<filename.ext>>A:A1".
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetAddr
(LCH_CELL Cell,
lushort BufLen,
lptr(lmbcs) lpAddr)
Arguments
Cell The handle of an existing cell object.
BufLen The number of bytes available in the buffer pointed to by lpAddr, including room for a null-terminating byte. (maximum of LCI_MAX_ADDR_LEN)
lpAddr A pointer to storage to which to return the address string.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lmbcs addr[LCI_MAX_ADDR_LEN];
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetAddr(Cell,3,addr);
Status = LciClDestroy(&Cell);
Definition
Retrieves the current bold attribute setting for a cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetBoldFlag
(LCH_CELL Cell,
lptr(lbool) lpBold)
Arguments
Cell The handle of an existing cell object.
lpBold A pointer to storage to which to return the bold attribute setting for the cell (LTRUE if bold is on, LFALSE if bold is off).
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_INVALID_CELL »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lbool BoldFlag;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetBoldFlag(Cell,&BoldFlag);
. . .
Status = LciClDestroy(&Cell);
Definition
Gets the current border colors.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetBorderColor
(LCH_CELL Cell,
lptr(lushort) lpTopLine,
lptr(lushort) lpBottomLine,
lptr(lushort) lpLeftLine,
lptr(lushort) lpRightLine)
Arguments
Cell The handle of an existing cell object.
lpTopLine Pointer to an lushort which will be set to the possible line type values.
lpBottomLine Pointer to an lushort which will be set to the possible line type values.
lpLeftLine Pointer to an lushort which will be set to the possible line type values.
lpRightLine Pointer to an lushort which will be set to the possible line type values.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort Top, Bottom, Left, Right;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetBorderColor(Cell, &Top, &Bottom, &Left, &Right);
. . .
Status = LciClDestroy(&Cell);
Definition
Gets the current border linetypes for a cell. The line type for each area (left, right, top, bottom) will be returned.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetBorders
(LCH_CELL Cell,
lptr(lushort) lpTopLine,
lptr(lushort) lpBottomLine,
lptr(lushort) lpLeftLine,
lptr(lushort) lpRightLine)
Arguments
Cell The handle of an existing cell object.
lpTopLine, Pointer to an lushort in which the line type of the top line is returned.
lpBottomLine, Pointer to an lushort in which the line type of the bottom line is returned.
lpLeftLine, Pointer to an lushort in which the line type of the left line is returned.
lpRightLine Pointer to an lushort in which the line type of the right line is returned.
Possible linetype values are:
LCI_LINE_TYPE_NONE
LCI_LINE_TYPE_SINGLE
LCI_LINE_TYPE_DOUBLE
LCI_LINE_TYPE_WIDE
LCI_LINE_TYPE_NARROWDOT
LCI_LINE_TYPE_DOT
LCI_LINE_TYPE_DASH
LCI_LINE_TYPE_DOTDASH
LCI_LINE_TYPE_DASHDOTDOT
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort Topline,Bottomline,Leftline,Rightline;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetBorders(Cell,&Topline,&Bottomline,&Leftline,
&Rightline);
. . .
Status = LciClDestroy(&Cell);
Definition
Returns the one-based column number of a cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetCol
(LCH_CELL Cell,
lptr(lushort) lpColNum)
Arguments
Cell The handle of an existing cell object.
lpColNum A pointer to an lushort in which to return the column number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort ColNum;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetCol(Cell,&ColNum);
. . .
Status = LciClDestroy(&Cell);
Definition
Gets the cell foreground or background color. The color is in the form of an index from 0 to 255 into the current Windows color palette.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetColor
(LCH_CELL Cell,
lushort Area,
lptr(lushort) lpColor)
Arguments
Cell The handle of an existing cell object.
Area The area type. Valid areas are:
LCI_COLOR_TYPE_BG Background area
LCI_COLOR_TYPE_FG Foreground area
lpColor A pointer to an lushort in which to return the color. The lpColor values correspond to those set in Window Display Options Palette, can be 0 to 255 or one of the following predifined constants:
LCI_COLOR_1
LCI_COLOR_2
LCI_COLOR_3
LCI_COLOR_4
LCI_COLOR_5
LCI_COLOR_6
LCI_COLOR_7
LCI_COLOR_8
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_INVALID_INDEX »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort Color;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetColor(Cell,LCI_COLOR_TYPE_FG,&Color);
Status = LciClDestroy(&Cell);
Definition
Returns a flag associated with the cell that is LTRUE if negative cell values are displayed in a contrasting color or intensity.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetColorNegFlag
(LCH_CELL Cell,
lptr(lbool) lpColorNegFlag)
Arguments
Cell The handle of an existing cell object.
lpColorNegFlag A pointer to an lbool in which to return the flag. The result is LTRUE if negative values are displayed in a contrasting color; LFALSE otherwise.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lbool NegFlag;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetColorNegFlag(Cell,&NegFlag);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the width of the column containing a cell as viewed by a specified pane in all windows. Column width is specified in number of characters and ranges from LCI_MIN_COL_WIDTH to LCI_MAX_COL_WIDTH.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetColWidth
(LCH_CELL Cell,
lushort PaneNum,
lptr(lushort) lpColWidth)
Arguments
Cell The handle of an existing cell object.
PaneNum The one-based number of a pane within each window, or LCI_CURRENT_PANE to specify the current pane. One (1) refers to the top, left, or only pane.
lpColWidth A pointer to an lushort in which to return the column width.
Returns
LCS_SUCCESS »Page
LCS_HIDDEN_COL »Page
LCS_INVALID_CELL »Page
LCS_INVALID_PANE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort ColWidth;
lushort PaneNum;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetColWidth(Cell,PaneNum,&ColWidth);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the numeric contents of a cell, that is. the number the user typed into the cell and that 1-2-3 displays in the control panel when the user is editing the cell. If the cell is blank, the value retrieved is zero. If the contents of the cell is not a number or blank, the error code LCS_NOT_NUM is returned. Call LciClGetContentsType »Page to determine if the contents of the cell is a number.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetContentsNum
(LCH_CELL Cell,
lptr(lfloat10) lpContentsNum)
Arguments
Cell The handle of an existing cell object.
lpContentsNum A pointer to an lfloat10 in which to return the numeric contents.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_CELL »Page
LCS_NA »Page
LCS_NOT_NUM »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lfloat10 ContentsNum;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsNum(Cell,&ContentsNum);
if (Status == LCS_NOT_NUM)
{
/* Get contents as strings.*/
}
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the literal contents of a cell, that is, what the user typed into the cell and what 1-2-3 displays in the control panel when the user is editing the cell. If the contents of the cell is a number, the number is converted to a string. To get a numeric cell contents without conversion to string, call LciClGetContentsNum »Page . Call LciClGetContentsType »Page to determine if the contents of the cell is a number.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetContentsStr
(LCH_CELL Cell,
lushort BufLen,
lptr(lmbcs) lpContentsStr)
Arguments
Cell The handle of an existing cell object.
BufLen The number of bytes available in the buffer pointed to by lpContentsStr, including room for a null-terminating byte. This value need not be greater than LCI_MAX_CELL_LEN.
lpContentsStr A pointer to a lmbcs string in which to return the contents string.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lmbcs ContentsStr[LCI_MAX_CELL_LEN];
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,LCI_MAX_CELL_LEN,ContentsStr);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the type of the literal contents of a cell, that is. the type of value that the user typed into the cell and that 1-2-3 displays in the control panel when the user is editing the cell. The contents can be a number, label, formula, blank, @ERR, or @NA.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetContentsType
(LCH_CELL Cell,
lptr(lushort) lpContentsType)
Arguments
Cell The handle of an existing cell object.
lpContentsType A pointer to an lushort in which to return the contents type. Possible values are
Constant Meaning
LCI_CONTENTS_TYPE_BLANK Blank
LCI_CONTENTS_TYPE_ERR @ERR
LCI_CONTENTS_TYPE_FORMULA A formula
LCI_CONTENTS_TYPE_LABEL A label
LCI_CONTENTS_TYPE_NA @NA
LCI_CONTENTS_TYPE_NUMBER A number
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort ContentsType;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsType(Cell,&ContentsType);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the context handle that was used to construct the cell object.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetContext
(LCH_CELL Cell,
lptr(LCH_CONTEXT) lpContext)
Arguments
Cell The handle of an existing cell object.
lpContext A pointer to storage in which to return the context handle.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
LCH_CONTEXT CellContext;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContext(Cell,&CellContext);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the sheet, column, and row numbers of a cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetCoords
(LCH_CELL Cell,
lptr(lushort) lpSheetNum,
lptr(lushort) lpColumnNum,
lptr(lushort) lpRowNum)
Arguments
Cell The handle of an existing cell object.
lpSheetNum, Pointer to an lushort in which to return the sheet number.
lpColNum, Pointer to an lushort in which to return the column number.
lpRowNum Pointer to an lushort in which to return the row number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort Column;
lushort Row;
lushort Sheet;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetCoords(Cell,&Sheet,&Column,&Row);
.
Status = LciClDestroy(&Cell);
Definition
Retrieves the fully qualified pathname of the workfile in which a specified cell resides.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetFileName
(LCH_CELL Cell,
lushort BufLen,
lptr(lmbcs) lpFileName)
Arguments
Cell The handle of an existing cell object.
BufLen The number of bytes available in the lmbcs string pointed to by lpFileName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_FILENAME_LEN.
lpFileName A pointer to a lmbcs string in which to return the workfile pathname.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lmbcs FileName[LCI_MAX_FILENAME_LEN];
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetFileName(Cell,LCI_MAX_FILENAME_LEN,Filename);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves current typeface and font size. Fonts are available in a list of 1 - 8. A font designates typeface and size. Fonts 1 - 8 correspond to the list displayed by the Style Font dialog box.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetFont
(LCH_CELL Cell,
lptr(lushort) lpTypeFace)
Arguments
Cell The handle of an existing cell object.
lpTypeFace A pointer to an lushort in which to return the font type. Values for lpTypeface are:
LCI_FONT_1
LCI_FONT_2
LCI_FONT_3
LCI_FONT_4
LCI_FONT_5
LCI_FONT_6
LCI_FONT_7
LCI_FONT_8
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort Font;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetFont(Cell,&Font);
. . .
Status = LciClDestroy(&Cell);
Definition
Supports fonts using new styles. Gets the font of the cell contained in LCH_CELL, returns the name (for example, Helvetica), height in points, alignment (vertical and horizontal), attributes, font familiy, character set, and the type of underlining to use.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetFont2
(LCH_CELL Cell,
lptr (lmbcs) Name,
lptr (lsshort) Height,
lptr (lubyte) Align,
lptr (lubyte) Attributes,
lptr (lubyte) FontFamily,
lptr (lubyte) CharSet,
lptr (lubyte) UnderType)
Arguments
Cell The handle of an existing cell object.
Name Font name
Height Height of font in points
Align vertical alignment: base, center, top
horizontal alignment: bottom, default, left, right, center, diagonal, even
Attributes bold, italic, single underline, strikeout, outline
FontFamily Font family: Don't care, Roman, Swiss, Modern, Script, Decorative
Font pitch: Default, Fixed, Variable
CharSet Character set: Ansi, Symbol, Shiftjis, Hangul, Big5, OEM
UnderType Underlining: None, single, double, thick, box, singlestrike, doublestrike, thickstrike
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
#include "lcienum.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lmbcs FontName[LCI_MAX_FONTNAME]
lsshort FontHeight;
lubyte FontAlign;
lubyte FontAttribs;
lubyte FontCharSet;
lubyte FontUnderLineType;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetFont2(Cell,
FontName,
&FontHeight,
&FontAlign,
&FontAttribs,
&FontCharSet,
&FontUnderLineType);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the format and precision (that is, number of decimal places) by which the cell value is displayed. If the format is not a number format (FIXED, SCIENTIFIC, CURRENCY, COMMA, PERCENT), then the precision retrieved will be set to 0.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetFormat
LCH_CELL Cell,
lptr(lushort) lpFormat,
lptr(lushort) lpPlaces)
Arguments
Cell The handle of an existing cell object.
lpFormat A pointer to an lushort in which to return the format. Refer to LciClSetFormat »Page for a list of the possible values.
lpPlaces A pointer to an lushort in which to return the number of decimal places.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort Format;
lushort Places;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetFormat(Cell,&Format,&Places);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the italic attribute for a cell.
Format
LCT_STATUS LCI_CALL LciClGetItalicFlag
(LCH_CELL Cell,
lptr(lbool) lpItalic)
Arguments
Cell The handle of an existing cell object.
lpItalic A pointer to an lbool in which to return the italic flag (LTRUE if italics are on; LFALSE if italics are off).
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lbool Italics;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetItalicFlag(Cell,&Italics);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the format used to display labels in a cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetLabelType
(LCH_CELL Cell,
lptr(lushort) lpLabelType)
Arguments
Cell The handle of an existing cell object.
lpLabelType A pointer to an lushort in which to return the label type. The following values can be returned:
LCI_LABEL_TYPE_CENTER
LCI_LABEL_TYPE_NONPRINTING
LCI_LABEL_TYPE_NO_PREFIX - indicates the cell is not a label
LCI_LABEL_TYPE_REPEATING
LCI_LABEL_TYPE_RIGHT
LCI_LABEL_TYPE_LEFT
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort LabelType;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetLabelType(Cell,&LabelType);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves a flag that is LTRUE if the cell has been set to automatically enclose any negative numeric value in parentheses; LFALSE otherwise .
Format
#include "lcicomn.h,
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetParenFlag
(LCH_CELL Cell,
lptr(lbool) lpParenFlag)
Arguments
Cell The handle of an existing cell object.
lpParenFlag A pointer to an lbool in which to return the flag.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lbool ParenFlag;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetParenFlag(Cell,&ParenFlag);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the current cell shading attribute setting.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetPattern
(LCH_CELL Cell,
lptr(lushort) lpPattern)
Arguments
Cell The handle of an existing cell object.
lpPattern A pointer to an lushort in which to return the shading pattern value. Valid shading values are:
LCI_PATTERN_LIGHT
LCI_PATTERN_DARK
LCI_PATTERN_CLEAR
LCI_PATTERN_SOLID
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort Pattern;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetPattern(Cell,&Pattern);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves a flag that is LTRUE if the cell is currently protected (modifications to the cell are not allowed); LFALSE otherwise.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetProtectFlag
(LCH_CELL Cell,
lptr(lbool) lpProtectFlag)
Arguments
Cell The handle of an existing cell object.
lpProtectFlag A pointer to an lbool in which to return the flag.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lbool Protected;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetProtectFlag(Cell,&Protected);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the current one-based row number of a cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetRow
(LCH_CELL Cell,
lptr(lushort) lpRowNum)
Arguments
Cell The handle of an existing cell object.
lpRowNum A pointer to an lushort in which to return the row number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort RowNum;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetRow(Cell,&RowNum);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the current row height in points.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetRowHeight
( LCH_CELL Cell,
lptr(lushort) lpRowHeight)
Arguments
Cell The handle of an existing cell object.
lpRowHeight A pointer to an lushort in which to return the row height.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort RowHeight;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetRowHeight(Cell,&RowHeight);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the status of the drop shadow attribute for a cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetShadowFlag
(LCH_CELL Cell,
lptr(lbool) lpShadowFlag)
Arguments
Cell The handle of an existing cell object.
lpShadowFlag A pointer to an lbool in which to return the shadow flag (LTRUE if the cell has a drop shadow; LFALSE if not).
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lbool ShadowOn;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetShadowFlag(Cell,&ShadowOn);
.
Status = LciClDestroy(&Cell);
Definition
Retrieves the one-based number of the sheet in which the cell resides.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetSheet
(LCH_CELL Cell,
lptr(lushort) lpSheetNum)
Arguments
Cell The handle of an existing cell object.
lpSheetNum A pointer to an lushort in which to return the sheet number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort SheetNum;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetSheet(Cell,&SheetNum);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the current underline setting for a cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetUnderline
(LCH_CELL Cell,
lptr(lushort) lpUnderline)
Arguments
Cell The handle of an existing cell object.
lpUnderline A pointer to an lushort in which to return the underline type. Valid settings are:
LCI_LINE_TYPE_NONE
LCI_LINE_TYPE_SINGLE
LCI_LINE_TYPE_DOUBLE
LCI_LINE_TYPE_WIDE
LCI_LINE_TYPE_BOX
LCI_LINE_TYPE_SINGLSTRIKE
LCI_LINE_TYPE_DOUBLSTRIKE
LCI_LINE_TYPE_THICKSTRIKE
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort Underline;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetUnderline(Cell,&Underline);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves a flag that is LFALSE if the cell has been deleted by deleting its row or column; LTRUE otherwise. A cell can also be made invalid if it is the target cell of a move or copy operation.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetValidFlag
(LCH_CELL Cell,
lptr(lbool) lpValidFlag)
Arguments
Cell The handle of an existing cell object.
lpValidFlag A pointer to an lbool in which to return the flag.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lbool ValidCell;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetValidFlag(Cell,&ValidCell);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the current value (as opposed to contents) of a cell if that value is a number. If the cell contains null, or a label or string formula, the retrieved value is zero. If the cell contains @ERR or @NA, the returned status is LCS_ERR or LCS_NA. Call LciClGetValType »Page to find out the type of the value.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciCellGetValNum
(LCH_CELL Cell,
lptr(lfloat10) lpValNum)
Arguments
Cell The handle of an existing cell object.
lpValNum A pointer to an lfloat10 in which to return the numeric value.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_CELL »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lfloat10 CellValue;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetValNum(Cell,&CellValue);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the current value (as opposed to contents) of a cell if that value is not a number. If the cell is blank or contains a number or number formula, the returned value is "". If the cell contains @ERR or @NA, the returned status is LCS_ERR or LCS_NA. Call LciClGetValNum »Page to obtain a number value; call LciClGetValType »Page to find out the type of the value.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciCellGetValStr
(LCH_CELL Cell,
lushort BufLen,
lptr(lmbcs) lpValStr)
Arguments
Cell The handle of an existing cell object.
BufLen The number of bytes available in the lmbcs string pointed to by lpValStr, including room for a null-terminating byte. The buffer need not be greater than LCI_MAX_CELL_LEN.
lpValStr A pointer to a lmbcs string in which to return the string value.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_INVALID_CELL »Page
LCS_NA »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lmbcs CellValStr[LCI_MAX_CELL_LEN];
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetValStr(Cell,LCI_MAX_CELL_LEN,CellValStr);
. . .
Status = LciClDestroy(&Cell);
Definition
Retrieves the type of the value (as opposed to contents) of a cell. If a cell contains a formula, its value can be either string, number, @ERR, or @NA. If it contains a label, the value type is string. If it contains a number, the value type is number. If it contains blank, @ERR, or @NA, ValType is LCI_VAL_TYPE_BLANK, LCI_VAL_TYPE_ERR, or LCI_VAL_TYPE_NA.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClGetValType
(LCH_CELL Cell,
lptr(lushort) lpValType)
Arguments
Cell The handle of an existing cell object.
lpValType A pointer to an lushort in which to return the value type. Possible values are:
Constant Meaning
LCI_VAL_TYPE_BLANK Blank contents
LCI_VAL_TYPE_ERR @ERR
LCI_VAL_TYPE_NA @NA
LCI_VAL_TYPE_NUM A number
LCI_VAL_TYPE_STR A string
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lushort ValType;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetValType(Cell,&ValType);
. . .
Status = LciClDestroy(&Cell);
Definition
Moves the contents, format, places, and protection attributes from one cell to another. This operation corresponds to the Edit Move Cells command on a single-cell range.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClMove
(LCH_CELL CellFrom,
LCH_CELL CellTo)
Arguments
CellFrom The handle of a cell object from which to move.
CellTo The handle of a cell object to which to move.
Returns
LCS_SUCCESS »Page
LCS_DIFFERENT_FILES »Page
LCS_INVALID_FROM_CELL »Page
LCS_INVALID_TO_CELL »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL SourceCell;
LCH_CELL TargetCell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&TargetCell);
Status = LciClConstructCoords(Context,LCI_CURRENT_WORKFILE,
LCI_CURRENT_SHEET,5,7,&SourceCell);
Status = LciClMove(SourceCell,TargetCell);
. . .
Status = LciClDestroy(&TargetCell);
Status = LciClDestroy(&SourceCell);
Definition
Changes the cell sheet coordinate to the next sheet in the workfile. If the cell refers to the last sheet in a workfile, the function advances the cell to the first sheet of the workfile.
Use LciClNextSheet to move forward linearly through sheets in a workfile. Use LciClPrevSheet »Page to move backward linearly through sheets in a workfile.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CELL LciClNextSheet
(LCH_CELL Cell)
Argument
Cell The handle of an existing cell object.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClNextSheet(Cell);
. . .
Status = LciClDestroy(&Cell);
Definition
Changes the cell sheet coordinate to the previous sheet in the specified workfile. If the cell refers to the first sheet in a workfile, the function sets the cell sheet coordinates to the last sheet of the workfile.
Use LciClPrevSheet to move backward linearly through sheets in a workfile, changing the sheet coordinate as appropriate, while keeping column and row coordinates constant. Use LciClNextSheet »Page to move forward linearly through sheets in a workfile.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CELL LciClPrevSheet
(LCH_CELL Cell)
Argument
Cell The handle of an existing cell object.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClPrevSheet(Cell);
. . .
Status = LciClDestroy(&Cell);
Definition
Executes a worksheet macro stored in a specified cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClRunMacro
(LCH_CELL Cell)
Argument
Cell The handle of a cell object that contains the macro to run.
Returns
LCS_SUCCESS »Page
LCS_KEY_BREAK »Page
LCS_INVALID_CELL »Page
LCS_INVALID_USE »Page
LCS_MACRO_ERROR »Page
LCS_MISSING_ARG »Page
LCS_STACK_OVERFLOW »Page
LCS_INVALID_VALUE »Page
LCS_NULL_HANDLE »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClSetContentsStr(Cell,"{HELP}");
Status = LciClRunMacro(Cell);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the bold attribute for a cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CELL LciClSetBoldFlag
(LCH_CELL Cell,
lbool Bold)
Arguments
Cell The handle of an existing cell object.
Bold The desired bold type (LTRUE if you want the cell entry displayed in bold; LFALSE if you do not).
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Turn bold on in the cell. */
Status = LciClSetBoldFlag(Cell,LTRUE);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the current border colors for a cell. The border color constants can be seen through the Lines & Color dialog box under Border - Line Color, to view thier respective colors.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetBorderColor
(LCH_CELL Cell,
lushort TopColor,
lushort BottomColor,
lushort LeftColor,
lushort RightColor)
Arguments
Cell The handle of an existing cell object.
TopColor An lushort set to one of the valid border color values.
BottomColor An lushort set to one of the valid border color values.
LeftColor An lushort set to one of the valid border color values.
RightColor An lushort set to one of the valid border color values.
Valid border colors are:
LCI_BORDER_COLOR_1
LCI_BORDER_COLOR_2
LCI_BORDER_COLOR_3
LCI_BORDER_COLOR_4
LCI_BORDER_COLOR_5
LCI_BORDER_COLOR_6
LCI_BORDER_COLOR_7
LCI_BORDER_COLOR_8
LCI_BORDER_COLOR_9
LCI_BORDER_COLOR_10
LCI_BORDER_COLOR_11
LCI_BORDER_COLOR_12
LCI_BORDER_COLOR_13
LCI_BORDER_COLOR_14
LCI_BORDER_COLOR_15
LCI_BORDER_COLOR_16
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClSetBorderColor(Cell,
LCI_BORDER_COLOR_4, // top = lt. green
LCI_BORDER_COLOR_4, // bottom = lt. green
LCI_BORDER_COLOR_5, // left = royal blue
LCI_BORDER_COLOR_5); // right = royal blue
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the borders for a cell. The line type for each area (left, right, top, bottom) will be set on each call. If you want to set ALL or OUTLINE, simply set each border to the same type. If you want to set one without regard to the others, set that one to a specific type (NONE, SINGLE, DOUBLE, WIDE) and set the others to LCI_LINE_TYPE_NOCHANGE. This will guarantee that the current setting for a given border will remain unchanged.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetBorders
(LCH_CELL Cell,
lushort TopLine,
lushort BottomLine,
lushort LeftLine,
lushort RightLine)
Arguments
Cell The handle of an existing cell object.
TopLine The desired border setting for the top border of the cell.
BottomLine The desired border setting for the bottom border of the cell.
LeftLine The desired border setting for the left border of the cell.
RightLine The desired border setting for the right border of the cell.
Valid settings are: LCI_LINE_TYPE_NOCHANGE
LCI_LINE_TYPE_NONE,
LCI_LINE_TYPE_SINGLE,
LCI_LINE_TYPE_DOUBLE
LCI_LINE_TYPE_WIDE
LCI_LINE_TYPE_NARROWDOT
LCI_LINE_TYPE_DOT
LCI_LINE_TYPE_DASH
LCI_LINE_TYPE_DOTDASH
LCI_LINE_TYPE_DASHDOTDOT
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_INVALID_TYPE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Set left and right to wide; leave top and bottom unchanged. */
Status = LciClSetBorders(Cell, LCI_LINE_TYPE_NOCHANGE,
LCI_LINE_TYPE_NOCHANGE,
LCI_LINE_TYPE_WIDE,
LCI_LINE_TYPE_WIDE);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the one-based column number of a cell without changing row or sheet coordinates.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetCol
LCH_CELL Cell,
lushort ColNum)
Arguments
Cell The handle of an existing cell object.
ColNum The new column number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_INVALID_COL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Move cell to column IV. */
Status = LciClSetCol(Cell,256);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the foreground or background color of a cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetColor
(LCH_CELL Cell,
lushort Area,
lushort Color)
Arguments
Cell The handle of an existing cell object.
Area The desired area type. Valid settings are:
LCI_COLOR_TYPE_BG
LCI_COLOR_TYPE_FG
Color The desired color type. Colors are an integer from 0 to 255 that is to an index into the Windows color palette or one of the following predefined constants:
LCI_COLOR_1
LCI_COLOR_2
LCI_COLOR_3
LCI_COLOR_4
LCI_COLOR_5
LCI_COLOR_6
LCI_COLOR_7
LCI_COLOR_8
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_INVALID_INDEX »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context, &Cell);
/* Set cell background to color 7 */
Status = LciClSetColor(Cell, LCI_COLOR_TYPE_BG, 232);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets whether or not negative cell values should be displayed in a contrasting color.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetColorNegFlag
(LCH_CELL Cell,
lbool ColorNegFlag)
Arguments
Cell The handle of an existing cell object.
ColorNegFlag The desired flag value. ColorNegFlag is LTRUE if cell values are to be displayed in a contrasting color; LFALSE if not.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_CELL »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Display negative cell values in contrasting colors. */
Status = LciClSetColorNegFlag(Cell,LTRUE);
. . .
Status = LciClDestroy(&Cell);
Definition
Modifies the width of the column containing a cell as viewed by a specified pane in all windows. Column width is specified in number of characters and ranges from LCI_MIN_COL_WIDTH (1) to LCI_MAX_COL_WIDTH (240).
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetColWidth
(LCH_CELL Cell,
lushort PaneNum,
lushort ColWidth)
Arguments
Cell The handle of an existing cell object.
PaneNum The one-based number of a pane within each window, or LCI_CURRENT_PANE to specify the current pane. One (1) refers to the top left, or only pane.
ColWidth The desired column width. If ColWidth is equal to LCI_DEFAULT_COL_WIDTH (numeric 0), the width of the column is set to the default column width of the containing sheet.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_CELL »Page
LCS_INVALID_PANE »Page
LCS_INVALID_WIDTH »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Set column width in current pane to default. */
Status = LciClSetColWidth(Cell,LCI_CURRENT_PANE,
LCI_DEFAULT_COL_WIDTH);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the contents of a cell to the specified number. This is the value that the user sees when viewing the cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetContentsNum
(LCH_CELL Cell,
lfloat10 ContentsNum)
Arguments
Cell The handle of an existing cell object.
ContentsNum The desired numeric contents.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lfloat10 ContentsNum;
lushort StackType;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Set cell contents to 5. */
Status = LciMtPushShort(Context,5);
Status = LciMtPopFloat10(Context,&ContentsNum,&StackType);
Status = LciClSetContentsNum(Cell,ContentsNum);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the literal contents of a cell as if the user typed a value into the control line and pressed ENTER.
Setting lpContentsStr to a single-quoted string (*'...*) sets the contents type to LCI_CONTENTS_TYPE_LABEL and the value type to LCI_VAL_TYPE_STR.
Setting lpContentsStr to a number sets the contents type to LCI_CONTENTS_TYPE_NUM and the value type to LCI_VAL_TYPE_NUM.
Setting lpContentsStr to @ERR sets the contents type to LCI_CONTENTS_TYPE_ERR and value type to LCI_VAL_TYPE_ERR.
Setting lpContentsStr to @NA sets contents type to LCI_CONTENTS_TYPE_NA and value type to LCI_VAL_TYPE_NA.
Setting lpContentsStr to any string which begins with "@" sets the contents type to LCI_CONTENTS_TYPE_FORMULA, in which case the value type depends on the formula's current value at runtime.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetContentsStr
(LCH_CELL Cell,
lptr(lmbcs) lpContentsStr)
Arguments
Cell The handle of an existing cell object.
lpContentsStr A pointer to a lmbcs string that contains the desired string. Its length must not exceed LCI_MAX_CELL_LEN.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_INVALID_FORMULA »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_CELL »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Set cell contents to "hello world" */
Status = LciClSetContentsStr(Cell,"hello world");
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the sheet, column, and row numbers of a cell. All coordinates are one-based.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetCoords
(LCH_CELL Cell,
lushort SheetNum,
lushort ColumnNum,
lushort RowNum)
Arguments
Cell The handle of an existing cell object.
SheetNum The desired sheet number.
ColumnNum The desired column number.
RowNum The desired row number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_INVALID_COL »Page
LCS_INVALID_ROW »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Move cell pointer to C:D1. */
Status = LciClSetCoords(Cell,3,4,1);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the pathname of the workfile in which a specified cell resides without regard to the coordinates of the cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetFileName
(LCH_CELL Cell,
lptr(lmbcs) lpFileName)
Arguments
Cell The handle of an existing cell object.
lpFileName A pointer to a lmbcs string that contains the desired workfile pathname. Its length must not exceed LCI_MAX_FILENAME_LEN.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_SHEET »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Move cell to "INVENTRY.WK3". */
Status = LciClSetFileName(Cell,"INVENTRY.WK3");
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the current typeface and font size. Fonts are available in a list of 1 - 8. Chooing a font also designates typeface and size. Fonts 1 - 8 correspond to the fonts displayed in the Style Font dialog box.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetFont
(LCH_CELL Cell,
lushort TypeFace)
Arguments
Cell The handle of an existing cell object.
TypeFace The desired typeface value. Valid settings are:
LCI_FONT_1
LCI_FONT_2
LCI_FONT_3
LCI_FONT_4
LCI_FONT_5
LCI_FONT_6
LCI_FONT_7
LCI_FONT_8
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Set font to font 3. */
Status = LciClSetFont(Cell,LCI_FONT_3);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the current font attribute for a cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetFont2
(LCH_CELL Cell,
lptr (lmbcs) Name,
lsshort Height,
lubyte Align,
lubyte Attributes,
lubyte FontFamily,
lubyte CharSet,
lubyte UnderType)
Arguments
Cell The handle of an existing cell object.
Name Font name
Height Height of font in points
Align vertical alignment: base, center, top
horizontal alignment: bottom, default, left, right, center, diagonal, even
Attributes bold, italic, single underline, strikeout, outline
FontFamily Font family: Don't care, Roman, Swiss, Modern, Script, Decorative
Font pitch: Default, Fixed, Variable
CharSet Character set: Ansi, Symbol, Shiftjis, Hangul, Big5, OEM
UnderType Underlining: None, single, double, thick, box, singlestrike, doublestrike, thickstrike
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
#include "lcienum.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClSetFont2(Cell,
"MyFont",
24,
LCI_VERT_ALIGN_CENTER | LCI_HORZ_ALIGN_CENTER,
LCI_FONT_BOLD,
LCI_FONT_CHARSET_ANSI,
LCI_FONT_FAMILY_SWISS | LCI_FONT_PITCH_FIXED,
LCI_LINE_TYPE_NONE);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the format and precision by which the cell value is displayed. The places argument for non-numeric formats is ignored. For all numeric formats, places must be betweeen 0 - LCI_MAX_PLACES.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetFormat
(LCH_CELL Cell,
lushort Format,
lushort Places)
Arguments
Cell The handle of an existing cell object.
Format The desired format. Possible values are:
Constant Meaning
LCI_FORMAT_AUTO automatic format
LCI_FORMAT_BAR +/- format
LCI_FORMAT_COMMA thousands separators (numeric)
LCI_FORMAT_CURRENCY international currency format (numeric)
LCI_FORMAT_DATE_INTL_LONG long international date format (D4)
LCI_FORMAT_DATE_INTL_SHORT short international date format (D5)
LCI_FORMAT_DAY_MIN DD-MMM date format (D2)
LCI_FORMAT_DAY_MON_YR DD-MMM-YY date format (D1)
LCI_FORMAT_DEFAULT default format
LCI_FORMAT_FIXED fixed format (numeric)
LCI_FORMAT_GENERAL general format
LCI_FORMAT_HIDDEN hidden format
LCI_FORMAT_HR_MIN HH:MM (AM/PM) time format (D7)
LCI_FORMAT_HR_MIN_SEC HH:MM:SS (AM/PM) time format (D6)
LCI_FORMAT_LABEL label format
LCI_FORMAT_MON_YR MMM-YY date format (D3)
LCI_FORMAT_PERCENT percent format (numeric)
LCI_FORMAT_SCIENTIFIC sci (scientific) format (numeric)
LCI_FORMAT_TEXT text format
LCI_FORMAT_TIME_INTL_LONG long international (24hr) time format (D8)
LCI_FORMAT_TIME_INTL_SHORT short international (24hr) time format (D9)
Places The desired number of decimal places, or LCI_DEFAULT_PLACES.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_CELL »Page
LCS_INVALID_PLACES »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_INVALID_FORMAT »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Set format to percent with 3 decimal places. */
Status = LciClSetFormat(Cell,LCI_FORMAT_PERCENT,3);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the italic attribute for a cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetItalicFlag
(LCH_CELL Cell,
lbool Italic)
Arguments
Cell The handle of an existing cell object.
Italic The desired italic type (LTRUE if you want the cell entry displayed in italics; LFALSE if you do not).
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Set italics on. */
Status = LciClSetItalicFlag(Cell,LTRUE);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the format used to display labels in a cell. It has no effect on numbers, formulas, or blank cells.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetLabelType
(LCH_CELL Cell,
lushort LabelType)
Arguments
Cell The handle of an existing cell object.
LabelType The desired label type. Possible values are:
LCI_LABEL_TYPE_CENTER
LCI_LABEL_TYPE_LEFT
LCI_LABEL_TYPE_NONPRINTING
LCI_LABEL_TYPE_REPEATING
LCI_LABEL_TYPE_RIGHT
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
LCS_INVALID_LABEL_TYPE »Page
LCS_FILE_SEALED »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Center the label in the cell. */
Status = LciClSetLabelType(Cell,LCI_LABEL_TYPE_CENTER);
. . .
Status = LciClDestroy(&Cell);
Definition
Turns display of negative numeric values in parentheses on or off.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetParenFlag
(LCH_CELL Cell,
lbool ParenFlag)
Arguments
Cell The handle of an existing cell object.
ParenFlag The desired flag value (LTRUE to display parentheses; LFALSE otherwise).
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_CELL »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Turn parentheses on. */
Status = LciClSetParenFlag(Cell,LTRUE);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the current cell shading attribute. The shading attribute is the pattern that is drawn as the background of a cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetPattern
(LCH_CELL Cell,
lushort Pattern)
Arguments
Cell The handle of an existing cell object.
Pattern The desired shading value. Valid settings are:
LCI_PATTERN_LIGHT
LCI_PATTERN_DARK
LCI_PATTERN_CLEAR (default)
LCI_PATTERN_SOLID
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_INVALID_TYPE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Turn on light shading. */
Status = LciClSetPattern(Cell,LCI_PATTERN_LIGHT);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets protection on or off for a cell. The protection attribute is meaningful only when global protection is turned on.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetProtectFlag
(LCH_CELL Cell,
lbool ProtectFlag)
Arguments
Cell The handle of an existing cell object.
ProtectFlag The desired flag value (LTRUE to protect the cell; LFALSE otherwise).
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_CELL »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Allow modifications to the cell. */
Status = LciClSetProtectFlag(Cell,LFALSE);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the one-based row number of a cell without changing sheet or column coordinates.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetRow
(LCH_CELL Cell,
lushort RowNum)
Arguments
Cell The handle of an existing cell object.
RowNum The desired row number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_INVALID_ROW »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Move the cell pointer to row 8192. */
Status = LciClSetRow(Cell,8192);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the current row height in points. The maximum row height is LCI_MAX_ROW_HEIGHT; the minimum is LCI_MIN_ROW_HEIGHT.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetRowHeight
(LCH_CELL Cell,
lushort RowHeight)
Arguments
Cell The handle of an existing cell object.
RowHeight The desired row height.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_INVALID_NUM »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Set row height to 1 inch (72 points). */
Status = LciClSetRowHeight(Cell,72);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets drop shadow on or off for a cell. A drop shadow is an attribute that makes the cell stand out as though it were raised above the plane of the sheet.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetShadowFlag
(LCH_CELL Cell,
lbool ShadowFlag)
Arguments
Cell The handle of an existing cell object.
ShadowFlag The desired shadow type (LTRUE if you want the cell entry displayed with a drop shadow; LFALSE if you do not).
Returns
LCS_SUCCESS »Page
LCS_HIDDEN_SHEET »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Turn drop shadow on. */
Status = LciClSetShadowFlag(Cell,LTRUE);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the one-based sheet number of a cell without changing row or column coordinates.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetSheet
(LCH_CELL Cell,
lushort SheetNum)
Arguments
Cell The handle of an existing cell object.
SheetNum The desired sheet number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
. . .
Status = LciClConstructCurr(Context,&Cell);
/* Move the cell pointer to sheet C: (that is, the third sheet). */
Status = LciClSetSheet(Cell,3);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the current underline setting for a cell.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LciClSetUnderline
(LCH_CELL Cell,
lushort Underline)
Arguments
Cell The handle of an existing cell object.
Underline The desired underline type. Valid settings are:
LCI_LINE_TYPE_NOCHANGE
LCI_LINE_TYPE_NONE
LCI_LINE_TYPE_SINGLE
LCI_LINE_TYPE_DOUBLE
LCI_LINE_TYPE_WIDE
LCI_LINE_TYPE_BOX
LCI_LINE_TYPE_SINGLSTRIKE
LCI_LINE_TYPE_DOUBLSTRIKE
LCI_LINE_TYPE_THICKSTRIKE
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_INVALID_TYPE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCH_STATUS Status;
. . .
Status = LciClConstructCurr(Context, &Cell);
/* Give the cell double underline attribute. */
Status = LciClSetUnderline(Cell, LCI_LINE_TYPE_DOUBLE);
. . .
Status = LciClDestroy(&Cell);
Definition
Returns the current attributes of a cell in a structured bitmap format. This function is optimized to work with the formats as they are supported in 1-2-3 for Windows Release 1.0. Although this function will be supported in future versions of 1-2-3 for Windows, it may not be optimized for those versions.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LcxClGetAttributeFlags
(LCH_CELL Cell,
lptr(LCT_ATTRIBUTES) lpAttr)
typedef union LCT_ATTRIBUTES_ {
struct {
lulong l1;
lulong l2;
} longwords;
struct {
unsigned font :3 /* 0-7 */
unsigned bold :1 /* 0-1 */
unsigned italic :1 /* 0-1 */
unsigned underline :2 /* 0-3 */
/* 0=none, 1=single, 2=double, 3=wide */
unsigned reserve0 :1 /* 0-1 */
unsigned cell_color :3 /* 0-7 */
unsigned reserve1 :4
unsigned color_negative :1 /* 0-1 */
unsigned bg_color :3 /* 0-7 */
unsigned pattern :2 /* 0-3 */
/* 0=clear, 1=light, 2=dark, 3=solid */
unsigned drop_shadow :1 /* 0-1 */
unsigned reserve2 :2
unsigned border_left :2 /* 0-3 */
/* 0=none, 1=single, 2=double, 3=wide */
unsigned border_right :2 /* 0-3 */
/* 0=none, 1=single, 2=double, 3=wide */
unsigned border_top :2 /* 0-3 */
/* 0=none, 1=single, 2=double, 3=wide */
unsigned border_bottom :2 /* 0-3 */
/* 0=none, 1=single, 2=double, 3=wide */
unsigned general_format :7 /* LCF_FORMAT_* */
unsigned protected :1 /* 0-1 */
unsigned reserve3 :1
unsigned parentheses :1 /* 0-1 */
unsigned :3 /* 0-7 */
} attrs;
} LCT_ATTRIBUTES;
Arguments
Cell The handle of an existing cell object.
lpAttr A pointer to an LCT_ATTRIBUTES union that will be set to the current cell attribute settings.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
LCT_ATTRIBUTES Attributes;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LcxClGetAttributeFlags(Cell,&Attributes);
if (Attributes.attrs.underline == 1)
/* Determines if cell is underlined. */
{
. . .
}
Status = LciClDestroy(&Cell);
Definition
Returns the current attributes of a cell in a structured bitmap format. This function is optimized to work with the formats as they are supported in 1-2-3 Release 4.0 for Windows. Although this function will be supported in future versions of 1-2-3 for Windows, it may not be optimized for those versions.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LcxClGetAttributeFlags2
(LCH_CELL Cell,
lptr(LCT_ATTRIBUTES2) lpAttributes)
typedef struct LCT_ATTRIBUTES2_ {
struct {
/* (16 bits) Font Style info */
unsigned font : 12; /* Font handle */
unsigned resv1 : 1; /* Reserved */
unsigned underline : 3; /* Underline conditions */
/* (24 Bits) Cell Patterns. */
unsigned f_color : 8; /* Foreground color index */
unsigned b_color : 8; /* Background color index */
unsigned use_b_color_ndx : 1; /* Use Background color index */
unsigned use_f_color_ndx : 1; /* Use Foreground color index */
unsigned fillpattern : 6; /* Up to 64 fill patterns. */
/* (12 Bits) Text alignment/attributes */
unsigned v_align : 2; /* Alignment for non labels, vertical */
unsigned h_align : 3; /* Horizontal alignment */
unsigned shad2 : 1; /* INTERNAL USE ONLY */
unsigned resv2 : 2; /* Reserved */
unsigned wrap : 1; /* Possible word wrap usage */
unsigned negative : 1; /* Negative #s are red or not. */
unsigned unformated : 1; /* Unused */
unsigned text : 1; /* Text bit attribute for :TE */
/* (1 Bit) Shadow Style */
unsigned shadow : 1; /* Shadow Frame Styles */
/* (20 bits) Border color info up to 31 colors 0 default */
unsigned b_edge_color: 5; /* Bottom edge style */
unsigned t_edge_color: 5; /* Top edge style */
unsigned resv2a : 1; /* padding */
unsigned r_edge_color: 5; /* Right edge style */
unsigned l_edge_color: 5; /* Left edge style */
/* (12 bits) Border style info for 8 border types plus 0 default */
unsigned b_edge : 4; /* Bottom edge style */
unsigned resv2b : 2; /* padding */
unsigned t_edge : 4; /* Top edge style */
unsigned r_edge : 4; /* Right edge style */
unsigned l_edge : 4; /* Left edge style */
/* (3 Bits) Optmization/FM3 Compatiblity, Special bits */
unsigned graph : 1; /* Graph bit attribute */
unsigned DDELink : 1; /* Range contains a DDE Link. */
unsigned resv3 : 2; /* Reserved */
/* Byte 12 Custom User formats */
unsigned userfmt : 8; /* User format handle */
/* Byte 13 Style ID of parent */
unsigned styleid : 8;
} attr2;
union format {
lulong lfmts;
struct {
unsigned general_format : 7; /* LCF_FORMAT_* */
unsigned protectd : 1; /* 0-1 */
unsigned reserve3 : 1;
unsigned parentheses : 1; /* 0-1 */
} fmts;
}number_format;
} LCT_ATTRIBUTES2;
Arguments
Cell The handle of an existing cell object.
lpAttributes A pointer to an LCT_ATTRIBUTES2 which will be set to the current cell attribute settings.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
LCT_ATTRIBUTES2 Attributes;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LcxClGetAtrributeFlags2(Context,&Cell,&Attributes);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the current attribute settings for a cell. LcxClSetAttributeFlags uses a structured bitmap defined as LCT_ATTRIBUTES for its settings. This function is optimized to work with the formats as they are supported in 1-2-3 for Windows Release 1.0. Although the function will be supported in future versions of 1-2-3 for Windows, it may not be optimized for those versions.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LcxClSetAttributeFlags
(LCH_CELL Cell,
LCT_ATTRIBUTES Attr)
typedef union LCT_ATTRIBUTES_ {
struct {
lulong l1;
lulong l2;
} longwords;
struct {
unsigned font :3 /* 0-7 */
unsigned bold :1 /* 0-1 */
unsigned italic :1 /* 0-1 */
unsigned underline :2 /* 0-3 */
/* 0 = none, 1 = single, 2 = double, 3 = wide */
unsigned reserve0 :1 /* 0-1 */
unsigned cell_color :3 /* 0-7 */
unsigned reserve1 :4
unsigned color_negative :1 /* 0-1 */
unsigned bg_color :3 /* 0-7 */
unsigned pattern :2 /* 0-3 */
/* 0 = clear, 1 = ight, 2 = dark, 3 = solid */
unsigned drop_shadow :1 /* 0-1 */
unsigned reserve2 :2
unsigned border_left :2 /* 0-3 */
/* 0 = none, 1 = single, 2 = double, 3 = wide */
unsigned border_right :2 /* 0-3 */
/* 0 = none, 1 = single, 2 = double, 3 = wide */
unsigned border_top :2 /* 0-3 */
/* 0 = none, 1 = single, 2 = double, 3 = wide */
unsigned border_bottom :2 /* 0-3 */
/* 0 = none, 1 = single, 2 = double, 3 = wide */
unsigned general_format :7 /* LCF_FORMAT_* */
unsigned protected :1 /* 0-1 */
unsigned reserve3 :1
unsigned parentheses :1 /* 0-1 */
unsigned :3 /* 0-7 */
} attrs;
} LCT_ATTRIBUTES;
Arguments
Cell The handle of an existing cell object.
Attr An LCT_ATTRIBUTES structure that contains the settings to which the cell will be set.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_CELL »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
LCT_ATTRIBUTES Attrib;
. . .
Status = LciClConstructCurr(Context,&Cell);
Attrib.longwords.l1 = 0L; /* Set all attributes */
Attrib.longwords.l2 = 0L; /* to zero. */
LcxClSetAttributeFlags(Cell,Attrib);
. . .
Status = LciClDestroy(&Cell);
Definition
Sets the current attribute settings for a cell. LcxClSetAttributeFlags2 uses a structured bitmap defined as LCT_ATTRIBUTES for its settings. This function is optimized to work with the formats as they are supported in 1-2-3 Release 4.0 for Windows. Although the function will be supported in future versions of 1-2-3 for Windows, it may not be optimized for those versions.
Format
#include "lcicomn.h"
#include "lcicell.h"
LCT_STATUS LCI_CALL LcxClSetAttributeFlags2
(LCH_CELL Cell,
LCT_ATTRIBUTES2 Attributes)
typedef struct LCT_ATTRIBUTES2_ {
struct {
/* (16 bits) Font Style info */
unsigned font : 12; /* Font handle */
unsigned resv1 : 1; /* Reserved */
unsigned underline : 3; /* Underline conditions */
/* (24 Bits) Cell Patterns. */
unsigned f_color : 8; /* Foreground color index */
unsigned b_color : 8; /* Background color index */
unsigned use_b_color_ndx : 1; /* Use Background color index */
unsigned use_f_color_ndx : 1; /* Use Foreground color index */
unsigned fillpattern : 6; /* Up to 64 fill patterns. */
/* (12 Bits) Text alignment/attributes */
unsigned v_align : 2; /* Alignment for non labels, vertical */
unsigned h_align : 3; /* Horizontal alignment */
unsigned shad2 : 1; /* INTERNAL USE ONLY */
unsigned resv2 : 2; /* Reserved */
unsigned wrap : 1; /* Possible word wrap usage */
unsigned negative : 1; /* Negative #s are red or not. */
unsigned unformated : 1; /* Unused */
unsigned text : 1; /* Text bit attribute for :TE */
/* (1 Bit) Shadow Style */
unsigned shadow : 1; /* Shadow Frame Styles */
/* (20 bits) Border color info up to 31 colors 0 default */
unsigned b_edge_color: 5; /* Bottom edge style */
unsigned t_edge_color: 5; /* Top edge style */
unsigned resv2a : 1; /* padding */
unsigned r_edge_color: 5; /* Right edge style */
unsigned l_edge_color: 5; /* Left edge style */
/* (12 bits) Border style info for 8 border types plus 0 default */
unsigned b_edge : 4; /* Bottom edge style */
unsigned resv2b : 2; /* padding */
unsigned t_edge : 4; /* Top edge style */
unsigned r_edge : 4; /* Right edge style */
unsigned l_edge : 4; /* Left edge style */
/* (3 Bits) Optmization/FM3 Compatiblity, Special bits */
unsigned graph : 1; /* Graph bit attribute */
unsigned DDELink : 1; /* Range contains a DDE Link. */
unsigned resv3 : 2; /* Reserved */
/* Byte 12 Custom User formats */
unsigned userfmt : 8; /* User format handle */
/* Byte 13 Style ID of parent */
unsigned styleid : 8;
} attr2;
union format {
lulong lfmts;
struct {
unsigned general_format : 7; /* LCF_FORMAT_* */
unsigned protectd : 1; /* 0-1 */
unsigned reserve3 : 1;
unsigned parentheses : 1; /* 0-1 */
} fmts;
}number_format;
} LCT_ATTRIBUTES2;
Arguments
Cell The handle of an existing cell object.
Attributes An LCT_ATTRIBUTES2 which contains the settings to which the cell will be set. This struct needs to be initialized with a call to LcxClGetAttributeFlags2 before this call.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
LCT_ATTRIBUTES2 Attributes;
. . .
Status = LciClConstructCurr(Context,&Cell);
Attributes.v_align = LCI_VERT_ALIGN_CENTER;
Attributes.h_align = LCI_HORZ_ALIGN_CENTER;
Status = LcxClSetAtrributeFlags2(Context,&Cell,Attributes);
. . .
Status = LciClDestroy(&Cell);
The Event Group contains LCI Functions for registering and unregistering events in an add-in, and several Callback functions for the various data types. The group also contains Event Definitions or enumerated data types available for using 1-2-3 for Windows events. These event definitions are used in the EventID argument of the LCI functions for registering, unregistering, and for writing an Event Handler.
You may select detailed indexes from the following:
Registration Functions »Page
Callback Functions »Page
Event Definitions »Page
Function Meaning
LciEvRegister »Page Registers an event handler with its associated add-in by providing the address of its event handler routine, the name of the enumerated data type (1-2-3 event), and by specifying when the handler should execute in relation to the event.
LciEvUnregister »Page Unregisters the event handler from its associated add-in.
Callback functions get and set data associated with an event. Callback functions can only be called from event handlers. Event data is accessible only while the event handler has control.
A callback function exists for each type of event data. The range of event data (type) includes numbers (lslong and lfloat10), strings (lmbcs), menuids (lslong), keys (lslong), modes (lslong), formats (lslong), filenames (lmbcs and LCT_DOSNAME_INFO), cellcoords (lslong), and objects (LCH_RANGE and LCH_CELL).
The input parameters common to all callback functions are as follows:
LCH_EVARG hArg
hArg is the argument context handle for the specified event that is passed to the event handler. It is used to get all types of event data. Any objects obtained with a callback function should be destroyed with the standard object destructor prior to exiting the handler.
lsshort ArgIndex
ArgIndex is specified only for events that have multiple arguments of the same type. If the description of an event specifies more than one data element of any one type, use ArgIndex = 0 to get the first one of that type, ArgIndex = 1 to get the second one, and so forth.
lptr(type) lpxxx
lpxxx is the pointer to the receiving C variable.
Function Description
LciEvGetArgCell »Page Constructs and retrieves a cell object, LCH_CELL, associated with the event for the calling event handler. The event handler should destroy the cell object prior to relinquishing control.
LciEvGetArgCellCoord »Page Retrieves the sheet, row and column information for a cell expressed in a single 32-bit quantity, associated with the event for the calling event handler.
LciEvGetArgInt »Page Retrieves an lslong associated with the event for the calling event handler.
LciEvGetArgNum »Page Retrieves an lfloat10 associated with the event for the calling event handler.
LciEvGetArgRange »Page Constructs and retrieves a range object, LCH_RANGE, associated with the event for the calling event handler. The event handler should destroy the range object prior to relinquishing control.
LciEvGetArgStr »Page Retrieves a lmbcs string associated with the event for the calling event handler.
LciEvGetErrCode »Page Retrieves the error code, if any, encountered in prior event handlers for the event, or the event itself, for the calling event handler.
LciEvGetParsedName »Page Retrieves a filename as a lmbcs string along with offsets into the string,which are useful for parsing, associated with the event for the calling event handler.
LciEvPostErrMsg »Page Provides a pointer to the null-terminated error message string that the handler displays to the user. Event handlers returning LCS_EVENT_MSG must post an error message with this function.
LciEvSetArgInt »Page Substitutes the event handler-supplied lslong for the one supplied by 123 for the event.
LciEvSetArgRange »Page Substitutes the event handler-supplied range object, LCH_RANGE, for the one supplied by 123 for the event.
LciEvSetArgStr »Page Substitutes the event handler-supplied string for the one supplied by 123 for the event.
Calling the Callback functions returns the data described here. Events listed as being menu-driven may also be triggered in some cases through LCI routines.
Functional Category Description
Data »Page Invoked through commands on the GUI menu and the /Data menu.
Display »Page Affects aspects of screen display.
File »Page Invoked through commands on the GUI menu and the /File menu.
Format »Page Manipulates cell or range formats.
Graph »Page Invoked through commands on the GUI menu and the /Graph menu.
Keyboard »Page Triggered by keyboard input.
Macro »Page Associated with macro execution.
Main Menu »Page Invoked through the GUI menu and the main 1-2-3 Classic menu.
Miscellaneous »Page All other events for which event handling support exists.
Mouse »Page Triggered by mouse input.
Poll »Page Triggered by the 1-2-3 scheduler as low priority tasks.
Printing »Page Related to printing.
Range »Page Related to ranges, most of which are invoked through commands on the GUI menu and the /Range menu.
Recalc »Page Recomputes a worksheet.
Worksheet »Page Invoked through commands on the GUI menu and the /Worksheet menu.
Undo »Page Triggered by the 1-2-3 undo processing.
Definition
Registers a handler procedure that will be called when the specified event occurs.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvRegister
(LCH_CONTEXT Context,
LCT_EVH_CALL FuncPtr,
lsshort EventId,
lushort OptionFlags,
lptr(LCH_REGISTRATION) lpRegistration)
Arguments
Context Add-in context handle.
FuncPtr Address of the event handler routine.
EventId Name of the enumerated data type (1-2-3 event) to which the specified event belongs.
OptionFlags Specifies when the handler should execute in relation to the event. OptionFlags should be set with the following event state masks:
Constant Meaning
LCI_EV_BEFORE Indicates that the handler executes before the event.
LCI_EV_REPLACER Indicates that the handler may execute in place of the event.
LCI_EV_AFTER Indicates that the handler executes after the event.
lpRegistration Address that receives the registration handle uniquely identifying this handler function. The only explicit use for the registration handle is as a parameter to the LciEvUnregister function if you choose to deactivate the handler before the module that registered it unloads.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_INVALID_ARG_FLAGS »Page
Example
#include "lcicomn.h"
#include "lcievent.h"
. . .
/* Poll event handler registration handle. */
static LCH_REGISTRATION evReg = LNULL;
. . .
/* Poll event handler prototype. */
LCT_STATUS LCI_CALL Poll_Handler{
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg};
. . .
/* Initialize Routine #1. */
LCT_STATUS LCI_CALL AdnInitialize(LCH_CONTEXT Context)
{
LCT_STATUS Status;
/* Register for Poll event. */
Status = LciEvRegister(Context, Poll_Handler,
LCE_POLL, LCI_EV_BEFORE, &evReg };
return (Status);
}
. . .
/* The Poll Event Handler function */
LCT_STATUS LCI_CALL Poll_Handler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg1);
{
. . .
}
Definition
Unregisters a handler for a particular event.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvUnregister
(LCH_CONTEXT Context,
LCH_REGISTRATION Registration)
Arguments
Context Add-in context handle.
Registration Registration handle of the handler you want to unregister. It is the handle supplied when the handler is registered. The add-in should set Registration back to LNULL after unregistering the handler.
Returns
LCS_SUCCESS »Page
LCS_INVALID_ARG_FLAGS »Page
Example
#include "lcicomn.h"
#include "lcievent.h"
. . .
/* Poll handler registration handle */
static LCH_REGISTRATION evReg;
. . .
/* Add-in termination function */
LCT_STATUS LCI_CALL AdnTerminate(LCH_CONTEXT Context)
{
LCT_STATUS Status;
/* Unregister the Poll event handler. */
Status = LciEvUnregister( Context, evReg );
/* Set handle back to zero. */
evReg = LNULL;
. . .
return(Status);
}
Definition
The LciEvGetArgCell function constructs and retrieves a cell object.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvGetArgCell /* This is a CONSTRUCTOR */
(LCH_EVARG hArg,
lsshort ArgIndex,
lptr(LCH_CELL) lpCell)
Arguments
hArg Argument context handle for the specified event. It is used to get strings, arrays, or objects. Any objects obtained with a callback function should be destroyed with the standard object destructor prior to exiting the handler.
ArgIndex Specified only for events that have multiple arguments of the same type; otherwise, it is ignored.
lpCell Pointer to storage in which to store the cell object handle.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_INVALID_ARG_FLAGS »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
#include "lcievent.h"
. . .
/* LCE_MOUSE_CLICK_CELL event handler */
LCT_STATUS LCI_CALL CellClickedHandler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg1)
{
LCT_STATUS Status;
. . .
LCH_CELL MouseClickedHere;
/* Get the cell the mouse was clicked on
(LCE_MOUSE_CLICK_CELL event). */
Status = LciEvGetArgCell( hEvArg, 0, &MouseClickedHere );
. . .
/ Destroy the cell. */
LciClDestroy (&MouseClickedHere);
return (Status);
} /* End of CellClickedHandler */
Definition
The LciEvGetArgCellCoord function retrieves a cell coordinate and can be used for cell event data as an alternative to LciEvGetArgCell.
A cell coordinate contains the sheet, row, and column information for a cell expressed in a single lslong. It is useful for quick cell evaluation but cannot be used in LCI functions that require a LCH_CELL object. This lslong can be evaluated using the CellcoordToSheetNum, CellcoordToRowNum, and CellcoordToColNum macros shown in the Example for this function.
Note These macros add 1 to the value because cellcoord is zero-based, not 1-based as in Lcixxx calls.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvGetArgCellCoord
(LCH_EVARG hArg,
lsshort ArgIndex,
lptr(lslong) lpValInt)
Arguments
hArg Argument context handle for the specified event passed to event handler. It is used to get strings, arrays, or objects. Any objects obtained with a callback function should be destroyed with the standard object destructor prior to exiting the handler.
ArgIndex Specified only for events that have multiple arguments of the same type; otherwise, it is ignored.
lpValInt Pointer to an lslong in which to store the cell coordinate.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_INVALID_ARG_FLAGS »Page
Example
#include "lcicomn.h"
#include "lcievent.h"
. . .
typedef lslong cellcoord;
#define CellcoordToRowNum(cc) (*((lptr(lushort))&(cc))+1)
#define CellcoordToSheetNum(cc) (*((lptr(lubyte))&(cc)+2)+1)
#define CellcoordToColNum(cc) (*((lptr(lubyte))&(cc)+3)+1)
. . .
/* LCE_MOUSE_CLICK_CELL event handler */
LCT_STATUS LCI_CALL CellClickedHandler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg1)
{
LCT_STATUS Status;
lushort RowNum;
lushort SheetNum;
lushort ColNum;
cellcoord MouseClickedHere;
/* Get cell mouse was clicked on. */
Status = LciEvGetArgCellCoord( hEvArg, 0, &MouseClickedHere );
. . .
RowNum = CellcoordToRowNum(MouseClickedHere);
SheetNum = CellcoordToSheetNum(MouseClickedHere);
ColNum = CellcoordToColNum(MouseClickedHere);
. . .
return (Status);
} /* End of CellClickedHandler */
Definition
The LciEvGetArgInt function retrieves an lslong.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvGetArgInt
(LCH_EVARG hArg,
lsshort ArgIndex,
lptr(lslong) lpValInt)
Arguments
hArg Argument context handle for the specified event passed to the event handler. It is used to get strings, arrays, or objects. Any objects obtained with a callback function should be destroyed with the standard object destructor prior to exiting the handler.
ArgIndex Specified only for events that have multiple arguments of the same type; otherwise, it is ignored.
lpValInt Pointer to an lslong in which to store the result.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_INVALID_ARG_FLAGS »Page
Example
#include "lcicomn.h"
#include "lcievent.h"
. . .
/* Worksheet Insert Sheet handler function*/
LCT_STATUS LCI_CALL WIS_Handler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg1)
{
LCT_STATUS Status;
. . .
lslong NSheets; /* Interpret as an lushort. */
/* Get number of sheets being inserted in /WIS event. */
Status = LciEvGetArgInt( hEvArg,0, &NSheets );
. . .
return (Status);
} /* End of WISHandler */
Definition
The LciEvGetArgNum function retrieves an lfloat10.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvGetArgNum
(LCH_EVARG hArg,
lsshort ArgIndex,
lptr(lfloat10) lpValNum)
Arguments
hArg Argument context handle for the specified event passed to the event handler. It is used to get strings, arrays, or objects. Any objects obtained with a callback function should be destroyed with the standard object destructor prior to exiting the handler.
ArgIndex Specified only for events that have multiple arguments of the same type; otherwise, it is ignored.
lpValNum Pointer to an lfloat10 in which to store the result.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_INVALID_ARG_FLAGS »Page
Example
#include "lcicomn.h"
#include "lcievent.h"
. . .
/* Data Fill handler function */
LCT_STATUS LCI_CALL DataFillHandler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg1)
{
LCT_STATUS Status;
. . .
/* Get values for Data Fill event. */
lfloat10 StartVal;
lfloat10 StepVal;
lfloat10 StopVal;
Status = LciEvGetArgNum( hEvArg, 0, &StartVal );
. . .
Status = LciEvGetArgNum( hEvArg, 1, &StepVal );
. . .
Status = LciEvGetArgNum( hEvArg, 2, &StoptVal );
. . .
return (Status);
} /*End of DataFillHandler() */
Definition
The LciEvGetArgRange function constructs and retrieves a range object.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvGetArgRange /* This is a CONSTRUCTOR */
(LCH_EVARG hArg,
lsshort ArgIndex,
lptr(LCH_RANGE) lpRange)
Arguments
hArg Argument context handle for the specified event passed to event handler. It is used to get strings, arrays, or objects. Any objects obtained with a callback function should be destroyed with the standard object destructor prior to exiting the handler.
ArgIndex Specified only for events that have multiple arguments of the same type; otherwise, it is ignored.
lpRange Pointer to storage in which to store the range object handle.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_INVALID_ARG_FLAGS »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
#include "lcievent.h"
. . .
/* Range Justify event handler */
LCT_STATUS LCI_CALL RJ_Handler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg1)
{
LCT_STATUS Status;
. . .
LCH_RANGE JustifyRange;
/* Get target range for RangeJustify event. */
Status = LciEvGetArgRange( hEvArg, 0, &JustifyRange );
. . .
/* Destroy the range. */
LciRgDestroy(&JustifyRange);
return (Status);
} /* End of RJ_Handler */
Definition
The LciEvGetArgStr function retrieves a string.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvGetArgStr
(LCH_EVARG hArg,
lsshort ArgIndex,
lsshort BufLen,
lptr(lmbcs) lpValStr)
Arguments
hArg Argument context handle for the specified event passed to event handler. It is used to get strings, arrays, or objects. Any objects obtained with a callback function should be destroyed with the standard object destructor prior to exiting the handler.
ArgIndex Specified only for events that have multiple arguments of the same type; otherwise, it is ignored.
BufLen Length of buffer for lpValStr.
lpValStr Pointer to a lmbcs string in which to store the result.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_INVALID_ARG_FLAGS »Page
Example
#include "lcicomn.h"
#include "lcievent.h"
. . .
/* RangeNameNoteCreate handler function*/
LCT_STATUS LCI_CALL RNNC_Handler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg1)
{
LCT_STATUS Status;
. . .
/* Get note for /RangeNameNoteCreate event. */
lmbcs Note[100};
Status = LciEvGetArgStr( hEvArg, 0, 100, Note );
return (Status);
} /* End of RNNC_Handler */
Definition
The LciEvGetErrCode function is used by event handlers to retrieve the error code, if any, returned by prior event handlers or encountered in the 1-2-3 event itself.
If a previous handler (or the operation or its replacer itself if the event is after) signals an error, the TimeFlags argument of the event handler call will have bit LCI_EV_IS_ERR_MSK set. The present call can be used to find out what that error is. If a before handler signals an error, all subsequent before handlers and all after handlers will be notified, and the operation will be suppressed, but not replaced (except certain operations that proceed regardless). If the operation itself (or its replacer) signals an error, all after handlers will be notified. Errors raised by after handlers are suppressed for this purpose.
If a before handler signals that it wishes to replace an event, that fact will also be reported to subsequent handlers by this call, but the LCI_EV_IS_ERR_MSK is not set for this status.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvGetErrCode
(LCH_EVARG hArg)
Argument
hArg Argument context handle for the specified event passed to event handler. It is used to get strings, arrays, or objects. Any objects obtained with a callback function should be destroyed with the standard object destructor prior to exiting the handler.
Returns
LCS_SUCCESS »Page
LCS_EVENT_MSG »Page
LCS_EVENT_MULTI_ERR »Page
LCS_OUT_OF_MEMORY »Page
LCS_EVENT_REPLACE »Page
The values for LCT_STATUS returned by the LciGetErrCode function are summarized below.
LCS_SUCCESS
All prior handlers and the event executed successfully.
LCS_EVENT_MSG
Only one prior handler returned an error, and the error was a custom error string. (A custom error string is one that you write to address an error that the handler may encounter.)
LCS_EVENT_MULTI_ERR
More than one error was returned by some combination of handlers and the event. None of the errors was LCS_OUT_OF_MEMORY.
LCS_OUT_OF_MEMORY
One or more prior handlers and/or the event returned an LCS_OUT_OF_MEMORY error. LCS_OUT_OF_MEMORY supersedes all other errors returned by handlers.
LCS_xxx or other 1-2-3 error
Only one prior handler or the event returned an error. The error returned can be any LCS_xxx value listed in LCIERROR.H or a core 1-2-3 error in which case the high-order word of LCT_STATUS is non-zero.
LCS_EVENT_REPLACE
A prior before handler has signalled that it wishes to replace the event. If the current handler is an after handler, the replacement has already occurred and was otherwise successful. If the current handler is a before handler, it will be unable to replace the operation itself, but the replacement will occur after all before handlers have been called. Actual errors reported by the replacer or other before handlers supercede this status.
If you want to retrieve the error message text associated with the returned error code, use the LciUtErrorText »Page utility library function.
Example
#include "lcicomn.h"
#include "lcievent.h"
. . .
/* File Retrieve/Open Handler */
LCT_STATUS LCI_CALL FRO_Handler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg1)
{
LCT_STATUS Status;
/* Check for errors in prior event handlers;
a non-zero value in this test means an error. */
if (EventFlags & LCI_EV_IS_ERR_MSK){
/* Get the error code, handle OUT OF MEMORY. */
if ((LciEvGetErrCode(hEvArg)) == LCS_OUT_OF_MEMORY){
/* Out of memory processing */
. . .
}
}
. . .
return (Status);
} /* End of FRO_Handler */
Definition
The LciEvGetParsedName function retrieves a filename as a string along with offsets into the string that are useful for parsing. The parse information is platform-specific, so the offset pointer should be defined appropriately. For DOS systems, the offset pointer is a pointer to a LCT_DOSNAME_INFO structure, defined in the C include file LCIEVENT.T. This offset pointer should be declared as a lptr(LCT_DOSNAME_INFO) and should be cast as a lptr(lushort) on the function call. If the offsets are not desired, use LciEvGetArgStr »Page to get a filename as a string only.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvGetParsedName
(LCH_EVARG hArg,
lsshort ArgIndex,
lsshort BufLen,
lptr(lmbcs) lpValStr,
lptr(lushort) lpOffset)
Arguments
hArg Argument context handle for the specified event passed to event handler. It is used to get strings, arrays, or objects. Any objects obtained with a callback function should be destroyed with the standard object destructor prior to exiting the handler.
ArgIndex Specified only for events that have multiple arguments of the same type; otherwise, it is ignored.
BufLen Length of buffer for string.
lpValStr Pointer to a lmbcs string in which to store the filename.
lpOffset Pointer to an lushort (or LCT_DOSNAME_INFO for DOS systems) in which to store the offsets for parsing the filename.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_INVALID_ARG_FLAGS »Page
Example
#include "lcicomn.h"
#include "lcievent.h"
. . .
/* LCE_FILE_FRO_NAME event handler */
LCT_STATUS LCI_CALL FRO_Handler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg1)
{
LCT_STATUS Status;
. . .
lmbcs FileName[LCI_MAX_FILENAME_LEN];
LCT_DOSNAME_INFO OffsetInfo;
/* Get target filename of /Worksheet Delete File event. */
Status = LciEvGetParsedName( hEvArg, 0, LCI_MAX_FILENAME_LEN,
FileName, (lptr(lushort))(&OffsetInfo));
. . .
return (Status);
} /*End of FRO_Handler */
Definition
Displays a custom error message to the user. Event handlers returning LCS_EVENT_MSG must post an error message with this function.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvPostErrMsg
(LCH_EVARG hArg,
lptr(lmbcs) lpMessage)
Arguments
hArg Argument context handle for the specified event passed to event handler. It is used to get strings, arrays, or objects. Any objects obtained with a callback function should be destroyed with the standard object destructor prior to exiting the handler.
lpMessage Pointer to the null-terminated lmbcs error message string that the handler is returning. If the calling event handler is the only one returning an error, then 1-2-3 displays the error message contained in lpMessage to the user. Any error string that exceeds 79 characters is truncated.
Note If more than one handler function returns an error, 1-2-3 displays an error message to the user that more than one error has occurred.
Returns
None
Example
#include "lcicomn.h"
#include "lcievent.h"
. . .
/* Block all File Saves. */
LCT_STATUS LCI_CALL FileSaveHandler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg1)
{
LCT_STATUS Status;
/* Test event timing. */
switch(TimeFlags & LCI_EV_STATE_MSK){
/* Request to block. */
case (LCI_EV_BEFORE):
Status = LCI_EVENT_REPLACE;
break;
/* OK, we are blocking now. */
case (LCI_EV_REPLACER):
Status = LciEvPostErrMsg( hEvArg, "File Save Not Allowed" );
Status = LCS_EVENT_MSG;
break;
. . .
} /* End switch on timing. */
. . .
return (Status);
} /*End of FileSaveHandler */
Definition
The LciEvSetArgInt function sets the value of an lslong. Replace handlers that can substitute 123 supplied values for event data with their own use this function.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvSetArgInt
(LCH_EVARG hArg,
lsshort ArgIndex,
lslong ValInt)
Arguments
hArg Argument context handle for the specified event passed to event handler It is used to get strings, arrays, or objects. Any objects obtained with a callback function should be destroyed with the standard object destructor prior to exiting the handler.
ArgIndex Specified only for events that have multiple arguments of the same type; otherwise, it is ignored.
ValInt An lslong which contains the desired value.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_INVALID_ARG_FLAGS »Page
Example
#include "lcicomn.h"
#include "lcievent.h"
. . .
/* Keyboard event handler */
LCT_STATUS LCI_CALL KBD_Handler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg1)
{
LCT_STATUS Status;
lmbcs MyKey = ':';
. . .
switch (EventId){ /* Test event we are handling. */
case (LCE_KBDSTUFFHI):
/* Replace the key for this event. */
Status = LciEvSetArgInt(hEvArg, 0,
(lslong)(MyKey));
break;
. . .
}
. . .
return (Status);
} /*End of Keyboard event handler */
Definition
The LciEvSetArgStr function sets the value of a string. Replace handlers that can substitute 123 supplied values for event data with their own use this function.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvSetArgStr
(LCH_EVARG hArg,
lsshort ArgIndex,
lptr(lmbcs) lpValStr)
Arguments
hArg Argument context handle for the specified event passed to event handler. It is used to get strings, arrays, or objects. Any objects obtained with a callback function should be destroyed with the standard object destructor prior to exiting the handler.
ArgIndex Specified only for events that have multiple arguments of the same type; otherwise, it is ignored.
lpValStr Pointer to the null-terminated lmbcs string that contains the desired replacement string.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_INVALID_ARG_FLAGS »Page
LCS_NULL_HANDLE »Page
Example
#include "lcicomn.h"
#include "lcievent.h"
. . .
/* System event replace handler */
LCT_STATUS LCI_CALL SystemHandler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg1)
{
LCT_STATUS Status;
. . .
lptr(lmbcs) CmdLine = "Dir";
/* Replace command suppied with System event.*/
Status = LciEvSetArgStr(hEvArg, 0, CmdLine);
. . .
return (Status);
} /* End of SystemHandler */
Definition
The LciEvSetArgRange function sets a range object. Replace handlers that can substitute 123 supplied values for event data with their own use this function.
Format
#include "lcicomn.h"
#include "lcievent.h"
LCT_STATUS LCI_CALL LciEvSetArgRange
(LCH_EVARG hArg,
lsshort ArgIndex,
LCH_RANGE hRange)
Arguments
hArg Argument context handle for the specified event passed to event handle. It is used to get strings, arrays, or objects. Any objects obtained with a callback function should be destroyed with the standard object destructor prior to exiting the handler.
ArgIndex Specified only for events that have multiple arguments of the same type; otherwise, it is ignored.
hRange Range object.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_INVALID_ARG_FLAGS »Page
LCS_NULL_HANDLE »Page
Example
#include "lcicomn.h"
#include "lcievent.h"
. . .
/* Range Preselect event handler */
LCT_STATUS LCI_CALL RangePreselectHandler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg1)
{
LCT_STATUS Status;
LCH_RANGE OurRange;
. . .
Status = LciRgConstructAddr(Context,"A:A1..J12",&OurRange);
. . .
/* Supply a Range preset for LCE_RANGE_PRESET event.*/
Status = LciEvSetArgRange( hEvArg, 0, OurRange);
. . .
LciRgDestroy(&OurRange);
return (Status);
} /* End of RangePreselectHandler */
Event Description
LCE_DATA_DD »Page Data Distribution calculates the frequency distribution of the values in a range.
LCE_DATA_DECG »Page Data External Create Table in the GUI menu and /Data External Create Go in the Lotus Classic menu create an external table.
LCE_DATA_DED »Page Data External Disconnect in the GUI menu and /Data External Delete in the Lotus Classic menu delete a table from an external database.
LCE_DATA_DEOC »Page Data External Send Command in the GUI menu and /Data External Other Command in the Lotus Classic menu send a command to a database management program.
LCE_DATA_DEOT »Page /Data External Other Translation specifies the native database character set (Lotus Classic menu only).
LCE_DATA_DER »Page /Data External Reset stops using a table in an external database (Lotus Classic menu only).
LCE_DATA_DF »Page Data Fill fills a range with a sequence of values.
LCE_DATA_DMI »Page Data Matrix Invert creates the inverse of a matrix.
LCE_DATA_DMM »Page Data Matrix Multiply multiplies two ranges as matrices.
LCE_DATA_DPG »Page Data Parse Go parses labels in the input column and places them in the output range.
LCE_DATA_DPR »Page Data Parse Reset clears input column and output range.
LCE_DATA_DQDD »Page Data Query Del Delete deletes records and closes up spaces in input range.
LCE_DATA_DQE »Page Data Query Extract copies to output range all records that match criteria.
LCE_DATA_DQF »Page Data Query Find highlights each record that matches criteria.
LCE_DATA_DQME »Page Data Query Modify Extract copies to the output range all records that match criteria.
LCE_DATA_DQMI »Page Data Query Modify Insert inserts records from the output range into the input range.
LCE_DATA_DQMR »Page Data Query Modify Replace replaces records in the input range with extracted records.
LCE_DATA_DQR »Page Data Query Reset clears input, criteria, and output ranges.
LCE_DATA_DQU »Page Data Query Extract with the Unique box checked in the GUI menu and /Data Query Unique in the Lotus Classic menu copy to output range all nonduplicate records that match criteria.
LCE_DATA_DRG »Page Data Regression Go calculates a data regression for the specified range.
LCE_DATA_DRR »Page Data Regression Reset clears the X range, Y range, output range, and resets Intercept to Compute.
LCE_DATA_DSG »Page Data Sort Go sorts data and returns to READY mode.
LCE_DATA_DSR »Page Data Sort Reset clears data range and sort keys.
LCE_DATA_DTLG »Page /Data Table Labeled Go calculates the table (Lotus Classic menu only).
LCE_DATA_DTR »Page Data Table Reset clears table ranges and input cells for all data tables.
LCE_DATA_DT1 »Page What-If Table 1-Way in the GUI menu and /Data Table 1 in the Lotus Classic menu create a table of values with one input cell and one or more dependent formulas.
LCE_DATA_DT2 »Page What-If Table 2-Way in the GUI menu and /Data Table 2 in the Lotus Classic menu create a table of values with two input cells and one dependent formula.
LCE_DATA_DT3 »Page What-If Table 3-Way in the GUI menu and /Data Table 3 in the Lotus Classic menu create a table of values with three input cells and one dependent formula.
$242 LCE_DATA_DD Data Distribution
Data Distribution calculates the frequency distribution of the values in a range.
Data Description
LCH_RANGE valuesrange valuesrange is the range containing the values.
LCH_RANGE binrange binrange is the range containing the specified numeric intervals.
$243 LCE_DATA_DECG Data External Create Go
Data External Create Table in the GUI menu and /Data External Create Go in the Lotus Classic menu create an external table.
Data Description
lptr(lmbcs) lpdbname lpdbname is the database name.
lptr(lmbcs) lptablename lptablename is the table name.
$244 LCE_DATA_DED Data External Delete
Data External Disconnect in the GUI menu and /Data External Delete in the Lotus Classic menu delete a table from an external database.
Data Description
lptr(lmbcs) lpdbname lpdbname is the database name.
$245 LCE_DATA_DEOC Data External Other Command
Data External Send Command in the GUI menu and /Data External Other Command in the Lotus Classic menu send a command to a database management program.
Data Description
lptr(lmbcs) lpdbname lpdbname is the database name.
lptr(lmbcs) lpcommand lpcommand is the command string.
$246 LCE_DATA_DEOT Data External Other Translation
/Data External Other Translation specifies the native database character set (Lotus Classic menu only).
Data Description
lptr(lmbcs) lpdbname lpdbname is the database name.
lslong codepage codepage specifies the native codepage of the database.
$247 LCE_DATA_DER Data External Reset
/Data External Reset stops using a table in an external database (Lotus Classic menu only).
Data
None
$248 LCE_DATA_DF Data Fill
Data Fill fills a range with a sequence of values.
Data Description
LCH_RANGE fillrange fillrange is the range to fill.
lfloat10 start start is the start value.
lfloat10 step step is the step value.
lfloat10 stop stop is the stop value.
$249 LCE_DATA_DMI Data Matrix Invert
Data Matrix Invert creates the inverse of a matrix.
Data Description
LCH_RANGE invertrange invertrange is the range to invert.
LCH_RANGE outputrange outputrange is the destination range.
$250 LCE_DATA_DMM Data Matrix Multiply
Data Matrix Multiply multiplies two ranges as matrices.
Data Description
LCH_RANGE multrange1 multrange1 is the first range.
LCH_RANGE multrange2 multrange2 is the second range.
LCH_RANGE outputrange outputrange is the destination range.
$251 LCE_DATA_DPG Data Parse Go
Data Parse Go parses labels in the input column and places them in the output range.
Data
None
$252 LCE_DATA_DPR Data Parse Reset
Data Parse Reset clears input column and output range.
Data
None
$253 LCE_DATA_DQDD Data Query Del Delete
Data Query Del Delete deletes records and closes up spaces in input range.
Data
None
$254 LCE_DATA_DQE Data Query Extract
Data Query Extract copies to output range all records that match criteria.
Data
None
$255 LCE_DATA_DQF Data Query Find
Data Query Find highlights each record that matches criteria.
Data
None
$256 LCE_DATA_DQME Data Query Modify Extract
Data Query Modify Extract copies to the output range all records that match criteria.
Data
None
$257 LCE_DATA_DQMI Data Query Modify Insert
Data Query Modify Insert inserts records from the output range into the input range.
Data
None
$258 LCE_DATA_DQMR Data Query Modify Replace
Data Query Modify Replace replaces records in the input range with extracted records.
Data
None
$259 LCE_DATA_DQR Data Query Reset
Data Query Reset clears input, criteria, and output ranges.
Data
None
$260 LCE_DATA_DQU Data Query Unique
Data Query Extract with the Unique box checked in the GUI menu and /Data Query Unique in the Lotus Classic menu copy to output range all nonduplicate records that match criteria.
Data
None
$261 LCE_DATA_DRG Data Regression Go
/Data Regression Go calculates a data regression for the specified range.
Data
None
$262 LCE_DATA_DRR Data Regression Reset
Data Regression Reset clears the X range, Y range, output range, and resets intercept to compute.
Data
None
$263 LCE_DATA_DSG Data Sort Go
Data Sort Go sorts data and returns to READY mode.
Data
None
$264 LCE_DATA_DSR Data Sort Reset
Data Sort Reset clears data range and sort keys.
Data
None
$265 LCE_DATA_DTLG Data Table Labeled Go
/Data Table Labeled Go calculates the table (Lotus Classic menu only).
Data
None
$266 LCE_DATA_DTR Data Table Reset
Data Table Reset clears table ranges and input cells for all data tables.
Data
None
$267 LCE_DATA_DT1 Data Table 1
Selecting the What-If Table 1-Way in the GUI menu and /Data Table1 in the Lotus Classic menu create a table of values with one input cell and one or more dependent formulas.
Data Description
LCH_RANGE tablerange tablerange is the table destination range.
LCH_RANGE inputcell1 inputcell1 is the input cell.
$268 LCE_DATA_DT2 Data Table 2
Selecting the What-If Table 2-Way in the GUI menu and /Data Table2 in the Lotus Classic menu create a table of values with two input cells and one dependent formula.
Data Description
LCH_RANGE tablerange tablerange is the table destination range.
LCH_RANGE inputcell1 inputcell1 is the first input cell.
LCH_RANGE inputcell2 inputcell2 is the second input cell.
$269 LCE_DATA_DT3 Data Table 3
Selecting the What-If Table 3-Way in the GUI menu and /Data Table3 in the Lotus Classic menu create a table of values with three input cells and one dependent formula.
Data Description
LCH_RANGE tablerange tablerange is the table destination range.
LCH_RANGE formulacell formulacell is the dependent formula.
LCH_RANGE inputcell1 inputcell1 is the first input cell.
LCH_RANGE inputcell2 inputcell2 is the second input cell.
LCH_RANGE inputcell3 inputcell3 is the third input cell.
Event Description
LCE_DISP_CP_CONTENTS »Page Occurs when 1-2-3 displays the contents and format of a cell in the control panel.
LCE_GET_CELL_PREFIX »Page Occurs when 1-2-3 prepares to combine the current cell pointer address, format information, and contents into a buffer for display.
LCE_WINDOW_SHOW »Page Occurs when 1-2-3 updates the worksheet window.
LCE_DISP_MENU_PANEL »Page Occurs when 1-2-3 updates the control panel due to a menu, prompt. or list display.
$272 LCE_DISP_CP_CONTENTS
DisplayCellContents occurs when 1-2-3 displays the contents and format of a cell in the control panel.
Only before handlers are valid for DisplayCellContents. 1-2-3 ignores DisplayCellContents handler errors.
Data Description
LCH_CELL cellpointer cellpointer identifies the current cell.
lslong right_margin (Arg1) right_margin
$273 LCE_GET_CELL_PREFIX
GetCellPrefix occurs when 1-2-3 prepares to combine the current cell pointer address, format information, and contents into a buffer for display. A handler for this event is passed the buffer when it contains the current cell address only. 1-2-3 will later add the format information and contents to the buffer.
Only before handlers are valid for GetCellPrefix. 1-2-3 ignores GetCellPrefix handler errors.
Data Description
LCH_CELL cellpointer cellpointer identifies the current cell.
lptr(lmbcs) lpdisplaybuffer lpdisplaybuffer holds the contents of the 1-2-3 display buffer for the current cell. The buffer contains the cell address; for example, A:A1.
$274 LCE_WINDOW_SHOW
WindowShow is triggered when 1-2-3 updates the worksheet window.
Data
None
$275 LCE_DISP_MENU_PANEL
LCE_DISP_MENU_PANEL occurs when 1-2-3 refreshes the control panel due to a menu prompt or list display. A handler can replace the panel state.
Data Description
lslong panel_state See LCIEVENT.T for a complete list of LCE_PNL_xxx states.
Event Description
LCE_FILE_FAL »Page File Administration Update Links in the GUI menu and /File Admin Link-Refresh calculates formulas in active files that refer to data in other active files or files on disk.
LCE_FILE_FCA »Page File Combine Add adds numeric data from a worksheet file on disk to numbers or blank cells in the current file.
LCE_FILE_FCC »Page File Combine Copy copies specified data from a worksheet file on disk to the current file.
LCE_FILE_FCS »Page File Combine Subtract subtracts numeric data in a worksheet file on disk from numbers or blank cells in the current file.
LCE_FILE_FE »Page /File Erase erases a file on disk (Lotus Classic menu only).
LCE_FILE_FIN »Page File Import Numbers imports data from a text file.
LCE_FILE_FIT »Page File Import Text imports data from a text file.
LCE_FILE_FNA »Page /File New After creates a new worksheet file after the current file (Lotus Classic menu only).
LCE_FILE_FNB »Page /File New Before creates a new worksheet file before the current file (Lotus Classic menu only).
LCE_FILE_FOA »Page File Open After reads a worksheet file from disk into memory and places it behind the current file in the Files In Memory List (/FLA). It is triggered by both the File Open GUI menu command and the /FOA Lotus Classic menu command. It is not triggered the very first time you use the File Open GUI command if you have not yet modified the untitled worksheet that appears at startup.
LCE_FILE_FOB »Page File Open Before reads a worksheet file from disk into memory and places it in front of the current file in the Files In Memory List (/FLA). This event is triggered only by the /FOB Lotus Classic menu command, not by the GUI File Open command.
LCE_FILE_FRO_NAME »Page File Retrieve and Open reads a worksheet file from disk into memory. It is triggered by the GUI File Open command and the /File Retrieve, /File Open After, and /File Open Before commands from the Lotus Classic menu. A replace handler can override the filename.
LCE_FILE_FR »Page File Retrieve reads a worksheet file from disk into memory. It is triggered the first time the GUI File Open command is issued if the untitled worksheet has not yet been modified and anytime the /File Retrieve command is issued from the Lotus Classic menu.
LCE_FILE_FS »Page File Save and File Save As in the GUI menu and /File Save in the Lotus Classic menu save worksheet data and settings to a worksheet file on disk.
LCE_FILE_FXF »Page File Xtract Formulas extracts a range of data, including formulas and worksheet settings, by copying data from an active file and saving it to a worksheet file on disk.
LCE FILE FXV »Page File Xtract Values extracts a range of data, including labels and numbers, from a worksheet file in memory and copies the data to a worksheet file in memory and copies the data to a worksheet file on disk.
LCE_FILE_WDF »Page \Worksheet Delete File deletes an active file from memory without erasing the corresponding file on disk (Lotus Classic menu only).
$278 LCE_FILE_FAL File Admin Link-Refresh
File Administration Update Links in the GUI menu and /File Admin Link-Refresh in the Lotus Classic menu recalculate formulas in active files that refer to data in other active files or files on disk.
Data
None
$279 LCE_FILE_FCA File Combine Add
File Combine Add adds numeric data from a worksheet file on disk to numbers or blank cells in the current file.
Data Description
lptr(lmbcs) lpfilename lpfilename holds the file that is the source for FCA.
LCH_CELL targetcell targetcell holds the cell that is the target of FCA.
LCH_RANGE sourcerange sourcerange contains the range in the file from which FCA is combining information. (If FCA is combining an entire file, sourcerange is the active range in the file from which FCA is combining information.)
$280 LCE_FILE_FCC File Combine Copy
File Combine Copy copies specified data from a worksheet file on disk to the current file.
Data Description
lptr(lmbcs) lpfilename lpfilename holds the file that is the source for FCC.
LCH_CELL targetcell targetcell holds the cell that is the target of FCC.
LCH_RANGE sourcerange sourcerange contains the range in the file from which FCC is combining information. (If FCC is combining an entire file, sourcerange is the active range in the file from which FCC is combining information.)
$281 LCE_FILE_FCS File Combine Subtract
File Combine Subtract subtracts numeric data in a worksheet file on disk from numbers or blank cells in the current file.
Data Description
lptr(lmbcs) lpfilename lpfilename holds the file that is the source for FCS.
LCH_CELL targetcell targetcell holds the cell that is the target of FCS.
LCH_RANGE sourcerange sourcerange contains the range in the file from which FCS is combining information. (If FCS is combining an entire file, sourcerange is the active range in the file from which FCS is combining information.)
$282 LCE_FILE_FE File Erase
/File Erase erases a file on disk (Lotus Classic menu only).
Data Description
lptr(lmbcs) lpfilename lpfilename holds the file that is the target of FE.
$283 LCE_FILE_FIN File Import Numbers
File Import Numbers imports data from a text file. FIN interprets data in one of two ways: as a combination of labels and numbers if the source file contains delimiters; or as numbers only if the source file does not contain delimiters.
Data Description
lptr(lmbcs) lpfilename lpfilename holds the file that is the source for FIN. (Note that the target of FIN is the current file.)
$284 LCE_FILE_FIT File Import Text
File Import Text imports data from a text file. FIT interprets each line of data as a separate label and places labels into a single column of the current worksheet.
Data Description
lptr(lmbcs) lpfilename lpfilename holds the file that is the source for FIT. (Note that the target of FIT is the current file.)
$285 LCE_FILE_FNA File New After
/FNA creates a new worksheet file after the current file (Lotus Classic menu only).
Data Description
lptr(lmbcs) lpfilename lpfilename holds the name of the file that is the target of FNA.
$286 LCE_FILE_FNB File New Before
/File New Before creates a new worksheet file before the current file (Lotus Classic menu only).
Data Description
lptr(lmbcs) lpfilename lpfilename holds the name of the file that is the target of FNB.
$287 LCE_FILE_FOA /File Open After
File Open After reads a worksheet file from disk into memory and places it behind the current file in the Files In Memory List (/FLA). It is triggerd by both the File Open GUI menu command and the /FOA Lotus Classic menu command. It is not triggered the very first time you use the File Open GUI command if you have not yet modified the untitled worksheet that appears at startup.
Data Description
lptr(lmbcs) lpfilename lpfilename holds the name of the file that is the target of FOA.
Note Registered before handlers for the LCE_FILE_FR, LCE_FILE_FOA, and LCE_FILE_FOB events are called before the contents of the file are read in, but after the file is initially opened for validation.
Before handlers wishing to gain control before any file processing occurs should be registered for the LCE_FILE_FRO_NAME event instead of this one.
$288 LCE_FILE_FOB File Open Before
File Open Before reads a worksheet file from disk into memory and places it in front of the current file in the Files In Memory List (/FLA). This event is triggered only by the /FOB Lotus Classic menu command, not by the GUI File Open menu command.
Data Description
lptr(lmbcs) lpfilename lpfilename holds the name of the file that is the target of FOB.
Note Registered before handlers for the LCE_FILE_FR, LCE_FILE_FOA, and LCE_FILE_FOB events are called before the contents of the file are read in, but after the file is initially opened for validation.
Before handlers wishing to gain control before any file processing occurs should be registered for the LCE_FILE_FRO_NAME event instead of this one.
$289 LCE_FILE_FR File Retrieve
File Retrieve reads a worksheet file from disk into memory. It is triggered the first time the GUI File Open menu command is issued if the untitled worksheet has not yet been modified and anytime the /File Retrieve command in the Lotus Classic menu is issued.
Data Description
lptr(lmbcs) lpfilename lpfilename holds the file that is the target of FR.
Note Registered before handlers for the LCE_FILE_FR, LCE_FILE_FOA, and LCE_FILE_FOB events are called before the contents of the file are read in, but after the file is initially opened for validation.
Before handlers wishing to gain control before any file processing occurs should be registered for the LCE_FILE_FRO_NAME event instead of this one.
$290 LCE_FILE_FRO_NAME File Retrieve & Open
File Retrieve and Open reads a worksheet file from disk into memory. It is triggered by the GUI File Open menu command and the /File Retrieve, /File Open After, and /FiIe Open Before commands in the Lotus Classic menu. A replace handler can override the filename.
Data Description
lptr(lmbcs) lpfilename lpfilename holds the file that is the target of retrieve or open.
Note Replace handlers must actually be registered with the LCI_EV_BEFORE timing value, not LCI_EV_REPLACER. Handlers for this event are never called with the LCI_EV_REPLACER timing value.
$291 LCE_FILE_FS File Save
File Save and File Save As in the GUI menu and /File Save in the Lotus Classic menu save worksheet data and settings to a worksheet file on disk.
Data Description
lptr(lmbcs) lpfilename lpfilename holds the file that is the target of FS.
lslong save_mode (Arg1) save_mode values in LCIEVENT.T
$292 LCE_FILE_FXF File Xtract Formulas
File Xtract Formulas extracts a range of data, including formulas and worksheet settings, by copying data from an active file and saving it to a worksheet file on disk.
Data Description
lptr(lmbcs) lpfilename lpfilename holds the worksheet file on disk that is the target of FXF.
LCH_RANGE sourcerange sourcerange holds the range in the current file from which FXF will extract data.
lslong backupflag backupflag is true if the backup file will be, or was, created on disk (because the target file already exists); otherwise, backupflag is false.
$293 LCE_FILE_FXV File Xtract Values
File Xtract Values extracts a range of data, including labels and numbers, from a worksheet file in memory and copies the data to a worksheet file on disk. FXV evaluates any formulas in the source range and copies the resultant values, not the formulas themselves.
Data Description
lptr(lmbcs) lpfilename lpfilename holds the worksheet file on disk that is the target of FXV.
LCH_RANGE sourcerange sourcerange holds the range in the current file from which FXV will extract data.
lslong backupflag backupflag is true if the backup file will be, or was, created on disk (because the target file already exists); otherwise, backupflag is false.
$294 LCE_FILE_WDF Worksheet Delete File
/Worksheet Delete File deletes an active file from memory without erasing the corresponding file on disk. Handlers for this event are not triggered if only one file exists in memory because 1-2-3 treats the deletion as a workspace erase (Lotus Classic menu only).
Data Description
lptr(lmbcs) lpfilename lpfilename holds the file that WDF deletes from memory.
lslong firstsheet (Arg1) firstsheet
lslong lastsheet lastsheet
lslong depth depth
Note Sheet numbers, row numbers, and column numbers returned to event handlers are zero-based. To use them with Lci functions, add 1 to their values.
Event Description
LCE_FMT_CLEAR_FMTS »Page Occurs when 1-2-3 clears the format data for worksheets.
LCE_FMT_MOVE_FMTS »Page Occurs when 1-2-3 moves a range format data to another range.
LCE_FMT_SET_CELL_FMT »Page Sets a cell format.
LCE_FMT_RF_FMTS »Page Sets a cell range.
$297 LCE_FMT_CLEAR_FMTS
FormatClearFormats occurs when 1-2-3 clears the format data for worksheets, for example, during /Worksheet Erase Yes or /File Retrieve.
Data Description
lslong firstsheet (Arg1) firstsheet identifies the first worksheet whose formats are cleared.
lslong lastsheet lastsheet identifies the last worksheet whose formats are cleared. (lastsheet refers to the worksheet position in memory.)
Note Sheet numbers, row numbers, and column numbers returned to event handlers are zero-based. To use them with Lci functions, add 1 to their values.
$298 LCE_FMT_MOVE_FMTS
FormatMoveFormats occurs when 1-2-3 moves range format data to another range, for example, during /Move.
Data Description
LCH_CELL upperleftsource upperleftsource indicates the cell in the upper left corner of the source range.
LCH_CELL lowerrightsource lowerrightsource indicates the cell in the lower right corner of the source range.
LCH_CELL targetcell targetcell identifies the cell into which the format is moved.
$299 LCE_FMT_SET_CELL_FMT
FormatSetCellFormats occurs when a cell format is being set. It happens during processing of various commands; for example, it occurs repeatedly as the /Copy command changes the format of each cell in the target range.
Data Description
LCH_CELL targetcell targetcell is the cell whose format is set.
lslong format (Arg1) format is the format to which the cell is set. See LCIEVENT.T for a complete list of LCE_FMT_xxx values.
$300 LCE_FMT_RF_FMTS
FormatRangeFormats occurs when a range format is being set (FormatRangeFormats is triggered during /Range Format.). To determine the format to which the range is being set, use Cell object attributes. See the attributes for Format, Highlight, Protection, Parenthesis, and ColorNegative in the LCI Cell Library.
Data Description
LCH_RANGE formatrange formatrange is the range whose format is being set.
Event Description
LCE_GRAPH_BUILD »Page Triggered when 1-2-3 updates a chart.
LCE_GRAPH_DO_CHART »Page Triggered when 1-2-3 builds a chart.
LCE_GRAPH_GNC »Page Graph Name Create names the current graph (Lotus Classic menu only).
LCE_GRAPH_GND »Page Graph Name Delete deletes a named graph.
LCE_GRAPH_GNR »Page Graph Name Delete All in the GUI menu and /Graph Name Reset in the Lotus Classic menu delete all named graphs in the current file.
LCE_GRAPH_GNU »Page Graph Name Use makes a named graph current (Lotus Classic menu only).
LCE_GRAPH_GV »Page Graph View temporarily removes the worksheet from the screen and displays the current graph on the full screen. GV, {GRAPH} and GRAPH (F10) trigger GV.
$303 LCE_GRAPH_BUILD Update Chart
Triggered whenever 1-2-3 updates a chart.
Data
None
$304 LCE_GRAPH_DO_CHART Build Chart
Triggered whenever 1-2-3 builds a chart.
Data Description
lslong chart_type (Arg1) chart_type (See values in LCIEVENT.)
$305 LCE_GRAPH_GNC Graph Name Create
/Graph Name Create names the current graph (Lotus Classic menu only).
Data Description
lptr(lmbcs) lpgraphname lpgraphname is the name to assign the current graph.
$306 LCE_GRAPH_GND Graph Name Delete
Graph Name Delete deletes a named graph.
Data Description
lptr(lmbcs) lpgraphname lpgraphname is the graph to delete.
$307 LCE_GRAPH_GNR Graph Name Reset
Graph Name Delete All in the GUI menu and /Graph Name Reset in the Lotus Classic menu delete all named graphs in the current file.
Data
None
$308 LCE_GRAPH_GNU Graph Name Use
/Graph Name Use makes a named graph current (Lotus Classic menu only).
Data Description
lptr(lmbcs) lpgraphname lpgraphname is the named graph.
$309 LCE_GRAPH_GV Graph View
Graph View temporarily removes the worksheet from the screen and displays the current graph on the full screen. GV, {GRAPH} and GRAPH (F10) trigger GV. (/Worksheet Window Graph does not trigger GV.)
After the replace handler executes, 1-2-3 waits for the user to enter a keystroke before continuing, as it does when the GV event itself executes.
Data
None
Event Description
LCE_KBDREADY »Page Occurs when 1-2-3 is in READY mode and about to process a character that has no special meaning in READY mode.
LCE_KBDSTUFFHI »Page Occurs just before 1-2-3 receives a character from either a macro or the keyboard.
LCE_KBDSTUFFLO »Page Occurs just before 1-2-3 receives a character from the keyboard.
LCE_KBDTRANSLATEHI »Page Occurs just after 1-2-3 receives a character from a macro, the keyboard, or a handler, and just before 1-2-3 processes the input.
LCE_KBDTRANSLATELO »Page Occurs just after 1-2-3 receives a character from the keyboard or a handler, and just before 1-2-3 processes the input.
$312 LCE_KBDREADY
KeyBoardReady occurs when 1-2-3 is in READY mode and about to process a character from the keyboard that has no special meaning to 1-2-3 for that mode. (Examples of characters that have special meaning in READY mode include the / and arrow keys.)
Only before and replace handlers are valid for KeyBoardReady.
Data Description
lulong LMBCScode (Arg1) LMBCScode is the LMBCS code for the character that 1-2-3 will process.
$313 LCE_KBDSTUFFHI
KeyBoardStuffHi occurs just before 1-2-3 receives a character from either a macro or the keyboard. A replace handler for KeyBoardStuffHi lets you provide the character that 1-2-3 is to process in place of either a macro or the keyboard.
Only before and replace handlers are valid.
Data Description
lulong LMBCScode (Arg1) LMBCScode is the LMBCS code for the character that 1-2-3 will process.
$314 LCE_KBDSTUFFLO
KeyBoardStuffLo occurs just before 1-2-3 receives a character from the keyboard only. A replace handler for KeyBoardStuffLo lets you provide the character that 1-2-3 is to process in place of keyboard input.
Only before and replace handlers are valid.
Data Description
lulong LMBCScode (Arg1) LMBCScode is the LMBCS code for the character that 1-2-3 will process.
$315 LCE_KBDTRANSLATEHI
KeyboardTransHi occurs just after 1-2-3 receives a character from a macro, the keyboard, or a handler, and just before 1-2-3 processes the input. A before handler for KeyboardTransHi lets you examine characters from the keyboard, a macro, or a handler, while a replace handler lets you replace the character.
Only before and replace handlers are valid.
Data Description
lulong LMBCScode (Arg1) LMBCScode is the LMBCS code for the character that 1-2-3 will process.
$316 LCE_KBDTRANSLATELO
KeyboardTransLo occurs just after 1-2-3 receives a character from either a handler or the keyboard, and just before 1-2-3 processes the input. A replace handler for KeyboardTransLo lets you interpret the characters from the keyboard or the handler instead of having 1-2-3 process them.
Only before and replace handlers are valid.
Data Description
lulong LMBCScode (Arg1) LMBCScode is the LMBCS code for the character that 1-2-3 will process.
Event Description
LCE_MACRO_BEGIN »Page Occurs when a macro starts to execute.
LCE_MACRO_END »Page Occurs at the end of a macro execution.
LCE_MACRO_EXEC »Page Occurs when an advanced 1-2-3 macro command executes.
LCE_MACRO_STEP »Page Occurs at a single step in macro STEP mode execution.
$319 LCE_MACRO_BEGIN
MacroBegin occurs when a macro starts to execute. Only before handlers are valid for MacroBegin. 1-2-3 ignores MacroBegin handler errors.
Data Description
lslong offset (Arg1) offset into begincell.
LCH_CELL begincell begincell is the first cell whose contents the Macro Processor executes. begincell is only relevant if external is false.
$320 LCE_MACRO_END
MacroEnd is the end of execution of any macro.
Only before handlers are valid for Macro. 1-2-3 ignores MacroEnd errors.
Data Description
lslong offset (Arg1) offset into endcell.
LCH_CELL endcell endcell is the last cell whose contents the Macro Processor executed.
$321 LCE_MACRO_EXEC
MacroExec occurs when an advanced 1-2-3 macro command executes. This event is not triggered by add-in-defined macro commands.
Only before handlers are valid for MacroExec.
Data Description
lptr(lmbcs) lpcommand lpcommand indicates which advanced command is being executed. See LCIEVENT.T for complete list of LCE_MAC_xxx macro commands.
$322 LCE_MACRO_STEP
MacroStep represents each pause that occurs in macro execution when STEP mode is active.
Only before handlers are valid for MacroStep. 1-2-3 ignores MacroStep handler errors.
Data
None
Event Description
LCE_QUIT »Page Quit ends the current 1-2-3 session and returns control to the operating system or to the Access menu, depending on how 1-2-3 is started.
LCE_SYSTEM »Page Temporarily suspends 1-2-3 and returns control to the operating system. The {SYSTEM} advanced macro command also triggers this event.
$325 LCE_QUIT Quit
Quit ends the current 1-2-3 session and returns control to the operating system or to the Access menu, depending on how 1-2-3 is started.
Only before and replace handlers are valid for Quit.
Data
None
$326 LCE_SYSTEM System
SystemEvent temporarily suspends 1-2-3 and returns control to the operating system so that you can use operating system commands without ending the current 1-2-3 session.
The {SYSTEM} advanced macro command also triggers the SystemEvent event.
Data Description
lptr(lmbcs) lpcommandline lpcommandline holds the command that System issues at the operating prompt.
lslong dosretcode dosretcode is the return code of the most recent system call.
Event Description
LCE_ABORT »Page Occurs when there is an error condition.
LCE_GOTO »Page Occurs when the user presses GOTO (F5) or when the macro command {GOTO} executes.
LCE_GOTO END »Page Occurs when the user presses the END key followed by a cursor movement key, or when the {END} macro command executes.
LCE_MENU »Page Occurs every time a user traverses the Lotus 1-2-3 Classic menu tree.
$329 LCE_ABORT
Abort is the occurrence of any error condition. Only before and after handlers are valid for Abort. 1-2-3 ignores Abort handler errors.
Data Description
lslong errorcode (Arg1) errorcode is the 1-2-3 error code. errorcode is always zero for after handlers.
$330 LCE_GOTO
GoTo is the point in processing immediately after a user presses GOTO (F5). The {GOTO} macro command also triggers GoTo. GoTo after handlers are not triggered when the target of GoTo is a filename only; they are triggered only when the target of GoTo includes a range specification.
Note Only before and after handlers are valid for GoTo. GoTo after handler errors are ignored.
Data Description
lslong rangetarget (Arg1) rangetarget is true if the target of GoTo includes a range; false if the target of GoTo is a filename only. (<<filename>> is a specification that does not include a range; <<filename>>A:A1 or A1 are specifications that do include a range.)
LCH_RANGE targetrange targetrange is the range that is the target of GoTo. targetrange is valid only if rangetarget is true.
lptr(lmbcs) lptargetfilename lptargetfilename is the file that is the target of GoTo. lptargetfilename is valid only if rangetarget is false.
$331 LCE_GOTO_END
GoToEnd is the point in processing immediately after a user pressed END followed by a cursor movement key. The {END} macro command also triggers GoToEnd.
Note Only before handlers are valid for GoToEnd.
Data Description
lslong direction (Arg1) direction. See LCIEVENT.T for a complete list of direction values.
LCH_CELL currcell currcell indicates the current cell.
LCH_CELL nextcell nextcell identifies the cell into which the cellpoint is moved.
$332 LCE_MENU
The Menu event is triggered every time a user traverses the Lotus Classic Menu tree.
Data Description
lslong menuid (Arg1) menuid is the menu node traversed. See LCIEVENT.T for a complete list of LCE_MENU_xxx values.
Event Description
LCE_MOUSE_CLICK_CELL »Page Occurs when the mouse clicks on a cell.
LCE_MOUSE_DRAG_COMPLETE »Page Occurs when a user completes a range select with the mouse.
LCE_MOUSE_CLICK_FRAME »Page Occurs when the mouse clicks on the worksheet frame.
$335 LCE_MOUSE_CLICK_CELL
Triggered when the user clicks the mouse on a cell. Only before handlers are valid.
Data Description
LCH_CELL tocell tocell is where the cellpointer is moved to.
LCH_CELL fromcell fromcell is where the cellpointer is moved from.
$336 LCE_MOUSE_DRAG_COMPLETE
Triggered when the user completes a range selection by dragging with the mouse. Only before handlers are valid.
Data Description
LCH_CELL upperleft upperleft is the upper left cell of the selected range.
LCH_CELL lowerright lowerright is the lower right cell of the selected range.
$337 LCE_MOUSE_CLICK_FRAME
Triggered when the user clicks the mouse on a worksheet frame. The from/to cell coordinates are available. Only before handlers are valid.
Data Description
LCH_CELL tocell tocell is where the cellpointer is moved to.
LCH_CELL fromcell fromcell is where the cellpointer is moved from.
Event Description
LCE_POLL »Page Lets you register a handler to be called as the lowest priority task by the 1-2-3 scheduler.
$340 LCE_POLL
The Poll event lets you register a handler to be called as the lowest priority task by the 1-2-3 scheduler. The scheduler is a routine that cycles through a prioritized list of tasks on an ongoing basis. The current state of the 1-2-3 environment determines the scheduler's agenda of tasks, and therefore the frequency with which Poll handlers execute. Examples of 1-2-3 tasks that the scheduler performs include the following: processing user input, recalculating formulas, printing, performing system cleanup, and refreshing the screen display. It is not possible to regulate the intervals at which a Poll handler is called.
Only before handlers are valid for Poll. 1-2-3 ignores Poll handler errors.
Data
None
Event Description
LCE_PRINT_PEG »Page /Print Encoded Go sends print output to an encoded file.
LCE_PRINT_PFG »Page /Print File Go sends print output to a text file.
LCE_PRINT_PPG »Page /Print Printer Go sends print output directly to a printer.
$343 LCE_PRINT_PEG Print Encoded Go
/Print Encoded Go sends print output to an encoded file.
Data Description
lptr(lmbcs) lpfilename lpfilename is the name of the output file.
$344 LCE_PRINT_PFG Print File Go
/Print File Go sends print output to a text file.
Data Description
lptr(lmbcs) lpfilename lpfilename is the name of the output file.
$345 LCE_PRINT_PPG Print Printer Go
/Print Printer Go sends print output directly to a printer.
Data
None
Event Description
LCE_RANGE_COPY »Page /Copy copies data from a specified source range to a specified target range (Lotus Classic menu only).
LCE_RANGE_FIXUP »Page Updates the coordinates of ranges affected by an adjustment in the worksheet.
LCE_RANGE_MOVE »Page /Move moves data from a specified source range to a specified target range (Lotus Classic menu only).
LCE_RANGE_PRESELECT »Page Occurs whenever a range is specified as input to a menu command.
LCE_RANGE_PRESELECT_CLEAR »Page Occurs whenever a range is specified as input to a menu command and clears the current preset.
LCE_RANGE_RE »Page /Range Erase erases the data in a range, but leaves the cell format(s) for the range intact (Lotus Classic menu only).
LCE_RANGE_RI »Page /Range Input limits cell-pointer movement and data entry to unprotected cells in a range so that you can enter and edit data in those cells only (Lotus Classic menu only).
LCE_RANGE_RJ »Page Range Justify aligns the information in a column of labels to fit within a width you specify.
LCE_RANGE_RLC »Page Style Alignment in the GUI menu or /Range Label Center in the Lotus Classic menu centers labels in a range.
LCE_RANGE_RLL »Page Style Alignment in the GUI menu or /Range Label Left in the Lotus Classic menu left-aligns labels in a range.
LCE_RANGE_RLR »Page Style Alignment in the GUI menu or /Range Label Right in the Lotus Classic menu right-aligns labels in a range.
LCE_RANGE_RNC »Page Range Name Create assigns a name to a range.
LCE_RANGE_RND »Page Range Name Delete deletes a defined range name and any associated range name note, but leaves the data in the range intact.
LCE_RANGE_RNLD »Page Range Name Label Down with Down selected in the GUI menu or /Range Name Labels Down in the Lotus Classic menu assigns a label as a range name to a single-cell range. The label names the single-cell range directly beneath it.
LCE_RANGE_RNLL »Page Range Name Label Create with Left selected in the GUI menu or /Range Name Labels Left in the Lotus Classic menu assigns a label as a range name to a single-cell range. The label names the single-cell range directly to its left.
LCE_RANGE_RNLR »Page Range Name Label Create with Right selected in the GUI menu or /Range Name Labels Right in the Lotus Classic menu assigns a label as a range name to a single-cell range. The label names the single-cell range directly to its right.
LCE_RANGE_RNLU »Page Range Name Label Create with Up selected in the GUI menu or /Range Name Labels Up in the Lotus Classic menu assigns a label as a range name to a single-cell range. The label names the single-cell range directly above it.
LCE_RANGE_RNNC »Page /Range Name Note Create creates a note for a defined range name or lets you edit an existing note (Lotus Classic menu only).
LCE_RANGE_RNND »Page /Range Name Note Delete deletes a note for a defined range name (Lotus Classic menu only).
LCE_RANGE_RNNR »Page /Range Name Note Reset deletes all range name notes in the current file, including notes for undefined range names (Lotus Classic menu only).
LCE_RANGE_RNR »Page Range Name Delete in the GUI menu and /Range Name Reset in the Lotus Classic menu deletes all range names and their notes, if any, in the current file.
LCE_RANGE_RNU »Page Range Name Undefine specifies a range name to be undefined by dissociating an existing range name from a range address.
LCE_RANGE_RT »Page Range Transpose on the GUI menu or /Range Trans on the Lotus Classic menu copies a range of data, transposing the data, and replacing any formulas with their current values.
LCE_RANGE_RV »Page Edit Quick Copy with Convert to Values checked on the GUI menu and /Range Value in the Lotus Classic menu copies a range of data, replacing any formulas with their current values.
$348 LCE_RANGE_COPY Copy
/Copy copies data from a specified source range to a specified target range (Lotus Classic menu only).
Data Description
LCH_RANGE sourcerange sourcerange is a handle to the range from which RangeCopy copies the data.
LCH_RANGE targetrange targetrange is a handle to the range to which RangeCopy copies data.
$349 LCE_RANGE_FIXUP
RangeFixup notifies you when the cell coordinates of ranges are affected by an adjustment in the worksheet. For example, if a user inserts a column in a range whose original coordinates were A:A1..A:B1, RangeFixup notifies you when the range coordinates are changing to A:A1..A:C1.
Only before and after handlers are valid for RangeFixup.
Data
None
$350 LCE_RANGE_MOVE Move
/Move moves data from a specified source range to a specified target range (Lotus Classic menu only).
Data Description
LCH_RANGE sourcerange sourcerange is a handle to the range from which RangeMove moves the data.
LCH_RANGE targetrange targetrange is a handle to the range to which RangeMove moves data.
$351 LCE_RANGE_PRESELECT
RangePreselect occurs when a user specifies a range as input to a menu command. Only before and replace handlers are valid for RangePreselect. 1-2-3 ignores RangePreselect handler errors.
Data Description
LCH_RANGE inputrange inputrange can be set by a replace handler to override the user selection. The user-specified value for inputrange is not available; that is, it is not available with LciEvGetArgRange »Page .
$352 LCE_RANGE_PRESELECT_CLEAR
RangePreselectClear occurs when a user specifies a range as input to a menu command and clears the current preset. Only before and replace handlers are valid for RangePreselectClear. 1-2-3 ignores RangePreselectClear handler errors.
Data
None
$353 LCE_RANGE_RE Range Erase
/Range Erase erases the data in a range, but leaves the cell format(s) for the range intact (Lotus Classic menu only). The {BLANK} macro keyword also triggers the RE event.
Data Description
LCH_RANGE rangename rangename holds the name of the range that is the target of RE.
$354 LCE_RANGE_RI Range Input
/Range Input limits cell-pointer movement and data entry to unprotected cells in a range so that you can enter and edit data in those cells only (Lotus Classic menu only).
1-2-3 ignores any errors returned by an after handler for an RI event.
Data Description
LCH_RANGE rangename rangename holds the name of the range that is the target of RI.
$355 LCE_RANGE_RJ Range Justify
Range Justify aligns the information in a column of labels to fit in the width you specify.
Data Description
LCH_RANGE rangename rangename holds the name of the range that is the target of RJ.
$356 LCE_RANGE_RLC Range Label Center
Style Alignment in the GUI menu or /Range Label Center in the Lotus Classic menu centers labels in a range.
Data Description
LCH_RANGE rangename rangename holds the name of the range that is the target of RLC.
$357 LCE_RANGE_RLL Range Label Left
Style Alignment in the GUI menu or /Range Label Left in the Lotus Classic menu left-aligns labels in a range.
Data Description
LCH_RANGE rangename rangename holds the name of the range that is the target of RLL.
$358 LCE_RANGE_RLR Range Label Right
Style Alignment in the GUI menu or /Range Label Right in the Lotus Classic menu right-aligns labels in a range.
Data Description
LCH_RANGE rangename rangename holds the name of the range that is the target of RLR.
$359 LCE_RANGE_RNC Range Name Create
Range Name Create assigns a name to a range.
Data Description
lptr(lmbcs) lprangename lprangename holds the new range name that RNC creates. The range name can be an unqualified range name if the range in question is in the current file, and a fully qualified range name if it's in another active file.
LCH_RANGE targetrange targetrange holds the address of the range for which RNC creates a name.
$360 LCE_RANGE_RND Range Name Delete
Range Name Delete deletes a defined range name and any associated range name note, but leaves the data in the range intact.
Data Description
lptr(lmbcs) lprangename lprangename holds the range name that RND deletes. The range name can be an unqualified range name if the range in question is in the current file, and a fully qualified range name if it's in another active file.
$361 LCE_RANGE_RNLD Range Name Labels Down
Range Name Label Create with Down selected in the GUI menu or /Range Name Labels Down in the Lotus Classic menu assigns a label as a range name to a single-cell range. The label names the single-cell range directly beneath it.
Data Description
LCH_RANGE therange therange (probably not a named range) holds labels to give as names to the newly created ranges.
$362 LCE_RANGE_RNLL Range Name Labels Left
Range Name Label Create with Left selected in the GUI menu or /Range Name Labels Left in the Lotus Classic menu assigns a label as a range name to a single-cell range. The label names the single-cell range directly to its left.
Data Description
LCH_RANGE therange therange (probably not a named range) holds labels to give as names to the newly created ranges.
$363 LCE_RANGE_RNLR Range Name Labels Right
Range Name Label Create with Right selected in the GUI menu or /Range Name Labels Right in the Lotus Classic menu assigns a label as a range name to a single-cell range. The label names the single-cell range directly to its right.
Data Description
LCH_RANGE therange therange (probably not a named range) holds labels to give as names to the newly created ranges.
$364 LCE_RANGE_RNLU Range Name Labels Up
Range Name Label Create with Up selected in the GUI menu or /Range Name Labels Up in the Lotus Classic menu assigns a label as a range name to a single-cell range. The label names the single-cell range directly above it.
Data Description
LCH_RANGE therange therange (probably not a named range) holds labels to give as names to the newly created ranges.
$365 LCE_RANGE_RNNC Range Name Note Create
/Range Name Note Create creates a note for a defined range name or lets you edit an existing note (Lotus Classic menu only).
Data Description
lptr(lmbcs) lpnote lpnote holds the note for the specified range name.
LCH_RANGE rangename rangename holds the name of the range for which RNNC creates or edits a note.
$366 LCE_RANGE_RNND Range Name Note Delete
/Range Name Note Delete deletes a note for a defined range name (Lotus Classic menu only).
Data Description
LCH_RANGE rangename rangename holds the range name from which RNND deletes the note.
$367 LCE_RANGE_RNNR Range Name Note Reset
/Range Name Note Reset deletes all range name notes in the current file, including notes for undefined range names (Lotus Classic menu only).
Data
None
$368 LCE_RANGE_RNR Range Name Reset
Range Name Delete in the GUI menu and /Range Name Reset in the Lotus Classic menu deletes all range names and their notes, if any, in the current file along with any associated range name notes, but leaves data in the named ranges intact.
Data
None
$369 LCE_RANGE_RNU Range Name Undefine
Range Name Undefine specifies a range name to be undefined by dissociating an existing range name from a range address.
Data Description
lptr(lmbcs) lprangename lprangename holds the range name that RNU specifies to be undefined. The range name can be an unqualified range name if the range in question is in the current file, and a fully qualified range name if it's in another active file.
$370 LCE_RANGE_RT Range Trans
Range Transpose on the GUI menu or /Range Trans on the Lotus Classic menu copies a range of data, transposing the data, and replacing any formulas with their current values.
Data Description
LCH_RANGE sourcerange sourcerange holds the name of the range from which RT copies data.
LCH_RANGE targetrange targetrange holds the name of the range into which RT copies data.
lslong transpose_type transpose_type is an enumerated type that indicates the type of transposition. See LCIEVENT.T for possible values.
$371 LCE_RANGE_RV Range Value
Edit Quick Copy with Convert to Values checked on the GUI menu and /Range Value in the Lotus Classic menu copy a range of data, replacing any formulas with their current values.
Data Description
LCH_RANGE sourcerange sourcerange holds the name of the range from which RV copies data.
LCH_RANGE targetrange targetrange holds the name of the range to which RV copies data.
Event Description
LCE_RECALC »Page The point in processing that immediately precedes the 123 recalculation of a worksheet.
$374 LCE_RECALC
RecalcEvent is the point in processing that immediately precedes the 1-2-3 recalculation of a worksheet. The {RECALC} macro command, CALC (F9), and automatic recalculation all trigger RecalcEvent. Handlers are triggered only once per execution of RecalcEvent, regardless of the value of the recalculation iteration count (as set by /Worksheet Global Recalc Iteration).
Only before and replace handlers are valid for RecalcEvent. 1-2-3 ignores RecalcEvent handler errors.
Data
None
Event Description
LCE_WKS_WDC »Page Worksheet Delete Column deletes one or more columns in an active file.
LCE_WKS_WDR »Page Worksheet Delete Row deletes one or more rows in an active file.
LCE_WKS_WDS »Page Worksheet Delete Sheet deletes one or more worksheets in an active file.
LCE_WKS_WEY »Page /Worksheet Erase Yes removes all active worksheets and files from memory, replacing them with one blank worksheet (Lotus Classic menu only).
LCE_WKS_WGGD »Page Worksheet Global Group Disable turns off GROUP mode for the current file.
LCE_WKS_WGGE »Page Worksheet Global Group Enable turns on GROUP mode for the current file.
LCE_WKS_WHD »Page /Worksheet Hide Disable redisplays hidden worksheets (Lotus Classic menu only).
LCE_WKS_WHE »Page /Worksheet Hide Enable hides specified worksheets (Lotus Classic menu only).
LCE_WKS_WIC »Page Worksheet Insert Column inserts one or more blank columns in a worksheet or set of worksheets.
LCE_WKS_WIR »Page Worksheet Insert Row inserts one or more blank rows in a worksheet or set of worksheets.
LCE_WKS_WIS »Page Worksheet Insert Sheet inserts new, blank worksheets in the current file.
LCE_WKS_WWC »Page Window Split Clear in the GUI menu and /Worksheet Window Clear in the Lotus Classic menu restore full-screen worksheet display.
LCE_WKS_WWG »Page /Worksheet Window Graph divides the screen vertically and displays the current graph in the right window (Lotus Classic menu only).
LCE_WKS_WWH »Page Window Split Horizontal in the GUI menu and /Worksheet Window Horizontal in the Lotus Classic menu split the screen horizontally to open a new window.
LCE_WKS_WWP »Page Window Split Perspective in the GUI menu and /Worksheet Window Perspective in the Lotus Classic menu display three stacked windows that contain consecutive worksheets.
LCE_WKS_WWV »Page Window Split Vertical in the GUI menu and /Worksheet Window Vertical in the Lotus Classic menu split the screen vertically to open a new window.
$377 LCE_WKS_WDC Worksheet Delete Column
Window Delete Column deletes one or more columns in an active file.
Data Description
LCH_RANGE targetrange targetrange holds a range that identifies the column(s) you want to delete.
lslong ispartial LTRUE if columns are deleted only from a range of rows.
$378 LCE_WKS_WDR Worksheet Delete Row
Worksheet Delete Row deletes one or more rows in an active file.
Data Description
LCH_RANGE targetrange targetrange holds a range that identifies the row(s) you want to delete.
lslong ispartial LTRUE if rows are deleted only from a range of columns.
$379 LCE_WKS_WDS Worksheet Delete Sheet
Worksheet Delete Sheet deletes one or more worksheets in an active file.
Data Description
LCH_RANGE targetrange targetrange holds a range that identifies the worksheet(s) you want to delete. All worksheets spanned by the specified range are deleted.
targetrange consists of coordinates referring to the top left corner of the sheets to be deleted, for example, if sheets B through D were being deleted: B:A1..D:A1 would be the coordinates in targetrange.
$380 LCE_WKS_WEY Worksheet Erase Yes
/Worksheet Erase Yes removes all active worksheets and files from memory, replacing them with one blank worksheet (Lotus Classic menu only). If only one active file exists, WEY is triggered by /Worksheet Delete File because, in this case, /Worksheet Delete File is the same as /Worksheet Erase.
Data
None
$381 LCE_WKS_WGGD Worksheet Global Group Disable
Worksheet Global Group Disable turns off GROUP mode for the current file.
Data
None
$382 LCE_WKS_WGGE Worksheet Global Group Enable
Worksheet Global Group Enable turns on GROUP mode for the current file.
Data
None
$383 LCE_WKS_WHD Worksheet Hide Disable
/Worksheet Hide Disable redisplays hidden worksheets (Lotus Classic menu only).
Data
None
$384 LCE_WKS_WHE Worksheet Hide Enable
/Worksheet Hide Enable hides specified worksheets (Lotus Classic menu only).
Data Description
LCH_RANGE targetrange targetrange holds a range that identifies the location of the worksheet(s) to hide.
$385 LCE_WKS_WIC Worksheet Insert Column
Worksheet Insert Column inserts one or more blank columns in a worksheet or set of worksheets.
Data Description
LCH_RANGE targetrange targetrange is the range in which WIC inserts column(s). (WIC inserts column(s) to the left of the first column in the specified range.)
lslong ispartial LTRUE if columns are inserted only in a range of rows.
$386 LCE_WKS_WIR Worksheet Insert Row
Worksheet Insert Row inserts one or more blank rows in a worksheet or set of worksheets.
Data Description
LCH_RANGE targetrange targetrange is the range in which WIR inserts row(s). (WIR inserts row(s) above the first row in the specified range.)
lslong ispartial LTRUE if rows are inserted only in a range of columns.
$387 LCE_WKS_WIS Worksheet Insert Sheet
Worksheet Insert Sheet inserts new, blank worksheets in the current file.
Event handling for WIS occurs in two passes.
The first pass occurs when 1-2-3 attempts to insert the first of the worksheets that the user asked to insert. On this call, numsheets always equals one, and beginsheet equals the number of the worksheet at which insertion begins. In the case of /Worksheet Insert Sheet After, beginsheet is the current worksheet; in the case of /Worksheet Insert Sheet Before, beginsheet is the current worksheet less one.
The second call to WIS handlers occurs when 1-2-3 attempts to insert the remaining worksheets. On this call, numsheets equals the number of worksheets, less one, that the user has selected. For /Worksheet Insert Sheet After, beginsheet has the value it had on the first call, plus one; for /Worksheet Insert Sheet Before, beginsheet has the value it had on the first call.
CAUTION You cannot block the WIS event.
Data Description
lslong beginsheet (Arg1) beginsheet holds an integer that identifies the current worksheet.
lslong numsheets numsheets holds an integer that specifies the number of new worksheets to insert.
lslong append append, if true, specifies that WIS insert new worksheets after the current worksheet; if false, it specifies that WIS insert new worksheets before the current worksheet.
Note Sheet numbers, row numbers, and column numbers returned to event handlers are zero-based. To use them with Lci functions, add 1 to their values.
$388 LCE_WKS_WWC Worksheet Window Clear
Window Split Clear in the GUI menu and /Worksheet Window Clear in the Lotus Classic menu restore full-screen worksheet display.
Data
None
$389 LCE_WKS_WWG Worksheet Window Graph
/Worksheet Window Graph divides the screen vertically and displays the current graph in the right-window (Lotus Classic menu only).
Data Description
LCH_RANGE targetrange targetrange holds a range that identifies the location at which WWG splits the screen. (WWG performs the split so that the first column in the range becomes the first column in the graph window.)
$390 LCE_WKS_WWH Worksheet Window Horizontal
Window Split Horizontal in the GUI menu and /Worksheet Window Horizontal in the Lotus Classic menu split the screen horizontally to open a new window.
Data Description
LCH_RANGE targetrange targetrange holds a range that identifies the location at which WWH splits the screen. (WWH performs the split so that the first row in the range becomes the first row in the new window.)
$391 LCE_WKS_WWP Worksheet Window Perspective
Window Split Perspective in the GUI menu and /Worksheet Window Perspective in the Lotus Classic menu display three stacked windows that contain consecutive worksheets.
Data
None
$392 LCE_WKS_WWV Worksheet Window Vertical
Window Split Vertical in the GUI menu and /Worksheet Window Vertical in the Lotus Classic menu split the screen vertically to open a new window.
Data Description
LCH_RANGE targetrange targetrange holds a range that identifies the location at which WWV splits the screen. (WWV performs the split so that the first column in the range becomes the first column in the new window.)
Event Description
LCE_UNDO_FLUSH »Page Occurs when a user enters a command that can be retracted with an Undo command. UndoFlush deletes all records from the undo queue that relate to the previous reversible command.
LCE_UNDO_REWIND »Page Occurs when a user selects the Undo command and the effect of the most recent command is reversed.
$395 LCE_UNDO_FLUSH
UndoFlush occurs when a user implements a command that may be subject to an Undo command. When a reversible 1-2-3 command starts to execute, 1-2-3 deletes the records associated with the previous command from the undo queue. This processing ensures that only the results of the most recent reversible command will be reversed if the user presses UNDO (ALT-F4). After performing UndoFlush, 1-2-3 starts to execute the current command and accumulate records associated with it.
Only before and after handlers are valid for UndoFlush. 1-2-3 ignores UndoFlush handler errors.
Data
None
$396 LCE_UNDO_REWIND
UndoRewind occurs when a user selects the Undo command.
If a replace handler executes in place of the event, 1-2-3 first calls the replace handler and any after handlers, then displays the error message Cannot undo this series of add-in operations to inform the user that a replace handler prevented the Undo command from executing.
Data
None
The GUI (Graphical User Interface) functions group contains the functions you use to create and manipulate graphical objects (such as tool instance windows, menu objects, and dialog boxes). The GUI functions group contains four different types of functions and a set of messages that are sent to a tool procedure when certain events (such as the display of a dialog box or the destruction of a window) occur in 1-2-3 for Windows. The four function type groups and the one message group are listed below along with the notation used in the function descriptions.
Group Function Notation
Toolclass Objects »Page LciTc...
Tool Instance Objects »Page LciTi...
Menu Objects »Page LciMn...
Preset and Validate Objects »Page LciPs..., LciVl...
Tool Messages »Page TOOLMSG_...
A toolclass object (also refered to as a tool) defines a type of window that can appear on the 1-2-3 desktop. A toolclass can have one or more instances, each occupying its own window. Each toolclass has its own menu that is displayed when a window that contains an instance of that toolclass has input focus.
Sheet windows, the graph window, and the key transcript window are examples of toolclasses that are built into 1-2-3. It is possible to have many sheet instances open at any time.The graph and key transcript toolclasses allow only one instance to be open at a time.
Add-ins can create custom toolclasses that extend the tools available to the 1-2-3 user. 1-2-3 for Windows performs much of the user input processing for a toolclass. Keystroke behavior at READY mode and the keystroke and mouse transitions through the menus and dialog boxes for a tool are specified in a resource script file. 1-2-3 reads in the compiled resources as required at runtime in order to process keyboard and mouse input. If 1-2-3 needs additional information from a tool, or needs to inform the tool of certain events that occur during user input, it does so by sending messages to a tool procedure.
The tool procedure is similar to a window procedure but handles messages sent by 1-2-3 for Windows. An add-in that created a custom toolclass would need both a window procedure for handling messages from the underlying windowing software and a tool procedure for handling messages from 1-2-3. The Lci provides default functions for both windows messages and tool messages. An add-in can replace the tool procedure for any toolclass and handle the tool messages itself. This is analagous to subclassing a window procedure in Windows. Unlike subclassing in Windows, however, the add-in is not required to call the old tool procedure with messages it does not handle. Instead, it calls the default tool procedure. Each time the tool procedure is replaced by an add-in, 1-2-3 adds the new tool procedure to a chain. Calling the default tool procedure ensures that the other tool procedures in the chain for the same toolclass will be called.
In many cases, an add-in will not need to create a custom toolclass. The add-in user interface requirements might be satisfied by dynamically adding to an existing toolclass menu and/or by putting up one or more dialog boxes. In this case the add-in must subclass an existing tool and provide a tool procedure for handling messages generated when processing the add-in menu items and dialogs. Routines in the Lci provide these capabilities.
Function Meaning
LciTcAddToolProc »Page Adds an add-in tool procedure for a toolclass to the list of tool procedures that are called by 1-2-3 to handle tool messages for that toolclass.
LciTcConstructCurr »Page Retrieves an object handle to the toolclass that is associated with the current active tool instance.
LciTcConstructName »Page Retrieves an object handle to a toolclass based on the specified toolclass name.
LciTcDefToolProc »Page Provides default processing for any tool messages that the add-in does not handle
LciTcDeleteToolProc »Page Deletes a tool procedure from the list of tool procedures that are called by 1-2-3 to handle tool messages.
LciTcDestroy »Page Releases a toolclass object handle.
LciTcGetInstanceCount »Page Gets the number of instances of a given toolclass.
LciTcGetMenu »Page Retrieves the handle of the top level menu associated with a toolclass.
LciTcGetMenuIds »Page Allocates a range of unique contiguous menu IDs for use by an add-in and returns the value of the first ID in the range.
LciTcIterInstances »Page Directs a caller-supplied instance iterator function through the instances of a given class until the iterator callback returns LFALSE or all instances have been processed.
LciTcRegister »Page Registers a custom tool type with 1-2-3.
LciTcRunDialog »Page Runs an add-in specified dialog box.
LciTcSendControlMsg »Page Sends a message to a control.
LciTcSetMenu »Page Replaces the menu for the specified tool.
LciTcUnregister »Page Unregisters a custom tool type.
Definition
Adds an add-in tool procedure for a toolclass to a list of procedures maintained by 1-2-3 for Windows. The tool procedure is added at the beginning of the list, meaning this will be the first tool procedure called by 1-2-3 to process tool messages unless another tool procedure is added subsequently.
When the add-in finishes processing tool messages, it should remove the tool procedure using LciTcDeleteToolProc »Page . This can be done from within the tool procedure itself or within any other procedure including AdnTerminate. Use a global variable or add-in data structure using LciLdSetAddinData »Page to store the toolclass object if neccessary.
Note: For information on AdnTerminate, see the ADK Developer's Guide.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTcAddToolProc
(LCH_TOOLCLASS Toolclass,
LCT_TOOLPROC_PTR lpfnToolProc)
Arguments
Toolclass A tool object handle.
lpfnToolProc Pointer to tool message handling function. The prototype of the function is as follows:
LCT_STATUS LCI_CALL ToolProc
(LCH_TOOLINST Toolinst, lushort Msg, lulong P1, lulong P2)
where Toolinst is the object handle of the tool instance that generated the message, Msg is the message identifier, and P1 and P2 are the message parameters.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
LCH_TOOLCLASS ToolClass;
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2);
. . .
/* Construct a toolclass object and add its tool procedure.
The tool procedure added here will get messages first and
decide whether or not to pass the messages on to any tool
procedures added before it. This is referred to as
SubClassing.*/
LCT_STATUS Status;
Status = LciTcConstructCurr (Context, &ToolClass);
Status = LciTcAddToolProc (ToolClass, ToolProc);
. . .
Status = LciTcDeleteToolProc (ToolClass, ToolProc);
Status = LciTcDestroy(&ToolClass);
/* Tool procedure that processes tool messages sent by 1-2-3 */
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
. . .
}
Definition
Retrieves an object handle to the toolclass that is associated with the current active tool instance. See LciTiConstructClass »Page and LciTiConstructCurr »Page for information on constructing tool instances.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTcConstructCurr
(LCH_CONTEXT Context,
lptr(LCH_TOOLCLASS) lpToolclass)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpToolclass A pointer to storage to which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
LCH_TOOLCLASS ToolClass;
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2);
/* Construct a toolclass object and add its tool procedure.
The tool procedure added here will get messages first and
decide whether or not to pass the messages on to any tool
procedures added before it. This is referred to
as SubClassing. */
LCT_STATUS Status;
Status = LciTcConstructCurr (Context, &ToolClass);
Status = LciTcAddToolProc (ToolClass, ToolProc);
. . .
Status = LciTcDeleteToolProc (ToolClass, ToolProc);
Status = LciTcDestroy(&ToolClass);
Definition
Retrieves an object handle to a toolclass based on the specified toolclass name.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTcConstructName
(LCH_CONTEXT Context,
lushort ToolclassType,
lptr(lmbcs) lpCustomClassName,
lptr(LCH_TOOLCLASS) lpToolclass)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
ToolclassType One of the following constants:
Constant Meaning
LCI_TOOLCLASS_SHEET 1-2-3 Sheet toolclass.
LCI_TOOLCLASS_GRAPH 1-2-3 Graph toolclass.
LCI_TOOLCLASS_CUSTOM An add-in custom toolclass.
lpCustomClassName Pointer to a lmbcs string that specifies the toolclass name of a custom toolclass. The toolclass name for a custom toolclass is specified in the TOOL statement in the resource file script. This parameter is ignored if the ToolclassType parameter is LCI_TOOLCLASS_SHEET or LCI_TOOLCLASS_GRAPH.
lpToolclass A pointer to storage to which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_INVALID_NAME »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
LCH_TOOLCLASS ToolClass;
LCT_STATUS Status;
Status = LciTcConstructName(Context,
LCI_TOOLCLASS_SHEET,
LNULL,
&ToolClass);
. . .
Status = LciTcDestroy(&ToolClass);
Definition
Provides default processing for any tool messages that the add-in does not handle. Messages are passed to the next tool procedure in the list of tool procedures for the given toolclass, if any, or to a default tool procedure internal to 1-2-3.
Format
#include "lcicomn.h"
#include "lcigui.h"
lulong LCI_CALL LciTcDefToolProc
(LCH_TOOLCLASS Toolclass,
LCH_TOOLINST Toolinst,
lushort Msg,
lulong P1,
lulong P2)
Arguments
Toolclass The object handle of the toolclass for which the tool procedure is processing messages.
Toolinst The tool instance object handle that was passed to the tool message procedure.
Msg The message ID.
P1 The first message parameter.
P2 The second message parameter.
Returns
The value returned by the tool procedure that handled the message.
Example
#include "lcicomn.h"
#include "lcigui.h"
LCH_TOOLCLASS ToolClass;
LCH_DIALOG Dialog;
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2);
. . .
/* Run a dialog box. The dialog box behavior is primarily
determined by the DIALOGSTRUCT statements in the resource
file. */
LCT_STATUS Status;
Status = LciTcConstructCurr (Context, &ToolClass);
Status = LciTcAddToolProc (ToolClass, ToolProc);
Status = LciTcRunDialog (ToolClass, DIALOG_ID, &Dialog);
. . .
/* tool messages sent by 1-2-3 */
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
LCT_STATUS Status;
LCT_STATUS ReturnCode = 0L;
switch(Msg){
. . .
case TOOLMSG_DLGTERM:
Status = LciTcDeleteToolProc (ToolClass, ToolProc);
Status = LciTcDestroy (&ToolClass);
break;
. . .
default:
/* Messages not processed should be passed along to the next
tool procedure in the list for a given toolclass. */
ReturnCode = LciTcDefToolProc (ToolClass, ToolInst,
Msg, P1, P2);
break;
}
return(ReturnCode);
}
Definition
Deletes a tool procedure from the list of tool procedures that are called by 1-2-3 to handle tool messages for a toolclass. This function should be called when an add-in no longer needs to get tool messages from 1-2-3.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTcDeleteToolProc
(LCH_TOOLCLASS Toolclass,
LCT_TOOLPROC_PTR lpfnToolProc)
Arguments
Toolclass A toolclass object handle.
lpfnToolProc Pointer to the tool procedure to be removed from the chain.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
LCH_TOOLCLASS ToolClass;
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2);
. . .
/* Construct a toolclass object and add its tool procedure.
The tool procedure added here will get messages first and
decide whether or not to pass the messages on to any tool
procedures added before it. This is referred to as
SubClassing. */
LCT_STATUS Status;
Status = LciTcConstructCurr (Context, &ToolClass);
Status = LciTcAddToolProc (ToolClass, ToolProc);
. . .
/* When the add-in finishes processing tool messages, it should
remove the tool procedure and destroy the toolclass object.
These can be done from within the tool procedure itself or
within any other procedure including AdnTerminate. Use a
global variable or Add-in Data structure to store the
toolclass object, if neccessary. */
Status = LciTcDeleteToolProc (ToolClass, ToolProc);
Status = LciTcDestroy(&ToolClass);
. . .
/* Tool procedure that processes tool messages sent by 1-2-3 */
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
. . .
}
Definition
Releases a toolclass object handle.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTcDestroy
(lptr(LCH_TOOLCLASS) lpToolclass)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpToolclass A pointer to a toolclass object handle. The handle is set to LNULL.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLCLASS ToolClass;
LCT_STATUS Status;
Status = LciTcConstructCurr (Context, &ToolClass);
. . .
Status = LciTcDestroy(&ToolClass);
Definition
Gets the number of instances of a given toolclass.
Format
LCT_STATUS LCI_CALL LciTcGetInstanceCount
(LCH_TOOLCLASS Toolclass,
lptr(lushort) Count)
Arguments
Toolclass A tool object handle. Returns the total number of instances for all toolclasses if passed LNULL.
Count A pointer to an lushort in which to return the number of instances of ToolClass.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcigui.h"
lbool LCI_CALL Iterator (LCH_TOOLINST ToolInst, lptr(lulong)
DataPointer);
. . .
LCT_STATUS Status;
lushort Count;
lulong Data;
/* Iterate through all custom tool instances and display a
message in their client area using a Windows function. */
Status = LciTcConstructName (Context, LCI_TOOLCLASS_CUSTOM,
"Custom",&ToolClass);
Status = LciTcGetInstanceCount (ToolClass, &Count);
/* The data that you pass to the iterator function can be
anything you want. This is a Windows utility macro that
stores two shorts inside a long. */
Data = MAKELONG(1,Count);
Status = LciTcIterInstances (Context, ToolClass, Iterator, &Data);
. . .
/* This is the iterator function that will get called by 1-2-3. */
lbool LCI_CALL Iterator (LCH_TOOLINST ToolInst, lptr(lulong)
DataPointer)
{
LCT_STATUS Status;
HANDLE hWnd;
HDC hDC;
lushort Num;
lushort Total;
char Message[64];
Status = LciTiGetWindowHandle (ToolInst, &hWnd);
/* This is the Windows code to output text in a window. */
hDC = GetDC(hWnd);
Num = LOWORD(*DataPointer);
Total = HIWORD(*DataPointer);
wsprintf(Message, "Window number %d of %d", Num, Total);
TextOut(hDC, 0, 0, Message, 64);
ReleaseDC(hWnd, hDC);
*DataPointer = MAKELONG(Num+1,Total);
return(LTRUE);
}
Definition
Retrieves the handle of the top level menu associated with a toolclass. The top-level menu is the horizontal menu bar. The handles of popup menus can be obtained using LciMnGetSubMenu »Page .
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTcGetMenu
(LCH_TOOLCLASS Toolclass,
lptr(LCH_MENU) lpMenu)
Arguments
Toolclass A toolclass object handle.
lpMenu A pointer to storage to which to return the menu object handle.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCT_STATUS Status;
Status = LciTcConstructName(Context,
LCI_TOOLCLASS_SHEET,
LNULL,
&ToolClass);
Status = LciTcGetMenu(ToolClass,&MenuBar);
. . .
Status = LciMnDestroy(&MenuBar);
Status = LciTcDestroy(&ToolClass);
Definition
Allocates a range of unique contiguous menu IDs for use by an add-in and returns the value of the first ID in the range. IDs for menu items that are inserted by an add-in must be unique for a given toolclass. These IDs are released when the associated toolclass is released using LciTcDestroy »Page . See the LciMn... functions for information on inserting menu items.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTcGetMenuIds
(LCH_TOOLCLASS Toolclass,
lushort Count,
lptr(lushort) lpIdStart)
Arguments
Toolclass A toolclass object handle.
Count The number of IDs to allocate to the add-in.
lpIdStart A pointer to an lushort in which to return the value of the first ID in the range of allocated IDs.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_ID_SPACE »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCH_MENU ToolMenu;
LCT_STATUS Status;
lushort MenuId;
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2);
/* Gets the current menu bar associated with the 1-2-3 sheet
class, and adds one new menu item to it. Assumes the "Tools"
submenu is the eighth item by position in the default 1-2-3
sheet menu bar. Normally, you would verify this by checking
its label since other add-ins may have altered the menu.
Appends the new menu item to the bottom of the popup menu. */
Status = LciTcConstructName(Context,
LCI_TOOLCLASS_SHEET,
LNULL,
&ToolClass);
Status = LciTcAddToolProc(ToolClass, ToolProc);
/* You can allocate the menu IDs anytime before inserting the
menu items. */
Status = LciTcGetMenuIds(ToolClass, 1, &MenuId);
Status = LciTcGetMenu(ToolClass, &MenuBar);
Status = LciMnGetSubMenu(MenuBar, 8, ToolMenu);
Status = LciMnInsertItem(ToolMenu,
LCIMENUITEM_APPEND,
LCI_MENUITEM_BYPOSITION,
MenuId+0,
LCI_MENUITEM_PROC,
(lulong) (MenuId+0),
"&1 Menu Item",
"Description",
LCF_MENUITEM_ENABLED);
. . .
/* Tool procedure that processes tool messages sent by 1-2-3 */
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
LCT_STATUS ReturnCode = 0L;
switch(Msg){
case TOOLMSG_MENUPROC:
/* Will get this message because LCI_MENUITEM_PROC was specified
when inserting the menu item. Let the message get passed to
the default tool procedure if the ID does not belong to the
add-in. */
if(P1 == MenuId+0){
. . .
}
else{
ReturnCode = LciTcDefToolProc(ToolClass,
ToolInst,
Msg,
P1,
P2);
}
break;
default:
/* Messages not processed should be passed along to the next
tool procedure in the list for a given toolclass. */
ReturnCode = LciTcDefToolProc(ToolClass,
ToolInst,
Msg,
P1,
P2);
break
}
return(ReturnCode);
}
. . .
/* When the add-in is finished, it should restore the menu,
remove the tool procedure, and destroy any objects it
constructed.These operations can be done from within the tool
procedure itself or any other procedure including AdnTerminate
Use global variables or an add-in data structure to store the
objects, if necessary. */
Status = LciMnDeleteItem(ToolMenu,
MenuId+0,
LCI_MENUITEM_BYCOMMAND);
Status = LciMnDestroy(&ToolMenu);
Status = LciMnDestroy(&MenuBar);
Status = LciTcDeleteToolProc(ToolClass, ToolProc);
Status = LciTcDestroy(&ToolClass);
Definition
Directs a caller-supplied instance iterator function through the instances of a given class until the iterator function returns LFALSE or all instances have been processed.
Format
LCT_STATUS LCI_CALL LciTcIterInstances
(LCH_CONTEXT Context,
LCH_TOOLCLASS ToolClass,
lptr(LCT_ITER_FUNC) IpIterator,
lptr(lulong) lpData)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
ToolClass A Tool object handle. LNULL signifies all toolclasses.
lpData A pointer to an lulong that is passed to the iterator function. This pointer can be used to exchange data between the caller and the iterator function.
IpIterator A pointer to a function that 1-2-3 calls for each instance of the specified ToolClass. The prototype of the function is
lbool LCI_CALL Iterator(LCH_TOOLINST ToolInst,
lptr(lulong) lpDataPointer)
where
ToolInst is the handle of the current tool instance and
lpDataPointer is the data pointer that was passed to LciIterInstances.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcigui.h"
lbool LCI_CALL Iterator (LCH_TOOLINST ToolInst, lptr(lulong)
DataPointer);
. . .
LCT_STATUS Status;
lushort Count;
lulong Data;
/* Iterate through all custom tool instances and display a
message in their client area using a Windows function. */
Status = LciTcConstructName (Context, LCI_TOOLCLASS_CUSTOM,
"Custom", &ToolClass);
Status = LciTcGetInstanceCount (ToolClass, &Count);
/* The data that you pass to the iterator function can be
anything you want. This is a Windows utility macro that
stores two shorts inside a long. */
Data = MAKELONG(1,Count);
Status = LciTcIterInstances (Context, ToolClass, Iterator, &Data);
. . .
/* This is the iterator function that will get called by 1-2-3. */
lbool LCI_CALL Iterator (LCH_TOOLINST ToolInst, lptr(lulong),
DataPointer)
{
LCT_STATUS Status;
HANDLE hWnd;
HDC hDC;
lushort Num;
lushort Total;
char Message[64];
Status = LciTiGetWindowHandle (ToolInst, &hWnd);
/* This is the Windows code to output text in a window. */
hDC = GetDC(hWnd);
Num = LOWORD(*DataPointer);
Total = HIWORD(*DataPointer);
wsprintf(Message, "Window number %d of %d", Num, Total);
TextOut(hDC, 0, 0, Message, 64);
ReleaseDC(hWnd, hDC);
*DataPointer = MAKELONG(Num+1,Total);
return(LTRUE);
}
Definition
Registers a custom toolclass with 1-2-3. Once a new toolclass has been registered, an add-in can create instances of that toolclass using the tool instance object. 1-2-3 uses the toolclass name to create tool instance windows. The add-in is required to register the window class with Windows using the RegisterClass SDK function. The window class name passed to the RegisterClass function should be the same as the toolclass name.
Note This function causes the custom resource data for the toolclass to be loaded into memory. The resources are assumed to be linked to the add-in .ADW file. If the resources are not found, the LCS_RESOURCE_LOAD_ERROR status is returned.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTcRegister
(LCH_CONTEXT Context,
lushort Toolid,
LCT_TOOLPROC_PTR lpfnToolProc,
lptr(LCT_REGISTRATION) lpRegistration)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Toolid The resource ID of the tool specified in the TOOL statement in the resource file.
lpfnToolProc Pointer to tool message handling function. This function will be called to handle tool messages for the new toolclass. The prototype of the function is as follows:
LCT_STATUS LCI_CALL ToolProc
(LCH_TOOLINST Toolinst, lushort Msg, lulong P1, lulong P2)
where
Toolinst is the object handle of the tool instance that is receiving the message,
Msg is the message identifier, and
P1 and P2 are the message parameters.
lpRegistration A pointer to storage to which to return a registration handle that can subsequently be used to unregister the tool.
Returns
LCS_SUCCESS »Page
LCS_RESOURCE_LOAD_ERROR »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcigui.h"
#include "lcild.h"
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2);
DWORD FAR PASCAL WinProc (HWND hWnd, WORD wMsg, WORD wParm,
DWORD lParm);
. . .
LCH_REGISTRATION Registration;
LCT_STATUS Status;
WNDCLASS WndClass; /* Defined in windows.h */
HANDLE LibHandle;
/* To call many Windows functions, you need the add-in module
handle. */
Status = LciLdGetLibHandle (Context, &LibHandle);
/* Register a custom toolclass with its default tool and window
procedures. */
WndClass.style = CS_GLOBALCLASS | CS_HREDRAW | CS_VREDRAW;
WndClass.lpfnWndProc = WinProc;
WndClass.cbClsExtra = 0;
WndClass.cbWndExtra = LCI_TOOLCLASS_EXTRABYTES;
WndClass.hInstance = LibHandle;
WndClass.hIcon = LoadIcon(NULL, IDI_APPLICATION);
WndClass.hCursor = LoadCursor(NULL, IDC_ARROW);
WndClass.hbrBackground = NULL;
WndClass.lpszMenuName = NULL;
WndClass.lpszClassName = "Custom Tool";
RegisterClass(&WndClass);
Status = LciTcRegister (Context, TOOL_ID, ToolProc, &Registration);
. . .
/* When the add-in finishes, it should unregister the toolclass.
Use a global variable or Add-in Data structure to store the
toolclass object if neccessary. */
Status = LciTcUnregister (Registration);
/* Tool procedure that processes tool messages sent by 1-2-3 */
. . .
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
. . .
}
/* Window Procedure that processes tool messages sent by Windows */
DWORD FAR PASCAL WinProc (HWND hWnd, WORD wMsg, WORD wParm,
DWORD lParm)
{
. . .
}
Definition
Runs an add-in specified dialog box. The add-in must provide a tool procedure to handle messages generated while processing input for the dialog. The add-in tool procedure should be set with a call to LciTcAddToolProc »Page . If the tool procedure is not set, tool messages will be sent to the current tool procedure, which might be a tool procedure in another add-in, or a default tool procedure inside 1-2-3.
Note The dialog box is not displayed immediately. LciTcRunDialog sets up 1-2-3 to display the dialog box and then returns. The dialog is displayed when control is returned to 1-2-3, either by exiting from an add-in function, or by calling LciUtYield »Page .
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTcRunDialog
(LCH_TOOLCLASS Toolclass,
lushort DialogId,
lptr(LCH_DIALOG) lpDialog)
Arguments
Toolclass A toolclass object handle.
DialogId The resource ID of the dialog.
lpDialog A pointer to storage to which to return the handle of the dialog box.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2);
. . .
LCH_TOOLCLASS ToolClass;
LCH_DIALOG Dialog;
lbool DialogFlag;
LCT_STATUS Status;
/* Run a dialog box. The dialog box behavior is primarily
determined by the DIALOGSTRUCT statements in the resource
file. */
Status = LciTcConstructCurr (Context, &ToolClass);
Status = LciTcAddToolProc (ToolClass, ToolProc);
Status = LciTcRunDialog (ToolClass, DIALOG_ID, &Dialog);
DialogFlag = LTRUE;
while(DialogFlag){
LciUtYield(Context);
}
. . .
/* Tool procedure that processes tool messages sent by 1-2-3 */
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
LCT_STATUS Status;
LCT_STATUS ReturnCode = 0L;
switch(Msg){
case TOOLMSG_DLGTERM:
DialogFlag = LFALSE;
Status = LciTcDeleteToolProc (ToolClass, ToolProc);
Status = LciTcDestroy (&ToolClass);
break;
default:
/* Messages not processed should be passed along to the next
tool procedure in the list for a given toolclass. */
ReturnCode = LciTcDefToolProc (ToolClass, ToolInst,
Msg, P1, P2);
break;
}
return(ReturnCode);
}
Definition
Sends a message to a control.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTcSendControlMsg
(LCH_TOOLCLASS Toolclass,
LCH_CONTROL Control,
lushort Msg,
lulong P1,
lulong P2)
Arguments
Tool The object handle of the tool that is handling messages for the dialog box.
Control The object handle of the control to which to send the message. This handle can be obtained during processing of a TOOLMSG_DLGPRESET or TOOLMSG_DLGVALIDATE message using one of the access functions LciPsGetControl »Page or LciVlGetControl »Page .
Msg The message ID.
P1 The first message parameter.
P2 The second message parameter.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
LCH_TOOLCLASS ToolClass;
. . .
/* Tool procedure that processes tool messages sent by 1-2-3 */
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
LCH_CONTROL Control;
LCT_STATUS Status;
LCT_STATUS ReturnCode = 0L;
lulong ID;
switch(Msg){
case TOOLMSG_DLGPRESET:
/* Each dialog control with the PRESET attribute will cause this
message to be sent. Use the control ID value to identify it. */
Status = LciPsGetControl ((LCH_PRESET)P1, &Control);
Status = LciPsGetValue ((LCH_PRESET)P1, &ID);
switch(ID){
case CONTROL_ID:
/* Communicate with the control by sending it a Windows message.
These can be standard Windows messages or 1-2-3 specific
Windows messages. The values of P1 and P2 are unique for
each message. */
Status = LciTcSendControlMsg (ToolClass, Control,
WM_SETTEXT, 0L, "Control Text");
break;
}
break;
/* Remainder of tool procedure */
. . .
}
return (ReturnCode);
}
Definition
Replaces the menu for the specified tool. The new menu is specified by a menu object. The menu object should have been created using LciMnConstructNew »Page , with the menu type set to LCI_MENUTYPE_MENUBAR.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTcSetMenu
(LCH_TOOLCLASS Toolclass,
lptr(LCH_MENU) lpPrevMenu,
LCH_MENU Menu)
Arguments
Toolclass A tool object handle.
lpPrevMenu A pointer to storage to which to return a handle to the menu that is being replaced. This is set to LNULL if an error occurs.
Menu The menu object that describes the new menu for the tool.
Returns
LCS_SUCCESS »Page
LCS_INVALID_MENU_TYPE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2);
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCH_MENU OldMenu;
LCH_MENU NullMenu;
LCT_STATUS Status;
lushort MenuId;
/* Replace the current menu bar asociated with the 1-2-3
sheet class, and add one new popup menu with three menu
items to it. */
Status = LciTcConstructName(Context,
LCI_TOOLCLASS_SHEET,
LNULL,
&ToolClass);
Status = LciTcAddToolProc(ToolClass, ToolProc);
/* You can allocate the menu IDs anytime before inserting the
menu items. The menu bar, the popups, and each of the menu
items need a unique ID */
Status = LciTcGetMenuIds(ToolClass, 6, &MenuId);
Status = LciMnConstructNew (Context,
LCI_TOOLCLASS_SHEET,
LNULL,
(MenuId + 0)
LCI_MENUTYPE_MENUBAR,
&MenuBar);
/* Insert items into the new menu. */
. . .
Status = LciTcSetMenu(ToolClass, &OldMenu, MenuBar);
. . .
/* Tool procedure that processes tool messages sent by 1-2-3 */
LCT_STATUS LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
. . .
}
. . .
/* When the add-in is finished, it should restore the menu,
remove the tool procedure, and destroy any objects it
constructed. These operations can be done from within the
tool procedure itself or within any other procedure including
AdnTerminate.
/* The NullMenu variable is only necessary because there is no
explicit "reset" function and because the "set" function will
not take LNULL as the second parameter. */
Status = LciTcSetMenu(Toolclass, &NullMenu, OldMenu);
Status = LciMnDeleteItem(MenuBar,
(MenuId+0),
LCI_MENUITEM_BYCOMMAND);
Status = LciMnDestroy(&NullMenu);
Status = LciMnDestroy(&OldMenu);
Status = LciMnDestroy(&MenuBar);
Status = LciTcDeleteToolProc(ToolClass, &ToolProc);
Status = LciTcDestroy(&ToolClass);
Definition
Unregisters a custom toolclass.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTcUnregister
(LCH_REGISTRATION RegisterHandle)
Arguments
RegisterHandle The registration handle that was obtained from the call to LciTcRegister »Page .
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcigui.h"
#include "lcild.h"
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2);
DWORD FAR PASCAL WinProc (HWND hWnd, WORD wMsg, WORD wParm,
DWORD lParm);
. . .
LCH_TOOLCLASS ToolClass;
LCH_REGISTRATION Registration;
LCT_STATUS Status;
WNDCLASS WndClass; /* Defined in windows.h */
HANDLE LibHandle;
/* To call many Windows functions, you need the add-in module
handle. */
Status = LciLdGetLibHandle (Context, &LibHandle);
/* Register a custom toolclass with its default tool and window
procedures. */
WndClass.style = CS_GLOBALCLASS | CS_HREDRAW | CS_VREDRAW;
WndClass.lpfnWndProc = WinProc;
WndClass.cbClsExtra = 0;
WndClass.cbWndExtra = LCI_TOOLCLASS_EXTRABYTES;
WndClass.hInstance = LibHandle;
WndClass.hIcon = LoadIcon(NULL, IDI_APPLICATION);
WndClass.hCursor = LoadCursor(NULL, IDC_ARROW);
WndClass.hbrBackground = NULL;
WndClass.lpszMenuName = NULL;
WndClass.lpszClassName = "Custom Tool";
RegisterClass(&WndClass);
Status = LciTcRegister (Context, TOOL_ID, ToolProc, &Registration);
/* TOOL_ID is in resource file. */
/* When the add-in finishes, it should unregister the
toolclass. Use a global variable or add-in data structure
(see LciLdSetAddinData) to store the toolclass object,
if neccessary. */
Status = LciTcUnregister (Registration);
/* Tool procedure that processes tool messages sent by 1-2-3 */
LCT_STATUS LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
. . .
}
/* Window Procedure that processes tool messages sent by Windows */
DWORD FAR PASCAL WinProc (HWND hWnd, WORD wMsg, WORD wParm,
DWORD lParm)
{
. . .
}
Tool instance objects refer to instances of a toolclass. A tool instance occupies a window on the 1-2-3 desktop. Tool instance objects can be created for existing tool instances (ones that are already open) or they can be used to create new tool instances (by creating a new window).
Function Meaning
LciTiActivate »Page Makes the specified tool instance the current active instance.
LciTiConstructClass »Page Retrieves an object handle to a tool instance of the specified class.
LciTiConstructCurr »Page Retrieves an object handle to the tool instance that is currently active.
LciTiDefWindowProc »Page Provides default processing for any window messages that are not handled by the window procedure for a custom tool window.
LciTiDestroy »Page Releases a tool instance object handle.
LciTiGetClass »Page Retrieves an enumerated value that represents the toolclass that the tool instance belongs to.
LciTiGetTitle »Page Retrieves the title that is displayed in the caption bar of the tool instance window.
LciTiGetTitleLen »Page Retrieves the length, in bytes, of the title that is displayed in the caption bar of the tool instance window.
LciTiGetWindowHandle »Page Retrieves the Microsoft Windows window handle for the specified tool instance window.
LciTiSetTitle »Page Modifies the title that is displayed in the caption bar of the tool instance window.
Definition
Makes the specified tool instance the current active instance.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTiActivate
(LCH_TOOLINST Toolinst)
Arguments
Toolinst A tool instance object handle.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLINST ToolInst;
LCT_STATUS Status;
/* Get an object handle for the untitled worksheet and give
it focus. */
Status = LciTiConstructClass (Context, LCI_TOOLCLASS_SHEET,
LNULL, "Untitled", 0, &ToolInst);
Status = LciTiActivate(ToolInst);
/* Destroy the tool instance when done. */
Status = LciTiDestroy (&Toolinst);
Definition
Retrieves an object handle to a tool instance of the specified class. If a tool instance with the same title and class is already open, a new object handle is created for that instance; otherwise, a new tool instance is created that results in the creation of a new MDI window.
Note 1-2-3 for Windows allows only a single graph window to be open at any time. For this reason, it is not possible to use LciTiConstructClass to create new graph windows.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTiConstructClass
(LCH_CONTEXT Context,
lushort ToolclassType,
lptr(lmbcs) lpCustomClassName,
lptr(lmbcs) lpTitle,
lushort Style,
lptr(LCH_TOOLINST) lpToolinst)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
ToolclassType One of the following constants:
Constant Meaning
LCI_TOOLCLASS_SHEET 1-2-3 Sheet toolclass.
LCI_TOOLCLASS_GRAPH 1-2-3 Graph toolclass.
LCI_TOOLCLASS_CUSTOM An add-in custom toolclass.
lpCustomClassName Pointer to a lmbcs string that specifies the toolclass name of a custom toolclass. The toolclass name for a custom toolclass is specified in the TOOL statement in the resource script file. This parameter is ignored if the ToolclassType parameter is LCI_TOOLCLASS_SHEET or LCI_TOOLCLASS_GRAPH.
lpTitle Pointer to a lmbcs string that specifies the title of the tool instance (that appears in the caption bar of the tool instance window). If this is the same as the one already open for lpCustomClassName, then no new tool instance is created.
Style One or more of the following flags OR'd together, or 0 (zero) if the tool instance window is to be created without scroll bars:
Constant Meaning
LCF_VSCROLL Create the window with vertical scroll bars.
LCF_HSCROLL Create the window with horizontal scroll bars.
lpToolinst A pointer to storage to which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CLASS »Page
LCS_NOT_FOUND »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLINST ToolInst;
LCT_STATUS Status;
/* Get an object handle for the untitled worksheet and give
it focus. */
Status = LciTiConstructClass (Context, LCI_TOOLCLASS_SHEET,
LNULL, "Untitled", 0, &ToolInst);
Status = LciTiActivate(ToolInst);
. . .
/* Destroy the tool instance when done. */
Status = LciTiDestroy (&Toolinst);
Definition
Retrieves an object handle to the tool instance that is currently active.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTiConstructCurr
(LCH_CONTEXT Context,
lptr(LCH_TOOLINST) lpToolinst)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpToolinst A pointer to storage to which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLINST ToolInst;
LCT_STATUS Status;
Status = LciTiConstructCurr (Context, &ToolInst);
. . .
Status = LciTiDestroy (&Toolinst);
Definition
Provides default processing for any window messages that are not handled by the window procedure for a custom tool window.
Note This function must be used for Windows messages, and must be used instead of the default Windows message procedures provided by the MS Windows SDK.
Format
#include "lcicomn.h"
#include "lcigui.h"
lulong LCI_CALL LciTiDefWindowProc
(lushort hWnd,
lushort Msg,
lushort wParam,
lulong lParam)
Arguments
hWnd The window handle of the tool instance window.
Msg The message ID.
wParam The first message parameter.
lParam The second message parameter.
Returns
The value returned as a result of message processing. This value depends on the message being sent.
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcigui.h"
/* Window Procedure that processes tool messages sent by Windows */
DWORD FAR PASCAL WinProc (HWND hWnd, WORD wMsg, WORD wParm,
DWORD lParm)
{
lulong ReturnCode = 0L;
Switch(wMsg){
/* Some messages you will want to handle yourself. */
case WM_PAINT:
. . .
break;
/* The rest of the messages will be passed to the default
window proc in 1-2-3. */
default;
ReturnCode = LciTiDefWindowProc(hWnd, wMsg, wParm, lParm);
break;
}
return(ReturnCode);
}
Definition
Releases a tool instance object handle.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTiDestroy
(lptr(LCH_TOOLINST) lpToolinst)
Argument
lpToolinst A pointer to a tool instance object handle. The handle is set to LNULL.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLINST ToolInst;
LCT_STATUS Status;
/* Get the object handle for the untitled worksheet and give
it focus. */
Status = LciTiConstructClass (Context, LCI_TOOLCLASS_SHEET,
LNULL, "Untitled", 0, &ToolInst);
Status = LciTiActivate(ToolInst);
. . .
/* Destroy the tool instance when done. */
Status = LciTiDestroy (&ToolInst);
Definition
Retrieves an enumerated value that represents the toolclass that the tool instance belongs to. If the toolclass that the tool instance belongs to is LCI_TOOLCLASS_CUSTOM, the string that represents the toolclass name is also returned.
Format
LCT_STATUS LCI_CALL LciTiGetClass
(LCH_TOOLINST Toolinst,
lptr(lushort) lpToolClassType,
lushort Buflen,
lptr(lmbcs) lpClassName)
Arguments
Toolinst A tool instance object handle.
lpToolclassType A pointer to storage to which to return the toolclass type. This will be one of the following constants:
Constant Meaning
LCI_TOOLCLASS_SHEET 1-2-3 Sheet toolclass.
LCI_TOOLCLASS_GRAPH 1-2-3 Graph toolclass.
LCI_TOOLCLASS_CUSTOM An add-in custom toolclass.
Buflen The number of bytes available in the buffer pointed to by lpClassName, including room for a null-terminating byte.
lpClassName A pointer to storage to which to return the string value, which is LNULL if the toolclass type is LCI_TOOLCLASS_SHEET or LCI_TOOLCLASS_GRAPH.
Returns
LCS_SUCCESS »Page
LCS_STR_TOO_LONG »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
#include "lcild.h"
. . .
/* Tool procedure that processes tool messages sent by 1-2-3 */
lulong LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
LCT_STATUS Status;
lulong ReturnCode = 0L;
LCH_TOOLCLASS ToolClass;
lushort ToolClassType;
lmbcs ClassName[256];
/* At this point, you would normally already have a toolclass
object stored away somewhere, but if you do need to create
one as you go, you can. */
Status = LciTiGetClass (ToolInst, &ToolClassType, 256, ClassName);
Status = LciTcConstructName (GlobalContext, ToolClassType,
ClassName,&ToolClass);
/* Remainder of tool procedure */
. . .
Status = LciTcDestroy (&ToolClass);
return (ReturnCode);
}
Definition
Retrieves the title that is displayed in the caption bar of the tool instance window.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTiGetTitle
(LCH_TOOLINST Toolinst,
lushort BufLen,
lptr(lmbcs) lpTitle)
Arguments
Toolinst A tool instance object handle.
BufLen The number of bytes available in the buffer pointed to by lpTitle, including room for a null-terminating byte.
lpTitle A pointer to storage to which to return the string value.
Returns
LCS_SUCCESS »Page
LCS_STR_TOO_LONG »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLINST ToolInst;
LCT_STATUS Status;
lmbcs Title[256];
. . .
/* Get a handle to the current active tool instance, and get
its title using 256 characters as an arbitrary length. */
Status = LciTiConstructCurr (Context, &ToolInst);
Status = LciTiGetTitle (ToolInst, 256, Title);
. . .
/* Destroy the tool instance when done. */
Status = LciTiDestroy (&Toolinst);
Definition
Retrieves the length, in bytes, of the title that is displayed in the caption bar of the tool instance window.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTiGetTitleLen
(LCH_TOOLINST Toolinst,
lptr(lushort) lpTitleLen)
Arguments
Toolinst A tool instance object handle.
lpTitleLen A pointer to storage to which to return the length of the title string.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLINST ToolInst;
LCT_STATUS Status;
lushort TitleLen;
lmbcs *pTitle;
/* Get a handle to the current active tool instance, and get
its title. */
Status = LciTiConstructCurr (Context, &ToolInst);
Status = LciTiGetTitleLen (ToolInst, &TitleLen);
pTitle = LocalLock(LocalAlloc(LMEM_MOVEABLE, TitleLen+1));
Status = LciTiGetTitle (ToolInst, TitleLen, pTitle);
. . .
/* Destroy the tool instance when done. */
LocalFree(LocalHandle(pTitle));
Status = LciTiDestroy (&Toolinst);
Definition
Retrieves the Microsoft Windows window handle for the specified tool instance window.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTiGetWindowHandle
(LCH_TOOLINST Toolinst,
lptr(lushort) lphWnd)
Arguments
Toolinst A tool instance object handle.
lphWnd A pointer to storage to which to return the window handle.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcigui.h"
lbool LCI_CALL Iterator (LCH_TOOLINST ToolInst, lptr(lulong)
DataPointer);
. . .
LCH_TOOLCLASS ToolClass;
LCT_STATUS Status;
lushort Count;
lulong Data;
/* Iterate through all Custom tool instances and display a
message in their client area using a Windows function. */
Status = LciTcConstructName (Context, LCI_TOOLCLASS_CUSTOM,
"Custom", &ToolClass);
Status = LciTcGetInstanceCount (ToolClass, &Count);
/* The data that you pass to the iterator function can be
anything you want. This is a Windows utility macro that
stores two shorts inside a long. */
Data = MAKELONG(1,Count);
Status = LciTcIterInstances (Context, ToolClass, Iterator, &Data);
. . .
/* This is the iterator function that will get called by 1-2-3. */
lbool LCI_CALL Iterator (LCH_TOOLINST ToolInst, lptr(lulong)
DataPointer)
{
LCT_STATUS Status;
HWND hWnd;
HDC hDC;
lushort Num;
lushort Total;
char Message[64];
Status = LciTiGetWindowHandle (ToolInst, &(lushort)hWnd);
/* This is the windows code to output text in a window. */
hDC = GetDC(hWnd);
Num = LOWORD(*DataPointer);
Total = HIWORD(*DataPointer);
wsprintf(Message, "Window number %d of %d", Num, Total);
TextOut(hDC, 0, 0, Message, 64);
ReleaseDC(hWnd, hDC);
*DataPointer = MAKELONG(Num+1,Total);
return(LTRUE);
}
Definition
Modifies the title that is displayed in the caption bar of the tool instance window.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciTiSetTitle
(LCH_TOOLINST Toolinst,
lptr(lmbcs) lpTitle)
Arguments
Toolinst A tool instance object handle.
lpTitle A pointer to a lmbcs string that contains the desired title string.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLINST ToolInst;
LCT_STATUS Status;
/* Get a handle to the current active tool instance, and set
its title. */
Status = LciTiConstructCurr (Context, &ToolInst);
Status = LciTiSetTitle (ToolInst, "My Tool Instance");
. . .
/* Destroy the tool instance when done. */
Status = LciTiDestroy (&Toolinst);
A menu object refers to the set of menu items that form a menu at some level (that is, it may be the top level menu or any popup menu).
Function Meaning
LciMnConstructNew »Page Creates a new popup menu or menu bar.
LciMnDeleteItem »Page Deletes an item from a menu.
LciMnDestroy »Page Releases a menu object handle.
LciMnGetCheckFlag »Page Retrieves the checked or unchecked state of a menu item.
LciMnGetEnableFlag »Page Retrieves the enabled or disabled state of a menu item.
LciMnGetItemCount »Page Retrieves the number of menu items in a menu.
LciMnGetLabel »Page Retrieves the label text of a menu item.
LciMnGetSubMenu »Page Retrieves the object handle of a popup menu given a handle to its parent menu.
LciMnInsertItem »Page Inserts a new menu item in a menu.
LciMnRedraw »Page Redraws menu.
LciMnSetCheckFlag »Page Sets the checked or unchecked state of a menu item.
LciMnSetEnableFlag »Page Sets the enabled or disabled state of a menu item.
LciMnSetLabel »Page Replaces the label of the specified menu item with the specified string.
Definition
Creates a new popup menu or menu bar. The menu is initially empty. Items may be added to it using LciMnInsertItem »Page .
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciMnConstructNew
(LCH_CONTEXT Context,
lushort ToolclassType,
lptr(lmbcs) lpCustomClassName,
lushort Id,
lushort MenuType,
lptr(LCH_MENU) lpMenu)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
ToolclassType The type of toolclass for which the new menu is being created. This can be one of the following constants:
Constant Meaning
LCI_TOOLCLASS_SHEET 1-2-3 Sheet toolclass.
LCI_TOOLCLASS_GRAPH 1-2-3 Graph toolclass.
LCI_TOOLCLASS_CUSTOM An add-in custom toolclass.
lpCustomClassName Pointer to a lmbcs string that specifies the toolclass name of a custom toolclass. The toolclass name for a custom toolclass is specified in the TOOL statement in the resource script file. This parameter is ignored if the ToolclassType parameter is LCI_TOOLCLASS_SHEET or LCI_TOOLCLASS_GRAPH.
Id The ID of the new menu. IDs must be unique for a given toolclass. You can use LciTcGetMenuIds »Page to get unique IDs.
MenuType One of the following constants:
Constant Meaning
LCI_MENUTYPE_POPUP Creates a new popup menu.
LCI_MENUTYPE_MENUBAR Create a new top level menu (the top level menu is the horizontal menu bar).
lpMenu A pointer to storage to which to return the object handle of the new menu.
Returns
LCS_SUCCESS »Page
LCS_INVALID_CLASS »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU Menu;
LCT_STATUS Status;
lushort MenuId;
Status = LciTcConstructName(Context,LCI_TOOLCLASS_SHEET,LNULL,
&ToolClass);
Status = LciTcGetMenuIds(ToolClass,1,&MenuId);
Status = LciMnConstructNew(Context,LCI_TOOLCLASS_SHEET,LNULL,
LCI_MENUTYPE_POPUP,&Menu);
. . .
Status = LciMnDestroy(&Menu);
Status = LciTcDestroy(&ToolClass);
Definition
Deletes an item from a menu. If the item is a popup menu, deletes all the items from the popup as well.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciMnDeleteItem
(LCH_MENU Menu,
lushort Id,
lushort IdType)
Arguments
Menu A menu object handle.
Id Either the unique ID of the menu item or its (1-based) position relative to the first item in the menu, depending on the value of IdType.
IdType Specifies how the Id parameter should be interpreted. Can be one of the following constants:
Constant Meaning
LCI_MENUITEM_BYPOSITION The Id parameter gives the position of the menu item within the given menu.
LCI_MENUITEM_BYCOMMAND The Id parameter gives the unique menu ID.
Returns
LCS_SUCCESS »Page
LCS_INVALID_ID »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2);
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCH_MENU ToolMenu;
LCT_STATUS Status;
lushort MenuId;
/* Get the current menu bar associated with the 1-2-3 sheet
class and add one new menu item to it. Assume the "Tools"
submenu is the eighth item by position in the default 1-2-3
sheet menu bar. Normally, you would verify this by checking
its label since other add-ins may have altered the menu.
Appends the new menu item to the bottom of the popup menu. */
Status = LciTcConstructName(Context,
LCI_TOOLCLASS_SHEET,
LNULL,
&ToolClass);
Status = LciTcAddToolProc(ToolClass, ToolProc);
/* You can allocate the menu IDs anytime before inserting the
menu items. */
Status = LciTcGetMenuIds(ToolClass, 1, &MenuId);
Status = LciTcGetMenu(ToolClass, &MenuBar)'
Status = LciMnGetSubMenu(Menubar, 8, ToolMenu);
Status = LciMnInsertItem(ToolMenu,
LCI_MENUITEM_APPEND,
LCI_MENUITEM_BYPOSITION,
MenuId+0,
LCI_MENUITEM_PROC,
(lulong)(MenuId+0),
"&1 Menu Item",
"Description",
LCF_MENUITEM_ENABLED);
. . .
/* When processing is completed, delete the menu item. */
Status = LciMnDeleteItem(ToolMenu, MenuId+0,
LCI_MENUITEM_BYCOMMAND);
Status = LciMnDestroy(&ToolMenu):
Status = LciMnDestroy(&MenuBar);
Status = LciTcDeleteToolProc(ToolClass, ToolProc);
Status = LciTcDestroy(&ToolClass);
Definition
Releases a menu object handle. This merely releases the storage associated with the menu object. It does not delete the menu. To delete a menu, use LciMnDeleteItem »Page .
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciMnDestroy
lptr(LCH_MENU) lpMenu)
Arguments
lpMenu A pointer to a menu object handle. The handle is set to LNULL.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCT_STATUS Status;
Status = LciTcConstructName(Context,
LCI_TOOLCLASS_SHEET,
LNULL,
&ToolClass);
Status = LciTcGetMenu(ToolClass, &MenuBar);
. . .
Status = LciMnDestroy(&MenuBar);
Status = LciTcDestroy(&ToolClass);
Definition
Retrieves the checked or unchecked state of a menu item.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciMnGetCheckFlag
(LCH_MENU Menu,
lushort Id,
lushort IdType,
lptr(lbool) lpCheckFlag)
Arguments
Menu A menu object handle.
Id Either the unique ID of the menu item or its (1-based) position relative to the first item in the menu, depending on the value of IdType.
IdType Specifies how the Id parameter should be interpreted. Can be one of the following constants:
Constant Meaning
LCI_MENUITEM_BYPOSITION The Id parameter gives the position of the menu item within the given menu.
LCI_MENUITEM_BYCOMMAND The Id parameter gives the unique menu ID.
lpCheckFlag Pointer to an lbool in which to return the check flag. LTRUE if the menu item is checked; LFALSE if it is unchecked.
Returns
LCS_SUCCESS »Page
LCS_INVALID_ID »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCH_MENU SubMenu;
LCT_STATUS Status;
lbool CheckFlag;
/* Get check status of first window in 1-2-3. Default is the
untitled window. Assume current is sheet window. */
Status = LciTcConstructCurr(Context,&ToolClass);
Status = LciTcGetMenu(ToolClass, &MenuBar);
/* Assume no new items have been added to the 1-2-3 menu bar
and that Window is still the ninth item. */
Status = LciMnGetSubMenu(MenuBar, 9, &SubMenu);
/* Include menu separators when determining the postition. */
Status = LciMnGetCheckFlag(SubMenu,7,LCI_MENUITEM_BYPOSITION,
&CheckFlag);
. . .
Status = LciMnDestroy(&SubMenu);
Status = LciMnDestroy(&MenuBar);
Status = LciTcDestroy(&ToolClass);
Definition
Retrieves the enabled or disabled state of a menu item.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciMnGetEnableFlag
(LCH_MENU Menu,
lushort Id,
lushort IdType,
lptr(lbool) lpEnableFlag)
Arguments
Menu A menu object handle.
Id Either the unique ID of the menu item, or its (1-based) position relative to the first item in the menu, depending on the value of IdType.
IdType Specifies how the Id parameter should be interpreted. Can be one of the following constants:
Constant Meaning
LCI_MENUITEM_BYPOSITION The Id parameter gives the position of the menu item within the given menu
LCI_MENUITEM_BYCOMMAND The Id parameter gives the unique menu ID.
lpEnableFlag Pointer to an lbool in which to return the enable flag. LTRUE if the menu item is enabled; LFALSE if it is disabled (grayed).
Returns
LCS_SUCCESS »Page
LCS_INVALID_ID »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCH_MENU SubMenu;
LCT_STATUS Status;
lbool EnableFlag;
/* Get UNDO enabled status. */
/* Assume current sheet is sheet window. */
Status = LciTcConstructCurr(Context,&ToolClass);
Status = LciTcGetMenu(ToolClass, &MenuBar);
/* Assume no new items have been added to the 1-2-3 menu bar
and that Edit is still the second item. */
Status = LciMnGetSubMenu(MenuBar, 2, &SubMenu);
/* Undo is first item in Edit menu. */
Status = LciMnGetEnableFlag(SubMenu, 1, LCI_MENUITEM_BYPOSITION,
&EnableFlag);
. . .
Status = LciMnDestroy(&SubMenu);
Status = LciMnDestroy(&MenuBar);
Status = LciTcDestroy(&ToolClass);
Definition
Retrieves the number of menu items in a menu.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciMnGetItemCount
(LCH_MENU Menu,
lptr(lushort) lpItemCount)
Arguments
Menu A menu object handle.
lpItemCount A pointer to an lushort in which to return the number of menu items in Menu.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCH_MENU ToolMenu;
LCT_STATUS Status;
lushort MenuId;
lushort ItemCount;
Status = LciTcConstructName(Context,
LCI_TOOLCLASS_SHEET,
LNULL,
&ToolClass);
Status = LciTcGetMenuIds(Toolclass,1,&MenuId);
Status = LciTcGetMenu(ToolClass, &MenuBar);
Status = LciMnGetSubMenu(MenuBar, 8, &ToolMenu);
/* Add a menu separator if no other add-in has already done so.
Assume the "Tools" menu has nine items by default. */
Status = LciMnGetItemCount(ToolMenu,&ItemCount);
If(ItemCount == 9){
Status = LciMnInsertItem(ToolMenu,
LCI_MENUITEM_APPEND,
LCI_MENUITEM_BYPOSITION,
0,
LCI_MENUITEM_SEPARATOR,
0L,
LNULL,
LNULL,
0L);
Status = LciMnInsertItem)(ToolMenu,
LCI_MENUITEM_APPEND,
LCI_MENUITEM_BYPOSITION,
MenuId+0,
LCI_MENUITEM_PROC,
(lulong)(MenuId+0),
"&1 Menu Item",
"Description",
LCF_MENUITEM_ENABLED);
. . .
Status = LciMnDeleteItem(ToolMenu,
MenuId+0,
LCI_MENUITEM_BYCOMMAND);
/* Delete the menu separator we added previously.
Assume the "Tools" menu has nine items by default. */
Status = LciMnGetItemCount(ToolMenu, &ItemCount);
if(ItemCount == 10){
Status = LciMnDeleteItem(ToolMenu,
10,
LCI_MENUITEM_BYPOSITION);
Status = LciMnDestroy(&ToolMenu);
Status = LciMnDestroy(&MenuBar);
Status = LciTcDestroy(&ToolClass);
Definition
Retrieves the label text of a menu item.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciMnGetLabel
(LCH_MENU Menu,
lushort Id,
lushort IdType,
lushort BufLen,
lptr(lmbcs) lpLabel)
Arguments
Menu A menu object handle.
Id Either the unique ID of the menu item or its (1-based) position relative to the first item in the menu, depending on the value of IdType.
IdType Specifies how the Id parameter should be interpreted. Can be one of the following constants:
Constant Meaning
LCI_MENUITEM_BYPOSITION The Id parameter gives the position of the menu item within the given menu
LCI_MENUITEM_BYCOMMAND The Id parameter gives the unique menu item ID
BufLen The number of bytes available in the buffer pointed to by lpLabel, including room for a null-terminating byte.
lpLabel A pointer to storage to which to return the string value.
Returns
LCS_SUCCESS »Page
LCS_INVALID_ID »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCH_MENU SubMenu;
LCT_STATUS Status;
lmbcs lpLabel[LCI_MAX_FILENAME_LEN];
/* Get name of first Window in 1-2-3. */
/* Assume current is sheet window. */
Status = LciTcConstructCurr(Context,&ToolClass);
Status = LciTcGetMenu(ToolClass, &MenuBar);
/* Assume no new items have been added to the 1-2-3 menu bar
and that Window is still the ninth item. */
Status = LciMnGetSubMenu(MenuBar, 9 &SubMenu);
/* Include menu separators when determining position. */
Status = LciMnGetLabel(SubMenu, 7, LCI_MENU_ITEM_BYPOSITION,
LCI_MAX_FILENAME_LEN,lpLabel);
. . .
Status = LciMnDestroy(&SubMenu);
Status = LciMnDestroy(&MenuBar);
Status = LciTcDestroy(&ToolClass);
Definition
Retrieves the object handle of a popup menu given the object handle of its parent menu.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciMnGetSubMenu
(LCH_MENU Menu,
lushort Index,
lptr(LCH_MENU) lpMenu)
Arguments
Menu A menu object handle.
Index The (1-based) position of the popup within the given menu. It is not possible to use the command ID of the popup in this function.
lpMenu A pointer to storage to which to return the menu object handle. LNULL if the specified menu does not exist or is not a popup menu.
Returns
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCH_MENU ToolMenu;
LCT_STATUS Status;
. . .
/* Get the object handle of the tool popup menu in
the sheet menu. */
Status = LciTcConstructName(Context,
LCI_TOOLCLASS_SHEET,
LNULL,
&ToolClass);
Status = LciTcGetMenu(ToolClass, &MenuBar);
Status = LciMnGetSubMenu(MenuBar,8,&ToolMenu);
. . .
Status = LciMnDestroy(&ToolMenu);
Status = LciMnDestroy(&MenuBar);
Status = LciTcDestroy(&ToolClass);
Definition
Inserts a new menu item in a menu.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciMnInsertItem
(LCH_MENU Menu,
lushort Id,
lushort IdType,
lushort NewItemId,
lushort ItemType,
lulong ItemData,
lptr(lmbcs) lpLabel,
lptr(lmbcs) lpLongPrompt,
lulong OptionFlags)
Arguments
Menu A menu object handle.
Id Specifies the menu item before which the new menu item is to be inserted. It is either the unique ID of the menu item or its (1-based) position relative to the first item in the menu. The IdType parameter determines which is used. This value can also be LCI_MENUITEM_APPEND, in which case, the new menu item is appended to the end of Menu.
IdType Specifies how the Id parameter should be interpreted. Can be one of the following constants:
Constant Meaning
LCI_MENUITEM_BYPOSITION The Id parameter gives the position of the menu item within the given menu of where to place the new menu item.
LCI_MENUITEM_BYCOMMAND The Id parameter gives the unique menu ID of where to place the new menu item.
Note If Id is LCI_MENUITEM_APPEND, then IdType must be LCI_MENUITEM_BYPOSITION.
NewItemId Specifies the unique ID of the new menu item. This must be a unique ID for the toolclass. Can be 0 if ItemType is LCI_MENUITEM_SEPARATOR. See LciTcGetMenuIds »Page for obtaining unique IDs for a toolclass.
ItemType Can be one of the following constants:
Constant Meaning
LCI_MENUITEM_DIALOG The menu item leads to a dialog box.
LCI_MENUITEM_EXECSTR The menu item runs a macro string.
LCI_MENUITEM_POPUP The menu item leads to a popup menu.
LCI_MENUITEM_PROC The menu item sends a TOOLMSG_MENUPROC message to the tool procedure. At that point, the code can be executed.
LCI_MENUITEM_SEPARATOR The menu item is a separator.
ItemData If ItemType is LCI_MENUITEM_DIALOG, contains the resource ID of a dialog box to be displayed when the menu item is selected.
If ItemType is LCI_MENUITEM_EXECSTR, contains a pointer to a lmbcs string that will be interpreted as a macro string to be run when the menu item is selected.
If ItemType is LCI_MENUITEM_POPUP, contains the menu handle of the new popup.
If ItemType is LCI_MENUITEM_PROC, contains a value that will be passed to the tool procedure in the first parameter of a TOOLMSG_MENUPROC message.
Note This parameter is ignored if ItemType is LCI_MENUITEM_SEPARATOR.
lpLabel Pointer to a lmbcs string that contains the menu item text. Should be LNULL if ItemType is LCI_MENUITEM_SEPARATOR. If the string contains an & (ampersand), the character following the & will be used as the menu item mnemonic.
lpLongPrompt Pointer to lmbcs string that contains the long prompt to be displayed when the menu item is highlighted (or LNULL for no long prompt). If LNULL is specified, 1-2-3 will send a TOOLMSG_LONGPROMPT message to the tool procedure when the menu item is highlighted.
OptionFlag One or more of the following flags OR'd together:
Constant Meaning
LCF_MENUITEM_CHECKED The menu item will be displayed with a check mark.
LCF_MENUITEM_DISABLED The menu item will be disabled.
LCF_MENUITEM_ENABLED The menu item will be enabled.
LCF_MENUITEM_GRAYED The menu item will be grayed and disabled.
LCF_MENUITEM_UNCHECKED The menu item will be displayed without a check mark.
LCF_MENUITEM_NOREDRAW The menu item will not be redrawn when an item is inserted.
Note LCF_MENUITEM_CHECKED and LCF_MENUITEM_UNCHECKED cannot be used together. LCF_MENUITEM_DISABLED and LCF_MENUITEM_ENABLED cannot be used together.
Note With the addition of LCF_MENUITEM_GRAYED, LCF_MENUITEM_DISABLED is no longer grayed. To have the menuitem disabled and grayed, the LCF_MENUITEM_GRAYED flag must be passed to it.
Returns
LCS_SUCCESS »Page
LCS_INVALID_ID »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2);
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCH_MENU ToolMenu;
LCT_STATUS Status;
lushort MenuId;
/* Get the current menu bar associated with the 1-2-3 sheet class
and add one new menu item to it. Assume the "Tools" submenu
is the eighth item by position in the default 1-2-3 sheet menu
bar. Normally, you would verify this by checking its label
since other add-ins may have altered the menu. Appends the
new menu item to the bottom of the popup menu. */
Status = LciTcConstructName(Context,
LCI_TOOLCLASS_SHEET,
LNULL,
&ToolClass);
Status = LciTcAddToolProc(ToolClass, ToolProc);
/* You can allocate the menu IDs anytime before inserting the
menu items. */
Status = LciTcGetMenuIds(ToolClass, 1, &MenuId);
Status = LciTcGetMenu(ToolClass, &MenuBar)'
Status = LciMnGetSubMenu(Menubar, 8, ToolMenu);
Status = LciMnInsertItem(ToolMenu,
LCI_MENUITEM_APPEND,
LCI_MENUITEM_BYPOSITION,
MenuId+0,
LCI_MENUITEM_PROC,
(lulong)(MenuId+0),
"&1 Menu Item",
"Description",
LCF_MENUITEM_ENABLED);
. . .
/* When processing is completed, delete the menu item. */
Status = LciMnDeleteItem(ToolMenu, MenuId+0,
LCI_MENUITEM_BYCOMMAND);
Status = LciMnDestroy(&ToolMenu):
Status = LciMnDestroy(&MenuBar);
Status = LciTcDeleteToolProc(ToolClass, ToolProc);
Status = LciTcDestroy(&ToolClass);
Definition
Forces a redraw of the 123 menu.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciMnRedraw
(LCH_CONTEXT Context)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2);
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCH_MENU ToolMenu;
LCT_STATUS Status;
lushort MenuId;
/* Get the current menu bar associated with the 1-2-3 sheet class
and add one new menu. */
Status = LciTcConstructName(Context,
LCI_TOOLCLASS_SHEET,
LNULL,
&ToolClass);
Status = LciTcAddToolProc(ToolClass, ToolProc);
/* You can allocate the menu IDs anytime before inserting the
menu items. */
Status = LciTcGetMenuIds(ToolClass, 1, &MenuId);
Status = LciTcGetMenu(ToolClass, &MenuBar);
Status = LciMnGetSubMenu(Menubar, 5, ToolMenu);
Status = LciMnInsertItem(ToolMenu,
LCI_MENUITEM_APPEND,
LCI_MENUITEM_BYPOSITION,
MenuId + 0,
LCI_MENUITEM_PROC,
(lulong)(MenuId + 0),
"&1 Menu Item",
"Description",
LCF_MENUITEM_ENABLED);
/* Redraw the new menu. */
Status = LciMnRedraw(Context);
/* When processing is completed, delete the menu item. */
Status = LciMnDeleteItem(ToolMenu, MenuId + 0,
LCI_MENUITEM_BYCOMMAND);
Status = LciMnDestroy(&ToolMenu);
Status = LciMnDestroy(&MenuBar);
Status = LciTcDeleteToolProc(ToolClass, ToolProc);
Status = LciTcDestroy(&ToolClass);
Definition
Sets the checked or unchecked state of a menu item.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciMnSetCheckFlag
(LCH_MENU Menu,
lushort Id,
lushort IdType,
lbool CheckFlag)
Arguments
Menu A menu object handle.
Id Either the unique ID of the menu item or its (1-based) position relative to the first item in the menu, depending on the value of IdType.
IdType Specifies how the Id parameter should be interpreted. Can be one of the following constants:
Constant Meaning
LCI_MENUITEM_BYPOSITION The Id parameter gives the position of the menu item within the given menu.
LCI_MENUITEM_BYCOMMAND The Id parameter gives the unique menu item ID.
CheckFlag The value to which to set the check flag: LTRUE if the menu item is to be checked; LFALSE if it is to be unchecked.
Returns
LCS_SUCCESS »Page
LCS_INVALID_ID »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCH_MENU ToolMenu;
LCT_STATUS Status;
lushort MenuId;
lushort ItemCount;
/* Get the current menu bar associated with the 1-2-3 sheet
class and add one new menu item to it. Assume the "Tools"
submenu is the eighth item by position in the default 1-2-3
sheet menu bar. Normally, you would verify this by checking
its label since other add-ins may have altered the menu.
Appends the new menu item to the bottom of the popup menu. */
Status = LciTcConstructName(Context, LCI_TOOLCLASS_SHEET, LNULL,
&ToolClass);
/* You can allocate the menu IDs anytime before inserting the
menu items. */
Status = LciTcGetMenuIds(ToolClass, 1, &MenuId);
Status = LciTcGetMenu(ToolClass, &MenuBar);
Status = LciMnGetSubMenu(MenuBar, 8, &ToolMenu);
Status = LciMnInsertItem(ToolMenu, LCI_MENUITEM_APPEND,
LCI_MENUITEM_BYPOSITION, MenuId+0, LCI_MENUITEM_PROC,
(lulong)(MenuId), "&Check This",
"Description", LCF_MENUITEM_ENABLED);
Status = LciMnSetCheckFlag(ToolMenu, MenuId,
LCI_MENUITEM_BYCOMMAND, LTRUE);
. . .
Status = LciMnDeleteItem(ToolMenu, MenuId+0,
LCI_MENUITEM_BYCOMMAND);
Status = LciMnDestroy(&ToolMenu);
Status = LciMnDestroy(&MenuBar);
Status = LciTcDestroy(&ToolClass);
Definition
Sets the enabled or disabled state of a menu item.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciMnSetEnableFlag
(LCH_MENU Menu,
lushort Id,
lushort IdType,
lsshort EnableFlag)
Arguments
Menu A menu object handle.
Id Either the unique ID of the menu item or its (1-based) position relative to the first item in the menu, depending on the value of IdType.
IdType Specifies how the Id parameter should be interpreted. Can be one of the following constants:
Constant Meaning
LCI_MENUITEM_BYPOSITION The Id parameter gives the position of the menu item within the given menu
LCI_MENUITEM_BYCOMMAND The Id parameter gives the unique menu item ID.
EnableFlag The values of the enable flag can be:
LCI_MENUITEM_ENABLED if the menu item is to be enabled.
LCI_MENUITEM_GRAYED if it is to be disabled and grayed.
LCI_MENUITEM_DISABLED if the menu is to be disabled but not grayed
Returns
LCS_SUCCESS »Page
LCS_INVALID_ID »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
#include "winresid.h"
lulong ToolProc(LCH_TOOLINST Toolinst,
lushort Msg,
lulong P1,
lulong P2);
LCH_TOOLCLASS Toolclass;
. . .
/* Create a toolclass object referring to the sheet tool
and add the add-in tool procedure. */
LCT_STATUS Status;
Status = LciTcConstructName(Context, LCI_TOOLCLASS_SHEET,
LNULL, &Toolclass);
Status = LciTcAddToolProc(Toolclass, ToolProc);
. . .
/* Tool procedure that processes tool messages from
1-2-3 */
lulong ToolProc (LCH_TOOLINST Toolinst, lushort Msg,
lulong P1,lulong P2)
{
lulong ReturnCode = 0L;
switch(Msg){
/* Disable the close item every time the file menu
pops up. */
case TOOLMSG_POPUP:
if (ID_F == (lushort)P1){
LCH_MENU FileMenu, MainMenu;
LciTcGetMenu(Toolclass, &MainMenu);
LciMnGetSubMenu(MainMenu, 1, &FileMenu);
LciMnSetEnableFlag(FileMenu, ID_FC,
LCI_MENUITEM_BYCOMMAND, LFALSE);
LciMnDestroy(&FileMenu);
LciMnDestroy(&MainMenu);
}
/* Fall through */
default:
ReturnCode = LciTcDefToolProc(Toolclass, Toolinst,
Msg, P1, P2);
}
return(ReturnCode);
}
. . .
/* When the add-in is finished, it needs to remove the
tool procedure and destroy the toolclass object. */
LciTcDeleteToolProc(Toolclass, ToolProc);
LciTcDestroy(&Toolclass);
Definition
Replaces the label of the specified menu item with the specified string. If the specified string contains an & (ampersand), the character following the & is used as the mnemonic for the menu item.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciMnSetLabel
(LCH_MENU Menu,
lushort Id,
lushort IdType,
lptr(lmbcs) lpLabel)
Arguments
Menu A menu object handle.
Id Either the unique ID of the menu item or its (1-based) position relative to the first item in the menu, depending on the value of IdType.
IdType Specifies how the Id parameter should be interpreted. Can be one of the following constants:
Constant Meaning
LCI_MENUITEM_BYPOSITION The Id parameter gives the position of the menu item within the given menu.
LCI_MENUITEM_BYCOMMAND The Id parameter gives the unique menu item ID.
lpLabel A pointer to a lmbcs string that contains the desired menu label.
Returns
LCS_SUCCESS »Page
LCS_INVALID_ID »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCH_MENU SubMenu;
LCT_STATUS Status;
/* Change Undo text to "Undoit". */
/* Assume current sheet is the sheet window. */
Status = LciTcConstructCurr(Context, &ToolClass);
Status = LciTcGetMenu(ToolClass, &Menubar);
/* Assume no new items have been added to the 1-2-3 menu bar
and that Edit is still the second item. */
Status = LciMnGetSubMenu(MenuBar, 2, &SubMenu);
/* Undo is first menu item. */
Status = LciMnSetLabel(SubMenu, 1, LCI_MENUITEM_BYPOSITION,
"&Undoit");
. . .
Status = LciMnDestroy(&Submenu);
Status = LciMnDestroy(&Menubar);
Status = LciTcDestroy(&ToolClass);
Preset and validate objects are pseudo objects that are passed in the first message parameter of a TOOLMSG_PRESET or a TOOLMSG_VALIDATE message. They can be used to get the handle of the control for which the message is being sent and the value associated with the preset or validate message. (The value is the one specified in the PRESET or VALIDATE statement in the resource script file.)
Note There is no way to create one of these objects; they are created internally so that the handle can be passed in a message .
Function Meaning
LciPsGetControl »Page Retrieves the handle to the control for which the preset message is being sent.
LciPsGetValue »Page Retrieves the value associated with a preset.
LciVlGetControl »Page Retrieves the handle to the control for which the validate message is being sent.
LciVlGetValue »Page Retrieves the value associated with a validate message.
Definition
Retrieves the handle to the control for which the preset message is being sent.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciPsGetControl
(LCH_PRESET Preset,
lptr(LCH_CONTROL) lpControl)
Arguments
Preset A Preset object handle.
lpControl A pointer to storage to which to return the control handle.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
/* Tool procedure that processes tool messages sent by 1-2-3 */
lulong LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
LCT_STATUS Status;
lulong ReturnCode = 0L;
LCH_CONTROL Control;
lulong ID;
switch(Msg)
{
case TOOLMSG_DLGPRESET:
/* Each dialog control with the PRESET attribute will cause
this message to be sent. Use the preset value to identify it. */
Status = LciPsGetControl ((LCH_PRESET)P1, &Control);
Status = LciPsGetValue ((LCH_PRESET)P1, &ID);
switch(ID)
{
case CONTROL_ID:
/* Communicate with the control by sending it a Windows message.
These can be standard Windows messages or 1-2-3 specific
Windows messages. */
Status = LciTcSendControlMsg (ToolClass, Control,
WM_SETTEXT, 0L, "Control Text");
break;
}
break;
/* Remainder of tool procedure */
. . .
}
return (ReturnCode);
}
Definition
Retrieves the value associated with a preset. The value is specified with the PRESET statement in the resource file. See the Developer's Guide Part 5, Chapter 1 for more information.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciPsGetValue
(LCH_PRESET Preset,
lptr(lulong) lpValue)
Arguments
Preset A Preset object handle.
lpValue A pointer to an lulong in which to return the preset value.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
/* Tool procedure that processes tool messages sent by 1-2-3 */
lulong LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
LCT_STATUS Status;
lulong ReturnCode = 0L;
LCH_CONTROL Control;
lulong ID;
switch(Msg){
case TOOLMSG_DLGPRESET:
/* Each dialog control with the PRESET attribute will cause
this message to be sent. Use the preset value to identify it. */
Status = LciPsGetControl ((LCH_PRESET)P1, &Control);
Status = LciPsGetValue ((LCH_PRESET)P1, &ID);
switch(ID)
{
case CONTROL_ID:
/* Communicate with the control by sending it a Windows message.
These can be standard Windows messages or 1-2-3 specific
Windows messages. */
Status = LciTcSendControlMsg (ToolClass, Control,
WM_SETTEXT, 0L, "Control Text");
break;
}
break;
/* Remainder of tool procedure */
. . .
}
return (ReturnCode);
}
Definition
Retrieves the handle to the control for which the validate message is being sent.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciVlGetControl
(LCH_VALIDATE Validate,
lptr(LCH_CONTROL) lpControl)
Arguments
Validate A validate object handle.
lpControl A pointer to storage to which to return the control handle.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
/* Tool procedure that processes tool messages sent by 1-2-3 */
lulong LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
LCT_STATUS Status;
lulong ReturnCode = 0L;
LCH_CONTROL Control;
lulong ID1, ID2;
switch(Msg) {
case TOOLMSG_DLGVALIDATE:
/* Each dialog control with the VALIDATE attribute will cause
this message to be sent. Use the validate value to
identify it. */
Status = LciVlGetControl ((LCH_VALIDATE)P1, &Control);
Status = LciVlGetValue ((LCH_VALIDATE)P1, &ID1, &ID2);
switch(ID1)
{
case CONTROL_ID:
{
/* Communicate with the control by sending it a Windows message.
These can be standard Windows messages or 1-2-3 specific
Windows messages. */
lmbcs ControlText[50];
Status = LciTcSendControlMsg (ToolClass,
Control,WM_GETTEXT, 50,
ControlText);
break;
}
}
break;
/* Remainder of tool procedure */
. . .
}
return (ReturnCode);
}
Definition
Retrieves the values associated with a validate message. The values are specified with the VALIDATE statement in the resource file. See the Developer's Guide Part 5, Chapter 1 for more information.
Format
#include "lcicomn.h"
#include "lcigui.h"
LCT_STATUS LCI_CALL LciVlGetValue
(LCH_VALIDATE Validate,
lptr(lulong) lpValue1
lptr(lulong) lpValue2)
Arguments
Validate A Validate object handle.
lpValue1 A pointer to an lulong in which to return the first validate value as defined with the VALIDATE statement in the resource file.
lpValue2 A pointer to an lulong in which to return the second validate value.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
/* Tool procedure that processes tool messages sent by 1-2-3 */
lulong LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
LCT_STATUS Status;
lulong ReturnCode = 0L;
LCH_CONTROL Control;
lulong ID1, ID2;
switch(Msg)
{
case TOOLMSG_DLGVALIDATE:
/* Each dialog control with the VALIDATE attribute will
cause this message to be sent. Use the validate value
to identify it. */
Status = LciVlGetControl ((LCH_VALIDATE)P1, &Control);
Status = LciVlGetValue ((LCH_VALIDATE)P1, &ID1, &ID2);
switch(ID1){
case CONTROL_ID: {
/* Communicate with the control by sending it a Windows message.
These can be standard Windows messages or 1-2-3 specific
Windows messages. */
lmbcs ControlText[50];
Status = LciTcSendControlMsg(ToolClass,
Control,WM_GETTEXT,50,
ControlText);
break;
}
}
break;
/* Remainder of tool procedure */
. . .
}
return (ReturnCode);
}
These messages are sent to the tool procedure from 1-2-3 to notify a tool when certain GUI events occur in 1-2-3 for Windows. See LciTcAddToolProc »Page , LciTcDeleteToolProc »Page , LciTcDefToolProc »Page , and LciTcRegister »Page for more information about tool procedures. Each message is represented by three arguments in the tool procedure. A tool procedure has the following prototype:
lulong LCI_CALL ToolProc(LCH_TOOLINST toolinst,
lushort MSG,
lulong P1,
lulong P2)
The tool message is contained in the MSG parameter. P1 and P2 are different for each message.
In most cases an add-in will handle messages for menu items or dialog boxes created by the add-in. The add-in must decide whether to handle messages or whether to pass them to the default tool procedure. For menu item related messages, the add-in can check the item ID that is passed in one of the message parameters. For dialog related messages, the dialog handle is not always available and a static variable might need to be used to indicate whether to handle a stream of related messages. The following example illustrates this usage:
/* Standard Dialog Box Coding Standard:
(dialog box messages only)
============================================================== */
lulong LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
static BOOL MyDialog;
switch(Msg) {
case TOOLMSG_COMMAND:
/* This will allow you to uniquely identify a dialog box launched
from a menu choice. FirstId and LastId would be the first and
last command IDs allocated by LciTcGetMenuIds(). */
if(((WORD)P1 >= FirstId) && ((WORD)P1 <= LastId)){
MyDialog = LTRUE;
}
break;
case TOOLMSG_DLGINIT:
/* This will allow you to uniquely identify a dialog box launched
by the add-in using LciTcRunDialog, which also sets the value
of DialogHandle (another static variable). */
if(MyDialog == LFALSE) { /* If the flag is already true,
the dialog was run from a menu. */
if((LCH_DIALOG)P2 == DialogHandle
MyDialog = LTRUE;
}
break;
/* Other dialog messages */
case TOOLMSG_DLGxxxx:
if (MyDialog == LTRUE){
/* Put code here. */
}
break;
case TOOLMSG_DLGTERM:
/* When the dialog box terminates, clear the flag. */
{
MyDialog = LFALSE;
}
break;
default:
/* Messages not processed should be passed along to the next
tool procedure in the list for a given toolclass. */
ReturnCode = LciTcDefToolProc(ToolClass, ToolInst,
Msg, P1, P2);
}
return(ReturnCode);
} /* End of ToolProc */
These messages are sent to the tool procedure to notify a tool when certain events occur in the 1-2-3 for Windows Graphical Input Manager.
Message Meaning
TOOLMSG_ACTIVATE »Page Sent whenever focus is switched to a different tool instance window.
TOOLMSG_COMMAND »Page Sent each time 1-2-3 processes a WM_COMMAND message.
TOOLMSG_DLGEXECSTR »Page Sent whenever a control in a dialog triggers an EXECUTE action.
TOOLMSG_DLGINIT »Page Sent during dialog initialization, before the dialog box is displayed.
TOOLMSG_DLGPOSTDISPLAY »Page Sent immediately after a dialog box is displayed.
TOOLMSG_DLGPREDISPLAY »Page Sent when 1-2-3 is about to display a dialog box.
TOOLMSG_DLGPRESET »Page Sent for each control in the dialog that has a PRESET statement associated with it. Allows preset values for controls to be filled in before the dialog is displayed.
TOOLMSG_DLGPROC »Page Sent whenever a control in a dialog triggers a PROCEDURE action.
TOOLMSG_DLGTERM »Page Sent just before the dialog window is destroyed.
TOOLMSG_DLGVALIDATE »Page Sent whenever a control in a dialog triggers a VALIDATE action. Allows control states to be validated before the dialog box is executed.
TOOLMSG_HELP »Page Sent when the Help key (F1) is pressed.
TOOLMSG_ICONBAR_INIT »Page Sent whenever a new tool instance window is opened to determine whether the SmartIcon palette should be displayed for that window.
TOOLMSG_LONGPROMPT »Page Sent every time the menu highlight moves from one menu item to another. Gives the add-in a chance to display a long prompt.
TOOLMSG_MENUEXECSTR »Page Sent when a menu item is selected that has an EXECUTE statement associated with it.
TOOLMSG_MENUPROC »Page Sent when a menu item is selected that has a PROCEDURE statement associated with it.
TOOLMSG_MENURESET »Page Sent every time the core processes a {menu-reset} macro.
TOOLMSG_POPUP »Page Sent immediately before a popup menu is dropped down. This gives the add-in a chance to modify the menu before it is displayed.
Definition
Sent whenever focus is switched from one tool instance window to another. A tool instance window is a sheet window, graph window, key transcript window, or custom add-in window. The ToolInst parameter passed to the tool procedure contains the tool instance handle of the tool instance that is receiving focus.
Parameter Description
p1 Not used.
p2 Not used.
Return
Ignored.
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcigui.h"
lulong LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
switch (Msg) {
case TOOLMSG_ACTIVATE:
{
/* Display a message box every time focus is switched to a
different tool instance window. */
HWND hwnd;
LciTiGetWindowHandle(ToolInst, &hwnd);
MessageBox(hwnd, "New document activated!, "Message",
MB_OK);
break;
}
. . .
}
return(ReturnCode);
}
Definition
Sent every time 1-2-3 processes a WM_COMMAND message.
Parameter Description
p1 Contains the command ID of the menu item that generated the WM_COMMAND message.
p2 Ignored.
Return
LTRUE if the command was handled: LFALSE otherwise. Returning LTRUE prevents 1-2-3 from executing the commands that are normally associated with the item.
Example
#include "lcicomn.h"
#include "lcigui.h"
#include "winresid.h"
/* Tool procedure that processes tool message sent by 1-2-3 */
lulong LCI_CALL ToolProc(LCLH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
switch(Msg) {
/* These menu-related messages will be sent to the Tool Procedure
automatically, without any special Lci calls or resource
statements. Since you get these messages for all menu items
and popups, you should ALWAYS check the command ID in each
case before acting on the message. */
case TOOLMSG_COMMAND:
/* Use this message to handle all menu item selections for both
1-2-3 and add-ins. For add-ins, this is less flexible than
handling TOOLMSG_MENUPROC, which also lets you pass data in
one of the parameters. 1-2-3 menu command IDs are defined in
WINRESID.H. */
/* This is how you would block a 1-2-3 menu command from being
executed. This does not affect choices made from the 1-2-3
Classic menu. */
if((WORD)P1 == ID_FO) /* File Open menu command ID */
ReturnCode = LTRUE; /*Return TRUE to block; otherwise, */
/* pass it on.*/
}
. . .
return(ReturnCode);
}
Definition
Sent whenever a control in a dialog triggers an EXECUTE action. Control actions are specified in the DIALOGSTRUCT statement in the resource file. For more information on control triggers and actions, see the Developer's Guide Part 5, Chapter 1.
Parameter Description
p1 Pointer to execute string.
p2 Reserved.
Return
Ignored.
Example
#include "lcicomn.h"
#include "lcigui.h"
/* Tool procedure that processes tool messages sent by 1-2-3 */
lulong LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
switch(Msg){
case TOOLMSG_DLGEXECSTR:
/* This will replace the string in the resource EXECUTE statement
with an alternative. */
ReturnCode = LciTcDefToolProc(ToolClass, ToolInst, Msg,
"(indicate \"EXECUTE intercepted\"}", P2);
break;
default;
/* Messages not processed should be passed along to the next
tool procedure in the list for a given toolclass. */
ReturnCode = LciTcDefToolProc(ToolClass, ToolInst,
, P1, P2);
break;
}
return(ReturnCode);
}
Definition
Sent during dialog initialization, before the dialog box is displayed.
Parameter Description
p1 Not used.
p2 The dialog handle of the current dialog box. This handle is the handle returned in a call to LciTcRunDialog »Page .
Return
Ignored.
Example
#include "lcicomn.h"
#include "lcigui.h"
lulong LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
static BOOL MyDialog;
switch(Msg) {
case TOOLMSG_DLGINIT:
/* This will allow you to uniquely identify a dialog box launched
by the add-in using LciTcRunDialog, which also sets the value
of DialogHandle (another static variable). */
if(MyDialog == LFALSE) { /* If the flag is already
true, the dialog was run from a menu. */
if((LCH_DIALOG)P2 == DialogHandle
MyDialog = LTRUE;
}
break;
}
return(ReturnCode);
} /* End of ToolProc */
Definition
Sent immediately after a dialog box is displayed.
Parameter Description
p1 Not used.
p2 Reserved.
Return
Ignored.
Example
#include "lcicomn.h"
#include "lcigui.h"
lulong LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
static HWND hwndPrevDialog;
switch(Msg)
{
case TOOLMSG_DLGPOSTDISPLAY:
/* An add-in that manages its own dialog nesting might want to
destroy the previous dialog at this point. */
DestroyWindow(hwndPrevDialog);
break;
. . .
}
return(ReturnCode);
} /* End of ToolProc */
Definition
Sent immediately before a dialog box is displayed.
Parameter Description
p1 The window handle (HWND) of the dialog.
p2 Reserved.
Return
Ignored.
Example
#include "lcicomn.h"
#include "lcigui.h"
/* Tool procedure that processes tool messages sent by 1-2-3 */
lulong LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
switch(Msg){
case TOOLMSG_DLGPREDISPLAY:
/* This is an example of how to manipulate the dialog box
directly by calling Windows functions in his case, setting
the screen postion). The numbers used are arbitrary. For more
information on Windows functions, see the Windows SDK. */
SetWindowPos((HWND)P1, NULL, 0, 0, 100, 100, SWP_NOZORDER);
break;
. . .
}
return(ReturnCode);
}
Definition
Sent for each control in the dialog that has a PRESET statement associated with it. Allows preset values for controls to be filled in before the dialog is displayed. PRESET statements are defined in the DIALOGSTRUCT statement in the resource file. See the Developer's Guide Part 5, Chapter 1 for more information.
Parameter Description
p1 Handle to a preset information block (LCH_PRESET). The handle of the control and the value specified for the preset in the resource file can be obtained by calling LciPsGetControl and LciPsGetValue using this handle.
p2 Reserved.
Return
Ignored.
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcigui.h"
/* Tool procedure that processes tool messages sent by 1-2-3 */
lulong LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
LCH_CONTROL Control;
lulong ID;
switch(Msg){
case TOOLMSG_DLGPRESET:
/* Use this message to set the initial state of a control,
especially those controls that INITCTL cannot be used with
(like edit controls). Use the preset value to identify the
control if you have more than one control with a PRESET
attribute. You would normally NOT pass this along to the
default tool procedure after handling it. */
Status = LciPsGetControl((LCH_PRESET)P1, &Control);
Status = LciPsGetValue((LCH_PRESET)P1, &ID);
/* Communicate with the control by sending it a Windows message.
These can be standard Windows messages or 1-2-3 specific
Windows messages. The following sets the initial value of the
edit control to "DEFAULT". */
Status = LciTcSendControlMsg(ToolClass, Control, WM_SETTEXT
OL "DEFAULT");
break;
. . .
}
return(ReturnCode);
}
Definition
Sent whenever a control in a dialog triggers a PROCEDURE action. Control actions are specified in the DIALOGSTRUCT statement in the resource file. For more information on trigger controls, see the Developer's Guide Part 5, Chapter 1.
Parameter Description
p1 The procedure ID that was specified with the PROCEDURE statement in the resource file.
p2 Reserved.
Return
Ignored.
Example
#include "lcicomn.h"
#include "lcigui.h"
#include "lcicell.h"
/* Tool procedure that processes tool messages sent by 1-2-3 */
lulong LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
LCH_CELL Cell;
lulong ReturnCode = 0L;
switch(Msg){
case TOOLMSG_DLGPROC:
/* Use this message to perform any operation. Use the procedure
ID to identify the control if you have more than one control
with a PROCEDURE action. You would normally NOT pass this
along to the default tool procedure after handling it. */
/* This is an example of how to affect cells in response to a
button being pushed. You must save Context in a global
variable in order to use it in a tool procedure. */
/* Create cell object */
Status = LciClConstructCurr(GlobalContext, &Cell);
/* Set its contents. */
Status = LciClSetContentsStr(Cell, "Button Pushed");
/* Release the object. */
Status = LciClDestroy(&Cell);
break;
. . .
}
return(ReturnCode)
}
Definition
Sent just before the dialog window is destroyed.
Parameter Description
p1 Window handle (HWND) of the dialog box.
p2 Reserved.
Return
LTRUE if the tool will be responsible for destroying the dialog, LFALSE otherwise. If the tool returns LTRUE, it is expected to call the Windows SDK function DestroyWindow to destroy the dialog window.
Example
#include "lcicomn.h"
#include "lcigui.h"
/* Tool procedure that processes tool messages sent by 1-2-3 */
lulong LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
switch(Msg){
case TOOLMSG_DLGTERM:
/* Use this message to perform cleanup operations. It is a good
place to remove and destroy the tool procedure if it is no
longer needed. You would normally NOT pass this along to the
default tool procedure after handling it. */
/* If you add the tool procedure immediately before calling
LciTcRunDialog, then this is a good place to remove it. */
Status = LciTcDeleteToolProc(ToolClass, ToolProc):
Status = LciTcDestroy(&ToolClass);
break;
. . .
}
return(ReturnCode);
}
Definition
Sent whenever a control in a dialog triggers a VALIDATE action. It can be used to test the state of a control before the dialog box terminated. Control actions are defined in the DIALOGSTRUCT statement in the resource file. The return value can be tested using an IF statement in the resource file. See the Developer's Guide Part 5, Chapter 1 for more information.
Parameter Description
p1 Handle to a validation information block (LCH_VALIDATE). The handle of the control and the value specified in the VALIDATE statement in the resource file can be obtained by calling LciVlGetControl and LciVlGetValue using this handle.
p2 Reserved.
Return
An integer that can be tested conditionally in the resource file.
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcigui.h"
/* Tool procedure that processes tool messages sent by 1-2-3 */
lulong LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
LCH_CONTROL Control;
lulong ID1, ID2;
lmbcs String[256];
switch(Msg){
case TOOLMSG_DLGVALIDATE:
/* Use this message to get the final state of a control,
especially those controls that IF SET cannot be used with
(like edit controls). Use the validate value to identify the
control if you have more than one control with a VALIDATE
action. You would normally NOT pass this along to the default
tool procedure after handling it. */
Status = LciVlGetControl((LCH_VALIDATE)P1, &Control);
Status = LciVLGetValue((LCH_VALIDATE)P1, &ID1, &ID2);
/* Communicate with the control by sending it a Windows message.
These can be standard Windows messages or 1-2-3 specific
Windows messages. The following will get the text out of the
edit control. */
Status = LciTcSendControlMsg(ToolClass, Control, WM_GETTEXT,
256, String);
ReturnCode = 1L;
break;
. . .
}
return(ReturnCode);
}
Definition
Sent when the Help key (F1) is pressed.
Parameter Description
p1 Contains the help ID that is either the command ID of the current highlighted menu item or the command ID of the current active control in a dialog box.
p2 Not used.
Return
Ignored.
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcigui.h"
lulong LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
static BOOL MyDialog;
switch(Msg)
{
case TOOLMSG_HELP:
if (MyDialog)
{
HWND hwnd;
LciTiGetWindowHandle(ToolInst, &hwnd);
/* Call add-in specific WinHelp. When the toolproc is removed
or the add-in is terminated, WinHelp should be called with
the HELP_QUIT parameter. */
WinHelp(hwnd, "ADDIN.HLP", HELP_INDEX, NULL);
}
break;
. . .
}
return(ReturnCode);
}
Definition
Sent whenever a new tool instance window is created to determine whether the SmartIcon Palette should be initialized for the new window.
Parameter Description
p1 not used.
p2 Reserved.
Return
A non-zero value indicates that the SmartIcon Palette should be initialized for the new tool instance window.
Example
#include "lcicomn.h"
#include "lcigui.h"
. . .
lulong LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode;
switch (Msg) {
case TOOLMSG_ICONBAR_INIT:
{
/* Suppress display of the SmartIcon Palette for this window. */
ReturnCode = 0L;
break;
}
. . .
}
return(ReturnCode);
}
Definition
Sent each time the menu highlight moves from one menu item to another if there is no long prompt specified for the highlighted menu item. Gives the add-in a chance to change the long prompt or to display a long prompt if the menu item was inserted in the menu with a NULL long prompt string. This message is always sent for menu items that are part of the original menu specified in the MENU statement in the resource file.
Parameter Description
p1 The command ID of the currently selected (highlighted) menu item.
p2 Pointer to a buffer in which to return a long prompt string.
Return
If non-zero value is returned, 1-2-3 will display the string.
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcigui.h"
/* Tool procedure that processes tool messages sent by 1-2-3 */
lulong LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
switch(Msg){
case TOOLMSG_LONGPROMPT:
/* This will replace the description 1-2-3 uses for the add-in
menu. It assumes the items were inserted with a NULL
description to begin with. FirstId anad LastId would be the
first and last command IDs allocated by LciTcGetMenuIds().
The lstrcpy function is a standard Windows function. */
if(((WORD)P1 >= FirstId) && ((WORD)P1 <= LastId)){
lstrcpy(P2, "Custom Description");
ReturnCode = 1L;
}
break;
. . .
}
return(ReturnCode);
}
Definition
Sent when a menu item is selected that has an EXECUTE statement associated with it, or that was inserted into the menu with the ItemType parameter set to LCI_MENUITEM_EXECSTR. The EXECUTE string is specified in the MENUITEM statement in the resource file. See the Developer's Guide Part 5, Chapter 16 for more information. See LciMnInsertItem »Page for more information about inserting menu items.
Parameter Description
p1 Pointer to string to be executed.
p2 The command ID of the menu item that was selected.
Return
Ignored.
Example
#include "lcicomn.h"
#include "lcigui.h"
lulong LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
switch(Msg){
case TOOLMSG_MENUEXECSTR:
/* Use this message to modify the EXECUTE string, if desired.
The EXECUTE sring will get run regardless of whether you
modiy it or not. To block the EXECUTE string, replace it
with a NULL string. */
/* This will replace the string in the resource EXECUTE statement
with an alternative. */
ReturnCode = LciTcDefToolProc(ToolClass,
ToolInst, Msg,
"(indicate \"EXECUTE intercepted\")", P2);
break;
. . .
}
return(ReturnCode);
}
Definition
Sent when a menu item is selected that has a PROCEDURE statement associated with it, or that was inserted in the menu with the ItemType parameter set to LCI_MENUITEM_PROC. The PROCEDURE statement is specified in the MENUITEM statement in the resource file. See the Developer's Guide Part 5, Chapter 1 for more information. See LciMnInsertItem »Page for more information about inserting menu items.
Parameter Description
p1 The value that was specified with the PROCEDURE statement in the resource file or in the ItemData parameter in the call to LciMnInsertItem.
p2 The command ID of the menu item that was selected.
Return
Ignored.
Example
#include "lcicomn.h"
#include "lcigui.h"
#include "lcicell.h"
lulong LCI_CALL ToolProc(LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
LCT_CELL Cell;
lulong ReturnCode = 0L;
switch(Msg){
case TOOLMSG_MENUPROC:
/* This is an example of how to affect cells in response to a
menu item being chosen. You must save Context in a global
variable in order to use it in a tool procedure. */
/* Create cell object. */
Status = LciClConstructCurr(GlobalContext, &Cell);
/* Set its contents. */
Status = LciClSetContentsStr(Cell, "Button Pushed");
/* Release the object. */
Status = LciClDestroy(&Cell);
break;
. . .
}
return(ReturnCode);
}
Definition
Sent every time the core processes a {menu-reset} macro. The {menu-reset} macro removes all items added to any menus by macros or add-ins. This gives the add-in a chance to restore itself to the menu.
Parameter Description
p1 Not used.
p2 Not used.
Return
Ignored.
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcigui.h"
lulong LCI_CALL ToolProc (LCH_TOOLINST ToolInst,
lushort Msg,
lulong P1,
lulong P2)
{
lulong ReturnCode = 0L;
switch (Msg) {
case TOOLMSG_MENURESET:
{
/* Put add-in back on menu. */
LCH_TOOLCLASS ToolClass;
LCH_MENU MenuBar;
LCH_MENU ToolMenu;
LCT_STATUS Status;
lushort MenuId;
/* Get the current menu bar associated with the 1-2-3 sheet class
and add one new menu item to it. Assume the "Tools" submenu
is the eighth item by position in the default 1-2-3 sheet menu
bar. Normally, you would verify this by checking its label
since other add-ins may have altered the menu. Appends the
new menu item to the bottom of the popup menu. */
Status = LciTcConstructName(Context,
LCI_TOOLCLASS_SHEET,
LNULL,
&ToolClass);
Status = LciTcAddToolProc(ToolClass, ToolProc);
/* You can allocate the menu IDs anytime before inserting the
menu items. */
Status = LciTcGetMenuIds(ToolClass, 1, &MenuId);
Status = LciTcGetMenu(ToolClass, &MenuBar)'
Status = LciMnGetSubMenu(Menubar, 8, ToolMenu);
Status = LciMnInsertItem(ToolMenu,
LCI_MENUITEM_APPEND,
LCI_MENUITEM_BYPOSITION,
MenuId+0,
LCI_MENUITEM_PROC,
(lulong)(MenuId+0),
"&1 Menu Item",
"Description",
LCF_MENUITEM_ENABLED);
break;
}
. . .
}
return(ReturnCode);
}
Definition
Sent immediately before a popup menu is dropped down. This gives the add-in a chance to modify the menu before it is displayed.
Parameter Description
p1 The command ID of the popup menu.
p2 Reserved.
Note This message is also sent when 1-2-3 initially displays the top level menu bar and should not be handled for that case. The ID in the P1 parameter is the ID specified for the MENU statement in the resource file.
Return
Ignored.
Example
#include "lcicomn.h"
#include "lcigui.h"
#include "winresid.h"
lulong LCI_CALL ToolProc(LCH_TOOLINST ToolInst, lushort Msg,
lulong P1, lulong P2)
{
lulong ReturnCode = 0L;
switch(Msg){
case TOOLMSG_POPUP:
/* Dynamically change the text of a menu item immediately before
it is displayed by 1-2-3. */
if(P1 == ID_FX){ /* This is the "File popup menu." */
LCH_MENU MainMenu, FileMenu;
LciTcGetMenu(ToolClass, &MainMenu);
LciMnGetSubMenu(MainMenu, 1, &FileMenu);
LciMnSetLabel(FileMenu, ID_FX,
LCI_MENUITEM_BYCOMMAND,
"Leaving 1-2-3");
}
ReturnCode = LciTcDefToolProc(ToolClass, ToolInst,
Msg, P1, P2);
break;
. . .
}
return(ReturnCode);
}
New ADK 4.0 LMBCS functions
The LMBCS functions allow you to work with different character sets and codepages. They provide a variety of services primarily designed to permit translation between the internal string representation, LMBCS, and the native code set, designated by the specified codepage. The internal LMBCS representation is distinguished by a Group designation (used to optimize the representation for the local form of the product). This is given in the csid field of the environment block described in the file ltsstrct.h.
The new ADK 4.0 LMBCS functions allow you to manipulate LMBCS strings on a byte-by-byte basis. They also provide ANSI and codepage translation, although some of the functionality may parallel 1.0 routines. Using the following 4.0 functions is strongly recommended.
Note These functions do not require you to load LMBSRVW.DLL using load_lmbsrv() or call LciMbConstruct().
Function Meaning
LciMbAppendChr »Page Appends a LMBCS character to the end of a LMBCS string, and updates the pointer at the end of the string.
LciMbAppendSubstr »Page Appends a substring to a string pointer, and updates the pointer.
LciMbCharCase »Page Forces a character to upper or lowercase.
LciMbChrBytes »Page Determines the number of significant bytes in a LMBCS character.
LciMbChrSize »Page Determines the size of the LMBCS character in bytes (based on leadbytes).
LciMbConvertAnsiToLmbcs »Page Translates an ANSI string into a LMBCS string.
LciMbConvertLmbcsToAnsi »Page Translates a LMBCS string into an ANSI string.
LciMbDeleteChr »Page Deletes a LMBCS character.
LciMbDestroy »Page Removes a LMBCS translation module from memory and destroys the translation object.
LciMbFindChr »Page Searches for a LMBCS character, updates the pointer.
LciMbFindPrevChr »Page Finds the previous occurrence of a character in a LMBCS string and updates the pointer.
LciMbInsertChr »Page Inserts a LMBCS character into a string, returns the changed size in bytes, and updates the pointer.
LciMbLmbcsToNative »Page Translates a LMBCS string into a native string.
LciMbNativeToLmbcs »Page Translates a native string into a LMBCS string.
LciMbPeekNextChr »Page Peeks (returns) the next LMBCS character in a string without updating the pointer.
LciMbReplaceChr »Page Replaces a LMBCS character in a string with a new LMBCS character.
LciMbSkipNextChr »Page Skips the next LMBCS character and updates the pointer.
LciMbSkipNonSpaces »Page Skips non-spaces in a string and updates the pointer to the next space character.
LciMbSkipPrevChr »Page Skips to the previous LMBCS character in a string and updates the pointer.
LciMbSkipSpaces »Page Skips spaces up to the next nonspace character in the string, and updates the pointer.
LciMbStrcmp »Page Compares two strings.
LciMbStrcmpCollated »Page Compares and orders two strings according to the current country driver.
LciMbStrcmpWildcard »Page Compares two strings with wildcards in them byte for byte.
LciMbStrlen »Page Determines the character string length.
LciMbStrncmp »Page Compares two strings against each other (substring) and updates the second string pointer.
Previous ADK 1.0 LMBCS functions
The LMBCS functions allow you to work with different character sets and codepages. They provide a variety of services primarily designed to permit translation between the internal string representation, LMBCS, and the native code set, designated by the specified codepage. The internal LMBCS representation is distinguished by a Group designation (used to optimize the representation for the local form of the product). This is given in the csid field of the environment block described in the file ltsstrct.h.
The LciMbConstruct and LciMbDestroy functions allow you to set up a translation module for any one Codepage/Group combination. Normally, this would be the Group used by the product and the Codepage for the machine that the product is running on. However, these services allow you to maintain other translation setups simultaneously. If several setups are maintained, the Browse facility permits you to search through the available codepages.
Notes In all these functions, the use of lretarg is equivalent to lptr. Both are defined in ltsdefs.h.
These functions require you to load LMBSRVW.DLL using load_lmbsrv() or call LciMbConstruct().
Function Meaning
LciMbBrowseCodepage »Page Retrieves the next codepage available for use.
LciMbBrowseConstruct »Page Constructs a browse object handle to be used for retrieving codepages.
LciMbBrowseDestroy »Page Releases a browse handle.
LciMbConstruct »Page Loads a LMBCS translation module and constructs a translation object handle.
LciMbCountChrs »Page Gets the number of characters in a native or LMBCS string.
LciMbDestroy »Page Removes a LMBCS translation module from memory and destroys the translation object.
LciMbGetCodepage »Page Gets the codepage ID associated with a translation object.
LciMbGetGroup »Page Gets the LMBCS group number associated with a translation object.
LciMbTransLmbcsToNative »Page Translates a LMBCS string into a native string.
LciMbTransNativeToLmbcs »Page Translates a native string into a LMBCS string.
load_lmbsrv »Page Loads the module LMBSRVW.DLL.
unload_lmbsrv »Page Removes the module LMBSRVW.DLL from memory.
Definition
Appends a LMBCS character to the end of a LMBCS string, and updates the pointer at the end of the string.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbAppendChr
(LCH_CONTEXT Context,
lptr(lptr(lmbcs)) lplpString,
lmbchr Chr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lplpString Pointer to a LMBCS pointer.
Chr LMBCS character to append.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs theString[MAX_STRING];
lmbchr Chr;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,theString);
...
/* peek at the next mbcs character and append a copy of it to
the end of the string.*/
Status = LciMbPeekNextChr(Context,theString,&Chr);
Status = LciMbAppendChr(Context,&theString,Chr);
...
Status = LciClDestroy(&Cell);
Definition
Appends a substring to a string pointer and updates the pointer.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbAppendSubstr
(LCH_CONTEXT Context,
lptr(lptr(lmbcs))lplpSourceStr,
lptr(lmbcs)Substr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lplpSourceStr Pointer to a LMBCS pointer of a string which will be appended.
Substr Pointer to a LMBCS string to append.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs SourceStr[MAX_STRING];
lmbcs Substr[MAX_STRING];
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,SourceStr);
Status = LciClGetContentsStr(Cell,MAX_STRING,Substr);
...
/* Append copy of buffer to end of the source string */
Status = LciMbAppendSubstr(Context,&SourceStr,Substr);
Status = LciClDestroy(&Cell);
Definition
Forces a character to upper or lowercase.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbCharCase
(LCH_CONTEXT Context,
lmbchr Chr,
lushort Type,
lptr(lmbcs) lpOutStr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Chr Character on which to force type.
Type Desired type attribute.
Constant Meaning
LCF_TOUPPER Force to uppercase
LCF_TOLOWER Force to lowercase
lpOutStr Pointer to a LMBCS string that contains the new character.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
...
lmbchr OutChr;
lmbchr Chr;
lushort Type;
LCT_STATUS Status;
...
/* Set type to uppercase and half pitch
Type = LCF_TOUPPER;
Chr = 'a';
...
/* force type
Status = LciMbCharCase(Context,Chr,Type,&OutChr);
Definition
Determines the number of significant bytes in a LMBCS character.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbChrBytes
(LCH_CONTEXT Context,
lmbchr Chr,
lptr(lsshort) lpLen)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Chr LMBCS character to be evaluated.
lpLen Number of significant bytes returns here.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcicell.h"
#include "lcimb.h"
. . .
LCH_CELL Cell;
LCT_STATUS Status;
lmbcs ContentsStr[LCI_MAX_CELL_LEN];
lsshort length;
lptr(lmbcs) lpContentsStr;
. . .
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,LCI_MAX_CELL_LEN,ContentsStr);
lpContentsStr = ContentsStr;
length = 0;
/* loop through Cell contents looking for a multi byte character
* which presumably needs special handling.
*/
do
{
lpContentsStr += length;
Status = LciMbChrBytes(Context, *lpContentsStr, &length);
}
while (length == 1 || *lpContentsStr != LNULL);
. . .
Status = LciClDestroy(&Cell);
Definition
Determines the size of the LMBCS character in bytes (based on leadbytes).
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbChrSize
(LCH_CONTEXT Context,
lubyte First_byte,
lptr(lsshort) lpSize)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
First_byte The leadbyte of the LMBCS character being sized.
lpSize The character size returns here in bytes.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#include "lcicell.h"
#define MAX_STRING 20
...
lmbcs First_byte[MAX_STRING];
lsshort Size;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,First_byte);
...
/* determine size of first char */
Status = LciMbChrSize(Context,*First_byte,&Size);
...
Status = LciClDestroy(&Cell);
Definition
Translates an ANSI string into a LMBCS string.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbConvertAnsiToLmbcs
(LCH_CONTEXT Context,
lptr(lmbcs)lpFromStr,
lptr(lmbcs)lpToStr,
lsshort Max,
lptr(lbool) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpFromStr Input string pointer.
lpToStr Output string pointer.
Max Maximum size of the output string.
lpResult LTRUE if the string is normal, LFALSE if it overflows.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs From[MAX_STRING];
lmbcs To[MAX_STRING];
lsshort Max = MAX_STRING;
lbool Result;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,From);
...
/* convert string LMBCS to ANSI */
Status = LciMbConvertAnsiToLmbcs(Context,From,To,Max,&Result);
...
Status = LciClDestroy(&Cell);
Definition
Translates a LMBCS string into an ANSI string.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbConvertLmbcsToAnsi
(LCH_CONTEXT Context,
lptr(lmbcs)lpFromStr,
lptr(lmbcs)lpToStr,
lsshort Max,
lptr(lbool) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpFromStr Input string pointer.
lpToStr Output string pointer.
Max Maximum size of the output string.
lpResult LTRUE if the string is normal, LFALSE if it overflows.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs From[MAX_STRING];
lmbcs To[MAX_STRING];
lsshort Max = MAX_STRING;
lbool Result;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,20,From);
...
/* convert string LMBCS to ANSI */
Status = LciMbConvertLmbcsToAnsi(Context,From,To,Max,&Result);
...
Status = LciClDestroy(&Cell);
Definition
Deletes a LMBCS character.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbDeleteChr
(LCH_CONTEXT Context,
lptr(lptr(lmbcs))lplpString,
lptr(lsshort) lpSize)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lplpString Pointer to a LMBCS pointer points to the character to delete.
lpSize The character size returns here in bytes.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs theString[MAX_STRING];
lptr(lmbcs) ptrString = theString;
lsshort Size;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,theString);
...
/* delete at the current mbcs character */
Status = LciMbDeleteChr(Context,&ptrString,&Size);
...
Status = LciClDestroy(&Cell);
Definition
Removes the LMBCS translation module from memory and releases the translation object.
Format
#include "lcicomn.h"
#include "lcimblib.h"
LCT_STATUS LCI_CALL LciMbDestroy
(lptr(LCH_MBXTAB) lpMbxtab)
Arguments
lpMbxtab Pointer to a translation object handle, which is LNULL upon return.
Returns
LCS_SUCCESS »Page
LCS_CLOSE_ERROR »Page
Example
#include "lcicomn.h"
#include "lcimblib.h"
. . .
LCH_MBXTAB MbxTab;
LCT_STATUS Status;
. . .
Status = LciMbConstruct(Context,865,1,254,0,&MbxTab);
. . .
/* Destroy the Codepage Handle, associated memory, and modules
in memory */
Status = LciMbDestroy(&MbxTab);
Definition
Searches for a LMBCS character and updates the pointer.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbFindChr
(LCH_CONTEXT Context,
lptr(lptr(lmbcs))lplpString,
lmbchr Chr,
lbool CaseDependent,
lptr(lbool) lpFound)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lplpString Pointer to a LMBCS pointer. This is the string to search.
Chr LMBCS character for which to search.
CaseDependent LTRUE to search for a case-sensitive character, LFALSE to search for an case-insensitive character.
lpFound LTRUE if found, LFALSE in not found.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs theString[MAX_STRING];
lmbchr Chr;
lbool Found;
lbool CaseDependent;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,theString);
...
CaseDependent = LTRUE;
/* Search for N tilde uppercase, see Appendix A in the 123
Release 4 for Windows User's Guide */
Chr = 165;
...
/* find a LMBCS character in string */
Status = LciMbFindChr(Context,&theString,Chr,CaseDependent,&Found);
...
Status = LciClDestroy(&Cell);
Definition
Finds a previous occurrence of a character in a LMBCS string and updates the pointer.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbFindPrevChr
(LCH_CONTEXT Context,
lptr(lptr(lmbcs))lplpSourceStr,
lptr(lmbcs)lpSourceStr,
lmbchr Chr,
lbool CaseDependent;
lptr(lbool) lpFound)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lplpSourceStr Pointer to a LMBCS pointer. This is the string to search.
lpSourceStr Pointer to a LMBCS string.
CaseDependent LTRUE to search for a case-sensitive character, LFALSE to search for a case-insensitive character.
Chr LMBCS character for which to search.
lpFound LTRUE if found, LFALSE in not found.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs SourceStr[MAX_STRING];
lptr(lmbcs) lpSourceStr = SourceStr;
lmbchr Chr;
lbool CaseDependent;
lbool Found;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,theString);
...
/* Search for N tilde uppercase, see Appendix A in the 123
Release 4 for Windows User's Guide */
Chr = 165;
CaseDependent = LFALSE;
...
/* find a previous LMBCS character in string, */
Status = LciMbFindPrevChr(Context,&lpSourceStr,&SourceStr,Chr,
CaseDependent,&Found);
...
Status = LciClDestroy(&Cell);
Definition
Inserts a LMBCS character into a string, returns the changed size in bytes, and updates the pointer.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbInsertChr
(LCH_CONTEXT Context,
lptr(lptr(lmbcs))lplpString,
lmbchr Chr,
lptr(lsshort) lpSize)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lplpString Pointer to a LMBCS pointer that updates when inserting characters.
Chr LMBCS character to insert.
lpSize The character size returns here in bytes.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs theString[MAX_STRING];
lmbchr Chr;
lsshort Size;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,theString);
...
/* peek at the next mbcs character and insert a copy of it
in the string */
Status = LciMbPeekNextChr(Context,theString,&Chr);
Status = LciMbInsertChr(Context,&theString,Chr,&Size);
...
Status = LciClDestroy(&Cell);
Definition
Scans a LMBCS string and converts it to the native format. This is the codepage which is "native" to the machine, code page 437 or 850, for example.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbLmbcsToNative
(LCH_CONTEXT Context,
lptr(lmbcs)lpFromStr,
lptr(lmbcs)lpToStr,
lsshort Max,
lptr(lbool ) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
From Input string pointer.
To Output string pointer.
Max Maximum size of the output string.
lpResult LTRUE if the string is normal, LFALSE if it overflows.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs From[MAX_STRING];
lmbcs To[MAX_STRING];
lsshort Max = MAX_STRING;
lptr(lmbcs) Lead_bytes;
lbool Result;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCoords(Context, 1, 3, 4, &Cell);
Status = LciClGetContentsStr(Cell1, MAX_STRING, From);
...
Lead_bytes = From;
/* get translation table pointer and convert string between
country formats */
Status = LciMbLmbcsToNative(Context, Lead_bytes, From, To,
Max, &Result);
...
Status = LciClDestroy(&Cell);
Definition
Converts a string using the codepage table (for example codepage 437 or 850), scans a native string, converts it to the LMBCS format, and removes control codes.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbNativeToLmbcs
(LCH_CONTEXT Context,
lptr(lmbcs)lpFromStr,
lptr(lmbcs)lpToStr,
lsshort Max,
lptr(lbool) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
From Input string pointer.
To Output string pointer.
Max Maximum size of the output string.
lpResult LTRUE if the string is normal, LFALSE if it overflows.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs From[MAX_STRING];
lmbcs To[MAX_STRING];
lsshort Max = MAX_STRING;
lbool Result;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCoords(Context, 1, 3, 4, &Cell);
Status = LciClGetContentsStr(Cell, 20, From);
...
/* get translation table pointer and convert string */
Status = LciMbNativeToLmbcs(Context, From, To, Max, &Result);
...
Status = LciClDestroy(&Cell);
Definition
Peeks (returns) the next LMBCS character in a string without updating the pointer.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbPeekNextChr
(LCH_CONTEXT Context,
lptr(lmbcs) lpString,
lptr(lmbchr) lpLmbchr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpString Pointer to a LMBCS string.
lpLmbchr The next LMBCS character in the string pointed to by lpString, NULL if at the end of the string.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs theString[MAX_STRING];
lmbchr Chr;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,theString);
...
Status = LciMbPeekNextChr(Context,theString,Chr);
...
Status = LciClDestroy(&Cell);
Definition
Replaces a LMBCS character in a string with a new LMBCS character.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbReplaceChr
(LCH_CONTEXT Context,
lptr(lptr(lmbcs))lplpString,
lmbchr Chr,
lptr(lsshort) lpSize)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lplpString Pointer to a LMBCS pointer that points to, replaces, and updates the character.
Chr LMBCS character used for replacement.
lpSize The character size returns here in bytes.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs theString[MAX_STRING];
lmbchr Chr;
lsshort Size;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,theString);
...
/* peek at the next LMBCS character and replace current a
copy of it in the string */
Status = LciMbPeekNextMbcs(Context,theString,&Chr);
Status = LciMbReplaceChr(Context,&theString,Chr,&Size);
...
Status = LciClDestroy(&Cell);
Definition
Skips the next LMBCS character and updates the pointer.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbSkipNextChr
(LCH_CONTEXT Context,
lptr(lptr(lmbcs))lplpString,
lptr(lsshort) lpBytesMoved)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lplpString Pointer to a LMBCS pointer that updates to point to the next LMBCS character.
lpBytesMoved The number of bytes (not characters) moved returns here.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs theString[MAX_STRING];
lsshort BytesMoved;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,theString);
...
Status = LciMbSkipNextChr(Context,&theString,&BytesMoved);
...
Status = LciClDestroy(&Cell);
Definition
Skips nonspaces in a string and updates the pointer to the next space character.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbSkipNonSpaces
(LCH_CONTEXT Context,
lptr(lptr(lmbcs))lplpString,
lptr(lushort) lpBytesMoved)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lplpString Pointer to a LMBCS pointer that updates and points to the next space character.
lpBytesMoved The number of bytes (not characters) moved returns here.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs theString[MAX_STRING];
lushort BytesMoved;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,theString);
...
Status = LciMbSkipNonSpaces(Context,&theString,&BytesMoved);
...
Status = LciClDestroy(&Cell);
Definition
Skips to the previous LMBCS character in a string and updates the pointer.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbSkipPrevChr
(LCH_CONTEXT Context,
lptr(lptr(lmbcs))lplpString,
lptr(lmbcs)lpStr,
lptr(lsshort) lpBytesMoved)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lplpString Pointer to a LMBCS pointer that updates the previous character.
lpStr Pointer to a LMBCS string.
lpBytesMoved The number of bytes (not characters) moved returns here.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs theString[MAX_STRING];
lptr(lmbcs) lptheString = theString;
lsshort BytesMoved;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context, &Cell);
Status = LciClGetContentsStr(Cell, MAX_STRING, theString);
...
Status = LciMbSkipPrevChr(Context, &lptheString, theString,
&BytesMoved);
...
Status = LciClDestroy(&Cell);
Definition
Skips spaces up to the next nonspace character in the string, and updates the pointer.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbSkipSpaces
(LCH_CONTEXT Context,
lptr(lptr(lmbcs))lplpString,
lptr(lushort) lpBytesMoved)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lplpString Pointer to a LMBCS pointer that updates and points to the next nonspace LMBCS character.
lpBytesMoved The number of bytes (not characters) moved returns here.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs theString[MAX_STRING];
lushort BytesMoved;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,theString);
...
Status = LciMbSkipSpaces(Context,&theString,&BytesMoved);
...
Status = LciClDestroy(&Cell);
Definition
Compares two strings.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbStrcmp
(LCH_CONTEXT Context,
lptr(lmbcs)lpStr1,
lptr(lmbcs)lpStr2,
lbool CaseDependent,
lptr(lsshort) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpStr1 Pointer to a LMBCS string.
lpStr2 Pointer to a LMBCS string.
CaseDependent LTRUE to search for a case-sensitive character, LFALSE to search for a case-insensitive character.
lpResult 0 if equal, -1 if (str1 < str2), 1 if (str1 > str2).
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs Str1[MAX_STRING];
lmbcs Str2[MAX_STRING];
lsshort Result;
LCT_STATUS Status;
LCH_CELL Cell;
LCH_CELL Cell1;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,Str1);
Status = LciClConstructCoords(Context,1,3,4,&Cell1);
Status = LciClGetContentsStr(Cell1,MAX_STRING,Str2);
...
CaseDependent = LTRUE;
...
/* Compare two strings character for character */
Status = LciMbStrcmp(Context,Str1,Str2,CaseDependent,&Result);
...
Status = LciClDestroy(&Cell);
Status = LciClDestroy(&Cell1);
Definition
Compares and orders two strings according to the current country driver.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbStrcmpCollated
(LCH_CONTEXT Context,
lptr(lmbcs)lpStr1,
lptr(lmbcs)lpStr2,
lbool CaseDependent,
lptr(lsshort) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpStr1 Pointer to a LMBCS string.
lpStr2 Pointer to a LMBCS string.
CaseDependent LTRUE to search for a case-sensitive character, LFALSE to search for a case-insensitive character.
lpResult 0 if equal, -1 if (str1 < str2), 1 if (str1 > str2)
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs Str1[MAX_STRING];
lmbcs Str2[MAX_STRING];
lsshort Result;
LCT_STATUS Status;
LCH_CELL Cell;
LCH_CELL Cell1;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context, &Cell);
Status = LciClGetContentsStr(Cell, MAX_STRING, Str1);
Status = LciClConstructCoords(Context, 1, 3, 4, &Cell1);
Status = LciClGetContentsStr(Cell1, MAX_STRING, Str2);
...
CaseDependent = LTRUE;
/* Compare to LMBCS strings byte for byte */
Status = LciMbStrcmpCollated(Context, Str1, Str2, CaseDependent,
&Result);
...
Status = LciClDestroy(&Cell);
Status = LciClDestroy(&Cell1);
Definition
Compares two strings with wildcards in them byte for byte. Although strings may contain the same LMBCS characters, bytes may be different.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbStrcmpWildcard
(LCH_CONTEXT Context,
lptr(lmbcs)lpStr1,
lptr(lmbcs)lpStr2,
lptr(lsshort) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpStr1 Pointer to a LMBCS string.
lpStr2 Pointer to a LMBCS string.
lpResult 0 if equal, -1 if (str1 < str2), 1 if (str1 > str2).
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs Str1[MAX_STRING];
lmbcs Str2[MAX_STRING];
lsshort Result;
LCT_STATUS Status;
LCH_CELL Cell;
LCH_CELL Cell1;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,Str1);
Status = LciClConstructCoords(Context,1,3,4,&Cell1);
Status = LciClGetContentsStr(Cell1,MAX_STRING,Str2);
...
/* Compare strings containing wildcards */
Status = LciMbStrcmpWildcard(Context,Str1,Str2,&Result);
...
Status = LciClDestroy(&Cell);
Status = LciClDestroy(&Cell1);
Definition
Returns the number of LMBCS characters in a string.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbStrlen
(LCH_CONTEXT Context,
lptr(lmbcs)lpStr,
lptr(lsshort) lpLen)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpStr Pointer to a LMBCS string.
lpLen Size of string in bytes.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs theString[MAX_STRING];
lsshort length;
LCT_STATUS Status;
LCH_CELL Cell;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,theString);
...
/* find total characters in LMBCS string */
Status = LciMbStrlen(Context,theString,&length);
...
Status = LciClDestroy(&Cell);
Definition
Compares two strings against each other (substring) and updates the second string pointer.
Format
#include "lcicomn.h"
#include "lcimb.h"
LCT_STATUS LCI_CALL LciMbSubstrncmp
(LCH_CONTEXT Context,
lptr(lmbcs)lpStr1,
lptr(lptr(lmbcs))lplpStr2,
lbool CaseDependent,
lptr(lsshort) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpStr1 Pointer to a LMBCS string.
lplpStr2 Pointer to a LMBCS pointer.
CaseDependent LTRUE to search for a case-sensitive character, LFALSE to search for a case-insensitive character.
lpResult 0 if equal, or if the first string is a substring of the second (the second string pointer points after the matching string) -1 if (first < second), 1 if (first > second).
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimb.h"
#define MAX_STRING 20
...
lmbcs Str1[MAX_STRING];
lmbcs Str2[MAX_STRING];
lsshort Result;
LCT_STATUS Status;
LCH_CELL Cell;
LCH_CELL Cell1;
...
/* construct a cell at the current cursor location and get a
LMBCS string from the cell */
Status = LciClConstructCurr(Context,&Cell);
Status = LciClGetContentsStr(Cell,MAX_STRING,Str1);
Status = LciClConstructCoords(Context,1,3,4,&Cell1);
Status = LciClGetContentsStr(Cell1,20,Str2);
...
CaseDependent = LTRUE;
/* compare strings include substring compare */
Status = LciMbStrncmp(Context,Str1,&Str2,CaseDependent,&Result);
...
Status = LciClDestroy(&Cell);
Status = LciClDestroy(&Cell1);
Definition
Retrieves the next codepage available for use.
Format
#include "lcicomn.h"
#include "lcimblib.h"
LCT_STATUS LCI_CALL LciMbBrowseCodepage
(LCH_MBBROWSE Browse
lretarg(lushort) lpCodepageID
lretarg(lptr(char)) lplpDescription
lretarg(lushort) lpOutput)
Arguments
Browse Pointer to storage in which to return the object handle.
lpCodepageID Pointer to an lushort in which to contain the codepage ID.
lplpDescription Pointer to a pointer which will point to the description string.
lpOutput Pointer to an lushort in which to return the length of the description string. This length does not include the null-terminating string.
Returns
LCS_SUCCESS »Page
LCS_OPEN_ERROR »Page
LCS_END_OF_FILE »Page
Note LciMbBrowseCodepage allocates storage for the description string using the environment block memory allocation, alloc. lplpDescription (contains the returned pointer to the allocated storage). When the add-in is finished with the description string, it should release the storage using the environment block deallocation, dealloc. See Part 2, Chapter 1 in the ADK Developer's Guide for more information about the environment block.
Example
#include "lcicomn.h"
#include "lcimblib.h"
. . .
LCH_MBBROWSE Browse;
LCT_STATUS Status;
lushort CodepageId;
lptr(char) LpDescription;
lushort Output;
. . .
Status = LciMbBrowseConstruct(Context, &Browse);
Status = LciMbBrowseCodepage(Browse, &CodepageId,
&LpDescription, &Output);
. . .
Status = LciMbBrowseDestroy(&Browse);
Definition
Constructs a browse object handle to be used for retrieving codepages. This also initializes the browser for the first LciMbBrowseCodepage call.
Format
#include "lcicomn.h"
#include "lcimblib.h"
LCT_STATUS LCI_CALL LciMbBrowseConstruct
(LCH_CONTEXT Context,
lretarg(LCH_MBBROWSE) lpBrowse)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpBrowse Pointer to storage in which to return the browse object handle.
Returns
LCS_SUCCESS »Page
LCS_OPEN_ERROR »Page
Example
#include "lcicomn.h"
#include "lcimblib.h"
. . .
LCH_MBBROWSE Browse;
LCT_STATUS Status;
. . .
/* Get a Browse Handle */
Status = LciMbBrowseConstruct(Context,&Browse);
. . .
Status = LciMbBrowseDestroy(&Browse);
Definition
Deallocates the browse object handle and any additional memory allocated during browsing.
Format
#include "lcicomn.h"
#include "lcimblib.h"
LCT_STATUS LCI_CALL LciMbBrowseDestroy
(lptr(LCH_MBBROWSE) lpBrowse)
Arguments
lpBrowse Pointer to a browse object handle, which is LNULL upon return.
Returns
LCS_SUCCESS »Page
LCS_CLOSE_ERROR »Page
Example
#include "lcicomn.h"
#include "lcimblib.h"
. . .
LCH_MBBROWSE Browse;
LCT_STATUS Status;
. . .
Status = LciMbConstruct(Context,&Browse);
. . .
/* Destroy the Handle */
Status = LciMbBrowseDestroy(&Browse);
Definition
Loads a LMBCS translation module identified by a specified codepage and group and returns a translation object handle that is used by subsequent translation functions. Once you have set up a translation module for the desired combination, use the LciMbTransLmbcsToNative and LciMbTransNativeToLmbcs routines to perform the actual translations.
Format
#include "lcicomn.h"
#include "lcimblib.h"
LCT_STATUS LCI_CALL LciMbConstruct
(LCH_CONTEXT Context,
lushort Codepage,
lushort Group,
lushort BadChar,
lushort TranslateOption,
lretarg(LCH_MBXTAB) lpMbxtab)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Codepage The unique codepage number that identifies the desired character set and causes the translation module associated with this character set to be loaded.
Group Contains the default LMBCS group to be used to optimize future translations.
BadChar If 0, skip untranslatable characters; otherwise, BadChar contains the character that is to be substituted for the untranslatable characters. BadChar may only have a value between 0 and 255.
TranslateOption Sets the option flags for subsequent translations. It can have one of the following values:
Option Definition
MB_TRANS_CC Translate native control codes to LMBCS control codes; otherwise, do not translate control codes. Note that this value is not supported in the current version of LMBCS services.
MB_TRANS_SNGL Translate only one character from input to output.
Note Using TranslateOption=0 will result in the translation of the entire string with the exception of control codes.
lpMbxtab Pointer to the storage to which to return the translation object handle.
Note By convention, all LMBCS strings are null-terminated, while all native text strings are presumed not null-terminated and always have an associated parameter that describes the byte-length of the string.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_OPEN_ERROR »Page
Example
#include "lcicomn.h"
#include "lcimblib.h"
. . .
LCH_MBXTAB MbxTab;
LCT_STATUS Status;
. . .
/* Load the codepage for NORDIC characters */
Status = LciMbConstruct(Context,
865, /* Codepage */
1, /* Code Group */
254, /* Default Bad Char */
0, /* Flags */
&MbxTab ); /* Return Handle */
. . .
Status = LciMbDestroy(&MbxTab);
Definition
Gets the number of characters in a native or LMBCS string.
Format
#include "lcicomn.h"
#include "lcimblib.h"
LCT_STATUS LCI_CALL LciMbCountChars
(LCH_MBXTAB Mbxtab,
lptr(char) lpInStr,
lushort InByteCount,
lretarg(lushort) lpCharCount)
Arguments
Mbxtab A translation object handle.
lpInStr Pointer to a native string or a LMBCS string.
InByteCount Byte length of lpInStr, or 0 if lpInStr is a LMBCS string.
lpCharCount Pointer to an lushort in which to return the number of characters in lplnStr.
Returns
LCS_SUCCESS »Page
LCS_OPEN_ERROR »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcimblib.h"
. . .
LCH_MBXTAB MbxTab;
Lptr(char) InStr = "hello world";
lushort InByteCount;
lushort CharCount;
LCT_STATUS Status;
. . .
Status = LciMbConstruct(Context,865,1,254,0,&MbxTab);
. . .
InByteCount = lstrlen(Instr);
Status = LciMbCountChars(MbxTab,InStr,InByteCount,&CharCount);
. . .
Status = LciMbDestroy(&MbxTab);
Definition
Gets the number of the character set (codepage ID) associated with a translation object handle constructed by LciMbConstruct.
Format
#include "lcicomn.h"
#include "lcimblib.h"
LCT_STATUS LCI_CALL LciMbGetCodepage
(LCH_MBXTAB Mbxtab,
lretarg(lushort) lpCodepage)
Arguments
Mbxtab A translation object handle.
lpCodepage Pointer to an lushort in which the codepage id will be returned.
Returns
LCS_SUCCESS »Page
LCS_OPEN_ERROR »Page
Example
#include "lcicomn.h"
#include "lcimblib.h"
. . .
LCH_MBXTAB MbxTab;
LCT_STATUS Status;
lushort CodepageValue;
. . .
Status = LciMbConstruct(Context,865,1,254,0,&MbxTab);
/* CodepageValue will be equal to 865 on return. */
Status = LciMbGetCodepage(MbxTab,&CodepageValue);
. . .
Status = LciMbDestroy(&MbxTab);
Definition
Gets the number of the LMBCS group associated with a translation object created with LciMbConstruct.
Format
#include "lcicomn.h"
#include "lcimblib.h"
LCT_STATUS LCI_CALL LciMbGetGroup
(LCH_MBXTAB Mbxtab,
lretarg(lushort) lpGroup)
Arguments
Mbxtab A translation object handle.
lpGroup Pointer to an lushort in which the LMBCS group will be returned.
Returns
LCS_SUCCESS »Page
LCS_OPEN_ERROR »Page
Example
#include "lcicomn.h"
#include "lcimblib.h"
. . .
LCH_MBXTAB MbxTab;
lushort GroupValue;
. . .
Status = LciMbConstruct(Context,865,1,254,0,&MbxTab);
/* Will return GroupValue == 1 */
Status = LciMbGetGroup(MbxTab,&GroupValue);
. . .
Status = LciMbDestroy(&MbxTab);
Definition
Translates a LMBCS string into a native character string.
Format
#include "lcicomn.h"
#include "lcimblib.h"
LCT_STATUS LCI_CALL LciMbTransLmbcsToNative
(LCH_MBXTAB Mbxtab,
lptr(lmbcs) lpInStr,
lushort BufLen,
lretarg(char) lpOutStr,
lretarg(lushort) lpOutByteCount,
lretarg(lushort) lpOutBadCount)
Arguments
Mbxtab A translation object handle.
lpInStr LMBCS string to translate.
BufLen Number of bytes allocated for lpOutStr.
lpOutStr Pointer to output buffer for native string (no null terminator).
lpOutByteCount Pointer to an lushort that will contain the number of bytes in lpOutStr filled in by the function.
lpOutBadCount Pointer to an lushort that will contain the number of untranslatable characters (if lpOutStr is not LNULL).
Returns
LCS_SUCCESS »Page
LCS_OPEN_ERROR »Page
LCS_STR_TOO_LONG »Page
Note If an output buffer pointed to by lpOutStr and of length BufLen is provided, it receives the native string and the length is stored at the location pointed to by lpOutByteCount. If lpOutStr is LNULL, the function only returns the number of bytes it needs to hold the resultant string. If lpOutBadCount is not LNULL, the number of untranslatable characters encountered is stored at the location pointed to by lpOutBadCount. If an lpOutStr buffer is provided and the length of the buffer is insufficient to hold the resultant string, the string is truncated and the function returns LCS_STR_TOO_LONG. If the MB_TRANS_SNGL option was specified in LciMbConstruct »Page , only one LMBCS character will be read from lpInStr. lpOutStr will contain only one native character, whose byte count will be in lpOutByteCount.
Example
#include "lcicomn.h"
#include "lcimblib.h"
. . .
LCH_MBXTAB MbxTab;
LCT_STATUS Status;
char NativeOutString[256];
lmbcs NordicString[514];
lushort NativeByteCount;
lushort NativeBadCount;
. . .
Status = LciMbConstruct(Context,865,1,254,0,&MbxTab);
. . .
/* Translate Nordic to Native. */
Status = LciMbTransLmbcsToNative((LCH_MBXTAB)MbxTab,
NordicString,(lushort)sizeof(NativeOutString),
NativeOutString,&NativeByteCount,&NativeBadCount);
. . .
Status = LciMbDestroy(&MbxTab);
Definition
Translates a native string into a LMBCS string.
Format
#include "lcicomn.h"
#include "lcimblib.h"
LCT_STATUS LCI_CALL LciMbTransNativeToLmbcs
(LCH_MBXTAB Mbxtab,
lptr(char) lpInStr,
lushort InByteCount,
lushort BufLen,
lretarg(lmbcs) lpOutStr,
lretarg(lushort) lpOutByteCount)
Arguments
Mbxtab A translation object handle.
lpInStr Native string to translate.
InByteCount Number of bytes in lpInStr.
BufLen Number of bytes in lpOutStr .
lpOutStr Pointer to output buffer for LMBCS string (no null terminator).
lpOutByteCount Pointer to an lushort in which to return the number of bytes filled in lpOutStr by the function.
Returns
LCS_SUCCESS »Page
LCS_OPEN_ERROR »Page
LCS_STR_TOO_LONG »Page
Note If an output buffer pointed to by lpOutStr and of length BufLen is provided, it receives the LMBCS string and the length is stored at the location pointed to by lpOutByteCount. If lpOutStr is LNULL, the function only returns the number of bytes it needs to hold the resultant string. If lpOutStr is provided and the length of the buffer is insufficient to hold the resultant string, the string is truncated and the function returns LCS_STR_TOO_LONG. The resultant string in lpOutStr is always null-terminated. If the MB_TRANS_SNGL option was specified in LciMbConstruct »Page , only one native character will be read from lpInStr, regardless of the value of InByteCount. lpOutStr will contain the byte counts for both the input native character and the output LMBCS character, as follows:
(lpOutByteCount & 255) = byte count of output LMBCS character
(((lpOutByteCount >> 8) & 255) - 1 ) = byte count of input native character
Example
#include "lcicomn.h"
#include "lcimblib.h"
. . .
LCH_MBXTAB MbxTab;
LCT_STATUS Status;
char NativeInString[256];
lmbcs NordicString[514];
lushort NordicByteCount;
lushort i;
. . .
Status = LciMbConstruct(Context,865,1,254,0,&MbxTab);
. . .
/* Load up a string to translate. */
for(i = 1;i < 256;i++)NativeInString[i-1] = (char)i;
/* Translate to Nordic LMBCS */
Status = LciMbTransNativeToLmbcs(MbxTab, NativeInString, 256,
514, NordicString, &NordicByteCount);
. . .
LciMbDestroy(&MbxTab);
Definition
Loads the module LMBSRVW.DLL. This call must be made successfully once and only once before any other LciMb calls. This call is available only from the LMBSRVW.LIB library.
Format
#include "lcicomn.h"
#include "lcimblib.h"
LCT_STATUS LCI_CALL load_lmbsrv
(lptr(envblk) lpevh)
Arguments
lpevh Pointer to an environment block. Module is loaded through the callback lpevh->load.
Returns
LCS_SUCCESS »Page
LCS_OPEN_ERROR »Page
Example
#include "lcicomn.h"
#include "lcimblib.h"
. . .
LCT_STATUS Status;
lptr(envblk) lppEnvBlk;
. . .
/* Lmbcs needs Environment block to get a pointer to it*/
Status = LciUtGetEnvBlock(Context,&lppEnvBlk);
/* Load LMBSRVW.DLL */
Status = load_lmbsrv(lppEnvBlk);
. . .
Status = unload_lmbsrv(lppEnvBlk);
Definition
Unloads the module LMBSRVW.DLL. This call must be made successfully once and only once after load_lmbsrv call is successfully made. This call is available only from the LMBSRVW.LIB library.
Format
#include "lcicomn.h"
#include "lcimblib.h"
LCT_STATUS LCI_CALL unload_lmbsrv
(lptr (envblk) lpevh)
Arguments
lpevh Pointer to an environment block. Module is unloaded through the callback lpevh->unload.
Returns
LCS_SUCCESS »Page
LCS_CLOSE_ERROR »Page
Example
#include "lcicomn.h"
#include "lcimblib.h"
. . .
lptr(envblk) lppEnvBlk;
LCT_STATUS Status;
. . .
/* Terminate the LMBSRVW.DLL */
Status = unload_lmbsrv((lptr(envblk))lppEnvBlk);
You use the C runtime load functions to get and set add-in data and information about the states of an executing add-in.
Function Meaning
LciLdGetAddinData »Page Retrieves the add-in data allocated by the user (with GlobalAlloc or LocalAlloc, for example).
LciLdGetAddinHandle »Page LciLdGetAddinHandle is called by an add-in to store the add-in specific portion of the current Context.
LciLdGetLibHandle »Page Retrieves the Windows handle to the currently executing .ADW instance in memory. This function corresponds to the handle returned by the Microsoft Windows LoadLibrary call.
LciLdGetRunInfo »Page Gets the current and historic state of add-in execution.
LciLdGetStackInfo »Page Gets the stack size for the current add-in.
LciLdLoadCompatLib »Page Loads the compatibility library for 1-2-3 Release 3.1 C add-in code.
LciLdSetAddinData »Page Stores a pointer to the add-in data allocated by the user (with GlobalAlloc or LocalAlloc, for example).
LciLdSetAddinHandle »Page LciLdSetAddinHandle is called by an add-in to restore the add-in specific portion of the Context data.
LciLdSetStackInfo »Page Sets the stack size for the current add-in.
LciLdUnloadCompatLib »Page Unloads the compatibility library for 1-2-3 Release 3.1 C add-in code.
Definition
Gets a pointer to the add-in data that has been allocated and previously stored by the user (with GlobalAlloc or LocalAlloc, for example).
Add-in data is data that the add-in wishes to store from one invocation to another, rather than using global data. It is data that is specific to a particular instance of an add-in. The pointer is set by calling LciLdSetAddinData »Page .
Format
#include "lcicomn.h"
#include "lcild.h"
LCT_STATUS LCI_CALL LciLdGetAddinData
(LCH_CONTEXT Context,
lptr(lptr(void)) lplpData)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lplpData A pointer in which the pointer to the users previously stored add-in data will be placed.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcild.h"
. . .
LCH_CELL Cell;
. . .
/* Get cell handle that has been previously stored in
add-in data */
Status = LciLdGetAddinData(Context, &Cell);
Definition
LciLdGetAddinHandle is called by an add-in to store the add-in specific portion of the current Context. This function will get valid information if called from an Adn* function or from a function that is being executed as a registered @function, macro keyword, or event handler. The LCH_ADDIN that is retrieved can be used to force an LCH_CONTEXT variable to apply to a particular instance of an add-in, and is intended to be used during invocation of a GUI dialog or menu function. The LCH_ADDIN can be restored to an LCH_CONTEXT using LciLdSetAddinHandle »Page .
Declare the following global variables:
LCH_CONTEXT TheContext;
LCH_ADDIN TheAddinHandle;
In your Adn... functions, save the context and AddinHandle by doing the following:
TheContext = Context;
LciLdGetAddinHandle(Context, &TheAddinHandle);
This saves the add-in specific portion of the Context handle in a variable for later use in a GUI procedure, which is not supplied with a valid and current context.
In any GUI function, restore the context by doing the following:
LciLdSetAddinHandle(TheContext, TheAddinHandle);
Then use TheContext as you would Context. This restores the add-in specific data to the Context block. This call is necessary because the add-in specific portion of the Context gets changed when any other add-in is called, which is all right except that the runtime never gets a chance to dispatch to the add-in when GUI message functions are invoked. Because of this, Context never gets fixed up to have the correct add-in references.
Format
#include "lcicomn.h"
#include "lcild.h"
LCT_STATUS LCI_CALL LciLdGetAddinHandle(
LCH_CONTEXT Context,
lptr(LCH_ADDIN) lpAddinHandle)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpAddinHandle A pointer that is set to point to a copy of the add-in specific data.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcild.h"
. . .
/* Global static data declarations */
LCH_ADDIN Addin;
. . .
/* Local data declarations in AdnInitialize */
LCT_STATUS Status;
. . .
/* Get the add-in specific data for later usage. */
Status = LciLdGetAddinHandle(Context, &Addin);
. . .
/* In a tool procedure, restore the add-in specific data
to the Context. */
Status = LciLdSetAddinHandle(Context, Addin);
Definition
Retrieves the Windows handle to the currently executing .ADW instance in memory. This handle corresponds to that returned by the Microsoft Windows LoadLibrary function when the add-in was loaded.
Format
#include "lcicomn.h"
#include "windows.h"
#include "lcild.h"
LCT_STATUS LCI_CALL LciLdGetLibHandle
(LCH_CONTEXT Context,
lptr(HANDLE) lphApplication)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lphApplication Pointer to the library handle.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "windows.h"
#include "lcild.h"
. . .
HANDLE Addin;
. . .
/* Get the library handle for the add-in. */
LciLdGetLibHandle(Context, &Addin);
Definition
Gets the current and historic state of add-in execution. The current state is stored in the upper word of the lulong as a single status. The execution history since the last READY mode state is stored in the lower word as a series of OR'd bits (as described below). For example, if the current function had been reached via a user running a macro keyword that loaded this application, you might get a history of LCF_LD_INFO_INITIALIZE | LCI_LD_INFO_MACRO_KEYWORD and a current state of LCF_LD_INFO_INITIALIZE.
Format
#include "lcicomn.h"
#include "lcild.h"
LCT_STATUS LCI_CALL LciLdGetRunInfo
(LCH_CONTEXT Context,
lptr(lulong) lpInfo)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpInfo A pointer to an lulong in which the the runtime state information will be stored. The information can be one or more of the following ORed together:
Context Meaning
LCF_LD_INFO_PREINIT AdnPreinit executing
LCF_LD_INFO_INITIALIZE AdnInitialize executing
LCF_LD_INFO_ATFUNC User @func executing
LCF_LD_INFO_MACRO_KEYWORD User macro keyword executing
LCF_LD_INFO_MAIN AdnMain executing
LCF_LD_INFO_TERMINATE AdnTerminate executing
LCF_LD_INFO_REMOVE Add-in being removed
LCF_LD_INFO_CLEAR All visible add-ins being cleared
LCF_LD_INFO_FILE_RETRIEVE Auto-load on file retrieve
LCF_LD_INFO_SYSTEM_LOAD Auto-load on product startup
LCF_LD_INFO_CANT_SUSPEND MAX levels of recursion reached during macro-run or event handling
LCF_LD_INFO_RUN_EVENT Event handler executing
LCF_LD_INFO_SYSTEM_EVENT /S event being handled
LCF_LD_INFO_EXIT Shutting down, remove all add-ins
LCF_LD_INFO_EXTERNAL Current instance started by a Tool Procedure or Event Handler.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcild.h"
. . .
lulong RunInfo;
. . .
LciLdGetRunInfo(Context, &RunInfo);
if (RunInfo & (LCF_LD_INFO_FILE_RETRIEVE |
LCF_LD_INFO_SYSTEM_LOAD))
return (LCS_SUCCESS);
Definition
Gets the stack size for the current add-in. See LciLdSetStackInfo »Page for information on setting the stack size.
Format
#include "lcicomn.h"
#include "lcild.h"
LCT_STATUS LCI_CALL LciLdGetStackInfo
(LCH_CONTEXT LpiContext,
lptr(lushort) lpStackSize,
lptr(lbool) lpPrivateStack )
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpStackSize A pointer to an lushort in which the size of the stack for the add-in will be stored.
lpPrivateStack A pointer to an lbool in which the private stack flag setting will be stored. (LTRUE = run a private stack; LFALSE = run on the 1-2-3 stack)
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcild.h"
. . .
lushort StackSize;
lbool PrivateStack;
. . .
LciLdGetStackInfo(Context, &StackSize, &PrivateStack);
Definition
Load the compatibility library for 1-2-3 Release 3.1 C add-in code. This call must be made prior to calling any compatibility functions.
Format
#include "lcicomn.h"
#include "lcild.h"
LCT_STATUS LCI_CALL LciLdLoadCompatLib
(LCH_CONTEXT Context)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
LCS_RESOURCE_LOAD_ERROR »Page
Example
#include "lcicomn.h"
#include "lcild.h"
. . .
LCT_STATUS Status;
. . .
/* Load the LPI compatibility library. */
Status = LciLdLoadCompatLib(Context);
if (Status != LCS_SUCCESS) {
/* Failed to load compatibility library. */
. . .
}
. . .
Status = LciLdUnloadCompatLib(Context);
Definition
Stores a pointer to the add-in data allocated by the user (with GlobalAlloc or LocalAlloc, for example).
Add-in data is data that the add-in wishes to store from one invocation to another, rather than using global data. It is data that is specific to a particular instance of an add-in. The pointer can be retrieved by calling LciLdGetAddinData »Page at a later time.
Note The user is responsible for all allocation and freeing of memory because the runtime stores only the pointer and does not make a copy of the data.
Format
#include "lcicomn.h"
#include "lcild.h"
LCT_STATUS LCI_CALL LciLdSetAddinData
(LCH_CONTEXT Context,
lptr(void) lpData)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpData A pointer to a buffer that contains the add-in data. Note that the pointer is stored, not the data itself.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcild.h"
#include "lcicell.h"
. . .
LCT_STATUS Status;
LCH_CELL Cell;
. . .
/* Construct a cell and save the handle for later use. */
Status = LciClConstructCurr(Context, &Cell);
if(Status == LCS_SUCCESS)
LciLdSetAddinData(Context, Cell);
Definition
LciLdSetAddinHandle is called by an add-in to restore the add-in specific portion of the Context data. This function is used to force an LCH_CONTEXT variable to apply to a particular instance of an add-in, and is intended to be used during invocation of a GUI dialog or menu function. The LCH_ADDIN should be stored using LciLdGetAddinHandle »Page during an appropriate function.
Format
#include "lcicomn.h"
#include "lcild.h"
LCT_STATUS LCI_CALL LciLdSetAddinHandle(
LCH_CONTEXT Context,
LCH_ADDIN AddinHandle)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
AddinHandle A handle to valid add-in handle that restores add-in specific data to a given Context..
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcild.h"
. . .
/* Global static data declarations */
LCH_ADDIN Addin;
. . .
/* Local data declarations in AdnInitialize */
LCT_STATUS Status;
. . .
/* Get the add-in specific data for later usage. */
Status = LciLdGetAddinHandle(Context, &Addin);
. . .
/* In a tool procedure, restore the add-in specific data
to the Context. */
Status = LciLdSetAddinHandle(Context, Addin);
Definition
Sets the stack size for the current add-in. The user can specify one of the two following methods of running:
· Run on a private stack: To specify a private stack, set PrivateStack = LTRUE and StackSize > 0. It is recommended that you start with StackSize = 4096 or greater and find the optimum size for your add-in by testing.
· Run on the 1-2-3 stack: To specify the 1-2-3 stack, set PrivateStack equal to LFALSE and StackSize equal to the number of bytes that your add-in needs in order to run. If that amount of stack space is not available, 1-2-3 returns LCS_OUT_OF_MEMORY.
Note This function should be called only from AdnPreInit. If you do not call this function, your add-in will be assigned by default a private stack 5K bytes in size.
Format
#include "lcicomn.h"
#include "lcild.h"
LCT_STATUS LCI_CALL LciLdSetStackInfo
(LCH_CONTEXT Context,
lushort StackSize,
lbool PrivateStack)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
StackSize The size of the stack desired.
PrivateStack Specifies whether a private stack is desired (LTRUE) or if the user wishes to run on the 1-2-3 stack (LFALSE).
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lcild.h"
. . .
/* Request to run on the 1-2-3 stack with 4KB of space. */
if (LciLdSetStackInfo (Context, 4096, LFALSE) != LCS_SUCCESS)
return (LCS_OUT_OF_MEMORY);
Definition
Unloads the compatibility library for 1-2-3 Release 3.1 add-in C code from memory. This function must be called if LciLdLoadCompatLib »Page has been called successfully.
Format
#include "lcicomn.h"
#include "lcild.h"
LCT_STATUS LCI_CALL LciLdUnloadCompatLib
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcild.h"
. . .
/* Unload the compatibility library; always returns SUCCESS. */
LciLdUnloadCompatLib(Context);
You can perform calculations in your add-ins using 1-2-3 Release 4's internal calculation engine, which uses a stack-based paradigm. The stack-based functions are listed according to the following categories:
Function Meaning
LciMtAbs »Page Replaces the number at the top of the stack with its absolute value.
LciMtACos »Page Replaces the value at the top of the stack with its arc cosine (the angle, in radians, whose cosine is the value of the top of the stack).
LciMtAdd »Page Replaces the first two values at the top of the stack with their sum.
LciMtASin »Page Replaces the value at the top of the stack with its arc sine (the angle, in radians, whose sine is the value of the top of the stack).
LciMtATan »Page Replaces the value at the top of the stack with its arc tangent (the angle, in radians, whose tangent is the value at the top of the stack).
LciMtATan2 »Page Replaces the first two values on the top of the stack with the arc tangent of TOS/(TOS-1) (the angle, in radians, whose tangent is TOS/(TOS-1)).
LciMtCompare »Page Compares the first two values at the top of the stack and sets an output argument to a value that reflects the result of the comparison.
LciMtCompareReturn »Page Compares the first two values at the top of the stack and returns a value that reflects the result of the comparison.
LciMtCos »Page Replaces the value at the top of the stack with its cosine.
LciMtDiv »Page Replaces the first two values at the top of the stack with the quotient that results from (TOS-1)/TOS.
LciMtDropMany »Page Removes a specified number of values from the top of the stack.
LciMtDropOne »Page Removes the top value from the stack.
LciMtDup »Page Duplicates the value at the top of the stack and pushes the duplicate onto the top of the stack.
LciMtDupNth »Page Duplicates the value n down from the top of the stack (TOS - n) and pushes the duplicate onto the top of the stack.
LciMtEq »Page Replaces the first two values at the top of the stack with LTRUE, if the two values are equal, or LFALSE, if they are not equal.
LciMtExp »Page Replaces the value at the top of the stack with e raised to the power of the value at the top of the stack.
LciMtGetDepth »Page Retrieves the number of values currently on the stack.
LciMtGetType »Page Retrieves the type of the value at the top of the stack.
LciMtGt »Page Replaces the first two values at the top of the stack with LTRUE if (TOS-1) is greater than TOS, or LFALSE otherwise.
LciMtGte »Page Replaces the first two values at the top of the stack with LTRUE if (TOS-1) is greater than or equal to TOS, and LFALSE otherwise.
LciMtInt »Page Replaces the value at the top of the stack with its integer component.
LciMtLN »Page Replaces the value at the top of the stack with its natural logarithm (base e).
LciMtLog »Page Replaces the value at the top of the stack with its common logarithm (base 10).
LciMtLt »Page Replaces the first two values at the top of the stack with LTRUE if (TOS-1) is less than TOS, and LFALSE otherwise.
LciMtLte »Page Replaces the first two values at the top of the stack with LTRUE, if (TOS-1) is less than or equal to TOS, and LFALSE otherwise.
LciMtMod »Page Replaces the first two values at the top of the stack with the remainder that results from dividing (TOS-1)/TOS.
LciMtMul »Page Replaces the first two values at the top of the stack with their product.
LciMtNegate »Page Negates the value at the top of the stack.
LciMtNeq »Page Replaces the first two values at the top of the stack with LTRUE, if the two values are not equal, or LFALSE, if they are equal.
LciMtPopFloat8 »Page Pops the value off the top of the stack and stores it in an lfloat8 format.
LciMtPopFloat10 »Page Pops the value off the top of the stack and stores it in an lfloat10 format.
LciMtPopLong »Page Pops the value off the top of the stack and stores it in a long integer (lslong) value.
LciMtPopLongReturn »Page Pops the value off the top of the stack and returns it as a long integer (lslong) value.
LciMtPopShort »Page Pops the value off the top of the stack and stores it in a short integer (lsshort) format.
LciMtPopShortReturn »Page Pops the value off the top of the stack and returns it as a short integer (lsshort) value.
LciMtPow »Page Replaces the first two values at the top of the stack with (TOS-1)(TOS). TOS is the value at the top of the stack, and (TOS-1) is the value one down from the top of the stack.
LciMtPushErr »Page Pushes LCI_NUM_ERR onto the type stack and 0.0 onto the number stack.
LciMtPushFloat8 »Page Converts an lfloat8 to an lfloat10 and pushes the converted value onto the stack.
LciMtPushFloat10 »Page Pushes an lfloat10 value onto the stack.
LciMtPushLong »Page Converts an lslong to an lfloat10 and pushes the converted value onto the stack.
LciMtPushNa »Page Pushes LCI_NUM_NA onto the type stack and 0.0 onto the number stack.
LciMtPushOne »Page Pushes the number 1.0 onto the stack.
LciMtPushPi »Page Pushes the number Pi onto the stack.
LciMtPushRand »Page Pushes a randomly generated number between 0 and 1 onto the top of the stack.
LciMtPushShort »Page Converts the lsshort to an lfloat10 and pushes the converted value onto the stack.
LciMtPushZero »Page Pushes the number 0.0 onto the stack.
LciMtSin »Page Replaces the value at the top of the stack with its sine.
LciMtSqrt »Page Replaces the value at the top of the stack with its square root.
LciMtSub »Page Replaces the first two values at the top of the stack with the result of subtracting TOS from (TOS-1).
LciMtSwap »Page Swaps the positions of the value at the top of the stack (TOS) and the value one down from the top (TOS - 1).
LciMtSwapNth »Page Swaps the positions of the value at the top of the stack (TOS) and the value n down from the top (TOS - n).
LciMtTan »Page Replaces the value at the top of the stack with its tangent.
Definition
Replaces the number at the top of the stack with its absolute value.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtAbs
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Changes the number at top of the stack positive. */
Status = LciMtPushFloat10(Context,-1.003);
Status = LciMtAbs(Context);
Status = LciMtPopFloat10(Context,&Float10,&StackType);
Definition
Replaces the value at the top of the stack with its arc cosine (the angle in radians whose cosine is the value at the top of the stack). The result is in the range [0,Pi].
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtACos
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note LciMtACos requires its argument to be an angle in radians. If the absolute value of the element at the top of the stack is greater than 1, the resulting value at the top of the stack is undefined, and its type is LCI_NUM_ERR.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the arc cosine of the number 1. */
Status = LciMtPushOne(Context);
Status = LciMtACos(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Replaces the first two values at the top of the stack with their sum.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtAdd
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note Calling LciMtAdd reduces the number stack depth by one.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lsshort Short;
lushort StackType;
. . .
/* Finds the result of 1 + 1. */
Status = LciMtPushOne(Context);
Status = LciMtDup(Context, &StackType);
Status = LciMtAdd(Context);
Status = LciMtPopShort(Context, &Short);
Definition
Replaces the value at the top of the stack with its arc sine (the angle in radians whose result is the value at the top of the stack). The result is in the range [-Pi/2, Pi/2].
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL
LciMtASin (LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note LciMtASin requires its argument to be an angle in radians. If the absolute value of the element at the top of the stack is greater than 1, the resulting value at the top of the stack is undefined, and its type is LCI_NUM_ERR.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the arc sine of the number 1. */
Status = LciMtPushOne(Context);
Status = LciMtASin(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Replaces the value at the top of the stack with its arc tangent (the angle, in radians, whose tangent is the value at the top of the stack). The result resides in the range [-Pi/2, Pi/2].
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtATan
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note LciMtATan requires its argument to be an angle in radians.
See Also
LciMtATan2 »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the arc tangent of the number 1. */
Status = LciMtPushOne(Context);
Status = LciMtATan(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Pops the first two values off the top of the stack and replaces them with the arc tangent of TOS/(TOS-1) (the angle in radians whose tangent is TOS/(TOS-1)). TOS is the value at the top of the stack, and (TOS-1) is the value one down from the top of the stack.
The result resides in the ranges listed in the table below.
(TOS-1) TOS Range of result
>= 0 >= 0 [0, Pi/2]
< 0 >= 0 (Pi/2,Pi]
< 0 < 0 (-Pi, -Pi/2)
>= 0 < 0 [-Pi/2, 0)
= 0 = 0 ERR
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtATan2
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note LciMtATan2 requires its argument to be an angle in radians. Calling LciMtATan2 reduces the number stack depth by one.
See Also
LciMtATan »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the arc tangent of -1/1. */
Status = LciMtPushOne(Context);
Status = LciMtPushShort(Context, -1);
Status = LciMtATan2(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Compares the value at the top of the stack (TOS) with the value one down from the top (TOS-1). It sets an output argument to LCI_GREATER if TOS is greater than (TOS-1), to LCI_EQUAL if the two values are equal, and to LCI_LESS if TOS is less than (TOS-1).
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtCompare
(LCH_CONTEXT Context,
lptr(lsshort) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpResult A pointer to an lsshort in which to return the result of the comparison. Possible values are:
LCI_GREATER TOS is greater than (TOS-1)
LCI_EQUAL TOS is equal to (TOS-1)
LCI_LESS TOS is less than (TOS-1)
Returns
LCS_SUCCESS »Page
Note LciMtCompare does not affect the contents of the stack.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lsshort Result;
. . .
Status = LciMtCompare(Context, &Result);
Definition
Compares the value at the top of the stack (TOS) with the value one down from the top (TOS-1). It returns LCI_GREATER if TOS is greater than (TOS-1), LCI_EQUAL if the two values are equal, and LCI_LESS if TOS is less than (TOS-1). This function is similar to LciMtCompare »Page but returns the result of the comparison instead of a status code so that calls can be nested for efficiency.
Format
#include "lcicomn.h"
#include "lcimath.h"
lsshort LCI_CALL LciMtCompareReturn
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
The result of the comparison. Possible values are:
Constant Meaning
LCI_GREATER TOS is greater than (TOS-1)
LCI_EQUAL TOS is equal to (TOS-1)
LCI_LESS TOS is less than (TOS-1)
Note LciMtCompareReturn does not affect the contents of the stack.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
if (LciMtCompareReturn(Context)){
. . .
}
Definition
Replaces the value at the top of the stack with its cosine.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtCos
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note LciMtCos requires its argument to be an angle in radians.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the cosine of the number 0. */
Status = LciMtPushZero(Context);
Status = LciMtACos(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Replaces the first two values at the top of the stack with the quotient that results from (TOS-1)/TOS. TOS is the value at the top of the stack, and (TOS-1) is the value one down from the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtDiv
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note If TOS is 0, the resulting value at the top of the stack is undefined and its type is LCI_NUM_ERR. Similarly, if calling LciMtDiv causes a stack overflow or underflow, the resulting value at the top of the stack is undefined and its type is LCI_NUM_ERR. Calling LciMtDiv reduces the number stack depth by one.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the result of 10/2. */
Status = LciMtPushShort(Context, 10);
Status = LciMtPushShort(Context, 2);
Status = LciMtDiv(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Removes a specified number of values from the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtDropMany
(LCH_CONTEXT Context,
lsshort DropCount)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
DropCount Number of values to remove from the top of the stack.
Returns
LCS_SUCCESS »Page
Note Calling LciMtDropMany reduces the number stack depth by DropCount. If n is less than or equal to 0, or exceeds the number of elements on the stack, your add-in will either halt or yield unpredictable results. If DropCount is 1, LciMtDropMany behaves the same as LciMtDropOne.
See Also
LciMtDropOne »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lushort StackType;
lsshort StackDepth;
. . .
/* If the value at the top of the stack equals ERR, then
drop all the values previously pushed on the stack. */
Status = LciMtGetType(Context, &StackType);
if (StackType == LCI_NUM_ERR){
Status = LciMtGetDepth(Context, &StackDepth);
Status = LciMtDropMany(Context, StackDepth);
}
Definition
Removes the top value from the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtDropOne
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note Calling LciMtDropOne reduces the number stack depth by one.
See Also
LciMtDropMany »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lushort StackType;
. . .
/* If the value at the top of the stack equals ERR,
then drop it. */
Status = LciMtGetType(Context, &StackType);
if (StackType == LCI_NUM_ERR){
LciMtDropOne(Context);
}
Definition
Duplicates the value at the top of the stack and pushes the duplicate onto the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtDup
(LCH_CONTEXT Context,
lptr(lushort) lpStackType)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpStackType A pointer to an lushort in which to return the type of the value at the top of the stack. The type can have one of the following values:
Constant Meaning
LCI_EMPTY_STACK nothing on the stack
LCI_NUM_TREAL an lfloat10
LCI_NUM_ERR the value ERR
LCI_NUM_NA the value NA
Returns
LCS_SUCCESS »Page
Note Calling LciMtDup increases the number stack depth by 1. LciMtDup is the equivalent of LciMtDupNth (0).
See Also
LciMtDupNth »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lsshort Short;
lushort StackType;
. . .
/* Finds the result of 1/1. */
Status = LciMtPushOne(Context);
Status = LciMtDup(Context, &StackType);
Status = LciMtAdd(Context);
Status = LciMtPopShort(Context, &Short);
Definition
Duplicates the value n down from the top of the stack (TOS - n) and pushes the duplicate onto the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtDupNth
(LCH_CONTEXT Context,
lsshort Position,
lptr(lushort) lpStackType)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Position The position of the value you want to duplicate.
lpStackType A pointer to an lushort in which to return the type of the value at the top of the stack. The type can have one of the following values:
Constant Meaning
LCI_EMPTY_STACK nothing on the stack
LCI_NUM_TREAL an lfloat10
LCI_NUM_ERR the value ERR
LCI_NUM_NA the value NA
Returns
LCS_SUCCESS »Page
Note Calling LciMtDupNth increases the number stack depth by 1. If Position is 0, LciMtDupNth behaves the same as LciMtDup.
See Also
LciMtDup »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lslong Long;
lushort StackType;
. . .
/* Finds the result of 10*(20-10). */
Status = LciMtPushLong(Context, 10L);
Status = LciMtPushLong(Context, 20L);
Status = LciMtDupNth(Context, 1, &StackType);
Status = LciMtSub(Context);
Status = LciMtMul(Context);
Status = LciMtPopLong(Context, &Long);
Definition
Replaces the first two values at the top of the stack with LTRUE if the two values are equal, or LFALSE, if they are not equal.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtEq
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note Calling LciMtEq reduces the number stack depth by one. Use LciMtPopShort »Page to pop the value at the top of the stack after calling LciMtEq.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lsshort Result;
. . .
/* Tests two random numbers to see if they are equal. */
Status = LciMtRand(Context);
Status = LciMtRand(Context);
Status = LciMtEq(Context);
Status = LciMtPopShort(Context, &Result);
if (Result == LTRUE){
. . . .
}
Definition
Replaces the value at the top of the stack with e raised to the power of the value at the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtExp
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note If calling LciMtExp causes a stack overflow or underflow, the resulting value at the top of the stack is undefined, and its type is LCI_NUM_ERR.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat8 Float8;
. . .
/* Raises e to the third power. */
Status = LciMtPushShort(Context, 3);
Status = LciMtExp(Context);
Status = LciMtPopFloat8(Context, &Float8);
Definition
Retrieves the number of values currently on the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtGetDepth
(LCH_CONTEXT Context,
lptr(lsshort) lpStackDepth)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpStackDepth A pointer to an lsshort in which to return the stack depth.
Returns
LCS_SUCCESS »Page
Note LciMtGetDepth does not affect the contents of the stack.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lushort StackType;
lsshort StackDepth;
. . .
/* If the value at the top of the stack equals ERR, then drop
all the values that have been previously pushed on the stack. */
Status = LciMtGetType(Context, &StackType);
if (StackType == LCI_NUM_ERR){
Status = LciMtGetDepth(Context &StackDepth);
Status = LciMtDropMany(Context, StackDepth);
}
Definition
Retrieves the type of the value at the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtGetType
(LCH_CONTEXT Context,
lptr(lushort) lpStackType)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpStackType A pointer to an lushort in which to return the type of the value at the top of the stack. The type can have one of the following values:
Constant Meaning
LCI_EMPTY_STACK nothing on the stack
LCI_NUM_TREAL an lfloat10
LCI_NUM_ERR the value ERR
LCI_NUM_NA the value NA
Returns
LCS_SUCCESS »Page
Note LciMtGetType does not affect the contents of the stack.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lushort StackType;
. . .
/* If the value at the top of the stack equals ERR,
PushOne then drop it. */
Status = LciMtGetType(Context, &StackType);
if (StackType == LCI_NUM_ERR){
LciMtDropOne(Context);
}
Definition
Replaces the first two values at the top of the stack with LTRUE if (TOS-1) is greater than TOS, or LFALSE otherwise. TOS is the value at the top of the stack, and (TOS-1) is the value one down from the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtGt
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note Calling LciMtGt reduces the number stack depth by one. Use LciMtPopShort »Page to pop the value at the top of the stack after calling LciMtGt.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lsshort Result;
. . .
/* Tests two random numbers to see if the first is greater
than the second. */
Status = LciMtRand(Context);
Status = LciMtRand(Context);
Status = LciMtGt(Context);
Status = LciMtPopShort(Context, &Result);
if (Result == LTRUE){
. . .
}
Definition
Replaces the first two values at the top of the stack with LTRUE if (TOS-1) is greater than or equal to TOS, and LFALSE otherwise. TOS is the value at the top of the stack, and (TOS-1) is the value one down from the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtGte
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note Calling LciMtGte reduces the number stack depth by one. Use LciMtPopShort »Page to pop the value at the top of the stack after calling LciMtGte.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lsshort Result;
. . .
/* Tests two random numbers to see if the first is greater
than or equal to the second. */
Status = LciMtRand(Context);
Status = LciMtRand(Context);
Status = LciMtGte(Context);
Status = LciMtPopShort(Context, &Result);
if (Result == LTRUE){
. . .
}
Definition
Replaces the value at the top of the stack with an integer, which is the value without its fractional part. For instance, 4.2 and 4.7 both become 4.0, and -4.2 and -4.7 both become -4.0.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtInt
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lslong Long;
. . .
/* Finds the integer component of the square root of 37. */
Status = LciMtPushLong(Context, 37L);
Status = LciMtSqrt(Context);
Status = LciMtInt(Context);
Status = LciMtPopLong(Context, &Long);
Definition
Replaces the value at the top of the stack with its natural logarithm (base e).
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtLN
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note If the value of the element at the top of the stack is less than or equal to 0, the resulting value at the top of the stack is undefined, and its type is LCI_NUM_ERR.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the natural logarithm of 13. */
Status = LciMtPushShort(Context, 13);
Status = LciMtLN(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Replaces the value at the top of the stack with its common logarithm (base 10).
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtLog
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note If the value of the element at the top of the stack is less than or equal to 0, the resulting value at the top of the stack is undefined, and its type is LCI_NUM_ERR.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the base 10 logarithm of 13. */
Status = LciMtPushShort(Context, 13);
Status = LciMtLog(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Replaces the first two values at the top of the stack with LTRUE if (TOS-1) is less than TOS, and LFALSE otherwise. TOS is the value at the top of the stack, and (TOS-1) is the value one down from the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtLt
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note Calling LciMtLt reduces the number stack depth by one. Use LciMtPopShort »Page to pop the value at the top of the stack after calling LciMtLt.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lsshort Result;
. . .
/* Tests two random numbers to see if the first is less than
the second. */
Status = LciMtRand(Context);
Status = LciMtRand(Context);
Status = LciMtLt(Context);
Status = LciMtPopShort(Context, &Result);
if (Result == LTRUE){
. . .
}
Definition
Replaces the first two values at the top of the stack with LTRUE if (TOS-1) is less than or equal to TOS, and LFALSE otherwise. TOS is the value at the top of the stack, and (TOS-1) is the value one down from the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtLte
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note Calling LciMtLte reduces the number stack depth by one. Use LciMtPopShort »Page to pop the value at the top of the stack after calling LciMtLte.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lsshort Result;
. . .
/* Tests two random numbers to see if the first is less than
or equal to the second. */
Status = LciMtRand(Context);
Status = LciMtRand(Context);
Status = LciMtLte(Context);
Status = LciMtPopShort(Context, &Result);
if (Result == LTRUE){
. . .
}
Definition
Replaces the first two values at the top of the stack with the remainder that results from dividing (TOS-1)/TOS. TOS is the value at the top of the stack, and (TOS-1) is the value one down from the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtMod
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note If the value of the element at the top of the stack is equal to 0, the resulting value at the top of the stack is undefined, and its type is LCI_NUM_ERR. Calling LciMtMod reduces the number stack depth by one.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
. . .
/* Tests to see if 100 is evenly divisible by 7. */
Status = LciMtPushLong(Context, 100L);
Status = LciMtPushLong(Context, 7L);
Status = LciMtMod(Context);
if (LciMtPopLongReturn(Context) == 0){
. . .
}
Definition
Replaces the first two values at the top of the stack with their product.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtMul
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note If calling LciMtMul causes a stack overflow or underflow, the resulting value at the top of the stack is undefined, and its type is LCI_NUM_ERR. Calling LciMtMul reduces the number stack depth by one.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lslong Long;
lushort StackType;
. . .
/* Finds the result of 10*(20-10). */
Status = LciMtPushLong(Context, 10L);
Status = LciMtPushLong(Context, 20L);
Status = LciMtDupNth(Context, 1, &StackType);
Status = LciMtSub(Context);
Status = LciMtMul(Context);
Status = LciMtPopLong(Context, &Long);
Definition
Negates the value at the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtNegate
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
Status = LciMtNegate(Context);
Status = LciMtPopFloat10(Context,&Float10,&StackType);
Definition
Replaces the first two values at the top of the stack with LTRUE if the two values are not equal, or LFALSE, if they are equal.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtNeq
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note Calling LciMtNeq reduces the number stack depth by one. Use LciMtPopShort »Page to pop the value at the top of the stack after calling LciMtNeq.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lushort Result;
. . .
/* Tests two random numbers to see if they are not equal. */
Status = LciMtRand(Context);
Status = LciMtRand(Context);
Status = LciMtNeq(Context);
Status = LciMtPopShort(Context, &Result);
if (Result == LTRUE){
. . .
}
Definition
Pops a value off the top of the stack and stores it in an lfloat8 format.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPopFloat8
(LCH_CONTEXT Context,
lptr(lfloat8) LpValNum)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpValNum A pointer to an lfloat8 in which you want to return the value.
Returns
LCS_SUCCESS »Page
LCS_VAL_TOO_BIG »Page
Note If LciMtPopFloat8 returns LCS_VAL_TOO_BIG, the value that lpValNum points to is the IEEE representation of an undefined number.
See Also
LciMtPopFloat10 »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat8 Float8;
. . .
/* Raises e to the third power. */
Status = LciMtPushShort(Context, 3);
Status = LciMtExp(Context);
Status = LciMtPopFloat8(Context, &Float8);
Definition
Pops a value off the top of the stack and stores it in an lfloat10 format.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPopFloat10
(LCH_CONTEXT Context,
lptr(lfloat10) lpValNum,
lptr(lushort) lpStackType)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpValNum A pointer to an lfloat10 in which to return the value.
lpStackType A pointer to an lushort in which to return the type of the value at the top of the stack. The type can have one of the following values:
Constant Meaning
LCI_EMPTY_STACK nothing on the stack
LCI_NUM_TREAL an lfloat10
LCI_NUM_ERR the value ERR
LCI_NUM_NA the value NA
Returns
LCS_SUCCESS »Page
See Also
LciMtPopFloat8 »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the cosine of the number 0. */
Status = LciMtPushZero(Context);
Status = LciMtCos(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Pops the value at the top of the stack and rounds it to a long integer (lslong) value.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPopLong
(LCH_CONTEXT Context,
lptr(lslong) lpValNum)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpValNum A pointer to an lslong in which to return the value at the top of stack, rounded to an integer (lslong). If the value is too big to fit into an lslong, ValNum is set to 0X80000000 and the function returns LCS_VAL_TOO_BIG.
Returns
LCS_SUCCESS »Page
LCS_VAL_TOO_BIG »Page
Note LciMtPopLong rounds the result using the round-to-even-exponent method. For instance, 9.5 rounds to 10, and 8.5 rounds to 8.
See Also
LciMtPopShort »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lslong Long;
lushort StackType;
. . .
/* Finds the result of 10*(20-10). */
Status = LciMtPushLong(Context, 10L);
Status = LciMtPushLong(Context, 20L);
Status = LciMtDupNth(Context, 1, &StackType);
Status = LciMtSub(Context);
Status = LciMtMul(Context);
Status = LciMtPopLong(Context, &Long);
Definition
Pops the value at the top of the stack and returns it as the function value. The value is rounded to a long integer (lslong) value. This function is similar to LciMtPopLong »Page but returns the popped value instead of a status code so that calls can be nested for efficiency.
Format
#include "lcicomn.h"
#include "lcimath.h"
lslong LCI_CALL LciMtPopLongReturn
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
The value as a long integer (lslong).
LCIMATH_LONG_TOO_BIG is returned if the number is too big for a long. See Lcimath.h for definition.
Note LciMtPopLongReturn rounds the result using the round-to-even-exponent method. For instance, 9.5 rounds to 10, and 8.5 rounds to 8.
See Also
LciMtPopShortReturn »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
. . .
/* Tests to see if 100 is evenly divisible by 7. */
Status = LciMtPushLong(Context, 100L);
Status = LciMtPushLong(Context, 7L);
Status = LciMtMod(Context);
if (LciMtPopLongReturn(Context) == 0){
. . .
}
Definition
Pops the value at the top of the stack and rounds it to an integer (lsshort) value.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPopShort
(LCH_CONTEXT Context,
lptr(lsshort) lpValNum)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpValNum A pointer to an lsshort in which to return the value at the top of stack, rounded to an integer (lsshort). If the value is too big to fit into an lsshort, ValNum is set to 0X8000 and the function returns LCS_VAL_TOO_BIG.
Returns
LCS_SUCCESS »Page
LCS_VAL_TOO_BIG »Page
Note LciMtPopShort rounds the result using the round-to-even-exponent method. For instance, 9.5 rounds to 10, and 8.5 rounds to 8.
See Also
LciMtPopLong »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lsshort Short;
lushort StackType;
. . .
/* Finds the result of 1/1. */
Status = LciMtPushOne(Context);
Status = LciMtDup(Context, &StackType);
Status = LciMtAdd(Context);
Status = LciMtPopShort(Context, &Short);
Definition
Pops the value at the top of the stack and rounds it to an integer (lsshort) value. This function is similar to LciMtPopShort »Page but returns the popped value instead of a status code so that calls can be nested for efficiency.
Format
#include "lcicomn.h"
#include "lcimath.h"
lsshort LCI_CALL LciMtPopShortReturn
LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
The returned value as an integer (lsshort).
LCIMATH_SHORT_TOO_BIG is returned if the number is too big for a short. See Lcimath.h for the value returned.
Note LciMtPopShortReturn rounds the result using the round-to-even-exponent method. For instance, 9.5 rounds to 10, and 8.5 rounds to 8.
See Also
LciMtPopLongReturn »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
. . .
/* Tests two random numbers to see if they are equal. */
Status = LciMtRand(Context);
Status = LciMtRand(Context);
Status = LciMtEq(Context);
if (LciMtPopShortReturn(Context)){
. .
}
Definition
Replaces the first two values at the top of the stack with (TOS-1)(TOS). TOS is the value at the top of the stack, and (TOS-1) is the value one down from the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPow
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note If any of the following conditions occur, the resulting value at the top of the stack is undefined, and the type of the value is LCI_NUM_ERR:
stack overflow
stack underflow
(TOS-1) = 0 and TOS <= 0
(TOS-1) < 0 and TOS is not an integer
Note Calling LciMtPow reduces the number stack depth by one.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat8 Float8;
. . .
/* Raises 10.2 to the third power using 8 byte floating-point
numbers. */
Status = LciMtPushFloat8(Context, 10.2);
Status = LciMtPushShort(Context, 3);
Status = LciMtPow(Context);
Status = LciMtPopFloat8(Context, &Float8);
Definition
Pushes LCI_NUM_ERR onto the type stack and 0.0 onto the number stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPushErr
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
See Also
LciMtPushNa »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
. . .
Status = LciMtPushErr(Context);
Definition
Converts the lfloat8 to an lfloat10 and pushes the converted value onto the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPushFloat8
(LCH_CONTEXT Context,
lfloat8 ValNum)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
ValNum The desired value.
Returns
LCS_SUCCESS »Page
See Also
LciMtPushFloat10 »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Initializes a variable to 10.1 and leaves it on the stack. */
Status = LciMtPushFloat8(Context, 10.1);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Status = LciMtPushFloat10(Context, &Float10);
Definition
Pushes the specified lfloat10 value onto the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPushFloat10
(LCH_CONTEXT Context,
lfloat10 ValNum)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
ValNum The desired value.
Returns
LCS_SUCCESS »Page
See Also
LciMtPushFloat8 »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Initializes a variable to 10.1 and leaves it on the stack. */
Status = LciMtPushFloat8(Context, 10.1);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Status = LciMtPushFloat10(Context, &Float10);
Definition
Converts the lslong to an lfloat10 and pushes the converted value onto the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPushLong
(LCH_CONTEXT Context,
lslong ValNum)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
ValNum The desired value.
Returns
LCS_SUCCESS »Page
See Also
LciMtPushShort »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lslong Long;
lushort StackType;
. . .
/* Finds the result of 10*(20-10). */
Status = LciMtPushLong(Context, 10L);
Status = LciMtPushLong(Context, 20L);
Status = LciMtDupNth(Context, 1, &StackType);
Status = LciMtSub(Context);
Status = LciMtMul(Context);
Status = LciMtPopLong(Context, &Long);
Definition
Pushes LCI_NUM_NA onto the type stack and 0.0 onto the number stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPushNa
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
See Also
LciMtPushErr »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
. . .
Status = LciMtPushNa(Context);
Definition
Pushes the number 1.0 onto the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPushOne
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
See Also
LciMtPushPi »Page , LciMtPushZero »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the result of 1/1. */
Status = LciMtPushOne(Context);
Status = LciMtPushOne(Context);
Status = LciMtDiv(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Pushes the number Pi onto the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPushPi
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
See Also
LciMtPushOne »Page , LciMtPushZero »Page .
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the tangent of the number Pi. */
Status = LciMtPushPi(Context);
Status = LciMtTan(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Pushes a randomly-generated number between 0 and 1 onto the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPushRand
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lsshort Result;
. . .
/* Tests two random numbers to see if they are equal. */
Status = LciMtPushRand(Context);
Status = LciMtPushRand(Context);
Status = LciMtEq(Context);
Status = LciMtPopShort(Context, &Result);
if (Result == LTRUE){
. . .
}
Definition
Converts the lsshort to an lfloat10 and pushes the converted value onto the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPushShort
(LCH_CONTEXT Context,
lsshort ValNum)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
ValNum The desired value.
Returns
LCS_SUCCESS »Page
See Also
LciMtPushLong »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the natural logarithm of 13. */
Status = LciMtPushShort(Context, 13);
Status = LciMtLN(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Pushes the number 0.0 onto the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtPushZero
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
See Also
LciMtPushOne »Page , LciMtPushPi »Page .
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the cosine of the number 0. */
Status = LciMtPushZero(Context);
Status = LciMtCos(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Replaces the value at the top of the stack with its sine.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtSin
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note LciMtSin requires its argument to be an angle in radians.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the sine of the number 1. */
Status = LciMtPushOne(Context);
Status = LciMtSin(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
Definition
Replaces the value at the top of the stack with its square root.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtSqrt
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note If the value of the element at the top of the stack is less than 0, the resulting value at the top of the stack is undefined, and its type is LCI_NUM_ERR.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lslong Long;
. . .
/* Finds the integer component of the square root of 37. */
Status = LciMtPushLong(Context, 37L);
Status = LciMtSqrt(Context);
Status = LciMtInt(Context);
Status = LciMtPopLong(Context, &Long);
Definition
Replaces the first two values at the top of the stack with the result of subtracting TOS from (TOS-1). TOS is the value at the top of the stack, and (TOS-1) is the value one down from the top of the stack.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtSub
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note If calling LciMtSub causes a stack overflow or underflow, the resulting value at the top of the stack is undefined, and its type is LCI_NUM_ERR. Calling LciMtSub reduces the number stack depth by one.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lslong Long;
lushort StackType;
. . .
/* Finds the result of 10*(20-10). */
Status = LciMtPushLong(Context, 10L);
Status = LciMtPushLong(Context, 20L);
Status = LciMtDupNth(Context, 1, &StackType);
Status = LciMtSub(Context);
Status = LciMtMul(Context);
Status = LciMtPopLong(Context, &Long);
Definition
Swaps the positions of the value at the top of the stack (TOS) and the value one down from the top (TOS-1).
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtSwap
(LCH_CONTEXT Context,
lptr(lushort) lpStackType)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpStackType A pointer to an lushort in which to return the type of the value at the top of the stack. The type can have one of the following values:
Constant Meaning
LCI_EMPTY_STACK nothing on the stack
LCI_NUM_TREAL an lfloat10
LCI_NUM_ERR the value ERR
LCI_NUM_NA the value NA
Returns
LCS_SUCCESS »Page
Note LciMtSwap does not affect the number of elements on the stack. LciMtSwap(Context,lpStackType) is the equivalent of LciMtSwapNth(Context1,lpStackType)).
See Also
LciMtSwapNth »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lushort StackType;
. . .
Status = LciMtSwap(Context, &StackType);
Definition
Swaps the positions of the value at the top of the stack (TOS) and the value n down from the top (TOS-n), where n is the value you specify.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtSwapNth
(LCH_CONTEXT Context,
lsshort Position,
lptr(lushort) lpStackType)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Position The position of the value you want to swap.
lpStackType A pointer to an lushort in which to return the type of the value at the top of the stack. The type can have one of the following values:
Constant Meaning
LCI_EMPTY_STACK nothing on the stack
LCI_NUM_TREAL an lfloat10
LCI_NUM_ERR the value ERR
LCI_NUM_NA the value NA
Returns
LCS_SUCCESS »Page
Note LciMtSwapNth does not affect the number of elements on the stack. LciMtSwapNth (1) is the equivalent of LciMtSwap.
See Also
LciMtSwap »Page
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
lushort StackType;
. . .
/* Swaps the first (top) and third values on the stack. */
Status = LciMtSwapNth(Context, 2, &StackType);
Definition
Replaces the value at the top of the stack with its tangent.
Format
#include "lcicomn.h"
#include "lcimath.h"
LCT_STATUS LCI_CALL LciMtTan
(LCH_CONTEXT Context)
Argument
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
Note LciMtTan requires its argument to be an angle in radians. If the value of the element at the top of the stack is either -Pi/2 or Pi/2, the resulting value at the top of the stack is undefined, and its type is LCI_NUM_ERR.
Example
#include "lcicomn.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 Float10;
lushort StackType;
. . .
/* Finds the tangent of the number Pi. */
Status = LciMtPushPi(Context);
Status = LciMtTan(Context);
Status = LciMtPopFloat10(Context, &Float10, &StackType);
You use Range functions to represent 1-2-3 worksheet ranges in your add-ins. A data object that has type Range refers to a specific 1-2-3 range.
Function Meaning
LciRgCalc »Page Recalculates a range in specified order.
LciRgConstructAddr »Page Constructs an object handle to a range specified by a name or address string.
LciRgConstructCoords »Page Constructs an object handle to a range specified by workfile name and coordinates of the first and last cells.
LciRgConstructCurr »Page Constructs an object handle to the currently selected range or to the single-cell range at the current location of the cell pointer.
LciRgCoords2Name »Page Creates a name for a specified range, and updates the LCH_RANGE structure to be a named range.
LciRgCopy »Page Copies the contents, format and protection status in the source range to the target range. The cells in the source range are not modified.
LciRgCopyVals »Page Copies the data in the source range to the target range, replacing any formulas in the range with their values. Format and protection are also copied.
LciRgCreateName »Page Creates a name for a specified range.
LciRgCreateScenario »Page Creates a name for a specified scenario.
LciRgCreateVersion »Page Creates a name for a specified version.
LciRgDeleteName »Page Deletes a range name and any associated range name notes from the worksheet file that contains the range name.
LciRgDestroy »Page Releases a range object handle.
LciRgEditCopy »Page Copies a range to the clipboard.
LciRgEditCut »Page Cuts a range to the clipboard.
LciRgEditPaste »Page Pastes contents of the clipboard, including all attributes, to a range.
LciRgEditPasteSpec »Page Pastes styles from the clipboard to a range.
LciRgErase »Page Erases the contents of the cells in the specified range.
LciRgGetAddr »Page Retrieves the string representation of the location of the specified range.
LciRgGetColCount »Page Retrieves the number of columns in the range.
LciRgGetContext »Page Retrieves the context handle corresponding to a range object handle.
LciRgGetCoords »Page Retrieves the location coordinates of the first and last cells in the range.
LciRgGetFileName »Page Retrieves the name of the workfile that contains the specified range.
LciRgGetFirstCol »Page Retrieves the number of the first column in the range.
LciRgGetFirstRow »Page Retrieves the number of the first row in the range.
LciRgGetFirstSheet »Page Retrieves the number of the first sheet in the range.
LciRgGetLastCol »Page Retrieves the number of the last column in the range.
LciRgGetLastRow »Page Retrieves the number of the last row in the range.
LciRgGetLastSheet »Page Retrieves the number of the last sheet in the range.
LciRgGetNote »Page Retrieves the range name note attached to the specified range.
LciRgGetRowCount »Page Retrieves the number of rows in the specified range.
LciRgGetSheetCount »Page Retrieves the number of sheets in the specified range.
LciRgGetValidFlag »Page Retrieves a flag that specifies if the range reference in the range object is still valid.
LciRgIterCells »Page Directs a caller-supplied iterator function through the cells in a range until either the iterator function returns LFALSE or all cells in the range have been iterated through.
LciRgJustify »Page Realigns a column of labels, treating the column as a paragraph and adjusting the labels so that no lines are wider than the last column in the range.
LciRgMove »Page Moves the contents, format, and protection status of the source range to the target range.
LciRgRegisterCalc »Page Registers a callback function to be called after each calc cycle if a given range is "dirty."
LciRgRunMacro »Page Executes a worksheet macro stored in a specified range.
LciRgSetBoldFlag »Page Sets or clears the bold flag for every cell in a range.
LciRgSetBorderColor »Page Sets the current font attribute for a cell.
LciRgSetBorders »Page Sets the borders for every cell in a range.
LciRgSetColor »Page Sets the foreground or background color for every cell in a range.
LciRgSetColorNegFlag »Page Sets or clears a flag that is LTRUE if negative values are displayed in contrasting color; LFALSE otherwise for each cell in a specified range.
LciRgSetColWidth »Page Sets the column width in characters for each column within a specified range.
LciRgSetFont »Page Sets the current typeface and font size for every cell in a range.
LciRgSetFont2 »Page Sets the current font attribute for a range.
LciRgSetFormat »Page Sets the format and number of decimal places of each cell in a specified range.
LciRgSetHiddenFlag »Page Hides or makes visible every cell in a range.
LciRgSetItalicFlag »Page Turns italics on or off for every cell in a range.
LciRgSetLabelType »Page Sets the alignment of labels contained in the cell for each cell in a range.
LciRgSetNote »Page Sets the range name note to be attached to a specified range.
LciRgSetOutline »Page Sets the outermost border lines for cells of a range to a specific line type.
LciRgSetParenFlag »Page Specifies whether negative values are to be enclosed in parentheses for each cell in the specified range.
LciRgSetPattern »Page Sets the shading attribute for each cell in a range.
LciRgSetProtectFlag »Page Sets or clears the protection flag for every cell in a range.
LciRgSetRowHeight »Page Sets the row height in points for every row in the range.
LciRgSetShadowFlag »Page Sets or clears the drop shadow attribute for every cell in a range.
LciRgSetUnderline »Page Sets the underline setting for every cell in a range.
LciRgTranspose »Page Copies the data in the source range to the target range, changing the orientation of the data by transposing the values in the cells of the source range relative to the cells of the target range.
LciRgUndefineName »Page Creates an undefined range name by dissociating a range name from its range address.
LciRgUnregisterCalc »Page Unregisters something registered by LciRgRegisterCalc.
LcxRgSetAttributeFlags »Page Sets the current attribute settings for all cells in a range for 1-2-3 for Windows, Release 1.0.
LcxRgSetAttributeFlags2 »Page Sets the current attribute flags for a range for 1-2-3 Release 4.0 for Windows.
Definition
Recalculates a range in specified order.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgCalc
(LCH_RANGE Range,
lushort CalcOrder)
Arguments
Range The handle of an existing range object.
CalcOrder The desired calculation order. Possible values are:
LCI_CALC_ORDER_COLWISE
LCI_CALC_ORDER_ROWWISE
Returns
LCS_SUCCESS »Page
LCS_INVALID_ORDER »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* Calculate the range columnwise. */
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgCalc(Range,LCI_CALC_ORDER_COLWISE);
. . .
Status = LciRgDestroy(&Range);
Definition
Constructs an object handle to a range specified by a name or address string. Range objects that are in files that are not in memory must refer to named ranges.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgConstructAddr
(LCH_CONTEXT Context,
lptr(lmbcs) lpRangeAddr,
lptr(LCH_RANGE) lpRange)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
RangeAddr A range name (for a named range) or address (for example, <<myfile>>A:E10..A:J12).
lpRange A pointer to storage to which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_INVALID_ADDRESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructAddr(Context,"<<myfile>>A:E10..A:J12",
&Range);
. . .
Status = LciRgDestroy(&Range);
Definition
Constructs an object handle to a range specified by workfile name and coordinates of the first and last cells. Range objects that are in files that are not in memory must refer to named ranges.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgConstructCoords
(LCH_CONTEXT Context,
lptr(lmbcs) lpFileName,
lushort FirstSheetNum,
lushort FirstColNum,
lushort FirstRowNum,
lushort LastSheetNum,
lushort LastColNum,
lushort LastRowNum,
lptr(LCH_RANGE) lpRange)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpFileName The name of a workfile. It must not be longer than LCI_MAX_FILENAME_LEN. It can be LCI_UNTITLED_WORKFILE to specify the untitled workfile or LCI_CURRENT_WORKFILE to specify the current workfile.
FirstSheetNum One-based sheet number of the first cell in the range.
FirstColNum One-based column number of the first cell in the range.
FirstRowNum One-based row number of the first cell in the range.
LastSheetNum One-based sheet number of the last cell in the range.
LastColNum One-based column number of the last cell in the range.
LastRowNum One-based row number of the last cell in the range.
lpRange A pointer to storage to which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_INVALID_COL »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_ROW »Page
LCS_INVALID_SHEET »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* Construct a range in untitled workfile from C:B2..C:E10. */
Status = LciRgConstructCoords(Context,LCI_UNTITLED_WORKFILE,
3,2,2,3,5,10,&Range);
. . .
Status = LciRgDestroy(&Range);
Definition
Constructs an object handle to the currently selected range or to a single-cell range corresponding to the current location of the cell pointer if there is no currently selected range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgConstructCurr
(LCH_CONTEXT Context,
lptr(LCH_RANGE) lpRange)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpRange A pointer to storage to which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
. . .
Status = LciRgDestroy(&Range);
Definition
Copies the contents, format, and protection status of cells in the source range to the target range. The cells in the source range are not modified unless the source range overlays the target range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgCopy
(LCH_RANGE SourceRange,
LCH_RANGE TargetRange)
Arguments
SourceRange The handle of the source range object.
TargetRange The handle of the target range object.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_BOUNDS »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE SourceRange;
LCH_RANGE TargetRange;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&SourceRange);
Status = LciRgConstructAddr(Context,
"<<myfile>>A:E10..A:J12",
&TargetRange);
Status = LciRgCopy(SourceRange, TargetRange);
. . .
Status = LciRgDestroy(&SourceRange);
Status = LciRgDestroy(&TargetRange);
Definition
Copies the data from a source range to a target range, replacing any formulas in the source range with their values in the target range. Format and protection are also copied. The cells in the source range are not modified unless the source range overlaps the target range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgCopyVals
(LCH_RANGE SourceRange,
LCH_RANGE TargetRange)
Arguments
SourceRange The handle of the source range object.
TargetRange The handle of the target range object.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_BOUNDS »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE SourceRange;
LCH_RANGE TargetRange;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&SourceRange);
Status = LciRgConstructAddr(Context,
"<<myfile>>A:E10..A:J12",
&TargetRange);
Status = LciRgCopyVals(SourceRange, TargetRange);
. . .
Status = LciRgDestroy(&SourceRange);
Status = LciRgDestroy(&TargetRange);
Definition
Creates a name for a specified range, and updates the LCH_RANGE structure to be a named range. The call sequence to complete this is :
LciRgConstructCoords()
LciRgCoords2Name()
LciRgDestroy()
The above is similar to performing the following :
LciRgConstructCoords()
LciRgCreateName()
LciRgDestroy()
LciRgConstructAddr()
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgCoords2Name
(LCH_RANGE Range,
lptr(lmbcs) Rangename)
Arguments
Range The handle of an existing range object.
RangeName The name to create.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_NAME »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* construct a coordinate range */
Status = LciRgConstructCoords(Context,"myfile.wk4",
1,1,1,
3,3,3, &Range);
/* name it, and continue operating on it */
Status = LciRgCoords2Name(Range, "MYRANGE");
. . .
Status = LciRgDestroy(&Range);
Definition
Creates a name for a specified range.
Note that LciRgCreateName creates a named range in 1-2-3 using the coordinates of the range passed. This does not convert the range passed in from a coordinate range to a named range. To do that, use LciRgCoord2Name.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgCreateName
(LCH_RANGE Range,
lptr(lmbcs) lpRangename)
Arguments
Range The handle of an existing range object.
lpRangename Pointer to a lmbcs string that specifies the name to be assigned to the range.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_NAME »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgCreateName(Range,"MyRangeName");
. . .
Status = LciRgDestroy(&Range);
Definition
Creates a scenario in the Version Manager using the current versions in the applicable ranges.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgCreateScenario
(LCH_CONTEXT Context,
lptr(lmbcs) lpScenarioName,
lushort ShareOption,
lptr(lmbcs) lpComment)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpScenarioName Name of the scenario.
ShareOption Is a #define that specifies shareoption for the scenario. It is either of the following constants:
ShareOption 1-2-3 does the following:
LCI_UNPROTECTED Applies no protection to the scenario; default if the argument is omitted
LCI_PROTECTED Prevents changes to the scenario
LCI_HIDDEN Prevents changes to and hides the scenario
lpComment Text that specifies a comment about the scenario. You must supply a comment, LNULL is not accepted for this field.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
...
LCT_STATUS Status;
...
Status = LciRgCreateScenario(Context, "Optimistic",
LCI_UNPROTECTED, "Assumes booming economy.");
Definition
Creates a version in the Version Manager. The range must be a named range.
Note You must create your range with a call to LciRgCoords2Name.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgCreateVersion
(LCH_RANGE Range,
lptr(lmbcs) lpVersionName,
lushort ShareOption,
lbool Retain-styles,
lptr(lmbcs) lpComment)
Arguments
Range The name of the range that contains the version. Range must be an existing named range.
lpVersionName Pointer to a lmbcs string that specifies the name to be assigned to the range.
ShareOption The text that specifies the sharing option for the version. It is either of the following:
ShareOption 1-2-3 does the following:
LCI_UNPROTECTED Applies no protection to the version; default if the argument is omitted
LCI_PROTECTED Prevents changes to the version
LCI_HIDDEN Prevents changes to and hides the version
Retain-styles A yes/no argument that specifies whether to save style information with the version. LTRUE = retain, LFALSE = do not retain.
lpComment The text that specifies a comment about the version. You must supply a comment, LNULL is not accepted for this field.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* construct a coordinate range */
Status = LciRgConstructAddr(Context,"<<myfile>>A:E10..A:J12",
&Range);
/* name it, and continue operating on it */
Status = LciRgCoords2Name(Range, "MYRANGE");
Status = LciRgCreateVersion(Range, "Strong Sales",
LCI_UNPROTECTED, LTRUE, "50% probability");
. . .
Status = LciRgDestroy(&Range);
Definition
Deletes a range name and any associated range name notes from the worksheet file that contains the range name. The range name can be specified with or without the filename. If the range name does not include the filename, the range name must be unique in memory. The file must be in memory. The data in cells remains unchanged.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgDeleteName
(LCH_CONTEXT Context,
lptr(lmbcs) lpRangeName)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpRangeName Pointer to a lmbcs string that specifies the range name to delete.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_NAME »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCT_STATUS Status;
. . .
Status = LciRgDeleteName(Context,"MyRangeName");
Definition
Releases a range object handle and frees all associated memory.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgDestroy
(LCH_RANGE Range)
Arguments
lpRange A pointer to a range object handle.
Note lpRange is LNULL upon return from LciRgDestroy.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context, &Range);
. . .
Status = LciRgDestroy(&Range);
Definition
Copies a range to the clipboard.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciRgEditCopy
(LCH_CONTEXT Context,
LCT_RANGE Range,
lptr(lmbcs) format)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Range Range to copy.
Format Clipboard Format to use.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
....
LCH_RANGE Range;
LCT_STATUS Status;
....
Status = LciRgConstructCurr(Context,&Range);
/* copy range to the clipboard */
Status = LciRgEditCopy(Range,LNULL);
Definition
Cuts a range to the clipboard.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciRgEditCut
(LCH_CONTEXT Context,
LCT_RANGE Range,
lptr(lmbcs) format)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Range Range to cut.
Format Clipboard Format to use.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
....
LCH_RANGE Range;
LCT_STATUS Status;
....
Status = LciRgConstructCurr(Context,&Range);
/* cut the range to the clipboard */
Status = LciRgEditCut(Range,LNULL);
Definition
Pastes contents of clipboard, including all attributes, to a range.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciRgEditPaste
(LCH_CONTEXT Context,
LCT_RANGE Range,
lptr(lmbcs) format)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Range Range to paste into.
Format Clipboard Format to use.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
....
LCH_RANGE Range;
LCT_STATUS Status;
....
Status = LciRgConstructCurr(Context,&Range);
/* Paste range from the clipboard */
Status = LciRgEditPaste(Range,LNULL);
Definition
Pastes styles from clipboard to a range.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciRgEditPasteSpec
(LCH_CONTEXT Context,
LCT_RANGE Range,
lushort Properties);
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Range Range to paste into.
Properties Properties to paste:
LCF_SPEC_BOTH
LCF_SPEC_CONTENTS
LCF_SPEC_STYLES
LCF_SPEC_VALUES
LCF_SPEC_QUERY
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcienum.h"
#include "lcirange.h"
....
LCH_RANGE Range;
LCT_STATUS Status;
....
Status = LciRgConstructCurr(Context,&Range);
/* paste style info from clipboard */
Status = LciRgEditPasteSpec(Range,LCF_SPEC_STYLES);
Definition
Erases the contents of the cells in the specified range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgErase
(LCH_RANGE Range)
Arguments
Range The handle of an existing range object.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgErase(Range);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the string representation of the location of the specified range. The address is specified in either the form of an address "<<filename.ext>> A:A1..IV:IV8192", or if a range name is passed "<<filename.ext>>myrange".
Format
#include "lcicomn.h"
#include "lcirange.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciRgGetAddr
(LCH_RANGE Range,
lushort BufLen,
lptr(lmbcs) lpAddr)
Arguments
Range The handle of an existing range object.
BufLen The number of bytes available in the buffer pointed to by lpAddr, including room for a null-terminating byte. The value need not be greater than LCI_MAX_RANGENAME_LEN.
lpAddr A pointer to a lmbcs string in which to return the range address string.
Returns
LCS_SUCCESS »Page
LCS_STR_TOO_LONG »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCT_STATUS Status;
LCH_RANGE Range;
lmbcs RangeName[LCI_MAX_RANGENAME_LEN];
. . .
Status = LciRgConstructAddr(Context, RangeName, &Range);
Status = LciRgGetAddr(Range,LCI_MAX_RANGENAME_LEN,RangeName);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the number of columns in the range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetColCount
(LCH_RANGE Range,
lptr(lushort) lpColCount)
Arguments
Range The handle of an existing range object.
lpColCount A pointer to an lushort in which to return the column count.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lushort ColCount;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetColCount(Range,&ColCount);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the context handle that was used to construct the range object.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetContext
(LCH_RANGE Range,
lptr(LCH_CONTEXT) lpContext)
Arguments
Range The handle of an existing range object.
lpContext A pointer to storage to which to return the context handle.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCH_CONTEXT NewContext;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetContext(Range,&NewContext);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the location coordinates of the first and last cells in the range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetCoords
(LCH_RANGE Range,
lushort BufLen,
lptr(lmbcs) lpFileName,
lptr(lushort) lpFirstSheetNum,
lptr(lushort) lpFirstColNum,
lptr(lushort) lpFirstRowNum,
lptr(lushort) lpLastSheetNum,
lptr(lushort) lpLastColNum,
lptr(lushort) lpLastRowNum)
Arguments
Range The handle of an existing range object.
BufLen The number of bytes available in the buffer pointed to by lpFileName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_FILENAME_LEN.
lpFileName Pointer to a lmbcs string in which to return the filename.
lpFirstSheetNum Pointer to an lushort in which to return the sheet number of the first cell.
lpFirstColNum Pointer to an lushort in which to return the column number of the first cell.
lpFirstRowNum Pointer to an lushort in which to return the row number of the first cell.
lpLastSheetNum Pointer to an lushort in which to return the sheet number of the last cell.
lpLastColNum Pointer to an lushort in which to return the column number of the last cell.
lpLastRowNum Pointer to an lushort in which to return the row number of the last cell.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lmbcs FileName[LCI_MAX_FILENAME_LEN];
lushort FirstSheetNum,FirstColNum,FirstRowNum;
lushort LastSheetNum,LastColNum,LastRowNum;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetCoords (Range,
LCI_MAX_FILENAME_LEN,
FileName,
&FirstSheetNum,
&FirstColNum,
&FirstRowNum,
&LastSheetNum,
&LastColNum,
&LastRowNum);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the name of the workfile that contains the specified range. If you specified a filename when you created the range object, the range must be defined in that file if on disk or in memory. If you did not specify a path or extension for the file, the default 1-2-3 directory is searched for the file. If you specified the wildcard file reference (<<?>>RangeName) when you created the range object, the range must be defined in one and only one file in memory. If you did not specify any file information when you created the range object, the range must be defined in the current worksheet file.
If the worksheet file containing the range is in memory, the filename retrieved includes the full path. If the worksheet file is on disk, the filename contains as much file information as you specified when you created the range object. If you subsequently retrieved the file from the disk, the filename is updated to include the full path.
Range objects in files not in memory must refer to named ranges.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetFileName
(LCH_RANGE Range,
lushort BufLen,
lptr(lmbcs) lpFileName)
Arguments
Range The handle of an existing range object.
BufLen The number of bytes available in the buffer pointed to by lpFileName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_FILENAME_LEN.
lpFileName A pointer to a lmbcs string in which to return the filename.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lmbcs FileName[LCI_MAX_FILENAME_LEN];
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetFileName(Range,
LCI_MAX_FILENAME_LEN,
FileName);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the number of the first column in a range. Numbering starts at one and is relative to the worksheet, not relative to the range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetFirstCol
(LCH_RANGE Range,
lptr(lushort) lpColNum)
Arguments
Range The handle of an existing range object.
lpColNum A pointer to an lushort in which to return the column number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lushort ColNum;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetFirstCol(Range,&ColNum);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the number of the first row in the range. Numbering starts at one and is relative to the worksheet, not relative to the range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetFirstRow
(LCH_RANGE Range,
lptr(lushort) lpRowNum)
Arguments
Range The handle of an existing range object.
lpRowNum A pointer to an lushort in which to return the row number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lushort RowNum;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetFirstRow(Range,&RowNum);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the number of the first sheet in the range. Numbering starts at one and is relative to the workfile, not relative to the range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetFirstSheet
(LCH_RANGE Range,
lptr(lushort) lpSheetNum)
Arguments
Range The handle of an existing range object.
lpSheetNum A pointer to an lushort in which to return the sheet number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lushort SheetNum;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetFirstSheet(Range,&SheetNum);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the number of the last column in the range. Numbering starts at one and is relative to the worksheet, not relative to the range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetLastCol
(LCH_RANGE Range,
lptr(lushort) lpColNum)
Arguments
Range The handle of an existing range object.
lpColNum A pointer to an lushort in which to return the column number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lushort ColNum;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetLastCol(Range,&ColNum);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the number of the last row in the range. Numbering starts at one and is relative to the worksheet, not relative to the range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetLastRow
(LCH_RANGE Range,
lptr(lushort) lpRowNum)
Arguments
Range The handle of an existing range object.
lpRowNum A pointer to an lushort in which to return the row number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lushort RowNum;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetLastRow(Range,&RowNum);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the number of the last sheet in the range. Numbering starts at one and is relative to the workfile, not relative to the range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetLastSheet
(LCH_RANGE Range,
lptr(lushort) lpSheetNum)
Arguments
Range The handle of an existing range object.
lpSheetNum A pointer to an lushort in which to return the sheet number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lushort SheetNum;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetLastSheet(Range,&SheetNum);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the range name note attached to the specified range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetNote
(LCH_RANGE Range,
lushort BufLen,
lptr(lmbcs) lpNote)
Arguments
Range The handle of an existing range object.
BufLen The number of bytes available in the buffer pointed to by lpNote, including room for a null-terminating byte. BufLen need not be greater than LCI_MAX_NOTE_LEN.
lpNote A pointer to a lmbcs string in which to return the text of the note. lpNote should be initialized to LNULL.
Note Range must be a named range.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lmbcs Note[LCI_MAX_NOTE_LEN];
. . .
lstrcpy(Note,LNULL);
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetNote(Range,LCI_MAX_NOTE_LEN,Note);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the number of rows in the specified range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetRowCount
(LCH_RANGE Range,
lptr(lushort) lpRowCount)
Arguments
Range The handle of an existing range object.
lpRowCount A pointer to an lushort in which to return the number of rows.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lushort RowCount;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetRowCount(Range,&RowCount);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the number of sheets in the specified range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetSheetCount
(LCH_RANGE Range,
lptr(lushort) lpSheetCount)
Arguments
Range The handle of an existing range object.
lpSheetCount A pointer to an lushort in which to return the number of sheets.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lushort SheetCount;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetSheetCount(Range,&SheetCount);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves a flag that specifies whether the range reference in the range object is still valid. A range object is valid if the range it refers to exists. A range object can become invalid if 1-2-3 deleted rows, columns, or sheets where the range was located, or removed the file that contains the range from memory.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgGetValidFlag
(LCH_RANGE Range,
lptr(lbool) lpValidFlag)
Arguments
Range The handle of an existing range object.
lpValidFlag A pointer to an lbool in which to return the flag. The flag is LTRUE if the range is still valid; LFALSE otherwise.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lbool ValidFlag;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgGetValidFlag(Range,&ValidFlag);
. . .
Status = LciRgDestroy(&Range);
Definition
Directs a caller-supplied iterator function through the cells in a range until the iterator function returns LFALSE or when the function has iterated through all the cells in the range. If the iterator function returns LFALSE, LciRgIterCells will return a status of LCS_RG_ITER_TERMINATE. It will return LCS_SUCCESS if it has iterated through all the cells.
Dimension-specific arguments (column, row, and sheet) determine both the order of interation and direction (ascending, descending). The caller must supply dimension specifiers for all three dimensions (column, row, and sheet) in the three dimension specifier arguments (Dim1Spec, Dim2Spec, and Dim3Spec), but may do so in any order. Failure to specify all three dimensions will result in a return status of LCS_INVALID_ITER_SPEC »Page .
Dimension Specifier Meaning
LCI_RG_ITER_ROW_UP Iterates through rows in ascending order.
LCI_RG_ITER_ROW_DOWN Iterates through rows in descending order.
LCI_RG_ITER_COLUMN_UP Iterates through columns in ascending order.
LCI_RG_ITER_COLUMN_DOWN Iterates through columns in descending order.
LCI_RG_ITER_SHEET_UP Iterates through sheets in ascending order.
LCI_RG_ITER_SHEET_DOWN Iterates through sheets in descending order.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgIterCells
(LCH_RANGE Range,
lushort Dim1Spec,
lushort Dim2Spec,
lushort Dim3Spec,
lptr(LCT_ITER_FUNC_RANGE) Iterator,
lptr(lulong) lpData);
Arguments
Range The handle of the existing range object.
Dim1Spec The specification for the first (fastest iterating or innermost) dimension of iteration.
Dim2Spec Specification for the second dimension of iteration.
Dim3Spec Specification for the third (slowest iterating or outermost) dimension of iteration.
Iterator A caller-supplied function that will be invoked by LciRgIterCells for each cell in the range (see function prototype below.)
lpData A pointer to caller's data that will be passd each time the caller's interator function is invoked by LciRgIterCells.
lbool LCI_CALL Iterator
(LCH_CELL Cell,
lptr(lulong) lpData)
Note The lptr(lulong) lpData item in the code shown above is the same as the lpData item passed to LciRgIterCells.
Cell The object handle of the current cell the iterator has reached in the range.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_ITER_SPEC »Page
LCS_OUT_OF_MEMORY »Page
LCS_RG_ITER_TERMINATE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicell.h
#include "lcicomn.h"
#include "lcirange.h"
. . .
{
LCH_RANGE Range;
LCT_STATUS Status;
lushort NumberCellCount = 0;
LciRgConstructCurr(Context,&Range);
/* Call the iterator function to get a count of
all the cells in the current range that contain a number
value */
Status = LciRgIterCells(Range,
LCI_RG_ITER_ROW_DOWN,
LCI_RG_ITER_COLUMN_DOWN,
LCI_RG_ITER_SHEET_DOWN,
AverageCells,
&NumberCellCount);
. . .
}
lbool LCI_CALL AverageCells(LCH_CELL Cell, lptr(lulong) lpCount)
{
lushort ValueType;
LciClGetValType(Cell,&ValueType);
if (LCI_VAL_TYPE_NUM == ValueType)
++(lushort)*lpCount;
return LTRUE;
}
Definition
Realigns a column of labels, treating the column as a paragraph and adjusting the labels so that no lines are wider than the last column in the range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgJustify
(LCH_RANGE Range,
lushort PaneNum)
Arguments
Range The handle of the existing range object.
PaneNum The one-based number of a pane within each window, or LCI_CURRENT_PANE to specify the current pane. PaneNum=1 refers to the top, left, or only pane.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_PANE »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_CELL »Page
LCS_RANGE_FULL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgJustify(Range,LCI_CURRENT_PANE);
. . .
Status = LciRgDestroy(&Range);
Definition
Moves the contents, format, and protection status of cells in the source range to the target range. The cells in the source range are overwritten if the source range overlaps the target range. Otherwise, the contents of the source range are erased and the formats are changed to the worksheet dafault formats. Once the move is completed, the source range object is no longer valid and should be destroyed by calling LciRgDestroy »Page .
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgMove
(LCH_RANGE SourceRange,
LCH_RANGE TargetRange)
Arguments
SourceRange The handle of the source range object.
TargetRange The handle of the target range object.
Returns
LCS_SUCCESS »Page
LCS_DIFFERENT_FILES »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_BOUNDS »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE SourceRange;
LCH_RANGE TargetRange;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&SourceRange);
Status = LciRgConstructAddr(Context,
"<<myfile>>A:E10..A:J12",
&TargetRange);
Status = LciRgMove(SourceRange,TargetRange);
. . .
Status = LciRgDestroy(&SourceRange);
Status = LciRgDestroy(&TargetRange);
Definition
Registers a callback function to be called after each calc cycle if the specified range is "dirty."
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgRegisterCalc
(LCH_RANGE Range,
lptr (LCT_CALC_FUNC_RANGE) Handler,
lushort RegID,
lptr (LCH_REGISTRATION) lpRegHandle)
Arguments
Range The handle of a range object containing the macro to run.
Handler Pointer to the callback function,
typedef void LIC_CALL LCT_CALC_FUNC_RANGE (lushort RegId) ;
Note: This callback does not provide an LCI context. To use other LCI functions in this callback, the calling program must save its context and use LciLdGetAddinHandle in AdnInitialize and LciLdSetAddinHandle in this routine. This is similar to the procedure necessary in tool procedures.
RegID User-defined number, returned with the callback.
lpRegHandle Handle to enable unregistration.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lcild.h"
#include "lcirange.h"
#define USER_RANGE_TAG 17
/* global data */
LCH_CONTEXT g=GlobalContext;
LCH_ADDIN AddinHandle;
LCH_REGISTRATION RegHandle;
. . .
LCT_STATUS AdnInitialize(LCH_CONTEXT Context)
{
. . .
GlobalContext = Context;
LciLdGetAddinHandle(Context, &AddinHandle);
. . .
}
LCT_CALC_FUNC_RANGE MyRangeChanged(lushort RegId)
{
LciLdSetAddinHandle(GlobalContext, AddinHandle);
. . .
}
{
LCT_STATUS Status;
LCH_RANGE Range;
. . .
Status = LciRgConstructXXXX(Context, ... , &Range);
. . .
Status = LciRgRegisterCalc(Range, MyRangeChanged, USER_RANGE_TAG,
&RegHandle);
. . .
}
Definition
Executes a worksheet macro stored in a specified range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgRunMacro
(LCH_RANGE Range)
Arguments
Range The handle of a range object containing the macro to run.
Returns
LCS_SUCCESS »Page
LCS_KEY_BREAK »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_MACRO_ERROR »Page
LCS_STACK_OVERFLOW »Page
LCS_MISSING_ARG »Page
LCS_INVALID_VALUE »Page
LCS_NULL_HANDLE »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgRunMacro(Range);
. . .
Status = LciRgDestroy(&Range);
Definition
Sets the bold flag for every cell in a range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetBoldFlag
(LCH_RANGE Range,
lbool Bold)
Arguments
Range The handle of an existing range object.
Bold LTRUE if you want all cells in the range displayed bold; LFALSE if you do not.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetBoldFlag(Range,LTRUE);
. . .
Status = LciRgDestroy(&Range);
Definition
Sets the current border color for a range. The border color constants can be seen through the Lines & Color dialog box under Border - Line Color, to view thier respective colors.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetBorderColor
(LCH_RANGE Range,
lushort TopColor,
lushort BottomColor,
lushort LeftColor,
lushort RightColor)
Arguments
Cell The handle of an existing cell object.
TopColor An lushort set to one of the valid border color values.
BottomColor An lushort set to one of the valid border color values.
LeftColor An lushort set to one of the valid border color values.
RightColor An lushort set to one of the valid border color values.
Valid border colors are:
LCI_BORDER_COLOR_1
LCI_BORDER_COLOR_2
LCI_BORDER_COLOR_3
LCI_BORDER_COLOR_4
LCI_BORDER_COLOR_5
LCI_BORDER_COLOR_6
LCI_BORDER_COLOR_7
LCI_BORDER_COLOR_8
LCI_BORDER_COLOR_9
LCI_BORDER_COLOR_10
LCI_BORDER_COLOR_11
LCI_BORDER_COLOR_12
LCI_BORDER_COLOR_13
LCI_BORDER_COLOR_14
LCI_BORDER_COLOR_15
LCI_BORDER_COLOR_16
Returns
LCS_SUCCESS »Page
LCS_INVALID TYPE »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetBorderColor(Range,
LCI_BORDER_COLOR_4, // top = lt. green
LCI_BORDER_COLOR_4, // bottom = lt. green
LCI_BORDER_COLOR_5, // left = royal blue
LCI_BORDER_COLOR_5); // right = royal blue
. . .
Status = LciRgDestroy(&Range);
Definition
Sets the borders for each cell in a range. If you want to set ALL, simply set each line to the same type. If you want to set one and leave the others unchanged, set the desired one to a specific type (NONE, SINGLE, DOUBLE, WIDE) and set the others to LCI_LINE_TYPE_NOCHANGE. In order to set the OUTLINE of a range, you must call LciRgSetOutline »Page .
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetBorders
(LCH_RANGE Range,
lushort TopLine,
lushort BottomLine,
lushort LeftLine,
lushort RightLine)
Arguments
Range The handle of an existing range object.
TopLine, The type of border for the top line.
BottomLine The type of border for the bottom line.
LeftLine The type of border for the left line.
RightLine The type of border for the right line.
Valid line types are:
LCI_LINE_TYPE_NOCHANGE,
LCI_LINE_TYPE_NONE,
LCI_LINE_TYPE_SINGLE,
LCI_LINE_TYPE_DOUBLE
LCI_LINE_TYPE_WIDE
LCI_LINE_TYPE_NARROWDOT
LCI_LINE_TYPE_DOT
LCI_LINE_TYPE_DASH
LCI_LINE_TYPE_DOTDASH
LCI_LINE_TYPE_DASHDOTDOT
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_TYPE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
/* Set all borders to double. */
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetBorders(Range,
LCI_LINE_TYPE_DOUBLE,
LCI_LINE_TYPE_DOUBLE,
LCI_LINE_TYPE_DOUBLE,
LCI_LINE_TYPE_DOUBLE);
. . .
Status = LciRgDestroy(&Range);
Definition
Sets the foreground or background color of a range of cells. Use LciRgSetColorNegFlag »Page to have negative values appear in red.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetColor
(LCH_RANGE Range,
lushort Area,
lushort Color)
Arguments
Range The handle of an existing range object.
Area The desired area type. Valid areas are:
LCI_COLOR_TYPE_BG for background
LCI_COLOR_TYPE_FG for foreground
Color The desired color for the range. Colors are an integer from 0 to 255 that is an index into the Windows color palette. Valid colors are 0 to 255, or one of the following predefined constants:
LCI_COLOR_1
LCI_COLOR_2
LCI_COLOR_3
LCI_COLOR_4
LCI_COLOR_5
LCI_COLOR_6
LCI_COLOR_7
LCI_COLOR_8
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_INDEX »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
/* Set background color. */
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context, &Range);
Status = LciRgSetColor(Range, LCI_COLOR_TYPE_BG, 153);
. . .
Status = LciRgDestroy(&Range);
Definition
For each cell in a specified range, sets whether negative values are to be displayed in a contrasting color. Note that only changes made in the top or left pane are saved with the file.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetColorNegFlag
(LCH_RANGE Range,
lbool ColorNegFlag)
Arguments
Range The handle of an existing range object.
ColorNegFlag The desired flag value. LTRUE if negative values are to be displayed in a contrasting color; LFALSE otherwise.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
/* Set negative numbers in contrasting color. */
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetColorNegFlag(Range,LTRUE);
. . .
Status = LciRgDestroy(&Range);
Definition
For each column within a specified range, sets the column width in characters. Column width can range from LCI_MIN_COL_WIDTH to LCI_MAX_COL_WIDTH.
Note Only changes made in the top or left pane are saved.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetColWidth
(LCH_RANGE Range,
lushort PaneNum,
lushort ColWidth)
Arguments
Range The handle of an existing range object.
PaneNum The one-based number of a pane within each window, or LCI_CURRENT_PANE to specify the current pane. PaneNum = 1 refers to the top, left, or only pane.
ColWidth The desired column width or LCI_DEFAULT_COL_WIDTH to use the default column width for the worksheet.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_WIDTH »Page
LCS_INVALID_PANE »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
/* Set column width to 70. */
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetColWidth(Range,LCI_CURRENT_PANE,70);
. . .
Status = LciRgDestroy(&Range);
Definition
Sets the current typeface and font size according to the chosen font. Font choices correspond to the list of eight fonts displayed in the Style Fonts dialog box.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetFont
(LCH_RANGE Range,
lushort TypeFace)
Arguments
Range The handle of an existing range object.
TypeFace The desired typeface setting for the range. Valid settings are:
LCI_FONT_1
LCI_FONT_2
LCI_FONT_3
LCI_FONT_4
LCI_FONT_5
LCI_FONT_6
LCI_FONT_7
LCI_FONT_8
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
/* Set font to font type symbol 12 from the default font list.*/
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetFont(Range,LCI_FONT_8);
. . .
Status = LciRgDestroy(&Range);
Definition
Sets the current font attribute for a range. The align field is not implemented at this time. The information can be set and retrieved but has no effect on the display. Alignment should be set using LcxClSetAttributeFlags2.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetFont2
(LCH_RANGE Range,
lptr (lmbcs) lpName,
lsshort Height
lubyte Align,
lubyte Attributes,
lubyte FontFamily,
lubyte CharSet,
lubyte UnderType)
Arguments
Range The handle of an existing range object.
Name (i.e. Helvetica) of LCI_MAX-FONTNAME_LEN.
Height Height in points.
Alignment Valid settings are:
LCI_FONT_ALIGN_VERT_BASE
LCI_FONT_ALIGN_VERT_CENTER
LCI_FONT_ALIGN_VERT_TOP
LCI_FONT_ALIGN_VERT_BOTTOM
LCI_FONT_ALIGN_HORZ_DEFAULT
LCI_FONT_ALIGN_HORZ_LEFT
LCI_FONT_ALIGN_HORZ_RIGHT
LCI_FONT_ALIGN_HORZ_CENTER
LCI_FONT_ALIGN_HORZ_DIAGONAL
LCI_FONT_ALIGN_HORZ_EVEN
Attributes (Bold, Italic, etc.) Valid settings are:
LCI_FONT_BOLD
LCI_FONT_ITALIC
LCI_FONT_UNDERLINE - single underline
LCI_FONT_STRIKEOUT
LCI_FONT_OUTLINE
LCI_FONT_SHADOW
FontFamily Valid settings are:
LCI_FONT_FAMILY_DONTCARE
LCI_FONT_FAMILY_ROMAN
LCI_FONT_FAMILY_MODERN
LCI_FONT_FAMILY_SCRIPT
LCI_FONT_FAMILY_DECORATIVE
LCI_FONT_PITCH_DEFAULT
LCI_FONT_PITCH_FIXED
LCI_FONT_VARIABLE
CharSet Valid settings are:
LCI_FONT_CHARSET_ANSI
LCI_FONT_CHARSET_SYMBOL
LCI_FONT_CHARSET_SHIFTJIS
LCI_FONT_CHARSET_HANGUL
LCI_FONT_CHARSET_BIG5
LCI_FONT_CHARSET_OEM
UnderType Valid settings are:
LCI_LINE_TYPE_NONE
LCI_LINE_TYPE_SINGLE
LCI_LINE_TYPE_DOUBLE
LCI_LINE_TYPE_THICK
LCI_LINE_TYPE_BOX
LCI_LINE_TYPE_SINGLESTRIKE
LCI_LINE_TYPE_DOUBLESTRIKE
LCI_LINE_TYPE_THICKSTRIKE
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
#include "lcienum.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetFont2(Range,
"MyFont",
24,
LCI_VERT_ALIGN_CENTER | LCI_HORZ_ALIGN_CENTER,
LCI_FONT_BOLD,
LCI_FONT_CHARSET_ANSI,
LCI_FONT_FAMILY_SWISS | LCI_FONT_PITCH_FIXED,
LCI_LINE_TYPE_NONE);
. . .
Status = LciRgDestroy(&Range);
Definition
Sets the format and number of decimal places of each cell in a specified range.
Note Only changes made in the top or left pane are saved.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetFormat
(LCH_RANGE Range,
lushort Format,
lushort Places)
Arguments
Range The handle of an existing range object.
Format The format to set. Possible values are:
Constant Meaning
LCI_FORMAT_AUTO automatic format
LCI_FORMAT_BAR +/- format
LCI_FORMAT_COMMA thousands separators (numeric)
LCI_FORMAT_CURRENCY international currency format (numeric)
LCI_FORMAT_DATE_INTL_LONG long international date format
LCI_FORMAT_DATE_INTL_SHORT short international date format (D4)
LCI_FORMAT_DAY_MON DD-MMM date format (D2)
LCI_FORMAT_DAY_MON_YR DD-MMM-YY date format (D1)
LCI_FORMAT_DEFAULT default format
LCI_FORMAT_FIXED fixed format (numeric)
LCI_FORMAT_GENERAL general format
LCI_FORMAT_HIDDEN hidden format
LCI_FORMAT_HR_MIN HH:MM (AM/PM) time format (D7)
LCI_FORMAT_HR_MIN_SEC HH:MM:SS (AM/PM) time format (D6)
LCI_FORMAT_LABEL label format
LCI_FORMAT_MON_YR MMM-YY date format (D3)
LCI_FORMAT_PERCENT percent format (numeric)
LCI_FORMAT_SCIENTIFIC sci (scientific) format (numeric)
LCI_FORMAT_TEXT text format
LCI_FORMAT_TIME_INTL_LONG long international (24hr) time format (D8)
LCI_FORMAT_TIME_INTL_SHORT short international (24hr) time format (D9)
Places The number of decimal places to set or LCI_DEFAULT_PLACES. This argument is ignored if Format is not a numeric format.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_FORMAT »Page
LCS_INVALID_PLACES »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
/* Set Range Format to Currency with 2 decimal places. */
LCH_RANGE Range;
LCT_STATUS Status;
. . .
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetFormat(Range,LCI_FORMAT_CURRENCY,2);
. . .
Status = LciRgDestroy(&Range);
Definition
Hides or makes visible all the cells in the specified range.
Note Only changes made in the top or left pane are saved.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetHiddenFlag
(LCH_RANGE Range,
lushort PaneNum,
lbool HiddenFlag)
Arguments
Range The handle of an existing range object.
PaneNum The one-based number of a pane within each window, or LCI_CURRENT_PANE to specify the current pane. PaneNum = 1 refers to the top, left, or only pane.
HiddenFlag LTRUE to hide all cells in the range; LFALSE to make them visible.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_PANE »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_NO_VISIBLE_COLS »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* Hide all cells in the range. */
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetHiddenFlag(Range,LCI_CURRENT_PANE,LTRUE);
. . .
Status = LciRgDestroy(&Range);
Definition
Turns italics on or off for every cell in a range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetItalicFlag
(LCH_RANGE Range,
lbool Italic)
Arguments
Range The handle of an existing range object.
Italic LTRUE if you want all cells in the range displayed in italics; LFALSE if you do not.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* Turn italics on. */
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetItalicFlag(Range,LTRUE);
. . .
Status = LciRgDestroy(&Range);
Definition
For each cell in a range, sets the alignment of labels contained in the cell. It has no effect on numbers, formulas, blank cells, and labelsthat are added subsequently to the range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetLabelType
(LCH_RANGE Range,
lushort LabelType)
Arguments
Range The handle of an existing range object.
LabelType The label type to set. Possible values are:
Constant Meaning
LCI_LABEL_TYPE_CENTER Aligned at the center.
LCI_LABEL_TYPE_LEFT Aligned at the left.
LCI_LABEL_TYPE_RIGHT Aligned at the right.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_LABEL_TYPE »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* Set label alignment to center */
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetLabelType(Range,LCI_LABEL_TYPE_CENTER);
. . .
Status = LciRgDestroy(&Range);
Definition
Sets the range name note attached to a specified range. If the new note is an empty string, any existing range name note is deleted.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetNote
(LCH_RANGE Range,
lptr(lmbcs) lpNote)
Arguments
Range The handle of an existing range object.
lpNote Pointer to a lmbcs string that contains the text of the note to be attached to the range.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_NOTE »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* Set the Range Name Note to MyNote. */
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetNote(Range,"MyNote");
. . .
Status = LciRgDestroy(&Range);
Definition
Sets the outside border lines for the outermost cells of a range to a specific line type.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetOutline
(LCH_RANGE Range,
lushort OutlineType)
Arguments
Range The handle of an existing range object.
OutlineType The desired outline type. Valid types are:
LCI_LINE_TYPE_NONE
LCI_LINE_TYPE_SINGLE
LCI_LINE_TYPE_DOUBLE
LCI_LINE_TYPE_WIDE
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* Set the Range Outline to double. */
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetOutline(Range,LCI_LINE_TYPE_DOUBLE);
. . .
Status = LciRgDestroy(&Range);
Definition
Place or remove parentheses around values in a range of cells that contain negative values.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetParenFlag
(LCH_RANGE Range,
lbool ParenFlag)
Arguments
Range The handle of an existing range object.
ParenFlag LTRUE for parentheses around negative values; LFALSE otherwise.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* Enclose negative values in parenthesis. */
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetParenFlag(Range,LTRUE);
. . .
Status = LciRgDestroy(&Range);
Definition
Sets the shading attribute for each cell in a range. The shading attribute is the pattern that 1-2-3 uses as the background of a cell.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetPattern
(LCH_RANGE Range,
lushort Pattern);
Arguments
Range The handle of an existing range object.
Pattern The desired shading pattern. Valid shading values are:
LCI_PATTERN_LIGHT
LCI_PATTERN_DARK
LCI_PATTERN_CLEAR
LCI_PATTERN_SOLID
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_TYPE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* Set the Shading Pattern to light. */
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetPattern(Range,LCI_PATTERN_LIGHT);
. . .
Status = LciRgDestroy(&Range);
Definition
Protects or unprotects cells in the specified range whenever global protection is enabled.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetProtectFlag
(LCH_RANGE Range,
lbool ProtectFlag)
Arguments
Range The handle of an existing range object.
ProtectFlag LTRUE to protect every cell in the range; LFALSE otherwise.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* Set a flag to LTRUE if the cell is protected when global
protection is enabled. */
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetProtectFlag(Range,LTRUE);
. . .
Status = LciRgDestroy(&Range);
Definition
Sets the row height in points for every row in the range. Legal row heights are LCI_MIN_ROW_HEIGHT to LCI_MAX_ROW_HEIGHT, inclusive.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetRowHeight
(LCH_RANGE Range,
lushort RowHeight)
Arguments
Range The handle of an existing range object.
RowHeight The desired row height.
Returns
LCS_SUCCESS »Page
LCS_INVALID_NUM »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* Set Row Height to 15. */
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetRowHeight(Range,15);
. . .
Status = LciRgDestroy(&Range);
Definition
Sets the drop shadow setting for a range. The drop shadow is an attribute that makes the range stand out as though it were raised above the plane of the sheet.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetShadowFlag
(LCH_RANGE Range,
lbool ShadowFlag)
Arguments
Range The handle of an existing range object.
ShadowFlag LTRUE if you want the range to have a drop shadow; LFALSE if you do not.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_HIDDEN_SHEET »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* Set the drop shadow flag for a range. */
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetShadowFlag(Range,LTRUE);
. . .
Status = LciRgDestroy(&Range);
Definition
Sets or removes underlines for every cell in a range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetUnderline
(LCH_RANGE Range,
lushort Underline)
Arguments
Range The handle of an existing range object.
Underline The desired underline type. Valid settings are:
LCI_LINE_TYPE_NOCHANGE
LCI_LINE_TYPE_NONE
LCI_LINE_TYPE_SINGLE
LCI_LINE_TYPE_DOUBLE
LCI_LINE_TYPE_WIDE
LCI_LINE_TYPE_BOX
LCI_LINE_TYPE_SINGLSTRIKE
LCI_LINE_TYPE_DOUBLSTRIKE
LCI_LINE_TYPE_THICKSTRIKE
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_TYPE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
. . .
/* Set single underline for every cell in the range. */
Status = LciRgConstructCurr(Context,&Range);
Status = LciRgSetUnderline(Range,LCI_LINE_TYPE_SINGLE);
. . .
Status = LciRgDestroy(&Range);
Definition
Copies the data in the source range to the target range, changing the orientation of the data by transposing the values in the cells of the source range relative to the cells of the target range. LciRgTranspose replaces formulas with values. Format and protection are also copied. The cells in the source range are not modified unless the source range overlaps the target range.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgTranspose
(LCH_RANGE SourceRange,
LCH_RANGE TargetRange,
lushort TransType)
Arguments
SourceRange The handle of the source range object.
TargetRange The handle of the target range object.
TransType Specifies orientation of the data to be transposed. Possible values are:
Constant Meaning
LCI_TRANS_ROWS_TO_COLS Transposes the rows of the source range to the columns of the target range.
LCI_TRANS_SHEETS_TO_ROWS Transposes the sheets of the source range to the rows of the target range.
LCI_TRANS_COLS_TO_SHEETS Transposes the columns of the source range to the sheets of the target range.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_TRANS_TYPE »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_BOUNDS »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE SourceRange;
LCH_RANGE TargetRange;
LCT_STATUS Status;
. . .
/* Transpose the sheets of the source range to the rows of
the target range. */
Status = LciRgConstructCurr(Context,&SourceRange);
Status = LciRgConstructAddr(Context,
"<<myfile>>A:E10..A:J12",
&TargetRange);
Status = LciRgTranspose(SourceRange,
TargetRange,
LCI_TRANS_SHEETS_TO_ROWS);
. . .
Status = LciRgDestroy(&SourceRange);
Status = LciRgDestroy(&TargetRange);
Definition
Creates an undefined range name by dissociating a range name from its range address. The range name continues to exist, but it is not associated with a range. Formula references to the range name are not changed.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgUndefineName
(LCH_CONTEXT Context,
lptr(lmbcs) lpRangeName)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpRangeName Pointer to a lmbcs string that contains the name to be undefined.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_NAME »Page
LCS_INVALID_USE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_CONTEXT Context;
LCT_STATUS Status;
. . .
Status = LciRgUndefineName(Context,"MyRangeName");
Definition
Unregisters something registered by LciRgRegisterCalc.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetUnregisterCalc
(LCH_RANGE Range,
lptr (LCH_REGISTRATION) lpRegHandle)
Arguments
Range Range handle that was registered.
lpRegHandle Handle to enable unregistration.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_INVALID_REGISTRATION »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
/* global data */
LCH_REGISTRATION RegHandle;
{
LCT_STATUS Status;
LCH_RANGE Range;
. . .
Status = LciRgUnregisterCalc(Range, &RegHandle);
. . .
}
Definition
Sets the current attribute settings for all cells in a range.
Note This function has an Lcx prefix because it is not a standard Lotus C Interface function. This function is optimized to work with the formats as they are supported in 1-2-3 for Windows, Release 1.0. Although this function will be supported in future versions of 1-2-3 for Windows, it may not be optimized for those versions.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LcxRgSetAttributeFlags
(LCH_RANGE Range,
LCT_ATTRIBUTES Attr)
typedef union LCT_ATTRIBUTES_ {
struct {
lulong l1;
lulong l2;
} longwords;
struct {
unsigned font :3 /* 0-7 */
unsigned bold :1 /* 0-1 */
unsigned italic :1 /* 0-1 */
unsigned underline :2 /* 0-3 */
/* 0=none, 1=single, 2=double, 3=wide */
unsigned reserve0 :1 /* 0-1 */
unsigned cell_color :3 /* 0-7 */
unsigned reserve1 :4
unsigned color_negative :1 /* 0-1 */
unsigned bg_color :3 /* 0-7 */
unsigned pattern :2 /* 0-3 */
/* 0=clear, 1=light, 2=dark, 3=solid */
unsigned drop_shadow :1 /* 0-1 */
unsigned reserve2 :2
unsigned border_left :2 /* 0-3 */
/* 0=none, 1=single, 2=double, 3=wide */
unsigned border_right :2 /* 0-3 */
/* 0=none, 1=single, 2=double, 3=wide */
unsigned border_top :2 /* 0-3 */
/* 0=none, 1=single, 2=double, 3=wide */
unsigned border_bottom :2 /* 0-3 */
/* 0=none, 1=single, 2=double, 3=wide */
unsigned general_format :7 /* LCF_FORMAT_* */
unsigned protected :1 /* 0-1 */
unsigned reserve3 :1
unsigned parentheses :1 /* 0-1 */
unsigned :3 /* 0-7 */
} attrs;
} LCT_ATTRIBUTES;
Arguments
Range The handle of an existing range object.
Attr An LCT_ATTRIBUTES structure that contains the settings to which all cells in the range will be set. This structure is found in the lcicomn.h include file.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_RANGE »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
LCT_ATTRIBUTES Attributes;
. . .
/* Set attributes to bold italic */
Status = LciRgConstructCurr(Context, &Range);
Attributes.attrs.bold = 1;
Attributes.attrs.italic = 1;
Status = LcxRgSetAttributeFlags(Range,Attributes);
. . .
Status = LciRgDestroy(&Range);
Definition
Sets the current attribute flags for a range.
Note This function has an Lcx prefix because it is not a standard Lotus C Interface function. This function is optimized to work with the formats as they are supported in 1-2-3 Release 4.0 for Windows. Although this function will be supported in future versions of 1-2-3 for Windows, it may not be optimized for those versions.
Format
#include "lcicomn.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciRgSetAttributeFlags2
(LCH_RANGE Range,
LCT_ATTRIBUTES2 Attributes)
typedef struct LCT_ATTRIBUTES2_ {
struct {
/* (16 bits) Font Style info */
unsigned font : 12; /* Font handle */
unsigned resv1 : 1; /* Reserved */
unsigned underline : 3; /* Underline conditions */
/* (24 Bits) Cell Patterns. */
unsigned f_color : 8; /* Foreground color index */
unsigned b_color : 8; /* Background color index */
unsigned use_b_color_ndx : 1; /* Use Background color index */
unsigned use_f_color_ndx : 1; /* Use Foreground color index */
unsigned fillpattern : 6; /* Up to 64 fill patterns. */
/* (12 Bits) Text alignment/attributes */
unsigned v_align : 2; /* Alignment for non labels, vertical */
unsigned h_align : 3; /* Horizontal alignment */
unsigned shad2 : 1; /* INTERNAL USE ONLY */
unsigned resv2 : 2; /* Reserved */
unsigned wrap : 1; /* Possible word wrap usage */
unsigned negative : 1; /* Negative #s are red or not. */
unsigned unformated : 1; /* Unused */
unsigned text : 1; /* Text bit attribute for :TE */
/* (1 Bit) Shadow Style */
unsigned shadow : 1; /* Shadow Frame Styles */
/* (20 bits) Border color info up to 31 colors 0 default */
unsigned b_edge_color: 5; /* Bottom edge style */
unsigned t_edge_color: 5; /* Top edge style */
unsigned resv2a : 1; /* padding */
unsigned r_edge_color: 5; /* Right edge style */
unsigned l_edge_color: 5; /* Left edge style */
/* (12 bits) Border style info for 8 border types plus 0 default */
unsigned b_edge : 4; /* Bottom edge style */
unsigned resv2b : 2; /* padding */
unsigned t_edge : 4; /* Top edge style */
unsigned r_edge : 4; /* Right edge style */
unsigned l_edge : 4; /* Left edge style */
/* (3 Bits) Optmization/FM3 Compatiblity, Special bits */
unsigned graph : 1; /* Graph bit attribute */
unsigned DDELink : 1; /* Range contains a DDE Link. */
unsigned resv3 : 2; /* Reserved */
/* Byte 12 Custom User formats */
unsigned userfmt : 8; /* User format handle */
/* Byte 13 Style ID of parent */
unsigned styleid : 8;
} attr2;
union format {
lulong lfmts;
struct {
unsigned general_format : 7; /* LCF_FORMAT_* */
unsigned protectd : 1; /* 0-1 */
unsigned reserve3 : 1;
unsigned parentheses : 1; /* 0-1 */
} fmts;
}number_format;
} LCT_ATTRIBUTES2;
Arguments
Range The handle of an existing range object.
Attributes An LCT_ATTRIBUTES2 which contains the settings to which the range will be set. this struct needs to be initailized with a cell to LcxClGetAttributeFlags2.
Returns
LCS_SUCCESS »Page
LCS_INVALID_RANGE »Page
LCS_STACK_OVERFLOW »Page
LCS_FILE_SEALED »Page
LCS_OFFSHEET_RANGE »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
LCT_ATTRIBUTES2 Attributes;
. . .
Status = LciRgConstructCurr(Context,&Range);
Attributes.v_align = LCI_VERT_ALIGN_CENTER;
Attributes.h_align = LCI_HORZ_ALIGN_CENTER;
Status = LcxClSetAtrributeFlags2(Context,&Range,Attributes);
. . .
Status = LciRgDestroy(&Range);
The @function registration functions register add-in @functions with 1-2-3. Once you register a procedure as an add-in @function, you can use it just as you would a 1-2-3 @function.
Function Meaning
LciAfGetArgLong »Page Gets the number argument of an input argument to the @function as an lslong.
LciAfGetArgNum »Page Gets the lfloat10 value of an input argument to the @function.
LciAfGetArgRange »Page Gets the argument to an @function as an LCH_RANGE.
LciAfGetArgShort »Page Gets the number value of an input argument to the @function as an lsshort.
LciAfGetArgStr »Page Gets an lptr(lmbcs) string argument passed to an add-in @function.
LciAfGetArgType »Page Gets the type of an argument passed to an add-in @function.
LciAfForceArgRange »Page Returns a range, if appropriate, for a specified @function argument or cell .
LciAfRegister »Page Registers an add-in C function as a 1-2-3 @function.
LciAfReturnArgLong »Page Sets an lslong value as the return value of the @function.
LciAfReturnArgNum »Page Sets an lfloat10 value as the return value of an @function.
LciAfReturnArgShort »Page Sets an lsshort value as the return value of an @function.
LciAfReturnArgStr »Page Sets a lptr(lmbcs) string value as the return value of an @function.
LciAfReturnArgType »Page Sets the return value of an @function as either an @ERR or @NA.
LciAfUnRegister »Page Unregisters an add-in @function that was registered by LciAfRegister »Page .
Definition
Retrieves the numeric value of an input argument to the @function as an lslong. If the number is not an integer quantity, it is rounded using standard rounding rules.
Note This function should only be called during execution of a registered add-in @function.
Format
#include "lcicomn.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciAfGetArgLong
(LCH_CONTEXT Context,
lushort ArgIndex,
lptr(lslong) lpValLong)
Arguments
Context The context handle that was passed to the target C function.
ArgIndex Is the one-based position of the input argument. This value cannot be greater than the number of arguments passed to the @function in this invocation or less than 1. The maximum argument count is LCI_MAX_AF_ARG_COUNT.
lpValLong A pointer to an lslong in which the numeric value of the input argument to the @function will be returned.
Status
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
LCS_NOT_NUM »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
. . .
LCT_STATUS Status;
lslong ValLong;
/* Send second argument to an @function as a long. */
Status = LciAfGetArgLong(Context,2,&ValLong);
Definition
Retrieves the lfloat10 value of an input argument to the @function.
Note This function should only be called during execution of a registered add-in @function.
Format
#include "lcicomn.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciAfGetArgNum
(LCH_CONTEXT Context,
lushort ArgIndex,
lptr(lfloat10) lpValNum)
Arguments
Context The context handle that was passed to the target C function.
ArgIndex Is the one-based position of an input argument. This value cannot be greater than the number of arguments passed to the @function in this invocation or less than 1.The maximum argument count is LCI_MAX_AF_ARG_COUNT.
lpValNum A pointer to an lfloat10 in which the value of the input argument to the @function will be returned.
Status
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
LCS_NOT_NUM »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
. . .
LCT_STATUS Status;
lfloat10 ValNum;
/* Get second argument to function as an lfloat10. */
Status = LciAfGetArgNum(Context,2,&ValNum);
Definition
Gets a range input argument to the @function. Ranges must be multiple cells. If the User can enter both single and multiple cells, use LciAfForceArgRange »Page , which captures both. This function acts as a Range constructor and the range should be destroyed using LciRgDestroy »Page before returning.
Note This function should only be called during execution of a registered add-in @function.
Format
#include "lcicomn.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciAfGetArgRange
(LCH_CONTEXT Context,
lushort ArgIndex,
lptr(LCH_RANGE) lpRange)
Arguments
Context The context handle that was passed to the target C function.
ArgIndex Is the one-based position of an input argument. This value cannot be greater than the number of arguments passed to the @function in this invocation or less than 1. The maximum argument count is LCI_MAX_AF_ARG_COUNT.
lpRange A pointer to storage to which to return the range handle. Note that range contents and attributes should not be modified while running an @function.
Status
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
LCS_NOT_RANGE »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
#include "lcirange.h"
. . .
LCT_STATUS Status;
LCH_RANGE Range;
/* Get third argument to function as an range. */
Status = LciAfGetArgRange(Context,3,&Range);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the number value of an input argument to the @function as an lsshort. If the number is not an integer, it will be rounded using standard rounding rules.
Note This function should only be called during execution of a registered add-in @function.
Format
#include "lcicomn.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciAfGetArgShort
(LCH_CONTEXT Context,
lushort ArgIndex,
lptr(lsshort) lpValShort)
Arguments
Context The context handle that was passed to the target C function.
ArgIndex Is the one-based position of an input argument. This value cannot be greater than the number of arguments passed to the @function in this invocation or less than 1. The maximum argument count is LCI_MAX_AF_ARG_COUNT.
lpValShort A pointer to an lsshort in which the number value of the input argument to the @function will be returned.
Status
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
LCS_NOT_NUM »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
. . .
LCT_STATUS Status;
lsshort ValShort;
/* Get second argument to function as a short. */
Status = LciAfGetArgShort(Context,2,&ValShort);
Definition
Retrieves a string input argument to the @function.
Note This function should only be called during execution of a registered add-in @function.
Format
#include "lcicomn.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciAfGetArgStr
(LCH_CONTEXT Context,
lushort ArgIndex,
lushort BufLen,
lptr(lmbcs) lpValStr)
Arguments
Context The context handle that was passed to the target C function.
ArgIndex Is the one-based position of an input argument. This value cannot be greater than the number of arguments passed to the @function in this invocation or less than 1. The maximum argument count is LCI_MAX_AF_ARG_COUNT.
BufLen The number of bytes available in the buffer pointed to by lpValStr, including room for a null-terminating byte.
lpValStr A pointer to a lmbcs string in which the string input argument to the @function will be returned.
Status
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
LCS_OUT_OF_MEMORY »Page
LCS_NOT_STR »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
. . .
LCT_STATUS Status;
lmbcs ValStr[100];
Status = LciAfGetArgStr(Context,1,100,ValStr);
Definition
Retrieves the type of an input argument.
Note This function should only be called during execution of a registered add-in @function.
Format
#include "lcicomn.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciAfGetArgType
(LCH_CONTEXT Context,
lushort ArgIndex,
lptr(lushort) lpValType)
Arguments
Context The context handle that was passed to the target C function.
ArgIndex Is the one-based position of an input argument. This value cannot be greater than the number of arguments passed to the @function in this invocation or less than 1. The maximum argument count is LCI_MAX_AF_ARG_COUNT.
lpValType A pointer to an lushort in which to return the data type. Possible values are:
Constant Meaning
LCI_VAL_TYPE_ERR @ERR
LCI_VAL_TYPE_NA @NA
LCI_VAL_TYPE_NUM A number
LCI_VAL_TYPE_RANGE A range handle
LCI_VAL_TYPE_STR A string
Status
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
. . .
LCT_STATUS Status;
lushort ArgType;
/* Get the type of the fourth argument to the function. */
Status = LciAfGetArgType(Context,4,&ArgType);
switch(ArgType)
{
. . .
}
Definition
Returns a range, if appropriate, for a specified @function argument. Similar to LciAfGetArgRange, however, if the user specified a single cell in this argument, LciAfForceArgRange will also return a range for that cell, whereas LciAfGetArgRange will return an LCS_NOT_RANGE error. Acts as a Range constructor. Therefore the range should be destoyed using LciRgDestroy »Page before returning.
Note This function should only be called during execution of a registered add-in @function.
Format
#include "lcicomn.h"
#include "lciatfnc.h"
LCT_STATUS LCI_CALL LciAfForceArgRange
(LCH_CONTEXT LpiContext,
lushort ArgIndex,
lptr(LCH_RANGE) lpRange)
Arguments
LpiContext The context handle that was passed to the target C function.
ArgIndex One-based position of an input argument. This value cannot be greater than the number of arguments passed to the @function in this invocation or less than 1.
lpRange A pointer to storage to which to return the range handle. Note that range contents and attributes should not be modified during the execution of the @function.
Returns
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
LCS_NOT_RANGE »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
#include "lcirange.h"
. . .
LCT_STATUS Status;
LCH_RANGE Range;
/* Get second argument to function as a range */
Status = LciAfForceArgRange(Context, 2, &Range);
. . .
Status = LciRgDestroy(&Range);
Definition
Registers an add-in C function as a 1-2-3 @function. Registration makes the @function available for users.
Format
#include "lcicomn.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciAfRegister
(LCH_CONTEXT Context,
lptr(lmbcs) lpAtName,
lptr(LCT_AF_CALL) lpCFunctionPtr,
lulong RegisterArg,
lushort ArgCount,
lptr(lushort) lpArgTypeFlagsArray,
lulong OptionFlags,
lptr(LCH_REGISTRATION) lpRegistration)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpAtName The name of the @function to be registered, as it will appear in spreadsheet formulas, minus the leading "@". Maximum length is 16 characters. Names that are longer are truncated.
lpCFunctionPtr A pointer to the C function to be called when an instance of AtName is evaluated in a spreadsheet formula. The calling sequence of the C function is:
LCT_STATUS LCI_CALL client_c_function
(LCH_CONTEXT Context,
lulong RegisterArg,
lushort ActualArgCount)
where Context is the same context that 1-2-3 passed to the C function that registered the @function, RegisterArg is the registration-specific argument, and ActualArgCount is the actual number of input arguments passed to the @function. The data types of the input arguments are restricted by the values in lpArgTypeFlagsArray at registration time.
RegisterArg A data value specific to this registration that 1-2-3 will pass to the C function each time it is invoked as the target of the specified @function. This value can be a pointer to an arbitrary data structure. RegisterArg allows you to implement different @functions using the same C procedure.
ArgCount The minimum number of arguments up to 32 required to invoke the @function (LCI_MAX_AF_ARG_COUNT is defined to 32 in lcicomn.h). If OptionFlags includes LCF_AF_REGISTER_VARYING_ARGS, the @function will accept more than this number of arguments. If ArgCount equals zero and OptionFlags includes LCF_AF_REGISTER_VARYING_ARGS, the @function will accept zero or more arguments of any type.
lpArgTypeFlagsArray A pointer to an array of ArgCount words of flags specifying the data types allowed for each input argument. Each element of the array can be any OR'd combination of the following flags. The zero'th element of the array corresponds to the first input argument. If OptionFlags includes LCF_AF_REGISTER_VARYING_ARGS, input arguments past the ArgCount'th argument have the same data type requirements as the ArgCount'th argument.
Constant Meaning
LCF_AF_ARG_ALLOW_NUM Allows a number input.
LCF_AF_ARG_ALLOW_RANGE Allows a range handle input.
LCF_AF_ARG_ALLOW_STR Allows a string input.
LCF_AF_ARG_ALLOW_ANY Allows string range or number type input.
OptionFlags Consists of zero or more of the following flags OR'd together. The "DIRTY" flags are mutually exclusive:
Constant Meaning
LCF_AF_REGISTER_DIRTY_ALWAYS @function is invoked whenever recalculation takes place.
LCF_AF_REGISTER_DIRTY_ARG @function is invoked whenever one of its arguments changes value.
LCF_AF_REGISTER_DIRTY_DATE @function is invoked whenever the date changes.
LCF_AF_REGISTER_VARYING_ARGS @function will accept any number of arguments greater than or equal to ArgCount.
lpRegistration A pointer to a variable of type LCH_REGISTRATION in which to return a registration handle that can be passed to LciAfUnregister.
Note A successfully registered @function can be unregistered by one of the following actions:
· calling LciAfUnregister with the handle returned at registration
· removing the add-in by having the user explicitly execute a remove or clear
· terminating 1-2-3.
Note Although the lpArgTypeFlagsArray and the absence of the LCF_AF_REGISTER_VARYING_ARGS are ignored in 1-2-3 for Windows Release 1.0, they may be implemented in future versions of 1-2-3 for Windows. Code should be written to utilize these features or @functions may stop working in future versions.
Status
LCS_SUCCESS »Page
LCS_INVALID_NAME »Page
LCS_INVALID_NUM »Page
LCS_OUT_OF_MEMORY »Page
LCS_MISSING_DATA »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
. . .
LCT_STATUS Status;
lushort ArgFlags;
LCH_REGISTRATION Registration;
ArgFlags[0] = LCF_AF_ARG_ALLOW_ANY;
ArgFlags[1] = LCF_AF_ARG_ALLOW_RANGE | LCF_AF_ARG_ALLOW_NUM;
ArgFlags[2] = LCF_AF_ARG_ALLOW_STR;
/* Register an @function that will take a minimum of three
arguments of which the first argument may be a range, string,
or number; the second only a range or number, and the third
and subsequent argument may only be strings. This function is
invoked using the name NEWATFUNC in the spreadsheet. It will
be dirty when an argument to it changes. */
Status = LciAfRegister(Context,
"NewAtFunc", /* Name used in sheet */
internal_c_function, /* C function name */
0L, /* Registration argument */
3, /* Minimum argument count */
ArgFlags, /* Arg flags array */
LCF_AF_REGISTER_DIRTY_ARG |
LCF_AF_REGISTER_VARYING_ARGS, /* Options */
&Registration);
. . .
Status = LciAfUnregister(Context, Registration);
Definition
Sets an lslong value as the return value of the @function. Any previously set value will be replaced.
Note This function should only be called during execution of a registered add-in @function.
Format
#include "lcicomn.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciAfReturnArgLong
(LCH_CONTEXT Context,
lslong ReturnNum)
Arguments
Context The context handle that was passed to the target C function.
ReturnNum The return value.
Status
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
. . .
LCT_STATUS Status;
lulong ReturnNum;
. . .
ReturnNum = 300000;
Status = LciAfReturnArgLong(Context,ReturnNum);
Definition
Sets an lfloat10 value as the return value of an @function. This function may only be called during execution of an add-in @function. Any previously set return value will be replaced.
Note This function should only be called during execution of a registered add-in @function.
Format
#include "lcicomn.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciAfReturnArgNum
(LCH_CONTEXT Context,
lfloat10 ReturnNum)
Arguments
Context The context handle that was passed to the target C function.
ReturnNum The return value.
Status
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
#include "lcimath.h"
. . .
LCT_STATUS Status;
lfloat10 NumVal;
lushort StackType;
. . .
LciMtPushShort(Context, 33);
LciMtPopFloat10(Context,&NumVal,&StackType);
LciAfReturnArgNum(Context, NumVal);
Definition
Sets an lsshort value as the return value of an @function. Any previously set return value will be replaced.
Note This function should only be called during execution of a registered add-in @function.
Format
#include "lcicomn.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciAfReturnArgShort
(LCH_CONTEXT Context,
lsshort ReturnNum)
Arguments
Context The context handle that was passed to the target C function.
ReturnNum The return value.
Status
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
. . .
LCT_STATUS Status;
. . .
Status = LciAfReturnArgShort(Context,42);
Definition
Sets a string value as the return value of an @function. Any previously set return value will be replaced.
Note This function should only be called during execution of a registered add-in @function.
Format
#include "lcicomn.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciAfReturnArgStr
(LCH_CONTEXT Context,
lptr(lmbcs) ReturnStr)
Arguments
Context The context handle that was passed to the target C function.
ReturnStr A pointer to a lmbcs string in which to store the return value.
Status
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
. . .
LCT_STATUS Status;
/* Return "hello world" from an @function.*/
Status = LciAfReturnArgStr(Context, "hello world");
Definition
Sets either @ERR or @NA as the return value of the @function. Any previously set return value will be replaced.
Note This function should only be called during execution of a registered add-in @function.
Format
#include "lcicomn.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciAfReturnArgType
(LCH_CONTEXT Context,
lushort ReturnType)
Arguments
Context The context handle that was passed to the target C function.
ReturnType The return type. Possible values are:
Constant Meaning
LCI_VAL_TYPE_ERR ERR
LCI_VAL_TYPE_NA NA
Status
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
. . .
LCT_STATUS Status;
/* Return ERR from the @function.*/
Status = LciAfReturnArgType(Context,LCI_VAL_TYPE_ERR);
Definition
Unregisters an add-in @function that was previously registered by LciAfRegister »Page . Unregistering the @function means that it can no longer be called by users.
Format
#include "lcicomn.h"
#include "lciaf.h"
LCT_STATUS LCI_CALL LciAfUnregister
(LCH_CONTEXT Context,
LCH_REGISTRATION Registration)
Arguments
Context The context handle that was passed to LciAfRegister.
Registration A registration handle previously returned by a call to LciAfRegister.
Status
LCS_SUCCESS »Page
LCS_INVALID_REGISTRATION »Page
Example
#include "lcicomn.h"
#include "lciaf.h"
. . .
LCT_STATUS Status;
lushort ArgFlags[3];
LCH_REGISTRATION Registration;
ArgFlags[0] = LCF_AF_ARG_ALLOW_ANY;
ArgFlags[1] = LCF_AF_ARG_ALLOW_RANGE | LCF_AF_ARG_ALLOW_NUM;
ArgFlags[2] = LCF_AF_ARG_ALLOW_STR;
/* Register an @function that will take a minimum of three
arguments of which the first argument may be a range, string,
or number; the second only a range or number, and the third
and subsequent argument may only be strings. This function
is invoked using the name NEWATFUNC in the spreadsheet. It
will be dirty when an argument to it changes. */
Status = LciAfRegister(Context,
"NewAtFunc", /* Name used in sheet */
internal_c_function, /* C function name */
0L, /* Registration argument */
3, /* Minimum argument count */
ArgFlags, /* Arg flags array */
LCF_AF_REGISTER_DIRTY_ARG |
LCF_AF_REGISTER_VARYING_ARGS, /* Options */
&Registration);
. . .
Status = LciAfUnregister(Context, Registration);
The macro registration functions register custom macro procedures and keywords with 1-2-3. Once you register a procedure as a macro, you can use it just as you would any 1-2-3 macro keyword or procedure.
Function Meaning
LciMcGetArgLong »Page Gets an argument to a registered macro keyword as an lslong.
LciMcGetArgNum »Page Gets an argument to a registered macro keyword as an lfloat10.
LciMcGetArgRange »Page Gets an argument to a registered macro keyword as an LCH_RANGE.
LciMcGetArgShort »Page Gets an argument to a registered macro keyword as an lsshort.
LciMcGetArgStr »Page Gets an argument to a registered macro keyword as an lptr(lmbcs).
LciMcGetArgType »Page Gets the type of an argument passed to a registered macro keyword.
LciMcRegister »Page Registers a C function to be called as a 1-2-3 macro keyword.
LciMcUnregister »Page Unregisters an add-in macro that was previously registered by LciMcRegister »Page .
Definition
Retrieves the lslong value of an input argument to the macro. If the number is not an integer quantity, it will be rounded using standard rounding rules.
Note This function should only be called during the execution of a registered add-in macro keyword.
Format
#include "lcicomn.h"
#include "lcimc.h"
LCT_STATUS LCI_CALL LciMcGetArgLong
(LCH_CONTEXT Context,
lushort ArgIndex,
lptr(lslong) lpValLong)
Arguments
Context The context handle that was passed to the target C function.
ArgIndex The one-based position of an input argument. This value cannot be greater than the number of arguments passed to the macro in this invocation. The maximum argument count is LCI_MAX_MC_ARG_COUNT.
lpValLong A pointer to an lslong in which the value of the input argument to the macro will be returned.
Returns
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
LCS_NOT_NUM »Page
Example
#include "lcicomn.h"
#include "lcimc.h"
. . .
LCT_STATUS Status;
lushort ArgIndex = 2;
lslong ValNum;
. . .
/* Get second argument to function as an lslong. */
Status = LciMcGetArgLong(Context, ArgIndex, &ValNum);
Definition
Retrieves the lfloat10 value of an input argument to the macro.
Note This function should only be called during the execution of a registered add-in macro keyword.
Format
#include "lcicomn.h"
#include "lcimc.h"
LCT_STATUS LCI_CALL LciMcGetArgNum
(LCH_CONTEXT Context,
lushort ArgIndex,
lptr(lfloat10) lpValNum)
Arguments
Context The context handle that was passed to the target C function.
ArgIndex The one-based position of an input argument. This value cannot be greater than the number of arguments passed to the macro in this invocation. The maximum argument count is LCI_MAX_MC_ARG_COUNT.
lpValNum A pointer to an lfloat10 in which the value of the input argument to the macro will be returned.
Returns
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
LCS_NOT_NUM »Page
Example
#include "lcicomn.h"
#include "lcimc.h"
. . .
LCT_STATUS Status;
lushort ArgIndex = 3;
lslong ValNum;
. . .
/* Get third argument to function as an lfloat10. */
Status = LciMcGetArgNum(Context, ArgIndex, &ValNum);
Definition
Retrieves a handle to a range passed as an input argument to the macro. This function acts as a Range constructor and the range should be destroyed using LciRgDestroy »Page before returning.
Note This function should only be called during the execution of a registered add-in macro keyword.
Format
#include "lcicomn.h"
#include "lcimc.h"
#include "lcirange.h"
LCT_STATUS LCI_CALL LciMcGetArgRange
(LCH_CONTEXT Context,
lushort ArgIndex,
lptr(LCH_RANGE) lpRange)
Arguments
Context The context handle that was passed to the target C function.
ArgIndex The one-based position of an input not greater than the number of arguments passed to the macro in this invocation. The maximum argument count is LCI_MAX_MC_ARG_COUNT.
lpRange A pointer to storage to which the range handle passes as the input argument to the macro will be returned.
Returns
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
LCS_NOT_RANGE »Page
Example
#include "lcicomn.h"
#include "lcimc.h"
#include "lcirange.h"
. . .
LCH_RANGE Range;
LCT_STATUS Status;
lushort ArgIndex = 3;
. . .
/* Get the third argument to function as a range. */
Status = LciMcGetArgRange(Context, ArgIndex, &Range);
. . .
Status = LciRgDestroy(&Range);
Definition
Retrieves the lsshort value of an input argument to the macro. If the number is not an integer quantity it will be rounded using standard rounding rules.
Note This function should only be called during the execution of a registered add-in macro keyword.
Format
#include "lcicomn.h"
#include "lcimc.h"
LCT_STATUS LCI_CALL LciMcGetArgShort
(LCH_CONTEXT Context,
lsshort ArgIndex,
lptr(lushort) lpValShort)
Arguments
Context The context handle that was passed to the target C function.
ArgIndex The one-based position of an input argument. This value cannot be greater than the number of arguments passed to the macro in this invocation. The maximum argument count is LCI_MAX_MC_ARG_COUNT.
lpValShort A pointer to an lushort in which the value of the input argument to the macro will be returned.
Returns
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
LCS_NOT_NUM »Page
Example
#include "lcicomn.h"
#include "lcimc.h"
. . .
LCT_STATUS Status;
lushort ArgIndex = 1;
lushort ValNum;
. . .
/* Get first argument to function as an lsshort. */
Status = LciMcGetArgShort(Context, ArgIndex, &ValNum);
Definition
Retrieves the value of a string argument passed to an add-in macro.
Note This function should only be called during the execution of a registered add-in macro keyword.
Format
#include "lcicomn.h"
#include "lcimc.h"
LCT_STATUS LCI_CALL LciMcGetArgStr
(LCH_CONTEXT Context,
lushort ArgIndex,
lushort BufLen,
lptr(lmbcs) lpValStr)
Arguments
Context The context handle that was passed to the target C function.
ArgIndex The one-based position number of an input argument. This value cannot be greater than the number of arguments passed to the macro in this invocation or less than 1. The maximum argument count is LCI_MAX_MC_ARG_COUNT.
BufLen The number of bytes available in the buffer pointed to by lpValStr, including room for a null-terminating byte.
lpValStr A pointer to the lmbcs string in which the value of the string argument passed to the add-in macro will be returned.
Returns
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
LCS_NOT_STR »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lcimc.h"
. . .
LCT_STATUS Status;
lushort ArgIndex = 5;
lmbcs ValStr[LCI_MAX_COMMAND_LEN];
. . .
/* Get the fifth argument to a function as a string. */
Status = LciMcGetArgStr(Context, ArgIndex, LCI_MAX_COMMAND_LEN,
ValStr);
Definition
Retrieves the type of the argument passed to an add-in macro.
Note This function should only be called during the execution of a registered add-in macro keyword.
Format
#linclude "lcicomn.h"
#include "lcimc.h"
LCT_STATUS LCI_CALL LciMcGetArgType
(LCH_CONTEXT Context,
lushort ArgIndex,
lptr(lushort) lpValType)
Arguments
Context The context handle that was passed to the target C function.
ArgIndex The one-based position of an input argument.This value cannot be greater than the number of arguments passed to the macro in this invocation or less than 1. The maximum argument count is LCI_MAX_MC_ARG_COUNT.
lpValType A pointer to an lushort in which the data type of the argument passed to the add-in macro will be returned. Possible values are:
Constant Meaning
LCI_VAL_TYPE_ERR @ERR
LCI_VAL_TYPE_NA @NA
LCI_VAL_TYPE_NUM A number
LCI_VAL_TYPE_RANGE A range handle
LCI_VAL_TYPE_STR A string
LCI_VAL_TYPE_BLANK Macro keyword registered with argument type of LCF_MC_ARG_ALLOW_NUMBER and the argument to the macro references an empty cell.
Returns
LCS_SUCCESS »Page
LCS_INVALID_INDEX »Page
Example
#include "lcicomn.h"
#include "lcimc.h"
. . .
LCT_STATUS tatus;
lushort ArgIndex = 1;
lushort ValType;
. . .
/* Get the type of the first argument to the function. */
Status = LciMcGetArgType(Context, ArgIndex, &ValType);
Definition
Registers a C function to be called as a 1-2-3 macro keyword. Registration makes the function available for users.
Format
#include "lcicomn.h"
#include "lcimc.h"
LCT_STATUS LCI_CALL LciMcRegister
(LCH_CONTEXT Context,
lptr(lmbcs) lpKeywordName,
LCT_MC_CALL CFunctionPtr,
lulong RegisterArg,
lushort ArgCount,
lptr(lushort) lpArgTypeFlagsArray,
lulong OptionFlags,
lptr(LCH_REGISTRATION) lpRegistration)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpKeywordName The name of the macro keyword to be registered as it will appear in macros. Maximum length is 16 characters. Names that are longer are truncated.
CFunctionPtr A pointer to the C function to be called when an instance of lpKeywordName is evaluated in a macro.The calling sequence of the C function is:
LCT_STATUS LCI_CALL client_c_function
(LCH_CONTEXT Context,
lulong RegisterArg,
lushort ArgCount)
where Context is the same context that 1-2-3 passed to the C function that registered the macro, RegisterArg is the registration-specific argument, and ArgCount is the actual number of input arguments passed to the macro.
RegisterArg A data value specific to this registration that 1-2-3 will pass to the C function each time it is invoked as the target of the specified macro.This value can be a pointer to an arbitrary data structure. RegisterArg allows you to implement different macro keywords using the same C procedure.
ArgCount The minimum number of arguments up to 32 required to invoke the macro (LCI_MAX_MC_ARG_COUNT is defined to 32 in lcicomn.h). If OptionFlags includes LCF_MC_REGISTER_VARYING_ARGS, the macro will accept more than this number of arguments. Otherwise, it requires exactly this number of arguments. If ArgCount equals zero and OptionFlags includes LCF_MC_REGISTER_VARYING_ARGS, the macro will accept zero or more arguments of any type.
lpArgTypeFlagsArray A pointer to an array of ArgCount words of flags specifying the data types allowed for each input argument. Each element of the array can be any OR'd combination of the following flags. The zero'th element of the array corresponds to the first input argument. If OptionFlags includes LCF_MC_REGISTER_VARYING_ARGS, input arguments past the ArgCount'th argument have the same data type requirements as the ArgCount'th argument.
Constant Meaning
LCF_MC_ARG_ALLOW_MISSING Allow missing argument (",,")
LCF_MC_ARG_ALLOW_NUM Allow a number input
LCF_MC_ARG_ALLOW_RANGE Allow a range handle input
LCF_MC_ARG_ALLOW_STR Allow a string input
LCF_MC_ARG_ALLOW_ANY Allow a number, string, or range
OptionFlags Consists of the following flag or no flag:
Constant Meaning
LCF_MC_REGISTER_VARYING_ARGS One or more arguments can be missing in the macro invocation, delimited by commas.
lpRegistration A pointer to storage to which the registration handle that can be passed to LciMcUnregister will be returned.
Note A successfully registered macro can be unregistered by one of the following actions:
· a call to LciMcUnregister »Page with the handle returned at registration
· removal of the add-in caused by the user explicitly doing a remove
or clear
· terminating 1-2-3.
Note Although the lpArgTypeFlagsArray and the absence of the LCF_MC_REGISTER_VARYING_ARGS are ignored in 1-2-3 for Windows Release 1.0, they may be implemented in future versions of 1-2-3 for Windows. Code should be written to utilize these features or macros may stop working in future versions.
Returns
LCS_SUCCESS »Page
LCS_INVALID_NAME »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lcimc.h"
. . .
LCT_STATUS Status;
LCH_REGISTRATION Registration;
lushort ArgTypeFlagsArray[1];
. . .
ArgTypeFlagsArray[0] = LCF_MC_ARG_ALLOW_NUM;
/* Register function MyMacro as a macro keyword "mymacro".*/
/* The function takes only 1 argument, which must
be a number. */
. . .
Status = LciMcRegister(Context, "MyMacro", Mymacro, 1L, 1,
ArgTypeFlagsArray, 0L, &Registration);
Definition
Unregisters an add-in macro that was previously registered by LciMcRegister »Page . Unregistering the macro means that it cannot any longer be called by users.
Format
#include "lcicomn.h"
#include "lcimc.h"
LCT_STATUS LCI_CALL LciMcUnregister
(LCH_CONTEXT Context,
LCH_REGISTRATION Registration)
Arguments
Context The context handle that was passed to LciMcRegister.
Registration A registration handle previously returned by a call to LciMcRegister.
Returns
LCS_SUCCESS »Page
LCS_INVALID_REGISTRATION »Page
Example
#include "lcicomn.h"
#include "lcimc.h"
. . .
LCT_STATUS Status;
LCH_REGISTRATION Registration;
lushort ArgIndex = 2;
lslong ValNum;
lushort ArgTypeFlagsArray[1];
ArgTypeFlagsArray[0] = LCF_MC_ARG_ALLOW_NUM;
. . .
/* Register function MyMacro as a macro keyword "mymacro".*/
/* The function takes only 1 argument,which must be a number.*/
. . .
Status = LciMcRegister(Context,"MyMacro", mymacro, 1L, 1,
ArgTypeFlagsArray, 0L, &Registration);
. . .
Status = LciMcUnregister(Context, Registration);
The return code from a library function is always a status code. If the function retrieves some other value (such as an ADT type from a constructor), then that value is stored in a data item that is supplied by the caller and passed by reference to the function.
A return code of LCS_SUCCESS indicates that the function call completed successfully and that other values retrieved by the function are stored in the data items supplied by the caller. Any return code other than LCS_SUCCESS indicates that an exceptional condition occurred at runtime and other values may or may not be retrieved, depending on the function.
LCS_ALREADY_EXISTS »Page
LCS_ALREADY_GROUPED »Page
LCS_ALREADY_IN_MEMORY »Page
LCS_ALREADY_RESERVED »Page
LCS_CLOSE_ERROR »Page
LCS_CONVERSION_ERROR »Page
LCS_DIFFERENT_FILES »Page
LCS_DISK_ERROR »Page
LCS_END_OF_FILE »Page
LCS_ERR »Page
LCS_EVENT_MSG »Page
LCS_EVENT_MULTI_ERR »Page
LCS_EVENT_REPLACE »Page
LCS_FILE_IN_USE »Page
LCS_FILE_NOT_FOUND »Page
LCS_FILE_NOT_SEALED »Page
LCS_FILE_SEALED »Page
LCS_HIDDEN_COL »Page
LCS_HIDDEN_SHEET »Page
LCS_INCORRECT_EXTRACT_TYPE »Page
LCS_INCORRECT_WRITE_TYPE »Page
LCS_INIT_ERROR_NO_MSG »Page
LCS_INTERNAL_ERROR »Page
LCS_INVALID_ADDRESS »Page
LCS_INVALID_ARG_FLAGS »Page
LCS_INVALID_CELL »Page
LCS_INVALID_CLASS »Page
LCS_INVALID_COL »Page
LCS_INVALID_COUNT »Page
LCS_INVALID_EXTENSION »Page
LCS_INVALID_EXTRACT_TYPE »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_FORMAT »Page
LCS_INVALID_FORMULA »Page
LCS_INVALID_FROM_CELL »Page
LCS_INVALID_ID »Page
LCS_INVALID_INDEX »Page
LCS_INVALID_ITER_SPEC »Page
LCS_INVALID_LABEL_TYPE »Page
LCS_INVALID_MENU_TYPE »Page
LCS_INVALID_NAME »Page
LCS_INVALID_NOTE »Page
LCS_INVALID_NUM »Page
LCS_INVALID_ORDER »Page
LCS_INVALID_PANE »Page
LCS_INVALID_PASSWORD »Page
LCS_INVALID_PATH »Page
LCS_INVALID_PLACES »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_REGISTRATION »Page
LCS_INVALID_ROW »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_SIZE »Page
LCS_INVALID_STR »Page
LCS_INVALID_TO_CELL »Page
LCS_INVALID_TRANS_TYPE »Page
LCS_INVALID_TYPE »Page
LCS_INVALID_UNDO_MODE »Page
LCS_INVALID_USE »Page
LCS_INVALID_VALUE »Page
LCS_INVALID_WIDTH »Page
LCS_INVALID_WORKFILE »Page
LCS_INVALID_WRITE_TYPE »Page
LCS_KEY_BREAK »Page
LCS_MACRO_ERROR »Page
LCS_MANUAL_RESERVATION »Page
LCS_MISSING_ARG »Page
LCS_MISSING_DATA »Page
LCS_NA »Page
LCS_NO_UNDO_HANDLER »Page
LCS_NO_UNTITLED_CELL »Page
LCS_NO_VISIBLE_COLS »Page
LCS_NO_VISIBLE_SHEETS »Page
LCS_NOT_FOUND »Page
LCS_NOT_GROUPED »Page
LCS_NOT_IN_MEMORY »Page
LCS_NOT_NUM »Page
LCS_NOT_RANGE »Page
LCS_NOT_RESERVED »Page
LCS_NOT_STR »Page
LCS_NULL_HANDLE »Page
LCS_NUM_NOT_FOUND »Page
LCS_OFFSHEET_RANGE »Page
LCS_OPEN_ERROR »Page
LCS_OUT_OF_BOUNDS »Page
LCS_OUT_OF_ID_SPACE »Page
LCS_OUT_OF_MEMORY »Page
LCS_PASSWORD_REQUIRED »Page
LCS_PROTECTED_CELL »Page
LCS_PROTECTED_SHEET »Page
LCS_RANGE_FULL »Page
LCS_READ_ERROR »Page
LCS_RECORD_NOT_FOUND »Page
LCS_REQUEST_REFUSED »Page
LCS_RESERVATION_SEALED »Page
LCS_RESOURCE_LOAD_ERROR »Page
LCS_RG_ITER_TERMINATE »Page
LCS_RUNTIME_ERROR »Page
LCS_SIZE_IN_KBYTES »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_SUCCESS »Page
LCS_SYSTEM_ERROR »Page
LCS_TOO_FEW_SHEETS »Page
LCS_TOO_MANY_SHEETS »Page
LCS_UNABLE_TO_COMPLY »Page
LCS_UNABLE_TO_RESERVE »Page
LCS_UNDO_DISABLED »Page
LCS_UNKNOWN_ERROR »Page
LCS_VAL_TOO_BIG »Page
LCS_WINDOWS_ERROR »Page
LCS_WRITE_ERROR »Page
$664 LCS_ALREADY_EXISTS
There is already a worksheet file on disk with the name you specified in LciWfNew »Page . This error is also returned in LciWfSave »Page and LciWfExtract »Page if LCI_WRITE_NEW was specified.
Note Do not attempt to return status from AdnInitialize, AdnMain, AdnTerminate, or any macro or @function.
$665 LCS_ALREADY_GROUPED
The worksheet file specified in LciWfSetGroupFlag »Page is already in GROUP mode.
$666 LCS_ALREADY_IN_MEMORY
The worksheet file you specified in LciWfRetrieve »Page or LciWfOpen »Page refers to a file that is already loaded into memory.
$667 LCS_ALREADY_RESERVED
The worksheet file you specified in LciWfSetReserveFlag »Page to reserve is already reserved.
$668 LCS_CLOSE_ERROR
1-2-3 cannot close the 1-2-3 for Windows Configuration File (123R4.INI); or, one of the following situations has occurred: LciMbDestroy »Page was unable to deallocate the specified object handle; unload_lmbsrv »Page cannot unload the module; the driver has attempted to unload more than once.
$669 LCS_CONVERSION_ERROR
Returned from LciAtChar »Page to indicate that although a valid LMBCS code was input, it is not assigned to a character in this implementation of 1-2-3.
$670 LCS_DIFFERENT_FILES
You are attempting to move the data in a cell or range to a cell or range in another file. You cannot move data between files with LciClMove »Page or LciRgMove »Page . Instead, copy a cell or range and then delete the data in the source cell or range.
$671 LCS_DISK_ERROR
In most cases, 1-2-3 encountered a disk error while trying to get access to or to save a worksheet file on disk using LciWf... functions.
$672 LCS_END_OF_FILE
Returned from LciMbBrowseCodepage »Page when no more codepages are available.
$673 LCS_ERR
This is returned for any LciAtxxx functions whose result is @ERR. LciClGetValNum »Page , LciClGetValStr »Page , and LciClGetContentsNum »Page also return LCS_ERR if the call contains the value @ERR.
$674 LCS_EVENT_MSG
Only one prior handler returned an error, and the error was a custom error string. (A custom error string is one that you write to address an error that the handler may encounter.)
$675 LCS_EVENT_MULTI_ERR
More than one error was returned by some combination of event handlers and the event, and none of the errors was LCS_OUT_OF_MEMORY.
$676 LCS_EVENT_REPLACE
A prior before handler has signalled that it wishes to replace the event. If the current handler is an after handler, the replacement has already occurred and was otherwise successful. If the current handler is a before handler, it will be unable to replace the operation itself, but the replacement will occur after all before handlers have been called. Actual errors reported by the replacer or other before handlers supercede this status. If you want to retrieve the error message text associated with the returned error code, use the LciUtErrorText »Page utility library function.
$677 LCS_FILE_IN_USE
The worksheet file you specified in LciWfErase »Page is currently in use by another process or user.
$678 LCS_FILE_NOT_FOUND
The worksheet file you specified in LciWf... file access functions is not on the disk.
$679 LCS_FILE_NOT_SEALED
The specified worksheet file in LciWfSetSealType »Page was not sealed and LCI_SEAL_NONE was specified (that is, to unseal the file and reservation setting).
$680 LCS_FILE_SEALED
The specified worksheet file is sealed and cannot be altered. The function will not complete successfully until the file has been unsealed.
$681 LCS_HIDDEN_COL
This code is returned when a hidden column is specified. In LciClFormatRow »Page , the starting value you specified refers to a cell in a hidden column. In LciClGetColWidth »Page , the column you specified is hidden. In LciWsSetCellPointerCoords »Page and LciWsSetCellTopLeftCoords »Page , the column reference refers to a hidden column.
$682 LCS_HIDDEN_SHEET
Returned for functions that disallow operations on a hidden worksheet: LciClSetShadowFlag »Page , LciRgSetShadowFlag »Page , LciShGetDefaultColWidth »Page , LciShSetDefaultColWidth »Page , LciWsSetCellPointerCoords »Page , LciWsSetCellTopLeftCoords »Page , and LciWsSetCurrSheet »Page .
$683 LCS_INCORRECT_EXTRACT_TYPE
An invalid extract type in LciWfExtract »Page was specified. You must use LCI_EXTRACT_FORMULAS or LCI_EXTRACT_VALUES.
$684 LCS_INCORRECT_WRITE_TYPE
The save type you specified in LciWfExtract »Page is invalid. You must use one of the following three types: LCI_WRITE_NEW, LCI_WRITE_REPLACE, LCI_WRITE_BACKUP.
$685 LCS_INIT_ERROR_NO_MSG
This error code should be returned by add-ins from AdnPreinit or AdnInitialize. The runtime will interpret this code to mean that an error has occurred in the add-in and will unload the add-in (and unregister any events, @functions, or macro keywords it may have registered for), but will not post any message to the user. This code is not returned by any Lotus C Interface functions.
$686 LCS_INTERNAL_ERROR
An unknown, internal error occurred. This should never occur; however, if it does, you should call Lotus Development Corporation technical support for assistance.
$687 LCS_INVALID_ADDRESS
The string you specified in LciClConstructAddr »Page or LciRgConstructAddr »Page is not a valid 1-2-3 cell address, range address, or range name, or it references a file not in memory. For the latter, a range name, not coordinates, must be specified..
$688 LCS_INVALID_ARG_FLAGS
While trying to register an event handler, the options flag was determined to be invalid. In LciEvRegister »Page , an invalid event ID or timing option was specified. For event data callback functions, you attempted to get data that did not exist for the event.
$689 LCS_INVALID_CELL
A cell reference in a cell object is no longer valid either because the row or column has been deleted or because the file is no longer in memory.
$690 LCS_INVALID_CLASS
The type of toolclass provided to LciTiConstructClass »Page or LciMnConstructNew »Page must be LCI_TOOLCLASS_SHEET, LCI_TOOLCLASS_GRAPH, or LCI_TOOLCLASS_CUSTOM; or, the class name supplied for a custom class is invalid.
$691 LCS_INVALID_COL
This code is returned if the column number you specified is invalid. Column numbers must be between 1 and 256, inclusive. The following functions return this status: LciClConstructCoords »Page , LciClSetCoords »Page , LciClSetCol »Page , LciRgConstructCoords »Page , LciShDeleteCols »Page , LciShInsertCols »Page , LciWsSetCellPointerCoords »Page , and LciWsSetCellTopLeftCoords »Page .
$692 LCS_INVALID_COUNT
The recalc iteration count specified in LciWfSetCalcIterCount »Page is not in the range 1-50. The number of sheets specified to insert in LciWfInsertSheet »Page or to delete in LciWfDeleteSheets »Page is not in the range 1-255.
$693 LCS_INVALID_EXTENSION
The extension you specified in LciWsSetListExt »Page and LciWsSetSaveExt »Page has more than three characters or contains invalid characters.
$694 LCS_INVALID_EXTRACT_TYPE
See LCS_INCORRECT_EXTRACT_TYPE »Page , which is supported in this release. This may, however, be supported in future releases.
$695 LCS_INVALID_FILENAME
The worksheet filename you specified is invalid. The filename is invalid if the function requires a file to be in memory, if the file cannot be found, or if the filename contains invalid characters.
$696 LCS_INVALID_FORMAT
The format you specified is not a valid format type for LciClSetFormat »Page , LciRgSetFormat »Page , or LciShSetFormat »Page .
$697 LCS_INVALID_FORMULA
The formula you specified in LciClSetContentsStr »Page is not valid.
$698 LCS_INVALID_FROM_CELL
The cell you specified as the cell from which you want to copy or move data in LciClCopy »Page or LciClMove »Page is not a valid cell reference either because the worksheet is no longer in memory or the row or column has been deleted.
$699 LCS_INVALID_ID
You did not specify a valid menu item ID for LciMn... calls.
$700 LCS_INVALID_INDEX
Generally returned when a positional value specified is incorrect. For the LciAfGetArg... functions (for example, LciAfGetArgNum »Page ) and LciMcGetArgXXX functions (for example LciMcGetArgNum »Page ), this code is returned when the argument number to get is incorrect. For LciMnGetSubMenu »Page , an incorrect menu position was specified. For LciClGetColor »Page , LciClSetColor »Page , and LciRgSetColor »Page , an incorrect enumerated type was specified.
$701 LCS_INVALID_ITER_SPEC
You did not specify all three dimensions for the iteration function in LciRgIterCells »Page .
$702 LCS_INVALID_LABEL_TYPE
You specified an invalid label type for LciClSetLabelType »Page , LciShSetLabelType »Page , or LciRgSetLabelType »Page .
$703 LCS_INVALID_MENU_TYPE
The menu object specified in LciTcSetMenu »Page was not constructed with a menu type of LCI_MENUTYPE_MENUBAR in LciMnConstructNew »Page .
$704 LCS_INVALID_NAME
Attempting to create, delete, or undefine a name failed. Failure occurs in the following instances. In LciRgCreateName »Page , the specified range name (begins with a filename) is either longer than LCI_MAX_RGNAME_LEN characters or is an empty string. In LciRgDeleteName »Page and LciRgUndefineName »Page , one of the following occured: the range name does not exist, exists in more than one worksheet file, refers to a worksheet that is not in memory, or is an empty string. In LciAfRegister »Page and LciMcRegister »Page , an @function or macro keyword with the same name is already registered, or the function name is LNULL. In LciTcConstructName »Page , the specified toolclass is invalid or the classname specified is invalid.
$705 LCS_INVALID_NOTE
The specified note in LciRgSetNote »Page is too long. The range name note can be a maximum of LCI_MAX_NOTE_LEN characters, including the null-terminating byte.
$706 LCS_INVALID_NUM
An invalid numerical value was supplied. Failure occurs during: LciRgSetRowHeight »Page or LciClSetRowHeight »Page if the specified height in points is not in the range LCI_MIN_ROW_HEIGHT to LCI_MAX_ROW_HEIGHT; LciClFormatRow »Page if number of columns specified is zero or greater than the number of columns from the specified cell to the rightmost edge of the sheet, or the resulting string is > LCI_MAX_ROW_WIDTH; LciUtIntToLetter »Page if the specified integer to be converted to a worksheet or column letter is not in the range 1 to 256; LciUtBeep »Page where the frequency supplied must be between LCI_MIN_BEEP_FREQ and LCI_MAX_BEEP_FREQ inclusive; LciAfRegister »Page if the number of arguments specified was greater than LCI_MAX_AF_ARG_COUNT; LciShSetFormat »Page if the number of decimal places specified was greater than LCI_MAX_PLACES; LciWsSetCalcIterCount »Page if the number of iterations is not between between 1 and 50; LciWsSetZoom »Page where the zoom amount must be between 25 and 400 inclusive; LciWsGetFileName »Page where the file count specified must be between 1 and the number of files currently in memory.
$707 LCS_INVALID_ORDER
You specified a recalc order type in LciRgCalc »Page other than LCI_CALC_ORDER_COLWISE or LCI_CALC_ORDER_ROWWISE.
$708 LCS_INVALID_PANE
An invalid pane number was specified. Valid pane numbers are as follows: 1 when Window Split Type is set to Clear; 1 or 2 when the window is split horizontally or vertically; and 1, 2, or 3 when the window is split using perspective mode.
$709 LCS_INVALID_PASSWORD
The password you specified to access the workfile in LciWf... functions is incorrect.
$710 LCS_INVALID_PATH
The path you specified in LciWsSetDefaultDir »Page is not a valid path.
$711 LCS_INVALID_PLACES
You requested that 1-2-3 display an invalid number of decimal places in LciClSetFormat »Page , LciRgSetFormat »Page , or LciUtFormatValFloat »Page . The number of decimal places must be in the range 0 to LCI_MAX_PLACES.
$712 LCS_INVALID_RANGE
The range reference in the range object is no longer valid usually because the containing workfile was deleted from memory, or an LNULL range object handle was passed to the function. Some functions return this code for additional reasons as well: LciRgGetNote »Page and LciRgSetNote »Page because the referenced range is not a named range; LciWfCombine »Page and LciWfExtract »Page because the referenced range name is not in the specified file.
$713 LCS_INVALID_REGISTRATION
This is returned from LciAfUnregister »Page or LciMcUnregister »Page if the @function or macro keyword has already been unregistered or if you passed an invalid registration handle.
$714 LCS_INVALID_ROW
The row number you specified is invalid. Row numbers must be in the range 1 - 8192. The following functions return this status: LciClConstructCoords »Page , LciClSetCoords »Page , LciClSetRow »Page , LciRgConstructCoords »Page , LciShDeleteRows »Page , LciShInsertRows »Page , LciWsSetCellPointerCoords »Page , and LciWsSetCellTopLeftCoords »Page .
$715 LCS_INVALID_SHEET
In most cases, this return code is returned if the worksheet number you specified is invalid or if the worksheet reference in a sheet object is no longer valid. Worksheet numbers must be between 1 and 256, inclusive, and the worksheet must exist in memory; or, the worksheet number you specified is larger than the number of worksheets in the current worksheet file.
$716 LCS_INVALID_SIZE
The number of the range name to retrieve in LciWfGetRangeName »Page must be greater than zero.
$717 LCS_INVALID_STR
Valid string characters must be in ASCII and valid worksheet letters must be between A and IV to avoid this return code. In LciUtIntToLetter »Page and LciUtLetterToInt »Page , you must use a string that corresponds to a valid worksheet or column letter (between A and IV, inclusive).
$718 LCS_INVALID_TO_CELL
The cell you specified as the cell to which you want to copy or move data in LciClCopy »Page or LciClMove »Page is not a valid cell reference either because the worksheet file is no longer in memory or the row or column has been deleted.
$719 LCS_INVALID_TRANS_TYPE
You specified an invalid transpose type in LciRgTranspose »Page . You must select one of the following three types: LCI_TRANS_ROWS_TO_COLS, LCI_TRANS_SHEETS_TO_ROWS, or LCI_TRANS_COLS_TO_SHEETS.
$720 LCS_INVALID_TYPE
You specified a type that does not exist or that cannot be used in LciAtInfoNum »Page , LciAtInfoStr »Page , LciClSetBorders »Page , LciClSetUnderline »Page , LciClSetPattern »Page , LciRgSetBorders »Page , LciRgSetUnderline »Page , LciRgSetPattern »Page , LciWsSetColor »Page , or LciWsSetFrameType »Page .
$721 LCS_INVALID_UNDO_MODE
You specified an invalid undo mode type in LciWsSetUndoMode »Page . The undo mode type can be one of the following: LCI_UNDO_OFF, LCI_UNDO_OFF_UNTIL_READY, or LCI_UNDO_ON.
$722 LCS_INVALID_USE
You cannot use this function in its current context. It is returned in the following circumstances: LciXXRunMacro was invoked during a file retrieve; LciUtSystem »Page cannot be called during a recalc; the sheet, workfile, and workspace LciSet... functions cannot be used during recalc; the LciWf... operations cannot be performed during a recalc or file retrieve; LciUtDisplayError »Page cannot be called during product startup.
$723 LCS_INVALID_VALUE
A macro in a cell does not contain a valid value. This is returned from LciUtRunMacro »Page , LciUtRunMacroArray »Page , LciClRunMacro »Page , and LciRgRunMacro »Page .
$724 LCS_INVALID_WIDTH
A column width was specified that did not fall within the range of LCI_MIN_COL_WIDTH and LCI_MAX_COL_WIDTH (which are defined in terms of number of characters) in the following functions: LciClSetColWidth »Page , LciRgSetColWidth »Page , LciShSetDefaultColWidth »Page , LciUtFormatValInteger »Page , LciUtFormatValFloat »Page , and LciUtFormatValStr »Page .
$725 LCS_INVALID_WORKFILE
The file you specified is not a valid 1-2-3 worksheet file in LciWfRetrieve »Page or LciWfCombine »Page .
$726 LCS_INVALID_WRITE_TYPE
See LCS_INCORRECT_WRITE_TYPE »Page , which is supported in this release. LCS_INVALID_WRITE_TYPE may, however, be supported in future releases.
$727 LCS_KEY_BREAK
This return code occurs when the 1-2-3 user presses CTRL-BREAK when the add-in is anticipating a different keyboard response. This code is returned under the following conditions: for LciUtRunMacro »Page , LciUtRunMacroArray »Page , LciClRunMacro »Page , and LciRgRunMacro »Page , 1-2-3 stopped the macro because the user pressed CTRL-BREAK while the macro was running. It is also returned from the LciWfSave »Page and LciWfExtract »Page functions because the user pressed CTRL-BREAK while the file was being saved with a password.
$728 LCS_MACRO_ERROR
1-2-3 encountered an error when it tried to run the macro in LciClRunMacro »Page , LciRgRunMacro »Page , LciUtRunMacro »Page , and LciUtRunMacroArray »Page .
$729 LCS_MANUAL_RESERVATION
LCI_RETRIEVE_RESERVE was specified in LciWfRetrieve »Page or LCI_OPEN_RESERVE in LciWfOpen »Page , and the workfile was retrieved or opened without a reservation. You need to use LciWfSetReserveFlag »Page to get a reservation, or you can use LciWfSetReserveType »Page to make reservation automatic when the file is next retrieved or opened. In both cases, the retrieve or open is completed and the desired workfile is in memory.
The specified macro contained fewer than the required number of arguments. Returned from LciUtRunMacro »Page , LciUtRunMacroArray »Page , LciClRunMacro »Page , or LciRgRunMacro »Page .
$730 LCS_MISSING_DATA
The @function you registered with LciAfRegister »Page has the options flag set to zero.
$731 LCS_NA
This is returned if the result of an Lci @function (LciAt...) is NA; only 1-2-3 can assign NA to a cell. This is also returned from LciClGetValNum »Page , LciClGetContentsNum »Page , or LciClGetValStr »Page if the cell contains the value NA.
$732 LCS_NO_UNDO_HANDLER
The workspace object specified in LciWsWriteUndoRecord »Page does not have an Undo handler associated with it.
$733 LCS_NO_UNTITLED_CELL
Returned from LciShSetTitleColCount »Page or LciShSetTitleRowCount »Page if the titles would overflow the window. You can only set titles within the displayed window size.
$734 LCS_NO_VISIBLE_COLS
The range you specified in LciRgSetHiddenFlag »Page spans all 256 columns in a worksheet, and you cannot hide all the columns in a worksheet.
$735 LCS_NO_VISIBLE_SHEETS
You have attempted to hide the last visible worksheet in a file as specified in LciShSetHiddenFlag »Page .
$736 LCS_NOT_FOUND
Returned from LciTiConstructClass »Page when the program attempted to create a new instance of a Graph toolclass or when the program attempted to construct a toolclass when there was no previously active document.
$737 LCS_NOT_GROUPED
The workfile specified in LciWfSetGroupFlag »Page was not in group mode and you requested to turn group mode off.
$738 LCS_NOT_IN_MEMORY
The specified worksheet file is not in memory and, therefore, the operation cannot be performed.
$739 LCS_NOT_NUM
(1) You did not specify a valid number as the argument for this function, or the cell contents, @function, or (2) the macro keyword function argument you are trying to retrieve as a number is not a numeric argument.
$740 LCS_NOT_RANGE
The argument for the @function or Macro keyword you are trying to retrieve as a range using one of LciAfGetArgRange »Page , LciMcGetArgRange »Page , or LciAfForceArgRange »Page is not a range type.
$741 LCS_NOT_RESERVED
You do not have the reservation for the worksheet file you specified in LciWfSave »Page or in LciWfSetReserveFlag »Page (and you requested that the reservation be released).
$742 LCS_NOT_STR
The macro keyword or @function argument you are trying to retrieve as a string in LciAfGetArgStr »Page or LciMcGetArgStr »Page is not a string type.
$743 LCS_NULL_HANDLE
LciEvSetArgRange »Page , LciEvSetArgStr »Page , LciClRunMacro »Page , or LciRgRunMacro »Page has received an object handle or buffer that is LNULL. LciWfIterAddinRecords »Page was passed an iterator callback function that is LNULL, the record passed to LciWfInsertAddinRecord »Page , or LciWfReplaceAddinRecord »Page was LNULL.
$744 LCS_NUM_NOT_FOUND
The 1-2-3 error code value does not have a corresponding error message.
$745 LCS_OFFSHEET_RANGE
This is returned if the specified range refers to a range that is not in memory (or is in an external table); that is, the range is part of a workfile that is not in memory.
$746 LCS_OPEN_ERROR
LciWsUpdateSettings »Page cannot open the file 123.CNF. In LciMbBrowseConstruct »Page you failed to allocate a handle, or the program cannot find the file LMBSRV.INI. LciMbConstruct »Page failed to open a translation module for the input codepage, it could not locate LMBSRVW.DLL or LMBSRV.INI, or no such codepage resource is available. In load_lmbsrv »Page the module cannot be loaded, you attempted to load the driver more than once, or one of the lmbcs module functions was passed LNULL for Context, handle, or environment block handle.
$747 LCS_OUT_OF_BOUNDS
In LciAtCharLongToStr »Page and LciAtCharStrToLong »Page this indicates an invalid LMBCS code. In LciRgCopy »Page , LciRgCopyVals »Page , LciRgMove »Page , LciRgTranspose »Page , LciShDeleteCols »Page , LciShDeleteRows »Page , LciShInsertCols »Page , or LciShInsertRows »Page , this indicates that the function could not be performed because the result would overflow the worksheet. Lastly, this is returned from LciWsSetPaneType »Page if the cell pointer is not in the correct location to change the window type.
$748 LCS_OUT_OF_ID_SPACE
This is returned by LciTcGetMenuIds »Page when 1-2-3 is unable to allocate a unique menu id.
$749 LCS_OUT_OF_MEMORY
1-2-3 cannot allocate enough memory to perform the specified operation. For LciLdSetStackInfo »Page , the out-of-memory condition occurs if the user requests the 1-2-3 stack and the amount specified is not available, the user specifies a private stack of size (0) and there are fewer than 100 bytes specified, or the stack size has already been exceeded. When this is returned from an Event Handler call, it means one or more prior handlers and/or the event returned an LCS_OUT_OF_MEMORY error. LCS_OUT_OF_MEMORY supersedes all other errors returned by handlers.
$750 LCS_PASSWORD_REQUIRED
A password must be specified in order to access the workfile in LciWfRetrieve »Page , LciWfOpen »Page , or LciWfCombine »Page .
$751 LCS_PROTECTED_CELL
The cell you are trying to change has the protected flag turned on and it must be unprotected in order to proceed. This is returned from LciCl... and LciRg... functions, which would affect the contents of a cell.
$752 LCS_PROTECTED_SHEET
The sheet specified has the protected flag turned on and it must be unprotected in order to proceed. This status is returned from LciShDeleteCols »Page , LciShDeleteRows »Page , LciShInsertCols »Page , LciShInsertRows »Page , and LciWfDeleteSheets »Page .
$753 LCS_RANGE_FULL
One or more of the cells that the LciRgJustify »Page function would use to contain realigned data already contain data, or the realigned labels extend beyond the range you specified.
$754 LCS_READ_ERROR
1-2-3 encountered a disk error while trying to read the specified file in LciWfImport »Page .
$755 LCS_RECORD_NOT_FOUND
The current record is null because you are at the start of an empty list or because you are past the last record in the list in LciWfDeleteAddinRecord »Page , LciWfInsertAddinRecord »Page , or LciWfReplaceAddinRecord »Page .
$756 LCS_REQUEST_REFUSED
Returned by LciWfIterAddinRecords »Page if iteration is already in progress. Returned by LciWfDeleteAddinRecord »Page , LciWfInsertAddinRecord »Page , or LciWfReplaceAddinRecord »Page if iteration is NOT in progress or if the specified record length is too small.
$757 LCS_RESERVATION_SEALED
The worksheet file you specified in LciWfSetSealType »Page has its reservation status sealed. You cannot change the reservation status without first unsealing the file.
$758 LCS_RESOURCE_LOAD_ERROR
The program has encountered an error loading the resource file. Your resource file may be corrupted or may not be in a valid 1-2-3 for Windows format. For LciLdLoadCompatLib »Page , an error occurred loading L1WLPX.DLL. Check to be sure it is in the 1-2-3 for Windows product directory.
$759 LCS_RG_ITER_TERMINATE
The iterator function supplied in LciRgIterCells »Page returned LFALSE, or an error occurred while iterating through the range.
$760 LCS_RUNTIME_ERROR
This is returned by LciEvGetArgInt »Page when it is unable to retrieve the specified argument because it is an invalid resource.
$761 LCS_SIZE_IN_KBYTES
If the amount of memory available on your system exceeds 2,147,483,647 bytes, the lulong value stored by the LciWsGetMemAvail »Page function is in kilobytes. LCS_SIZE_IN_BYTES rounds down the memory size to the nearest increment of 1024.
$762 LCS_STACK_OVERFLOW
The stack has outgrown its allocated space. Execution of the function should stop because further growth of the stack will overwrite program data.
$763 LCS_STR_TOO_LONG
For set functions that accept a string, the specified string or string length is too long for the function. Examples of this include the string specified in LciUtSystem »Page (must not exceed LCI_MAX_COMMAND_LEN), LciShSetZeroStr »Page (must not exceed LCI_MAX_ZERO_STR_LEN), and LciWsSetIntlCurrency »Page (must not exceed LCI_MAX_CURRSIGN_LEN). For get functions that return a string, the return string is too long to fit the buffer supplied by the calling function. A truncated string is returned that is as large as the size of the buffer allocated by the caller. Examples include LciClGetAddr »Page , LciTiGetClass »Page , and LciRgGetCoords »Page .
$764 LCS_SUCCESS
A return code of LCS_SUCCESS indicates that the function call completed successfully and that other values retrieved by the function are stored in the data items supplied by the caller. Any return code other than LCS_SUCCESS indicates that an exceptional condition has arisen at run-time. When LCS_SUCCESS is returned from an Event Handler, it means that all prior handlers and the event executed successfully. »Page
$765 LCS_SYSTEM_ERROR
The operating system encountered an error when it executed the specified command because you did not specify a command to be executed for LciUtSystem »Page , or the operating system returned an error for the specified command.
$766 LCS_TOO_FEW_SHEETS
You attempted to delete more worksheets than are active in LciWfDeleteSheets »Page . For instance, if there are ten active worksheets in a file and you specify five worksheets to be deleted, starting at the seventh worksheet, this code is returned. It is also returned if you attempt to delete all the active worksheets in a file. There must be at least one active worksheet left in the file.
$767 LCS_TOO_MANY_SHEETS
The number of worksheets you specified in LciWfInsertSheet »Page , plus the number of existing worksheets exceeds the maximum number of worksheets per file.
$768 LCS_UNABLE_TO_COMPLY
An error occurred in LciEvGetArgInt »Page when trying to convert a resource to an integer.
$769 LCS_UNABLE_TO_RESERVE
You cannot reserve the worksheet file you requested in LciWfSetReserveFlag »Page , LciWfRetrieve »Page , or LciWfOpen »Page , either because someone else currently owns the reservation or because the reservation status for this file is sealed.
$770 LCS_UNDO_DISABLED
You are trying to copy data from the Undo Buffer (see LciWsUndoCommand »Page ), clear the Undo Buffer (see LciWsClearUndo »Page ), or write an Undo record (see LciWsWriteUndoRecord »Page ) when Undo is not enabled in 1-2-3 for Windows.
$771 LCS_UNKNOWN_ERROR
The function failed for an unknown reason. Please report this error to Lotus Customer Support.
$772 LCS_VAL_TOO_BIG
You tried to pop an lfloat8 (double) floating-point number, an lulong 4-byte signed integer, or an lushort 2-byte signed integer off the math stack, and the number is too large or too small in magnitude to fit in the range.
$773 LCS_WINDOWS_ERROR
The program has encountered an error in Windows. This error is not curently returned by any Lci functions but may be used by your add-in.
$774 LCS_WRITE_ERROR
1-2-3 encountered a disk error while trying to save the specified worksheet file. The disk you are writing to may be write-protected or the file attribute may be read-only.
The 1-2-3 Release 4 for Windows (Darwin) Add-in Development Kit Team
Ruth Anthony, Marty Casey, Steve Chin, Ben Cole, Maida Eisenberg, David Folk, Peter Rodman, David Rosenbaum, Chris Smith, Dick Suitor, Leeann Sack, Jonathan Spencer, Francis Welch, and Alice (XU) Lei.
Thank you Pat, Bob and Paul, Steve, Bennett, Willie, Tony, and Len.
The saga continues . . . from Darwin, Australia to Walden Pond . . . Engage!!!
You use the sheet functions to represent 1-2-3 worksheets in your add-in. A data object that has type sheet refers to a specific 1-2-3 worksheet. The sheet group contains the following functions:
Function Meaning
LciShConstructCoords »Page Constructs an object handle to a sheet specified by sheet number and workfile.
LciShConstructCurr »Page Constructs an object handle to the current sheet.
LciShDeleteCols »Page Deletes a specified number of columns from the sheet, beginning with a specified column.
LciShDeleteRows »Page Deletes a specified number of rows from the sheet, beginning with a specified row.
LciShDestroy »Page Releases a sheet object handle and frees all associated memory.
LciShGetAddr »Page Retrieves the fully qualified address string of the specified worksheet, for example <<C:\DAT\XYZ.WK3>>B.
LciShGetContext »Page Retrieves the context handle corresponding to a sheet object.
LciShGetDefaultColWidth »Page Retrieves the default width for columns in a sheet as viewed by a specified pane in all windows.
LciShGetFileName »Page Retrieves the full pathname of the workfile containing a specified sheet.
LciShGetFormat »Page Retrieves the global format and the number of decimal places for cells in a specified sheet.
LciShGetHiddenFlag »Page Retrieves a value that indicates whether or not the sheet is hidden.
LciShGetLabelType »Page Retrieves the type of the default label alignment settings for the specified sheet.
LciShGetLastCellAddr »Page Retrieves the address string of the last cell in the active area of the worksheet.
LciShGetLastCellCoords »Page Retrieves the filename and coordinates of the last cell in the active area of the worksheet.
LciShGetName »Page Gets the name of the sheet.
LciShGetNum »Page Retrieves the one-based number of a specified sheet in its containing workfile.
LciShGetProtectFlag »Page Retrieves a value that indicates whether or not the cells in the specified sheet are protected.
LciShGetTitleColCount »Page Retrieves the number of title columns frozen along the left edge of a specified sheet.
LciShGetTitleRowCount »Page Retrieves the number of title rows frozen along the top edge of a specified sheet.
LciShGetZeroStr »Page Retrieves the string that 1-2-3 displays if the value of a cell is zero.
LciShInsertCols »Page Inserts a specified number of columns in the sheet before a specified column.
LciShInsertRows »Page Inserts a specified a number of rows in the sheet before a specified row.
LciShSetDefaultColWidth »Page Sets the default width for columns in a sheet as viewed by a specified pane in all windows.
LciShSetFormat »Page Sets the global format including number of decimal places for cells in a specified sheet.
LciShSetHiddenFlag »Page Specifies whether a worksheet in the current file is hidden.
LciShSetLabelType »Page Sets the default label alignment for a specified sheet.
LciShSetName »Page Sets the name of a sheet.
LciShSetProtectFlag »Page Sets worksheet global protection on or off.
LciShSetTitleColCount »Page Sets the number of columns frozen along the left edge of a specified sheet.
LciShSetTitleRowCount »Page Sets the number of rows frozen along the top edge of a specified sheet.
LciShSetZeroStr »Page Sets the string that 1-2-3 displays if the value of a cell is zero.
Definition
Constructs an object handle to a sheet specified by a sheet number within a specified workfile.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShConstructCoords
(LCH_CONTEXT Context,
lptr(lmbcs) lpFileName,
lushort SheetNum,
lptr(LCH_SHEET) lpSheet)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpFileName The workfile name. It must not be longer than LCI_MAX_FILENAME_LEN. It can be LCI_UNTITLED_WORKFILE to specify the no-name workfile or LCI_CURRENT_WORKFILE to specify the current workfile.
SheetNum The one-based number of a sheet within the workfile.
lpSheet A pointer to storage to which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_SHEET »Page
LCS_NOT_IN_MEMORY »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
lptr(lmbcs) WfileName = "myfile.wk3"
. . .
/* Construct a handle to sheet B in myfile.wk3. */
Status = LciShConstructCoords(Context,WfileName,2,&Sheet);
. . .
Status = LciShDestroy(&Sheet);
Definition
Constructs an object handle to the current sheet.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShConstructCurr
(LCH_CONTEXT Context,
lptr(LCH_SHEET) lpSheet)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpSheet A pointer to storage to which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShDestroy(&Sheet);
Definition
Deletes a specified number of columns from the sheet, beginning with a specified column.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShDeleteCols
(LCH_SHEET Sheet,
lushort FirstColNum,
lushort ColCount)
Arguments
Sheet The handle of an existing sheet object.
FirstColNum The number of the first column to delete.
ColCount The number of columns to delete.
Returns
LCS_SUCCESS »Page
LCS_INVALID_COL »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_OUT_OF_BOUNDS »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_SHEET »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
/* Delete columns C through G from the Sheet. */
Status = LciShDeleteCols(Sheet,3,5);
. . .
Status = LciShDestroy(&Sheet);
Definition
Deletes a specified number of rows from the sheet, beginning with a specified row.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShDeleteRows
(LCH_SHEET Sheet,
lushort FirstRowNum,
lushort RowCount)
Arguments
Sheet The handle of an existing sheet object.
FirstRowNum The number of the first row to delete.
RowCount The number of rows to delete.
Returns
LCS_SUCCESS »Page
LCS_INVALID_ROW »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_OUT_OF_BOUNDS »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_SHEET »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
/* Delete rows 7 through 12 inclusive. */
Status = LciShDeleteRows(Sheet,7,6);
. . .
Status = LciShDestroy(&Sheet);
Definition
Releases a sheet object handle and frees all associated memory.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShDestroy
(lptr(LCH_SHEET) lpSheet)
Arguments
lpSheet A pointer to a sheet object handle. lpSheet will be set to LNULL when the sheet handle is released.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves the fully qualified address string of the specified worksheet, for example, <<C:\DAT\XYZ.WK3>>b. Returns LCS_INVALID_SHEET if the sheet is invalid (that is, it has been deleted).
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetAddr
(LCH_SHEET Sheet,
lushort BufLen,
lptr(lmbcs) lpSheetAddr)
Arguments
Sheet The handle of an existing sheet object.
BufLen The number of bytes available in the buffer pointed to by lpSheetAddr, including room for a null-terminating byte. BufLen need not be greater than LCI_MAX_FILENAME_LEN + LCI_MAX_WSNAME_LEN.
lpSheetAddr A pointer to a lmbcs string in which to return the address string.
Returns
LCS_SUCCESS »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
#define SNAME_LEN LCI_MAX_FILENAME_LEN+LCI_MAX_WSNAME_LEN
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
lmbcs Address[SNAME_LEN];
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetAddr(Sheet,SNAME_LEN,Address);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves the context handle with which the specified sheet object was constructed.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetContext
(LCH_SHEET Sheet,
lptr(LCH_CONTEXT) lpContext)
Arguments
Sheet The handle of an existing sheet object.
lpContext A pointer to storage to which to return the context handle.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCH_CONTEXT ShContext;
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetContext(Sheet,&ShContext);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves the default width for columns in a sheet as viewed by a specified pane in all windows. Column width is specified in number of characters; ranges from LCI_MIN_COL_WIDTH to LCI_MAX_COL_WIDTH. The default column width can be overridden per column by calling LciClSetColWidth »Page or LciRgSetColWidth »Page .
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetDefaultColWidth
(LCH_SHEET Sheet,
lushort PaneNum,
lptr(lushort) lpDefaultColWidth)
Arguments
Sheet The handle of an existing sheet object.
PaneNum The one-based number of a pane within each window, or LCI_CURRENT_PANE to specify the current pane. 1(one) refers to the top, left, or only pane.
lpDefaultColWidth A pointer to an lushort in which to return the column width.
Returns
LCS_SUCCESS »Page
LCS_HIDDEN_SHEET »Page
LCS_INVALID_PANE »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
lushort DefColWidth;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetDefaultColWidth(Sheet,LCI_CURRENT_PANE,
&DefColWidth);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves the full pathname of the workfile containing the specified sheet.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetFileName
(LCH_SHEET Sheet,
lushort BufLen,
lptr(lmbcs) lpFileName)
Arguments
Sheet The handle of an existing sheet object.
BufLen The number of bytes available in the buffer pointed to by lpFileName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_FILENAME_LEN.
lpFileName A pointer to a lmbcs string in which to return the filename.
Returns
LCS_SUCCESS »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
lmbcs FileName[LCI_MAX_FILENAME_LEN];
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetFileName(Sheet,LCI_MAX_FILENAME_LEN,FileName);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves the global format and the number of decimal places for cells in a specified sheet.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetFormat
(LCH_SHEET Sheet,
lptr(lushort) lpFormat,
lptr(lushort) lpPlaces)
Arguments
Sheet The handle of an existing sheet object.
lpFormat A pointer to an lushort in which to return the format. Refer to LciShSetFormat »Page for a list of the possible values.
lpPlaces A pointer to a buffer in which to return the number of decimal places. This value should be ignored if the format is non-numeric (see LciShSetFormat »Page ).
Returns
LCS_SUCCESS »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
lushort Format;
lushort Places;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetFormat(Sheet,&Format,&Places);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves a boolean flag that is LTRUE if the sheet is hidden; LFALSE if it is displayed.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetHiddenFlag
(LCH_SHEET Sheet,
lptr(lbool) lpHiddenFlag)
Arguments
Sheet The handle of an existing sheet object.
lpHiddenFlag A pointer to an lbool in which to return the flag.
Returns
LCS_SUCCESS »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
lbool HiddenSheet;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetHiddenFlag(Sheet,&HiddenSheet);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves the type of the default label alignment setting for the specified sheet.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetLabelType
(LCH_SHEET Sheet,
lptr(lushort) lpLabelType)
Arguments
Sheet The handle of an existing sheet object.
lpLabelType A pointer to an lushort in which to return the label type. Possible values are:
Constant Meaning
LCI_LABEL_TYPE_CENTER Centers all labels.
LCI_LABEL_TYPE_LEFT Left-aligns all labels.
LCI_LABEL_TYPE_RIGHT Right-aligns all labels.
Returns
LCS_SUCCESS »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
LCS_INVALID_LABEL_TYPE »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
lushort LabelType;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetLabelType(Sheet,&LabelType);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves the address string of the last cell in the active area of the worksheet in a form that can be passed to LciClConstructAddr »Page .
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetLastCellAddr
(LCH_SHEET Sheet,
lushort BufLen,
lptr(lmbcs) lpLastCellAddr)
Arguments
Sheet The handle of an existing sheet object.
BufLen The number of bytes available in the buffer pointed to by lpLastCellAddr, including room for a null-terminating byte. This value need not be greater than LCI_MAX_ADDR_LEN.
lpLastCellAddr A pointer to a lmbcs string in which to return the address of the last cell.
Returns
LCS_SUCCESS »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
lmbcs CellAddr[LCI_MAX_ADDR_LEN];
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetLastCellAddr(Sheet,LCI_MAX_ADDR_LEN,CellAddr);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves the filename and coordinates of the last cell in the active area of the worksheet.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetLastCellCoords
(LCH_SHEET Sheet,
lushort BufLen,
lptr(lmbcs) lpFileName,
lptr(lushort) lpSheetNum,
lptr(lushort) lpColNum,
lptr(lushort) lpRowNum)
Arguments
Sheet The handle of an existing sheet object.
BufLen The number of bytes available in the buffer pointed to by lpFileName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_FILENAME_LEN.
lpFileName A pointer to a lmbcs string in which to return the filename.
lpSheetNum A pointer to an lushort in which to return the sheet number.
lpColNum A pointer to an lushort in which to return the column number.
lpRowNum A pointer to an lushort in which to return the row number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
LCH_SHEET Sheet;
LCT_STATUS Status;
lmbcs FileName[LCI_MAX_FILENAME_LEN];
lushort SheetNum;
lushort Row;
lushort Col;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetLastCellCoords (Sheet,
LCI_MAX_FILENAME_LEN,
&SheetNum,&Col,&Row);
. . .
Status = LciShDestroy(&Sheet);
Definition
Gets the name of the sheet.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetName
(LCH_SHEET Sheet,
lushort Buflen,
lptr(lmbcs) lpName)
Arguments
Sheet The handle of an existing sheet object.
Buflen Len of the name buffer.
lpName String in which to put the name.
Returns
LCS_SUCCESS »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
#define MAX_SHEET_NAME 32
. . .
LCH_SHEET Sheet;
lmbcs SheetName[MAX_SHEET_NAME];
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
Status = LciShGetName(Sheet,MAX_SHEET_NAME,SheetName);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves the one-based number of a specified sheet in its containing workfile.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetNum
(LCH_SHEET Sheet,
lptr(lushort) lpSheetNum)
Arguments
Sheet The handle of an existing sheet object.
lpSheetNum A pointer to an lushort in which to return the sheet number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
lushort SheetNum;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetNum(Sheet,&SheetNum);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves a value that indicates whether the cells in the specified sheet are protected (that is, Worksheet Global Protection is on). LTRUE is returned if they are protected; LFALSE if they are not.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetProtectFlag
(LCH_SHEET Sheet,
lptr(lbool) lpProtectFlag)
Arguments
Sheet The handle of an existing sheet object.
lpProtectFlag A pointer to an lbool in which to return the flag.
Returns
LCS_SUCCESS »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
lbool ProtectFlag;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetProtectFlag(Sheet,&ProtectFlag);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves the number of columns frozen along the left edge of a specified sheet. These columns stay on the screen as the cell pointer moves around the sheet.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetTitleColCount
(LCH_SHEET Sheet,
lushort PaneNum,
lptr(lushort) lpColCount)
Arguments
Sheet The handle of an existing sheet object.
PaneNum The one-based number of a pane within each window, or LCI_CURRENT_PANE to specify the current pane. 1(one) refers to the top, left, or only pane.
lpColCount A pointer to an lushort in which to return the number of frozen columns.
Returns
LCS_SUCCESS »Page
LCS_INVALID_PANE »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
lushort ColCount;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetTitleColCount(Sheet,LCI_CURRENT_PANE,&ColCount);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves the number of rows frozen along the top edge of a specified sheet. These rows stay on the screen as the cell pointer moves around the sheet.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetTitleRowCount
(LCH_SHEET Sheet,
lushort PaneNum,
lptr(lushort) lpRowCount)
Arguments
Sheet The handle of an existing sheet object.
PaneNum The one-based number of a pane within each window, or LCI_CURRENT_PANE to specify the current pane. 1(one) refers to the top, left, or only pane.
lpRowCount A pointer to an lushort in which to return the number of frozen rows.
Returns
LCS_SUCCESS »Page
LCS_INVALID_PANE »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
lushort RowCount;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetTitleRowCount(Sheet,LCI_CURRENT_PANE,&RowCount);
. . .
Status = LciShDestroy(&Sheet);
Definition
Retrieves the string that determines how 1-2-3 displays cell values of zero in the specified sheet. If the returned string is an empty string ( " " ), zero values are displayed as 0. If the zero string is a single quote ( " ' " ), a double quote ( " " " ), or a caret ( " ^ " ), 1-2-3 displays zeros as blanks (Note: The spacing in the character strings appears for clarity in the documentation). In all other cases, 1-2-3 interprets the string as a label that is displayed in place of zero values. If the label is right justified, it is retrieved as "label (double quote followed by the label). If the label is left justified, it is retrieved as 'label. If the label is centered, it is retrieved as ^label.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShGetZeroStr
(LCH_SHEET Sheet,
lushort BufLen,
lptr(lmbcs) lpZeroStr)
Arguments
Sheet The handle of an existing sheet object.
BufLen The number of bytes available in the buffer pointed to by lpZeroStr, including room for a null-terminating byte. This value need not be greater than LCI_MAX_CELL_LEN,
lpZeroStr A pointer to a lmbcs string in which to return the zero string.
Returns
LCS_SUCCESS »Page
LCS_INVALID_SHEET »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
lmbcs ZeroStr[LCI_MAX_CELL_LEN];
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetZeroStr(Sheet,LCI_MAX_CELL_LEN,ZeroStr);
. . .
Status = LciShDestroy(&Sheet);
Definition
Inserts a specified number of columns into the sheet before a specified column.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShInsertCols
(LCH_SHEET Sheet,
lushort BeforeCol,
lushort ColCount)
Arguments
Sheet The handle of an existing sheet object.
BeforeCol The number of the existing column before which to insert new columns.
ColCount The number of columns to insert.
Returns
LCS_SUCCESS »Page
LCS_INVALID_COL »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_OUT_OF_BOUNDS »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_SHEET »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
LCH_SHEET Sheet;
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
/* Insert 7 columns starting at column C */
Status = LciShInsertCols(Sheet,3,7);
. . .
Status = LciShDestroy(&Sheet);
Definition
Inserts a specified number of rows into the sheet before a specified row.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShInsertRows
(LCH_SHEET Sheet,
lushort BeforeRow,
lushort RowCount)
Arguments
Sheet The handle of an existing sheet object.
BeforeRow The number of the existing row before which to insert new rows.
RowCount The number of rows to insert.
Returns
LCS_SUCCESS »Page
LCS_INVALID_ROW »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_OUT_OF_BOUNDS »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_SHEET »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
/* Insert 3 rows starting at row 5 */
Status = LciShInsertRows(Sheet,5,3);
. . .
Status = LciShDestroy(&Sheet);
Definition
Sets the default width for columns in a sheet as viewed by a specified pane in all windows. Column width is specified in number of characters; ranges from LCI_MIN_COL_WIDTH to LCI_MAX_COL_WIDTH. The default column width can be overridden per column by calling LciClSetColWidth »Page or LciRgSetColWidth »Page .
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShSetDefaultColWidth
(LCH_SHEET Sheet,
lushort PaneNum,
lushort DefaultColWidth)
Arguments
Sheet The handle of an existing sheet object.
PaneNum The one-based number of a pane within each window, or LCI_CURRENT_PANE to specify the current pane. 1(one) refers to the top, left, or only pane.
DefaultColWidth The desired column width.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_HIDDEN_SHEET »Page
LCS_INVALID_PANE »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_INVALID_WIDTH »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
/* Set the default column width in pane 2 to 7 characters. */
Status = LciShSetDefaultColWidth(Sheet,2,7);
. . .
Status = LciShDestroy(&Sheet);
Definition
Sets the global format including the number of decimal places for cells in a specified sheet.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShSetFormat
(LCH_SHEET Sheet,
lushort Format,
lushort Places)
Arguments
Sheet The handle of an existing sheet object.
Format The desired format. Possible values are:
Constant Meaning
LCI_FORMAT_AUTO automatic format
LCI_FORMAT_BAR +/- format
LCI_FORMAT_COMMA thousands separators (numeric)
LCI_FORMAT_CURRENCY international currency format (numeric)
LCI_FORMAT_DATE_INTL_LONG long international date format (D4)
LCI_FORMAT_DATE_INTL_SHORT short international date format (D5)
LCI_FORMAT_DAY_MON DD-MMM date format (D2)
LCI_FORMAT_DAY_MON_YR DD-MMM-YY date format (D1)
LCI_FORMAT_FIXED fixed format (numeric)
LCI_FORMAT_GENERAL general format
LCI_FORMAT_HIDDEN hidden format
LCI_FORMAT_HR_MIN HH:MM (AM/PM) time format (D7)
LCI_FORMAT_HR_MIN_SEC HH:MM:SS (AM/PM) time format (D6)
LCI_FORMAT_LABEL label format
LCI_FORMAT_MON_YR MMM-YY date format (D3)
LCI_FORMAT_PERCENT percent format (numeric)
LCI_FORMAT_SCIENTIFIC sci (scientific) format (numeric)
LCI_FORMAT_TEXT text format
LCI_FORMAT_TIME_INTL_LONG long international (24hr) time format (D8)
LCI_FORMAT_TIME_INTL_SHORT short international (24hr) time format (D9)
Places The desired number of decimal places or LCI_DEFAULT_PLACES. Places is ignored if Format specifies a non-numeric format.
Returns
LCS_SUCCESS »Page
LCS_INVALID_FORMAT »Page
LCS_INVALID_NUM »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
/* Set percent format(%) with zero decimal places. */
Status = LciShSetFormat(Sheet,LCI_FORMAT_PERCENT,0);
. . .
Status = LciShDestroy(&Sheet);
Definition
Specifies whether a worksheet in the current file is hidden. You cannot hide all worksheets in a file.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShSetHiddenFlag
(LCH_SHEET Sheet,
lbool HiddenFlag)
Arguments
Sheet The handle of an existing sheet object.
HiddenFlag The flag to be set. Set HiddenFlag to LTRUE if you want to hide the sheet; set it to LFALSE if you want to redisplay the sheet.
Returns
LCS_SUCCESS »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_NO_VISIBLE_SHEETS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
/* Hide this sheet. */
Status = LciShSetHiddenFlag(Sheet,LTRUE);
. . .
Status = LciShDestroy(&Sheet);
Definition
Sets the default label alignment for a specified sheet. It has no effect on numbers, formulas, or blank cells. This setting will only affect labels entered after the setting has been changed.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShSetLabelType
(LCH_SHEET Sheet,
lushort LabelType)
Arguments
Sheet The handle of an existing sheet object.
LabelType The label type to be set. Possible values are:
Constant Meaning
LCI_LABEL_TYPE_CENTER Centers all labels.
LCI_LABEL_TYPE_LEFT Left-aligns all labels.
LCI_LABEL_TYPE_RIGHT Right-aligns all labels.
Returns
LCS_SUCCESS »Page
LCS_INVALID_LABEL_TYPE »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
/* Center all labels by default. */
Status = LciShSetLabelType(Sheet,LCI_LABEL_TYPE_CENTER);
. . .
Status = LciShDestroy(&Sheet);
Definition
Sets the name of a sheet.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShSetName
(LCH_SHEET Sheet,
lptr(lmbcs) lpName)
Arguments
Sheet The handle of an existing sheet object.
lpName String to name the sheet.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
#define MAX_SHEET_NAME 32
. . .
LCH_SHEET Sheet;
lmbcs SheetName[MAX_SHEET_NAME];
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
Status = LciShSetName(Sheet,SheetName);
. . .
Status = LciShDestroy(&Sheet);
Definition
Sets worksheet global protection on or off. The default in 1-2-3 is on.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShSetProtectFlag
(LCH_SHEET Sheet,
lbool ProtectFlag)
Arguments
Sheet The handle of an existing sheet object.
ProtectFlag The flag to be set. It is LTRUE to turn protection on; LFALSE to turn it off.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
/* Turn global protection off. */
Status = LciShSetProtectFlag(Sheet,LFALSE);
. . .
Status = LciShDestroy(&Sheet);
Definition
Sets the number of columns frozen along the left edge of a specified sheet for a particular pane. These columns stay on the screen as the cell pointer moves around the sheet.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShSetTitleColCount
(LCH_SHEET Sheet,
lushort PaneNum,
lushort ColCount)
Arguments
Sheet The handle of an existing sheet object.
PaneNum The one-based number of a pane within each window, or LCI_CURRENT_PANE to specify the current pane. 1(one) refers to the top, left, or only pane.
ColCount The desired number of frozen columns. If it is zero, no columns are frozen.
Returns
LCS_SUCCESS »Page
LCS_INVALID_PANE »Page
LCS_INVALID_SHEET »Page
LCS_NO_UNTITLED_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
#include "lciwkspc.h"
. . .
LCH_SHEET Sheet;
LCH_WORKSPACE Wkspace;
LCT_STATUS Status;
lushort SheetNum;
. . .
Status = LciWsConstructCurr(Context,&Wkspace);
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetNum(Sheet,&SheetNum);
/* Make C4 the top left cell in the current sheet, then make
columns C and D titled */
Status = LciWsSetCellTopLeftCoords(Wkspace,LCI_CURRENT_WORKFILE,
SheetNum,3,4);
Status = LciShSetTitleColCount(Sheet,LCI_CURRENT_PANE,2);
. . .
Status = LciShDestroy(&Sheet);
Status = LciShDestroy(&Wkspace);
Definition
Sets the number of rows frozen along the top edge of a specified sheet for a particular pane. These rows stay on the screen as the cell pointer moves around the sheet.
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShSetTitleRowCount
(LCH_SHEET Sheet,
lushort PaneNum,
lushort RowCount)
Arguments
Sheet The handle of an existing sheet object.
PaneNum The one-based number of a pane within each window, or LCI_CURRENT_PANE to specify the current pane. 1(one) refers to the top, left, or only pane.
RowCount The desired number of frozen rows. If it is zero, no rows are frozen.
Returns
LCS_SUCCESS »Page
LCS_INVALID_PANE »Page
LCS_INVALID_SHEET »Page
LCS_NO_UNTITLED_CELL »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
#include "lciwkspc.h"
. . .
LCH_SHEET Sheet;
LCH_WORKSPACE Wkspace;
LCT_STATUS Status;
lushort SheetNum;
. . .
Status = LciWsConstructCurr(Context,&Wkspace);
Status = LciShConstructCurr(Context,&Sheet);
. . .
Status = LciShGetNum(Sheet,&SheetNum);
/* Make C4 the top left cell in the current sheet, then make
rows 4 and 5 titled */
Status = LciWsSetCellTopLeftCoords(Wkspace,LCI_CURRENT_WORKFILE,
SheetNum,3,4);
Status = LciShSetTitleRowCount(Sheet,LCI_CURRENT_PANE,2);
. . .
Status = LciShDestroy(&Sheet);
Status = LciShDestroy(&Wkspace);
Definition
Sets the string that determines how 1-2-3 displays cell values of zero in the specified sheet. If the zero string is an empty string ( " " ), zero values are displayed as 0. If the zero string is a single quote ( " ' " ), a double quote ( " " " ), or a caret ( " ^ " ), 1-2-3 displays zeros as blanks (Note: The spacing in the character strings appears for clarity in the documentation). In all other cases, 1-2-3 interprets the string as a label that is displayed in place of zero values. The string is right-justified if its leftmost character is either a double quote ("text) or a regular character (text). The string is left-justified if its leftmost character is a single quote ('text). The string is centered if its leftmost character is a caret (^text).
Format
#include "lcicomn.h"
#include "lcisheet.h"
LCT_STATUS LCI_CALL LciShSetZeroStr
(LCH_SHEET Sheet,
lptr(lmbcs) lpZeroStr)
Arguments
Sheet The handle of an existing sheet object.
lpZeroStr A pointer to the desired zero string. If this string is longer than LCI_MAX_ZERO_STR_LEN, the error code LCS_STR_TOO_LONG is returned.
Returns
LCS_SUCCESS »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lcisheet.h"
. . .
LCH_SHEET Sheet;
LCT_STATUS Status;
. . .
Status = LciShConstructCurr(Context,&Sheet);
. . .
/* Display the string "zero" left-justified where the cell
value = 0. */
Status = LciShSetZeroStr(Sheet,"\"zero);
. . .
Status = LciShDestroy(&Sheet);
You use the add-in support functions in the utility group to enhance your add-ins. The add-in support functions are listed alphabetically below.
Function Meaning
LciUtAllocBlock »Page Allocates a block of the desired size from the specified heap. Stores the byte with the block. If you created the heap by using the LCT_MMALLOCCLEAR option, this block initializes to zero.
LciUtBeep »Page Sounds the computer speaker.
LciUtCreateHeap »Page Initializes a new heap by adding a Heap Info structure to the Heap Table. Uses the internal 123 memory manager. This heap can be suballocated using LciUtAllocBlock.
LciUtDestroyHeap »Page Frees pages, clears the Page Table and Heap Table entries for this heap. Use caution to prevent freeing pages which other clients may have locked Blocks.
LciUtDisplayError »Page Displays an error string in a message box.
LciUtErrorText »Page Retrieves corresponding error message string for error codes returned from library functions.
LciUtExit »Page Exits the add-in immediately.
LciUtFreeBlock »Page Frees the specified block of memory.
LciUtFormatValFloat »Page Presents the input value in the float format the way 1-2-3 would present it in a cell of specified width.
LciUtFormatValInteger »Page Presents the input value in the integer format the way 1-2-3 would present it in a cell of specified width.
LciUtFormatValStr »Page Presents the input value in the string format the way 1-2-3 would in a cell of specified width.
LciUtGetDefaultAddinDir »Page Retrieves the drive and path of the default add-in directory.
LciUtGetEnvBlock »Page Retrieves the environment block for the product.
LciUtGetLotusIniNum »Page Obtains a value for the keyname and section header in 123R4.INI.
LciUtGetLotusIniStr »Page Obtains a string from the keyname and section header in 123R4.INI.
LciUtGetPersonalDir »Page Retrieves the drive and path of the 1-2-3 personal directory.
LciUtGetSystemDir »Page Retrieves the drive and path of the 1-2-3 Windows product file directory.
LciUtIntToLetter »Page Converts worksheet or column integers to worksheet or column letters.
LciUtLearnStr »Page Writes a string to the learn buffer.
LciUtLetterToInt »Page Converts worksheet or column letters to worksheet or column integers.
LciUtMaxBlockSize »Page Returns the maximum block size allocated.
LciUtPrintRangeFlag »Page Checks to see if a print range exists.
LciUtResizeBlock »Page Resizes a presently allocated block of memory to a larger size. Works with allocated blocks using LciUtAllocBlock only. If you created this heap by using the LCT_MMALLOCCLEAR option, the extra memory initializes to zero.
LciUtRunMacro »Page Runs macros directly from an add-in.
LciUtRunMacroArray »Page Runs an array of strings that correspond to macros commands directly from an add-in.
LciUtSetDefaultAddinDir »Page Sets the drive and path of the default add-in directory.
LciUtSetIndicator »Page Handles updating the status bar mode indicator.
LciUtSetLongPrompt »Page Handles writing a string to the indicator, or resetting the indicator.
LciUtSetLotusIniNum »Page Writes a value for the keyname and section header in 123R4.INI.
LciUtSetLotusIniStr »Page Writes a string for the keyname and section header in 123R4.INI.
LciUtSizeOfBlock »Page Returns the size of the specified block. Works with allocated blocks using LciUtAllocBlock only.
LciUtSystem »Page Runs an operating system command from an add-in.
LciUtVersion »Page Retrieves the float that corresponds to the current version number of 1-2-3 for Windows libraries (1.0) and the string that corresponds to the current version, "123 Release 4 for Windows."
LciUtYield »Page Causes the add-in to yield to 1-2-3 for a single poll event.
LciUt123EnvCall »Page Calls a routine from the 123 stack environment.
Definition
Allocates a block of the desired size from the specified heap. Stores the byte with the block. If you created the heap by using the LCT_MMALLOCCLEAR option, this block initializes to zero.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtAllocBlock
(LCH_CONTEXT Context,
LCT_MMHEAP HeapHandle,
lsshort Size,
lptr(LCT_MMBP) BlkPtr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 started.
HeapHandle Heap from which to allocate a block.
Size Size in bytes.
BlkPtr Pointer for the allocated block.
Returns
LCS_SUCCESS »Page
LCS_NULL_HANDLE »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
...
lsshort Options;
lmbcs HeapName[16];
LCT_MMHEAP HeapHandle;
LCT_MMBP BlkPtr;
LCT_STATUS Status;
lsshort Size;
...
Options = (MMSIZEKEPT | MMALLOCNOCLEAR);
strcpy(HeapName,"myheap");
...
Status = LciUtCreateHeap(Context,Options,HeapName,&HeapHandle);
...
Status = LciUtAllocBlock(Context,HeapHandle,Size,&BlkPtr);
Definition
Sounds the computer speaker.
Note Values specified for frequency and duration have no effect under Windows since this routine ultimately calls the Windows SDK function MessageBeep (which takes no arguments). The frequency and duration arguments exist strictly for compatibility with existing and future products.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtBeep
(LCH_CONTEXT Context,
lushort Frequency,
lushort Duration)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Frequency Integer between LCI_MIN_BEEP_FREQ and LCI_MAX_BEEP_FREQ, inclusive, that corresponds to the Hertz value (frequency in cycles per second) of the beep.
Duration Integer between 0 and 65,535, inclusive, that corresponds to the duration of the beep (in milliseconds).
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
. . .
LCT_STATUS Status;
. . .
/* Sound a beep. */
Status = LciUtBeep(Context,LCI_MIN_BEEP_FREQ,0);
Definition
Initializes a new heap by adding a Heap Info structure to the Heap Table. Uses the internal 123 memory manager. This heap can be suballocated using LciUtAllocBlock.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtCreateHeap
(LCH_CONTEXT Context,
lsshort Options,
lptr(lmbcs) lpHeapName,
lptr(LCT_MMHEAP) HeapHandle)
Arguments
Context The context handle that was passed to the C program when 1-2-3 started.
Options You can combine the following options for this heap:
LCS_MMSIZEKEPT (recommended) tells the memory manager that the size
LCT_MMALLOCCLEAR clears the memory block.
LCT_MMALLOCNOCLEAR leaves memory "as is" when allocating a block from this heap.
lpHeapName Name of the heap. Maximum of 16 characters.
HeapHandle The handle returns here.
Returns
LCS_SUCCESS »Page
LCS_NULL_HANDLE »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
...
lsshort Options;
lmbcs lpHeapName[16];
LCT_MMHEAP HeapHandle;
LCT_STATUS Status;
...
Options = (LCS_MMSIZEKEPT | LCS_MMALLOCNOCLEAR);
strcpy(lpHeapName,"myheap");
...
Status = LciUtCreateHeap(Context,Options,lpHeapName,&HeapHandle);
Definition
Frees pages, clears the Page Table and Heap Table entries for this heap. Use caution to prevent freeing pages which other clients may have locked Blocks.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtDestroyHeap
(LCH_CONTEXT Context,
LCT_MMHEAP HeapHandle)
Arguments
Context The context handle that was passed to the C program when 1-2-3 started.
HeapHandle Handle of the heap to destroy.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
...
lsshort Options;
lmbcs HeapName[16];
LCT_MMHEAP HeapHandle;
LCT_STATUS Status;
...
Options = (MMSIZEKEPT | LCT_MMALLOCNOCCLEAR);
strcpy(HeapName,"myheap");
...
Status = LciUtCreateHeap(Context,Options,HeapName,&HeapHandle);
...
Status = LciUtDestroyHeap(Context,HeapHandle);
Definition
Displays an error string in a message box.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtDisplayError
(LCH_CONTEXT Context,
LCT_STATUS ErrId,
lptr(lmbcs) lpErrorText)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
ErrId The Id of the error message to be displayed. It can be an LCS error or an id between LCI_ADDIN_ERROR_START and LCI_ADDIN_ERROR_END for a custom error.
lpErrorText Pointer to a LMBCS string that contains the custom text to be displayed in the message box, or LNULL for an LCS error.
Returns
LCS_SUCCESS »Page
LCS_INVALID_NUM »Page
LCS_OUT_OF_MEMORY »Page
LCS_INVALID_USE »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
/*LCI_ADDIN_ERROR_START is in lcienum.h.*/
#define LCS_MY_ADDIN_ERROR (LCI_ADDIN_ERROR_START+100)
. . .
LCT_STATUS Status;
lptr(lmbcs) errString="Error in my addin";
. . .
/* Let users know we are out of memory. */
Status = LciUtDisplayError(Context,LCS_OUT_OF_MEMORY,LNULL);
...
/*To display your own addin error message.*/
Status=LciUtDisplayError(Context, LCS_MY_ADDIN_ERROR, errString);
Definition
ErrorText interprets the error codes that library functions return. You provide LciUtErrorText with an LCI or 1-2-3 error code and it retrieves the corresponding error message string for the code.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtErrorText
(LCH_CONTEXT Context,
LCT_STATUS ErrCode,
lushort BufLen,
lptr(lmbcs) lpMessage)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
ErrCode Error code value from library function.
Note Passing values less than zero to this function causes unpredictable results. In addition, the value 0, LCS_SUCCESS, is not an error code and should not be passed to this function.
BufLen Length of output buffer including null-terminating byte. Buflen need not be greater thab LCI_MAX_ERROR_TEXT_LEN.
lpMessage Pointer to the lmbcs string in which the error code string is to be stored.
Returns
LCS_SUCCESS »Page
LCS_NUM_NOT_FOUND »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
#include "lcild.h"
. . .
lmbcs lpErrorText[LCI_MAX_ERROR_TEXT_LEN];
LCT_STATUS Status;
. . .
Status = LciLdLoadCompatLib(Context);
if (Status != LCS_SUCCESS)
{
Status = LciUtErrorText(Context,Status,
LCI_MAX_ERROR_TEXT_LEN, lpErrorText);
}
Definition
Leaves the add-in and returns to 1-2-3 for Windows. Any allocated resources should be cleaned up prior to making this cell since 1-2-3 for Windows will not do it for you.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtExit
(LCH_CONTEXT Context,
LCT_STATUS Status)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Status The status returned by the add-in.
Returns
None
Example
#include "lcicomn.h"
#include "lciutil.h"
#include "lcievent.h"
. . .
LCT_STATUS LCI_CALL my_event_handler
(LCH_CONTEXT CONTEXT,
LCH_EVARG hEvArg,
lsshort EventId,
lushort TimeFlags,
lslong Arg)
{
/* Exit if an error has occurred in this event. */
LCT_STATUS Status;
. . .
Status = LciEvGetErrCode(hEvArg);
if(Status != LCS_SUCCESS)
LciUtExit(Context,Status);
...
}
Definition
Frees the specified block of memory.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtFreeBlock
(LCH_CONTEXT Context,
LCT_MMBP BlkPtr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 started.
BlkPtr Pointer to the block to free.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
...
lsshort Options;
lmbcs HeapName[16];
LCT_MMHEAP HeapHandle;
LCT_MMBP BlkPtr;
LCT_STATUS Status;
...
Options = (MMSIZEKEPT | LCT_MMALLOCNOCCLEAR);
strcpy(HeapName,"myheap");
...
Status = LciUtCreateHeap(Context,Options,HeapName,&HeapHandle);
...
Status = LciUtAllocBlock(Context,HeapHandle,Size,&BlkPtr);
...
Status = LciUtFreeBlock(Context,BlkPtr);
Definition
Format presents specified input value in the specified format (float, integer, or string) the way 1-2-3 would display it in a cell of specified width. If resulting string is wider than the specified width, asterisks are returned.
Note The function prototypes for these functions are in lcicell.h not lciutil.h.
Format
#include "lcicomn.h"
#include "lcicell.h"
* Float *
LCT_STATUS LCI_CALL LciUtFormatValFloat
(LCH_CONTEXT Context,
lfloat10 Value,
lushort Format,
lushort Places,
lushort Width,
lushort BufLen,
lptr(lmbcs) lpResult)
* Integer *
LCT_STATUS LCI_CALL LciUtFormatValInteger
(LCH_CONTEXT Context,
lslong Value,
lushort Format,
lushort Places,
lushort Width,
lushort BufLen,
lptr(lmbcs) lpResult)
* String *
LCT_STATUS LCI_CALL LciUtFormatValStr
(LCH_CONTEXT Context,
lptr(lmbcs) Value,
lushort Format,
lushort Places
lushort Width,
lushort BufLen,
lptr(lmbcs) lpResult)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Value A pointer to a lmbcs string that contains the value you want to format.
Format The output format.
Places The number of decimal places you want the output to contain (ignored for strings).
Width Width of output cell in characters, from LCI_MIN_COL_WIDTH to LCI_MAX_COL_WIDTH.
BufLen The number of bytes available in buffer pointed to by lpResult, including room for the null-terminating byte.
lpResult Pointer to a lmbcs string in which the result is to be stored.
Returns
LCS_SUCCESS »Page
LCS_INVALID_PLACES »Page
LCS_INVALID_WIDTH »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Note LCS_INVALID_PLACES is returned only for LciUtFormatValFloat.
Example
#include "lcicomn.h"
#include "lcicell.h"
#include "lciatfnc.h"
. . .
LCT_STATUS Status;
lmbcs lpResult[20];
lfloat10 MemAvail;
lmbcs Directory[LCI_MAX_DIRNAME_LEN];
lulong TimeVal;
. . .
/* Get MemAvail, Directory, and Today. */
Status = LciAtInfoNum(Context, LCI_FLOAT_INFO_MEMAVAIL,
&MemAvail);
Status = LciAtInfoStr(Context,LCI_STR_INFO_DIRECTORY,
LCI_MAX_DIRNAME_LEN,Directory);
Status = LciAtToday(Context,&TimeVal);
. . .
/* Format MemAvail with thousands separator, no decimal places,
column with of 9. */
Status = LciUtFormatValFloat(Context, MemAvail,
LCI_FORMAT_COMMA, 0, 9, 20, lpResult);
. . .
/* Format Directory for 10 column width. */
Status = LciUtFormatValStr(Context, Directory,
LCI_FORMAT_TEXT, 9, 20, lpResult);
. . .
/* Format today's date in DD-MM-YY format, 10 columns wide. */
Status = LciUtFormatValInteger(Context, TimeVal,
LCI_FORMAT_DAY_MON_YR, 0, 9, 20, lpResult);
Definition
Retrieves the drive and path of the default add-in directory. Corresponds to addin = parameter in [DIRECTORIES] section of 123R4.INI file.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtGetDefaultAddinDir
(LCH_CONTEXT Context,
lushort BufLen,
lptr(lmbcs) lpDirName)
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 lpDirName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_DIRNAME_LEN.
lpDirName A pointer to a lmbcs string in which the directory pathname will be returned.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
...
LCT_STATUS Status;
lmbcs lpDefAddinDir[LCI_MAX_DIRNAME_LEN];
. . .
Status = LciUtGetDefaultAddinDir(Context, LCI_MAX_DIRNAME_LEN,
lpDefAddinDir);
Definition
Retrieves a pointer to the environment block for the product. It may be used for loading the LMBCS services driver, for example. The environment block is a structure defined in ltsstrct.h that allows DataLens and Toolkit users to have access to a variety of information and basic services. The definition of the environment block is shown below.
typedef struct envblk_
{ /* Environment descriptor block */
lushort envsize; /* Length of environment
descriptor */
platform pfid; /* Platform identifier */
lmbcs_type csid; /* Application LMBCS group */
lsshort pad; /* ..for alignment.. */
lsshort maps; /* Maximum number of mapped
handles */
memory_type type; /* Type of memory allocation
scheme */
lmhdl(void) nulh; /* Null handle value */
lulong maxsize; /* Largest block that can be
allocated */
lptr(lmbcs) applid; /* Application identification
string */
lptr(void) gabinfo; /* Place for Datalens
registration file */
lptr(char) regfile; /* Name of Datalens registration
file */
lexportp (lmhdl (void), get) (lulong,lsshort);
/* Memory allocator */
lexportp (lbool, free) (lmhdl (void), lulong);
/* Memory deallocator */
lexportp (lptr (void), map) (lmhdl (void), lsshort );
/* Memory mapper */
lexportp (void, unmap) (lmhdl (void), lsshort);
/* Memory unmapper */
lexportp (lptr (void), alloc) (lulong);
/* Fixed memory allocator */
lexportp (lbool, dealloc) (lptr (void),lulong);
/* Fixed memory deallocator */
lexportp (lushort, load) (lptr (char), lretarg (lptr (void)),
lretarg,lretarg (lptr (void));
/* Module loader */
lexportp (lushort, unload) (lptr (void));
/* Module unloader */
lexportp (lushort, syscall) (lptr (char));
/* System command shell */
} envblk;
/* Environment descriptor block */
You may use these fields to make your add-in behave predictably on different hardware and software platforms. For example, the type field can be used to test for the use of extended or expanded memory in case your add-in does not map memory, or you can use the maxsize field to determine the allowable range before trying to allocate memory.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtGetEnvBlock
(LCH_CONTEXT Context,
lptr(lptr(envblk))lppEnvBlock)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lppEnvBLock The address of a pointer that will receive the address of the environment block for the product.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
. . .
LCT_STATUS Status;
lptr(envblk) EnviroBlkPtr;
. . .
/* Get environment block address. */
Status = LciUtGetEnvBlock(Context,&EnviroBlkPtr);
Definition
Obtains a value for the keyname and section header in 123R4.INI.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtGetLotusIniNum
(LCH_CONTEXT Context,
lptr(lmbcs) lpSectionName,
lptr(lmbcs) lpKeyName,
lsshort nDefault,
lptr(lsshort) Value)
Arguments
Context The context handle that was passed to the C program when 1-2-3 started.
lpSectionName Name of the section from which to get the value.
lpKeyName Name whose associated value is to be read.
nDefault The default value, if the keyname does not exist.
Value The value returns here.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
#define MAX_STRING 32
...
lmbcs lpSectionName[MAX_STRING];
lmbcs lpKeyName[MAX_STRING];
lsshort nDefault;
lsshort Value;
LCT_STATUS Status;
...
strcpy(lpSectionName, "CONFIG");
strcpy(lpKeyName, "page_length");
nDefault = 60;
...
Status = LciUtGetLotusIniNum(Context, lpSectionName, lpKeyName,
nDefault, &Value);
Definition
Obtains a string from the keyname and section header in 123R4.INI.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtGetLotusIniStr
(LCH_CONTEXT Context,
lptr(lmbcs) lpSectionName,
lptr(lmbcs) lpKeyName,
lptr(lmbcs) lpDefault,
lptr(lmbcs) lpRetString,
lsshort Size,
lptr(lsshort) Value)
Arguments
Context The context handle that was passed to the C program when 1-2-3 started.
lpSectionName Name of the section from which to get a string.
lpKeyName Name whose associated string is to be read.
lpDefault The default string, if the keyname does not exist.
lpRetString The string read (default string) appears here.
Size The maximum buffer size.
Value Size of string returned.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
#define MAX_STRING 32
#define DEF_LEN 80
...
lmbcs lpSectionName[MAX_STRING];
lmbcs lpKeyName[MAX_STRING];
lmbcs lpDefStr[DEF_LEN];
lmbcs lpRetStr[DEF_LEN];
lsshort Size = DEF_LEN;
lsshort Value;
LCT_STATUS Status;
...
strcpy(lpSectionName,"FILES");
strcpy(lpKeyName,"lastopen1");
strcpy(lpDefStr,"c:\windows\123w\myfile.wk3");
...
Status = LciUtGetLotusIniStr(Context, lpSectionName, lpKeyName,
lpDefStr, lpRetStr, Size, &Value);
Definition
Retrieves the drive and path of the 1-2-3 personal directory. Corresponds to personal = string in the [DIRECTORIES] section of 123R4.INI file.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtGetPersonalDir
(LCH_CONTEXT Context,
lushort BufLen,
lptr(lmbcs) lpDirName)
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 lpDirName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_DIRNAME_LEN.
lpDirName A pointer to a lmbcs string in which to return the directory pathname.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
. . .
LCT_STATUS Status;
lmbcs lpPersonalDir[LCI_MAX_DIRNAME_LEN];
. . .
Status = LciUtGetPersonalDir(Context, LCI_MAX_DIRNAME_LEN,
lpPersonalDir);
Definition
Retrieves the drive and path of the 1-2-3 for Windows main program directory.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtGetSystemDir
(LCH_CONTEXT Context,
lushort BufLen,
lptr(lmbcs) lpDirName)
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 lpDirName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_DIRNAME_LEN.
lpDirName A pointer to a lmbcs string in which to return the directory pathname
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
. . .
LCT_STATUS Status;
lmbcs lpSystemDir[LCI_MAX_DIRNAME_LEN];
. . .
Status = LciUtGetSystemDir(Context, LCI_MAX_DIRNAME_LEN,
lpSystemDir);
Definition
Converts worksheet and column headers to integers, and integers to worksheet or column headers.
Format
#include "lcicomn.h"
#include "lciutil.h"
* Integer to string *
LCT_STATUS LCI_CALL LciUtIntToLetter
(LCH_CONTEXT Context,
lsshort RefNum,
lushort BufLen,
lptr(lmbcs) lpLetter)
* String to integer *
LCT_STATUS LCI_CALL LciUtLetterToInt
(LCH_CONTEXT Context,
lptr(lmbcs) lpRefLetter,
lptr(lushort) lpNum)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
RefNum Integer (between 1 and 256) you want to convert to a worksheet or column letter. Passing zero causes unpredictable results.
lpRefLetter Pointer to a lmbcs string (between A and IV, inclusive) that corresponds to the worksheet or column letter you want to convert.
BufLen Length of the output buffer, including null-terminating byte.
lpLetter Pointer to a lmbcs string of size BufLen in which the worksheet or column letter will be stored.
lpNum Pointer to an lushort in which the worksheet or column number will be stored.
Returns
LCS_SUCCESS »Page
LCS_INVALID_NUM »Page
LCS_INVALID_STR »Page
LCS_STACK_OVERFLOW »Page
Note LCS_INVALID_NUM is returned only by the integer to string form. LCS_INVALID_STR is returned only by the string to integer form.
Example
#include "lcicomn.h"
#include "lciutil.h"
. . .
LCT_STATUS Status;
lmbcs lpColStr[5];
lushort ColNum;
. . .
/* Get letters for column value of 85. */
Status = LciUtIntToLetter(Context, 85, 5, lpColStr);
/* Get integer for column "BB". */
Status = LciUtLettertoInt(Contex, "BB", &ColNum);
Definition
Writes a string to the learn buffer. This is the buffer where 1-2-3 actions are learned as macros in the transcript window. In order to use this function your add-in must have macro keywords defined to perform actions which the user can also perform via menu commands or dialog boxes. For example, in 1-2-3 the user can open a file using the File - Open dialog box or via the {FILE-OPEN} macro command.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtLearnBuffer
(LCH_CONTEXT Context,
lptr(lmbcs) lpStr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpStr Pointer to a lmbcs string to write to the learn buffer.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
. . .
LCT_STATUS Status;
lmbcs lpLearnBuf[80] = "{hello-world";
LCH_CELL Cell;
lmbcs addr[LCI_MAX_ADDR_LEN];
. . .
Status = LciClConstructCurr(Context, &Cell);
Status = LciClGetAddr(Cell, LCI_MAX_ADD_LEN, addr);
strcat(lpLearnBuf, addr);
strcat(lpLearnBuf,'}');
. . .
Status = LciUtLearnString(Context, lpLearnBuf);
Definition
Returns the maximum block size allocated.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtMaxBlockSize
(LCH_CONTEXT Context,
lptr(lsshort) MaxSize)
Arguments
Context The context handle that was passed to the C program when 1-2-3 started.
MaxSize Maximum block size allocated in bytes.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
...
lsshort MaxSize;
LCT_STATUS Status;
...
Status = LciUtMaxBlockSize(Context, &MaxSize);
Definition
Checks to see if a print range exists. Sets a flag to LTRUE if a print range has already been specified; LFALSE if no print range currently exists.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtPrintRangeFlag
(LCH_CONTEXT Context,
lptr(lbool) PrintRangeExists)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
PrintRangeExists A pointer to an lbool flag.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
. . .
LCT_STATUS Status;
lbool PrintRangeExists;
. . .
Status = LciUtPrintRangeFlag(Context, &PrintRangeExist);
Definition
Resizes a presently allocated block of memory to a larger size. Works with allocated blocks using LciUtAllocBlock only. If you created this heap by using the LCT_MMALLOCCLEAR option, the extra memory initializes to zero.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtResizeBlock
(LCH_CONTEXT Context,
LCT_MMBP BlkPtr,
lsshort NewSize,
lptr(LCT_MMBP) NewBlkPtr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 started.
BlkPtr Pointer to the block to resize.
NewSize New size of block.
NewBlkPtr Pointer to the resized block.
Returns
LCS_SUCCESS »Page
LCS_NULL_HANDLE »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
...
lsshort Options;
lmbcs HeapName[16];
LCT_MMHEAP HeapHandle;
lslong Size;
lslong NewSize;
LCT_MMBP BlkPtr;
LCT_MMBP NewBlkPtr;
LCT_STATUS Status;
...
Options = (MMSIZEKEPT | LCT_MMALLOCNOCCLEAR);
strcpy(HeapName,"myheap");
Size = 1024;
...
Status = LciUtCreateHeap(Context, Options, HeapName, &HeapHandle);
...
Status = LciUtAllocBlock(Context, HeapHandle, Size, &BlkPtr);
...
NewSize = 4096;
...
Status = LciUtResizeBlock(Context, BlkPtr, NewSize, &NewBlkPtr);
Definition
The LciUtRunMacro functions interpret a string or a string array as a 1-2-3 macro and executes it. You use these functions from an add-in application or to run 1-2-3 commands that the add-in library does not support.
Note You will not get an error trying to run LciUtRunMacro or LciUtRunMacroArray the first time from a dialog proc or from an event handler; however, in these cases LciUtYield »Page will not give up control to 1-2-3, and the request to run the macro will simply be posted to be run the next time 1-2-3 returns to the READY state. There is no way to have a macro actually be run while executing a dialog proc or an event handler.
Note Do not use the macro keyword {BRANCH range} in a macro script used for LciUtRunMacro or LciUtRunMacroArray. If it is desired to execute a macro script in a range on a sheet, call to that location and return by using {range}.
Format
#include "lcicomn.h"
#include "lciutil.h"
* String *
LCT_STATUS LCI_CALL LciUtRunMacro
(LCH_CONTEXT Context,
lptr(lmbcs) lpMacro)
* String array *
LCT_STATUS LCI_CALL LciUtRunMacroArray
(LCH_CONTEXT Context,
lptr(lptr(lmbcs)) lplpStrArray,
lushort Size)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpMacro Pointer to a lmbcs string that contains a macro (string form only).
lplpStrArray Pointer to the array of lmbcs strings that correspond to macro commands (string array form only).
Size Number of entries in the array (string array form only).
Returns
LCS_SUCCESS »Page
LCS_KEY_BREAK »Page
LCS_INVALID_USE »Page
LCS_MACRO_ERROR »Page
LCS_STACK_OVERFLOW »Page
LCS_OUT_OF_MEMORY »Page
LCS_INVALID_VALUE »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
. . .
LCT_STATUS Status;
. . .
/* String example */
Status = LciUtRunMacro(Context,"/WEY");
. . .
/* String array example */
LCT_STATUS Status;
lptr(lmbcs) macros[ ] = {
"/WEY",
"/QY"
};
. . .
Status = LciUtRunMacroArray(Context, macros, 2);
Definition
Sets the drive and path of the default add-in directory in memory. The path will not be written to disk until an update is performed (Alt-F10 Settings System Update).
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtSetDefaultAddinDir
(LCH_CONTEXT Context,
lptr(lmbcs) lpDirName)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpDirName A pointer to the lmbcs string that corresponds to the add-in directory pathname.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
. . .
LCT_STATUS Status;
. . .
Status = LciSetDefaultAddinDir(Context, "C:\\ADDIN");
Definition
Handles updating the status bar mode indicator.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtSetIndicator
(LCH_CONTEXT Context,
lushort ModeIndicator,
lptr(lushort) PrevMode)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
ModeIndicator Mode to change to. Possible values are:
LCI_MODE_WAIT
LCI_MODE_READY
LCI_MODE_LABEL
LCI_MODE_MENU
LCI_MODE_VALUE
LCI_MODE_POINT
LCI_MODE_EDIT
LCI_MODE_ERROR
LCI_MODE_FIND
LCI_MODE_FILES
LCI_MODE_HELP
LCI_MODE_STAT
LCI_MODE_FRMT
LCI_MODE_NAMES
PrevMode The previous mode of the indicator.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS Status;
lushort PrevMode;
....
/* Set mode to wait */
Status = LciUtSetIndicator(Context, LCI_MODE_WAIT, &PrevMode);
.....
/* execute the addin */
.....
/* put indicator back to original mode */
Status = LciUtSetIndicator(Context, PrevMode, &PrevMode);
Definition
Handles writing a string to the indicator, or resetting the indicator.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtSetLongPrompt
(LCH_CONTEXT Context,
lptr(lmbcs) lpStr)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpStr String to write or NULL to reset, or an empty string to clear the mode indicator.
Returns
LCS_SUCCESS »Page
LCS_ERR »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
...
LCT_STATUS Status;
...
/* tell user that the add-in is now active */
Status = LciUtSetLongPrompt(Context, "Running myprog...");
...
/* done with add-in, clear my indicator string... */
Status = LciUtSetLongPrompt(Context, LNULL);
Defintion
Writes a value for the keyname and section header in 123R4.INI.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtSetLotusIniNum
(LCH_CONTEXT Context,
lptr(lmbcs) lpSectionName,
lptr(lmbcs) lpKeyName,
lsshort NewValue,
lptr(lbool) Result)
Arguments
Context The context handle that was passed to the C program when 1-2-3 started.
lpSectionName Name of the section from which to set the value.
lpKeyName Name whose associated value is to be set.
NewValue The new value. Creates the keyname if it does not exist.
Result The result returns here.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
#define MAX_STRING 32
...
lmbcs lpSectionName[MAX_STRING];
lmbcs lpKeyName[MAX_STRING];
lsshort NewValue;
lbool Result;
LCT_STATUS Status;
...
strcpy(SectionName, "CONFIG");
strcpy(KeyName, "page_length");
NewValue = 66;
...
Status = LciUtSetLotusIniNum(Context, lpSectionName, lpKeyName,
NewValue, &Result);
Definition
Writes a string for the keyname and section header in 123R4.INI.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtSetLotusIniStr
(LCH_CONTEXT Context,
lptr(lmbcs) lpSectionName,
lptr(lmbcs) lpKeyName,
lptr(lmbcs) lpNewString,
lptr(lbool) Result)
Arguments
Context The context handle that was passed to the C program when 1-2-3 started.
lpSectionName Name of the section from which to set a string.
lpKeyName Name whose associated string is to be set.
lpNewString The new string. Creates the keyname if it does not exist.
Result The result returns here.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
#define MAX_STRING 32
#define DEF_LEN 80
...
lmbcs lpSectionName[MAX_STRING];
lmbcs lpKeyName[MAX_STRING];
lmbcs lpNewStr[DEF_LEN];
lbool Result;
LCT_STATUS Status;
...
strcpy(lpSectionName, "FILES");
strcpy(lpKeyName, "lastopen1");
strcpy(lpNewStr, "c:\windows\123w\newfile.wk3");
...
Status = LciUtSetLotusIniStr(Context, lpSectionName, lpKeyName,
lpNewStr, &Result);
Definition
Returns the size of the specified block. Works with allocated blocks using LciUtAllocBlock only.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtSizeOfBlock
(LCH_CONTEXT Context,
LCT_MMBP BlkPtr,
lptr(lsshort) Size)
Arguments
Context The context handle that was passed to the C program when 1-2-3 started.
BlkPtr Pointer to a block.
Size Block size returns here.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
...
lsshort Options;
lmbcs HeapName[16];
LCT_MMHEAP HeapHandle;
lslong Size;
LCT_MMBP BlkPtr;
LCT_STATUS Status;
...
Options = (MMSIZEKEPT | LCT_MMALLOCNOCCLEAR);
strcpy(HeapName,"myheap");
Size = 1024;
...
Status = LciUtCreateHeap(Context, Options, HeapName, &HeapHandle);
...
Status = LciUtAllocBlock(Context, HeapHandle, Size, &BlkPtr);
...
Status = LciUtSizeOfBlock(Context, BlkPtr, &Size);
Definition
Runs an operating system command from an add-in. This function is similar to the 1-2-3 System command except that you are limited to executing a single operating system command for each function call.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtSystem
(LCH_CONTEXT Context,
lptr(lmbcs) lpCommand)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpCommand Pointer to a lmbcs string that contains the operating system command you want to run.
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_SYSTEM_ERROR »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
. . .
LCT_STATUS Status;
. . .
Status = LciUtSystem(Context,"mkdir C:\\LOGS");
Definition
Retrieves the string that corresponds to the current version of 1-2-3 for Windows and the float that corresponds to the current version number of the libraries for the 1-2-3 for Windows add-in toolkit. For example, "123W release 4.00.00" is the string returned for the most recent release of 1-2-3 Release 4 for Windows, where 4.00.00 represents a major revision number of 1, a minor version of 0, and no sub-releases.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtVersion
(LCH_CONTEXT Context,
lushort BufLen,
lptr(lmbcs) lpProduct,
lptr(lfloat10) Library)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
BufLen Length of the output buffer, including the null-terminating byte.
lpProduct Pointer to a lmbcs string in which the product version string will be returned.
Library Pointer to an lfloat10 in which the library version number will be stored.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
. . .
LCT_STATUS Status;
lfloat10 LibVer;
lmbcs lpProdVer[40];
. . .
Status = LciUtVersion(Context, 40, lpProdVer, &LibVer);
if (strcmp(lpProdVer, "123W release 4.00.00") != 0)
{
/* If this is not the most recent release, then
do something special.
*/
}
Definition
LciUtYield provides a means of returning control to 1-2-3 for Windows so that its background tasks can proceed. Other reasons could be to allow 1-2-3 to manage input to a dialog box, or to let 1-2-3 respond to system messages during particularly long processes, such as a long calculation.
Do not use LciUtYield from a tool procedure that is used to run add-in dialogs. In addition, only use an LCE_POLL »Page event handler. Yield should only be used by those add-ins that run on their own stack. For those add-ins that consist primarily of functions driven by messages normally handled in a tool procedure, neither a separate stack nor LciUtYield is necessary.
LciUtYield usually returns an LCS_SUCCESS status. If for some reason it cannot return control to 1-2-3, it will either return LCS_INVALID_USE or LCS_OUT_OF_MEMORY. The first indicates that LciUtYield cannot be used under the current conditions; the second indicates that some needed resource could not be allocated -- either auxiliary storage or event registration.
The system cannot tolerate yielding during system startup (that is, the add-in is listed in [AUTOLOAD ADDINS] section of 123R4.INI). If it is necessary to yield during the AdnInitialize function, be sure to test the return status and have some fallback process if yielding is impossible. For example, one should test the status from LciUtYield and use default values if the attempt to yield fails.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUtYield
(LCH_CONTEXT Context)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciutil.h"
#include "lcievent.h"
#include "lcild.h"
. . .
LCT_STATUS LCI_CALL AdnMain(Context)
{
LCT_STATUS Status;
lsshort MySemaphore = 1;
LCH_REGISTRATION evReg = LNULL;
/* Register a poll event handler that performs a number of
calculations. */
Status = LciEvRegister(Context, PollHandler,
LCE_POLL, LCI_EV_BEFORE, &evReg);
Status = LciLdSetAddinData(Context,(lptr(void))&MySemaphore);
. . .
/* We are not done until MySemaphore is set to zero. */
while (MySemaphore)
Status = LciUtYield(Context);
. . .
Status = LciEvUnregister(Context, evReg);
. . .
} /* End of AdnMain */
. . .
LCT_STATUS LCI_CALL PollHandler(
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventID,
lushort TimeFlags,
lslong Arg)
{
LCT_STATUS Status;
lptr(lsshort) lpSemaphore;
Status = LciLdGetAddinData(Context, (lptr(lptr(void)))
(&lpSemaphore));
. . .
if ( /* We are still performing calculations. */){
/* Do some work. */
. . .
Return(LCS_SUCCESS);
}
else { /* The work is done. */
/* Set semaphore to fall out of while loop is in our
AdnMain. */
*lpSemaphore = 0;
}
return(LCS_SUCCESS);
} /* End of PollHandler*/
Definition
Calls a routine from the 123 stack environment.
Format
#include "lcicomn.h"
#include "lciutil.h"
LCT_STATUS LCI_CALL LciUt123EnvCall
(LCH_CONTEXT Context
ENVCALLPTR Routine,
lptr(void) Arglist)
where the callback function has the following specification:
LCT_STATUS (lptr(LCI_CALL) ENVCALLPTR)
(LCH_CONTEXT Context,
lptr(void) Arglist);
Arguments
Context The addin context
Routine A function pointer to the (pascal) routine to be called. The routine takes two arguments: the context and the pointer to a routine-specific structure.
Arglist A pointer to the routine-specific argument structure.
Returns
Whatever the routine returns.
Example
lushort hWnd; // set to window handle of the current tool window
LCT_STATUS LCI_CALL WinDialogBox
(LCH_CONTEXT Context, lptr(void) Arglist)
{
. . .
DialogBox (hModule, MAKEINTRESOURCE (ID_DIALOG_MEMO2), hWnd,
DialogFunc);
return LCS_SUCCESS;
}
LCT_STATUS FAR PASCAL EventHandler (
LCH_CONTEXT Context,
LCH_EVARG hEvArg,
lsshort EventId, // event ID #
lushort TimeFlags, // before or after
lslong Arg)
{
LCT_STATUS Status;
. . .
Status = LciUt123EnvCall(Context, WinDialogBox, LNULL);
. . .
}
You use the workfile objects to represent 1-2-3 worksheet files in your add-in. A data object that has type LCH_WORKFILE refers to a specific 1-2-3 worksheet file.
The WorkFile group also contains the functions you use to add, delete, and modify add-in records.
Function Meaning
LciWfCombine »Page Combines an entire source worksheet file on disk, or a range of values from that file, into the current worksheet file, using the cell pointer as the first cell location for new values.
LciWfConstructCurr »Page Constructs a workfile object that corresponds to the worksheet file the cell pointer currently resides in.
LciWfConstructName »Page Constructs a workfile object specified by filename.
LciWfDelete »Page Deletes a workfile from memory.
LciWfDeleteSheets »Page Deletes one or more worksheets from a specified workfile.
LciWfDestroy »Page Releases a workfile object handle.
LciWfErase »Page Erases a worksheet file on disk.
LciWfExtract »Page Saves the contents of a range in a specified workfile to a worksheet file on disk.
LciWfGetActiveFlag »Page Retrieves a value that indicates whether a workfile is in memory.
LciWfGetCalcIterCount »Page Returns the number of times 1-2-3 recalculates active files during the current session either when the recalculation order is set to Columnwise or Rowwise, or when recalculation is set to Natural and there is a circular reference.
LciWfGetCalcOrder »Page Retrieves the current setting for the order in which 1-2-3 recalculates worksheets in a specified workfile.
LciWfGetCalcType »Page Retrieves the current setting for the method 1-2-3 uses to recalculate worksheets in a specified workfile.
LciWfGetChangedFlag »Page Retrieves a value that indicates whether a specified active workfile has been modified since it was last saved.
LciWfGetContext »Page Retrieves the context handle corresponding to a specified workfile object handle.
LciWfGetDirPath »Page Retrieves the disk drive and path of a specified worksheet file.
LciWfGetExtension »Page Retrieves the extension of a specified workfile.
LciWfGetFullName »Page Retrieves the fully qualified pathname of a specified worksheet file.
LciWfGetGroupFlag »Page Retrieves group mode status.
LciWfGetLastCellAddr »Page Retrieves the address string of the last cell in the active area of a specified worksheet file.
LciWfGetLastCellCoords »Page Retrieves the location coordinates of the last cell in the active area of a specified worksheet file.
LciWfGetName »Page Retrieves the filename of a specified worksheet file, not including directory path or extension.
LciWfGetRangeName »Page Retrieves one of the range names associated with a workfile.
LciWfGetRangeNameCount »Page Retrieves the number of range names associated with a workfile.
LciWfGetReserveFlag »Page Retrieves the reservation status of a specified worksheet file.
LciWfGetReserveType »Page Retrieves a value that specifies whether a reservation is automatically available when you open or retrieve a file.
LciWfGetSealType »Page Retrieves a value indicating whether a worksheet file and/or the worksheet file reservation setting are sealed.
LciWfGetSheetCount »Page Retrieves the number of worksheets in a specified worksheet file.
LciWfImport »Page Reads text or numbers from a text file into a specified worksheet.
LciWfInsertSheet »Page Inserts one or more blank worksheets into a specified worksheet file, either before or after a specified sheet.
LciWfNew »Page Creates a new worksheet file containing one blank worksheet.
LciWfOpen »Page Reads a specified worksheet file from disk into a new window.
LciWfResetRangeNames »Page Deletes all range names in a workfile.
LciWfRetrieve »Page Reads a specified worksheet file from disk into memory in place of the current file.
LciWfSave »Page Saves a specified worksheet file and its settings to disk.
LciWfSetCalcIterCount »Page Sets the number of times 1-2-3 recalculates active files during the current session either when the recalculation order is set to Columnwise or Rowwise, or when recalculation is set to Natural and there is a circular reference.
LciWfSetCalcOrder »Page Sets the order in which 1-2-3 recalculates worksheets in a specified workfile.
LciWfSetCalcType »Page Sets the method 1-2-3 uses to recalculate worksheets in a specified workfile.
LciWfSetGroupFlag »Page Sets group mode on or off.
LciWfSetReserveFlag »Page Sets or releases a reservation.
LciWfSetReserveType »Page Specifies whether a reservation is automatically available when you open or retrieve a file.
LciWfSetSealType »Page Seals or unseals a worksheet file and/or the worksheet file reservation setting.
Add-In Record Functions
Function Meaning
LciWfDeleteAddinRecord »Page Deletes the current add-in record.
LciWfInsertAddinRecord »Page Inserts a record into the add-in record list in the workfile.
LciWfIterAddinRecords »Page Iterates through the list of add-in records in the workfile, using VendorID, if specified, as a filter. Calls the add-in's callback function with each record found.
LciWfReplaceAddinRecord »Page Modifies the current add-in record. The modified record is returned to the callback function on the next iteration.
Definition
Combines an entire source worksheet file on disk, or a range of values from that file, into the current worksheet file, using the cell pointer as the first cell location for new values.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfCombine
(LCH_WORKFILE Workfile,
lptr(lmbcs) lpPassword,
lptr(lmbcs) lpRangeAddr,
lulong OptionFlags)
Arguments
Workfile The handle of an existing workfile object.
lpPassword A pointer to the lmbcs string that contains the password (if necessary) for the disk file. Its length must not exceed LCI_MAX_PASSWORD_LEN. It can be LCI_NO_PASSWORD to not specify a password.
lpRangeAddr A pointer to the lmbcs string that contains the name or address string of a range, or LNULL to combine the entire disk file. The length must not exceed LCI_MAX_ADDR_LEN.
OptionFlags The type of combination desired. Possible values are:
Constant Meaning
LCI_COMBINE_ADD Add disk file values to the values in the current file.
LCI_COMBINE_COPY Replace the values in the current file with values from the disk file
LCI_COMBINE_SUBTRACT Subtract disk file values from the values in the current file.
Returns
LCS_SUCCESS »Page
LCS_DISK_ERROR »Page
LCS_FILE_NOT_FOUND »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_PASSWORD »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_INVALID_WORKFILE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_PASSWORD_REQUIRED »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCT_STATUS Status;
LCH_WORKFILE Wfile;
. . .
Status = LciWfConstructName(Context,"EXPENSES.WK3",&Wfile);
Status = LciWfCombine(Wfile,LCI_NO_PASSWORD,LNULL,
LCI_COMBINE_COPY);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Constructs a workfile object that corresponds to the worksheet file the cell pointer currently resides in.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfConstructCurr
(LCH_CONTEXT Context,
lptr(LCH_WORKFILE) lpWorkfile)
Arguments
Context The context that was passed to the C program when 1-2-3 invoked it.
lpWorkfile A pointer to storage in which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCT_STATUS Status;
LCH_WORKFILE Wfile;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Constructs a workfile object specified by filename.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfConstructName
(LCH_CONTEXT Context,
lptr(lmbcs) lpFileName,
lptr(LCH_WORKFILE) lpWorkfile)
Arguments
Context The context that was passed to the C program when 1-2-3 invoked it.
lpFileName The name of the workfile. It can be LCI_UNTITLED_WORKFILE to specify the untitled workfile, or LCI_CURRENT_WORKFILE to specify the current workfile. Its length must not exceed LCI_MAX_FILENAME_LEN.
lpWorkfile A pointer to storage in which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_INVALID_FILENAME »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lmbcs lpFileName[] = "C:\\123W\\FILES\\BUDGET.WK3";
. . .
Status = LciWfConstructName(Context,lpFileName,&Wfile);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Deletes a workfile from memory. This is the same function as File Close except that it closes the file without prompting the user to save it under any circumstances.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfDelete
(LCH_WORKFILE Workfile)
Arguments
Workfile The handle of an existing workfile object.
Returns
LCS_SUCCESS »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCT_STATUS Status;
LCH_WORKFILE Wfile;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfDelete(Wfile);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Deletes the current add-in record.
Note You must determine the pointer and length values of the current add-in record with LciWfIterAddinRecords »Page before you use this function. The callback function must have control for you to use this function. If the callback function is called with Null pointer and length values, the list is empty or you are at the end of the list. The only operation that can be performed in this case is inserting a record before the current record (LciWfInsertAddinRecord »Page ).
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfDeleteAddinRecord
(LCH_WORKFILE Workfile)
Arguments
Workfile The handle of an existing workfile object.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_REQUEST_REFUSED »Page -Returned if not in an iterator function.-
LCS_RECORD_NOT_FOUND »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCH_STATUS Status;
. . .
Status = LciWfIterAddinRecords(Wfile,LNULL,&CallbackFunc,LNULL);
. . .
LCT_STATUS LCI_CALL CallbackFunc(
LCH_WORKFILE hWf
lptr(void) Record,
lushort Len,
lulong Data)
{
/* Delete all add-in records. */
LciWfDeleteAddinRecord(hWf);
Definition
Deletes one or more worksheets from a specified workfile. The first sheet in a workfile starts at 1.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfDeleteSheets
(LCH_WORKFILE Workfile,
lushort FirstSheetNum,
lushort SheetCount)
Arguments
Workfile The handle of an existing workfile object.
FirstSheetNum The worksheet number of the first worksheet to delete.
SheetCount The number of worksheets to delete.
Returns
LCS_SUCCESS »Page
LCS_INVALID_COUNT »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_OUT_OF_MEMORY »Page
LCS_PROTECTED_SHEET »Page
LCS_STACK_OVERFLOW »Page
LCS_TOO_FEW_SHEETS »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCT_STATUS Status;
LCH_WORKFILE Wfile;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfDeleteSheets(Wfile,2,10);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Releases a workfile object handle.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfDestroy
(lptr(LCH_WORKFILE) lpWorkfile)
Arguments
lpWorkfile A pointer to an existing workfile object handle, which this call sets to LNULL.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCT_STATUS Status;
LCH_WORKFILE Wfile;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Erases a worksheet file on disk.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfErase
(LCH_WORKFILE Workfile)
Arguments
Workfile The handle of an existing workfile object.
Returns
LCS_SUCCESS »Page
LCS_DISK_ERROR »Page
LCS_FILE_IN_USE »Page
LCS_FILE_NOT_FOUND »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCT_STATUS Status;
LCH_WORKFILE Wfile;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfErase(Wfile);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Saves the contents of a range in a specified workfile to a worksheet file on disk. Saves either formulas or values and all associated settings.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfExtract
(LCH_WORKFILE Workfile,
lptr(lmbcs) lpRangeAddr,
lptr(lmbcs) lpFileName,
lptr(lmbcs) lpPassword,
lulong OptionFlags)
Arguments
Workfile The handle of an existing workfile object.
lpRangeAddr A pointer to a lmbcs string that contains the name or address string of a range in the workfile. Its length must not exceed LCI_MAX_ADDR_LEN.
lpFileName A pointer to a lmbcs string that contains the pathname of the disk file to extract to, or LCI_CURRENT_WORKFILE to extract to the disk file associated with the current workfile in memory. LCI_CURRENT_WORKFILE is not allowed for a file created by LciWfNew »Page that has not previously been saved. The length of the filename must not exceed LCI_MAX_FILENAME_LEN.
lpPassword A pointer to a lmbcs string that contains the password (if necessary) for the disk file. Its length must not exceed LCI_MAX_PASSWORD_LEN. It can be LCI_NO_PASSWORD to not specify a password.
OptionFlags Must contain two enums OR'd together as follows:
(1) The type of extraction desired. Possible values are:
Constant Meaning
LCI_EXTRACT_FORMULAS Saves formulas, labels, and values.
LCI_EXTRACT_VALUES Saves only labels and values. Converts formulas to numbers.
(2) The write-type argument. Possible values are:
Constant Meaning
LCI_WRITE_NEW Creates a new worksheet file.
LCI_WRITE_REPLACE Overwrites the existing version of the file.
LCI_WRITE_BACKUP Backs up the existing version of the file before saving it.
Returns
LCS_SUCCESS »Page
LCS_ALREADY_EXISTS »Page
LCS_DISK_ERROR »Page
LCS_KEY_BREAK »Page
LCS_FILE_NOT_FOUND »Page
LCS_INCORRECT_EXTRACT_TYPE »Page
LCS_INCORRECT_WRITE_TYPE »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_PASSWORD »Page
LCS_INVALID_RANGE »Page
LCS_INVALID_USE »Page
LCS_INVALID_WORKFILE »Page
LCS_NOT_IN_MEMORY »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lmbcs lpRange[] = "EXTRACT";
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfExtract(Wfile,lpRange,LCI_CURRENT_WORKFILE,
LCI_NO_PASSWORD,
LCI_EXTRACT_VALUES | LCI_WRITE_REPLACE);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves a flag that is LTRUE if a workfile is active (in memory); LFALSE otherwise.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetActiveFlag
(LCH_WORKFILE Workfile,
lptr(lbool) lpActiveFlag)
Arguments
Workfile The handle of an existing workfile object.
lpActiveFlag A pointer to an lbool in which to return the flag.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lbool Result;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetActiveFlag(Wfile,&result);
/* If result isn't TRUE, something is very wrong. */
if (Result != LTRUE) return (LCS_INTERNAL_ERROR);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves the number of times 1-2-3 recalculates active files during the current session either when the recalculation order is set to Columnwise or Rowwise, or when recalculation is set to Natural and there is a circular reference. The value is an integer between 1 and 50, inclusive. The default value is one.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetCalcIterCount
(LCH_WORKFILE Workfile,
lptr(lushort) lpCalcIterCount)
Arguments
Workfile The handle of an existing workfile object.
lpCalcIterCount A pointer to an lushort in which to return the count.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lushort Result;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetCalcIterCount(Wfile,&Result);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves the current setting for the order in which 1-2-3 recalculates worksheets in a specified workfile.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetCalcOrder
(LCH_WORKFILE Workfile,
lptr(lushort) lpCalcOrder)
Arguments
Workfile The handle of an existing workfile object.
lpCalcOrder A pointer to an lushort in which to return the recalc order. Possible values are:
Constant Meaning
LCI_CALC_ORDER_COLWISE Recalculation by column.
LCI_CALC_ORDER_ROWWISE Recalculation by row.
LCI_CALC_ORDER_NATURAL Natural recalculation.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lushort Result;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetCalcOrder(Wfile,&Result);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves the current setting for the method 1-2-3 uses to recalculate worksheets in a specified workfile.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetCalcType
(LCH_WORKFILE Workfile,
lptr(lushort) lpCalcType)
Arguments
Workfile The handle of an existing workfile object.
lpCalcType A pointer to an lushort in which to return the recal method. Possible values are:
Constant Meaning
LCI_CALC_TYPE_AUTO Automatic recalculation.
LCI_CALC_TYPE_MANUAL Manual recalculation.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lushort Result;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetCalcType(Wfile,&Result);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves a flag that is LTRUE if a specified active workfile has been modified since it was last saved; LFALSE otherwise.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetChangedFlag
(LCH_WORKFILE Workfile,
lptr(lbool) lpChangedFlag)
Arguments
Workfile The handle of an existing workfile object.
lpChangedFlag A pointer to an lbool in which to return the changed flag.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lbool Result;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetChangedFlag(Wfile,&Result);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves the context handle corresponding to a workfile object handle.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCI_STATUS LCI_CALL LciWfGetContext
(LCH_WORKFILE Workfile,
lptr(LCH_CONTEXT) lpContext)
Arguments
Workfile The handle of an existing workfile object.
lpContext A pointer to storage in which to store the context handle.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCH_CONTEXT WfileContext;
LCT_STATUS Status;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
. . .
Status = LciWfGetContext(Wfile,&WfileContext);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves the disk drive and path of a specified worksheet file.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetDirPath
(LCH_WORKFILE Workfile,
lushort BufLen,
lptr(lmbcs) lpDirPath)
Arguments
Workfile The handle of an existing workfile object.
BufLen The number of bytes available in the buffer pointed to by lpDirPath, including room for a null-terminating byte. This value need not be greater than LCI_MAX_DIRNAME_LEN.
lpDirPath A pointer to a lmbcs string in which to return the path without the trailing backslash (\).
Returns
LCS_SUCCESS »Page
LCS_INVALID_FILENAME »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lmbcs lpResult[LCI_MAX_DIRNAME_LEN];
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetDirPath(Wfile,LCI_MAX_DIRNAME_LEN,lpResult);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves the extension of a specified workfile.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetExtension
(LCH_WORKFILE Workfile,
lushort BufLen,
lptr(lmbcs) lpExtension)
Arguments
Workfile The handle of an existing workfile object.
BufLen The number of bytes available in the buffer pointed to by lpExtension, including room for a null-terminating byte. This value need not be greater than LCI_MAX_FILEEXT_LEN.
lpExtension A pointer to a lmbcs string in which to return the file extension.
Returns
LCS_SUCCESS »Page
LCS_INVALID_FILENAME »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lmbcs lpResult[LCI_MAX_FILEEXT_LEN];
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetExtension(Wfile,4,lpResult);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves the fully qualified pathname of a specified worksheet file.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetFullName
(LCH_WORKFILE Workfile,
lulong BufLen,
lptr(lmbcs) lpFullName)
Arguments
Workfile The handle of an existing workfile object.
BufLen The number of bytes available in the buffer pointed to by lpFullName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_FILENAME_LEN.
lpFullName A pointer to a lmbcs string in which to return the full filename, including path and extension.
Returns
LCS_SUCCESS »Page
LCS_INVALID_FILENAME »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lmbcs lpResult[LCI_MAX_FILENAME_LEN];
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetFullName(Wfile,LCI_MAX_FILENAME_LEN,lpResult);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves a flag that is LTRUE if group mode is currently on; LFALSE otherwise.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetGroupFlag
(LCH_WORKFILE Workfile,
lptr(lbool) lpGroupFlag)
Arguments
Workfile The handle of an existing workfile object.
lpGroupFlag A pointer to an lbool in which to return the flag.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lbool Result;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetGroupFlag(Wfile,&Result);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves the address string of the last cell in the active area of a specified worksheet file.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetLastCellAddr
(LCH_WORKFILE Workfile,
lushort BufLen,
lptr(lmbcs) lpAddr)
Arguments
Workfile The handle of an existing workfile object.
BufLen The number of bytes available in the buffer pointed to by lpAddr, including room for a null-terminating byte. This value need not be greater than LCI_MAX_CELLADDR_LEN.
lpAddr A pointer to a lmbcs string in which to return the address string.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lushort Buflen;
lmbcs lpCellAddr[LCI_MAX_CELLADDR_LEN];
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Buflen = LCI_MAX_CELLADDR_LEN;
Status = LciWfGetLastCellAddr(Wfile,Buflen,lpCellAddr);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves the location coordinates of the last cell in the active area of a specified worksheet file.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetLastCellCoords
(LCH_WORKFILE Workfile,
lushort BufLen,
lptr(lmbcs) lpFileName,
lptr(lushort) lpSheetNum,
lptr(lushort) lpColNum,
lptr(lushort) lpRowNum)
Arguments
Workfile The handle of an existing workfile object.
BufLen The number of bytes available in the buffer pointed to by lpFileName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_FILENAME_LEN.
lpFileName A pointer to a lmbcs string in which to return the filename.
lpSheetNum Pointer to an lushort in which to return the sheet number.
lpColNum Pointer to an lushort in which to return the column number.
lpRowNum Pointer to an lushort in which to return the row number.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lmbcs lpFileName[LCI_MAX_FILENAME_LEN];
lushort SheetNum;
lushort ColNum;
lushort RowNum;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetLastCellCoords(Wfile,LCI_MAX_FILENAME_LEN,
lpFileName,&SheetNum,
&ColNum,&RowNum);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves the filename of a specified worksheet file, not including directory path or extension.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetName
(LCH_WORKFILE Workfile,
lushort BufLen,
lptr(lmbcs) lpFileName)
Arguments
Workfile The handle of an existing workfile object.
BufLen The number of bytes available in the buffer pointed to by lpFileName, including room for a null-terminating byte. This value should not be greater than LCI_MAX_FILENAME_LEN.
lpFileName A pointer to a lmbcs string in which to return the filename, without the path or extension.
Returns
LCS_SUCCESS »Page
LCS_INVALID_FILENAME »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lmbcs lpFileName[LCI_MAX_FILENAME_LEN];
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetName(Wfile,LCI_MAX_FILENAME_LEN,lpFileName);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves one of the range names associated with a workfile. Call LciWfGetRangeNameCount »Page to find out how many names there are.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetRangeName
(LCH_WORKFILE Workfile,
lushort Index,
lushort Buflen,
lptr(lmbcs) lpRangeName)
Arguments
Workfile The handle of an existing workfile object.
Index A one-based number specifying which name to return.
BufLen The number of bytes available in the buffer pointed to by lpRangeName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_RANGENAME_LEN.
lpRangeName A pointer to a lmbcs string in which to return the name.
Returns
LCS_NOT_IN_MEMORY »Page
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
LCS_INVALID_SIZE »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lushort NumRanges;
lushort index;
lmbcs lpRangeName[LCI_MAX_RANGENAME_LEN];
. . .
/* Retrieve all ranges for current workfile. */
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetRangeNameCount(Wfile,&NumRanges);
for (index = 1; index <= NumRanges; index++)
{
LciWfGetRangeName(Wfile,index,LCI_MAX_RANGENAME_LEN,
lpRangeName);
. . .
}
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves the number of range names associated with a workfile. Call LciWfGetRangeName »Page to get the actual names.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetRangeNameCount
(LCH_WORKFILE Workfile,
lptr(lushort) lpNameCount)
Arguments
Workfile The handle of an existing workfile object.
lpNameCount A pointer to an lushort in which to return the count.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lushort NumRanges;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetRangeNameCount(Wfile,&NumRanges);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves LTRUE if the caller has the reservation to a specified worksheet file, LFALSE otherwise.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetReserveFlag
(LCH_WORKFILE Workfile,
lptr(lbool) lpReserveFlag)
Arguments
Workfile The handle of an existing workfile object.
lpReserveFlag A pointer to an lbool in which to return the flag.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lbool Result;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetReserveFlag(Wfile,&Result);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves a value that indicates whether a reservation is automatically available when you open or retrieve a file.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetReserveType
(LCH_WORKFILE Workfile,
lptr(lushort) lpReserveFlag)
Arguments
Workfile The handle of an existing workfile object.
lpReserveFlag A pointer to an lushort in which to return the reserve type. Possible values are:
Constant Meaning
LCI_RESERVE_TYPE_AUTO Reservation is automatically obtained, if available.
LCI_RESERVE_TYPE_MANUAL Reservation must be obtained by setting RESERVED function.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lushort Result;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetReserveType(Wfile,&Result);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves a value that indicates whether a worksheet file and/or the worksheet file reservation setting are sealed.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetSealType
(LCH_WORKFILE Workfile,
lptr(lushort) lpSealType)
Arguments
Workfile The handle of an existing workfile object.
lpSealType A pointer to an lushort in which to return the seal type. Possible values are:
Constant Meaning
LCI_SEAL_FILE The file and the reservation setting are sealed.
LCI_SEAL_RESERVATION Only the reservation setting is sealed.
LCI_SEAL_NONE Neither the file nor the reservation setting is sealed.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lushort Result;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetSealType(Wfile,&Result);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Retrieves the number of worksheets in a specified worksheet file.
Format
#include "lcicomm.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfGetSheetCount
(LCH_WORKFILE Workfile,
lptr(lushort) lpSheetCount)
Arguments
Workfile The handle of an existing workfile object.
lpSheetCount A pointer to an lushort in which to return the number of worksheets.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lushort SheetCount;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfGetSheetCount(Wfile,&SheetCount);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Reads text or numbers from a text file into a specified worksheet.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfImport
(LCH_WORKFILE Workfile,
lptr(lmbcs) lpFileName,
lulong OptionFlags)
Arguments
Workfile The handle of an existing workfile object.
lpFileName A pointer to a lmbcs string that contains the pathname of a disk file to import, or LCI_CURRENT_WORKFILE to import the disk file associated with the current workfile in memory. The length of the filename must not exceed LCI_MAX_FILENAME_LEN.
OptionFlags The type of import desired. Possible values are:
Constant Meaning
LCI_IMPORT_TEXT Import text.
LCI_IMPORT_NUMBERS Import numbers.
Returns
LCS_SUCCESS »Page
LCS_DISK_ERROR »Page
LCS_FILE_NOT_FOUND »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_READ_ERROR »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfImport(Wfile,LCI_CURRENT_WORKFILE,
LCI_IMPORT_NUMBERS);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Inserts a record into the add-in record list. If fBefore is LTRUE, the record is inserted before the current record. If the current record is the empty list head, the record will become the first record. If fBefore is LFALSE, the record is inserted after the current record. Insertions after the current record are not permitted if the current record is null (at the start of an empty list or past the last record in the list). If attempted, the function returns the status message LCS_RECORD_NOT_FOUND.
Note You must determine the pointer and length values of the current add-in record with LciWfIterAddinRecords »Page before you use this function. The callback function must have control for you to use this function. If the callback function is called with LNULL pointer and length values, the list is empty or you are at the end of the list. The only operation that can be performed in this case is inserting a record before the current record.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfInsertAddinRecord
(LCH_WORKFILE Workfile,
lptr(void) lpRecordBody,
lushort RecordLen,
lbool fBefore )
Arguments
Workfile The handle of an existing workfile object.
lpRecordBody A copy of the in-memory record (only available for the duration of the callback function)
RecordLen Length of the in-memory record
fBefore A boolean that corresponds to the placement of the new record (LTRUE for before the current record; LFALSE for after the current record)
Returns
LCS_SUCCESS »Page
LCS_NULL_HANDLE »Page
LCS_NOT_IN_MEMORY »Page
LCS_OUT_OF_MEMORY »Page
LCS_REQUEST_REFUSED »Page -If not in an iterator function.-
LCS_RECORD_NOT_FOUND »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
typedef struct _ADN_REC {
lushort subtype;
lubyte VendorID[4];
lushort version;
lubyte recdata[MAX_REC_DATA_LEN];
} ADNREC;
. . .
LCT_STATUS Status;
LCH_WORKFILE Wfile;
Status = LciWfConstructCurr(Context, &Wfile);
/* Iterate through add-in records to insert a record. */
Status = LciWfIterAddinRecords(Wfile, LNULL, &CallbackFunc, LNULL);
. . .
LCT_STATUS LCI_CALL CallbackFunc(
LCH_WORKFILE hWf,
lptr(lvoid) Record,
lushort Len,
lulong Data)
{
ADNREC AdnRecord;
LCT_STATUS Status;
/* Fill in the add-in record */
AdnRecord.subtype = 0xFFFF;
AdnRecord.version = 0;
strncpy(&AdnRecord.VendorID, "ADN1", 4);
/* Record data is range count for the file. */
LciWfGetRangeNameCount(hWf,
(lptr(lushort))
(&AdnRecord.recdata));
/* Insert the record. */
Status = LciWfInsertAddinRecord(hWf, &AdnRecord,
sizeof(ADNREC), LTRUE);
. . .
}
Definition
Inserts one or more blank worksheets into a specified worksheet file, either before or after a specified sheet.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfInsertSheet
(LCH_WORKFILE Workfile,
lushort StartSheetNum,
lushort SheetCount,
lushort PositionType)
Arguments
Workfile The handle of an existing workfile object.
StartSheetNum The one-based number of the worksheet to insert before or after.
SheetCount The number of worksheets to insert.
PositionType The position type argument. Possible values are:
Constant Meaning
LCI_POSITION_AFTER Insert after StartSheetNum.
LCI_POSITION_BEFORE Insert before StartSheetNum.
Returns
LCS_SUCCESS »Page
LCS_INVALID_COUNT »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_TOO_MANY_SHEETS »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
. . .
/* Insert 10 sheets after the second sheet in the current
workfile. */
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfInsertSheet(Wfile,2,10,LCI_POSITION_AFTER);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Iterates through a list of add-in records matching the VendorId in the workfile. If VendorId is LNULL, the function returns all records. If VendorId is not LNULL, only those records with matching add-in identifiers are returned. The function iterates through the entire list, or until the callback function returns a status not equal to LCS_SUCCESS. When the iterator terminates and returns to its caller, the iterator resets itself so that a subsequent call will start the process from the beginning of the list.
At the end of the list, or at the start of an empty list, the callback function is called exactly once with null values for pointer and length.
When the callback function is called with non-null pointer and length values, it can delete the record (LciWfDeleteAddinRecord »Page ), insert a new record before or after the current record (LciWfInsertAddinRecord »Page ), or modify the current record (LciWfReplaceAddinRecord »Page ). These record processing routines are only available while the callback function has control.
When the callback function is called with Null pointer and length values, the list is empty or you are at the end of the list. The only operation that can be performed in this case is inserting a record before the current record (LciWfInsertAddinRecord).
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfIterAddinRecords
(LCH_WORKFILE Workfile,
lptr(lubyte) lpVendorId,
LCT_REC_FPTR CallbackFunc,
lulong CallbackData)
where the Callback function has the following specification
LCT_STATUS CallbackFunc
(LCH_WORKFILE Workfile,
lptr(void) lpRecordBody,
lushort RecordLen,
lulong CallbackData)
Arguments
Workfile The handle of an existing workfile object.
lpVendorId A pointer to a lubyte array[4].
lpRecordBody A pointer to a copy of the in-memory record (only available for the duration of the callback function).
RecordLen Length of the record.
CallbackData The callback data passed to LciWfIterAddinRecords.
Returns
LCS_SUCCESS »Page
LCS_NULL_HANDLE »Page
LCS_NOT_IN_MEMORY »Page
LCS_OUT_OF_MEMORY »Page
LCS_REQUEST_REFUSED »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
#define REC_DELETE 0
#define REC_INSERT 1
. . .
LCT_STATUS Status;
LCH_WORKFILE Wfile;
/* Iterate through add-in records to delete. */
Status = LciWfConstructCurr(Context, &Wfile);
Status = LciWfIterAddinRecords(Wfile, LNULL, &CallbackFunc,
REC_DELETE);
. . .
/* Iterate through the add-in records to insert. */
Status = LciWfIterAddinRecords(Wfile, "MEMO", &CallbackFunc,
REC_INSERT);
. . .
LCT_STATUS LCI_CALL CallbackFunc(
LCH_WORKFILE hWf,
lptr(void) Record,
lushort Len,
lulong Data)
{
. . .
/* Switch on data to determine operation. */
switch(Data){
case REC_DELETE:
. . .
break;
case REC_INSERT:
. . .
break;
}
. . .
} /* End of callbackFunc */
Definition
Creates a new worksheet file containing one blank worksheet.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfNew
(LCH_WORKFILE Workfile,
lulong OptionFlags)
Arguments
Workfile The handle of an existing workfile object.
OptionFlags Can be:
Constant Meaning
LCI_NEW_BEFORE Places the new workfile before the current workfile; otherwise, it is placed after the current workfile.
Note In 1-2-3 for Windows, opening a new file always opens a new MDI window. Therefore, this option has no real relevance and is here for the sake of compatibility with previous releases of 1-2-3.
Returns
LCS_SUCCESS »Page
LCS_ALREADY_EXISTS »Page
LCS_DISK_ERROR »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lmbcs lpFileName[] = "myfile.wk3";
Status = LciWfConstructName(Context, lpFileName, &Wfile);
Status = LciWfNew(Wfile, LCI_NEW_BEFORE);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Reads a specified worksheet file from disk into a new window. Upon opening, the new worksheet file becomes the current window.
Note Due to changes in the C user interface, add-in developers must now include the extension when calling LciWfOpen and passing it a lmbcs string. The extension must be included to successfully open the workfile.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfOpen
(LCH_WORKFILE Workfile,
lptr(lmbcs) lpPassword,
lulong OptionFlags)
Arguments
Workfile The handle of an existing workfile object.
lpPassword A pointer to a lmbcs string that contains the password (if necessary) for the disk file. Its length must not exceed LCI_MAX_PASSWORD_LEN. It can be LCI_NO_PASSWORD to not specify a password.
OptionFlags One of the following values:
Constant Meaning
LCI_OPEN_RESERVE Notification is desired if the file is open without a reservation.
LCI_OPEN_NO_RESERVE No notification is required if the file is opened without a reservation.
Note If LCI_OPEN_RESERVE is specified, LCS_SUCCESS indicates that the file was retrieved with a reservation; LCS_UNABLE_TO_RESERVE indicates that someone else has the reservation and the file is not opened; LCS_MANUAL_RESERVATION indicates that a reservation was not automatically obtained, but the file was opened into memory. For the latter case, LciWfSetReserveFlag »Page can be used to get a reservation on the opened file. Also, if desired, LciWfSetReserveType »Page can be used to set an automatic reservation for the next open of the file.
Returns
LCS_SUCCESS »Page
LCS_ALREADY_IN_MEMORY »Page
LCS_DISK_ERROR »Page
LCS_FILE_NOT_FOUND »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_PASSWORD »Page
LCS_INVALID_USE »Page
LCS_MANUAL_RESERVATION »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_UNABLE_TO_RESERVE »Page
LCS_PASSWORD_REQUIRED »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lmbcs lpFileName[] = "nasales.wk3";
. . .
Status = LciWfConstructName(Context,lpFileName,&Wfile);
Status = LciWfOpen(Wfile,LCI_NO_PASSWORD,LCI_OPEN_RESERVE);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Modifies the current add-in record. The modified record is returned to the callback function on the next iteration.
Note You must determine the pointer and length values of the current add-in record with LciWfIterAddinRecords »Page before you use this function. The callback function must have control for you to use this function. If the callback function is called with null pointer and length values, the list is empty or you are at the end of the list. The only operation that can be performed in this case is inserting a record before the current record (LciWfInsertAddinRecord »Page ).
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfReplaceAddinRecord
(LCH_WORKFILE Workfile,
lptr(lubyte) lpRecordBody,
lushort RecordLen )
Arguments
Workfile The handle of an existing workfile object.
lpRecordBody A copy of the in-memory record (only available for the duration of the callback function).
RecordLen Length of the in-memory record.
Returns
LCS_SUCCESS »Page
LCS_NULL_HANDLE »Page
LCS_NOT_IN_MEMORY »Page
LCS_OUT_OF_MEMORY »Page
LCS_REQUEST_REFUSED »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCT_STATUS Status;
ADNREC NewRecord;
{
ADNREC AdnRecord;
LCT_STATUS Status;
/* Fill in the add-in record. */
AdnRecord.subtype = 0xFFFF;
AdnRecord.version = 0;
strncpy(&AdnRecord.VendorID, "ADN1", 4);
/* Record data is range count for the file. */
LciWfGetRangeNameCount(hWf,
(lptr(lushort))
(&AdnRecord.recdata));
/* Insert the record. */
Status = LciWfReplaceAddinRecord(hWf, &NewRecord, sizeof
(ADNREC), LTRUE);
. . .
}
Definition
Deletes all range names in a workfile.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfResetRangeNames
(LCH_WORKFILE Workfile)
Argument
Workfile The handle of an existing workfile object.
Returns
LCS_SUCCESS »Page
LCS_FILE_SEALED »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_NOT_IN_MEMORY »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfResetRangeNames(Wfile);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Reads a specified worksheet file from disk into memory in place of the current file.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfRetrieve
(LCH_WORKFILE Workfile,
lptr(lmbcs) lpPassword,
lulong OptionFlags)
Arguments
Workfile The handle of an existing workfile object.
lpPassword A pointer to the lmbcs string that contains the password (if necessary) for the disk file. Its length must not exceed LCI_MAX_PASSWORD_LEN. It can be LCI_NO_PASSWORD to not specify a password.
OptionFlags Can be as follows:
Constant Meaning
LCI_RETRIEVE_RESERVE Notification is desired if the file is retrieved without a reservation.
LCI_RETRIEVE_NO_RESERVE No notification is required if the file is retrieved without a reservation.
Note If LCI_RETRIEVE_RESERVE is specified, LCS_SUCCESS indicates that the file was retrieved with a reservation; LCS_UNABLE_TO_RESERVE indicates that someone else has the reservation, and the file is not retrieved; LCS_MANUAL_RESERVATION indicates that a reservation was not automatically obtained, but the file was retrieved into memory. For the latter case, LciWfSetReserveFlag »Page can be used to get a reservation on the retrieved file. Also, if desired, LciWfSetReserveType »Page can be used to set an automatic reservation for the next retrieve of the file.
Returns
LCS_SUCCESS »Page
LCS_ALREADY_IN_MEMORY »Page
LCS_DISK_ERROR »Page
LCS_FILE_NOT_FOUND »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_PASSWORD »Page
LCS_INVALID_USE »Page
LCS_INVALID_WORKFILE »Page
LCS_MANUAL_RESERVATION »Page
LCS_OUT_OF_MEMORY »Page
LCS_PASSWORD_REQUIRED »Page
LCS_STACK_OVERFLOW »Page
LCS_UNABLE_TO_RESERVE »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
lmbcs lpFileName[] = "nasales.wk3";
. . .
Status = LciWfConstructName(Context, lpFileName, &Wfile);
Status = LciWfRetrieve(Wfile, LCI_NO_PASSWORD,
LCI_RETRIEVE_RESERVE);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Saves a specified worksheet file and its settings to disk.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfSave
(LCH_WORKFILE Workfile,
lptr(lmbcs) lpFileName,
lptr(lmbcs) lpPassword,
lulong OptionFlags)
Arguments
Workfile The handle of an existing workfile object.
lpFileName A pointer to a lmbcs string that contains the pathname of a file, or LCI_CURRENT_WORKFILE to save to the file associated with the workfile. LCI_CURRENT_WORKFILE is not allowed for a file created by LciWfNew »Page that has not previously been saved. The length of the filename must not exceed LCI_MAX_FILENAME_LEN.
lpPassword A pointer to a lmbcs string that contains the password (if necessary) for the save file. Its length must not exceed LCI_MAX_PASSWORD_LEN. It can be LCI_NO_PASSWORD to not specify a password.
OptionFlags The save type argument. The values for NEW, REPLACE, or BACKUP can be OR'd with the values for file format. If none of the file format types are specified, the file will be written in the default format. Possible values are:
Constant Meaning
LCI_WRITE_NEW Creates a new worksheet file.
LCI_WRITE_REPLACE Overwrites the existing version of the file.
LCI_WRITE_BACKUP Backs up the existing version of the file before saving it.
LCI_WRITE_NS4 Write in 1-2-3 Release 4 for Windows shared format.
LCI_WRITE_WK1 Write in 1-2-3 Release 2.x for DOS compatible format.
LCI_WRITE_WK3 Write in 1-2-3 Release 3.x for DOS and 1-2-3 for Windows Release 1.x compatible format.
LCI_WRITE_WK4 Write in 1-2-3 Release 4 for Windows compatible format.
LCI_WRITE_TXT Write as a text file (.prn or .txt).
Returns
LCS_SUCCESS »Page
LCS_KEY_BREAK »Page
LCS_ALREADY_EXISTS »Page
LCS_DISK_ERROR »Page
LCS_FILE_NOT_FOUND »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_PASSWORD »Page
LCS_INVALID_USE »Page
LCS_INCORRECT_WRITE_TYPE »Page
LCS_NOT_IN_MEMORY »Page
LCS_NOT_RESERVED »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_WRITE_ERROR »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfSave(Wfile,LCI_CURRENT_WORKFILE,LCI_NO_PASSWORD,
LCI_WRITE_REPLACE|LCI_WRITE_WK3);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Sets the number of times 1-2-3 recalculates active files during the current session either when the recalculation order is set to Columnwise or Rowwise, or when recalculation is set to Natural and there is a circular reference. The value is an integer between 1 and 50, inclusive. The default value is one.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfSetCalcIterCount
(LCH_WORKFILE Workfile,
lushort CalcIterCount)
Arguments
Workfile The handle of an existing workfile object.
CalcIterCount The desired number of iterations.
Returns
LCS_SUCCESS »Page
LCS_INVALID_COUNT »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfNew(Wfile,10);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Sets the order in which 1-2-3 recalculates worksheets in a specified workfile.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfSetCalcOrder
(LCH_WORKFILE Workfile,
lushort CalcOrder)
Arguments
Workfile The handle of an existing workfile object.
CalcOrder The desired calculation order. Possible values are:
Constant Meaning
LCI_CALC_ORDER_COLWISE Recalculation by column.
LCI_CALC_ORDER_ROWWISE Recalculation by row.
LCI_CALC_ORDER_NATURAL Natural recalculation.
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfSetCalcOrder(Wfile,LCI_CALC_ORDER_NATURAL);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Sets the method 1-2-3 uses to recalculate worksheets in a specified workfile.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfSetCalcType
(LCH_WORKFILE Workfile,
lushort CalcType)
Arguments
Workfile The handle of an existing workfile object.
CalcType The desired calculation method. Possible values are:
Constant Meaning
LCI_CALC_TYPE_AUTO Automatic recalculation.
LCI_CALC_TYPE_MANUAL Manual recalculation.
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfSetCalcType(Wfile,LCI_CALC_TYPE_AUTO);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Sets group mode on or off.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfSetGroupFlag
(LCH_WORKFILE Workfile,
lbool GroupFlag)
Arguments
Workfile The handle of an existing workfile object.
GroupFlag The desired flag value: LTRUE to turn group mode on; LFALSE to turn it off.
Returns
LCS_SUCCESS »Page
LCS_ALREADY_GROUPED »Page
LCS_FILE_SEALED »Page
LCS_INVALID_USE »Page
LCS_NOT_GROUPED »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfSetGroupFlag(Wfile,LTRUE);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Sets or releases a reservation for a specified workfile.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfSetReserveFlag
(LCH_WORKFILE Workfile,
lbool ReserveFlag)
Arguments
Workfile The handle of an existing workfile object.
ReserveFlag The desired flag value: LTRUE to reserve a workfile; LFALSE to release a reservation.
Returns
LCS_SUCCESS »Page
LCS_ALREADY_RESERVED »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_USE »Page
LCS_NOT_RESERVED »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_UNABLE_TO_RESERVE »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfSetReserveFlag(Wfile,LTRUE);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Specifies whether a reservation is automatically available when you open or retrieve a file.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfSetReserveType
(LCH_WORKFILE Workfile,
lushort ReserveType)
Arguments
Workfile The handle of an existing workfile object.
ReserveType The reserve type setting. Possible values are:
Constant Meaning
LCI_RESERVE_TYPE_AUTO Reservation is automatically obtained, if available.
LCI_RESERVE_TYPE_MANUAL Reservation must be obtained by using RESERVED command or function.
Returns
LCS_SUCCESS »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_INVALID_USE »Page
LCS_FILE_SEALED »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfSetReserveType(Wfile,LCI_RESERVE_TYPE_AUTO);
. . .
Status = LciWfDestroy(&Wfile);
Definition
Seals or unseals a worksheet file and/or the worksheet file reservation setting.
Format
#include "lcicomn.h"
#include "lciwfile.h"
LCT_STATUS LCI_CALL LciWfSetSealType
(LCH_WORKFILE Workfile,
lushort SealType,
lptr(lmbcs) lpPassword)
Arguments
Workfile The handle of an existing workfile object.
SealType The seal setting. Possible values are:
Constant Meaning
LCI_SEAL_FILE Seals the file and the reservation setting.
LCI_SEAL_RESERVATION Seals only the reservation setting.
LCI_SEAL_NONE Unseals the file and reservation setting.
lpPassword Pointer to password string.
Returns
LCS_SUCCESS »Page
LCS_FILE_NOT_SEALED »Page
LCS_FILE_SEALED »Page
LCS_INVALID_PASSWORD »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_RESERVATION_SEALED »Page
Example
#include "lcicomn.h"
#include "lciwfile.h"
. . .
LCH_WORKFILE Wfile;
LCT_STATUS Status;
. . .
Status = LciWfConstructCurr(Context,&Wfile);
Status = LciWfSetSealType(Wfile,LCI_SEAL_NONE,"FOOPASSWORD");
. . .
Status = LciWfDestroy(&Wfile);
You use the Workspace objects to represent the 1-2-3 environment. The environment contains all active files and any add-ins that are loaded in 1-2-3.
Function Meaning
LciWsCalc »Page Performs optimal recalculation of all active files in the workspace.
LciWsClearUndo »Page Clears 1-2-3 undo history.
LciWsConstructCurr »Page Retrieves the workspace corresponding to the current 1-2-3 session.
LciWsDestroy »Page Releases a workspace object handle.
LciWsDirtyAtFunction »Page Forces formulas containing dirty @functions to recalculate.
LciWsErase »Page Removes all active files from memory and places the cell pointer in cell A:A1 of the untitled worksheet.
LciWsGetAddinDir »Page Retrieves the drive and path of the calling add-in.
LciWsGetAutoexecFlag »Page Retrieves the current setting of the autoexec flag.
LciWsGetCalcIterCount »Page Retrieves the number of times 1-2-3 recalculates active files during the current session.
LciWsGetCalcOrder »Page Retrieves the order in which 1-2-3 performs recalculation.
LciWsGetCalcType »Page Retrieves the method 1-2-3 uses to perform recalculation.
LciWsGetCellPointerCoords »Page Retrieves the current location of the cell pointer.
LciWsGetCellTopLeftCoords »Page Retrieves the filename and coordinates of the cell in the top left corner of the active file.
LciWsGetClockType »Page Retrieves a value that indicates whether 1-2-3 displays the date and time setting, the current worksheet filename, or nothing in the file-and-clock indicator.
LciWsGetColor »Page Retrieves the current color for the workspace area.
LciWsGetContext »Page Retrieves the context handle corresponding to a workspace object handle.
LciWsGetCurrFile »Page Retrieves the fully qualified filename (including device, directory, path, and filename) of the current worksheet file.
LciWsGetCurrPane »Page Retrieves the number of the pane that the cell pointer is currently in within the workspace.
LciWsGetCurrSheet »Page Retrieves the number of the current worksheet in the current worksheet file.
LciWsGetDefaultDir »Page Retrieves the pathname of the default directory that 1-2-3 uses when it reads, saves, or lists files.
LciWsGetDisplayOptions »Page Retrieves the workspace display options.
LciWsGetFileCount »Page Retrieves the number of worksheet files in the workspace.
LciWsGetFileName »Page Retrieves the fully qualified pathname of a worksheet file according to its current postion in the workspace.
LciWsGetFileNum »Page Retrieves the one-based number of a worksheet file specified by pathname.
LciWsGetFrameType »Page Retrieves the current workspace frame settings.
LciWsGetIndicatorFlags »Page Retrieves an array of boolean values, corresponding to the current state of the 1-2-3 status indicators.
LciWsGetIntlCurrency »Page Retrieves the international currency sign and type.
LciWsGetIntlDateType »Page Retrieves the international date type.
LciWsGetIntlNegType »Page Retrieves the international negative type.
LciWsGetIntlPuncType »Page Retrieves the international punctuation type.
LciWsGetIntlTimeType »Page Retrieves the international time type.
LciWsGetListExt »Page Retrieves the name of the default extension 1-2-3 uses to list files.
LciWsGetMemAvail »Page Retrieves the amount of memory (in bytes) currently available on your system.
LciWsGetName »Page Retrieves the name of a workspace object.
LciWsGetPaneSyncFlag »Page Retrieves the current setting of the pane synchronization flag that specifies whether the top and bottom or left and right panes of a window are synchronized when the window is split.
LciWsGetPaneType »Page Retrieves the mode that 1-2-3 uses for displaying worksheets in windows and panes.
LciWsGetRowHeight »Page Retrieves the row height in points of the current default font (Font 1).
LciWsGetSaveExt »Page Retrieves the default extension that 1-2-3 uses to save files.
LciWsGetStartupDir »Page Retrieves the pathname of the user startup directory.
LciWsGetUndoMode »Page Retrieves the current undo mode in 1-2-3.
LciWsGetZoom »Page Retrieves the percentage for the workspace display to zoom.
LciWsRegisterUndoHandler »Page Registers an undo handler for the workspace object.
LciWsSetAutoexecFlag »Page Sets the autoexec flag.
LciWsSetCalcIterCount »Page Sets the number of times 1-2-3 recalculates active files during the current session.
LciWsSetCalcOrder »Page Sets the order in which 1-2-3 performs recalculation.
LciWsSetCalcType »Page Sets the method 1-2-3 uses to perform recalculation.
LciWsSetCellPointerCoords »Page Sets the location of the cell pointer.
LciWsSetCellTopLeftCoords »Page Positions the data displayed in the workspace so that a specified cell is in the top left corner.
LciWsSetClockType »Page Sets whether 1-2-3 displays the date and time setting, the current worksheet filename, or nothing in the file-and-clock indicator.
LciWsSetColor »Page Sets the workspace area default color for the various display options.
LciWsSetCurrFile »Page Sets the pathname of the current worksheet file.
LciWsSetCurrPane »Page Moves the cell pointer to a specified pane in the workspace without changing the workfile or cell coordinates.
LciWsSetCurrSheet »Page Sets a specified sheet to be the current worksheet in the current workfile.
LciWsSetDefaultDir »Page Sets the pathname of the default directory that 1-2-3 uses when it reads, saves, or lists files.
LciWsSetDisplayOptions »Page Sets the workspace display settings.
LciWsSetFrameType »Page Sets the workspace frame display mode.
LciWsSetIntlCurrency »Page Sets the international currency sign and type.
LciWsSetIntlDateType »Page Sets the international date type.
LciWsSetIntlNegType »Page Sets the international negative type.
LciWsSetIntlPuncType »Page Sets the international punctuation type.
LciWsSetIntlTimeType »Page Sets the international time type.
LciWsSetListExt »Page Sets the default extension 1-2-3 uses to list files.
LciWsSetPaneSyncFlag »Page Sets the window synchronization flag that specifies whether the top and bottom or left and right panes of a window are synchronized when the window is split.
LciWsSetPaneType »Page Sets the mode that 1-2-3 uses for displaying worksheets in windows and panes.
LciWsSetSaveExt »Page Sets the default extension that 1-2-3 uses to save files.
LciWsSetUndoMode »Page Sets the current undo mode in 1-2-3.
LciWsSetZoom »Page Sets the workspace display zoom size (between 25% and 400%, inclusive).
LciWsSetTabState »Page Turns tabs on and off.
LciWsUndoCommand »Page Reverses the effects of the most recently executed undoable command or action.
LciWsUnregisterUndoHandler »Page Unregisters the undo handler for a workspace object.
LciWsUpdateSettings »Page Saves the current worksheet global settings as the default settings in the [CONFIG] section of the 123R4.INI file.
LciWsWriteUndoRecord »Page Writes an undo record to 1-2-3 undo history.
Definition
Performs optimal recalculation of all active files in the workspace.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsCalc
(LCH_WORKSPACE Workspace)
Arguments
Workspace The handle of an existing workspace object.
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Find the Workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr(Context,&Workspace);
. . .
/* Perform optimal recalculation of all active files in the
workspace. */
Status = LciWsCalc(Workspace);
Status = LciWsDestroy(&Workspace);
Definition
Clears 1-2-3 undo history. Undo should be disabled with LciWsSetUndoMode »Page using LCI_UNDO_OFF or LCI_UNDO_OFF_UNTIL_READY if this routine is used.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsClearUndo
(LCH_WORKSPACE Workspace)
Arguments
Workspace The handle of an existing workspace object.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_INVALID_USE »Page
LCS_UNDO_DISABLED »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Construct a workspace object. */
Status = LciWsConstructCurr(Context, &Workspace);
. . .
/* Clear any records in 1-2-3's undo history. */
Status = LciWsClearUndo(Workspace);
. . .
/* Destroy the workspace object. */
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the workspace corresponding to the current 1-2-3 session.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsConstructCurr
(LCH_CONTEXT Context,
lptr(LCH_WORKSPACE) lpWorkspace)
Arguments
Context The context handle that was passed to the C program when 1-2-3 invoked it.
lpWorkspace A pointer to storage to which to return the object handle.
Returns
LCS_SUCCESS »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Find the Workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context,&Workspace);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Releases a workspace object handle.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsDestroy
(lptr(LCH_WORKSPACE) lpWorkspace)
Arguments
lpWorkspace A pointer to a workspace object handle, which this call sets to NULL.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Release a workspace object handle. */
Status = LciWsDestroy(&Workspace);
Definition
Make all formulas containing add-in @functions which have dirtiness of LCF_AF_REGISTER_DIRTY_DATE dirty, that is, force them to recalculate.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsDirtyAtFunction
(LCH_WORKSPACE Workspace);
Arguments
Workspace The handle of an existing workspace object.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
...
LCH_WORKSPACE theWkspace;
LCT_STATUS Status;
...
Status = LciWsConstructCurr(Context, &theWkspace);
...
/* force recalc of all the add-in @functions with DIRTY_DATE type dirtiness */
Status = LciWsDirtyAtFunc(theWkspace);
...
Status = LciWsDestroy(&theWkspace);
Definition
Removes all active files from memory and places the cell pointer in cell A:A1 of the untitled worksheet.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsErase
(LCH_WORKSPACE Workspace)
Arguments
Workspace The handle of an existing workspace object.
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context,&Workspace);
. . .
/* Remove all active files from memory and place the cell
pointer in cell A:A1 of the unnamed worksheet. */
Status = LciWsErase(Workspace);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the drive and path of the calling add-in. The trailing backslash is always removed unless the directory is the root (for example, C:\ or D:\) in which case the backslash is included.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCH_STATUS LCI_CALL LciWsGetAddinDir
(LCH_WORKSPACE Workspace,
lushort BufLen,
lptr(lmbcs) lpDirName)
Arguments
Workspace The handle of an existing workspace object.
BufLen The number of bytes available in the buffer pointed to by lpDirName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_DIRNAME_LEN.
lpDirName A pointer to a lmbcs string in which to return the directory pathname.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs DirName[LCI_MAX_DIRNAME_LEN];
lushort BufLen = LCI_MAX_DIRNAME_LEN;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context,&Workspace);
. . .
/* Return the drive and path of the calling add-in. */
Status = LciWsGetAddinDir(Workspace,BufLen,DirName);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the current setting of the autoexec flag. If the flag value is LTRUE, 123 runs an autoexecute macro after a File Open or /File Retrieve operation. If the flag value is LFALSE, 1-2-3 does not run autoexecute macros.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetAutoexecFlag
(LCH_WORKSPACE Workspace,
lptr(lbool) lpAutoexecFlag)
Arguments
Workspace The handle of an existing workspace object.
lpAutoexecFlag A pointer to an lbool in which to return the flag.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lbool AutoexecFlag;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context,&Workspace);
. . .
/* Return the current setting of the autoexec flag. */
Status = LciWsGetAutoexecFlag(Workspace,&AutoexecFlag);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the number of times 1-2-3 recalculates active files during the current session either when the recalculation order is set to Columnwise or Rowwise, or when recalculation is set to Natural and there is a circular reference. The value is an integer between 1 and 50, inclusive. The default value is one.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetCalcIterCount
(LCH_WORKSPACE Workspace,
lptr(lushort) lpCalcIterCount)
Arguments
Workspace The handle of an existing workspace object.
lpCalcIterCount A pointer to an lushort in which to return the count.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort CalcIterCount;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context,&Workspace);
. . .
/* Return the number of times 1-2-3 recalculates active files
during the current session.*/
Status = LciWsGetCalcIterCount(Workspace,&CalcIterCount);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the order in which 1-2-3 performs recalculation.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetCalcOrder
(LCH_WORKSPACE Workspace,
lptr(lushort) lpCalcOrder)
Arguments
Workspace The handle of an existing workspace object.
lpCalcOrder A pointer to an lushort in which to return the calculation order. Possible values are:
Constant Meaning
LCI_CALC_ORDER_COLWISE recalculation by column
LCI_CALC_ORDER_ROWWISE recalculation by row
LCI_CALC_ORDER_NATURAL natural recalculation
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort CalcOrder;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the order in which 1-2-3 performs recalculation. */
Status = LciWsGetCalcOrder(Workspace,&CalcOrder);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the method 1-2-3 uses to perform recalculation.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetCalcType
(LCH_WORKSPACE Workspace,
lptr(lushort) lpCalcType)
Arguments
Workspace The handle of an existing workspace object.
lpCalcType A pointer to an lushort in which to return the calculation type. Possible values are:
Constant Meaning
LCI_CALC_TYPE_AUTO automatic recalculation
LCI_CALC_TYPE_MANUAL manual recalculation
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort CalcType;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the method 1-2-3 uses to perform recalculation. */
Status = LciWsGetCalcType(Workspace,&CalcType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the current location of the cell pointer.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetCellPointerCoords
LCH_WORKSPACE Workspace,
lushort BufLen,
lptr(lmbcs) lpFileName,
lptr(lushort) lpSheetNum,
lptr(lushort) lpColNum,
lptr(lushort) lpRowNum)
Arguments
Workspace The handle of an existing workspace object.
BufLen The number of bytes available in the buffer pointed to by lpFileName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_FILENAME_LEN.
lpFileName A pointer to a lmbcs string in which to return the file pathname.
lpSheetNum A pointer to a lmbcs string in which to return the number of the current worksheet.
lpColNum A pointer to a lmbcs string in which to return the current column number.
lpRowNum A pointer to a lmbcs string in which to return the current row number.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs FileName[LCI_MAX_FILENAME_LEN];
lushort BufLen = LCI_MAX_FILENAME_LEN;
lushort SheetNum;
lushort ColNum;
lushort RowNum;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the current location of the cell pointer */
Status = LciWsGetCellPointerCoords
(Workspace,BufLen,FileName,&SheetNum,&ColNum,&RowNum);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the filename and coordinates of the cell in the top left corner of the active file.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetCellTopLeftCoords
(LCH_WORKSPACE Workspace,
lushort BufLen,
lptr(lmbcs) lpFileName,
lptr(lushort) lpSheetNum,
lptr(lushort) lpColNum,
lptr(lushort) lpRowNum)
Arguments
Workspace The handle of an existing workspace object.
BufLen The number of bytes available in the buffer pointed to by lpFileName, including room for a null-terminating byte.This value need not be greater than LCI_MAX_FILENAME_LEN.
lpFileName A pointer to a lmbcs string in which to return the file pathname.
lpSheetNum A pointer to a lmbcs string in which to return the number of the current worksheet.
lpColNum A pointer to a lmbcs string in which to return the column number.
lpRowNum A pointer to a lmbcs string in which to return the row number.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs FileName[LCI_MAX_FILENAME_LEN];
lushort BufLen = LCI_MAX_FILENAME_LEN;
lushort SheetNum;
lushort ColNum;
lushort RowNum;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the FileName and coordinates of the cell in the top
left corner of the current window. */
Status = LciWsGetCellTopLeftCoords
(Workspace,BufLen,FileName,&SheetNum,&ColNum,&RowNum);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves a value that indicates whether 1-2-3 displays the date and time setting, the current worksheet filename, or nothing in the file-and-clock indicator. The default setting displays the filename.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetClockType
(LCH_WORKSPACE Workspace,
lptr(lushort) lpClockType)
Arguments
Workspace The handle of an existing workspace object.
lpClockType A pointer to an lushort in which to return the clock type. Possible values are:
Constant Meaning
LCI_CLOCK_STANDARD displays the date and time in standard format
LCI_CLOCK_INTL displays the date and time in international format
LCI_CLOCK_FILENAME displays the name of the current file
LCI_CLOCK_NONE removes the file-and-clock indicator
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort ClockType;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return whether 1-2-3 displays the date and time setting,
the current worksheet filename, or nothing in the
file-and-clock indicator.*/
Status = LciWsGetClockType(Workspace,&ClockType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the current color for the workspace area.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetColor
(LCH_WORKSPACE Workspace,
lushort WsArea,
lptr(lushort) Color)
Arguments
Workspace The handle of an existing workspace object.
WsArea The area type. Valid area types are:
Constant Meaning
LCI_COLOR_TYPE_FRAME worksheet frame
LCI_COLOR_TYPE_BG cell background
LCI_COLOR_TYPE_FG cell foreground
LCI_COLOR_TYPE_NEGATIVE negative values
LCI_COLOR_TYPE_SHADOW drop shadows
LCI_COLOR_TYPE_GRID spreadsheet grid
LCI_COLOR_TYPE_BORDERS range borders
LCI_COLOR_TYPE_SELECTED selected range
LCI_COLOR_TYPE_UNPROTECTED unprotected cells
Color A pointer to an lushort in which to return the color. The Color values correspond to those set in Window Display Options Palette, can be 0 to 255 or one of the following predifined constants:
LCI_COLOR_1
LCI_COLOR_2
LCI_COLOR_3
LCI_COLOR_4
LCI_COLOR_5
LCI_COLOR_6
LCI_COLOR_7
LCI_COLOR_8
Note LciWsGetColor does not check for invalid input and does not signal if an invalid input is received.
LCI_COLOR_TYPE_FRAME, LCI_COLOR_TYPE_SELECTED, and LCI_COLOR_TYPE_UNPROTECTED options are no longer supported.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort WsArea = LCI_COLOR_TYPE_FRAME;
lushort Color;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Get the current color for the worksheet area. */
Status = LciWsGetColor(Workspace,WsArea,&Color);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the context handle corresponding to a workspace object handle.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetContext
(LCH_WORKSPACE Workspace,
lptr(LCH_CONTEXT) lpContext)
Arguments
Workspace The handle of an existing workspace object.
lpContext A pointer to storage to which to return the context handle.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the context handle corresponding to the workspace
object handle */
Status = LciWsGetContext(Workspace,&Context);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the fully qualified filename (including device, directory, path, and filename) of the current worksheet file.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetCurrFile
(LCH_WORKSPACE Workspace,
lushort BufLen,
lptr(lmbcs) lpFileName)
Arguments
Workspace The handle of an existing workspace object.
BufLen The number of bytes available in the buffer pointed to by lpFileName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_FILENAME_LEN.
lpFileName A pointer to a lmbcs string in which to return the file pathname.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs FileName[LCI_MAX_FILENAME_LEN];
lushort BufLen = LCI_MAX_FILENAME_LEN;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the fully qualified filename (including device,
directory path, and filename) of the current worksheet file. */
Status = LciWsGetCurrFile (Workspace,BufLen,FileName);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the number of the pane that the cell pointer is currently in within the workspace.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetCurrPane
(LCH_WORKSPACE Workspace,
lptr(lushort) lpPaneNum)
Arguments
Workspace The handle of an existing workspace object.
lpPaneNum A pointer to an lushort in which to return the one-based number of the pane within the window.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort PaneNum;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the number of the pane that the cell pointer is
currently in within the current window. */
Status = LciWsGetCurrPane(Workspace,&PaneNum);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the number of the current worksheet in the current worksheet file.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetCurrSheet
(LCH_WORKSPACE Workspace,
lptr(lushort) lpSheetNum)
Arguments
Workspace The handle of an existing workspace object.
lpSheetNum A pointer to an lushort in which to return the number of the current worksheet.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort SheetNum;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the number of the current worksheet in the current
worksheet file. */
Status = LciWsGetCurrSheet(Workspace,&SheetNum);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the pathname of the default directory that 1-2-3 uses when it reads, saves, or lists files.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetDefaultDir
(LCH_WORKSPACE Workspace,
lushort BufLen,
lptr(lmbcs) lpDirName)
Arguments
Workspace The handle of an existing workspace object.
BufLen The number of bytes available in the buffer pointed to by lpDirName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_DIRNAME_LEN.
lpDirName A pointer to a lmbcs string in which to return the directory pathname.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs DirName[LCI_MAX_DIRNAME_LEN];
lushort BufLen = LCI_MAX_DIRNAME_LEN;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the pathname of the default directory that 1-2-3 uses
when it reads, saves, or lists files. */
Status = LciWsGetDefaultDir(Workspace,BufLen,DirName);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the workspace display options: whether to display page breaks, whether to display in draft mode, whether to display in black and white, and whether to display grid lines.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetDisplayOptions
(LCH_WORKSPACE Workspace,
lptr(lulong) DisplayOptions)
Arguments
Workspace The handle of an existing workspace object.
DisplayOptions A pointer to an lulong in which to return the display options type. The result is a binary OR of one or more of the following:
LCF_DISPLAY_OPTION_PAGE_BREAKS
LCF_DISPLAY_OPTION_GRID_LINES
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lulong DisplayOptions;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Get the workspace display options. */
Status = LciWsGetDisplayOptions(Workspace,&DisplayOptions);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the number of worksheet files in the workspace.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetFileCount
(LCH_WORKSPACE Workspace,
lptr(lushort) lpFileCount)
Arguments
Workspace The handle of an existing workspace object.
lpFileCount A pointer to an lushort in which to return the count.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort FileCount;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the number of worksheet files currently in memory. */
Status = LciWsGetFileCount(Workspace,&FileCount);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the fully qualified pathname of a worksheet file specified by a number ranging between one and the number of workfiles in the workspace (that is, specified 1-2-3 window).
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetFileName
(LCH_WORKSPACE Workspace,
lushort FileNum,
lushort BufLen,
lptr(lmbcs) lpFileName)
Arguments
Workspace The handle of an existing workspace object.
FileNum The one-based number of a workfile in memory. Call LciWsGetFileCount »Page to find out how many there are.
BufLen The number of bytes available in the buffer pointed to by lpFileName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_FILENAME_LEN.
lpFileName A pointer to a buffer in which to return the file pathname.
Returns
LCS_SUCCESS »Page
LCS_INVALID_NUM »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs FileName[LCI_MAX_FILENAME_LEN];
lushort BufLen = LCI_MAX_FILENAME_LEN;
lushort FileNum;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the fully qualified pathname of a worksheet file. */
Status = LciWsGetFileName(Workspace,FileNum,BufLen,FileName);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the one-based number of a worksheet file specified by pathname.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetFileNum
(LCH_WORKSPACE Workspace,
lptr(lmbcs) lpFileName,
lptr(lushort) lpFileNum)
Arguments
Workspace The handle of an existing workspace object.
lpFileName A pointer to a lmbcs string that contains the pathname of a workfile. Its length must not exceed LCI_MAX_FILENAME_LEN.
lpFileNum A pointer to an lushort in which to return the file number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_FILENAME »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs FileName[LCI_MAX_FILENAME_LEN];
lushort FileNum;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Define the filename. */
lstrcpy(FileName,"c:\\123w\\Testfile.wk3");
/* Return the one-based number of a worksheet file specified by
pathname. */
Status = LciWsGetFileNum(Workspace,FileName,&FileNum);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the current workspace frame settings. This function retrieves the frame settings as set in the Window Display Options dialog box.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetFrameType
(LCH_WORKSPACE Workspace,
lptr(lushort) lpFrameSetting)
Arguments
Workspace The handle of an existing workspace object.
lpFrameSetting A pointer to an lushort in which to return the frame setting. The frame setting is one of the following:
LCI_FRAME_STANDARD
LCI_FRAME_CHARACTERS
LCI_FRAME_INCHES
LCI_FRAME_METRIC
LCI_FRAME_POINTS
LCI_FRAME_NONE
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort FrameSetting;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Get the current workspace frame settings. */
Status = LciWsGetFrameType(Workspace,&FrameSetting);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves an array of boolean values corresponding to the current state of the 1-2-3 status indicators. If an indicator is on, the corresponding flag is set to LTRUE; if it is off, the flag is set to LFALSE.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetIndicatorFlags
(LCH_WORKSPACE Workspace,
lptr(lbool) lpIndFlagArray)
Arguments
Workspace The handle of an existing workspace object.
lpIndFlagArray A pointer to an lbool array of dimension LCI_INDICATOR_ARRAY_SIZE to which the current status indicator values will be copied. The elements of the array can be indexed as follows:
Index Returns Indicator
LCI_INDICATOR_CALC CALC
LCI_INDICATOR_CALCBLINK CALCBLINK
LCI_INDICATOR_CAPS CAPS
LCI_INDICATOR_CIRC CIRC
LCI_INDICATOR_CMD CMD
LCI_INDICATOR_ENDKEY ENDKEY
LCI_INDICATOR_FILE FILE
LCI_INDICATOR_GROUP GROUP
LCI_INDICATOR_MEM MEM
LCI_INDICATOR_NUM NUM
LCI_INDICATOR_OVR OVR
LCI_INDICATOR_RO RO
LCI_INDICATOR_SCROLL SCROLL
LCI_INDICATOR_SST SST
LCI_INDICATOR_STEP STEP
LCI_INDICATOR_ZOOM ZOOM
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lbool IndicatorFlagsArray[LCI_INDICATOR_ARRAY_SIZE];
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return an array of boolean values corresponding to the current
state of the 1-2-3 status indicators. */
Status = LciWsGetIndicatorFlags(Workspace,IndicatorFlagsArray);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the international currency sign and type.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetIntlCurrency
(LCH_WORKSPACE Workspace,
lushort BufLen,
lptr(lmbcs) lpIntlCurrencySign,
lptr(lushort) lpIntlCurrencyType)
Arguments
Workspace The handle of an existing workspace object.
BufLen The number of bytes available in the buffer pointed to by lpIntlCurrencySign, including room for a null-terminating byte. This value need not be greater than LCI_MAX_CURRSIGN_LEN.
lpIntlCurrencySign A pointer to a lmbcs string in which to return the LMBCS character sequence representing the currency sign.
lpIntlCurrencyType A pointer to an lushort in which to return the international currency type. Possible values are:
Constant Meaning
LCI_INTL_CURRENCY_PREFIX sign precedes number
LCI_INTL_CURRENCY_SUFFIX sign follows number
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs IntlCurrencySign[LCI_MAX_CURRSIGN_LEN];
lushort BufLen = LCI_MAX_CURRSIGN_LEN;
lushort IntlCurrencyType;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the international currency sign and type. */
Status = LciWsGetIntlCurrency
(Workspace,Buflen,IntlCurrencySign,&IntlCurrencyType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the international date type.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetIntlDateType
(LCH_WORKSPACE Workspace,
lptr(lushort) lpIntlDateType)
Arguments
Workspace The handle of an existing workspace object.
lpIntlDateType A pointer to an lushort in which to return the international date type. Possible values are:
Constant Meaning
LCI_INTL_DATE_MMDDYYSLASH MM/DD/YY
LCI_INTL_DATE_DDMMYYSLASH DD/MM/YY
LCI_INTL_DATE_DDMMYYDOT DD.MM.YY
LCI_INTL_DATE_YYMMDDHYPHEN YY-MM-DD
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort IntlDateType;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the International date type */
Status = LciWsGetIntlDateType(Workspace,&IntlDateType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the international negative type. This determines whether 1-2-3 uses a minus sign or parentheses to indicate negative values formatted as comma or currency. The default is parentheses.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetIntlNegType
(LCH_WORKSPACE Workspace,
lptr(lushort) lpIntlNegType)
Arguments
Workspace The handle of an existing workspace object.
lpIntlNegType A pointer to an lushort in which to return the international negative type. Possible values are:
Constant Meaning
LCI_INTL_NEG_PARENS encloses negative value in parentheses
LCI_INTL_NEG_SIGN precedes negative value with a minus sign
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort IntlNegType;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the international negative type */
Status = LciWsGetIntlNegType(Workspace,&IntlNegType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the international punctuation type.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetIntlPuncType
(LCH_WORKSPACE Workspace,
lptr(lushort) lpIntlPuncType)
Arguments
Workspace The handle of an existing workspace object.
lpIntlPuncType A pointer to a buffer in which to return the international punctuation type. Meanings are listed in order of: decimal point, argument separator, and thousands separator. Possible values are:
Constant Meaning
LCI_INTL_PUNC_A .,,
LCI_INTL_PUNC_B ,..
LCI_INTL_PUNC_C .;,
LCI_INTL_PUNC_D ,;.
LCI_INTL_PUNC_E .,space
LCI_INTL_PUNC_F ,.space
LCI_INTL_PUNC_G .;space
LCI_INTL_PUNC_H ,;space
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort IntlPuncType;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the international punctuation type */
Status = LciWsGetIntlPuncType(Workspace,&IntlPuncType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the international time type.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetIntlTimeType
(LCH_WORKSPACE Workspace,
lptr(lushort) lpIntlTimeType)
Arguments
Workspace The handle of an existing workspace object.
lpIntlTimeType A pointer to an lushort in which to return the international time type. (Lowercase letters will actually be displayed in the positions shown. Uppercase characters indicate number positions.) Possible values are:
Constant Meaning
LCI_INTL_TIME_HHMMSSCOLON HH:MM:SS
LCI_INTL_TIME_HHMMSSDOT HH.MM.SS
LCI_INTL_TIME_HHMMSSCOMMA HH,MM,SS
LCI_INTL_TIME_HHHMMMSSS HHhMMmSSs
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort IntlTimeType;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the international time type */
Status = LciWsGetIntlTimeType(Workspace,&IntlTimeType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the name of the default extension 1-2-3 uses to list files.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetListExt
(LCH_WORKSPACE Workspace,
lushort BufLen,
lptr(lmbcs) lpListExt)
Arguments
Workspace The handle of an existing workspace object.
BufLen The number of bytes available in the buffer pointed to by lpListExt, including room for a null-terminating byte. This value need not be greater than LCI_MAX_FILEEXT_LEN.
lpListExt A pointer to a lmbcs string in which to return the list extension string.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort BufLen = LCI_MAX_FILEEXT_LEN;
lmbcs ListExt[LCI_MAX_FILEEXT_LEN];
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the name of the default extension 1-2-3 uses to list
files. */
Status = LciWsGetListExt(Workspace,BufLen,ListExt);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the amount of memory (in bytes) currently available on your system.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetMemAvail
(LCH_WORKSPACE Workspace,
lptr(lulong) lpMemAvail)
Arguments
Workspace The handle of an existing workspace object.
lpMemAvail A pointer to an lulong in which to return the amount of available memory in bytes.
Returns
LCS_SUCCESS »Page
LCS_SIZE_IN_KBYTES »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lulong MemAvail;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the Amount of memory currently avaliable on your system
in bytes. */
Status = LciWsGetMemAvail(Workspace,&MemAvail);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the name of a workspace object.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetName
(LCH_WORKSPACE Workspace,
lushort BufLen,
lptr(lmbcs) lpWorkspaceName)
Arguments
Workspace The handle of an existing workspace object.
BufLen The number of bytes available in the buffer pointed to by lpWorkspaceName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_WSNAME_LEN.
lpWorkspaceName A pointer to a lmbcs string in which to return the workspace name.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs WorkspaceName[LCI_MAX_WSNAME_LEN];
lushort BufLen = LCI_MAX_WSNAME_LEN;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the name of a workspace object */
Status = LciWsGetName(Workspace,BufLen,WorkspaceName);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the current setting of the pane synchronization flag that specifies whether the top and bottom or left and right panes of a window are synchronized when the window is split. LTRUE signifies that the windows are synchronized; LFALSE that they are unsynchronized.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetPaneSyncFlag
(LCH_WORKSPACE Workspace,
lptr(lbool) lpPaneSyncFlag)
Arguments
Workspace The handle of an existing workspace object.
lpPaneSyncFlag A pointer to an lbool in which to return the flag.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lbool PaneSyncFlag;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the current setting of the pane synchronization flag
that specified how window is synchronized when it is split. */
Status = LciWsGetPaneSyncFlag(Workspace,&PaneSyncFlag);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the current mode that 1-2-3 uses for displaying worksheets. 1-2-3 can horizontally or vertically split the screen into two windows, create a perspective view of three consecutive worksheets, vertically split the screen and display the current graph in the righthand window, or display the current workshet in a single window.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetPaneType
(LCH_WORKSPACE Workspace,
lptr(lushort) lpPaneType)
Arguments
Workspace The handle of an existing workspace object.
lpPaneType A pointer to an lushort in which to return the pane type. Possible values are:
Constant Meaning
LCI_PANE_TYPE_HORIZ two horizontal panes
LCI_PANE_TYPE_VERT two vertical panes
LCI_PANE_TYPE_PERSPECTIVE perspective view
LCI_PANE_TYPE_GRAPH graph pane
LCI_PANE_TYPE_SINGLE single pane
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lulong PaneType;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the mode that 123 uses for displaying worksheets in
windows and panes. */
Status = LciWsGetPaneType(Workspace,&PaneType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the row height in points of the current default font.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetRowHeight
(LCH_WORKSPACE Workspace,
lptr(lushort) lpRowHeight)
Arguments
Workspace The handle of an existing workspace object.
lpRowHeight A pointer to an lushort in which to return the row height (in points).
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort RowHeight;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Get the row height in points of the current default font. */
Status = LciWsGetRowHeight(Workspace,&RowHeight);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the default extension that 1-2-3 uses to save files.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetSaveExt
(LCH_WORKSPACE Workspace,
lushort BufLen,
lptr(lmbcs) lpSaveExt)
Arguments
Workspace The handle of an existing workspace object.
BufLen The number of bytes available in the lmbcs string pointed to by lpSaveExt, including room for a null-terminating byte.This value need not be greater than LCI_MAX_FILEEXT_LEN.
lpSaveExt A pointer to a lmbcs string in which to return the default extension.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs SaveExt[LCI_MAX_FILEEXT_LEN];
lushort Buflen = LCI_MAX_FILEEXT_LEN;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the default extension that 1-2-3 uses to save files. */
Status = LciWsGetSaveExt(Workspace,BufLen,SaveExt);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the pathname of the user startup directory. This directory corresponds to the directory where the user was when 1-2-3 was invoked.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetStartupDir
(LCH_WORKSPACE Workspace,
lushort BufLen,
lptr(lmbcs) lpDirName)
Arguments
Workspace The handle of an existing workspace object.
BufLen The number of bytes available in the buffer pointed to by lpDirName, including room for a null-terminating byte. This value need not be greater than LCI_MAX_DIRNAME_LEN.
lpDirName A pointer to a lmbcs string in which to return the directory pathname.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs DirName[LCI_MAX_FILENAME_LEN];
lushort Buflen = LCI_MAX_FILENAME_LEN;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Return the pathname of the user's startup directory. */
Status = LciWsGetStartupDir(Workspace,BufLen,DirName);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the current undo mode in 1-2-3.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetUndoMode
(LCH_WORKSPACE Workspace,
lptr(lushort) lpUndoMode)
Arguments
Workspace The handle of an existing workspace object.
lpUndoMode A pointer to an lushort in which to return the mode. It is one of the following:
LCI_UNDO_OFF
LCI_UNDO_OFF_UNTIL_READY
LCI_UNDO_ON
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort UndoMode;
. . .
/* Construct a workspace object. */
Status = LciWsConstructCurr(Context, &Workspace);
. . .
/* Get 1-2-3's Undo mode. */
Status = LciWsGetUndoMode(Workspace, &UndoMode);
. . .
/* Destroy the workspace object. */
Status = LciWsDestroy(&Workspace);
Definition
Retrieves the percentage for the workspace display to zoom. Valid numbers are between 25% and 400%, inclusive.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsGetZoom
(LCH_WORKSPACE Workspace
lptr(lushort) lpZoomAmount)
Arguments
Workspace The handle of an existing workspace object.
lpZoomAmount A pointer to an lushort in which to return the zoom amount.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort ZoomAmount;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Get the percentage for the workspace to zoom. */
Status = LciWsGetZoom(Workspace,ZoomAmount);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Registers an undo handler for the workspace object.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsRegisterUndoHandler
(LCH_WORKSPACE Workspace,
lptr(LCT_UNDO_HANDLER) lpUndoHandler)
Arguments
Workspace The handle of an existing workspace object.
lpUndoHandler A pointer to a function that will get called to undo the operation. The calling sequence of the function is:
LCT_STATUS LCI_CALL UndoHandler
(LCH_CONTEXT Context,
lptr(void) lpUndoData,
lushort Length)
where: Context is the context handle that was passed to the C program when 1-2-3 invoked it.
lpUndoData is a buffer that contains data that the undo handler uses to reverse the effects of a particular operation.
Length is the length of lpUndoData in bytes.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
LCT_STATUS LCI_CALL UndoHandler (LCH_CONTEXT Context,
lptr(void) UndoData, lushort Length);
. . .
/* Construct a workspace object. */
Status = LciWsConstructCurr(Context, &Workspace);
. . .
/* Register a custom undo handler for this workspace object. */
Status = LciWsRegisterUndoHandler(Workspace, UndoHandler);
. . .
/* Destroy the workspace object. */
Status = LciWsDestroy(&Workspace);
Definition
Sets the autoexec flag. If the flag value is LTRUE, 1-2-3 runs an autoexecute macro after a File Open or a /File Retrieve operation. If the flag value is LFALSE, 1-2-3 does not run autoexecute macros.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetAutoexecFlag
(LCH_WORKSPACE Workspace,
lbool AutoexecFlag)
Arguments
Workspace The handle of an existing workspace object.
AutoexecFlag The desired flag value.
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the autoexec flag to TRUE. */
Status = LciWsSetAutoexecFlag(Workspace,LTRUE);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the number of times 1-2-3 recalculates active files during the current session either when the recalculation order is set to columnwise or rowwise, or when recalculation is set to natural and there is a circular reference. The value is an integer between 1 and 50, inclusive. The default value is one.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetCalcIterCount
(LCH_WORKSPACE Workspace,
lushort CalcIterCount)
Arguments
Workspace The handle of an existing workspace object.
CalcIterCount The desired count.
Returns
LCS_SUCCESS »Page
LCI_INVALID_NUM »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the number of times 1-2-3 recalculates active files during
the current session to 10. */
Status = LciWsSetCalcIterCount(Workspace,(lushort)10);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the order in which 1-2-3 performs recalculation.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetCalcOrder
(LCH_WORKSPACE Workspace,
lushort CalcOrder)
Arguments
Workspace The handle of an existing workspace object.
CalcOrder The desired calculation order. Possible values are:
Constant Meaning
LCI_CALC_ORDER_COLWISE recalculation by column
LCI_CALC_ORDER_ROWWISE recalculation by row
LCI_CALC_ORDER_NATURAL natural recalculation
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the order in which 1-2-3 performs recalculation to
"recalculation by column." */
Status = LciWsSetCalcOrder(Workspace,LCI_CALC_ORDER_COLWISE);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the method 1-2-3 uses to perform recalculation.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetCalcType
(LCH_WORKSPACE Workspace,
lushort CalcType)
Arguments
Workspace The handle of an existing workspace object.
CalcType The desired recalculation type. Possible values are:
Constant Meaning
LCI_CALC_TYPE_AUTO automatic recalculation
LCI_CALC_TYPE_MANUAL manual recalculation
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the method 1-2-3 uses to perform recalculation to
"manual recalculation" */
Status = LciWsSetCalcType(Workspace, LCI_CALC_TYPE_MANUAL);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the location of the cell pointer.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetCellPointerCoords
(LCH_WORKSPACE Workspace,
lptr(lmbcs) lpFileName,
lushort SheetNum,
lushort ColNum,
lushort RowNum)
Arguments
Workspace The handle of an existing workspace object.
lpFileName The desired file pathname. Its length must not exceed LCI_MAX_FILENAME_LEN. It can be LCI_UNTITLED_WORKFILE to specify the untitled workfile, or LCI_CURRENT_WORKFILE to specify the current workfile.
SheetNum The desired sheet number.
ColNum The desired column number.
RowNum The desired row number.
Returns
LCS_SUCCESS »Page
LCS_HIDDEN_COL »Page
LCS_HIDDEN_SHEET »Page
LCS_INVALID_COL »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_ROW »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the location of the cell pointer. */
Status = LciWsSetCellPointerCoords
(Workspace,LCI_CURRENT_WORKFILE,2,256,8192);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Positions the data displayed in the workspace so that a specified cell is in the top left corner.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetCellTopLeftCoords
(LCH_WORKSPACE Workspace,
lptr(lmbcs) lpFileName,
lushort SheetNum,
lushort ColNum,
lushort RowNum)
Arguments
Workspace The handle of an existing workspace object.
lpFileName The desired file pathname. Its length must not exceed LCI_FILENAME_LEN. It can be LCI_UNTITLED_WORKFILE to specify the untitled workfile, or LCI_CURRENT_WORKFILE to specify the current workfile.
SheetNum The desired sheet number.
ColNum The desired column number.
RowNum The desired row number.
Returns
LCS_SUCCESS »Page
LCS_HIDDEN_COL »Page
LCS_HIDDEN_SHEET »Page
LCS_INVALID_COL »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_ROW »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Position the data displayed in the current window so that a
specified cell is in the top left corner. */
Status = LciWsSetCellTopLeftCoords
(Workspace,LCI_CURENT_WORKFILE,10,100,1000);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Determines whether 1-2-3 displays the date and time setting, the current worksheet filename, or nothing in the file-and-clock indicator. The default setting displays the filename.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciSetClockType
(LCH_WORKSPACE Workspace,
lushort ClockType)
Arguments
Workspace The handle of an existing workspace object.
ClockType The desired clock type. Possible values are:
Constant Meaning
LCI_CLOCK_STANDARD displays the date and time in standard format
LCI_CLOCK_INTL displays the date and time in international format
LCI_CLOCK_FILENAME displays the name of the current file
LCI_CLOCK_NONE removes the file-and-clock indicator
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort ClockType = LCI_CLOCK_STANDARD;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Position the data displayed in the current window so that a
specified cell is in the top left corner. */
Status = LciWsSetClockType(Workspace,ClockType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the workspace area default color for the frame, the cell background and foreground, negative values, drop shadows, the grid, borders, selected cells, and unprotected cells. The cell foreground and background should not be set to the same color. If they are, the product will reset the cell foreground color to LCI_COLOR_1.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetColor
(LCH_WORKSPACE Workspace,
lushort ColorType,
lushort Color)
Arguments
Workspace The handle of an existing workspace object.
ColorType The desired color area type. Valid settings are:
LCI_COLOR_TYPE_FRAME
LCI_COLOR_TYPE_BG
LCI_COLOR_TYPE_FG
LCI_COLOR_TYPE_NEGATIVE
LCI_COLOR_TYPE_SHADOW
LCI_COLOR_TYPE_GRID
LCI_COLOR_TYPE_BORDERS
LCI_COLOR_TYPE_SELECTED
LCI_COLOR_TYPE_UNPROTECTED
Color The desired color. Valid colors are 0 to 255 or one of the following:
LCI_COLOR_1
LCI_COLOR_2
LCI_COLOR_3
LCI_COLOR_4
LCI_COLOR_5
LCI_COLOR_6
LCI_COLOR_7
LCI_COLOR_8
Note These color correspond to those set in the Window Display Options Palette dialog box.
Note LCI_COLOR_TYPE_FRAME, LCI_COLOR_TYPE_SELECTED, and LCI_COLOR_TYPE_UNPROTECTED options are no longer supported.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort Color = LCI_COLOR_4;
lushort ColorType = LCI_COLOR_TYPE_FG;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the default color for the cell forground to 4 */
Status = LciWsSetColor(Workspace,ColorType,Color);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the pathname of the current worksheet file.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetCurrFile
(LCH_WORKSPACE Workspace,
lptr(lmbcs) lpFileName)
Arguments
Workspace The handle of an existing workspace object.
lpFileName A pointer to a lmbcs string that contains the desired file pathname. It must not be longer than LCI_MAX_FILENAME_LEN. It can be LCI_UNTITLED_WORKFILE to specify the untitled workfile or LCI_CURRENT_WORKFILE to specify the current workfile.
Returns
LCS_SUCCESS »Page
LCS_INVALID_FILENAME »Page
LCS_INVALID_USE »Page
LCS_NOT_IN_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs FileName[LCI_MAX_FILENAME_LEN];
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the file pathname to the associated string */
lstrcpy(FileName,"c:\\123w\\");
. . .
/* Set the current worksheet file pathname */
Status = LciWsSetCurrFile(Workspace,FileName);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Moves the cell pointer to a specified pane in the workspace without changing the workfile or cell coordinates.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetCurrPane
(LCH_WORKSPACE Workspace,
lushort PaneNum)
Arguments
Workspace The handle of an existing workspace object.
PaneNum The desired pane number.
Returns
LCS_SUCCESS »Page
LCS_INVALID_PANE »Page
LCS_INVALID_USE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort PaneNum = 2;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Move the cell pointer to pane 2. */
Status = LciWsSetCurrPane(Workspace,PaneNum);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the current worksheet in the current workfile to be the sheet corresponding to the specified number.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetCurrSheet
(LCH_WORKSPACE Workspace,
lushort SheetNum)
Arguments
Workspace The handle of an existing workspace object.
SheetNum The number of the worksheet to make current. SheetNum corresponds to the position of the desired sheet in the workfile.
Returns
LCS_SUCCESS »Page
LCS_HIDDEN_SHEET »Page
LCS_INVALID_SHEET »Page
LCS_INVALID_USE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort SheetNum = 22;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the number of the current worksheet in the current
worksheet file to 22. */
Status = LciWsSetCurrSheet(Workspace,SheetNum);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the pathname of the default directory that 1-2-3 uses when it reads, saves, or lists files.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetDefaultDir
(LCH_WORKSPACE Workspace,
lptr(lmbcs) lpDirName)
Arguments
Workspace The handle of an existing workspace object.
lpDirName A pointer to a lmbcs string that contains the desired default directory pathname. Its length must not exceed LCI_MAX_DIRNAME_LEN.
Returns
LCS_SUCCESS »Page
LCS_INVALID_PATH »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs DirName[LCI_MAX_DIRNAME_LEN];
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the File Pathname to the associated string. */
lstrcpy(DirName,"c:\\123w\\USER1\\");
. . .
/* Set the pathname of the default directory to the user's home. */
Status = LciWsSetDefaultDir(Workspace,DirName);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the workspace display settings.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetDisplayOptions
(LCH_WORKSPACE Workspace,
lulong Options)
Arguments
Workspace The handle of an existing workspace object.
Options The desired display options. Valid options are:
LCF_DISPLAY_OPTION_PAGE_BREAKS
LCF_DISPLAY_OPTION_GRID_LINES
Note Options can be binary OR'd together. For example:
Options = LCF_DISPLAY_OPTION_PAGE_BREAKS | LCF_DISPLAY_OPTION_GRID_LINES;
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lulong DisplayOptions;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Turn on all display options. */
DisplayOptions =
LCF_DISPLAY_OPTION_PAGE_BREAKS |
LCF_DISPLAY_OPTION_GRID_LINES;
. . .
/* Set the display options settings. */
Status = LciWsSetDisplayOptions(Workspace,DisplayOptions);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the workspace frame display mode.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetFrameType
(LCH_WORKSPACE Workspace,
lushort FrameSetting)
Arguments
Workspace The handle of an existing workspace object.
FrameSetting The desired frame setting type. Valid settings are:
LCI_FRAME_STANDARD
LCI_FRAME_CHARACTERS
LCI_FRAME_INCHES
LCI_FRAME_METRIC
LCI_FRAME_POINTS
LCI_FRAME_NONE
Note These settings correspond to those available in the Window Display Options dialog box.
Returns
LCS_SUCCESS »Page
LCS_INVALID_TYPE »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort FrameSettings = LCI_FRAME_INCHES;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the workspace frame display mode. */
Status = LciWsSetFrameType(Workspace,FrameSettings);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the international currency sign and type.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetIntlCurrency
(LCH_WORKSPACE Workspace,
lptr(lmbcs) lpIntlCurrencySign,
lushort IntlCurrencyType)
Arguments
Workspace The handle of an existing workspace object.
lpIntlCurrencySign A pointer to a lmbcs string that contains the desired currency sign. Its length must not exceed LCI_MAX_CURRSIGN_LEN.
IntlCurrencyType The desired international currency type. Possible values are:
Constant Meaning
LCI_INTL_CURRENCY_PREFIX sign precedes number
LCI_INTL_CURRENCY_SUFFIX sign follows number
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
LCS_STR_TOO_LONG »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs IntlCurrencySign[LCI_MAX_CURRSIGN_LEN];
lushort IntlCurrencyType = LCI_INTL_CURENCY_PREFIX;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Copy the currency type to a string. */
lstrcpy(IntlCurrencySign,'$');
. . .
/* Set the international currency sign and type. */
Status = LciWsSetIntlCurency
(Workspace,IntlCurrencySign,IntlCurrencyType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the international date type.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetIntlDateType
(LCH_WORKSPACE Workspace,
lushort IntlDateType)
Arguments
Workspace The handle of an existing workspace object.
IntlDateType The desired international date type. Possible values are:
Constant Meaning
LCI_INTL_DATE_MMDDYYSLASH MM/DD/YY
LCI_INTL_DATE_DDMMYYSLASH DD/MM/YY
LCI_INTL_DATE_DDMMYYDOT DD.MM.YY
LCI_INTL_DATE_YYMMDDHYPHEN YY-MM-DD
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort IntlDateType = LCI_INTL_DATE_DDMMYYDOT;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the international date type */
Status = LciWsSetDateType(Workspace,IntlDateType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the international negative type. This determines whether 1-2-3 uses a minus sign or parentheses to indicate negative values formatted as comma or currency. The default is parentheses.
Definition
Sets the international negative type.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetIntlNegType
(LCH_WORKSPACE Workspace,
lushort IntlNegType)
Arguments
Workspace The handle of an existing workspace object.
IntlNegType The desired international negative type. Possible values are:
Constant Meaning
LCI_INTL_NEG_PARENS encloses negative value in parentheses
LCI_INTL_NEG_SIGN precedes negative value with a minus sign
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort IntlNegType = LCI_INTL_NEG_PARENS;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the international neg type */
Status = LciWsSetNegType(Workspace,IntlNegType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the international punctuation type.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetIntlPuncType
(LCH_WORKSPACE Workspace,
lushort IntlPuncType)
Arguments
Workspace The handle of an existing workspace object.
IntlPuncType The desired international punctuation type. Possible values, listed in order of decimal point, argument separator, and thousands separator, are:
Constant Meaning
LCI_INTL_PUNC_A .,,
LCI_INTL_PUNC_B ,..
LCI_INTL_PUNC_C .;,
LCI_INTL_PUNC_D ,;.
LCI_INTL_PUNC_E .,space
LCI_INTL_PUNC_F ,.space
LCI_INTL_PUNC_G .;space
LCI_INTL_PUNC_H ,;space
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort IntlPuncType = LCI_INTL_PUNC_C;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the international punctuation type. */
Status = LciWsSetPuncType(Workspace,IntlPuncType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the international time type.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetIntlTimeType
(LCH_WORKSPACE Workspace,
lushort IntlTimeType)
Arguments
Workspace The handle of an existing workspace object.
IntlTimeType The desired international time type. (Lowercase letters will actually be displayed in the positions shown. Uppercase characters indicate number positions.) Possible values are:
Constant Meaning
LCI_INTL_TIME_HHMMSSCOLON HH:MM:SS
LCI_INTL_TIME_HHMMSSDOT HH.MM.SS
LCI_INTL_TIME_HHMMSSCOMMA HH,MM,SS
LCI_INTL_TIME_HHHMMMSSS HHhMMmSSs
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort IntlTimeType = LCI_INTL_TIME_HHMMSSDOT;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the International time type */
Status = LciWsSetIntlTimeType(Workspace,IntlTimeType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the the default extension 1-2-3 uses to list files.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetListExt
(LCH_WORKSPACE Workspace,
lptr(lmbcs) lpListExt)
Arguments
Workspace The handle of an existing workspace object.
lpListExt A pointer to a lmbcs string that contains the desired list extension string. Its length must not exceed LCI_MAX_FILEEXT_LEN.
Returns
LCS_SUCCESS »Page
LCS_INVALID_EXTENSION »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs ListExt[LCI_MAX_FILEEXT_LEN];
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Copy the file extension into the string. */
lstrcpy(ListExt,"TXT");
. . .
/* Set the name of the default extension 1-2-3 uses to list files. */
Status = LciWsSetListExt(Workspace,ListExt);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the window synchronization flag that specifies whether the top and bottom or left and right panes of a window are synchronized when the window is split. LTRUE signifies that the windows are synchronized; LFALSE that they are unsynchronized.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetPaneSyncFlag
(LCH_WORKSPACE Workspace,
lbool PaneSyncFlag)
Arguments
Workspace The handle of an existing workspace object.
PaneSyncFlag The desired flag value.
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lbool PaneSyncFlag = LTRUE;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the Pane sync flag to TRUE. */
Status = LciWsSetPaneSyncFlag(Workspace,PaneSyncFlag);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the mode that 1-2-3 uses for displaying worksheets in windows and panes. 1-2-3 can horizontally or vertically split the screen into two windows, create a perspective view of three consecutive worksheets or display the current worksheet in a single window.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetPaneType
(LCH_WORKSPACE Workspace,
lushort PaneType)
Arguments
Workspace The handle of an existing workspace object.
PaneType The desired pane type. Possible values are:
Constant Meaning
LCI_PANE_TYPE_HORIZ two horizontal panes
LCI_PANE_TYPE_VERT two vertical panes
LCI_PANE_TYPE_PERSPECTIVE perspective view
LCI_PANE_TYPE_SINGLE single pane
Returns
LCS_SUCCESS »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_BOUNDS »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort PaneType = LCI_PANE_TYPE_PERSPECTIVE;
. . .
/* Find the workspace corresponding to the current
1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the mode that 123 uses for displaying worksheets in
windows and panes. */
Status = LciWsSetPaneType(Workspace,PaneType);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the default extension that 1-2-3 uses to save files.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetSaveExt
(LCH_WORKSPACE Workspace,
lptr(lmbcs) lpSaveExt)
Arguments
Workspace The handle of an existing workspace object.
lpSaveExt A pointer to a lmbcs string that contains the new save extension. Its length must not exceed LCI_MAX_FILEEXT_LEN.
Returns
LCS_SUCCESS »Page
LCS_INVALID_EXTENSION »Page
LCS_INVALID_USE »Page
LCS_OUT_OF_MEMORY »Page
LCS_STACK_OVERFLOW »Page
Example
#include "windows.h"
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lmbcs SaveExt[LCI_MAX_FILEEXT_LEN];
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Copy the extension into the string. */
lstrcpy(SaveExt,"SAV");
. . .
/* Set the default extension that 1-2-3 uses to save files. */
Status = LciWsSetSaveExt(Workspace,SaveExt);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Sets the current undo mode in 1-2-3. Undo should not be set ON unless it was turned off temporarily during the current execution.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetUndoMode
(LCH_WORKSPACE Workspace,
lushort UndoMode)
Arguments
Workspace The handle of an existing workspace object.
UndoMode The desired undo mode. It can be one of the following:
LCI_UNDO_OFF
LCI_UNDO_OFF_UNTIL_READY
LCI_UNDO_ON
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_INVALID_USE »Page
LCS_INVALID_UNDO_MODE »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Construct a workspace object. */
Status = LciWsConstructCurr(Context, &Workspace);
. . .
/* Enable Undo in 1-2-3. */
Status = LciWsSetUndoMode(Workspace, LCI_UNDO_ON);
. . .
/* Destroy the workspace object. */
Status = LciWsDestroy(&Workspace);
Definition
Sets the workspace display zoom size (between 25% and 400%, inclusive).
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetZoom
(LCH_WORKSPACE Workspace,
lushort ZoomAmount)
Arguments
Workspace The handle of an existing workspace object.
ZoomAmount The desired amount of display. Valid values are between 25 and 400, inclusive.
Returns
LCS_SUCCESS »Page
LCS_INVALID_NUM »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
lushort ZoomAmount = 225;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Set the zoom amount to 225%. */
Status = LciWsSetZoom(Workspace,ZoomAmount);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Turns display of worksheet tabs on and off.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsSetTabState
(LCH_WORKSPACE Workspace,
lbool On_Off,
lptr(lbool) lpPrevState)
Arguments
Sheet The handle of an existing sheet object.
On_Off LTRUE to turn on. LFALSE to turn off.
lpPrevState The previous state of the sheet tabs.
Returns
LCS_SUCCESS »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
lbool PrevState;
LCT_STATUS Status;
. . .
/* Find the Workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context,&Workspace);
. . .
/* turn off display of worksheet tabs */
Status = LciWsSetTabState(Workspace, LFALSE, &PrevState);
....
/* return tabs to original state */
Status = LciWsSetTabState(Workspace,PrevState,&PrevState);
Status = LciWsDestroy(&Workspace);
Definition
Reverses the effects of the most recently executed undoable command or action. This is equivalent to the user choosing Edit Undo or pressing Alt + Backspace in 1-2-3. Undo should (subsequently) be disabled with LciWsSetUndoMode »Page using LCI_UNDO_ODD or LCI_UNDO_OFF_UNTIL_READY if this routine is used.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsUndoCommand
(LCH_WORKSPACE Workspace)
Arguments
Workspace The handle of an existing workspace object.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_INVALID_USE »Page
LCS_UNDO_DISABLED »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Construct a workspace object. */
Status = LciWsConstructCurr(Context, &Workspace);
. . .
/* Undo the last command. */
Status = LciWsUndoCommand(Workspace);
. . .
/* Destroy the workspace object. */
Status = LciWsDestroy(&Workspace);
Definition
Unregisters the undo handler for a workspace object.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsUnregisterUndoHandler
(LCH_WORKSPACE Workspace)
Argument
Workspace The handle of an existing workspace object for which you have previously registered an undo handler by calling LciWsRegisterUndoHandler »Page .
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Construct a workspace object. */
Status = LciWsConstructCurr(Context, &Workspace);
. . .
/* Unregister a custom undo handler for this workspace object. */
Status = LciWsUnregisterUndoHandler(Workspace);
. . .
/* Destroy the workspace object. */
Status = LciWsDestroy(&Workspace);
Definition
Saves the current worksheet global settings as the default settings in the [CONFIG] section of the 123R4.INI file. When 1-2-3 starts, it reads the default settings from the 123R4.INI file.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsUpdateSettings
(LCH_WORKSPACE Workspace)
Arguments
Workspace The handle of an existing workspace object.
Returns
LCS_SUCCESS »Page
LCS_CLOSE_ERROR »Page
LCS_INVALID_USE »Page
LCS_OPEN_ERROR »Page
LCS_STACK_OVERFLOW »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
/* Find the workspace corresponding to the current 1-2-3 session. */
Status = LciWsConstructCurr (Context, &Workspace);
. . .
/* Update the settings in the 123R4.INI file. */
Status = LciWsUpdateSettings(Workspace);
. . .
Status = LciWsDestroy(&Workspace);
Definition
Writes an undo record to 1-2-3 undo history.
Format
#include "lcicomn.h"
#include "lciwkspc.h"
LCT_STATUS LCI_CALL LciWsWriteUndoRecord
(LCH_WORKSPACE Workspace,
lptr(void) lpUndoData,
lushort Length)
Arguments
Workspace The handle of an existing workspace object for which you have previously registered an undo handler by calling LciWsRegisterUndoHandler »Page .
lpUndoData Pointer to the undo data record. This should contain the data necessary to reverse the effects of a particular operation.
Length Length of the buffer in bytes pointed to by lpUndoData.
Returns
LCS_SUCCESS »Page
LCS_STACK_OVERFLOW »Page
LCS_INVALID_USE »Page
LCS_UNDO_DISABLED »Page
LCS_NO_UNDO_HANDLER »Page
Example
#include "lcicomn.h"
#include "lciwkspc.h"
. . .
LCH_WORKSPACE Workspace;
LCT_STATUS Status;
. . .
struct
{
lushort UndoCode;
lushort UndoInfo;
}
UndoData;
. . .
/* Construct a workspace object. */
Status = LciWsConstructCurr(Context, &Workspace);
. . .
/* Initialize an undo record with data needed to undo a command. */
UndoData.UndoCode = 1;
UndoData.UndoInfo = 123;
. . .
/* Write the undo record. */
Status = LciWsWriteUndoRecord(Workspace, &UndoData, sizeof(UndoData));
. . .
/* Destroy the workspace object. */
Status = LciWsDestroy(&Workspace);
1$ADK_Table_of_Contents
2$1-2-3 @Functions Group
3$LciAtAvg
4KAverage;Avg;Values-Average
5$LciAtChar
6KChar;LMBCS Character String;LMBCS Code
7$LciAtCount
8KCount;Count nonblank cells;Nonblank cell count
9$LciAtCTerm
10KCTerm;Investment PV to FV;Number of Periods;Term
11$LciAtD360
12KD360;Days;Days Between Dates
13$LciAtDate
14KDate;Date Number;YY/MM/DD Number
15$LciAtDateValue
16KDate Number;DateValue
17$LciAtDAvg
18KDatabase Average Values;DAvg;DB Field Values
19$LciAtDay
20KDay;Day of Month
21$LciAtDays360
22KDays;Days Between Dates;Days360
23$LciAtDCount
24KDatabase nonblank cell count;DCount;Nonblank Cells
25$LciAtDDB
26KDDB;Depreciation Allowance;Double-Declining Balance
27$LciAtDGet
28KDatabase Table Value;DGet;Get Value/Label
29$LciAtDMax
30KDMax;Maximum Value in Database
31$LciAtDMin
32KDMin;Minimum Value in Database
33$LciAtDStD
34KDatabase Population Deviation;DStD;Population Standard Deviation
35$LciAtDStDS
36KDatabase Sample Deviation;DStDS;Sample Standard Deviation
37$LciAtDSum
38KDatabase Sum;DSum;Sum of Values
39$LciAtDVar
40KDatabase Population Variance;DVar;Variance
41$LciAtDVarS
42KDatabase Sample Variance;DVarS;Sample Variance;Variance
43$LciAtExact
44KExact;Exact Match;Match Strings;Test Match
45$LciAtFind
46KFind;Find Search String
47$LciAtFV
48KFuture Value;FV;Investment Future Value
49$LciAtHLookup
50KHLookup;Horizontal Lookup;Lookup Table;Range Row Lookup;Row Contents
51$LciAtHour
52KHour;Hour Value;Time Number
53$LciAtInfo
54K1-2-3 Information;Info;Information;System;System Information
55$LciAtIRR
56KInternal Rate of Return;Investment IRR;IRR;Profit
57$LciAtLmbcsGroup
58$LciAtIsERR
59KBoolean ERR;Cell Input Value;Error Contents;IsERR
60$LciAtIsNA
61KBoolean NA;Cell NA Value;IsNA;NA Contents
62$LciAtIsNumber
63KCell Number Value;IsNumber;Number Contents;Numeric Value
64$LciAtIsRange
65KFind Range Name;IsRange;Range Name Defined
66$LciAtIsString
67KBlank;Cell Contents Test;ERR;IsString;Label;NA;Number
68$LciAtLeft
69KGet First CharCount Character;Get Left Character;Left
70$LciAtLower
71KConvert Uppercase;Lower;Lowercase
72$LciAtMax
73KMax;Max Value in Range;Maximum Value
74$LciAtMid
75KGet String Characters;Mid;Specify Characters To Get
76$LciAtMin
77KMin;Minimum Value;Smallest Range Value
78$LciAtMinute
79KConvert Time Number;Get Minute;Minute;Minute
80$LciAtMonth
81KConvert Date Number;Get Month;Month;Month
82$LciAtNewLine
83KCR/LF;NewLine;NewLine
84$LciAtNow
85KCurrent Date;Current Time;Date;Date & Time;Now;Time
86$LciAtNPV
87KFuture Cash Flow Values;Net Present Value;NPV
88$LciAtPmt
89KLoan Amortization;Payment;Periodic Payment;Pmt
90$LciAtProper
91KCap Letters;Initial Caps;Proper;Proper Capitalization
92$LciAtPV
93KInvestment Value;Present Value;PV
94$LciAtRate
95KFuture Value Rate;Growth;Interest Rate;Rate
96$LciAtRepeat
97KDupCount;Repeat;Repeat;Repeat a String
98$LciAtReplace
99KCharCount;Replace;Replace String Characters
100$LciAtRight
101KCharacters;CharCount;Get Last Characters;Get Right Characters;Right
102$LciAtRound
103KPlaces;Round;Round Off
104$LciAtSecond
105KConvert Time Number;Get Seconds;Second;Time Number
106$LciAtSLn
107KAllowance;Depreciation;SLn;Straight Line Depreciation
108$LciAtStD
109KDeviation;Population;Population Deviation;Standard Deviation;StD
110$LciAtStDS
111KRange Deviation;Sample;Sample Standard Deviation;StDS
112$LciAtString
113KConvert Number;Number to String;String
114$LciAtSum
115KAdd;Add Values;Sum;Sum a Range
116$LciAtSYD
117KSum Digits;Sum of digits;Sum-of-the-years digits;SYD;SYD Depreciation
118$LciAtTerm
119KFuture Value;Investment Term;Payment Periods;Term
120$LciAtTime
121KConvert HH/MM/SS;Get Time Number;Time
122$LciAtTimeValue
123KGet Time Number;Time Value;TimeValue
124$LciAtToday
125KDate;Today;Today;Today's Date
126$LciAtUpper
127KCap Letters;Convert Lowercase;Upper;Uppercase
128$LciAtValue
129KConvert Number;Number to Value;Numeric Value;Value
130$LciAtVar
131KPopulation;Population Variance;Range Population;Var;Variance
132$LciAtVarS
133KRange Variation;Sample;Sample Variation;Variation;VarS
134$LciAtVDB
135KAsset;Declining Balance;Depreciation Allowance;VDB
136$LciAtVLookup
137KColumn Lookup;Lookup;LookupValue;Vertical Lookup;VLookup
138$LciAtYear
139KConvert Date Number;Date;Year;Year;Year Number
140$Cell Library Procedures
141KCell constructor;cell library;cell library procedures;cell procedures;cells;LciCl
142$Cell Constructor: Address String
143Kaddress;cell address;Cell constructor;creating cell;creating cell constructor
144$LciClConstructCoords
145$LciClConstructCurr
146$Cell Copy+ cell_procs:025
147Kcell copy;copy;copy cell procedure;Copying cells
148$Cell Destructor
149Kcell destructor;Deleting cell constructor;deleting cell instance;removing cell instance
150$LciClErase
151$LciClFormatRow
152$LciClGetAddr
153$LciClGetBoldFlag
154$LciClGetBorderColor
155$LciClGetBorders
156$LciClGetCol
157$LciClGetColor
158$LciClGetColorNegFlag
159$Column Width
160Kcell width;changing cell width;changing column width;column width;Column widths;width
161$LciClGetContentsNum
162$LciClGetContentsStr
163$LciClGetContentsType
164$LciClGetContext
165$LciClGetCoords
166$File Name
167Kfile name;file names;Filename;naming files;pathname;workfile name
168$LciClGetFont
169$LciClGetFont2
170$LciClGetFormat
171$LciClGetItalicFlag
172$LciClGetLabelType
173$LciClGetParentFlag
174$LciClGetPattern
175$LciClGetProtectFlag
176$LciClGetRow
177$LciClGetRowHeight
178$LciClGetShadowFlag
179$LciClGetSheet
180$LciClGetUnderline
181$LciClGetValidFlag
182$LciClGetValNum
183$LciClGetValStr
184$LciClGetValType
185$Cell Move
186KCell move;move;move procedure;moving cells
187$LciClNextSheet
188$LciClPrevSheet
189$LciClRunMacro
190$LciClSetBoldFlag
191$LciClSetBorderColor
192$LciClSetBorders
193$LciClSetCol
194$LciClSetColor
195$LciClSetColorNegFlag
196$LciClSetColWidth
197Kcell width;changing cell width;changing column width;column width;Column widths;width
198$LciClSetContentsNum
199$LciClSetContentsStr
200$LciClSetCoords
201$LciClSetFileName
202$LciClSetFont
203$LciClSetFont2
204$LciClSetFormat
205$LciClSetItalicFlag
206$LciClSetLabelType
207$LciClSetParenFlag
208$LciClSetPattern
209$LciClSetProtectFlag
210$LciClSetRow
211$LciClSetRowHeight
212$LciClSetShadowFlag
213$LciClSetSheet
214$LciClSetUnderline
215$LcxClGetAttributeFlags
216$LcxClGetAttributeFlags2
217$LcxClSetAttributeFlags
218$LcxClSetAttributeFlags2
219$Event Group
220KEvents
221$Registration Functions
222$Callback Functions
223KGet;LciEvGetxxx;LciEvSetxxx;Set:Callbacks
224$Event Definitions
225K1-2-3 Events;Events;LCE arguments
226$LciEvRegister
227$LciEvUnregister
228$LciEvGetArgCell
229$LciEvGetArgCellCoord
230$LciEvGetArgInt
231$LciEvGetArgNum
232$LciEvGetArgRange
233$LciEvGetArgStr
234$LciEvGetErrCode
235$LciEvGetParsedName
236$LciEvPostErrMsg
237$LciEvSetArgInt
238$LciEvSetArgStr
239$LciEvSetArgRange
240$Data Events
241KData Events;Database;DB Events
242$LCE_DATA_DD
243$LCE_DATA_DECG
244$LCE_DATA_DED
245$LCE_DATA_DEOC
246$LCE_DATA_DEOT
247$LCE_DATA_DER
248$LCE_DATA_DF
249$LCE_DATA_DMI
250$LCE_DATA_DMM
251$LCE_DATA_DPG
252$LCE_DATA_DPR
253$LCE_DATA_DQDD
254$LCE_DATA_DQF
255$LCE_DATA_DQF
256$LCE_DATA_DQME
257$LCE_DATA_DQMI
258$LCE_DATA_DQMR
259$LCE_DATA_DQR
260$LCE_DATA_DRG
261$LCE_DATA_DRG
262$LCE_DATA_DRR
263$LCE_DATA_DSR
264$LCE_DATA_DSR
265$LCE_DATA_DTLG
266$LCE_DATA_DTR
267$LCE_DATA_DT1
268$LCE_DATA_DT2
269$LCE_DATA_DT3
270$Display Events
271KDisplay;Display Events;Menu Prompt:Control Panel;Window Events
272$LCE_DISP_CP_CONTENTS
273$LCE_GET_CDLL_PREFIX
274$LCE_WINDOW_SHOW
275$LCE_DISP_MENU_PANEL
276$File Events
277KFile Admin;File Combine;File Erase;File Events;File Extract;File Import;File New;File Open;File Retrieve;File Save
278$LCE_FILE_FAL
279$LCE_FILE_FCA
280$LCE_FILE_FCC
281$LCE_FILE_FCS
282$LCE_FILE_FE
283$LCE_FILE_FIN
284$LCE_FILE_FIT
285$LCE_FILE_FNA
286$LCE_FILE_FNB
287$LCE_FILE_FOA
288$LCE_FILE_FOB
289$LCE_FILE_FR
290$LCE_FILE_FRO_NAME
291$LCE_FILE_FS
292$LCE_FILE_FXF
293$LCE_FILE_FXV
294$LCE_FILE_WDF
295$Format Events
296KCell Format;Cell Range;Clear Format;Format Events;Move Format;Range Format
297$LCE_FMT_CLEAR_FMTS
298$LCE_FMT_MOVED_FMTS
299$LCE_FMT_SET_CELL_FMT
300$LCE_FMT_RF_FMTS
301$Graph Events
302KBuild Chart;Graph Events;Graph View;Reset GraphsGraph Name
303$LCE_GRAPH_BUILD
304$LCE_GRAPH_DO_CHART
305$LCE_GRAPH_GNC
306$LCE_GRAPH_GNR
307$LCE_GRAPH_GNR
308$LCE_GRAPH_GNU
309$LCE_GRAPH_GNU
310$Keyboard Events
311KHandler Input;Keyboard Events;Keyboard Input;Macro Input;READY mode
312$LCE_KBREADY
313$LCE_KBDSTUFFHI
314$LCE_KBDSTUFFLO
315$LCE_KBDTRANSLATEHI
316$LCE_KBDTRANSLATELO
317$Macro Events
318KAdvanced Macro;Macro Events;Macro Execution;Single Step;STEP Mode
319$LCE_MACRO_BEGIN
320$LCE_MACRO_END
321$LCE_MACRO_EXEC
322$LCE_MACRO_STEP
323$Main Menu Events
324KAccess Menu;End 1-2-3;Main Menu;QUIT;System
325$LCE_QUIT
326$LCE_SYSTEM
327$Miscellaneous Events
328KAbort;Error;GoTo;Menu;Miscellaneous
329$LCE_ABORT
330$LCE_GOTO
331$LCE_GOTO_END
332$LCE_MENU
333$Mouse Events
334KClick;Click Frame;Drag;Mouse;Mouse Events
335$LCE_MOUSE_CLICK_CELL
336$LCE_MOUSE_DRAG_COMPLETE
337$LCE_MOUSE_CLICK_FRAME
338$Poll Events
339K1-2-3 Scheduler;Before Handlers;Poll;Poll Events;Priorities;Register Hanler;Tasks
340$LCE_POLL
341$Printing Events
342KPrint Encoded Go;Print File Go;Print Printer Go;Printing;Printing Events
343$LCE_PRINT_PEG
344$LCE_PRINT_PFG
345$LCE_PRINT_PPG
346$Range Events
347KRange;Range Copy;Range Create;Range Erase;Range Events;Range Fixup;Range Input;Range Justify;Range Label;Range Move;Range Name;Range Preselect;Range Transpose;Range Unprotect;Range Value
348$LCE_RANGE_COPY
349$LCE_RANGE_FIXUP
350$LCE_RANGE_MOVE
351$LCE_RANGE_PRESELECT
352$LCE_RANGE_PRESELECT_CLEAR
353$LCE_RANGE_RE
354$LCE_RANGE_RI
355$LCE_RANGE_RJ
356$LCE_RANGE-RLC
357$LCE_RANGE_RLL
358$LCE_RANGE_RLR
359$LCE_RANGE_RNC
360$LCE_RANGE_RND
361$LCE_RANGE_RNLD
362$LCE_RANGE_RNLL
363$LCE_RANGE_RNLR
364$LCE_RANGE_RNLU
365$LCE_RANGE_RNNC
366$LCE_RANGE_RNND
367$LCE_RANGE_RNNR
368$LCE_RANGE_RNR
369$LCE_RANGE_RNU
370$LCE_RANGE_RT
371$LCE_RANGE_RV
372$Recalc Events
373KRecalc;Recalc Events;Worksheet Recalc
374$LCE_RECALC
375$Worksheet Events
376KWorksheet;Worksheet Delete;Worksheet Erase;Worksheet Events;Worksheet Global;Worksheet Hide;Worksheet Insert;Worksheet Window
377$LCE_WKS_WDC
378$LCE_WKS_WDR
379$LCE_WKS_WDS
380$LCE_WKS_WEY
381$LCE_WKS_WGGD
382$LCE_WKS_WGGE
383$LCE_WKS_WHD
384$LCE_WKS_WHE
385$LCE_WKS_WIC
386$LCE_WKS_WIR
387$LCE_WKS_WIS
388$LCE_WKS_WWC
389$LCE_WKS_WWG
390$LCE_WKS_WWH
391$LCE_WKS_WWP
392$LCE_WKS_WWV
393$Undo Events
394KFlush;Rewind;Undo;Undo Command;Undo Events;Undo Flush;Undo Rewind
395$LCE_UNDO_FLUSH
396$LCE_UNDO_REWIND
397$GUI (Graphical) Library
398KGraphical library;GUI (Graphical) Library
399$Toolclass objects
400KToolclass objects (GUI)
401$LciTcAddToolProc
402$LciTcConstructCurr
403$LciTcConstructName
404$LciTcDefToolProc
405$LciTcDeleteToolProc
406$LciTcDestroy
407$LciTcGetInstanceCount
408$LciTcGetMenu
409$LciTcGetMenulds
410$LciTcIterInstances
411$LciTcRegister
412$LciTcRunDialog
413$LciTcSendControlMsg
414$LciTcSetMenu
415$LciTcUnregister
416$Tool Instance objects
417KTool Instance objects (GUI)
418$LciTiActivate
419$LciTiConstructClass
420$LciTiConstructCurr
421$LciTiDefWindowProc
422$LciTiDestroy
423$LciTiGetClass
424$LciTiGetTitle
425$LciTiGetTitleLen
426$LciTiGetWindowHandle
427$LciTiSetTitle
428$Menu objects
429KMenu objects (GUI)
430$LciMnConstructNew
431$LciMnDeleteItem
432$LciMnDestroy
433$LciMnGetCheckFlag
434$LciMnGetEnableFlag
435$LciMnGetItemCount
436$LciMnGetLabel
437$LciMnGetSubMenu
438$LciMnInsertItem
439$$ LciMnRedraw
440$LciMnSetCheckFlag
441$LciMnSetEnableFlag
442$LciMnSetLable
443$Preset and Validate Objects
444KPreset objects (GUI);Validate objects (GUI)
445$LciPsGetControl
446$LicPsGetValue
447$LciVlGetValue
448$1-2-3 for Windows Tool Messages
449KMessages (1-2-3 for Windows Tool Messages);Tool procedure messages
450$ToolMsg_Activate
451$ToolMsg_Command
452$ToolMsg_DlgExecStr
453$ToolMsg_DlgInit
454$ToolMsg_DlgPostDisplay
455$ToolMsg_DlgPreDisplay
456$ToolMsg_DlgPreset
457$ToolMsg_DlgProc
458$ToolMsg_DlgTerm
459$ToolMsg_DlgValidate
460$ToolMsg_Help
461$ToolMsg_iconBar_Init
462$ToolMsg_LongPrompt
463$ToolMsg_MenuExecStr
464$ToolMsg_MenuProc
465$ToolMsg_Menureset
466$ToolMsg_Popup
467$LMBCS Functions
468KCharacter Set;LMBCS;Lotus Multi-byte Character Set;Strings
469$LciMbAppendChr
470$LciMbAppendSubStr
471$LciMbCharCase
472$LciMbChrBytes
473$LciMbChrSize
474$LciMbConvertAnsiToLmbcs
475$LciMbConvertLmbcsToAnsi
476$LciMbDeleteChr
477$LciMbDestroy
478$LciMbFindChr
479$LciMbFindPrevChr
480$LciMbInsertChr
481$LciMbLmbcsToNative
482$LciMbNativeToLmbcs
483$LciMbPeekNextChr
484$LciMbReplaceChr
485$LciMbSkipNextChr
486$LciMbSkipNonSpaces
487$LciMbSkipPrevChr
488$LciMbSkipSpaces
489$LciMbStrcmp
490$LciMbStrcmpCollated
491$LciMbStrcmpWildcard
492$LciMbStrlen
493$LciMbStrncmp
494$LciMbBrowseCodepage
495$LciMbBrowseConstruct
496$LciMbBrowseDestroy
497$LciMbConstruct
498$LciMbCountChrs
499$LciMbGetCodepage
500$LciMbGetGroup
501$LciMbTransLmbcsToNative
502$LciMbTransNativeToLmbcs
503$Load LMBCS Server
504KLMBCS Server;Load LMBCS Server
505$Unload LMBCS Server
506KLMBCS Server;Unload LMBCS Server
507$Load Functions
508KAdd-in data;C Runtime functions;Executing an add-in;Load functions
509$LciLdGetAddinData
510$LciLdGetAddinHandle
511$LciLdGetLibHandle
512$LciLdGetRunInfo
513$LciLdGetStackInfo
514$LciLdLoadCompatLib
515$LciLdSetAddinData
516$LciLdSetAddinHandle
517$LciLdSetStackInfo
518$LciLdUnloadCompatLib
519$Math Functions
520KLci math functions;Math functions;summary
521$LciMtAbs
522$LciMtACos
523$LciMtAdd
524$LciMtASin
525$LciMtATan
526$LciMtATan2
527$LciMtCompare
528$LciMtCompareReturn
529$LciMtCos
530$LciMtDiv
531$LciMtDropMany
532$LciMtDropOne
533$LciMtDup
534$LciMtDupNth
535$LciMtEq
536$LciMtExp
537$LciMtGetDepth
538$LciMtGetType
539$LciMtGt
540$LciMtGte
541$LciMtInt
542$LciMtLN
543$LciMtLog
544$LciMtLt
545$LciMtLte
546$LciMtMod
547$LciMtMul
548$LciMtNegate
549$LciMtNeq
550$LciMtPopFloat8
551$LciMtPopFloat10
552$LciMtPopLong
553$LciMtPopLongReturn
554$LciMtPopShort
555$LciMtPopShortReturn
556$LciMtPow
557$LciMtPushErr
558$LciMtPushFloat8
559$LciMtPushFloat10
560$LciMtPushLong
561$LciMtPushNa
562$LciMtPushOne
563$LciMtPushPi
564$LciMtPushRand
565$LciMtPushShort
566$LciMtPushZero
567$LciMtSin
568$LciMtSqrt
569$LciMtSub
570$LciMtSwap
571$LciMtSwapNth
572$LciMtTan
573$The Range Functions Group
574$LciRgCalc
575$LciRgConstructAddr
576$LciRgConstructCoords
577$LciRgConstructCurr
578$LciRgCopy
579$LciRgCopyVals
580$LciRgCoords2Name
581$LciRgCreateName
582$LciRgCreateScenario
583$LciRgCreateVersion
584$LciRgDeleteName
585$LciRgDestroy
586$LciRgEditCopy
587$LciRgtEditCut
588$LciRgEditPaste
589$LciRgEditPasteSpec
590$LciRgErase
591$LciRgGetAddr
592$LciRgGetColCount
593$LciRgGetContext
594$LciRgGetCoords
595$LciRgGetFileName
596$LciRgGetFirstCol
597$LciRgGetFirstRow
598$LciRgGetFirstSheet
599$LciRgGetLastCol
600$LciRgGetLastRow
601$LciRgGetLastSheet
602$LciRgGetNote
603$LciRgGetRowCount
604$LciRgGetSheetCount
605$LciRgGetValidFlag
606$LciRgIterCells
607$LciRgJustify
608$LciRgMove
609$LciRgRegisterCalc
610$LciRgRunMacro
611$LciRgSetBoldFlag
612$LciRgSetBorderColor
613$LciRgSetBorders
614$LciRgSetColor
615$LciRgSetColorNegFlag
616$LciRgSetColWidth
617$LciRgSetFont
618$LciRgSetFont2
619$LciRgSetFormat
620$LciRgSetHiddenFlag
621$LciRgSetItalicFlag
622$LciRgSetLabelType
623$LciRgSetNote
624$LciRgSetOutline
625$LciRgSetParenFlag
626$LciRgSetPattern
627$LciRgSetProtectFlag
628$LciRgSetRowHeight
629$LciRgsetShadowFlag
630$LciRgSetUnderline
631$LciRgTranspose
632$LciRgUnderlineName
633$LciRgUnregisterCalc
634$LcxRgSetAttributeFlags
635$LcxRgSetAttributeFlags2
636$Registering @Functions
637K@Functions, registering;Registering @functions
638$LciAfGetArgLong
639$LciAfGetArgNum
640$LciAfGetArgRange
641$LciAfGetArgShort
642$LciAfGetArgStr
643$LciAfGetArgType
644$LciAfForceArgRange
645$LciAfRegister
646$LciAfReturnArgLong
647$LciAfReturnArgNum
648$LciAfReturnArgShort
649$LciAfReturnArgStr
650$LciAfReturnArgType
651$LciAfUnregister
652$Registering Macro Keywords
653Kmacro registration;Registering macro keywords
654$LciMcGetArgLong
655$LciMcGetArgNum
656$LciMcGetArgRange
657$LciMcGetArgShort
658$LciMcGetArgStr
659$LciMcGetArgType
660$LciMcRegister
661$LciMcUnregister
662$Return codes
663KError codes;Return codes;Signals;Status codes
664$LCS_ALREADY_EXISTS
665$LCS_ALREADY_GROUPED
666$LCS_ALREADY_IN_MEMORY
667$LCS_ALREADY_RESERVED
668$LCS_CLOSE_ERROR
669$LCS_CONVERSION_ERROR
670$LCS_DIFFERENT_FILES
671$LCS_DISK_ERROR
672$LCS_END_OF_FILE
673$LCS_ERR
674$LCS_EVENT_MSG
675$LCS_EVENT_MULTI_ERR
676$LCS_EVENT_REPLACE
677$LCS_FILE_IN_USE
678$LCS_FILE_NOT_FOUND
679$LCS_FILE_NOT_SEALED
680$LCS_FILE_SEALED
681$LCS_HIDDEN_COL
682$LCS_HIDDEN_SHEET
683$LCS_INCORRECT_EXTRACT_TYPE
684$LCS_INCORRECT_WRITE_TYPE
685$LCS_INTERNAL_ERROR
686$LCS_INTERNAL_ERROR
687$LCS_INVALID_ADDRESS
688$LCS_INVALID_ARG_FLAGS
689$LCS_INVALID_CELL
690$LCS_INVALID_CLASS
691$LCS_INVALID_COL
692$LCS_INVALID_COUNT
693$LCS_INVALID_EXTENSION
694$LCS_INVALID_EXTRACT_TYPE
695$LCS_INVALID_FILENAME
696$LCS_INVALID_FORMAT
697$LCS_INVALID_FORMULA
698$LCS_INVALID_ID
699$LCS_INVALID_FROM_CELL
700$LCS_INVALID_INDEX
701$LCS_INVALID_ITER_SPEC
702$LCS_INVALID_LABEL_TYPE
703$LCS_INVALID_NAME
704$LCS_INVALID_NAME
705$LCE_INVALID_NOTE
706$LCS_INVALID_NUM
707$LCS_INVALID_ORDER
708$LCS_INVALID_PANE
709$LCS_INVALID_PASSWORD
710$LCS_INVALID_PASSWORD
711$LCS_INVALID_PLACES
712$LCS_INVALID_RANGE
713$LCS_INVALID_REGISTRATION
714$LCS_INVALID_ROW
715$LCS_INVALID_SHEET
716$LCS_INVALID_SIZE
717$LCS_INVALID_STR
718$LCS_INVALID_TO_CELL
719$LCS_INVALID_TRANS_TYPE
720$LCS_INVALID_TYPE
721$LCS_INVALID_UNDO_MODE
722$LCS_INVALID_USE
723$LCS_INVALID_VALUE
724$LCS_INVALID_WIDTH
725$LCS_INVALID_WORKFILE
726$LCS_INVALID_WRITE_TYPE
727$LCS_KEY_BREAK
728$LCS_MACRO_ERROR
729$LCS_MANUAL_RESERVATION
730$LCS_MISSING_DATA
731$LCS_NA
732$LCS_NO_UNDO_HANDLER
733$LCS_NO_UNTITLED_CELL
734$LCS_NO_VISIBLE_COLS
735$LCS_NO_VISIBLE_SHEETS
736$LCS_NOT_FOUND
737$LCS_NOT_GROUPED
738$LCS_NOT_IN_MEMORY
739$LCS_NOT_NUM
740$LCS_NOT_RANGE
741$LCS_NOT_RESERVED
742$LCS_NOT_STR
743$LCS_NULL_HANDLE
744$LCS_NUM_NOT_FOUND
745$LCS_OFFSHEET_RANGE
746$LCS_OPEN_ERROR
747$LCS_OUT_OF_BOUNDS
748$LCS_OUT_OF_ID_SPACE
749$LCS_OUT_OF_MEMORY
750$LCS_PASSWORD_REQUIRED
751$LCS_PROTECTED_CELL
752$LCS_PROTECTED_SHEET
753$LCS_RANGE_FULL
754$LCS_READ_ERROR
755$LCS_RECORD_NOT_FOUND
756$LCS_REQUEST_REFUSED
757$LCS_RESERVATION_SEALED
758$LCS_RESOURCE_LOAD_ERROR
759$LCS_RG_ITER_TERMINATE
760$LCS_RUNTIME_ERROR
761$LCS_SIZE_IN_KBYTES
762$LCS_STACK_OVERFLOW
763$LCS_STR_TOO_LONG
764$LCS_SUCCESS
765$LCS_SYSTEM_ERROR
766$LCS_TOO_FEW_SHEETS
767$LCS_TOO_MANY_SHEETS
768$LCS_UNABLE_TO_COMPLY
769$LCS_UNABLE_TO_RESERVE
770$LCS_UNDO_DISABLED
771$LCS_UNKNOWN_ERROR
772$LCS_VAL_TOO_BIG
773$LCS_WINDOWS_ERROR
774$LCS_WRITE_ERROR
775$Sheet Library
776KLci functions: Sheet ADT;Sheet library
777$LciShConstructCoords
778$LciShConstructCurr
779$LciShDeleteCols
780$LciShDeleteRows
781$LciShDestroy
782$LciShGetAddr
783$LciShGetContext
784$LciShGetDefaultColWidth
785$LciShGetFileName
786$LciShGetFormat
787$LciShGetHiddenFlag
788$LciShGetLabelType
789$LciShGetLastCellAddr
790$LciShGetLastCellCoords
791$LciShGetName
792$LciShGetNum
793$LciShGetProtectFlag
794$LciShGetTitleColCount
795$LciShGetTitleRowCount
796$LciShGetZeroStr
797$LciShInsertCols
798$LciShInsertRows
799$LciShSetDefaultColWidth
800$LciShSetFormat
801$LciShSethiddenFlag
802$LciShSetLabelType
803$LciShSetName
804$LciShSetProtectFlag
805$LciShSetTitleColCount
806$LciShSetTitleRowCount
807$LciShSetZeroStr
808$Utility Group Functions
809$LciUtAllocBlock
810$LciUtBeep
811Kbeep;computer bell;Computer sound;sound
812$LciUtCreateHeap
813KCreate Heap
814$LciUtDestroyHeap
815KDestroy Heap
816$Display Error
817KDisplay Error,Custom Error Display,Message Box Error
818$Error Codes
819K1-2-3 error codes;1-2-3 errors;Error codes;Error text;resource file codes;Return codes
820$LciUtExit
821$LciUtFreeBlock
822$Format Value
823Kformat (float);format (integer);format (string);Format value;input value format
824$LciUtGetDefaultAddinDir
825$LciUtGetEnvBlock
826$LciUtGetLotusIniNum
827$LciUtGetLotusIniStr
828$LciUtGetPersonalDir
829$LciUtGetSystemDir
830$Converting Address Letters to Integers
831Kaddress letters;column letter;converting integers to address letters;Converting worksheet and column letters to integers;integers to letters;worksheet letter
832$LciUtLearnStr
833$LciUtMaxBlockSize
834$Print Range Flag
835KPrint Range;Print Range Exists;Print Range Flag;Print Range Specified
836$LciUtResizeBlock
837$MacroRun
838Kmacro run;macro string arrays;Running a macro
839$LciUtSetDefaultAddinDir
840$LciUtSetIndicator
841$LciUtSetLongPrompt
842$LciUtSetLotusIniNum
843$LciUtSetLotusIniStr
844$LciUtSizeofBlock
845$System
846K/System;operating system;Running system commands;System commands from an add-in
847$Version Number
848K1-2-3 version;Add-In Library version;Current version;Version number
849$LciUtYield
850$LciUt123EnvCall
851$The_Workfile_Functions_Group
852$LciWfCombine
853$LciWfConstructCurr
854$LciWfConstructName
855$LciWfDelete
856KFile Close
857$LciWfDeleteAddinRecord
858$LciWfDeleteSheets
859$LciWfDestroy
860$LciWfErase
861$LciWfExtract
862$LciWfGetActiveFlag
863$LciWfGetCalcIterCount
864$LciWfGetCalcOrder
865$LciWfGetCalcType
866$LciWfGetChangedFlag
867$LciWfGetContext
868$LciWfGetDirPath
869$LciWfGetExtension
870$LciWfGetFullName
871$LciWfGetGroupFlag
872$LciWfGetLastCellAddr
873$LciWfGetLastCellCoords
874$LciWfGetName
875$LciWfGetRangeName
876$LciWfGetRangeNameCount
877$LciWfGetReserveFlag
878$LciWfGetReserveType
879$LciWfGetSealType
880$LciWfGetSheetCount
881$LciWfImport
882$LciWfInsertAddinRecord
883$LciWfInsertSheet
884$LciWfIterAddinRecords
885$LciWfNew
886$LciWfOpen
887$LciWfReplaceAddinRecord
888$LciWfResetRangeNames
889$LciWfRetrieve
890$LciWfSave
891$LciWfSetCalcIterCount
892$LciWfSetCalcOrder
893$LciWfSetCalcType
894$LciWfSetGroupFlag
895$LciWfSetReserveFlag
896$LciWfSetReserveType
897$LciWfSetSealType
898$The_Workspace_Functions_Group
899$LciWsCalc
900$LciWsClearUndo
901$LciWsConstructCurr
902$LciWsDestroy
903$LciWsDirtyAtFunction
904$LciWsErase
905$LciWsGetAddinDir
906$LciWsGetAutoexecFlag
907$LciWsGetCalcIterCount
908$LciWsGetCalcOrder
909$LciWsGetCalcType
910$LciWsGetCellPointerCoords
911$LciWsGetCellTopLeftCoords
912$LciWsGetClockType
913$LciWsGetColor
914$LciWsGetContext
915$LciEsGetCurrFile
916$LciWsGetCurrPane
917$LciWsGetCurrSheet
918$LciWsGetDefaultDir
919$LciWsGetDisplayOptions
920$LciWsGetFileCount
921$LciWsGetFileName
922$LciWsGetFileNum
923$LciWsGetFrameType
924$LciWsGetIndicatorFlags
925$LciWsGetIntlCurrency
926$LciWsGetIntlDateType
927$LciWsGetIntlNegType
928$LciWsGetIntlPuncType
929$LciWsGetIntlTimeType
930$LciWsGetListExt
931$LciWsGetMemAvail
932$LciWsGetName
933$LciWsGetPaneSyncFlag
934$LciWsGetPaneType
935$LciWsGetRowHeight
936$LciWsGetSaveExt
937$LciWsGetStartupDir
938$LciWsGetUndoMode
939$LciWsGetZoom
940$LciWsRegisterUndoHandler
941$LciWsSetAutoExecFlag
942$LciWsSetCalcIterCount
943$LciWsSetCalcOrder
944$LciWsSetCalcType
945$LciWsSetCellPointerCoords
946$LciWsSerCellTopLeftCoords
947$LciWsSetClockType
948$LciWsSetColor
949$LciWsSetCurrFile
950$LciWsSetCurrPane
951$LciWsSetCurrSheet
952$LciWsSetDefaultDir
953$LciWsSetDisplayOptions
954$LciWsSetFrameType
955$LciWsSetIntlCurrency
956$LciWsSetIntlDateType
957$LciWsSetIntlNegType
958$LciWsSetIntlPuncType
959$LciWsSetIntlTimeType
960$LciWsSetListExt
961$LciWsSetPaneSyncFlag
962$LciWsSetPaneType
963$LciWsSetSaveExt
964$LciWsSetUndoMode
965$LciWsSetZoom
966$LciWsSetTabState
967$LciWsUndoCommand
968$LciWsUnregisterUndoHandler
969$LciWsUpdateSettings
970$LciWsWriteUndoRecord