args.h

The <args.h> Header File

Routines for retrieving arguments passed to the program

Functions

ArgCount: Returns the number of arguments passed to the program.
EX_getArg: Returns a pointer to the nth argument.
EX_getBCD: Gets the nth floating point argument.
GetArgType: Returns the type of the current argument.
GetFloatArg: Returns the current argument of floating point type.
GetIntArg: Returns the current argument of integer type.
GetLongLongArg: Returns the current argument of double-long integer type.
GetStrnArg: Returns the current argument of string type.
GetSymstrArg: Returns a pointer to the terminating zero byte of the current argument of string type.
InitArgPtr: Initializes a pointer to the first argument passed to the program.
RemainingArgCnt: Returns the remaining number of arguments passed to the program.
SkipArg: Skips the current argument.

Global Variables

top_estack: Points to the top of the expression stack.

Constants

NULL: A null-pointer value.

Predefined Types

bcd: Represents the internal organization of floating point numbers in the format recognized by the TIOS.
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.
EStackIndex: Represents an index of a value on the TIOS expression stack.
Quantum: Represents a quantum within an expression.
SYM_STR: Represents a pointer to the terminating zero byte of a string.
Tags: An enumeration to describe types of entries on the expression stack.
ti_float: An alias for the standard ANSI float type.

Note: The header file estack.h contains a much more powerful set of functions to manipulate the expression stack.

ArgCount

unsigned short ArgCount (void);

Returns the number of arguments passed to the program.

ArgCount returns the number of arguments passed to the called program. It is a simple macro which calls TIOS function RemainingArgCnt.

EX_getArg

ESI EX_getArg (short n);

Returns a pointer to the nth argument.

EX_getArg is TIOS function which may be useful if you want to access arguments in non_sequential order. EX_getArg returns a pointer to the argument which ordinal number is n (which may be later processed using GetIntArg etc.). Arguments are numbered from zero (i.e. 0, 1, 2, ... N-1 where N is the total number of arguments). Note that when n = N, EX_getArg returns NULL, and when n > N, EX_getArg throws an error, so it is good idea to check in advance the total number of arguments using ArgCount.

EX_getBCD

short EX_getBCD (short n, float *dest);

Gets the nth floating point argument.

EX_getBCD is a somewhat limited TIOS function. It first calls EX_getArg passing n to it. Then, if the argument pointed to by the result of EX_getArg is not a floating point number, EX_getBCD returns FALSE, otherwise it stores the floating point value to the variable pointed to by dest and returns TRUE.

GetArgType

unsigned char GetArgType (CESI ap);

Returns the type of the current argument.

GetArgType returns a one-byte value which determines the type of the current argument (pointed to by ap). There are many types of arguments: strings, integers (positive or negative), fractions, floats, symbols, various algebraic expressions, lists, matrices, etc. The enum Tags defines a lot of constants: the most commonly used in argument lists are STR_TAG, POSINT_TAG, NEGINT_TAG, FLOAT_TAG, POSFRAC_TAG, ENDFRAC_TAG, COMPLEX_TAG, LIST_TAG and END_TAG. They represent respectively a string, a positive integer, a negative integer, a floating point value, a positive fraction, a negative fraction, a complex number, a beginning of the list structure and an end-of-list marker (which also has meaning "no more arguments"). Any values except these need to be regarded as "an expression": you need to handle them "by hand" (of course, if you know how). See InitArgPtr for an example of usage.

Note: You can use SkipArg to bypass the argument which you don't know how to handle (or, which you don't want to handle for any reason).

GetFloatArg

float GetFloatArg (CESI &ap);

Returns the current argument of floating point type.

GetFloatArg is a macro which returns the current floating point argument (pointed to by ap) and modifies ap to point to the next argument in the argument list. So, each successive time GetFloatArg is used, it returns the next argument in the argument list. Note that GetFloatArg assumes that the current argument is a floating point value (not an integer). This may be checked using GetArgType. If this is not true, the result of GetFloatArg is unpredictable.

GetIntArg

unsigned long GetIntArg (CESI &ap);

Returns the current argument of integer type.

GetIntArg is a macro which returns the current integer argument (pointed to by ap) and modifies ap to point to the next argument in the argument list. So, each successive time GetIntArg is used, it returns the next argument in the argument list. If the argument is a negative number (check the sign using GetArgType), GetIntArg returns its absolute value. See InitArgPtr for an example of usage. Note that GetIntArg assumes that the current argument IS an integer, either positive or negative (this may be checked using GetArgType). If this is not true, the result of GetIntArg is unpredictable.

If the current argument type is a fraction, do the following to pick it:

numerator = GetIntArg (ap);
ap++;
denominator = GetIntArg (ap);

i.e. pick two integers, with increasing argument pointer between two picks.

Note: It is not recommended to do something like

a = GetIntArg (top_estack);

It works fine sometimes, but not always. GetIntArg is a function-looking macro, with changes the value of its actual argument. So, if you write the statement mentioned above, you will also change the value of TIOS system variable top_estack, which is not always a good idea. So, I strictly recommend using an auxiliary variable, like in the following example:

ESI argptr = top_estack;
...
a = GetIntArg (argptr);

Using this method, you will avoid unexpected changes of top_estack.

GetLongLongArg

unsigned long long GetLongLongArg (CESI &ap);

Returns the current argument of double-long integer type.

GetLongLongArg works like GetIntArg, but returns a double-long integer.

GetStrnArg

const char *GetStrnArg (CESI &ap);

Returns the current argument of string type.

GetStrnArg is a macro which returns the current string argument (pointed to by ap) and modifies ap to point to the next argument in the argument list. So, each successive time GetStrnArg is used, it returns the next argument in the argument list. See InitArgPtr for an example of usage. Note that GetStrnArg assumes that the current argument IS a string (this may be checked using GetArgType). If this is not true, the effect of GetStrnArg is unpredictable.

GetSymstrArg

SYM_STR GetSymstrArg (CESI &ap);

Returns a pointer to the terminating zero byte of the current argument of string type.

GetSymstrArg does the same task as GetStrnArg but returns a pointer to the terminating zero byte of the string, instead of a pointer to the first byte of the string. This function is implemented because nearly all functions for TIOS VAT handling need just the pointer to the terminating byte of the string. As the arguments are stored in memory as strings which are bounded with zero bytes from both sides, the result of GetSymstrArg may be directly passed to TIOS VAT routines. See vat.h for more info.

InitArgPtr

void InitArgPtr (CESI &ap);

Initializes a pointer to the first argument passed to the program.

InitArgPtr is a macro which initializes ap (which is a pointer of type ESI) to point to the first argument passed to the assembly program. Principally, calling

InitArgPtr (argptr);

is equal to doing

argptr = top_estack;

See top_estack for more info.

InitArgPtr must be used before the first call to GetStrnArg etc. Here is an example of a program which reads string or integer arguments passed to it, and displays them on the screen, one by one (called "Argument Test"):

// An example of passing arguments to C program
// Try this program calling argtest(arg1,arg2,...)

#define USE_TI89
#define USE_TI92PLUS
#define USE_V200

#define MIN_AMS 100

#include <graph.h>
#include <printf.h>
#include <kbd.h>
#include <args.h>

void _main(void)
{
  ESI argptr;
  int argtype;
  long num;
  InitArgPtr (argptr);
  while ((argtype = GetArgType (argptr)) != END_TAG)
    {
      DrawStr (0, 30, "                          ", A_REPLACE);
      if (argtype == STR_TAG)
        DrawStr (0, 30, GetStrnArg (argptr), A_REPLACE);
      else if (argtype == POSINT_TAG || argtype == NEGINT_TAG)
        {
          num = GetIntArg (argptr);
          if (argtype == NEGINT_TAG)
            num = -num;
          printf_xy (0, 30, "%ld", num);
        }
      else
        {
          DrawStr (0, 30, "Wrong arg type!", A_REPLACE);
          ngetchx ();
          break;
        }
      ngetchx ();
    }
}

If the name of this program is example.89z, try to call it on the calculator using

example ("strarg1", 123, -12, "strarg2")

to see how it works in practice.

Note: I used notation "&ap" in the prototype description, although passing by reference does not exist in ordinary C (only in C++). However, this macro is implemented in such a way that it simulates "passing by reference".

RemainingArgCnt

AMS 1.01 or higher

unsigned short RemainingArgCnt (CESI ap);

Returns the remaining number of arguments passed to the program.

RemainingArgCnt returns the number of remaining arguments passed to the called program, i.e. the number of arguments which are not yet picked up. It is a simple alias for the TIOS function remaining_element_count.

SkipArg

void SkipArg (CESI &ap);

Skips the current argument.

SkipArg is a macro which modifies ap to point to the next argument in the argument list, regardless of its type. Note that this function must not be called if GetArgType returns END_TAG, i.e. if there is no more arguments. Else, an error will be thrown.

Note: SkipArg is implemented by calling TIOS function next_expression_index.