Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / CLIPPER / ACC86.ARC / ACCI86.DOC next >

Wrap

Text File | 1987-10-23 | 47.8 KB | 1,950 lines

ACCI86.LIB USERS MANUAL A Clipper Function Library Version 1.00 10/21/87 Copyright (c) Advanced Computer Consultants, Inc. 1987 P.O. Box 462 Ridgeland, MS 39158 ACCI86.LIB TABLE OF CONTENTS Page Contents 1 ...... License 2 ...... Warranty 3 ...... Registration Order Form 4 ...... Overview Chapter 1 File Open/Close Functions 6 ...... AC_OPEN() - Allows setting of sharing and access mode 7 ...... AC_FOPEN() - opens file with Deny None mode and Read/Write access as default AC_CREAT() - allow setting of file attributes AC_FCREA() - creates file with default attribute 8 ...... AC_CLOSE() - closes an open file AC_UNIQ() - create unique file using INT 5A Chapter 2 File I/O Functions (read and write) 9 ...... AC_GETS() - read string from file AC_PUTS() - write string to file AC_GETB() - read one byte as string from file 10 ...... AC_PUTB() - write string as one byte to file AC_GETI() - read integer from file AC_PUTI() - write integer to file 11 ...... AC_GETD() - read date from file AC_PUTD() - write date to file AC_GETZ() - read a ASCII 0 terminated string from file Chapter 3 File Pointer Functions 12 ...... AC_MVPTR() - move file pointer, all 3 modes AC_GOTOP() - goto beginning of file AC_GOBOT() - goto end of file 13 ...... AC_BOF() - is BOF AC_EOF() - is EOF AC_POSIN() - current position 14 ...... AC_SKIP() - move +- bytes AC_FSIZE() - file length (size) Page Contents - Continued Chapter 4 File Attribute Functions 15 ...... AC_GATTR() - read file attributes AC_ISRO() - is read only file AC_ISHID() - is a hidden file 16 ...... AC_ISSYS() - is a system file AC_ISSUB() - is a subdirectory AC_ISARC() - is archive bit set 17 ...... AC_PATTR() - write file attributes AC_MKRO() - make file read only AC_MKHID() - make file hidden 18 ...... AC_MKSYS() - make file system AC_MKARC() - set archive bit Chapter 5 File Time/Date Stamp Functions() 19 ...... AC_GTIME() - read file time stamp AC_GDATE() - read file date stamp AC_PTIME() - write file time stamp 20 ...... AC_PDATE() - write file date stamp AC_PTD() - write both time and date stamps Chapter 6 Misc. DOS Functions 21 ...... AC_QUIT() - quit the program passing DOS an exit code AC_RETCD() - get from DOS the exit code AC_COMIT() - Comit file using INT 68 22 ...... AC_DOS() - returns the DOS version as a string Chapter 7 Other Functions 23 ...... AC_DIAL() - dial a given telephone number string AC_MODEM() - set parameters for AC_DIAL() AC_SETM() - also sets parameters for AC_DIAL() 24 ...... AC_STCL() - set parameters on the constant display clock AC_CLSET() - simpler method to set the clock 25 ...... AC_CLON() - turn on the constant display clock AC_CLOFF() - turn off the constant display clock Page Contents - Continued Chapter 8 Error Recovery 26 ...... OVERVIEW AC_ERROR() - returns DOS or ACCI error number 27 ...... DOS ERROR CODES 29 ...... ACCI ERROR CODES Chapter 9 Standalone Utilities 30 ...... FRMSTRUC - prints the structure of a Report .FRM file LICENSE "Programs" shall mean the computer software contained in the ACCI86.LIB file and the accompanying documentation. The Programs are not in the public domain, nor are they free software. Copyright (C) 1987 ADVANCED COMPUTER CONSULTANTS, INC. All rights reserved. Non-registered users are granted a limited license to use the Programs on a trial basis for the purpose of determining whether the Programs are suitable for their needs. Use of the Programs, except for this limited purpose, requires registration. Use of non-registered copies of the Programs by any person, business, corporation, governmental agency or other entity is strictly prohibited. All users are granted a limited license to copy the Programs only for the trial use of others subject to the above limitations, and also the following: - The Programs must be copied in unmodified form, complete with the file containing this license information. - The full ACCI86.LIB documentation must be included with the copy. - No fee, charge or other compensation may be accepted or requested by any licensee. Operators of electronic bulletin board systems (Sysops) may post ACCI86.LIB for downloading by their users only as long as the above conditions are met. Registration grants a user the following non-exclusive privileges: - You may incorporate any of the Programs into software applications you develop. - You may modify the Programs for the purpose of incorporating them into your applications. - You may distribute copies of the Programs to the extent they are incorporated in your software applications and you have placed your own copyright notice on the application. - To incorporate the Programs into your application your application can not be a library of functions as are the Programs. - You may use the Programs as a library on only a single computer at one time. You are not limited by this license as to how many copies of your applications incorporating the Programs you may distribute. - You may purchase for an additional amount a copy of the assembler and Clipper source code. (See order form.) - The Programs remain the property of ADVANCED COMPUTER CONSULTANTS, INC. No amount of modification of the source or rewriting of the source code will allow you to consider the resultant source code to be your property. - Notification of upgrades. See the registration form for more information on registration, quantity purchases and similar topics. - 1 - WARRANTY ADVANCED COMPUTER CONSULTANTS, INC. will replace any disks found to be physically defective within 30 days from date of purchase. ADVANCED COMPUTER CONSULTANTS, INC. warrants that the Programs will perform in substantial compliance with the documentation supplied with the product. If a significant defect in the product is found, Purchaser will be entitled to a refund. In no event will such a refund exceed the purchase price of the Programs. EXCEPT AS PROVIDED ABOVE, ADVANCED COMPUTER CONSULTANTS, INC. DISCLAIMS ALL WARRANTIES, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE PRODUCT. SHOULD THE PROGRAMS PROVE TO BE DEFECTIVE, THE PURCHASER ASSUMES THE RISK OF PAYING THE ENTIRE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION AND ANY INCIDENTAL OR CONSEQUENTIAL DAMAGES. IN NO EVENT WILL ADVANCED COMPUTER CONSULTANTS, INC. BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION AND THE LIKE) ARISING OUT OF THE USE OF OR INABILITY TO USE THIS PRODUCT EVEN IF ADVANCED COMPUTER CONSULTANTS, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Use of this software product for any period of time constitutes your assumed acceptance of this agreement and subjects you to it's contents. - 2 - REGISTRATION ORDER FORM ADVANCED COMPUTER CONSULTANTS, INC. P.O. Box 462 Ridgeland, MS 39158 Registration costs $25. for first copy..... _____ @ $25. = __________ $20. for 2nd thru 10th copies..... _____ @ $20. = __________ $15. for 11th and up copies....... _____ @ $15. = __________ Registration Totals _____ $__________ Registration does not include a diskette. Diskettes containing the ACCI86.LIB, documentation, compiled standalone utilities, ect. may be purchased separately for $10. each. Library diskettes.... _____ @ $10. = __________ Copies of the Assembler and Clipper Source Code may be purchased separately by registered users. Prices include a diskette containing all of the source code and the contents of the Library diskette above. Source Code costs $25. for first copy..... _____ @ $25. = __________ $20. for 2nd thru 10th copies..... _____ @ $20. = __________ $15. for 11th and up copies....... _____ @ $15. = __________ Source Code Totals _____ $__________ Clipper version________________ Total Order $__________ Diskette: 5 1/4_____ 3 1/2_____ Quantity orders good only with that order, not cumulative over several orders. Check, cash, or money order only. U.S. funds only. NAME ________________________________________________ COMPANY _____________________________________________ ADDRESS _____________________________________________ _____________________________________________________ CITY ___________________ STATE _____ ZIP ____________ Upgrade notice sent to: (circle one of the below) Source - ID __________ CompuServe - _____________ Mail to above address - 3 - OVERVIEW of ACCI86.LIB Since this product is being distributed as "shareware" you have no doubt deduced that this is a part time project for me. My full time job is as an analyst/programmer and 95% of my code is compiled with Clipper. What I am able to do for support is stated below. Please send to me descriptions of any "bugs" you may find in this library. Also, please send to me any ideas or needs you have for additional functions. I am able to do some custom programming for a fee, write for details. SUPPORT POLICY: Support provided to Registered Users only. Send to me complete descriptions of any problems you are having with this library, including a small portion of your code containing the offending function. Include your name, company name, address, telephone number, and Registration Serial Number and I will respond as soon as I can. Please do not call. Send to one of the following mail boxes: Source: ID BBV301 CompuServe: 70701,2755 ADVANCED COMPUTER CONSULTANTS, INC. P.O. Box 462 Ridgeland, MS 39158 UPGRADE POLICY: I will send a notice to all Registered Users whenever there is a major upgrade to this library. There may or may not be an additional fee for the upgrade. I may also notify you of other products that I develop which may be of interest to Clipper programmers. Trademark Notice DOS, IBM is a trademark of International Business Machines Clipper is a trademark of Nantucket Corporation dBASE and dBASE III Plus are trademarks of Ashton-Tate Tom Rettig's Library is a trademark of Tom Rettig Associates How to Link. Name the ACCI86.LIB after the CLIPPER.LIB in linking your program. Compatable with Autumn 86 version of Clipper. The functions marked (DBF) would have to be recompiled to work with the Winter 85 version of Clipper. The assembly functions should work ok as is with Winter 85 although I have not tested it. I will make any necessary changes to make this library compatable with Summer 87 when it becomes available. When ordering library diskettes please state the version of Clipper you are using and I will compile the Clipper code for you with that version. - 4 - DOS FILE HANDLES Many of these functions use "file handles". A file handle is one way DOS keeps track of which file you are referring to when you execute DOS functions. When a file is opened with any of the Open Functions in Chapter 1 a numeric file handle is returned by DOS and is returned via the Open functions back to your Clipper program. Save this handle with a variable or in an array. The functions in Chapters 2, 3, and 5 all require the handle as a parameter. DOS predefines five standard device handles, you may use (with care) these handles also. Handle Use DOS Device 0 Standard input device CON: 1 Standard output device CON: 2 Standard error device CON: 3 Standard auxiliary device AUX: 4 Standard printer device LPT1: or PRN: DOS has an internal file pointer associated with each handle. All of the File I/O functions in Chapter 2 and many of the File Pointer functions in Chapter 3 move this pointer. During file I/O the pointer is left pointing to the last byte read or written, and unless you move the pointer, the next I/O function will begin with the next byte. - 5 - CHAPTER 1 File Open/Close Functions FUNCTION: AC_OPEN() (ASM) This function opens a file. The file is left open so that it can be processed. Syntax: AC_OPEN( expC1 , expC2 ) Parameters: expC1 = <drive><path>file_name expC2 = the open mode as a 8 char bit string Return: the file handle as an integer, if successful, -1 if not Examples: Handle = AC_OPEN('C:\apps\travel.fil','10010010') M_file = 'Payroll' M_mode = '10100010' && private, deny write, read/write Handle = AC_OPEN(M_file,M_mode) OPEN MODE BITS bit 7 - inheritance bit 0 = file is inherited by child process 1 = file is private to the current process bits 6, 5, 4 - sharing mode bits (defines what access others can have to this file after you have opened it) 000 = compatibility mode 001 = deny read/write (use exclusive) 010 = deny write 011 = deny read 100 = deny none bit 3 - reserved 0 = always cleared bits 2, 1, 0 - access mode bits (defines what access you can have to the file after opened) 000 = read access 001 = write access 010 = read/write access - 6 - FUNCTION: AC_FOPEN() (PRG) Open a file with defaults - inherited, deny none sharing, read/write access Syntax: AC_FOPEN( expC ) Parameter: expC = <drive><path>file_name Return: file handle if sucessful, -1 if failed Examples: Handle = AC_FOPEN('\apps\acct_pay') M_file = 'info.dat' Hands[1] = AC_FOPEN(M_file) FUNCTION: AC_CREAT() (ASM) This function creates and opens the passed file name for output. If the file exists, you specify if it is to be overwritten. The file is left open so that it can be processed. Syntax: AC_CREAT( expC1 , expL , expC2 ) Parameters: expC1 = <drive><path>file_name expL = if .T. an existing file is overwritten, if .F. the function fails if the file exists. expC2 = the attribute as a binary string. Return: the file handle as an integer, if successful, -1 if not Example: M_file = 'data.fil' Handle = AC_CREAT(M_file,.T.,'10100010') private, deny write, read/write FUNCTION: AC_FCREA() (PRG) Create a file with default attributes. Syntax: handle = AC_FCREA( expC ) Parameter: expC = <drive><path>file_name Return: file handle if sucessful, -1 if failed Example: Handle = AC_FOPEN('\apps\acct_pay') - 7 - FUNCTION: AC_CLOSE() (ASM) This function closes the passed file handle. Syntax: AC_CLOSE( expN ) Parameter: expN = the handle saved from one of the four open functions Return: .T., if successful, .F. if not Example: AC_CLOSE( Handle ) FUNCTION: AC_UNIQ() (ASM) This function creates a file and determines the file's name so that the file name is unique. The file is closed and the file name returned. Syntax: AC_UNIQ( expC1 , expC2 ) Parameters: expC1 = the file path terminated with a backslash '\' expC2 = the attribute as a bit string Return: the file \path\name, if successful, 'AC_ERROR', if failed Example: File_name = AC_UNIQ('C:\appls\','10100010') private, deny write, read/write - 8 - CHAPTER 2 File I/O Functions FUNCTION: AC_GETS() (ASM) This function reads a string from a file opened by AC_OPEN(). Syntax: AC_GETS( expN1 , expN2 ) Parameters: expN1 = the number of bytes to read from 1 to a maxinum of 255 expN2 = the file handle Return: file data as a string, or AC_ERROR if failed Examples: M_string = AC_GETS(20,Handle) Handle1 = AC_OPEN('hello.dat') Byte_ct = 15 @ 10,20 SAY AC_GETS(Byte_ct,Handle1) FUNCTION: AC_PUTS() (ASM) This function writes a string to a file opened by AC_OPEN(). Syntax: AC_PUTS( expN , expC ) Parameters: expN = the file handle expC = the string to write to disk Return: .T. if sucessfull, .F. if not Example: Handle3 = AC_FCREA('data.fil') AC_PUTS( Handle3, 'Write this string to file.' ) FUNCTION: AC_GETB() (ASM) This function returns a string containing 1s and 0s of the binary pattern of the current byte (bit order 76543210 of string) from a file opened by AC_OPEN(). Syntax: AC_GETB( expN ) Parameters: expN = the file handle Return: file data in a bit pattern of one byte in a char string, or 'AC_ERROR' if failed Example: M_byte = AC_GETB( Handle ) && read a carriage return ? M_byte '00001101' - 9 - FUNCTION: AC_PUTB() (ASM) This function receives a string containing 1s and 0s of the binary pattern of the byte (bit order 76543210 of string) to write to a file opened by AC_OPEN(). Syntax: AC_PUTB( expN , expC ) Parameters: expN = the file handle expC = the string to convert into a byte Return: .T. if sucessful, .F. if failed Example: AC_PUTB( Handle , '00001101' ) && write a carriage return FUNCTION: AC_GETI() (ASM) This function returns integer data from a file opened by AC_OPEN(). The bytes are read least significant byte first. Syntax: AC_GETI( expN1 , expN2 ) Parameters: expN1 = the file handle expN2 = number of bytes to read from 1 to a maximum of 4 Return: file data of type integer if sucessful, -1 if failed (check AC_ERROR()) Example: M_integer = AC_GETI( Handle, 2 ) FUNCTION: AC_PUTI() (ASM) This function writes integer data to a file opened by AC_OPEN(). The bytes are written least significant byte first. Syntax: AC_PUTI( expN1 , expN2 , expN3 ) Parameters: expN1 = the file handle expN2 = number of bytes to write from 1 to a maximum of 4 expN3 = the integer to write to disk Return: .T. if sucessful, .F. if not Example: AC_PUTI( Handle , 3 , 88000 ) && writes the number 88000 to disk in 3 bytes - 10 - FUNCTION: AC_GETD() (ASM) This function returns a date from a file opened by AC_OPEN(). The date string in the file must be in the format 'YYYYMMDD' Syntax: AC_GETD( expN ) Parameters: expN = the file handle Return: file data as a date if sucessful, an empty date if failed Example: M_date = AC_GETD( Handle ) ? TYPE('M_date') D FUNCTION: AC_PUTD() (ASM) This function writes a date to a file opened by AC_OPEN(). The date string is written to the file in the format 'YYYYMMDD' Syntax: AC_PUTD( expN , expD ) Parameters: expN = the file handle expD = the date to write to disk Return: .T. if sucessfull, .F. if failed Example: M_date = CTOD('10/10/87') AC_PUTD( Handle , M_date ) FUNCTION: AC_GETZ() (ASM) This function returns a string from a file opened by AC_OPEN(). Bytes are read from the file one byte at a time and tested for the string terminator ASCII 0. All bytes up to the string terminator are returned. Syntax: AC_GETZ( expN ) Parameters: expN = the file handle Return: file data as a string, or AC_ERROR if failed Examples: M_string = AC_GETZ( Handle ) - 11 - CHAPTER 3 File Pointer Functions FUNCTION: AC_MVPTR() (ASM) This function moves the file pointer in a file opened by AC_OPEN(). Syntax: AC_MVPTR( expN1 , expN2 , expN3 ) Parameters: expN1 = the file handle expN2 = MODE expN3 = number of bytes to move Return: new pointer location in relation to the beginning of the file, -1 if failed MODE: 0 = from beginning of file 1 = from current position 2 = from end of file Examples: top_of_file = AC_MVPTR( Handle, 0, 0 ) end_of_file = AC_MVPTR( Handle, 2, 0 ) skip_10 = AC_MVPTR( Handle, 1, 10 ) FUNCTION: AC_GOTOP() (PRG) Moves the file pointer to the top of the file (offset 0). Syntax: AC_GOTOP( expN ) Parameter: file handle Return: .T. if sucessful, .F. if failed Example: AC_GOTOP( Handle ) FUNCTION: AC_GOBOT() (PRG) Moves the file pointer to the bottom (end) of the file. Syntax: AC_GOBOT( expN ) Parameter: file handle Return: .T. if sucessful, .F. if failed - 12 - FUNCTION: AC_BOF() (PRG) Checks to see if the pointer is at the beginning of the file (offset 0). Syntax: AC_BOF( expN ) Parameter: file handle Return: .T. if pointer is at beginning of the file, .F. if not Example: AC_BOF( Handle ) FUNCTION: AC_EOF() (PRG) Checks to see if the pointer is at the end of the file. Syntax: AC_EOF( expN ) Parameter: file handle Return: .T. if the pointer is at the end of the file, .F. if not Example: AC_EOF( Handle ) FUNCTION: AC_POSIN() (PRG) Returns the position of the pointer in bytes from the beginning of the file. Syntax: AC_POSIN( expN ) Parameter: file handle Return: offset from beginning of file, -1 if failed Example: AC_POSIN( Handle ) - 13 - FUNCTION: AC_SKIP() (PRG) Moves the file pointer forward (or backward if negative) the input number of bytes. Syntax: AC_SKIP( expN1 , expN2 ) Parameter: expN1 = file handle expN2 = number of bytes to skip + or - Return: offset from beginning of file, -1 if failed Example: AC_GOTOP( Handle ) M_offset = AC_SKIP( Handle , 25 ) ? M_offset 25 FUNCTION: AC_FSIZE() (PRG) Returns the file length (size) in bytes. Syntax: AC_FSIZE( expN ) Parameter: file handle Return: length of file, same as file size with DOS DIR command, -1 if failed Examples: M_len = AC_FSIZE( Handle ) Handle = AC_OPEN('data.ext') M_len = AC_FSIZE( Handle ) && M_len contains lenth of file AC_CLOSE( Handle ) - 14 - CHAPTER 4 File Attribute Functions FUNCTION: AC_GATTR() (ASM) This function returns the attribute of the passed file name. Syntax: AC_GATTR( expC ) Parameter: expC = <drive><path>file_name Return: A char string made of 1s and 0s in the bit pattern of the file's attribute byte, 'AC_ERROR' if failed Example: M_attr = AC_GATTR( 'C:\apps\password.dbf' ) bit pattern '76543210' bit 0 - '1' = read only bit 1 - '1' = hidden file bit 2 - '1' = system file bit 3 - '1' = volume lable bit 4 - '1' = subdirectory bit 5 - '1' = archive bit 6 - '0' = undefined (must be 0) bit 7 - '0' = undefined (must be 0) FUNCTION: AC_ISRO() (PRG) Test to see if the file is Read Only. Syntax: AC_ISRO( expC ) Parameter: expC = <drive><path>file_name Return: .T. if file is read only, .F. if file is not read only Example: Read_stat = AC_ISRO( '\apps\payroll.dbf' ) FUNCTION: AC_ISHID() (PRG) Tests to see if the file is hidden. Syntax: AC_ISHID( expC ) Parameter: expC = <drive><path>file_name Return: .T. if file is hidden, .F. if file is not hidden Example: Hid_stat = AC_ISHID( '\apps\payroll.dbf' ) - 15 - FUNCTION: AC_ISSYS() (PRG) Tests to see if the file is a system file. Syntax: AC_ISSYS( expC ) Parameter: expC = <drive><path>file_name Return: .T. if file is a system file, .F. if file is not a system file Example: Sys_stat = AC_ISSYS( '\apps\payroll.dbf' ) FUNCTION: AC_ISSUB() (PRG) Tests to see if the file is a subdirectory. Syntax: AC_ISSUB( expC ) Parameter: expC = <drive><path>file_name Return: .T. if file is a subdirectory, .F. if file is not a subdirectory Example: Sub_stat = AC_ISSUB( '\apps\payroll.dbf' ) FUNCTION: AC_ISARC() (PRG) Tests to see if the file has archive bit set. Syntax: AC_ISARC( expC ) Parameter: expC = <drive><path>file_name Return: .T. if file archive bit set, .F. if file archive bit is not set Example: Arc_stat = AC_ISARC( '\apps\payroll.dbf' ) - 16 - FUNCTION: AC_PATTR() (ASM) This function changes the attribute of the passed file name. Syntax: AC_PATTR( expC1 , expC2 ) Parameters: expC1 = <drive><path>file_name expC2 = a char string made of 1s and 0s in the bit pattern of the attribute byte Return: .T. if successful, .F. if failed Example: AC_PATTR( 'C:\apps\password.dbf' , '00000011' ) && make file read only and hidden FUNCTION: AC_MKRO() (PRG) Makes the file read only. Syntax: AC_MKRO( expC , expL ) Parameters: expC = <drive><path>file_name expL = .T. to make read only, .F. to not make read only Return: .T. if sucessful, .F. if not sucessful Example: AC_MKRO( 'password.dbf' , .T. ) FUNCTION: AC_MKHID() (PRG) Makes the file hidden. Syntax: AC_MKHID( expC , expL ) Parameters: expC = <drive><path>file_name expL = .T. to make hidden, .F. to make regular (un-hidden) Return: .T. if sucessful, .F. if not sucessful Example: AC_MKHID( 'password.dbf' , .T. ) - 17 - FUNCTION: AC_MKSYS() (PRG) Makes the file a system file. Syntax: AC_MKSYS( expC , expL ) Parameters: expC = <drive><path>file_name expL = .T. to make system file, .F. to make not system Return: .T. if sucessful, .F. if not sucessful Example: AC_MKSYS( 'file.dat' , .F. ) FUNCTION: AC_MKARC() (PRG) Sets the archive bit in the file. Syntax: AC_MKARC( expC , expL ) Parameters: expC = <drive><path>file_name expL = .T. to set archive bit, .F. to clear archive bit Return: .T. if sucessful, .F. if not sucessful Example: AC_MKARC( 'password.dbf' , .F. ) - 18 - CHAPTER 5 File Time/Date Stamp Functions FUNCTION: AC_GTIME() (ASM) This function returns the file stamp time from a file. Syntax: AC_GTIME( expN ) Parameter: expN = file handle Return: file time stamp as a char string, 'AC_ERROR' if failed Example: M_time = AC_GTIME( Handle ) FUNCTION: AC_GDATE() (ASM) This function returns the file date stamp from a file. Syntax: AC_GDATE( expN ) Parameter: expN = file handle Return: file date stamp as a date type, an empty date if failed Example: M_date = AC_GDATE( Handle ) ? TYPE( 'M_date' ) D FUNCTION: AC_PTIME() (ASM) This function sets the file stamp time in a file. Syntax: AC_PTIME( expN , expC ) Parameters: expN = file handle expC = time string in the format 'hh:mm:ss' The seconds should be even. Return: .T. if successful, .F. if failed Example: AC_PTIME( Handle , '12:30:00' ) && sets time as 12:30 pm - 19 - FUNCTION: AC_PDATE() (ASM) This function sets the file stamp date in a file. The earliest possible date is 01/01/1980. The latest possible date is 12/31/2099. Syntax: AC_PDATE( expN , expD ) Parameters: expN = file handle expD = date as a date type Return: .T. if successful, .F. if failed Example: AC_PDATE( Handle , CTOD('10/10/87') ) FUNCTION AC_PTD() (PRG) This function changes both a files date and time stamps. Syntax: AC_FTD( expC1 , expD , expC2 ) Parameter: expC1 = <drive><path>file_name expD = date as a date type range from 01/01/1980 to 12/31/2099 expC2 = time string in the format 'hh:mm:ss' The seconds should be even. Return: .T. if sucessful, .F. if failed Example: AC_PTD( 'test.fil' , CTOD('10/18/87') , '10:10:30' ) - 20 - CHAPTER 6 Misc. DOS Functions FUNCTION: AC_QUIT() (ASM) This function terminates the Clipper compiled application and returns the passed return code. The parameter is the return code. You must close all databases, and files opened with the ACCI86.LIB with the appropriate commands. This function DOES NOT CLOSE ANY FILES!!! You can test the passed return code at the DOS level with the batch command ERRORLEVEL. Syntax: AC_QUIT( expN ) Parameter: the return code as an integer, range from 1 to 255 Return: .F. if fails to terminate the application Example: AC_QUIT(1) FUNCTION: AC_RETCD() (ASM) This function returns as an integer the return code of a terminated subprocess. This function must be called immediately after the process terminates. Syntax: AC_RETCD() Parameter: none Return: return code of type integer, -1 if failed Example: ret_code = AC_RETCD() FUNCTION: AC_COMIT() (ASM) This function causes all DOS file buffered data to be written to disk. This function may only be used with DOS version 3.3 or higher. The parameter is the file handle. Syntax: AC_COMIT( expN ) Parameter: the file handle Return: .T. if successful, .F. if failed Example: AC_COMIT( Handle ) - 21 - FUNCTION: AC_DOS() (ASM) This function returns the DOS version as a string in the format '3.30'. There is no parameter. Syntax: AC_DOS() Parameter: none Return: DOS version as a string in the format '3.30', 'AC_ERROR' if failed - 22 - CHAPTER 7 Other Functions FUNCTION: AC_DIAL() (ASM) This function dials the input telephone number on an attached Hayes compatable modem. Syntax: AC_DIAL( expC ) Parameters: expC = a char string of the telephone number to dial Return: .T. if sucessful, .F. if failed Example: AC_DIAL('601,555-1212') Phone_no = '812,555-1212' AC_DIAL( Phone_no ) FUNCTION: AC_MODEM() (ASM) This function sets the modem settings for use with the AC_DIAL() function. I recommend that you use AC_SETM(). Syntax: AC_MODEM( expN1 , expN2 , expC ) Parameters: expN1 = COM port expN2 = initstr expC = dial type ( T = touchtone, P = pulse dial ) Return: .T. if sucessful, .F. if failed FUNCTION: AC_SETM() (PRG) Sets the modem parameters by creating the initstr used by AC_MODEM(). Syntax: AC_SETP( expN1 , expN2 , expC1 , expN3 , expN4 , expC2 ) Parameters: expN1 = COM port - 1 or 2 expN2 = BAUD rate - 300, 1200, 2400 expC1 = Parity - E(ven), O(dd), N(one) expN3 = Word length - 7 or 8 expN4 = Stop Bits - 1 or 2 expC2 = Dial type - T = touchtone, P = pulse dial Return: .T. if sucessfull, .F. if failure Example: AC_SETP( 2, 1200, 'N', 8, 1, 'P' ) - 23 - The clock functions are used to set, turn on, turn off and display a constant display clock showing date, time, and day of week. Also displayed are the Caps Lock and Num Lock states. This function is an an interrupt which is chained onto interrupt 1Ch. If you turn on the display with AC_CLON() and exit the program (as by Quit at an error) without calling AC_CLOFF(), then your computer will hang. For this reason I recommend that you only use these functions after your program is fully debuged. The display is performed through direct writes to the screen buffer, this is faster. FUNCTION: AC_CLSET() (ASM) This function sets the parameters for the time/date continuous display. This function must be called before CLOCKON(). This function should only be called when CLOCKOFF() (continuous display is disabled.) All three parameters must be present. Syntax: AC_CLSET( expN1 , expN2 , expC ) Parameters: expN1 = Type of monitor, 1 = Monochrome, 2 = Color expN2 = Day of week <numeric> expC = Date string of the current date '10-Oct-87' Return: .T. if successful, .F. if not Example: see AC_STCL() FUNCTION: AC_STCL() (PRG) The best way to set the parameters for the constant display clock. Syntax: AC_STCL() Parameters: none Return: .T. if sucessful, .F. if failed The following is the code for AC_STCL FUNCTION AC_STCL Date_str = STR(DAY(DATE()),2,0) + '-' + SUBSTR(CMONTH(DATE()),1,3) ; + '-' + STR(YEAR(DATE())-1900,2,0) Monitor = IF(ISCOLOR(),2,1) RETURN AC_CLSET(Monitor,DOW(DATE()),Date_str) - 24 - FUNCTION: AC_CLON() (ASM) This function enables the time/date continuous display. Syntax: AC_CLON() Parameters: none Return: .T. if sucessful, .F. if not RECOMENDED PROGRAMMING: PUBLIC Clock_on IF AC_STCL() Clock_on = .T. AC_CLON() ELSE Clock_on = .F. ENDIF FUNCTION: AC_CLOFF() (ASM) This function disables the time/date continuous display. THIS FUNCTION MUST BE CALLED BEFORE EXITING THE PROGRAM OR THE COMPUTER WILL HANG. Syntax: AC_CLOFF() Parameters: none Return: .T. if sucessful, .F. if not RECOMENDED PROGRAMMING: IF Clock_on && see AC_CLON() example AC_CLOFF() ENDIF - 25 - CHAPTER 8 Error Recovery OVERVIEW - Most of the functions in this library will return data that will indicate if an error has occured. The type of the error return provided depends on the type of "good" data returned. The error indicators are listed below. File Handle = -1 indicates an error Char String = returns the message 'AC_ERROR' Numeric = -1 or 0, see each function Logical = returns .F. (false) on error Date = and empty date indicates an error Your program can test for error conditions in two ways. You can perform the function and test for the appropriate error data listed above and/or you can test by performing the AC_ERROR() function. This function returns a numeric error code. Most of these error codes are the standard DOS error codes, however, a few represent error conditions specific to this library. Example 1: M_handle = AC_OPEN('\apps\myfile',11000010') IF M_handle = -1 . . statements . ENDIF Example 2: M_handle = AC_OPEN('\apps\myfile',11000010') IF AC_ERROR() > 0 . . statements . ENDIF FUNCTION: AC_ERROR() (ASM) Returns the error code if an error occured on the last AC_* function called. If no error occured on the last AC_* function then 0 is returned. See the error codes and their meaning listed below. Syntax: AC_ERROR() Parameter: none Return: the last error code generated by an AC_* function or 0 if no error occured, this function can be called more than once until any other AC_* function is called again Example: M_error = AC_ERROR() - 26 - DOS ERROR CODES Code Meaning 1 - Invalid function number 2 - File not found 3 - Path not found 4 - Too many files open (no handles left) 5 - Access denied 6 - Invalid handle 7 - Memory control blocks destroyed 8 - Insufficient memory 9 - Invalid memory block address 10 - Invalid environment 11 - Invalid format 12 - Invalid access code 13 - Invalid data 14 - Reserved 15 - Invalid drive was specified 16 - Attempt to remove the current directory 17 - Not same device 18 - No more files 19 - Attempt to write on write-protected diskette 20 - Unknown unit 21 - Drive not ready 22 - Unknown command 23 - Data error CRC 24 - Bad request structure length 25 - Seek error 26 - Unknown media type 27 - Sector not found 28 - Printer out of paper 29 - Write fault 30 - Read fault 31 - General failure 32 - Sharing violation 33 - Lock violation 34 - Invalid disk change 35 - FCB unavailable 36 - Sharing buffer overflow 37 - 49 - Reserved 50 - Network request not supported 51 - Remote computer not listening 52 - Duplicate name on network 53 - Network name not found 54 - Network busy 55 - Network device no longer exists 56 - Net BIOS command limit exceeded 57 - Network adapter hardware error 58 - Incorrect response from network 59 - Unexpected network error 60 - Incompatible remote adapter 61 - Print queue full - 27 - DOS ERROR CODES - continued Code Meaning 62 - Not enough space for print file 63 - Print file was deleted 64 - Network name was deleted 65 - Access denied 66 - Network device type incorrect 67 - Network name not found 68 - Network name limit exceeded 69 - Net BIOS session limit exceeded 70 - Temporarily paused 71 - Network request not accepted 72 - Print or disk redirection is paused 73 - 79 - Reserved 80 - File exists 81 - Reserved 82 - Cannot make directory entry 83 - Fail on INT 24 84 - Too many redirections 85 - Duplicate redirection 86 - Invalid password 87 - Invalid parameter 88 - Network data fault - 28 - ACCI ERROR CODES Code Meaning 0 - No error 1000 - Incorrect number of parameters 1001 - Too many bytes to read 1002 - Date less than 01/01/80 or greater than 12/31/2099 - 29 - CHAPTER 9 Standalone Utilities FRMSTRUC (PRG) A standalone utility PRG that can be compiled and linked with Clipper. This program accepts the FRM file name, opens the file, determines all the breaks, fields, ect. and outputs this information. Note: This first version only works with .FRM files created with Clipper and dBASE III Plus, not original dBASE. Syntax: FRMSTRUC <FRM file name>,<option>,<output file> Parameters: FRM file name - the [drive][path]file name Option - P sends output to standard print - F send output to Output file - <drive><path>file_name the file extension of .TXT is added if there is no extension - S send output to the screen with pauses Return: 1 if sucessful, 0 if failed This return code can be tested with the DOS Batch command ERRORLEVEL IF ERRORLEVEL 1 && sucessful IF ERRORLEVEL 0 && failure - 30 -