Appendix B    External Functions

This appendix covers the JADE external functions declared in the RootSchema jomos external function library that call Windows library functions as defined in the Microsoft Developer Network (MSDN). These external functions are declared to avoid having to declare ANSI- and Unicode-specific definitions for some commonly called Windows library functions; for example, josShellExecute calls ShellExecuteA in an ANSI environment and ShellExecuteW in a Unicode environment.

The following table maps functions defined in the RootSchema jomos external function library to the corresponding MSDN function.

JADE External Function	Windows Function	Description
josCreateDirectory	CreateDirectory	Creates a directory that inherits information from other directories (security attributes default to null)
josDeleteDirectory	RemoveDirectory	Deletes an existing empty directory
josFileAccess	GetFileAttributes	Retrieves attributes for a specified file or directory (for details, see the paragraph that follows this table)
josFileCopy	CopyFile	Copies an existing file to a new file
josFileDelete	DeleteFile	Deletes an existing file
josGetKeyState	GetKeyState	Retrieves the status of the specified key; that is, whether the key is up, down, or toggled
josGetLastError	GetLastError	Retrieves the last error code value of the calling thread
josShellExecute	ShellExecute	Opens or prints the specified file; for example, to start another program under Microsoft Windows

In addition to these functions, the josValidateDirectory external function is declared, which validates that the specified name is a directory.

The josFileAccess function checks the specified file to determine if it exists and whether it can be read, written, or executed. This pointer is a call for files only; if you call it with a directory name, F_FILE_NOT_FOUND is returned. (Call the josValidateDirectory function to validate a directory.) The josFileAccess parameters are:

• fileName, which is a string that specifies the name of the file.

• aMode, which specifies a bit pattern constructed as follows.

  • 06, which checks for read and write permission

  • 04, which checks for read permission

  • 02, which checks for write permission

  • 01, which checks for execute permission

  • 00, which checks for the existence of the specified file

• log, which specifies if invalid path exceptions are logged to jommsg.log.

The josFileAccess and josValidateDirectory calls return zero (0) if successful or they return a JADE file‑handling error in the range 5000 through 5099.

For details about:

• Adding an external function to a class, see "Defining External Functions", in Chapter 8 of the JADE Development Environment User’s Guide

• Browsing the RootSchema jomos external function library to obtain the JADE external function method signature, see "Adding an External Function, in Chapter 8 of the JADE Development Environment User’s Guide

• External function calls, see "Using External Functions", in Chapter 1