_out123 Utility - Output to Lotus 1-2-3

Syntax

call "_out123",command,column_arg,row_arg

Description

The _out123 utility is used to output text and values that can be used in a Lotus 1-2-3 spreadsheet. Although some additional spreadsheet parameters may be specified through this program, no attempt has been made to provide output of sophisticated parameters such as formulas, graph definitions, and split screens. The _out123 utility is written to the standards of Lotus 1-2-3, Revision 1A.

The _out123 utility produces output in the Intel standard byte order, though this may not be the standard byte order for other platforms and may require the removal of the $07$ second argument from every occurrence of the SWAP function to make this version of _out123 compatible with a non-Intel standard platform. Conversely, an earlier version of the _out123 utility may require adding the $07$ second argument to every occurrence of the SWAP function for compatibility with a platform using the Intel standard byte order.

The _out123 utility is accessed through a CALL statement. With _out123, numerous CALLs are required to complete the spreadsheet. Therefore, it is recommended that _out123 be loaded into resident memory with the ADDR verb prior to use.

Accessing the _out123 utility assumes that the spreadsheet file is opened on channel 123. This eliminates a CALL list argument (the CALL list was designed for simplicity). Note that 1-2-3 spreadsheet files must have a .WKS extension. The _out123 program may be modified to accept a channel number by placing the variable CHANNEL at the desired position in the CALL and ENTER statement.

The CALL to _out123 takes one of the following forms:

CALL "_out123",DATA$
CALL "_out123",DATA$,COL,ROW

The ASCII data in DATA$ may specify spreadsheet parameters or data to be placed in a spreadsheet cell. If cell data is specified, then the COL and ROW arguments should be used. COL must be an integer in the range 1..256. ROW must be an integer in the range 1..2048. (The upper left corner of the spreadsheet is considered COL=1, ROW=1.)

The following commands may be placed in DATA$:

Command	Description
BEGIN	First data output to the spreadsheet.
END	Last data output to the spreadsheet.
'label "label ^label \label	Any text string beginning with a ' " ^ or \ is assumed to be a label. The first character determines the justification mode for the label as described in the 1-2-3 manual. The label (including the first character) must not exceed 240 bytes and may contain spaces. The COL and ROW arguments are used here.
number	Any string specifying a numeric value will cause a number to be placed into a cell. The COL and ROW arguments are used.
mm/dd/yy mm/dd/yyy	Text in a date format will be converted into a number and treated as a numeric. The number corresponding to a date is the day count since January 1, 1900. The 3-digit year is provided for dates after the year 1999 (01/01/000 is January 1, 2000). NOTE: 1-2-3 considers the year 1900 to be a leap year, though it is not. For compatibility, _out123 makes the same assumption. COL and ROW are used here.
BLANK	Causes a blank cell to be placed at the given COL and ROW. This is necessary only if for the cell to have special protection and format attributes (these attributes are explained below); otherwise, specifying a blank cell is redundant.
NA ERR	Places the 1-2-3 @NA or @ERR numeric value in a cell at the given COL and ROW.
PROTECT ON PROTECT OFF	Sets the worksheet global protection value.
CALCORDER NAT CALCORDER COL CALCORDER ROW	Sets the worksheet recalculation order.
CALCMODE AUTO CALCMODE MAN	Sets the worksheet to automatic or manual recalculation mode.
CALCCOUNT n	Sets the worksheet calculation reiteration count to the value n. n must be an integer in the range 1..50.
COLW n1 n2	Sets the width of a worksheet column n1 to be n2 characters wide. n1 must be an integer in the range 1..256 and n2 must be an integer in the range 1..72.
HEADER text FOOTER text	Sets the header and footer strings used by 1-2-3 when printing a spreadsheet. The text must not exceed 241 characters.

Attributes

An attribute specification may optionally precede a label, number, date, NA, ERR, or BLANK and must be enclosed in parentheses. It must not contain embedded spaces and must be separated from the label, number, etc. by at least one space. The attribute string consists of a protect specification and/or a display format specification. The protect specification must come first (if used) and consists of the letter "U" if that cell is to be unprotected. 1-2-3 sets protection for any cell not specifically unprotected. The display format consists of a type and possibly a number indicating the desired precision. The precision must be an integer from 0 to 15. The following are the allowable formats (see the 1-2-3 manual for a description of these formats):

Format	Description
Fn	Fixed, precision n
Sn	Scientific, precision n
Cn	Currency, precision n
,2	Comma, precision n
Pn	Percent, precision n
G	General
+	+/-
T	Text
D1	Date in 'DD-MM-YY' format
D2	Date in 'DD-MM' format
D3	Date in 'MM-YY' format

Display formats appear to have no real meaning for label cells. Any cell output without a specific format will have the attribute of "default." Such a cell is displayed according to the current worksheet default format, which may be changed by the user at any time. An exception to this is a cell expressed as a date (mm/dd/yy). If no format is given, _out123 will automatically force it to (D1). Here is a sample session to create a worksheet:

STRING "XYZ.WKS" ;REM "Create the 123 File
OPEN (123)"XYZ.WKS"; REM "Remember the .WKS extension
CALL "_out123","BEGIN"; REM "This must come first
CALL "_out123","'sales",1,1; REM "Put label at A1
CALL "_out123",DAY,2,1; REM "Put date at B1
CALL "_out123","1200.50",1,3; REM "Put numeric at A3
CALL "_out123","(C3) 123",1,4; REM "Put $123.000 at A4
CALL "_out123","(U) 77.12",1,5; REM "Put unprotected number at A5
CALL "_out123","(UP1) .23",1,6; REM "Put unprotected 23.0% at A6
CALL "_out123","(U) BLANK",1,7; REM "Put unprotected blank at A7
CALL "_out123","NA",1,8; REM "Set cell A8 to @NA
CALL "_out123","PROTECT ON"; REM "Enable worksheet protection
CALL "_out123","COLW 2 12"; REM "Set width of column B to 12 Characters
CALL "_out123","HEADER |Report"; REM "Set header for printout
CALL "_out123","END"; REM "All done, (this must be last)
CLOSE (123)

Many commands may be given in a single call to _out123 by placing them in one long string separated by spaces.

Examples

CALL "_out123","PROTECT ON CALCMODE AUTO"

A series of cells may be given:

CALL "_out123","1.2 (F3) 4200 -22.10 (U)BLANK
06/ 15/96",1,1

This will cause _out123 to begin at the given cell (A1) and output the values in a column (A2, A3, A4 ...). Each cell may have an attribute given; however, attributes do not carry over from one cell to the next. Several labels may be given as well as numbers in a command.

CALL "_out123","'label 1\ 'label2\ 10.50",1,1

The _out123 program will recognize a backslash "\" to terminate a label, enabling the programmer to give text in a compound command. The terminating backslash should not be confused with the backslash that may be used to begin a label. The same rule applies with any text string.

CALL "_out123","HEADER header string\ FOOTER
footer string"

The following are additional commands recognized by _out123 to make this feature more powerful:

Command	Description
ROW	Output sequential cells in a row rather than a column.
COL	Output sequential cells in a column rather than a row. This is the default mode whenever a call is performed to _out123.
@(col) @(col,row)	Similar to the PRO/5 positioning mnemonics except that @(1,1) is considered home (A1), col must be 1..256, and row must be 1 . . 2048. If this is used prior to the first cell data in a command string, the column and row arguments are not needed in the CALL list.

CALL "_out123","@(1,1) 1 2 3 @(3,1) ROW 4 5 6"

This will output the values 1, 2, 3 in a column starting at A1; then the values 4, 5, 6 in a row starting at C1.

Error Codes

Any errors occurring while executing _out123 will be passed back to the calling program. This includes any disk I/O errors. In addition to the regular PRO/5 errors, _out123 will generate the following:

Error	Description
160	Unknown command or invalid word argument to a command.
161	A text string, such as a label or header, is too long.
162	Invalid date.
163	Error in numeric argument such as column width or cell number.
164	Error in deciphering a cell attribute specification.

Always start with BEGIN and finish with END, or 1-2-3 will refuse to load the worksheet.

Asterisk-Filled Cells

If a cell in a worksheet is filled with asterisks (*******) when it should contain data, it indicates that the column containing that cell is not wide enough. The data is there but cannot be displayed. The column width can either be changed in 1-2-3 or a column width can be specified in the _out123 utility.