doslib14.doc

TABLE OF CONTENTS DOSLib DOS Library Programmer’s Reference Version 4.0 DOSLib Version 4.0 © 1992-96 Robert McNeel & Associates. All rights reserved. Printed 03-13-97 in USA. Robert McNeel & Associates 3670 Woodland Park Avenue North Seattle, WA 98103 Phone: (206) 545-7000 FAX: (206) 545-7321 Technical Support: (206) 545-7321 Bulletin Board Service: (206) 545-7303 Internet: CompuServe: GO MCNEEL DOSLib is a trademark of Robert McNeel & Associates. AutoCAD, AutoLISP and ARX are registered trademarks of Autodesk, Inc. DOS, MS-DOS, Windows, Windows 95 and Windows NT are registered trademarks of Microsoft Corporation. All other brands and product brands are trademarks or registered trademarks of their respective holders. License Agreement Permission to use, copy, and distribute this software for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in all supporting documentation. Robert McNeel & Associates makes no warranty, including but not limited to any implied warranties of merchantability or fitness for a particular purpose, regarding the software and accompanying materials. The software and accompanying materials are provided solely on an “as-is” basis. In no event shall Robert McNeel & Associates be liable to any special, collateral, incidental, or consequential damages in connection with or arising out of the use of the software or accompanying materials. 1 TABLE OF CONTENTS Table of Contents Introduction 5 System Requirements 5 Files in DOSLib 6 Installing DOSLib 6 Loading DOSLib 6 Function Overview 8 Drive Handling Functions 11 dos_chkdsk 11 dos_drive 12 dos_drives 12 Path Handling Functions 13 dos_fullpath 13 dos_makepath 14 dos_path 15 dos_splitpath 16 Directory Handling Functions 19 dos_chdir 19 dos_mkdir 20 dos_rendir 20 dos_rmdir 21 dos_pwdir 22 dos_subdir 22 File Handling Functions 25 dos_attrib 25 dos_copy 26 dos_delete 27 dos_dir 28 dos_file 28 dos_filesize 29 dos_find 30 dos_move 31 dos_rename 31 dos_search 32 dos_touch 33 Initialization File Handling Functions 35 dos_getini 35 dos_setini 36 Process Handling Functions 39 dos_command 39 dos_execute 40 Miscellaneous Functions 41 dos_about 41 dos_beep 41 dos_date 42 dos_help 43 dos_time 43 dos_ver 44 dos_win 45 Index 47 41 41 INTRODUCTION 1  Introduction DOSLib, or DOS Library, is a library of AutoLISP-callable functions that provide DOS command-line functionality in AutoCAD. Developed as an AutoCAD Runtime Extension (ARX) application, DOSLib gives your AutoLISP functions and commands greater DOS capability than what is offered by the current suite of AutoLISP functions. DOSLib extends the AutoLISP programming language by providing the following functionality: • Drive handling functions to change between drives and check disk space. • Path handling functions to manipulate path specifiers. • Directory handling functions to create, rename, remove and change directories. • File handling functions to copy, delete, move, and rename files. Functions for getting directory listings, searching and finding multiple instances of files, and changing attributes are provided. • Initialization file handling functions to manipulate Windows-style initialization (INI) files. • Process handling functions to run internal DOS commands or other programs. • Miscellaneous functions, like changing the system date and time. System Requirements DOSLib requires AutoCAD Release 14 for Windows 95, or NT. Files in DOSLib The following files make up DOSLib: Filename Description DOSLIB14.DOC DOSLib Programmer’s Reference in MS Word for Windows format. DOSLIB14.ARX DOSLib for AutoCAD Release 14 for Windows. Installing DOSLib Though DOSLib files can be installed in and run from any directory on a disk, the following locations are recommended: • A directory specified by the AutoCAD search path (for example, C:\ACADR14\SUPPORT). • A directory common to multiple users (for example, X:\PROJECTS). • The directory where the AutoCAD executable file (ACAD.EXE) is located (for example, C:\ACADR14). Loading DOSLib LOADING DOSLIB MANUALLY You can load DOSLib manually several ways. To load DOSLib from AutoCAD: 1 From the AutoCAD Tools menu, choose Applications. Or, type appload at the command prompt. The Load AutoLISP, ADS and ARX Files dialog box appears. 2 Click File. The Select LISP, ADS or ARX File Routine dialog box appears. 3 From the files list, select DOSLIB14.ARX from the directory where you copied the files. 4 Click OK. The Load AutoLISP, ADS and ARX Files dialog box appears. 5 Click Load. LOADING DOSLIB AUTOMATICALLY DOSLib can also be automatically loaded in several ways • You can add the appropriate DOSLib filename to the ACAD.ARX file. • You can add an arxload function for either the ACAD.LSP or MENU.MNL file. If you choose the xload method, the arxload function must be part of the S::STARTUP function. This is because AutoCAD does not initialize ADS until S::STARTUP. Also, AutoCAD processes the ACAD.LSP file before any MENU.MNL file. If both files have a S::STARTUP function, only the function in MENU.MNL is interpreted. The following code example demonstrates how you might automatically load DOSLib with the S::STARTUP function: Example ;AutoLISP automatic function (defun S::STARTUP () . . ;load DOSLib (cond ;if DOSLib is already loaded, return true ((not (null dos_about)) T ) ;if AutoCAD Release 14, ((= (atoi (substr (getvar "acadver") 1 2)) 14) (arxload "doslib14") ) (T (prompt " DOSLib AutoCAD R14") ) ) . . Function Overview Function Description Dos_about Displays information about DOSLib Dos_attrib Returns or changes file attributes Dos_beep Generates a sound using the computer speaker Dos_chdir Changes the current directory Dos_command Runs a COMMAND.COM command Dos_copy Copies a file Dos_date Returns or changes the system date Dos_delete Deletes files Dos_dir Returns a list of files Dos_chkdsk Returns drive space statistics Dos_drive Returns or changes the current drive Dos_drives Returns a list of available drives Dos_execute Executes an external program Dos_file Returns detailed file information Dos_filesize Returns file size information Dos_find Finds files Dos_fullpath Converts a partial path to a qualified path Dos_getini Gets an entry from an initialization file Dos_help Displays a list of DOSLib functions Dos_makepath Creates a path name from components Dos_mkdir Makes a directory Dos_move Moves a file Dos_path Returns the current DOS path Dos_pwdir Returns the path to the current directory Dos_rename Renames a file Dos_rendir Renames a directory Dos_rmdir Removes a directory Dos_search Searches for a file using environment paths Dos_setini Sets an entry in an initialization file Dos_splitpath Breaks a path name into components Dos_subdir Returns a list of subdirectories Dos_time Returns or changes the system time Dos_touch Changes file modification date and time dos_ver Returns the operating system version number dos_win Returns the current operating environment 2  Drive Handling Functions dos_chkdsk Returns drive space statistics for the current drive or for the specified drive. Use the rtos function to convert the return values to strings. Syntax (dos_chkdsk [drive]) Options drive The drive name (for example, C:, D:). Returns A list of three real numbers indicating the total disk space, used disk space, and free disk space in bytes. nil on error. Example (dos_chkdsk) (5.23526e+008 4.78839e+008 4.46874e+007) Example (dos_chkdsk "z:") (1.99996e+009 2,175e+008 1.78238e+009) See Also dos_chdir dos_drive Returns the current drive, or changes the current drive to the one specified. Syntax (dos_drive [drive]) Options drive Drive name (for example, C:, D:). Returns A string describing the current or new drive. nil on error. Example (dos_drive) "C:" Example (dos_drive "z:") "Z:" dos_drives Returns a list of available drives. Syntax (dos_drives) Returns A list of available local and network drives. nil on error. Example (dos_drives) ("A:" "B:" "C:" "X:" "Y:" "Z:") PATH HANDLING FUNCTIONS 3  Path Handling Functions dos_fullpath Converts a partial path to a fully qualified path. Unlike the dos_makepath function, dos_fullpath can be used with .\\ and ..\\ in the path. Syntax (dos_fullpath path) Arguments path If the path argument specifies a drive (C:, D:, etc.), the current directory of this drive is combined with the path. Returns A fully qualified path. Returns nil if drive is not valid or on error. Example (dos_fullpath "acad.dwg") "C:\\ACAD\\SUPPORT\\ACAD.DWG" Example (dos_fullpath "..\\windows\\win.ini") "C:\\WINDOWS\\WIN.INI" Example (dos_fullpath "z:") "Z:\\PUBLIC" SEE ALSO dos_makepath dos_fullpath dos_makepath Creates a single path, composed of a drive letter, directory path, file name, and file extension. Syntax (dos_makepath drive directory filename extension) Arguments drive The letter (A, B, etc.) corresponding to the desired drive and an optional trailing colon (:). The function inserts the colon automatically in the composite path name if it is missing. If drive is an empty string (""), no drive letter and colon appear in the returned path. directory The path of directories, not including the drive designator or the actual file name. The trailing slash is optional. Either forward slashes (/) or double-backslashes (\\) or both may be used in a single directory argument. If a trailing slash (/ or \\) is not specified, it is inserted automatically. If directory is a empty string (""), no slash is inserted in the returned path. filename The base file name without any extensions. If filename is an empty string (""), no file name is inserted in the returned path. extension The file name extension, with or without a leading period (.). The function inserts the period automatically if it does not appear in extension. If extension is an empty string (""), no period is inserted in the returned path. Returns A fully qualified path. Returns nil if drive is not valid or on error. Example (dos_makepath "c:" "\\acad" "acad" "exe") "C:\\ACAD\\ACAD.EXE" Example (dos_makepath "c:" "\\acad" "" "") "C:\\ACAD\\" Example (dos_makepath "" "\\acad" "acad" "exe") "\\ACAD\\ACAD.EXE" dos_path Returns a list describing the current DOS search path for executable programs as set by the either the PATH command or SET PATH statement. Syntax (dos_path) Returns Current value of DOS PATH or SET PATH statement. nil on error. Example (dos_path) ("C:\\ACAD\\" "C:\\WINDOWS\\" "C:\\DOS\\ "Z:\\PUBLIC") dos_splitpath Breaks a full path name into its four components. The function returns a list containing the four components. Syntax (dos_splitpath path) Arguments path A string containing a qualified path Returns drive The drive letter followed by a colon (:) if a drive is specified in path. directory The path of subdirectories, if any, including the trailing backslashes. Forward slashes (/), double-backslashes (\\), or both may be present in path. filename The base file name without any extension. extension The file name extension, if any, including the leading period. nil on error. Example (dos_splitpath "c:\\acad\\acad.exe") ("C:" "\\ACAD\\" "ACAD" ".EXE") Example (dos_splitpath "c:\\acad\\") ("C:" "\\ACAD\\" "" "") Example (dos_splitpath "c:\\acad") ("C:" "\\" "ACAD" "") DIRECTORY HANDLING FUNCTIONS 3  Directory Handling Functions dos_chdir Changes the current directory to the specified directory. This function can change the current directory on any drive; it cannot be used to change the current drive. Syntax (dos_chdir path) Arguments path An existing directory. Returns A qualified path to the current directory. nil on error. Example (dos_chdir "test") "C:\\ACAD\\TEST\\" Example (dos_chdir "\\drawings") "C:\\DRAWINGS\\" Example (dos_chdir "z:\\") "Z:\\" See Also dos_drive dos_mkdir Creates a new directory. Only one directory can be created at a time, so only the last component of path can name a new directory. Syntax (dos_mkdir path) Arguments path The directory name. Returns A qualified path to the newly created directory. nil on error. Example (dos_mkdir "test") "C:\\ACAD\\TEST\\" Example (dos_mkdir "\\drawings") "C:\\DRAWINGS\\" dos_rendir Renames a directory. Syntax (dos_rendir oldpath newpath) Arguments oldpath Must be the path name of an existing directory newpath Must not be the path name of an existing directory. Returns A qualified path containing the new directory name. nil on error. Example (dos_rendir "test" "backup") "C:\\ACAD\\BACKUP\\" Example (dos_rendir "backup" "support") nil dos_rmdir Removes a directory. Syntax (dos_rmdir path) Arguments path The specified directory must be empty and must not be the current directory or the root directory. Returns A qualified path to the removed directory. nil on error. Example (dos_rmdir "test") "C:\\ACAD\\TEST\\" Example (dos_rmdir "\\drawings") "C:\\DRAWINGS\\" dos_pwdir Returns the path to the current directory for the current drive, or the specified drive. Syntax (dos_pwdir [drive]) Options drive Specifies the drive, for example: C:, D:. Returns The path to the current directory for specified drive. nil on error. Example (dos_pwdir) "C:\\ACAD\\ Example (dos_pwdir "z:") "Z:\\PUBLIC\\" dos_subdir Returns a list of subdirectories found in current directory or in the specified directory. This function is the only path-related function whose return values do not contain trailing double-backslashes (\\). Syntax (dos_subdir [path]) Options path Specifies the desired directory. Returns A list of subdirectories. nil on error. Example (dos_subdir) (".." "ADS" "API" "FONTS" "IGESFONTS" "SAMPLE" "SUPPORT") (dos_subdir "c:\\") ("ACAD" "DOS" "TEMP" "WINDOWS") Example (dos_subdir "d:\\") nil FILE HANDLING FUNCTIONS 4  File Handling Functions dos_attrib Returns file attributes, or sets file attributes to the value described by bits. Syntax (dos_attrib [filespec [bits]]) Options filespec The desired file or files. Can contain DOS wildcard characters (“*” and “?”). If no filespec is supplied, it is assumed to be *.*. bits An integer (bit-coded) identifying the desired file attributes. Specify more than one file attribute by adding the bit values. The allowable bit values are as follows: Bit value Description