TABLE OF CONTENTS
dlg/AFormat()
dlg/Capitalize()
dlg/CronEvent()
dlg/DeScore()
dlg/MDate()
dlg/SendCtlMsg()
dlg/Stricmp()
dlg/StripSpaces()
dlg/Strnicmp()
dlg/TBaud()
dlg/TCheckCarrier()
dlg/TColors()
dlg/TCont()
dlg/TDevQuery()
dlg/TFreeze()
dlg/TGetSer()
dlg/TGetTitle()
dlg/TInTrans()
dlg/TKill()
dlg/TOutTrans()
dlg/TRecover()
dlg/TScreen()
dlg/TSendBreak()
dlg/TSetFlags()
dlg/TString()
dlg/TTimeDelay()
dlg/TTitle()
dlg/TUnSetFlags()
dlg/TWindow()
dlg/TWinHeight()
dlg/UnderScore()
dlg/Upper()
dlg/WhenEvent()
dlg/XAFPrintf()
dlg/XASPrintf()

top dlg/AFormat()

    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()

top dlg/Capitalize()

    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()

top dlg/CronEvent()

    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()

top dlg/DeScore()

    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()

top dlg/MDate()

    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()

top dlg/SendCtlMsg()

    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()

top dlg/Stricmp()

    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()

top dlg/StripSpaces()

    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

top dlg/Strnicmp()

    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()

top dlg/TBaud()

    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()

top dlg/TCheckCarrier()

    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()

top dlg/TColors()

    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()

top dlg/TCont()

    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()

top dlg/TDevQuery()

    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()

top dlg/TFreeze()

    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()

top dlg/TGetSer()

    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()

top dlg/TGetTitle()

    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()

top dlg/TInTrans()

    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()

top dlg/TKill()

    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()

top dlg/TOutTrans()

    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()

top dlg/TRecover()

    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()

top dlg/TScreen()

    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()

top dlg/TSendBreak()

    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()

top dlg/TSetFlags()

    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()

top dlg/TString()

    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()

top dlg/TTimeDelay()

    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()

top dlg/TTitle()

    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()

top dlg/TUnSetFlags()

    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()

top dlg/TWindow()

    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()

top dlg/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()

top dlg/UnderScore()

    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()

top dlg/Upper()

    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()

top dlg/WhenEvent()

    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()

top dlg/XAFPrintf()

    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()

top dlg/XASPrintf()

    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()