` Printed Icetips Article

Icetips Article



Par2: Useful API Functions
1998-07-27 -- Frank Piscopo
 
Prototypes of the following Clarion Runtime API Calls are declared in
CLIB.CLW - use the following embed:

Inside the Global Map
  INCLUDE('CLIB.CLW')

For a complete list of all the documented calls, refer to Chapter 14 of the
Programmer's Guide.
-----------------------------------------------------
LOW-LEVEL FILE FUNCTIONS:

Access(*CSTRING,SHORT),SHORT
Usage:   IF Access(p,a) ...
         where p is the path to check, in a C-string,
         and a is the access mode (use ff_: equates in EQUATES.CLW)
Purpose: Tests whether a file or directory can be accessed in
         the specified mode (can be used for file existence tests).

API_Remove(*CSTRING),SHORT
Usage:   IF API_Remove(p) ...
         where p is pathname of the file to remove, in a C-string.
Purpose: Deletes a file (not a directory; for this, refer to RmDir below).

API_Rename(*CSTRING,*CSTRING),SHORT
Usage:   IF API_Rename(p1,p2) ...
         where p1 is the original filename in a C-string,
         and p2 is the new filename in a C-string.
Purpose: Renames a file or directory.

FnSplit(*CSTRING,*CSTRING,*CSTRING,*CSTRING,*CSTRING),SHORT
Usage:   IF FnSplit(p,v,d,n,e) ...
         where p is a pathname to split, in a C-string,
         v is a C-string to receive the DRIVE letter,
         d is a C-string to receive the DIRECTORY,
         n is a C-string to receive the FILENAME,
         e is a C-string to receive the EXTENSION.
Purpose: Splits a pathname into the various parts as listed above.
         I should assume that unspecified parts in p are
         taken from the current default directory and drive.

MkDir(*CSTRING),SHORT
Usage:   IF MkDir(d) ...
         where d is the directory pathname, in a C-string.
Purpose: Creates a new directory, specified by d.

RmDir(*CSTRING),SHORT
Usage:   IF RmDir(d) ...
         where d is the directory pathname, in a C-string.
Purpose: Deletes a directory, which presumably should be empty.

--- All the above functions return a SHORT to indicate success or failure of the
function.

STRING FUNCTIONS:

IsAscii(SHORT),SHORT
Usage:   IF IsAscii(VAL(c)) ...
         where c is any one-character constant or string variable.
Purpose: Tests whether c is an ASCII character.

IsCntrl(SHORT),SHORT
Usage:   IF IsCntrl(VAL(c)) ...
         where c is any one-character constant or string variable.
Purpose: Tests whether c is a control character.

IsDigit(SHORT),SHORT
Usage:   IF IsDigit(VAL(c)) ...
         where c is any one-character constant or string variable.
Purpose: Tests whether c is a numeric digit character.

IsGraph(SHORT),SHORT
Usage:   IF IsGraph(VAL(c)) ...
         where c is any one-character constant or string variable.
Purpose: Tests whether c is a printable character, excluding SPACE.

IsPrint(SHORT),SHORT
Usage:   IF IsPrint(VAL(c)) ...
         where c is any one-character constant or string variable.
Purpose: Tests whether c is a printable character, including SPACE.

IsPunct(SHORT),SHORT
Usage:   IF IsPunct(VAL(c)) ...
         where c is any one-character constant or string variable.
Purpose: Tests whether c is a punctuation character.

IsSpace(SHORT),SHORT
Usage:   IF IsSpace(VAL(c)) ...
         where c is any one-character constant or string variable.
Purpose: Tests whether c is a white-space character (space, tab, CR, LF, FF).

IsXDigit(SHORT),SHORT
Usage:   IF IsXDigit(VAL(c)) ...
         where c is any one-character constant or string variable.
Purpose: Tests whether c is a hex digit (like IsDigit() plus A,B,C,D,E,F).

StrCSpn(*CSTRING,*CSTRING),USHORT
Usage:   IF StrCSpn(c1,c2) ...
         where c1 and c2 are C-string variables.
Purpose: Finds the first occurance in c2 of any character in c1
         (don't take my word for this one; the meaning of c1 and c2 may be swapped).

StrSpn(*CSTRING,*CSTRING),USHORT
Usage:   IF StrCSpn(c1,c2) ...
         where c1 and c2 are C-string variables.
Purpose: Finds the first character in c2 which IS NOT in c1
         (ditto, meaning of c1 and c2 may be swapped).

StrRev(*CSTRING),CSTRING
Usage:   c1 = StrRev(c2)
         where c1 and c2 are C-string variables.
Purpose: Returns the reverse of a string
         (StrRev('Reverse') returns 'esreveR')

--- Most of the above functions can be used in user-written functions
    to make them more useful to test whole strings.  For example,
    one could write something like the following to test whether a
    string is free of non-printable characters:

!----------------------------------------------
IsPrintS PROCEDURE(s)
l        LONG,AUTO
i        LONG,AUTO
  CODE
  l = LEN(CLIP(s))
  LOOP i = 1 TO l
    IF ~IsPrint(VAL(s[i])) THEN RETURN FALSE.
  END
  RETURN TRUE
!----------------------------------------------



Printed November 23, 2024, 2:23 am
This article has been viewed/printed 35201 times.