link.h

The <link.h> Header File

Calc/calc and calc/computer link interface routines

Functions

getcalc: Receives a variable (or program) from the link interface.
LIO_Get: Gets a CBL file from the link interface.
LIO_GetMultiple: Gets a multiple (???) from the link interface.
LIO_Receive: Receives a file from the link interface.
LIO_RecvData: Receives data from the link interface.
LIO_Send: Sends a file through the link interface.
LIO_SendData: Sends data through the link interface.
LIO_SendIdList: Sends the ID list of the calculator through the link port.
LIO_SendProduct: Sends a product code through the link interface.
OSCheckLinkOpen: Checks if the link port is open.
OSCheckSilentLink: Checks the link state.
OSLinkClose: Closes a low-level link communication.
OSLinkCmd: Process the command received through the link port.
OSLinkOpen: Opens low-level link communication.
OSLinkReset: Resets the link interface.
OSLinkTxQueueActive: Determines whether the transmit queue is active.
OSLinkTxQueueInquire: Determines the number of free bytes in the transmit buffer.
OSReadLinkBlock: Reads bytes from the link receive buffer.
OSWriteLinkBlock: Inserts bytes into the link transmit buffer.
sendcalc: Sends a variable (or program) through the link interface.

Constants

NULL: A null-pointer value.

Predefined Types

Bool: An enumeration to describe true or false values.
CESI: Represents a pointer to a constant expression.
ESI: Represents an index of a value on the TIOS expression stack.
ESQ: Represents a quantum within an expression.
LIO_CTX: A file context structure used in some high-level link commands.
size_t: A type to define sizes of strings and memory blocks.
SYM_STR: Represents a pointer to the terminating zero byte of a string.

Note: Some functions from this header file are straightforward and quite simple to use, but some of them require good knowledge of TI's communication protocols (much better than my knowledge about it, so don't ask me about details; protocol information can be found at http://www.ticalc.org/pub/text/calcinfo/tixx_guide.zip).

getcalc

void getcalc (SYM_STR SymName);

Receives a variable (or program) from the link interface.

getcalc receives a variable (or program) from the link interface (this is exactly what the TI-Basic command GetCalc does). SymName is a pointer to the variable name. Note that SymName is not an ordinary C string. Instead, it is zero-started zero-terminated string, and SymName points to the terminating byte of it (many TIOS functions for manipulating with TIOS variables use such strings). See SYMSTR and other functions from the vat.h header file for more info about symbol names).

Note: getcalc enters a loop which will not end until the data is received. The only method to break out of this loop (if no data is received) is pressing the 'ON' key.

LIO_Get

unsigned short LIO_Get (LIO_CTX *file);

Gets a CBL file from the link interface.

LIO_Get is a high-level function which receives a CBL (Calculator-Based Laboratory) file through the link interface and fills LIO_CTX structure pointed to by file accordingly (note that I don't know much more about it). LIO_Get returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values).

LIO_GetMultiple

short LIO_GetMultiple (LIO_CTX *file);

Gets a multiple (???) from the link interface.

Yet another unclear high-level link routine. It is called often as a subroutine in other high-level linking routines. In fact, it just performs

LIO_Receive (file, 0, 0);

but returns a different result. If LIO_Receive returns 0, LIO_GetMultiple returns -1. If LIO_Receive returns 0xFFFF, LIO_GetMultiple returns 0. Else, LIO_GetMultiple returns the same value returned from LIO_Receive. Don't ask me what it means. Any additional info is welcomed.

LIO_Receive

unsigned short LIO_Receive (LIO_CTX *file, unsigned short DevType, short skipmuch);

Receives a file from the link interface.

LIO_Receive is a high-level function which receives a file (a variable for example) through the link interface and fills the LIO_CTX structure pointed to by file accordingly. However, this function is not so easy for usage, because you need to interpret the file context structure pointed to by file manually after using this function, which is not a trivial task. If you want just to receive a variable through the link interface, function getcalc is much easier to use. The advantage of this routine is greater generality in comparing to getcalc (for example, it allows transfer even between incompatible TI models, if properly used; sorry, I don't know too much about it).

The parameter DevType determines the device type (see LIO_Send for the explanation about its meaning). It seems that it is possible to set DevType to zero (it probably means "receive from anything").

The parameter skipmuch is a boolean parameter (if it is non-zero, a lot of code in this function is skipped over). skipmuch has to do with the Silent Link mode (see OSCheckSilentLink). When receiving a file manually, the AMS calls LIO_Receive with a value of 0 for skipmuch; in Silent Link mode, LIO_Receive is called with a value of 1 once the header has been read, to transfer the file properly.

LIO_Receive returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values).

LIO_RecvData

unsigned short LIO_RecvData (void *dest, unsigned long size, unsigned long WaitDelay);

Receives data from the link interface.

LIO_RecvData reads size bytes through the link interface, and stores received bytes at the address dest. This functions calls repeatedly OSReadLinkBlock function as many times as necessary to receive wanted amount of data. Parameter WaitDelay is the maximal allowed waiting time: if no data is received during WaitDelay timer ticks (one timer tick is 1/20 seconds by default), the reading fails. When WaitDelay is set to zero, this means "waiting forever". Anyway, this operation may be interrupted by pressing ON key. LIO_RecvData returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values).

Note: This functions registers LIO_TIMER for measuring the time. See OSRegisterTimer for more info.

LIO_Send

unsigned short LIO_Send (LIO_CTX *file, unsigned short DevType);

Sends a file through the link interface.

LIO_Send is a high-level function which sends a file (a variable, a screen dump file, etc.) described by the LIO_CTX structure pointed to by file through the link interface. However, this function is not so easy for usage, because you need to fill the file context structure pointed to by file manually before using this function. If you want just to send a variable through the link interface, function sendcalc is much easier to use. The advantage of this routine is greater generality in comparing to sendcalc (for example, it allows transfer even between incompatible TI models, if properly used; sorry, I don't know too much about it).

Parameter DevType determines the device type (this information is stored in the header of each packet during the communication). It is a collection of flags. Bit b7 is 0 during transfer from a computer to a calculator and 1 during transfer from a calculator to a computer or another calculator. Bits b6 and b5 are reserved (keep them to 0). Bit b4 is 1 if a device is a "special" device, whatever it means (so far, I know that this bit is set if a device is TI-89 or CBL). Bits b3-b0 determine the calculator type (so far, I know the following meanings: 0010 for TI-82, 0011 for TI83, 0101 for TI85, 1000 for TI-89 or TI-92 Plus, and 1001 for TI-92). So, DevType should to be 0x98 for sending from TI-89 or 0x88 for sending from TI-92 Plus.

LIO_Send returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values).

LIO_SendData

unsigned short LIO_SendData (const void *src, unsigned long size);

Sends data through the link interface.

LIO_SendData sends size bytes from the address src through the link interface. This function calls repeatedly OSWriteLinkBlock function as many times as necessary to send all of data. Returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values).

LIO_SendIdList

AMS 2.00 or higher

unsigned short LIO_SendIdList (unsigned short delete);

Sends the ID list of the calculator through the link port.

If the ID list does not exist, creates one using the calculator's ID. Otherwise, the calculator ID is appended. This list is then sent over the link port.
If delete is TRUE, the ID list is deleted from memory after it is sent.
The function returns non-zero if an error occurs, otherwise it returns zero.

LIO_SendProduct

unsigned short LIO_SendProduct (LIO_CTX *file, unsigned short DevType);

Sends a product code through the link interface.

LIO_SendProduct is a high-level function which sends a Product Code through the link interface. What exactly will be sent is described in LIO_CTX structure pointed to by file. Parameter DevType determines the device type (see LIO_Send for the explanation about its meaning). This routine is called from the VAR_LINK menu. Returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values).

OSCheckLinkOpen

unsigned short OSCheckLinkOpen (void);

Checks if the link port is open.

This function returns TRUE if the link port is open, FALSE otherwise.

OSCheckSilentLink

short OSCheckSilentLink (void);

Checks the link state.

OSCheckSilentLink returns an integer which determines the link state. The meaning of the returned value is:

0 None (the link is silent)

1 A variable header or extended header is received

2 A direct command, a screen dump, a request with size or a request is in progress

3 The link is ready

This function is called from high-level keyboard reading functions like kbhit and ngetchx, and if it returns non-zero, OSLinkCmd is called to process the received packet (as the link is interrupt-driven, a packet may be received asynchronously, without the request from the program itself). So, the TIOS can receive variables from the link whenever the program is waiting for a keypress (used mainly when the calculator is in the Home Screen).

OSLinkClose

void OSLinkClose (void);

Closes a low-level link communication.

OSLinkClose waits until eventual bytes waiting in transmit queue are sent out, then clears both transmit and receive queues, and clear a flag which tells that the communication is opened.

OSLinkCmd

void OSLinkCmd (short NormalState);

Process the command received through the link port.

OSLinkCmd should to be called after OSCheckSilentLink if the result returned from it is non-zero (this means that there is a packet received from the link port, which waits to be processed). This function handles link commands when the calculator is in the Home Screen for example (link commands are stored in packets). Parameter NormalState should to be set to TRUE if the calculator is in a "normal receiving state", i.e. if the current application is "Home Screen", if the screen is not splitted, and if there is no any event-driven "applets" installed using EV_captureEvents (see events.html for more info). This parameter helps TIOS to conclude which link commands should be processed, and which commands should be rejected (for example, the calculator cannot receive variables if it is not in a "normal receiving state").

OSLinkOpen

void OSLinkOpen (void);

Opens low-level link communication.

OSLinkOpen clears both transmit and receive queues, then set a flag which tells that the communication is opened.

Deprecated alias: flush_link

OSLinkReset

void OSLinkReset (void);

Resets the link interface.

OSLinkReset resets the link interface. It also resets all link variables and performs OSLinkClose.

Deprecated alias: reset_link

OSLinkTxQueueActive

short OSLinkTxQueueActive (void);

Determines whether the transmit queue is active.

OSLinkTxQueueActive returns TRUE if the transmit queue is active, else returns FALSE. This function checks bit b1 in I/O port 0x60000C (interrupt on transmit buffer empty).

OSLinkTxQueueInquire

unsigned short OSLinkTxQueueInquire (void);

Determines the number of free bytes in the transmit buffer.

OSLinkTxQueueInquire returns the number of free bytes in the link transmit buffer. Note that this number may change in a time without any obvious actions, because the link communication is interrupt driven.

Deprecated alias: tx_free

OSReadLinkBlock

unsigned short OSReadLinkBlock (char *buffer, unsigned short num);

Reads bytes from the link receive buffer.

OSReadLinkBlock reads at most num bytes into buffer from the link receive buffer. Returns the number of bytes read.

Note: This function is a low-level function. See also LIO_RecvData for a higher-level variant of this function.

Deprecated alias: receive

OSWriteLinkBlock

short OSWriteLinkBlock (const char *buffer, unsigned short num);

Inserts bytes into the link transmit buffer.

OSWriteLinkBlock inserts num bytes from buffer into the link transmit buffer. Returns 0 if the operation was sucessful, else returns a non-zero value. num must be in the range 1-128. An error occurs if num is out of range or if there is not enough room in the transmit buffer to insert num bytes.

Note: This function is a low-level function. See also LIO_SendData for a higher-level variant of this function.

Deprecated alias: transmit

sendcalc

unsigned short sendcalc (SYM_STR SymName, short allowSysVars, unsigned short DevType, unsigned char *compat);

Sends a variable (or program) through the link interface.

sendcalc sends a variable (or program) through the link interface (this is exactly what the TI-Basic command SendCalc does). SymName is a pointer to the variable name. allowSysVars is a Boolean parameter. If it is TRUE, transfer of a system variable will be allowed, and if it is FALSE, such transfer will be rejected. DevType determines the device type (see LIO_Send for the explanation about its meaning). If Compat is not a NULL pointer, sendcalc also stores in a byte variable pointed to by compat compatibility information about the variable which will be transfered (see info about SYM_ENTRY structure in vat.h header file for more info about compatibility flags).

Note that SymName is not an ordinary C string. Instead, it is zero-started zero-terminated string, and SymName points to the terminating byte of it (many TIOS functions for manipulating with TIOS variables use such strings). See SYMSTR and other functions from the vat.h header file for more info about symbol names). For example, to send a variable called "example" from one TI-89 unit to another, use the following command:

sendcalc (SYMSTR ("example"), FALSE, 0x98, NULL);

Replace 0x98 with 0x89 to simulate TI-Basic SendChat command instead of SendCalc.

sendcalc returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values). This function also may throw an error in a case of various fatal errors, so error trapping (using functions from the error.h header file) is recommended.

See also: getcalc, cmd_sendcalc, cmd_sendchat

LIO_CTX

typedef struct {
unsigned short hVar; /* File handle (or 0 if no handles associated) */
union {
const void *pVar; /* Pointer to the file, used only if hVar is 0 */
struct {
unsigned short FindFlags;
unsigned short NameSym;

} DirVars; /* Used only if hVar is non-zero */

} extra;
const char *VarName; /* Pointer to the var name (ordinary C string) */
unsigned long VarSize; /* Size of the variable */
unsigned short Index; /* Only for CBL access - data sent as float array */
unsigned short Unknown; /* Sent after index */
unsigned char VarType; /* See below */
unsigned char VarCompat; /* See info about SYM_ENTRY in vat.h */

} LIO_CTX;

A file context structure used in some high-level link commands.

LIO_CTX is a file context structure used in some high-level link commands. Some fields of this structure are not so clear for me. However, in many applications not all fields need to be set properly, so limited use of this structure is possible.

The field VarType may contain the following values (I don't know much more than I wrote in this table, so don't ask me about details):

0 Expression

4 List

6 Matrix

10 Data

11 Text

12 String

13 GDB variable

14 Geometry figure

16 Picture

17 Picture (???)

18 TI-Basic program

19 TI-Basic function

20 Geometry macro

21 In link protocol, cause execution of assembly block

25 Directory list (used recursively, unless VarType 26 follows)

26 List the folder table entries

27 List contents of a given folder (VarType 26 should follow)

28 Other (OTH) file

29 Backup file

31 Folder entry symbol in group files

32 Used for getting a certificate

33 ASM program

34 ID List

35 Product code (AMS)

36 FLASH application

37 Certificate

0	None (the link is silent)
1	A variable header or extended header is received
2	A direct command, a screen dump, a request with size or a request is in progress
3	The link is ready

0	Expression
4	List
6	Matrix
10	Data
11	Text
12	String
13	GDB variable
14	Geometry figure
16	Picture
17	Picture (???)
18	TI-Basic program
19	TI-Basic function
20	Geometry macro
21	In link protocol, cause execution of assembly block
25	Directory list (used recursively, unless VarType 26 follows)
26	List the folder table entries
27	List contents of a given folder (VarType 26 should follow)
28	Other (OTH) file
29	Backup file
31	Folder entry symbol in group files
32	Used for getting a certificate
33	ASM program
34	ID List
35	Product code (AMS)
36	FLASH application
37	Certificate