


	CHAPTER 8:   HP 95LX System Manager Services Reference

This chapter describes the HP 95LX System-Manager services that are available
to any System-Manager-compliant application.

===== OVERVIEW =====

The HP 95LX System-Manager Services provide a simple, memory-effective means by
which all HP 95LX System-Manager-compliant applications can share a set of
library functions. These services simplify development of HP 95LX applications
and maximize memory efficiency.

Because System-Manager Services are inherently viewed as a set of subroutine
calls made by applications, the services described herein are specified as
'C' Language function calls. Services are grouped by functionality, and each
group has a brief operational overview, description of any data structures
required by the group, and specifications for each function. Individual
function descriptions include parameter conventions, return values, and a
functional synopsis.

The functional areas are:

	* Event Services.
	* Menu Services.
	* File Menu Services.
	* Screen Services.
	* Editing Services.
	* File Services.
	* Process Management Services.
	* Clipboard Services.
	* Sound Services.
	* Memory Management Services.
	* Date/Time Services.
	* Printer Services.
	* Configuration Services.
	* Communications Services.
	* Miscellaneous Services.
	* Resource Services.
	* Help Services.
	* Collating Services.
	* 1-2-3 Bridge Services.

These services are described in the following sections of this chapter.

===== HEADER FILES =====

Header files are used for macro and structure definitions. All functional
areas require the inclusion of interface.h for C modules or
interfac.mac for assembler modules.

Some functional areas also require the inclusion of additional header files
as follows:


	Service Class	C Program	Assembler Program
	-------------	---------	-----------------
	Event		event.h		event.mac
	Menu		menu.h		menu.mac
	File Menu	fmenu.h		fmenu.mac
	Editing		edit.h		smedit.mac
	Clipboard	cbcodes.h	cbcodes.mac
	File I/O	fileio.h	filio.mac
	Date/Time	smtime.h	smtime.mac
	Configuration	settings.h	settings.mac
	Communication	comio.h		comio.mac
	Bridge		bridge.h	bridge.mac
	Misc		m_error.h	m_error.mac

A NOTE ON C-LANGUAGE FUNCTION PROTOTYPES

The header files do not contain function prototypes for the services. Instead,
interfac.h contains macro definitions that expand System-Manager-service
calls into calls to a single service-dispatch routine.

Hence, if a service is accidentally called with the incorrect number of
parameters, it will not match the macro and the compiler will issue a warning
about too few or not enough actual parameters for the macro.

However, if a service is accidentally called with an incorrect argument type
but with the correct number of parameters, this may not be caught by the
compiler due to the lack of a function prototype.

The following functions in interfac.h are not usable by applications:

	com_timer_addr		com_timer_count_addr
	InitCom			m_appcount
	m_app_name		m_common_open         
	m_day_trigger		m_disable_macros
	m_enable_macros		m_fall_printer
	m_get_settings		m_ram_iv_info
	m_reboot		m_set_daterule
	m_set_settings		m_spawnarg
	m_sys_rsrc_addr

A NOTE ON FAR VERSUS NEAR POINTERS IN SERVICE CALLS FROM C

All pointers in System-Manager-service calls are far pointers. However,
the service macros contain casts of pointer arguments to far pointers.
Consequently, near pointers can be used for data in cases where the
compiler can supply the segment value due to the cast.


===== EVENT SERVICES =====

While active, applications should poll the System Manager's event functions to
get input from the user, and dispatch according to the type of event reported
and the current state of the application (doing a menu, editing text, etc.).
Keystrokes are translated for both applications (CP 850) and 123 (LICS and
function key flags).   Event information is passed through the structure of
type EVENT, which is defined below.

typedef struct {
    enum event_kind kind;     /* event kind code defined below */
    unsigned int data;        /* For ASCII keys, this is just the ASCII
                                 code in the low byte. For non-ASCII keys,
                                 the scan code is in the high byte and the
                                 low byte is zero. */
    unsigned char scan;       /* scan code from BIOS */
    unsigned char shifts;     /* shifts register, when function returns */
                              /* not necessarily when key struck */
    unsigned int lics;        /* LICS translation of keystroke */
    unsigned char fkey_num;   /* function key number for 123 only */
    void far *bridge;         /* pointer to 123 bridge data structure */
} EVENT;

The meanings of the event_kind codes are:

	Code		Meaning
	------------	-----------------------------------------------
	E_ACTIV		Application receiving the event has just been
			activated or reactivated. This should be taken as a
			signal to (re)display in the active state.

	E_ALARM_DAY	The application's daily chance to set an alarm.

	E_ALARM_EXP	The application's alarm has expired.

	E_BREAK		Control-Break detected.
			shifts reports current state of keyboard shift flags.

	E_BRIDGE	Event reported only to 123 when a bridge service is
			requested. Pointer to data is found in bridge field.

	E_DEACT		Application receiving this event is about to be
			deactivated. It is given the opportunity to prepare for
			an inactive state that will begin following the next
			m_event call.

	E_GROW		A request to 123 to grow.

	E_KEY		Keystroke available to application.
			data contains the CP 850 ASCII value.
			scan contains the keyboard scan code.
			lics contains the LICS interpretation of the keystroke.
			fkey_num contains the function key code used by 123.
			shifts reports current state of keyboard shift flags,
			not necessarily the state of the shifts when key was
			struck.

	E_NONE		No event available.
			shifts reports current state of keyboard shift flags
			(immediately before control is returned).

	E_SHRINK	A request to 123 to shrink.

	E_TERM		Application receiving the event is about to be
			terminated. It should respond to this event as if
			{MENU,Quit} had been entered from the top level.

			An application may interact with the user and make
			calls to m_event as necessary. It should ultimately
			make a call to m_fini() to give up control, or to
			m_no_fini() if the user has indicated a desire to abort
			the shutdown process.

	E_TIMECHANGE	Indicates that the system date or time has been changed.

Applications using the event services must include the header files event.h
and interfac.h.

M_EVENT
-------

    void m_event(eventptr);
    EVENT far *eventptr;


Transfers control to the System Manager until a reportable event has occurred
or until a timeout period of approximately 0.5 seconds has elapsed.  The event
is reported in *eventptr and is taken out of the system queue.

In the event of a timeout, E_NONE will be reported.  This gives applications 
the opportunity to redisplay the current time.

M_FLUSH_KB
----------

    void m_flush_kb();


Flushes the keyboard queue. Control is returned when the queue is empty.

M_NEVENT
--------

    void m_nevent(eventptr);
    EVENT far *eventptr;


Transfers control to the System Manager.  If no event has occurred, 
E_NONE will be reported.  The event is reported in *eventptr.

If the event is an E_KEY event, the event is not removed from the system queue.
However, all other events, such as activation and deactivation events are only
reported once, despite the fact that m_nevent() has been called.

M_NO_FINI
---------

    void m_no_fini(eventptr);
    EVENT far *eventptr;


If, in response to an E_TERM event, an application discerns that the user
wishes to abort the shutdown procedure, it should call m_no_fini(). This call
will release the system locks (allowing context switching) and break the
shutdown sequence. The application making the call will continue to be the
active application.

An event structure must be passed, but its fields will be undefined on return,
and may be safely ignored.

M_SH_STATUS
-----------

    int m_sh_status();


Gets the current status of the keyboard shift flags. Return value is same as
value returned by BIOS (Int 16h, Service 2).

M_YIELD
-------

    void m_yield(eventptr);
    EVENT far *eventptr;


Voluntary suspension of an application. When called, the application is placed
at the end of the application stack, and the active state reverts to the next
application. Control will not return to the caller of m_yield until some
external action causes it to be made active again (generally, user request via
hotkey).

The return value will be the same as if the application had made an 
m_event() call and had been suspended; that is, the expected event type 
on return is E_ACTIV.


===== MENU SERVICES =====

All applications should use the menuing system provided by the System Manager.
The menu system uses the 1-2-3-styled two-line menu bar (where the top line
contains keywords to all of the options available at a particular decision
branch and the second line displays a long message corresponding to the
currently highlighted option). Because of the screeen space constraints, 
the two lines are used for keywords, and no long prompts are supported.

There is an option which supports a prompted menu, in which the top line is a
constant prompt (it does not change as the item selection changes) and the
second line is filled with keywords.

Menus are used by calling menu_setup() to fill a data structure of type
MENUDATA. menu_on() should be called when the menu becomes active;
menu_off() when menu selection has been made. The application should
repeatedly call menu_key() and menu_dis() while keystrokes are
available or until the user has selected an item or aborted the process. Note
that process events (i.e., non-keystrokes) should be handled without calls to
menu_dis().

The definition for the structure MENUDATA is:


typedef struct {
     /* define the menu display storage area */
     /* the intent is to have one string per display line to make display 
        management easier */
     char menu_text [MAX_MENU][MAX_MWID];  /* menu display storage area */
     int menu_count;                       /* number of keywords */
     int menu_highlight;                   /* index of hightlighted item */
                                           /* -1 for no highlight */
     /* flag indicating special mode with single prompt on top line */
     int menu_tprompt;                     /* 0 ==> no */
     /* define the menu information table */
     char menu_line   [MAX_KWDS];    /* which line of menu this word is on */
     char menu_offset [MAX_KWDS];    /* offset of this keyword in the string */
     char menu_length [MAX_KWDS];    /* length of this keyword */
     char menu_letter [MAX_KWDS];    /* first letter of this keyword */
     /* store the pointers to the long prompts */
     unsigned menu_prompt[MAX_KWDS];	/* DS-relative offsets... */

     } MENUDATA;


Applications using the menu services must include the header files menu.h
and interfac.h.

MENU_DIS
--------

    void menu_dis(m);
    MENUDATA far *m;


Displays the menu, when appropriate, with any necessary highlighting.

MENU_KEY
--------

    int menu_key(m, keystroke, presult);
    MENUDATA far *m;
    int keystroke;
    int far *presult;


Given the keystroke, updates the menu display and returns the index of
the selected item (if any). The routine determines the appropriate action
for any arbitrary keystroke. keystroke should be the value returned in
the data field of the event structure.

Sets *presult to -1 if no final selection has been made, otherwise
to the index of the selected item. 

Returns 0.

MENU_OFF
--------

    void menu_off(m);
    MENUDATA far *m;


Deactivates menu management, removes highlight.

MENU_ON
-------

    void menu_on(m);
    MENUDATA far *m;


Activates menu management and highlights first item in list.

MENU_SETUP
----------

    int menu_setup(m,keywords,keyword_count,double_space,top_prompt,
                tprompt_len,long_prompts)
    MENUDATA far *m;
    char far *keywords;
    int keyword_count;
    int double_space;
    char far *top_prompt;
    int tprompt_len;
    char far *long_prompts;


Builds a menu structure to be used later.

m points to a structure of type MENUDATA to be filled in by the procedure.
keywords points to a series of null-terminated strings which make up the
keywords of the menu. The first character of the second word directly follows
the null terminator of the first, and so on. keyword_count indicates the
number of keywords present. double_space indicates whether one (value of
0) or two (value of 1) spaces will be displayed between menu items. The
spacing argument is taken as a recommendation: single spacing will be used if
it keeps all items on the top line or if the second line is filled.

For normal menus, *top_prompt will be NULL, and tprompt_len will be 0.
In that case, long_prompts points to an array of pointers (all relative to
the constant resource segment) to the long prompts for the menu. There must be
a one-to-one correspondence between long prompts and keywords.

***********
* NOTE!!! *
***********
Long prompts are not supported and long_prompts will be ignored on the HP 95LX.
***********
* NOTE!!! *
***********

Special menus with top-line prompts are created by setting *top_prompt and
tprompt_len.

Returns 0.


===== FILE MENU SERVICES =====

File-Menu services provide a flexible method for file name selection. The
services can display a list of file names from which the user can make a
selection by moving a cursor to the desired name and pressing [[ENTER]].

The list of file names can be selected by means of a wild card. A common
usage is to display all the file names that have the application-specific
extension.

The services make use of three structures: FMENU, FILEINFO, and EDITDATA.
FMENU and FILEINFO are described below; EDITDATA is described in the Editing
Services section.

The FMENU structure is:


typedef struct {

    /*---Members to be Initialized by the Application---*/
    char far *fm_path;              /* base directory name C:\DATA\ */
    char far *fm_pattern;           /* file pattern, e.g. *.WK1 */
    FILEINFO far *fm_buffer;        /* workspace for file list (hold infos) */
    int fm_buf_size;                /* size of the buffer in bytes */
    int fm_startline,fm_startcol;   /* starting row,col */
    int fm_numlines,fm_numcols;     /* number of lines and columns */
    int fm_filesperline;            /* number of files displayed across */

    /*---Members thst are initialized by the File Menu Services---*/

    int fm_firstedit;               /* 0 if first edit char, else multi line */
    int fm_filesinbuf;              /* number of files in list */
    int fm_maxfinbuf;               /* maximum number of files buffer holds */
    int fm_topfile;                 /* file at top of list */
    int fm_curselect;               /* index of the file highlight */
    int fm_oldselect;               /* index of file to un-highlight */
    int fm_focus;                   /* 1 = fmenu, 2 = edit */
    } FMENU;


As indicated by the comments, some elements of this structure are to be
initialized by the application. This initialization must occur prior to the
call to fmenu_init. These elements are:

	fm_path		Pointer to null-terminated name of directory that is to
			be searched for files. For examole, C:\_DAT.

	fm_pattern	Pointer to null-terminated string that contains a file
			name or a wild-card-file pattern. For example, *.WK1.

	fm_buffer	Pointer to an array of FILEINFO structures (see below)
			that will be used to hold the file names that match the
			file pattern. The number of elements in this array is
			the total number of files that can be displayed by the
			File-Menu Services. Thus, choosing the size of this
			array is a tradeoff between memory usage for this array
			and how many files are supported.

	fm_buf_size	Size (bytes) of file-name list pointed to by fm_buffer.
			If NFILES is the number of elements in fm_buffer,
			fm_buf_size is NFILES * sizeof(FILEINFO).

	fm_startline	Number of lines on the display where the file-menu
			prompt will appear. The file list will start on the
			next line down. As with the Screen Services, the top
			line is the number -3. A common value is -2 which
			leaves the top line free for a prompt such as
			"File to open."

	fm_startcol	Leftmost column to be used by the file-menu display. A
			common value is 0.

	fm_numlines	Number of lines to be used by the file-menu display,
			including the file-menu-prompt line. A common value is
			13, which, together with the top line for a general
			prompt and the bottom two lines for softkey labels will
			use all lines of the display.

	fm_muncols	Number of columns to be used by the file-menu display.
			A common value is 40 which uses all columns of the
			display.

	fm_filesperline	Number of file names to be displayed on each line
			across the screen.  A common value is 3 given that
			fm_numcols is 40.


In addition, a common usage employs a file-selection prompt identifying the
file to be selected (for example, "File to open:"). This prompt is inserted
in the EDITDATA structure prior to calling fmenu_init.


There are four EDITDATA structure elements to be initialized as follows: 

	prompt_window		Should be set to 1.
	promtp_line_length	Should be set to 0.
	message_line		Should point to the desired prompt string.
	message_line_length	The length of the prompt string.


The FILEINFO structure is:


    typedef struct {
        char fi_attr;           /* file attribute */
        int fi_time;            /* time modified */
        int fi_date;            /* date modified */
        long fi_size;           /* file length */
        char fi_name[13]        /* file name */
    } FILEINFO;


The FILEINFO structure is used internally by the File-Menu Services and is
not intended to be manipulated directly by the application.

Applications using the File-Menu Services must include the header files
fmenu.h, edit.h, and interfac.h.

FMENU_DIS
---------

    int fmenu_dis(fmenu_data,edit_data);
    FMENU far *fmenu_data;
    EDITDATA far *edit_data;


Redisplays the current file-menu screen. fmenu_data and edit_data
are pointers to the same FMENU and EDITDATA structures that were used in
the call to fmenu_init.

FMENU_INIT
----------

    int fmenu_init(fmenu_data,edit_data,name,namelen,maxlen);
    FMENU far *fmenu_data;
    EDITDATA far *name;
    char far *name;
    int namelen;
    int maxlen; 


Initializes the File-Selection-Menu Services and displays the
File-Selection menu. fmenu_data points to an FMENU structure that has
been initialized by the application as shown above. edit_data points to
an EDITDATA structure that is normally initialized with a file-selection
prompt as described above. name points to a null-terminated string that
can be a file name, a pattern, or a null string. If name is a file name
or pattern, fmenu_init will present this name on the prompt line and will
not display the names of files that match fm_pattern. If name is a null
string, fmenu_init displays fm_pattern on the prompt line and displays the
names of files that match this pattern. namelen is the length of the
name string.

The maxlen must be present, but is not used. We recommend that you set
maxlen to zero.

Returns RET_OK normally; else returns RET_BADFILE, RET_BADDIR, or RET_BADDRIVE
if there is a problem with name. If such an error results, a common
recourse is to use the null string for name. This causes the File-Menu
Services to use the file pattern contained in fm_pattern, which should
specify an existing directory.

FMENU_KEY
---------

    int fmenu_key(fmenu_data,edit_data,key);
    FMENU far *fmenu_data;
    EDITDATA far *edit_data;
    int key;


Processes a keystroke that is entered while the File-Menu Service is
active. fmenu_data and edit_data are pointers to the same FMENU and
EDITDATA structures that were used in the call to fmenu_init.

key is the value of the keystroke as returned in event.data by the Event
Services.

The return values defined in fmenu.h are:


    RET_UNKNOWN       key was unknown by fmenu_key.
    RET_OK            key was processed by fmenu_key,
                        just call fmenu_dis.
    RET_BAD           key was known by fmenu_key,
                      but was invalid (for example, pgdn off list).
    RET_REDISPLAY     redisplay application area before calling fmenu_dis.
    RET_ACCEPT        user made a file selection, the filename is in the
                      edit_buffer element of the EDITDATA structure
                      pointed to by edit_data.
    RET_ABORT         user aborted operation.
 

FMENU_OFF
---------

    int fmenu_off(fmenu_data,edit_data);
    FMENU far *fmenu_data;
    EDITDATA far *edit_data;


Clears the portions of the screen that were used by the File-Menu Services.
fmenu_data and edit_data are pointers to the same FMENU and EDITDATA
structures that were used in the call to fmenu_init.

Returns RET_OK.

===== SCREEN SERVICES =====

Accessing the user display is done through the following functions. All row
and column values given relative to the top-left corner of the application's
active window; that is, (0,0) are the coordinates of the first character that
may be drawn in the applications window.  

In the HP 95LX, position (0,0) corresponds to the first column in the fourth
row. Negative row coordinates can be used to access the first three rows of
the HP 95LX screen; for example, the top row is -3.

Applications using the screen services must include the header file
interfac.h.

M_CHRATTR
---------

    m_chrattr(buffer,len);
    char far *buffer;
    int len;


Returns the characters and attributes starting from the top left corner of the
screen.

len character/attribute pairs are put into buffer.

M_CHRINV
--------

    m_chrinv(row,col,nchars);
    int row,col,nchars;


Invert the attributes for nchars, starting at the screen location 
specified by row and col.

M_CHRRVRT
---------

    m_chrrvrt(row,col,buf,len);
    int row,col,len;
    char far *buf;


Restore attributes on display.  buf is a pointer to an array of
characters, which are the saved attributes to be restored. len tells how
many characters are to be restored. row and col tell which characters
to restore.

M_CLEAR
-------

    m_clear(row,col,nrows,ncols);
    int row,col,nrows,ncols;


Clears a rectangular region where row and col specify the top-left
corner and nrows and ncols specify the dimensions.

M_DIRTY_SYNC
------------

    void m_dirty_sync(void);


Causes an immediately redisplay of the virtual display buffer.  This function
is called automatically at the beginning of m_event (and m_nevent).

M_DISP
------

    m_disp(row,col,str,len,style,ostyle);
    int row,col,len,style,ostyle;
    char far *str;


Displays str of length len at row and col, with the attribute
style. The ostyle parameter is required, but is not used. The valid
values for style are:


	Style	MDA Attribute	Description
	-----	-------------	-----------
	0	07h		Normal
	1	70h		Inverse
	4	01h		Underlined
	8	87h		Normal Blink
	9	F0h		Inverse and Blink
	12	81h		Underline and Blink


m_disp puts the string into a virtual display buffer and does not write the
string to the physical display. The changes to the virtual display buffer
are written to the physical display each time the application requests the
next event. The m_dirty_sync function should be used if it is desired to
update the physical display immediately after an m_disp call (as might be
the case during debugging).

M_GETMODE
---------

    int m_getmode(void);


Returns the current display mode, 1=text or 2=graphics.

M_ROWS_COLS
-----------

    int m_rows_cols();


Returns number of rows in high byte, number of columns in low byte.

M_SCROLL
--------

    m_scroll(row,col,nrows,ncols,offset);
    int row,col,nrows,ncols,offset;


Scrolls vertically the rectangular region where row and col specify
the top-left corner, nrows and ncols specify the dimensions, and
offset is the number of lines to scroll.

M_SETCUR
--------

    void m_setcur(row,col);
    int row,col;


Sets the cursor position to the row and column coordinates specified by
row and col. The cursor can be turned off by moving it to an
off-screen location; for example, use m_setcur(0,-1).

M_SETMODE
---------

    void m_setmode(mode);
    int mode;


Sets the display mode to text (mode=1) or graphics (mode=2) and
clears the display.

M_XCHG
------

    m_xchg(row,col,nrows,ncols,region);
    int row,col,nrows,ncols;
    char far *region;


Copies the information in region into the rectangular region on the screen
whose top-left coordinates are row and col, and whose dimensions are
nrows and ncols.


===== EDITING SERVICES =====

The System Manager provides general purpose editing facilities that should be
used by all applications.  Single-line editing is done by filling a structure
of type EDITDATA by calling EDIT_INI() or EDIT_TOP(), and then by repeatedly
calling EDIT_KEY() and EDIT_DIS() until the editing is terminated (generally
when a CR is struck), which will be signalled by EDIT_KEY().

The EDITDATA structure is defined as follows:


typedef struct {
    int edit_length;            /* current length of the edit buffer */
    char first_time;            /* flag for special processing on first char */
    char spec_flags;            /* bit 0 is tab handling */
    int prompt_window;          /* whether this belongs to prpt. Window*/
    char far *message_line;     /* the top line message for prompt */
    int message_line_length;    /* length of message_line */
    char far *prompt_line;      /* second line of prompt window */
    int prompt_line_length;     /* length of prompt_line */
    char edit_buffer[80]        /* work space */
    int line_array[2];          /* to be passed to mdit structure */
    MDITDATA mdit;              /* multi-line struct, to hold more info */
    int e_dispcols;
} EDITDATA;


The width of the edit buffer may exceed the width of the display window, 
up to 78 characters. Horizontal scrolling is handled by the services.

Multi-line editing is done similarly, but with calls to the mdit_*() series of
functions. The multi-line editor allows the buffer to exceed the capacity of
its display window, up to some length fixed at initialization.

The MDITDATA structure is defined as follows:


typedef struct {
    char far *m_buffer;      /* user supplied edit buffer */
    int m_length;            /* length of buffer */
    int m_pos;               /* current cursor position */
    int m_row, m_col;        /* location of edit area */
    int m_nrows,m_ncols;     /* dimensions of logical edit area */
    int m_yoff,m_disprows;   /* log.top line of display;lines of display*/
    char m_ccol;             /* cursor column */
    char m_modified;         /* 1 if buffer has been changed */
    char m_xoff;             /* 1st disp. col (for ticker fields only) */
    char wrapflag            /* word wrap enable flag */
    int far *m_line;         /* caller supplied buffer for line starts */
                             /* must be at least m_nrows+1 long */
    int markon;              /* marking is currently active flag */
    char spec_flag;
    int markst;              /* offset of start of marked region, inclusive */
    int markend;             /* offset of end of region, inclusive */
    int m_dispcols;          /* displayable columns */
} MDITDATA;


The m_nrows field specifies the number of rows in the buffer. m_disprows
specifies the number of rows displayed on the screen.

Applications using the editing services must include the header files
edit.h and interfac.h.

EDIT_DIS
--------

    int edit_dis(e);
    EDITDATA far *e;


Displays the edit area, defined in e, on the screen.

Returns 0

EDIT_INIT
---------

    edit_init(e,ini_buf,ini_len,max_len,display_line,display_col);
    EDITDATA far *e;
    char far *ini_buf;
    int ini_len,display_line,display_col,max_len;


Sets up the structure e for single line editing at an arbitrary location.
ini_buf points to a string of length ini_len, which is the default 
value for the edit field.  This buffer must be in the application's data 
segment.  max_len indicates the maximum width of the field.  
dislay_line and display_col provides coordinates for the first 
character of the field.

Calls edit_dis() to display the field.

Returns 0.

EDIT_KEY
--------

    int edit_key(e,keystroke,presult);
    EDITDATA far *e;
    int keystroke;
    int far *presult;


Processes keystroke in the context of e; that is, it does the 
work of inserting characters, etc, for the edit field. keystroke is the
value returned in event.data by the Event Services.

Sets *presult to 1 if editing has been completed, otherwise, sets
*presult to 0.

Returns 0.

EDIT_TOP
--------

    int edit_top(e,ini_buf,ini_buf_len,max_len,line1,len1,line2,len2);
    EDITDATA far *e;
    char far *line1;
    char far *line2;
    char far *ini_buf;
    int ini_buf_len;
    int len1;
    int len2;
    int max_len;


Sets up the structure e for single line editing. The field will be edited
on the top line of the application's menu area if it occupies only one line;
otherwise, it is edited on the second line of the menu area. The first
character of the edit field will follow the last character of the prompt
string (line2).

ini_buf points to a string of length ini_buf_len, which is the default
value for the edit field. This buffer must be located in the application's
data segment. max_len indicates the maximum width of the field. line1,
of length len1, will be displayed as a message. line2, of length
len2, will be displayed as the user prompt.

Calls edit_dis() to display the field.

Returns 0.

MDIT_CUTMARK
------------

    void mdit_cutmark(mp);
    MDITDATA far *mp;


Deletes the characters included in the marked region. If an application wants
to save the contents of marked region, it should copy the data prior to making
the cutmark call. The offsets for the start and end of the region are
maintained in the markst and markend fields of the MDITDATA structure.
Applications should note that if markend == m_length, the last character should
be ignored.

The marking mode is ended after successful completion of this function.

MDIT_DIS
--------

    void mdit_dis(mp);
    MDITDATA far *mp;


Displays the current contents of the edit field pointed to by mp and
updates the cursor position.

MDIT_FIL
--------

    mdit_fil(mp,fp);
    MDITDATA far *mp;
    FILE far *fp;


Writes the buffer in mp to the open file associated with fp. No
attempt is made to reposition the write pointer of the file.

Returns 0 if successful; otherwise, returns the error code reported by
m_write().

MDIT_INI
--------

    void mdit_ini(mp,row,col,nrows,ncols,buf,len,wrapflag,disprows,line_array);
    MDITDATA far *mp;
    int row,col,nrows,ncols,len;
    char far *buf;
    int wrapflag;
    int disprows;
    int far *line_array;


Initializes the structure mp for multi-line editing. row and col
establish the top-left corner of the edit region; nrows and ncols
establish the dimensions of the logical edit region. The caller must provide
the buffer through buf, which must be located in the application's data
segment. Its length is specified in len, and the maximum length is 32767.

m_nrows specifies the number of rows in the edit buffer, while 
m_disprows specifies the number of screen rows that are displayed; that
is, the latter defines the size of the region on the screen.

wrapflag, if nonzero, enables word wrapping.

line_array provides the mdit functions a buffer in which to store line
offsets for each row. It must be at least (m_nrows+1)*sizeof(int) bytes
long, and must be located in the application's data segment.

To use mdit functions without vertical scrolling, m_disprows must equal
m_nrows. Applications must also provide the buffer space for
line_array.

Returns 0

MDIT_INS_STR
------------

    int mdit_ins_str(mp,str,len);
    MDITDATA far *mp;
    char far *str;
    int len;


Allows entry of multiple characters into the edit buffer. Screen will be
updated after all characters have been inserted.

MDIT_KEY
--------

    int mdit_key(mp,keystroke);
    MDITDATA far *mp;
    int keystroke;


Processes keystroke in the context of mp; that is, it does the work of
inserting characters, etc, for the edit field. keystroke is the value
returned in event.data by the Event Services.

If marking mode is in effect, only cursor movement keys will be accepted.

The cursor movement keys are as follows:


         UP ARROW              Move to previous line, same column if possible.
         DOWN ARROW            Move to next line, same column if possible.
         LEFT ARROW            Move to previous character.
         RIGHT ARROW           Move to next charcter.
         HOME                  First column of current line
         END                   Last column of current line
         CONTROL HOME          First character of buffer.
         CONTROL END           Last character of buffer.
         CONTROL LEFT ARROW    Beginning of previous word.
         CONTROL RIGHT ARROW   Beginning of next word.


The following keys also have special meanings:


         BACKSPACE             Delete character to left of cursor
         DELETE                Delete character under cursor.
         CONTROL ENTER         Delete characters from cursor to end of line.
         CONTROL BACKSPACE     Delete word to left of cursor.
         TAB                   Insert spaces from current position to next tab
                               stop.


Returns 0.

MDIT_MARK
---------

    void mdit_mark(mp);
    MDITDATA far *mp;


Invokes the multi-line editor's marking mode. While marking is active, only
cursor movement keys are accepted by mdit_key(). The current cursor position
becomes the anchor, and the user may select text before or after the anchor,
but the anchor cannot be moved.

An application may inspect or copy the text in the marked region by observing
the current values in the markst and markend fields of the MDITDATA structure.

This function causes the display to be updated showing the initial marked
region (1 character) in inverse video.

MDIT_UNMARK
-----------

    void mdit_unmark(mp);
    MDITDATA far *mp;


Ends the multi-line editor's marking mode. This function has no other effect
on the MDITDATA structure, but it will redisplay the text without the marking
attributes.


===== FILE SERVICES =====

Operations on disk files are done through the following set of calls. Refer
to the include file fileio.h for information on the structures and
m_error.h  for error codes used by the File Services.

***************
* CAUTION!!!! *
***************
The FILE Services use a FILE structure that is not compatible with the
FILE structure defined in a Standard C Library include file, stdio.h.
Modules using the System Manager File Services must not include stdio.h.
***************
* CAUTION!!!! *
***************

Applications may use either buffered and unbuffered operations. If only
unbuffered operations are used, then the structure NBFILE can be used in place
of FILE to save the RAM that would be used for the file buffer.

Applications that use File Services must include the header files fileio.h
and interfac.h, and may want to include m_error.h for file-error codes.

M_CLOSE
-------

    int m_close(fp);
    FILE far *fp;


Closes the file associated with fp.

Returns 0 if successful, otherwise, returns an error code.

M_COPYDT
--------

    void m_copydt(fpsrc,fpdest);
    FILE far *fpsrc;
    FILE far *fpdest;


Copies the date and time modified values from fpsrc to fpdest, both of
which must refer to files opened through System-Manager-file services.

M_CREATE
--------

    m_create(fp,filespec,len,sys,nobuf);
    FILE far *fp;
    char far *filespec;
    int len;
    int sys;
    int nobuf;


Creates a new file to be identified by filespec. len is the length
of filespec.  sys is not used and should be zero. If nobuf is set,
no buffering will be performed.

The file will be created and opened only if it does not already exist.

If successful, the values in fp will be updated and 0 will be returned.
Otherwise, an error code will be returned.

M_DELETE
--------

    int m_delete(bp,len,sys);
    char far *bp;
    int len;
    int sys;


Deletes the file specified by bp.  len is the length of
of the string pointed to by bp. sys is not used and should be set
to zero.

Returns 0 if successful, otherwise, returns an error code.

M_FCREAT
--------

    m_fcreat(fp,filespec,len,sys,nobuf);
    FILE far *fp;
    char far *filespec;
    int len;
    int sys;
    int nobuf;


Creates a new file identified by filespec. len is the length of
filespec. sys is not used and should be set to zero. If nobuf is
nonzero, no buffering will be performed.

Any existing file matching the filespec will be truncated.

If successful, the values in fp will be updated and 0 will be returned.
Otherwise, an error code will be returned.

M_FDATE
-------

    m_fdate(fp1,lp1);
    FILE far *fp1;
    char far *lp1;


For the file referenced by fp1, return the time and date values in *lp1.

M_GETATTR
---------

    m_getattr(bp,len,sys,attr);
    char far *bp;
    int len;
    int sys;
    unsigned far *attr;


For the file specified by bp, returns in attr the file attributes as
returned by DOS.  len is the length of the file specification. sys is
not used and should be set to zero.

M_GETDIR
--------

    int m_get_dir(drive,bp,lenp);
    char drive;
    char far *bp;
    int far *lenp;


Builds in bp the current directory for the specified drive. The
returned path includes the drive designator (for example, "c:"). *lenp
contains the length of the string returned in bp.

Returns 0.

M_GETDRV
--------

    int m_getdrv(drivep);
    char far *drivep;


Sets *drivep to the drive letter of the current default drive. Reported
values start at `A'.

Returns 0 if successful, otherwise, returns an error code.

M_GETFDT
--------

    void m_getfdt(fp,dateval);
    FILE far *fp;
    long far *dateval;


Gets the last modification date/time of the file fp and returns it in
*dateval.  The format of dateval is that of the date/time stamp in a
DOS directory entry.

M_GET_SYSDIR
------------

    m_get_sysdir(bp);
    char far *bp;


Copies into *bp the system directory path. On the HP 95LX, the
system-directory path is C:\_DAT\. On the Connectivity Pack, the
system-directory path is controlled by the PIMS environment variable with
default of C:\CPACK\.

M_IDENT
-------

    int m_ident(bp,len,sys,typep);
    char far *bp;
    int len;
    int sys;
    int far *typep;


Sets *typep to indicate the file type of the file whose name is pointed to
by bp.  len indicates the length of the filename stored in bp.
sys is not used and should be set to zero. 

The file type is set to 1 for a file, set to 2 for a directory, set to 3 for a
device, or set to 0 if filename is not found.

Returns 0 if successful, otherwise, returns an error code.

M_MATCH
-------

    int m_match(matchp,flagp);
    MATCH far *matchp;
    int far *flagp;


For the matchp structure set up by m_setpat(), find the next matching 
file name. *flagp is set to nonzero when a match is found; otherwise, *flagp
is set to zero.

Returns 0 under normal conditions; returns a nonzero error code with flagp 
set to 0 when an error other than no more matches is encountered.

M_MKDIR
-------

    int m_mkdir(bp,len,sys);
    char far *bp;
    int len;
    int sys;


Creates the directory specified in the string bp, where len is the
length of bp. sys is not used and should be set to zero.

Returns 0 if successful, otherwise, returns an error code.

M_OPEN
------

    int m_open(fp,filespec,len,sys,nobuf);
    FILE far *fp;
    char far *filespec;
    int len;
    int sys;
    int nobuf;


Opens an existing file identified by filespec. len is the length of
filespec. sys is not used and should be set to zero. If nobuf is
nonzero, no buffering will be performed.

If successful, the values in fp will be updated and 0 will be returned;
otherwise, an error code will be returned.

M_OPENRO
--------

    int m_openro(fp,filespec,len,sys,nobuf);
    FILE far *fp;
    char far *filespec;
    int len;
    int sys;
    int nobuf;


Opens an existing file identified by filespec in read-only mode. len
is the length of filespec. sys is not used and should be set to 0. If
nobuf is nonzero, no buffering will be performed.

If successful, the values in fp will be updated and 0 will be returned.
Otherwise, an error code will be returned.

M_PUTFDT
--------

    void m_putfdt(fp,dateval);
    FILE far *fp;
    long dateval;


Sets the last modification date/time of the file fp to dateval. The
format of dateval is that of the date/time stamp in a DOS directory entry.

M_READ
------

    m_read(fp,buffer,len,lenp);
    FILE far *fp;
    char far *buffer;
    int len;
    int far *lenpf;


Reads up to len bytes of data from the I/O stream fp into the memory
pointed to by buffer. *lenp tells how many bytes were actually read.
If *lenp != len and the returned value is zero, the end-of-file has
been reached.

Returns 0 if successful, otherwise, returns an error code.

M_RENAME
--------

    int m_rename(bp1,len1,sys1,bp2,len2,sys2);
    char far *bp1;
    char far *bp2;
    int len1;
    int sys1;
    int len2;
    int sys2;


Rename the file specified by the name pointed to by bp1 to the name
pointed to by bp2.  len1 and len2 are the lengths of the filenames
pointed to by bp1 and bp2 respectively. sys1 and sys2 are
not used and should be set to zero.

Returns 0 if successful, otherwise returns an error code.

M_RMDIR
-------

    int m_rmdir(bp,len,sys);
    char far *bp;
    int len;
    int sys;


Removes the directory specified in the string bp, where len is the
length of bp. sys is not used and should be set to zero.

Returns 0 if successful, otherwise, returns an error code.

M_SEEK
------

    m_seek(fp,mode,seek);
    FILE far *fp;
    int mode;
    long seek;


Sets the current position in the file associated with fp.  seek 
is the signed-byte offset of where to set the position, relative to the 
value of mode. Modes defined in fileio.h are:


	Mode		Meaning
	--------------	----------------------------
	seek_beginning	Offset from start of file.
	seek_current	Offset from current position.
	seek_end	Offset from end of file.


M_SETATTR
---------

    m_setattr(bp,len,sys,attr);
    char far *bp;
    int len;
    int sys;
    int attr;


For the file specified by bp, sets the file attributes to attr.  
len is the length of the file specification. sys is not used and
should be set to zero.

M_SETDIR
--------

    int m_setdir(bp,len);
    char far *bp;
    int len;


Given the path bp of length len, sets the current directory for the
drive included in the path.

Returns 0 if successful; otherwise, returns an error code.

M_SETDRV
--------

    int m_setdrv(drive);
    char drive;


Sets the default drive to drive.  Drive values should start with 'A'.

Returns 0 if successful, otherwise returns an error code.

M_SETPAT
--------

    m_setpat(matchp,bp,len,sys);
    MATCH far *matchp;
    char far *bp;
    int len;
    int sys;


Builds the MATCH structure used for seaching for files with the m_match()
function.  bp is the pattern to match, including any path information.  
len specifies the length of bp. sys is not used and should be set
to zero.

M_TELL
------

    int m_tell(fp,seekp);
    FILE far *fp;
    long far *seekp;


Sets *seekp to the current position in the file associated with fp.

Returns 0 if successful, otherwise, returns an error code.

M_VOLUME
--------

    void m_volume(bp,sizep);
    char far *bp;
    long far *sizep;


Sets bp to the name of the current volume and sets *sizep to the
amount of freespace available on that volume.

M_WRITE
-------

    m_write(fp,buffer,len);
    FILE far *fp;
    char far *buffer;
    int len;


Writes len bytes of data to the I/O stream fp from the memory pointed
to by buffer.

Returns 0 if successful, otherwise, returns an error code.


===== PROCESS MANAGEMENT SERVICES =====

M_FINI
------

    void m_fini(void);


Signals to the System Manager that the current application is done. Control is
never returned to the application.

M_INIT
------

    void m_init(void);


Must be called by the application's main entry point.

M_LOCK
------

    void m_lock(void);


Increments the system lock count, which prevents interruption of the currently
running application while it is nonzero. That is, it causes other
applications' hot keys to be ignored.

This could be used, for example, to prevent a task switch until after an
error message is acknowledged by the user.

M_REG_APP_NAME
--------------

    m_reg_app_name(appname);
    char far *appname;


Records the null-terminated string pointed to by appname as the name of
the application. The application name is used in the low memory closeout
screen. The third field in the APNAME.LST entry provides an initial name
for external applications. Internal applications use this function to
record their names.

M_SPAWN
-------

    int m_spawn(command_str,command_len,sysflag,prompt_str);
    char far *command_str;
    int command_len;    
    int sysflag;
    char far *prompt_str;


command_str points to the string that will be passed to COMMAND.COM for
execution. command_str must be terminated with a carriage return
('\r' = 0x0d). command_len is the length of command_str.

sysflag can be 0 or 2. Applications should set sysflag to 0; value
2 is reserved for internal System-Manager use. When sysflsg is set to 0,
the calling application must be the only open application. When sysflag
is set to 2, the spawn will be attempted even if other applications are open.

prompt_str points to a null-terminated string that will be displayed by
the System Manager at the top of the screen prior to invoking the program.

Returns 0 if successful; 513 if another application is active; 
otherwise, a DOS error code as returned by EXEC (INT 21h, AH = 4bh).

M_UNLOCK
--------

    void m_unlock(void);


Decrements the system lock count. If calls are not nested, allows the system
to take control from the current application.


===== CLIPBOARD SERVICES =====

The following functions provide a generic means of passing information between
applications.  In the current form, applications can only get or put information
onto the clipboard; there is no provision for forcing information through to
another application.  Data on the clipboard is named, however.  
Applications can therefore establish regimes of communication as needed.

The default representation of data is that of "TEXT".  All applications using
the clipboard at all should write a "TEXT" representation, and read a "TEXT"
representation if no other known representations are found.  Data in the "TEXT"
form should be ASCII characters, with a lone carriage return (0x0d) used to
mark the end of each line.

Clipboard return codes are contained in cbcodes.h.

M_CB_READ
---------

    m_cb_read(index,offset,data,length);
    char far *data;
    int index;
    unsigned int length,offset;


Reads length bytes into data from the representation associated 
with index.	 offset indicates the starting offset in the clipboard 
buffer from which data will be read.

M_CB_WRITE
----------

    m_cb_write(data,length);
    char far *data;
    unsigned int length;


Writes length bytes from data to the representation opened by 
m_new_rep().  The maximun length of a single call to m_cb_write is 1024.   
Multiples calls may be made to m_cb_write() if needed.

M_CLOSE_CB
----------

    int m_close_cb();


Attempts to close the clipboard and allow other applications to claim it.
Returns 0 if successful; returns -1 if the clipboard is not currently open.

M_FINI_REP
----------

    m_fini_rep(void);


Signals the clipboard that no further data will be sent for the current
representation.

M_NEW_REP
---------

    m_new_rep(rep_name);
    char far *rep_name;


Prepares the clipboard to receive a representation under the name
rep_name.  Multiple representations of the same data may be copied to the
clipboard.

M_OPEN_CB
---------

    int m_open_cb(void);


Attempts to claim the clipboard and lock out requests from other applications.
Returns 0 if successfully claimed, otherwise returns a nonzero value.

M_REP_INDEX
-----------

    int m_rep_index(name,index,length);
    char far *name;
    int far *index;
    unsigned int far *length;


Gets the index and length of a representation, given a name.  
Returns 0 with pointers updated if successful; otherwise, returns an error
code.

Applications attempting to respond to a Paste command should call this
function with the appropriate representation name ("TEXT" as default).

M_REP_NAME
----------

    m_rep_name(index,name,length);
    int index;
    char far *name;
    unsigned int far *length;


Gets the name and length of a representation, given an index.
Returns 0 with pointers updated if successful; otherwise, returns an error
code.

M_RESET_CB
----------

    m_reset_cb(author);
    char far *author;


Clears the contents of the clipboard and establishes the current application,
specified by the string author, as the creator of clipboard contents.
Applications should attempt to use a unique string for this value.  Returns 0
if successful; returns -1 if there is an error.


===== SOUND SERVICES =====

These services are used to signal the user through the system speaker.

M_ASOUND
--------

    void m_asound(index);
    int index;


Generates one of several various sound patterns, as specified by index.  
There are currently seven (0-6) supported patterns. The first four are used to
generate tones for 1-2-3, the remaining three are more complicated alarm
sounds.

M_BEEP
------

    void m_beep(void);


General purpose sound for error alerts.

M_SOUNDOFF
----------

    void m_soundoff(void);


Turns off the current sound.  If the speaker is on when this function is
called, the sound will actually continue until the next BIOS clock tick.

M_THUD
------

    void m_thud(void);


Generally used when a user's keystroke cannot be interpreted in the current
application state.


===== MEMORY MANAGEMENT SERVICES =====

When an application is invoked, the System Manager must provide the RAM space
indicated in the application's image structure. This amount of memory should
be sufficient for ordinary uses of the application.  

There are limited instances when more RAM is required, at which point the
application calls m_alloc() or m_alloc_large() to expand the size of its data
area. If successful, the application's data area may have been moved by the
System Manager. Consequently, applications must be careful to not store
the current data segment or to update these stored values after
memory-allocation calls.

Dynamic memory allocation is implemented by resizing the memory block
belonging to the application. The new buffer will therefore begin at the
previous end of the memory block. Calls to release memory are translated into
requests to shrink the memory block to the specified level. These services
should not be confused with the functions malloc() and free().

DOS memory allocation services are also available. However, it is likely that
all DOS memory will have been consumed by 1-2-3, and memory will be available
only by using the System-Manager's memory-management services.

M_ALLOC
-------

    void near * m_alloc(expsize);
    unsigned int expsize;


Attempts to expand the data space occupied by the accesory by expsize
bytes. If successful, the return value will be the offset (near address) of
the new buffer. The function returns 0 on failure. Failure may be caused by a
request which would grow the applications total data space beyond 64K or by an
exhaustion of system memory.

If expsize is not a multiple of 16 (the size of a paragraph), it will be
rounded up to the next multiple.

M_ALLOC_LARGE
-------------

    void near * m_alloc(exp_paras);
    unsigned int exp_paras;


Attempts to expand the data space occupied by the accesory by exp_paras
paragraphs (16 byte units). If successful, the return value will be the 
paragraph offset from the beginning of the application's data segment. The
function returns 0 on failure.

This function must be used with care, since it is possible to claim space that
cannot be accessed through the DS register (> 64K). Since the entire data
space of the application may be moved during certain System Manager calls, the
application must be careful either not to store any segment values that may
become invalid or to update these stored values after any time that the data
segment may have moved.

M_FREE
------

    unsigned int m_free(ptr);
    void near *ptr;


Shrinks the data space claimed by the application by releasing all memory
beyond ptr. Applications should make sure that the value of ptr is
above or equal to the first value returned by m_alloc().

M_FREE_LARGE
------------

    void m_free_large(paras);
    unsigned int paras;


Shrinks the data space claimed by the application beginning at paras that
is the paragraph offset from the beginning of the application's data segment.
Applications must make sure that the value of paras is above or equal to
the first value returned by m_alloc_large().


===== DATE/TIME SERVICES =====

There are three subsets of date and time services. Primarily, there are calls
to get and set the system time and to get the system-wide display format.
Secondly, there are alarm calls, which are primarily used by the Appointment
Book and Watch applications. Finally, there are stopwatch functions used by the
Watch.

The date and time information is maintained in the following structure:


    typedef struct {
       char dt_order;     /* month-day-year order, 0 = MDY, 1 = DMY, 2 = YMD */
       char dt_dsep;      /* date separator */
       char dt_tsep;      /* time seperator */
       cahr dt_24_hr;     /* nonzero means 24 hour time */
    } DTINFO;


The following structure is used to schedule alarms:


    typedef struct {
       char a_hour;                  /* time of alarm */
       char a_minute;
       char a_second;
       char a_pad;                   /* supplied by caller */
       int a_interval;               /* reschedule interval (seconds) */
       char a_use_seconds;           /* are seconds significant */
       char a_sound;                 /* alarm sound */
       char message[ALARM_MSG_LEN];  /* message displayed when alarm goes off*/
       char owner;                   /* task id of owner */
       char special;                 /* apps own use for sub-class*/
       char extra[ALARM_EXTRA_LEN];  /* apps own use for specific data */
    } ALARM;


This final structure is used to represent the actual time and date:


 typedef struct {
    int  dt_year;       /* year in the range of 1980, to 2116 */
    char dt_month;      /* Jan == 1 */
    char dt_date;       /* 1st == 1 */
    char dt_day;        /* Day of week, 0->6;  otherwise unknown */
    char dt_hour;
    char dt_minute;
    char dt_second;
    cahr dt_hundreth;
 } DTM;


M_ALARM
-------

    m_alarm(alarmp,type);
    ALARM far *alarmp;
    unsigned int type;


Sets an alarm as defined in the ALARM structure pointed to by alarm and
associates it with the application-determined alarm type.

M_DTINFO
--------

    m_dtinfo(dtp);
    DTINFO far *dtp;


Fills in the DTINFO structure pointed to by dtp with a special time and
date information as described below. Due to the special nature of this
information, m_dtinfo() should probably not be used.

The information returned in dtp does not have complete separator
information. The current separator information is stored in the settings
structure (see the Configuration Services section). In that structure,
there are two separators for both date and time, to provide for flexibility
of localization. Only the first character is copied into the DTINFO structure
by m_dtinfo(). It is probably easier for applications to get these fields
directly from the settings structure.

These values are not based on the date and time settings selected in the
SETUP utility. Rather, they are part of the localization done when the user
selects his country at very cold boot. The values are used exclusively to
format date and time values in the Filer's directory directory listings.
They should match what a localized version of DOS would display in response
to the DIR command.

M_GETDTM
--------

    m_getdtm(dtmp);
    DTM far *dtmp;


Returns the system date/time in the DTM structure pointed to by dtmp.

M_GET_SW
--------

    m_get_sw(start_time,elapsed_time,onflag);
    TIME far *start_time;
    TIME far *elapsed_time;
    char far *onflag;


Copies contents of system manager buffers and variables into those supplied by
the application.

M_GET_TIMER
-----------

    m_get_timer(start_time,elapsed_time,onflag);
    DTM far *start_time;
    DTM far *elapsed_time;
    char far *onflag;


Copies contents of System Manager buffers and variables into those supplied by
the application.

M_PARSE_DATE
------------

    int m_parse_date(rule,input,dtm);
    int rule;
    char far *input;
    DTM far *dtm;


Parses a null-terminated input string accoring to rule, and fills in the
day, date, week, and year fields of the DTM structure pointed to by dtm
(the time of day fields are unaffected). Unspecified fields that do not cause
parsing errors are set to 0.

The available rules (found in settings.h) are:


     0 - rule appropriate to currently selected system date format.
     1 - DR_DMY_LIM - date, month, year and year must be in limited range.
     2 - DR_MDY_LIM - month, date, year and year must be in limited range.
     3 - DR_YMD_LIM - year, month, date and year must be in limited range.
     4 - DR_MD - just month and date.
     5 - DR_DM - just date and month
     6 - DR_MY_LIM - month and year and year must be in limited range.


Years with the rules above must be in the range of 1900 to 2099. Two-digit
input of years is assumed to be in the range of 1980 to 2079. For parsing of
arbitrary years, OR DR_ANY_YEAR (0x8) onto the rule code.


Returns 0 if parsing is successful, nonzero if input is improperly formatted
or invalid value.

M_PARSE_TIME
------------

    int m_parse_time(rule,input,dtm);
    int rule;
    char far *input;
    DTM far *dtm;


Parses a null-terminated input string accoring to rule, and fills in the
hour, minute, second, and hundredth fields of the DTM structure pointed to by
dtm (the date fields are unaffected). Unspecified fields that do not cause
parsing errors are set to 0.

The available rules (found in settings.h) are:

     0 = rule appropriate to currently selected system time format.
     1 - TM_H_M_S_P = 12 hour clock, with optional am/pm specifier.
     2 - TM_H_M_S+24 = 24 hour clock.
     3 - TM_HM_S_24 = 24 hour clock with hours and minutes together.
     4 - TM_H_M_S_C_24 = 24 hour clock to hundredth resolution.
     5 - TM_H_M_P = 12 hour clock, without seconds.
     6 - TM_H_M_24 = 24 hour clock, without seconds.
     7 - TM_HM_24 = 24 hour clock with hours minutes together, without seconds.


Returns 0 if parsing is successful, nonzero if input is improperly formatted
or invalid value.

M_POSTTIME
----------

    void m_posttime(void);


Gets the current time and writes it to the display in the standard location.

M_SETDTM
--------

    m_setdtm(dtmp);
    DTM far *dtmp;


Sets the system date/time with the contents of the DTM structure pointed to by
dtmp.

M_START_SW
----------

    m_start_sw(time);
   TIME far *time;


Saves the starting time specified in the TIME structure pointed to by time
in a system manager buffer and sets the System-Manager-stopwatch flag to on.

M_STOP_SW
---------

    m_stop_sw(time);
    TIME far *time;


Saves the current elapsed time, as calculated by an application and stored in
the TIME structure pointed to by time, in a System-Manager buffer and sets
the stopwatch flag to off.

M_START_TIMER
-------------

    m_start_timer(start_dtm);
    DTM far *start_dtm;


Saves the starting time specified in the DTM structure pointed to by
start_dtm in a System-Manager buffer and sets the System-Manager-timer
flag to on.


M_STOP_TIMER
------------

    m_stop_timer(elapsed_time);
    DTM far *elapsed_time;


Saves the current elapsed time, as calculated by an application and contained
in the DTM structure pointed to by elapsed_time, in a System Manager
buffer and sets the timer flag to off.

M_TELL_ANYTIME
--------------

    char far *m_tell_anytime(content,row,col,dtinfo,dtm);
    int content;
    int row;
    int col;
    DTINFO far *dtinfo;
    DTM far *dtm;


Formats the date or time contained in the structure pointed to by dtm, 
according to content. Returns a pointer to a System Manager buffer 
containing the formatted time. The content parameter uses the same values
as with m_telltime(). row, col, and dtinfo are ignored, but are
currently left in to preserve existing calls.

M_TELLTIME
----------

    m_telltime(content,row,col);
    int content,row,col;


Displays the current date or time, according to content, at the given row and
column coordinates. The current system date and time formats are used.

The defined content values are as follows:


     0 = date only
     1 = time only
     2 = date and time
     3 = date prefixed with day of week.


M_XALARM
--------

    m_xalarm(type);
    unsigned int type;


Kills all alarms of the application-defined type.

===== PRINTER SERVICES =====

The printer services manage communications with and translation of characters
for specific printer types. The active printer is selected through SETUP. That
selection is used to control access tables for special characters and
print-control sequences.

M_CLOSE_PRINTER
---------------

    void m_close_printer(void);


Any remaining characters are flushed to the printer, and the printer 
channel is closed.

M_INIT_PRINTER
--------------
    unsigned int m_init_printer(void);


The printer tables are initialized for the selected printer. This call does
not initialize the communications channel.  It is intended to be called from
1-2-3 and SETUP only. Other applications should use m_open_printer. A segment
value is returned which is used by 1-2-3 to access printer information in a
standard format.

M_OPEN_PRINTER
--------------

    void m_open_printer(void);


Prepares the communications channel to converse with the printer. The printer
baud rate is established and the printer tables are set to the selected device.

M_TRANS_PRINTER
---------------

    int m_trans_printer(ch,bp);
    char ch;
    char far *bp;


This routine should be used by applications that wish to do their own printer
communications. The CP850 character passed as ch is converted to the 
sequence required by the selected printer to produce the equivalent character.
The resulting sequence is placed in the buffer pointed to by bp. This 
buffer must be at least 48 bytes long. The number of characters in the buffer
is returned by this routine. That number will always be greater than zero.
       
M_WRITE_PRINTER
---------------

    int m_write_printer(bp,len);
    char far *bp;
    unsigned int len;


The string pointed to by bp is sent to the printer. The string is expected
to be composed of CP850 characters and of length len. Any special
sequences required to produce the specified characters on the output are
supplied by this routine.

This routine does not add a carriage return (0x0d), line feed (0x0a) pair for
terminating a line so these should be included in the string as desired.

===== CONFIGURATION SERVICES =====

Various System Manager settings are maintained in RAM in a SETTINGS structure.
The functions in this section provide access to this information.

Applications using these services must include settings.h and
interfac.h.

See settings.h for the definition of the SETTINGS structure as well as the
manifest constants which specify the values that may be found in the structure.

M_GET_SETTINGS_ADDR
-------------------

    SETTINGS far *m_get_settings_addr(void);


Returns a pointer to the System Manager's settings structure. Applications
other than SETUP should never change any values in this structure, but should
use this only to enquire about system settings.


===== COMMUNICATIONS SERVICES =====

The Communication Services provide access to the serial port.

Applications using the Communications Services must include comio.h and
interfac.h. 

ComAnswer
---------

    int ComAnswer(handle,mode);
    com_handle handle;
    int mode;


Put the modem/com line in answer mode. handle identifies the port to
which the modem is connected. The only valid value for mode is
COM_ANS_NOWAIT.

Returns 0 if successful; otherwise returns an error code.

ComBreak
--------

    int ComBreak(handle,duration);
    com_handle handle;
    int duration;


Sends a break to the port associated with handle. The break state will be
held for duration milliseconds.

Returns 0 if successful, otherwise, returns an error code.

ComClose
--------

    int ComClose(handle);
    com_handle handle;


Closes the communication port associated with handle.

Returns 0 if successful, otherwise, returns an error code.

ComCommand
----------

    int ComCommand(handle,cmd,cmdlen);
    com_handle handle;
    char far *cmd;
    int cmdlen;


Sends the modem specific command pointed to by cmd to the modem attached
to the port associated with handle, where cmdlen is the length of the
command.

The modem will be put into command state and the command will be sent 
verbatim.

No translation will occur.

The transmit queue associated with handle will be flushed before the
command is sent.

To ensure that all data is sent, use ComXmitting() before sending the command.

Returns 0 if successful, otherwise, returns an error code.

ComConfigure
------------

    int ComConfigure(port,IRQnum,IObase,modem,permflag);
    int port;
    int IRQnum;
    int IObase;
    int modem;
    int permflag;

***********
* NOTE!!! *
***********
There is no need for this routine to be called on the HP 95LX, since there is
only one COM port, and one configuration that may be used.
***********
* NOTE!!! *
***********
    
Configures the communications port where IRQnum is the
interrupt-request number, IObase is the base address of the port in I/O
space, and modem is the modem type.

If permflag is nonzero, the information will be entered into the COM 
driver's permanent database, otherwise it will not be permanent.

Returns 0 if successful, otherwise, returns an error code.

ComDial
------

    int ComDial(handle,number);
    com_handle handle;
    char far *number;


Dials the number contained in number on the modem associated with
handle.

number includes punctuation and/or commas and the number will be dialed
according to the modem's specifications. For example, ','s cause a delay.

Returns 0 if successful, otherwise, returns an error code.

ComForceXoff
------------

    int ComForceXoff(handle);
    com_handle handle;


Forces XOFF state on the port associated with handle.

Returns 0 if successful, otherwise, returns an error code.

ComForceXon
-----------

    int ComForceXon(handle);
    com_handle handle;


Forces XON state on the port associated with handle.

Returns 0 if successful, otherwise, returns an error code.

ComHangUp
---------

    int ComHangUp(handle);
    com_handle handle;


Hangs up phone on the modem attached to the port associated with handle.
The transmit queue associated with handle will be flushed before the
command is sent. To ensure that all data is sent, use ComXmitting() before
sending the hang-up command.

Returns 0 if successful, otherwise, returns an error code.

ComHayesCommand
---------------

    int ComHayesCommand(handle,cmd,cmdlen);
    com_handle handle;
    char far *cmd;
    int cmdlen;


Sends the Hayes command pointed to by cmd to the modem attached to the
port associated with handle, where cmdlen is the length of the command.

The transmit queue associated with handle will be flushed before the
command is sent. To ensure that all data is sent, use ComXmitting() before
sending the command.

Returns 0 if successful, otherwise, returns an error code.

ComGet
------

    int ComGet(handle,settings);
    com_handle handle;
    com_settings far *settings;


Gets the communications settings for the port associated with handle.
These settings are returned in the structure pointed to by settings.

Returns 0 if successful, otherwise, returns an error code.

ComGetModem
-----------

    int ComGetModem(handle);
    com_handle handle;


If successful, returns the modem type for the port associated with handle, 
otherwise, returns an error code. If successful, the returned value is either
COM_MDM_NONE or COM_MDM_HAYES indicating either no modem or Hayes-compatible
modem, respectively.

ComOpen
-------

    int ComOpen(handle,port);
    com_handle far *handle;
    int port;


Opens the communication port specified by port and returns a handle in the
location given by handle. The returned handle is associated with this port
and is used in subsequent communications function calls.

Returns 0 if successful, otherwise, returns an error code.

ComQryErr
---------

    int ComQryErr(handle);
    com_handle handle;


Returns the error status of the port associated with handle. A return
value of 0 indicates no error. Possible nonzero error values are E_OVERN,
E_PARITY, E_FRAME, etc.

Use of ComStatus is preferred over use of ComQryErr.

ComQryRxQue
-----------

    int ComQryRxQue(handle,size,free);
    com_handle handle;
    int far *size;
    int far *free;


Queries the status of the receive queue for the port associated with
handle. Sets the location specified by size to the total queue size
and sets the location specified by free to the number of free bytes in
the queue.

Returns 0 if successful, otherwise, returns an error code.

ComQryTxQue
-----------

    int ComQryTxQue(handle,size,free);
    com_handle handle;
    int far *size;
    int far *free;


Queries the status of the transmit queue for the port associated with
handle. Sets the location specified by size to the total queue size
and sets the location specified by free to the number of free bytes in
the queue.

Returns 0 if successful, otherwise, returns an error code.

ComReceiveBytes
---------------

    int ComReceiveBytes(handle,data,datalen);
    com_handle handle;
    char far *data;
    int far *datalen;


Receives bytes from the port associated with handle. The data is received
in the location specified by data up to a maximum of datalen bytes. On
return, datalen is set to the number of bytes actually received, which can
be zero.

Returns 0 if successful, otherwise, returns an error code.

ComReset
--------

    int ComReset(handle,reset);
    com_handle handle;
    int reset;


Resets the port associated with handle in accordance with the reset
options specified in reset. reset uses bit values to indicate what is
to be reset. The constants listed below can be OR'd together to create the
desired reset actions.


	Constant		Bit	Action if Bit is Set
	--------------		---	------------------------------
	COM_RESET_LINE		0	Line is reset.
	COM_RESET_TXB		1	Transmit buffer is flushed.
	COM_RESET_RXB		2	Recieve buffer is flushed.
	COM_RESET_MODEM		3	Modem is reset.
	COM_RESET_RXFLOW	4	Receiver's ^S state is reset.
	COM_RESET_TXFLOW	5	Transmitter's ^S state is reset.


Always returns 0.

ComSendBytes
------------

    int ComSendBytes(handle,data,option,datalen);
    com_handle handle;
    char far *data;
    int option;
    int far *datalen;


Queues datalen bytes of data pointed to by data for transmission 
over the port associated with handle.  control uses bit values to
indicate queuing options.  The constants listed below can be OR'd
together to create the desired actions.


	Constant	Bit	Action if Bit is Set
	--------------	---	---------------------
	COM_CTL_WHOLE	0	Do not queue any data unless all datalen bytes
				will fit in the output queue.
	COM_CTL_SETRCV	1	Turn receiver on after sending data.


If COM_CTL_WHOLE is not specified, partial data may be queued and several
calls to ComSendBytes may be required to complete sending all the data. 

If successful, returns 0 and stores the number of bytes queued for 
transmision in the location specified by datalen. If not successful, an
error code is returned. In particular, E_NOFIT will be returned if
COM_CTL_WHOLE was specified and there is not enough free space in the transmit
queue to fit the data. In this case, the value pointed to by datalen will
be set to zero.

ComSet
------

    int ComSet(handle,settings);
    com_handle handle;
    com_settings far *settings;


Sets the communications settings for the port associated with handle to
the values contained in the structure pointed to by settings.

Note that the values used may differ from what is specified in the structure.
For instance, if IR is used, HALF-DUPLEX is forced, baud rate is limited to 
2400, and FLOW control is turned off. On return the passed structure will have
the settings that are actually being used.

Returns 0 if successful, otherwise, returns an error code.

ComSetDtr
---------

    int ComSetDtr(handle,state);
    com_handle handle;
    int state;


Sets the DTR state on the port associated with handle. If state is
zero, DTR will be set OFF, else DTR will be set ON.

ComStatus
---------

    int ComStatus(handle);
    com_handle handle;


Returns the error status of the port associated with handle. A return
value of 0 indicates no error. Possible nonzero error values are E_OVERN,
E_PARITY, E_FRAME, etc.

ComXmitting
-----------

    int ComXmitting(handle);
    com_handle handle;


Tests the transmitting status on the port associated with handle.

Returns 0 if nothing is being transmitted, else returns a nonzero value.


===== MISCELLANEOUS SERVICES =====

DrawBox
-------

    void drawbox(box_name);
    char far *box_name;


May be used to display the application name on draw the double line seperating
the menu area from the data window. The application name to be dieplayed is
pointed to by box_name. The display is cleared before the box is drawn.

M_ERRMSG
--------

    void m_errmsg(code,bp,len,lenp);
    int code;
    char far *bp;
    int len;
    int far *lenp;


Returns the string which serves as the error message for the code passed in
code. String is copied into buffer pointed to by bp, whose maximum
length is specified by len. The actual length of the returned string is
returned in *lenp.

If an error message is not found for the given code, the string "Error n" is
generated.

Actual codes are listed in m_error.h.

MESSAGE
-------

    void message(str1,len1,str2,len2);
    char far *str1;
    char far *str2;
    int len1;
    int len2;


Displays one or two lines of text in the menu area of the application window.
The string pointed to by str1 is displayed on the first line and the
string pointed to by srt2 is displayed on the second line. len1 and
len2 give the lengths of the strings str1 and str2, respectively.
Strings that are wider than the display area will be truncated.

When message is called, the screen hidden by the message box is saved by the
System Manager, and will be restored by a call to msg_off().

Generally speaking, applications should lock the system (m_lock()) until the
message is cleared by the user.


MESSAGE3
--------

    void message3(str1,len1,str2,len2,str3,len3);
    char far *str1;
    char far *str2;
    char far *str3;
    int len1;
    int len2
    int len3;


Similar to message() except that it supports three lines of text.

MSG_OFF
-------

    void msg_off(void);


Clears the message posted by a prior call to message() or message_3() and
restores the text that was covered by the message box.

M_FORM_FT
---------

    char far *m_form_ft(dtm);
    DTM far *dtm;


Given the time and date in the DTM structure pointed to by dtm, returns
a pointer to a null-terminated string in the format described above,
suitable for display in a directory listing.

***********
* NOTE!!! *
***********
The contents of the buffer will be destroyed by the next call to any of the
date and time formatting functions (made by the caller), so it should be
used immediately.
***********
* NOTE!!! *
***********

This function is used by the Filer to format the date and time used in its
directory listings.

ShowName
--------

    void showname(box_name);
    char far *box_name;


Displays box_name on the menu line of the application's window.


===== RESOURCE SERVICES =====

The Resource Services are only applicable to the built-in applications.

===== HELP SERVICES =====

At this time, the Help Services are only applicable to the built-in
applications.

===== COLLATING SERVICES =====

The System Manager provides character and string comparison functions which may
be used to sort items.  These comparisons are more useful than those based
solely on the machine's character set.

M_COL_CPSEARCH
--------------

    int m_col_cpsearch(sptr,slen,dptr,dlen,dir);
    char far *sptr;
    int slen;
    char far *dptr;
    int dlen;
    int dir;


The data string of length dlen pointed to by dptr is searched for the
search string of length slen pointed to by sptr. The search is in a
forward direction if dir = -1, and backwards if dir = +1. The
search comparison follows the same rules as for m_col_cpstr.

If found, returns the offset of the beginning of the search string within the
data string. If not found, returns 0. 

M_COL_CPSTR
-----------

    int m_col_cpstr(str1,len1,str2,len2);
    char far *str1;
    int len1;
    char far *str2;
    int len2;


Compares the supplied code page 850 string of length len1 pointed to by
str1 with the code page 850 string of length len2 pointed to by
str2. Comparison is case- and accent-insensitive: characters a, A, and
 are considered equivalent. Graphical characters also all evaluate
together.

Returns:


     0  if the strings are equal
    +1  if string 1 precedes string 2
    -1  if string 2 precedes string 1


M_COL_INIT
----------

    void m_col_init(void);


Initializes internal pointers in accordance with the global sort selection.
These are used by the LICS comparison routines.

M_COL_TOLOWER
-------------

    void m_col_tolower(sptr,len);
    char far *sptr;
    int len;


The code page 850 string of length len pointed to by sptr is scanned
through its length, and any upper case characters found are converted to their
lower-case equivalents.

M_COL_TOUPPER
-------------

    void m_col_toupper(sptr,len);
    char far *sptr;
    int len;


The code page 850 string of length len pointed to by sptr is scanned
through its length, and any lower case characters found are converted to their
upper case equivalents.


===== 1-2-3 BRIDGE SERVICES =====

The System Manager includes a bridge function, with a set of subfunctions,
which allow applications to communicate with 1-2-3.

Applications using the bridge services must include bridge.h.

Applications prepare a bridge parameter block (see below) and make a call to
the bridge service. The system manager confirms that 1-2-3 is loaded and
performs a context-switch so that the applicaiton is deactivated (but not
notified, since it is generating the bridge request) and 1-2-3 is reactivated
with a Bridge-Request Event, that contains a pointer to the
application-supplied parameter block.

1-2-3 then performs the requested action and signals the System Manager that
the service has been completed. 1-2-3 is fully responsible for the values
returned in the parameter block (except for -1 in the retcode that
indicates that 1-2-3 is not loaded). The System Manager then switches control
back to the application.

In general, the application should repaint its screen when it regains control.

The bridge parameter block definition is:


   typedef BRIDGE_BP {
      int bpb_funcode;          /* function code */
      int bpb_retcode;          /* return value */ 
      char bpb_rangename[16];   /* ASCIIZ name of range */
      int bpb_startcol;         /* column coordinates of range start */
      int bpb_startrow;         /* row coordinates of range start */
      int bpb_endcol;           /* column coordinates of range end */
      int bpb_endrow;           /* row coordinates of range end */
      int bpb_order;            /* order (row or col first) of range data */
      int bpb_bufsize;          /* size in bytes of supplied buffer */
      char near *bpb_buffer;    /* buffer for prompt and range data (must be
                                   located in same seg. as the struct) */
   } BRIDGE_BP;


Range specification (used even for a single cell) is stored in the
bpb_startcol, bpb_startrow, bpb_endcol, and bpb_endrow fields of the
bridge-parameter block. Coordinates are zero based so that the cell A1 is
stored as COL=0, ROW=0.

If the range is to be accessed by name, the name is stored as an ASCIIZ string
in the bpb_rangename field.

Applications and 1-2-3 exchange cell contents using a buffer composed of
variable length cell records. The records contain a single byte type followed
by a type specific body. The cells are in the order declared by a flag passed
with the get/set functions.

The following cell types are defined:

	Type Code	Type		Body Length
	----------	----		-----------------
	B		Blank		0
	I		Integer		2
	N		Float		8
	S		ASCIIZ String	variable
	F		Formula		variable


BRIDGE_SERV
-----------

    void bridge_serv(bpb);
    BRIDGE_BP far *bpb;


The bridge services are used by setting a function code in the bridge
parameter block and then calling bridge_serv. The valid function codes are
described below.

*** BRIDGE_TEST

This function should be called before using any other services to ensure that
1-2-3 is loaded and ready to receive bridge calls.


   INPUT:

       bpb_funcode        BRIDGE_TEST (0)

   OUTPUT:

       bpb_retcode        1 if 1-2-3 is loaded and safe for bridge services
                          0 if 1-2-3 is loaded, but busy.
                         -1 if 1-2-3 is not loaded.


*** BRIDGE_GETRANGE

This function switches to 1-2-3 POINT mode, for user to select range. Range
can be entered by painting, or by name. Pressing the NAMES key (F3) will
switch to NAMES mode, allowing the user to select by name.


   INPUT:

       bpb_funcode       BRIDGE_GETRANGE (1)
       bpb_buffer        ASCIIZ string containing user prompt.
       bpb_order         The range edit is controlled by the following
                         bitflags:
                              1 = BRIDGE_GETRANGE_EDITOLD
                              2 = BRIDGE_GETRANGE_STARTANCHORED
                              4 = BRIDGE_GETRANGE_SHOWHIDDEN

                         If directed to EDITOLD, then getrange edits the
                         range in startcol..., else starts at the current
                         cursor position.

                         If STARTANCHORED then getrange begins with an
                         ancored range, else single cell.

                         If SHOWHIDDEN, then 1-2-3 will show hidden columns
                         hidden with /wch, else will hide those columns.

   OUTPUT:

       bpb_retcode       1 if successful
                         0 if user entered ESC, thus aborting selection.
                        -1 if 1-2-3 is not loaded.

       bpb_rangename     ASCIIZ string is used selected by name, else '\0'

       bpb_startcol      Coordinates of selected range.
       bpb_startrow
       bpb_endcol
       bpb_endrow


*** BRIDGE_GETRANGE_ADDR

This function returns the current coordinates for a named range.


   INPUT:

       bpb_funcode        BRIDGE_GETRANGE_ADDR (2)

       bpb_rangename      ASCIIZ string containing range name.

   OUTPUT:

       bpb_retcode        1 if successful
                          0 if range name not found.
                         -1 if 1-2-3 is not loaded.

       bpb_startcol       Coordinates of selected range.
       bpb_startrow
       bpb_endcol
       bpb_endrow


*** BRIDGE_SETRANGE_ADDR

This function sets the coordinates for a named range. If the range name
already exists, its coordinates will be replaced. If the range does not
already exist, it will be created.


   INPUT:

       bpb_funcode       BRIDGE_SETRANGE_ADDR (3)

       bpb_rangename     ASCIIZ string containing range name.

       bpb_startcol      Coordinates of selected range.
       bpb_startrow
       bpb_endcol
       bpb_endrow

   OUTPUT:

       bpb_retcode       1 if successful
                         0 if failed (not enough room in 123 or invalid values)
                        -1 if 1-2-3 is not loaded.


*** BRIDGE_GETRANGE_DATA

This function gets the data associated with a range of cells, which must be
specified through coordinates. The data is exported from 1-2-3 into the client
supplied buffer (bpb_buffer). Cells are copied until the entire range is
exported, or the buffer overflows. The data is a stream of cell records that
must be parsed by the client.


   INPUT:

       bpb_funcode        BRIDGE_GETRANGE_DATA (4)

       bpb_startcol       Coordinates of range.
       bpb_startrow
       bpb_endcol
       bpb_endrow

       bpb_order          Row order = 0 (a1,b1,a2,b2,etc)
                          Column order = 1 (a1,a2,b1,b2,etc)

       bpb_bufsize        Size in bytes of client supplied buffer.

       bpb_buffer         Pointer to client supplied buffer.  Segment must
                          be the same as that of the bpb structure itself,
                          which must be in the client's data segment.
   OUTPUT:

       bpb_retcode        Number of cells returned in buffer.
                          0 may indicate error in argument specification.
                         -1 if 1-2-3 not loaded,

       bpb_buffer         Stream of cell records.


*** BRIDGE_SETRANGE_DATA

This function sets the contents of a cell or range. The data is imported to
1-2-3 from the bpb_buffer field. The entire range must be contained in the
RDB. The data is a stream of cell records which will be parsed by 1-2-3.


   INPUT:

       bpb_funcode        BRIDGE_SETRANGE_DATA (5)

       bpb_startcol       Coordinates of range.
       bpb_startrow
       bpb_endcol
       bpb_endrow

       bpb_order          Row order = 0 (a1,a2,b1,b2,etc)
                          column order = 1 (a1,b1,a2,b2,etc)

       bpb_bufsize        Size in bytes of the cell stream found in
                          bpb_buffer.

       bpb_buffer         Pointer to client supplied buffer.  Segment must
                          be the same as that of the bpb structure itself,
                          which must be in the client's data segment.  Data
                          must be a stream of cells to be parsed by 1-2-3.

   OUTPUT:

       bpb_retcode        number of cells successfully entered.  Any number
                          less than the full range indicates error, probably
                          inadequate memory or invalid range specification.
                         -1 if 1-2-3 not loaded.


*** BRIDGE_RECALC

This function tells 1-2-3 to recalculate the current worksheet.


   INPUT:

       bpb_funcode        BRIDGE_RECALC (6)

   OUTPUT:

       bpb_retcode        1 if successful
                          0 if error
                         -1 if 1-2-3 is not loaded.

*** BRIDGE_GET_CURSOR

This function gets the cell coordinates of the cursor.


   INPUT:

       bpb_funcode        BRIDGE_GET_CURSOR (7)

   OUTPUT:

       bpb_startcol       Coordinates of cursor.
       bpb_startrow

       bpb_retcode        1 if successful.
                          0 if error.

                         -1 if 1-2-3 is not loaded.


*** BRIDGE_SET_CURSOR

This function sets the cell coordinates for the cursor.


   INPUT:

       bpb_funcode        BRIDGE_SET_CURSOR (8)

       bpb_startcol       Coordinates for cursor.
       bpb_startrow

   OUTPUT:

       bpb_retcode        1 if successful
                          0 if error
                         -1 if 1-2-3 is not loaded.


*** BRIDGE_REDISPLAY

This function causes 1-2-3 to redisplay the worksheet, but does not redisplay
the control panel or status area. 


   INPUT:

       bpb_funcode        BRIDGE_REDISPLAY (9)

   OUTPUT:

       bpb_retcode        1 if successful
                          0 if error
                         -1 if 1-2-3 is not loaded.


*** BRIDGE_CELLTYPE

This function returns the cell type of the specified cell.


   INPUT:

       bpb_funcode        BRIDGE_CELLTYPE (10)

       bpb_startcol       Coordinates of cell.
       bpb_startrow

   OUTPUT:

       bpb_retcode        'B' if blank
                          'I' if integer
                          'N' if float
                          'S' if ASCIIZ string
                          'F' if formula


*** BRIDGE_CALCTYPE

This function returns the current calc type of 1-2-3.


    INPUT:

       bpb_funcode        BRIDGE_CALCYTPE(11)

    OUTPUT:

       bpb_retcode        0 if 1-2-3 in manual mode.
                         -1 if 1-2-3 in automatic mode.

