home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / FileMover / HF-OM1.DMS / in.adf / OpusSDK.lha / SDK / docs / dos.doc < prev    next >
Encoding:
Text File  |  1997-05-11  |  16.9 KB  |  487 lines
  1. dopus5.library/DateFromStrings                 dopus5.library/DateFromStrings
  2.  
  3.     NAME
  4.         DateFromStrings - convert date and time strings to a datestamp
  5.  
  6.     SYNOPSIS
  7.         DateFromStrings(date, time, ds)
  8.                          A0    A1   A2
  9.  
  10.         BOOL DateFromStrings(char *, char *, struct DateStamp *);
  11.  
  12.     FUNCTION
  13.         This routine takes a date string and a time string and converts them
  14.         to a DOS DateStamp. The DOS StrToDate() routine is used to perform
  15.         this conversion, so it is sensitive to the current locale. If the
  16.         time string contains an 'a' or a 'p' to signify am or pm, it
  17.         is automatically converted to 24 hour time for the DOS call.
  18.  
  19.     INPUTS
  20.         date - date string to convert
  21.         time - time string to convert
  22.         ds - DateStamp to store result
  23.  
  24.     RESULT
  25.         Returns TRUE if successful.
  26.  
  27.     NOTES
  28.         This routine expects the date string in the FORMAT_DOS format
  29.         (dd-mmm-yy). DateFromStringsNew() offers more control.
  30.  
  31.     SEE ALSO
  32.         ParseDateStrings(), DateFromStringsNew(), dos.library/StrToDate()
  33.  
  34. dopus5.library/DateFromStringsNew           dopus5.library/DateFromStringsNew
  35.  
  36.     NAME
  37.         DateFromStringsNew - convert date and time strings to a datestamp
  38.  
  39.     SYNOPSIS
  40.         DateFromStringsNew(date, time, ds, method)
  41.                             A0    A1   A2    D0
  42.  
  43.         BOOL DateFromStrings(char *, char *, struct DateStamp *, ULONG);
  44.  
  45.     FUNCTION
  46.         This routine takes a date string and a time string and converts them
  47.         to a DOS DateStamp. The DOS StrToDate() routine is used to perform
  48.         this conversion, so it is sensitive to the current locale. If the
  49.         time string contains an 'a' or a 'p' to signify am or pm, it
  50.         is automatically converted to 24 hour time for the DOS call.
  51.  
  52.     INPUTS
  53.         date - date string to convert
  54.         time - time string to convert
  55.         ds - DateStamp to store result
  56.         method - date string format (eg FORMAT_DOS, FORMAT_CDN, etc)
  57.  
  58.     RESULT
  59.         Returns TRUE if successful.
  60.  
  61.     SEE ALSO
  62.         ParseDateStrings(), dos.library/StrToDate()
  63.  
  64. dopus5.library/DeviceFromHandler             dopus5.library/DeviceFromHandler
  65.  
  66.     NAME
  67.         DeviceFromHandler - returns device name from handler
  68.  
  69.     SYNOPSIS
  70.         DeviceFromHandler(handler, buffer)
  71.                             A0       A1
  72.  
  73.         struct DosList *DeviceFromHandler(struct MsgPort *, char *);
  74.  
  75.     FUNCTION
  76.         This function takes a pointer to a filesystem's handler
  77.         (message port) and returns the associated device name.
  78.  
  79.     INPUTS
  80.         handler - pointer to handler message port
  81.         buffer - buffer to store device name (must be >=34 bytes)
  82.  
  83.     RESULT
  84.         If the port supplied is a valid filesystem handler, the
  85.         name of the device is stored in the supplied buffer, and
  86.         a pointer to the DosList entry for that device is returned.
  87.  
  88.     SEE ALSO
  89.         DeviceFromLock(), DevNameFromLock()
  90.  
  91. dopus5.library/DeviceFromLock                   dopus5.library/DeviceFromLock
  92.     NAME
  93.         DeviceFromLock - returns device name from a filelock
  94.  
  95.     SYNOPSIS
  96.         DeviceFromLock(lock, buffer)
  97.                         A0     A1
  98.  
  99.         struct DosList *DeviceFromLock(BPTR, char *);
  100.  
  101.     FUNCTION
  102.         This function takes a filelock and returns the name of the
  103.         device that lock resides on.
  104.  
  105.     INPUTS
  106.         lock - pointer to lock
  107.         buffer - buffer to store device name (must be >=34 bytes)
  108.  
  109.     RESULT
  110.         The name of the device is stored in the supplied buffer, and
  111.         a pointer to the DosList entry for that device is returned.
  112.  
  113.     SEE ALSO
  114.         DeviceFromHandler(), DevNameFromLock()
  115.  
  116. dopus5.library/DevNameFromLock                 dopus5.library/DevNameFromLock
  117.  
  118.     NAME
  119.         DevNameFromLock - return the full pathname of a file
  120.  
  121.     SYNOPSIS
  122.         DevNameFromLock(lock, buffer, size)
  123.                          D1     D2     D3
  124.  
  125.         BOOL DevNameFromLock(BPTR, char *, long);
  126.  
  127.     FUNCTION
  128.         Returns a fully qualified path for the lock. The only difference
  129.         between this function and the equivalent DOS library routine is
  130.         that the device name of the disk is returned, rather than the
  131.         volume name.
  132.  
  133.         For example, if the NameFromLock() routine returned :
  134.  
  135.             Workbench:S/startup-sequence
  136.  
  137.         The DevNameFromLock() routine would return :
  138.  
  139.             DH0:S/startup-sequence
  140.  
  141.     INPUTS
  142.         lock - filelock to obtain the path for
  143.         buffer - buffer to store path
  144.         size - size of buffer
  145.  
  146.     RESULT
  147.         This function returns TRUE if it succeeds.
  148.  
  149.     SEE ALSO
  150.         DeviceFromLock(), dos.library/NameFromLock()
  151.  
  152. dopus5.library/FreeDosPathList                 dopus5.library/FreeDosPathList
  153.  
  154.     NAME
  155.         FreeDosPathList - free a DOS path list
  156.  
  157.     SYNOPSIS
  158.         FreeDosPathList(list)
  159.                          A0
  160.  
  161.         void FreeDosPathList(BPTR);
  162.  
  163.     FUNCTION
  164.         This function frees a standard DOS path list, by unlocking each
  165.         lock and FreeVec()ing each entry.
  166.  
  167.     INPUTS
  168.         list - pointer to head of list
  169.  
  170.     RESULT
  171.         The list is freed.
  172.  
  173.     SEE ALSO
  174.         GetDosPathList()
  175.  
  176. dopus5.library/GetDosPathList                   dopus5.library/GetDosPathList
  177.  
  178.     NAME
  179.         GetDosPathList - get a copy of a DOS path list
  180.  
  181.     SYNOPSIS
  182.         GetDosPathList(list)
  183.                         A0
  184.  
  185.         BPTR GetDosPathList(BPTR);
  186.  
  187.     FUNCTION
  188.         This routine has two uses. The first is to copy an existing DOS
  189.         path list that you supply. The second is to attempt to find and copy
  190.         the system path list.
  191.  
  192.     INPUTS
  193.         list - path list to copy or NULL
  194.  
  195.     RESULT
  196.         If you supply a path list, it will be copied and the address of the
  197.         first entry of the new list will be returned.
  198.  
  199.         If you pass NULL, this routine attempts to find a system path list to
  200.         copy. The Amiga has no definitive path list, so the only way to
  201.         obtain one is to copy it from another process. This routine looks for
  202.         the following processes (in order) : Workbench, Initial CLI, Shell
  203.         Process, New_WShell and Background CLI. If one of these processes is
  204.         found and it has a valid path list, that list is copied and returned
  205.         to you.
  206.  
  207.     NOTES
  208.         If Workbench is not running, Opus creates a dummy task called
  209.         'Workbench', purely to provide a path list for programs that use this
  210.         method.
  211.  
  212.     SEE ALSO
  213.         FreeDosPathList()
  214.  
  215. dopus5.library/GetFileVersion                   dopus5.library/GetFileVersion
  216.  
  217.     NAME
  218.         GetFileVersion - get a file's version information
  219.  
  220.     SYNOPSIS
  221.         GetFileVersion(name, verptr, revptr, date, progress)
  222.                         A0     D0      D1     A1      A2
  223.  
  224.         BOOL GetFileVersion(char *, short *, short *,
  225.                             struct DateStamp *, APTR);
  226.  
  227.     FUNCTION
  228.         This routine examines the given file and returns the file's version
  229.         number and revision, and creation date if available. It looks primarily
  230.         for a $VER string, but also understands the format of libraries,
  231.         devices, etc, and can extract the version from the Romtag structure in
  232.         the file. You can also supply a Progress handle if you want to use a
  233.         progress indicator while looking for the version information.
  234.  
  235.     INPUTS
  236.         name - full pathname of file to examine
  237.         verptr - pointer to short to receive the version number
  238.         revptr - pointer to short to receive the revision number
  239.         date - pointer to DateStamp structure (NULL if no date needed)
  240.         progress - pointer to progress indicator (or NULL)
  241.  
  242.     RESULT
  243.         Returns TRUE if a valid version number was found (this does not
  244.         necessarily mean that a date was found too).
  245.  
  246. dopus5.library/IsDiskDevice                       dopus5.library/IsDiskDevice
  247.  
  248.     NAME
  249.         IsDiskDevice - determine if a device is a DOS storage device
  250.  
  251.     SYNOPSIS
  252.         IsDiskDevice(handler)
  253.                        A0
  254.  
  255.         BOOL IsDiskDevice(struct MsgPort *);
  256.  
  257.     FUNCTION
  258.         This function takes a pointer to a handler (message port) and
  259.         returns TRUE if the device is for storage (eg a disk or a hard
  260.         drive), and FALSE if it is not.
  261.  
  262.     INPUTS
  263.         handler - pointer to handler message port
  264.  
  265. dopus5.library/LaunchCLI                             dopus5.library/LaunchCLI
  266.  
  267.     NAME
  268.         LaunchCLI - launch a program as a CLI process
  269.  
  270.     SYNOPSIS
  271.         LaunchCLI(name, screen, curdir, input, output, flags, stack)
  272.                    A0     A1      D0      D1     D2     D3     D4
  273.  
  274.         BOOL LaunchCLI(char *, struct Screen *, BPTR, BPTR, BPTR, short, long);
  275.  
  276.     FUNCTION
  277.         This routine makes it easy to launch a program as a CLI process. The
  278.         launched process will have a full path list and copy of local
  279.         environment variables. You can have the process launched synchronously,
  280.         which means this function would not return until the process quit.
  281.         The stack size defaults to 4096 bytes, but you may specify your own
  282.         stack size by setting the LAUNCHF_USE_STACK flag.
  283.  
  284.     INPUTS
  285.         name - name of the program to launch, including any arguments
  286.         screen - a screen for errors to appear on (or NULL for default)
  287.         curdir - lock for current directory, or NULL for default
  288.         input - file handle for standard input, or NULL
  289.         output - file handle for standard output, or NULL
  290.         flags - set LAUNCHF_WAIT flag if you want to wait for the process to return
  291.                 set LAUNCHF_USE_STACK flag if you are specifying a stack size
  292.         stack - stack size to use if LAUNCHF_USE_STACK flag is set
  293.  
  294.     RESULT
  295.         Returns TRUE if the process was launched successfully. If the
  296.         'wait' parameter was set to TRUE, will not return until the child
  297.         process does.
  298.  
  299.     NOTES
  300.         This function will search the current path list for your program
  301.         if you do not specify the full path.
  302.  
  303.     SEE ALSO
  304.         LaunchWB, dos.library/SystemTagList
  305.  
  306. dopus5.library/LaunchWB                               dopus5.library/LaunchWB
  307.  
  308.     NAME
  309.         LaunchWB - launch a program as a Workbench process
  310.  
  311.     SYNOPSIS
  312.         LaunchWB(name, screen, wait)
  313.                    A0     A1    D0
  314.  
  315.         BOOL LaunchWB(char *, struct Screen *, short);
  316.  
  317.     FUNCTION
  318.         This routine makes it easy to launch a program as a Workbench process.
  319.         Workbench processes expect to receive a startup message from the
  320.         launching process, and ordinarily the launching process must wait
  321.         until this message is replied to. Using this function relieves you
  322.         of this - you can launch the process and then forget about it.
  323.         The launched process will have a full path list and copy of local
  324.         environment variables.
  325.  
  326.     INPUTS
  327.         name - name of the program to launch, including any arguments
  328.         screen - a screen for errors to appear on (or NULL for default)
  329.         wait - set to TRUE if you want to wait for the process to return
  330.  
  331.     RESULT
  332.         Returns TRUE if the process was launched successfully. If the
  333.         'wait' parameter was set to TRUE, will not return until the child
  334.         process does. Otherwise, it will return immediately and you do not
  335.         need to wait for a reply to the startup message.
  336.  
  337.     NOTES
  338.         This function will search the current path list for your program
  339.         if you do not specify the full path.
  340.  
  341.     SEE ALSO
  342.         LaunchCLI, LaunchWBNew, dos.library/SystemTagList
  343.  
  344. dopus5.library/LaunchWBNew                         dopus5.library/LaunchWBNew
  345.  
  346.     NAME
  347.         LaunchWBNew - launch a program as a Workbench process
  348.  
  349.     SYNOPSIS
  350.         LaunchWBNew(name, screen, wait, stack, default_tool)
  351.                    A0     A1    D0     D1        A2
  352.  
  353.         BOOL LaunchWBNew(char *, struct Screen *, short, long, char *);
  354.  
  355.     FUNCTION
  356.         This routine offers more control than LaunchWB() when launching a
  357.         Workbench process. It allows you to specify the stack size and
  358.         default tool that are used if the program you are launching is
  359.         a project and has no icon of its own.
  360.  
  361.     INPUTS
  362.         name - name of the program to launch, including any arguments
  363.         screen - a screen for errors to appear on (or NULL for default)
  364.         wait - set to TRUE if you want to wait for the process to return
  365.         stack - stack size to use if no icon present
  366.         default_tool - default tool to use if no icon or not set
  367.  
  368.     RESULT
  369.         Returns TRUE if the process was launched successfully. If the
  370.         'wait' parameter was set to TRUE, will not return until the child
  371.         process does. Otherwise, it will return immediately and you do not
  372.         need to wait for a reply to the startup message.
  373.  
  374.     NOTES
  375.         This function will search the current path list for your program
  376.         if you do not specify the full path.
  377.  
  378.     SEE ALSO
  379.         LaunchWB, LaunchCLI, dos.library/SystemTagList
  380.  
  381. dopus5.library/ParseDateStrings               dopus5.library/ParseDateStrings
  382.  
  383.     NAME
  384.         ParseDateStrings - parse a date/time string into separate buffers
  385.  
  386.     SYNOPSIS
  387.         ParseDateStrings(string, date, time, rangeptr)
  388.                            A0     A1    A2      A3
  389.  
  390.         char *ParseDateStrings(char *, char *, char *, long *);
  391.  
  392.     FUNCTION
  393.         This function takes a date/time string (eg "8-12-95 10:34:18") and
  394.         splits the date and time elements into separate buffers. It also
  395.         supports the use of the '>' character to indicate ranges. For
  396.         example, "10-jan-94 > 15-jun-95" would indicate any date between
  397.         those dates.
  398.  
  399.     INPUTS
  400.         string - combined date/time string. This routine is smart enough
  401.                  to handle it if the time comes before the date, or
  402.                  vice versa, and it also deals reasonably well with
  403.                  different types of date inputs.
  404.         date - buffer to receive the date component (>=22 bytes)
  405.         time - buffer to receive the time component (>=22 bytes)
  406.         rangeptr - long pointer to receive the range code (or NULL)
  407.  
  408.     RESULT
  409.         The return from this function is a pointer to the end of the
  410.         parsed part of the input string. If the range returns RANGE_BETWEEN
  411.         (to signify a range between two dates), you will need to call
  412.         ParseDateStrings() again on the remainder of the string to get the
  413.         next date and time.
  414.  
  415.     SEE ALSO
  416.         DateFromStrings()
  417.  
  418. dopus5.library/SearchFile                           dopus5.library/SearchFile
  419.  
  420.     NAME
  421.         SearchFile - search a file or buffer for a text string
  422.  
  423.     SYNOPSIS
  424.         SearchFile(file, text, flags, buffer, bufsize)
  425.                     A0    A1     D0     A2      D1
  426.  
  427.         long SearchFile(APTR, UBYTE *, ULONG, UBYTE *, ULONG);
  428.  
  429.     FUNCTION
  430.         This routine searches a file, either on disk or in memory, for
  431.         a specified text string. It supports hex or decimal ascii values,
  432.         and limited wildcard searching. To search for a hex string,
  433.         the supplied search string should begin with a $ and then consist
  434.         of two-character hex codes. When searching for plain text, a
  435.         decimal ascii value can be specified with a \ character (eg \127).
  436.         A literal \ is given as \\. A question mark (?) is used as a
  437.         single wildcard character in both hex and text searches.
  438.  
  439.     INPUTS
  440.         file - buffered IO file handle
  441.         text - text string to search for
  442.         flags - Combination of the following flags :
  443.  
  444.                    SEARCH_NOCASE     - not case sensitive
  445.                    SEARCH_WILDCARD   - support ? as a wildcard character
  446.                    SEARCH_ONLYWORDS  - only match whole words
  447.  
  448.         buffer - memory buffer to search if no file specified
  449.         bufsize - size of memory buffer
  450.  
  451.     RESULT
  452.         If the supplied string is found, the offset within the file/buffer
  453.         of the first instance is returned. If no match is found or an error
  454.         occurs, -1 is returned.
  455.  
  456. dopus5.library/SetEnv                                   dopus5.library/SetEnv
  457.  
  458.     NAME
  459.         SetEnv - set a global environment variable
  460.  
  461.     SYNOPSIS
  462.         SetEnv(name, string, permanent)
  463.                 A0     A1        D0
  464.  
  465.         void SetEnv(char *, char *, BOOL);
  466.  
  467.     FUNCTION
  468.         This routine sets the named environment variable to the supplied
  469.         string value, and optionally saves it permanently.
  470.  
  471.     INPUTS
  472.         name - name of the variable to set
  473.         string - text string to set the variable to (must be null-terminated)
  474.         permanent - set to TRUE if you want the variable saved
  475.  
  476.     RESULT
  477.         The environment variable will be created if it does not exist. Any
  478.         sub-directories that are needed will also be created. For example,
  479.         if you set the variable "foo/bar/baz", the directories "env:foo"
  480.         and "env:foo/bar" would be automatically created if they did not
  481.         exist. If you set the 'permanent' flag to TRUE, the variable
  482.         will also be created in the ENVARC: directory.
  483.  
  484.     SEE ALSO
  485.         dos.library/GetVar
  486.  
  487.