Calc/calc and calc/computer link interface routines
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).
| 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.
See also: sendcalc, cmd_getcalc
| 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).
| 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.
| 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).
| 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.
| 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).
| 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).
| 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).
| 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 |
| 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.
| 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 can not receive variables if it is not in a "normal receiving state").
| 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
| 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
| 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).
| 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
| 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
See also: LIO_RecvData
| 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
See also: LIO_SendData
| 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
typedef struct {
|
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 |