NAME
   AFormat -- Low level I/O routine

SYNOPSIS
   result = AFormat(User,data,putsub,fmt,argp)
                    A0   A1   A2     D0  A3
   LONG AFormat(struct USER_DATA *,void *,int (*putsub)(),char *,char *)

FUNCTION
   Does standard 'C'-style formatting.

INPUTS
   User   -- Optional USER_DATA structure (used for ansi color). NULL may be
             used if you are not using DLG ansi color switches.

   data   -- Data that gets passed through to putsub().

   putsub -- Function to be called to output a character.  This fuction takes
             two arguments -- the character to be output, and a pointer to the
             data being passed through.

   fmt    -- Format tring containing text and switches (see any printf()
             documentation for examples of the switches).

   argp   -- Pointer to a memory area (usually the stack) that contains the
             arguments to the formatting statements.  Note that all arguments
             must be long values.

RESULT
   The result is the number of characters output.

EXAMPLE

   void     MyPutStr(char *, char *);

   struct   USER_DATA   UserDat;
   char                *buffy;

   AFormat(&UserDat,buffy,MyPutStr,"This is a %s.","test");


NOTES
   Compatiable with most printf() format strings.  If the User structure
   is passed, the format string may include DLG %a and %b color codes.

   There is no floating point support nor is %x formatting supported.

   %hd should not be used and will cause invalid results, except when you are
   using SHORTs, in which case you MUST use %hd.

BUGS
   See above

SEE ALSO
   XAFPrintf(), XASPrintf(), AFPrintf(), ASPrintf()

NAME
   Capitalize -- Capitalize a string

SYNOPSIS
   Capitalize(string)
              A0
   void Capitalize(char *)

FUNCTION
   Capitalizes a string (makes the first character of each word a
   capital letter).

INPUTS
   string -- String to be capitalized.

RESULT
   none

EXAMPLE

   char t[] = "capitalize this"

   Capitalize(&t);

   // Should come out as "Capitalize This"

NOTES

BUGS

SEE ALSO
   Upper()

NAME

   CronEvent -- Send message to TPTCron

SYNOPSIS

   result = CronEvent(messtype,time,command)
                      D0       D1   A0
   LONG CronEvent(UBYTE,ULONG,char *)

FUNCTION
    Sends a message to TPTCron

INPUTS
   messtype -- One of the following values, as defined in cron.h:

               ADDEVENT    Add an event
               DELEVENT    Delete an event
               LISTEVENTS  List the dynamic event list
               CRONEXIT    Shut down TPTCron
               WHENEVENT   Query next occurrance of event
               READFILE    Read a crontab file
               TABLIST     List the permanent event list
               CHANGEDIR   Change TPTCron's current directory

   time     -- Time for event to be added (for ADDEVENT call), in minutes
               from current time.

   command  -- One of the following:

               o  Command to be added for ADDEVENT call.

               o  Command to be deleted (* and ? wildcards supported) for a
                  DELEVENT call.

               o  Command to be queried (* and ? wildcards supported) for a
                  WHENEVENT call.

               o  Crontab file to be read for a READFILE command.

               o  New directory for a CHANGEDIR call.

RESULT
   Most commands return the following errors, as defined in cron.h:

   CNOERR         Operation successful
   OUTOFMEM       Insufficient memory for requested operation
   BADSYNTAX      Invalid arguments
   NOCRON         TPTCron not currently active
   TABNOTFOUND    Crontab file not found (READFILE)
   NOEVENTS       No events to list (LISTEVENTS)
   DIRNOTFOUND    Directory not found (CHANGEDIR)

   The DELEVENT command returns the number of events deleted.
   The WHENEVENT command returns the number of minutes until the first match.

EXAMPLE

   // Use CronEvent to run a background task (0 min delay)

   rc = CronEvent(ADDEVENT, 0, "DLG:ResMan");

   // Empty out all occurences of a particular command

   while(CronEvent(DELEVENT, 0, command));

NOTES
   Using ADDEVENT with a time offset of 0 is a cheap way of firing off a task
   that will detach from your process completely. This has all the good points
   of using System() with NULL filehandles, and none of the bad points (i.e.
   CronEvent won't try to close your IO file handles on you).

BUGS

SEE ALSO
   WhenEvent()

NAME
   DeScore -- De-underscores a string

SYNOPSIS
   DeScore(string)
           A0
   void DeScore(char *)

FUNCTION
   Replaces all underscore characters '_' with spaces in a string.  Useful for
   converting a user's directory name into a username.

INPUTS
   string -- String to be descored.

RESULT
   none

EXAMPLE
   DeScore("John_Doe");

   // Result: "John Doe"

NOTES

BUGS

SEE ALSO
   UnderScore()

NAME
   MDate -- Make a timestamp and stores it in a string.

SYNOPSIS
   MDate(string)
         A0
   void MDate(char *)

FUNCTION
   Makes a string containing a timestamp of the current time.

INPUTS
   string -- Pointer to a buffer to place the timestamp in. The buffer must be
            at least 20 characters long (19 characters plus NULL-termination).

RESULT
   No return value.

   The resulting timestamp will be in the format "ddd dd mmm yy hh:mm", e.g.
   "Mon  3 May 93  1:22" for the 3rd of May, 1993, at 1:22.

EXAMPLE
   MDate(mytimestamp);

NOTES

BUGS

SEE ALSO
   SMDate(), AmigaTime(), UnpackTime()

NAME
   SendCtlMsg -- Low-level handler interface

SYNOPSIS
   result = SendCtlMsg(mod, aux_stat, port)
                       D0   D1        A0
   LONG SendCtlMsg(LONG, LONG, char *)

FUNCTION
   Provides a low-level interface to the handler.

INPUTS
   mod      -- Handler command (defined in devices/tpt.h):

               TDELSTAT       Unset flag(s)
               TADDSTAT       Set flag(s)
               TBAUD          Set baud rate
               TPOPWIND       Open a window
               TCLOSEWIND     Close a window
               TTIMEOUTDELAY  Change timeout delay
               TKILL          Kill port, shut down handler
                              for that port.
               TFREEZE        Leave port online, but disable
                              handler's text-handling functions
               TCONT          Restore handler's text-handling
                              functions
               TRECOVER       Reinitiate a killed port
               TPOPSCREEN     Open a screen
               TCLOSESCREEN   Close a screen
               TVERSION       Display version information
               TTITLE         Set screen's title
               TSTRING        Send text to handler as if
                              user had typed it
               TCOLORS        Set colors for screen
               TDEVQUERY      Get handler serial port info
               TWINHEIGHT     Set height of open window
               TGETSER        Get serial port I/O pointers
               TGETTITLE      Retrieve screen's title
               TINTRANS       Set up input translation table
               TOUTTRANS      Set up output translation table
               TCHECKCARRIER  Check carrier
               TSENDBREAK     Send a break character
               TBUFFER        Set buffer for port
               TANSIPOS       Turn on/off ANSI positioning (not
                              currently active)

   aux_stat -- Command argument

   port     -- Three-character port name

RESULT
   Error message as defined in devices/tpt.h:

      NOERR          Command executed without error
      GENERALERR     Undefined type of error
      ACTIVERR       Requested command can only be performed on an
                     active port; port is not active
      WINOPENERR     Error opening window
      WINCLOSEDERR   Error closing window
      SCROPENERR     Error opening screen
      SCRCLOSEDERR   Error closing screen
      FROZENERR      Requested command cannot be performed on a
                     frozen port. Port is frozen.

EXAMPLE
   error = SendCtlMsg(T_ECHO, NULL, "TL0");

NOTES
   Almost all commands are available as seperate library
   functions that handle the dirty work for you; as such,
   you should avoid using this function without (a) a darned
   good reason for it, and (b) full knowledge of what you are
   doing.

BUGS

SEE ALSO
   TSetFlags(), TUnSetFlags(), TBaud(), TColors(), TCont(), TDevQuery(),
   TFreeze(), TGetSer(), TGetTitle(), TKill(), TRecover(), TScreen(),
   TString(), TTimeDelay(), TTitle(), TWindow(), TWinHeight(), TInsTrans(),
   TOutTrans(), TCheckCarrier(), TSendBreak()

NAME
   Stricmp -- Case insensitive string compare

SYNOPSIS
   result = Stricmp(str1,str2)
                    A0   A1
   LONG Stricmp(char *,char *)

FUNCTION
   Does a case insensitive string comparison

INPUTS
    str1 -- First string.
    str2 -- Second string.

RESULT
   <0 if str1 is alphanumerically smaller than str2
    0 if str1 is identical to str2
   >0 if str1 is alphanumerically greater than str2

EXAMPLE

   if (Stricmp("THIS","this")) printf("Hmmm, they should be equal\n");

NOTES
   This code duplicates some code in utility.library. The prototypes are
   constructed so that there will be no conflicts.

   If you are using utility.library in your program, you MUST include
   proto/utility.h before proto/dlg.h or there will be a conflict.

   If utility.library is in use, the Stricmp() functions in utility.library will
   be used instead of the dlg.library routine.

BUGS
   See above; conflicts with utility.library. Expect it to disappear.

SEE ALSO
   Strnicmp(), utility.library/Stricmp()

NAME
   StripSpaces -- Removes leading and trailing spaces from a string

SYNOPSIS
   StripSpaces(string)
             A0
   void StripSpaces(char *)

FUNCTION
   Removes leading and trailing spaces from a string

INPUTS
   string -- string to be stripped

RESULT
   none

EXAMPLE
   char t[] = " A little spacey   ";

   StripSpaces(&t);

   // Result: "A little spacey"

NOTES

BUGS

SEE ALSO

NAME
   Strnicmp -- Case insensitive, length-limited string compare

SYNOPSIS
   result = Strincmp(str1,str2,len)
                    A0   A1    D0
   LONG Stricmp(char *,char *,USHORT)

FUNCTION
   Does a case insensitive string comparison for a limited length.

INPUTS
   str1 -- First string.
   str2 -- Second string.
   len  -- Maximum length to check

RESULT
   <0 if str1 is alphanumerically smaller than str2
    0 if str1 is identical to str2
   >0 if str1 is alphanumerically greater than str2

EXAMPLE

   if (Strnicmp("THIS","this", 3)) printf("Hmmm, they should be equal\n");

NOTES
   The comparison is only made for "len" characters, or the shorter length of
   the two strings, whichever is shortest.

   This code duplicates some code in utility.library. The prototypes are
   constructed so that there will be no conflicts.

   If you are using utility.library in your program, you MUST include
   proto/utility.h before proto/dlg.h or there will be a conflict.

   If utility.library is in use, the Strnicmp() functions in utility.library
   will be used instead of the dlg.library routine.

BUGS
   See above; conflicts with utility.library. Expect it to disappear.

SEE ALSO
   Stricmp(), utility.library/Strnicmp()

NAME
   TBaud -- Set the baud rate for a port

SYNOPSIS
   result = TBaud(baud,port)
                  D0   A0
   LONG TBaud(LONG,char *)

FUNCTION
   Sets the baud rate for a port.

INPUTS
   baud -- Baud rate.

   port -- Port.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE

    error = TBaud(19200,"TR0");

NOTES

BUGS

SEE ALSO
   SendCtlMsg()

NAME
   TCheckCarrier -- Checks for the presence of a carrier

SYNOPSIS
   result = TCheckCarrier(port)
                          A0
   LONG TCheckCarrier(char *)

FUNCTION
   Checks for the presence of carrier. If carrier is not present, the port is
   shut down as if TKill() was executed.

INPUTS
   port -- the port to check.

RESULT
   FALSE (0) if no carrier is detected.
   TRUE  (1) if carrier is still present.

EXAMPLE
   if(!TCheckCarrier("TR0")) printf("Carrier lost!\n");

NOTES

BUGS

SEE ALSO
   SendCtlMsg(), TKill()

NAME
   TColors -- Change the colors for a port

SYNOPSIS
   result = TColors(colortable,port)
                    A0         A1
   LONG TColors(USHORT *,char *)

FUNCTION
   Changes the colors for a port.

INPUTS
   colortable -- Color table suitable for passing to the graphics.library
                 LoadRGB4() routine.

   port       -- Port.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE
   error = TColors(colors,"TR0");

NOTES

BUGS

SEE ALSO
   SendCtlMsg(), graphics.library/LoadRGB4()

NAME
   TCont -- UnFreeze a port

SYNOPSIS
   result = TCont(port)
                  A0
   LONG TCont(char *)

FUNCTION
   UnFreezes a port frozen with TFreeze().

INPUTS
   port -- Port.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE

   TCont("TR0");

NOTES

BUGS

SEE ALSO
    SendCtlMsg(), TFreeze()

NAME
   TDevQuery -- Get information about a port

SYNOPSIS
   result = TDevQuery(devstruct,port)
                      A0        A1
   LONG TDevQuery(struct tdev_info *,char *)

FUNCTION
   Gets information about a port.

INPUTS
   devstruct -- tdev_info structure.  The format of this structure is
                as follows:

                  char devname[21]   --   Name of serial device being used.

                  unsigned char unit --   Unit number of serial device being
                                          used.

                  long serflags      --   Serial flags being used.

   port      -- Port to query.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE

    struct tdev_info ds;

    error = TDevQuery(&ds,"TR0");

NOTES

BUGS

SEE ALSO
   SendCtlMsg()

NAME
   TFreeze -- Cause port to suspend all I/O

SYNOPSIS
   result = TFreeze(port)
                    A0
   LONG TFreeze(char *)

FUNCTION
   Causes port to suspend all I/O.

INPUTS
   port -- Port to freeze.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE
   TFreeze("TR0");

NOTES
   Freezing a port removes the handler from the serial I/O stream
   and allows the program that initiated the freeze to have
   unfettered, unfiltered access to the data stream on the serial
   port. This is MANDATORY for any program that wants to transfer
   binary files, for example -- the file upload and download routines
   use this function in order to ensure that files are transferred
   without being corrupted. If the handler is in the stream, it will
   attempt to 'interpret' the data stream with undesireable effects.

BUGS

SEE ALSO
   SendCtlMsg(), TCont()

NAME
   TGetSer -- Get serial port I/O handles for direct access

SYNOPSIS
   result = TGetSer(serstruct,port)
                    A0        A1
   LONG TGetSer(struct TPTSerStuff *,char *)

FUNCTION
   Gets pointers to the serial port's I/O data streams; presumably,
   you have a use for that information.

INPUTS
   serstruct --   TPTSerStuff structure to be filled in.  This structure has
                  the following format:

                  struct  IOExtSer *read  -- IOMessage for reading.

                  struct  IOExtSer *write -- IOMessage for writing.

   port      --   Port of interest.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE

   struct TPTSerStuff ss;

   error = TGetSer(&ss,"TR0");

NOTES
   This is primarilly of interest to someone that is writing directly to and
   reading directly from the serial port -- usually that means binary file
   transfers, but could be something else as well. Before you can read and
   write directly, you need to get the handler out of the way using TFreeze(),
   but be sure to fill in your TPTSerStuff structure first, otherwise you will
   get an error (ACTIVEERR). Once you have gotten your pointers, freeze the
   port, do your thing, and then unfreeze the port.

BUGS

SEE ALSO
   SendCtlMsg(), TCont(), TFreeze()

NAME
   TGetTitle -- Get the screen/window title for a port

SYNOPSIS
   result = TGetTitle(title,port)
                      A0    A1
   LONG TGetTitle(char *,char *)

FUNCTION
   Gets the screen/window title for a port.

INPUTS
   title -- Character array in which to place contents of screen title

   port  -- Port of interest.

RESULT
    0 if successful (plus string will be safely copied)
    negative if an error occurred

EXAMPLE

   char t[256];

   error = TGetTitle( t, "TR0");

NOTES

BUGS

SEE ALSO
   SendCtlMsg(), TTitle()

NAME
   TInTrans -- Set the input translation table for a port

SYNOPSIS
   result = TInTrans(trans,port)
                     A0    A1
   LONG TInTrans(char *,char *)

FUNCTION
   Sets the input translation table for a port.

INPUTS
   trans -- Array of 256 characters.  Input character x will be mapped to
            trans[x].

   port  -- Port.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE
   error = TInTrans(trans,"TR0");

NOTES

BUGS

SEE ALSO
   SendCtlMsg(), TOutTrans()

NAME
   TKill -- Kill a port

SYNOPSIS
   result = TKill(port)
                  A0
   LONG TKill(char *)

FUNCTION
   Kills a port.  If a user is online, s/he will be logged off and
   carrier will be dropped. No warnings.

INPUTS
   port -- Port to kill.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE
   error = TKill("TR0");

NOTES
   A killed port must be recovered before you can use it again.

BUGS

SEE ALSO
   SendCtlMsg(), TRecover()

NAME
   TOutTrans -- Set the output translation table for a port

SYNOPSIS
   result = TOutTrans(trans,port)
                      A0    A1
   LONG TOutTrans(char *,char *)

FUNCTION
   Sets the output translation table for a port.

INPUTS
   trans -- Array of 256 characters.  Character x will be output is
            trans[x].

   port  -- Port.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE
   error = TOutTrans(trans,"TR0");

NOTES

BUGS

SEE ALSO
   TInTrans()

NAME
   TRecover -- Recover a killed port

SYNOPSIS
   result = TRecover(port)
                     A0
   LONG TRecover(char *)

FUNCTION
   Recovers a killed port if for some reason it couldn't shut down
   properly

INPUTS
   port -- Port to recover.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE
   error = TRecover("TR0");

NOTES
   While a port may be killed using TKill(), it will still be
   listed as active by the resource manager, so you can't get it
   back just by activating it. This function exists for such
   instances.

BUGS

SEE ALSO
   SendCtlMsg(), TKill()

NAME
   TScreen -- Open/close a screen for a port

SYNOPSIS
   result = TScreen(onoff,scrstruct,port)
                    D0    A0        A1
   LONG TScreen(LONG,struct ScrStruct *,char *)

FUNCTION
   Opens/Closes a screen for a port.

INPUTS
   onoff
      0 to close, 1 to open

   scrstruct
      ScrStruct structure.  This structure (defined in portconfig.h) is
      formatted as follows:

      short width, height, depth -- Width, height, and depth of the screen.

      UBYTE hires                -- 1 for hires, 0 for lores.

      UBYTE interlace            -- 1 for interlaced, 0 for non-interlaced.

      char fontname[41]          -- Name of font to be used (case sensitive and
                                    must include ".font").

      UBYTE fontsize             -- Point size of font.

      UBYTE flags                -- One or more flags:

                                    DISP_BKGRND    The screen should pop up
                                                   behind all other screens.

      UWORD colortable[8]        -- Color table suitable for passing to the
                                    graphics.library function LoadRGB4().

    port
      Port to open screen for.

RESULT
    0 if successful
    negative if an error occurred

EXAMPLE

   // assume you've already set up some stuff

   struct ScrStruct scr;

   scr.width = width;   // You get this stuff from a port display config file
   scr.height= height;
   scr.depth = depth;
   scr.hires = 1;
   scr.interlace = 0;
   scr.font = "topaz.font"
   scr.fontsize = 8;
   scr.flags = DISP_BKGRND;
   scr.colortable = myColors;

   error = TScreen(1,&scr,"TR0");

NOTES
   Don't forget that you can easily load up your ScrStruct from a port config
   file.

BUGS

SEE ALSO
   SendCtlMsg(), TWindow(), graphics.library/LoadRGB4()

NAME
   TSendBreak -- Send a break to the serial device.

SYNOPSIS
   result = TSendBreak(port)
                       A0
   LONG TSendBreak(char *)

FUNCTION
   Clears pending writes to the port, then sends a SDCMD_BREAK command to the
   serial device.

INPUTS
   port -- the port to break.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE

   ret = TSendBreak("TR0");

NOTES

BUGS

SEE ALSO
   SendCtlMsg()

NAME
   TSetFlags -- Set handler flags

SYNOPSIS
   result = TSetFlags(flags,port)
                      D0    A0
   LONG TSetFlags(ULONG,char *)

FUNCTION
   Sets various handler flags.

  INPUTS
   flags -- As follows:

      T_ECHO            Enable echoing of characters.
      T_CRLF            Enable CR/LF conversion.
      T_RAW             Enable RAW moded.
     *T_RPEND           Read pending.
     *T_WAIT_FOR        Wait for input.
     *T_TYPEAHEAD_FULL  TypeAhead full.
      T_BREAK           Pass through user-typed ^C signals.
     *T_WINDOW          Window is opened.
      T_KILL_ENABLE     Allow handler to send ^C kill signals.
      T_DO_PEND         Keep track of pending kills.
     *T_KILL_PEND       Control-C sent.
     *T_SER_TIMEOUT     Serial Timeout.
      T_DO_TIMEOUT      Enable inactivity timeouts.
      T_CTLD            Pass ^D characters through.
      T_PAUSE           Enable ^S^Q pausing.
     *T_PAUSED          Port Paused.
     *T_KILLED          Port Killed.
     *T_SCREEN          Screen is opened.
      T_PASS_THRU       Enable 'passthru' mode.
      T_VERB_PAUSE      Display verbose "[PAUSED]" message.
     *T_CWRITE_PEND     Console write pend.
      T_LINEFREEZE      Freeze output when user starts typing in line
                        mode.
     *T_FROZEN          Port Frozen.
     *T_WRITE_PEND      Serial write pend.

   port -- Port.

RESULT
   new handler flags.

EXAMPLE

   // Enable echoing of typed characters and RAW console mode
   flags = TSetFlags(T_ECHO | T_RAW,"TR0");

NOTES
   Flags marked with an asterisk (*) are ONLY to be set internally by
   the handler! You are given access to these flags as it may be important
   for you to know what the handler is doing, but do not mess with the
   internal flags or unexpected things may (well, probably will) happen.

   In order to get the current flag settings do:

       flags = TSetFlags(0, port);

   the flags returned will be the current flags.

BUGS

SEE ALSO
   SendCtlMsg(), TUnSetFlags()

NAME
   TString -- Pretend a user typed a string

SYNOPSIS
   result = TString(string,port)
                    A0     A1
   LONG TString(char *,char *)

FUNCTION
   Take a string as if it was typed as input by a user on a port.

INPUTS
   string -- String.

   port   -- Port.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE
   error = TString("This line would be six words long...","TR0");

NOTES

BUGS

SEE ALSO
   SendCtlMsg()

NAME
   TTimeDelay -- Set the timeout delay for a port

SYNOPSIS
   result = TTimeDelay(delay,port)
                       D0    A0
   LONG TTimeDelay(LONG,char *)

FUNCTION
   Sets the timeout delay for a port.

INPUTS
   delay -- Timeout delay (in 5-second intervals).

   port  -- Port to effect.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE
   error = TTimeDelay(10,"TR0");

NOTES

BUGS

SEE ALSO
   SendCtlMsg()

NAME
   TTitle -- Change the screen/window title for a port

SYNOPSIS
   result = TTitle(title,port)
                   A0    A1
   LONG TTitle(char *,char *)

FUNCTION
   Changes the screen/window title for a port.

INPUTS
   title -- New title.

   port  -- Port.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE
   error = TTitle("New title","TR0");

NOTES

BUGS

SEE ALSO
   SendCtlMsg(), TGetTitle()

NAME
   TUnSetFlags -- Clear (unset) handler flags for a port

SYNOPSIS
   result = TUnSetFlags(flags,port)
                        D0    A0
   LONG TUnSetFlags(ULONG,char *)

FUNCTION
   Unsets various handler flags for a port.

INPUTS
   flags -- See TSetFlags().

   port  -- Port.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE
   TUnSetFlags(T_ECHO|T_RAW,"TR0");

NOTES

BUGS

SEE ALSO
   SendCtlMsg(), TSetFlags()

NAME
   TWindow -- Open/close a window on a port

SYNOPSIS
   result = TWindow(onoff,winstruct,port)
                    D0    A0        A1
   LONG TWindow(LONG,struct WinStruct *,char *)

FUNCTION
   Opens/closes a window on a port.

INPUTS
   onoff
      0 to close, 1 to open.

   winstruct

      WinStruct structure.  The format of this structure (defined in
      portconfig.h) is as follows:

         short x, y           -- x and y position of upper left corner of
                                 window.

         short width, height  -- Width and height of window.

         char fontname[41]    -- Name of font to be used (case sensitive and
                                 must include ".font").

         UBYTE fontsize       -- Point size of font.

         UBYTE flags          -- One or more flags:

                                 DISP_BKGRND    The window should pop up behind
                                                all other windows.


   port
      Port to effect.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE
   // assume you've already set up some stuff

   struct WinStruct ws;

   ws.x = xpos;   // You get this stuff from a port display config file
   ws.y = ypos;
   ws.width = width;
   ws.height= height;
   ws.fontname = "topaz.font"
   ws.fontsize = 8;
   ws.flags = (ws.flags | DISP_BKGRND);

   error = TWindow(1,&ws,"TR0");

NOTES
   Don't forget that you can easily load up your WinStruct from a port config
   file.

BUGS

SEE ALSO
   SendCtlMsg(), TScreen(), TWinHeight()

NAME
   TWinHeight -- Change the height of the window on a port

SYNOPSIS
   result = TWinHeight(height,port)
                       A0     A1
   LONG TWinHeight(char *,char *)

FUNCTION
   Changes the height of the window on a port.

INPUTS
   height -- New height of window.

   port   -- Port window is supposed to be attached to.

RESULT
   0 if successful
   negative if an error occurred

EXAMPLE

NOTES

BUGS

SEE ALSO
   SendCtlMsg(), TWindow()

NAME
   UnderScore -- Underscore a string

SYNOPSIS
   UnderScore(string)
              A0
   void UnderScore(char *)

FUNCTION
   Replaces spaces with underscores '_' in a string.  Useful when converting
   a username to a user's directory name.

INPUTS
   string -- String to be underscored.

RESULT
   none

EXAMPLE
    UnderScore("John Doe");

    // Result: "John_Doe"

NOTES

BUGS

SEE ALSO
   DeScore()

NAME
   Upper -- Convert a string to uppercase

SYNOPSIS
   Upper(string)
         A0
   void Upper(char *)

FUNCTION
   Converts a string to uppercase.

INPUTS
   string -- String to be converted

RESULT
   none

EXAMPLE

   char t[] = "This is a Test";

   Upper(&t);

NOTES

BUGS

SEE ALSO
   Capitalize()

NAME
   WhenEvent -- Check when an event will next happen

SYNOPSIS
   result = WhenEvent(string)
                      A0
   LONG WhenEvent(char *)

FUNCTION
   Checks when a TPTCron event will next happen.

INPUTS
   string -- Pattern to search for ('*' and '?' wildcards supported).

RESULT
    Number of seconds until event will occur.

    -1 if operation failed or event does not exist.

EXAMPLE

    secs = WhenEvent("*UU*");

    if(secs==-1)
      printf("WhenEvent failed\n");
    else
      printf("The next UUCP event will occur in %d seconds\n",secs);

NOTES
   This is similar to using CronEvent with the WHENEVENT flag, but
   CronEvent returns minutes, where WhenEvent() returns seconds.

BUGS

SEE ALSO
   CronEvent()

NAME
   XAFPrintf -- Put formatted output to a file

SYNOPSIS
    result = XAFPrintf(User,fh,fmt,argptr)
                       A0   A1 A2  A3
    LONG XAFPrintf(struct USER_DATA *,BPTR,char *,void *)

FUNCTION
   Does standard 'C'-stype formatting to a file.

INPUTS
   User   -- Optional USER_DATA structure (used for ansi color). May be set to
             NULL.

   fh     -- Open, writeable file handle opened with e.g. Open() or Output().

   fmt    -- Format tring containing text and switches (see any printf()
             documentation for examples of the switches).

   argptr -- Pointer to a memory area (usually the stack) that contains
             the arguments to the formatting statements.  Note that all
             arguments must be long values.

RESULT
   The result is the number of characters output.

EXAMPLE

   BPTR  fh;
   BPTR  sout;

   char  t[] = "test";

   struct USER_DATA  UserDat;

   // Output to a file

   if(fh = Open("Ram:Test.file",MODE_NEWFILE))
   {
      XAFPrintf(&UserDat,fh,"This is a %s.",(LONG *)t);
      Close(fh);
   }

   // Output to the console
   if(sout = Output())
   {
      XAFPrintf(&UserDat,sout,"This is a %s.",(LONG *)t);
      Close(fh);
   }

   // Also output to the console
   XAFPrintf(&UserDat,Output(),"This is a %s.",(LONG *)t);


NOTES
   Compatiable with most printf() format strings.  If the User structure
   is passed, the format string may include DLG %a and %b color codes.

   There is no floating point support nor is %x formatting supported.

   %hd should not be used and will cause invalid results, except when you are
   using SHORTs, in which case you MUST use %hd.

   io.lib contains the wrap-around function AFPrintf(), which converts all args
   to LONGs for you. Using IO.lib/AFPrintf() is the preferred method of
   accessing this routine.

BUGS
   See above.

  SEE ALSO
    AFormat(), XASPrintf(), IO.lib/AFPrintf()

NAME
   XASPrintf -- Put formatted output in a string

SYNOPSIS
   result = XASPrintf(User,buf,fmt,argptr)
                      A0   A1  A2  A3
   LONG XASPrintf(struct USER_DATA *,char *,char *,void *)

FUNCTION
   Does standard 'C'-stype formatting to a string.

INPUTS
   User   -- Optional USER_DATA structure (used for ansi color). May be set to
             NULL.

   buf    -- Buffer to send output to.

   fmt    -- Format tring containing text and switches (see any printf()
             documentation for examples of the switches).

   argptr -- Pointer to a memory area (usually the stack) that contains
             the arguments to the formatting statements.  Note that all
             arguments must be long values.

RESULT
   The result is the number of characters output.

EXAMPLE

   char  dest[256];
   char  t[] = "test";

   struct USER_DATA  UserDat;


   XASPrintf(&UserDat,dest,"This is a %s.",(LONG *)t);

NOTES
   Compatiable with most printf() format strings.  If the User structure
   is passed, the format string may include DLG %a and %b color codes.

   There is no floating point support nor is %x formatting supported.

   %hd should not be used and will cause invalid results, except when you are
   using SHORTs, in which case you MUST use %hd.

   io.lib contains the wrap-around function ASPrintf(), which converts all args
   to LONGs for you. Using IO.lib/ASPrintf() is the preferred method of
   accessing this routine.

BUGS
   See above.

  SEE ALSO
    AFormat(), XAFPrintf(), IO.lib/ASPrintf()